hms/docs/superpowers/specs/2026-04-25-erp-ai-module-design.md

erp-ai 模块设计规格

日期: 2026-04-25 | 状态: 设计审批通过，待实施 技术架构演进方向: 实时能力层 → AI 智能分析流

---

1. 背景与目标

HMS 健康管理平台已完成全部基础模块和健康业务模块的开发。为提升患者端体验、降低医患沟通成本，引入 AI 智能分析能力，让患者在小程序端即可获得化验单解读、健康趋势分析、个性化体检方案和报告摘要等 AI 驱动的自助服务。

核心目标：

• 患者按需获取 AI 流式解读，无需等待医生电话
• 模型无关的 AI Gateway，支持多提供商切换和 A/B 测试
• 严格数据脱敏，PII 不离开服务器
• Prompt 模板数据库化管理，支持版本控制和回滚
• 架构预留异步分析管道，平滑演进到混合模式

---

2. 模块定位

2.1 在 HMS 架构中的位置

erp-core (ErpModule trait + EventBus + AppState)
    ↑
erp-health ──publish──→ {patient.lab-report.created, health.vital-signs.updated, ...}
    ↑
erp-ai (NEW) ──subscribe──→ health 事件 (Phase 3 预留)
              ──publish──→ {ai.analysis.completed, ai.analysis.failed}
    ↑
erp-server (组装入口)

2.2 为什么是独立模块而非内嵌

• AI 是跨横切平台能力，非健康专属（未来消息、工作流、客服都可能用）
• 遵循 CLAUDE.md 铁律：业务 crate 之间禁止直接依赖
• 通过 EventBus + HealthDataProvider trait 获取数据，模块边界清晰
• 提供商切换、成本管理、脱敏策略全部内聚在 erp-ai 内部

---

3. 架构设计

3.1 Crate 结构

crates/erp-ai/
├── Cargo.toml
└── src/
    ├── lib.rs              # 模块入口, ErpModule impl
    ├── error.rs            # AiError → AppError
    ├── provider/           # AI 提供商抽象
    │   ├── mod.rs          # AiProvider trait 定义
    │   ├── claude.rs       # Claude API 实现
    │   ├── openai.rs       # OpenAI API 实现 (Phase 2)
    │   └── config.rs       # 提供商配置 & 路由策略
    ├── pipeline/           # 分析管道
    │   ├── mod.rs          # AnalysisPipeline trait
    │   ├── request.rs      # 请求驱动管道 (Phase 1, SSE)
    │   └── async.rs        # 异步管道 (Phase 3, stub)
    ├── sanitization/       # 数据脱敏层
    │   ├── mod.rs          # DeIdentificationService
    │   └── rules.rs        # 脱敏规则
    ├── prompt/             # Prompt 管理
    │   ├── mod.rs          # PromptManager trait
    │   └── template.rs     # 模板渲染引擎
    ├── entity/             # SeaORM Entity
    │   ├── ai_prompt.rs
    │   ├── ai_analysis.rs
    │   └── ai_usage.rs
    ├── service/            # 业务逻辑
    │   ├── analysis.rs     # AnalysisService (核心编排)
    │   ├── prompt.rs       # PromptService (CRUD + 版本)
    │   └── usage.rs        # UsageService (用量追踪)
    └── handler/            # Axum 路由
        ├── mod.rs
        ├── analysis.rs     # SSE 流式分析端点
        ├── prompt.rs       # Prompt 管理 CRUD
        └── usage.rs        # 用量统计端点

3.2 核心抽象

/// AI 提供商 trait
#[async_trait]
pub trait AiProvider: Send + Sync {
    async fn stream_generate(&self, req: GenerateRequest) -> Result<impl Stream<Item = Chunk>>;
    async fn generate(&self, req: GenerateRequest) -> Result<GenerateResponse>;
    fn name(&self) -> &str;
    async fn health_check(&self) -> Result<bool>;
}

/// 分析管道 trait (Phase 1: RequestPipeline; Phase 3: + AsyncPipeline)
pub trait AnalysisPipeline: Send + Sync {
    fn analyze(&self, ctx: AnalysisContext) -> impl Stream<Item = AnalysisChunk>;
}

/// 数据脱敏 trait
pub trait DataSanitizer: Send + Sync {
    fn sanitize(&self, data: &serde_json::Value) -> Result<SanitizedData>;
}

3.3 erp-core 扩展

/// 新增到 erp-core，由 erp-health 实现
pub trait HealthDataProvider: Send + Sync {
    async fn get_report_by_id(&self, tenant_id: Uuid, report_id: Uuid) -> AppResult<LabReport>;
    async fn get_vital_signs(&self, tenant_id: Uuid, patient_id: Uuid, metrics: &[String], range: TimeRange) -> AppResult<Vec<VitalSign>>;
    async fn get_patient_summary(&self, tenant_id: Uuid, patient_id: Uuid) -> AppResult<PatientSummary>;
    async fn get_full_report(&self, tenant_id: Uuid, report_id: Uuid) -> AppResult<HealthReport>;
}

/// 新增事件类型
pub enum AiEvent {
    AnalysisCompleted { analysis_id: Uuid, patient_id: Uuid, analysis_type: String },
    AnalysisFailed { analysis_id: Uuid, error: String },
}

/// 新增权限码
pub const AI_PERMISSIONS: &[&str] = &[
    "ai.analysis.request",
    "ai.analysis.view",
    "ai.analysis.manage",
    "ai.prompt.list",
    "ai.prompt.manage",
    "ai.usage.view",
    "ai.admin.provider",
];

---

4. 数据流设计

4.1 请求驱动管道 (Phase 1)

患者点击"AI解读" → POST /api/v1/ai/analyze/lab-report
  → 鉴权 (JWT → tenant_id + user_id)
  → 权限检查 (ai.analysis.request)
  → 加载数据 (via HealthDataProvider trait)
  → DeIdentificationService.sanitize()
  → PromptManager.render(template, sanitized_data)
  → AiProvider.stream_generate(prompt)
  → SSE 流式返回给前端
  → 存储完整结果到 ai_analysis_results
  → 记录用量到 ai_usage_logs
  → 发布 ai.analysis.completed 事件

4.2 SSE 事件格式

event: chunk
data: {"content": "您的血常规检查中，", "index": 1}

event: metadata
data: {"model": "claude-sonnet-4-6", "tokens": {"input": 856, "output": 423}, "duration_ms": 3200}

event: done
data: {"analysis_id": "uuid-xxx", "status": "completed"}

4.3 四种分析场景

场景	端点	输入	Prompt 模板
化验单解读	POST /ai/analyze/lab-report	report_id	lab_report_interpretation
趋势分析	POST /ai/analyze/trends	patient_id + metrics + 时间范围	health_trend_analysis
个性化方案	POST /ai/analyze/checkup-plan	patient_id	personalized_checkup_plan
报告摘要	POST /ai/analyze/report-summary	report_id	report_summary_generation

---

5. 数据库设计

5.1 ai_prompts

列	类型	说明
id	UUID v7	主键
tenant_id	UUID	租户
name	VARCHAR(100)	模板标识
description	TEXT	用途描述
system_prompt	TEXT	系统角色 Prompt
user_prompt_template	TEXT	用户 Prompt 模板 ({{variable}} 占位符)
variables_schema	JSONB	模板变量 JSON Schema
model_config	JSONB	{provider, model, temperature, max_tokens}
version	INT	语义版本（自增）
is_active	BOOLEAN	当前激活版本
category	VARCHAR(50)	analysis / summary / suggestion
tags	JSONB	标签数组
+ 标准审计字段		tenant_id, created_at, updated_at, created_by, updated_by, deleted_at, version

5.2 ai_analysis_results

列	类型	说明
id	UUID v7	主键
tenant_id	UUID	租户
patient_id	UUID	患者
analysis_type	VARCHAR(50)	lab_report / trend / checkup_plan / report_summary
source_ref	VARCHAR(200)	来源引用
prompt_id	UUID	关联 Prompt
prompt_version	INT	Prompt 版本号
model_used	VARCHAR(100)	实际模型
input_data_hash	VARCHAR(64)	SHA-256（缓存键）
sanitized_input	JSONB	脱敏输入快照（审计）
result_content	TEXT	AI 完整输出
result_metadata	JSONB	tokens/耗时/模型信息
status	VARCHAR(20)	pending / streaming / completed / failed
error_message	TEXT	失败原因
+ 标准审计字段

5.3 ai_usage_logs

列	类型	说明
id	UUID v7	主键
tenant_id	UUID	租户
provider	VARCHAR(50)	claude / openai / local
model	VARCHAR(100)	具体模型
analysis_type	VARCHAR(50)	分析类型
input_tokens	INT
output_tokens	INT
duration_ms	INT
cost_cents	INT	费用（分）
is_cache_hit	BOOLEAN
created_at	TIMESTAMP

---

6. 数据脱敏与安全

6.1 脱敏规则

• 移除: 姓名、身份证号、手机号、地址、出生日期、医生姓名
• 泛化: 精确年龄 → 年龄段 (18-30, 30-40, 40-50, ...)
• 保留: 科室、检验指标、诊断编码、用药记录、家族史

6.2 安全防护层

1. 速率限制: 患者端 10次/天/人，管理端 100次/小时/租户 (Redis Token Bucket)
2. 输入验证: schema 校验，租户隔离校验
3. Prompt 注入防护: JSON 序列化注入，不做字符串拼接
4. 输出过滤: 正则扫描处方药推荐/诊断结论，强制追加免责声明
5. 审计日志: sanitized_input 保留脱敏快照

6.3 降级策略

缓存命中 → 直接返回
缓存未命中 + AI 可用 → 正常 SSE
缓存未命中 + AI 不可用 + 有旧版本 → 返回旧结果 + 标注
缓存未命中 + AI 不可用 + 无历史 → 本地规则引擎（50 条常见指标）

---

7. API 设计

/api/v1/ai/
├── analyze/
│   ├── POST /lab-report         SSE  化验单解读
│   ├── POST /trends             SSE  健康趋势分析
│   ├── POST /checkup-plan       SSE  个性化体检方案
│   └── POST /report-summary     SSE  报告摘要生成
├── analysis/
│   ├── GET  /history            JSON 分析历史列表
│   └── GET  /:id                JSON 分析详情
├── prompts/                     (需 ai.prompt.manage)
│   ├── GET  /                   JSON Prompt 列表
│   ├── POST /                   JSON 新建 Prompt
│   ├── GET  /:id                JSON Prompt 详情
│   ├── PUT  /:id                JSON 编辑 (自动+1版本)
│   ├── POST /:id/activate       JSON 激活指定版本
│   ├── GET  /:id/versions        JSON 版本历史
│   └── POST /:id/rollback        JSON 回滚
├── usage/                       (需 ai.usage.view)
│   ├── GET  /stats              JSON 用量统计
│   ├── GET  /costs              JSON 费用明细
│   └── GET  /models             JSON 模型分布
└── admin/
    ├── GET  /providers          JSON 提供商状态
    ├── PUT  /providers/:name/config  JSON 更新配置
    └── POST /providers/:name/test    JSON 连通性测试

---

8. 前端设计

8.1 小程序 (Phase 1)

• 报告详情页新增「AI 智能解读」卡片，引导点击
• 新增 AI 解读展示页，SSE 逐字流式渲染
• 历史解读列表（点击查看过往分析）

8.2 Web 管理后台 (Phase 2)

• AI Prompt 管理页面：列表/编辑/版本历史/diff 对比/回滚
• AI 用量统计仪表盘：按天/模型/场景维度
• 提供商状态与配置管理

---

9. 扩展路线图

Phase 1 — MVP (约 2-3 周)

• erp-ai crate 骨架 + ErpModule 实现
• AiProvider trait + Claude SSE 实现
• DeIdentificationService
• PromptManager + 3 张表 + migration
• 4 个分析端点
• 缓存 + 降级规则引擎
• 小程序 AI 解读功能
• 速率限制 + 审计日志

Phase 2 — 运营强化 (约 2 周)

• Web Prompt 管理完整 UI
• 版本 diff 对比 + 回滚
• 用量统计仪表盘
• OpenAI 提供商实现
• 成本告警
• 分享功能

Phase 3 — 混合管道 (约 2-3 周)

• AsyncAnalysisPipeline 实现
• EventBus 订阅 health 事件
• 后台预分析队列
• 消息中心通知集成
• WebSocket StreamingProvider 实现
• 本地模型对接 (Ollama/vLLM)

Phase 4 — 智能化 (持续)

• Prompt A/B 测试
• 分析效果评分
• 多轮对话式解读
• 多模态输入 (OCR)
• 知识库 RAG

Phase 1 架构预留点

预留点	位置	做法
AnalysisPipeline trait	pipeline/mod.rs	RequestPipeline 唯一实现，Phase 3 加 AsyncPipeline
StreamingProvider trait	provider/mod.rs	SSE 唯一实现，Phase 3 加 WebSocket
AnalysisContext.trigger	pipeline/mod.rs	枚举 Request | Event，Phase 3 加 Event
HealthDataProvider trait	erp-core	erp-health 实现，erp-ai 注入使用
事件发布	service/analysis.rs	完成后发布事件，Phase 1 无消费者也发布
model_config 字段	ai_prompts 表	每模板独立配置 provider/model

---

10. 关键文件清单

区域	文件	操作
erp-core	src/trait.rs	新增 HealthDataProvider trait
erp-core	src/event.rs	新增 ai.* 事件类型
erp-core	src/permission.rs	新增 ai.* 权限码
erp-health	src/ai_provider.rs	新增 HealthDataProvider impl
erp-ai	整个 crate	新建
erp-server	src/main.rs	注册 AiModule
erp-server/migration	新增 migration	3 张表
apps/miniprogram	报告详情页 + 解读页	新增/修改
apps/web	Prompt 管理页面	Phase 2 新增

---

11. 验证方案

后端验证

• cargo check — 全 workspace 编译通过
• cargo test -p erp-ai — 单元测试覆盖 provider/sanitization/prompt/service
• 启动后端服务，通过 curl 测试 SSE 端点流式输出
• 通过 Swagger UI 测试 Prompt CRUD 和用量统计端点

小程序验证

• 打开报告详情页，确认「AI 解读」卡片展示
• 点击触发 SSE 流式渲染，确认逐字输出效果
• 测试缓存命中（第二次请求秒返回）
• 测试降级（停止 AI 服务后请求，确认降级提示）

安全验证

• 确认发送给 AI 的数据不包含 PII
• 确认速率限制生效（超过 10 次返回 429）
• 确认审计日志完整记录