整理项目文档索引和规范说明
This commit is contained in:
andy
@@ -11,9 +11,13 @@
|
||||
- 后端基础结构、ID、审计字段、分页和 Mapper 规范参考 `docs/import/reusable/backend-base-structure-pagination-guidelines.md`。
|
||||
- Java 代码规范参考 `docs/import/reusable/alibaba-java-coding-guidelines-summary.md`。
|
||||
- SuperAgent 与 AgentBus 可移植集成经验参考 `docs/import/reusable/integrations/superagent-agentbus-portable-integration-guide.md`。
|
||||
- 当前项目专属文档总索引位于 `docs/project/README.md`。
|
||||
- 当前项目专属后端规范位于 `docs/project/backend-development-guidelines.md`。
|
||||
- 当前项目时间设计说明位于 `docs/project/backend-time-design.md`。
|
||||
- 当前项目专属前端规范位于 `docs/project/frontend-development-guidelines.md`。
|
||||
- 当前项目前后端协作入口位于 `docs/project/frontend-backend/README.md`。
|
||||
- 当前项目 SuperAgent 与 AgentBus 接入记录位于 `docs/project/integrations/superagent-agentbus-project-integration-guide.md`。
|
||||
- 当前项目 SuperAgent HTTP 对外接口总契约位于 `docs/project/integrations/superagent-api-contract.md`。
|
||||
- 当前项目 SuperAgent MCP 资料包位于 `docs/project/integrations/superagent-mcp/README.md`。
|
||||
|
||||
如本文件、`docs/project` 与 `docs/import/reusable` 中的通用规范冲突，以本文件和 `docs/project` 的当前项目补充为准。
|
||||
@@ -97,6 +101,8 @@
|
||||
- 集合、空值、字符串、时间、金额和 `BigDecimal` 使用安全写法。
|
||||
- 后端业务时间点统一按 UTC 处理：数据库 `LocalDateTime` 默认表示 UTC，API 返回时间点字段必须使用带 `Z` 的 ISO 8601 UTC 时间；新增响应 DTO 优先使用 `OffsetDateTime`，从数据库快照输出时使用 `UtcTimeFormatter` 统一转换。
|
||||
- 入住日期、离店日期、酒店营业日等酒店本地业务日期不得和 UTC 时间点混用，应使用 `LocalDate` 或明确酒店时区语义的字段。
|
||||
- 新增 MySQL 表必须显式使用 `ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin COMMENT='...'`；字符串默认按大小写敏感保存和比较，避免外部 opaque id、哈希、Token、状态码或业务代码因默认不区分大小写而误判。
|
||||
- 如某个业务查询确实需要大小写不敏感，应在查询层、搜索列或专门索引中明确实现，并在 migration 和文档中说明原因，不能依赖数据库默认 collation。
|
||||
- 异常不吞掉，日志有上下文但不输出 Secret 或个人敏感信息。
|
||||
- 写操作考虑幂等、并发版本、事务边界、审计和失败恢复。
|
||||
- 复杂业务规则、外部字段映射、脱敏和幂等逻辑必须有必要中文注释。
|
||||
|
||||
@@ -15,7 +15,7 @@ mcp-server/
|
||||
SuperAgent MCP 方案入口指针。当前不单独部署 MCP 服务，运行时代码内嵌在 `server/`，对外资料包位于 `docs/project/integrations/superagent-mcp/`。
|
||||
|
||||
docs/
|
||||
项目文档、可复用规范、当前项目需求和外部系统接入记录。
|
||||
项目文档、可复用规范、当前项目需求和外部系统接入记录。当前项目文档总索引见 `docs/project/README.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 设计规范
|
||||
|
||||
@@ -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`。
|
||||
|
||||
@@ -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 时间，页面再按酒店或用户时区展示。
|
||||
|
||||
@@ -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 时间点混用。
|
||||
|
||||
170
docs/project/backend-time-design.md
Normal file
170
docs/project/backend-time-design.md
Normal file
@@ -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 语义。
|
||||
@@ -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. 当前已明确后置事项
|
||||
|
||||
|
||||
@@ -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. 文档索引
|
||||
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# M002 SuperAgent 查询上下文接口最小字段定义
|
||||
|
||||
> 文档状态：阶段记录。本文记录 SuperAgent 查询上下文接口 1、2 的最小字段落地过程。
|
||||
> 当前对外接口总契约以 `../integrations/superagent-api-contract.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)` | 创建和更新时间 |
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# M002 Order Task Workflow 订单任务主流程 V1
|
||||
|
||||
> 文档状态：历史参考。当前 M002 订单任务主流程已由
|
||||
> `M002-order-task-workflow-v2.md` 承接；后续开发、接口和测试优先以 V2 为准。
|
||||
> 本文只用于理解早期流程讨论和边界来源。
|
||||
|
||||
## 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# M002 SuperAgent Task Result API Contract
|
||||
|
||||
> 文档状态：阶段记录。本文记录 M002 阶段 SuperAgent 提交 AI 任务结果的入站接口设计。
|
||||
> 当前对外接口总契约以 `../integrations/superagent-api-contract.md` 为准；
|
||||
> 如字段、错误码、鉴权或请求范围出现重复描述，以总契约和当前代码实现为准。
|
||||
|
||||
## 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
|
||||
Reference in New Issue
Block a user