补齐订单详情V4总览接口

docs/project/frontend-backend/frontend-to-backend-api-requests.md

@@ -30,7 +30,7 @@
 | 接口 / 能力 | 当前后端状态 | 前端是否可直接接入 | 仍需后端处理 |
 | --- | --- | --- | --- |
 | `GET /api/reservation/tasks` | 已完成第一版，已补来源邮件会话字段和所属订单状态筛选 | 可以 | `order_status` 按任务所属订单状态过滤；不传时保持当前全部任务列表行为。 |
-| `GET /api/reservation/orders/{orderId}` | 已完成第一版，已补旧 `tasks[]` 来源邮件会话字段和 V4 `v4_order_tasks[]` 时间线 | 可以 | 暂无；`include_tasks=false` 时旧 `tasks[]` 和 V4 `v4_order_tasks[]` 都返回空数组。 |
+| `GET /api/reservation/orders/{orderId}` | 已完成第一版，已补旧 `tasks[]` 来源邮件会话字段、V4 总览和 V4 `v4_order_tasks[]` 时间线 | 可以 | 暂无；`include_tasks=false` 时旧 `tasks[]`、V4 `v4_order_tasks[]` 和 `related_source_messages[]` 都返回空数组，`order_overview` 为空快照，`next_v4_action.action_type=NONE`。 |
 | `GET /api/reservation/tasks/{taskId}` | 已完成第一版，已补任务顶层来源邮件字段和 `fields[]` 3.0 元数据 | 可以 | 当前 Controller 不接收 `hotel_id`；如后续多酒店隔离需要前端显式传酒店上下文，请后端补可选入参或确认按 taskId 全局唯一即可。 |
 | `PUT /api/reservation/tasks/{taskId}/draft` | 已完成 | 可以 | 当前 Controller 不接收 `hotel_id`；如写操作需要酒店上下文幂等 / 权限校验，请后端补可选入参或请求体字段。 |
 | `POST /api/reservation/tasks/{taskId}/confirm` | 已完成 | 可以 | 当前 Controller 不接收 `hotel_id`；如写操作需要酒店上下文幂等 / 权限校验，请后端补可选入参或请求体字段。 |
@@ -47,7 +47,7 @@
 | `POST /api/system/reservation/demo-data` | 已完成 | 仅本地 / test 联调可用 | 默认关闭，必须后端配置访问口令；不能作为生产页面接口。 |
 | `POST /api/system/debug/eml-superagent-runs` | 已完成第一版 | 仅 dev/test Debug 页面可用 | 默认关闭，必须后端配置访问口令、阿里云 OSS 和 SuperAgent Open API；第一版只展示 SuperAgent 结果，不创建订单和任务；已能识别旧 S000/S999 和新结构化 S10/S99。 |
 | `GET /api/source-message-conversations/{externalConversationId}` | 未发现后端实现 | 不可以 | 历史讨论过的候选路径，当前不提供；前端统一使用 `GET /api/source-messages/{sourceMessageId}/conversation`。 |
-| `GET /api/reservation/message-notifications` | 未发现后端实现 | 不可以 | 第一版不做独立接口；旧 S000/S999 已通过 `SOURCE_MESSAGE_ONLY` 任务展示，0711 P0 新 S10/S99 也继续复用任务列表 / 任务详情只读展示。 |
+| `GET /api/reservation/message-notifications` | 未发现后端实现 | 不可以 | 历史候选路径，当前不提供。旧 S000/S999 和 V3 S10/S99 兼容数据通过 `SOURCE_MESSAGE_ONLY` 任务展示；V4 S10/S99 新数据走 V4 工作台和 `/api/reservation/source-notifications/{notificationId}`，不要再请求本候选路径。 |
 | `GET /api/reservation/task-card-field-whitelist` | 未发现后端实现 | 不可以 | 若任务详情 `fields[]` 已补齐 3.0 元数据，可后置。 |
 | `GET /api/reservation/lookups/accounts` / `room-types` / `rate-codes` | M002 V4 CP11 已实现 | 可以 | 用于 V4 任务卡下拉 / 搜索选择；Bearer token + `RESERVATION_TASK_READ` + 酒店访问权；支持 `hotel_id`、`keyword`、`page_num`、`page_size`，第一版只返回 ACTIVE 目录。 |
 
@@ -97,7 +97,7 @@ GET /api/reservation/tasks
 | --- | --- | --- |
 | `hotel_id` | 否 | 酒店 ID。单酒店阶段默认可为空，由后端按当前用户上下文或平台酒店表唯一 `ACTIVE` 酒店解析；显式传值时后端会校验访问权限。 |
 | `order_id` | 否 | 按订单过滤。 |
-| `task_type` | 否 | 当前任务列表筛选只提供 `NEW_BOOKING`、`UPDATE_BOOKING`、`CANCEL_BOOKING`、`MANUAL_REVIEW`、`SOURCE_MESSAGE_ONLY`；不再提供历史 `INFORMATIONAL_MESSAGE` 筛选项。0711 P0 结构化 S10/S99 复用 `SOURCE_MESSAGE_ONLY` 只读源邮件通知卡。 |
+| `task_type` | 否 | 当前旧任务列表筛选只提供 `NEW_BOOKING`、`UPDATE_BOOKING`、`CANCEL_BOOKING`、`MANUAL_REVIEW`、`SOURCE_MESSAGE_ONLY`；不再提供历史 `INFORMATIONAL_MESSAGE` 筛选项。旧 S000/S999 和 V3 S10/S99 兼容数据复用 `SOURCE_MESSAGE_ONLY` 只读源邮件通知卡；V4 S10/S99 新数据不进旧任务列表，走 V4 工作台和来源通知详情。 |
 | `task_status` | 否 | 任务状态过滤。 |
 | `task_subtype` | 否 | 任务卡 subtype 过滤。 |
 | `order_status` | 否 | 按任务所属订单状态过滤，支持 `TEMPORARY`、`ACTIVE`、`ENDED`、`LOGIC_DELETED`；不传时保持当前行为。 |
@@ -165,9 +165,9 @@ GET /api/reservation/tasks
 GET /api/reservation/orders/{orderId}
 ```
 
-当前状态：后端已按 P0 最小诉求实现第一版。接口返回订单摘要、旧 V2/V3 同订单任务时间线和 V4 订单任务时间线；`include_tasks=false` 时只返回订单摘要，旧 `tasks[]` 和 V4 `v4_order_tasks[]` 都为空数组。旧任务时间线已补齐每个任务的来源邮件会话摘要。
+当前状态：后端已按 P0 最小诉求实现第一版，并在 M002 V4 CP15.1 补齐订单详情 V4 总览字段。接口返回订单摘要、V4 当前确认快照、V4 下一步处理入口、关联来源邮件摘要、旧 V2/V3 同订单任务时间线和 V4 订单任务时间线；`include_tasks=false` 时旧 `tasks[]`、V4 `v4_order_tasks[]` 和 `related_source_messages[]` 都返回空数组，`order_overview` 为空快照，`next_v4_action.action_type=NONE`。旧任务时间线已补齐每个任务的来源邮件会话摘要。
 
-订单详情低保真已确认沿用“订单摘要 + 同订单任务队列 + 当前任务卡 + OPERA 模拟操作 + 审计时间线”。同订单任务队列里的每个任务都需要自己的“查看邮件会话”入口，因为不同任务可能来自不同邮件或不同邮件会话。因此 `tasks[]` 中每个任务已补齐来源邮件会话字段。V4 新模型下，同一订单的多卡订单任务通过 `v4_order_tasks[]` 单独返回，前端点击后进入 V4 订单任务详情。
+订单详情页后续应定位为“订单总览 + 当前确认快照 + V4 任务时间线 + 下一步入口”，不是 V4 任务卡处理页。同订单任务队列里的每个任务都需要自己的“查看邮件会话”入口，因为不同任务可能来自不同邮件或不同邮件会话。因此 `tasks[]` 中每个任务已补齐来源邮件会话字段。V4 新模型下，同一订单的多卡订单任务通过 `v4_order_tasks[]` 单独返回，前端点击后进入 V4 订单任务详情。
 
 建议入参：
 
@@ -195,6 +195,45 @@ GET /api/reservation/orders/{orderId}
     "created_at": "2026-07-08T03:00:00Z",
     "updated_at": "2026-07-08T03:10:00Z"
   },
+  "order_overview": {
+    "account_code": "QBD_TRAVEL",
+    "account_name": "Q.B.D. TRAVEL GROUP CO., LTD",
+    "market_code": "LEISURE",
+    "source_code": "TRAVEL_AGENT",
+    "arrival_date": "2026-07-26",
+    "departure_date": "2026-07-29",
+    "rate_code": "BAR",
+    "room_items": [
+      {
+        "room_type_code": "RM1",
+        "room_count": 2
+      }
+    ],
+    "trace_card_status": null,
+    "rooming_list_card_status": null,
+    "payment_card_status": "REVIEW_REQUIRED",
+    "latest_confirmed_at": "2026-07-08T04:20:00Z"
+  },
+  "next_v4_action": {
+    "order_task_id": "40001",
+    "card_id": "41003",
+    "action_type": "REVIEW",
+    "action_status": "REVIEW_REQUIRED",
+    "open_order_task_count": 1
+  },
+  "related_source_messages": [
+    {
+      "source_message_id": "30002",
+      "hotel_id": "HOTEL-TEST",
+      "external_message_id": "AAMk-example",
+      "external_conversation_id": "thread-20260708-002",
+      "subject": "Booking Update",
+      "sender_summary": "guest@example.com",
+      "received_at": "2026-07-08T04:00:00Z",
+      "source_sent_at": null,
+      "conversation_message_count": 2
+    }
+  ],
   "tasks": [
     {
       "task_id": "10001",
@@ -231,6 +270,32 @@ GET /api/reservation/orders/{orderId}
         "review_required_count": 1,
         "confirmed_count": 0
       },
+      "cards": [
+        {
+          "card_id": "41001",
+          "card_type": "SOURCE_MESSAGE_DISPLAY",
+          "event_type": null,
+          "source_event_index": 0,
+          "card_sort_order": 10,
+          "card_status": "READONLY",
+          "review_status": null,
+          "confirmed_by": null,
+          "confirmed_at": null,
+          "latest_activity_at": "2026-07-08T04:00:10Z"
+        },
+        {
+          "card_id": "41003",
+          "card_type": "PAYMENT",
+          "event_type": "PAYMENT",
+          "source_event_index": 2,
+          "card_sort_order": 60,
+          "card_status": "REVIEW_REQUIRED",
+          "review_status": "PENDING",
+          "confirmed_by": null,
+          "confirmed_at": null,
+          "latest_activity_at": "2026-07-08T04:05:00Z"
+        }
+      ],
       "source_message_summary": {
         "source_message_id": "30002",
         "hotel_id": "HOTEL-TEST",
@@ -263,11 +328,20 @@ GET /api/reservation/orders/{orderId}
 | `external_conversation_id` | 来源消息所属邮件会话 ID。 |
 | `conversation_message_count` | 会话内邮件数量。 |
 | `result_type` / `ai_task_type` / `route_code` / `system_process_category` | V3 路由展示字段，和任务列表字段语义一致。 |
+| `order_overview` | V4 订单详情当前确认快照，只从已确认 V4 卡片派生；未确认 AI 建议不会进入这里。 |
+| `order_overview.account_code` / `account_name` / `market_code` / `source_code` | 来自已确认 Basic Information 卡；为空表示 Basic Information 尚未确认或无可靠确认值。 |
+| `order_overview.arrival_date` / `departure_date` / `rate_code` / `room_items[]` | 来自已确认 Room Information 卡；后出现的已确认卡会覆盖前面同字段。 |
+| `order_overview.trace_card_status` / `rooming_list_card_status` / `payment_card_status` | 当前订单下对应业务卡最新状态，方便订单详情页展示是否还有待处理事项。 |
+| `order_overview.latest_confirmed_at` | 当前订单 V4 卡片最近确认 UTC 时间。 |
+| `next_v4_action` | 订单详情页下一步处理入口，口径与订单列表 V4 入口一致；前端点击后跳 `/reservation/order-tasks/{order_task_id}`。 |
+| `next_v4_action.action_type` | `CONFIRM` / `REVIEW` / `NONE`。订单详情页不直接调用确认或复核接口，应进入 V4 订单任务详情页处理。 |
+| `related_source_messages[]` | 当前订单 V4 订单任务关联来源邮件安全摘要去重列表；用于订单页邮件区，不包含正文、HTML 或附件 URL。 |
 | `v4_order_tasks[]` | V4 订单任务时间线数组。旧 `tasks[]` 继续保留；V4 时间线按 `source_received_at`、`source_message_id`、`order_context_index`、`created_at`、数字 ID 正序返回。 |
 | `v4_order_tasks[].order_task_id` | V4 订单任务 ID，字符串。 |
 | `v4_order_tasks[].order_ref` | V4 回调包内订单引用，不等同 PMS 永久订单号。 |
 | `v4_order_tasks[].order_task_status` | V4 订单任务状态，当前为 `OPEN` / `COMPLETED`。 |
 | `v4_order_tasks[].card_counts` | V4 任务卡数量摘要。 |
+| `v4_order_tasks[].cards[]` | V4 订单任务下任务卡安全摘要，只返回状态、复核状态、确认人和确认时间，不返回业务 payload。 |
 | `v4_order_tasks[].source_message_summary` | V4 来源邮件安全摘要，不包含正文、HTML、附件 URL 或 AI 原始 payload。 |
 | `v4_order_tasks[].latest_activity_at` | V4 订单任务自身 `updated_at` 与其下卡片 `updated_at` 的最大 UTC 时间。 |
 
@@ -410,7 +484,7 @@ POST /api/system/reservation/demo-data
 
 仍建议后端确认：
 
-- `GET /api/reservation/tasks` 是否会在结构化 S10/S99 行中稳定返回 `task_type=SOURCE_MESSAGE_ONLY`，或允许返回 `MESSAGE_NOTIFICATION` 并只依赖 `result_type/route_code/system_process_category`；前端当前两种都兼容。
+- `GET /api/reservation/tasks` 中旧 S000/S999 和 V3 S10/S99 兼容行是否稳定返回 `task_type=SOURCE_MESSAGE_ONLY`。V4 S10/S99 已不应从旧任务列表返回，应通过 V4 工作台和来源通知接口展示。
 - `adapter_contract_error` / `unhandled_current_intent` 如果未来也作为独立列表行返回，请保持 `source_message_id` 可用，便于前端继续提供邮件会话入口。
 - 同卡人工复核解阻成功后是否一定返回 `opera_operations[]`。当前文档写“两条 OPERA 模拟操作”，前端实现按实际返回刷新，不假设固定数量。
 - Parent Group `manual_review.reason_code=target_object_unclear` 场景需要任务详情稳定透出 `context_used.parent_identity_candidates[]`。当前 `ReservationTaskDetailResult` 后端 DTO 仅透出 `manual_review`，前端已兼容顶层 `context_used.parent_identity_candidates[]` 或 `manual_review.context_used.parent_identity_candidates[]`，但若后端不透出 candidates，页面只能显示空态提示。
@@ -713,11 +787,11 @@ Content-Type: application/json
 - 如果后端已有更细的字段来源或适用场景元数据，可后续再扩展 `field_source`、`applicable_scenario`，不作为本轮 P0 阻塞项。
 - 前端默认不需要为 `GET /api/reservation/orders`、`GET /api/reservation/tasks`、`GET /api/reservation/orders/{orderId}` 自动拼 `hotel_id`；如已接入酒店选择器，可以传当前选中酒店，后端会校验访问权限。当前 `GET /api/reservation/tasks/{taskId}` 以及任务写操作 Controller 不接收 `hotel_id`；第一版先按 ID 定位，后续多酒店隔离 / 权限方案统一补齐。
 
-## 9. S10/S99 源邮件只读通知卡与历史兼容
+## 9. S10/S99 源邮件只读通知与历史兼容
 
-当前状态：后端不提供独立 Message Notification 列表 / 详情接口。旧 SuperAgent 入口返回 `S000,source_message_id` 或 `S999,source_message_id` 时，后端会创建 `SOURCE_MESSAGE_ONLY` 只读特殊任务；0711 P0 结构化 `S10/S99` 也复用同一只读任务模型。前端已通过 `GET /api/reservation/tasks?task_type=SOURCE_MESSAGE_ONLY` 和 `GET /api/reservation/tasks/{taskId}` 展示；任务列表筛选只保留 `SOURCE_MESSAGE_ONLY`、`S10`、`S99`，不再提供 `S000`、`S999` 历史筛选项。
+当前状态：后端不提供历史候选的 `/api/reservation/message-notifications` 列表 / 详情接口。旧 SuperAgent 入口返回 `S000,source_message_id` 或 `S999,source_message_id` 时，后端会创建 `SOURCE_MESSAGE_ONLY` 只读特殊任务；V3 结构化 `S10/S99` 兼容路径也沿用该旧任务模型。V4 `route_code=S10/S99` 新数据已改为独立来源通知模型，通过 V4 工作台和 `/api/reservation/source-notifications/{notificationId}` 展示，并通过 `/api/reservation/source-notifications/{notificationId}/ack` 确认已读 / 已处理。
 
-0711 P0 新入口已迁移为结构化 `S10/S99`：
+V3 入口兼容语义：
 
 - `S10`：`result_type=source_message_review_notification`，`route_code=S10`，表示未匹配当前支持的业务事件。
 - `S99`：`result_type=source_message_review_notification`，`route_code=S99`，表示输入不足或无法形成业务素材包。
@@ -729,12 +803,13 @@ Content-Type: application/json
 展示规则：
 
 - 旧 `task_type=SOURCE_MESSAGE_ONLY`、`task_subtype=S000/S999`：按只读源邮件通知卡展示。
-- 新 `route_code=S10/S99`：按只读源邮件通知卡展示。
-- 任务列表可见，订单列表不可见。
-- 任务详情只允许查看来源邮件、会话、附件和 SuperAgent 原始返回。
+- V3 `route_code=S10/S99` 兼容数据：按旧只读源邮件通知卡展示。
+- V4 `route_code=S10/S99` 新数据：按来源通知详情展示，可 ack，不通过旧任务详情处理。
+- 旧 `SOURCE_MESSAGE_ONLY` 任务列表可见，订单列表不可见；V4 来源通知在 V4 工作台可见，订单列表和订单详情不可见。
+- 旧任务详情只允许查看来源邮件、会话、附件和 SuperAgent 原始返回；V4 来源通知详情只允许查看来源邮件摘要、通知信息和 ack 状态。
 - 任务详情通过 `source_message_only_result` 返回 `entry_result_code`、`entry_result_meaning`、`entry_result_description`、`entry_result_source_message_id`、`result_type`、`route_code`、`agent_assessment`、`notification`、S99 的入口 `manual_review` 和 `raw_answer`。
-- 不显示编辑、确认、人工转换、执行 OPERA 或重试 OPERA 按钮。
-- 不参与订单任务执行顺序阻塞。
+- 不显示编辑、人工转换、执行 OPERA 或重试 OPERA 按钮；V4 只显示 ack。
+- 不参与订单任务执行顺序阻塞，也不创建隐藏技术订单。
 
 当前不建议新增路径：
 
@@ -1112,9 +1187,9 @@ POST /api/reservation/tasks/{taskId}/order-binding
 - 订单列表、任务列表当前统一使用 `items + page` 分页结构；邮件会话详情不分页，返回同一会话全部邮件。
 - 邮件会话详情接口已优先使用 `GET /api/source-messages/{sourceMessageId}/conversation`。
 - 任务详情 `fields[]` 已由后端直接透出 P0 需要的 3.0 元数据；独立字段白名单接口后置。
-- 独立 Message Notification 页面继续后置；旧 S000/S999 和新 S10/S99 都先在任务列表和任务详情展示。
+- 独立 Message Notification 页面继续后置；旧 S000/S999 和 V3 S10/S99 继续在旧任务列表和任务详情兼容展示，V4 S10/S99 走 V4 工作台和来源通知详情。
 - 邮件会话全文读取的审计策略由后端内部处理；前端不保存原文读取 key。
-- `GET /api/reservation/tasks` 结构化 S10/S99 行的 `task_type` 返回值请后端最终确认：前端已兼容 `SOURCE_MESSAGE_ONLY` 和 `MESSAGE_NOTIFICATION`，但文档口径最好稳定一个。
+- `GET /api/reservation/tasks` 中旧 S000/S999 和 V3 S10/S99 兼容行的 `task_type` 返回值请后端最终确认；V4 S10/S99 不应再进入旧任务列表。
 - `manual-review-resolutions` 成功响应中的 `opera_operations[]` 数量请后端最终确认；前端不写死两条，只按返回内容刷新展示。
 - 系统管理菜单树增强接口已完成：`GET /api/admin/menus/tree`、`PUT /api/admin/menus/tree-order`。
 - Manual Invoice 第一阶段的客户 / 联系人目录来源、模板初始文件、VAT 配置和生成记录是否必须落库，已在 M009 中列为开发前确认项。