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

实现M002 V4入站写入新模型

Browse Source
This commit is contained in:
andy
2026-07-19 00:54:58 +07:00
parent e6fbd7a111
commit e59ac2f3bf
17 changed files with 1256 additions and 115 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -42,7 +42,7 @@ V3 以以下资料和决策为输入：
- M002 V3 正式采用 0711 P0 基线，并从 2026-07-12 起采用 P0.1 Parent Group / Allotment 增量修订。
- 旧数据 `S000/S999` 继续在任务列表可见；新数据迁移为 `S10/S99`。
- M002 V3 / P0.1 阶段 `S10/S99` 继续复用隐藏技术订单 + 任务列表只读卡，不进入订单列表和订单执行队列；M002 V4 新模型已确认 S10 改为来源通知模型，不再挂隐藏技术订单。
- M002 V3 / P0.1 阶段 `S10/S99` 继续复用隐藏技术订单 + 任务列表只读卡，不进入订单列表和订单执行队列；M002 V4 新模型已确认 S10/S99 改为来源通知模型，不再挂隐藏技术订单。
- 缺少 `source_message.source_message_id` 时，后端已按 `HTTP 400 + infrastructure_input_error + retryable=true` 的技术错误响应返回，不创建 SourceMessage、AI transition、订单、任务或通知卡。
- 内部任务模型采用“方案 C”：完整保存 AI 三元组，系统处理分类和前端展示分类单独维护。
- type-known manual review 使用同一张业务卡复核解阻，不生成第二张 normal task。
@@ -152,7 +152,7 @@ V3 接收端按根结构分流：
- 不允许保存草稿、最终确认、复核转换、普通切换订单、执行 OPERA、重试 OPERA。
- 任务详情展示来源邮件、邮件会话、附件、SuperAgent 原始返回、`route_code` 和入口说明。
以上是 M002 V3 / P0.1 当前实现口径。M002 V4 新模型落地时，S10 改为来源通知模型：任务列表 / 工作台展示，点击进入纯通知详情页，只显示邮件展示卡和确认按钮；不创建订单、不进订单列表、不参与订单阻塞，也不支持编辑、复核、OPERA 或人工终止。
以上是 M002 V3 / P0.1 当前实现口径。M002 V4 新模型落地时，S10/S99 改为来源通知模型：任务列表 / 工作台展示，点击进入纯通知详情页，只显示邮件展示卡和确认按钮；不创建订单、不进订单列表、不参与订单阻塞，也不支持编辑、复核、OPERA 或人工终止。
### 6.3 旧 S000 / S999 兼容
@@ -250,7 +250,7 @@ V3 内部模型采用方案 C，避免把 SuperAgent 的任务三元组直接等
- 有 `group_code`、`confirmation_number` 等可定位字段时，优先挂靠或创建相应订单。
- 同一个 `hotel_id + GROUP_CODE` 只能有一个 `ACTIVE` 订单。
- 同一个 `hotel_id + CONFIRMATION_NUMBER` 只能有一个 `ACTIVE` 订单。
- M002 V3 / P0.1 当前实现中，`S10/S99` 使用隐藏技术订单，不进入订单列表；M002 V4 S10 目标模型改为独立来源通知，不再挂订单。
- M002 V3 / P0.1 当前实现中，`S10/S99` 使用隐藏技术订单，不进入订单列表；M002 V4 S10/S99 目标模型改为独立来源通知，不再挂订单。
P0 新增明确：复核场景下需要支持用户确认订单归属。它不是普通任务切换订单：
@@ -438,9 +438,11 @@ V3 P0.1 不做以下事项：
- `S000/S999` 文本结果兼容处理。
- 结构化 `S10/S99` 入站处理，复用 `SOURCE_MESSAGE_ONLY` 只读特殊任务。
- V4 包级 `route_code=S10/S99` 入站处理，复用 `SOURCE_MESSAGE_ONLY` 只读特殊任务；普通 V4 业务包要求 `route_code=null`。
- V4 包级 `route_code=S10/S99` 已识别；M002 V4 CP4 后，新 V4 S10/S99 写入来源通知模型，普通 V4 业务包要求 `route_code=null`。
- V4 业务根 `source_message + order_contexts[] + message_events[]` 基础解析；`source_message.source_message_id` 按 SourceMessage Inbox 的 `external_message_id` 反查邮件。
- V4 第一版识别 `NEW_BOOKING`、`UPDATE_BOOKING`、`CANCEL_BOOKING`、`TRACE_RESERVATION_NOTES`、`ROOMING_LIST`、`PAYMENT`，可映射 event 先复用现有订单 / 任务 / 任务卡链路，并保存 `catalog_code=M002V4`、`skill_id=booking-desk-event-v4`、`field_contract_version=20260718-v4` 和 V4 原始三元组 / 原始 event payload。
- M002 V4 CP4 已补充新模型写入：普通 V4 业务包会额外创建 V4 订单任务、来源邮件展示卡、Basic Information 卡和业务卡；只有契约错误、没有合法业务 event 的包不会创建 V4 订单任务。
- M002 V4 CP4 后，V4 `route_code=S10/S99` 写入 `workflow_reservation_v4_source_notification`，不再创建隐藏技术订单或旧任务；V3 S10/S99 和旧 S000/S999 仍保留历史兼容链路。
- V4 包级契约错误在 `source_message.source_message_id` 可定位时只写 `adapter_contract_error` transition，不创建订单、任务或用户可处理卡；`source_message_id` 缺失或 SourceMessage 不存在时仍返回明确错误。
- V4 `PAYMENT.attachment_ids[]` 必须匹配 `source_message.attachments[].id`；V4 `UPDATE_BOOKING` 不接受 `rate_code` 或 `after.rate_code`；这类契约错误只落 `adapter_contract_error` transition，不创建用户可处理业务任务。
- 40 条 P0.1 路由枚举 / 稳定配置。
@@ -472,14 +474,14 @@ V3 P0.1 不做以下事项：
M002 V4 CP2 设计文档已落地：
- 文档路径：`docs/project/requirements/M002-v4-order-task-card-domain-model-cp2.md`。
- 设计内容：SourceMessage 邮件展示卡、S10 来源通知、`source_message_id + order_ref` 订单任务、Basic Information 独立卡、每个 V4 event 的业务卡、卡片确认 / 复核 / 锁定、同订单阻塞、表结构草案和后续接口草案。
- 已确认：V4 工作台统一列表新开 `/api/reservation/workbench-items`，业务订单任务新开 `/api/reservation/order-tasks/**`，S10 来源通知使用 `/api/reservation/source-notifications/**`；S10 采用来源通知模型；`FIT + BOOKING_CODE` 不建 ACTIVE 唯一约束，匹配多条进人工复核；Basic Information 必须先确认，其它业务卡第一版不强制逐张确认；Account / Market / Source 目录第一版使用后端固定种子数据。
- 当前状态：只完成文档设计，未新增表、Entity、Repository、接口或前端页面。
- 设计内容：SourceMessage 邮件展示卡、S10/S99 来源通知、`source_message_id + order_ref` 订单任务、Basic Information 独立卡、每个 V4 event 的业务卡、卡片确认 / 复核 / 锁定、同订单阻塞、表结构草案和后续接口草案。
- 已确认：V4 工作台统一列表新开 `/api/reservation/workbench-items`，业务订单任务新开 `/api/reservation/order-tasks/**`，S10/S99 来源通知使用 `/api/reservation/source-notifications/**`；S10/S99 采用来源通知模型；`FIT + BOOKING_CODE` 不建 ACTIVE 唯一约束，匹配多条进人工复核；Basic Information 必须先确认，其它业务卡第一版不强制逐张确认；Account / Market / Source 目录第一版使用后端固定种子数据。
- 当前状态：CP3 表结构 / Repository 和 CP4 入站写入新模型已完成；V4 查询接口、卡片确认 / 复核和前端页面仍未实现。
仍需后续 checkpoint 实现：
- V4 表结构和 Repository 落地已完成第一版：新增 V4 订单任务表、V4 任务卡表和 V4 来源通知表，并提供 Entity、Mapper、Repository、幂等创建、`order_context_index` 稳定排序、非 event 卡 `source_event_index=0` 和 version 乐观锁更新基础方法。
- V4 入站写入新模型，真正创建 SourceMessage 展示卡、Basic Information 卡和业务卡。
- V4 入站写入新模型已完成第一版：真正创建 SourceMessage 展示卡、Basic Information 卡、业务卡和 S10/S99 来源通知。
- V4 查询接口、卡片确认 / 复核 / 锁定、同订单阻塞和业务审计。
- V4 前端页面模型、任务详情字段矩阵和目录校验完全切换。
- 真实 OPERA / OHIP、普通任务任意切换订单、字段矩阵从当前扁平结构整体迁移到 0711 P0 新结构、历史旧 Parent Cancel Booking payload 批量迁移。

40
docs/project/requirements/M002-v4-agent-callback-field-contract.md
View File

@@ -6,7 +6,7 @@
| --- | --- |
| 文档版本 | 1.4 |
| 日期 | 2026-07-18 |
| 状态 | 当前 V4 字段基线；后端已完成 CP1 入站解析基线、CP2 多卡模型设计和 CP3 持久化基线，完整 V4 多卡入站写入与接口仍需后续 checkpoint |
| 状态 | 当前 V4 字段基线；后端已完成 CP1 入站解析基线、CP2 多卡模型设计、CP3 持久化基线和 CP4 入站写入新模型，V4 查询 / 写接口仍需后续 checkpoint |
| 适用范围 | 0718 业务基线下，Agent → Adapter / MCP → 信息系统的业务回调字段 |
| 不适用范围 | 数据库表设计、前端视觉细节、真实 PMS API、技术失败后台重试、旧 M002 V3 数据兼容 |
@@ -16,7 +16,7 @@
本契约用于后续 M002 V4 主流程设计、后端领域建模、前端页面模型、Adapter / MCP Schema 对齐和 SuperAgent 联调。当前后端已按本文完成 V4 入站解析基线：能识别 V4 包、校验关键契约、保存 AI transition / 任务卡原始 payload，并把可映射的六类 event 先接入现有订单任务链路。
V4 订单任务与多卡领域模型的 CP2 设计已经单独落到 `M002-v4-order-task-card-domain-model-cp2.md`。截至 CP3，表结构、Entity、Mapper、Repository 基线已经实现；SuperAgent 入站写入新模型、V4 前端查询接口和卡片写操作接口仍未实现。
V4 订单任务与多卡领域模型的 CP2 设计已经单独落到 `M002-v4-order-task-card-domain-model-cp2.md`。截至 CP4，表结构、Entity、Mapper、Repository 基线已经实现，SuperAgent V4 入站已经能写入 V4 订单任务、来源邮件展示卡、Basic Information 卡、业务卡和 S10/S99 来源通知；V4 前端查询接口和卡片写操作接口仍未实现。
当前已确认开发阶段数据可以清空，因此 M002 V4 后续可以按新模型重建，不要求兼容旧任务数据、旧草稿、旧 OPERA 模拟、旧 `S000/S999`、旧 Fallback 或旧 `case_keys`。
@@ -84,7 +84,7 @@ V4 正式采用并冻结以下 key：
| key | 中文说明 |
| --- | --- |
| `route_code` | 包级路由。普通业务为 `null`，纯通知为 `S10` |
| `route_code` | 包级路由。普通业务为 `null`，纯通知为 `S10` 或 `S99` |
| `source_message` | 当前触发邮件的包级来源事实，只出现一次 |
| `order_contexts` | 订单级上下文集合，每个 `order_ref` 一项 |
| `message_events` | 业务事件数组，承载六类 Event |
@@ -251,9 +251,9 @@ PAYMENT
Basic Information 不是 Event。邮件展示卡不是 Event，由 `source_message` 固定生成。
S10 是包级纯通知路由，不属于上述业务枚举。
S10/S99 是包级来源通知路由，不属于上述业务枚举。S10 表示纯信息类邮件，S99 表示无法形成业务素材包；两者都不创建订单或业务卡。
S99、Fallback、`Need Manual Review`、独立 Voucher、Payment Evidence、Voucher Received 均不再作为新 Agent 输出。
Fallback、`Need Manual Review`、独立 Voucher、旧 Payment Evidence、Voucher Received 均不再作为新 Agent 输出。
## 10. target_order
@@ -567,7 +567,7 @@ true
具体字段错误路径、错误码和页面提示由信息系统根据 Schema、目录和业务规则生成。
## 18. S10 纯通知
## 18. S10/S99 来源通知
### 18.1 结构
@@ -590,7 +590,7 @@ true
- 用户点击“确认”后任务完成。
- 不提供人工终止。
- 不调用 PMS，不修改订单。
- 不输出 S99、Fallback、原因码、通知说明或 `Need Manual Review`。
- S10/S99 第一版只表达来源通知类型，不输出 Fallback、原因码、通知说明或 `Need Manual Review`。
## 19. 技术异常
@@ -614,6 +614,8 @@ true
- 如果 V4 包级结构不符合契约，但 `source_message.source_message_id` 能按 SourceMessage Inbox 的 `external_message_id` 定位到邮件，后端会创建 AI batch，并写入一条 `catalog_code=M002V4`、`system_process_category=ADAPTER_CONTRACT_ERROR` 的 transition；不创建订单、任务或酒店用户可处理卡。
- 如果 `source_message.source_message_id` 缺失、无法解析或无法定位 SourceMessage，后端仍返回明确请求错误，不创建 AI batch / transition。
- 单个 `message_events[i]` 的契约错误只影响该 event，同包其它合法 event 继续按数组顺序处理。
- 普通 V4 业务包中，只有至少有一个合法业务 event 的 `order_ref` 会创建 V4 订单任务、来源邮件展示卡、Basic Information 卡和对应业务卡；全包只有契约错误 event 时不创建 V4 订单任务或用户可处理卡。
- V4 `route_code=S10/S99` 会写入 `workflow_reservation_v4_source_notification`，不再创建隐藏技术订单或旧 `workflow_reservation_task`；旧 V3 S10/S99 和旧文本 S000/S999 仍保留历史兼容链路。
当前项目可以保留 `platform_superagent_dispatch_run` 或同类技术运行记录作为主链路技术状态载体，后续另行设计查询、告警、超时和重试能力。
@@ -687,10 +689,10 @@ AI 回调包
## 24. 当前开发结论
- 0718 业务基线覆盖 M002 V3 的任务级草稿、READY、OPERA 模拟、Fallback、S99 和旧 Need Manual Review 页面语义。
- 新数据只按 `S10` 表达纯通知。
- 新数据按 `S10/S99` 表达来源通知；两者都采用同一来源通知模型。
- 用户可见任务按订单任务 + 多卡建模。
- 普通业务邮件的来源邮件展示卡只读展示，不需要用户确认。
- S10 因为没有业务卡，邮件展示卡需要确认按钮，用于记录已读 / 已处理。
- S10/S99 因为没有业务卡，邮件展示卡需要确认按钮，用于记录已读 / 已处理。
- Basic Information 必须先确认；其它业务卡第一版可以独立确认，不强制逐张顺序确认。
- 每张业务卡独立确认、确认后永久锁定。
- 不保存草稿。
@@ -704,7 +706,7 @@ AI 回调包
- `POST /api/integrations/superagent/task-results` 接收 V4 JSON 包：`route_code`、`source_message`、`order_contexts[]`、`message_events[]`。
- `source_message.source_message_id` 按 SourceMessage Inbox 的 `external_message_id` 定位当前邮件；SuperAgent 不传内部数据库 ID。
- `route_code=S10/S99` 复用现有 `SOURCE_MESSAGE_ONLY` 只读特殊任务机制；任务列表可见，订单列表不可见，不可编辑和执行。
- V4 `route_code=S10/S99` 写入 `workflow_reservation_v4_source_notification` 来源通知模型；旧 `SOURCE_MESSAGE_ONLY` 只读特殊任务仅保留给 V3 S10/S99 和旧 S000/S999 兼容数据。
- 普通业务包要求 `route_code=null`，并按 `message_events[]` 数组顺序处理。
- 第一版识别六类 `event_type`：`NEW_BOOKING`、`UPDATE_BOOKING`、`CANCEL_BOOKING`、`TRACE_RESERVATION_NOTES`、`ROOMING_LIST`、`PAYMENT`。
- 能映射到现有稳定任务卡的 event 会创建业务任务，并在 `ai_payload_json` 中保存 `v4_source_message`、`v4_order_context`、`v4_message_event`、`route_code`、系统处理分类和 `field_contract_version=20260718-v4`。
@@ -714,10 +716,16 @@ AI 回调包
- `UPDATE_BOOKING` 中出现 `rate_code` 或 `after.rate_code` 时按 `UPDATE_RATE_CODE_NOT_ALLOWED` 写入 `adapter_contract_error` transition。
- `manual_review` 只接受 `null` 或布尔 `true`；`true` 必须能由当前对象中可识别的未解决字段解释。
当前 CP1 仍未完成：
当前 CP4 已完成：
- 尚未重建 V4 订单任务 + 多卡领域模型；Basic Information 仍只是保存在 V4 原始 payload / order context 中，未作为独立可确认任务卡落地。
- 尚未取消 V3 草稿 / OPERA 模拟骨架；现有可映射 event 仍复用 M002 V3 任务状态和任务卡创建链路。
- 普通 V4 业务包按 `source_message_id + order_ref` 写入 `workflow_reservation_v4_order_task`。
- 普通 V4 业务包固定创建 `SOURCE_MESSAGE_DISPLAY` 只读卡和 `BASIC_INFORMATION` 可确认 / 可复核卡。
- 合法 V4 event 按 `event_type` 创建 `ROOM_INFORMATION`、`TRACE_RESERVATION_NOTES`、`ROOMING_LIST` 或 `PAYMENT` 业务卡；event 契约错误只落 AI transition。
- V4 S10/S99 写入 `workflow_reservation_v4_source_notification`，状态为 `ACK_REQUIRED`。
当前仍未完成：
- 普通 V4 业务包暂时仍保留旧 V3 任务状态、草稿和 OPERA 模拟骨架兼容，便于前端过渡；V4 新查询 / 写接口完成后再逐步废弃旧链路。
- 尚未接入真实 PMS / OPERA / OHIP。
- 尚未改造前端 V4 页面模型；前端第一版只能通过现有任务详情字段和原始 payload 观察 V4 入站结果。
@@ -729,12 +737,12 @@ AI 回调包
- 普通业务包固定展示来源邮件卡，但该卡只读、不阻塞、不替代邮件会话接口。
- 每个 `order_ref` 创建一张 Basic Information 卡。
- 每个 `message_events[]` event 创建一张业务卡，卡片按固定业务顺序展示。
- S10 后续按来源通知模型实现，不再挂隐藏技术订单；只在任务列表 / 工作台展示，并进入纯通知详情页确认已读 / 已处理。
- S10/S99 后续按来源通知模型实现，不再挂隐藏技术订单；只在任务列表 / 工作台展示，并进入纯通知详情页确认已读 / 已处理。
- `FIT + BOOKING_CODE` 不建立 ACTIVE 唯一约束；业务绑定查到多条时进入人工复核。
- V4 前端工作台统一列表草案为 `/api/reservation/workbench-items`，业务订单任务接口新开 `/api/reservation/order-tasks/**`，S10 来源通知详情草案为 `/api/reservation/source-notifications/{notificationId}`。
- V4 前端工作台统一列表草案为 `/api/reservation/workbench-items`，业务订单任务接口新开 `/api/reservation/order-tasks/**`，S10/S99 来源通知详情草案为 `/api/reservation/source-notifications/{notificationId}`。
- V4 新数据不再保存后端草稿；用户只提交最终确认或复核解阻。
- 卡片确认后锁定，错误修正后续通过审计和未来纠错流程表达，不覆盖原确认。
- 技术异常只进入 AI transition / 技术运行记录，不进入用户可处理卡。
- CP3 已新增 V4 订单任务表、V4 任务卡表和 V4 来源通知表，继续复用 SourceMessage、AI batch、AI transition、Reservation Order 和业务审计表。
CP3 只完成表结构、Entity、Mapper、Repository、幂等创建、`order_context_index` 稳定排序、非 event 卡 `source_event_index=0` 和基础乐观锁更新。后续开发应从 CP4 入站写入新模型开始，并继续补 V4 查询接口、卡片确认 / 复核、S10 ack 和前端页面。
CP3 只完成表结构、Entity、Mapper、Repository、幂等创建、`order_context_index` 稳定排序、非 event 卡 `source_event_index=0` 和基础乐观锁更新。CP4 已把 V4 回调写入新模型。后续开发应继续补 V4 查询接口、卡片确认 / 复核、S10/S99 ack 和前端页面。

74
docs/project/requirements/M002-v4-order-task-card-domain-model-cp2.md
View File

@@ -6,9 +6,9 @@
| --- | --- |
| 文档版本 | 0.2 |
| 日期 | 2026-07-18 |
| 状态 | CP2 设计已确认；CP3 表结构、Entity、Mapper、Repository 基线已实现 |
| 状态 | CP2 设计已确认；CP3 表结构、Entity、Mapper、Repository 基线已实现；CP4 入站写入新模型已实现 |
| 适用范围 | M002 V4 入站后的订单任务、多卡、状态、查询和写操作设计 |
| 不适用范围 | V4 入站写入新模型、V4 前端查询接口、卡片确认 / 复核接口、真实 PMS / OPERA / OHIP、前端页面视觉稿、历史数据迁移 |
| 不适用范围 | V4 前端查询接口、卡片确认 / 复核接口、真实 PMS / OPERA / OHIP、前端页面视觉稿、历史数据迁移 |
## 1. 文档定位
@@ -16,7 +16,7 @@ M002 V4 CP1 已完成 SuperAgent V4 回调包入站解析、基础校验、路
本文是 CP2 设计文档，用于把 2026-07-18 V4 字段契约落成后续可开发的数据模型和接口草案。
截至 CP3，后端已实现本文第 10、11 节中的持久化基线：新增 `workflow_reservation_v4_order_task`、`workflow_reservation_v4_task_card`、`workflow_reservation_v4_source_notification` 三张表，以及对应 Entity、Mapper、Repository 和基础测试。CP3 仍未把 SuperAgent V4 入站结果写入这些新表，也未开放 V4 前端查询或写操作接口。
截至 CP4，后端已实现本文第 10、11 节中的持久化基线，并已把 SuperAgent V4 入站结果写入新表：普通业务包创建 V4 订单任务、来源邮件展示卡、Basic Information 卡和业务卡；V4 S10/S99 创建来源通知。当前仍未开放 V4 前端查询或写操作接口。
后续如本文与 `M002-v4-agent-callback-field-contract.md` 的字段契约冲突，以字段契约为准；如与安全边界冲突，以 `security-access-control-boundary.md` 为准。
@@ -24,10 +24,10 @@ M002 V4 CP1 已完成 SuperAgent V4 回调包入站解析、基础校验、路
| 主题 | CP1 当前实现 | V4 目标模型差距 |
| --- | --- | --- |
| 入站识别 | 已识别 `route_code`、`source_message`、`order_contexts[]`、`message_events[]` | 还没有把 `order_ref` 建成订单任务聚合 |
| SourceMessage | 已按 `source_message.source_message_id` 反查 SourceMessage Inbox | 还没有固定生成业务包内邮件展示卡 |
| Basic Information | 只保存在 `v4_order_context` 原始 payload 中 | 还没有作为每个 `order_ref` 的独立可确认、可锁定卡 |
| 业务 Event | 可映射 event 临时创建旧 `workflow_reservation_task` | 还没有一 event 一业务卡的 V4 多卡模型 |
| 入站识别 | 已识别 `route_code`、`source_message`、`order_contexts[]`、`message_events[]` | CP4 已把有合法 event 的 `order_ref` 建成订单任务聚合；V4 查询接口仍未实现 |
| SourceMessage | 已按 `source_message.source_message_id` 反查 SourceMessage Inbox | CP4 已固定生成普通业务包内邮件展示卡；邮件正文完整读取仍走 SourceMessage 会话接口 |
| Basic Information | 已写入 V4 Basic Information 独立卡 | 目录校验、确认 / 复核写接口仍待 CP6 / CP7 |
| 业务 Event | 可映射 event 临时创建旧 `workflow_reservation_task`，并已额外创建 V4 业务卡 | 旧任务链路仍作前端过渡兼容，后续 V4 查询和写接口完成后再逐步废弃 |
| 技术错误 | 已落 `adapter_contract_error` transition | 已符合目标方向：不创建用户可处理卡 |
| 草稿 / READY / OPERA | 仍复用 V3 草稿、READY 和 OPERA 模拟骨架 | V4 新数据确认口径是不保存草稿、确认后锁定、当前不生成 OPERA |
| 前端查询 | 复用旧任务列表和任务详情 | 需要新订单任务详情接口返回邮件卡、Basic Information 卡和业务卡数组 |
@@ -98,7 +98,7 @@ V4 package / event contract error
- Basic Information 不是 event，但必须是独立任务卡。
- 来源邮件展示卡不是 event，普通业务包内只读，不参与订单执行阻塞。
- S10 采用来源通知模型：任务列表 / 工作台可见，点击进入纯通知详情页；只显示邮件展示卡和确认按钮，不创建订单、不进订单列表、不参与订单阻塞，也不支持编辑、复核、OPERA 或人工终止。
- S10/S99 采用来源通知模型：任务列表 / 工作台可见，点击进入纯通知详情页；只显示邮件展示卡和确认按钮，不创建订单、不进订单列表、不参与订单阻塞，也不支持编辑、复核、OPERA 或人工终止。
- 同一 `order_ref` 下如果有多个相同 `event_type`，第一版按 event 数组项分别建卡；页面排序按固定卡片顺序，再按 `source_event_index` 排序。
## 6. 状态设计
@@ -124,8 +124,8 @@ V4 package / event contract error
| `PENDING_CONFIRM` | 待确认 | 若没有前置阻塞，允许提交最终确认 |
| `REVIEW_REQUIRED` | 待人工复核 | 若没有前置阻塞，允许提交复核修正并确认 |
| `CONFIRMED` | 已确认锁定 | 只能查看，不允许再次编辑或覆盖 |
| `ACK_REQUIRED` | 通知待确认 | 仅用于 S10 来源通知，落在 `workflow_reservation_v4_source_notification.notification_status` |
| `ACKED` | 通知已确认 | 仅用于 S10 来源通知，落在 `workflow_reservation_v4_source_notification.notification_status` |
| `ACK_REQUIRED` | 通知待确认 | 仅用于 S10/S99 来源通知，落在 `workflow_reservation_v4_source_notification.notification_status` |
| `ACKED` | 通知已确认 | 仅用于 S10/S99 来源通知，落在 `workflow_reservation_v4_source_notification.notification_status` |
### 6.3 可操作性派生
@@ -254,7 +254,7 @@ V4 当前不做 OPERA / PMS 执行，但仍需要保留同订单处理顺序，
- 按来源邮件接收时间、AI batch 接收时间、订单任务创建时间排序。
- 更早订单任务仍有未完成可确认卡时，后续订单任务只能查看。
- 技术错误 transition 不参与阻塞。
- S10 来源通知不参与阻塞，也不被阻塞。
- S10/S99 来源通知不参与阻塞，也不被阻塞。
## 10. 数据表设计草案
@@ -306,7 +306,7 @@ uk_reservation_v4_order_task_source_index(hotel_id, source_message_id, order_con
| --- | --- |
| `id` | V4 任务卡 ID |
| `hotel_id` | 酒店 ID |
| `v4_order_task_id` | 所属 V4 订单任务 ID；S10 来源通知不挂订单任务，后续使用独立通知模型承载 |
| `v4_order_task_id` | 所属 V4 订单任务 ID；S10/S99 来源通知不挂订单任务，后续使用独立通知模型承载 |
| `source_message_id` | 来源消息 ID，便于查邮件会话 |
| `ai_transition_id` | 对应 event 的 AI transition ID；Basic Information 和来源邮件展示卡可为空 |
| `card_type` | 卡片类型 |
@@ -339,7 +339,7 @@ uk_reservation_v4_task_card_slot(hotel_id, v4_order_task_id, card_sort_order, so
### 10.4 已新增表：`workflow_reservation_v4_source_notification`
一条记录表示一个 S10 来源通知。它不挂订单任务、不创建订单、不进入订单列表，只用于任务列表 / 工作台和纯通知详情页。
一条记录表示一个 S10/S99 来源通知。它不挂订单任务、不创建订单、不进入订单列表，只用于任务列表 / 工作台和纯通知详情页。
| 字段 | 中文说明 |
| --- | --- |
@@ -347,10 +347,10 @@ uk_reservation_v4_task_card_slot(hotel_id, v4_order_task_id, card_sort_order, so
| `hotel_id` | 酒店 ID，第一版使用系统默认酒店或 SourceMessage 所属酒店 |
| `source_message_id` | SourceMessage Inbox 内部 ID |
| `ai_batch_id` | AI 回调批次 ID |
| `ai_transition_id` | S10 对应 AI transition ID |
| `route_code` | 固定为 `S10` |
| `ai_transition_id` | S10/S99 对应 AI transition ID |
| `route_code` | `S10` 或 `S99` |
| `notification_status` | `ACK_REQUIRED` / `ACKED` |
| `raw_payload_json` | S10 原始 AI 片段或包级摘要 |
| `raw_payload_json` | S10/S99 原始 AI 片段或包级摘要 |
| `ack_by` / `ack_at` | 确认人和确认 UTC 时间 |
| `source_received_at` | 来源邮件接收 UTC 时间，用于任务列表 / 工作台排序 |
| `version` | 乐观锁版本，用于确认按钮并发控制 |
@@ -410,7 +410,7 @@ CP3 Repository 已封装：
- 按 SourceMessage + order_ref 幂等创建订单任务。
- 按 `order_context_index` 保留同一 SourceMessage 下多个 `order_contexts[]` 的稳定顺序。
- 创建 Basic Information / SourceMessage / Event 卡的基础插入方法；非 event 卡 `source_event_index` 固定写入 `0`。
- 按 SourceMessage + AI batch 幂等创建 S10 来源通知。
- 按 SourceMessage + AI batch 幂等创建 S10/S99 来源通知。
- 查询订单任务详情和卡片列表。
- 查询来源通知列表和详情。
- 卡片状态的 version 乐观锁更新基础方法。
@@ -425,18 +425,18 @@ Service 不直接访问 Mapper。
建议新增或拆分：
- `ReservationV4TaskIntakeService`：V4 入站从 AI transition 落 V4 订单任务和卡片。
- `ReservationV4TaskIntakeService`：已实现，V4 入站从 AI transition 落 V4 订单任务、卡片和 S10/S99 来源通知。
- `ReservationV4OrderTaskQueryService`：前端查询订单任务列表和详情。
- `ReservationV4TaskCardCommandService`：处理卡片确认、复核和订单归属确认。
- `ReservationV4SourceNotificationService`：处理 S10 来源通知查询和确认。
- `ReservationV4SourceNotificationService`：处理 S10/S99 来源通知查询和确认。
当前 `ReservationAiTaskIntakeServiceImpl` 后续应只负责入站编排和调用 V4 service，不继续膨胀成 V4 领域服务。
当前 `ReservationAiTaskIntakeServiceImpl` 已在 V4 分支调用 `ReservationV4TaskIntakeService` 完成新模型写入；后续查询、确认和复核仍应继续拆到独立 V4 service，避免主入站类继续膨胀。
## 12. 前端查询接口草案
以下只是接口草案，CP2 不实现。
V4 前端接口不继续扩展旧 `/api/reservation/tasks/**` 作为 V4 主模型入口。第一版草案中，工作台统一列表使用 `/api/reservation/workbench-items`，业务订单任务使用 `/api/reservation/order-tasks/**`，S10 来源通知详情和确认使用 `/api/reservation/source-notifications/**`。
V4 前端接口不继续扩展旧 `/api/reservation/tasks/**` 作为 V4 主模型入口。第一版草案中，工作台统一列表使用 `/api/reservation/workbench-items`，业务订单任务使用 `/api/reservation/order-tasks/**`，S10/S99 来源通知详情和确认使用 `/api/reservation/source-notifications/**`。
### 12.1 工作台统一列表
@@ -449,7 +449,7 @@ GET /api/reservation/workbench-items
用途：
- 作为 V4 任务列表 / 工作台的第一版统一入口。
- 同时返回业务订单任务和 S10 来源通知。
- 同时返回业务订单任务和 S10/S99 来源通知。
- 前端按 `item_type` 区分跳转目标。
返回摘要应包含：
@@ -457,10 +457,10 @@ GET /api/reservation/workbench-items
- `item_type`：`ORDER_TASK` / `SOURCE_NOTIFICATION`。
- `target_id`：订单任务 ID 或来源通知 ID。
- `source_message_summary`
- `display_order_key`：S10 来源通知为空。
- `card_counts`：S10 来源通知为空或只返回通知状态。
- `next_action_card_id`：S10 来源通知为空。
- `notification_status`：仅 S10 来源通知返回 `ACK_REQUIRED` / `ACKED`。
- `display_order_key`：S10/S99 来源通知为空。
- `card_counts`：S10/S99 来源通知为空或只返回通知状态。
- `next_action_card_id`：S10/S99 来源通知为空。
- `notification_status`：仅 S10/S99 来源通知返回 `ACK_REQUIRED` / `ACKED`。
- `order_task_status`：仅业务订单任务返回 `OPEN` / `COMPLETED`。
- `display_status`：可返回 `OPEN` / `BLOCKED` / `COMPLETED` / `ACK_REQUIRED` / `ACKED`。
- `readonly_reason_code`
@@ -503,7 +503,7 @@ GET /api/reservation/order-tasks
说明：
- 该接口只返回业务订单任务，不返回 S10 来源通知。
- 该接口只返回业务订单任务，不返回 S10/S99 来源通知。
- V4 任务列表 / 工作台页面第一版优先使用 `GET /api/reservation/workbench-items`。
### 12.3 订单任务详情
@@ -530,7 +530,7 @@ GET /api/reservation/order-tasks/{orderTaskId}
前端应以返回的 `cards[]` 和 `availability` 为准渲染，不自行拼完整字段矩阵。
### 12.4 S10 来源通知详情
### 12.4 S10/S99 来源通知详情
```text
GET /api/reservation/source-notifications/{notificationId}
@@ -551,7 +551,7 @@ GET /api/reservation/source-notifications/{notificationId}
说明：
- 只用于 S10 纯通知详情页。
- 只用于 S10/S99 来源通知详情页。
- 不返回 `order_task`、`bound_order`、`basic_information_card` 或 `business_cards`。
- 邮件正文、附件 URL 和会话原文读取仍按 SourceMessage 权限和原文读取审计规则处理。
@@ -607,7 +607,7 @@ POST /api/reservation/source-notifications/{notificationId}/ack
权限：RESERVATION_TASK_CONFIRM
```
S10 已确认采用来源通知模型，不继续复用隐藏技术订单或旧 `SOURCE_MESSAGE_ONLY` 任务确认方式。第一版通知详情只显示邮件展示卡和确认按钮，确认动作表示已读 / 已处理。
S10/S99 已确认采用来源通知模型，不继续复用隐藏技术订单或旧 `SOURCE_MESSAGE_ONLY` 任务确认方式。第一版通知详情只显示邮件展示卡和确认按钮，确认动作表示已读 / 已处理。
请求要点：
@@ -657,7 +657,7 @@ S10 已确认采用来源通知模型，不继续复用隐藏技术订单或旧
| 查询工作台、订单任务列表 / 详情、来源通知详情 | `FRONTEND_USER` | `RESERVATION_TASK_READ` | 只读默认不写业务审计 |
| 确认卡片 | `FRONTEND_USER` | `RESERVATION_TASK_CONFIRM` | 写业务审计 |
| 复核解阻 | `FRONTEND_USER` | `RESERVATION_MANUAL_REVIEW_RESOLVE` | 写业务审计 |
| 确认 S10 来源通知 | `FRONTEND_USER` | `RESERVATION_TASK_CONFIRM` | 写业务审计 |
| 确认 S10/S99 来源通知 | `FRONTEND_USER` | `RESERVATION_TASK_CONFIRM` | 写业务审计 |
| 读取邮件正文 / 附件 | `FRONTEND_USER` | `SOURCE_MESSAGE_READ` + `SOURCE_MESSAGE_ORIGINAL_READ` | 写原文读取审计 |
| SuperAgent V4 回调 | `THIRD_PARTY_SUPERAGENT` | HMAC 机器鉴权 | 写 AI batch / transition |
@@ -668,22 +668,22 @@ AI 原始 payload、邮件正文、附件 URL 和技术 trace 不应直接进入
| Checkpoint | 目标 | 主要交付 |
| --- | --- | --- |
| M002-V4-CP3 | V4 表结构和基础 Repository | 新增 V4 order task / card / source notification 表、Entity、Mapper、Repository、测试 |
| M002-V4-CP4 | V4 入站落新模型 | SuperAgent V4 回调创建订单任务、Basic Information 卡、业务卡、邮件展示卡和 S10 来源通知 |
| M002-V4-CP4 | V4 入站落新模型 | 已完成：SuperAgent V4 回调创建订单任务、Basic Information 卡、业务卡、邮件展示卡和 S10/S99 来源通知 |
| M002-V4-CP5 | V4 查询接口 | 工作台统一列表、订单任务列表、详情、订单详情时间线和来源通知详情查询接口 |
| M002-V4-CP6 | V4 卡片确认和复核 | 不保存草稿，支持确认、复核、锁定、审计、阻塞规则和 S10 来源通知确认 |
| M002-V4-CP6 | V4 卡片确认和复核 | 不保存草稿，支持确认、复核、锁定、审计、阻塞规则和 S10/S99 来源通知确认 |
| M002-V4-CP7 | 受控目录第一版 | Account、RoomType、RateCode、Department 固定目录或版本化快照校验 |
| M002-V4-CP8 | V4 前端契约收口 | 字段、控件、availability、错误展示和旧任务入口切换 |
| M002-V4-CP9 | 旧 V3 / V2 能力收口评估 | 明确哪些兼容入口可以关闭，哪些仍保留只读历史 |
## 17. 已确认设计决策
1. V4 前端接口不继续扩展旧 `/api/reservation/tasks/**`；工作台统一列表新开 `/api/reservation/workbench-items`，业务订单任务新开 `/api/reservation/order-tasks/**`，S10 来源通知使用 `/api/reservation/source-notifications/**`。
1. V4 前端接口不继续扩展旧 `/api/reservation/tasks/**`；工作台统一列表新开 `/api/reservation/workbench-items`，业务订单任务新开 `/api/reservation/order-tasks/**`，S10/S99 来源通知使用 `/api/reservation/source-notifications/**`。
2. `FIT + BOOKING_CODE` 第一版不建立 ACTIVE 唯一约束；业务绑定时要求匹配结果至多一条，匹配多条进入人工复核。
3. `BOOKING_CODE` 只是拿到 `CONFIRMATION_NUMBER` 前的临时定位字段，后续不作为 PMS 永久主键。
4. S10 采用来源通知模型：任务列表 / 工作台展示，不挂隐藏技术订单；通知详情只显示邮件展示卡和确认按钮。
5. S10 不创建订单、不进订单列表、不参与订单阻塞，也不支持编辑、复核、OPERA 或人工终止。
4. S10/S99 采用来源通知模型：任务列表 / 工作台展示，不挂隐藏技术订单；通知详情只显示邮件展示卡和确认按钮。
5. S10/S99 不创建订单、不进订单列表、不参与订单阻塞，也不支持编辑、复核、OPERA 或人工终止。
6. 第一版不强制所有业务卡逐张顺序确认，但 Basic Information 必须先确认。
7. Basic Information 的 Account / Market / Source 目录第一版使用后端固定种子数据。
8. 普通业务邮件的来源邮件展示卡只读展示，不需要用户确认；用户只确认 Basic Information 和具体业务卡。
9. S10 因为没有业务卡，邮件展示卡需要确认按钮，用来记录已读 / 已处理。
9. S10/S99 因为没有业务卡，邮件展示卡需要确认按钮，用来记录已读 / 已处理。
10. V4 新模型落地并完成前端切换后，旧 V2/V3 任务详情、草稿保存和最终确认接口可以逐步废弃。