# App.k12.Parents 项目知识摘要

本文档是根据当前项目源码、构建配置和已实现功能整理的公开知识摘要，不包含 AI 内部系统提示词、受限知识库原文、凭据或平台内部资料。

## 1. 项目基础

- 项目名称：爱学蝶变家长端
- 项目类型：uni-app x
- Vue 版本：Vue 3
- 渲染模式：Vapor，当前构建日志显示 Web 使用 VDOM 编译目标
- 默认脚本语言：TypeScript
- 主要平台：Android、Web
- HBuilderX：5.33
- AppID：`__UNI__800D1E3`
- Android 包名：`com.yx.k12.parents`
- 远程仓库：`https://gitea.23544.com/tanxin/App.k12.Parents.git`

## 2. 目录结构

| 目录或文件 | 用途 |
| --- | --- |
| `pages/` | 页面文件，使用 `.uvue` |
| `components/` | 可复用组件 |
| `api/` | API 类型和请求函数 |
| `store/` | 用户、学生和页面状态 |
| `utils/request.ts` | 请求封装和 Mock 响应 |
| `uni_modules/` | uni-app x 组件和插件 |
| `manifest.json` | 应用元信息和平台配置 |
| `pages.json` | 页面路由配置 |
| `uni.scss` | 全局样式变量 |
| `unpackage/` | HBuilderX 编译、发行输出，不应提交 |

## 3. 页面清单

### 登录和注册

- `pages/login/index`：手机号密码登录、验证码登录入口、找回密码和注册入口。
- `pages/login/verify-code`：验证码登录。
- `pages/login/forgot-password`：验证码校验和密码重置。
- `pages/register/index`：注册入口。
- `pages/register/scan-student`：注册流程扫码验证学生。
- `pages/register/input-student`：注册流程手动验证学生。
- `pages/register/parent-account`：填写家长账号和密码并提交注册。
- `pages/register/complete`：注册完成页。

### 主业务页面

- `pages/index/index`：首页。
- `pages/study/index`：学情报告、趋势、活跃度和知识点掌握情况。
- `pages/tasks/index`：任务列表及状态筛选。
- `pages/profile/index`：家长资料、孩子切换和绑定入口。
- `pages/profile/verify-student`：登录后验证待绑定学生。
- `pages/vocabulary/index`：英语词汇。
- `pages/growth/index`：成长激励。
- `pages/today-learning/index`：今日学习。
- `pages/alerts/index`：预警信息。

## 4. 组件

### `components/main-tab-bar.uvue`

底部主导航，包含首页、学情、任务和我的四个入口。

- 复用已有页面栈，避免重复创建同一页面。
- 路由比较会去掉前导 `/` 和查询参数。
- 图标使用 `uni-icons-x` 或独立的柱状图样式。
- 所有导航图标使用统一高度容器，保证文字基线对齐。

### `components/qr-scanner.uvue`

通用二维码扫描组件。

- Web 使用 `@zxing/browser` 和浏览器摄像头。
- 原生平台使用 uni-app x `camera` 组件。
- `scan` 事件返回二维码字符串。
- `error` 事件通知摄像头不可用或权限异常。
- 支持扫描冷却时间，默认间隔为 5000 毫秒。
- 组件销毁时停止扫描并清理摄像头资源。
- 组件只负责扫描，不负责学生验证或绑定业务。

### 图表组件

- `components/study-trend-chart.uvue`：学习趋势折线图。
- `components/study-activity-chart.uvue`：学习活跃度柱状图。

## 5. uni-app x 编码规则

- 页面和组件优先使用 `<script setup lang="ts">`。
- 使用 `display: flex` 时必须显式写出 `flex-direction`。
- 样式优先使用独立 class 选择器。
- 避免使用不兼容的子选择器、通配选择器和标签选择器。
- App 和 Web 的摄像头实现必须使用条件编译区分。
- 固定尺寸的导航图标、按钮、列表和图表需要显式设置宽高或稳定布局。
- 使用 uni-app x 不支持或存在平台差异的 CSS 属性前，应先查阅项目适用文档并通过真实编译验证。
- 组件引用优先复用项目现有 `uni_modules`，避免重复安装同类依赖。

## 6. 学生验证与绑定

### 注册时流程

1. 用户扫码或输入学生账号和姓名。
2. 页面调用学生二维码或账号验证接口。
3. 验证成功后，将学生加入注册流程内存列表。
4. 最多暂存 3 名学生。
5. 家长账号页面提交注册时，将学生 ID 数组提交给注册接口。

### 登录后流程

1. 用户在“我的”页面点击“扫码绑定”或“手动输入”。
2. 进入 `pages/profile/verify-student`。
3. 页面读取当前家长的已绑定学生列表。
4. 用户扫码或输入账号、姓名进行学生验证。
5. 页面检查重复学生和 3 人上限。
6. 当前页面只显示“已验证，尚未绑定”。

### 当前限制

项目目前有学生验证接口，但没有发现登录后创建绑定关系的真实后端接口。因此：

- 学生验证不等于建立绑定关系。
- 页面不能只修改本地列表来代替服务端绑定。
- 接入真实绑定前，需要后端提供新增绑定接口、请求参数和返回格式。
- 当前 Mock 数据不能证明真实身份、绑定关系或持久化行为。

## 7. API 概览

主要 API 位于 `api/student.ts` 和 `api/auth.ts`。

| API | 用途 |
| --- | --- |
| `apiVerifyStudentQRCode` | 验证学生二维码 |
| `apiVerifyStudentAccount` | 验证学生账号和姓名 |
| `apiGetBoundStudents` | 查询当前家长已绑定学生 |
| `apiGetStudentHomeProfile` | 查询首页当前学生资料 |
| `apiGetStudentAlerts` | 查询学生预警信息 |
| `apiRegister` | 提交家长注册信息和注册时学生 ID 数组 |

`utils/request.ts` 会在已有用户令牌时添加 Bearer Authorization。当前项目默认启用 Mock API，修改真实接口时需要同步修改 API 类型、请求函数、Mock 响应和页面错误处理。

## 8. 图标规范

项目已安装 `uni_modules/uni-icons-x`，图标名称定义在：

`uni_modules/uni-icons-x/components/uni-icons/icons.uts`

常用图标包括：

- `home`、`home-filled`
- `person`、`person-filled`
- `checkbox`、`checkbox-filled`
- `scan`、`camera`
- `search`、`refresh`
- `medal`、`medal-filled`

图标颜色和尺寸可通过 class 设置。底部导航选中态主色为 `#554be9`，未选中态为 `#9da8ba`。

## 9. 构建验证

Web 发行构建命令：

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

输出目录：

`unpackage/dist/build/web`

注意事项：

- Web 发行输出应通过 Web 服务器访问。
- 不建议直接双击打开 `index.html`。
- 修改 `.uvue`、路由或组件后应执行真实编译。
- 摄像头权限、Android 导航和原生扫码必须在真机或对应运行环境中验证。

## 10. Git 规则

`.gitignore` 已排除：

- `node_modules/`
- `unpackage/`
- `.hbuilderx/`
- `.env` 和 `.env.*`
- `*.keystore`
- `*.jks`
- `*.p12`

提交前检查：

```powershell
git status
git diff --cached
git diff --cached --check
```

未经明确要求，不自动提交或推送代码。