# skillhub 后端日期时间治理计划

## 1. 当前结论

当前主系统已经基本完成 UTC 语义收口：

- 核心业务时间字段大多已迁到 `Instant`
- 核心事件时间列大多已迁到 `TIMESTAMPTZ`
- 服务层“当前时间”大多已统一走注入 `Clock`
- 普通 API 和后台 DTO 的绝对时间已基本统一输出 UTC ISO-8601

系统当前保留的已经不是大范围混用，而是少量兼容尾项。剩余风险主要集中在：

- 个别旧接口仍允许无时区字符串输入
- 新增代码如果重新引入 `LocalDateTime.now()`，可能把系统带回默认时区依赖
- 缺少跨时区自动化回归时，仍可能遗漏边界问题

## 2. 目标

治理目标不是“所有地方都只用一种类型”，而是统一时间语义：

- 绝对时间点：统一使用 UTC 语义，Java 使用 `Instant`
- 面向业务输入的本地时间：只有在需求明确要求“本地日历时间”时才允许保留 `LocalDateTime`
- 数据库存储绝对时间点时，统一使用 `TIMESTAMPTZ`
- 对外 API 返回绝对时间点时，统一输出 ISO-8601 UTC 字符串，例如 `2026-03-18T06:30:00Z`
- 不再把没有时区语义的 `LocalDateTime` 继续向领域层传播

这里要明确区分：

- i18n 解决的是语言、文案、本地化展示
- 时间统一到 UTC 解决的是跨时区一致性

## 3. 目标模型

建议把后端时间字段分成三类管理：

### 3.1 系统事件时间

适用字段：

- `createdAt`
- `updatedAt`
- `publishedAt`
- `submittedAt`
- `reviewedAt`
- `hiddenAt`
- `yankedAt`
- `lastUsedAt`
- `revokedAt`
- `readAt`
- `handledAt`
- `tokenExpiresAt`

约束：

- Java 类型统一为 `Instant`
- 数据库列统一为 `TIMESTAMPTZ`
- 读写都按 UTC 绝对时间处理

进度登记：

- `audit_log.created_at` 已通过 V42 迁移到 `TIMESTAMPTZ`，详见 `docs/16-backend-time-inventory.md` §3.1

### 3.2 业务输入时间

适用场景：

- 用户手工输入一个“到某天某时截止”的字段
- 规则明确绑定某个业务时区，而不是系统时区

约束：

- 如果该时间代表真实绝对时刻，入口就应要求带时区或明确时区来源，然后在服务层立刻转换为 `Instant`
- 不允许把用户输入的裸 `yyyy-MM-ddTHH:mm:ss` 长期保存在核心领域模型中

### 3.3 纯日期字段

适用场景：

- 生日
- 账期
- 结算日
- 自然日统计

约束：

- 使用 `LocalDate`
- 不参与 UTC/时区转换

## 4. 现状问题

### 4.1 历史问题已基本清理

此前系统的主要问题包括：

- 领域层大量使用 `LocalDateTime`
- 服务层散落 `LocalDateTime.now()`
- 数据库 DDL 大量使用 `TIMESTAMP`
- 兼容层存在隐式 UTC 假设和冲突解释

当前这些问题在主链代码中已基本完成治理，保留它们主要是为了说明为什么迁移顺序必须先做基础设施，再做模型与数据库。

### 4.2 当前仍存在的实际问题

- `ApiTokenService` 仍兼容裸时间字符串输入
- 尚未建立静态约束来阻止未来重新引入 `LocalDateTime.now()`
- 尚未形成系统性的跨时区回归基线

## 5. 治理原则

- 先统一新增代码，再迁移存量代码
- 先统一领域模型，再迁移数据库，再收口 API
- 所有“当前时间”获取统一从 `Clock` 注入，禁止继续散落 `now()`
- 迁移期间优先保证 API 兼容，避免前端和 CLI 同时破坏
- 对外只暴露明确语义的时间格式，不暴露“无时区但又默认是 UTC”的灰色状态

## 6. 分阶段计划

### Phase 0：基线审计

产出：

- 全量时间字段清单
- `LocalDateTime` / `Instant` / `LocalDate` 使用清单
- `TIMESTAMP` / `TIMESTAMPTZ` 列清单
- API 请求与响应中的时间字段清单
- 兼容层中所有 epoch 转换点清单

当前状态：

- 已完成初版盘点
- 已同步到当前代码真实进展

### Phase 1：统一规范与基础设施

执行内容：

- 新增全局 UTC `Clock`
- 配置 Hibernate JDBC 时区为 UTC
- 配置 Jackson UTC 输出
- 建立“绝对时间用 `Instant`”规范

当前状态：

- 已完成

### Phase 2：代码层迁移到 `Instant`

执行内容：

- 实体字段改为 `Instant`
- `LocalDateTime.now()` 改为 `Instant.now(clock)`
- 比较逻辑统一为 `Instant`
- DTO 与服务同步迁移

当前状态：

- 主链已基本完成
- 生产代码中仅剩极少数兼容解析代码保留 `LocalDateTime`

### Phase 3：数据库迁移到 `TIMESTAMPTZ`

执行内容：

- 为核心表新增 Flyway migration
- 明确历史 `TIMESTAMP` 数据按 UTC 解释

当前状态：

- 主链核心事件时间列已基本完成
- 已落地 migration `V13` 到 `V23`

### Phase 4：API 契约收口

执行内容：

- 普通 JSON API 中所有绝对时间字段统一输出 UTC 字符串
- 禁止接口返回裸 `LocalDateTime.toString()`
- 逐步淘汰无时区输入

当前状态：

- 普通 API 与后台 DTO 已基本完成 UTC 输出收口
- 剩余兼容重点是旧接口对裸时间字符串输入的处理策略

### Phase 5：清理与强约束

执行内容：

- 清理遗留兼容时区假设
- 增加 ArchUnit 或静态扫描规则
- 增加跨时区测试，例如 `UTC` 与 `Asia/Shanghai`

当前状态：

- 尚未完成
- 这是下一阶段最有价值的工作

## 7. 重点技术决策

### 7.1 为什么用 `Clock` 而不是只用 `Instant.now()`

- `Instant` 解决“时间如何表达”
- `Clock` 解决“当前时间从哪里来”
- 推荐组合是 `Instant.now(clock)`

这使服务层可测试、可固定时间、可避免机器本地时区干扰。

### 7.2 是否统一引入 `OffsetDateTime`

本项目更适合以 `Instant` 作为核心绝对时间类型，原因是：

- 多数字段表达的是事件发生时刻
- 业务侧通常不需要保留原始 offset
- `Instant` 更能防止“看起来像本地时间”的误解

只有在必须保留调用方原始 offset 的场景下，才考虑 `OffsetDateTime`。

### 7.3 `expiresAt` 这类用户输入字段怎么处理

长期目标：

- API 约定输入为 RFC 3339 / ISO-8601 带时区时间
- 服务层解析后立即转换为 `Instant`

短期兼容：

- 旧接口若仍接受裸字符串，应在 controller 或 service 边界集中兜底
- 必须明确记录这是兼容逻辑，而不是长期契约

## 8. 风险与应对

| 风险 | 应对 |
|------|------|
| 历史 `TIMESTAMP` 数据真实语义不一致 | 先做抽样和数据画像，必要时分批迁移 |
| 前端或 CLI 已依赖不带时区的旧格式 | 保留短期兼容解析，同时明确废弃计划 |
| 新代码继续引入 `LocalDateTime.now()` | 加静态扫描和 review 规则阻断 |
| 缺少跨时区回归导致边界问题漏检 | 增加 `UTC` / `Asia/Shanghai` 双时区测试矩阵 |

## 9. 推荐后续顺序

1. 为 `LocalDateTime.now()` 和实体层 `LocalDateTime` 增加静态约束
2. 增加跨时区回归测试
3. 梳理并逐步淘汰裸时间字符串输入兼容
4. 对生产历史数据做一次抽样校验，确认所有 `TIMESTAMPTZ` 迁移都符合 UTC 解释假设
