实现前端演示数据受控生成接口

2026-07-08 19:09:17 +08:00
parent 3c1649a567
commit c83935a26c
17 changed files with 1271 additions and 16 deletions
--- a/docs/project/frontend-backend/backend-to-frontend-notes.md
+++ b/docs/project/frontend-backend/backend-to-frontend-notes.md
@@ -51,10 +51,103 @@
 | `GET /api/source-messages/{id}/original` | 读取来源消息原文 | 需要受控访问头，返回 HTML 时前端展示前必须 sanitize。 |
 | `GET /api/source-messages/{sourceMessageId}/conversation` | 读取邮件会话详情 | 返回同一外部会话全部邮件的完整 text/html、附件外链、内联图片和关联订单 / 任务摘要；前端不传原文读取 key，但展示 HTML 前必须 sanitize。 |

+### 5.1 本轮新增 / 修改接口说明
+
+本轮后端新增或补齐了以下前端 P0 查询能力。前端后续开发时，应优先以本节作为接入口径。
+
+| 接口 | 本轮变化 | 前端接入注意 |
+| --- | --- | --- |
+| `GET /api/reservation/orders` | 新增订单列表接口。 | `order_status` 不传时默认查询全部订单状态；`page_num` 从 1 开始；`page_size` 后端有最大值保护；`open_task_count` 排除 `COMPLETED` 和 `FAILED`；`next_processable_task_id` 为空表示当前没有可继续处理的任务。 |
+| `GET /api/reservation/tasks` | 补齐来源邮件会话摘要字段。 | 列表仍然只返回安全摘要，不返回正文、HTML、附件 URL 或 AI 原始 payload；点击邮件入口时使用 `source_message_id` 调会话详情。 |
+| `GET /api/reservation/orders/{orderId}` | 补齐 `tasks[]` 每条任务的来源邮件会话摘要字段。 | `include_tasks=false` 可只取订单摘要；时间线顺序由后端按订单队列返回，前端不要自行按创建时间重排。`include_source_summary` 第一版不作为前端裁剪字段的强约束，前端暂不要依赖它减少返回字段。 |
+| `GET /api/reservation/tasks/{taskId}` | 补齐顶层来源邮件字段，并扩展 `fields[]` 元数据。 | 顶层来源字段用于打开邮件会话；`fields[]` 中的 `result_type`、`task_type`、`task_subtype`、`default_value_source` 用于前端字段分组、调试和白名单对齐。 |
+| `GET /api/source-messages/{sourceMessageId}/conversation` | 新增邮件会话详情接口。 | 当前唯一推荐路径是这个接口；不要调用历史讨论过的 `/api/source-message-conversations/{externalConversationId}`。 |
+
+### 5.2 来源邮件会话字段说明
+
+任务列表、订单详情任务时间线、任务详情顶层会返回以下来源邮件字段：
+
+| 字段 | 说明 | 前端使用方式 |
+| --- | --- | --- |
+| `source_message_id` | 本系统内部 SourceMessage Inbox ID。 | 打开邮件会话详情时作为路径参数传入 `/api/source-messages/{sourceMessageId}/conversation`。 |
+| `source_subject` | 来源邮件主题安全摘要。 | 用于列表或任务详情标题旁展示，不代表完整邮件主题一定无敏感信息。 |
+| `source_sender_summary` | 来源发件人安全摘要。 | 用于辅助用户判断邮件来源。 |
+| `source_received_at` | 本系统接收来源消息时间，UTC。 | 前端展示时按用户或酒店时区格式化。 |
+| `external_conversation_id` | 外部邮件会话 ID。 | 仅用于展示或调试，不作为当前会话详情接口路径参数。 |
+| `conversation_message_count` | 同一外部会话下的邮件数量。 | 用于提示用户打开的是整段会话，不是单封邮件。 |
+
+### 5.3 邮件会话详情接入注意
+
+- `GET /api/source-messages/{sourceMessageId}/conversation` 只接收路径参数 `sourceMessageId`；第一版不接收 `hotelId`、`includeBody`、`includeRelated`。
+- 后端会根据 `sourceMessageId` 定位 `external_conversation_id`，并返回同一会话下全部邮件；如果来源消息没有外部会话 ID，会降级返回当前单封邮件。
+- `messages[]` 按后端接收时间正序返回，前端不要重新按创建时间或任务时间排序。
+- 返回内容包含完整 `text_body`、`html_body`、`inline_images[]`、`attachments[]`、`related_orders[]`、`related_tasks[]`。
+- `html_sanitize_required=true` 时，前端必须先 sanitize 再渲染 HTML；不要使用未清洗的 `html_body` 直接设置 DOM。
+- `inline_images[]` 和 `attachments[]` 里的 `externalUrl` 可能包含有时效或访问凭证的外链，前端不得写入普通日志、错误上报、localStorage 或 URL query。
+- 会话详情接口由后端内部写原文读取审计，前端不传 `X-TH-Hotel-Source-Original-Read-Key`。
+- 会话详情外层字段主要是 snake_case，但媒体对象沿用原文读取接口字段，当前是 `mediaType`、`fileName`、`contentType`、`sizeBytes`、`externalUrl`、`externalMediaId` 这种 camelCase，前端类型定义需要单独处理。
+
+### 5.4 订单列表接入注意
+
+- `GET /api/reservation/orders` 默认返回全部订单状态，包括 `TEMPORARY`、`ACTIVE`、`ENDED`、`LOGIC_DELETED`。
+- `keyword` 会匹配订单业务号、临时订单号、展示名、订单状态，也会匹配来源消息安全摘要命中的 SourceMessage ID；前端可以用邮件主题、外部消息 ID 或会话 ID 辅助查订单。
+- `open_task_count` 只统计未关闭任务，排除 `COMPLETED` 和 `FAILED`。
+- `next_processable_task_id` 是后端按同订单队列实时计算出的下一条可处理任务；前端可以用它做“继续处理”入口。
+- `display_order_key` 是前端优先展示的订单业务号或临时订单号；`group_code` 和 `confirmation_number` 只有在当前订单业务号类型匹配时返回。
+- 订单 ID、任务 ID、SourceMessage ID 在这些前端接口中按字符串返回，前端不要转换成 JavaScript number。
+
+### 5.5 前端联调演示数据 seed 接口
+
+后端提供一个受控的 dev/test 演示数据入口，方便前端在空库或本地环境快速看到页面效果。
+
+```text
+POST /api/system/reservation/demo-data
+Header: X-TH-Hotel-Demo-Data-Key: <本地演示数据访问口令>
+Content-Type: application/json
+
+{
+  "hotel_id": "HOTEL-TEST",
+  "run_label": "frontend-smoke"
+}
+```
+
+启用方式：
+
+- 默认关闭，需要后端环境显式设置 `reservation.demo-data.enabled=true` 或环境变量 `RESERVATION_DEMO_DATA_ENABLED=true`。
+- 必须配置 `reservation.demo-data.access-key` 或环境变量 `RESERVATION_DEMO_DATA_ACCESS_KEY`。
+- 该接口只用于 dev/test 联调，不允许放进生产普通页面，也不要把访问口令写进前端仓库、浏览器环境变量或构建产物。
+
+返回内容：
+
+- `demo_run_id`：本次 seed 的唯一关键词，可用于任务列表 / 订单列表搜索。
+- `source_messages[]`：本次生成的 SourceMessage ID、外部消息 ID 和会话 ID。
+- `orders[]`：本次生成的订单 ID、订单状态和展示键。
+- `tasks[]`：本次生成的任务 ID、任务类型、任务 subtype 和任务状态。
+- `entrypoints`：可直接访问的后端查询入口，包括任务列表、订单列表、队列订单详情、失败任务详情和邮件会话详情。
+
+当前 seed 覆盖的页面效果：
+
+- 同订单前置任务未完成，后续任务只读不可处理。
+- 已完成 New Booking 任务和两条 OPERA 模拟成功记录。
+- OPERA 模拟失败任务，可在任务详情看到失败 attempt 和重试入口。
+- Fallback / manual_review 任务。
+- Message Notification 只读任务。
+- 同一邮件会话下多封邮件、完整 HTML、附件外链和内联图片外链。
+
+### 5.6 任务详情字段元数据接入注意
+
+- `fields[]` 第一版服务于任务详情动态展示，字段来源与白名单规则以 `docs/import/20260708/任务卡前端展示字段表 3.0.xlsx` 为准。
+- `result_type`、`task_type`、`task_subtype`、`default_value_source` 已透出给前端，用于和最新前端白名单对齐。
+- 后端校验、最终确认写入、OPERA 映射和展示条件仍以 `docs/import/20260706/任务卡展示编辑矩阵.xlsx` 为完整规则来源。
+- 前端保存草稿时不要自行按 `write_path` 重组 OPERA 参数；第一版按任务详情返回的字段和值提交即可，真实 OPERA 参数组装后续由后端 adapter / 转换层处理。
+- 任务详情页控制按钮时以 `availability.editable`、`availability.confirmable`、`availability.executable`、`availability.read_only` 和 `availability.blocked` 为准；`can_process` 和 `readonly_reason_code` 只出现在任务列表 / 订单时间线摘要里。
+
 ## 6. 不给前端直接调用的接口

+- `POST /api/system/reservation/demo-data` 只用于 dev/test 联调造数，不是生产业务页面接口；访问口令不能进入前端代码。
 - `POST /api/integrations/superagent/task-results` 是 SuperAgent 到后端的服务到服务入站接口。
 - `POST /api/ai-query/v1/case-context` 和 `POST /api/ai-query/v1/object-detail` 是 SuperAgent 查询上下文接口，不是前端页面接口。
+- `GET /api/source-message-conversations/{externalConversationId}` 是历史讨论过的候选路径，当前后端不提供，前端不要接入。
 - AgentBus probe、fixture、replay、system 类接口不应放到普通业务前端页面。

 ## 7. 需要持续提醒的后置事项
--- a/docs/project/frontend-backend/frontend-to-backend-api-requests.md
+++ b/docs/project/frontend-backend/frontend-to-backend-api-requests.md
@@ -14,6 +14,7 @@
 | P0 | 任务详情读取接口 `GET /api/reservation/tasks/{taskId}` | 任务详情页动态渲染 | 已完成第一版，已补来源邮件字段和 3.0 字段元数据 |
 | P0 | 任务详情操作接口 | 任务详情保存、确认、OPERA、审计 | 已完成；前端可直接接入 |
 | P0 | 邮件会话详情接口 `GET /api/source-messages/{sourceMessageId}/conversation` | 邮件会话详情页 | 已完成第一版 |
+| 联调 | 演示数据 seed 接口 `POST /api/system/reservation/demo-data` | 本地 / test 前端页面看效果 | 已完成；仅 dev/test 受控使用 |
 | P1 | Message Notification 列表 / 详情接口 | 信息提醒页或订单详情只读卡片 | 未完成独立接口；可先通过任务列表 / 任务详情展示 `INFORMATIONAL_MESSAGE` |
 | P1 | 任务卡前端字段白名单元数据接口 | 字段白名单调试、版本对齐 | 未完成；若任务详情已透出完整元数据，可后置 |
 | 后置 | 普通任务切换订单接口 | 任务详情订单归属调整 | 未完成；已确认后置 |
@@ -38,7 +39,8 @@
 | `GET /api/source-messages/{id}/original` | 已完成单封原文受控读取 | 谨慎接入 | 只能读单封邮件，不能返回同一 conversation 全量邮件。 |
 | `GET /api/reservation/orders` | 已完成第一版 | 可以 | 默认查询全部订单状态；`open_task_count` 排除 `COMPLETED` 和 `FAILED`。 |
 | `GET /api/source-messages/{sourceMessageId}/conversation` | 已完成第一版 | 可以 | 返回完整 text/html、媒体外链和关联订单 / 任务摘要；前端不传原文读取 key。 |
-| `GET /api/source-message-conversations/{externalConversationId}` | 未发现后端实现 | 不可以 | 可作为后端偏好的邮件会话详情路径。 |
+| `POST /api/system/reservation/demo-data` | 已完成 | 仅本地 / test 联调可用 | 默认关闭，必须后端配置访问口令；不能作为生产页面接口。 |
+| `GET /api/source-message-conversations/{externalConversationId}` | 未发现后端实现 | 不可以 | 历史讨论过的候选路径，当前不提供；前端统一使用 `GET /api/source-messages/{sourceMessageId}/conversation`。 |
 | `GET /api/reservation/message-notifications` | 未发现后端实现 | 不可以 | 如需独立信息提醒页再新增；第一版可先用任务接口过滤。 |
 | `GET /api/reservation/task-card-field-whitelist` | 未发现后端实现 | 不可以 | 若任务详情 `fields[]` 已补齐 3.0 元数据，可后置。 |

@@ -155,7 +157,7 @@ GET /api/reservation/orders/{orderId}
 | `orderId` | 是 | 订单 ID。 |
 | `hotel_id` | 否 | 酒店 ID。第一版如果只有单酒店，可为空。 |
 | `include_tasks` | 否 | 是否返回任务时间线，默认 `true`。 |
-| `include_source_summary` | 否 | 是否返回来源消息摘要，默认 `true`。 |
+| `include_source_summary` | 否 | 是否返回来源消息摘要，默认 `true`；第一版参数保留，前端暂不要依赖它做字段裁剪。 |

 建议返参：

@@ -227,7 +229,7 @@ GET /api/reservation/orders
 | `order_status` | 否 | `TEMPORARY`、`ACTIVE`、`ENDED`、`LOGIC_DELETED`。 |
 | `group_code` | 否 | 按 Group Code 精确或模糊查询，后端决定。 |
 | `confirmation_number` | 否 | 按 Confirmation No 查询。 |
-| `keyword` | 否 | 前端搜索框统一关键词。 |
+| `keyword` | 否 | 前端搜索框统一关键词；后端匹配订单字段，也会匹配来源消息安全摘要命中的 SourceMessage ID。 |
 | `page_num` | 否 | 页码。 |
 | `page_size` | 否 | 每页条数。 |

@@ -258,7 +260,48 @@ GET /api/reservation/orders
 }
 ```

-## 6. 邮件会话详情接口
+## 6. 前端联调演示数据 seed 接口
+
+建议路径：
+
+```text
+POST /api/system/reservation/demo-data
+```
+
+当前状态：后端已完成第一版。该接口只用于本地 / test 联调造数，默认关闭，不是生产业务页面接口。
+
+启用条件：
+
+| 配置 | 说明 |
+| --- | --- |
+| `reservation.demo-data.enabled=true` | 显式启用接口，也可用环境变量 `RESERVATION_DEMO_DATA_ENABLED=true`。 |
+| `reservation.demo-data.access-key` | 配置访问口令，也可用环境变量 `RESERVATION_DEMO_DATA_ACCESS_KEY`。 |
+| `X-TH-Hotel-Demo-Data-Key` | 请求头必须携带，与后端配置口令一致。 |
+
+请求示例：
+
+```json
+{
+  "hotel_id": "HOTEL-TEST",
+  "run_label": "frontend-smoke"
+}
+```
+
+返回说明：
+
+| 字段 | 说明 |
+| --- | --- |
+| `demo_run_id` | 本次 seed 唯一关键词，可用于任务列表 / 订单列表搜索。 |
+| `source_messages[]` | 生成的来源消息 ID、外部消息 ID 和外部会话 ID。 |
+| `orders[]` | 生成的订单 ID、订单状态和展示键。 |
+| `tasks[]` | 生成的任务 ID、任务类型、任务 subtype 和任务状态。 |
+| `entrypoints` | 可直接访问的任务列表、订单列表、订单详情、任务详情、邮件会话详情 URL。 |
+
+第一版 seed 覆盖：队列阻塞、已完成 OPERA 模拟、OPERA 失败可重试、Fallback 人工复核、Message Notification、邮件会话完整 HTML / 附件 / 内联图片。
+
+前端注意：不要把访问口令写入前端仓库、浏览器环境变量或构建产物；该接口只能由本地联调人员手动调用或由受控测试脚本调用。
+
+## 7. 邮件会话详情接口

 建议优先路径：

@@ -266,13 +309,13 @@ GET /api/reservation/orders
 GET /api/source-messages/{sourceMessageId}/conversation
 ```

-可选补充路径：
+历史候选路径，当前不提供：

 ```text
 GET /api/source-message-conversations/{externalConversationId}
 ```

-当前状态：后端已完成第一版。前端入口从某个任务的 `source_message_id` 进入，后端根据该 SourceMessage 找到 `external_conversation_id`，再返回同一邮件会话下的全部邮件。
+当前状态：`GET /api/source-messages/{sourceMessageId}/conversation` 已完成第一版。前端入口从某个任务的 `source_message_id` 进入，后端根据该 SourceMessage 找到 `external_conversation_id`，再返回同一邮件会话下的全部邮件。

 中文说明：

@@ -347,7 +390,7 @@ GET /api/source-message-conversations/{externalConversationId}
 }
 ```

-## 7. 任务详情接口字段元数据扩展
+## 8. 任务详情接口字段元数据扩展

 建议路径：

@@ -451,7 +494,7 @@ GET /api/reservation/tasks/{taskId}
 - `result_type`、`task_type`、`task_subtype`、`default_value_source` 当前从后端字段矩阵定义透出。
 - 如果后端已有更细的字段来源或适用场景元数据，可后续再扩展 `field_source`、`applicable_scenario`，不作为本轮 P0 阻塞项。

-## 8. Message Notification 列表 / 详情接口
+## 9. Message Notification 列表 / 详情接口

 当前状态：未发现后端独立 Message Notification 列表 / 详情接口。当前后端已经支持 `INFORMATIONAL_MESSAGE` 任务类型进入任务体系，第一版前端可以先通过 `GET /api/reservation/tasks?task_type=INFORMATIONAL_MESSAGE` 和 `GET /api/reservation/tasks/{taskId}` 展示信息提醒任务。仅当产品确认需要独立“信息提醒页”时，再新增本节接口。

@@ -492,7 +535,7 @@ GET /api/reservation/message-notifications/{taskId}
 }
 ```

-## 9. 任务卡前端字段白名单元数据接口
+## 10. 任务卡前端字段白名单元数据接口

 是否需要该接口待确认。如果任务详情接口 `fields[]` 已透出 3.0 所需元数据，则第一版可以不做独立白名单接口；如果后续需要字段矩阵调试页、版本对齐页或前端预加载全部任务卡配置，再补独立接口。

@@ -530,7 +573,7 @@ GET /api/reservation/task-card-field-whitelist
 }
 ```

-## 10. 已确认后置接口
+## 11. 已确认后置接口

 普通任务切换订单接口继续后置，前端暂不开发提交能力。后续如果恢复开发，建议另行确认：

@@ -559,7 +602,7 @@ POST /api/reservation/tasks/{taskId}/order-binding
 }
 ```

-## 11. 待确认问题
+## 12. 待确认问题

 - 订单列表、任务列表当前统一使用 `items + page` 分页结构；邮件会话详情不分页，返回同一会话全部邮件。
 - 邮件会话详情接口已优先使用 `GET /api/source-messages/{sourceMessageId}/conversation`。
--- a/docs/project/requirements/M002-backend-checkpoint-plan.md
+++ b/docs/project/requirements/M002-backend-checkpoint-plan.md
@@ -317,8 +317,9 @@ Controller、Service、Service 实现类的方法必须有中文注释。Entity
 - 已补齐 `GET /api/reservation/tasks` 来源邮件会话摘要字段：`source_sender_summary`、`source_received_at`、`external_conversation_id`、`conversation_message_count`。
 - 已补齐 `GET /api/reservation/orders/{orderId}` 的 `tasks[]` 来源邮件会话摘要字段。
 - 已补齐 `GET /api/reservation/tasks/{taskId}` 顶层来源邮件会话字段，并在 `fields[]` 透出 `result_type`、`task_type`、`task_subtype`、`default_value_source`。
- 已实现订单列表接口 `GET /api/reservation/orders`，默认查询全部订单状态，支持酒店、订单状态、Group Code、Confirmation No.、关键词和分页筛选；`open_task_count` 排除 `COMPLETED` 和 `FAILED`。
+- 已实现订单列表接口 `GET /api/reservation/orders`，默认查询全部订单状态，支持酒店、订单状态、Group Code、Confirmation No.、关键词和分页筛选；`keyword` 可匹配订单字段，也可匹配来源消息安全摘要命中的 SourceMessage ID；`open_task_count` 排除 `COMPLETED` 和 `FAILED`。
 - 已实现邮件会话详情接口 `GET /api/source-messages/{sourceMessageId}/conversation`，根据 SourceMessage 定位外部会话，返回完整 text/html、附件外链、内联图片、来源摘要和关联订单 / 任务摘要；原文读取审计由后端内部写入。
+- 已实现 dev/test 受控演示数据 seed 接口 `POST /api/system/reservation/demo-data`，默认关闭，需配置 `reservation.demo-data.enabled=true` 和访问口令；生成真实落库的任务列表、订单列表、订单详情、任务详情和邮件会话详情演示数据。
 - Message Notification 独立列表 / 详情、任务卡前端字段白名单独立接口继续后置；第一版分别复用任务列表 / 任务详情和 `fields[]` 元数据。

 ## 12. 建议开发节奏