hms/docs/discussions/2026-05-13-development-process-retrospective.md

# HMS 开发流程阶段总结与优化 — 多专家组发散式讨论

> 日期: 2026-05-13 | 参与者: iven, Claude（六位虚拟专家）
> 数据基准: 770 次提交 / 175 次 fix（22.7%）/ 近月 24% fix 率
> 关联: [质量系统性预防方案](../docs/discussions/2026-05-08-quality-systemic-prevention.md) | [六维度分析](../docs/superpowers/specs/2026-05-11-system-comprehensive-analysis-design.md)

---

## 1. 背景与数据概览

HMS 项目自 2026-04-10 首次提交以来，历经 33 天密集开发，累计 770 次提交。系统已从 MVP 成长为包含 17 个 Rust crate、297 个前端文件、66 个小程序页面的中型医疗 SaaS 平台。

但开发过程中暴露了一个不可忽视的信号：**近 1/4 的提交在修 bug**。

### 1.1 核心数据

| 指标 | 值 | 含义 |
|------|-----|------|
| 总提交 | 770 次 | 33 天，日均 23 次 |
| fix 类型提交 | 175 次（22.7%） | 近 1/4 的提交在修 bug |
| 近月 fix 率 | 151/630 = 24.0% | 趋势未改善 |
| 单次批量 fix 最高 | 16 个问题 | 角色测试 V3 一轮发现 16 个 |
| 角色测试总发现 | 27 个独立问题（4 轮） | 测试→发现→修复周期长
| V1→V2 审计 | 新增 21 个问题 | 新代码持续引入新 bug |

### 1.2 fix 提交类别分布（全部 175 次）

| 类别 | 次数 | 占比 | 典型模式 |
|------|------|------|---------|
| 前后端接口不一致 | ~35 | 20% | 字段名/路径/类型不匹配 |
| 权限/菜单/路由 | ~25 | 14% | 权限码散落、菜单不可见 |
| 安全（租户隔离/PII） | ~25 | 14% | SQL 注入、越权、CORS |
| 小程序特有问题 | ~28 | 16% | 登录态、平台限制、Storage |
| 后端开发了前端未集成 | ~10 | 6% | 硬编码假数据、缺失对接 |
| 数据库/迁移 | ~15 | 9% | 表名错误、SQL 方言、幂等性 |
| 状态管理/竞态 | ~15 | 9% | 事件链断裂、CAS、并发 |
| 其他（编译/UX/AI） | ~22 | 13% | 类型错误、AI 模型适配 |

### 1.3 时间线上的问题密度

```
4 月 10-15 日  ██████  基础设施搭建 + 首批权限问题（fix 15 次）
4 月 16-22 日   ████████  核心医疗模块 + 安全首次审计（fix 28 次）
4 月 23-28 日   ██████████  内容管理+AI+透析扩展（fix 35 次，高峰）
4 月 29-5 月 4  ██████████  V1 审计 + 质量加固（fix 30 次）
5 月 5-8 日     ████████████  角色测试 4 轮迭代（fix 45 次，最高峰）
5 月 9-13 日    ████████  媒体库+轮播图+Copilot（fix 22 次）
```

**观察：fix 密度在 5 月 5-8 日达到最高峰**，原因是 4 轮角色测试集中发现了 27 个问题。这表明大量 bug 在引入后数天甚至数周才被发现，而非在开发时就被拦截。

---

## 2. 问题目录 — 八类问题的具体案例与根因

### 2.1 前后端接口不一致（~35 次 fix，占比最高）

这是出现频率最高的问题类型，贯穿整个项目周期。

**问题 A：字段名不匹配**
- 后端 DTO 用 `consultation_type`，前端写 `type` → 请求 422
- 后端 DTO 用 `planned_date`，前端写 `due_date` → 数据丢失
- 后端返回 `unread_count_patient`，前端读 `unread_count` → 显示 NaN
- commit: `c53f562` fix(web,miniprogram): 端到端测试修复 + 33 接口字段对齐

**问题 B：请求体结构不匹配**
- 后端 `CreateFollowUpRecordReq` 要求 `{task_id, result, patient_condition}`，前端传 `{task_id, content:{text}}` → 422
- commit: `8316281` fix(miniprogram): 修复 API 接口字段对齐 -- 33 接口端到端验证
- commit: `fbb28e6` fix(miniprogram): submitRecord 补充 task_id 字段

**问题 C：返回数据格式不匹配**
- 后端 `Vec<(NaiveDate, f64)>` 序列化为数组 `[[date, value]]`，前端期望对象 `[{date, value}]` → 趋势图不显示
- commit: `1f8fd04` fix(health): 趋势图数据不显示 -- 后端 DTO 元组转结构体

**问题 D：遗漏字段**
- 后端文章列表 API 缺少 `version` 字段，前端更新时无法做乐观锁 → 更新覆盖
- commit: `96b952c` fix(health): 文章列表 API 补充 version 字段

**根因**：后端 Rust DTO 和前端 TypeScript 接口各自维护，没有任何自动同步机制。后端改了字段名，前端不知道。

---

### 2.2 权限/菜单/路由问题（~25 次 fix，持续时间最长）

从 4 月 11 日到 5 月 10 日，权限相关 fix 持续出现 29 天，是最顽固的问题类别。

**问题 A：权限码格式不统一**
- seed 迁移用冒号分隔 `health:patient:list`，handler 检查用点号 `health.patient.list` → **所有权限检查返回 403**
- commit: `0d7d3af` fix(auth): 权限编码冒号改点号 + 补充缺失权限

**问题 B：菜单三重配置遗漏**
- 媒体库菜单不可见，排查发现三个独立问题：
  1. parent_id 查找条件错误（指向不存在的父菜单）
  2. menu INSERT 缺少 permission 字段
  3. 缺少 menu_roles 角色关联
- commit: `edb4b65` fix(health): 修复媒体库和轮播图菜单不可见 -- 三重修复

**问题 C：路由注册方式导致中间件泄漏**
- Axum `.merge()` 导致 middleware 泄漏到整个路由树，公开端点被加了认证中间件
- 改用 `.nest()` 隔离后才修复
- commit: `84b671d` fix(server+health): 修复路由 middleware 泄漏

**问题 D：权限码缺 .list 导致 403**
- 每个实体需要 `.list` + `.manage` 两个权限码，漏掉 `.list` 列表页直接 403
- 这个问题在 CLAUDE.md 反模式中已有警告，但仍反复出现

**根因**：权限系统涉及 4 层同步（handler 权限码 → seed 迁移 → 前端路由 meta → 菜单可见性），每加一个功能需手动同步 4 处，遗漏率几乎 100%。

---

### 2.3 安全问题（~25 次 fix，4 轮审计才收敛）

**问题 A：SQL 注入**
- `action_inbox_service.rs` 用 `format!` 拼接 `patient_id`/`user_id` 到 SQL → 注入向量
- commit: `2b90db4` fix(health): P0 安全修复

**问题 B：FHIR 越权**
- `allowed_patient_ids` 已声明但未在查询层强制执行 → 第三方可访问非授权患者数据
- commit: `2b90db4` + `4828713` fix(health): FHIR 子查询添加 tenant_id 过滤

**问题 C：开发配置泄漏到生产**
- JWT Secret 硬编码 `"dev-secret-key"` 作为 fallback
- CORS 通配符 `*` 在生产环境生效
- commit: `f7bf5a8` fix(server): CORS 生产环境拒绝通配符

**问题 D：默认放行模式**
- OAuth 端点无权限检查、限流默认放行、Redis 不可达时直接放行
- 每次安全审计都发现同类问题：**开发便利优先，生产安全靠人工事后加固**
- commit: `080d2cb` fix(security): 限流 fail-closed + 多租户安全加固

**根因**：缺乏"安全默认"原则。所有新端点默认放行，需要开发者主动加限制 → 必然遗漏。

---

### 2.4 小程序特有问题（~28 次 fix）

**问题 A：登录态管理混乱**
- 退出登录后刷新仍保持登录态（Storage 未清理）
- useDidShow 生命周期中认证恢复失败
- 页面间用 Storage 传递数据，刷新后丢失
- commit: `3c828bf` + `6632985` + `f75bc19`

**问题 B：微信平台限制未适配**
- `<image>` 不支持 HTTP URL（轮播图 404）
- 域名白名单未配置
- commit: `4788e19` fix(health,miniprogram): 轮播图改用相对路径

**问题 C：关怀模式（老年适配）**
- 非线性放大计算错误，页面尺寸异常
- 20px 字号低于适老阈值 22px
- commit: `4335f7e` + `257ca94`

**根因**：小程序 124 文件 0 测试，质量保障完全真空。所有问题靠手动发现。

---

### 2.5 后端开发了但前端未集成（~10 次 fix）

**问题 A：前端仍用硬编码假数据**
- 运营仪表盘、统计页、系统信息页在 API 就绪后仍显示假数据
- commit: `2e4d98c` fix(web): 统计页空列表接入真实 API + 运营待办去硬编码

**问题 B：新端点已开发但未对接**
- `GET /health/vital-signs/today` 后端已开发，前端未调用
- commit: `d26a847` fix(health): 对接今日体征摘要新端点

**问题 C：后端返回关联数据但前端仍显示原始 ID**
- 告警详情显示原始 patient_id / rule_id，未做关联展示
- commit: `0acf901` fix(web): 告警详情显示患者名和规则标题替代原始 ID

**根因**：前后端开发节奏不同步，后端先完成但无机制追踪前端是否已集成。

---

### 2.6 数据库/迁移问题（~15 次 fix）

**问题 A：表名单复数混用**
- Entity 定义用 `tenant`（单数），迁移 SQL 写 `tenants`（复数）→ 外键引用失败
- commit: `a174f88` fix(migration): 修复表名 tenants 改为 tenant

**问题 B：SQL 方言不兼容**
- PostgreSQL `DELETE` 不支持 `LIMIT`，迁移脚本写成了 MySQL 语法
- commit: `d5c9654` fix(db): 修复 SQL 语法 + RLS 动态表名查询

**问题 C：迁移非幂等**
- 多次执行同一迁移会报唯一约束冲突
- commit: `99dad17` fix(server+health): 修复迁移幂等性

**根因**：迁移脚本缺乏在 fresh database 上的自动验证。

---

### 2.7 状态管理/竞态条件（~15 次 fix）

**问题 A：Token 刷新并发竞态**
- 同一 refresh token 并发使用两次，先查后改非原子操作 → token 失效
- commit: `3e1413a` fix(auth): 修复 Token 刷新并发竞态条件

**问题 B：事件链断裂**
- `consultation.new_message` 和 `lab_report.reviewed` 事件已发布但消费者未注册 → 功能静默失败
- commit: `ef0b784` fix(health): 修复两条断裂事件链

**问题 C：CAS 条件过严**
- 预约 CAS 精确匹配排班时段，时区偏移导致匹配失败
- commit: `9b8c2ff` fix(health): 预约 CAS 从精确匹配改为范围匹配

**根因**：事件消费者注册无启动时检查，CAS 操作缺乏统一封装。

---

### 2.8 编译/UX/AI 等其他问题（~22 次 fix）

**编译/类型错误** — 10 处 TypeScript 编译错误（`fb809f1`）、Rust 类型不匹配（`7ab89f5`）
**AI 模型适配** — qwen3 thinking 模式导致输出为空（`b1a96ac`）、分析结果 JSON 嵌套（`1f91dcc`）
**UX 微调** — 文章预览尺寸（`6269815`）、仪表盘浮点精度（`0721733`）

这类问题量小且影响有限，不作为流程优化重点。

---

## 3. 连锁效应分析 — "修一个，冒两个"

开发过程中最让人沮丧的不是单个 bug，而是修了 A 之后发现 B 也坏了。以下是三个典型案例。

### 3.1 媒体库五连修（5 月 10 日，5 次连续 fix）

```
step 1: 实现媒体库 + 轮播图（feat 提交 ×5）
step 2: fix — 图片不显示，缺 /uploads Vite 代理
step 3: fix — 修完路径后图片 401，需要 JWT token
step 4: fix — Web 修好了，小程序轮播图又 404（HTTP 限制）
step 5: fix — 图片修好了，菜单看不到（三重配置遗漏）
step 6: fix — 迁移外键引用表名错误
```

**一个功能，5 次 fix，每次只发现一类问题。** 如果有功能完成检查清单（DoD），第一步就能发现所有 5 类问题。

### 3.2 权限系统贯穿全周期（4 月 11 日 → 5 月 10 日，29 天未收敛）

```
4/11  fix: 权限编码冒号→点号 + 补充缺失权限
4/16  fix: 移除权限 fallback（必须显式分配）
4/24  fix: 修复路由 middleware 泄漏
4/25  fix: 权限同步 + 迁移幂等性
5/05  fix: 权限同步修复（又发现遗漏）
5/06  fix: 权限守卫、权限配置问题
5/07  fix: 权限越权（角色测试发现）
5/10  fix: 菜单不可见（媒体库，又是权限问题）
```

**29 天内持续出现，每次修了"一处"但"其他处"仍然不一致。** 根本原因是权限定义散落在 4 处，没有单一真相源。

### 3.3 角色测试四轮迭代（5 月 5-8 日，10 次批量 fix）

```
第 1 轮: 发现 5 个共性问题 → fix
第 2 轮: 发现 8 个问题 → fix
第 3 轮: 发现 4 个共性问题 → fix
第 4 轮: 发现 7 个问题 → fix
       小程序多角色找茬: 16 个问题 → fix
       小程序 V2: 11 个问题 → fix
       小程序 V3: 8 个问题 → fix
       业务链路测试: 3 类问题 → fix
```

**10 次批量 fix 才收敛。** 如果每个功能在开发时就有基本的端到端验证，这些问题在第一次角色测试前就应该被拦截。

### 3.4 连锁效应的根本原因

| 根本原因 | 表现 | 涉及的 fix 次数 |
|---------|------|----------------|
| **缺少功能完成检查清单** | 每次只修一类问题，不全面验证 | ~60 次 |
| **同步点散落在多处** | 修了一处忘了另一处 | ~40 次 |
| **验证滞后** | 开发时不验证，测试/审计时集中发现 | ~50 次 |

---

## 4. 六位专家发散讨论

基于以上问题目录，召集六位虚拟专家从不同视角讨论流程改进方案。

### 专家 1：流程架构师 — "为什么同样的问题反复出现？"

**核心论点：24% fix 率不是代码质量问题，是流程缺失问题。**

1. **缺少 Feature DoD（功能完成定义）**
   - 现状：代码写完 → 提交 → 下一个功能。没有统一的完成标准。
   - 媒体库 5 次 fix 说明：每次只验证了一类问题，没有"全量验证"步骤。
   - 建议：建立 Feature DoD 清单，写入 CLAUDE.md，每个功能标记"完成"前必须逐项检查。

2. **反馈周期太长**
   - bug 在引入后数天甚至数周才被发现（角色测试时），修复成本指数级增长。
   - 角色测试 4 轮才收敛（27 → 11 → 8 → 3），而不是一轮完成。
   - 建议：每个功能完成时立即做 5-10 分钟的端到端手动验证。

3. **没有"破坏性变更"意识**
   - 新增迁移/路由/权限时不检查是否影响已有功能。
   - V1→V2 审计发现 21 个新问题，说明新代码持续引入回归。
   - 建议：CI 增加基于 diff 的定向回归测试。

**"如果只能改一件事"：** 建立 Feature DoD 清单并强制执行。

---

### 专家 2：质量工程专家 — "测试是写代码前的契约，不是写完后的补救"

**核心论点：测试金字塔倒挂严重，前端几乎无自动化保障。**

1. **后端测试量大但结构性缺陷**
   - 999 个测试函数，但异步测试仅 184 个（18.4%）。
   - 并发预约、事件消费、多租户隔离等核心路径缺异步集成测试。
   - 预约并发 bug 只在角色测试时被发现，单元测试无法捕获。

2. **前端测试覆盖率严重不足**
   - Web：297 文件 / 62 测试文件（1:4.8）
   - 小程序：124 文件 / **0 测试** — 质量保障真空
   - 小程序 31 次 fix 中大部分是状态管理和 API 对接问题，自动化测试完全可以预防。

3. **缺少"错误预算"概念**
   - fix 率 24% 没有目标、没有趋势监控。
   - 建议：设定 fix 率目标 < 15%，每周跟踪趋势。

**"如果只能改一件事"：** 给小程序补 service 层测试。124 文件 0 测试是最大质量真空。

---

### 专家 3：安全审计专家 — "安全靠设计时预防，不靠事后发现"

**核心论点：25 次安全 fix 中 80% 可以通过安全 lint 在提交前拦截。**

1. **安全修复模式高度重复**
   - 每次都是同一个模式：默认放行 → 发现问题 → 收紧。
   - CORS 通配符、OAuth 无权限、FHIR 越权、限流放行 — 本质都是"默认放行"。
   - 建议：建立"安全默认"原则 — 所有新端点默认拒绝，必须显式声明权限。

2. **租户隔离反复遗漏**
   - 从 4 月 11 日到 5 月 5 日，24 天内租户隔离问题出现 5 次。
   - 每次审计都发现新的遗漏点。
   - 建议：租户过滤统一中间件，禁止手写 tenant_id 过滤。

**"如果只能改一件事"：** 在 CLAUDE.md 增加"新增端点安全检查清单"。

---

### 专家 4：DevOps/自动化专家 — "人能记住的事，不应该靠人记住"

**核心论点：24% fix 率的本质是手动同步成本。**

1. **权限码 4 处手动同步是最大系统性 bug 源**
   - handler / seed / 路由 meta / 菜单 — 每加一个功能同步 4 处，遗漏率 100%。
   - 12+ 次权限相关 fix，每次都是"忘了同步第 N 处"。
   - 建议：`permissions.yaml` 单一真相源 + 构建时自动生成。

2. **缺少 CI 质量门禁**
   - 当前只有 `cargo check` + `cargo test`，没有权限完整性检查、路径一致性检查、安全 lint。
   - 建议：CI 增加 4 个门禁（权限/路径/安全/覆盖率）。

3. **OpenAPI 注解 33%，前端完全不用 spec**
   - 后端生成 spec，前端手写路径，两边必然分叉。
   - 建议：openapi-typescript 自动生成前端 API 客户端。

**"如果只能改一件事"：** 实施 `permissions.yaml` 单一真相源。消除 12+ 次 fix 的根因。

---

### 专家 5：产品/需求管理专家 — "功能冻结≠冻结完成，而是冻结了技术债"

**核心论点：需求推进速度 > 质量保障速度。**

1. **6 个冻结模块是隐性成本**
   - 护理计划 44 分、班次 41 分 — 完成度极低但持续占用编译体积和认知负担。
   - 建议：冻结超时策略 — 冻结 > 2 周自动触发决策（完成或移除）。

2. **缺少质量红线**
   - 770 次提交中 24% 是 fix，说明需求推进速度远超质量保障速度。
   - 建议：fix 率 > 20% 时新功能需额外审批。

3. **缺少"最小可验证增量"**
   - 媒体库一次提交 5+ 个 crate 的改动，验证只能事后进行。
   - 建议：拆分为更小的可验证增量，每步有明确验证标准。

**"如果只能改一件事"：** 设定质量红线 — fix 率 > 20% 时优先偿还技术债。

---

### 专家 6：技术债务分析师 — "债务不可怕，可怕的是不可见"

**核心论点：技术债缺乏可视化管理。**

1. **已完成的技术债偿还**
   - event.rs 2871 行 → 已拆分为 13 个领域文件
   - module.rs 1595 行 → 已拆分为 13 个子模块

2. **未处理的技术债**
   - erp-health 仍为巨石（189 文件，12 子域）
   - utoipa 注解 33%
   - 小程序 0 测试
   - 6 个冻结模块

3. **建议：建立技术债看板**
   - 量化每项债务的"利息"（修复频率 × 修复成本）
   - 每个迭代 20% 时间用于偿还

**"如果只能改一件事"：** 建立技术债看板，让债务利息可视化。

---

## 5. 共识与行动方案

### 5.1 六位专家的共识

| # | 共识 | 专家一致性 |
|---|------|-----------|
| C1 | 24% fix 率是系统性流程问题，非个别代码质量问题 | 6/6 |
| C2 | 权限码 4 处手动同步是最高优先级的自动化目标 | 6/6 |
| C3 | 小程序 0 测试是最大质量真空 | 5/6 |
| C4 | 缺少 Feature DoD 是 fix 反复出现的直接原因 | 6/6 |
| C5 | 前后端接口不一致的根因是缺少契约自动同步 | 6/6 |
| C6 | 新需求推进速度 > 质量保障速度 | 6/6 |

### 5.2 分歧与权衡

| 议题 | 观点 A | 观点 B | 建议 |
|------|--------|--------|------|
| 新功能 vs 技术债 | 设质量红线，fix > 20% 停新功能 | 过于刚性，影响交付 | **软红线**：fix > 20% 时新功能需额外审批 |
| 权限注册表方案 | YAML 单一真相源 + 自动生成 | 改造成本高，先用 lint | **分两步**：先 lint 拦截，再迁移 YAML |
| 小程序测试策略 | 先补 service 层接口测试 | 先补关键页面 E2E | **service 层优先**（投入产出比更高） |
| 冻结模块处理 | 立即决定：完成或移除 | 等有资源时处理 | **冻结超时**：> 2 周自动触发决策 |

### 5.3 行动方案（按优先级排序）

#### P0 — 立即实施（1-2 天见效）

| # | 行动 | 投入 | 消除的 fix 类别 |
|---|------|------|----------------|
| P0-1 | **建立 Feature DoD 清单**，写入 CLAUDE.md | 2h | 权限遗漏、菜单不可见、安全默认、前后端不一致 |
| P0-2 | **新增端点安全检查清单**，写入 CLAUDE.md | 1h | CORS/OAuth/限流/脱敏遗漏 |
| P0-3 | **CLAUDE.md 增加前后端同步检查项** | 1h | 字段名/路径/类型不匹配 |

#### P1 — 本周实施（3-5 天见效）

| # | 行动 | 投入 | 消除的 fix 类别 |
|---|------|------|----------------|
| P1-1 | **权限注册完整性 CI 检查**：handler 权限码 vs seed 一致性 | 4h | 权限码不一致 |
| P1-2 | **API 路径一致性 CI 检查**：前端 API 路径 vs 后端 OpenAPI spec | 1d | 前后端路径分叉 |
| P1-3 | **小程序 service 层测试**（29 个文件） | 2d | 小程序 API 对接问题 |
| P1-4 | **`createProtectedRoute()` wrapper** — 不声明权限码则无法创建路由 | 0.5d | 路由守卫遗漏 |

#### P2 — 下阶段实施（持续改进）

| # | 行动 | 投入 | 效果 |
|---|------|------|------|
| P2-1 | `permissions.yaml` 单一真相源 + 自动生成 | 3-5d | 根除权限同步问题 |
| P2-2 | openapi-typescript 自动生成前端 API 客户端 | 2-3d | 根除路径分叉 |
| P2-3 | 冻结模块策略（完成/移除/超时） | 1d | 减少隐性技术债 |
| P2-4 | 技术债看板建立 | 1d | 债务可视化 |
| P2-5 | fix 率趋势监控（每周跟踪） | 0.5d | 质量趋势感知 |

### 5.4 度量体系

| 指标 | 当前值 | 目标值 | 测量方式 |
|------|--------|--------|---------|
| fix 率 | 24% | < 15% | fix 提交数 / 总提交数 |
| 权限同步遗漏 | 12+ 次/月 | 0 次 | CI 检查结果 |
| 前端测试文件 | 62/297 | 120/297 | 文件计数 |
| 小程序测试 | 0 文件 | 29 service 全覆盖 | 文件计数 |
| 单次批量 fix | 16 个 | < 5 个 | 单次提交修复数 |

### 5.5 质量红线

| 红线 | 触发条件 | 行动 |
|------|---------|------|
| fix 率 > 20% | 连续 2 周 | 新功能需额外审批 |
| 单次批量 fix > 10 | 单次提交 | 回溯 DoD 是否执行 |
| 安全 CRITICAL | 审计发现 | 立即修复，暂停其他 |

---

## 附录 A：Feature DoD 清单（建议版本）

每个功能标记"完成"前，必须通过以下检查清单：

```markdown
## Feature DoD — 功能完成检查清单

### 后端
- [ ] Entity 包含所有标准字段（id/tenant_id/created_at/updated_at/deleted_at/version）
- [ ] Handler 添加 require_permission 权限守卫
- [ ] 权限码已写入 seed 迁移（.list + .manage）
- [ ] utoipa 注解已添加（OpenAPI 文档可见）
- [ ] Service 层核心路径有单元/集成测试
- [ ] 多租户隔离正确（tenant_id 过滤）
- [ ] 输入验证完整（必填字段 + 格式校验）
- [ ] 错误处理统一（AppError，不 panic）
- [ ] 关键操作有 tracing 日志

### 前端（Web）
- [ ] API 路径与后端 OpenAPI spec 一致
- [ ] 路由使用 createProtectedRoute 并声明权限码
- [ ] 菜单配置已更新（可见性 + 权限关联）
- [ ] 错误状态有用户友好提示
- [ ] 不使用 any 类型

### 前端（小程序）
- [ ] Service 层接口契约与后端 DTO 一致
- [ ] 登录态处理正确（useDidShow 恢复）
- [ ] 长者模式适配完成
- [ ] 无硬编码路径

### 安全
- [ ] 新增端点有权限声明（非默认放行）
- [ ] 敏感数据有脱敏/加密处理
- [ ] 用户输入已验证和消毒
- [ ] 无 CORS 通配符

### 验证
- [ ] cargo check 全 workspace 通过
- [ ] cargo test 全部通过
- [ ] 浏览器中手动验证功能正常
- [ ] 相关路由权限按角色测试通过
```

---

## 结论

**核心洞察：24% fix 率的根因不是"代码写得不好"，而是"流程让好代码也容易出错"。**

权限散落 4 处、前后端类型各自维护、缺少完成检查清单、验证滞后 — 这些是系统性问题，需要系统性解决。

**最有效的三件事：**
1. **Feature DoD**（2h 投入）— 让每次提交都经过全量检查
2. **权限/路径 CI 一致性检查**（1-2d 投入）— 让不一致无法通过 CI
3. **小程序 service 层测试**（2d 投入）— 填补最大质量真空

这三件事做完，预计 fix 率可从 24% 降至 15% 以下。