统一系统时间输出并优化任务列表查询
This commit is contained in:
@@ -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. 后端代码注释规范
|
||||
|
||||
@@ -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 长整型精度问题;如果当前接口仍返回数字,前端不要自行做数学运算。
|
||||
- 接口字段发生变化前,需要先更新本目录沟通文档或对应需求文档。
|
||||
|
||||
@@ -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 历史。
|
||||
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user