# HMS 健康管理平台 — 三维度深度分析报告

> 日期: 2026-05-07 | 数据截止: commit 786f57c (第 692 次提交) | 分析范围: 全系统

## 背景

HMS 健康管理平台经过 692 次提交的密集开发，从近 30 次提交（全为 fix 类型）来看已进入**上线前质量加固阶段**。本报告从后端架构、前端体验、文档质量三个维度对系统进行全面梳理，识别过时数据、关键风险和改进机会。

## 1. 执行摘要

| 维度 | 评分 | 关键发现 |
|------|------|---------|
| 后端架构 | 7.5/10 | 模块化优秀，erp-health 巨石化（38%占比），514 个 unwrap() |
| 前端体验 | 6.5/10 | Web 质量好，小程序测试极差，AI 入口缺失，国际化缺失 |
| 文档质量 | 6.0/10 | 体系完善但数据严重过时（12+ 指标与实际不符） |
| **综合** | **6.4/10** | 功能完整度 85%，生产就绪度约 55% |

**最高优先级行动：**
1. CRITICAL — 创建生产级 Dockerfile（从"能跑"到"能部署"）
2. HIGH — 补全 AI 分析前端 UI 入口（核心差异化功能完整呈现）
3. HIGH — 配置 pre-commit hooks（阻止问题继续累积）

---

## 2. 后端架构分析

### 2.1 Crate 结构概览

系统共 18 个 Rust crate，579 个 .rs 源文件：

| Crate | 文件数 | 代码量(约) | 职责 |
|-------|--------|-----------|------|
| erp-health | 179 | 35,750 | 核心医疗模块（38% 占比） |
| erp-server | 18 | 23,481 | HTTP 入口 + 路由组装 |
| erp-plugin | 24 | 10,945 | 插件引擎 |
| erp-ai | 45 | 7,039 | AI 分析 |
| erp-auth | 38 | 6,889 | 认证/权限 |
| erp-workflow | 26 | 5,327 | 工作流引擎 |
| erp-config | 24 | 4,974 | 配置/字典/菜单 |
| erp-message | 18 | 3,699 | 消息通知 |
| erp-core | 23 | 2,513 | 基础框架 |
| erp-dialysis | 20 | 1,779 | 透析管理 |
| 插件骨架 ×7 | 7 | ~430 | 各类插件原型 |

**依赖关系：** `erp-core` → 8 个业务模块 → `erp-server` 组装。模块间零直接业务依赖，通过 EventBus + trait 通信。

### 2.2 erp-health 巨石模块风险

**规模：** 179 文件 / 35,750 行，占全部 Rust 代码的 38%。

**内部结构：**
- entity/: 55 个实体文件
- handler/: 29 个 HTTP handler
- service/: 37 个服务文件（含 5 个子目录）
- dto/: 20 个 DTO 文件
- fhir/: 4 个 FHIR R4 兼容层文件
- oauth/: 6 个 OAuth 文件
- event.rs: 2,327 行（含 1,300+ 行测试）

**风险点：**
- 4 个 service 文件超过 1,000 行（points_service 1,863 行、patient_service 1,118 行）
- 单个 crate 搭载 12 个业务子域（患者/预约/随访/咨询/告警/积分/设备/内容/护理/透析/班次/知情同意）
- 建议：按子域拆分为 3-4 个独立 crate

### 2.3 erp-ai 模块

**规模：** 45 文件 / 7,039 行，22 条 API 路由。

- 4 个 AI Provider：Claude、OpenAI、Ollama、Registry
- 11 个实体（分析记录/队列/知识库/Prompt/风险阈值/建议/配额等）
- 支持 SSE 流式分析，每日自动扫描高风险患者
- 事件驱动：`lab_report.uploaded` → 自动入队 → 化验单解读

### 2.4 事件系统

- **31 个事件类型**（health 模块内）+ 跨模块事件
- **23 个幂等消费者**，每个有 `is_event_processed()` 检查
- 基于 `tokio::sync::broadcast` + PostgreSQL Outbox + LISTEN/NOTIFY
- 死信队列兜底：消费失败写入 `dead_letter_events` 表
- 治理风险：事件类型已从 25 暴增，但缺乏版本管理和 schema 注册

### 2.5 代码质量信号

| 信号 | 数量 | 严重程度 |
|------|------|---------|
| TODO/FIXME | 5 处 | 低 |
| unwrap() 调用 | 514 个（含测试） | 高（erp-plugin 113、erp-ai 77） |
| 注释掉的代码 | 0 行 | 优秀 |
| pub 函数 | ~1,201 个 | 公共 API 面积较大 |

### 2.6 数据库迁移

共 128 个迁移文件（最早 2026-04-10，最新 2026-05-07），覆盖：
- 基础设施（001-031）、插件系统（033-041）、核心医疗（042-058）
- 安全加密（062-072）、告警设备（073-095）、扩展功能（096-128）
- 亮点：RLS 全面启用、审计日志哈希链、pgvector 扩展

### 2.7 API 路由统计

约 250+ 条路由，分布：
- erp-health: ~137 条（public 1 + FHIR 14 + gateway 2 + protected ~120）
- erp-ai: 22 条
- 其他模块: ~90 条（auth/config/workflow/message/plugin/dialysis）

---

## 3. 前端分析

### 3.1 Web 前端

| 维度 | 数据 |
|------|------|
| 框架 | React 19 + Ant Design 6 + Zustand 5 + Tailwind CSS v4 |
| 源文件 | 283 个 TS/TSX |
| 路由 | 55 条（8 系统 + 6 插件 + 38 健康 + 6 冻结） |
| API 模块 | 50 个（含完整 TypeScript 类型定义） |
| Store | 6 个 Zustand Store（均有测试） |
| 主题 | 4 套（信任蓝/温润东方/深邃夜色/翡翠清雅） |

**亮点：**
- API 层封装质量高：自动 token 刷新 + 并发请求队列去重 + 5 秒内存缓存
- 三层权限控制：路由级（PrivateRoute）+ 组件级（AuthButton）+ 菜单级
- 测试工厂模式：`listPageTests.tsx` 自动生成列表页标准测试
- 6 个 Store 全部有请求去重和错误处理

**问题：**
- **国际化缺失**：无 i18n 框架，所有文本硬编码中文
- **6 条路由冻结**：护理计划/班次/家庭代理/药物/透析/排班显示"功能暂未开放"
- **AI 分析无 UI 入口**：4 个 SSE 端点完整实现但无前端页面触发

### 3.2 微信小程序

| 维度 | 数据 |
|------|------|
| 框架 | Taro 4.2 + React 18 + Zustand 5 |
| 源文件 | 118 个 TS/TSX |
| 页面 | ~54 个（主包 12 + 分包 42） |
| TabBar | 4 个（首页/健康/消息/我的） |
| 医生端 | 独立分包（16 个页面） |
| API 服务 | 37 个模块 |

**亮点：**
- AES 加密安全存储，生产环境强制密钥
- BLE 蓝牙设备集成（小米手环）
- 请求层并发去重 + 60 秒缓存 + 切换患者自动隔离

**问题：**
- 测试极差：仅 BLE 模块 4 个单元测试 + 4 个 E2E
- 118 个源文件几乎无测试覆盖

### 3.3 测试覆盖对比

| 层级 | 源文件 | 测试文件 | 覆盖比 |
|------|--------|---------|--------|
| Rust 后端 | 579 | 101（含测试）+ 25 集成 | 1:4.5 |
| Web 前端 | 283 | 62 单元 + 13 E2E | 1:3.8 |
| 小程序 | 118 | 4 单元 + 4 E2E | 1:14.8 |
| **后端测试函数** | **772 个**（611 单元 + 153 集成 + 8 多模块） | 97.5% 通过率 |

---

## 4. 文档与质量分析

### 4.1 文档体系

| 类型 | 数量 | 状态 |
|------|------|------|
| 设计规格 | 47 份 | 覆盖全面 |
| 实施计划 | 49 份 | 覆盖全面 |
| 讨论记录 | 26 份 | 遵循命名规范 |
| 审计报告 | 25 份（V1×8 + V2×13 + 截图） | 双轮完整审计 |
| Wiki 页面 | 12 个 | 数据过时 |
| plans/ 目录 | 87 个文件 | 膨胀需归档 |

### 4.2 wiki 数据过时（已验证）

| 指标 | wiki 值 | 实际值 | 偏差 |
|------|--------|--------|------|
| Git 提交 | 577 | 692 | +115 |
| 数据库迁移 | 123 | 128 | +5 |
| Rust 源文件 | 484 | 579 | +95 |
| Web 前端文件 | 225 | 283 | +58 |
| 前端测试文件 | 36 | 62 | +26 |
| E2E spec | 5 | 13 | +8 |
| 设计规格 | 41 | 47 | +6 |
| 实施计划 | 38 | 49 | +11 |
| 讨论记录 | 18 | 26 | +8 |

### 4.3 CI/CD 与工程质量

| 项 | 状态 | 说明 |
|----|------|------|
| GitHub Actions | ✅ 配置 | Rust check/test/clippy + 前端 tsc/test/build |
| Gitea Actions | ✅ 配置 | Rust fmt/check/test + 前端 build + 安全审计 |
| ESLint | ✅ 配置 | TypeScript 严格模式 + React Hooks 规则 |
| Prettier | ❌ 未配置 | 无代码格式化工具 |
| Pre-commit hooks | ❌ 未配置 | 质量门禁形同虚设 |
| Docker | ⚠️ 仅数据库 | PostgreSQL + Redis，无应用镜像 |
| 生产部署 | ❌ 无方案 | 无法部署到任何服务器 |

### 4.4 根目录污染

遗留文件散落在项目根目录：
- 日志文件：`crash.log`、`server-output.log`、`server-stderr.log` 等
- 测试令牌：`.test_token`、`.test_token_fresh.txt`
- 截图：`current-page.png`、`home-full.png`、`home-improved.png`
- 快照：`snapshot_*.txt`（4 个）
- OCR 数据：`chi_sim.traineddata`（3.4MB）
- Python 脚本：`test_api_auth.py`、`test_users.py`

---

## 5. 项目阶段判断

**阶段：上线前质量加固**

证据：
1. 近 30 次提交全为 `fix` 类型（feat:fix 比约 2.3:1 的历史值已逆转）
2. 工作重心是 5 角色深度测试修复 + 安全加固 + AI 模块修复
3. V2 审计完成（85%），CRITICAL 安全问题已修复
4. 6 个模块主动冻结（护理/班次/家庭代理/药物/透析/排班）

**定位：**
- 功能完整度：85%（12 个活跃功能域基本完整）
- 代码质量：75%（Rust 后端优秀，前端质量待提升）
- 安全合规：70%（PII 加密优秀，但仍有 CRITICAL 漏洞发现）
- 可部署性：40%（无生产部署方案）
- 可维护性：65%（文档完善但过时，代码膨胀需治理）

---

## 6. 关联文档

- [多专家组头脑风暴记录](2026-05-07-expert-brainstorm-session.md) — 5 位专家独立评审 + 行动清单
- [wiki/index.md](../../wiki/index.md) — 待更新的知识库入口
- [V2 审计最终报告](../audits/v2/13-final-report.md) — 85% 完成度审计
- [夯实基础设计规格](../superpowers/specs/2026-05-05-foundation-solidification-design.md) — 冻结策略和后续路线图