docs(health): 六维度全面均衡分析报告 + 六专家组头脑风暴评审

- 新增六维度分析报告：架构(7.5)/代码质量(7.0)/业务完整度(7.5)/安全合规(7.5)/生产就绪(5.5)/可扩展性(6.5)，综合 6.9/10 (B) - 组织 6 位虚拟专家（架构师/后端/前端/安全/DevOps/产品）独立评审，综合 7.0/10 (B)，较上次 6.4/10 提升 +0.6 - 识别 Top 5 行动优先级：OpenAPI 注解补全、性能基准、event.rs 拆分、小程序测试、冻结模块解冻 - 制定三个月路线图：Month 1 质量加固 → Month 2 功能补全 → Month 3 生产化 - 更新 wiki/index.md 关键数字（57 实体、999 测试、24 unwrap、75+ 权限码等）
2026-05-11 03:43:51 +08:00
parent 6269815046
commit 9487ccb62e
3 changed files with 641 additions and 27 deletions
--- a/docs/superpowers/specs/2026-05-11-system-comprehensive-analysis-design.md
+++ b/docs/superpowers/specs/2026-05-11-system-comprehensive-analysis-design.md
@@ -0,0 +1,331 @@
+# HMS 健康管理平台 — 六维度全面均衡分析报告
+
+> 日期: 2026-05-11 | 数据截止: commit c716cc0 (feat/media-library-banner 分支) | 提交: 720+
+> 上次分析: 2026-05-07 (综合 6.4/10 B-) | 本次基准: 媒体库+轮播图上线后
+
+## 执行摘要
+
+| 维度 | 评分 | 趋势 | 关键发现 |
+|------|------|------|---------|
+| 架构合理性 | 7.5/10 | → | 模块边界清晰，event.rs 2871 行成最大技术债 |
+| 代码质量 | 7.0/10 | ↑ | Clippy 0 警告，生产 unwrap 降至 24 处，utoipa 覆盖仅 33% |
+| 业务完整度 | 7.5/10 | ↑ | 媒体库/轮播图上线，6 个模块仍冻结 |
+| 安全合规 | 7.5/10 | ↑ | PII 加密全面，0 SQL 注入，缺速率限制 |
+| 生产就绪度 | 5.5/10 | → | 依赖全部最新，缺性能基准和监控 |
+| 可扩展性 | 6.5/10 | → | 模块化单体路径清晰，本地存储限制 |
+| **综合** | **6.9/10** | **↑** | 功能完整度 87%，生产就绪度约 60% |
+
+**与上次对比（2026-05-07 → 2026-05-11）：**
+- 代码质量 ↑ — Clippy 0 警告（从有警告到清零），生产 unwrap 从 514 降至 24
+- 业务完整度 ↑ — 媒体库/轮播图/文章编辑器上线，冻结模块从 7 降至 6
+- 安全合规 ↑ — SQL 注入已修复，FHIR 越权已修复，V2 CRITICAL 全部清零
+- 生产就绪度 → — 无变化，仍缺性能基准和监控体系
+- 综合 6.4 → 6.9，评级从 B- 提升到 B
+
+**Top 5 行动优先级：**
+1. **CRITICAL** — 补全 OpenAPI 文档（erp-health 31/32 handler 无注解）
+2. **HIGH** — 建立性能基准测试和监控体系
+3. **HIGH** — 拆分 event.rs（2871 行）和 module.rs（1595 行）
+4. **HIGH** — 小程序补全单元测试（当前 124 文件 0 测试）
+5. **MEDIUM** — 解冻冻结模块（6 个模块前端无 UI）
+
+---
+
+## 1. 架构合理性分析
+
+**评分：7.5 / 10（B+）** | 与上次持平
+
+### 1.1 现状数据
+
+| 指标 | 值 |
+|------|-----|
+| Rust crate | 17 个（+ 7 插件骨架） |
+| Rust 源文件 | 599 个 |
+| 分层结构 | L1(erp-core) → L2(8 业务模块) → L3(erp-server) |
+| 领域事件 | 31 类型 + 23 幂等消费者 |
+| 权限码 | 75+ 个，声明式路由绑定 |
+| EventBus | broadcast + 持久化 + dead-letter + LISTEN/NOTIFY |
+| 模块间依赖 | 零直接业务依赖（仅 EventBus + trait） |
+
+### 1.2 优势
+
+1. **教科书级模块化单体** — 17 crate 严格分层，ErpModule trait 统一生命周期（注册/启动/关闭/健康检查），天然支持微服务拆分
+2. **事件驱动架构成熟** — Outbox 模式 + LISTEN/NOTIFY + 死信队列 + 幂等消费，事件不丢失不重复
+3. **多租户纵深防御** — JWT 中间件注入 → SeaORM 自动过滤 → PostgreSQL RLS 策略三层隔离
+4. **UUID v7 主键** — 时间排序 + 唯一性，分布式友好
+5. **软删除 + 乐观锁** — 版本字段检查，数据不可丢失
+
+### 1.3 风险与缺口
+
+| 风险 | 严重度 | 位置 |
+|------|--------|------|
+| event.rs 2871 行，混合 31 事件定义 + 23 消费者 + 测试 | HIGH | `crates/erp-health/src/event.rs` |
+| module.rs 1595 行，150+ 路由注册在单文件 | HIGH | `crates/erp-health/src/module.rs` |
+| erp-plugin 复杂度（data_service 1907 行 + manifest 1809 行） | MEDIUM | `crates/erp-plugin/` |
+| 6 个冻结模块的架构债务 | MEDIUM | 路由/权限/菜单仍存在 |
+| erp-health 仍为巨石模块（189 文件，12 业务子域） | MEDIUM | `crates/erp-health/` |
+
+### 1.4 建议行动
+
+1. **拆分 event.rs** — 按领域拆为 `patient_events.rs`、`alert_events.rs`、`consultation_events.rs` 等，事件定义和消费者分离
+2. **拆分 module.rs** — 路由按业务域分组为 `routes/patient_routes.rs`、`routes/appointment_routes.rs` 等
+3. **冻结模块策略明确** — 要么解冻并完成 UI，要么从路由树中移除（减少编译体积和认知负担）
+
+---
+
+## 2. 代码质量分析
+
+**评分：7.0 / 10（B）** | 较上次 ↑（6.0 → 7.0）
+
+### 2.1 现状数据
+
+| 指标 | 值 | 评估 |
+|------|-----|------|
+| Clippy 警告 | 0 | 全 workspace 清零 |
+| 生产代码 unwrap() | 24 处 | 低风险（多为安全解包） |
+| 测试代码 unwrap/expect | ~488 处 | 可接受 |
+| Rust 大文件(>800行) | 17 个 | 需关注 top 5 |
+| TSX 大文件(>800行) | 0 个 | 优秀 |
+| 前端 API 层绕过 | 0 处 | 优秀 |
+| Web console.log | 0 处 | 优秀 |
+| MP console.log | 33 处 | 生产构建自动移除 |
+| TypeScript any | Web 32 / MP 35 | Web 多为测试代码 |
+| 后端测试 | 999 函数（815 同步 + 184 异步） | 丰富 |
+| 前端测试 | 644 断言（472 Web + 39 MP + 133 E2E） | 中等 |
+| utoipa 注解 | 322 个 / 21/64 文件 = 33% | erp-health 缺口大 |
+| 依赖版本 | 全部最新主版本线 | 优秀 |
+
+### 2.2 优势
+
+1. **Clippy 全清零** — 从 514 个 unwrap() 降至 24 个生产 unwrap，0 Clippy 警告，质量门禁见效
+2. **API 层零绕过** — 前端 0 处直接 fetch/axios 调用，全部通过 api/ 层
+3. **错误处理一致** — 所有 handler 统一返回 AppError，类型化错误链
+4. **Web 代码极干净** — 0 console.log、0 超大文件、any 多为测试 mock
+5. **后端测试丰富** — 999 测试函数，78 个文件包含内联测试模块
+
+### 2.3 风险与缺口
+
+| 风险 | 严重度 | 详情 |
+|------|--------|------|
+| OpenAPI 文档覆盖仅 33% | CRITICAL | erp-health 31/32 handler 无注解，API 文档不完整 |
+| 小程序 0 个单元测试 | HIGH | 124 文件完全无测试覆盖 |
+| 覆盖率工具未执行 | HIGH | vitest coverage 已配置但无最新报告 |
+| 17 个 Rust 大文件 | MEDIUM | event.rs(2871)、data_service.rs(1907)、manifest.rs(1809) |
+| MP 源码 33 处 console.log | LOW | 生产构建自动移除，但影响代码整洁 |
+
+### 2.4 建议行动
+
+1. **批量补全 utoipa 注解** — 为 erp-health 剩余 31 个 handler 添加 OpenAPI 注解
+2. **小程序测试补全** — 优先为 service 层（29 个文件）编写单元测试
+3. **执行覆盖率报告** — 运行 `vitest run --coverage` 和 `cargo tarpaulin`，建立基线
+
+---
+
+## 3. 业务完整度分析
+
+**评分：7.5 / 10（B+）** | 较上次 ↑（6.5 → 7.5）
+
+### 3.1 现状数据
+
+| 指标 | 值 |
+|------|-----|
+| erp-health 实体 | 57 个（新增 media_folder/media_item/banner） |
+| erp-health handler | 31 个 |
+| erp-health service | 36 个（含子模块） |
+| Web 活跃路由 | 29 个 |
+| Web 冻结路由 | 6 个 |
+| 小程序页面 | 66 个（主包 12 + 分包 54） |
+| 后台定时任务 | 5 个 |
+| 新增功能 | 媒体库管理 + 轮播图管理 + 文章编辑器重设计 |
+
+### 3.2 优势
+
+1. **内容管理闭环** — 文章 CRUD + 媒体库 + 轮播图 + 公共端点（小程序访客可访问）
+2. **文章编辑器重设计** — 公众号风格三栏布局 + iPhone 15 Pro 预览 + 丰富样式模板
+3. **Design Token 全面推广** — 68 SCSS 文件接入，关怀模式 CSS 变量级联
+4. **长者模式 100% 覆盖** — 58/58 页面全部完成
+5. **医生端功能丰富** — 17 页面涵盖患者/咨询/随访/报告/告警/透析/处方
+
+### 3.3 风险与缺口
+
+| 冻结模块 | 前端状态 | 后端状态 | 业务影响 |
+|----------|---------|---------|---------|
+| care-plans | 有页面(CarePlanList/Detail) | 有 CRUD | 可快速解冻 |
+| shifts | 有页面(ShiftList/Detail) | 有 CRUD | 可快速解冻 |
+| family-proxy | 有页面 | 有 CRUD | 可快速解冻 |
+| medications | 有页面 | 有 CRUD | 可快速解冻 |
+| dialysis | 有页面(DialysisManageList) | 有独立 crate | 可快速解冻 |
+| schedules | 有页面(DoctorSchedule) | 有 CRUD | 可快速解冻 |
+
+**重要发现：** 6 个冻结模块全部已有前端页面和后端 CRUD，仅被 `frozen: true` 标记阻止访问。解冻成本极低（改 routeConfig.ts 即可），但需要：
+- 验证功能完整性（E2E 测试）
+- 确认权限码配置正确
+- UI/UX 一致性检查
+
+### 3.4 建议行动
+
+1. **批量解冻** — 优先解冻 care-plans、shifts、dialysis（业务价值最高）
+2. **解冻后验证** — 每个解冻模块执行 E2E 测试确认功能正常
+3. **AI 模块 UI 入口** — 4 个 SSE 分析端点缺少前端触发入口
+
+---
+
+## 4. 安全合规分析
+
+**评分：7.5 / 10（B+）** | 较上次 ↑（7.0 → 7.5）
+
+### 4.1 现状数据
+
+| 指标 | 状态 |
+|------|------|
+| PII 加密 | AES-256-GCM + HMAC-SHA256 + DEK 轮换 |
+| 加密字段覆盖 | 咨询内容、诊断备注、执业证号、随访结果、手机号、症状等 |
+| SQL 注入 | 0 处（全部参数化或 sanitize_identifier） |
+| JWT 认证 | 自动刷新 + 并发队列 + 身份一致性校验 |
+| 多租户隔离 | middleware 注入 + SeaORM 过滤 + RLS 策略 |
+| HTML 清理 | ammonia 库 |
+| V2 CRITICAL | 全部修复（SQL 注入 + FHIR 越权） |
+
+### 4.2 优势
+
+1. **V2 CRITICAL 全清零** — SQL 注入和 FHIR 越权两个 CRITICAL 级漏洞已修复
+2. **PII 加密链路完整** — 从存储加密到 HMAC 盲索引到脱敏展示，全链路覆盖
+3. **零 SQL 注入面** — 15 处 format! SQL 均不含用户输入
+4. **认证体系成熟** — JWT 自动刷新、并发请求队列、身份一致性校验
+
+### 4.3 风险与缺口
+
+| 风险 | 严重度 | 详情 |
+|------|--------|------|
+| 缺少 API 速率限制 | HIGH | 无 rate limiting middleware |
+| 公开端点安全审查 | MEDIUM | public_routes 需评估是否可被滥用 |
+| BLE 网关认证强度 | MEDIUM | gateway_routes 的 token 机制待验证 |
+| 密钥轮换机制 | MEDIUM | secret_key 手动配置，无自动轮换 |
+| 审计日志完整性 | MEDIUM | 部分操作缺少审计追踪 |
+
+### 4.4 建议行动
+
+1. **添加速率限制** — 使用 tower-http 的 RateLimit layer，按 IP + 用户维度限制
+2. **公开端点审计** — 评估 /public/* 端点的滥用风险，添加 IP 限制
+3. **审计日志补全** — 确保所有写操作（create/update/delete）都有审计记录
+
+---
+
+## 5. 生产就绪度分析
+
+**评分：5.5 / 10（C+）** | 与上次持平
+
+### 5.1 现状数据
+
+| 指标 | 状态 |
+|------|------|
+| 依赖版本 | 全部最新主版本线 |
+| N+1 查询 | 无 |
+| 前端 memoization | 56% 页面有，44% 无（多为小页面） |
+| 性能基准 | 无 |
+| 覆盖率报告 | 工具已配置，未执行 |
+| 错误处理 | 一致（全 AppError） |
+| 监控 | 未确认 |
+| Docker | 有配置 |
+| 环境变量 | config.toml + 环境变量 |
+
+### 5.2 优势
+
+1. **依赖健康** — 所有 Rust 和 TypeScript 依赖均为最新主版本线
+2. **无 N+1 查询** — 使用 SeaORM 批量查询和关联加载
+3. **错误处理一致** — 所有 handler 返回 AppError，前端统一错误提示
+4. **前端构建优化** — 生产构建自动移除 console.log，terser 压缩
+
+### 5.3 风险与缺口
+
+| 风险 | 严重度 | 详情 |
+|------|--------|------|
+| 无性能基准测试 | HIGH | 无法量化响应时间、吞吐量 |
+| 监控体系不明 | HIGH | tracing 覆盖率、metrics 端点待确认 |
+| 无覆盖率报告 | MEDIUM | 工具已配置但未执行，无法量化测试覆盖 |
+| 前端 bundle 大小 | MEDIUM | 未确认首屏加载性能 |
+| SSE 断线重连 | LOW | 需验证客户端重连机制 |
+
+### 5.4 建议行动
+
+1. **建立性能基线** — 使用 `criterion` 创建核心 API 基准测试
+2. **执行覆盖率报告** — 后端 `cargo tarpaulin` + 前端 `vitest --coverage`
+3. **配置 metrics 端点** — 使用 `metrics` + `metrics-exporter-prometheus`
+4. **前端性能审计** — Lighthouse 跑分 + bundle 分析
+
+---
+
+## 6. 可扩展性分析
+
+**评分：6.5 / 10（B-）** | 与上次持平
+
+### 6.1 现状数据
+
+| 指标 | 状态 |
+|------|------|
+| 模块化架构 | 天然支持微服务拆分 |
+| EventBus | 进程内 broadcast，可迁移到分布式 MQ |
+| 数据库 | PostgreSQL，共享数据库多租户隔离 |
+| 文件存储 | 本地文件系统（媒体库） |
+| 缓存 | Redis（仅 AI 模块使用） |
+| 迁移 | 137 个，自动执行 |
+| 主键策略 | UUID v7 |
+
+### 6.2 优势
+
+1. **微服务拆分路径清晰** — 模块间零依赖，每个 crate 可独立部署
+2. **EventBus 可演进** — 从 broadcast → Kafka/NATS 无需改业务代码
+3. **UUID v7** — 时间排序 + 唯一性，分布式 ID 生成友好
+4. **迁移自动执行** — 137 个迁移，启动时自动应用
+
+### 6.3 风险与缺口
+
+| 风险 | 严重度 | 详情 |
+|------|--------|------|
+| 本地文件存储限制 | HIGH | 媒体库文件存本地，无法水平扩展 |
+| 缓存范围有限 | MEDIUM | Redis 仅用于 AI 模块，其他模块无缓存 |
+| 数据库扩展 | MEDIUM | 单 PostgreSQL 实例，无读写分离 |
+| API 网关缺失 | LOW | 直接暴露 Axum 端点，无统一入口 |
+
+### 6.4 建议行动
+
+1. **媒体存储抽象** — 添加 Storage trait，支持本地/S3/OSS 切换
+2. **数据库连接池优化** — 配置 PgPoolOptions，添加读写超时
+3. **缓存策略** — 将 Redis 扩展到权限缓存、会话缓存
+4. **API 网关评估** — 评估 nginx/caddy 反代方案
+
+---
+
+## 7. 综合评分与路线图建议
+
+### 7.1 综合评分矩阵
+
+| 维度 | 评分 | 权重 | 加权分 |
+|------|------|------|--------|
+| 架构合理性 | 7.5 | 20% | 1.50 |
+| 代码质量 | 7.0 | 20% | 1.40 |
+| 业务完整度 | 7.5 | 20% | 1.50 |
+| 安全合规 | 7.5 | 15% | 1.13 |
+| 生产就绪度 | 5.5 | 15% | 0.83 |
+| 可扩展性 | 6.5 | 10% | 0.65 |
+| **综合** | | | **6.9/10 (B)** |
+
+### 7.2 三个月路线图建议
+
+**Month 1 — 质量加固（提升到 7.5+）**
+- 补全 utoipa 注解（erp-health 31 个 handler）
+- 建立性能基准测试
+- 执行覆盖率报告建立基线
+- 拆分 event.rs 和 module.rs
+
+**Month 2 — 功能补全（提升到 8.0+）**
+- 解冻 6 个冻结模块
+- AI 模块前端 UI 入口
+- 小程序单元测试补全
+- API 速率限制
+
+**Month 3 — 生产化（提升到 8.5+）**
+- 监控和可观测性体系
+- 媒体存储 S3/OSS 抽象
+- 性能优化（前端 bundle + 后端查询）
+- 端到端压力测试