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-20 15:16:21 +07:00
parent e5218e10eb
commit d45ff5b4ed
10 changed files with 889 additions and 240 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
docs/project/frontend-backend/backend-to-frontend-notes.md
View File

@@ -106,7 +106,7 @@
| --- | --- | --- |
| `GET /api/reservation/orders` | 补齐订单列表 V4 继续处理入口字段，并新增统一 open count 字段；前端展示已接入。 | `order_status` 不传时默认查询全部订单状态；`page_num` 从 1 开始；`page_size` 后端有最大值保护；`open_work_item_count` 是订单列表展示用统一待处理数量，开发阶段不考虑旧数据，第一版直接等于 `v4_open_order_task_count`；前端展示待处理数量时只读该字段，不自行计算旧任务数和 V4 数，也不使用旧 `open_task_count` 作为展示数量；旧 `open_task_count` 和 `next_processable_task_id` 继续保留用于 V2/V3 兼容与排查。V4 新增 `next_v4_order_task_id`、`next_v4_action_card_id`、`next_v4_action_type`、`next_v4_action_status`、`v4_open_order_task_count`；前端“继续处理”已按优先级实现：存在 `next_v4_order_task_id` 时跳 `/reservation/order-tasks/{next_v4_order_task_id}`，否则回退旧 `/reservation/tasks/{next_processable_task_id}`；两者都没有时展示无待处理状态。 |
| `GET /api/reservation/tasks` | 补齐来源邮件会话摘要字段，并新增 `order_status` 查询参数。 | `order_status` 按任务所属订单状态过滤，支持 `TEMPORARY`、`ACTIVE`、`ENDED`、`LOGIC_DELETED`；列表仍然只返回安全摘要，不返回正文、HTML、附件 URL 或 AI 原始 payload；点击邮件入口时使用 `source_message_id` 调会话详情。 |
| `GET /api/reservation/orders/{orderId}` | 补齐旧 `tasks[]` 来源邮件会话摘要字段，并新增 V4 总览和 `v4_order_tasks[]` 订单任务时间线。 | `include_tasks=false` 可只取轻量摘要，此时 `tasks[]`、`v4_order_tasks[]` 和 `related_source_messages[]` 都为空，`order_overview` 为空快照，`next_v4_action.action_type=NONE`；旧 `tasks[]` 顺序由后端按订单队列返回，V4 `v4_order_tasks[]` 按 `source_received_at`、`source_message_id`、`order_context_index`、`created_at`、数字 ID 正序返回；前端不要自行重排。`include_source_summary` 第一版不作为前端裁剪字段的强约束，前端暂不要依赖它减少返回字段。 |
| `GET /api/reservation/orders/{orderId}` | 补齐旧 `tasks[]` 来源邮件会话摘要字段，并新增 V4 总览和 `v4_order_tasks[]` 订单任务时间线；前端订单详情总览页已接入。 | `include_tasks=false` 可只取轻量摘要，此时 `tasks[]`、`v4_order_tasks[]` 和 `related_source_messages[]` 都为空，`order_overview` 为空快照，`next_v4_action.action_type=NONE`；旧 `tasks[]` 顺序由后端按订单队列返回，V4 `v4_order_tasks[]` 按 `source_received_at`、`source_message_id`、`order_context_index`、`created_at`、数字 ID 正序返回；前端不要自行重排。订单详情页只展示 V4 确认快照、下一步入口、关联来源消息和任务卡安全摘要，不在该页确认、复核或编辑任务卡，也不展示 payload、邮件正文或附件 URL。`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` | 新增邮件会话详情接口，并补齐 `html_body_sanitized` / `html_render_mode`。 | 当前唯一推荐路径是这个接口；前端渲染邮件 HTML 时优先使用 `html_body_sanitized`；不要调用历史讨论过的 `/api/source-message-conversations/{externalConversationId}`。 |
| `POST /api/system/debug/eml-superagent-runs` | 新增 Debug EML 上传到 SuperAgent 调试接口，并补齐独立 Debug 外部消息 ID、原始 Message-ID 保留、安全 HTML 字段和入口通知识别。 | 只用于调试页面；请求为 multipart/form-data；必须传 `X-TH-Hotel-Debug-Upload-Key`，但该 key 不能写进前端源码、构建产物、URL、localStorage 或错误上报；SuperAgent 返回旧 S000/S999 或新 S10/S99 入口通知时都不应被前端视为 JSON 解析失败。 |
@@ -157,7 +157,7 @@ POST /api/auth/logout
| `external_conversation_id` | 外部邮件会话 ID。 | 仅用于展示或调试，不作为当前会话详情接口路径参数。 |
| `conversation_message_count` | 同一外部会话下的邮件数量。 | 用于提示用户打开的是整段会话，不是单封邮件。 |
订单详情已经补齐 V4 订单页总览字段：`order_overview`、`next_v4_action`、`related_source_messages[]` 和增强后的 `v4_order_tasks[].cards[]`。订单详情页应定位为订单视角总览，不要在订单详情页直接编辑、确认或复核任务卡；点击 `next_v4_action.order_task_id` 或时间线 `order_task_id` 后进入 `/reservation/order-tasks/{orderTaskId}` 对应的 V4 订单任务详情页处理。
订单详情已经补齐并完成前端接入 V4 订单页总览字段：`order_overview`、`next_v4_action`、`related_source_messages[]` 和增强后的 `v4_order_tasks[].cards[]`。订单详情页定位为订单视角总览，不要在订单详情页直接编辑、确认或复核任务卡；点击 `next_v4_action.order_task_id` 或时间线 `order_task_id` 后进入 `/reservation/order-tasks/{orderTaskId}` 对应的 V4 订单任务详情页处理。
`order_overview` 只从已确认 V4 卡片派生：Basic Information 未确认时 Account / Market / Source 为空；Room Information 未确认时日期、Rate Code、房型房量为空。前端不要把未确认卡片 display payload 反推成订单事实。
@@ -165,7 +165,7 @@ POST /api/auth/logout
| 字段 | 说明 | 前端使用方式 |
| --- | --- | --- |
| `order_task_id` | V4 订单任务 ID，字符串。 | 点击 V4 时间线项时跳转 `/api/reservation/order-tasks/{orderTaskId}` 对应的前端详情页。 |
| `order_task_id` | V4 订单任务 ID，字符串。 | 点击 V4 时间线项时跳转前端路由 `/reservation/order-tasks/{orderTaskId}`，该页面再调用 `GET /api/reservation/order-tasks/{orderTaskId}`。 |
| `order_ref` | SuperAgent V4 回调包内订单引用。 | 用于区分同一邮件里的多个订单上下文，不等同 PMS 永久订单号。 |
| `order_task_status` | V4 订单任务状态，当前为 `OPEN` / `COMPLETED`。 | 展示处理状态，不要用于替代卡片级 `availability`。 |
| `card_counts` | V4 卡片数量摘要。 | 展示待确认、待复核和已确认规模。 |
@@ -504,6 +504,7 @@ RESERVATION_ROOMING_LIST_GENERATE
- 前端不展示 `ai_payload_json`、邮件完整正文、附件 URL、raw evidence 或 SuperAgent 原始 payload；来源邮件详情仍从邮件会话页面查看，卡片内仅展示后端普通接口返回的安全摘要、邮件片段和附件名称。
- V4 来源消息卡读取 `attachments`、`uploaded_media`、`file_references` 时，只允许展示附件名称、类型和大小等安全摘要；如果后端 payload 中异常出现 `https://`、`oss://`、`s3://` 等直接 URL 字符串，前端必须替换为“未命名附件”或隐藏，不得把 URL 渲染到普通业务页面。
- V4 主流程不调用旧 V2/V3 草稿、旧任务确认、旧同卡复核接口，也不展示 OPERA 模拟操作入口。
- 2026-07-20 测试机 smoke 注意：订单详情页依赖 `GET /api/reservation/orders/{orderId}` 返回 `order_overview`、`next_v4_action`、`related_source_messages[]` 和 `v4_order_tasks[].cards[]`。如果测试机响应仍只有旧 `order`、`tasks[]`、基础 `v4_order_tasks[]` 和 `warnings`，应先确认测试机后端是否部署了包含 M002 V4 CP15.1 的最新包；前端不要为了该旧响应重新做兼容逻辑，避免把部署问题固化成页面分支。
## 6. 不给前端直接调用的接口

8
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[]` 来源邮件会话字段和 V4 `v4_order_tasks[]` 时间线 |
| P0 | 订单详情接口 `GET /api/reservation/orders/{orderId}` | 订单详情页 | 已完成第一版，已补旧 `tasks[]` 来源邮件会话字段和 V4 `order_overview` / `next_v4_action` / `related_source_messages[]` / `v4_order_tasks[].cards[]`，前端订单详情总览页已接入 |
| P0 | 任务详情读取接口 `GET /api/reservation/tasks/{taskId}` | 任务详情页动态渲染 | 已完成第一版，已补来源邮件字段和 3.0 字段元数据 |
| P0 | 任务详情操作接口 | 任务详情保存、确认、OPERA、审计 | 已完成；前端可直接接入 |
| P0 | 邮件会话详情接口 `GET /api/source-messages/{sourceMessageId}/conversation` | 邮件会话详情页 | 已完成第一版 |
@@ -30,7 +30,7 @@
| 接口 / 能力 | 当前后端状态 | 前端是否可直接接入 | 仍需后端处理 |
| --- | --- | --- | --- |
| `GET /api/reservation/tasks` | 已完成第一版，已补来源邮件会话字段和所属订单状态筛选 | 可以 | `order_status` 按任务所属订单状态过滤；不传时保持当前全部任务列表行为。 |
| `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/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`；如写操作需要酒店上下文幂等 / 权限校验，请后端补可选入参或请求体字段。 |
@@ -165,9 +165,9 @@ GET /api/reservation/tasks
GET /api/reservation/orders/{orderId}
```
当前状态：后端已按 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`。旧任务时间线已补齐每个任务的来源邮件会话摘要。
当前状态：后端已按 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`。旧任务时间线已补齐每个任务的来源邮件会话摘要。
订单详情页后续应定位为“订单总览 + 当前确认快照 + V4 任务时间线 + 下一步入口”，不是 V4 任务卡处理页。同订单任务队列里的每个任务都需要自己的“查看邮件会话”入口，因为不同任务可能来自不同邮件或不同邮件会话。因此 `tasks[]` 中每个任务已补齐来源邮件会话字段。V4 新模型下，同一订单的多卡订单任务通过 `v4_order_tasks[]` 单独返回，前端点击后进入 V4 订单任务详情。
订单详情页当前定位为“订单总览 + 当前确认快照 + V4 任务时间线 + 下一步入口”，不是 V4 任务卡处理页。同订单任务队列里的每个任务都需要自己的“查看邮件会话”入口，因为不同任务可能来自不同邮件或不同邮件会话。因此 `tasks[]` 中每个任务已补齐来源邮件会话字段。V4 新模型下，同一订单的多卡订单任务通过 `v4_order_tasks[]` 单独返回，前端点击后进入 V4 订单任务详情。
建议入参：

30
docs/project/requirements/M002-v4-test-machine-smoke-checklist.md
View File

@@ -8,7 +8,7 @@
| 日期 | 2026-07-19 |
| 状态 | 测试机 V4 前后端联调冒烟清单 |
| 适用范围 | 登录、酒店权限、V4 工作台、V4 订单任务详情、目录 lookup、卡片确认、复核解阻、S10/S99 ack、订单详情 V4 时间线 |
| 不适用范围 | 真实 OPERA / OHIP、目录同步、旧 V2/V3 全量回归、前端视觉验收 |
| 不适用范围 | 真实 OPERA / OHIP、目录同步、旧 V2/V3 全量回归、M011 CP4、前端视觉验收 |
## 1. 测试前置
@@ -256,15 +256,19 @@ ORDER BY updated_at DESC, id DESC;
| 项目 | 结果 | 备注 |
| --- | --- | --- |
| 登录与酒店权限 | 待测 | |
| V4 工作台 | 待测 | |
| V4 订单任务详情 | 待测 | |
| Account Lookup | 待测 | |
| Room Type Lookup | 待测 | |
| Rate Code Lookup | 待测 | |
| Basic Information 确认 | 待测 | |
| 业务卡确认 | 待测 | |
| REVIEW_REQUIRED 复核解阻 | 待测 | |
| S10/S99 ack | 待测 | |
| 订单详情 V4 时间线 | 待测 | |
| 目录管理 CP1 | 待测 | |
| 登录与酒店权限 | 通过 | 2026-07-20 smoke：`/api/auth/me` 返回 `HOTEL-TEST` 和 V4 权限；未带 Bearer 访问 V4 工作台返回 401；错误 `hotel_id` 访问工作台和订单详情返回 403。 |
| V4 工作台 | 通过 | `GET /api/reservation/workbench-items` 返回 5 条，包含 `ORDER_TASK` 和 `SOURCE_NOTIFICATION`；列表未发现邮件正文、附件 URL、AI 原始 payload 字段。 |
| V4 订单任务列表 | 通过 | `GET /api/reservation/order-tasks` 返回业务订单任务，不包含来源通知；`card_status=REVIEW_REQUIRED` 查询当前测试数据返回 0 条。 |
| V4 订单任务详情 | 通过 | `GET /api/reservation/order-tasks/2079096313548677122` 返回 `source_message_card`、`basic_information_card`、`business_cards[]`、`fields[]` 和 `availability`；Basic 未确认前业务卡 `readonly_reason_code=PRIOR_CARD_NOT_CONFIRMED`。 |
| Account Lookup | 通过 | `GET /api/reservation/lookups/accounts` 返回 3 条 ACTIVE Account。 |
| Room Type Lookup | 通过 | `GET /api/reservation/lookups/room-types` 返回 8 条 ACTIVE Room Type。 |
| Rate Code Lookup | 通过 | `GET /api/reservation/lookups/rate-codes` 返回 5 条 ACTIVE Rate Code，`stale=false`；有固定种子 warning，符合当前第一版目录状态。 |
| Basic Information 确认 | 通过 | 使用 `version=0` 确认 Basic Information 成功，卡片进入 `CONFIRMED`，version 递增到 1，业务卡随后变为可确认。 |
| 业务卡确认 | 通过 | 使用 `version=0` 确认 Room Information 成功，订单任务进入 `COMPLETED`，工作台显示 `display_status=COMPLETED`，订单列表 `open_work_item_count=0`、`v4_open_order_task_count=0`。 |
| REVIEW_REQUIRED 复核解阻 | 未覆盖写操作 | 当前测试机没有 `REVIEW_REQUIRED` 待复核卡；已用历史完成记录 `2078906313578168322` 验证详情和 `V4_CARD_REVIEW_RESOLVE` 审计查询返回脱敏结果。下一轮需要准备一条待复核测试数据后再跑写操作。 |
| S10/S99 来源通知详情 | 通过 | 工作台包含 S10 与 S99 来源通知；详情接口返回通知摘要和来源消息卡，不返回订单任务或业务卡。 |
| S10/S99 ack | 通过 | 对已 ACK 的 S10 通知重复 ack 返回 200 且保持 `ACKED`，验证幂等；S10/S99 均未创建订单，也未进入订单列表。 |
| V4 业务审计 | 通过 | 订单任务确认审计和来源通知 ack 审计接口返回 200；快照未发现 `ai_payload_json`、正文、HTML、附件 URL、token、secret 等敏感字段。 |
| 订单详情 V4 总览 / 时间线 | 失败 | 测试机 `GET /api/reservation/orders/2079096313393487874` 返回 200，但响应仍只有 `order`、旧 `tasks[]`、基础 `v4_order_tasks[]` 和 `warnings`；缺少 CP15.1 要求的 `order_overview`、`next_v4_action`、`related_source_messages[]` 和 `v4_order_tasks[].cards[]`。本地最新后端已有测试覆盖，优先排查测试机是否部署了包含 CP15.1 的最新包。 |
| M011 AgentBus Booking Excel 预处理观察 | 未覆盖 outbound payload | `GET /api/system/agentbus-probe` 显示测试机 AgentBus 已连接且已捕获 frame；当前普通 HTTP 接口不暴露发给 SuperAgent 的 outbound payload，无法仅通过本次 smoke 确认 `attachment_extractions[]` 是否追加。未推进 M011 CP4，未新增解析批次表或行级持久化。 |
| 目录管理 CP1 | 未覆盖 | 本 checkpoint 聚焦 V4 主流程联调；目录管理后台另行 smoke。 |