hms/docs/superpowers/specs/2026-04-25-feature-completion-design.md

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