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/docs/superpowers/specs/2026-04-25-feature-completion-design.md
+++ b/docs/superpowers/specs/2026-04-25-feature-completion-design.md
@@ -0,0 +1,299 @@
+# HMS 功能完善迭代设计规格
+
+> 日期: 2026-04-25
+> 状态: 已确认
+> 关联: `docs/superpowers/specs/2026-04-25-erp-ai-module-design.md`
+
+## 1. 背景与目标
+
+### 1.1 项目现状
+
+HMS 健康管理平台已完成核心业务开发（237 次提交、57k 行 Rust + 174 前端文件），但存在以下功能缺口：
+
+- **按钮级权限控制缺失** — 路由守卫已有，但操作按钮（新增/编辑/删除）未做权限过滤
+- **AI 模块管理端空白** — 后端 6 个 API 端点已实现，但前端无管理页面
+- **小程序端 AI 不可见** — 患者无法查看 AI 分析报告
+
+### 1.2 目标
+
+通过纵向切片方式逐步交付三个功能域，每个切片从前到后完整打通：
+
+1. **切片 1：按钮级权限** — 基础设施，后续页面的前置依赖
+2. **切片 2：AI 管理端** — 3 个 PC 管理页面
+3. **切片 3：小程序报告** — 患者端只读查看
+
+---
+
+## 2. 切片 1：按钮级权限控制
+
+### 2.1 架构
+
+```
+auth store (permissions: string[])
+    ↓
+usePermission(code) → { hasPermission: boolean }
+    ↓
+<AuthButton code="health.patient.manage"> ... </AuthButton>
+    ↓
+无权限 → 不渲染（hidden 模式）
+有权限 → 正常渲染子元素
+```
+
+### 2.2 组件设计
+
+**usePermission hook**
+
+位置: `apps/web/src/hooks/usePermission.ts`
+
+```typescript
+function usePermission(code: string): { hasPermission: boolean }
+```
+
+- 从 auth store 读取当前用户 permissions 数组
+- 返回 code 是否在权限列表中
+
+**AuthButton 组件**
+
+位置: `packages/ui-components/src/AuthButton.tsx`
+
+Props:
+- `code: string` — 权限码（如 `health.patient.manage`）
+- `children: ReactNode` — 受保护的按钮内容
+
+行为: 无权限时不渲染 children（hidden 模式）。
+
+**AuthGuard 组件**
+
+位置: `packages/ui-components/src/AuthGuard.tsx`
+
+Props:
+- `code: string` — 权限码
+- `children: ReactNode` — 受保护的内容块
+
+行为: 同 AuthButton，用于包裹非按钮内容（如整个 Tab、区块）。
+
+### 2.3 改造范围
+
+优先改造健康模块 15 个页面中的操作按钮：
+
+| 页面 | 按钮权限码 |
+|------|-----------|
+| PatientList | health.patient.manage |
+| PatientDetail | health.patient.manage |
+| AppointmentList | health.appointment.manage |
+| DoctorList | health.doctor.manage |
+| DoctorSchedule | health.doctor.manage |
+| FollowUpTaskList | health.follow-up.manage |
+| FollowUpRecordList | health.follow-up.manage |
+| ConsultationList | health.consultation.manage |
+| ConsultationDetail | health.consultation.manage |
+| OfflineEventList | health.articles.manage |
+| PatientTagManage | health.patient.manage |
+| StatisticsDashboard | health.health-data.list (只读) |
+| PointsProductList | health.articles.manage |
+| PointsOrderList | health.articles.list |
+| PointsRuleList | health.articles.manage |
+
+扩展到基础模块页面（Users, Roles, Organizations, Workflow 等）。
+
+### 2.4 验证标准
+
+- [ ] 无权限用户看不到操作按钮
+- [ ] 有权限用户操作正常
+- [ ] 权限变更后界面实时更新（无需刷新）
+
+---
+
+## 3. 切片 2：AI 管理端 3 页面
+
+### 3.1 路由设计
+
+```
+/health/ai/prompts     → Prompt 管理
+/health/ai/analysis    → 分析历史
+/health/ai/usage       → 用量统计
+```
+
+### 3.2 页面 A — Prompt 管理
+
+位置: `apps/web/src/pages/health/AiPromptList.tsx`
+
+**功能清单：**
+
+| 功能 | 说明 |
+|------|------|
+| 列表展示 | 表格：名称/类型（化验单解读、趋势分析、体检方案、报告摘要）/版本号/状态（active/draft）/更新时间 |
+| 新建 Prompt | Modal 表单：名称、类型（下拉）、系统提示词、用户提示词模板（支持 `{{variable}}` 占位符） |
+| 编辑 Prompt | 同新建，自动递增版本号 |
+| 激活/停用 | 切换按钮，激活时停用同类型旧模板 |
+| 版本历史 | 展开行显示所有历史版本，支持一键回滚 |
+
+**API 封装：**
+
+位置: `apps/web/src/api/ai/prompts.ts`
+
+```typescript
+// 对应后端已有的 ai_prompt 实体 CRUD
+getPrompts(params: ListParams): Promise<PaginatedResponse<Prompt>>
+createPrompt(data: CreatePromptDto): Promise<Prompt>
+updatePrompt(id: string, data: UpdatePromptDto): Promise<Prompt>
+activatePrompt(id: string): Promise<Prompt>
+rollbackPrompt(id: string): Promise<Prompt>
+```
+
+**权限码：** `ai.prompt.list`（查看）、`ai.prompt.manage`（编辑/激活/回滚）
+
+### 3.3 页面 B — 分析历史
+
+位置: `apps/web/src/pages/health/AiAnalysisList.tsx`
+
+**功能清单：**
+
+| 功能 | 说明 |
+|------|------|
+| 列表展示 | 表格：分析类型/患者姓名/状态（streaming/completed/failed）/创建时间/token 用量 |
+| 详情查看 | 点击行展开/Modal 展示完整分析结果（Markdown 渲染） |
+| 筛选 | 按类型（4 种）、时间范围（DateRangePicker）、患者（PatientSelect 组件复用） |
+| 重新分析 | 对 failed 记录支持重新发起分析 |
+
+**API 封装：**
+
+位置: `apps/web/src/api/ai/analysis.ts`
+
+```typescript
+getAnalysisHistory(params: AnalysisQueryParams): Promise<PaginatedResponse<Analysis>>
+getAnalysisDetail(id: string): Promise<Analysis>
+```
+
+**权限码：** `ai.analysis.list`（查看）、`ai.analysis.manage`（重新分析）
+
+### 3.4 页面 C — 用量统计
+
+位置: `apps/web/src/pages/health/AiUsageDashboard.tsx`
+
+**功能清单：**
+
+| 功能 | 说明 |
+|------|------|
+| 概览卡片 | 4 张 StatCard：总用量/本月/今日/平均 token |
+| 趋势图 | Ant Design Charts 折线图，按日/周/月切换 |
+| 类型分布 | 饼图展示 4 种分析类型的占比 |
+| 用户排行 | 表格展示用户维度用量排名 |
+
+**API 封装：**
+
+位置: `apps/web/src/api/ai/usage.ts`
+
+```typescript
+getUsageOverview(): Promise<UsageOverview>
+getUsageTrend(params: TrendParams): Promise<TrendData[]>
+getUsageByType(): Promise<TypeDistribution[]>
+getUsageByUser(params: UserRankingParams): Promise<PaginatedResponse<UserUsage>>
+```
+
+**后端补充：** 需要在 erp-ai handler 中新增用量统计端点（当前仅有 list/get，需增加 aggregation）。
+
+**权限码：** `ai.usage.list`
+
+### 3.5 菜单注册
+
+在 `apps/web/src/layouts/MainLayout.tsx` 健康管理菜单组下新增：
+
+```
+健康管理
+├── 患者管理
+├── 医护管理
+├── 预约管理
+├── 随访管理
+├── 咨询管理
+├── 文章管理
+├── 积分商城
+├── 统计看板
+└── AI 分析          ← 新增
+    ├── Prompt 管理
+    ├── 分析历史
+    └── 用量统计
+```
+
+### 3.6 验证标准
+
+- [ ] Prompt CRUD 全流程可用（创建/编辑/激活/回滚）
+- [ ] 分析历史可筛选、可查看详情（Markdown 正确渲染）
+- [ ] 用量统计图表数据正确
+- [ ] 所有操作按钮受 AuthButton 权限控制
+- [ ] 页面响应式布局正常
+
+---
+
+## 4. 切片 3：小程序 AI 报告查看
+
+### 4.1 新增页面
+
+**报告列表页**
+
+位置: `apps/miniprogram/src/pages/report/list.tsx`
+
+- 调用 `/api/v1/ai/analysis/history?patient_id={currentPatientId}`
+- 列表展示分析记录（类型图标 + 时间 + 状态标签）
+- 点击进入详情
+
+**报告详情页**
+
+位置: `apps/miniprogram/src/pages/report/detail.tsx`
+
+- 调用 `/api/v1/ai/analysis/{id}`
+- Markdown 渲染分析结果（使用 Taro rich-text 或 taro-markdown 组件）
+- 底部展示分析时间和 token 用量信息
+
+### 4.2 路由集成
+
+在首页（`pages/index/index.tsx`）健康数据区域增加"AI 报告"入口卡片。
+
+### 4.3 API 复用
+
+后端端点已存在（`list_analysis` + `get_analysis`），无需新增。需确保：
+- 患者只能查看自己的分析记录（通过 JWT user_id → patient_id 过滤）
+- 响应数据中不含 PII
+
+### 4.4 验证标准
+
+- [ ] 患者可查看自己的 AI 分析历史
+- [ ] 详情页 Markdown 正确渲染
+- [ ] 无法查看其他患者的报告
+- [ ] 无报告时显示空状态提示
+
+---
+
+## 5. 实施顺序
+
+| 阶段 | 内容 | 依赖 | 预计工作量 |
+|------|------|------|-----------|
+| P1 | usePermission hook + AuthButton/AuthGuard 组件 | 无 | 2 文件 |
+| P2 | 健康模块 15 页面按钮权限改造 | P1 | 15 文件 |
+| P3 | AI API 前端封装（3 个 service 文件） | 无 | 3 文件 |
+| P4 | AI Prompt 管理页面 | P1, P3 | 1 文件 |
+| P5 | AI 分析历史页面 | P1, P3 | 1 文件 |
+| P6 | AI 用量统计页面 + 后端聚合 API | P1, P3 | 2 文件 |
+| P7 | 菜单注册 + 路由配置 | P4-P6 | 2 文件 |
+| P8 | 小程序报告列表 + 详情页 | P3 | 2 文件 |
+| P9 | 小程序首页入口集成 | P8 | 1 文件 |
+
+---
+
+## 6. 非目标（明确排除）
+
+- 不涉及 CI/CD 流水线建设（属于安全与稳定性方向）
+- 不涉及 erp-plugin unwrap 修复（属于代码质量方向）
+- 不涉及 TypeScript strict 模式开启（属于质量方向，单独处理）
+- 不涉及新的 AI 提供商接入（仅使用现有 Claude 提供商）
+- 不涉及用量配额/计费功能（后续迭代）
+
+---
+
+## 7. 技术约束
+
+- 前端组件使用 Ant Design 6 现有组件
+- 图表使用 Ant Design Charts（项目已有依赖）
+- 小程序 Markdown 渲染使用社区 taro-markdown 组件或 rich-text
+- 后端新增聚合 API 遵循现有 handler/service 模式
+- 所有新页面使用 i18n key，不硬编码中文
--- 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]] — 验证清单 · 测试分布 · 性能基准

 ## 核心架构问答