实现 M002 订单任务入站与队列规则

docs/project/requirements/M002-backend-checkpoint-plan.md

@@ -0,0 +1,316 @@
+# 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 接口契约。