docs(wiki+spec): 项目全景分析 + 功能完善设计规格

- 新增 wiki/erp-ai.md (AI 模块知识库页面) - 修正 wiki/index.md 数据不一致 (crate 数 16、迁移 55、模块含 ai) - 更新 wiki/erp-server.md (7 模块注册) - 新增功能完善设计规格 (按钮权限 + AI 3 页面 + 小程序报告)
2026-04-25 20:22:24 +08:00
parent d2baacae7e
commit d22ad6088a
4 changed files with 457 additions and 11 deletions
--- a/wiki/erp-ai.md
+++ b/wiki/erp-ai.md
@@ -0,0 +1,143 @@
+---
+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 页面 |
--- a/wiki/erp-server.md
+++ b/wiki/erp-server.md
@@ -39,9 +39,9 @@ AppConfig::load() → 安全检查 → init_tracing → db::connect → Migrator
  → 构建Router → bind + serve → 优雅关闭(CTRL+C/SIGTERM)
 ```

-### 注册的 6 个模块
+### 注册的 7 个模块

-AuthModule → ConfigModule → WorkflowModule → MessageModule → PluginModule → **HealthModule**
+AuthModule → ConfigModule → WorkflowModule → MessageModule → PluginModule → **HealthModule** → **AiModule**

 ### AppState

@@ -69,6 +69,7 @@ AppState {
 | 组装 → | erp-message | `MessageModule` | 启动时注册 |
 | 组装 → | erp-plugin | `PluginModule` | 启动时注册 |
 | 组装 → | [[erp-health]] | `HealthModule` | 启动时注册 |
+| 组装 → | [[erp-ai]] | `AiModule` | 启动时注册 |
 | 依赖 ← | [[erp-core]] | ErpModule trait, EventBus | 所有模块 |
 | 依赖 ← | [[infrastructure]] | PostgreSQL, Redis | 连接 |

--- a/wiki/index.md
+++ b/wiki/index.md
@@ -6,16 +6,18 @@

 | 指标 | 值 |
 |------|-----|
-| Rust crate | 15 个（7 核心 + erp-health + 6 插件 + erp-plugin-prototype） |
-| 数据库表 | 30 基础表 + 18 健康业务表（已实现） |
-| 数据库迁移 | 50 个 |
-| 核心模块 | 5 基础 (auth/config/workflow/message/plugin) + 1 业务 (health) |
-| Web 前端页面 | 30 路由（含 10 健康管理路由） |
-| 健康模块组件 | 11 个共享组件（StatusTag/PatientSelect/DoctorSelect/VitalSignsChart 等） |
-| 微信小程序 | Taro 4.2 + React 18，20 个页面 |
+| Rust crate | 16 个（erp-core + 6 基础业务 + erp-health + erp-ai + 6 插件 + erp-plugin-prototype） |
+| 数据库表 | 30 基础表 + 18 健康业务表 + 3 AI 表（已实现） |
+| 数据库迁移 | 55 个 |
+| 核心模块 | 5 基础 (auth/config/workflow/message/plugin) + 2 业务 (health + ai) |
+| Web 前端页面 | 62 个 TSX 组件（含 15 健康管理页面） |
+| 健康模块组件 | 12 个共享组件（StatusTag/PatientSelect/DoctorSelect/VitalSignsChart 等） |
+| 微信小程序 | Taro 4.2 + React 18，27 个页面 |
 | 前端单元测试 | 3 个（vitest）+ 4 E2E spec（playwright） |
 | 后端测试 | 36 个（workspace）+ 57 validation 纯函数测试 |
+| 总代码量 | Rust ~57k 行 + 前端 TSX/TS ~174 文件 |
 | API 文档 | `http://localhost:3000/api/docs/openapi.json` |
+| Git 提交 | 237 次 |

 ## 症状导航

@@ -51,9 +53,10 @@

 ### 核心业务层（HMS 专属）
 - [[erp-health]] — **患者管理 · 健康数据 · 预约排班 · 随访管理 · 咨询管理**（原生 Rust 模块，已实现）
+- [[erp-ai]] — **AI 智能分析 · 化验单解读 · 趋势分析 · 报告摘要**（原生 Rust 模块，开发中）

 ### 组装层
- [[erp-server]] — Axum 入口 · AppState · 6 模块注册 · 后台任务 · 优雅关闭
+- [[erp-server]] — Axum 入口 · AppState · 7 模块注册 · 后台任务 · 优雅关闭

 ### 患者端
 - [[miniprogram]] — **微信小程序** · Taro 4.2 · 微信登录 · 手机绑定 · 健康数据查看
@@ -61,7 +64,7 @@
 ### 基础设施
 - [[infrastructure]] — 连接信息 · 环境变量 · 一键启动 (**单一真相源**)
 - [[database]] — SeaORM 迁移 · 多租户表结构
- [[frontend]] — React 19 SPA · 健康管理页面（13 页面 + 11 组件）
+- [[frontend]] — React 19 SPA · 健康管理页面（15 页面 + 12 组件）
 - [[testing]] — 验证清单 · 测试分布 · 性能基准

 ## 核心架构问答