iven/hms
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7fcabd2e6b78696cbfeeca8a0e05a0268bb824e3
hms/wiki/index.md
iven 28bcdc4208
Some checks failed
CI / frontend-build (push) Has been cancelled
Details
CI / security-audit (push) Has been cancelled
Details
CI / rust-check (push) Has been cancelled
Details
CI / rust-test (push) Has been cancelled
Details
docs: 更新 wiki — Design Token 全面接入记录 
- index.md: 更新关键数字（716 提交）、新增 Design Token 指标行
- miniprogram.md: 新增 §1.1 Design Token 系统完整文档（10 级字号表、
  4 结构 token、使用规则、关怀模式说明）、更新变更记录
2026-05-09 23:58:09 +08:00

153 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# HMS 健康管理平台 — 知识库
> **Health Management System (HMS)** — 面向体检中心/医疗机构的综合健康管理平台。从 ERP 底座分叉，继承身份权限/工作流/消息/配置等基础能力，`erp-health` 原生模块承载医疗业务。
## 关键数字
> 最后更新: 2026-05-09 | 数据截止: commit 890c132 (第 716 次提交)
| 指标 | 值 |
|------|-----|
| 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 受保护） |
| 核心模块 | 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 基础模块手动注册 |
| Clippy | **全 workspace 0 警告**（2026-05-07 清零） |
| API 文档 | `http://localhost:3000/api/docs/openapi.json` |
| Git 提交 | 716 次 |
| 审计状态 | V1: 83% (2026-04-30) → V2: 85% (2026-05-05)，P0 安全修复已完成 |
| 角色测试 | 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 类型） |
## 症状导航
| 症状 | 先查 | 再查 | 常见根因 |
|------|------|------|----------|
| API 返回 403 | 权限码检查 | [[wasm-plugin]] 权限系统 | 权限码不匹配 / 缺少 .list 权限 |
| API 返回 500 无日志 | [[erp-core]] 错误链 | 后端 tracing 输出 | AppError::Internal 静默 |
| 数据库连接失败 | [[infrastructure]] | PostgreSQL 服务状态 | 服务未启动 / 环境变量未设置 |
| 前端 401 刷新时 | [[frontend]] auth store | API client token 刷新 | token 过期未主动刷新 |
| 迁移执行失败 | [[database]] | PostgreSQL 日志 | 表冲突 / 唯一索引 + 软删除 / 缺失迁移文件 |
| 端口被占用 | [[infrastructure]] dev.ps1 | 端口 5174-5189 进程 | 残留 Vite 进程 |
| 预约创建 400 doctor_id is required | [[erp-health]] 预约并发控制 | AppointmentList.tsx | 医生字段为必填（后端 CAS 要求） |
| 预约超额 | [[erp-health]] 排班并发 | appointment CAS 操作 | 并发控制未走原子 CAS |
| 患者创建 422 birth_date trailing input | [[frontend]] 日期序列化 | DatePicker dayjs 对象 | 未格式化为 YYYY-MM-DD 字符串 |
| 跨租户数据泄漏 | [[architecture]] 多租户策略 | [[database]] tenant_id | 查询缺少 tenant_id 过滤 |
| 小程序页面空白 | [[miniprogram]] defineConstants | `process.env` 未替换 | 编译时未注入环境变量 |
| 小程序登录失败 `btoa is not defined` | [[miniprogram]] secure-storage | Web API 不可用 | 使用 `Taro.arrayBufferToBase64` 替代 |
| 微信登录 500 | [[database]] wechat_users 表结构 | Entity 字段与表不匹配 | 补 `created_by/updated_by/version` 列 |
| 迁移文件缺失报错 | [[database]] 迁移注册 | migration/src/lib.rs | 已应用的迁移文件被删除，需创建 stub |
| MCP 连接失败 `split` error | [[miniprogram]] MCP 联调 | project.config.json | 未开启 `automationAudits` |
| MCP mp_screenshot 超时 | [[miniprogram]] MCP 联调 | automator 已知 bug | 用 `page_getElement` 替代截图 |
| MCP 导航后跳回登录页 | [[miniprogram]] MCP 联调 §6.4 | storage 被清空 | 明文 token 写入后立即 reLaunch |
| MCP token 注入后仍 401 | [[miniprogram]] MCP 联调 §6.1 | 用了生产构建 | dev 构建（`NODE_ENV=development`）+ 空密钥 |
| MCP App 级命令全部超时 | [[miniprogram]] MCP 联调 §6.2 | 多 DevTools 实例冲突 | `taskkill /F /IM wechatdevtools.exe` 后重开 |
| MCP CLI 报"需要重新登录" | [[miniprogram]] MCP 联调 §6.2 | DevTools 未扫码 | 在 DevTools 中先扫码登录 |
| 积分商城 Tab 页空白 | [[miniprogram]] 待优化 | 未关联患者档案 | 需增加降级 UI 引导建档 |
| MCP 批量审计页面栈溢出 | [[miniprogram]] MCP 联调 §6.6 | `navigateTo` 超 10 层 | 改用 `reLaunch` 逐页测试 |
| 告警管理按钮不显示 | [[frontend]] 权限码拼写 | AlertList.tsx | `health.alert.manage` → `health.alerts.manage`（缺 s） |
| 小程序晚间血压丢失 | [[miniprogram]] 体征录入 | indicator_type 映射 | **已修复：** 新增 `blood_pressure_evening` 类型，录入页+日常监测页+后端+测试全覆盖 |
| AI 分析 SSE 无 UI 入口 | [[erp-health]] AI 分析 | 前端未调用 | 4 个 SSE 端点无管理界面触发 |
| AI 分析返回对话式回复 | [[erp-ai]] prompt 模板 | 迁移 000123 | system_prompt 未加非对话指令 / 数据为空 |
| AI 分析结果显示原始 JSON | [[erp-ai]] 缓存回放 | `replay_cached` | 迁移 000123 前的嵌套 JSON bug，前端 `extractPlainText` 兼容 |
| AI 分析输出全空（SSE content=""） | [[erp-ai]] qwen3 thinking | `strip_think_block` | qwen3 流式 API content 为空，改非流式 + 剥离 think 块 |
| Ollama 内存不足 `memory layout` | [[infrastructure]] Ollama 配置 | `OLLAMA_CONTEXT_LENGTH` | 默认 262144 导致 35GB KV cache，设为 4096 |
| Ollama 暴露到局域网 | [[infrastructure]] Ollama 安全 | `OLLAMA_HOST` | 默认 `0.0.0.0`，必须设 `127.0.0.1` |
| AI 趋势/报告分析 500 模板渲染失败 | [[erp-ai]] Handlebars 模板 | `anomalies.length` | `.length` 不是有效 Handlebars 语法，改为 `{{#if anomalies}}` |
| AI 分析 400 缺少数据 | 后端预校验 | handler 层 | 化验报告 items 为空 / 趋势数据 metrics 为空 |
| 患者创建空名称成功 | [[erp-health]] patient_handler | `name.trim().is_empty()` | **已修复：** 后端添加空名称校验返回 Validation 错误 |
| 仪表盘统计 500 | [[erp-health]] stats_handler | 单个查询异常导致整接口崩溃 | **已修复：** 容错处理，单个查询失败返回零值 |
| FHIR 端点全部 404 | [[erp-server]] main.rs | 路由注册在 `/fhir` 非 `/api/v1/fhir` | **已修复：** 移到 `/api/v1/fhir` |
| 冻结模块 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`） |
## 模块导航
### 基础层（继承自 ERP 底座）
- [[erp-core]] — 错误体系 · 事件总线 · 模块 trait · 共享类型
- [[architecture]] — 架构决策 · 设计原则 · 技术选型
### 业务层（继承自 ERP 底座）
- erp-auth — 用户/角色/权限/组织/部门/岗位 · JWT · RBAC · 行级数据权限
- erp-config — 字典/菜单/设置/编号规则/主题/语言
- erp-workflow — BPMN 解析 · Token 驱动 · 任务分配
- erp-message — 消息 CRUD · 模板 · 订阅 · 通知面板
- erp-plugin — WASM 运行时 · 动态表 · 热更新（HMS 保留但非主要扩展方式）
### 核心业务层（HMS 专属）
- [[erp-health]] — **患者管理 · 健康数据 · 预约排班 · 随访管理 · 咨询管理 · 内容管理 · 积分商城 · 透析管理 · 线下活动 · 日常监测 · 告警系统**（原生 Rust 模块，46 实体，已实现）
- [[erp-ai]] — **AI 智能分析 · 化验单解读 · 趋势分析 · 报告摘要**（原生 Rust 模块，6 实体，Phase 1 MVP，已对接本地 Ollama qwen3:4b）
### 组装层
- [[erp-server]] — Axum 入口 · AppState · 7+ 模块注册 · 后台任务 · 优雅关闭
### 患者端
- [[miniprogram]] — **微信小程序** · Taro 4.2 · 微信登录 · 手机绑定 · 健康数据查看
### 基础设施
- [[infrastructure]] — 连接信息 · 环境变量 · 一键启动 (**单一真相源**)
- [[database]] — SeaORM 迁移 · 多租户表结构（128 迁移）
- [[frontend]] — React 19 SPA · 健康管理页面（55 路由 + 工作台组件）
- [[testing]] — 验证清单 · 测试分布 · 性能基准
## 核心架构问答
**为什么 erp-health 用原生模块而非 WASM 插件？** 医疗业务需要 18 强类型实体、自定义 API（趋势分析/统计报表）、文件上传（化验单/体检报告）、未来 AI 集成，超出 WASM 插件能力范围。详见 [[erp-health]]。
**模块间如何通信？** [[erp-core]] EventBus 发布/订阅 DomainEvent。erp-health 发布 `patient.created`、`appointment.confirmed` 等事件，订阅 `workflow.task.completed` 等。详见 [[architecture]]。
**多租户怎么隔离？** 共享数据库 + `tenant_id` 列过滤，中间件从 JWT 注入。详见 [[database]] [[architecture]]。
**患者/医护与 erp-auth 的关系？** 账号走 `users` 表，erp-health 通过 `user_id` 外键关联扩展字段（科室、职称、档案等）。患者可先建档后绑定账号。
## 文档索引
| 类型 | 位置 |
|------|------|
| 健康模块设计规格 | `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` |
| 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 份) |
| 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 份) |
| 全系统审计报告（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` |
| 审计功能清单 | `docs/audits/01-feature-inventory.md`（328 路由三端映射矩阵） |
| 审计后端完整性 | `docs/audits/02-backend-integrity.md`（100% 调用链连通） |
| 审计事件系统 | `docs/audits/03-event-system.md`（25 事件 / 14 消费者 / 100% payload 一致） |
| 审计参数配置 | `docs/audits/04-parameter-config.md`（105 DTO / 50 权限码 / 数据映射缺口） |
| 审计差距模式 | `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/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/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 通过) |
| 小程序 E2E 测试结果 | `docs/qa/role-test-results/T10-miniprogram-e2e-results.md` (需手动执行) |
| 协作规则 | `CLAUDE.md` |
| 插件制作指南 | `.claude/skills/plugin-development/SKILL.md` |
Reference in New Issue View Git Blame Copy Permalink