hms/docs/superpowers/specs/2026-05-17-system-six-dimension-analysis-design.md

# HMS 六维度全面均衡分析报告（2026-05-17）

> 日期: 2026-05-17 | 方法: 6 专家组并行分析 + 代码级核实 | 数据基准: feat/media-library-banner 分支

## 1. 概述

### 1.1 分析方法

本次分析采用"6 专家组并行头脑风暴"模式，每个专家从不同维度审视系统：

| 专家 | 角色 | 分析维度 |
|------|------|----------|
| 首席架构师 | Senior Developer | 架构演进、事件系统、技术债务 |
| 安全工程师 | Security Engineer | 漏洞修复、合规差距、密钥管理 |
| QA 测试专家 | Senior Developer | 测试覆盖、质量门禁、工具链 |
| 前端/UX 架构师 | Frontend Developer | 前端架构、Design Token、性能 |
| DevOps/SRE | DevOps Automator | 生产就绪度、监控、CI/CD |
| 产品经理 | Senior Project Manager | 产品完整度、用户价值、路线图 |

数据来源：652 个 Rust 源文件（136,908 行）、307 个 Web TS/TSX 文件、161 个小程序 TS/TSX 文件、147 个数据库迁移、128 个权限码，全部经过代码级核实。

### 1.2 六维度综合评分

| 维度 | 评分 | 等级 | 上次(2026-05-11) | 变化 |
|------|------|------|-----------------|------|
| 架构 | 8.5/10 | A- | 7.5 | +1.0 |
| 安全 | 7.5/10 | B+ | 7.0 | +0.5 |
| 测试 | 5.5/10 | C+ | 6.5 | -1.0 |
| 前端/UX | 7.2/10 | B+ | 6.0 | +1.2 |
| DevOps | 3.8/10 | D+ | 4.0 | -0.2 |
| 产品 | 8.0/10 | B+ | 7.5 | +0.5 |
| **综合** | **6.8/10** | **B** | **6.9** | -0.1 |

**核心判断：** 架构和产品是系统最强维度，DevOps 是最明显短板。综合评分与上次基本持平，但内部结构变化显著——前端/UX 因统一组件库迁移大幅提升，测试因小程序零单元测试被拉低。

---

## 2. 维度一：架构 (8.5/10)

### 2.1 架构健康度评估

**依赖拓扑：** 严格星型结构，10 个 L2 crate 全部仅依赖 erp-core，零循环依赖。erp-server 是唯一聚合点。这在 17 crate 规模下是完全合理的。

```
                erp-core (零业务依赖)
               /    |    \    \     \
         erp-auth  config  workflow  message  health  ai  dialysis
                                                        \   |   /
                                                      erp-server
erp-plugin (依赖 erp-core，WASM 运行时)
```

**模块边界：** 所有业务 crate 通过 EventBus + trait 通信，不创建直接依赖。新模块（如 erp-billing）接入仅需 1-2 天，遵循成熟的 crate 模板。

### 2.2 事件系统成熟度

| 指标 | 值 | 评价 |
|------|-----|------|
| Health 域事件类型 | 31 | 覆盖全面 |
| 全系统事件类型 | 51 | 跨模块联动完善 |
| 事件发布点 | 82 | 密度合理 |
| 消费者模块 | 12 | 主要业务域覆盖 |
| Outbox 可靠性 | 7/10 | 持久化+NOTIFY+兜底轮询三重保障 |

**待改进：** 事件 payload 使用 `serde_json::Value`（无类型约束），超过 50 个事件类型后 schema 演进会变危险。建议为每个事件定义 Typed payload struct。

### 2.3 技术债务 TOP 5

| 排名 | 目标 | 问题 | 优先级 | 工作量 |
|------|------|------|--------|--------|
| #1 | erp-server/main.rs (991行) | OpenAPI 注解+路由+启动全在一个文件，65次clone | P1 | 2天 |
| #2 | erp-plugin 三巨头 (5,474行) | data_service+manifest+dynamic_table 过于庞大 | P2 | 3天 |
| #3 | version.unwrap() 模式 (8+处) | 系统性重复，数据损坏时 panic | P1 | 0.5天 |
| #4 | erp-health service 层日志缺失 | 26 个 service 仅 11 处 tracing | P1 | 1天 |
| #5 | erp-message/module.rs (1,220行) | 单文件包含全部消息逻辑 | P2 | 1天 |

### 2.4 erp-health 模块评估

214 文件 / 40,306 行，不需要拆分为子 crate，但需要内部模块化：
- Entity: 59 文件 / Handler: 32 文件 / Service: 57 文件（含子目录）
- 4 个文件超 800 行：action_inbox_service(1,104)、follow_up_service(1,000)、validation(916)、consultation_service(859)
- 建议：将大 service 拆为子目录（如 `action_inbox/crud.rs + query.rs + event_publish.rs`）

### 2.5 10x 数据量瓶颈

假设扩展到 1,000 租户 / 100 万患者：
- **瓶颈1**: 健康数据趋势查询聚合计算，需物化视图或预计算汇总表
- **瓶颈2**: Outbox Relay 单线程处理，需按 tenant_id 分片
- **瓶颈3**: EventBus broadcast channel 消费者 lag，需考虑 Redis Streams
- **非瓶颈**: UUID v7 B-tree（append-only）、Axum 路由（260+无压力）、SeaORM（编译时生成）

---

## 3. 维度二：安全 (7.5/10)

### 3.1 漏洞修复优先级

**P0（立即修复，共 ~4h）**

| 编号 | 问题 | 文件 | 方案 | 工作量 |
|------|------|------|------|--------|
| NEW-1 | 文件上传无 MIME 白名单 | media_handler.rs | 添加 ALLOWED_MIME_TYPES + 扩展名清理 | 2-3h |
| NEW-2 | OAuth JWT 密钥独立读取 | oauth/handler.rs | 复用 AppState 已验证密钥 | 1-2h |

**P1（短期修复，共 ~6h）**

| 编号 | 问题 | 文件 | 方案 | 工作量 |
|------|------|------|------|--------|
| HIGH-1 | JWT RwLock unwrap 热路径 | jwt_auth.rs:80,210 | 替换为 DashMap | 1-2h |
| MED-3 | Storage Secret 启动检查缺失 | config.rs | 添加与 JWT 相同的 exit(1) 检查 | 0.5h |
| COMP-1 | 审计日志 fire-and-forget 写入 | audit_service.rs:59 | 关键操作改为同步写入 | 4-6h |

**P2（中期修复，共 ~15h）**

| 编号 | 问题 | 方案 | 工作量 |
|------|------|------|--------|
| HIGH-2 | 动态表名 SQL 引号不一致 | 统一 safe_table_name() | 2-3h |
| HIGH-3 | WASM host block_on | spawn_blocking 线程池隔离 | 4-6h |
| MED-1 | version unwrap 20+处 | erp-core bump_version() 工具函数 | 2-3h |
| COMP-2 | PII 加密覆盖度无注册表 | 建立加密字段注册表 | 4-6h |

### 3.2 安全架构评分

| 子维度 | 评分 | 关键发现 |
|--------|------|----------|
| 认证体系 | 8/10 | Argon2 + 分层路由 + Token 黑名单 + 账户锁定 |
| 授权体系 | 7.5/10 | 128 权限码 + RBAC + 行级数据权限 + RLS |
| 数据保护 | 7/10 | AES-256-GCM PII + 哈希链审计日志 + Zeroizing |
| API 安全 | 8/10 | 三层限速 + fail-close + SeaORM 参数化 + sanitize_identifier |

### 3.3 医疗合规差距

| 合规领域 | 状态 | 关键差距 |
|----------|------|----------|
| HIPAA 访问控制 | PASS | RBAC + 多租户 + Argon2 |
| HIPAA 传输加密 | WARN | 代码无 TLS，需反向代理层文档化 |
| HIPAA 紧急访问 | MISSING | 无 break-glass 机制 |
| GDPR 被遗忘权 | MISSING | 软删除≠匿名化，需 GDPR 删除端点 |
| GDPR 数据可携带 | MISSING | 无数据导出端点 |
| 等保三级通信保密 | WARN | 需 TLS 部署证明 |
| 等保三级个人信息保护 | PARTIAL | 需同意管理 + 数据保留策略 |

### 3.4 积极发现

- 生产环境启动检查（JWT/CORS/KEK 全部 exit(1)）是业界最佳实践
- 哈希链审计日志在医疗 SaaS 中极为罕见
- 多层限速 + fail-close 体现安全工程成熟度
- Argon2 + Zeroizing + AES-256-GCM 密码学最佳实践组合

---

## 4. 维度三：测试 (5.5/10)

### 4.1 后端测试密度

| Crate | 测试函数 | 测试/文件 | Service 覆盖率 |
|-------|---------|-----------|---------------|
| erp-health | 203 | 0.95 | 15.8% (9/57) |
| erp-ai | 141 | 2.27 | 61.1% (11/18) |
| erp-config | 78 | 3.25 | 80% (4/5) |
| erp-core | 77 | 3.21 | N/A |
| erp-message | 77 | 4.28 | 75% (3/4) |
| erp-plugin | 78 | 3.25 | N/A |
| erp-workflow | 63 | 2.42 | **0%** (0/5) |
| erp-auth | 41 | 1.08 | 25% (3/12) |
| **合计** | **943** | **1.45** | -- |

**关键风险：** erp-health 是最关键模块（215 文件），但 service 层仅 15.8% 有测试。erp-workflow 完全没有 service 层测试。13/31 handler 无集成测试。

### 4.2 前端测试现状

| 平台 | 单元测试 | E2E | 最大风险 |
|------|---------|-----|---------|
| Web | 62 文件 / ~693 断言 | 13 spec | 页面覆盖 21% |
| 小程序 | **0 文件** | 4 spec | **全部逻辑层零测试** |

**小程序零单元测试是最严重的质量盲区。** 42 个 service 文件、5 个 store、7 个 utils 全部无测试保护。API 契约同步完全依赖手动发现。

### 4.3 测试补全策略

**Phase A — 小程序基础层（2-3天）：**
- utils/ 全覆盖 (~35 测试)
- services/request.ts 核心逻辑 (~20 测试)
- stores/ 全覆盖 (~40 测试)

**Phase B — 小程序 Service 层（3-5天）：**
- health/auth/consultation services (~95 测试)

**Phase C — 后端安全关键路径（1周）：**
- erp-auth service 层: 25% → 80% (~45 测试)
- erp-workflow service 层: 0% → 60% (~30 测试)
- 告警 handler 集成测试: 0 → 覆盖 (~20 测试)

### 4.4 质量门禁建议

| 套件 | 耗时 | 频率 | 包含 |
|------|------|------|------|
| 快速反馈 | ~3min | 每次 commit | unit tests + type check |
| 标准验证 | ~10min | 每个 PR | + integration tests + clippy + lint |
| 完整回归 | ~30min | main merge | + E2E + coverage + security |
| 性能基准 | ~15min | 版本发布前 | benchmarks + load tests |

### 4.5 覆盖率目标

| 层级 | 当前 | 3个月 | 6个月 |
|------|------|-------|-------|
| 后端 service 层 | ~30% | 60% | 80% |
| 后端 handler 集成测试 | 58% (18/31) | 80% | 100% |
| 小程序 service+store | 0% | 60% | 80% |
| Web 页面组件 | 21% | 40% | 60% |
| E2E 覆盖 | 5 条核心链路 | 10 条 | 15 条 |

---

## 5. 维度四：前端/UX (7.2/10)

### 5.1 前端架构评分

| 子维度 | Web | 小程序 | 评价 |
|--------|-----|--------|------|
| 代码组织 | 8.0/10 | 7.0/10 | 目录结构清晰，分层合理 |
| 状态管理 | 优秀 | 良好 | Zustand 5，Web 6 store / MP 5 store |
| Design Token | 8.5/10 | 8.5/10 | 11 级字号 + 非线性关怀模式放大 |
| 请求层抽象 | 优秀 | 优秀 | JWT 主动刷新 / 并发限制 MAX_CONCURRENT=8 |
| 组件化 | 7.0/10 | 7.0/10 | Web 18 + MP 21 组件，仍有提升空间 |
| 测试覆盖 | 7.0/10 | **0/10** | MP 零单元测试 |

### 5.2 Design Token 亮点

Token 三层架构是项目做得最好的部分之一：

```
tokens.scss (定义 11 级字号 + 12 结构 token)
→ variables.scss (语义色 var(--tk-pri))
→ 页面 SCSS (75 页面全量接入 var(--tk-*))
```

- 非线性关怀模式放大：标题 x1.15 / 正文 x1.35 / 辅助 x1.55
- 医生端靛蓝色系通过 `.doctor-mode` CSS 变量级联覆盖
- Web 端 4 套主题通过 Ant Design ConfigProvider 动态切换

### 5.3 小程序核心亮点

- `request.ts`：并发限制(8) + inflight 去重 + 响应缓存(TTL+patientId 隔离) + Token 刷新去重
- 统一组件库：PageShell/ContentCard/StatusTag/ListItem/VitalCard 等 17 UI + 4 pattern 组件
- 分包策略：主包 12 页面 + 7 分包按业务域划分
- `safeNavigateTo` 栈深度保护解决微信 10 层限制

### 5.4 前端待改进项

| 问题 | 优先级 | 工作量 | 方案 |
|------|--------|--------|------|
| OpenAPI spec 自动生成 TS 类型 | P0 | 3天 | 引入 openapi-typescript，根治 35 次接口不同步 fix |
| MP 核心层单元测试 | P0 | 5-8天 | request.ts + stores + 核心 services |
| Web 大文件拆分(>400行 x15) | P1 | 5天 | 提取共享表单/列表模式 |
| MP service 层 doctor/ 重复逻辑 | P1 | 2天 | 提取 services/shared/ 共享接口 |
| Storybook 组件文档 | P1 | 3天 | MP 17 组件逐个建档 |

---

## 6. 维度五：DevOps (3.8/10)

### 6.1 生产就绪度评分

| 子维度 | 评分 | 关键差距 |
|--------|------|----------|
| 部署方案 | 5/10 | Docker 完善，但无 HTTPS/LB/多副本 |
| 高可用性 | 2/10 | 单容器，无水平扩展，文件上传存本地磁盘 |
| 灾难恢复 | 3/10 | pg_dump 有，但无恢复测试、无异地备份 |
| 监控告警 | 3/10 | Prometheus exporter 已实现(端口 9090)，但未接入采集端 |
| CI/CD | 4/10 | 基础 CI 存在，无 CD/安全扫描/E2E |
| 密钥管理 | 4/10 | 环境变量注入，无 Vault/KMS |

### 6.2 紧急修复路线图

**Phase 0 — 安全修复（1-2天）：**
- Redis 连接启用 TLS
- 数据库连接 SSL mode
- 固定 Docker 基础镜像版本
- 备份推送到异地存储(S3/OSS)

**Phase 1 — 最小可观测性（3-5天）：**
- Docker Compose 添加 Prometheus + Grafana（代码已有 exporter）
- 基础仪表盘（HTTP QPS/延迟/错误率 + DB/Redis 健康）
- 基础告警规则（服务宕机、错误率 >5%）
- 接入告警通道（企业微信/钉钉 Webhook）

**Phase 2 — CI/CD 完善（3-5天）：**
- Docker 镜像构建 + 推送到 Registry
- 安全扫描（cargo audit + npm audit + Trivy）
- 部署脚本（pull + migrate + health check + switch）

**Phase 3 — 生产加固（5-7天）：**
- Nginx/Caddy 反向代理 + HTTPS（Let's Encrypt）
- 上传文件存储迁移到对象存储（解锁多副本前提）
- 日志聚合（Loki）+ 审计日志持久化
- 密钥管理迁移到 Vault/云 KMS

### 6.3 医疗 SaaS 合规硬性要求

| 要求 | 当前状态 | 优先级 |
|------|---------|--------|
| 数据传输加密(HTTPS) | 无 | P0 |
| 审计日志持久化(6年+) | 无 | P0 |
| 数据备份恢复测试 | 未验证 | P0 |
| 安全漏洞扫描 | 无 | P1 |
| 密钥管理服务 | .env 文件 | P1 |
| 灾难恢复计划 | 无 | P1 |

---

## 7. 维度六：产品 (8.0/10)

### 7.1 功能完整度评估

| 梯队 | 模块 | 后端 | 管理后台 | 小程序 | 综合评分 |
|------|------|------|---------|--------|---------|
| 第一梯队(>85%) | 患者管理 | 完整 | PatientList+Detail | 建档/查看 | 95% |
| | 健康数据 | 完整 | 健康记录+化验 Tab | 体征/趋势/监测 | 90% |
| | 预约排班 | 完整 | AppointmentList | 创建/详情 | 90% |
| | 咨询管理 | 完整 | ConsultationList | 列表/聊天 | 90% |
| | 告警系统 | 完整 | AlertDashboard | 列表/详情 | 90% |
| | 内容管理 | 完整 | ArticleEditor+Banner | 文章/轮播图 | 88% |
| | 积分商城 | 完整 | PointsRule/Product | 商城/兑换 | 85% |
| 第二梯队(60-84%) | 随访管理 | 完整 | 三页面齐全 | 工作流联动弱 | 80% |
| | AI 分析 | 9实体+4Provider | 页面存在但缺触发入口 | AI 报告列表 | 70% |
| | 设备采集 | 完整 | RealtimeMonitor | BLE 同步 | 70% |

### 7.2 AI 能力"最后一公里"问题

| AI 能力 | 后端 | 前端入口 | 可触达率 |
|---------|------|---------|---------|
| 化验单解读 | SSE 端点完整 | 缺触发按钮 | ~40% |
| 趋势分析 | SSE 端点完整 | 缺触发入口 | ~30% |
| 报告摘要 | SSE 端点完整 | 缺入口 | ~20% |
| AI 客服聊天 | 完整 | 小华助手页面 | ~80% |

**核心判断：** AI 管理能力（Prompt 管理 + 用量统计）已完整，但核心消费场景缺少 UI 入口。这是"有了发动机但没有方向盘"的状态。

### 7.3 差异化竞争力

1. **AI + 医疗数据深度整合** — 化验解读/趋势分析/报告摘要，Prompt 可配置
2. **Rust 事件驱动架构** — 高并发稳定、模块可独立部署、数据不丢失
3. **多租户 SaaS + FHIR 开放平台** — 零部署、数据隔离、与 HIS/LIS 互操作

### 7.4 SaaS 定价建议

| 层级 | 目标 | 核心功能 | 定价锚点 |
|------|------|---------|---------|
| 免费层 | 引流体验 | 患者管理+基础排班+咨询+3篇文章/月 | 0 |
| 专业层 | 核心营收 | AI 分析+护理计划+告警+设备+透析+FHIR | 按年检量阶梯定价 |
| 企业层 | 高价值增值 | 多租户集团+FHIR 读写+AI 自定义+专属部署 | 定制报价 |

---

## 8. TOP 10 紧急行动清单

| # | 行动项 | 维度 | 优先级 | 工作量 | 预期效果 |
|---|--------|------|--------|--------|----------|
| 1 | 文件上传 MIME 白名单 | 安全 | P0 | 2-3h | 消除存储型 XSS |
| 2 | OAuth JWT 密钥路径统一 | 安全 | P0 | 1-2h | 消除空密钥绕过 |
| 3 | CI 添加安全扫描 | DevOps | P0 | 0.5天 | 持续安全防线 |
| 4 | AI 分析前端触发入口 | 产品 | P0 | 3-5天 | AI 可触达率 30%→80% |
| 5 | JWT RwLock→DashMap | 安全 | P1 | 1-2h | 消除认证热路径 DoS |
| 6 | version.unwrap() 消除 | 架构 | P1 | 0.5天 | 消除 8+ 处潜在 panic |
| 7 | MP 核心层单元测试 | 测试 | P1 | 5-8天 | 消除最大质量盲区 |
| 8 | 最小可观测性(Prometheus+Grafana) | DevOps | P1 | 3-5天 | 代码已有 exporter |
| 9 | main.rs 拆分重构 | 架构 | P1 | 2天 | 消除 65 次 clone |
| 10 | OpenAPI 自动生成 TS 类型 | 前端 | P1 | 3天 | 根治 35 次接口不同步 |

**P0 总工作量：~4-5 天**（#1-#4）
**P1 总工作量：~15-20 天**（#5-#10）

---

## 9. Wiki 关键数字校正表

| 指标 | Wiki 旧值 | 实际值 | 变化 |
|------|-----------|--------|------|
| Rust 源文件 | 649 | **652** | +3 |
| 数据库迁移 | 146 | **147** (m20260516) | +1 |
| erp-health 文件 | 189 | **214** | +25 |
| erp-health Entity | 57 | **59** (handler 32/service 41) | +2 |
| erp-ai 文件 | 45 | **62** | +17 |
| 权限码 | 132 | **128** (health 52 + 其他 76) | -4 |
| Web TS/TSX | 332 | **307** | -25 |
| Web 活跃路由 | 29 | **36** (冻结 5) | +7 |
| Web API 模块 | 52 | **42** | -10 |
| 小程序 TS/TSX | 163 | **161** | -2 |
| 小程序页面 | 66 | **60** | -6 |
| 前端测试断言 | 472+39 | **~757** | 重新定义口径 |
| 事件类型 | 31(health) | **31**(health)/**51**(全系统) | 补全系统口径 |
| utoipa 注解文件 | 88 | **89** | +1 |
| Rust 代码总行数 | 未记录 | **136,908** | 新增 |
| Entity 总数(全系统) | 未记录 | **109** | 新增 |
| Service 总数(全系统) | 未记录 | **107** | 新增 |