yelan
fc22d22f85
用 VITE_MOCK_* 系列环境变量替换全局 VITE_USE_MOCK，各模块独立控制演示数据 启用，并新增 src/utils/mock-flags.ts 统一解析缺省值。文档库关闭演示库时 如实提示接口待接入，避免静默沿用本地数据或覆盖已保存内容。
70 lines
4.8 KiB
Markdown
70 lines
4.8 KiB
Markdown
# 工作台首页接口核验与接入说明
|
||
|
||
> 事实基准：用户于 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 中不再出现首页为统计目的而循环拉取全部签署任务或模板的请求。
|