hms/wiki/erp-ai.md

title, updated, status, tags

title	updated	status	tags
erp-ai AI 分析模块	2026-05-05	in-development	ai llm sse health-analysis ollama

erp-ai AI 分析模块

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

设计规格: docs/superpowers/specs/2026-04-25-erp-ai-module-design.md

1. 设计决策

为什么需要 AI 模块？

健康管理平台需要为医护人员提供智能辅助分析能力：化验单解读、健康趋势分析、体检方案推荐、报告摘要生成。这些能力需要一个独立的模块来管理 AI 提供商、Prompt 模板和用量追踪。

核心架构选择

• 原生 Rust crate — 与 erp-health 同级，直接调用数据库和事件总线
• ErpModule trait 实现 — AiModule 在 erp-server 注册，路由挂载到 /api/v1/ai
• SSE 流式响应 — 所有分析端点使用 Server-Sent Events 实时推送
• 多提供商支持 — AiProvider trait 抽象，已实现 Claude (Anthropic)、Ollama (本地)、OpenAI
• 数据脱敏 — 发送前自动移除患者 PII（姓名、身份证、手机号）
• 分析预校验 — 触发分析前校验数据完整性，items/sections 为空时直接返回 400
• 非对话化 Prompt — 迁移 000123 更新所有 prompt 为结构化输出格式

2. 关键文件 + 数据流

目录结构

crates/erp-ai/
├── src/
│   ├── lib.rs              ← 模块导出 (AiModule, AiState, AiError)
│   ├── module.rs           ← ErpModule trait 实现, 6 权限码, 路由定义
│   ├── error.rs            ← AiError → AppError (59 行)
│   ├── state.rs            ← AiState { db, event_bus, provider }
│   ├── dto.rs              ← 请求/响应 DTO (102 行)
│   ├── provider/
│   │   ├── mod.rs          ← AiProvider trait 定义
│   │   └── claude.rs       ← Claude SSE 流式实现 (227 行)
│   ├── service/
│   │   ├── analysis.rs     ← AnalysisService 核心编排 (183 行)
│   │   ├── prompt.rs       ← PromptService 模板渲染 (67 行)
│   │   └── usage.rs        ← UsageService 用量追踪 (45 行)
│   ├── handler/
│   │   └── mod.rs          ← 6 个 SSE + REST 端点 (340 行)
│   ├── prompt/
│   │   └── mod.rs          ← Prompt 模板引擎 (25 行)
│   └── entity/
│       ├── ai_prompt.rs    ← Prompt 模板 Entity
│       ├── ai_analysis.rs  ← 分析结果 Entity
│       └── ai_usage.rs     ← 用量日志 Entity

实体模型（6 个实体）

实体	用途
ai_prompt	Prompt 模板（版本管理、激活/回滚）
ai_analysis	分析结果记录（输入参数、输出摘要、token 用量）
ai_usage	用量追踪（按租户/用户聚合）
ai_suggestion	AI 建议记录（风险分级、建议内容、状态跟踪）
ai_risk_threshold	风险阈值配置（按指标定义临界值）
ai_action	AI 行动分发（从建议到行动的闭环跟踪）

权限码（6 个）

权限码	说明
ai.analysis.list / ai.analysis.manage	查看分析历史 / 发起分析
ai.prompt.list / ai.prompt.manage	查看 Prompt / 管理 Prompt
ai.usage.list	查看用量统计
ai.provider.manage	管理提供商配置

API 端点: /api/v1/ai/

端点	方法	说明
/ai/analyze/lab-report	POST	化验单智能解读（SSE）
/ai/analyze/trends	POST	健康趋势分析（SSE）
/ai/analyze/checkup-plan	POST	体检方案推荐（SSE）
/ai/analyze/report-summary	POST	报告摘要生成（SSE）
/ai/analysis/history	GET	分析历史列表
/ai/analysis/{id}	GET	分析结果详情

集成契约

方向	模块	接口	触发时机
依赖 →	erp-health	健康数据查询	分析时读取患者数据
依赖 →	erp-core	EventBus, AppError	模块注册
注册 →	erp-server	AiModule	启动时注册

3. 代码逻辑

SSE 流式分析流程

客户端 POST → handler::stream_*()
  → 预校验: items/sections 为空 → 400 直接拒绝
  → sanitization: 移除 PII (姓名→患者, 身份证→***)
  → PromptService: 加载激活模板 + 渲染变量
  → AnalysisService: 编排分析流程
    → 检查缓存: 相同输入 + prompt 版本 → 复用已有结果（直接回放纯文本）
    → AiProvider::stream(): 调用 LLM API（Ollama/Claude/OpenAI）
    → 逐 chunk SSE 推送: data: { "content": "..." }
  → AnalysisService: 保存结果到 ai_analysis（已完成的跳过）
  → 后处理: 解析建议、发布事件
  → SSE done

数据脱敏

发送给 LLM 的数据经过脱敏处理：

• 患者姓名 → "患者"
• 身份证号 → 全掩码
• 手机号 → 138****1234 格式

模块依赖

AiModule 声明依赖 ["health"]，确保健康模块先于 AI 模块初始化。

⚡ 不变量: 所有发送到外部 LLM 的数据必须经过 PII 脱敏 ⚡ 不变量: SSE 连接超时必须设置，避免挂起 ⚡ 不变量: 用量追踪必须记录，用于计费和审计

4. Ollama 本地模型对接

配置方式

crates/erp-server/config/default.toml:

[ai]
default_provider = "ollama"
model = "qwen3:4b"

[ai.providers.ollama]
provider_type = "ollama"
base_url = "http://localhost:11434"
default_model = "qwen3:4b"
max_tokens = 2048
temperature = 0.3
is_enabled = true

已知限制

问题	说明
qwen3-vl:4b 无法运行	Ollama 已知 bug（#13101），VL 模型内存估算异常（3.3GB 模型要求 38.3 GiB）
qwen3:4b 思考模式	模型内置 <think/> 标签，首次响应可能延迟
无图像识别能力	当前所有分析使用结构化数据库数据，不需要 VL 模型
Prompt 模板 model_config	DB 中 ai_prompt.model_config.model 优先级高于全局配置，需同步更新

已修复的 bug

Bug	修复
缓存回放 JSON 嵌套	replay_cached 直接回放纯文本；complete_analysis 跳过已完成记录
分析返回对话式回复	迁移 000123 更新 prompt 为非对话、结构化输出
空数据触发无效分析	handler 层预校验 items/sections 非空

5. 活跃问题 + 陷阱

当前状态: 🔧 开发中

6 个 API 端点已实现，SSE 流式分析可用，已对接本地 Ollama。前端 3 个管理页面已实现（Prompt 管理、分析历史、用量统计）。当前为 Phase 1 MVP。

待完善

问题	级别	说明
小程序端集成	P2	患者端查看 AI 分析结果
用量配额限制	P1	按租户设置用量上限
化验报告必填项	P1	后端校验已加，前端录入表单也应对应设置必填

6. 变更记录

日期	变更
2026-05-05	对接本地 Ollama qwen3:4b；修复缓存回放 JSON 嵌套 bug；预校验 + prompt 非对话化
2026-04-25	创建 erp-ai wiki 页面