App.k12.Parents/PROJECT_ASSISTANT_GUIDE.md

项目协作与开发指南

本文档是当前项目开发协作规则的公开摘要，不是 AI 的内部系统提示词或隐藏指令原文。

项目概况

• 项目名称：爱学蝶变家长端
• 技术栈：uni-app x、Vue 3、Vapor 模式、TypeScript/UTS
• 主要平台：Android、Web
• HBuilderX：5.33
• AppID：__UNI__800D1E3
• Android 包名：com.yx.k12.parents

开发约束

• 优先复用现有页面、组件、API 和 uni_modules，避免重复实现。
• 修改前先检查相关页面、接口、路由和状态管理，确认现有业务流程。
• 页面和组件使用 <script setup lang="ts">。
• 使用 display: flex 时必须显式声明 flex-direction。
• uni-app x 样式尽量使用独立 class 选择器，不使用子选择器、通配选择器或标签选择器。
• 默认使用 ASCII 字符编辑代码；只有业务文本或已有文件编码需要时才使用非 ASCII 字符。
• 手动修改文件使用补丁方式，避免无关格式化和大范围重构。
• 不修改或回退其他开发者已有的工作区改动。

UI 约定

• 保持现有家长端的紫色主色、浅灰背景、白色内容区和紧凑卡片风格。
• 底部导航使用统一的图标容器、文字基线和选中态。
• 优先使用项目已安装的 uni-icons-x 图标组件。
• 固定底栏、按钮、列表和图表需要设置稳定尺寸，避免内容变化造成布局跳动。
• 页面需要关注 Android 和 Web 的布局差异，尤其是安全区、摄像头和滚动区域。

扫码能力

• 通用扫码组件：components/qr-scanner.uvue
• Web 平台使用 @zxing/browser 和浏览器摄像头。
• 原生平台使用 uni-app x camera 组件，模式为 scanCode。
• 扫码组件通过 scan 事件返回结果，通过 error 事件通知摄像头错误。
• 页面业务负责解析二维码、校验内容和处理业务结果；扫码组件不耦合学生绑定业务。
• 页面销毁时必须停止扫描并释放摄像头资源。

学生绑定流程

• 注册流程页面位于 pages/register/。
• 登录后验证学生页面位于 pages/profile/verify-student.uvue。
• 当前项目已有学生二维码和账号验证接口。
• 当前项目尚未发现登录后创建学生绑定关系的服务端接口。
• 因此登录后验证结果不能伪装成已绑定，也不能只修改本地列表来代替服务端绑定。
• 绑定关系真正落地前，需要后端提供新增绑定接口及请求、返回格式。

API 与 Mock

• API 封装位于 api/。
• 请求封装位于 utils/request.ts。
• 当前默认启用 Mock 数据，不能将 Mock 成功响应视为真实服务端结果。
• 修改接口时需要同步检查类型、Mock 响应和页面错误处理。

验证流程

完成代码修改后至少执行一次相关平台的真实编译验证，优先使用 Web 编译检查跨平台语法和组件引用。

F:\HBuilderX\cli.exe publish web --platform "Web" --project "E:\project\App.k12.Parents"

Web 构建产物位于：

unpackage/dist/build/web

扫码、摄像头权限、原生导航和 Android 行为仍需在真机或 Android 构建环境中验证。

Git 协作

• 远程仓库：https://gitea.23544.com/tanxin/App.k12.Parents.git
• 默认分支：main
• 不提交 node_modules/、unpackage/、本机 HBuilderX 配置、环境文件和证书文件。
• 提交前检查 git status、git diff 和待提交文件列表。
• 未经明确要求，不自动提交或推送代码。