# 全系统走查问题修复 — 多专家组头脑风暴

> 日期: 2026-05-03 | 参与者: 架构组 + 测试组 + 产品组

## 背景

基于 `docs/discussions/2026-05-03-full-system-walkthrough.md` 的走查结果，35+ 页面发现 P0 问题 4 项、P1 问题 6 项、P2 建议 4 项。三个专家组分别从架构/前端、质量/测试、产品/UX 视角进行深度分析和方案设计。

## 议题 1：EntityName 解析失败（P0 — A1/A4）

### 根因分析

**架构组发现：**

1. `EntityName` 组件是纯展示组件，依赖调用方传入 `name` prop
2. 告警/咨询/AI 分析页面的后端 DTO 缺少反规范化字段（如 `patient_name`、`doctor_name`）
3. 前端已有 `resolvePatientName` store 方法（health store），但告警/咨询页面未调用

**影响范围：** 告警列表/仪表盘、咨询列表/详情、AI 分析历史、行动收件箱

### 修复方案：3 层方案

| 层级 | 方案 | 耗时 | 详情 |
|------|------|------|------|
| 后端 | 告警/咨询/AI 分析的 list API 添加 JOIN 查询 | 1-2 天 | 返回 `patient_name`、`doctor_name` 反规范化字段，避免前端 N+1 查询 |
| 前端 | 枚举映射补全 | 0.5 天 | `SEVERITY_LABEL` 加 `high/medium`，`ALERT_STATUS_LABEL` 加 `active` |
| 前端 | 设备管理改造 | 0.5 天 | 患者ID输入改为 `PatientSelect` 搜索组件 |

### 决策：后端补充反规范化字段 vs 前端 batch 解析

**结论：后端 JOIN 方案。** 原因：
- 避免 N+1 查询（告警列表可能有 50+ 条，每条解析患者名 = 50 次 API 调用）
- 已有先例：预约列表 API 已 JOIN 返回 `patient_name`、`doctor_name`
- 保持 EntityName 组件简单（纯展示），复杂度在数据层解决

---

## 议题 2：数据展示层缺陷（P0 — A2/A3, P1 — B1/B3）

### 测试组发现

| 问题 | 文件 | 详情 |
|------|------|------|
| 医护人数硬编码 0 | `AdminDashboard.tsx` L17 | `useCountUp(0)` 无 API 调用，后端无医护统计端点 |
| 严重程度枚举缺失 | `constants/health.ts` | `SEVERITY_LABEL` 定义了 `info/warning/critical/urgent`，但后端用 `high/medium` |
| 告警状态枚举缺失 | `constants/health.ts` | `ALERT_STATUS_LABEL` 缺 `active` 状态 |
| EntityName 零测试 | `components/EntityName.tsx` | 无测试文件，无法验证 fallback 行为 |
| 工作台服务状态卡 | `Home.tsx` / `AdminDashboard.tsx` | health check API 可能未正确配置或前端轮询间隔不合理 |

### 修复方案

1. **后端新增医护统计 API** — `GET /api/v1/health/doctors/stats` 返回总数/在线数
2. **枚举映射统一** — 对照后端 `AlertSeverity` enum 补全前端常量映射
3. **EntityName 测试** — 单元测试覆盖 3 条路径：name 存在 / name 缺失 fallback / loading 状态

---

## 议题 3：AI SSE 端点无前端入口（P1）

### 现状

后端已实现 4 个 SSE 端点：
- `POST /api/v1/health/ai/analysis/stream` — 智能分析
- `POST /api/v1/health/ai/trends/stream` — 趋势分析
- `POST /api/v1/health/ai/interpretation/stream` — 化验单解读
- `POST /api/v1/health/ai/summary/stream` — 报告摘要

前端无任何触发入口。

### 产品组建议：嵌入工作流而非独立页面

**理由：** AI 分析是辅助工具，不应有独立管理页面。用户在处理具体业务时触发 AI 更自然。

**集成方案：**

| 触发点 | SSE 端点 | 展示位置 |
|--------|----------|----------|
| 患者详情 → "AI 健康分析"按钮 | analysis/stream | 患者详情页内嵌结果面板 |
| 患者详情 → 健康数据 Tab | trends/stream | 趋势图表上方"AI 解读"折叠面板 |
| 患者详情 → 化验单 Tab | interpretation/stream | 化验单详情下方"AI 解读"区域 |
| 随访完成 → 自动生成摘要 | summary/stream | 随访记录详情页 |

**耗时估计：** 3-5 天（含 SSE 连接管理、错误处理、结果持久化）

---

## 议题 4：行动收件箱扩展

### 现状

行动收件箱当前聚合：告警处理 + AI 建议。产品组认为应扩展为统一工作台。

### 扩展建议

| 新增类型 | 来源 | 优先级 |
|----------|------|--------|
| 预约确认待办 | 预约状态变更 → 未确认 | 高 |
| 咨询回复提醒 | 新咨询消息 | 高 |
| 随访到期预警 | 随访任务截止日期 | 中 |
| 积分兑换审核 | 积分订单状态 | 低 |

**技术方案：** 后端 `action_inbox` 表已支持 `source_type` + `source_id` 多态关联，只需扩展事件消费者。

**耗时：** 2-3 天（新增 3 个事件消费者 + 前端筛选器扩展）

---

## 综合行动清单

### 止血（P0，总计 2-3 天）

| # | 任务 | 耗时 | 负责 |
|---|------|------|------|
| 1 | 告警/咨询 list API 添加 JOIN 返回 patient_name/doctor_name | 1 天 | 后端 |
| 2 | 告警/AI/咨询前端页面使用反规范化字段 | 0.5 天 | 前端 |
| 3 | 枚举映射补全（severity + status） | 0.5 天 | 前端 |
| 4 | 医护统计 API + Dashboard 对接 | 0.5 天 | 全栈 |

### 补短板（P1，总计 4-6 天）

| # | 任务 | 耗时 | 负责 |
|---|------|------|------|
| 5 | AI SSE 前端集成（嵌入患者详情/工作流） | 3-5 天 | 全栈 |
| 6 | 设备管理患者选择器改造 | 0.5 天 | 前端 |
| 7 | 排班管理空状态引导 | 0.5 天 | 前端 |

### 治本（P2，总计 3-4 天）

| # | 任务 | 耗时 | 负责 |
|---|------|------|------|
| 8 | EntityName 组件测试 + 枚举覆盖测试 | 1 天 | 测试 |
| 9 | 行动收件箱扩展（预约/咨询/随访聚合） | 2-3 天 | 全栈 |

---

## 结论 / 待定

### 共识

1. **后端 JOIN 优于前端 batch** — 反规范化字段是解决 EntityName 问题的正确方式
2. **AI SSE 嵌入工作流** — 不做独立管理页面，在患者详情/随访流程中触发
3. **行动收件箱是正确的统一工作台方向** — 逐步聚合各模块待办
4. **止血优先于新功能** — 先修复 P0 展示问题，再推进 AI 集成

### 待讨论

1. 医护统计 API 是否需要按科室/职称分组，还是只返回总数？
2. AI SSE 结果是否持久化到数据库（当前只在前端展示）？
3. 行动收件箱是否需要实时推送（WebSocket），还是轮询即可？
4. 测试数据清理策略 — 是否提供 E2E_* 记录清理脚本？