工作台首页后端接口需求

1. 目标

工作台首页是只读的概览页，当前前端可以通过模板、院区和签署任务接口临时聚合数据，但任务量较大时会产生多次分页请求，而且现有任务列表主要按 createdAt 查询，无法准确支持“按签署时间统计”和“按超时时间统计”。

建议后端提供一个聚合接口，由后端在权限范围内一次性计算首页所需数据。

2. 推荐接口

GET /api/v1/workbench/overview

请求头：

X-Token: {登录令牌}

请求参数：

参数	类型	必填	说明
`campusId`	UUID	是	当前首页选择的院区
`period`	integer	是	签署趋势和文档排名周期，只允许 `7`、`14`、`30`
`todoLimit`	integer	否	待办数量，默认 `8`，最大 `20`
`rankingLimit`	integer	否	排名数量，默认 `10`，最大 `20`

日期计算建议统一使用服务端的医院业务时区（上海为 Asia/Shanghai），响应中的时间字段使用 ISO-8601 格式。

3. 返回结构

接口继续使用当前统一响应包装：

{
  "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，现有接口至少需要补充或明确以下能力：

GET /api/v1/templates/available-versions 必须支持 campusId，并返回真实 departmentId；前端已可以使用该筛选参数。
GET /api/v1/sign-tasks 需要支持按 signedAt 和 expiredAt 查询，而不能只支持 createdAt。
任务列表最好支持多状态查询，或者提供待签署任务汇总接口，否则待办数量需要分别请求多个状态。
任务或模板响应需要提供稳定的 templateId、templateName、departmentName，避免历史模板不可用时只能显示模板版本号。
如果继续使用分页聚合，接口需要保证 total、page、size 一致，并允许客户端按最大页大小安全拉取全部数据。

7. 前端对接验收标准

切换院区后，四个指标、趋势、待办和排名都只属于当前院区。
切换 7/14/30 天后，趋势和排名同时改变统计周期。
跨自然日、任务延迟签署和任务延迟超时场景下，指标仍按 signedAt、expiredAt 正确统计。
首页显示的昨日变化不再使用固定文案。
待办点击后可以根据 taskId 直接打开详情，即使任务不在签署工作台当前第一页。

6.0 KiB Raw Permalink Blame History Unescape Escape