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

完成M002 V3 CP4列表详情展示

Browse Source
This commit is contained in:
andy
2026-07-11 15:53:22 +08:00
parent 9bcbe8a3ac
commit 6416c1b78a
15 changed files with 647 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -48,9 +48,9 @@
| `GET /api/auth/me` | 恢复当前登录态 | 前端启动后带 `Authorization: Bearer <access_token>` 调用；401 时清理 token 并进入登录页。 |
| `POST /api/auth/logout` | 登出当前 session | 带 `Authorization: Bearer <access_token>`；成功后前端必须清理本地 token 和当前用户上下文。 |
| `GET /api/reservation/orders` | 查询订单列表 | 默认返回全部订单状态；`open_task_count` 排除 `COMPLETED` 和 `FAILED`；隐藏技术订单不返回，因此 S10/S99 和旧 S000/S999 不会在订单列表形成订单。 |
| `GET /api/reservation/tasks` | 查询任务列表 / 工作台 | 用 `can_process` 和 `readonly_reason_code` 控制入口按钮；列表不返回 AI 原始 payload、邮件正文或附件 URL；已返回来源邮件会话摘要字段，并支持 `order_status` 按任务所属订单状态筛选；旧 S000/S999 和新 S10/S99 当前都会以 `task_type=SOURCE_MESSAGE_ONLY` 只读任务返回，任务结果回调响应已包含 `route_code/system_process_category`，列表接口完整透出 V3 路由字段后续补齐。 |
| `GET /api/reservation/orders/{orderId}` | 查询订单详情与任务时间线 | `include_tasks=false` 可只取订单摘要；时间线按后端队列顺序返回，前端不要自行按创建时间重排；`tasks[]` 已返回来源邮件会话摘要字段；隐藏技术订单详情不可作为普通订单页打开。 |
| `GET /api/reservation/tasks/{taskId}` | 查询任务详情 | 以返回的可处理状态和只读原因控制按钮，不只看任务状态；`fields[]` 已包含 P0 字段元数据；源邮件只读通知卡字段列表和 OPERA 操作列表为空，旧数据通过 `source_message_only_result` 返回 S000/S999 入口结果；结构化 S10/S99 已可入站并保存，详情接口完整透出 `agent_assessment/notification/manual_review` 后续补齐。 |
| `GET /api/reservation/tasks` | 查询任务列表 / 工作台 | 用 `can_process` 和 `readonly_reason_code` 控制入口按钮；列表不返回 AI 原始 payload、邮件正文或附件 URL；已返回来源邮件会话摘要字段，并支持 `order_status` 按任务所属订单状态筛选；旧 S000/S999 和新 S10/S99 都以 `task_type=SOURCE_MESSAGE_ONLY` 只读任务返回，列表已透出 `result_type`、`ai_task_type`、`route_code`、`system_process_category`。 |
| `GET /api/reservation/orders/{orderId}` | 查询订单详情与任务时间线 | `include_tasks=false` 可只取订单摘要；时间线按后端队列顺序返回，前端不要自行按创建时间重排；`tasks[]` 已返回来源邮件会话摘要字段和 V3 路由字段；隐藏技术订单详情不可作为普通订单页打开。 |
| `GET /api/reservation/tasks/{taskId}` | 查询任务详情 | 以返回的可处理状态和只读原因控制按钮，不只看任务状态；`fields[]` 已包含 P0 字段元数据；源邮件只读通知卡字段列表和 OPERA 操作列表为空；结构化 S10/S99 通过 `source_message_only_result.agent_assessment`、`notification`、`manual_review` 展示；普通业务任务可通过 `adapter_contract_errors[]` 和 `unhandled_intents[]` 查看同批次未建任务的诊断信息。 |
| `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，不用于普通任务切换订单。 |
@@ -142,7 +142,9 @@ POST /api/auth/logout
- 源邮件只读通知卡背后有隐藏技术订单用于满足后端任务外键，但订单列表不会返回该订单；任务列表中该类任务的 `display_order_key`、`temporary_order_no`、`group_code`、`confirmation_number` 可能为空，前端不要因此隐藏整条任务。
- 当前前端已按 `SOURCE_MESSAGE_ONLY` 展示旧 S000/S999；后端回调已支持结构化 `route_code=S10/S99`、`result_type=source_message_review_notification` 的新入口通知，并继续只在任务列表和任务详情提供只读查看入口；`INFORMATIONAL_MESSAGE` 仅作为历史 Message Notification 兼容路径保留。
- 任务列表里旧 `task_type=SOURCE_MESSAGE_ONLY`、`task_subtype=S000/S999` 或新 `task_subtype=S10/S99` 的记录只展示邮件来源和 SuperAgent 入口结果，不展示处理按钮。
- 任务详情里 `source_message_only_result` 仅对 `SOURCE_MESSAGE_ONLY` 返回，包含 `entry_result_code`、`entry_result_meaning`、`entry_result_description`、`entry_result_source_message_id` 和 `raw_answer`；结构化 S10/S99 已在入站 payload 中保存 `route_code`，但详情接口完整透出 `agent_assessment`、`notification` 和入口 `manual_review` 仍待后续 checkpoint；普通业务任务该字段为空。
- 任务详情里 `source_message_only_result` 仅对 `SOURCE_MESSAGE_ONLY` 返回，包含 `entry_result_code`、`entry_result_meaning`、`entry_result_description`、`entry_result_source_message_id`、`result_type`、`route_code`、`agent_assessment`、`notification`、`manual_review` 和 `raw_answer`；普通业务任务该字段为空。
- 任务列表、订单任务时间线和任务详情顶层已透出 `result_type`、`ai_task_type`、`route_code`、`system_process_category`。前端展示任务卡标题和标签时优先用这些稳定 code，不要只靠旧 `task_type` 判断。
- `adapter_contract_errors[]` 和 `unhandled_intents[]` 只在任务详情返回，表示同一 SuperAgent 入站批次中没有生成业务任务的诊断块；前端只读展示并提供来源邮件入口，不显示保存、确认、执行或重试按钮。
### 5.6 前端联调演示数据 seed 接口
@@ -268,7 +270,7 @@ run_label: 可选调试标签
## 7. 需要持续提醒的后置事项
- 普通任务切换订单接口继续后置。
- M002 V3 的结构化 `S10/S99` 入站、42 路由枚举 / 稳定配置、`UNHANDLED_CURRENT_INTENT` 和 `adapter_contract_error` transition 最小落库已完成；type-known manual review 同卡解阻、复核场景订单归属确认、任务列表 / 详情完整透出 V3 路由字段仍需后续后端 checkpoint。前端新页面应预留字段和状态，不要继续只写死旧 `S000/S999`。
- M002 V3 的结构化 `S10/S99` 入站、42 路由枚举 / 稳定配置、`UNHANDLED_CURRENT_INTENT`、`adapter_contract_error` transition 最小落库，以及任务列表 / 订单时间线 / 任务详情 V3 路由字段和只读诊断块透出已完成；type-known manual review 同卡解阻、复核场景订单归属确认仍需后续后端 checkpoint。
- 系统管理后台 V1 已完成；后续若要做用户搜索更多筛选、批量操作、密码策略增强、MFA、登录设备管理，应单独开需求。
- 现有 Reservation / SourceMessage 业务接口的强制登录、强制权限和业务审计 actor 全量迁移仍后置。
- 真实 OPERA / OHIP 接入继续后置。

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

@@ -16,7 +16,7 @@
| P0 | 邮件会话详情接口 `GET /api/source-messages/{sourceMessageId}/conversation` | 邮件会话详情页 | 已完成第一版 |
| 联调 | 演示数据 seed 接口 `POST /api/system/reservation/demo-data` | 本地 / test 前端页面看效果 | 已完成；仅 dev/test 受控使用 |
| 联调 | Debug EML 上传接口 `POST /api/system/debug/eml-superagent-runs` | Debug 页面上传 `.eml` 看 SuperAgent 结果 | 已完成第一版；仅 dev/test 受控使用 |
| P1 | S000/S999 特殊只读任务展示 | 任务列表、任务详情来源邮件查看 | 已完成后端第一版；前端已按 `SOURCE_MESSAGE_ONLY` 完成列表筛选、S000/S999 展示和详情只读展示，不做独立 Message Notification 接口 |
| P1 | S10/S99 源邮件只读通知卡与旧 S000/S999 兼容 | 任务列表、任务详情来源邮件查看 | 已完成第一版：旧 S000/S999 兼容，新结构化 S10/S99 可入站并在任务列表 / 详情只读展示 |
| P1 | 任务卡前端字段白名单元数据接口 | 字段白名单调试、版本对齐 | 未完成；若任务详情已透出完整元数据，可后置 |
| 后置 | 普通任务切换订单接口 | 任务详情订单归属调整 | 未完成；已确认后置 |
@@ -41,9 +41,9 @@
| `GET /api/reservation/orders` | 已完成第一版 | 可以 | 默认查询全部订单状态；`open_task_count` 排除 `COMPLETED` 和 `FAILED`。 |
| `GET /api/source-messages/{sourceMessageId}/conversation` | 已完成第一版，已补 `html_body_sanitized` 和 `html_render_mode` | 可以 | 返回完整 text/html、后端清洗后的 HTML、媒体外链和关联订单 / 任务摘要；前端不传原文读取 key，页面展示优先使用 `html_body_sanitized`。 |
| `POST /api/system/reservation/demo-data` | 已完成 | 仅本地 / test 联调可用 | 默认关闭，必须后端配置访问口令；不能作为生产页面接口。 |
| `POST /api/system/debug/eml-superagent-runs` | 已完成第一版 | 仅 dev/test Debug 页面可用 | 默认关闭，必须后端配置访问口令、阿里云 OSS 和 SuperAgent Open API；第一版只展示 SuperAgent 结果，不创建订单和任务。 |
| `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` 任务展示。 |
| `GET /api/reservation/message-notifications` | 未发现后端实现 | 不可以 | 第一版不做独立接口；旧 S000/S999 已通过 `SOURCE_MESSAGE_ONLY` 任务展示，0711 P0 新 S10/S99 也继续复用任务列表 / 任务详情只读展示。 |
| `GET /api/reservation/task-card-field-whitelist` | 未发现后端实现 | 不可以 | 若任务详情 `fields[]` 已补齐 3.0 元数据，可后置。 |
## 3. 任务列表 / 工作台接口字段补齐
@@ -68,7 +68,11 @@ GET /api/reservation/tasks
| `display_order_key` | 前端优先展示的业务号或临时订单号。 |
| `temporary_order_no` | 临时订单号。 |
| `task_type` | 系统主任务类型。 |
| `result_type` | AI 结果类型，例如 `normal_task`、`manual_review`、`source_message_review_notification`。 |
| `ai_task_type` | SuperAgent 原始任务类型，例如 `New Booking`、`S10`、`S99`。 |
| `task_subtype` | 任务 subtype。 |
| `route_code` | M002 V3 路由码，例如 `R01_NEW_FIT_RESERVATION_NORMAL`、`S10`、`S99`。 |
| `system_process_category` | 系统处理分类，例如 `BUSINESS_TASK`、`SOURCE_MESSAGE_NOTIFICATION`。 |
| `task_status` | 任务状态。 |
| `card_name` | 任务卡展示名称。 |
| `queue_sequence` | 同订单队列顺序。 |
@@ -86,7 +90,7 @@ GET /api/reservation/tasks
| --- | --- | --- |
| `hotel_id` | 否 | 酒店 ID。单酒店阶段默认可为空，由后端按当前用户上下文或平台酒店表唯一 `ACTIVE` 酒店解析；显式传值时后端会校验访问权限。 |
| `order_id` | 否 | 按订单过滤。 |
| `task_type` | 否 | `NEW_BOOKING`、`UPDATE_BOOKING`、`CANCEL_BOOKING`、`MANUAL_REVIEW`、`INFORMATIONAL_MESSAGE`、`SOURCE_MESSAGE_ONLY`。其中 `INFORMATIONAL_MESSAGE` 仅历史兼容，新入口 S000/S999 使用 `SOURCE_MESSAGE_ONLY`。 |
| `task_type` | 否 | `NEW_BOOKING`、`UPDATE_BOOKING`、`CANCEL_BOOKING`、`MANUAL_REVIEW`、`INFORMATIONAL_MESSAGE`、`SOURCE_MESSAGE_ONLY`。其中 `INFORMATIONAL_MESSAGE` 仅历史兼容；旧入口 S000/S999 和 0711 P0 结构化 S10/S99 均复用 `SOURCE_MESSAGE_ONLY` 只读源邮件通知卡。 |
| `task_status` | 否 | 任务状态过滤。 |
| `task_subtype` | 否 | 任务卡 subtype 过滤。 |
| `order_status` | 否 | 按任务所属订单状态过滤，支持 `TEMPORARY`、`ACTIVE`、`ENDED`、`LOGIC_DELETED`；不传时保持当前行为。 |
@@ -107,7 +111,11 @@ GET /api/reservation/tasks
"display_order_key": "GRP-001",
"temporary_order_no": "TMP-20260708-001",
"task_type": "UPDATE_BOOKING",
"result_type": "normal_task",
"ai_task_type": "Update Booking",
"task_subtype": "RATE_CHANGE",
"route_code": "R07_UPDATE_RATE_CODE_NORMAL",
"system_process_category": "BUSINESS_TASK",
"task_status": "PENDING_CONFIRM",
"card_name": "Rate Change",
"queue_sequence": 2,
@@ -140,6 +148,7 @@ GET /api/reservation/tasks
| `source_received_at` | 邮件来源接收时间，优先取 AgentBus payload `received_at`，用于任务列表排序和展示。 |
| `external_conversation_id` | 来源消息所属邮件会话 ID，用于打开完整邮件会话详情。 |
| `conversation_message_count` | 会话内邮件数量，用于提示用户该入口是整段会话，不是单封邮件。 |
| `result_type` / `ai_task_type` / `route_code` / `system_process_category` | V3 路由展示字段，用于任务卡标签、筛选和 S10/S99 只读卡判断。 |
## 4. 订单详情与任务时间线接口字段补齐
@@ -183,7 +192,11 @@ GET /api/reservation/orders/{orderId}
{
"task_id": "10001",
"task_type": "NEW_BOOKING",
"result_type": "normal_task",
"ai_task_type": "New Booking",
"task_subtype": "NEW_BOOKING",
"route_code": "R01_NEW_FIT_RESERVATION_NORMAL",
"system_process_category": "BUSINESS_TASK",
"task_status": "COMPLETED",
"card_name": "New Booking",
"queue_sequence": 1,
@@ -213,6 +226,7 @@ GET /api/reservation/orders/{orderId}
| `source_received_at` | 邮件来源接收时间，优先取 AgentBus payload `received_at`。 |
| `external_conversation_id` | 来源消息所属邮件会话 ID。 |
| `conversation_message_count` | 会话内邮件数量。 |
| `result_type` / `ai_task_type` / `route_code` / `system_process_category` | V3 路由展示字段，和任务列表字段语义一致。 |
## 5. 订单列表接口
@@ -299,7 +313,21 @@ POST /api/system/reservation/demo-data
| `tasks[]` | 生成的任务 ID、任务类型、任务 subtype 和任务状态。 |
| `entrypoints` | 可直接访问的任务列表、订单列表、订单详情、任务详情、邮件会话详情 URL。 |
第一版 seed 覆盖：队列阻塞、已完成 OPERA 模拟、OPERA 失败可重试、Fallback 人工复核、历史 Message Notification 只读任务、邮件会话完整 HTML / 附件 / 内联图片。S000/S999 特殊只读任务可通过 SuperAgent 回调或后续专用夹具补充。
第一版 seed 覆盖：队列阻塞、已完成 OPERA 模拟、OPERA 失败可重试、Fallback 人工复核、历史 Message Notification 只读任务、邮件会话完整 HTML / 附件 / 内联图片。旧 S000/S999 特殊只读任务可通过 SuperAgent 回调或后续专用夹具补充；0711 P0 新入口的 S10/S99 需要后端后续 checkpoint 补充结构化 fixture。
## 6.1 M002 V3 当前状态和后续待补能力
本节记录 0711 P0 基线确认后，前端关心的 V3 能力状态。已完成项可以直接接入；后置项需要另开 checkpoint。
| 能力 | 页面 / 场景 | 状态 | 前端最小诉求 |
| --- | --- | --- | --- |
| 结构化 `S10/S99` 入站 | 任务列表、任务详情、Debug EML 结果展示 | 已完成第一版 | 后端接收 `result_type=source_message_review_notification + route_code=S10/S99`，创建只读源邮件通知卡；任务列表可见，订单列表不可见；返回 `route_code`、入口说明、`agent_assessment`、`notification` 和 S99 的入口 `manual_review`。 |
| 旧 `S000/S999` 兼容映射 | 任务列表、任务详情 | 已完成第一版 | 旧数据继续可见；前端可按 `S000→S10`、`S999→S99` 展示统一文案。 |
| 42 路由元数据 | 任务列表筛选、订单任务时间线、任务详情标题、字段展示 | 已完成第一版 | 后端保存并返回 AI 原始 `result_type/ai_task_type/task_subtype`、`route_code` 和系统处理分类；前端不要只依赖系统主任务类型判断卡片。 |
| `unhandled_current_intents[]` 展示块 | 任务详情 | 已完成第一版 | 后端保存并在任务详情 `unhandled_intents[]` 返回未覆盖业务意图，只用于展示和源邮件查看，不自动建业务任务卡。 |
| `adapter_contract_error` | 任务详情、错误提示 | 已完成第一版 | 命中 P1/P2 未闭合或路由冲突时，任务详情 `adapter_contract_errors[]` 返回稳定错误 code 和原始片段，不转成 Fallback。 |
| type-known manual review 同卡解阻 | 任务详情复核 | 后置 | `manual_review` 不再全部等同 Fallback；已知业务卡型应返回原业务卡信息、`review_status`、`review_resolution` 和可编辑 pointer 字段。 |
| 复核场景订单归属确认 | 任务详情复核 | 后置 | 后端提供复核确认时的订单归属确认 / 选择能力；这不等于普通任务任意切换订单。 |
前端注意：不要把访问口令写入前端仓库、浏览器环境变量或构建产物；该接口只能由本地联调人员手动调用或由受控测试脚本调用。
@@ -404,7 +432,7 @@ GET /api/source-message-conversations/{externalConversationId}
GET /api/reservation/tasks/{taskId}
```
当前状态：后端已有任务详情接口，前端任务详情页可以接入。该接口已返回 `fields[]`、草稿、确认 payload、可处理状态和 OPERA 模拟操作；本轮已透出来源邮件会话字段，以及 `docs/import/20260708/任务卡前端展示字段表 3.0.xlsx` 中 P0 需要的字段元数据。
当前状态：后端已有任务详情接口，前端任务详情页可以接入。该接口已返回 `fields[]`、草稿、确认 payload、可处理状态和 OPERA 模拟操作；本轮已透出来源邮件会话字段，以及旧 `docs/import/20260708/任务卡前端展示字段表 3.0.xlsx` 中 P0 需要的字段元数据。0711 P0 后续开发应迁移到 `docs/import/20260711/开发交付_P0冻结基线_2026-07-11/01_Adapter_Frontend/任务卡前端字段变更说明_3.0_to_当前版_2026-07-10.xlsx` 和同目录路由说明。
任务详情页面相关已完成接口：
@@ -474,7 +502,7 @@ GET /api/reservation/tasks/{taskId}
"system_task_type": "NEW_BOOKING",
"task_card_type": "NEW_BOOKING",
"task_status": "PENDING_CONFIRM",
"field_contract_version": "20260708-3.0",
"field_contract_version": "20260711-p0",
"fields": [
{
"row_number": 2,
@@ -501,19 +529,26 @@ GET /api/reservation/tasks/{taskId}
- 如果后端已有更细的字段来源或适用场景元数据，可后续再扩展 `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. S000/S999 特殊只读任务与历史 Message Notification
## 9. S10/S99 源邮件只读通知卡与历史兼容
当前状态：后端不提供独立 Message Notification 列表 / 详情接口。SuperAgent 新入口返回 `S000,source_message_id` 或 `S999,source_message_id` 时，后端会创建 `SOURCE_MESSAGE_ONLY` 只读特殊任务。前端已通过 `GET /api/reservation/tasks?task_type=SOURCE_MESSAGE_ONLY` 和 `GET /api/reservation/tasks/{taskId}` 展示，并在任务列表筛选中支持 `SOURCE_MESSAGE_ONLY`、`S000`、`S999`。
当前状态：后端不提供独立 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`、`S000`、`S999`、`S10`、`S99`。
0711 P0 新入口已迁移为结构化 `S10/S99`：
- `S10`：`result_type=source_message_review_notification`，`route_code=S10`，表示未匹配当前支持的业务事件。
- `S99`：`result_type=source_message_review_notification`，`route_code=S99`，表示输入不足或无法形成业务素材包。
- 旧 `S000` 前端语义映射为 `S10`。
- 旧 `S999` 前端语义映射为 `S99`。
历史 `INFORMATIONAL_MESSAGE` 仍可通过任务列表 / 任务详情兼容展示，但新数据不要依赖它。
展示规则：
- `task_type=SOURCE_MESSAGE_ONLY`、`task_subtype=S000`：纯信息类邮件。
- `task_type=SOURCE_MESSAGE_ONLY`、`task_subtype=S999`：无法形成业务素材包。
- 旧 `task_type=SOURCE_MESSAGE_ONLY`、`task_subtype=S000/S999`：按只读源邮件通知卡展示。
- 新 `route_code=S10/S99`：按只读源邮件通知卡展示。
- 任务列表可见，订单列表不可见。
- 任务详情只允许查看来源邮件、会话、附件和 SuperAgent 原始返回。
- 任务详情通过 `source_message_only_result` 返回 `entry_result_code`、`entry_result_meaning`、`entry_result_description`、`entry_result_source_message_id` 和 `raw_answer`。
- 任务详情通过 `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 按钮。
- 不参与订单任务执行顺序阻塞。
@@ -556,6 +591,55 @@ GET /api/reservation/message-notifications/{taskId}
}
```
V3 S10 结构化详情当前增量：
```json
{
"task_id": "10010",
"readonly": true,
"result_type": "source_message_review_notification",
"route_code": "S10",
"agent_assessment": {
"status": "no_booking_action_detected",
"reason_code": "no_booking_action_detected"
},
"notification": {
"notification_type": "source_message_review",
"show_source_message": true,
"requires_user_decision": true
},
"manual_review": null,
"source_message_id": "30010"
}
```
## 9.1 V3 诊断展示块
任务详情接口已新增两个只读数组：
| 字段 | 说明 |
| --- | --- |
| `adapter_contract_errors[]` | 同一 SuperAgent 入站批次中未生成任务的 Adapter 契约错误。 |
| `unhandled_intents[]` | 同一 SuperAgent 入站批次中无法映射到业务任务卡的未处理意图。 |
数组元素字段：
| 字段 | 说明 |
| --- | --- |
| `transition_id` | AI transition ID。 |
| `source_event_index` | AI current 事件序号。 |
| `array_index` | AI 返回数组顺序。 |
| `result_type` | AI 结果类型。 |
| `ai_task_type` | AI 原始任务类型。 |
| `task_subtype` | 业务动作 subtype，可能为空。 |
| `route_code` | V3 路由码。 |
| `system_process_category` | 系统处理分类。 |
| `adapter_error_code` | 契约错误代码；未处理意图通常为空。 |
| `adapter_error_message` | 契约错误安全摘要。 |
| `payload_fragment` | 对前端展示安全的 AI item 片段。 |
前端注意：这两个数组不是任务队列，不提供编辑、确认、执行 OPERA 或重试入口；只用于解释为什么同一封邮件中的某些 event 没有变成业务任务。
## 10. 任务卡前端字段白名单元数据接口
是否需要该接口待确认。如果任务详情接口 `fields[]` 已透出 3.0 所需元数据，则第一版可以不做独立白名单接口；如果后续需要字段矩阵调试页、版本对齐页或前端预加载全部任务卡配置，再补独立接口。
@@ -572,13 +656,13 @@ GET /api/reservation/task-card-field-whitelist
| --- | --- | --- |
| `task_type` | 否 | 按系统主任务类型过滤。 |
| `task_subtype` | 否 | 按任务卡 subtype 过滤。 |
| `version` | 否 | 字段白名单版本，例如 `20260708-3.0`。 |
| `version` | 否 | 字段白名单版本，例如 `20260711-p0`。 |
建议返参：
```json
{
"version": "20260708-3.0",
"version": "20260711-p0",
"items": [
{
"task_type": "UPDATE_BOOKING",
@@ -628,5 +712,5 @@ POST /api/reservation/tasks/{taskId}/order-binding
- 订单列表、任务列表当前统一使用 `items + page` 分页结构；邮件会话详情不分页，返回同一会话全部邮件。
- 邮件会话详情接口已优先使用 `GET /api/source-messages/{sourceMessageId}/conversation`。
- 任务详情 `fields[]` 已由后端直接透出 P0 需要的 3.0 元数据；独立字段白名单接口后置。
- 独立 Message Notification 页面继续后置；新入口 S000/S999 第一版先在任务列表和任务详情展示。
- 独立 Message Notification 页面继续后置；旧 S000/S999 和新 S10/S99 都先在任务列表和任务详情展示。
- 邮件会话全文读取的审计策略由后端内部处理；前端不保存原文读取 key。

14
docs/project/requirements/M002-order-task-workflow-v3.md
View File

@@ -6,7 +6,7 @@
| --- | --- |
| 文档版本 | 0.1 |
| 日期 | 2026-07-11 |
| 状态 | 0711 P0 基线确认版；后端已完成 M002 V3 CP1-CP2 入站解析与路由基线 |
| 状态 | 0711 P0 基线确认版；后端已完成 M002 V3 CP1-CP4 入站、路由持久化和列表 / 详情展示基线 |
| 适用范围 | SourceMessage 之后的 SuperAgent 输出适配、任务路由、只读通知卡、人工复核同卡解阻、前后端协作边界 |
| 主要读者 | 产品、后端、前端、测试、SuperAgent 对接方、后续协作 agent |
@@ -310,7 +310,7 @@ Agent payload 不可变。本系统在同一张卡上维护复核状态：
- 任务列表支持展示旧 `S000/S999` 和新 `S10/S99`，但新文案以 `S10/S99` 为主。
- `S10/S99` 只读卡只出现在任务列表和任务详情，不出现在订单列表。
- 任务列表不应仅按旧 `SOURCE_MESSAGE_ONLY` 判断；应兼容后端后续返回的 `route_code=S10/S99`、`result_type=source_message_review_notification`。
- 任务列表不应仅按旧 `SOURCE_MESSAGE_ONLY` 判断；当前后端已返回 `route_code=S10/S99`、`result_type=source_message_review_notification`。
- type-known manual review 不再统一展示成 Fallback，应展示原业务卡名称和 subtype，并显示复核状态。
- 复核解阻页需要能提交 `field_overrides[]`，并在复核场景下确认订单归属。
- `unhandled_current_intents[]` 只作为展示块，不提供执行按钮。
@@ -324,8 +324,8 @@ V3 建议拆成以下 checkpoint，避免一次性重构过大：
| --- | --- | --- |
| M002-V3-CP1 | 文档和枚举基线 | 已完成：建立 42 路由枚举 / 稳定配置，作为入站路由唯一代码源 |
| M002-V3-CP2 | 入站解析兼容 | 已完成：正式回调支持结构化 S10/S99 和 V3 业务根，保留旧 S000/S999 兼容 |
| M002-V3-CP3 | 路由持久化 | 部分完成：已保存 AI 原始三元组、route_code、system_process_category、unhandled_current_intents 和 adapter_contract_error；message_events / unhandled_current_intents 的前端完整展示仍后置 |
| M002-V3-CP4 | 列表 / 详情展示 | 任务列表和详情支持 S10/S99、42 路由只读展示、type-known review 展示 |
| M002-V3-CP3 | 路由持久化 | 已完成第一版：已保存 AI 原始三元组、route_code、system_process_category、unhandled_current_intents 和 adapter_contract_error |
| M002-V3-CP4 | 列表 / 详情展示 | 已完成第一版：任务列表、订单任务时间线和任务详情透出 V3 路由字段；任务详情支持 S10/S99 入口通知结构、unhandled intent 展示块和 adapter contract error 展示块 |
| M002-V3-CP5 | 同卡复核解阻 | 支持 review_status、field_overrides、复核场景订单归属确认和 READY 流转 |
| M002-V3-CP6 | P0 fixtures 回归 | 引入 0711 P0 fixtures / validator 作为后端适配测试参考，补充项目级测试 |
@@ -343,7 +343,7 @@ V3 P0 不做以下事项：
## 14. 当前代码现状提醒
截至 M002 V3 CP1-CP2 落地后，当前后端已经实现：
截至 M002 V3 CP4 落地后，当前后端已经实现：
- `S000/S999` 文本结果兼容处理。
- 结构化 `S10/S99` 入站处理，复用 `SOURCE_MESSAGE_ONLY` 只读特殊任务。
@@ -351,6 +351,9 @@ V3 P0 不做以下事项：
- V3 业务根 `source_message + message_events[]` 基础解析；能派生到稳定路由的 event 创建业务任务，无法派生的 event、显式 `contract_errors`、根 `missing_fields`、不完整 `manual_review` 和不完整 parent split 候选只落 `adapter_contract_error` transition。
- `unhandled_current_intents[]` 只落 `UNHANDLED_CURRENT_INTENT` transition，不创建订单和任务，也不伪装成 adapter 契约错误。
- AI transition 最小保存 `route_code`、`system_process_category`、`adapter_error_code`、`adapter_error_message`。
- 任务列表、订单任务时间线和任务详情顶层透出 `result_type`、`ai_task_type`、`task_subtype`、`route_code`、`system_process_category`。
- `SOURCE_MESSAGE_ONLY` 任务详情透出 `source_message_only_result.result_type`、`route_code`、`agent_assessment`、`notification`、`manual_review` 和 `raw_answer`。
- 业务任务详情按同一 AI 批次透出 `adapter_contract_errors[]` 与 `unhandled_intents[]` 只读展示块。
- 订单 / 任务列表、任务详情、草稿保存、最终确认、OPERA 模拟骨架和审计列表。
- SuperAgent 查询上下文接口 1、2，以及邮件会话相关查询。
@@ -360,5 +363,4 @@ V3 P0 不做以下事项：
- 复核场景订单归属确认。
- `manual_review.missing_fields[]` 到任务卡可编辑字段白名单的完整映射校验。
- `source_message.source_message_id` 缺失时按 V3 typed `infrastructure_input_error` 结构响应。
- 任务列表 / 详情完整透出 V3 `route_code`、入口通知结构、unhandled intent 展示块和 adapter contract error 展示。
- 真实 OPERA / OHIP、普通任务任意切换订单、P0 fixtures / validator 全量回归。