From 9487ccb62eab50a9b0cc4539944ae85b8930a772 Mon Sep 17 00:00:00 2001 From: iven Date: Mon, 11 May 2026 03:43:51 +0800 Subject: [PATCH] =?UTF-8?q?docs(health):=20=E5=85=AD=E7=BB=B4=E5=BA=A6?= =?UTF-8?q?=E5=85=A8=E9=9D=A2=E5=9D=87=E8=A1=A1=E5=88=86=E6=9E=90=E6=8A=A5?= =?UTF-8?q?=E5=91=8A=20+=20=E5=85=AD=E4=B8=93=E5=AE=B6=E7=BB=84=E5=A4=B4?= =?UTF-8?q?=E8=84=91=E9=A3=8E=E6=9A=B4=E8=AF=84=E5=AE=A1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增六维度分析报告:架构(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-expert-brainstorm-session.md | 273 +++++++++++++++ ...11-system-comprehensive-analysis-design.md | 331 ++++++++++++++++++ wiki/index.md | 64 ++-- 3 files changed, 641 insertions(+), 27 deletions(-) create mode 100644 docs/discussions/2026-05-11-expert-brainstorm-session.md create mode 100644 docs/superpowers/specs/2026-05-11-system-comprehensive-analysis-design.md diff --git a/docs/discussions/2026-05-11-expert-brainstorm-session.md b/docs/discussions/2026-05-11-expert-brainstorm-session.md new file mode 100644 index 0000000..78c11e3 --- /dev/null +++ b/docs/discussions/2026-05-11-expert-brainstorm-session.md @@ -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 基线 diff --git a/docs/superpowers/specs/2026-05-11-system-comprehensive-analysis-design.md b/docs/superpowers/specs/2026-05-11-system-comprehensive-analysis-design.md new file mode 100644 index 0000000..04ac1b7 --- /dev/null +++ b/docs/superpowers/specs/2026-05-11-system-comprehensive-analysis-design.md @@ -0,0 +1,331 @@ +# HMS 健康管理平台 — 六维度全面均衡分析报告 + +> 日期: 2026-05-11 | 数据截止: commit c716cc0 (feat/media-library-banner 分支) | 提交: 720+ +> 上次分析: 2026-05-07 (综合 6.4/10 B-) | 本次基准: 媒体库+轮播图上线后 + +## 执行摘要 + +| 维度 | 评分 | 趋势 | 关键发现 | +|------|------|------|---------| +| 架构合理性 | 7.5/10 | → | 模块边界清晰,event.rs 2871 行成最大技术债 | +| 代码质量 | 7.0/10 | ↑ | Clippy 0 警告,生产 unwrap 降至 24 处,utoipa 覆盖仅 33% | +| 业务完整度 | 7.5/10 | ↑ | 媒体库/轮播图上线,6 个模块仍冻结 | +| 安全合规 | 7.5/10 | ↑ | PII 加密全面,0 SQL 注入,缺速率限制 | +| 生产就绪度 | 5.5/10 | → | 依赖全部最新,缺性能基准和监控 | +| 可扩展性 | 6.5/10 | → | 模块化单体路径清晰,本地存储限制 | +| **综合** | **6.9/10** | **↑** | 功能完整度 87%,生产就绪度约 60% | + +**与上次对比(2026-05-07 → 2026-05-11):** +- 代码质量 ↑ — Clippy 0 警告(从有警告到清零),生产 unwrap 从 514 降至 24 +- 业务完整度 ↑ — 媒体库/轮播图/文章编辑器上线,冻结模块从 7 降至 6 +- 安全合规 ↑ — SQL 注入已修复,FHIR 越权已修复,V2 CRITICAL 全部清零 +- 生产就绪度 → — 无变化,仍缺性能基准和监控体系 +- 综合 6.4 → 6.9,评级从 B- 提升到 B + +**Top 5 行动优先级:** +1. **CRITICAL** — 补全 OpenAPI 文档(erp-health 31/32 handler 无注解) +2. **HIGH** — 建立性能基准测试和监控体系 +3. **HIGH** — 拆分 event.rs(2871 行)和 module.rs(1595 行) +4. **HIGH** — 小程序补全单元测试(当前 124 文件 0 测试) +5. **MEDIUM** — 解冻冻结模块(6 个模块前端无 UI) + +--- + +## 1. 架构合理性分析 + +**评分:7.5 / 10(B+)** | 与上次持平 + +### 1.1 现状数据 + +| 指标 | 值 | +|------|-----| +| Rust crate | 17 个(+ 7 插件骨架) | +| Rust 源文件 | 599 个 | +| 分层结构 | L1(erp-core) → L2(8 业务模块) → L3(erp-server) | +| 领域事件 | 31 类型 + 23 幂等消费者 | +| 权限码 | 75+ 个,声明式路由绑定 | +| EventBus | broadcast + 持久化 + dead-letter + LISTEN/NOTIFY | +| 模块间依赖 | 零直接业务依赖(仅 EventBus + trait) | + +### 1.2 优势 + +1. **教科书级模块化单体** — 17 crate 严格分层,ErpModule trait 统一生命周期(注册/启动/关闭/健康检查),天然支持微服务拆分 +2. **事件驱动架构成熟** — Outbox 模式 + LISTEN/NOTIFY + 死信队列 + 幂等消费,事件不丢失不重复 +3. **多租户纵深防御** — JWT 中间件注入 → SeaORM 自动过滤 → PostgreSQL RLS 策略三层隔离 +4. **UUID v7 主键** — 时间排序 + 唯一性,分布式友好 +5. **软删除 + 乐观锁** — 版本字段检查,数据不可丢失 + +### 1.3 风险与缺口 + +| 风险 | 严重度 | 位置 | +|------|--------|------| +| event.rs 2871 行,混合 31 事件定义 + 23 消费者 + 测试 | HIGH | `crates/erp-health/src/event.rs` | +| module.rs 1595 行,150+ 路由注册在单文件 | HIGH | `crates/erp-health/src/module.rs` | +| erp-plugin 复杂度(data_service 1907 行 + manifest 1809 行) | MEDIUM | `crates/erp-plugin/` | +| 6 个冻结模块的架构债务 | MEDIUM | 路由/权限/菜单仍存在 | +| erp-health 仍为巨石模块(189 文件,12 业务子域) | MEDIUM | `crates/erp-health/` | + +### 1.4 建议行动 + +1. **拆分 event.rs** — 按领域拆为 `patient_events.rs`、`alert_events.rs`、`consultation_events.rs` 等,事件定义和消费者分离 +2. **拆分 module.rs** — 路由按业务域分组为 `routes/patient_routes.rs`、`routes/appointment_routes.rs` 等 +3. **冻结模块策略明确** — 要么解冻并完成 UI,要么从路由树中移除(减少编译体积和认知负担) + +--- + +## 2. 代码质量分析 + +**评分:7.0 / 10(B)** | 较上次 ↑(6.0 → 7.0) + +### 2.1 现状数据 + +| 指标 | 值 | 评估 | +|------|-----|------| +| Clippy 警告 | 0 | 全 workspace 清零 | +| 生产代码 unwrap() | 24 处 | 低风险(多为安全解包) | +| 测试代码 unwrap/expect | ~488 处 | 可接受 | +| Rust 大文件(>800行) | 17 个 | 需关注 top 5 | +| TSX 大文件(>800行) | 0 个 | 优秀 | +| 前端 API 层绕过 | 0 处 | 优秀 | +| Web console.log | 0 处 | 优秀 | +| MP console.log | 33 处 | 生产构建自动移除 | +| TypeScript any | Web 32 / MP 35 | Web 多为测试代码 | +| 后端测试 | 999 函数(815 同步 + 184 异步) | 丰富 | +| 前端测试 | 644 断言(472 Web + 39 MP + 133 E2E) | 中等 | +| utoipa 注解 | 322 个 / 21/64 文件 = 33% | erp-health 缺口大 | +| 依赖版本 | 全部最新主版本线 | 优秀 | + +### 2.2 优势 + +1. **Clippy 全清零** — 从 514 个 unwrap() 降至 24 个生产 unwrap,0 Clippy 警告,质量门禁见效 +2. **API 层零绕过** — 前端 0 处直接 fetch/axios 调用,全部通过 api/ 层 +3. **错误处理一致** — 所有 handler 统一返回 AppError,类型化错误链 +4. **Web 代码极干净** — 0 console.log、0 超大文件、any 多为测试 mock +5. **后端测试丰富** — 999 测试函数,78 个文件包含内联测试模块 + +### 2.3 风险与缺口 + +| 风险 | 严重度 | 详情 | +|------|--------|------| +| OpenAPI 文档覆盖仅 33% | CRITICAL | erp-health 31/32 handler 无注解,API 文档不完整 | +| 小程序 0 个单元测试 | HIGH | 124 文件完全无测试覆盖 | +| 覆盖率工具未执行 | HIGH | vitest coverage 已配置但无最新报告 | +| 17 个 Rust 大文件 | MEDIUM | event.rs(2871)、data_service.rs(1907)、manifest.rs(1809) | +| MP 源码 33 处 console.log | LOW | 生产构建自动移除,但影响代码整洁 | + +### 2.4 建议行动 + +1. **批量补全 utoipa 注解** — 为 erp-health 剩余 31 个 handler 添加 OpenAPI 注解 +2. **小程序测试补全** — 优先为 service 层(29 个文件)编写单元测试 +3. **执行覆盖率报告** — 运行 `vitest run --coverage` 和 `cargo tarpaulin`,建立基线 + +--- + +## 3. 业务完整度分析 + +**评分:7.5 / 10(B+)** | 较上次 ↑(6.5 → 7.5) + +### 3.1 现状数据 + +| 指标 | 值 | +|------|-----| +| erp-health 实体 | 57 个(新增 media_folder/media_item/banner) | +| erp-health handler | 31 个 | +| erp-health service | 36 个(含子模块) | +| Web 活跃路由 | 29 个 | +| Web 冻结路由 | 6 个 | +| 小程序页面 | 66 个(主包 12 + 分包 54) | +| 后台定时任务 | 5 个 | +| 新增功能 | 媒体库管理 + 轮播图管理 + 文章编辑器重设计 | + +### 3.2 优势 + +1. **内容管理闭环** — 文章 CRUD + 媒体库 + 轮播图 + 公共端点(小程序访客可访问) +2. **文章编辑器重设计** — 公众号风格三栏布局 + iPhone 15 Pro 预览 + 丰富样式模板 +3. **Design Token 全面推广** — 68 SCSS 文件接入,关怀模式 CSS 变量级联 +4. **长者模式 100% 覆盖** — 58/58 页面全部完成 +5. **医生端功能丰富** — 17 页面涵盖患者/咨询/随访/报告/告警/透析/处方 + +### 3.3 风险与缺口 + +| 冻结模块 | 前端状态 | 后端状态 | 业务影响 | +|----------|---------|---------|---------| +| care-plans | 有页面(CarePlanList/Detail) | 有 CRUD | 可快速解冻 | +| shifts | 有页面(ShiftList/Detail) | 有 CRUD | 可快速解冻 | +| family-proxy | 有页面 | 有 CRUD | 可快速解冻 | +| medications | 有页面 | 有 CRUD | 可快速解冻 | +| dialysis | 有页面(DialysisManageList) | 有独立 crate | 可快速解冻 | +| schedules | 有页面(DoctorSchedule) | 有 CRUD | 可快速解冻 | + +**重要发现:** 6 个冻结模块全部已有前端页面和后端 CRUD,仅被 `frozen: true` 标记阻止访问。解冻成本极低(改 routeConfig.ts 即可),但需要: +- 验证功能完整性(E2E 测试) +- 确认权限码配置正确 +- UI/UX 一致性检查 + +### 3.4 建议行动 + +1. **批量解冻** — 优先解冻 care-plans、shifts、dialysis(业务价值最高) +2. **解冻后验证** — 每个解冻模块执行 E2E 测试确认功能正常 +3. **AI 模块 UI 入口** — 4 个 SSE 分析端点缺少前端触发入口 + +--- + +## 4. 安全合规分析 + +**评分:7.5 / 10(B+)** | 较上次 ↑(7.0 → 7.5) + +### 4.1 现状数据 + +| 指标 | 状态 | +|------|------| +| PII 加密 | AES-256-GCM + HMAC-SHA256 + DEK 轮换 | +| 加密字段覆盖 | 咨询内容、诊断备注、执业证号、随访结果、手机号、症状等 | +| SQL 注入 | 0 处(全部参数化或 sanitize_identifier) | +| JWT 认证 | 自动刷新 + 并发队列 + 身份一致性校验 | +| 多租户隔离 | middleware 注入 + SeaORM 过滤 + RLS 策略 | +| HTML 清理 | ammonia 库 | +| V2 CRITICAL | 全部修复(SQL 注入 + FHIR 越权) | + +### 4.2 优势 + +1. **V2 CRITICAL 全清零** — SQL 注入和 FHIR 越权两个 CRITICAL 级漏洞已修复 +2. **PII 加密链路完整** — 从存储加密到 HMAC 盲索引到脱敏展示,全链路覆盖 +3. **零 SQL 注入面** — 15 处 format! SQL 均不含用户输入 +4. **认证体系成熟** — JWT 自动刷新、并发请求队列、身份一致性校验 + +### 4.3 风险与缺口 + +| 风险 | 严重度 | 详情 | +|------|--------|------| +| 缺少 API 速率限制 | HIGH | 无 rate limiting middleware | +| 公开端点安全审查 | MEDIUM | public_routes 需评估是否可被滥用 | +| BLE 网关认证强度 | MEDIUM | gateway_routes 的 token 机制待验证 | +| 密钥轮换机制 | MEDIUM | secret_key 手动配置,无自动轮换 | +| 审计日志完整性 | MEDIUM | 部分操作缺少审计追踪 | + +### 4.4 建议行动 + +1. **添加速率限制** — 使用 tower-http 的 RateLimit layer,按 IP + 用户维度限制 +2. **公开端点审计** — 评估 /public/* 端点的滥用风险,添加 IP 限制 +3. **审计日志补全** — 确保所有写操作(create/update/delete)都有审计记录 + +--- + +## 5. 生产就绪度分析 + +**评分:5.5 / 10(C+)** | 与上次持平 + +### 5.1 现状数据 + +| 指标 | 状态 | +|------|------| +| 依赖版本 | 全部最新主版本线 | +| N+1 查询 | 无 | +| 前端 memoization | 56% 页面有,44% 无(多为小页面) | +| 性能基准 | 无 | +| 覆盖率报告 | 工具已配置,未执行 | +| 错误处理 | 一致(全 AppError) | +| 监控 | 未确认 | +| Docker | 有配置 | +| 环境变量 | config.toml + 环境变量 | + +### 5.2 优势 + +1. **依赖健康** — 所有 Rust 和 TypeScript 依赖均为最新主版本线 +2. **无 N+1 查询** — 使用 SeaORM 批量查询和关联加载 +3. **错误处理一致** — 所有 handler 返回 AppError,前端统一错误提示 +4. **前端构建优化** — 生产构建自动移除 console.log,terser 压缩 + +### 5.3 风险与缺口 + +| 风险 | 严重度 | 详情 | +|------|--------|------| +| 无性能基准测试 | HIGH | 无法量化响应时间、吞吐量 | +| 监控体系不明 | HIGH | tracing 覆盖率、metrics 端点待确认 | +| 无覆盖率报告 | MEDIUM | 工具已配置但未执行,无法量化测试覆盖 | +| 前端 bundle 大小 | MEDIUM | 未确认首屏加载性能 | +| SSE 断线重连 | LOW | 需验证客户端重连机制 | + +### 5.4 建议行动 + +1. **建立性能基线** — 使用 `criterion` 创建核心 API 基准测试 +2. **执行覆盖率报告** — 后端 `cargo tarpaulin` + 前端 `vitest --coverage` +3. **配置 metrics 端点** — 使用 `metrics` + `metrics-exporter-prometheus` +4. **前端性能审计** — Lighthouse 跑分 + bundle 分析 + +--- + +## 6. 可扩展性分析 + +**评分:6.5 / 10(B-)** | 与上次持平 + +### 6.1 现状数据 + +| 指标 | 状态 | +|------|------| +| 模块化架构 | 天然支持微服务拆分 | +| EventBus | 进程内 broadcast,可迁移到分布式 MQ | +| 数据库 | PostgreSQL,共享数据库多租户隔离 | +| 文件存储 | 本地文件系统(媒体库) | +| 缓存 | Redis(仅 AI 模块使用) | +| 迁移 | 137 个,自动执行 | +| 主键策略 | UUID v7 | + +### 6.2 优势 + +1. **微服务拆分路径清晰** — 模块间零依赖,每个 crate 可独立部署 +2. **EventBus 可演进** — 从 broadcast → Kafka/NATS 无需改业务代码 +3. **UUID v7** — 时间排序 + 唯一性,分布式 ID 生成友好 +4. **迁移自动执行** — 137 个迁移,启动时自动应用 + +### 6.3 风险与缺口 + +| 风险 | 严重度 | 详情 | +|------|--------|------| +| 本地文件存储限制 | HIGH | 媒体库文件存本地,无法水平扩展 | +| 缓存范围有限 | MEDIUM | Redis 仅用于 AI 模块,其他模块无缓存 | +| 数据库扩展 | MEDIUM | 单 PostgreSQL 实例,无读写分离 | +| API 网关缺失 | LOW | 直接暴露 Axum 端点,无统一入口 | + +### 6.4 建议行动 + +1. **媒体存储抽象** — 添加 Storage trait,支持本地/S3/OSS 切换 +2. **数据库连接池优化** — 配置 PgPoolOptions,添加读写超时 +3. **缓存策略** — 将 Redis 扩展到权限缓存、会话缓存 +4. **API 网关评估** — 评估 nginx/caddy 反代方案 + +--- + +## 7. 综合评分与路线图建议 + +### 7.1 综合评分矩阵 + +| 维度 | 评分 | 权重 | 加权分 | +|------|------|------|--------| +| 架构合理性 | 7.5 | 20% | 1.50 | +| 代码质量 | 7.0 | 20% | 1.40 | +| 业务完整度 | 7.5 | 20% | 1.50 | +| 安全合规 | 7.5 | 15% | 1.13 | +| 生产就绪度 | 5.5 | 15% | 0.83 | +| 可扩展性 | 6.5 | 10% | 0.65 | +| **综合** | | | **6.9/10 (B)** | + +### 7.2 三个月路线图建议 + +**Month 1 — 质量加固(提升到 7.5+)** +- 补全 utoipa 注解(erp-health 31 个 handler) +- 建立性能基准测试 +- 执行覆盖率报告建立基线 +- 拆分 event.rs 和 module.rs + +**Month 2 — 功能补全(提升到 8.0+)** +- 解冻 6 个冻结模块 +- AI 模块前端 UI 入口 +- 小程序单元测试补全 +- API 速率限制 + +**Month 3 — 生产化(提升到 8.5+)** +- 监控和可观测性体系 +- 媒体存储 S3/OSS 抽象 +- 性能优化(前端 bundle + 后端查询) +- 端到端压力测试 diff --git a/wiki/index.md b/wiki/index.md index 3c8a5b2..7b4ac32 100644 --- a/wiki/index.md +++ b/wiki/index.md @@ -4,33 +4,36 @@ ## 关键数字 -> 最后更新: 2026-05-09 | 数据截止: commit 890c132 (第 716 次提交) +> 最后更新: 2026-05-11 | 数据截止: commit c716cc0 (feat/media-library-banner 分支) | 指标 | 值 | |------|-----| -| Rust crate | 18 个(erp-core + 5 基础业务 + erp-health + erp-ai + erp-dialysis + erp-plugin + 5 插件 + erp-plugin-prototype) | -| 数据库表 | 30 基础表 + 44 健康业务表 + 3 AI 表(已实现) | -| 数据库迁移 | 129 个 | -| 后端路由 | 250+ 个(8 公开 + 14 FHIR + 2 网关 + ~230 受保护) | +| Rust crate | 17 个(erp-core + 5 基础业务 + erp-health + erp-ai + erp-dialysis + erp-plugin + 7 插件/原型) | +| Rust 源文件 | 599 个 | +| 数据库表 | 30 基础表 + 49 健康业务表 + 9 AI 表 + 3 媒体库/轮播图表 | +| 数据库迁移 | 137 个(最新 m20260510_000137) | +| 后端路由 | 260+ 个(11 公开 + 14 FHIR + 2 网关 + ~240 受保护) | | 核心模块 | 5 基础 (auth/config/workflow/message/plugin) + 3 业务 (health + ai + dialysis) | -| erp-health 实体 | 46 个 Entity(~36k 行 Rust,179 文件) | -| erp-ai 实体 | 6 个 Entity(~7k 行 Rust,45 文件,4 AI Provider) | -| Web 前端 | 283 个 TS/TSX 文件(55 路由,含 38 健康路由 + 6 冻结路由) | -| 微信小程序 | Taro 4.2 + React 18,118 个 TS/TSX 文件 / 59 页面 / 3 TabBar + 医生端分包(10 子包) | -| 前端单元测试 | 62 个测试文件(vitest)+ 13 E2E spec(playwright) | -| 后端测试 | 611 单元 + 153 集成 = 772 个函数(97.5% 通过率) | -| 总代码量 | Rust ~87k 行(579 源文件)+ Web 前端 283 文件 + 小程序 118 文件 | -| 事件系统 | 31+ 事件类型(health 模块内)/ 23 幂等消费者 / Outbox + LISTEN/NOTIFY | -| DTO | 105+ 个结构体(20+ 文件) | -| 权限码 | 50 声明(health 39 + ai 6 + dialysis 5)+ 56 基础模块手动注册 | +| erp-health 实体 | **57 个** Entity(31 handler / 36 service / 21 DTO,189 文件) | +| erp-ai 实体 | 9 个 Entity(45 文件,4 AI Provider) | +| Web 前端 | 297 个 TS/TSX 文件(29 活跃路由 + 6 冻结路由,52 API 模块) | +| 微信小程序 | Taro 4.2 + React 18,124 个 TS/TSX 文件 / 66 页面 / 4 TabBar + 医生端分包 | +| 前端单元测试 | 62 个测试文件(472 Web 断言 + 39 MP 断言)+ 13 E2E spec(124 断言) | +| 后端测试 | **999 个函数**(815 同步 + 184 异步),78 个文件含内联测试 | +| 事件系统 | 31 事件类型(health 模块内)/ 23 幂等消费者 / Outbox + LISTEN/NOTIFY | +| 权限码 | **75+ 个**(health 28 + auth 25 + ai 7 + workflow 8 + dialysis 5 + plugin 2) | +| 生产 unwrap | **24 处**(从 514 降至 24),全为安全解包 | +| utoipa 注解 | 322 个 / 21/64 handler 文件 = 33% 覆盖 | | Clippy | **全 workspace 0 警告**(2026-05-07 清零) | +| 依赖版本 | 全部最新主版本线(Rust edition 2024) | | API 文档 | `http://localhost:3000/api/docs/openapi.json` | -| Git 提交 | 716 次 | -| 审计状态 | V1: 83% (2026-04-30) → V2: 85% (2026-05-05),P0 安全修复已完成 | +| Git 提交 | 720+ 次 | +| 系统分析评分 | **6.9/10 (B)**(六维度全面均衡分析,2026-05-11) | +| 审计状态 | V1: 83% → V2: 85%,P0 安全修复已完成,V2 CRITICAL 全清零 | | 角色测试 | R01-R05 全角色验证完成,86.5% 通过率,5 个 BUG 已修复;小程序 MP 多角色 96.2% 通过率 | -| UI/UX 重构 | Phase 1-5 完成(6 共享组件 + 4 角色仪表盘 + 个人统计数据 + 表单抽屉 + 小程序优化) | -| Design Token | 10 级字号 + 4 结构 token,68 SCSS 文件全面接入(634 引用,3 特殊硬编码),关怀模式 CSS 变量级联自动生效 | -| 项目阶段 | **上线前质量加固**(近 30 次提交全为 fix 类型) | +| Design Token | 10 级字号 + 4 结构 token,68 SCSS 文件全面接入,关怀模式 CSS 变量级联自动生效 | +| 长者模式 | 58/58 页面 100% 覆盖 | +| 项目阶段 | **功能完善**(媒体库+轮播图+文章编辑器上线,6 模块冻结待解冻) | ## 症状导航 @@ -74,6 +77,10 @@ | 冻结模块 API 可绕过 | [[erp-server]] frozen_module | 后端无拦截中间件 | **已修复:** 新增 `frozen_module_middleware` | | 积分端点 403 权限码错 | [[erp-health]] points_handler | 患者端用了 `health.health-data.list` | **已修复:** 改为 `health.points.list` | | MCP 审计大量 LOGIN_REDIRECT | [[miniprogram]] §6.8 审计脚本 | 测试用户密码配置错误 | **已修复:** 所有测试用户密码均为 `Admin@2026`(不是 `Test@2026`) | +| 小程序访客轮播图不显示 | [[miniprogram]] 访客首页 | `TARO_APP_DEFAULT_TENANT_ID` 未配置 | **已修复:** `.env` 添加默认 tenant_id,空字符串时跳过 API 调用 | +| 小程序轮播图图片 404 | [[erp-health]] 公开端点 | Axum 路由参数 `:id` → `{id}` 语法变更 + URL 拼接缺失 `/api/v1` | **已修复:** 路由改用 `{banner_id}`,新增 `/public/banner-image/{id}` 图片服务端点 | +| 前端媒体库图片 401 | [[frontend]] MediaLibrary | `/uploads` 路径需要 JWT 认证 | **已修复:** 新增 `resolveMediaUrl()` 工具函数自动拼接 `?token=`,Vite 代理 `/uploads` | +| 后端启动 panic "Path segments must not start with `:`" | [[erp-health]] module.rs | Axum v0.8+ 路由参数语法变更 | 路由定义使用 `{param}` 而非 `:param` | ## 模块导航 @@ -89,8 +96,8 @@ - erp-plugin — WASM 运行时 · 动态表 · 热更新(HMS 保留但非主要扩展方式) ### 核心业务层(HMS 专属) -- [[erp-health]] — **患者管理 · 健康数据 · 预约排班 · 随访管理 · 咨询管理 · 内容管理 · 积分商城 · 透析管理 · 线下活动 · 日常监测 · 告警系统**(原生 Rust 模块,46 实体,已实现) -- [[erp-ai]] — **AI 智能分析 · 化验单解读 · 趋势分析 · 报告摘要**(原生 Rust 模块,6 实体,Phase 1 MVP,已对接本地 Ollama qwen3:4b) +- [[erp-health]] — **患者管理 · 健康数据 · 预约排班 · 随访管理 · 咨询管理 · 内容管理 · 媒体库 · 轮播图管理 · 积分商城 · 透析管理 · 线下活动 · 日常监测 · 告警系统**(原生 Rust 模块,57 实体 / 31 handler / 36 service,已实现) +- [[erp-ai]] — **AI 智能分析 · 化验单解读 · 趋势分析 · 报告摘要**(原生 Rust 模块,9 实体 / 45 文件 / 4 AI Provider,Phase 1 MVP) ### 组装层 - [[erp-server]] — Axum 入口 · AppState · 7+ 模块注册 · 后台任务 · 优雅关闭 @@ -100,8 +107,8 @@ ### 基础设施 - [[infrastructure]] — 连接信息 · 环境变量 · 一键启动 (**单一真相源**) -- [[database]] — SeaORM 迁移 · 多租户表结构(128 迁移) -- [[frontend]] — React 19 SPA · 健康管理页面(55 路由 + 工作台组件) +- [[database]] — SeaORM 迁移 · 多租户表结构(137 迁移) +- [[frontend]] — React 19 SPA · 健康管理页面(29 活跃路由 + 6 冻结 + 工作台组件) - [[testing]] — 验证清单 · 测试分布 · 性能基准 ## 核心架构问答 @@ -121,13 +128,15 @@ | 健康模块设计规格 | `docs/superpowers/specs/2026-04-23-health-management-module-design.md` | | AI 模块设计规格 | `docs/superpowers/specs/2026-04-25-erp-ai-module-design.md` | | 内容管理设计规格 | `docs/superpowers/specs/2026-04-26-content-management-design.md` | +| 媒体库+轮播图设计规格 | `docs/superpowers/specs/2026-05-10-media-library-banner-design.md` | +| 六维度全面均衡分析 | `docs/superpowers/specs/2026-05-11-system-comprehensive-analysis-design.md`(6.9/10 B,六维度评估) | | PII 加密扩展规格 | `docs/superpowers/specs/2026-04-26-pii-encryption-expansion-design.md` | | 实时体征管线探讨 | `docs/superpowers/specs/2026-04-26-realtime-vital-signs-pipeline-design.md` | | 平台复盘与演进 | `docs/superpowers/specs/2026-04-26-platform-retrospective-and-evolution-design.md` | -| 设计规格(全量) | `docs/superpowers/specs/` (47 份) | +| 设计规格(全量) | `docs/superpowers/specs/` (50 份) | | UI/UX 重构设计规格 | `docs/superpowers/specs/2026-04-28-ui-ux-overhaul-design.md` | | UI/UX 重构实施计划 | `docs/superpowers/plans/2026-04-28-ui-ux-overhaul-plan.md` | -| 实施计划(全量) | `docs/superpowers/plans/` (49 份) | +| 实施计划(全量) | `docs/superpowers/plans/` (51 份) | | 全系统审计报告(V1) | `docs/audits/08-audit-report-2026-04-30.md`(83% 总体完成度,2 CRITICAL + 3 HIGH) | | 全系统审计报告(V2) | `docs/audits/v2/13-final-report.md`(85% 总体完成度,P0 安全修复已完成) | | 审计基线快照 | `docs/audits/00-baseline-snapshot.md` | @@ -138,12 +147,13 @@ | 审计差距模式 | `docs/audits/05-gap-patterns.md`(5 种模式,透析/知情同意 MP 缺失) | | 审计错误处理 | `docs/audits/06-error-handling.md`(SSE 不挂起 / 日志 30% 覆盖) | | 审计测试覆盖 | `docs/audits/07-test-coverage.md`(772 测试 / 前端极低 / AI 无集成测试) | -| 讨论记录 | `docs/discussions/` (26 份) | +| 讨论记录 | `docs/discussions/` (29 份) | | 事件注册表 | `docs/event-registry.md` | | Wiki 方法论 | `docs/wiki-methodology.md` | | 项目深度分析 | `docs/superpowers/specs/2026-05-03-project-analysis-brainstorm-design.md`(5 专家组分析,B+ 评分) | | 三维度系统分析 | `docs/discussions/2026-05-07-three-dimension-analysis.md`(后端/前端/质量三维深度分析,2026-05-07) | | 多专家组头脑风暴 | `docs/discussions/2026-05-07-expert-brainstorm-session.md`(5 专家组评审,综合 6.4/10 B-,行动清单) | +| 六维度系统分析+头脑风暴 | `docs/superpowers/specs/2026-05-11-system-comprehensive-analysis-design.md`(6 专家组,综合 6.9/10 B,三个月路线图) | | 角色测试计划(全量) | `docs/qa/role-test-plans/` (R01-R05) | | 角色测试结果 | `docs/qa/role-test-results/` (R01 100% / R02 100% / R03 90.9% / R04 90.0% / R05 72.7% → 修复后待复测) | | 系统集成测试结果 | `docs/qa/role-test-results/T00-system-integration-results.md` (20/28 通过) |