finance和marking v3 移动前端

Q 613c0faafa docs(readme): 补全四大板块——技术栈/目录结构与用途/编码规范/构建与本地运行		пре 4 дана
.gitignore	f30f6486a7 docs: 初始化移动端前端仓库（工程约定 README + .gitignore 占位）	пре 4 дана
README.md	613c0faafa docs(readme): 补全四大板块——技术栈/目录结构与用途/编码规范/构建与本地运行	пре 4 дана

移动端前端（老师 / 学生 / 家长）

单仓多端，按角色分包：teacher / student / parent 三端共享 packages/shared（身份/登录态、通用组件、接口封装）。本文档覆盖四块：技术栈 / 目录结构与用途 / 编码规范 / 构建。接口契约见工作区文档库 unified/、academic/05-architecture/、teaching/05-architecture/（本仓库不复制契约原文）。

定位

一个移动端仓服务三个角色端：

端	主要场景	主要域
老师端	打卡、查看/批改练习、备课查看	教务（打卡）+ 教学（练习/备课）
学生端	做题、查看练习记录与分析	教学
家长端	绑定孩子、查看孩子练习/费用	教务（bindchild 绑定、费用）+ 教学（练习）

三端底层用户统一（canonical_user_id + 7 角色），故共用 shared 的 SSO 接入与登录态，仅按角色分包差异视图。

1. 技术栈

关注点	选型	说明 / 依据
框架	Vue 3（`<script setup>` + Composition API）	与 PC 端同栈，组件/工具/类型可复用
语言	TypeScript（strict）	契约类型化；`R<T>` 信封泛型与 PC 端一致
构建	Vite（每端独立入口）	按端分包产物；主 chunk < 1024KB
UI	Vant 4	移动交互组件库（默认中文 locale）；如混用 Element Plus 组件需双 locale 注入
状态	Pinia	登录态/角色/institution·campus 作用域（shared 内建）
路由	Vue Router 4（每端独立路由表）	角色差异用权限码判断
HTTP	axios（统一封装于 `shared/api`）	统一 `{code, data, message}` 信封处理
鉴权	SSO（最小可行）token + 微信 per-campus 授权（家长端主入口）	统一 identity 签发（ADR-014）；多 appid 按 campus 绑定
工作区	pnpm monorepo（workspaces）	`packages/shared` + `apps/{student,parent,teacher}`
代码风格	ESLint + Prettier	提交前 lint

2. 目录结构与用途

.
├── README.md              ← 本文件
├── package.json           ← 根（workspaces 声明 + 公共脚本/依赖）
├── pnpm-workspace.yaml    ← pnpm 工作区（packages/* + apps/*）
├── tsconfig.base.json     ← TS 公共配置（apps/* 继承 + paths 指 shared 源码）
├── .env.example           ← 环境变量模板（各端 VITE_API_BASE / VITE_WECHAT_* 等）
├── packages/
│   └── shared/            ← 三端共享（唯一登录态/SSO 实现，见铁律 1）
│       ├── src/
│       │   ├── identity/  ←   SSO 接入：token 存取、静默刷新/吊销、微信 per-campus 授权
│       │   ├── api/       ←   接口封装：统一信封 + 错误码；按域分子目录（academic/teaching/…）
│       │   ├── components/←   通用组件（作用域感知、列表、表单、Badge 色板）
│       │   ├── types/     ←   契约类型：R<T>、角色/权限码、各域 DTO
│       │   └── composables/←  可组合逻辑：useListPage 等
│       └── package.json   ←   包名 @unified/shared；main 指向 src（按源码消费，免构建）
└── apps/
    ├── student/           ← 学生端：src/{views,router,api 域扩展}/ + main.ts（独立 Vite 入口）
    ├── parent/            ← 家长端：同上（微信授权主入口 + bindchild 绑定流）
    └── teacher/           ← 老师端：同上（规划待建，结构对齐 student/parent）

目录用途约定：

目录	用途	约束
`packages/shared`	三端共享层：SSO/登录态、接口封装、通用组件、契约类型	唯一 token 存取与 SSO 实现点；零端差异逻辑
`apps/{端}/src/views`	该端页面	只经 `shared/api` 发起请求；不实现登录
`apps/{端}/src/router`	该端独立路由 + 权限码守卫	角色差异用权限码，不写 `role == N`
`apps/{端}/.env*`	该端构建变量（API base、微信 appid 映射）	只 `.env.example` 入库
`tsconfig.base.json`	公共 TS 配置	apps 经 `paths` 直指 `@unified/shared` 源码（dev 免构建、类型直达）

3. 编码规范

3.1 结构铁律

登录态/SSO 只有一份，放 packages/shared/src/identity；三端不得各自实现登录（对齐"底层用户统一"）。
家长↔学生绑定以教务侧 bindchild 为事实源（对齐清单 §6）：家长端进入时按绑定关系拉取孩子数据，不本地存绑定快照。
三端路由独立（各自 views/ + router），但共用 shared/components 与 shared/api；角色差异用权限码判断，不写 role == N 硬编码。
接口调用只经 shared/api/，三端 views 内不散写请求。
shared 改动影响三端：改 shared 必须三端各自 pnpm build 通过后方可提交（跨端回归门禁）。

3.2 接口与响应契约

统一「HTTP 恒 200 + body code」信封 {code, data, message, total?, success}；判成功读 code === 200，错误文案读 message，不靠拦截器 reject、不靠 HTTP status。
错误码分段（与后端/PC 端一致）：1xxx 认证/权限 · 2xxx 参数 · 3xxx 数据 · 4xxx 依赖 · 5xxx 系统；1001/1002 走 identity 统一刷新/重登流程（并发只刷一次）。
AI 类异步结果（批改/分析）：派发成功 ≠ 完成，轮询任务终态或业务表，前端展示"处理中"态而非静默。
命名：入参/出参 camelCase；组件 PascalCase；组合式函数 useXxx。

3.3 鉴权与微信授权

家长端主入口 = 微信 per-campus 授权（campus → appid 映射由后端下发）；老师/学生端账密 + 微信绑定。
token 刷新单例：并发过期只触发一次 refresh（Promise 复用），成功后重放原请求。
授权失败/未绑定时引导到对应端登录页，不白屏。

3.4 可复用资产与惯例（源自教务 Go 重构实战）

三端复用模式：与教务重构一致采用"移动教师/移动家长 Vant + 共享 shared"；shared/identity（SSO 接入、token 存取/刷新/吊销）三端共用一份。
locale：Vant 4 默认中文，不动；如混用 Element Plus 组件需命令式 + 声明式双注入。
列表页规范：useListPage<T> + 列表组件（分页/下拉刷新收口）；Badge 色板纯数据零 Vue 依赖（年级学段色系/科目首字简称）。
脱敏展示：手机号/身份证按后端已脱敏值展示，前端不再二次处理（源头脱敏）。

3.5 质量门禁

门禁	命令	基线
类型检查	`vue-tsc --noEmit`（各端 + shared）	0 错误
构建	`pnpm -r build`（三端）	各端主 chunk < 1024KB
Lint	`pnpm -r lint`	0 错误
跨端回归	改 shared 后三端全量 build	全绿方可提交

3.6 Git 与提交规范

工程纪律：本地 commit 可执行；脚手架搭建与 git push 前必须经用户确认（逐次确认）。
提交信息：conventional commits（feat: / fix: / chore: / docs: / refactor:）；影响 shared 的提交在正文标注 affects: student,parent,teacher。
提交前自检：三端 build 通过；敏感值未入库（.env 走 .gitignore，仅 .env.example 入库）。

4. 构建与本地运行

pnpm install                        # 工作区安装
pnpm --filter student dev           # 单端开发（student / parent / teacher）
pnpm -r build                       # 三端全量构建 → apps/*/dist/（部署经 nginx 按端分发）

环境变量（各端 .env.example 入库，实际 .env.* 不入库）：VITE_API_BASE（后端 base）、VITE_WECHAT_APPID（家长端微信入口）。

5. 与文档目录的关系

本仓库只放移动端代码；家长绑定、费用、练习契约见工作区文档库 academic/05-architecture/ 与 teaching/05-architecture/；学生端契约兼容基线见 unified/00-planning/cross-system-reconciliation.md §5。
与 PC 端仓库共享编码惯例（统一信封/脱敏/权限码/commit 规范），差异仅在 UI 库（Vant）与 monorepo 形态。