# 健康管家工作台 — 方案 B「工作流驱动」设计规格

> 日期: 2026-05-02 | 状态: 设计中（评审后修订 v2）
> 原型参考: `_temp/workbench-health-manager-B.html`
> 评审记录: 发现 7 CRITICAL + 5 IMPORTANT，已全部修复

## 1. 背景与目标

### 1.1 为什么要重新设计

现有工作台（方案 A/D/E/F）基于「临床医生管理透析团队」的假设设计。实际用户场景已明确：

- 机构已有 HIS + 专用血透系统，HMS 不碰临床透析流程
- HMS 定位是**患者与机构之间的纽带**：日常健康数据采集、随访干预、积分运营、健康科普
- 工作台的第一用户是**健康管家/随访护士**，不是做透析的医生

### 1.2 目标

| 指标 | 当前 | 目标 |
|------|------|------|
| 健康管家每日任务处理效率 | 无专门工作台，散落在各页面 | 统一入口，一件一件处理 |
| 任务遗漏率 | 未知（无追踪） | ≤2%（系统强制排序 + 超时提醒） |
| AI 建议触达率 | 有 AI 洞察面板但无强制处理流程 | 任务流中自动注入，100% 触达 |
| 平均任务响应时间 | 无数据 | 危急 ≤30min，紧急 ≤2h，普通 ≤24h |

### 1.3 范围

**分两期实施：**

| 阶段 | 任务类型 | 数据源状态 |
|------|---------|-----------|
| **Phase 1（本期）** | 体征告警、AI 建议待审、到期随访 | ✅ 现有 `action_inbox_service.rs` 已聚合 |
| **Phase 2（后续）** | 患者咨询、积分审批、体征少报提醒、干预评估 | ⏳ 需扩展数据源或新建调度 |

- **本期（Phase 1）**：健康管家/随访护士角色，3 种任务类型，三栏工作流布局
- **不在本期**：医生角色、运营角色、方案 A/C、Phase 2 任务类型

## 2. 角色定义 — 健康管家「刘小燕」

### 2.1 人物画像

| 维度 | 描述 |
|------|------|
| 姓名 | 刘小燕 |
| 职位 | 主管护师 / 健康管家 |
| 年龄 | 32 岁 |
| 工作经验 | 8 年护理，3 年健康管理 |
| 技术水平 | 熟练使用手机 App，PC 端基本操作无障碍 |
| 日均任务量 | 20-30 项（随访 8-12、体征审核 4-6、AI 建议 3-5、其他 3-5） |

### 2.2 典型工作日

```
08:00  打开工作台，按优先级处理紧急体征告警
08:30  逐个处理血压/血糖异常告警（电话随访 + 记录）
10:00  处理 AI 建议待审（审核并采纳或转给医生）
14:00  处理到期随访任务（电话/微信随访 + 记录）
16:00  回复患者咨询、处理积分兑换等（跳转对应模块）
17:00  检查今日完成情况，确认无遗漏后下班
```

### 2.3 核心痛点

1. **任务分散**：随访、体征、AI 建议散落在不同菜单，频繁切换
2. **优先级不清**：不知道该先处理哪个，容易遗漏紧急告警
3. **上下文缺失**：处理一个告警时需要单独打开患者详情查看历史
4. **AI 建议利用率低**：AI 面板在角落，不强制处理，容易被忽略

## 3. 信息架构 — 三栏布局

### 3.1 布局结构

**注意**：侧边栏由全局布局提供（`apps/web/src/layouts/`），工作台页面内部只有两栏（任务队列 + 详情面板）。

```
┌──────────────────────────────────────────────────────────┐
│  全局侧边栏（已有，不动）  │  工作台页面内部               │
│                          │                               │
│  ...                     │ ┌────────────┬──────────────┐ │
│  ⚡ 工作流（高亮）         │ │ 任务队列    │ 详情处理面板  │ │
│  📋 随访管理              │ │ 340px      │ flex:1       │ │
│  🩺 体征监测              │ │            │              │ │
│  💬 患者咨询              │ │ 头部统计    │ 患者信息栏    │ │
│  ...                     │ │ Tab 切换    │ 异常数据      │ │
│                          │ │ 任务列表    │ AI 建议       │ │
│                          │ │            │ 互动记录      │ │
│                          │ │            │ 操作按钮      │ │
│                          │ └────────────┴──────────────┘ │
└──────────────────────────────────────────────────────────┘
```

### 3.2 两栏职责

| 区域 | 职责 | 交互 |
|------|------|------|
| **任务队列** | 按优先级排列的待处理任务 + 统计 | 点击选中 → 右侧加载详情 |
| **详情面板** | 当前任务的完整上下文 + 操作 | 处理完成后自动跳转下一任务 |

### 3.3 全局侧边栏菜单调整

在现有全局侧边栏中，将「工作台」菜单项更名为「工作流」，点击进入方案 B 的三栏工作台。其他菜单项不变。

## 4. 组件清单

### 4.1 任务队列组件

| 组件 | 说明 | 数据源 |
|------|------|--------|
| **QueueHeader** | 队列统计（待处理/已完成） | `GET /health/action-inbox/stats`（现有） |
| **QueueTabs** | Tab 切换：待处理 / 已完成 | 前端状态 |
| **TaskItem** | 单个任务卡片：优先级圆点 + 标题 + 元信息 + 标签 + 时间 | 现有 `list_action_inbox` API |
| **TaskList** | 可滚动的任务列表容器 | Ant Design `List` + `InfiniteScroll` |

### 4.2 详情面板组件

| 组件 | 适用任务类型 | 说明 | 数据源 |
|------|-------------|------|--------|
| **PatientBar** | 全部 | 患者头像 + 姓名 + 年龄 + 科室 + 病史标签 | `GET /health/patients/:id`（现有） |
| **VitalAlertDetail** | 体征异常 | 异常数值 + 近 7 天趋势图 + 参考范围 | `GET /health/action-inbox/:source_ref/thread`（现有）+ `GET /health/vital-signs/trends`（现有） |
| **AiSuggestionCard** | AI 建议 | 风险评估 + 建议措施 + 采纳/拒绝操作 | thread API（现有） |
| **FollowUpForm** | 到期随访 | 随访表单 + 上次随访摘要 | thread API（现有） |
| **InteractionTimeline** | 全部 | 患者近期互动记录 | `GET /health/action-inbox/:source_ref/thread`（现有） |
| **ActionBar** | 全部 | 底部操作按钮（因任务类型不同而变化） | — |

### 4.3 任务类型与优先级（Phase 1 仅 3 种）

| 优先级 | 类型 | 自动生成规则 | 目标响应时间 | 数据源 |
|--------|------|-------------|-------------|--------|
| **危急 (P0)** | 体征危急值告警 | 告警系统生成 | ≤30 分钟 | `alerts` 表 |
| **紧急 (P1)** | AI 建议待审 | AI 分析引擎生成 | ≤2 小时 | `ai_analysis` 表 |
| **普通 (P2)** | 到期随访 | 随访计划到期 | ≤24 小时 | `follow_up_task` 表 |

### 4.4 任务 ID 格式

沿用现有 `action_inbox_service.rs` 的复合 ID 格式：`"{action_type}:{uuid}"`

- 告警任务：`"alert:550e8400-..."`
- AI 建议：`"ai_suggestion:660e8400-..."`
- 随访任务：`"follow_up:770e8400-..."`

操作分发逻辑：解析 `action_type` 前缀，路由到对应的底层服务。

## 5. 数据流与排序

### 5.1 任务生命周期

```
[自动生成] → [进入队列] → [选中处理] → [执行操作] → [完成/转交]
     ↑                                         │
     └── 超时未处理 → 升级优先级 ←──────────────┘
```

### 5.2 现有 API 复用策略

不新建 API 路径。**改造现有 `action-inbox` 系列接口**：

| 现有 API | 改造内容 |
|---------|---------|
| `GET /health/action-inbox` | 增加按优先级排序（改 SQL ORDER BY） |
| `GET /health/action-inbox/stats` | 增加「已完成」计数 |
| `GET /health/action-inbox/:source_ref/thread` | 增加 patient 上下文字段 |
| `POST /health/alerts/:id/acknowledge` | 沿用（完成告警任务） |
| `POST /health/ai-analysis/:id/review` | 沿用（采纳/拒绝 AI 建议） |
| `POST /health/follow-up/:id/complete` | 沿用（完成随访任务） |

详情面板的患者信息、趋势图通过**前端并行调用**现有 API 获取：
- `GET /health/patients/:id` → PatientBar
- `GET /health/vital-signs/trends?patient_id=&days=7` → VitalAlertDetail
- `GET /health/action-inbox/:source_ref/thread` → InteractionTimeline + 核心任务数据

前端用 `Promise.allSettled` 并行请求，加载中显示 Skeleton。

### 5.3 排序规则修复

现有 SQL 使用 `created_at DESC`（新的在前），需改为 `created_at ASC`（早的在前，FIFO），与设计规格一致。优先级映射从 3 级扩展为 4 级：

```sql
ORDER BY
  CASE priority_raw
    WHEN 'critical' THEN 0   -- P0 新增
    WHEN 'high' THEN 1
    WHEN 'urgent' THEN 1
    WHEN 'medium' THEN 2
    ELSE 3
  END,
  created_at ASC  -- 改为 ASC
```

## 6. 交互流程 — 处理一个任务的完整闭环

以「张伟 — 血压危急值 188/102」为例：

```
1. 进入工作台
   └→ 任务队列自动加载，张伟的告警排在最前（P0）

2. 点击任务
   └→ 右侧详情面板加载（并行请求患者信息 + thread + 趋势）：
      - 患者信息栏：张伟 / 男 / 58岁 / 血透中心 / 高血压3级
      - 异常数据：收缩压 188 / 舒张压 102 / 心率 92
      - 近 7 天收缩压趋势图（柱状图）
      - 近期互动记录

3. 执行操作
   └→ 点击「立即电话随访」
      └→ 弹出电话随访表单（预设患者电话号码）
      └→ 填写随访记录：确认用药 / 伴随症状 / 处理建议
      └→ 提交 → 调用 POST /health/alerts/:id/acknowledge

4. 任务完成
   └→ 任务从「待处理」移至「已完成」
   └→ 队列自动选中下一个任务
   └→ 右侧面板加载新任务的详情

5. 可选操作
   └→ 「转给医生」：更改 assigned_to → 对应医生（需 migration 加字段，Phase 2）
   └→ 「稍后处理」：本地状态，置底并标记延迟时间
```

### 6.1 操作按钮矩阵（Phase 1）

| 任务类型 | 主操作 | 次要操作 | 底层 API |
|---------|--------|---------|---------|
| 体征异常告警 | 记录处理结果 + 确认 | 稍后处理 | `POST /health/alerts/:id/acknowledge` |
| AI 建议待审 | 采纳 / 拒绝 | 稍后处理 | `POST /health/ai-analysis/:id/review` |
| 到期随访 | 开始随访（电话/线上/面访） | 稍后处理 | `POST /health/follow-up/:id/complete` |

### 6.2 空状态处理

- 队列为空时：显示「所有任务已处理完毕」+ 今日完成统计
- 详情面板未选中任务时：显示空态引导「从左侧选择一个任务开始处理」
- 加载中：Skeleton 占位

### 6.3 前端状态管理

使用 Zustand store `useWorkbenchStore`：

```typescript
interface WorkbenchState {
  tasks: ActionItem[];            // 任务列表
  selectedTaskId: string | null;  // 当前选中任务
  completedCount: number;         // 今日完成数
  tab: 'pending' | 'completed';   // 当前 Tab
  
  selectTask: (id: string) => void;
  completeTask: (id: string) => Promise<void>;
  refreshTasks: () => Promise<void>;
}
```

实时刷新策略：Phase 1 使用 30 秒轮询（`setInterval` + `refreshTasks`），Phase 2 考虑升级为 SSE。

## 7. 与现有系统的关系

### 7.1 改造策略

改造现有的 `Home.tsx` 工作台页面，替换当前仪表盘布局为方案 B 的任务队列 + 详情面板两栏布局。

**不新建页面**，在现有路由 `/health` 上直接改造。侧边栏不变。

### 7.2 涉及文件

| 文件 | 改动类型 | 说明 |
|------|---------|------|
| `apps/web/src/pages/health/Home.tsx` | **重写** | 从仪表盘布局改为任务队列 + 详情面板 |
| `apps/web/src/pages/health/components/TaskQueue.tsx` | **新增** | 任务队列组件 |
| `apps/web/src/pages/health/components/TaskDetail.tsx` | **新增** | 详情面板组件 |
| `apps/web/src/pages/health/components/PatientBar.tsx` | **新增** | 患者信息栏 |
| `apps/web/src/stores/workbenchStore.ts` | **新增** | Zustand store |
| `crates/erp-health/src/service/action_inbox_service.rs` | **改造** | 修复排序规则 + 扩展优先级 |
| `crates/erp-health/src/handler/device_reading_handler.rs` | **改造** | alert acknowledge 增加处理记录 |

### 7.3 数据库变更

Phase 1 **无需新建表**。任务从现有 3 张表聚合：
- 体征告警 ← `alerts` 表（未确认的告警）
- AI 建议 ← `ai_analysis` 表（状态=pending_review）
- 到期随访 ← `follow_up_task` 表（状态=pending + 到期日<=今天）

聚合逻辑沿用现有 `action_inbox_service.rs` 的 UNION ALL 方案。

### 7.4 权限

沿用现有权限码：`health.action-inbox.list` + `health.action-inbox.manage`。

### 7.5 验收标准

- [ ] 工作台展示 3 种任务类型（告警、AI 建议、随访），按优先级排序
- [ ] 点击任务，右侧详情面板展示完整上下文（患者信息 + 原始数据 + 趋势 + 互动记录）
- [ ] 告警任务可确认并记录处理结果
- [ ] AI 建议可采纳或拒绝
- [ ] 随访任务可完成并填写随访记录
- [ ] 任务完成后自动选中下一个
- [ ] 空状态有合理展示
- [ ] 30 秒自动刷新任务列表
- [ ] `cargo check` 通过
- [ ] 浏览器中实际操作验证通过