docs: 补充 V4.0 需求规格说明书（小程序+后端）

docs/需求规格说明书-V4.0-小程序与后端.md

@@ -0,0 +1,657 @@
+# 明缘云道场小程序 + 后端 API · 需求规格说明书 V4.0
+
+> 基于 `miniprogram/`（微信小程序前端）和 `server/`（FastAPI 后端）实际代码反向整理。
+> 与 V2.0/V3.0（涵盖 Web 主站 + 学员网站）平行存在；本文档 **仅覆盖这两个子系统**。
+> 
+> · 适用范围：`miniprogram/`、`server/`、`server/migrations/`
+> · 反向工程日期：2026-09-10
+> · 反向基线：`git` 工作树（HEAD = 当前）
+
+---
+
+## 目录
+
+1. 文档信息
+2. 项目概述
+3. 用户角色与权限
+4. 术语表
+5. 小程序前端（miniprogram/）
+6. 后端 API（server/）
+7. 数据模型
+8. 部署与配置
+9. 安全与合规
+10. 非功能性需求
+11. 错误约定
+12. 已知问题与 TODO
+
+---
+
+## 1. 文档信息
+
+| 项     | 内容                                                  |
+| ----- | --------------------------------------------------- |
+| 软件名称  | 明缘云道场小程序（前端）+ 明缘进阶场 API（后端）                         |
+| 版本    | V1.0 / V4.0 文档                                      |
+| 平台    | 前端：微信小程序 · 后端：Linux + Python 3.9 + FastAPI          |
+| 关键依赖  | 微信开发者工具 · PyMySQL + DBUtils · httpx · python-dotenv |
+| 客户端入口 | 微信内搜索 / 扫码进入「明缘云道场」                                 |
+| 服务端入口 | uvicorn `server.main:app` 监听 `:8000`                |
+| 文档目的  | 把代码事实定型为可验收的需求规格                                    |
+
+---
+
+## 2. 项目概述
+
+### 2.1 子系统定位
+
+| 子系统    | 代码路径           | 角色                                             |
+| ------ | -------------- | ---------------------------------------------- |
+| 小程序前端  | `miniprogram/` | 用户交互入口（打卡 / 计划 / 个人），本地无状态，所有数据走后端 API         |
+| 后端 API | `server/`      | 鉴权、业务逻辑、MySQL 读写、文件存储、WebView 桥接               |
+| 微信生态   | 微信开放接口         | `wx.login` 换取 openid、`getuserphonenumber` 绑手机号 |
+
+### 2.2 业务目标
+
+为「明缘进阶场」体系的成员提供基于微信的 **轻量化学习管理工具**，核心是：
+
+1. **每周打卡**（周日上课日）
+2. **周 / 月 / 年计划** 三级管理
+3. **小组统计**（学员互看，管理员全览）
+4. **个人主页**（资料、头像、登录方式）
+5. 内嵌 **H5 复用既有 Web 复盘系统**（通过 WebView + cookie 桥接）
+   
+   ### 2.3 不在范围内（明确）
+- 不在前端代码内的子系统（Web 主站 `xinhuo/19qi/18qi/`、学员站）——见 V3.0
+- 不做支付、不做 IM、不做推送（小程序代码中无相关痕迹）
+- 不做服务端渲染 SSR
+
+---
+
+## 3. 用户角色与权限
+
+### 3.1 角色矩阵
+
+代码侧只识别两种角色（`auth_users.role` 字段）：
+
+| 角色键                                                      | 中文       | 判定方式                                             | 用例                   |
+| -------------------------------------------------------- | -------- | ------------------------------------------------ | -------------------- |
+| `teacher`                                                | 管理员 / 老师 | `(user.role or '').strip().lower() == 'teacher'` | 看所有小组、看未分组人数、看全部打卡统计 |
+| 其他（含 `student`、`member`、`leader`、`group_leader`、`admin`） | 成员 / 组长  | 非 teacher 走学员分支                                  | 只看自己所在小组的数据          |
+
+> 注：`ROLE_LABELS`（`pages/profile/profile.js`）将 `student/member → 成员`、`teacher/admin → 管理员`、`leader/group_leader → 组长`，但后端权限只认 `teacher`，其他角色后端一律视作学员。
+
+### 3.2 权限矩阵
+
+| 接口前缀                                 | 学员               | 老师                |
+| ------------------------------------ | ---------------- | ----------------- |
+| `/api/v1/auth/*`                     | ✅ 自助             | ✅ 同左              |
+| `/api/v1/profile`                    | ✅ 自己             | ✅ 自己              |
+| `/api/v1/profile/avatar`             | ✅ 自己             | ✅ 自己              |
+| `/api/v1/checkin/weeks`              | ✅                | ✅                 |
+| `/api/v1/checkin/groups`             | ✅（仅看自己小组）        | ✅（看全部 + 未分组数）     |
+| `/api/v1/checkin/group`              | 仅自己小组（传他组 → 403） | 任意小组（不传看自己）       |
+| `/api/v1/checkin` POST               | ✅ 自己             | ✅ 自己              |
+| `/api/v1/checkin/list`               | ✅ 自己历史           | ✅ 自己历史            |
+| `/api/v1/plan/*` GET                 | ✅ 看自己 / 自己小组     | ✅ 看全部 + 未分组数      |
+| `/api/v1/plan` POST `/checkin`       | ✅ 自己当前周期         | ✅ 自己当前周期（限当前周期）   |
+| `/api/v1/plan/file/{sid}/...` DELETE | 仅自己 sid（403）     | 仅自己 sid（403）      |
+| `/api/v1/webview/redirect`           | 凭 token          | 凭 token（所有权限同 H5） |
+| `/api/v1/survey/*`                   | ✅                | ✅（无鉴权）            |
+| `/api/v1/feedback` GET               | ⚠ 无鉴权（已知问题）      | ⚠ 无鉴权（已知问题）       |
+| `/api/v1/course-vote`                | ✅ 自己投            | ✅ 自己投             |
+| `/api/v1/yijing/*`                   | ✅                | ✅                 |
+
+---
+
+## 4. 术语表
+
+| 术语                    | 含义                                                                                |
+| --------------------- | --------------------------------------------------------------------------------- |
+| openid                | 微信用户唯一标识，由 `code_to_openid(code)` 换取                                              |
+| token / session token | 64 位 hex，会话标识，写入 `auth_sessions` 表（不是 JWT，名字沿用老 JWT 配置）                           |
+| class_date            | 上课日 = 每周周日（周一 ~ 周日组成的自然周）                                                         |
+| period_key            | 计划周期键：周=YYYY-Www、月=YYYY-MM、年=YYYY                                                 |
+| 小组（group）             | `auth_users.group` 字段，如「01组」                                                      |
+| display_name          | 形如「01组张三」（仅当 group 形如 `NN组` 时拼接）                                                  |
+| webview 桥接            | 通过 `/api/v1/webview/redirect?token=...&target=...` 把 URL 上的 token 换成 cookie 再 302 |
+
+---
+
+## 5. 小程序前端（miniprogram/）
+
+### 5.1 全局结构
+
+```
+miniprogram/
+├── app.js            App 入口：onLaunch 调 ensureLogin → /profile
+├── app.json          7 个页面 + 4 tabBar + 导航主题色
+├── app.wxss          全局基础样式（背景 #FDFBF7、主色 #C67B30）
+├── project.config.json
+├── project.private.config.json
+├── sitemap.json
+├── assets/           tabBar 图标（home/checkin/plan/profile × 2）
+├── utils/
+│   ├── api.js        request / planFileUrl / 环境切换 / 401 跳登录
+│   └── auth.js       ensureLogin 单例 + loginWithPhone + token 存取
+└── pages/
+    ├── home/             首页（已登录 → 内嵌 H5；游客 → 原生介绍）
+    ├── checkin/          打卡（老师总览+详情 / 学员小组+个人）
+    ├── plan/             计划总览（周/月/年）
+    ├── plan-submit/      计划提交（文本 + 至多 4 张图）
+    ├── profile/          个人主页（资料 / 头像 / 退出）
+    ├── webview/          通用 WebView（域名白名单）
+    └── privacy/          隐私政策 + 用户协议（静态展示）
+```
+
+### 5.2 主题色与视觉规范
+
+| token | 值                              | 用途            |
+| ----- | ------------------------------ | ------------- |
+| 主背景   | `#FDFBF7`                      | 全站冷色米白底       |
+| 顶栏    | `#2C1810` 渐变 → `#6B3F24`       | Hero 卡背景      |
+| 主交互色  | `#C67B30`                      | 主按钮、未选中状态、强调色 |
+| 成功    | `#2E7D32`（+ 浅底 `#E8F4EB`）      | 「正常」打卡、已完成    |
+| 警示    | `#C0392B`（+ 浅底 `#FDEAEA`）      | 「不参加讨论」、错误页   |
+| 信息    | `#3A7BD5`                      | 「请假」          |
+| 文本主   | `#2C1810`                      | 标题            |
+| 文本辅   | `#8B7A6A` / `#999`             | 描述、时间戳        |
+| 圆角    | `12rpx / 16rpx / 24rpx`        | 卡片、按钮、Hero    |
+| 字号    | 22/24/26/28/30/32/34/40/48 rpx | 时间戳到主标题       |
+
+### 5.3 API 客户端（utils/api.js）
+
+#### 5.3.1 环境切换（多域名）
+
+```js
+getAccountInfoSync().miniProgram.envVersion
+├── 'develop' → baseUrl = https://test.muguaclub.cn/clock
+├── 'trial'   → baseUrl = https://test.muguaclub.cn/clock
+└── 'release' → baseUrl = https://m.muguaclub.cn/clock
+```
+
+- 三个环境对应 `STATIC_BASE_URL` + `H5_BASE_URL` 同源
+
+#### 5.3.2 request 行为约定
+
+| 入参       | 默认     | 说明                                                        |
+| -------- | ------ | --------------------------------------------------------- |
+| `url`    | 必填     | 必须以 `/api/v1` 开头                                          |
+| `method` | `GET`  | 影响幂等重试                                                    |
+| `data`   | `{}`   | 自动 JSON                                                   |
+| `auth`   | `true` | true 时自动从 storage 取 `token` 加 `Authorization: Bearer xxx` |
+
+行为：
+
+- **401** → 删 token + `goProfile()` 切到「我的」页（带 1.2s 防连点锁）
+- **幂等方法（GET / DELETE）** 失败自动 800ms 后重试一次；命中 `domain not` 错误不重试
+- **非 2xx** → reject 原 data（`{error/detail/message}`）
+
+#### 5.3.3 planFileUrl 路径约定
+
+`attachments/{user_id}/{plan_type}/{period_key}/{filename}` →
+`STATIC_BASE_URL + /clock/static/plan/<encoded/path>`
+
+> 前 4 段缺失则返回空串，强制调用方重新加载。
+
+### 5.4 登录态（utils/auth.js）
+
+#### 5.4.1 单例 + 指数退避
+
+- `loginPromise` 全局单例，解决 `App.onLaunch` 与首页 `onShow` 同时调 `ensureLogin` 的竞态
+- `wxLogin` 内部失败重试 3 次（首次 600ms → 800ms → 1000ms）
+- 失败兜底：`wechatLogin` 整个流程失败再重试 1 次（500ms 后）
+- 任何情况下 `loginPromise` 完成后清空 → 让下一次重新发起（避免冷启动偶发失败后卡死）
+
+#### 5.4.2 双入口登录
+
+| 入口     | 触发                                                                                                                  |
+| ------ | ------------------------------------------------------------------------------------------------------------------- |
+| 微信授权登录 | `ensureLogin()` → `/api/v1/auth/wechat-login` 用 code 换 token；后端返回 `need_phone:true` 时 resolve(null)，前端引导到「我的」页绑定手机号 |
+| 手机号登录  | `loginWithPhone(phoneCode)` → `/api/v1/auth/bind-phone` 必须同时传 `code` 和 `phone_code`；绑定成功后写 token 并返回 is_new:true    |
+
+### 5.5 页面清单
+
+#### 5.5.1 home 首页
+
+- **登录态判断**：`isLoggedIn = !!getToken()`
+- **已登录** → `<web-view src="/api/v1/webview/redirect?token=...&target=...">`，key 自增强制重建（解决切 tab 白屏）
+- **未登录** → 原生介绍页（Hero 头图 + 4 个模块卡 + 4 个产品介绍卡 + 引导登录按钮）
+- 提供分享：`onShareAppMessage` / `onShareTimeline`
+
+#### 5.5.2 checkin 打卡（核心）
+
+**老师视图**
+
+- `view = 'overview'`：所有小组打卡进度 + 自己的打卡状态
+- `view = 'detail'`：点开某小组看每个成员是否打卡 / 状态
+
+**学员视图**
+
+- 顶部打卡卡：5 个状态按钮（正常/迟到/请假/不参加讨论/早退），单选切换
+- `tab = 'group'`：本组成员列表
+- `tab = 'personal'`：个人打卡历史（分页，每页 20 条）
+
+**通用交互**
+
+- 周选择器：`/api/v1/checkin/weeks` 返 2022 年到当前的所有上课周六
+- 下拉刷新 + 上拉加载更多（个人历史 tab）
+- 周计划 / 月计划 / 年计划的周期切换（plan 页面公用同一套 picker）
+
+**打卡规则（来自 `routes/checkin.py`）**
+
+- 状态：`正常 / 迟到 / 请假 / 不参加讨论 / 早退`
+- 默认状态 `正常`
+- 备注最大 500 字符（仅非「正常」时允许）
+- 打卡窗口：上课日所在自然周（周一 ~ 周日）与当前周相同 / 未来周可打卡
+
+#### 5.5.3 plan 计划（核心）
+
+- 类型切换 tab：**周计划 / 月计划 / 年计划**
+- 卡片：
+  - 自己的状态（已提交/待提交 + 当前周期）
+  - 「提交 / 修改」按钮，`canSubmit=false` 时 disabled
+  - 窗口提示（如「周四截止，已过提交时间」）
+- 老师视图：所有小组列表
+- 学员视图：tab = 小组（自己成员）/ 个人（历史最多 20 条）
+- 周期 key：
+  - 周 = `YYYY-Www`（ISO 周）
+  - 月 = `YYYY-MM`
+  - 年 = `YYYY`
+
+**提交时间窗（`routes/plan.py`）**
+
+- 周：上一周五 00:00 ~ 本周四 23:59:59
+- 月 / 年：仅当前周期可提交，历史 / 未来都禁止
+
+#### 5.5.4 plan-submit 提交页
+
+| 控件       | 限制                                                                 |
+| -------- | ------------------------------------------------------------------ |
+| textarea | maxlength 1000、disabled=!canSubmit                                 |
+| 图片       | 最多 4 张、允许后缀 `jpg/jpeg/png/gif/webp/bmp`、>1MB 自动逐级压缩 80→60→45       |
+| 删除       | 调 `/api/v1/plan/file/{sid}/{plan_type}/{period}/{filename}` DELETE |
+| 提交       | 文本或图片必有一项；已有记录弹覆盖确认                                                |
+
+**上传协议**：`wx.uploadFile`，`formData = { plan_type, period_key }`，`name='files'`，**支持 multipart 多文件**
+
+#### 5.5.5 profile 个人主页
+
+**视图状态机**：`view ∈ { loading, profile, phoneLogin, loadError }`
+
+- 已登录 + 有 token → 显示完整资料 + 头像 + 班级分组列表 + 退出登录
+- 未登录 / need_phone → 显示手机号登录卡（强依赖隐私协议勾选）
+- chooseAvatar：调 `/api/v1/profile/avatar` 单文件上传，avatar 文件名统一为 `avatar.{ext}`，旧头像自动清理
+- 退出登录：调 `/api/v1/auth/logout`（尽力而为）+ 清本地 token + 清隐私同意标记 + reLaunch 回首页
+
+#### 5.5.6 webview 通用 web-view
+
+- 入参：`url`（必须 URL 编码）
+- **域名白名单**（`isAllowedUrl`）：仅允许 `m.muguaclub.cn` 和 `muguaclub.cn` 及其子域；非法 URL 渲染错误页
+
+#### 5.5.7 privacy 隐私 / 协议页
+
+- 两个静态文档：隐私政策 8 节、用户协议 8 节
+- 通过 query `type` 切换：`privacy` / `agreement`
+- 最后更新日期占位：**2026 年 9 月**
+
+### 5.6 通用 UI 特性
+
+- **骨架屏**：列表 / 表单 / 详情都有 `sk-*` 占位
+- **错误页**：圆形「!」 + 失败文案 + 「重新加载」按钮
+- **空态**：emoji + 简短说明
+- **分享**：所有页面都实现 `onShareAppMessage` + `onShareTimeline`
+
+---
+
+## 6. 后端 API（server/）
+
+### 6.1 工程骨架
+
+```
+server/
+├── __init__.py
+├── main.py           FastAPI() + 挂 9 个 router + /api/v1/health
+├── config.py         从 .env 读所有密钥 / 路径
+├── db.py             PyMySQL + DBUtils PooledDB，单例 per db
+├── security.py       encrypt_phone(hmac-sha256) + create_session_token
+├── wechat.py         code_to_openid + get_phone_number + _get_access_token
+├── user.py           make_display_name + get_class_groups + user_payload
+├── routes/
+│   ├── __init__.py
+│   ├── auth.py       /api/v1/auth/*
+│   ├── checkin.py    /api/v1/checkin/*
+│   ├── plan.py       /api/v1/plan/*
+│   ├── profile.py    /api/v1/profile*
+│   ├── webview.py    /api/v1/webview/redirect
+│   ├── survey.py     /api/v1/survey/*  (无鉴权)
+│   ├── feedback.py   /api/v1/feedback/* (含仅 ADMIN_KEY 的管理接口)
+│   ├── course_vote.py /api/v1/course-vote*
+│   └── yijing.py     /api/v1/yijing/* （从老 Flask 服务迁移）
+└── migrations/
+    ├── 001_add_wechat_openid_column.sql
+    ├── 002_plan_perf_index.sql
+    ├── 003_checkin_records_user_id.sql
+    └── 004_plan_checkins_user_id.sql
+```
+
+> ⚠ 已知 bug（`main.py:29`）：`uvicorn.run("server_prd.main:app", ...)` 引用不存在的包，启动会 ImportError。
+
+### 6.2 全局运行时依赖
+
+| 依赖                 | 作用                                                                                                                       |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------ |
+| FastAPI            | Web 框架                                                                                                                   |
+| uvicorn            | ASGI 运行（默认 :8000，host 127.0.0.1，dev 模式 reload）                                                                           |
+| PyMySQL            | MySQL 驱动                                                                                                                 |
+| DBUtils `PooledDB` | 连接池：`DB_POOL_MIN_CACHED=1 / MAX_CACHED=5 / MAX_CONNECTIONS=10 / MAX_USAGE=100`、ping=1、connect_timeout=5s、read_timeout=5s |
+| httpx              | 调用 `api.weixin.qq.com`（jscode2session / access_token / 手机号解密）                                                            |
+| python-dotenv      | `load_dotenv(dotenv_path, override=True)`                                                                                |
+| pydantic           | 请求体 / 响应模型                                                                                                               |
+
+### 6.3 配置项（config.py）
+
+| 键                                  | 默认                                          | 用途                                           |
+| ---------------------------------- | ------------------------------------------- | -------------------------------------------- |
+| `WECHAT_APPID` / `WECHAT_SECRET`   | 空                                           | 微信 API 凭据                                    |
+| `JWT_SECRET` *                     | 空                                           | **代码里没有真正用上 JWT**，命名沿用历史，实际为 `auth_sessions` |
+| `JWT_ALGORITHM`                    | `HS256`                                     | 同上，遗留                                        |
+| `JWT_TTL_SECONDS`                  | `90*24*3600`（90 天）                          | 会话有效期                                        |
+| `ADMIN_KEY`                        | 空                                           | `/api/v1/feedback/resolve` 管理密钥              |
+| `MYSQL_HOST/PORT/USER/PASSWORD/DB` | `localhost/3306/root/''/mys_info_v3`        | 主业务库                                         |
+| `SURVEY_DB`                        | `myxhxc`                                    | 问卷库（独立库，独立连接池）                               |
+| `PHONE_HMAC_KEY`                   | `MingYuan2026AuthKey`                       | 手机号 HMAC-SHA256 盐                            |
+| `H5_BASE_URL`                      | `http://127.0.0.1:8001`                     | WebView 跳转上游（H5 主站）                          |
+| `FEEDBACK_DIR`                     | `/home/introduction/feedback`               | 用户反馈 JSON + 图片目录                             |
+| `COURSE_VOTES_FILE`                | `/home/introduction/test/course_votes.json` | 课程投票持久化文件                                    |
+| `PLAN_ATTACH_DIR`                  | `/home/static/plan`                         | 计划附件根目录                                      |
+| `STATIC_ROOT` / `AVATAR_DIR`       | `/home/static[/avatars]`                    | 头像静态文件目录（nginx 直读）                           |
+| `DB_POOL_*`                        | 上表                                          | 连接池参数（仅从 os.environ 读，不走 config）             |
+
+> 注：`config.py` 用 `os.environ.get(name, default)`，但 `db.py` 用 `os.environ.get("DB_POOL_*")` 直接读。
+
+### 6.4 数据库连接池（db.py）
+
+- 多库支持：`_get_pool(database)` 按 db 名缓存 pool，**双数据库**（主业务 + survey）
+- `fetch_one / fetch_all / execute` 三个 API，借 / 还连接（`close()` 让连接回池）
+- `close_all()` 用于测试 / reload hook
+
+### 6.5 鉴权（`get_current_user`）
+
+判定顺序：
+
+1. `Authorization: Bearer xxx`（小程序 API 默认）
+2. `Cookie: auth_token=xxx`（H5 走 webview 桥接后自动带）
+3. 都无 → 401
+
+查表：
+
+- `auth_sessions WHERE token=? AND expires_at>NOW()` 拿到 `user_id`
+- 再 `SELECT * FROM auth_users WHERE id=?`
+
+### 6.6 接口约定
+
+#### 6.6.1 /api/v1/auth
+
+| 方法   | 路径              | 鉴权  | 说明                                                                                               |
+| ---- | --------------- | --- | ------------------------------------------------------------------------------------------------ |
+| POST | `/wechat-login` | 否   | `code` → openid → 查 user；命中即发 token，未命中返 `need_phone:true`                                       |
+| POST | `/bind-phone`   | 否   | `code, phone_code` → 拿手机号 → HMAC 查 user；命中即 update `wechat_openid` + 发 token；首次绑定返 `is_new:true` |
+| GET  | `/verify`       | 是   | 返回 `user_payload`                                                                                |
+| POST | `/logout`       | 是   | 删除 session + 清 user.wechat_openid + 删 cookie                                                     |
+
+#### 6.6.2 /api/v1/profile
+
+| 方法   | 路径                | 说明                                                                                                            |
+| ---- | ----------------- | ------------------------------------------------------------------------------------------------------------- |
+| GET  | `/profile`        | user_payload + `phone_display`（注意：**原文里 user 表无 phone_display 字段**，8.2 已知问题） + `wechat_avatar` + `login_type` |
+| POST | `/profile/avatar` | multipart 单文件，4MB 上限，存 `avatar.{ext}`，旧头像自动删；URL `=/clock/static/avatars/{uid}/avatar{ext}`                   |
+
+#### 6.6.3 /api/v1/checkin
+
+| 方法   | 路径                                        | 说明                                 |
+| ---- | ----------------------------------------- | ---------------------------------- |
+| GET  | `/weeks`                                  | 2022 年至当前的所有上课周六列表 + current_week  |
+| GET  | `/week`                                   | **已弃用**，仅供旧客户端                     |
+| GET  | `/groups?class_date=YYYY-MM-DD`           | 老师→全部小组 + 未分组数；学员→自己小组 + my_group  |
+| GET  | `/group?class_date=&group_name=`          | 单组成员 + 各自打卡状态；学员传他组→403            |
+| POST | `/checkin` `{status, class_date?, note?}` | upsert（按 user_id + class_date 唯一键） |
+| GET  | `/list?page=&size=`                       | 个人历史分页，默认 10，上限 50                 |
+
+#### 6.6.4 /api/v1/plan
+
+| 方法     | 路径                                                                       | 说明                                                                                        |
+| ------ | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
+| GET    | `/periods?type=`                                                         | 周/月/年周期列表 + current_period                                                                |
+| GET    | `/status?type=&period_key?=`                                             | 看本期是否已提交 + can_submit + message                                                           |
+| GET    | `/groups?type=&period_key?=`                                             | 老师看全部 + 未分组；学员看自己小组                                                                       |
+| GET    | `/group?type=&group_name=&period_key?=`                                  | 单组成员列表 + 各自 filled                                                                        |
+| POST   | `/checkin` `{plan_type, period_key?, status?, content?, attachments[]?}` | upsert（按 user_id + plan_type + period_key）                                                |
+| GET    | `/history?type=&page=&size=`                                             | 个人历史分页                                                                                    |
+| POST   | `/upload` multipart `{plan_type, period_key, files[]}`                   | 至多 4 文件、每文件 ≤10MB、白名单扩展名、保存路径 `attachments/{user_id}/{plan_type}/{period_key}/{filename}` |
+| GET    | `/file/{sid}/{plan_type}/{period}/{filename}`                            | 直读静态文件                                                                                    |
+| DELETE | `/file/{sid}/...`                                                        | 校验 sid == user.id，否则 403                                                                  |
+
+#### 6.6.5 /api/v1/webview
+
+| 方法  | 路径                         | 鉴权             | 说明                                          |
+| --- | -------------------------- | -------------- | ------------------------------------------- |
+| GET | `/redirect?token=&target=` | 否（凭 URL token） | 校验 token → set HttpOnly cookie → 302 target |
+
+安全要点：
+
+- `target` 仅允许相对路径（`/xxx`）或白名单域 `m.muguaclub.cn` 及其子域
+- cookie：`HttpOnly`、`Secure(scheme=https)`、`SameSite=Lax`、`MaxAge=JWT_TTL_SECONDS`
+
+#### 6.6.6 /api/v1/survey（独立库 `myxhxc`，无鉴权）
+
+| 方法   | 路径                                         | 说明                  |
+| ---- | ------------------------------------------ | ------------------- |
+| GET  | `/tasks`                                   | 状态为 active 的所有 task |
+| GET  | `/responses?task_id=`                      | 某 task 的所有 group 回答 |
+| POST | `/response` `{task_id, group_id, answers}` | upsert              |
+| PUT  | `/response/{rid}` `{answers}`              | 更新已有                |
+| POST | `/task`                                    | 占位，功能预留             |
+
+#### 6.6.7 /api/v1/feedback
+
+| 方法   | 路径                                   | 鉴权        | 说明                                            |
+| ---- | ------------------------------------ | --------- | --------------------------------------------- |
+| GET  | `""`                                 | ❌ 无       | 读所有 json 文件，按 unsolved/solved 倒序              |
+| POST | `""` `{name?, description?, image?}` | 否         | 写一个 4 位 hex id 的 JSON，可附 data:image base64 图片 |
+| GET  | `/file/{name}`                       | 否         | 直读图片                                          |
+| POST | `/resolve?id=&token=`                | ADMIN_KEY | 标记为 solved                                    |
+
+> ⚠ 已知问题：`/feedback` GET 当前无鉴权，任何人能看所有反馈（**安全风险**）
+
+#### 6.6.8 /api/v1/course_vote
+
+| 方法   | 路径                                               | 鉴权  | 说明                             |
+| ---- | ------------------------------------------------ | --- | ------------------------------ |
+| POST | `/course-vote` `{votes[3-6], rating?, comment?}` | 是   | 写入 `COURSE_VOTES_FILE` JSON 文件 |
+| GET  | `/course-votes`                                  | 是   | 聚合（总票数 / 评论均分）+ 我的投票           |
+
+> 用 JSON 文件存，无数据库，便于迁移自老 Flask。
+
+#### 6.6.9 /api/v1/yijing
+
+| 方法   | 路径                                                      | 鉴权  | 说明                                                               |
+| ---- | ------------------------------------------------------- | --- | ---------------------------------------------------------------- |
+| GET  | `/catalog`                                              | 否   | 八卦 + 六十四卦元数据                                                     |
+| GET  | `/progress`                                             | 是   | 5 个阶段（1..5）的学习进度                                                 |
+| POST | `/progress` `{stage[1-5], item_type, item_id, status?}` | 是   | upsert                                                           |
+| POST | `/quiz` `{stage, item_type, item_id, correct, answer?}` | 是   | 记一次尝试，对应进度 score++；score ≥ 2 → mastered；写入 yijing_reviews 用于复习排期 |
+
+### 6.7 后端非业务模块
+
+| 模块                             | 用途                      |
+| ------------------------------ | ----------------------- |
+| `start.sh` / `stop.sh`         | 启停脚本（开发环境）              |
+| `start_prd.sh` / `stop_prd.sh` | 生产环境启停（pid 文件管理）        |
+| `index.html`                   | 部署目录下的 health 静态页       |
+| `requirements.txt`             | 依赖清单                    |
+| `.env`                         | **曾被 git 跟踪，含密钥**（已知问题） |
+| `uvicorn.log`                  | 运行日志                    |
+
+---
+
+## 7. 数据模型
+
+> 由 `auth_users / auth_sessions / classes / groups / class_groups / group_history / checkin_records_old / plan_checkins / yijing_trigrams / yijing_hexagrams / yijing_progress / yijing_attempts / yijing_reviews / survey_tasks / survey_responses` 等表名 / SQL 反推；具体 DDL 不在 `server/` 内。
+
+### 7.1 主业务库（mys_info_v3）
+
+| 表                     | 主键                                                         | 关键字段                                                                                                                                          | 用途                                                      |
+| --------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
+| `auth_users`          | `id`                                                       | `student_id, name, phone_encrypted(HMAC-SHA256), wechat_openid(唯一键), wechat_avatar, login_type, role, \`group\``                              | 用户账号 + 资料                                               |
+| `auth_sessions`       | `id`                                                       | `user_id, token(唯一), expires_at`                                                                                                              | 会话（90 天）                                                |
+| `classes`             | `id`                                                       | `code, name`                                                                                                                                  | 班级（期/班次）                                                |
+| `groups`              | `id`                                                       | `group_code, sort`                                                                                                                            | 小组                                                      |
+| `class_groups`        | (复合)                                                       | `class_id, group_id, user_id, role_in_group`                                                                                                  | 班级 × 小组 × 学员 多对多                                        |
+| `group_history`       | (复合)                                                       | `user_id, class_id, old_group_id, changed_at`                                                                                                 | 学员所在小组变迁                                                |
+| `checkin_records_old` | (复合) `uk_checkin_user_date(user_id, class_date)`           | `user_id, class_date, checked_at, status, note`                                                                                               | **打卡记录**（注：表名保留 `_old` 后缀，迁移按 user_id，详见 migration 003） |
+| `plan_checkins`       | (复合) `uk_plan_user_period(user_id, plan_type, period_key)` | `user_id, plan_type, period_key, status(已完成/未完成), checked_at, content, attachments(JSON), created_at, updated_at` + 索引 `idx_plan_period_user` | 计划记录                                                    |
+| `yijing_trigrams`     | `id`                                                       | `name, symbol, nature, de, family, direction, xiantian, houtian, binary_code, class_xiang, summary`                                           | 八卦（教材化元数据）                                              |
+| `yijing_hexagrams`    | `id`                                                       | `name, full_name, symbol, upper_trigram, lower_trigram, binary_code, judgment, gua_explanation, bagong, gong_wuxing`                          | 六十四卦                                                    |
+| `yijing_progress`     | (复合 stage, item_type, item_id)                             | `user_id, stage, item_type, item_id, status(learning/mastered), score, attempts, correct`                                                     | 学习进度                                                    |
+| `yijing_attempts`     | `id`                                                       | `user_id, stage, item_type, item_id, correct, answer`                                                                                         | 尝试明细                                                    |
+| `yijing_reviews`      | (复合)                                                       | `user_id, item_type, item_id, due_at`                                                                                                         | 复习到期时间                                                  |
+
+### 7.2 问卷库（myxhxc）
+
+| 表                  | 关键字段                               |
+| ------------------ | ---------------------------------- |
+| `survey_tasks`     | `task_no, status(active), ...`     |
+| `survey_responses` | `task_id, group_id, answers(JSON)` |
+
+### 7.3 文件存储
+
+| 路径                                                                     | 用途             |
+| ---------------------------------------------------------------------- | -------------- |
+| `/home/static/avatars/{uid}/avatar{ext}`                               | 个人头像（nginx 直读） |
+| `/home/static/plan/attachments/{user_id}/{plan_type}/{period_key}/...` | 计划附件           |
+| `/home/introduction/feedback/*.json` + `images/*.png`                  | 反馈 JSON + 图片   |
+| `/home/introduction/test/course_votes.json`                            | 课程投票 JSON      |
+
+### 7.4 迁移状态（migrations/）
+
+- **001**：给 `auth_users` 加 `wechat_openid` 唯一键（绑微信前提）
+- **002**：给 `plan_checkins` 加 `(plan_type, period_key, student_id)` 索引（性能，已被 004 替换）
+- **003**：`checkin_records_old` 改按 `user_id` 关联，加唯一键 `(user_id, class_date)`
+- **004**：`plan_checkins` 改按 `user_id` 关联，加 `(user_id, plan_type, period_key)` 唯一键 + 替换索引；附件相对路径从 student_id 改写为 user_id
+
+---
+
+## 8. 部署与配置
+
+### 8.1 启动命令（开发）
+
+```bash
+pip install -r requirements.txt
+# 配置 server/.env：WECHAT_APPID / WECHAT_SECRET / MYSQL_* / PHONE_HMAC_KEY / ADMIN_KEY / H5_BASE_URL
+python -m uvicorn server.main:app --reload --port 8000
+```
+
+### 8.2 启动命令（生产）
+
+```bash
+# 启动
+bash server/start.sh
+# 停止
+bash server/stop.sh
+```
+
+### 8.3 nginx 转发示例（推断）
+
+```
+# /api/v1/* → :8000 (uvicorn)
+# /clock/static/* → /home/static/ (nginx 直读)
+# /clock/api/v1/webview/* → :8000 (cookie 桥接)
+# / → upstream muguaclub.cn / 8001 (H5 主站)
+```
+
+### 8.4 域名与端口
+
+| 角色  | 域名                  | 后端端口                       |
+| --- | ------------------- | -------------------------- |
+| 正式  | `m.muguaclub.cn`    | 8000 (FastAPI) + 8001 (H5) |
+| 测试  | `test.muguaclub.cn` | 同上                         |
+
+---
+
+## 9. 安全与合规
+
+### 9.1 鉴权
+
+- 单 token 体系：所有受保护接口统一用 `get_current_user`（`Authorization` 或 cookie）
+- 退出登录：删 session + 解绑 openid（下次需重新授权手机号）
+- WebView 桥接：URL 上短期 token → cookie，再 302 跳转同站域（防开放重定向）
+
+### 9.2 传输安全
+
+- 头像直链强制 https（`secure=request.url.scheme == "https"`）
+- Cookie `HttpOnly + SameSite=Lax`
+- OpenAPI 全 HTTPS（微信 API 仅 https）
+
+### 9.3 数据安全
+
+- 手机号 HMAC-SHA256 存 `phone_encrypted`，原号不出库
+- 反馈、计划内容、明文入库（小程序端有 maxlength 1000 / 500 限制）
+
+### 9.4 隐私合规
+
+- 「我的」页强制要求勾选隐私政策 + 用户协议才能调 `getPhoneNumber`
+- 隐私协议 8 节；用户协议 8 节；最后更新 2026 年 9 月（占位）
+- 客服邮箱 `[此处填写客服邮箱]` 占位需补充
+
+---
+
+## 10. 非功能性需求
+
+### 10.1 性能
+
+| 维度      | 要求                                  |
+| ------- | ----------------------------------- |
+| 首屏冷启动   | 幂等请求（GET/DELETE）网络错误自动 800ms 重试 1 次 |
+| 单实例 QPS | 与连接池 `maxconnections=10` 匹配；超出排队    |
+| 单次连接    | connect_timeout=5s，read_timeout=5s  |
+| 列表分页    | 打卡默认 10，最大 50；计划默认 10，最大 50         |
+| 客户端压缩   | 计划图片 >1MB 自动 80→60→45 三级降质压缩        |
+| 上传上限    | 单文件 10MB（计划）/ 4MB（头像）               |
+
+### 10.2 可用性
+
+- 单会话 90 天有效，过期即失效（前端需重新登录）
+- 计划历史周期只读（can_submit=false）
+- 学员只能查自己所在小组
+- 切换 tab / 周选择器 / 周期选择器都有 fallback（数据为空时不刷）
+
+### 10.3 可观测性（缺）
+
+代码中未发现业务埋点 / 性能监控 / 错误聚合；`uvicorn.log` 仅记录关键 warn/error（如 `微信登录 code 换取 openid 失败`）。
+
+### 10.4 兼容性
+
+- 小程序基础库 `>=3.0.0`（`wx.getAccountInfoSync`）
+- Python ≥3.9（FastAPI 最低版本）
+
+---
+
+## 11. 错误约定
+
+- HTTP 状态码：
+  - `200` 业务正常
+  - `400` 参数错误（含业务校验：「仅可填写当前周期」「已过打卡时间」等）
+  - `401` 缺 token / token 无效或过期
+  - `403` 无权限（学员查他组 / 删他人附件）
+  - `404` 资源不存在
+  - `500` 未捕获的运行时错误（FastAPI 默认）
+- 错误体：
+  - FastAPI 默认：`{"detail": "..."}`
+  - 业务自定义：`{"error": "..."}` 或 `{"success": false, "error": "..."}` 或 `{"need_phone": true, "error": "..."}`
+- 前端解析顺序（`pages/checkin/checkin.js`）：`err.detail → err.error → err.message`
+
+
+
+---
+
+> 文档结束。如有功能/接口改动，请同步更新本文件章节 5/6 并在文末「更新日志」追加条目。