142 lines
6.0 KiB
Markdown
142 lines
6.0 KiB
Markdown
# 工作台首页后端接口需求
|
||
|
||
## 1. 目标
|
||
|
||
工作台首页是只读的概览页，当前前端可以通过模板、院区和签署任务接口临时聚合数据，但任务量较大时会产生多次分页请求，而且现有任务列表主要按 `createdAt` 查询，无法准确支持“按签署时间统计”和“按超时时间统计”。
|
||
|
||
建议后端提供一个聚合接口，由后端在权限范围内一次性计算首页所需数据。
|
||
|
||
## 2. 推荐接口
|
||
|
||
```http
|
||
GET /api/v1/workbench/overview
|
||
```
|
||
|
||
请求头：
|
||
|
||
```http
|
||
X-Token: {登录令牌}
|
||
```
|
||
|
||
请求参数：
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| -------------- | ------- | ---- | ---------------------------------------------- |
|
||
| `campusId` | UUID | 是 | 当前首页选择的院区 |
|
||
| `period` | integer | 是 | 签署趋势和文档排名周期，只允许 `7`、`14`、`30` |
|
||
| `todoLimit` | integer | 否 | 待办数量，默认 `8`，最大 `20` |
|
||
| `rankingLimit` | integer | 否 | 排名数量，默认 `10`，最大 `20` |
|
||
|
||
日期计算建议统一使用服务端的医院业务时区（上海为 `Asia/Shanghai`），响应中的时间字段使用 ISO-8601 格式。
|
||
|
||
## 3. 返回结构
|
||
|
||
接口继续使用当前统一响应包装：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "OK",
|
||
"data": {
|
||
"campusId": "550e8400-e29b-41d4-a716-446655440000",
|
||
"timezone": "Asia/Shanghai",
|
||
"generatedAt": "2026-09-01T08:00:00Z",
|
||
"summary": {
|
||
"todaySigned": 36,
|
||
"todaySignedChange": 2,
|
||
"pendingPatientSigning": 18,
|
||
"todayOverdue": 2,
|
||
"availableTemplates": 128,
|
||
"coveredDepartments": 9
|
||
},
|
||
"trend": [
|
||
{
|
||
"date": "2026-08-26",
|
||
"label": "8/26",
|
||
"signedCount": 39
|
||
}
|
||
],
|
||
"todos": [
|
||
{
|
||
"taskId": "任务 UUID",
|
||
"patientId": "脱敏患者标识",
|
||
"patientName": "患者姓名",
|
||
"documentName": "知情同意书",
|
||
"departmentName": "消化内科",
|
||
"status": "WAITING_SIGN",
|
||
"signMethod": "PAD",
|
||
"updatedAt": "2026-09-01T07:50:00Z",
|
||
"expiredAt": "2026-09-01T09:00:00Z"
|
||
}
|
||
],
|
||
"documentRanking": [
|
||
{
|
||
"templateId": "模板 UUID",
|
||
"documentName": "住院患者知情同意书",
|
||
"departmentName": "全院通用",
|
||
"signedCount": 58
|
||
}
|
||
]
|
||
},
|
||
"traceId": "链路追踪 ID",
|
||
"timestamp": "2026-09-01T08:00:00Z"
|
||
}
|
||
```
|
||
|
||
## 4. 统计口径
|
||
|
||
### 4.1 指标卡
|
||
|
||
- `todaySigned`：`status=SIGNED` 且 `signedAt` 位于今天业务时区起止范围内的任务数。
|
||
- `todaySignedChange`：`todaySigned - yesterdaySigned`，正数表示上升，负数表示下降，`0` 表示持平。
|
||
- `pendingPatientSigning`：状态为 `CREATED`、`WAITING_SIGN` 或 `GENERATING` 的任务数；不按创建日期限制。
|
||
- `todayOverdue`：状态为 `EXPIRED` 且 `expiredAt` 位于今天业务时区起止范围内的任务数。
|
||
- `availableTemplates`：当前用户在指定院区有 `USE` 权限且已发布生效的模板数量，按 `templateId` 去重，不按版本行数重复计算。
|
||
- `coveredDepartments`：上述可用模板中非空 `departmentId` 的去重数量；全院通用模板不计入科室数。
|
||
|
||
### 4.2 签署趋势
|
||
|
||
返回最近 `period` 个自然日，包含今天，按日期升序排列。每天按 `signedAt` 统计 `SIGNED` 任务数，而不是按 `createdAt` 或 `updatedAt` 统计。
|
||
|
||
### 4.3 待办任务
|
||
|
||
待办包括 `CREATED`、`WAITING_SIGN`、`GENERATING` 和 `EXPIRED` 任务，按 `updatedAt` 倒序返回前 `todoLimit` 条。前端会将前三种状态展示为“等待患者签署”，将 `EXPIRED` 展示为“已超时”。
|
||
|
||
返回的患者标识必须遵守现有数据脱敏和权限规则，不返回明文证件号、明文手机号或其他不必要的敏感信息。
|
||
|
||
### 4.4 文档签署排名
|
||
|
||
仅统计 `signedAt` 位于最近 `period` 个自然日内的 `SIGNED` 任务，按 `templateId` 分组后倒序返回前 `rankingLimit` 条。分组键必须使用模板 ID，不能只使用文档名称，避免同名模板被错误合并。
|
||
|
||
## 5. 权限和错误响应
|
||
|
||
接口必须复用签署任务查询和模板 `USE` 权限的数据范围控制，只统计当前用户有权查看的院区、科室和任务。
|
||
|
||
建议至少返回以下状态：
|
||
|
||
| HTTP 状态 | 场景 |
|
||
| --------- | ------------------------------- |
|
||
| `200` | 查询成功 |
|
||
| `400` | `campusId` 或 `period` 参数错误 |
|
||
| `401` | 未登录或令牌失效 |
|
||
| `403` | 无权查看指定院区或工作台数据 |
|
||
| `500` | 服务端聚合失败 |
|
||
|
||
## 6. 暂时不增加聚合接口时的最小改造
|
||
|
||
如果暂时不能提供 `/workbench/overview`，现有接口至少需要补充或明确以下能力：
|
||
|
||
1. `GET /api/v1/templates/available-versions` 必须支持 `campusId`，并返回真实 `departmentId`；前端已可以使用该筛选参数。
|
||
2. `GET /api/v1/sign-tasks` 需要支持按 `signedAt` 和 `expiredAt` 查询，而不能只支持 `createdAt`。
|
||
3. 任务列表最好支持多状态查询，或者提供待签署任务汇总接口，否则待办数量需要分别请求多个状态。
|
||
4. 任务或模板响应需要提供稳定的 `templateId`、`templateName`、`departmentName`，避免历史模板不可用时只能显示模板版本号。
|
||
5. 如果继续使用分页聚合，接口需要保证 `total`、`page`、`size` 一致，并允许客户端按最大页大小安全拉取全部数据。
|
||
|
||
## 7. 前端对接验收标准
|
||
|
||
- 切换院区后，四个指标、趋势、待办和排名都只属于当前院区。
|
||
- 切换 `7/14/30` 天后，趋势和排名同时改变统计周期。
|
||
- 跨自然日、任务延迟签署和任务延迟超时场景下，指标仍按 `signedAt`、`expiredAt` 正确统计。
|
||
- 首页显示的昨日变化不再使用固定文案。
|
||
- 待办点击后可以根据 `taskId` 直接打开详情，即使任务不在签署工作台当前第一页。
|