整理项目文档索引和规范说明

2026-07-10 23:49:49 +08:00
parent 1efa819599
commit 1046e4ef74
13 changed files with 300 additions and 22 deletions
--- a/docs/import/reusable/backend-development-guidelines.md
+++ b/docs/import/reusable/backend-development-guidelines.md
@@ -99,6 +99,21 @@ server/src/main/java/<base_package>
 - 表、字段、索引和约束命名应清晰表达业务含义。
 - 业务表建议包含创建时间、更新时间、创建人、更新人、逻辑删除和版本字段。
 - 需要查询、排序、唯一性或关联的字段必须有明确索引策略。
+- 新项目建表前必须确认数据库字符集和 collation 策略，不能依赖数据库实例默认值。
+- MySQL 项目建议新建表显式使用 `ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin COMMENT='...'`，让字符串默认按大小写敏感保存和比较。
+- 外部 opaque id、第三方消息 ID、哈希、Token、nonce、幂等键、状态码和业务代码必须大小写敏感；否则容易出现 `X` 与 `x` 被误认为同一值的幂等或唯一键问题。
+- 如果业务需要大小写不敏感搜索，应通过查询层归一化、搜索字段、专门索引或搜索引擎实现，并在项目规范和 migration 注释中说明原因，不建议把整库或整表默认改回大小写不敏感。
+- 新建表模板：
+
+```sql
+CREATE TABLE example_table (
+    id BIGINT NOT NULL COMMENT '内部主键 ID',
+    external_id VARCHAR(256) NULL COMMENT '外部系统 ID，按大小写敏感保存和比较',
+    created_at DATETIME(6) NOT NULL COMMENT '记录创建 UTC 时间',
+    PRIMARY KEY (id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin COMMENT='示例业务表';
+```
+
 - 测试数据、真实业务数据和本地样本不得直接提交到仓库。

 ## 7. API 设计规范
--- a/docs/import/reusable/general-development-guidelines.md
+++ b/docs/import/reusable/general-development-guidelines.md
@@ -85,6 +85,7 @@
 - Service 编排业务流程、事务、领域对象、Repository 和外部端口。
 - 外部系统通过 Port / Adapter 隔离，业务层不直接依赖厂商 SDK 或外部 DTO。
 - 数据库变更必须可追踪；已发布 migration 不直接修改。
+- 新项目建表前必须明确数据库字符集和 collation 策略；MySQL 项目默认建议使用 `utf8mb4_bin`，避免外部 ID、Token、哈希、状态码或业务代码因大小写不敏感而误判。
 - 写接口要考虑幂等、并发版本、审计、失败恢复和脱敏。

 Java 后端代码默认参考 Alibaba Java Coding Guidelines。可复用摘要见 `docs/import/reusable/alibaba-java-coding-guidelines-summary.md`。
--- a/docs/project/README.md
+++ b/docs/project/README.md
@@ -4,17 +4,69 @@

 这些文档可以作为后续项目参考，但不应整份复制到新项目。新项目可复用内容应优先沉淀到 `docs/import/reusable/`。

-## 文档清单
+## 文档状态约定

- `backend-development-guidelines.md`：当前项目后端专属规范。
- `frontend-development-guidelines.md`：当前项目前端专属规范。
- `frontend-backend/README.md`：前后端协作入口，记录接口契约来源、字段白名单和当前后置事项。
- `go-live-notes.md`：当前项目上线注意事项，记录上线前检查、环境变量、安全、AgentBus、验证和回滚。
- `requirements/M001-source-message-inbox-prd.md`：M001 邮件来源入口 PRD，记录 AgentBus 邮件 JSON 入库、历史查询、原文读取和媒体引用边界。
- `requirements/M002-order-task-workflow-v1.md`：M002 订单任务主流程 V1，记录 SourceMessage 之后的 SuperAgent 抽取、订单挂靠、任务处理和 OPERA/OHIP 模拟操作边界。
- `requirements/M002-order-task-workflow-v2.md`：M002 订单任务主流程 V2，记录 AI 过渡层、任务卡矩阵、系统主任务类型、临时订单、订单号候选和 OPERA 模拟回填边界。
- `requirements/M002-superagent-task-result-api-contract.md`：M002 SuperAgent 任务结果入站接口契约，记录 HMAC 鉴权、请求响应、幂等和错误码。
- `requirements/M002-backend-data-model-design.md`：M002 后端数据模型设计，记录 AI 过渡层、订单、任务、任务卡、审计和 OPERA 模拟结果表。
- `requirements/M002-backend-checkpoint-plan.md`：M002 后端 checkpoint 计划，记录后端实现拆分、交付物和验收标准。
- `integrations/superagent-agentbus-project-integration-guide.md`：当前项目 SuperAgent 与 AgentBus 验证记录和项目级接入细节。
- `integrations/superagent-api-contract.md`：给 SuperAgent 对接方使用的接口契约，记录查询上下文、对象详情、任务结果通知和统一 HMAC 规则。
+- `当前有效`：后续开发和联调优先按该文档执行。
+- `权威契约`：同类接口或规则出现重复描述时，以该文档为准。
+- `阶段记录`：记录某个 checkpoint 的落地细节，可以辅助理解，但不应覆盖当前有效文档。
+- `历史参考`：保留早期讨论背景；若与当前有效文档冲突，以当前有效文档为准。
+- `草案`：需求或方案尚未完全落地，开发前需要再次确认。
+
+## 核心入口
+
+| 文档 | 状态 | 中文说明 |
+| --- | --- | --- |
+| `../../AGENTS.md` | 当前有效 | 项目协作入口，记录 agent 工作方式、分支、目录、前后端边界、安全和测试要求。 |
+| `../../README.md` | 当前有效 | 项目根说明，记录目录、启动命令、健康检查、Debug EML 和 MCP 基础说明。 |
+| `backend-development-guidelines.md` | 当前有效 | 当前项目后端专属规范。 |
+| `backend-time-design.md` | 当前有效 | 当前项目时间设计说明，记录数据库 UTC、API `Z` 时间、酒店时区展示和本地日期边界。 |
+| `frontend-development-guidelines.md` | 当前有效 | 当前项目前端专属规范。 |
+| `frontend-backend/README.md` | 当前有效 | 前后端协作入口，记录接口契约来源、字段白名单和当前后置事项。 |
+| `go-live-notes.md` | 当前有效 | 当前项目上线注意事项，记录上线前检查、环境变量、安全、AgentBus、验证和回滚。 |
+
+## 需求与方案
+
+| 文档 | 状态 | 中文说明 |
+| --- | --- | --- |
+| `requirements/M001-source-message-inbox-prd.md` | 当前有效 | M001 邮件来源入口 PRD，记录 AgentBus 邮件 JSON 入库、历史查询、原文读取和媒体引用边界。 |
+| `requirements/M002-order-task-workflow-v1.md` | 历史参考 | M002 订单任务主流程 V1，已由 V2 承接，保留用于理解早期流程。 |
+| `requirements/M002-order-task-workflow-v2.md` | 当前有效 | M002 订单任务主流程 V2，记录 AI 过渡层、任务卡矩阵、系统主任务类型、临时订单、订单号候选和 OPERA 模拟回填边界。 |
+| `requirements/M002-superagent-task-result-api-contract.md` | 阶段记录 | M002 SuperAgent 任务结果入站接口契约阶段记录；对外总契约以 `integrations/superagent-api-contract.md` 为准。 |
+| `requirements/M002-ai-query-minimal-fields.md` | 阶段记录 | M002 SuperAgent 查询上下文接口 1、2 最小字段落地记录；对外总契约以 `integrations/superagent-api-contract.md` 为准。 |
+| `requirements/M002-backend-data-model-design.md` | 阶段记录 | M002 后端数据模型设计，记录 AI 过渡层、订单、任务、任务卡、审计和 OPERA 模拟结果表。 |
+| `requirements/M002-backend-checkpoint-plan.md` | 阶段记录 | M002 后端 checkpoint 计划，记录后端实现拆分、交付物和验收标准。 |
+| `requirements/M003-identity-access-hotel-menu-v1.md` | 当前有效 | M003 登录、权限、酒店和动态菜单底座方案。 |
+| `requirements/M004-debug-eml-superagent-upload-v1.md` | 当前有效 | M004 Debug EML 上传 SuperAgent 调试方案。 |
+| `requirements/M005-hotel-context-unification-plan.md` | 当前有效 | M005 酒店上下文统一收口方案。 |
+| `requirements/M006-system-admin-management-console-v1.md` | 草案 | M006 系统管理后台方案，覆盖用户、角色、权限、菜单、酒店和用户酒店授权维护。 |
+
+## 集成契约
+
+| 文档 | 状态 | 中文说明 |
+| --- | --- | --- |
+| `integrations/superagent-api-contract.md` | 权威契约 | 给 SuperAgent 对接方使用的 HTTP 接口总契约，记录查询上下文、对象详情、邮件会话任务、邮件会话正文、任务结果通知和统一 HMAC 规则。 |
+| `integrations/superagent-mcp/README.md` | 当前有效 | SuperAgent MCP 资料包入口；MCP tools 是 HTTP 总契约的 MCP 映射说明，不单独替代总契约。 |
+| `integrations/superagent-agentbus-project-integration-guide.md` | 当前有效 | 当前项目 SuperAgent 与 AgentBus 验证记录和项目级接入细节。 |
+| `../../mcp-server/README.md` | 当前有效 | SuperAgent MCP 方案入口指针；当前不单独部署 MCP 服务，运行时代码内嵌在 `server/`。 |
+
+## 前后端协作
+
+| 文档 | 状态 | 中文说明 |
+| --- | --- | --- |
+| `frontend-backend/backend-to-frontend-notes.md` | 当前有效 | 后端提醒前端的接口、字段、时间、安全和展示注意事项。 |
+| `frontend-backend/frontend-to-backend-api-requests.md` | 当前有效 | 前端提醒后端需要增加或补齐的接口，已区分可用、后置和历史候选路径。 |
+| `frontend-backend/debug-eml-page-integration-guide.md` | 当前有效 | Debug EML 页面前端对接指南。 |
+
+## 执行计划
+
+| 文档 | 状态 | 中文说明 |
+| --- | --- | --- |
+| `../superpowers/plans/2026-07-10-m006-system-admin-v1.md` | 阶段记录 | M006 系统管理后台实现计划，作为执行 checkpoint 参考，不替代需求文档。 |
+
+## 权威来源说明
+
+- SuperAgent 对外 HTTP 接口以 `integrations/superagent-api-contract.md` 为权威来源。
+- SuperAgent MCP 文档以 `integrations/superagent-mcp/` 为对外交付资料包，但字段语义应跟随 HTTP 总契约。
+- M002 V1 只作为历史参考；订单任务主流程以后续开发以 `requirements/M002-order-task-workflow-v2.md` 为准。
+- 前端展示 / 编辑字段以导入的前端字段表为白名单，后端完整校验和 OPERA 映射仍以任务卡完整矩阵和后端规则为准。
+- 时间点语义以 `backend-time-design.md` 为准；数据库时间点按 UTC 理解，API 返回带 `Z` 的 UTC 时间，页面再按酒店或用户时区展示。
--- a/docs/project/backend-development-guidelines.md
+++ b/docs/project/backend-development-guidelines.md
@@ -10,6 +10,8 @@
 模型或 Agent 能力提供方并消费其结构化结果；本项目不开发模型、Prompt 优化平台、Agent
 Runtime、Planner、Memory 或通用工具调用框架。

+当前项目时间存储、接口返回、酒店时区展示和本地业务日期边界统一参考 `docs/project/backend-time-design.md`。
+
 ## 2. 技术栈

 以 `server/pom.xml` 为准，当前后端技术栈如下：
@@ -209,6 +211,22 @@ groupCode
 - SQL 文件应使用中文行注释划分表、索引、约束等主要结构。
 - 注释必须说明业务含义、来源或代码值范围。
 - 禁止使用“字段1”“备用字段”等模糊注释。
+- 新建 MySQL 表必须显式指定存储引擎、字符集和排序规则，默认使用 `ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin COMMENT='...'`。
+- 本项目字符串字段默认大小写敏感，包含用户名、展示名、邮件主题、菜单名称、状态筛选、外部 ID、哈希、Token、nonce、幂等键、业务代码等。这样可以避免 MySQL 默认大小写不敏感 collation 把 `X` 和 `x` 之类的外部 opaque id 误判为同一个值。
+- 已有表通过 `V13__make_existing_string_columns_case_sensitive.sql` 统一转为 `utf8mb4_bin`；后续新增表或新增字符串列不能重新退回默认 `*_ci` collation。
+- 如果某个功能确实需要大小写不敏感搜索，不应改变整表默认 collation，应在查询层使用规范化字段、搜索索引、`LOWER()`/归一化值或专门搜索方案实现，并在需求文档和 migration 注释中写明原因。
+- 新建表推荐模板：
+
+```sql
+CREATE TABLE example_table (
+    id BIGINT NOT NULL COMMENT '内部主键 ID',
+    external_id VARCHAR(256) NULL COMMENT '外部系统 ID，按大小写敏感保存和比较',
+    created_at DATETIME(6) NOT NULL COMMENT '记录创建 UTC 时间',
+    PRIMARY KEY (id),
+    KEY idx_example_external_id (external_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin COMMENT='示例业务表';
+```
+
 - 业务时间点以 UTC 写入数据库，API 层负责返回带 `Z` 的 ISO 8601 UTC 时间，例如 `2026-07-08T03:00:00Z`。
 - 新增 API 响应 DTO 中的时间点字段优先使用 `OffsetDateTime`；从数据库 `LocalDateTime` 快照输出到接口时，应通过 `UtcTimeFormatter` 转换，禁止直接把无时区 `LocalDateTime` 暴露给前端或 SuperAgent。
 - 酒店本地业务日期，例如入住日期、离店日期、营业日，优先使用 `LocalDate` 或明确酒店时区语义的字段，不和 UTC 时间点混用。
--- a/docs/project/backend-time-design.md
+++ b/docs/project/backend-time-design.md
@@ -0,0 +1,170 @@
+# 后端时间设计说明
+
+## 1. 文档定位
+
+本文集中记录本项目的时间存储、接口返回和页面展示规则，避免把数据库里的 UTC 时间误当成酒店当地展示时间。
+
+适用范围：
+
+- 后端数据库时间字段设计。
+- 后端 API 时间字段返回。
+- 前端展示和按日期筛选。
+- AgentBus / SuperAgent 等外部系统时间字段映射。
+
+如本文与具体业务 PRD 冲突，以业务 PRD 的特殊说明为准；没有特殊说明时，统一遵守本文。
+
+## 2. 总体原则
+
+一句话原则：
+
+数据库存 UTC 事实时间，接口返回带 `Z` 的 UTC 时间，页面按酒店或用户时区展示；酒店业务日期不做 UTC 时间点换算。
+
+落地规则：
+
+- 数据库中的时间点字段统一按 UTC 理解。
+- Java Entity 中的 `LocalDateTime` 默认表示 UTC 时间点，不表示服务器本地时间。
+- API 返回时间点字段必须是带 `Z` 的 ISO 8601 UTC 时间，例如 `2026-07-09T05:56:56Z`。
+- 前端展示时间点时，再按用户或酒店时区格式化；当前默认酒店时区是 `Asia/Bangkok`。
+- 入住日期、离店日期、酒店营业日等本地业务日期，不得和 UTC 时间点混用。
+
+## 3. 时间字段分类
+
+| 类型 | 示例字段 | 含义 | 数据库语义 | API 语义 | 页面展示 |
+| --- | --- | --- | --- | --- | --- |
+| 系统审计时间 | `created_at`、`updated_at`、`occurred_at`、`confirmed_at`、`completed_at` | 本系统内部动作发生时间 | UTC 时间点 | 带 `Z` 的 UTC 时间 | 按酒店或用户时区展示 |
+| 外部来源事件时间 | SourceMessage `received_at`、`source_sent_at` | 外部系统提供的邮件接收 / 发送时间 | UTC 时间点 | 带 `Z` 的 UTC 时间 | 按酒店或用户时区展示 |
+| 外部认证时间 | SuperAgent HMAC timestamp | 外部调用签名时间 | UTC 时间点 | ISO 8601 UTC | 不作为业务展示字段 |
+| 酒店本地业务日期 | 入住日期、离店日期、营业日 | 酒店当地日历日期 | `LocalDate` 或明确本地日期语义 | 日期字符串 | 直接按酒店本地日期展示 |
+
+## 4. 数据库存储规则
+
+MySQL 时间点字段当前主要使用 `DATETIME(6)`。
+
+注意：`DATETIME(6)` 本身不带时区。本项目约定，所有表示时间点的 `DATETIME(6)` 都按 UTC 解释。
+
+示例：
+
+```text
+数据库值：2026-07-09 05:56:56
+真实含义：2026-07-09T05:56:56Z
+泰国展示：2026-07-09 12:56:56
+```
+
+后端连接 MySQL 时，JDBC URL 应明确 `serverTimezone=UTC`。部署容器和 JVM 也应优先使用 UTC，或至少保证入库时间都通过 UTC 生成。
+
+## 5. Java 类型规则
+
+后端内部约定：
+
+- Entity / Snapshot 中从数据库读取的 `LocalDateTime` 默认表示 UTC 时间点。
+- API Response 中的时间点字段优先使用 `OffsetDateTime`。
+- 数据库 `LocalDateTime` 输出到 API 时，使用 `UtcTimeFormatter.toUtcOffsetDateTime(...)` 统一补 UTC offset。
+- 当前 UTC 时间统一使用 `LocalDateTime.now(ZoneOffset.UTC)` 或 `OffsetDateTime.now(ZoneOffset.UTC)`。
+- 酒店本地日期使用 `LocalDate`，不要使用 `LocalDateTime` 假装表示日期。
+
+示例：
+
+```java
+OffsetDateTime apiTime = UtcTimeFormatter.toUtcOffsetDateTime(entity.getCreatedAt());
+```
+
+## 6. SourceMessage 邮件时间规则
+
+`platform_source_message_inbox.received_at` 的语义已经调整为邮件来源接收时间：
+
+1. 优先取 AgentBus payload 或 source 中的 `received_at`。
+2. 如果 AgentBus 没有提供或格式无法解析，回退为本系统捕获该消息的 UTC 时间。
+3. `created_at` / `updated_at` 仍表示本系统记录创建 / 更新时间，不随邮件来源时间变化。
+4. `source_sent_at` 表示来源系统提供的邮件发送时间，缺失时为空。
+
+因此：
+
+- `received_at` 用于邮件会话排序和业务展示。
+- `created_at` / `updated_at` 用于系统审计和排查链路处理时间。
+- 不应把 `received_at` 和 `created_at` 强行要求相等。
+
+## 7. API 返回规则
+
+后端返回给前端的时间点字段统一是 UTC 字符串：
+
+```json
+{
+  "source_received_at": "2026-07-09T05:56:56Z",
+  "created_at": "2026-07-09T05:57:00Z"
+}
+```
+
+接口字段名保持业务语义：
+
+- `received_at` / `source_received_at`：邮件来源接收时间，UTC。
+- `source_sent_at`：邮件来源发送时间，UTC。
+- `created_at`：本系统记录创建时间，UTC。
+- `updated_at`：本系统记录更新时间，UTC。
+
+前端不能把这些带 `Z` 的时间直接当泰国本地时间显示。
+
+## 8. 页面展示规则
+
+页面展示时间点时，应按酒店或用户时区格式化。当前酒店默认时区是 `Asia/Bangkok`。
+
+示例：
+
+```text
+API 返回：2026-07-09T05:56:56Z
+泰国时间：2026-07-09 12:56:56
+```
+
+前端可以使用 `Intl.DateTimeFormat`：
+
+```ts
+new Intl.DateTimeFormat("zh-CN", {
+  timeZone: "Asia/Bangkok",
+  dateStyle: "short",
+  timeStyle: "medium",
+}).format(new Date("2026-07-09T05:56:56Z"));
+```
+
+业务人员最终应看页面展示时间；数据库只用于排查 UTC 事实时间。
+
+## 9. 按酒店本地日期筛选
+
+如果用户按酒店本地日期筛选，例如查询泰国当地 `2026-07-09` 的邮件，后端查询数据库前必须把本地日期范围转换成 UTC 范围。
+
+泰国时区示例：
+
+```text
+Asia/Bangkok 2026-07-09 00:00:00
+-> UTC 2026-07-08 17:00:00
+
+Asia/Bangkok 2026-07-10 00:00:00
+-> UTC 2026-07-09 17:00:00
+```
+
+查询建议使用左闭右开：
+
+```sql
+received_at >= '2026-07-08 17:00:00'
+AND received_at < '2026-07-09 17:00:00'
+```
+
+不要直接用数据库 UTC 日期的 `2026-07-09 00:00:00 ~ 23:59:59` 当作泰国当地一天。
+
+## 10. 排查规则
+
+排查时间问题时，先确认要看的是什么：
+
+| 场景 | 应看字段 | 判断方式 |
+| --- | --- | --- |
+| 业务人员看到邮件接收时间 | API `received_at` 或页面展示值 | API 是 UTC，页面转酒店时区 |
+| 判断 AgentBus 是否传了邮件接收时间 | 原始 payload `received_at` | 应是 ISO 8601 UTC，例如 `2026-07-09T05:56:56Z` |
+| 判断本系统什么时候写入记录 | `created_at` | UTC 系统审计时间 |
+| 判断链路处理延迟 | `created_at - received_at` | 两者都按 UTC 理解后再比较 |
+| 判断入住 / 离店日期 | 业务日期字段 | 不做 UTC 时间点换算 |
+
+## 11. 禁止事项
+
+- 不要把数据库 `DATETIME(6)` 直接当酒店当地时间展示。
+- 不要在数据库里同时保存一份 UTC 时间和一份泰国展示时间。
+- 不要把入住日期、离店日期、营业日用 UTC 时间点自动前后偏移。
+- 不要在前端用中文或英文展示文案判断时间语义，应按接口字段名和文档约定处理。
+- 不要在日志里输出包含客户敏感信息的完整邮件正文或附件 URL；时间字段可以输出，但要带上下文说明其 UTC 语义。
--- a/docs/project/frontend-backend/README.md
+++ b/docs/project/frontend-backend/README.md
@@ -13,6 +13,7 @@
 | `backend-to-frontend-notes.md` | 后端提醒前端的注意事项，包含项目开发、业务规则、接口使用和安全边界。 |
 | `frontend-to-backend-api-requests.md` | 前端提醒后端需要增加或补齐的接口，包含建议入参和返参草案。 |
 | `debug-eml-page-integration-guide.md` | Debug EML 页面前端对接指南，包含页面结构、上传接口、响应展示、错误处理和安全注意事项。 |
+| `../backend-time-design.md` | 时间设计说明，包含数据库 UTC、API `Z` 时间、酒店时区展示和本地日期筛选规则。 |

 ## 3. 当前字段来源分工

@@ -30,13 +31,15 @@

 ## 4. 当前接口契约来源

-| 契约 | 文档 |
-| --- | --- |
-| SuperAgent 任务结果入站接口 | `docs/project/requirements/M002-superagent-task-result-api-contract.md` |
-| SuperAgent 查询上下文接口 1、2 | `docs/project/requirements/M002-ai-query-minimal-fields.md` |
-| SuperAgent 对接总契约 | `docs/project/integrations/superagent-api-contract.md` |
-| 订单任务主流程 | `docs/project/requirements/M002-order-task-workflow-v2.md` |
-| 后端 checkpoint | `docs/project/requirements/M002-backend-checkpoint-plan.md` |
+| 契约 | 当前文档 | 中文说明 |
+| --- | --- | --- |
+| SuperAgent HTTP 对外总契约 | `docs/project/integrations/superagent-api-contract.md` | 权威契约，包含查询上下文、对象详情、邮件会话任务、邮件会话正文、任务结果通知和统一 HMAC 规则。 |
+| SuperAgent MCP tools | `docs/project/integrations/superagent-mcp/README.md` | MCP 对外交付资料包，tools 字段语义应跟随 SuperAgent HTTP 对外总契约。 |
+| SuperAgent 任务结果入站接口 | `docs/project/requirements/M002-superagent-task-result-api-contract.md` | 阶段记录，用于理解 M002 接收 AI 结果的落地细节；如与总契约冲突，以总契约为准。 |
+| SuperAgent 查询上下文接口 1、2 | `docs/project/requirements/M002-ai-query-minimal-fields.md` | 阶段记录，用于理解接口 1、2 的最小字段实现；如与总契约冲突，以总契约为准。 |
+| 订单任务主流程 | `docs/project/requirements/M002-order-task-workflow-v2.md` | 当前有效需求，M002 V1 只作为历史参考。 |
+| 后端 checkpoint | `docs/project/requirements/M002-backend-checkpoint-plan.md` | 阶段记录，用于理解后端拆分和验收。 |
+| 前端可用接口与待补接口 | `docs/project/frontend-backend/frontend-to-backend-api-requests.md` | 前后端协作清单，已区分可用、后置和历史候选路径，不替代后端权威契约。 |

 ## 5. 当前已明确后置事项

--- a/docs/project/integrations/superagent-mcp/README.md
+++ b/docs/project/integrations/superagent-mcp/README.md
@@ -15,6 +15,7 @@ server/src/main/java/cn/nianxx/thhotel/integrations/mcp/superagent/
 - 当前 MCP endpoint 内嵌在现有 Spring Boot 后端中。
 - 不需要额外部署独立 MCP 服务。
 - 文档可以按本目录整体交付给对接方，但 Secret 必须通过安全通道单独交付。
+- 本目录是 `../superagent-api-contract.md` 的 MCP 映射资料包；字段语义、错误码和安全边界如有重复，以 HTTP 对外总契约为准。

 ## 2. 文档索引

--- a/docs/project/requirements/M002-ai-query-minimal-fields.md
+++ b/docs/project/requirements/M002-ai-query-minimal-fields.md
@@ -1,5 +1,9 @@
 # M002 SuperAgent 查询上下文接口最小字段定义

+> 文档状态：阶段记录。本文记录 SuperAgent 查询上下文接口 1、2 的最小字段落地过程。
+> 当前对外接口总契约以 `../integrations/superagent-api-contract.md` 为准；
+> 如字段、错误码、鉴权或请求范围出现重复描述，以总契约和当前代码实现为准。
+
 ## 文档信息

 | 项目 | 内容 |
--- a/docs/project/requirements/M002-backend-data-model-design.md
+++ b/docs/project/requirements/M002-backend-data-model-design.md
@@ -108,7 +108,7 @@
 | `batch_idempotency_key` | `CHAR(64)` | 系统生成的批次幂等键 |
 | `client_id` | `VARCHAR(128)` | SuperAgent 调用方 ID |
 | `request_id` | `VARCHAR(128)` | 调用方请求 ID，可为空 |
-| `received_at` | `DATETIME(6)` | 接收时间 |
+| `received_at` | `DATETIME(6)` | AI 结果请求接收时间，按 UTC 理解 |
 | `item_count` | `INT` | AI item 数量 |
 | `extraction_warnings_json` | `LONGTEXT` | 抽取警告 JSON |
 | `created_at` / `updated_at` | `DATETIME(6)` | 创建和更新时间 |
--- a/docs/project/requirements/M002-order-task-workflow-v1.md
+++ b/docs/project/requirements/M002-order-task-workflow-v1.md
@@ -1,5 +1,9 @@
 # M002 Order Task Workflow 订单任务主流程 V1

+> 文档状态：历史参考。当前 M002 订单任务主流程已由
+> `M002-order-task-workflow-v2.md` 承接；后续开发、接口和测试优先以 V2 为准。
+> 本文只用于理解早期流程讨论和边界来源。
+
 ## 文档信息

 | 项目 | 内容 |
--- a/docs/project/requirements/M002-superagent-task-result-api-contract.md
+++ b/docs/project/requirements/M002-superagent-task-result-api-contract.md
@@ -1,5 +1,9 @@
 # M002 SuperAgent Task Result API Contract

+> 文档状态：阶段记录。本文记录 M002 阶段 SuperAgent 提交 AI 任务结果的入站接口设计。
+> 当前对外接口总契约以 `../integrations/superagent-api-contract.md` 为准；
+> 如字段、错误码、鉴权或请求范围出现重复描述，以总契约和当前代码实现为准。
+
 ## 文档信息

 | 项目 | 内容 |