Add project documentation

PROJECT_ASSISTANT_GUIDE.md

@@ -0,0 +1,78 @@
+# 项目协作与开发指南
+
+本文档是当前项目开发协作规则的公开摘要，不是 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 编译检查跨平台语法和组件引用。
+
+```powershell
+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` 和待提交文件列表。
+- 未经明确要求，不自动提交或推送代码。