docs(spec): 审查修正功能完善设计规格

修正审查发现的 CRITICAL/HIGH 问题：
- 后端 AI 端点空壳：标注需实现，新增 P0a-P0d 后端阶段
- 用户权限数据源缺失：新增 /auth/me/permissions 端点依赖
- 权限码映射修正：积分页面使用 health.points.*
- 组件路径修正：packages/ui-components → apps/web/src/components/
- 小程序路径调整：使用独立 ai-report/ 目录
- 菜单结构修正：扁平结构而非子菜单
- 补充版本回滚机制、安全降级、i18n 前缀约定

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

@@ -1,7 +1,7 @@
 # HMS 功能完善迭代设计规格
 
 > 日期: 2026-04-25
-> 状态: 已确认
+> 状态: 已确认（审查修正版）
 > 关联: `docs/superpowers/specs/2026-04-25-erp-ai-module-design.md`
 
 ## 1. 背景与目标
@@ -10,8 +10,8 @@
 
 HMS 健康管理平台已完成核心业务开发（237 次提交、57k 行 Rust + 174 前端文件），但存在以下功能缺口：
 
-- **按钮级权限控制缺失** — 路由守卫已有，但操作按钮（新增/编辑/删除）未做权限过滤
-- **AI 模块管理端空白** — 后端 6 个 API 端点已实现，但前端无管理页面
+- **按钮级权限控制缺失** — 路由守卫已有，但操作按钮（新增/编辑/删除）未做权限过滤；前端缺少权限数据源（`UserInfo` 接口不含 `permissions` 字段）
+- **AI 模块管理端空白** — 后端 6 个 API 端点中 4 个 SSE 流式端点可用，但 Prompt CRUD、分析历史查询、用量统计端点均为空壳或缺失
 - **小程序端 AI 不可见** — 患者无法查看 AI 分析报告
 
 ### 1.2 目标
@@ -29,7 +29,9 @@ HMS 健康管理平台已完成核心业务开发（237 次提交、57k 行 Rust
 ### 2.1 架构
 
 ```
-auth store (permissions: string[])
+后端新增 /api/v1/auth/me/permissions → 返回当前用户权限码列表
+    ↓
+auth store (permissions: string[]) ← 登录时从新端点加载
     ↓
 usePermission(code) → { hasPermission: boolean }
     ↓
@@ -39,6 +41,8 @@ usePermission(code) → { hasPermission: boolean }
 有权限 → 正常渲染子元素
 ```
 
+**前置依赖：** 当前 `UserInfo` 接口不含 `permissions` 字段（仅含 `roles`）。需后端新增 `/api/v1/auth/me/permissions` 端点，返回当前用户所有权限码的扁平列表（从角色 → 权限关联表聚合）。超级管理员（`is_system: true`）默认返回全部权限码。
+
 ### 2.2 组件设计
 
 **usePermission hook**
@@ -51,10 +55,11 @@ function usePermission(code: string): { hasPermission: boolean }
 
 - 从 auth store 读取当前用户 permissions 数组
 - 返回 code 是否在权限列表中
+- 权限数据加载失败时默认无权限（安全降级）
 
 **AuthButton 组件**
 
-位置: `packages/ui-components/src/AuthButton.tsx`
+位置: `apps/web/src/components/AuthButton.tsx`
 
 Props:
 - `code: string` — 权限码（如 `health.patient.manage`）
@@ -64,7 +69,7 @@ Props:
 
 **AuthGuard 组件**
 
-位置: `packages/ui-components/src/AuthGuard.tsx`
+位置: `apps/web/src/components/AuthGuard.tsx`
 
 Props:
 - `code: string` — 权限码
@@ -90,9 +95,9 @@ Props:
 | 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 |
+| PointsProductList | health.points.manage |
+| PointsOrderList | health.points.list |
+| PointsRuleList | health.points.manage |
 
 扩展到基础模块页面（Users, Roles, Organizations, Workflow 等）。
 
@@ -133,14 +138,16 @@ Props:
 位置: `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>
+// 后端需新增 Prompt CRUD 端点（当前仅有 service 层的 get_active_prompt + create_prompt）
+getPrompts(params: ListParams): Promise<PaginatedResponse<Prompt>>        // GET /api/v1/ai/prompts
+createPrompt(data: CreatePromptDto): Promise<Prompt>                      // POST /api/v1/ai/prompts
+updatePrompt(id: string, data: UpdatePromptDto): Promise<Prompt>          // PUT /api/v1/ai/prompts/{id}
+activatePrompt(id: string): Promise<Prompt>                               // POST /api/v1/ai/prompts/{id}/activate
+rollbackPrompt(id: string): Promise<Prompt>                               // POST /api/v1/ai/prompts/{id}/rollback
 ```
 
+**版本回滚机制：** 每次编辑 Prompt 创建新记录（递增 version），回滚 = 将目标旧版本 `is_active` 设为 `true` 并将当前激活版本 `is_active` 设为 `false`。不删除任何版本记录。
+
 **权限码：** `ai.prompt.list`（查看）、`ai.prompt.manage`（编辑/激活/回滚）
 
 ### 3.3 页面 B — 分析历史
@@ -161,8 +168,9 @@ rollbackPrompt(id: string): Promise<Prompt>
 位置: `apps/web/src/api/ai/analysis.ts`
 
 ```typescript
-getAnalysisHistory(params: AnalysisQueryParams): Promise<PaginatedResponse<Analysis>>
-getAnalysisDetail(id: string): Promise<Analysis>
+// 后端当前 list_analysis/get_analysis 为空壳（返回 ApiResponse::ok(())），需实现真实查询
+getAnalysisHistory(params: AnalysisQueryParams): Promise<PaginatedResponse<Analysis>>  // GET /api/v1/ai/analysis/history
+getAnalysisDetail(id: string): Promise<Analysis>                                       // GET /api/v1/ai/analysis/{id}
 ```
 
 **权限码：** `ai.analysis.list`（查看）、`ai.analysis.manage`（重新分析）
@@ -185,19 +193,21 @@ getAnalysisDetail(id: string): Promise<Analysis>
 位置: `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>>
+// 后端需完全新增：路由、handler、聚合 service
+// ai_usage_logs 表需增加 created_by 列（当前缺失 user_id），或复用 ai_analysis_results.created_by 做用户排行
+getUsageOverview(): Promise<UsageOverview>                                    // GET /api/v1/ai/usage/overview
+getUsageTrend(params: TrendParams): Promise<TrendData[]>                     // GET /api/v1/ai/usage/trend
+getUsageByType(): Promise<TypeDistribution[]>                                // GET /api/v1/ai/usage/by-type
+getUsageByUser(params: UserRankingParams): Promise<PaginatedResponse<UserUsage>>  // GET /api/v1/ai/usage/by-user
 ```
 
-**后端补充：** 需要在 erp-ai handler 中新增用量统计端点（当前仅有 list/get，需增加 aggregation）。
+**后端补充：** 需在 erp-ai 中新增用量统计聚合端点。优先方案：复用 `ai_analysis_results` 表的 `created_by` 字段做用户维度排行，避免修改 `ai_usage_logs` 表结构。如需精确 token 统计，后续可加迁移增加 `user_id` 列。
 
 **权限码：** `ai.usage.list`
 
 ### 3.5 菜单注册
 
-在 `apps/web/src/layouts/MainLayout.tsx` 健康管理菜单组下新增：
+在 `apps/web/src/layouts/MainLayout.tsx` 健康管理菜单组下新增 AI 分析入口。当前菜单为扁平结构（无子菜单折叠），新增项直接追加为同级菜单项：
 
 ```
 健康管理
@@ -206,13 +216,11 @@ getUsageByUser(params: UserRankingParams): Promise<PaginatedResponse<UserUsage>>
 ├── 预约管理
 ├── 随访管理
 ├── 咨询管理
-├── 文章管理
 ├── 积分商城
 ├── 统计看板
-└── AI 分析          ← 新增
-    ├── Prompt 管理
-    ├── 分析历史
-    └── 用量统计
+├── AI Prompt 管理   ← 新增（扁平）
+├── AI 分析历史      ← 新增（扁平）
+└── AI 用量统计      ← 新增（扁平）
 ```
 
 ### 3.6 验证标准
@@ -229,31 +237,32 @@ getUsageByUser(params: UserRankingParams): Promise<PaginatedResponse<UserUsage>>
 
 ### 4.1 新增页面
 
-**报告列表页**
+**AI 报告列表页**
 
-位置: `apps/miniprogram/src/pages/report/list.tsx`
+位置: `apps/miniprogram/src/pages/ai-report/list/index.tsx`
 
-- 调用 `/api/v1/ai/analysis/history?patient_id={currentPatientId}`
+- 调用 `GET /api/v1/ai/analysis/history` （后端需实现，根据 JWT user_id → patient_id 自动过滤）
 - 列表展示分析记录（类型图标 + 时间 + 状态标签）
 - 点击进入详情
 
-**报告详情页**
+**AI 报告详情页**
 
-位置: `apps/miniprogram/src/pages/report/detail.tsx`
+位置: `apps/miniprogram/src/pages/ai-report/detail/index.tsx`
 
-- 调用 `/api/v1/ai/analysis/{id}`
-- Markdown 渲染分析结果（使用 Taro rich-text 或 taro-markdown 组件）
+- 调用 `GET /api/v1/ai/analysis/{id}`
+- 使用 `taro-markdown` 组件渲染 Markdown 格式的分析结果（需先验证兼容性）
 - 底部展示分析时间和 token 用量信息
 
 ### 4.2 路由集成
 
 在首页（`pages/index/index.tsx`）健康数据区域增加"AI 报告"入口卡片。
 
-### 4.3 API 复用
+### 4.3 后端依赖
 
-后端端点已存在（`list_analysis` + `get_analysis`），无需新增。需确保：
-- 患者只能查看自己的分析记录（通过 JWT user_id → patient_id 过滤）
-- 响应数据中不含 PII
+后端 `list_analysis` 和 `get_analysis` 当前为空壳（仅验证权限后返回空值），需实现：
+- 根据 JWT 中的 user_id 查找关联 patient_id
+- 从 `ai_analysis_results` 表查询该患者的分析记录
+- 返回不含 PII 的脱敏结果
 
 ### 4.4 验证标准
 
@@ -268,15 +277,19 @@ getUsageByUser(params: UserRankingParams): Promise<PaginatedResponse<UserUsage>>
 
 | 阶段 | 内容 | 依赖 | 预计工作量 |
 |------|------|------|-----------|
-| 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 文件 |
+| P0a | 后端：新增 `/api/v1/auth/me/permissions` 端点 | 无 | erp-auth handler + service |
+| P0b | 后端：实现 Prompt CRUD 端点（list/create/update/activate/rollback） | 无 | erp-ai handler + service |
+| P0c | 后端：实现分析历史查询（list_analysis/get_analysis 从空壳到真实查询） | 无 | erp-ai handler + service |
+| P0d | 后端：新增用量统计聚合端点（overview/trend/by-type/by-user） | 无 | erp-ai handler + service + 可能迁移 |
+| P1 | 前端：usePermission hook + AuthButton/AuthGuard 组件 + auth store 加载 permissions | P0a | 3 文件 |
+| P2 | 前端：健康模块页面按钮权限改造 | P1 | 15 文件 |
+| P3 | 前端：AI API 封装（3 个 service 文件） | P0b-d | 3 文件 |
+| P4 | 前端：AI Prompt 管理页面 | P1, P3 | 1 文件 |
+| P5 | 前端：AI 分析历史页面 | P1, P3 | 1 文件 |
+| P6 | 前端：AI 用量统计页面 | P1, P3 | 1 文件 |
+| P7 | 前端：菜单注册 + 路由配置 | P4-P6 | 2 文件 |
+| P8 | 小程序：验证 taro-markdown 兼容性 + AI 报告列表/详情页 | P0c | 3 文件 |
+| P9 | 小程序：首页入口集成 | P8 | 1 文件 |
 
 ---
 
@@ -294,6 +307,7 @@ getUsageByUser(params: UserRankingParams): Promise<PaginatedResponse<UserUsage>>
 
 - 前端组件使用 Ant Design 6 现有组件
 - 图表使用 Ant Design Charts（项目已有依赖）
-- 小程序 Markdown 渲染使用社区 taro-markdown 组件或 rich-text
-- 后端新增聚合 API 遵循现有 handler/service 模式
-- 所有新页面使用 i18n key，不硬编码中文
+- 小程序 Markdown 渲染使用 taro-markdown 组件（P8 开始前验证兼容性）
+- 后端新增端点遵循现有 handler/service/entity 模式
+- 所有新页面使用 i18n key（前缀约定：`health.ai.*`），不硬编码中文
+- 权限数据加载失败时默认无权限（安全降级，宁可少显示按钮也不暴露越权操作）