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

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 和前端页面。