th-hotel-simple/docs/project/requirements/M002-backend-checkpoint-plan.md

M002 Backend Checkpoint Plan 后端开发 Checkpoint 计划

文档信息

项目	内容
文档版本	0.1
日期	2026-07-07
状态	后端开发计划草稿
适用范围	M002 后端实现拆分、交付物和验收标准
主要读者	后端、测试、产品、后续协作 agent

1. 文档定位

本文把 M002-order-task-workflow-v2.md、M002-superagent-task-result-api-contract.md 和 M002-backend-data-model-design.md 拆成可执行后端 checkpoint。

每个 checkpoint 都应先读项目规范，再按本项目包结构和注释要求实现。不要一次性把完整后端做完，也不要在不确定字段或目录归属时先写再重构。

2. 开发前必读

后端开发前必须先读：

• AGENTS.md
• README.md
• docs/project/backend-development-guidelines.md
• docs/import/reusable/backend-development-guidelines.md
• docs/import/reusable/backend-base-structure-pagination-guidelines.md
• docs/import/reusable/alibaba-java-coding-guidelines-summary.md
• docs/project/requirements/M002-order-task-workflow-v2.md
• docs/project/requirements/M002-superagent-task-result-api-contract.md
• docs/project/requirements/M002-backend-data-model-design.md
• docs/import/20260706/开发AI先读_工作顺序.md
• docs/import/20260706/AI输出参数并集字典.xlsx
• docs/import/20260706/任务卡展示编辑矩阵.xlsx

3. 代码组织要求

后端实现必须继续遵守当前项目包结构习惯：

• control 放 Controller 具体实现。
• service 放 Service 接口。
• service.impl 放 Service 实现类。
• domain 放 Entity。
• mapper 放 MyBatis Mapper。
• repository 放 Repository 接口和具体实现。
• common.dto、common.request、common.result 放通用数据载体。
• common.enums 放枚举。
• 外部系统适配类放在对应 integrations.<capability>.<provider>.adapter 包。

Controller、Service、Service 实现类的方法必须有中文注释。Entity 字段必须有中文注释。Mapper 继承 MyBatis-Plus 的自带方法不强制写注释，自定义方法按复杂度补充中文注释。

4. Checkpoint 1：接口契约与安全骨架

名称：m002-cp01-superagent-intake-security

目标：

• 建立 SuperAgent 任务结果入站接口骨架。
• 完成 HMAC 鉴权、请求体大小限制、timestamp 和 nonce 防重放。
• 暂不创建完整订单任务，只返回受控错误或最小接收结果。

建议范围：

• 新增配置项：SUPERAGENT_TASK_RESULT_HMAC_SECRET 等。
• 新增 HMAC 校验组件。
• 新增 nonce 去重存储，第一版可用数据库或可控缓存实现。
• 新增请求 / 响应 DTO。
• 新增统一错误响应。

验收标准：

• 缺失 Header 返回 401。
• timestamp 超时返回 401。
• 签名错误返回 401。
• nonce 重放返回 409。
• 请求体过大返回 413。
• 响应和日志不暴露 secret、签名原文或完整请求体。

不做：

• 不做业务字段合法性判断。
• 不执行 OPERA 模拟。
• 不开发前端页面。

5. Checkpoint 2：AI 过渡层持久化

名称：m002-cp02-ai-transition-persistence

目标：

• 建立 AI 接收批次表和 AI 过渡表。
• 保存 source_message_id + ai_task_results[] + extraction_warnings[]。
• 实现系统生成幂等键，保证重复提交不重复创建记录。

建议范围：

• Flyway migration。
• Entity、Mapper、Repository。
• 批次幂等键生成。
• item 幂等键生成。
• source_message_id 存在性校验。
• 保存 AI 原始 JSON 和常用物理列。

验收标准：

• 同一请求重复提交返回幂等重放，不重复插入。
• 同一 source_message_id 不同请求体第一版返回 409。
• 每个 item 保存 array_index、source_event_index 和 execution_order。
• 保存 ai_payload_json，用户后续修改不得覆盖该字段。

不做：

• 不创建 OPERA 操作。
• 不实现任务详情编辑。

6. Checkpoint 3：订单、任务和任务卡最小模型

名称：m002-cp03-order-task-card-model

目标：

• 建立订单、任务和任务卡表。
• 将 AI 过渡记录映射成系统订单、任务和任务卡。
• 完成主任务类型和任务卡类型映射。

建议范围：

• 订单状态枚举：TEMPORARY、ACTIVE、ENDED、LOGIC_DELETED。
• 任务状态枚举：PENDING_CONFIRM、READY、EXECUTING、FAILED、COMPLETED。
• 系统主任务类型枚举。
• 任务卡类型枚举。
• Message Notification 创建临时订单和只读任务卡。
• Fallback / manual_review 创建临时订单和人工复核任务卡。

验收标准：

• New Booking 无业务号时创建临时订单。
• Update / Cancel 可匹配订单时挂已有订单，不可匹配时挂临时订单。
• Message Notification 挂临时订单，但 queue_participation=false。
• 任务保存 AI 原始 task_type、系统主任务类型、任务卡类型和 subtype。
• 任务初始状态符合数据模型设计。

不做：

• 不实现用户编辑确认。
• 不实现 OPERA 模拟。

7. Checkpoint 4：订单挂靠与队列可处理状态

名称：m002-cp04-order-queue-availability

目标：

• 实现订单挂靠规则和同订单任务执行顺序。
• 实现实时计算任务是否可处理。
• 不落库 BLOCKED 状态。

建议范围：

• 按 order_id + execution_order 查询任务队列。
• 前置参与队列任务未完成时，后续任务只读。
• 前置参与队列任务为 FAILED 或 COMPLETED 时视为结束，不阻塞后续任务。
• queue_participation=false 的任务不阻塞队列。
• 数据库通过 hotel_id + order_id + queue_participation + execution_order 唯一约束兜底，服务层遇到并发队列序号冲突时重新取号重试。
• 联动任务识别 parent_source_event_index、linked_task_group_id、blocked_until_parent_completed。
• 第一版可先提供任务详情接口，返回实时可处理状态和只读原因，前端页面后续再定。

验收标准：

• 同一次 AI 返回多个任务时保留数组顺序。
• 前置任务未完成时后续任务不能编辑、确认、执行或重试。
• 前置任务为 FAILED 时后续任务不再被阻塞。
• Message Notification 不阻塞其他任务，也不被其他任务阻塞。
• 任务切换订单后按目标订单队列重新计算可处理状态。

不做：

• 不允许用户强制完成前置任务。
• 不允许跳过失败 OPERA 操作。

8. Checkpoint 5：任务详情、编辑和确认 payload

名称：m002-cp05-task-detail-confirmed-payload

目标：

• 提供任务详情读取接口。
• 支持用户编辑任务卡字段。
• 用户确认后生成 confirmed_payload_json。

建议范围：

• 任务详情 Response 包含 AI 原始摘要、任务卡字段、可处理状态和阻塞原因。
• 第一版任务卡字段矩阵写在代码 Provider 中，避免 Controller / Service 直接硬编码。
• 保存 draft_payload_json。
• 确认时生成 confirmed_payload_json。
• 审计用户字段修改和确认。

验收标准：

• 不可处理任务详情只能查看，不能编辑或确认。
• 可处理任务可以保存草稿。
• 用户确认后任务进入 READY。
• OPERA 参数不得从 ai_payload_json 读取。
• 用户修改不覆盖 AI 原始 JSON。

不做：

• 不接真实 OPERA。
• 不把 Excel 全量字段导入数据库。

9. Checkpoint 6：人工复核转换和订单迁移

名称：m002-cp06-manual-review-conversion

目标：

• 实现 Fallback / manual_review 的人工处理。
• 支持转为 New / Update / Cancel。
• 支持任务从临时订单迁移到已有订单。

建议范围：

• 转换类型接口。
• 订单切换接口。
• 临时订单逻辑删除。
• 转换原因字段第一版允许为空，但必须记录审计。
• 转为 UPDATE_BOOKING 或 CANCEL_BOOKING 时目标订单 ID 必填。
• 审计转换、迁移和删除。

验收标准：

• 转为 NEW_BOOKING 时临时订单可继续保留；如果 AI 原始 case_keys 已有 Group Code 或 Confirmation No.，第一版可先以 AI_CANDIDATE 激活原临时订单。
• 转为 UPDATE_BOOKING 或 CANCEL_BOOKING 时必须选择目标订单。
• 原临时订单无有效任务后进入 LOGIC_DELETED。
• 所有转换都记录前后快照；原因有则记录，没有则为空。

不做：

• 不允许绕过前置任务直接完成。
• 不做 AI 业务合法性二次判断。

10. Checkpoint 7：OPERA 模拟操作与重试

名称：m002-cp07-opera-simulation-results

目标：

• 建立 OPERA 模拟逻辑操作和 attempt 记录。
• 支持执行、失败、重试和结果展示。
• 支持 New Booking 在必要时回填订单业务号。

建议范围：

• 从 confirmed_payload_json 生成模拟操作。
• 每个任务可生成多条操作。
• 每次执行或重试新增 attempt。
• 失败任务进入 FAILED。
• 全部必要操作成功后任务进入 COMPLETED。
• 从 business_key_candidates_json 回填订单业务号。
• 第一版先在订单表设计 business_key_source、business_key_backfilled_at 等字段，OPERA 模拟执行模块后续再写入。

验收标准：

• 未确认任务不能执行 OPERA 模拟。
• 不可处理任务不能执行 OPERA 模拟。
• 失败操作不能跳过。
• 用户不能强制完成任务。
• 重试不覆盖历史 attempt。
• New Booking 无业务号时，模拟成功后可回填 Confirmation Number 或 Group Code 含义字段。

不做：

• 不接真实 OPERA 接口。
• 不写死真实 OPERA 返回字段路径。

11. Checkpoint 8：审计、查询和收口

名称：m002-cp08-audit-query-hardening

目标：

• 补齐审计查询、列表筛选、安全收口和回归测试。

建议范围：

• 订单任务审计查询。
• 任务列表基础筛选。
• 订单详情下任务时间线。
• 安全日志检查。
• 关键接口集成测试。

验收标准：

• 能追溯 AI 接收、任务创建、订单挂靠、用户修改、确认、迁移、OPERA 模拟和重试。
• 列表不返回完整 AI payload、邮件正文、附件 URL 或 Secret。
• 所有关键路径有测试覆盖。
• ./mvnw test 通过，或明确说明环境问题。

12. 建议开发节奏

建议一次只做一个 checkpoint。每个 checkpoint 完成后：

• 先自查是否符合项目包结构和中文注释规范。
• 运行相关测试。
• 做 code review。
• 再进入下一个 checkpoint。

如果实现过程中遇到以下情况，必须先暂停确认：

• 订单状态需要新增第五种。
• 任务状态需要新增新状态。
• OPERA 模拟结果字段需要写死真实路径。
• Excel 字段矩阵需要从代码配置改成数据库配置。
• 某个类不知道应该放在哪个包。
• 需要调整已确认的 SuperAgent 接口契约。