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

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 语义。