补齐前端P0查询接口

2026-07-08 16:34:27 +08:00
parent 66a613d6cd
commit 3c1649a567
34 changed files with 1662 additions and 39 deletions
--- a/docs/project/frontend-backend/frontend-to-backend-api-requests.md
+++ b/docs/project/frontend-backend/frontend-to-backend-api-requests.md
@@ -8,14 +8,41 @@

 | 优先级 | 接口 | 页面 / 场景 | 状态 |
 | --- | --- | --- | --- |
-| P0 | 任务列表 / 工作台接口 | 任务列表页、首页工作台 | 已实现第一版 |
-| P0 | 订单详情与任务时间线接口 | 订单详情页 | 已实现第一版 |
-| P1 | 订单列表接口 | 订单检索、订单入口 | 待后端设计 |
-| P1 | Message Notification 列表 / 详情接口 | 信息提醒页或订单详情只读卡片 | 待后端设计 |
-| P1 | 任务卡前端字段白名单元数据接口 | 任务详情动态渲染 | 待确认是否需要后端提供 |
-| 后置 | 普通任务切换订单接口 | 任务详情订单归属调整 | 已确认后置 |
+| P0 | 订单列表接口 `GET /api/reservation/orders` | 订单列表页、首页工作台 | 已完成第一版 |
+| P0 | 任务列表接口 `GET /api/reservation/tasks` | 任务列表菜单、订单详情任务入口 | 已完成第一版，已补来源邮件会话字段 |
+| P0 | 订单详情接口 `GET /api/reservation/orders/{orderId}` | 订单详情页 | 已完成第一版，已补 `tasks[]` 每个任务的来源邮件会话字段 |
+| P0 | 任务详情读取接口 `GET /api/reservation/tasks/{taskId}` | 任务详情页动态渲染 | 已完成第一版，已补来源邮件字段和 3.0 字段元数据 |
+| P0 | 任务详情操作接口 | 任务详情保存、确认、OPERA、审计 | 已完成；前端可直接接入 |
+| P0 | 邮件会话详情接口 `GET /api/source-messages/{sourceMessageId}/conversation` | 邮件会话详情页 | 已完成第一版 |
+| P1 | Message Notification 列表 / 详情接口 | 信息提醒页或订单详情只读卡片 | 未完成独立接口；可先通过任务列表 / 任务详情展示 `INFORMATIONAL_MESSAGE` |
+| P1 | 任务卡前端字段白名单元数据接口 | 字段白名单调试、版本对齐 | 未完成；若任务详情已透出完整元数据，可后置 |
+| 后置 | 普通任务切换订单接口 | 任务详情订单归属调整 | 未完成；已确认后置 |

-## 3. 任务列表 / 工作台接口
+## 2.1 后端当前接口完成度核对
+
+本节按 2026-07-08 当前后端 Controller 和 result record 核对，避免重复要求后端实现已经存在的接口。
+
+| 接口 / 能力 | 当前后端状态 | 前端是否可直接接入 | 仍需后端处理 |
+| --- | --- | --- | --- |
+| `GET /api/reservation/tasks` | 已完成第一版，已补来源邮件会话字段 | 可以 | 暂无。 |
+| `GET /api/reservation/orders/{orderId}` | 已完成第一版，已补 `tasks[]` 来源邮件会话字段 | 可以 | 暂无。 |
+| `GET /api/reservation/tasks/{taskId}` | 已完成第一版，已补任务顶层来源邮件字段和 `fields[]` 3.0 元数据 | 可以 | 暂无。 |
+| `PUT /api/reservation/tasks/{taskId}/draft` | 已完成 | 可以 | 暂无。 |
+| `POST /api/reservation/tasks/{taskId}/confirm` | 已完成 | 可以 | 暂无。 |
+| `GET /api/reservation/tasks/{taskId}/audits` | 已完成 | 可以 | 暂无。 |
+| `POST /api/reservation/tasks/{taskId}/opera-operations/{operationId}/execute` | 已完成第一版模拟操作 | 可以 | 暂无；真实 OPERA 写入另行确认。 |
+| `POST /api/reservation/tasks/{taskId}/opera-operations/{operationId}/retry` | 已完成第一版模拟重试 | 可以 | 暂无；真实 OPERA 重试另行确认。 |
+| `POST /api/reservation/tasks/{taskId}/manual-review-conversions` | 已完成 | 可以 | 暂无。 |
+| `GET /api/source-messages` | 已完成安全摘要列表 | 可以 | 不能替代邮件会话全文接口。 |
+| `GET /api/source-messages/{id}` | 已完成单条安全摘要 | 可以 | 不能替代邮件会话全文接口。 |
+| `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}` | 未发现后端实现 | 不可以 | 可作为后端偏好的邮件会话详情路径。 |
+| `GET /api/reservation/message-notifications` | 未发现后端实现 | 不可以 | 如需独立信息提醒页再新增；第一版可先用任务接口过滤。 |
+| `GET /api/reservation/task-card-field-whitelist` | 未发现后端实现 | 不可以 | 若任务详情 `fields[]` 已补齐 3.0 元数据，可后置。 |
+
+## 3. 任务列表 / 工作台接口字段补齐

 建议路径：

@@ -23,7 +50,31 @@
 GET /api/reservation/tasks
 ```

-当前状态：后端已按 P0 最小诉求实现第一版。接口只返回任务摘要、订单展示键、来源消息主题和实时可处理状态，不返回完整 AI payload、邮件正文或附件 URL。
+当前状态：后端已按 P0 最小诉求实现第一版，前端任务列表页可以直接接入该接口。接口已返回任务摘要、订单展示键、来源消息 ID / 主题、来源邮件会话摘要和实时可处理状态，不返回完整 AI payload、邮件正文或附件 URL。
+
+本轮前端新增“任务列表”菜单，并且任务列表、订单详情任务队列都需要能跳转到该任务来源消息所在的完整邮件会话。因此建议在现有返回项上补齐来源邮件会话摘要字段。
+
+已完成字段：
+
+| 字段 | 说明 |
+| --- | --- |
+| `task_id` | 任务 ID。 |
+| `order_id` | 关联订单 ID。 |
+| `hotel_id` | 酒店上下文 ID。 |
+| `display_order_key` | 前端优先展示的业务号或临时订单号。 |
+| `temporary_order_no` | 临时订单号。 |
+| `task_type` | 系统主任务类型。 |
+| `task_subtype` | 任务 subtype。 |
+| `task_status` | 任务状态。 |
+| `card_name` | 任务卡展示名称。 |
+| `queue_sequence` | 同订单队列顺序。 |
+| `queue_participation` | 是否参与订单执行队列。 |
+| `can_process` | 当前是否可处理。 |
+| `readonly_reason_code` | 只读原因代码。 |
+| `source_message_id` | 来源 SourceMessage Inbox ID。 |
+| `source_subject` | 来源消息主题摘要。 |
+| `created_at` | 任务创建时间。 |
+| `updated_at` | 任务更新时间。 |

 建议入参：

@@ -60,6 +111,10 @@ GET /api/reservation/tasks
      "readonly_reason_code": "PREVIOUS_TASK_NOT_FINISHED",
      "source_message_id": "30001",
      "source_subject": "Booking Update",
+      "source_sender_summary": "guest@example.com",
+      "source_received_at": "2026-07-08T02:58:00Z",
+      "external_conversation_id": "thread-20260708-001",
+      "conversation_message_count": 6,
      "created_at": "2026-07-08T03:00:00Z",
      "updated_at": "2026-07-08T03:10:00Z"
    }
@@ -72,7 +127,16 @@ GET /api/reservation/tasks
 }
 ```

-## 4. 订单详情与任务时间线接口
+本轮已新增字段：
+
+| 字段 | 说明 |
+| --- | --- |
+| `source_sender_summary` | 来源消息发件人摘要，用于任务列表快速判断来源。 |
+| `source_received_at` | 来源消息接收时间，用于任务列表排序和展示。 |
+| `external_conversation_id` | 来源消息所属邮件会话 ID，用于打开完整邮件会话详情。 |
+| `conversation_message_count` | 会话内邮件数量，用于提示用户该入口是整段会话，不是单封邮件。 |
+
+## 4. 订单详情与任务时间线接口字段补齐

 建议路径：

@@ -80,13 +144,16 @@ GET /api/reservation/tasks
 GET /api/reservation/orders/{orderId}
 ```

-当前状态：后端已按 P0 最小诉求实现第一版。接口返回订单摘要和同订单任务时间线；`include_tasks=false` 时只返回订单摘要。`include_source_summary` 第一版保留入参但订单时间线暂不展开来源摘要，来源主题请优先从任务列表接口读取。
+当前状态：后端已按 P0 最小诉求实现第一版。接口返回订单摘要和同订单任务时间线；`include_tasks=false` 时只返回订单摘要。任务时间线已补齐每个任务的来源邮件会话摘要。
+
+订单详情低保真已确认沿用“订单摘要 + 同订单任务队列 + 当前任务卡 + OPERA 模拟操作 + 审计时间线”。同订单任务队列里的每个任务都需要自己的“查看邮件会话”入口，因为不同任务可能来自不同邮件或不同邮件会话。因此建议补齐 `tasks[]` 中每个任务的来源邮件会话字段。

 建议入参：

 | 参数 | 必填 | 说明 |
 | --- | --- | --- |
 | `orderId` | 是 | 订单 ID。 |
+| `hotel_id` | 否 | 酒店 ID。第一版如果只有单酒店，可为空。 |
 | `include_tasks` | 否 | 是否返回任务时间线，默认 `true`。 |
 | `include_source_summary` | 否 | 是否返回来源消息摘要，默认 `true`。 |

@@ -118,6 +185,12 @@ GET /api/reservation/orders/{orderId}
      "queue_participation": true,
      "can_process": false,
      "readonly_reason_code": "TASK_FINISHED",
+      "source_message_id": "30001",
+      "source_subject": "Booking Request",
+      "source_sender_summary": "guest@example.com",
+      "source_received_at": "2026-07-08T02:58:00Z",
+      "external_conversation_id": "thread-20260708-001",
+      "conversation_message_count": 6,
      "created_at": "2026-07-08T03:00:00Z"
    }
  ],
@@ -125,6 +198,17 @@ GET /api/reservation/orders/{orderId}
 }
 ```

+本轮已新增字段：
+
+| 字段 | 说明 |
+| --- | --- |
+| `source_message_id` | 任务对应的来源 SourceMessage Inbox ID。 |
+| `source_subject` | 来源消息主题摘要。 |
+| `source_sender_summary` | 来源消息发件人摘要。 |
+| `source_received_at` | 来源消息接收时间。 |
+| `external_conversation_id` | 来源消息所属邮件会话 ID。 |
+| `conversation_message_count` | 会话内邮件数量。 |
+
 ## 5. 订单列表接口

 建议路径：
@@ -133,6 +217,8 @@ GET /api/reservation/orders/{orderId}
 GET /api/reservation/orders
 ```

+当前状态：后端已完成第一版。默认查询全部订单状态；`open_task_count` 排除 `COMPLETED` 和 `FAILED`，`next_processable_task_id` 按同订单队列可处理状态实时计算。
+
 建议入参：

 | 参数 | 必填 | 说明 |
@@ -154,6 +240,7 @@ GET /api/reservation/orders
      "order_id": "20001",
      "hotel_id": "HOTEL-TEST",
      "order_status": "ACTIVE",
+      "display_order_key": "GRP-001",
      "temporary_order_no": null,
      "confirmation_number": "CNF123456",
      "group_code": "GRP-001",
@@ -171,7 +258,202 @@ GET /api/reservation/orders
 }
 ```

-## 6. Message Notification 列表 / 详情接口
+## 6. 邮件会话详情接口
+
+建议优先路径：
+
+```text
+GET /api/source-messages/{sourceMessageId}/conversation
+```
+
+可选补充路径：
+
+```text
+GET /api/source-message-conversations/{externalConversationId}
+```
+
+当前状态：后端已完成第一版。前端入口从某个任务的 `source_message_id` 进入，后端根据该 SourceMessage 找到 `external_conversation_id`，再返回同一邮件会话下的全部邮件。
+
+中文说明：
+
+- “全部邮件”指同一个 `externalConversationId` 下的历史邮件、当前邮件和后续回复，不是只展示任务对应的单封来源邮件。
+- 邮件会话详情页需要展示完整正文或清洗后的 HTML、附件、内联图片、发件人摘要、发送 / 接收时间、主题和关联订单 / 任务。
+- 前端不在页面上做业务截断或隐藏；但仍只调用本项目后端接口，不直接访问邮箱、AgentBus、数据库或外部附件 URL Secret。
+- 如果后端仍需要审计原文读取，应由后端在该业务接口内部处理；前端不保存 `X-TH-Hotel-Source-Original-Read-Key` 一类受控访问 key。
+
+建议入参：
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `sourceMessageId` | 是 | 入口来源消息 ID。后端据此定位 `externalConversationId`。 |
+
+当前第一版不额外接收 `hotelId`、`includeBody`、`includeRelated`。后端默认按 SourceMessage 自身酒店上下文查询同会话邮件，返回完整 text/html 和关联订单 / 任务摘要，并在内部写原文读取审计。
+
+建议返参：
+
+```json
+{
+  "conversation": {
+      "external_conversation_id": "thread-20260708-001",
+      "hotel_id": "HOTEL-TEST",
+      "channel": "EMAIL",
+      "subject": "Re: Booking Update",
+      "message_count": 6,
+      "first_received_at": "2026-07-06T01:10:00Z",
+      "last_received_at": "2026-07-08T03:28:00Z"
+  },
+  "messages": [
+    {
+      "id": "30001",
+      "external_message_id": "msg-001",
+      "external_conversation_id": "thread-20260708-001",
+      "sender_summary": "guest@example.com",
+      "subject": "Booking Request",
+      "received_at": "2026-07-06T01:10:00Z",
+      "source_sent_at": "2026-07-06T01:08:00Z",
+      "text_body": "完整邮件正文",
+      "html_body": "<p>完整邮件 HTML</p>",
+      "html_sanitize_required": true,
+      "inline_images": [],
+      "attachments": [
+        {
+          "mediaType": "ATTACHMENT",
+          "fileName": "rooming-list.xlsx",
+          "contentType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+          "sizeBytes": 10240,
+          "externalUrl": "由后端决定是否返回可访问 URL",
+          "externalMediaId": "media-001"
+        }
+      ],
+      "related_orders": [
+        {
+          "order_id": "20001",
+          "display_order_key": "GRP-001",
+          "order_status": "ACTIVE"
+        }
+      ],
+      "related_tasks": [
+        {
+          "task_id": "10001",
+          "order_id": "20001",
+          "task_type": "NEW_BOOKING",
+          "task_subtype": "NEW_BOOKING",
+          "task_status": "PENDING_CONFIRM",
+          "card_name": "New Booking"
+        }
+      ]
+    }
+  ]
+}
+```
+
+## 7. 任务详情接口字段元数据扩展
+
+建议路径：
+
+```text
+GET /api/reservation/tasks/{taskId}
+```
+
+当前状态：后端已有任务详情接口，前端任务详情页可以接入。该接口已返回 `fields[]`、草稿、确认 payload、可处理状态和 OPERA 模拟操作；本轮已透出来源邮件会话字段，以及 `docs/import/20260708/任务卡前端展示字段表 3.0.xlsx` 中 P0 需要的字段元数据。
+
+任务详情页面相关已完成接口：
+
+| 接口 | 用途 | 后端状态 |
+| --- | --- | --- |
+| `GET /api/reservation/tasks/{taskId}` | 读取任务详情、字段矩阵、当前值、可处理状态、OPERA 操作摘要。 | 已完成第一版，已补本节字段。 |
+| `PUT /api/reservation/tasks/{taskId}/draft` | 保存任务卡草稿。 | 已完成。 |
+| `POST /api/reservation/tasks/{taskId}/confirm` | 最终确认任务卡字段。 | 已完成。 |
+| `GET /api/reservation/tasks/{taskId}/audits` | 查询任务审计流水。 | 已完成。 |
+| `POST /api/reservation/tasks/{taskId}/opera-operations/{operationId}/execute` | 执行 OPERA 模拟操作。 | 已完成第一版模拟。 |
+| `POST /api/reservation/tasks/{taskId}/opera-operations/{operationId}/retry` | 重试失败的 OPERA 模拟操作。 | 已完成第一版模拟。 |
+| `POST /api/reservation/tasks/{taskId}/manual-review-conversions` | 将 Fallback / manual_review 转换为具体任务类型。 | 已完成。 |
+
+已完成的 `fields[]` 字段：
+
+| 字段 | 说明 |
+| --- | --- |
+| `row_number` | 字段矩阵行号。 |
+| `card_name` | 任务卡名称。 |
+| `display_area` | 前端展示区域。 |
+| `field_path` | 字段路径。 |
+| `display_name` | 展示名。 |
+| `visible` | 是否展示。 |
+| `editable` | 是否可编辑。 |
+| `input_editable` | 是否输入方式编辑。 |
+| `select_editable` | 是否下拉方式编辑。 |
+| `date_picker` | 是否日期选择。 |
+| `number_input` | 是否数字输入。 |
+| `file_display` | 是否文件展示。 |
+| `table_editable` | 是否表格编辑。 |
+| `enum_options` | 枚举选项。 |
+| `required_rule` | 必填规则。 |
+| `display_condition` | 展示条件。 |
+| `validation_rule` | 校验规则。 |
+| `write_path` | 写入路径。 |
+| `opera_write_participation` | 是否参与 OPERA 写入。 |
+| `opera_parameter_mapping` | OPERA 参数映射。 |
+| `notes` | 备注。 |
+| `value` | 当前回显值。 |
+
+本轮已补字段：
+
+| 位置 | 字段 | 说明 |
+| --- | --- | --- |
+| 顶层 | `source_subject` | 任务来源消息主题摘要。 |
+| 顶层 | `source_sender_summary` | 任务来源消息发件人摘要。 |
+| 顶层 | `source_received_at` | 任务来源消息接收时间。 |
+| 顶层 | `external_conversation_id` | 任务来源消息所属邮件会话 ID。 |
+| 顶层 | `conversation_message_count` | 会话内邮件数量。 |
+| `fields[]` | `result_type` | 3.0 字段表中的结果类型，用于前端调试和字段分组校验。 |
+| `fields[]` | `task_type` | 3.0 字段表中的任务主类型。 |
+| `fields[]` | `task_subtype` | 3.0 字段表中的任务 subtype / 业务动作。 |
+| `fields[]` | `default_value_source` | 3.0 字段表中的默认值 / 回显来源。 |
+
+建议返参增量示例：
+
+```json
+{
+  "task_id": "10001",
+  "order_id": "20001",
+  "source_message_id": "30001",
+  "source_subject": "Booking Update",
+  "source_sender_summary": "guest@example.com",
+  "source_received_at": "2026-07-08T02:58:00Z",
+  "external_conversation_id": "thread-20260708-001",
+  "conversation_message_count": 6,
+  "system_task_type": "NEW_BOOKING",
+  "task_card_type": "NEW_BOOKING",
+  "task_status": "PENDING_CONFIRM",
+  "field_contract_version": "20260708-3.0",
+  "fields": [
+    {
+      "row_number": 2,
+      "card_name": "New Booking",
+      "result_type": "RESERVATION",
+      "task_type": "NEW_BOOKING",
+      "task_subtype": "NEW_BOOKING",
+      "display_area": "基础信息",
+      "field_path": "case_keys.group_code",
+      "display_name": "Group Code",
+      "visible": "是",
+      "editable": "否",
+      "default_value_source": "AI识别结果 / 已确认草稿回显",
+      "value": "GRP-001"
+    }
+  ]
+}
+```
+
+中文说明：
+
+- 如果前端只做“按后端字段直接渲染”，现有 `fields[]` 可以支撑第一版表单展示；本轮已经扩展 `ReservationTaskFieldResult`，避免前端维护第二套字段矩阵。
+- `result_type`、`task_type`、`task_subtype`、`default_value_source` 当前从后端字段矩阵定义透出。
+- 如果后端已有更细的字段来源或适用场景元数据，可后续再扩展 `field_source`、`applicable_scenario`，不作为本轮 P0 阻塞项。
+
+## 8. Message Notification 列表 / 详情接口
+
+当前状态：未发现后端独立 Message Notification 列表 / 详情接口。当前后端已经支持 `INFORMATIONAL_MESSAGE` 任务类型进入任务体系，第一版前端可以先通过 `GET /api/reservation/tasks?task_type=INFORMATIONAL_MESSAGE` 和 `GET /api/reservation/tasks/{taskId}` 展示信息提醒任务。仅当产品确认需要独立“信息提醒页”时，再新增本节接口。

 建议路径：

@@ -205,13 +487,14 @@ GET /api/reservation/message-notifications/{taskId}
  "informational_message": "该消息仅作信息提醒，不需要执行 OPERA 操作。",
  "attachments": [],
  "source_message_id": "30009",
+  "external_conversation_id": "thread-20260708-009",
  "created_at": "2026-07-08T03:00:00Z"
 }
 ```

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

-是否需要该接口待确认。如果前端直接读取或内置 `docs/import/20260708/任务卡前端展示字段表 3.0.xlsx` 转换后的配置，则第一版可以不做。
+是否需要该接口待确认。如果任务详情接口 `fields[]` 已透出 3.0 所需元数据，则第一版可以不做独立白名单接口；如果后续需要字段矩阵调试页、版本对齐页或前端预加载全部任务卡配置，再补独立接口。

 建议路径：

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

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

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

@@ -276,9 +559,10 @@ POST /api/reservation/tasks/{taskId}/order-binding
 }
 ```

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

- 任务列表和订单列表是否统一使用同一个分页结构。
- 前端字段白名单由后端接口提供，还是由前端从 Excel 转成静态配置。
+- 订单列表、任务列表当前统一使用 `items + page` 分页结构；邮件会话详情不分页，返回同一会话全部邮件。
+- 邮件会话详情接口已优先使用 `GET /api/source-messages/{sourceMessageId}/conversation`。
+- 任务详情 `fields[]` 已由后端直接透出 P0 需要的 3.0 元数据；独立字段白名单接口后置。
 - Message Notification 是否独立成页面，还是只在订单详情中展示。
- SourceMessage 原文读取在前端页面中的入口和权限方案仍待用户 / 权限体系确认。
+- 邮件会话全文读取的审计策略由后端内部处理；前端不保存原文读取 key。