[ADP-703] 日期時間和時間欄位慣例

指導原則

日期和時間欄位應該(SHOULD)使用反映資料類型的後綴：
- At 用於表示時間點的日期時間欄位（例如 createdAt、expiredAt）
- Date 用於不含時間的純日期欄位（例如 birthDate、startDate）
- Time 用於時刻或情境式時間欄位（例如 checkoutTime、cutoffTime）
當 At 和 Time 皆可適用時，優先使用 At 表示系統產生的時間點。
其他常見術語（timestamp、day）可以(MAY)在符合領域語言時自然使用。
必須(MUST)使用 RFC 3339 格式來表示日期時間和時間值。

使用類型特定的後綴能清楚地表達資料格式，無需查閱文件。一個好的 API 應該能夠語義化地描述自己。

為什麼不用裸名稱？ 像 created、deleted 或 start 這樣的欄位名稱語義模糊——它們可能是布林值、字串或時間戳記。加上後綴（createdAt、startDate）可以消除這種歧義。
為什麼要區分 At、Date 和 Time？ 不同的後綴傳達預期的格式：At 表示帶有時區的完整 RFC 3339 日期時間，Date 表示純日期值（YYYY-MM-DD），Time 表示時刻或情境式時間概念。birthAt 讀起來不自然；birthDate 更清晰也更符合慣用語。
當 At 和 Time 重疊時： 對於系統產生的生命週期時間點（建立、修改、刪除、過期），優先使用 At。將 Time 保留給「時間」屬於自然領域語言的情境（例如 checkoutTime、arrivalTime）。

關於值的表示，請參見使用 RFC 3339 格式表示日期時間和時間的要求。

RFC3339 格式概覽

參閱原始規範或 RFC3339概覽

日期時間欄位（時間點）——使用 At：

json

{
  "createdAt": "2023-10-12T08:00:00Z",
  "updatedAt": "2023-10-12T09:30:00Z",
  "expiredAt": "2024-01-01T00:00:00Z"
}

純日期欄位——使用 Date：

json

{
  "birthDate": "1990-05-15",
  "startDate": "2024-01-01",
  "dueDate": "2024-03-31"
}

情境式時間欄位——使用 Time：

json

{
  "checkoutTime": "2023-10-12T12:00:00Z",
  "arrivalTime": "2023-10-12T14:30:00Z",
  "cutoffTime": "17:00:00"
}

錯誤做法——不帶後綴的裸名稱語義模糊：

json

{
  "start": "2023-10-12T08:00:00Z",
  "end": "2023-10-12T10:00:00Z",
  "created": "2023-10-12T10:00:00Z"
}