df1d85bfde
- T40 UI 审计计划和结果文档（docs/qa/） - wiki 更新：miniprogram 设计系统合规审计记录 + index 关键数字更新 - 审计 V2 完整报告（docs/audits/v2/） - 讨论记录文档（docs/discussions/） - 设计规格和实施计划（docs/superpowers/） - 角色测试计划和结果（docs/qa/role-test-*） - Docker 生产部署配置
238 lines
9.1 KiB
Markdown
238 lines
9.1 KiB
Markdown
# 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) — 冻结策略和后续路线图
|