实现前端演示数据受控生成接口
This commit is contained in:
andy
@@ -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. 需要持续提醒的后置事项
|
||||
|
||||
Reference in New Issue
Block a user