huangting/th-hotel-simple
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

补齐订单详情V4任务时间线

Browse Source
This commit is contained in:
andy
2026-07-19 13:15:14 +07:00
parent 10c28f0acb
commit 13364e7edf
9 changed files with 496 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
docs/project/frontend-backend/frontend-to-backend-api-requests.md
View File

@@ -10,7 +10,7 @@
| --- | --- | --- | --- |
| P0 | 订单列表接口 `GET /api/reservation/orders` | 订单列表页、首页工作台 | 已完成第一版 |
| P0 | 任务列表接口 `GET /api/reservation/tasks` | 任务列表菜单、订单详情任务入口 | 已完成第一版，已补来源邮件会话字段和 `order_status` 筛选 |
| P0 | 订单详情接口 `GET /api/reservation/orders/{orderId}` | 订单详情页 | 已完成第一版，已补 `tasks[]` 每个任务的来源邮件会话字段 |
| P0 | 订单详情接口 `GET /api/reservation/orders/{orderId}` | 订单详情页 | 已完成第一版，已补旧 `tasks[]` 来源邮件会话字段和 V4 `v4_order_tasks[]` 时间线 |
| P0 | 任务详情读取接口 `GET /api/reservation/tasks/{taskId}` | 任务详情页动态渲染 | 已完成第一版，已补来源邮件字段和 3.0 字段元数据 |
| P0 | 任务详情操作接口 | 任务详情保存、确认、OPERA、审计 | 已完成；前端可直接接入 |
| P0 | 邮件会话详情接口 `GET /api/source-messages/{sourceMessageId}/conversation` | 邮件会话详情页 | 已完成第一版 |
@@ -29,7 +29,7 @@
| 接口 / 能力 | 当前后端状态 | 前端是否可直接接入 | 仍需后端处理 |
| --- | --- | --- | --- |
| `GET /api/reservation/tasks` | 已完成第一版，已补来源邮件会话字段和所属订单状态筛选 | 可以 | `order_status` 按任务所属订单状态过滤；不传时保持当前全部任务列表行为。 |
| `GET /api/reservation/orders/{orderId}` | 已完成第一版，已补 `tasks[]` 来源邮件会话字段 | 可以 | 暂无。 |
| `GET /api/reservation/orders/{orderId}` | 已完成第一版，已补旧 `tasks[]` 来源邮件会话字段和 V4 `v4_order_tasks[]` 时间线 | 可以 | 暂无；`include_tasks=false` 时旧 `tasks[]` 和 V4 `v4_order_tasks[]` 都返回空数组。 |
| `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`；如写操作需要酒店上下文幂等 / 权限校验，请后端补可选入参或请求体字段。 |
@@ -163,9 +163,9 @@ GET /api/reservation/tasks
GET /api/reservation/orders/{orderId}
```
当前状态：后端已按 P0 最小诉求实现第一版。接口返回订单摘要和同订单任务时间线；`include_tasks=false` 时只返回订单摘要。任务时间线已补齐每个任务的来源邮件会话摘要。
当前状态：后端已按 P0 最小诉求实现第一版。接口返回订单摘要、旧 V2/V3 同订单任务时间线和 V4 订单任务时间线；`include_tasks=false` 时只返回订单摘要，旧 `tasks[]` 和 V4 `v4_order_tasks[]` 都为空数组。旧任务时间线已补齐每个任务的来源邮件会话摘要。
订单详情低保真已确认沿用“订单摘要 + 同订单任务队列 + 当前任务卡 + OPERA 模拟操作 + 审计时间线”。同订单任务队列里的每个任务都需要自己的“查看邮件会话”入口，因为不同任务可能来自不同邮件或不同邮件会话。因此建议补齐 `tasks[]` 中每个任务的来源邮件会话字段。
订单详情低保真已确认沿用“订单摘要 + 同订单任务队列 + 当前任务卡 + OPERA 模拟操作 + 审计时间线”。同订单任务队列里的每个任务都需要自己的“查看邮件会话”入口，因为不同任务可能来自不同邮件或不同邮件会话。因此 `tasks[]` 中每个任务已补齐来源邮件会话字段。V4 新模型下，同一订单的多卡订单任务通过 `v4_order_tasks[]` 单独返回，前端点击后进入 V4 订单任务详情。
建议入参：
@@ -217,6 +217,35 @@ GET /api/reservation/orders/{orderId}
"created_at": "2026-07-08T03:00:00Z"
}
],
"v4_order_tasks": [
{
"order_task_id": "40001",
"order_ref": "order-1",
"order_task_status": "OPEN",
"card_counts": {
"total_count": 3,
"readonly_count": 1,
"pending_confirm_count": 1,
"review_required_count": 1,
"confirmed_count": 0
},
"source_message_summary": {
"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
},
"source_received_at": "2026-07-08T04:00:00Z",
"created_at": "2026-07-08T04:00:10Z",
"updated_at": "2026-07-08T04:05:00Z",
"latest_activity_at": "2026-07-08T04:05:00Z"
}
],
"warnings": []
}
```
@@ -232,6 +261,13 @@ GET /api/reservation/orders/{orderId}
| `external_conversation_id` | 来源消息所属邮件会话 ID。 |
| `conversation_message_count` | 会话内邮件数量。 |
| `result_type` / `ai_task_type` / `route_code` / `system_process_category` | V3 路由展示字段，和任务列表字段语义一致。 |
| `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[].source_message_summary` | V4 来源邮件安全摘要，不包含正文、HTML、附件 URL 或 AI 原始 payload。 |
| `v4_order_tasks[].latest_activity_at` | V4 订单任务自身 `updated_at` 与其下卡片 `updated_at` 的最大 UTC 时间。 |
## 5. 订单列表接口