hms/docs/superpowers/specs/2026-04-26-platform-retrospective-and-evolution-design.md

HMS 平台基座回顾与演进设计

日期: 2026-04-26 | 状态: Draft | 方法: 三专家多视角评审

---

1. 概述

1.1 回顾目的

HMS 健康管理平台经过 17 天密集开发（2026-04-10 ~ 2026-04-26），从 ERP 底座演进到包含 16 个 Rust crate、62 个前端页面、27 个小程序页面的综合医疗 SaaS 平台。本次回顾旨在：

• 验证基座设计 — 星形依赖拓扑、ErpModule trait、事件总线、多租户策略是否经得起实践检验
• 评估演进路径 — 从插件开发模式到原生模块开发的决策是否正确
• 识别缺口与风险 — 通过多专家视角发现盲点
• 制定演进路线 — 基于 P0/P1/P2 优先级指导后续迭代

1.2 评审方法

采用三专家独立评审，每个专家从不同视角分析相同的诊断和建议：

专家	视角	关注点
高级系统架构师	架构可持续性	模块边界、事件可靠性、技术债
医疗信息化专家	临床安全与合规	患者安全、PIPL 合规、领域模型
产品策略专家	ROI 与开发节奏	优先级、技术债量化、路线图现实性

1.3 核心结论

基座设计方向正确，但深度不足。 星形依赖、trait 抽象、事件总线等基础架构经受住了实践检验。但在临床安全（危急值告警未闭环）、合规（知情同意缺失）、事件可靠性（无重放机制）方面存在需立即修复的缺口。插件系统已验证可行性但对 HMS 核心业务贡献有限，建议有条件冻结。

---

2. 基座设计验证

2.1 评分总览

维度	评分	说明
模块边界	★★★★	星形拓扑零循环依赖，trait 契约清晰
ErpModule trait	★★★★	生命周期/权限/事件/健康检查统一接口
事件总线	★★★☆	基础设施扎实（broadcast+outbox），但无重放机制，消费侧不完整
多租户	★★★☆	JWT→TenantContext 全链路贯通，但缺 RLS 兜底和集成测试
权限体系	★★★★	RBAC + 行级数据权限 + 按钮级控制
插件系统	★★★☆	CRUD 场景验证通过，医疗场景天花板明显
API 一致性	★★★★	统一 envelope、分页、OpenAPI 自动文档
数据库迁移	★★★★	59 个迁移，幂等、可回滚、fixup 模式健康
测试覆盖	★☆☆☆	36 后端 + 3 前端，覆盖率 < 5%
合规性	★☆☆☆	知情同意缺失，审计不完整，PIE 加密范围不足

2.2 星形依赖拓扑

                    erp-core (L1)
                   /   |    \    \      \        \
          erp-auth  workflow  message  config  erp-health  erp-plugin  erp-ai
                   \   |    /    /      /        /        /
                        erp-server (L3, 组装入口)

• erp-core：零业务依赖，纯净基础层
• 7 个业务 crate：各只依赖 erp-core，兄弟间无横向依赖
• erp-server：唯一组装点，负责路由合并和模块初始化
• 无循环依赖 — 架构师验证通过

2.3 ErpModule trait

当前 trait 提供统一的模块接口：

• 身份：name() / id() / version()
• 依赖声明：dependencies() — 用于拓扑排序启动顺序
• 生命周期：on_startup() / on_shutdown() / health_check()
• 多租户：on_tenant_created() / on_tenant_deleted()
• 权限自描述：permissions() — 模块声明自己需要的权限码
• 事件订阅：register_event_handlers() / as_any()

已知张力：路由注册不在 trait 中，而是通过各模块的 inherent method (public_routes() / protected_routes()) 手动在 main.rs 中合并。原因是 Axum 的 Router<S> 泛型约束不适合 trait object。这是务实的妥协，但在添加新模块时有 boilerplate 成本。

2.4 事件总线

实现机制：tokio::sync::broadcast (容量 1024) + domain_events 表持久化（best-effort）+ Outbox relay (5秒轮询，3次重试)

发布侧（已识别的事件类型）：

模块	事件类型数	示例
erp-auth	10	user.login, user.created, role.created
erp-workflow	4	process_instance.started, task.completed
erp-message	1	message.sent
erp-health	13	patient.created, health_data.critical_alert, follow_up.overdue
erp-plugin	2+	plugin.config.updated, plugin.trigger.*

消费侧（已识别的订阅者）：

订阅者	订阅方式	处理的事件
erp-message	subscribe() 全量	appointment.*, process_instance.*, task.*
erp-health	register_handlers_with_state	workflow.task.completed
erp-plugin 通知	subscribe_filtered("plugin.trigger.*")	插件触发通知
outbox relay	轮询 DB	重发 pending 事件

已识别缺陷：

1. 无重放机制 — 内存 broadcast，服务重启后未消费的事件丢失
2. 无幂等保护 — follow_up.overdue 每 6 小时检查会重复发布同一条逾期事件
3. 全量订阅 — erp-message 使用 subscribe() 而非 subscribe_filtered()，所有事件都经过消息模块

2.5 多租户

已实现：

• JWT claims 提取 tenant_id → TenantContext 注入请求扩展
• 所有 Entity 含 tenant_id 字段，BaseFields 统一
• 所有 DomainEvent 携带 tenant_id
• on_tenant_created() / on_tenant_deleted() 钩子（auth 和 health 已实现）
• 部门级数据范围（department_ids 在 TenantContext 中）

缺失：

• 无 PostgreSQL RLS policy 作为兜底层
• 无强制 tenant_id 过滤的查询层机制 — 依赖每个 service 手动 .filter()
• 当前实际只有 default_tenant，微信登录硬编码使用 default_tenant_id
• 无多租户管理 API（创建/配置/迁移）

---

3. 演进路径回顾

3.1 时间线

4/10-4/16  基座搭建 (Phase 1-6)
           → core → auth → config → workflow → message
           → 全部原生 Rust 模块，30+ 数据库表

4/13-4/18  WASM 插件实验
           → 插件系统设计与实现 (Wasmtime + WIT bindgen)
           → CRM (5实体) → Inventory (6实体) → Freelance → ITOps
           → 证明：CRUD 密集型领域可行，沙盒隔离有效
           → 跨插件数据引用未解决

4/23-4/26  HMS 分叉 — 健康模块原生开发
           → 18+ 强类型实体 (患者/家属/医生/预约/排班/随访/咨询/体征/化验/透析/诊断/积分...)
           → PII 加密 (AES-256-GCM)、脱敏管道
           → AI 模块 (4 SSE 流式端点 + 3 REST 端点)
           → 微信小程序 (27 页面)
           → 按钮级权限控制

3.2 从插件到原生的决策链

原始插件愿景（设计规格 2026-04-13）：

• 平台模块原生，行业模块 WASM 插件
• 插件通过 9 个 Host API 函数通信（db_insert/query/update/delete、event_publish、config_get 等）
• 数据存 JSONB 动态表，路由自动生成
• UI 配置驱动，通用 PluginCRUDPage 组件

健康模块原生的 5 个硬限制（设计规格 2026-04-23 §1.3）：

限制	影响	不可妥协原因
20 实体上限	健康平台轻松超过	18+ 实体已是最低合理粒度
JSONB 存储	无强类型、无外键约束	医疗数据需要引用完整性和精确索引
无自定义 API	只有自动 CRUD	趋势分析/统计报表/日历视图无法实现
无文件上传	沙盒阻止文件系统访问	化验单/体检报告需要文件存储
WASM 沙盒限制	无 native crypto/外部 API/后台任务	PII 加密、微信集成、定时任务全部需要

3.3 得失评估

得 — 正确的决策：

决策	收益
星形依赖拓扑	模块独立性强，可独立测试和替换
ErpModule 统一接口	新模块注册流程标准化
事件总线	跨模块解耦通信的基础设施已就绪
JWT→TenantContext	多租户全链路贯通
健康模块原生	不受沙盒限制，加密/文件/后台任务全部可用
插件实验	验证了平台灵活性，CRM/库存可正常使用

失 — 需要修正的问题：

决策	代价
插件系统投入过大	22,000 行代码（41% Rust 总量），对 HMS 核心业务贡献接近零
积分系统混入 health	8 实体/12+ 路由，增加合规复杂度和数据泄露面
事件消费侧忽视	13 个事件只有 3 个被消费，危急告警和逾期通知空转
测试覆盖极薄	36 后端 + 3 前端测试，覆盖率 < 5%
合规意识不足	知情同意缺失、审计不完整、PIE 加密范围不足

---

4. 三专家评审摘要

4.1 高级系统架构师

诊断准确度：7/10 — 四个张力都真实存在，但优先级和细节有偏差。

关键补充：

发现	严重程度
WIT 接口是同步调用（阻塞），WASM 运行时嵌入主进程（故障隔离不足）	架构隐患
EventBus 内存 broadcast 无重放机制，服务重启丢事件	P1
follow_up.overdue 无幂等保护，每 6h 检查重复发布	P0
erp-message 用 subscribe() 全量订阅，性能隐患	P1
RLS 不是 P0，多租户集成测试才是	观点
积分系统（8 独立实体、12+ 路由）不应在 erp-health 内	共识
缺监控/可观测性、数据备份策略、API 版本升级路线图	盲点

核心原则：先补测试再重构，先修事件再上功能，先验证再加固。

4.2 医疗信息化专家

发现了比原始诊断更深层的临床安全风险。

新发现	严重程度
危急值阈值全部硬编码（收缩压 180/80、心率 150/40），不可配置	P0
daily_monitoring 表体征数据不经过危急值检测（合并前遗留）	P0
过敏史更新直接覆盖，无变更历史	P0
知情同意完全缺失（搜索 consent/同意/授权/隐私 零结果）	P0 — PIPL 违规
只有身份证号存储加密，姓名/过敏史/诊断/咨询内容明文	P1
审计日志不完整 — 只有预约状态变更记录前后值	P1
ip_address 和 user_agent 从未被填充	P1
读操作（查看患者详情/化验报告）完全没有审计记录	P1
诊断记录 icd_code 只做字符串约束，无格式校验，无同行审核	P1

合规评估：PIPL 第 29 条要求处理敏感个人信息须取得单独同意。医疗数据属于敏感个人信息。知情同意缺失是法律红线。

领域模型建议：积分系统（6 实体 + 2 线下活动实体）应拆分为独立 erp-points 或 erp-engagement 模块，与健康数据分离以降低合规复杂度。

4.3 产品策略专家

开发节奏不可持续但不必恐慌。

分析	结论
峰值 68 提交/天，fix 提交占 21.6%	短期冲刺可以，长期人会耗竭
41% Rust 代码在插件系统，对核心业务贡献接近零	最大 ROI 失衡
单人 + AI 的"速度幻觉"	68 提交/天 = 审查不足，积分混入 health 就是例证
测试覆盖 < 5%	正确水位不是 80%，而是关键路径不回退（目标 50-80 用例，3-4 天）

关键风险缓解建议：

• ADR（架构决策记录）强制化
• 医疗安全代码双人外部 review
• 每日提交上限 15 次
• 每月需求裁剪

V2 血透路线图评估：技术储备已够（dialysis_service 286 行骨架在），但缺市场验证。建议先做 3-5 家目标客户调研，确认需求后再做 2 周 MVP 试运行。

---

5. 共识优先级

5.1 三专家加权共识矩阵

议题	架构师	医疗专家	产品策略	共识等级
危急值告警闭环	P0	P0 + 硬编码	P0	三方一致
知情同意 (PIPL)	未涉及	P0	P0	两方一致
审计日志补全	未涉及	P1	P0	P0-P1
EventBus 可靠性	P1	未涉及	P0	P0-P1
随访逾期通知	P0	P0	P0	三方一致
积分系统拆分	应拆	应拆(合规)	占 19.5%	三方一致
RLS	不是 P0	P1	P0	有分歧
插件系统	有条件冻结	未涉及	冻结	两方一致
测试覆盖	先补测试	上线前必修	50-80 用例	三方一致
V2 血透	未涉及	缺标准流程	先调研	两方一致

5.2 P0 — 上线前必修（估计 2-3 周）

序号	项	工作量	负责 crate	说明
1	危急值告警消费者	1 天	erp-health + erp-message	health_data.critical_alert → 推送通知给责任医护
2	危急值阈值可配置化	2 天	erp-health	硬编码阈值改为数据库配置，支持科室/年龄差异化
3	daily_monitoring 合并后告警验证	1 天	erp-health	确认合并到 vital_signs 后所有体征数据都经过告警检测
4	随访逾期通知	1 天	erp-health + erp-message	follow_up.overdue → 催办通知 + 幂等保护
5	知情同意记录	3 天	erp-health	患者数据处理同意获取和记录机制
6	审计日志补全	3 天	erp-core + erp-health	临床数据变更记录前后值、读操作审计、IP/UA 填充
7	EventBus 持久化增强	2 天	erp-core	服务重启不丢事件 + overdue 事件幂等

5.3 P1 — 治理（2-4 周）

序号	项	工作量	说明
8	积分系统剥离	5 天	从 erp-health 拆分为独立 erp-engagement crate
9	关键路径测试	4 天	多租户隔离、患者安全路径、预约并发（50-80 用例）
10	插件系统冻结声明	0.5 天	保留代码，README 声明实验性，不再投入
11	erp-message 改用 subscribe_filtered	1 天	减少无效事件传递
12	统一事件消费模式	2 天	消除 register_event_handlers vs on_startup 双路径
13	过敏史变更历史	1 天	更新时记录旧值

5.4 P2 — 扩展（后续迭代）

序号	项	前置条件
14	PostgreSQL RLS	P1 测试覆盖完成
15	血透专科	3-5 家客户调研完成
16	OCR 化验单提取	血透验证后
17	IM 咨询	血透验证后
18	health 模块按子域重组目录	P1 测试覆盖完成
19	前端测试覆盖提升	P1 后端测试完成
20	动态菜单系统	现有计划可用

---

6. 风险与缓解

6.1 开发模式风险

风险	影响	缓解措施
单人认知单点	一人理解 16 个 crate，bus factor = 1	ADR 强制化，关键决策留文档
AI 生成"编译对但逻辑错"	危急值阈值硬编码、积分混入 health 就是例证	医疗安全代码双人外部 review
速度幻觉	68 提交/天 = 审查不足	每日提交上限 15 次
AI 回音壁	AI 不质疑需求合理性	每月需求裁剪，引入真实用户反馈

6.2 临床安全风险

风险	影响	缓解措施
危急值告警未闭环	危急体征值无人响应，可致患者安全事故	P0-1：实现消费者 + 阈值可配置
逾期随访无催办	患者失访，影响医疗质量指标	P0-4：实现通知 + 幂等保护
过敏史无变更记录	无法追溯过敏史变更，用药风险	P1-13：添加变更历史
告警阈值硬编码	无法适应儿科/老年科/血透科不同范围	P0-2：数据库配置

6.3 合规风险

风险	法规依据	缓解措施
知情同意缺失	PIPL 第 29 条	P0-5：实现同意记录机制
审计不完整	医疗机构信息化建设要求	P0-6：补全审计日志
PIE 加密范围不足	PIPL 第 51 条	P1：扩展加密到姓名/过敏史/诊断
数据删除权缺失	PIPL 第 47 条	P2：实现患者数据导出/删除

6.4 架构风险

风险	影响	缓解措施
EventBus 无重放	服务重启丢事件	P0-7：增强持久化
全量订阅	性能隐患，所有事件经消息模块	P1-11：改用过滤订阅
路由手动合并	新模块 boilerplate 成本	长期：ErpModule trait v2
erp-health 过大	18+ 实体，维护复杂度上升	P2-18：按子域重组

---

7. 附录

7.1 关键文件索引

文件	说明
crates/erp-core/src/module.rs	ErpModule trait + ModuleRegistry (拓扑排序)
crates/erp-core/src/events.rs	EventBus 实现 (broadcast + outbox)
crates/erp-core/src/types.rs	TenantContext, BaseFields, Pagination
crates/erp-core/src/rbac.rs	权限/角色检查
crates/erp-server/src/main.rs	服务组装和手动路由合并
crates/erp-server/src/state.rs	AppState + FromRef 桥接
crates/erp-server/src/outbox.rs	Outbox relay (5s 轮询, 3 次重试)
crates/erp-auth/src/middleware/jwt_auth.rs	JWT 认证 + TenantContext 注入
crates/erp-health/src/module.rs	HealthModule (ErpModule 实现 + 后台任务)
crates/erp-health/src/event.rs	健康模块事件订阅
crates/erp-health/src/crypto.rs	AES-256-GCM 加密
crates/erp-health/src/service/masking.rs	PII 脱敏管道
crates/erp-plugin/src/engine.rs	WASM 插件引擎
docs/superpowers/specs/2026-04-13-wasm-plugin-system-design.md	插件系统设计规格
docs/superpowers/specs/2026-04-23-health-management-module-design.md	健康模块设计规格
docs/discussions/2026-04-18-plugin-platform-brainstorm.md	插件平台演进讨论

7.2 迁移历史时间线

日期	迁移范围	说明
4/10-11	核心平台	租户、用户、凭证、角色、权限、组织、部门、岗位
4/12	配置 + 工作流	字典、菜单、设置、编号规则 + 流程定义/实例/令牌/任务
4/13	消息 + 审计	模板、消息、订阅 + 审计日志
4/14	修复	唯一索引与软删除冲突、标准字段补全
4/16	领域事件	domain_events 表
4/17	插件系统	插件表、动态表
4/18	搜索 + 权限	pg_trgm、实体注册表、数据范围
4/19	关联修复	用户部门、CRM 修复、插件市场
4/23	健康表	患者、微信用户、文章
4/24	索引修复	3 个 fixup 迁移
4/25	健康扩展	患者ID哈希、医生名、透析/化验增强、AI 表、积分
4/26	业务改进	诊断、列重命名、daily_monitoring 合并、菜单种子

总计：59 个迁移，17 天内。 fixup 迁移模式健康（不编辑旧迁移，单独修复）。

7.3 项目统计快照 (2026-04-26)

指标	值
Rust crate 数	16
Rust 代码行	~57,000
前端文件数	174 (TSX/TS)
前端页面	62
小程序页面	27
数据库迁移	59
数据库表	30 基础 + 18 健康 + 3 AI
后端测试	36
前端单元测试	3
Git 提交	237
开发周期	17 天

---

本文档由三专家多视角评审生成，作为 HMS 平台基座演进的参考基准。后续实施计划将基于本文档的优先级排序展开。