deploy 04191544

API-报告成片字段契约.md

@@ -0,0 +1,34 @@
+# API 契约：报告详情 / 列表中的「服务回顾短片」字段
+
+> 与 `ReportController.putHighlightFields`、`ReportHighlightVideoService` 实现一致；前端 `getReportByToken`、`getReportList` 及 `utils/reportShare.js` 依赖本契约。
+
+## 出现位置
+
+以下接口的 `data`（单条报告对象或列表元素）均包含相同短片相关键名（camelCase）：
+
+- `GET /api/report/get?token=...` 或 `?appointmentId=...`
+- `GET /api/report/list`（分页与非分页）
+
+## 字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `highlightVideoUrl` | string \| null | 成片 MP4。成功时为可播放的**绝对 URL**（由服务端 `app.base-url` 拼接相对路径）；未生成 / 失败时多为 null。库内历史数据可能存绝对 URL，接口层会原样或补全后返回。 |
+| `highlightShareCoverUrl` | string \| null | **分享卡片用封面**：成片导出后由 ffmpeg 截取的首帧 JPEG 的绝对 URL。仅 `highlightVideoStatus === 'done'` 且截帧成功时有值；失败或未生成时为 null。 |
+| `highlightPosterUrl` | null | **预留**：画布海报等独立资源；当前接口**恒为 null**。前端分享封面应优先 `highlightShareCoverUrl`，再按业务降级（见 `frontend/src/utils/reportShare.js`）。 |
+| `highlightVideoStatus` | string \| null | 如 `processing`、`done`、`failed`。 |
+| `highlightVideoError` | string \| null | 失败时的用户可读简述（成功 / 处理中一般为 null）。 |
+| `highlightFailReason` | string \| null | 机器可读归类：`material` / `service` / `network` / `unknown` 等。 |
+| `highlightFailReasonLabel` | string \| null | 失败类中文短标签，供 UI 展示。 |
+| `highlightDurationSec` | number \| null | 成片时长（秒，向上取整），done 时一般有值。 |
+| `highlightComposeMode` | string \| null | `preset`（预设顺序）或 `interleave`（穿插成片）。 |
+
+## 存储约定（后端）
+
+- `t_report.highlight_share_cover_url`：相对路径 `/api/upload/image/{yyyy}/{MM}/{dd}/{stem}_cover.jpg`，与成片文件同目录。
+- 新写入的 `highlight_video_url` 为相对路径 `/api/upload/image/.../highlight_{reportId}_{uuid}.mp4`（与上传接口返回形态一致）；历史全量 URL 仍兼容。
+
+## 行为要点
+
+1. 调用 `POST /api/report/highlight/start` 进入 `processing` 时，会**清空** `highlightShareCoverUrl`（旧封面不再与本次任务绑定）。
+2. 成片合成成功后写回首帧路径；若 ffmpeg 截帧失败，**成片仍可成功**，`highlightShareCoverUrl` 为 null，分享侧降级为服务后首图等。