实现前端P0订单任务查询接口

2026-07-08 14:18:57 +08:00
parent b58c6baafe
commit 936a5921b0
29 changed files with 1582 additions and 56 deletions
--- a/docs/project/frontend-backend/README.md
+++ b/docs/project/frontend-backend/README.md
@@ -0,0 +1,54 @@
+# 前后端协作入口
+
+## 1. 文档定位
+
+本文用于后端 agent、前端 agent 和测试在开发任务详情、订单详情、任务列表、Message Notification 等页面时统一查找接口契约、字段来源和当前后置事项。
+
+如本文与 `AGENTS.md`、`docs/project/requirements/` 中的业务需求冲突，以 `AGENTS.md` 和对应需求文档为准。
+
+## 2. 沟通文件
+
+| 文件 | 用途 |
+| --- | --- |
+| `backend-to-frontend-notes.md` | 后端提醒前端的注意事项，包含项目开发、业务规则、接口使用和安全边界。 |
+| `frontend-to-backend-api-requests.md` | 前端提醒后端需要增加或补齐的接口，包含建议入参和返参草案。 |
+
+## 3. 当前字段来源分工
+
+| 来源 | 当前用途 |
+| --- | --- |
+| `docs/import/20260708/任务卡前端展示字段表 3.0.xlsx` | 前端任务卡展示 / 编辑白名单。前端页面优先按该表决定哪些字段展示、哪些字段可编辑。 |
+| `docs/import/20260706/任务卡展示编辑矩阵.xlsx` | 后端完整规则来源。用于后端校验、最终确认写入、OPERA 映射、展示条件和任务卡完整约束。 |
+| `docs/import/20260706/AI输出参数并集字典.xlsx` | AI 输出字段路径、字段含义、建议存储方式和索引参考。 |
+
+约束说明：
+
+- 最新前端 Excel 只作为展示 / 编辑白名单，不替代后端完整规则矩阵。
+- 后端不应因为前端白名单缺少字段而自动放宽必填、枚举、校验或 OPERA 映射规则。
+- 如果前端白名单与后端完整矩阵冲突，应先记录到 `frontend-to-backend-api-requests.md` 的待确认问题，再由产品 / 后端 / 前端一起确认。
+
+## 4. 当前接口契约来源
+
+| 契约 | 文档 |
+| --- | --- |
+| SuperAgent 任务结果入站接口 | `docs/project/requirements/M002-superagent-task-result-api-contract.md` |
+| SuperAgent 查询上下文接口 1、2 | `docs/project/requirements/M002-ai-query-minimal-fields.md` |
+| SuperAgent 对接总契约 | `docs/project/integrations/superagent-api-contract.md` |
+| 订单任务主流程 | `docs/project/requirements/M002-order-task-workflow-v2.md` |
+| 后端 checkpoint | `docs/project/requirements/M002-backend-checkpoint-plan.md` |
+
+## 5. 当前已明确后置事项
+
+- 普通任务切换订单接口后置。
+- SuperAgent 查询接口 4 后置，当前先不开发。
+- SuperAgent 查询接口 3 涉及附件解析、OCR、Excel、voucher、rooming list 等能力，当前系统暂不具备，仍后置。
+- 用户身份 / 权限方案后置；当前后端审计 actor 仍是本地占位。
+- 真实 OPERA / OHIP 接入后置；当前仅有 OPERA 模拟骨架。
+
+## 6. 前端开发注意事项
+
+- 前端不得直接调用 SuperAgent、AgentBus、OPERA、OHIP 或数据库。
+- 前端不得发送后端 Secret、replay access key、Provider API Key 或 Oracle 凭证。
+- 页面展示文案可以本地化，但业务判断必须使用接口返回的稳定 code。
+- 任务详情页保存草稿和最终确认是两个接口，不能合并成一个前端动作。
+- 同一订单下，如果前置任务未结束，后续任务只能查看，不能编辑、确认或执行 OPERA 模拟操作。
--- a/docs/project/frontend-backend/backend-to-frontend-notes.md
+++ b/docs/project/frontend-backend/backend-to-frontend-notes.md
@@ -0,0 +1,62 @@
+# 后端提醒前端注意事项
+
+## 1. 文档定位
+
+本文记录后端侧提醒前端开发时必须注意的项目规范、业务规则、接口边界和安全要求。当前内容服务于 Reservation 任务详情、订单详情、任务列表、Message Notification 等第一版页面。
+
+## 2. 项目开发注意事项
+
+- 前端只调用本项目后端接口，不直接调用 SuperAgent、AgentBus、OPERA、OHIP 或数据库。
+- API 调用应统一放在前端 `src/services`，页面组件不要直接拼接后端 URL。
+- 业务判断必须使用后端返回的稳定 code，不使用中文或英文展示文案做判断。
+- 前端不得保存或传递后端 Secret、replay access key、Provider API Key、Oracle 凭证、AgentBus Token。
+- 后端数据库 ID 未来应尽量以字符串形式给前端，避免 JavaScript 长整型精度问题；如果当前接口仍返回数字，前端不要自行做数学运算。
+- 接口字段发生变化前，需要先更新本目录沟通文档或对应需求文档。
+
+## 3. 字段来源注意事项
+
+- `docs/import/20260708/任务卡前端展示字段表 3.0.xlsx` 是前端展示 / 编辑白名单。
+- `docs/import/20260706/任务卡展示编辑矩阵.xlsx` 是后端校验、最终确认写入、OPERA 映射和展示条件的完整规则来源。
+- 前端不要直接把整个 `ai_task_results[]` 渲染成表单，只展示白名单允许的字段。
+- 如果 3.0 白名单与旧矩阵冲突，应记录为前后端待确认问题，不由前端单方面放宽必填、枚举或校验规则。
+
+## 4. 业务规则注意事项
+
+- 任务详情页里，保存草稿和最终确认是两个独立动作，不能合并。
+- 用户可以修改任务字段内容；最终确认后，后端使用 `confirmed_payload_json` 作为 OPERA 模拟输入来源。
+- 同一订单下，前置任务未结束时，后续任务只能查看，不能编辑、确认或执行 OPERA 模拟操作。
+- 任务状态 `FAILED` 第一版视为结束状态，不阻塞后续任务；但失败的 OPERA 操作不能跳过，必须展示失败原因并允许重试。
+- Message Notification 挂临时订单，只读展示，不参与订单任务执行队列，不阻塞其他任务，也不被其他任务阻塞。
+- Fallback / manual_review 转为 New / Update / Cancel 时需要展示审计轨迹；当前 actor 仍是本地占位，正式用户身份后置。
+- 普通任务切换订单接口已确认后置，前端第一版不要把普通任务拖拽或切换订单做成可提交能力。
+
+## 5. 当前前端可用接口注意事项
+
+| 接口 | 用途 | 前端注意 |
+| --- | --- | --- |
+| `GET /api/reservation/tasks` | 查询任务列表 / 工作台 | 用 `can_process` 和 `readonly_reason_code` 控制入口按钮；列表不返回 AI 原始 payload、邮件正文或附件 URL。 |
+| `GET /api/reservation/orders/{orderId}` | 查询订单详情与任务时间线 | `include_tasks=false` 可只取订单摘要；时间线按后端队列顺序返回，前端不要自行按创建时间重排。 |
+| `GET /api/reservation/tasks/{taskId}` | 查询任务详情 | 以返回的可处理状态和只读原因控制按钮，不只看任务状态。 |
+| `PUT /api/reservation/tasks/{taskId}/draft` | 保存任务草稿 | 只保存草稿，不代表用户最终确认。 |
+| `POST /api/reservation/tasks/{taskId}/confirm` | 最终确认任务 | 后端会做第一版字段校验，通过后进入 `READY`。 |
+| `POST /api/reservation/tasks/{taskId}/manual-review-conversions` | Fallback 人工转换 | 只用于 manual_review / fallback，不用于普通任务切换订单。 |
+| `POST /api/reservation/tasks/{taskId}/opera-operations/{operationId}/execute` | 执行 OPERA 模拟操作 | 当前是模拟，不调用真实 OPERA。 |
+| `POST /api/reservation/tasks/{taskId}/opera-operations/{operationId}/retry` | 重试失败 OPERA 模拟操作 | 重试会追加 attempt 历史，前端不要覆盖旧失败记录。 |
+| `GET /api/reservation/tasks/{taskId}/audits` | 查询任务审计流水 | 用于展示人工确认、转换、模拟操作等轨迹。 |
+| `GET /api/source-messages` | 查询来源消息安全摘要 | 列表不返回邮件正文、HTML、附件 URL 或原始 payload。 |
+| `GET /api/source-messages/{id}` | 查询来源消息安全详情 | 只用于安全摘要详情。 |
+| `GET /api/source-messages/{id}/original` | 读取来源消息原文 | 需要受控访问头，返回 HTML 时前端展示前必须 sanitize。 |
+
+## 6. 不给前端直接调用的接口
+
+- `POST /api/integrations/superagent/task-results` 是 SuperAgent 到后端的服务到服务入站接口。
+- `POST /api/ai-query/v1/case-context` 和 `POST /api/ai-query/v1/object-detail` 是 SuperAgent 查询上下文接口，不是前端页面接口。
+- AgentBus probe、fixture、replay、system 类接口不应放到普通业务前端页面。
+
+## 7. 需要持续提醒的后置事项
+
+- SuperAgent 查询接口 3 文件解析当前不能做。
+- SuperAgent 查询接口 4 已确认继续后置。
+- 普通任务切换订单接口继续后置。
+- 用户 / 权限方案继续后置。
+- 真实 OPERA / OHIP 接入继续后置。
--- a/docs/project/frontend-backend/frontend-to-backend-api-requests.md
+++ b/docs/project/frontend-backend/frontend-to-backend-api-requests.md
@@ -0,0 +1,284 @@
+# 前端提醒后端待补接口
+
+## 1. 文档定位
+
+本文记录前端页面开发时希望后端新增、补齐或稳定的接口草案。本文中的路径、入参和返参是前端视角的最小诉求，不代表后端已经承诺实现；进入开发前需要后端按当前包结构、权限、安全和业务规则二次确认。
+
+## 2. 当前待补接口总览
+
+| 优先级 | 接口 | 页面 / 场景 | 状态 |
+| --- | --- | --- | --- |
+| P0 | 任务列表 / 工作台接口 | 任务列表页、首页工作台 | 已实现第一版 |
+| P0 | 订单详情与任务时间线接口 | 订单详情页 | 已实现第一版 |
+| P1 | 订单列表接口 | 订单检索、订单入口 | 待后端设计 |
+| P1 | Message Notification 列表 / 详情接口 | 信息提醒页或订单详情只读卡片 | 待后端设计 |
+| P1 | 任务卡前端字段白名单元数据接口 | 任务详情动态渲染 | 待确认是否需要后端提供 |
+| 后置 | 普通任务切换订单接口 | 任务详情订单归属调整 | 已确认后置 |
+
+## 3. 任务列表 / 工作台接口
+
+建议路径：
+
+```text
+GET /api/reservation/tasks
+```
+
+当前状态：后端已按 P0 最小诉求实现第一版。接口只返回任务摘要、订单展示键、来源消息主题和实时可处理状态，不返回完整 AI payload、邮件正文或附件 URL。
+
+建议入参：
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `hotel_id` | 否 | 酒店 ID。第一版如果只有单酒店，可为空。 |
+| `order_id` | 否 | 按订单过滤。 |
+| `task_type` | 否 | `NEW_BOOKING`、`UPDATE_BOOKING`、`CANCEL_BOOKING`、`MANUAL_REVIEW`、`INFORMATIONAL_MESSAGE`。 |
+| `task_status` | 否 | 任务状态过滤。 |
+| `task_subtype` | 否 | 任务卡 subtype 过滤。 |
+| `queue_participation` | 否 | 是否参与订单执行队列。 |
+| `keyword` | 否 | Group Code、Confirmation No、临时订单号、来源消息安全摘要关键词。 |
+| `page_num` | 否 | 页码，建议从 1 开始。 |
+| `page_size` | 否 | 每页条数。 |
+
+建议返参：
+
+```json
+{
+  "items": [
+    {
+      "task_id": "10001",
+      "order_id": "20001",
+      "hotel_id": "HOTEL-TEST",
+      "display_order_key": "GRP-001",
+      "temporary_order_no": "TMP-20260708-001",
+      "task_type": "UPDATE_BOOKING",
+      "task_subtype": "RATE_CHANGE",
+      "task_status": "PENDING_CONFIRM",
+      "card_name": "Rate Change",
+      "queue_sequence": 2,
+      "queue_participation": true,
+      "can_process": false,
+      "readonly_reason_code": "PREVIOUS_TASK_NOT_FINISHED",
+      "source_message_id": "30001",
+      "source_subject": "Booking Update",
+      "created_at": "2026-07-08T03:00:00Z",
+      "updated_at": "2026-07-08T03:10:00Z"
+    }
+  ],
+  "page": {
+    "page_num": 1,
+    "page_size": 20,
+    "total": 1
+  }
+}
+```
+
+## 4. 订单详情与任务时间线接口
+
+建议路径：
+
+```text
+GET /api/reservation/orders/{orderId}
+```
+
+当前状态：后端已按 P0 最小诉求实现第一版。接口返回订单摘要和同订单任务时间线；`include_tasks=false` 时只返回订单摘要。`include_source_summary` 第一版保留入参但订单时间线暂不展开来源摘要，来源主题请优先从任务列表接口读取。
+
+建议入参：
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `orderId` | 是 | 订单 ID。 |
+| `include_tasks` | 否 | 是否返回任务时间线，默认 `true`。 |
+| `include_source_summary` | 否 | 是否返回来源消息摘要，默认 `true`。 |
+
+建议返参：
+
+```json
+{
+  "order": {
+    "order_id": "20001",
+    "hotel_id": "HOTEL-TEST",
+    "order_status": "ACTIVE",
+    "temporary_order_no": "TMP-20260708-001",
+    "confirmation_number": "CNF123456",
+    "group_code": "GRP-001",
+    "block_code": null,
+    "allotment_code": null,
+    "display_name": "GRP-001",
+    "created_at": "2026-07-08T03:00:00Z",
+    "updated_at": "2026-07-08T03:10:00Z"
+  },
+  "tasks": [
+    {
+      "task_id": "10001",
+      "task_type": "NEW_BOOKING",
+      "task_subtype": "NEW_BOOKING",
+      "task_status": "COMPLETED",
+      "card_name": "New Booking",
+      "queue_sequence": 1,
+      "queue_participation": true,
+      "can_process": false,
+      "readonly_reason_code": "TASK_FINISHED",
+      "created_at": "2026-07-08T03:00:00Z"
+    }
+  ],
+  "warnings": []
+}
+```
+
+## 5. 订单列表接口
+
+建议路径：
+
+```text
+GET /api/reservation/orders
+```
+
+建议入参：
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `hotel_id` | 否 | 酒店 ID。 |
+| `order_status` | 否 | `TEMPORARY`、`ACTIVE`、`ENDED`、`LOGIC_DELETED`。 |
+| `group_code` | 否 | 按 Group Code 精确或模糊查询，后端决定。 |
+| `confirmation_number` | 否 | 按 Confirmation No 查询。 |
+| `keyword` | 否 | 前端搜索框统一关键词。 |
+| `page_num` | 否 | 页码。 |
+| `page_size` | 否 | 每页条数。 |
+
+建议返参：
+
+```json
+{
+  "items": [
+    {
+      "order_id": "20001",
+      "hotel_id": "HOTEL-TEST",
+      "order_status": "ACTIVE",
+      "temporary_order_no": null,
+      "confirmation_number": "CNF123456",
+      "group_code": "GRP-001",
+      "display_name": "GRP-001",
+      "open_task_count": 2,
+      "next_processable_task_id": "10002",
+      "updated_at": "2026-07-08T03:10:00Z"
+    }
+  ],
+  "page": {
+    "page_num": 1,
+    "page_size": 20,
+    "total": 1
+  }
+}
+```
+
+## 6. Message Notification 列表 / 详情接口
+
+建议路径：
+
+```text
+GET /api/reservation/message-notifications
+GET /api/reservation/message-notifications/{taskId}
+```
+
+列表建议入参：
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `hotel_id` | 否 | 酒店 ID。 |
+| `order_id` | 否 | 按临时订单或真实订单过滤。 |
+| `keyword` | 否 | 邮件主题、摘要、发送人关键词。 |
+| `page_num` | 否 | 页码。 |
+| `page_size` | 否 | 每页条数。 |
+
+详情建议返参：
+
+```json
+{
+  "task_id": "10009",
+  "order_id": "20009",
+  "task_type": "INFORMATIONAL_MESSAGE",
+  "task_status": "COMPLETED",
+  "queue_participation": false,
+  "readonly": true,
+  "visible_reason": "FYI message without booking operation",
+  "relevant_message_excerpt": "Noted with thanks.",
+  "informational_message": "该消息仅作信息提醒，不需要执行 OPERA 操作。",
+  "attachments": [],
+  "source_message_id": "30009",
+  "created_at": "2026-07-08T03:00:00Z"
+}
+```
+
+## 7. 任务卡前端字段白名单元数据接口
+
+是否需要该接口待确认。如果前端直接读取或内置 `docs/import/20260708/任务卡前端展示字段表 3.0.xlsx` 转换后的配置，则第一版可以不做。
+
+建议路径：
+
+```text
+GET /api/reservation/task-card-field-whitelist
+```
+
+建议入参：
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `task_type` | 否 | 按系统主任务类型过滤。 |
+| `task_subtype` | 否 | 按任务卡 subtype 过滤。 |
+| `version` | 否 | 字段白名单版本，例如 `20260708-3.0`。 |
+
+建议返参：
+
+```json
+{
+  "version": "20260708-3.0",
+  "items": [
+    {
+      "task_type": "UPDATE_BOOKING",
+      "task_subtype": "RATE_CHANGE",
+      "field_path": "rate.rate_code",
+      "display_name": "Rate Code",
+      "visible": true,
+      "editable": true,
+      "input_type": "select",
+      "options": []
+    }
+  ]
+}
+```
+
+## 8. 已确认后置接口
+
+普通任务切换订单接口继续后置，前端暂不开发提交能力。后续如果恢复开发，建议另行确认：
+
+```text
+POST /api/reservation/tasks/{taskId}/order-binding
+```
+
+待确认入参：
+
+```json
+{
+  "target_order_id": "20002",
+  "reason": "人工确认该任务属于另一个订单"
+}
+```
+
+待确认返参：
+
+```json
+{
+  "task_id": "10001",
+  "previous_order_id": "20001",
+  "target_order_id": "20002",
+  "task_status": "PENDING_CONFIRM",
+  "audit_id": "90001"
+}
+```
+
+## 9. 待确认问题
+
+- 任务列表和订单列表是否统一使用同一个分页结构。
+- 前端字段白名单由后端接口提供，还是由前端从 Excel 转成静态配置。
+- Message Notification 是否独立成页面，还是只在订单详情中展示。
+- SourceMessage 原文读取在前端页面中的入口和权限方案仍待用户 / 权限体系确认。