docs,ci: P2 质量体系 — 技术债看板 + 冻结策略 + fix 率趋势

- 新增 fix-rate-trend.sh: 按周统计 fix 率趋势 + 类别分布当前: 22.8% (177/776), 目标 < 15% - 新增 docs/tech-debt-board.md: 技术债看板含度量总览、高利息债务排序、已偿还债务、偿还优先级 - 新增 docs/discussions/2026-05-13-frozen-module-strategy.md: 6 个冻结模块策略 + 14 天超时规则 + 解冻/移除操作流程
2026-05-13 17:19:07 +08:00
parent e9458a6bdf
commit 20d606d21c
3 changed files with 283 additions and 0 deletions
--- a/docs/discussions/2026-05-13-frozen-module-strategy.md
+++ b/docs/discussions/2026-05-13-frozen-module-strategy.md
@@ -0,0 +1,64 @@
+# 冻结模块策略
+
+> 日期: 2026-05-13 | 参与者: iven, Claude
+
+## 背景
+
+HMS 有 6 个功能模块处于"冻结"状态 — 前端页面已开发但后端功能不完整或优先级调整导致暂停。冻结模块有双重保护：
+
+1. **前端**: `routeConfig.ts` 的 `frozen: true` 标记 → `PrivateRoute` 返回 403
+2. **后端**: `frozen_module_middleware` → API 直接返回 403
+
+## 冻结模块清单
+
+| 模块 | 路由 | 后端完成度 | 前端完成度 | 冻结日期 | 超时日期 |
+|------|------|-----------|-----------|---------|---------|
+| 护理计划 | /health/care-plans | Entity+Service+Handler 已有 | 列表+详情页 | 2026-05-05 | 2026-05-19 |
+| 班次管理 | /health/shifts | Entity+Service+Handler 已有 | 列表+详情页 | 2026-05-05 | 2026-05-19 |
+| 家庭代理 | /health/family-proxy | Entity+Service+Handler 已有 | 完整页面 | 2026-05-05 | 2026-05-19 |
+| 药物管理 | /health/medications | 部分实现 | 完整页面 | 2026-05-05 | 2026-05-19 |
+| 透析管理 | /health/dialysis | Entity+Service 已有 | 列表页 | 2026-05-05 | 2026-05-19 |
+| 排班日历 | /health/schedules | 复用 appointment | 日历页 | 2026-05-05 | 2026-05-19 |
+
+## 策略
+
+### 超时规则
+
+- 冻结超过 **14 天**自动触发决策评审
+- 评审结果三选一：**(a) 解冻完成** / **(b) 延期冻结（设新截止日）** / **(c) 移除**
+- 超时未决策的模块，默认延期 7 天并升级通知
+
+### 决策框架
+
+| 条件 | 建议 |
+|------|------|
+| 后端已有完整 CRUD + 测试 | **解冻**，补全 DoD 检查后上线 |
+| 后端部分实现，有明确需求 | **延期**，排入下一迭代 |
+| 无明确需求，冻结 > 30 天 | **移除**，清理前端页面和菜单 |
+
+### 当前建议（2026-05-19 评审）
+
+1. **透析管理**: 解冻 — 后端 Entity+Service+Handler 齐全，是核心医疗功能
+2. **班次管理**: 解冻 — 后端完整，医护排班是刚需
+3. **护理计划**: 延期 — 需要与随访/班次功能协同设计
+4. **家庭代理**: 延期 — 需要隐私合规评审
+5. **药物管理**: 解冻 — 后端部分实现，补全即可
+6. **排班日历**: 延期 — 依赖 appointment 模块的增强
+
+## 操作流程
+
+### 解冻操作
+
+1. 从 `routeConfig.ts` 移除 `frozen: true`
+2. 从 `frozen_module.rs` 的 `FROZEN_PREFIXES` 移除路径
+3. 执行 Feature DoD 检查清单
+4. 补全缺失的测试/注解/权限
+5. 提交并验证
+
+### 移除操作
+
+1. 从 `routeConfig.ts` 删除条目
+2. 从 `App.tsx` 删除路由和 lazy import
+3. 从菜单 seed 迁移中标记 `visible = false`
+4. 后端保留（不删除 handler/service），仅前端不可见
+5. 提交并验证
--- a/docs/tech-debt-board.md
+++ b/docs/tech-debt-board.md
@@ -0,0 +1,99 @@
+# HMS 技术债看板
+
+> 最后更新: 2026-05-13 | 分支: feat/media-library-banner
+
+## 度量总览
+
+| 指标 | 当前值 | 目标 | 状态 |
+|------|--------|------|------|
+| Fix 率 | 22.8% (177/776) | < 15% | 🟡 需改善 |
+| 后端测试 | 999 个函数 | 维持 | 🟢 健康 |
+| 前端测试覆盖 | 62/235 文件 (26%) | > 40% | 🟡 需改善 |
+| 小程序测试 | 9 文件 / 125 源文件 (7%) | > 80% | 🔴 真空 |
+| utoipa 注解 | Health 22/31, AI 0/19 | > 80% | 🔴 缺失 |
+| 大文件 (>800 行) | 15 个 | < 5 个 | 🟡 需拆分 |
+| production unwrap | 43 处 | < 10 | 🟡 需清理 |
+| TODO/FIXME | 5 处 | 清零 | 🟢 可控 |
+| 前端 any 类型 | 1 处 | 0 | 🟢 可控 |
+| console.log | 0 处 | 0 | 🟢 清洁 |
+
+## 高利息债务（修复频率 × 影响范围）
+
+### TD-1: utoipa 注解覆盖率 33% [利息: 高]
+
+- **当前**: 22/64 handler 文件有 utoipa 注解，AI 模块 0/19
+- **影响**: OpenAPI 文档不完整，前端无法自动生成 API 客户端
+- **修复成本**: 2-3d
+- **计划**: P2-2 openapi-typescript 自动生成时一并补全
+
+### TD-2: 大文件未拆分 [利息: 中]
+
+| 文件 | 行数 | 模块 | 建议 |
+|------|------|------|------|
+| data_service.rs | 1907 | plugin | 按实体拆分 |
+| manifest.rs | 1809 | plugin | 解析/验证/序列化分离 |
+| dynamic_table.rs | 1758 | plugin | SQL 构建/执行分离 |
+| module.rs | 1220 | message | 路由注册独立文件 |
+| service.rs | 1136 | plugin | 按功能拆分 |
+| data_handler.rs | 1121 | plugin | CRUD/查询/导入分离 |
+| action_inbox_service.rs | 1104 | health | 查询/聚合/通知分离 |
+| follow_up_service.rs | 1000 | health | 任务/记录/模板分离 |
+| main.rs | 981 | server | 路由注册独立模块 |
+| validation.rs | 916 | health | 按实体类型拆分 |
+| consultation_service.rs | 859 | health | 会话/消息/统计分离 |
+| points_service/event.rs | 858 | health | 事件类型拆分 |
+| fhir/handler.rs | 824 | health | 按资源类型拆分 |
+
+### TD-3: erp-plugin 巨石模块 [利息: 中]
+
+- **当前**: 7 个文件 > 800 行，总 189 文件
+- **影响**: 编译时间长、认知负担大
+- **修复成本**: 3-5d
+- **优先级**: 低（冻结功能，暂不活跃开发）
+
+### TD-4: production unwrap 43 处 [利息: 低]
+
+- **当前**: 从 514 降至 43，剩余多为安全解包（如 `get()` 已确认存在）
+- **影响**: 潜在 panic 风险
+- **修复成本**: 1d
+- **优先级**: 低（Clippy 0 警告，剩余均为安全场景）
+
+## 已偿还的债务
+
+| 债务 | 偿还日期 | 投入 |
+|------|---------|------|
+| event.rs 2871 行 | 2026-05-09 | 拆分为 13 个领域文件 |
+| module.rs 1595 行 | 2026-05-09 | 拆分为 13 个子模块 |
+| Clippy 警告 | 2026-05-07 | 全 workspace 0 警告 |
+| production unwrap 514→43 | 2026-05-07 | 批量替换为 expect/unwrap_or_default |
+| 权限码 4 处手动同步 | 2026-05-13 | CI 检查脚本 + seed 补全 |
+| 前后端 API 路径不一致 | 2026-05-13 | CI 检查脚本归一化 |
+| 小程序 0 测试 | 2026-05-13 | service 层 75 断言覆盖 |
+
+## 冻结模块看板
+
+| 模块 | 路由 | 后端 | 前端 | 冻结日期 | 超时日期 | 状态 |
+|------|------|------|------|---------|---------|------|
+| 护理计划 | /health/care-plans | Entity+Service+Handler 已有 | 列表+详情页已有 | 2026-05-05 | 2026-05-19 | 待决策 |
+| 班次管理 | /health/shifts | Entity+Service+Handler 已有 | 列表+详情页已有 | 2026-05-05 | 2026-05-19 | 待决策 |
+| 家庭代理 | /health/family-proxy | Entity+Service+Handler 已有 | 页面已有 | 2026-05-05 | 2026-05-19 | 待决策 |
+| 药物管理 | /health/medications | 部分实现 | 页面已有 | 2026-05-05 | 2026-05-19 | 待决策 |
+| 透析管理 | /health/dialysis | Entity+Service 已有 | 列表页已有 | 2026-05-05 | 2026-05-19 | 待决策 |
+| 排班日历 | /health/schedules | 复用 appointment | 日历页已有 | 2026-05-05 | 2026-05-19 | 待决策 |
+
+### 冻结策略
+
+1. **超时规则**: 冻结超过 14 天自动触发决策评审
+2. **决策选项**: (a) 解冻并完成 (b) 继续冻结并设新截止日 (c) 移除前端页面和菜单
+3. **当前**: 全部 6 个模块冻结于 2026-05-05，超时日期 2026-05-19
+4. **建议**: 优先解冻"透析管理"（已有完整后端）和"班次管理"（已有完整后端+前端）
+
+## 偿还优先级排序
+
+| 优先级 | 债务 | 预计投入 | 预期效果 |
+|--------|------|---------|---------|
+| 1 | 补全 utoipa 注解 (AI 模块) | 1d | OpenAPI 文档完整 |
+| 2 | 拆分 main.rs (981 行) | 0.5d | server 模块可维护性 |
+| 3 | 拆分 validation.rs (916 行) | 0.5d | health 模块可读性 |
+| 4 | 清理剩余 43 处 unwrap | 1d | 消除潜在 panic |
+| 5 | 拆分 service 大文件 (4 个 > 900 行) | 2d | health 模块可维护性 |
--- a/scripts/fix-rate-trend.sh
+++ b/scripts/fix-rate-trend.sh
@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+# fix-rate-trend.sh — Fix 率趋势监控
+#
+# 分析 git 提交历史，按周统计 fix 率趋势。
+# Fix 定义: 提交消息以 "fix" 开头（conventional commits）。
+#
+# 用法:
+#   bash scripts/fix-rate-trend.sh           # 全量趋势
+#   bash scripts/fix-rate-trend.sh 30        # 最近 30 天
+#
+# 目标: fix 率 < 15%（当前 ~23%）
+
+set -uo pipefail
+cd "$(git rev-parse --show-toplevel)"
+
+DAYS="${1:-999}"
+SINCE=""
+if [ "$DAYS" != "999" ]; then
+  SINCE="--since=\"${DAYS} days ago\""
+fi
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+echo "=========================================="
+echo "  Fix Rate Trend — fix / total commits"
+if [ "$DAYS" != "999" ]; then
+  echo "  (Last ${DAYS} days)"
+fi
+echo "=========================================="
+echo ""
+
+# Collect weekly stats
+declare -a WEEKS=()
+declare -a TOTALS=()
+declare -a FIXES=()
+declare -a RATES=()
+
+eval "git log --oneline --format='%ad|%s' --date=short $SINCE" | while IFS='|' read -r date msg; do
+  echo "$date|$msg"
+done | awk -F'|' '
+{
+  date = $1
+  msg = $2
+  # Get ISO week number (year-week)
+  cmd = "date -d \"" date "\" +\"%G-W%V\" 2>/dev/null || date -j -f \"%Y-%m-%d\" \"" date "\" +\"%G-W%V\" 2>/dev/null"
+  cmd | getline week
+  close(cmd)
+
+  total[week]++
+  if (msg ~ /^fix[\(:]/ || msg ~ /^fix$/) {
+    fix[week]++
+  } else {
+    fix[week] += 0
+  }
+}
+END {
+  n = asorti(total, sorted)
+  for (i = 1; i <= n; i++) {
+    w = sorted[i]
+    f = fix[w] + 0
+    t = total[w]
+    r = (f / t) * 100
+    printf "%s|%d|%d|%.1f\n", w, t, f, r
+  }
+}' > /tmp/fix-rate-$$.tmp
+
+# Display results
+printf "%-12s %6s %6s %8s  %s\n" "WEEK" "TOTAL" "FIX" "RATE" "BAR"
+echo "------------------------------------------------------------"
+
+ALL_TOTAL=0
+ALL_FIX=0
+
+while IFS='|' read -r week total fix rate; do
+  ALL_TOTAL=$((ALL_TOTAL + total))
+  ALL_FIX=$((ALL_FIX + fix))
+
+  # Color code by rate
+  bar_len=$(echo "$rate" | awk '{printf "%d", $1 / 5}')
+  bar=""
+  for ((i=0; i<bar_len; i++)); do bar="${bar}#"; done
+
+  if awk "BEGIN { exit ($rate < 15) ? 1 : 0 }"; then
+    if awk "BEGIN { exit ($rate < 25) ? 1 : 0 }"; then
+      color=$YELLOW
+    else
+      color=$RED
+    fi
+  else
+    color=$GREEN
+  fi
+
+  printf "%-12s %6d %6d " "$week" "$total" "$fix"
+  echo -e "${color}${rate}%${NC}  ${bar}"
+done < /tmp/fix-rate-$$.tmp
+
+rm -f /tmp/fix-rate-$$.tmp
+
+echo "------------------------------------------------------------"
+ALL_RATE=$(awk "BEGIN { printf \"%.1f\", ($ALL_FIX / $ALL_TOTAL) * 100 }")
+echo ""
+echo -e "Total: ${ALL_TOTAL} commits, ${ALL_FIX} fixes, rate: ${ALL_RATE}%"
+echo ""
+
+# Category breakdown for the most recent period
+echo "=========================================="
+echo "  Fix Category Breakdown (recent)"
+echo "=========================================="
+
+eval "git log --oneline --format='%s' $SINCE" | grep -iE "^fix" | \
+  sed -E 's/^fix\([^)]*\):? ?//' | \
+  grep -oE '(permission|auth|安全|security|tenant|CORS|SQL|XSS|前端|后端|接口|字段|API|路由|route|menu|菜单|编译|compile|类型|type|migration|迁移|race|竞态|token|event|事件|login|登录|miniprogram|小程序|Taro|media|轮播|banner)' | \
+  sort | uniq -c | sort -rn | head -15
+
+echo ""
+echo "Target: fix rate < 15%"
+echo "Red line: fix rate > 20% triggers review (see CLAUDE.md)"