docs: V1 发布策略头脑风暴 + 六维度发布就绪度分析文档

2026-05-20 17:53:10 +08:00
parent 65cf96f119
commit 853a0ca2b4
2 changed files with 708 additions and 0 deletions
--- a/docs/superpowers/specs/2026-05-20-v1-readiness-six-dimension-analysis.md
+++ b/docs/superpowers/specs/2026-05-20-v1-readiness-six-dimension-analysis.md
@@ -0,0 +1,287 @@
+# HMS V1 发布就绪度 — 六维度全面均衡分析
+
+> 日期: 2026-05-20 | 分支: feat/media-library-banner | 分析方法: 4 并行探索 + 6 专家组深度分析
+
+## 综合评分: 6.3/10 (B-)
+
+| 维度 | 评分 | 评级 | 趋势 | 核心发现 |
+|------|------|------|------|---------|
+| 架构 | **8.0** | A- | ↑ | 模块边界 9/10，事件消费者幂等不统一，缓存层薄弱 |
+| 安全 | **7.5** | B+ | → | PII 加密企业级 9/10，analytics 缺权限(HIGH)，缺 HSTS/CSP |
+| 前端 | **7.2** | B | ↑ | 64 页面全 lazy，长者模式 100%，小程序零测试 |
+| 产品 | **~7.0** | B | → | 核心流程完整，6 模块冻结，2 个 TODO 空实现 |
+| 测试 | **5.5** | C+ | → | 990 测试但 Handler 0%，小程序 0，中间件 0 |
+| DevOps | **3.8** | D+ | ↑ | CD 缺失，备份不合规，无监控告警 |
+
+---
+
+## 一、架构维度 (8.0/10)
+
+### 1.1 模块边界 — 优秀 (9/10)
+
+- erp-core (L1) 零业务依赖，所有 L2 模块彼此零依赖，erp-server (L3) 唯一组装点
+- 8 个模块全部实现 ErpModule trait，ModuleRegistry 按拓扑排序启动
+- 天然支持微服务拆分：只需将 EventBus 从进程内 broadcast 替换为消息队列
+
+### 1.2 SQL 拼接风险 — 安全但有代码气味 (7/10)
+
+| 位置 | 类型 | 风险 |
+|------|------|------|
+| `erp-plugin/src/host.rs:368` | advisory lock | NONE (纯数值) |
+| `erp-plugin/src/host.rs:336-398` | 动态表名 | LOW (sanitize_identifier) |
+| `erp-health/src/service/action_inbox_service.rs:240-353` | 硬编码条件 | NONE (编译时字面量) |
+
+`sanitize_identifier()` 实现正确但缺长度限制（PostgreSQL 63 字节标识符上限）。
+
+### 1.3 事件系统 — 良好 (7.5/10)
+
+- 31 事件类型 / 82 发布点 / 12 消费者模块 / Outbox + LISTEN/NOTIFY
+- `consume_with_retry()` 提供幂等保证但实际未被消费者调用
+- broadcast channel 容量 1024，高并发下可能 lag（30s 兜底轮询补偿）
+
+### 1.4 缓存层 — 薄弱 (6.5/10)
+
+- 仅有 Moka (权限缓存) + Redis (限流/session)，无业务数据缓存
+- 高频查询（菜单树、字典项、仪表盘统计）每次请求命中数据库
+- 10x 用户增长时数据库连接池将成为瓶颈
+
+### 1.5 架构 TOP 5 风险
+
+1. **事件消费者未统一走 consume_with_retry** (MEDIUM) — 幂等保护不完整，3-5d
+2. **broadcast channel 容量有限** (MEDIUM) — 高并发丢事件，2d
+3. **缓存层薄弱** (MEDIUM) — 10x 扩展瓶颈，5-8d
+4. **action_inbox_service SQL 拼接** (LOW) — 代码气味，0.5d
+5. **迁移文件过多(156个)** (LOW) — 维护成本，3d
+
+---
+
+## 二、安全维度 (7.5/10)
+
+### 2.1 认证与授权 — 优秀 (8.5/10)
+
+- JWT: HS256 + 15min access / 7d refresh + SHA-256 存储 refresh token
+- 原子性刷新: `validate_and_revoke_atomic()` 防止 TOCTOU 竞态
+- 密码: Argon2 + 随机 salt
+- 权限守卫: 444 处 `require_permission()` 调用，64 个 handler 文件
+- 多租户: 双层隔离（应用层 tenant_id + PostgreSQL RLS）
+
+### 2.2 PII 加密 — 优秀 (9/10)
+
+- KEK/DEK 分层 + AES-256-GCM + 盲索引 (HMAC-SHA256)
+- 生产环境强制 KEK 配置（`debug_assertions` 下 dev_default 会 panic）
+- 支持租户级密钥轮换 API
+
+### 2.3 API 安全 — 优秀 (9/10)
+
+- 5 层 rate limiting: IP登录(5/min) + IP刷新(30/min) + 用户API(300/min) + 网关(60/min) + 账户锁定(5次/15min)
+- 文件上传: 白名单 + Magic bytes + 大小限制 + UUID 文件名 + 租户隔离
+- CORS: 生产环境拒绝通配符
+
+### 2.4 安全 TOP 5 风险
+
+1. **Analytics batch 端点缺权限校验** (HIGH) — CVSS 5.3，1h
+2. **日志 PII 脱敏不完整** (MEDIUM) — secret_len 泄漏 + service 层未脱敏，4h
+3. **缺少 HSTS + CSP 安全头** (MEDIUM) — CVSS 3.1，2h
+4. **插件 sanitize_identifier 缺长度限制** (MEDIUM) — 8h
+5. **SSE token 通过 URL query parameter** (LOW) — 日志泄漏风险，4h
+
+---
+
+## 三、前端维度 (7.2/10)
+
+### 3.1 Web 前端 — 良好 (7.5/10)
+
+- 316 TS/TSX 文件，54 API 模块，5 Zustand stores，76 权限码
+- **64 个路由页面全部 React.lazy()** — 最佳实践
+- 6 个 manualChunks 分包，sourcemap 生产关闭
+- 10 处生产 `any`（7 处在 points.ts 可修复）
+- 最大文件 AdminDashboard.tsx 730 行（无超 800 行）
+- 62 个测试文件，以 API 契约测试为主
+
+### 3.2 小程序 — 良好但零测试 (7.0/10)
+
+- 59 页面（12 主包 + 47 子包），34 组件，38 service 文件
+- 并发安全架构完善: ConcurrencyLimiter(12) + safeNavigateTo + requestUnlimited
+- Design Token: 40+ CSS 变量，93 SCSS 文件全量接入
+- 长者模式: 58/58 页面 100% 覆盖
+- **零单元测试** — MCP 自动化审计 96.2% 通过率但只覆盖可达性
+
+### 3.3 前端 TOP 5 风险
+
+1. **小程序零单元测试** (CRITICAL) — 161 文件无测试，2-3d
+2. **i18n 未实际使用** (HIGH) — 2,298 处硬编码中文，3-5d
+3. **生产 any 10 处** (MEDIUM) — points.ts 7 处可修复，0.5d
+4. **a11y 基本缺失** (MEDIUM) — 仅 9 处 aria-/role，2-3d
+5. **BLE 模块 any 密集** (LOW) — 14 处，1d
+
+---
+
+## 四、测试维度 (5.5/10)
+
+### 4.1 测试分布
+
+| 层级 | 测试数 | 覆盖率 |
+|------|--------|--------|
+| 后端单元 | 802 | Service/DTO 覆盖较好 |
+| 后端集成 | 188 | 24 个测试文件 |
+| **Handler** | **~2** | **2.8% (2/72 文件)** |
+| **安全中间件** | **1** | **20% (1/5)** |
+| Web 前端 | 61 文件 | 页面覆盖率 20.8% |
+| 小程序 | **0** | **0%** |
+| E2E | 17 Web + 4 MP | 核心流程 |
+
+### 4.2 测试密度（测试/1K行代码）
+
+| Crate | 密度 | 评价 |
+|-------|------|------|
+| erp-core | 28.1 | 优秀 |
+| erp-message | 20.2 | 优秀 |
+| erp-config | 15.3 | 良好 |
+| erp-health | **4.9** | 不足 |
+| erp-server | **0.7** | 严重不足 |
+
+### 4.3 测试 TOP 5 风险
+
+1. **Handler 层 0% 覆盖** (CRITICAL) — 72 个文件无测试，2-3d
+2. **小程序 0 测试** (CRITICAL) — 161 文件无测试，2d
+3. **安全中间件 0 测试** (HIGH) — rate_limit/tenant_rls/frozen_module，1.5d
+4. **erp-health 28/57 service 无测试** (HIGH) — 核心业务模块，3-4d
+5. **CI 不覆盖 E2E/小程序** (MEDIUM) — 1.5d
+
+---
+
+## 五、DevOps 维度 (3.8/10)
+
+### 5.1 CI — 良好 (7/10)
+
+- 双平台 CI: GitHub Actions (5 阶段后端 + 4 阶段前端) + Gitea CI (4 jobs)
+- Rust 缓存 (Swatinem/rust-cache) + pnpm 缓存
+- Clippy 0 警告强制 + cargo audit
+
+### 5.2 CD — 缺失 (0/10)
+
+- 无自动化部署流程
+- 无 Docker 镜像版本 tag 策略
+- 无蓝绿/金丝雀部署
+
+### 5.3 监控 — 仅 exporter (4/10)
+
+- Prometheus 指标: http_requests_total, http_request_duration, db_pool, eventbus_pending
+- 3 级健康检查: /health, /health/live, /health/ready
+- **无 Prometheus Server / Grafana / 告警 / 日志聚合 / 分布式追踪**
+
+### 5.4 备份 — 不合规 (3/10)
+
+- 每日 pg_dump + 7 天保留
+- **无加密、无异地存储、无 PITR、无恢复测试**
+- 医疗数据合规要求: RPO < 1h, 保留 >= 5 年
+
+### 5.5 DevOps TOP 5 风险
+
+1. **无 CD 能力** (CRITICAL) — 发布完全手动，3-5d
+2. **备份不满足医疗合规** (CRITICAL) — 无加密/异地/PITR，5-8d
+3. **无监控告警** (HIGH) — 生产盲飞，3-5d
+4. **迁移在启动时自动执行** (HIGH) — 破坏性 DDL 风险，3-5d
+5. **安全审计不阻止合并** (MEDIUM) — continue-on-error: true，2-3d
+
+---
+
+## 六、产品维度 (~7.0/10)
+
+### 6.1 功能完整性
+
+- 核心流程完整: 患者建档 → 健康数据 → 预约 → 随访 → AI 分析
+- 管理员流程完整: 用户管理 → 角色权限 → 数据字典 → 系统配置
+- 6 个冻结模块: care-plans, shifts, family-proxy, medications, dialysis, dialysis-prescriptions, schedules
+- 2 个 TODO 空实现: ActionDetailDrawer、PendingTasks
+
+### 6.2 wiki 数据校准
+
+| 指标 | wiki | 实际 | 差距 |
+|------|------|------|------|
+| Rust 源文件 | 652 | 694 | +42 |
+| 后端路由 | 260+ | 376 | +116 |
+| 权限码 | 132 | 140 | +8 |
+| Git 提交 | 862 | 927+ | +65 |
+| Web TS/TSX | 307 | 316 | +9 |
+| 小程序 TS/TSX | 161 | 167 | +6 |
+| API 服务文件 | 28 | 54 | +26 |
+| utoipa 注解 | 89 | 94 | +5 |
+| "待修复"条目 | 4 | 0 (全已修复) | 需标记 |
+
+---
+
+## 七、V1 发布策略（多专家组辩论共识）
+
+### P0 阻塞项（4 天）— 不完成不发布
+
+| # | 行动项 | 维度 | 工作量 |
+|---|--------|------|--------|
+| A1 | Analytics batch 添加权限校验 | 安全 | 1h |
+| A2 | HSTS + CSP + Permissions-Policy 安全头 | 安全 | 2h |
+| A3 | 数据库备份加密 + 异地存储 | DevOps | 3d |
+| A4 | Nginx TLS 配置模板 | DevOps | 0.5d |
+| A5 | 迁移回滚策略文档 + 脚本 | DevOps | 1d |
+
+### P1 测试加固（3 天）— 强烈建议
+
+| # | 行动项 | 维度 | 工作量 |
+|---|--------|------|--------|
+| A6 | 安全中间件 unhappy path 测试 (~15个) | 测试 | 1.5d |
+| A7 | 核心 Handler 测试 (~40个) | 测试 | 1.5d |
+
+### P2 V1.1 推迟项（~30 天）
+
+| # | 行动项 | 维度 | 工作量 |
+|---|--------|------|--------|
+| B1 | Prometheus + Grafana 监控 + 告警 | DevOps | 3d |
+| B2 | CD Pipeline (GitHub Actions) | DevOps | 5d |
+| B3 | 小程序最小测试套件 | 测试 | 2d |
+| B4 | 事件消费者统一 consume_with_retry | 架构 | 5d |
+| B5 | 日志 PII 脱敏审查 | 安全 | 4h |
+| B6 | 生产迁移策略（独立步骤） | DevOps | 2d |
+| B7 | CI 安全审计阻止合并 | DevOps | 0.5d |
+| B8 | 菜单树/字典项缓存 | 架构 | 3d |
+| B9 | Web a11y 基础合规 | 前端 | 2-3d |
+| B10 | points.ts any 类型修复 | 前端 | 2h |
+
+### GO/NO-GO 硬底线
+
+以下任一条件不满足即 NO-GO：
+
+1. 多租户数据隔离验证通过（无跨租户泄漏）
+2. 核心用户流程端到端可用（建档→录入→预约→随访）
+3. 数据库备份可成功恢复（至少一次恢复测试）
+4. Analytics 越权已修复
+5. 迁移失败有回滚方案
+
+---
+
+## 八、关键数字校准表（wiki 更新用）
+
+| 指标 | 当前 wiki | 应更新为 |
+|------|-----------|---------|
+| Rust 源文件 | 652 | 694 |
+| 后端路由 | 260+ | 376+ |
+| 权限码 | 132 | 140 |
+| Git 提交 | 862 | 927+ |
+| Web TS/TSX | 307 | 316 |
+| 小程序 TS/TSX | 161 | 167 |
+| Web API 服务文件 | 28 | 54 |
+| 小程序组件 | 10 | 34 |
+| 小程序 Service 文件 | 10+ | 38 |
+| utoipa 注解文件 | 89 | 94 |
+| Web 冻结路由 | 5 | 6 |
+| 后端测试函数 | 943 | 990+ |
+| 系统评分 | 6.8/10 (B) | 6.3/10 (B-) |
+| 症状导航待修复 | 4 项 | 0 项（全已修复） |
+
+---
+
+## 附录: 分析方法论
+
+- **阶段 1**: 4 个并行探索 Agent（后端架构 / 前端+小程序 / 数据库+安全 / V1 就绪度）
+- **阶段 2**: 6 个专家组深度分析（架构师 / 安全工程师 / 测试工程师 / 前端专家 / SRE / 产品经理）
+- **阶段 3**: 多专家组辩论会议（4 个议题：发布范围 / 测试策略 / DevOps 优先级 / 技术债务取舍）
+- **总工具调用**: 400+ 次（Grep/Glob/Read/Bash 跨 10 个 Agent）
+- **总分析时长**: ~15 分钟（并行执行）