342 lines
14 KiB
Markdown
342 lines
14 KiB
Markdown
# 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.<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[]`，并将外部来源消息 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.、关键词和分页筛选；`keyword` 可匹配订单字段，也可匹配来源消息安全摘要命中的 SourceMessage ID；`open_task_count` 排除 `COMPLETED` 和 `FAILED`。
|
||
- 已实现邮件会话详情接口 `GET /api/source-messages/{sourceMessageId}/conversation`，根据 SourceMessage 定位外部会话，返回完整 text/html、附件外链、内联图片、来源摘要和关联订单 / 任务摘要；原文读取审计由后端内部写入。
|
||
- 已实现 dev/test 受控演示数据 seed 接口 `POST /api/system/reservation/demo-data`，默认关闭，需配置 `reservation.demo-data.enabled=true` 和访问口令；生成真实落库的任务列表、订单列表、订单详情、任务详情和邮件会话详情演示数据。
|
||
- Message Notification 独立列表 / 详情、任务卡前端字段白名单独立接口继续后置；第一版分别复用任务列表 / 任务详情和 `fields[]` 元数据。
|
||
|
||
## 12. 建议开发节奏
|
||
|
||
建议一次只做一个 checkpoint。每个 checkpoint 完成后：
|
||
|
||
- 先自查是否符合项目包结构和中文注释规范。
|
||
- 运行相关测试。
|
||
- 做 code review。
|
||
- 再进入下一个 checkpoint。
|
||
|
||
如果实现过程中遇到以下情况，必须先暂停确认：
|
||
|
||
- 订单状态需要新增第五种。
|
||
- 任务状态需要新增新状态。
|
||
- OPERA 模拟结果字段需要写死真实路径。
|
||
- Excel 字段矩阵需要从代码配置改成数据库配置。
|
||
- 某个类不知道应该放在哪个包。
|
||
- 需要调整已确认的 SuperAgent 接口契约。
|