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+ 权限码等）
This commit is contained in:
iven
273
docs/discussions/2026-05-11-expert-brainstorm-session.md
Normal file
273
docs/discussions/2026-05-11-expert-brainstorm-session.md
Normal file
@@ -0,0 +1,273 @@
|
||||
# HMS 多专家组头脑风暴 — 六维度全面均衡评审
|
||||
|
||||
> 日期: 2026-05-11 | 数据截止: commit c716cc0 (feat/media-library-banner) | 参与者: 架构/后端/前端/安全/运维/产品 六位虚拟专家
|
||||
> 关联: [六维度全面均衡分析报告](../superpowers/specs/2026-05-11-system-comprehensive-analysis-design.md)
|
||||
> 上次会议: [2026-05-07 五专家组评审](2026-05-07-expert-brainstorm-session.md)（综合 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
Block a user