# 项目协作与开发指南

本文档是当前项目开发协作规则的公开摘要，不是 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` 和待提交文件列表。
- 未经明确要求，不自动提交或推送代码。