# M002 Backend Checkpoint Plan 后端开发 Checkpoint 计划 ## 文档信息 | 项目 | 内容 | | --- | --- | | 文档版本 | 0.2 | | 日期 | 2026-07-08 | | 状态 | 后端 checkpoint 计划与阶段实现记录 | | 适用范围 | 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...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[]`，并将外部来源消息 ID 反查为内部 SourceMessage Inbox ID 后落业务表。 - 实现系统生成幂等键，保证重复提交不重复创建记录。 建议范围： - Flyway migration。 - Entity、Mapper、Repository。 - 批次幂等键生成。 - item 幂等键生成。 - 外部 `source_message_id` 存在性校验：通过 `hotel_id + provider + channel + external_message_id` 查找 SourceMessage Inbox。 - 保存 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 原始摘要、任务卡字段、可处理状态和阻塞原因。 - 第一版任务卡字段矩阵由 `reservation-task-card/field-matrix-v20260706.json` 资源和 Provider 提供，避免 Controller 直接硬编码。 - 保存 `draft_payload_json`。 - 确认时生成 `confirmed_payload_json`。 - `field_values` 第一版使用矩阵 `field_path` 作为 key，不按 `write_path` 生成 OPERA 参数；后续真实 OPERA 接入时必须在 adapter / 转换层重新组装参数。 - 确认时按 `task_subtype`、展示条件、必填、枚举、日期、数字等矩阵规则做第一版后端校验。 - 审计用户字段修改和确认。 验收标准： - 不可处理任务详情只能查看，不能编辑或确认。 - 可处理任务可以保存草稿。 - 用户确认后任务进入 `READY`。 - OPERA 参数不得从 `ai_payload_json` 读取。 - 用户修改不覆盖 AI 原始 JSON。 - 保存草稿接口：`PUT /api/reservation/tasks/{taskId}/draft`。 - 最终确认接口：`POST /api/reservation/tasks/{taskId}/confirm`。 不做： - 不接真实 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` 生成模拟操作。 - 第一版每个已确认任务固定生成两条 OPERA 模拟操作，后续接真实 OPERA 时再按任务类型扩展。 - 每次执行或重试新增 attempt。 - 模拟操作失败时只将该 `operation` 标记为 `FAILED`，任务不进入 `FAILED`，避免按队列规则误判为已结束并跳过失败 OPERA 操作。 - 全部必要操作成功后任务进入 `COMPLETED`。 - 第一版只保存模拟请求/响应摘要，不做 New Booking 业务号回填；订单表已预留 `business_key_source`、`business_key_backfilled_at` 等字段，后续真实 OPERA 或明确模拟返回结构后再写入。 验收标准： - 未确认任务不能执行 OPERA 模拟。 - 不可处理任务不能执行 OPERA 模拟。 - 失败操作不能跳过。 - 用户不能强制完成任务。 - 重试不覆盖历史 attempt。 - 执行接口：`POST /api/reservation/tasks/{taskId}/opera-operations/{operationId}/execute`。 - 重试接口：`POST /api/reservation/tasks/{taskId}/opera-operations/{operationId}/retry`。 - 审计列表接口：`GET /api/reservation/tasks/{taskId}/audits`。 不做： - 不接真实 OPERA 接口。 - 不写死真实 OPERA 返回字段路径。 - 不做普通任务切换订单。 - 不做 SuperAgent 查询上下文接口。 - 不接用户身份权限，审计 actor 第一版仍使用本地占位。 ## 11. Checkpoint 8：审计、查询和收口 名称：`m002-cp08-audit-query-hardening` 目标： - 补齐审计查询、列表筛选、安全收口和回归测试。 建议范围： - 订单任务审计查询。 - 任务列表基础筛选。 - 订单详情下任务时间线。 - 前端 P0 任务列表 / 工作台接口：`GET /api/reservation/tasks`。 - 前端 P0 订单详情与任务时间线接口：`GET /api/reservation/orders/{orderId}`。 - 安全日志检查。 - 关键接口集成测试。 验收标准： - 能追溯 AI 接收、任务创建、订单挂靠、用户修改、确认、迁移、OPERA 模拟和重试。 - 前端可通过 `GET /api/reservation/tasks` 获取任务摘要、订单展示键、来源消息主题和实时可处理状态。 - 前端可通过 `GET /api/reservation/orders/{orderId}` 获取订单摘要和同订单任务时间线。 - 列表不返回完整 AI payload、邮件正文、附件 URL 或 Secret。 - 所有关键路径有测试覆盖。 - `./mvnw test` 通过，或明确说明环境问题。 当前实现记录： - 已实现 `GET /api/reservation/tasks` 第一版，支持酒店、订单、任务类型、任务状态、任务 subtype、队列参与、关键词和分页筛选。 - 已实现 `GET /api/reservation/orders/{orderId}` 第一版，支持返回订单摘要和任务时间线，`include_tasks=false` 时只返回订单摘要。 - 两个接口均复用同订单队列可处理状态计算，`FAILED` 和 `COMPLETED` 视为结束，不阻塞后续任务。 - 已补齐 `GET /api/reservation/tasks` 来源邮件会话摘要字段：`source_sender_summary`、`source_received_at`、`external_conversation_id`、`conversation_message_count`。 - 已补齐 `GET /api/reservation/orders/{orderId}` 的 `tasks[]` 来源邮件会话摘要字段。 - 已补齐 `GET /api/reservation/tasks/{taskId}` 顶层来源邮件会话字段，并在 `fields[]` 透出 `result_type`、`task_type`、`task_subtype`、`default_value_source`。 - 已实现订单列表接口 `GET /api/reservation/orders`，默认查询全部订单状态，支持酒店、订单状态、Group Code、Confirmation No.、关键词和分页筛选；`open_task_count` 排除 `COMPLETED` 和 `FAILED`。 - 已实现邮件会话详情接口 `GET /api/source-messages/{sourceMessageId}/conversation`，根据 SourceMessage 定位外部会话，返回完整 text/html、附件外链、内联图片、来源摘要和关联订单 / 任务摘要；原文读取审计由后端内部写入。 - Message Notification 独立列表 / 详情、任务卡前端字段白名单独立接口继续后置；第一版分别复用任务列表 / 任务详情和 `fields[]` 元数据。 ## 12. 建议开发节奏 建议一次只做一个 checkpoint。每个 checkpoint 完成后： - 先自查是否符合项目包结构和中文注释规范。 - 运行相关测试。 - 做 code review。 - 再进入下一个 checkpoint。 如果实现过程中遇到以下情况，必须先暂停确认： - 订单状态需要新增第五种。 - 任务状态需要新增新状态。 - OPERA 模拟结果字段需要写死真实路径。 - Excel 字段矩阵需要从代码配置改成数据库配置。 - 某个类不知道应该放在哪个包。 - 需要调整已确认的 SuperAgent 接口契约。