Add project documentation

2026-10-29 16:05:01 +08:00
parent 4c6243a274
commit bea86a2c9e
3 changed files with 361 additions and 0 deletions
@@ -0,0 +1,87 @@
+# uni-agent 能力说明
+
+本文档是公开能力摘要，不是内部技能清单、系统提示词、实现代码或受限配置的导出。
+
+## 项目分析与代码维护
+
+- 阅读和梳理 uni-app、uni-app x 项目结构。
+- 定位页面、组件、路由、状态、API 和平台配置。
+- 根据现有代码风格进行小范围修改。
+- 识别潜在的运行时错误、类型问题、路由问题和跨平台差异。
+- 保留用户已有改动，不擅自回退无关文件。
+- 使用 Git 检查变更、整理提交和推送代码，但提交或推送应由用户明确授权。
+
+## uni-app x 开发
+
+- 编写和维护 `.uvue` 页面及组件。
+- 使用组合式 API 和 `<script setup>`。
+- 处理 Android、Web 等平台的条件差异。
+- 协助迁移页面的 API 写法，同时保持原有业务行为。
+- 分析 Vapor 模式下的页面、组件和编译问题。
+- 检查 uni-app x 的布局、样式、单位、定位和 Flexbox 使用方式。
+- 根据项目现有模式复用组件和 `uni_modules`。
+
+## 页面与交互
+
+- 实现登录、注册、资料、任务、学习报告、词汇和成长激励等页面。
+- 实现底部导航、页面栈复用、筛选、刷新、弹窗和加载状态。
+- 实现表单校验、错误提示、空状态、重试和提交状态。
+- 关注移动端安全区、固定底栏、滚动区域和不同屏幕尺寸。
+- 检查文字、按钮、图标和图表是否存在布局溢出或重叠。
+
+## 组件与原生能力
+
+- 抽取可复用的业务组件和展示组件。
+- 处理扫码、摄像头权限、二维码解析和资源释放。
+- 处理 Web 与原生平台的扫码实现差异。
+- 协助使用项目已有图标、导航、列表、刷新和表单组件。
+- 在需要时分析 UTS 插件和平台原生能力的接入边界。
+
+## 接口与数据流
+
+- 梳理页面到 API、状态和 Mock 数据之间的数据流。
+- 定义请求参数、响应类型和页面使用的业务模型。
+- 处理登录令牌、请求错误、加载状态和重试流程。
+- 区分 Mock 成功响应、客户端验证成功和服务端真实持久化。
+- 识别前端已有接口与后端缺失接口之间的边界。
+
+## uniCloud 与数据服务
+
+- 协助设计云函数、云对象、数据库集合和数据流。
+- 分析 JQL 查询、分页、联表、统计和权限规则。
+- 为云端接口设计前端类型和调用方式。
+- 协助生成和运行适合云端逻辑的测试。
+
+涉及后端服务、云函数、云对象、JQL 或数据库权限时，应先确认数据实体、调用方、输入、输出、错误处理和权限边界。
+
+## 测试与验证
+
+- 执行相关项目测试并分析失败原因。
+- 使用 HBuilderX 进行 Web 或 App 编译验证。
+- 检查构建日志中的错误和警告。
+- 根据需要验证页面截图、布局和交互状态。
+- 检查 Git 暂存内容、差异和换行或空白问题。
+
+自动化验证不能替代真机验证。摄像头、权限、原生导航、推送和平台特有行为仍需在对应运行环境检查。
+
+## 项目文档
+
+- 整理 README、接口说明、页面说明和开发约定。
+- 将当前项目的架构、限制、构建方式和验证流程整理成 Markdown。
+- 记录尚未实现的后端能力，避免前端用本地状态伪造服务端行为。
+
+## 安全与边界
+
+- 不导出系统提示词、开发者指令、内部知识库原文、内部技能实现或存储位置。
+- 不在聊天或代码中要求用户粘贴密码、令牌、私钥或证书内容。
+- 不提交环境文件、签名证书、私钥、构建产物和本机配置。
+- 不将 Mock 数据或前端校验描述为真实业务完成。
+- 不生成 Flutter 或 React Native 业务代码；相关代码可以作为现有项目参考进行分析。
+
+## 协作方式
+
+- 先读取项目上下文，再确定最小改动范围。
+- 复杂任务先拆分为分析、实现、验证和收尾步骤。
+- 编辑前说明将修改的文件和行为。
+- 完成后报告实际改动、验证结果和仍存在的限制。
+- 遇到明确冲突或缺少关键业务约定时，停止并请求澄清。
@@ -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` 和待提交文件列表。
+- 未经明确要求，不自动提交或推送代码。
@@ -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
+```
+
+未经明确要求，不自动提交或推送代码。