iven/hms
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b3f53cd43773bf74b8286ee2cd504e7606d79d12
hms/docs/discussions/2026-05-11-expert-brainstorm-session.md
iven 9487ccb62e 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

14 KiB
Raw Blame History

HMS 多专家组头脑风暴 — 六维度全面均衡评审

日期: 2026-05-11 | 数据截止: commit c716cc0 (feat/media-library-banner) | 参与者: 架构/后端/前端/安全/运维/产品 六位虚拟专家 关联: 六维度全面均衡分析报告 上次会议: 2026-05-07 五专家组评审（综合 6.4/10 B-）

背景

基于六维度全面均衡分析（架构合理性 + 代码质量 + 业务完整度 + 安全合规 + 生产就绪度 + 可扩展性），召集六位虚拟专家从不同视角对 HMS 系统进行独立评审。与上次（2026-05-07）相比，系统完成了媒体库+轮播图管理上线、文章编辑器重设计、Design Token 全面推广、Clippy 清零、生产 unwrap 从 514 降至 24 等重要工作。

Phase A: 现状报告（数据驱动）

综合评分矩阵

维度 分析评分 专家共识 趋势
架构合理性 7.5 7.2 →
代码质量 7.0 6.5 ↑
业务完整度 7.5 7.0 ↑
安全合规 7.5 7.5 ↑
生产就绪度 5.5 6.5 →
可扩展性 6.5 — →
综合 6.9 7.0 ↑ +0.6

Phase B: 专家独立评估

专家 A：首席架构师

评分：7.2 / 10（B+）

Top 3 优势：

  1. 严格的模块隔离 — 星型依赖图实现真正可拆分架构 — 所有 7 个业务模块只依赖 erp-core，没有任何模块间直接依赖。任何一个模块可以独立抽出为微服务而不需要修改其他模块代码。ErpModule trait 定义了完整的模块生命周期钩子。

  2. 事件系统具备生产级可靠性 — Outbox + 幂等 + Dead-Letter 三重保障 — 两阶段提交（持久化 pending → 广播 → published）配合 PostgreSQL NOTIFY 和 outbox relay。消费端有幂等检查和失败兜底。23 个消费者覆盖关键跨模块场景。

  3. 领域模型覆盖面广且一致性高 — 57 实体 / 31 handler / 36 service，所有实体遵循统一标准字段规范（id/tenant_id/created_at/updated_at/deleted_at/version），所有 API 遵循 /api/v1/ 和 ApiResponse 统一包装。

Top 3 风险：

  1. event.rs 2871 行是架构腐化的定时炸弹 — 31 事件 + 23 消费者 + 测试集中在单文件，任何消费者修改都需重编译整个文件，多人协作时几乎必然产生合并冲突。module.rs（1595 行）同理。

  2. 前端测试覆盖率严重不足 — 297 个 TS/TSX 文件仅 62 个测试文件，测试代码与业务代码比例 1:7.4。AdminDashboard（730 行）等核心页面完全没有测试。

  3. 6 个冻结模块是"半活半死"的隐性技术债 — 有前后端实现但被冻结，路由仍注册、实体仍编译、表仍存在。既不能安全删除，也不能放心使用。

"如果只能做一件事"： 拆分 event.rs 为独立的事件消费者子模块。收益最高：降低编译时间、消除合并冲突热点、为冻结模块清理扫清道路。

专家 B：后端工程负责人

评分：6.5 / 10（B-）

Top 3 优势：

  1. 工程纪律严格 — Clippy 全 workspace 0 警告，unwrap 从 514 降至 24，统一 AppError 错误处理，999 个测试函数提供扎实回归保护。

  2. PII 加密方案完整 — AES-256-GCM + HMAC-SHA256 + DEK 轮换，覆盖咨询内容/诊断/执业证/随访/手机号等敏感字段，KEK/DEK 分层密钥管理。

  3. 无 N+1 查询，数据访问层性能基础良好 — SeaORM 的 Entity + Model + Relation 模式配合 tenant_id 过滤，31+ 事件 Outbox + LISTEN/NOTIFY。

Top 3 风险：

  1. event.rs 2871 行 — 模块内聚性严重退化 — 每次事件定义变更触发 erp-health 全量重编译，合并冲突概率极高，违反 800 行上限规范。data_service.rs（1907 行）、manifest.rs（1809 行）同理。

  2. erp-health OpenAPI 注解覆盖率 3%（1/32 handler）— API 文档几乎不可用 — 260+ 后端路由绝大部分在 Swagger UI 上不可见，文档缺失 = 接口契约不存在。

  3. 异步测试比例偏低（184/999 = 18.4%） — 数据库操作、事件总线、并发预约 CAS 等核心路径需异步测试才能覆盖真实竞态条件。

"如果只能做一件事"： 拆分 event.rs 为按领域分组的小文件。这是编译性能瓶颈、协作摩擦点和架构退化的最先征兆。

专家 C：前端/UX 工程负责人

评分：7.2 / 10（B+）

Top 3 优势：

  1. API 层零绕过 + 零 console.log — 297 个文件没有任何直接 fetch 调用，全通过 52 个 API 模块文件封装。鉴权逻辑单点可控。

  2. Design Token 体系统一且覆盖完整 — 68 个 SCSS 文件全部接入 10 级字号 + 4 结构 token，关怀模式/长者模式 58/58 页面 100% 覆盖。

  3. 文件粒度控制到位 — 最大文件 730 行，远低于 800 行红线。6 个 Zustand store 分散管理，52 个 API 模块独立封装。

Top 3 风险：

  1. 小程序 124 文件零测试覆盖 — 质量保障真空 — 66 页面 / 29 service 文件完全无测试，回归验证全靠人工。

  2. TypeScript any 类型 67 处 — 类型安全网有系统性漏洞 — 医疗数据的类型安全是业务正确性最后防线，any 导致编译期无法捕获字段拼写错误。

  3. 高频 .map() 渲染页面缺少 memoization — PluginDashboard（12 次）、DashboardWidgets（11 次）等仪表盘组件数据频繁更新。

"如果只能做一件事"： 给小程序补测试。先覆盖 29 个 service 文件的接口契约测试 — 投入产出比最高。

专家 D：安全与合规官

评分：7.5 / 10（B+）

Top 3 优势：

  1. PII 加密 KEK/DEK 分层架构成熟度高 — 生产构建强制要求 KEK 环境变量，密钥材料 Drop 时清零，HMAC-SHA256 独立子密钥用于可搜索加密。

  2. 多租户隔离三层防线 — JWT 中间件 → SeaORM 过滤 → PostgreSQL RLS，RLS SET 使用参数绑定不存在注入风险。

  3. FHIR 越权修复 + 审计日志哈希链 — enforce_patient_scope 系统性修复，SHA-256 哈希链防篡改。

Top 3 风险：

  1. OAuth Token 端点缺少客户端级限流 — 凭据暴力破解向量 — Redis 不可达时 fail_close 默认 false 直接放行。OAuth client_secret 可被分布式暴力破解。

  2. 审计日志 fire-and-forget 写入 — 违反医疗合规不可抵赖性 — 写入失败仅 warn 不重试不阻断，哈希链断裂无检测。

  3. BLE 网关认证无速率限制和 API Key 轮换 — 一旦泄露攻击窗口永久，无法自动过期。

"如果只能做一件事"： 将 rate_limit.fail_close 默认改为 true，并为 OAuth Token 端点增加独立的客户端级速率限制。

专家 E：DevOps/SRE 负责人

评分：6.5 / 10（B-）

Top 3 优势：

  1. 安全设计层层设防 — 默认密钥拒绝启动、release 模式拒绝 CORS 通配符、Redis 驱动登录锁定、审计哈希链。

  2. 可观测性基础设施已落地 — Prometheus 指标导出（HTTP 请求/延迟直方图）、独立 9090 端口 metrics、连接池采样、健康检查分层设计。

  3. 事件驱动架构具备清晰微服务拆分路径 — broadcast → Kafka/NATS 平滑迁移，outbox relay → Debezium，应用层零修改。

Top 3 风险：

  1. 文件存储是单点故障 — 医疗数据合规红线 — 本地 uploads 目录无异地备份、无对象存储、无版本控制。磁盘损坏 = 患者数据不可恢复。

  2. 单 PostgreSQL 实例无读写分离 — 性能和可用性单点 — 连接池 max 20、无读副本、无 PgBouncer、无自动故障转移。

  3. 后台任务缺乏监控和死锁保护 — 静默失败风险 — 定时任务执行状态无指标暴露，失败仅 warn 无告警。

"如果只能做一件事"： 立即建立 PostgreSQL 自动备份 + 上传文件定期同步到对象存储。数据丢失是医疗平台唯一不可逆、不可辩护的事故。

专家 F：产品经理

评分：7.0 / 10（B）

Top 3 优势：

  1. 医疗业务覆盖完整度在同类产品中领先 — 57 实体覆盖患者全生命周期 12 个业务子域，5 角色定制化工作台，形成完整的健康管理和运营闭环。

  2. 内容运营基础设施已形成可闭环能力 — 媒体库 + 轮播图 + 文章编辑器三位一体，配合小程序访客首页动态化，运营人员无需开发介入即可完成完整内容发布流程。

  3. 多终端一致性与无障碍设计超出预期 — 4 套主题、Design Token 全面接入、关怀/长者模式 100% 覆盖，说明团队把无障碍内嵌到设计系统中。

Top 3 风险：

  1. 6 个冻结模块构成"功能幻觉"，损害客户信任 — 用户能看到但无法使用。透析管理尤其关键（产品定位"血透中心首发"但透析被冻结）。

  2. AI 分析是核心差异化卖点，但用户触达路径断裂 — 后端 4 个 SSE 端点已实现，前端有列表页，但缺少"触发分析"操作入口。

  3. 接近完成但缺少可部署方案 — 85% 功能完成度但无法进入商业化验证阶段，所有功能完善都是"在实验室里打磨"。

"如果只能做一件事"： 补全 AI 分析触发入口 + 生成生产级 Docker 镜像，让核心差异化功能可以被客户实际体验。

Phase C: 交叉讨论

共识点

  1. event.rs 拆分是第一优先 — 架构师和后端负责人同时将其列为"如果只能做一件事"，说明跨角色认同度高
  2. 数据保护是生产前提 — DevOps 和安全专家同时强调文件存储和数据库备份的紧迫性
  3. 冻结模块需要一次性决策 — 要么解冻要么删除，不允许"半活半死"状态持续
  4. 小程序测试空白是共识风险 — 前端负责人和架构师都标记了这个问题

分歧点

  1. OpenAPI 注解 vs 性能基准 — 后端负责人优先补文档，DevOps 优先建基准。折中：先做注解（成本低收益大），第二个月建基准
  2. 冻结模块策略 — 产品经理建议解冻透析+排班（业务价值），架构师建议删除或完整实现。折中：解冻高价值模块（透析、排班），其余添加"即将推出"提示
  3. fail_close 默认值 — 安全专家建议改为 true，DevOps 提醒 Redis 不可达会导致服务完全不可用。折中：先为 OAuth 和 BLE 端点单独添加限流层，月 2 再全局改 fail_close

资源冲突

  • 后端资源有限：event.rs 拆分和 OpenAPI 注解需要同一批开发者。优先拆分（消除瓶颈），然后批量补注解
  • 小程序测试需要前端资源：与功能开发竞争。建议测试框架搭建后由 CI 自动化提醒覆盖率变化

Phase D: 行动清单

P0 — 阻塞性（必须 2 周内完成）

# 行动 负责人 工时 验收标准
1 拆分 event.rs 为 6-8 个领域文件 架构师+后端 2-3 天 零文件 >800 行
2 fail_close 改 true + OAuth/BLE 独立限流 安全+DevOps 1 天 OAuth token 端点有客户端级限流
3 PostgreSQL 自动备份 + 文件异地同步 DevOps 2 天 pg_dump 每日全量 + WAL 增量

P1 — 高优先级（Month 1 内完成）

# 行动 负责人 工时 验收标准
4 拆分 module.rs 为路由子模块 架构师 1-2 天 零文件 >800 行
5 erp-health handler OpenAPI 注解补全 后端 5-7 天 80%+ handler 有注解
6 小程序 service 层测试框架搭建 前端 2-3 天 29 个 service 有基础测试
7 AI 分析触发入口补全 产品+前端 2 天 患者详情/化验报告页可发起分析
8 解冻透析管理和排班模块 产品+架构 1 天 + 验证 路由解冻，E2E 验证通过

P2 — 中优先级（Month 2 内完成）

# 行动 负责人 工时 验收标准
9 性能基准测试建立 DevOps 3 天 核心 API p50/p95/p99 基线
10 Grafana 监控仪表盘 DevOps 3 天 HTTP/DB/EventBus 指标可视化
11 TypeScript any 清零 前端 3-5 天 Web any 降至个位数
12 审计日志写入可靠性（重试+哈希链验证） 安全+后端 2 天 写入失败有重试，每日自动验证链完整性
13 前端核心页面测试补全 前端 5-7 天 5 个核心页面有测试

P3 — 持续改进（Month 3）

# 行动 负责人 工时 验收标准
14 媒体存储抽象（本地/S3 切换） 架构+DevOps 3-5 天 Storage trait + S3 实现
15 数据库读写分离准备 DevOps 5 天 PgBouncer + 读副本配置
16 异步测试比例提升至 35% 后端 5 天 关键并发路径有异步测试
17 BLE API Key 轮换机制 安全 2 天 Key 有 TTL 和自动过期
18 前端性能优化（memoization + bundle） 前端 5 天 LCP < 2s

综合评分汇总

专家 角色 评分 "如果只能做一件事"
A 首席架构师 7.2 拆分 event.rs
B 后端工程负责人 6.5 拆分 event.rs
C 前端/UX 工程负责人 7.2 小程序补测试
D 安全与合规官 7.5 fail_close 改 true + OAuth 限流
E DevOps/SRE 负责人 6.5 PostgreSQL 备份 + 文件异地同步
F 产品经理 7.0 AI 触发入口 + 生产 Docker 镜像
综合 7.0/10 (B) 较上次 6.4/10 (B-) 提升 +0.6

三个月路线图

Month 1 — 质量加固 + 安全加固（提升到 7.5+）

结构治理： event.rs 拆分 → module.rs 拆分 → OpenAPI 注解补全 安全加固： fail_close + OAuth/BLE 限流 + 审计日志可靠性 数据保护： PostgreSQL 备份 + 文件异地同步 测试补全： 小程序 service 层测试框架

Month 2 — 功能补全 + 可观测性（提升到 8.0+）

功能： 解冻透析+排班 → AI 触发入口 → 剩余冻结模块处理 可观测性： 性能基准 → Grafana 仪表盘 → 后台任务监控 质量： TypeScript any 清零 → 前端核心页面测试

Month 3 — 生产化 + 扩展性（提升到 8.5+）

存储： 媒体存储抽象 → S3/OSS 支持 数据库： PgBouncer + 读写分离准备 安全： BLE Key 轮换 → 安全态势可视化 性能： 前端 bundle 优化 → memoization → LCP 基线

Reference in New Issue View Git Blame Copy Permalink