# 工作台首页接口核验与接入说明

> 事实基准：用户于 2026-09-02 导出的 default_OpenAPI.json，OpenAPI 3.1.0，MEDISIGN 患者电子签 API v1。
>
> 接入状态：首页缺省（`VITE_MOCK_WORKBENCH_HOME` 未开启）已接入 GET /api/v1/workbench/overview。

## 1. 核验结论

最新契约已提供工作台首页聚合接口。真实模式下，首页不再循环读取模板、签署任务和组织数据并在浏览器聚合，而是由后端在权限范围内一次性返回指标、趋势、待办和文档排名。

全局 `appStore` 在应用加载后调用 GET /api/v1/campuses（page=1、size=200），仅保留启用院区，并以 UUID 作为下拉选项值。首页将当前选中 UUID 直接传给概览接口；API 边界只在未传 UUID 的调用场景下按院区名称兜底解析。

## 2. 已接入的请求

```http
GET /api/v1/workbench/overview?campusId={UUID}&period={7|14|30}&todoLimit=8&rankingLimit=10
X-Token: {登录令牌}
```

| 参数         | 必填 | 前端传值                  | 契约说明                       |
| ------------ | ---- | ------------------------- | ------------------------------ |
| campusId     | 是   | 当前工作台院区对应的 UUID | 必须在当前用户数据范围内       |
| period       | 是   | 7、14 或 30               | 同时决定趋势和文档排名统计周期 |
| todoLimit    | 否   | 8                         | 待办返回数量，范围 1–20        |
| rankingLimit | 否   | 10                        | 排名返回数量，范围 1–20        |

请求通过 utils/request.ts 的单例发送，实际浏览器路径为 /api/v1/workbench/overview，由 Vite 开发代理转发到后端。

## 3. 接口字段与页面映射

| 页面区域   | 后端字段                                                                                                            | 前端展示                                                   |
| ---------- | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| 四张指标卡 | summary.todaySigned、todaySignedChange、pendingPatientSigning、todayOverdue、availableTemplates、coveredDepartments | 今日签署、较昨日变化、待签署、今日超时、可用模板及覆盖科室 |
| 签署趋势   | trend[].label、trend[].signedCount                                                                                  | 按后端业务时区生成的近 7、14 或 30 天趋势                  |
| 我的待办   | todos[].taskId、patientId、patientName、documentName、departmentName、status、signMethod、updatedAt                 | 待办列表；点击 taskId 跳转签署工作台                       |
| 文档排名   | documentRanking[].templateId、documentName、departmentName、signedCount                                             | Top10 文档签署排名                                         |

趋势和排名都直接使用后端按 signedAt、医院业务时区聚合的结果；前端不再用 createdAt 或浏览器时区重新计算。

## 4. 待办状态展示

后端 TodoItem.status 使用签署任务状态枚举。前端按下列方式展示，避免把生成中、失败或已作废任务误标为待签署：

| 后端状态     | 页面状态                   |
| ------------ | -------------------------- |
| CREATED      | 待发送                     |
| WAITING_SIGN | 待签署，并区分手写板或短信 |
| GENERATING   | 文书生成中                 |
| EXPIRED      | 已超时                     |
| SIGNED       | 已签署                     |
| VOIDED       | 已作废                     |
| FAILED       | 处理失败                   |

pendingPatientSigning 的后端口径只统计 WAITING_SIGN；CREATED 和 GENERATING 不会被前端补入该指标。

## 5. 权限、错误与数据边界

- 接口使用 X-Token 鉴权；任务数据范围和模板 ACL 由后端在 SQL 层执行。
- campusId 无权限或工作台无权限时，后端返回 403；参数错误返回 400；未登录返回 401。
- 患者标识为不可逆展示标识；前端不记录或补全身份证号、完整手机号和病历数据。
- 接口返回 timezone 和 generatedAt，统计日期以医院业务时区为准。

## 6. 联调验收标准

- 切换院区后，请求携带新 campusId，四张指标卡、趋势、待办和排名同步更新。
- 切换 7、14、30 天后，趋势标题、趋势数据和文档排名同步变化。
- 返回空数组时，趋势、待办和排名显示各自空状态；指标卡显示 0。
- 服务端返回 GENERATING、FAILED、VOIDED 等状态时，页面标签与状态含义一致。
- Network 中不再出现首页为统计目的而循环拉取全部签署任务或模板的请求。