iven/hms
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ec87ae85cf4dff87f380e0edcd9a04f8d5351a4c
hms/wiki/architecture.md
iven ec87ae85cf docs(wiki): 全量 wiki 更新 — C1 晚间血压已修复标记 + 数据校正 
- miniprogram.md: 晚间血压 CRITICAL 标记为已修复
- index.md: 症状导航表更新
- architecture/database/erp-core/erp-health/frontend/testing: 同步更新
2026-05-03 19:32:30 +08:00

10 KiB
Raw Blame History

title, updated, status, tags
title updated status tags
架构决策记录 2026-04-28 stable
architecture
decisions
design-principles

架构决策记录

从 index 导航。关联: erp-core erp-server database wasm-plugin erp-health

1. 设计决策

模块化单体 + 渐进式拆分

模块间零直接依赖，跨模块通信通过事件总线和 trait 接口。ErpModule trait 天然支持未来按模块拆分为微服务。

HMS 架构：原生模块 + 插件并存

HMS 继承 ERP 底座的所有基础模块，erp-health 作为原生 Rust 模块承载医疗业务。WASM 插件系统保留但非 HMS 主要扩展方式。

HMS 平台
├── 基础模块（继承 ERP）: auth, config, workflow, message, plugin
├── 核心业务模块: erp-health（原生 Rust，44 实体/22 权限/25+ 页面）★ 已实现
├── AI 模块: erp-ai（3 实体，SSE 流式分析，Phase 1 MVP）
├── 透析模块: erp-dialysis（已拆分为独立 crate）
└── 可选插件: crm, inventory, freelance, itops, assessment（WASM）
└── 可选插件: crm, inventory, freelance, itops（WASM）

为什么 erp-health 用原生模块？

医疗业务需要 44 强类型实体、自定义 API（趋势分析/统计报表）、PII 数据加密（AES-256-GCM + KEK/DEK 分层）、文件上传、未来 AI 集成。WASM 插件的 JSONB 动态存储和 20 实体上限无法满足。详见 erp-health。

为什么用 UUIDv7？

时间排序 + UUID 唯一性 + 接近自增 ID 的索引性能。多租户 SaaS 下不同租户数据不会因 ID 冲突互相影响。

为什么 tenant_id 不在 API 路径中？

从 JWT 提取，中间件注入 TenantContext。防止：手动改 URL 越权 / API 暴露租户信息 / 忘记检查权限。管理员接口例外。

为什么错误类型跨 crate 用 thiserror？

anyhow 无类型信息，无法精确映射 HTTP 状态码。thiserror → AppError → 400/401/403/404/409/500。

为什么预约用原子 CAS？

防止并发创建预约时超额。事务内 UPDATE current_appointments + 1 WHERE current < max，CAS 成功后才 INSERT 预约记录。

2. 项目结构

目录布局

hms/
├── crates/                    # Rust Workspace
│   ├── erp-core/             # L1: 基础类型、错误、事件、模块 trait
│   ├── erp-auth/             # L2: 身份与权限模块
│   ├── erp-workflow/         # L2: 工作流引擎模块
│   ├── erp-message/          # L2: 消息中心模块
│   ├── erp-config/           # L2: 系统配置模块
│   ├── erp-health/           # L2: 健康管理模块 ★ HMS 核心
│   └── erp-server/           # L3: Axum 服务入口，组装所有模块
│       └── migration/        # SeaORM 数据库迁移
├── apps/
│   └── web/                  # Vite + React 19 SPA (主力前端)
├── packages/
│   └── ui-components/        # React 共享组件库
├── desktop/                  # (可选) Tauri 桌面端
├── docker/                   # Docker 开发环境配置
├── docs/
│   ├── superpowers/specs/    # 设计规格文档
│   └── discussions/          # 讨论记录
├── wiki/                     # 项目知识库
└── Cargo.toml                # Workspace root

模块依赖图

                    erp-core (L1)
                         |
          +--------------+--------------+--------------+-----------+
          |              |              |              |           |
      erp-auth      erp-config    erp-workflow    erp-message  erp-health  erp-ai  (L2)
          |              |              |              |           |
                                                                          |
                                                                    erp-dialysis
          +--------------+--------------+--------------+-----------+
                         |
                    erp-server (L3: 唯一组装点)
                         |
                    erp-plugin (WASM 插件运行时)

禁止: L2 间直接依赖 / L1 依赖业务模块 / 绕过事件总线

模块实现状态

模块 状态 实体数 权限数 页面数 测试覆盖
erp-auth ✅ 完成 11 表 23（种子数据） 用户/角色/组织 41 单元 + 3 集成
erp-config ✅ 完成 6 表 18（种子数据） 设置/字典/菜单 78 单元
erp-workflow ✅ 完成 5 表 8（种子数据） 工作流管理 63 单元 + 4 集成
erp-message ✅ 完成 3 表 5（种子数据） 消息中心 72 单元
erp-plugin ✅ 完成 4 表 2（种子数据） 插件管理/市场 78 单元 + 2 集成
erp-health ✅ 完成 45 表 39 25+ 页面 + 11 组件 159 单元 + 144 集成
erp-ai 🔄 Phase 1 3 表 6 AI 分析/Prompt/用量 36 单元
erp-dialysis 🔄 已拆分 - 5 - 10 单元 + 15 集成

技术选型

选择 理由
Axum 0.8 Tokio 团队维护，tower 生态，类型安全路由
SeaORM 1.1 异步、类型安全、迁移工具完善
PostgreSQL 18 企业级，JSON 支持，扩展丰富
Redis 7 缓存 + 限流 token bucket
React 19 + Ant Design 6 企业后台 UI 标配
Zustand 5 极简状态管理
Wasmtime 43 WASM 沙箱，Component Model，Fuel 限制

集成契约

方向 模块 触发时机
定义 → erp-core 所有模块的 trait 和类型
组装 ← erp-server 6 模块注册和启动
扩展 ← wasm-plugin 插件通过 Host Bridge 桥接
业务 ← erp-health 健康模块原生集成

3. 模块开发规范

新建业务模块清单

每个新模块必须包含：

  1. Cargo.toml — 依赖 erp-core
  2. src/lib.rs — 模块入口，实现 ErpModule trait
  3. src/error.rs — 模块错误类型，wrap AppError
  4. src/entity/ — SeaORM Entity 定义
  5. src/service/ — 业务逻辑层
  6. src/handler/ — Axum 路由处理器
  7. src/event.rs — 模块事件定义和处理器

ErpModule trait 实现

pub struct AuthModule;

impl ErpModule for AuthModule {
    fn name(&self) -> &str { "auth" }
    fn version(&self) -> &str { env!("CARGO_PKG_VERSION") }
    fn dependencies(&self) -> Vec<&str> { vec![] }

    fn register_routes(&self, router: Router) -> Router {
        router.nest("/api/v1", auth_routes())
    }

    fn register_event_handlers(&self, bus: &EventBus) { /* 订阅其他模块事件 */ }

    async fn on_tenant_created(&self, tenant_id: Uuid) -> AppResult<()> { Ok(()) }
}

数据库迁移规范

  • 迁移文件放在 crates/erp-server/migration/src/
  • 命名格式：m{YYYYMMDD}_{6位序号}_{描述}.rs
  • 必须可回滚（实现 down 方法）
  • 新增表必须包含所有标准字段（id, tenant_id, created_at, updated_at, created_by, updated_by, deleted_at, version）
  • 必须幂等（使用 if_not_exists）

4. 安全注意事项

认证安全

  • 密码存储: Argon2 哈希，禁止明文
  • JWT: access token 15min + refresh token 7d
  • Refresh Token 轮换: 每次使用后签发新的，旧的作废
  • Token 存储: 桌面端使用 Tauri secure store
  • 密码修改: 使所有已签发的 JWT 失效

多租户安全

  • 中间件注入: tenant_id 从 JWT 中提取，应用层不可伪造
  • 数据隔离: 所有查询自动过滤 tenant_id
  • 越权防护: 禁止跨租户数据访问
  • 租户 provisioning: on_tenant_created 钩子初始化数据

通用安全

  • 不硬编码密钥 — 使用环境变量或配置文件
  • 用户输入验证 — 所有 API 端点验证输入
  • SQL 注入防护 — SeaORM 参数化查询
  • 限流 — Redis token bucket（用户 100/min，IP 分级）
  • CORS — 白名单制，默认拒绝
  • 审计日志 — 所有关键操作记录变更前后状态 + 哈希链防篡改
  • 动态表 SQL — 使用 sanitize_identifier 防注入
  • PII 加密 — AES-256-GCM + KEK/DEK 分层管理（每租户独立 DEK）
  • HMAC 盲索引 — 支持加密字段的等值查询
  • RLS 行级安全 — PostgreSQL Row Level Policy，中间件 SET app.current_tenant_id
  • Dead Letter — 失败事件自动写入 dead_letter_events 表

5. 代码逻辑

⚡ 不变量: 模块间只通过 EventBus 和 trait 通信，无直接依赖 ⚡ 不变量: 所有数据表必须含 tenant_id，查询自动过滤 ⚡ 不变量: UUID v7 作为主键 ⚡ 不变量: 软删除，不硬删除 ⚡ 不变量: 所有 API 使用 /api/v1/ 前缀 ⚡ 不变量: 预约创建必须走原子 CAS，不能用 read-then-write ⚡ 不变量: PII 数据（身份证、手机号）加密存储 + 脱敏展示

6. 活跃问题 + 陷阱

⚠️ 当前共享数据库 + tenant_id 过滤，未来可扩展为 Schema 隔离或数据库隔离 ⚠️ EventBus 内存 broadcast 需 outbox 持久化保障（已通过后台任务实现） ⚠️ 微信登录固定到 default_tenant_id — 多租户场景需设计解析策略

2026-04-30 审计发现

发现 严重性 说明
前端权限码拼写错误 CRITICAL health.alert.manage → health.alerts.manage（缺 s），告警管理按钮永远不显示
56 个基础模块权限码未通过 PermissionDescriptor 声明 MEDIUM auth/config/workflow/message/plugin 通过种子数据手动注册，新增易遗漏
14 个事件无业务消费者 LOW 发布到 EventBus 但无后端消费者，SSE 推送仍有价值
Health service 层运行时日志极缺 HIGH 26 个 service 文件仅 11 处 tracing，patient_service（949 行）0 处
基础模块 ErpModule trait 实现度低 LOW 5/8 模块使用默认值（auth/config/workflow/message/plugin）

7. 变更记录

日期 变更
2026-05-01 审计数据更新：模块状态表刷新（772 测试 / 328 路由 / 50 权限码）、审计发现清单
2026-04-26 从 CLAUDE.md 迁移：目录结构、模块开发规范（§5）、安全注意事项（§7）
2026-04-25 全面更新：6 模块已实现状态表、预约 CAS 决策、PII 加密不变量、健康模块集成
2026-04-23 重构为 5 节结构，删除 erp-common 引用，精简技术选型表
Reference in New Issue View Git Blame Copy Permalink