---
title: erp-ai AI 分析模块
updated: 2026-04-25
status: in-development
tags: [ai, llm, sse, health-analysis, claude]
---

# 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)
- **数据脱敏** — 发送前自动移除患者 PII（姓名、身份证、手机号）

## 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
```

### 实体模型（3 个实体）

| 实体 | 用途 |
|------|------|
| ai_prompt | Prompt 模板（版本管理、激活/回滚） |
| ai_analysis | 分析结果记录（输入参数、输出摘要、token 用量） |
| ai_usage | 用量追踪（按租户/用户聚合） |

### 权限码（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_*()
  → sanitization: 移除 PII (姓名→患者, 身份证→***)
  → PromptService: 加载激活模板 + 渲染变量
  → AnalysisService: 编排分析流程
    → AiProvider::stream(): 调用 LLM API
    → 逐 chunk SSE 推送: data: { "content": "..." }
  → AnalysisService: 保存结果到 ai_analysis
  → UsageService: 记录 token 用量
  → SSE done
```

### 数据脱敏

发送给 LLM 的数据经过脱敏处理：
- 患者姓名 → "患者"
- 身份证号 → 全掩码
- 手机号 → `138****1234` 格式

### 模块依赖

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

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

## 4. 活跃问题 + 陷阱

### 当前状态: 🔧 开发中

6 个 API 端点已实现，SSE 流式分析可用。当前为 Phase 1 MVP。

### 待完善

| 问题 | 级别 | 说明 |
|------|------|------|
| 管理端前端页面 | P1 | Prompt 管理、分析历史、用量统计页面 |
| 小程序端集成 | P2 | 患者端查看 AI 分析结果 |
| 更多提供商 | P2 | 接入 OpenAI、本地模型等 |
| 用量配额限制 | P1 | 按租户设置用量上限 |

## 5. 变更记录

| 日期 | 变更 |
|------|------|
| 2026-04-25 | 创建 erp-ai wiki 页面 |