# 文档库管理 —— 真实接口验证报告

- 验证日期：2026-09-17
- 验证对象：`clinical-web` 文档库管理（`/management/documents`）
- 数据来源：MEDISIGN 后端 `https://ipad.shenynet.com`（真实接口，`VITE_MOCK_DOCUMENTS=false`）
- 验证方式：真实浏览器（Chrome headless + CDP）驱动真实页面，非静态审查

## 1. 结论

**文档库管理在真实接口下功能完整、闭环可用。**

从「新增文书」到「发布」再到「发起签署」的完整链路全部走通，
每一步后端均返回 200，页面运行时错误 0 条。

此前记录的「后端模板写接口作废（`POST /v1/templates` 稳定 500、列表恒 0 条）」**已不成立**，
写接口已恢复正常。

## 2. 只读功能验证

| 功能 | 结果 | 说明 |
|---|---|---|
| 列表加载 | 通过 | 真实模板正确渲染，科室三级分组（科室 → 分类 → 文书）正常 |
| 科室页签 | 通过 | 按实际科室归类，无科室的模板归入「未指定科室」 |
| 状态页签 | 通过 | 按后端原始状态过滤，`PENDING_REVIEW` 与 `REJECTED` 未合并 |
| 搜索 | 通过 | 按名称/编号/科室过滤正确 |
| 预览弹窗 | 通过 | **正文真实取回**（列表接口只给哈希，已正确补穿透版本详情） |
| 预览 - 签署预览页签 | 通过 | 占位符按演示患者填充，渲染正常 |
| 编辑弹窗 | 通过 | 名称/编号/说明/正文全部正确带出 |
| 新增弹窗 | 通过 | 空表单；院区取真实 UUID；版本号显示「由后端按 vN 自动生成」 |
| 加载态/错误态 | 通过 | 有独立加载态与错误态，未把失败降级成空态 |

## 3. 写操作与版本工作流验证

新建测试文书「【自动化测试】签署链路验证」（编号 `AUTO-TEST-800004`）后逐步执行：

| 步骤 | 卡片动作 | 后端接口 | 状态变化 |
|---|---|---|---|
| 1 | 保存文书 | `POST /v1/templates` + `POST /v1/templates/{id}/versions` | （新建）→ 草稿 |
| 2 | 提交审核 | `POST .../versions/{vid}/submit-review` | 草稿 → 待审核 |
| 3 | 驳回 | `POST .../versions/{vid}/reject` | 待审核 → 已驳回 |
| 4 | 重新提交 | `POST .../versions/{vid}/submit-review` | 已驳回 → 待审核 |
| 5 | 审核通过 | `POST .../versions/{vid}/approve` | 待审核 → 审核通过 |
| 6 | 发布 | `POST .../versions/{vid}/publish` | 审核通过 → 已发布 |
| 7 | 发起 | `GET .../versions/{vid}`（取真实正文） | 打开「新增签署任务」，模板已自动选中 |

驳回意见经 `reject` 的 `comment` 参数提交，用于留痕。

### 3.1 动作按钮文案随状态变化

前端按后端状态计算卡片主动作，文案**不是固定值**：

| 后端状态 | 卡片动作 |
|---|---|
| `DRAFT` | 提交审核 |
| `PENDING_REVIEW` | 审核通过 / 驳回 |
| `REJECTED` | 重新提交 |
| `APPROVED` | 发布 |
| `PUBLISHED` | 发起 |
| `DISABLED` | 重新启用 |

写自动化脚本或写测试用例时若写死「提交审核」，在后续步骤会全部点空。

### 3.2 工作流确认框的确认按钮文案

确认框的确认按钮文案**等于动作名本身**（「提交审核」「发布」「确认驳回」），
不是「确定」。按 `/确定|确认/` 匹配文字会点不到，应按 `.el-button--primary` 定位。

## 4. 接口调用清单（本次验证实际打到）

```
GET  /api/v1/auth/me
GET  /api/v1/campuses
GET  /api/v1/departments
GET  /api/v1/templates                      列表（分页拉全量）
GET  /api/v1/templates/{id}                 模板详情
GET  /api/v1/templates/{id}/versions        版本列表
GET  /api/v1/templates/{id}/versions/{vid}  版本详情（正文来源）
POST /api/v1/templates                      新建模板
POST /api/v1/templates/{id}/versions        新建版本
POST /api/v1/templates/{id}/versions/{vid}/submit-review
POST /api/v1/templates/{id}/versions/{vid}/reject
POST /api/v1/templates/{id}/versions/{vid}/approve
POST /api/v1/templates/{id}/versions/{vid}/publish
```

全部 200。

## 5. 已知限制与未覆盖项

### 5.1 入口未开放（既有设计，非本次回归）

- **版本历史**：`getTemplateVersions` 与 `DocumentVersionDialog` 均已实现，
  但卡片上没有「版本」按钮（`DocumentTemplateCard` 中 `showVersionAction = false`），
  用户无法从 UI 进入。
- **下架 / 归档**：同样没有按钮（`showRemoveAction = false`）。
  因此本次测试创建的文书**无法通过 UI 清理**，只能走接口归档。

### 5.2 混合模式下的模板树

当前本地配置为「文档库真实 + 签署工作台演示数据」。此配置下点「发起」，
「新增签署任务」弹窗左侧的模板树**仍为演示数据**（含后端不存在的文书），
仅从文档库带入的那一份是真实的。

原因：该弹窗调用 `getSigningTemplates()`，它读的是 `mockFlags.signing`。
将签署端也切到真实接口后，该模板树才会只显示后端真实模板。

### 5.3 未验证项

- 手写板设备桥接、线上签署回调、打印服务（后端尚未提供，前端为占位）
- 模板包导出（`showExportMessage` 为占位提示，后端无对应接口）

## 6. 验证环境注意事项

供后续复现参考：

1. **请求头是 `X-Token`，不是 `Authorization: Bearer`**（见 `utils/request.ts`）。
   用 curl 直连后端调试时写错会得到 `40100 请先登录`，容易误判成 token 失效。
2. **后端会话实际存活约 10 分钟**，而登录响应里的 `expiresAt` 声明 2 小时。
   登录与验证必须串在同一条命令里执行（`node scripts/login.cjs <code> && node <verify>.cjs`），
   否则必然被踢回 `/login`，表现为「页面上找不到按钮」。
3. 文档库的弹窗是自定义 `.dialog-mask`，**不是 Element Plus 的 `.el-dialog`**。
   关闭要点 `.dialog-mask .close-button`（预览 / Word 编辑器）或 `.dialog-close`（版本弹窗）。
   关不掉会导致下一个弹窗因 `visible` 未变化而不触发重置，造出「状态没重置」的假象。

## 7. 遗留测试数据

测试文书「【自动化测试】签署链路验证」（编号 `AUTO-TEST-800004`）当前为**已发布**状态，
保留在联调环境以便继续验证发起签署。不需要时归档即可：

```
POST /api/v1/templates/{templateId}/versions/{versionId}/archive
```