tanxin/App.k12.Parents
1
0
Fork 0
Code Pull Requests Actions Releases Activity
Files
d509e80321380f6eb84fd7c60ff73633a0a44fbb
App.k12.Parents/PROJECT_KNOWLEDGE_BASE.md
T
tanxin bea86a2c9e Add project documentation
2026-10-29 16:05:01 +08:00

6.8 KiB
Raw Blame History

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 发行构建命令：

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

提交前检查：

git status
git diff --cached
git diff --cached --check

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

View Git Blame Copy Permalink