feat(health): 添加 erp-health 健康管理模块骨架
新建 erp-health 原生 Rust crate，覆盖设计规格中定义的 5 大业务域： - 16 个 SeaORM Entity（患者/家属/标签/医生/健康档案/体征/化验单/预约/排班/随访/咨询等） - 16 表数据库迁移（含索引、外键、默认值、可回滚） - 40+ API 路由骨架（患者管理/健康数据/预约排班/随访/咨询/医生管理） - 12 个权限声明（health.patient/health-data/appointment/follow-up/consultation/doctor 各 .list/.manage） - DTO / Service / Handler / Event 四层架构，Service 使用 todo!() 占位 - erp-server 集成：模块注册 + AppState FromRef 桥接 + 路由挂载 同步更新 CLAUDE.md 项目进度、wiki 知识库、设计规格文档。
This commit is contained in:
iven
@@ -1,125 +1,102 @@
|
||||
# architecture (架构决策记录)
|
||||
---
|
||||
title: 架构决策记录
|
||||
updated: 2026-04-23
|
||||
status: stable
|
||||
tags: [architecture, decisions, design-principles]
|
||||
---
|
||||
|
||||
## 设计思想
|
||||
# 架构决策记录
|
||||
|
||||
ERP 平台采用 **模块化单体 + 渐进式拆分** 架构。核心原则：模块间零直接依赖，所有跨模块通信通过事件总线和 trait 接口。
|
||||
> 从 [[index]] 导航。关联: [[erp-core]] [[erp-server]] [[database]] [[wasm-plugin]] [[erp-health]]
|
||||
|
||||
## 关键架构决策
|
||||
## 1. 设计决策
|
||||
|
||||
### Q: 为什么用模块化单体而非微服务？
|
||||
### 模块化单体 + 渐进式拆分
|
||||
|
||||
**A:** ERP 系统的模块间数据一致性要求高，分布式事务成本大。单体起步，模块边界清晰，未来需要时可按模块拆分为微服务。`ErpModule` trait 天然支持这种渐进式迁移。
|
||||
模块间零直接依赖，跨模块通信通过事件总线和 trait 接口。`ErpModule` trait 天然支持未来按模块拆分为微服务。
|
||||
|
||||
### Q: 为什么用 UUIDv7 而不是自增 ID？
|
||||
### HMS 架构：原生模块 + 插件并存
|
||||
|
||||
**A:** UUIDv7 是时间排序的，既有 UUID 的分布式唯一性，又有接近自增 ID 的索引性能。对多租户 SaaS 尤其重要——不同租户的数据不会因为 ID 冲突而互相影响。
|
||||
HMS 继承 ERP 底座的所有基础模块，`erp-health` 作为原生 Rust 模块承载医疗业务。WASM 插件系统保留但非 HMS 主要扩展方式。
|
||||
|
||||
### Q: 为什么用 broadcast channel 做事件总线？
|
||||
```
|
||||
HMS 平台
|
||||
├── 基础模块（继承 ERP）: auth, config, workflow, message, plugin
|
||||
├── 核心业务模块: erp-health（原生 Rust）★
|
||||
└── 可选插件: crm, inventory, freelance, itops（WASM）
|
||||
```
|
||||
|
||||
**A:** `tokio::sync::broadcast` 提供多消费者发布/订阅，语义匹配模块间事件通知。设计规格要求 outbox 模式（持久化到 domain_events 表），但当前 Phase 1 先用内存 broadcast，后续再补持久化。
|
||||
### 为什么 erp-health 用原生模块？
|
||||
|
||||
### Q: 为什么错误类型跨 crate 边界必须用 thiserror？
|
||||
医疗业务需要 16+ 强类型实体、自定义 API（趋势分析/统计报表）、文件上传、未来 AI 集成。WASM 插件的 JSONB 动态存储和 20 实体上限无法满足。详见 [[erp-health]]。
|
||||
|
||||
**A:** `anyhow` 的错误没有类型信息，无法在 API 层做精确的 HTTP 状态码映射。`thiserror` 定义明确的错误变体，`AppError` 可以精确映射到 400/401/403/404/409/500。crate 内部可以用 `anyhow` 简化，但对外必须转 `AppError`。
|
||||
### 为什么用 UUIDv7？
|
||||
|
||||
### Q: 为什么 tenant_id 不在 API 路径中？
|
||||
时间排序 + UUID 唯一性 + 接近自增 ID 的索引性能。多租户 SaaS 下不同租户数据不会因 ID 冲突互相影响。
|
||||
|
||||
**A:** 从 JWT token 中提取 tenant_id，通过中间件注入 `TenantContext`。这防止了：
|
||||
- 用户手动修改 URL 访问其他租户数据
|
||||
- API 路径暴露租户信息
|
||||
- 开发者忘记检查租户权限
|
||||
### 为什么 tenant_id 不在 API 路径中？
|
||||
|
||||
管理员接口例外，可以通过路径指定 tenant_id。
|
||||
从 JWT 提取，中间件注入 `TenantContext`。防止：手动改 URL 越权 / API 暴露租户信息 / 忘记检查权限。管理员接口例外。
|
||||
|
||||
### Q: 为什么前端用 HashRouter 而非 BrowserRouter？
|
||||
### 为什么错误类型跨 crate 用 thiserror？
|
||||
|
||||
**A:** 部署时可能不在根路径下，HashRouter 不需要服务端配置 fallback 路由。对 SPA 来说更稳健。
|
||||
`anyhow` 无类型信息，无法精确映射 HTTP 状态码。`thiserror` → `AppError` → 400/401/403/404/409/500。
|
||||
|
||||
## 模块依赖铁律
|
||||
## 2. 关键文件 + 数据流
|
||||
|
||||
### 模块依赖图
|
||||
|
||||
```
|
||||
erp-core (L1)
|
||||
erp-common (L1)
|
||||
|
|
||||
+--------------+--------------+--------------+
|
||||
| | | |
|
||||
erp-auth erp-config erp-workflow erp-message (L2)
|
||||
| | | |
|
||||
+--------------+--------------+--------------+
|
||||
+--------------+--------------+--------------+-----------+
|
||||
| | | | |
|
||||
erp-auth erp-config erp-workflow erp-message erp-health (L2)
|
||||
| | | | |
|
||||
+--------------+--------------+--------------+-----------+
|
||||
|
|
||||
erp-server (L3: 唯一组装点)
|
||||
|
|
||||
erp-plugin (WASM 插件运行时)
|
||||
```
|
||||
|
||||
**禁止：**
|
||||
- L2 模块之间直接依赖
|
||||
- L1 模块依赖任何业务模块
|
||||
- 绕过事件总线直接调用其他模块
|
||||
**禁止**: L2 间直接依赖 / L1 依赖业务模块 / 绕过事件总线
|
||||
|
||||
## 多租户隔离策略
|
||||
|
||||
**当前策略：共享数据库 + tenant_id 列过滤**
|
||||
|
||||
所有业务表包含 `tenant_id` 列，查询时通过中间件自动注入过滤条件。这是最简单的 SaaS 多租户方案，未来可扩展为：
|
||||
- Schema 隔离 — 每个租户独立 schema
|
||||
- 数据库隔离 — 每个租户独立数据库（私有化部署）
|
||||
|
||||
`ErpModule::on_tenant_created()` 和 `on_tenant_deleted()` 钩子确保模块能在租户创建/删除时初始化/清理数据。
|
||||
|
||||
## 技术选型理由
|
||||
### 技术选型
|
||||
|
||||
| 选择 | 理由 |
|
||||
|------|------|
|
||||
| Axum 0.8 | Tokio 团队维护，与 tower 生态无缝集成，类型安全路由 |
|
||||
| SeaORM 1.1 | 异步、类型安全、Rust 原生 ORM，迁移工具完善 |
|
||||
| PostgreSQL 16 | 企业级关系型数据库，JSON 支持好，扩展丰富 |
|
||||
| Redis 7 | 高性能缓存，会话存储，限流 token bucket |
|
||||
| React 19 + Ant Design 6 | 成熟的组件库，企业后台 UI 标配 |
|
||||
| Zustand | 极简状态管理，无 boilerplate |
|
||||
| utoipa | Rust 代码生成 OpenAPI 文档，零额外维护 |
|
||||
| Wasmtime 43 | WASM 沙箱运行时，Component Model 支持，Fuel 资源限制 |
|
||||
| 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 限制 |
|
||||
|
||||
## 插件扩展架构
|
||||
### 集成契约
|
||||
|
||||
### Q: 为什么用 WASM 而不是 Lua / gRPC / dylib？
|
||||
| 方向 | 模块 | 触发时机 |
|
||||
|------|------|---------|
|
||||
| 定义 → | [[erp-core]] | 所有模块的 trait 和类型 |
|
||||
| 组装 ← | [[erp-server]] | 模块注册和启动 |
|
||||
| 扩展 ← | [[wasm-plugin]] | 插件通过 Host Bridge 桥接 |
|
||||
|
||||
**A:**
|
||||
## 3. 代码逻辑
|
||||
|
||||
| 方案 | 安全性 | 隔离性 | 性能 | 复杂度 |
|
||||
|------|--------|--------|------|--------|
|
||||
| **WASM** | 高（沙箱） | 进程内隔离 | 接近原生（JIT） | 中 |
|
||||
| Lua 脚本 | 中 | 无隔离 | 快 | 低 |
|
||||
| 进程外 gRPC | 高 | 进程级隔离 | 网络开销 | 高 |
|
||||
| dylib | 低（直接内存） | 无隔离 | 原生 | 低 |
|
||||
⚡ **不变量**: 模块间只通过 EventBus 和 trait 通信，无直接依赖
|
||||
⚡ **不变量**: 所有数据表必须含 `tenant_id`，查询自动过滤
|
||||
⚡ **不变量**: UUID v7 作为主键
|
||||
⚡ **不变量**: 软删除，不硬删除
|
||||
⚡ **不变量**: 所有 API 使用 `/api/v1/` 前缀
|
||||
|
||||
WASM 在安全性和性能之间取得最佳平衡。Wasmtime v43 的 Component Model 提供了类型安全的 Host-Plugin 接口，Fuel 机制防止恶意/有缺陷的插件消耗过多资源。
|
||||
## 4. 活跃问题 + 陷阱
|
||||
|
||||
### 插件架构拓扑
|
||||
⚠️ 当前共享数据库 + tenant_id 过滤，未来可扩展为 Schema 隔离或数据库隔离
|
||||
⚠️ EventBus 内存 broadcast 需 outbox 持久化保障（已通过后台任务实现）
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ erp-server │
|
||||
│ ┌──────────────┐ ┌──────────────────────────┐ │
|
||||
│ │ EventBus │ │ PluginRuntime (Wasmtime) │ │
|
||||
│ │ (broadcast) │ │ ┌──────┐ ┌──────┐ │ │
|
||||
│ └──────┬───────┘ │ │插件 A│ │插件 B│ │ │
|
||||
│ │ │ └──┬───┘ └──┬───┘ │ │
|
||||
│ │ │ │ Host API │ │ │
|
||||
│ │ │ ┌──┴────────┴──┐ │ │
|
||||
│ │ │ │ Host Bridge │ │ │
|
||||
│ │ │ └──┬───────────┘ │ │
|
||||
│ │ └─────┼────────────────────┘ │
|
||||
│ │ │ │
|
||||
│ ┌──────┴───────┐ ┌────┴─────┐ │
|
||||
│ │ DB (SeaORM) │ │ EventBus │ │
|
||||
│ └──────────────┘ └──────────┘ │
|
||||
└─────────────────────────────────────────────────┘
|
||||
```
|
||||
## 5. 变更记录
|
||||
|
||||
插件通过 Host Bridge 调用系统功能（db_insert、event_publish 等），Host Bridge 自动注入多租户隔离（tenant_id）和权限检查。详见 [[wasm-plugin]]。
|
||||
|
||||
## 关联模块
|
||||
|
||||
- **[[erp-core]]** — 架构契约的定义者
|
||||
- **[[erp-server]]** — 架构的组装执行者
|
||||
- **[[database]]** — 多租户隔离的物理实现
|
||||
- **[[wasm-plugin]]** — 插件扩展架构的实现
|
||||
| 日期 | 变更 |
|
||||
|------|------|
|
||||
| 2026-04-23 | 重构为 5 节结构，删除 erp-common 引用，精简技术选型表 |
|
||||
|
||||
Reference in New Issue
Block a user