实现 M002 V3 入站解析与路由基线

docs/project/frontend-backend/backend-to-frontend-notes.md

@@ -2,7 +2,7 @@
 
 ## 1. 文档定位
 
-本文记录后端侧提醒前端开发时必须注意的项目规范、业务规则、接口边界和安全要求。当前内容服务于 Reservation 任务详情、订单详情、任务列表、S000/S999 特殊只读任务、历史 Message Notification、系统管理后台等第一版页面。
+本文记录后端侧提醒前端开发时必须注意的项目规范、业务规则、接口边界和安全要求。当前内容服务于 Reservation 任务详情、订单详情、任务列表、S10/S99 源邮件只读通知卡、旧 S000/S999 兼容展示、历史 Message Notification、系统管理后台等第一版页面。
 
 ## 2. 项目开发注意事项
 
@@ -18,9 +18,11 @@
 
 ## 3. 字段来源注意事项
 
-- `docs/import/20260708/任务卡前端展示字段表 3.0.xlsx` 是前端展示 / 编辑白名单。
+- `docs/import/20260711/开发交付_P0冻结基线_2026-07-11/01_Adapter_Frontend/任务卡前端字段变更与路由说明_3.0_to_current.md` 是当前前端 / Adapter 路由说明，覆盖 42 路由、S10/S99、type-known manual review 和 fail-closed 口径。
+- `docs/import/20260711/开发交付_P0冻结基线_2026-07-11/01_Adapter_Frontend/任务卡前端字段变更说明_3.0_to_当前版_2026-07-10.xlsx` 是当前前端展示 / 编辑白名单和三元组路由表。
+- `docs/import/20260708/任务卡前端展示字段表 3.0.xlsx` 是历史前端展示 / 编辑白名单，已被 0711 P0 冻结基线承接。
 - `docs/import/20260706/任务卡展示编辑矩阵.xlsx` 是后端校验、最终确认写入、OPERA 映射和展示条件的完整规则来源。
-- 前端不要直接把整个 `ai_task_results[]` 渲染成表单，只展示白名单允许的字段。
+- 前端不要直接把整个旧 `ai_task_results[]` 或 V3 `message_events[]` 渲染成表单，只展示白名单允许的字段。
 - 如果 3.0 白名单与旧矩阵冲突，应记录为前后端待确认问题，不由前端单方面放宽必填、枚举或校验规则。
 
 ## 4. 业务规则注意事项
@@ -29,9 +31,11 @@
 - 用户可以修改任务字段内容；最终确认后，后端使用 `confirmed_payload_json` 作为 OPERA 模拟输入来源。
 - 同一订单下，前置任务未结束时，后续任务只能查看，不能编辑、确认或执行 OPERA 模拟操作。
 - 任务状态 `FAILED` 第一版视为结束状态，不阻塞后续任务；但失败的 OPERA 操作不能跳过，必须展示失败原因并允许重试。
-- SuperAgent 新入口结果只会生成 `normal_task`、`manual_review` 或纯文本 `S000/S999`；`informational_message` 仅历史兼容，新页面不要再按新数据入口依赖它。
-- `S000` 表示纯信息类邮件，`S999` 表示无法形成业务素材包。后端会创建 `SOURCE_MESSAGE_ONLY` 只读特殊任务，任务列表可见，订单列表不可见。
-- `SOURCE_MESSAGE_ONLY` 任务不允许编辑、确认、人工转换订单、执行 OPERA 或重试 OPERA；不参与订单任务执行队列，不阻塞其他任务，也不被其他任务阻塞。
+- M002 V3 新入口采用结构化 `S10/S99`：`S10` 表示未匹配当前支持的业务事件，`S99` 表示输入不足或无法形成业务素材包；旧 `S000/S999` 继续按历史数据兼容展示。
+- `S10/S99` 后端会创建只读源邮件通知卡，任务列表可见，订单列表不可见；当前代码中的旧 `SOURCE_MESSAGE_ONLY` 任务仍按同一只读语义展示。
+- 源邮件只读通知卡不允许编辑、确认、人工转换订单、执行 OPERA 或重试 OPERA；不参与订单任务执行队列，不阻塞其他任务，也不被其他任务阻塞。
+- type-known manual review 后续应展示为原业务任务卡的复核模式，不应统一展示成 Fallback。只有业务类型或 subtype 本身未知时才进入 Fallback。
+- 复核场景下允许用户确认订单归属；这不等于开放普通任务任意切换订单。
 - 历史 Message Notification 挂临时订单，只读展示，不参与订单任务执行队列，不阻塞其他任务，也不被其他任务阻塞。
 - Fallback / manual_review 转为 New / Update / Cancel 时需要展示审计轨迹；登录权限底座已提供，具体业务审计 actor 迁移仍后置。
 - 普通任务切换订单接口已确认后置，前端第一版不要把普通任务拖拽或切换订单做成可提交能力。
@@ -43,10 +47,10 @@
 | `POST /api/auth/login` | 用户名密码登录 | 成功后返回 `access_token`、当前用户、可访问酒店、权限码和可见菜单；token 只放 `sessionStorage`，不要放 `localStorage`、URL、日志或错误上报。 |
 | `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`；隐藏技术订单不返回，因此 S000/S999 不会在订单列表形成订单。 |
-| `GET /api/reservation/tasks` | 查询任务列表 / 工作台 | 用 `can_process` 和 `readonly_reason_code` 控制入口按钮；列表不返回 AI 原始 payload、邮件正文或附件 URL；已返回来源邮件会话摘要字段，并支持 `order_status` 按任务所属订单状态筛选；S000/S999 会以 `task_type=SOURCE_MESSAGE_ONLY` 返回。 |
+| `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 字段元数据；`SOURCE_MESSAGE_ONLY` 详情字段列表和 OPERA 操作列表为空，并通过 `source_message_only_result` 返回 S000/S999 入口结果。 |
+| `GET /api/reservation/tasks/{taskId}` | 查询任务详情 | 以返回的可处理状态和只读原因控制按钮，不只看任务状态；`fields[]` 已包含 P0 字段元数据；源邮件只读通知卡字段列表和 OPERA 操作列表为空，旧数据通过 `source_message_only_result` 返回 S000/S999 入口结果；结构化 S10/S99 已可入站并保存，详情接口完整透出 `agent_assessment/notification/manual_review` 后续补齐。 |
 | `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，不用于普通任务切换订单。 |
@@ -76,7 +80,7 @@
 | `GET /api/reservation/orders/{orderId}` | 补齐 `tasks[]` 每条任务的来源邮件会话摘要字段。 | `include_tasks=false` 可只取订单摘要；时间线顺序由后端按订单队列返回，前端不要自行按创建时间重排。`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 字段和 S000/S999 识别。 | 只用于调试页面；请求为 multipart/form-data；必须传 `X-TH-Hotel-Debug-Upload-Key`，但该 key 不能写进前端源码、构建产物、URL、localStorage 或错误上报；SuperAgent 返回 S000/S999 时不是 JSON 解析失败。 |
+| `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 解析失败。 |
 
 酒店上下文注意：Reservation 列表、订单详情、任务列表和 Debug EML 上传的 `hotel_id` 第一版都是可选参数。前端默认可以不传；后端会按当前登录用户酒店上下文或平台酒店表唯一 `ACTIVE` 酒店解析。如果前端传了当前选中酒店，后端会校验该酒店是否可访问。
 
@@ -135,10 +139,10 @@ POST /api/auth/logout
 - `next_processable_task_id` 是后端按同订单队列实时计算出的下一条可处理任务；前端可以用它做“继续处理”入口。
 - `display_order_key` 是前端优先展示的订单业务号或临时订单号；`group_code` 和 `confirmation_number` 只有在当前订单业务号类型匹配时返回。
 - 订单 ID、任务 ID、SourceMessage ID 在这些前端接口中按字符串返回，前端不要转换成 JavaScript number。
-- `SOURCE_MESSAGE_ONLY` 任务背后有隐藏技术订单用于满足后端任务外键，但订单列表不会返回该订单；任务列表中该类任务的 `display_order_key`、`temporary_order_no`、`group_code`、`confirmation_number` 可能为空，前端不要因此隐藏整条任务。
-- 当前前端已按 `SOURCE_MESSAGE_ONLY` 展示 S000/S999，只在任务列表和任务详情提供只读查看入口；`INFORMATIONAL_MESSAGE` 仅作为历史 Message Notification 兼容路径保留。
-- 任务列表里 `task_type=SOURCE_MESSAGE_ONLY`、`task_subtype=S000/S999` 的记录只展示邮件来源和 SuperAgent 入口结果，不展示处理按钮。
-- 任务详情里 `source_message_only_result` 仅对 `SOURCE_MESSAGE_ONLY` 返回，包含 `entry_result_code`、`entry_result_meaning`、`entry_result_description`、`entry_result_source_message_id` 和 `raw_answer`；普通任务该字段为空。
+- 源邮件只读通知卡背后有隐藏技术订单用于满足后端任务外键，但订单列表不会返回该订单；任务列表中该类任务的 `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；普通业务任务该字段为空。
 
 ### 5.6 前端联调演示数据 seed 接口
 
@@ -174,12 +178,12 @@ Content-Type: application/json
 - 已完成 New Booking 任务和两条 OPERA 模拟成功记录。
 - OPERA 模拟失败任务，可在任务详情看到失败 attempt 和重试入口。
 - Fallback / manual_review 任务。
-- 历史 Message Notification 只读任务；S000/S999 特殊只读任务可通过 SuperAgent 回调或后续专用夹具补充。
+- 历史 Message Notification 只读任务；旧 S000/S999 和新 S10/S99 特殊只读任务可通过 SuperAgent 回调补充，专用前端 fixture 仍可后续增加。
 - 同一邮件会话下多封邮件、完整 HTML、附件外链和内联图片外链。
 
 ### 5.7 任务详情字段元数据接入注意
 
-- `fields[]` 第一版服务于任务详情动态展示，字段来源与白名单规则以 `docs/import/20260708/任务卡前端展示字段表 3.0.xlsx` 为准。
+- `fields[]` 第一版服务于任务详情动态展示，字段来源与白名单规则后续以 `docs/import/20260711/开发交付_P0冻结基线_2026-07-11/01_Adapter_Frontend/任务卡前端字段变更说明_3.0_to_当前版_2026-07-10.xlsx` 和同目录路由说明为准；当前代码中仍有 20260708 白名单兼容口径。
 - `result_type`、`task_type`、`task_subtype`、`default_value_source` 已透出给前端，用于和最新前端白名单对齐。
 - 后端校验、最终确认写入、OPERA 映射和展示条件仍以 `docs/import/20260706/任务卡展示编辑矩阵.xlsx` 为完整规则来源。
 - 前端保存草稿时不要自行按 `write_path` 重组 OPERA 参数；第一版按任务详情返回的字段和值提交即可，真实 OPERA 参数组装后续由后端 adapter / 转换层处理。
@@ -215,7 +219,7 @@ run_label: 可选调试标签
 - `X-TH-Hotel-Debug-Upload-Key` 只能由调试人员在受控环境手动提供，不能放入 `VITE_*`、源码、构建产物、URL query、localStorage、错误上报或普通日志。
 - 返回的 `html_body_sanitized` 复用邮件会话详情的安全策略，前端展示 HTML 时优先使用；`html_body_with_oss_urls` 只作为调试原始处理结果，不建议直接渲染。
 - 返回的 `uploaded_media[]`、`original_eml_oss_url`、`html_body_with_oss_urls`、`html_body_sanitized` 可能包含 OSS URL；前端不要写入普通日志、埋点、错误上报或 URL query。
-- `superagent_parsed_json` 为空时，前端展示 `superagent_raw_answer` 和 `warnings[]`，不要假定 SuperAgent 总能返回 JSON。
+- `superagent_parsed_json` 为空时，前端展示 `superagent_raw_answer` 和 `warnings[]`，不要假定 SuperAgent 总能返回业务 JSON；旧 S000/S999 和新 S10/S99 都属于可解释入口结果，不是普通解析失败。
 
 ### 5.9 系统管理后台接口接入注意
 
@@ -264,6 +268,7 @@ run_label: 可选调试标签
 ## 7. 需要持续提醒的后置事项
 
 - 普通任务切换订单接口继续后置。
+- M002 V3 的结构化 `S10/S99` 入站、42 路由枚举 / 稳定配置、`UNHANDLED_CURRENT_INTENT` 和 `adapter_contract_error` transition 最小落库已完成；type-known manual review 同卡解阻、复核场景订单归属确认、任务列表 / 详情完整透出 V3 路由字段仍需后续后端 checkpoint。前端新页面应预留字段和状态，不要继续只写死旧 `S000/S999`。
 - 系统管理后台 V1 已完成；后续若要做用户搜索更多筛选、批量操作、密码策略增强、MFA、登录设备管理，应单独开需求。
 - 现有 Reservation / SourceMessage 业务接口的强制登录、强制权限和业务审计 actor 全量迁移仍后置。
 - 真实 OPERA / OHIP 接入继续后置。