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

- 新增 wiki/erp-ai.md (AI 模块知识库页面)
- 修正 wiki/index.md 数据不一致 (crate 数 16、迁移 55、模块含 ai)
- 更新 wiki/erp-server.md (7 模块注册)
- 新增功能完善设计规格 (按钮权限 + AI 3 页面 + 小程序报告)

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，不硬编码中文