Add project documentation
This commit is contained in:
tanxin
@@ -0,0 +1,196 @@
|
||||
# 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
|
||||
```
|
||||
|
||||
未经明确要求，不自动提交或推送代码。
|
||||
Reference in New Issue
Block a user