统一系统时间输出并优化任务列表查询

This commit is contained in:
andy
2026-07-08 15:15:42 +08:00
parent 936a5921b0
commit 8a196f14ed
20 changed files with 308 additions and 79 deletions

View File

@@ -209,7 +209,8 @@ groupCode
- SQL 文件应使用中文行注释划分表、索引、约束等主要结构。
- 注释必须说明业务含义、来源或代码值范围。
- 禁止使用“字段1”“备用字段”等模糊注释。
- 业务时间以 UTC 写入数据库API 层负责返回 ISO 8601
- 业务时间以 UTC 写入数据库API 层负责返回`Z` 的 ISO 8601 UTC 时间,例如 `2026-07-08T03:00:00Z`
- 酒店本地业务日期,例如入住日期、离店日期、营业日,优先使用 `LocalDate` 或明确酒店时区语义的字段,不和 UTC 时间点混用。
- JSON 字段只用于扩展元数据,不替代需要查询、约束或索引的正式列。
## 11. 后端代码注释规范

View File

@@ -9,6 +9,8 @@
- 前端只调用本项目后端接口,不直接调用 SuperAgent、AgentBus、OPERA、OHIP 或数据库。
- API 调用应统一放在前端 `src/services`,页面组件不要直接拼接后端 URL。
- 业务判断必须使用后端返回的稳定 code不使用中文或英文展示文案做判断。
- 后端返回的时间点字段统一是带 `Z` 的 ISO 8601 UTC 时间,例如 `created_at``updated_at``received_at``last_updated_at`;前端展示时再按用户或酒店时区格式化。
- 入住日期、离店日期、酒店营业日属于酒店本地业务日期,不要按 UTC 时间点自动换算日期。
- 前端不得保存或传递后端 Secret、replay access key、Provider API Key、Oracle 凭证、AgentBus Token。
- 后端数据库 ID 未来应尽量以字符串形式给前端,避免 JavaScript 长整型精度问题;如果当前接口仍返回数字,前端不要自行做数学运算。
- 接口字段发生变化前,需要先更新本目录沟通文档或对应需求文档。

View File

@@ -88,7 +88,7 @@
| 变量 | 是否 Secret | 上线注意事项 |
| --- | --- | --- |
| `SUPERAGENT_TASK_RESULT_HMAC_SECRET` | 是 | SuperAgent 查询接口 1、2 和任务结果通知接口共用的 HMAC secret。生产不能为空只能通过 Secret 注入。 |
| `SUPERAGENT_TASK_RESULT_CLOCK_SKEW_SECONDS` | 否 | 请求时间允许偏移,默认 `300` 秒。上线前确认双方机器时间已同步。 |
| `SUPERAGENT_TASK_RESULT_CLOCK_SKEW_SECONDS` | 否 | 请求时间允许偏移,默认 `300` 秒。上线前确认本系统、SuperAgent 和 AgentBus 所在机器时间已通过 NTP 同步。 |
| `SUPERAGENT_TASK_RESULT_NONCE_TTL_SECONDS` | 否 | nonce 防重放窗口,默认 `600` 秒。 |
| `SUPERAGENT_TASK_RESULT_MAX_BODY_BYTES` | 否 | SuperAgent 入站请求体最大字节数,默认 `1048576`。 |
@@ -120,7 +120,10 @@
- MySQL 版本满足项目要求,默认使用 MySQL 8.0+。
- migration 在 UAT 或测试库已经跑过。
- 表和字段中文注释能正常创建。
- 数据库时间按 UTC 写入,接口层负责返回 ISO 8601
- 数据库业务时间按 UTC 写入,接口层返回带 `Z` 的 ISO 8601 UTC 时间,例如 `2026-07-08T03:00:00Z`
- MySQL JDBC URL 建议明确 `serverTimezone=UTC`;部署容器和 JVM 也应使用 UTC或至少确认应用代码所有入库时间均通过 UTC 时钟生成。
- AgentBus 邮件来源时间、SuperAgent HMAC timestamp、本系统 `created_at` / `updated_at` / `received_at` 等时间点统一按 UTC 理解;前端展示时再按用户或酒店时区格式化。
- 入住日期、离店日期、酒店营业日属于酒店本地业务日期,不应因为 UTC 换算而自动前后偏移。
- 执行 V4 前,如果目标库已有 M002 试运行数据,必须先检查 ACTIVE 订单业务号重复和同订单任务队列序号重复。
- 执行 V5 / V6 前,如果目标库已有 M002 试运行数据,必须确认任务草稿、确认 payload 和 OPERA 模拟操作表允许从空数据开始补齐;不要手工伪造已确认 payload 或 attempt 历史。

View File

@@ -221,8 +221,8 @@ SuperAgent 不应知道或依赖内部 SourceMessage Inbox ID。任务结果通
"status": "ACTIVE",
"source_message_id": "1900000000000000001",
"created_from_task_id": null,
"created_at": "2026-07-08T01:00:00",
"last_updated_at": "2026-07-08T01:10:00",
"created_at": "2026-07-08T01:00:00Z",
"last_updated_at": "2026-07-08T01:10:00Z",
"arrival_date": null,
"departure_date": null,
"nights": null,

View File

@@ -71,6 +71,12 @@
| `X-TH-Hotel-Request-Id` | 否 | 调用方生成的请求 ID用于日志串联 |
| `X-TH-Hotel-AI-Trace-Id` | 否 | AI 运行链路 ID |
时间约定:
- 请求 Header `X-TH-Hotel-SuperAgent-Timestamp` 必须是带时区的 UTC ISO-8601 时间,例如 `2026-07-08T03:00:00Z`
- 响应中的 `created_at``last_updated_at``occurred_at` 等时间点统一返回带 `Z` 的 ISO-8601 UTC 时间。
- `source_message_id``source_event_index` 第一版仅兼容接收,不参与查询范围过滤;时间统一不依赖这两个字段是否已在本系统落库。
规范签名串:
```text