FR-121 · 需求索引 · 本頁由 build 掃資料夾生成

FR-121 全庫時間欄位改帶時區(timestamptz)

狀態:✅ 已出貨 1.21.0(2026-09-28) 文件 1 份

FR-121 一頁看完

§1

🔴 先看哪一份

你想知道 看這份 這份的性質
升級後使用者會感覺到什麼、DB 動了哪幾支 migration v1.21.0 release note §2.6、§4 定版
為什麼要改、怎麼切四張卡、顯示時區的原則 設計 design.md 設計決策,定稿凍結
每張卡做了什麼、怎麼驗 Notion 母卡 CM-2253 與六張子卡 歷史紀錄
§2

結論

  1. 資料庫的時間一律存帶時區的 UTC:全庫 200 餘個時間欄位(public、compliance、survey、oscal 四區,以及兩張按月分割的操作日誌表)都改成帶時區的欄位,不再有「猜這個時間是哪個時區」的欄位。
  2. API 回傳的時間一律帶時區偏移(例如 +08:00),後端寫入一律用帶時區的 UTC 時間。
  3. 畫面顯示這版固定台北時間:前端所有顯示時間的地方收成同一支函式(src/utils/dateTime.js 的 formatDateTime/formatDate),照 API 字串自帶的偏移顯示、不看瀏覽器時區;純日期欄位不做任何時區轉換。之後做使用者個人時區設定時,只改這一支函式與後端的顯示時區來源。
  4. 既有資料升級後時間不變:每個欄位依它實際的寫入方式(台北或 UTC)逐欄轉換;判斷寫入時區以安裝版真機為準,不以開發庫為準。
  5. 守衛測試擋回歸:test/test_no_naive_timestamp_columns.py 斷言全庫沒有不帶時區的時間欄位,例外清單為空。
§3

📊 總進度

卡 做什麼 狀態
CM-2254 public 主線與套件表改帶時區 ✅
CM-2255 compliance 表改帶時區,「我的任務」view 隨之重建 ✅
CM-2256 survey+oscal 表改帶時區 ✅
CM-2257 寫入端改帶時區的 UTC、API 回傳帶偏移、守衛測試 ✅
CM-2258 前端時間顯示收成單一格式化函式 ✅
CM-2259 操作日誌兩張分割表重建(按台北月初分區),守衛例外清空 ✅

隨 1.21.0 出貨(2026-09-28,190/188 STG/189 POC),出貨基線已含全部結構異動。

§4

需求討論紀錄

  • 2026-09-27:190 測試機總測發現畫面時間多 8 小時。決策者裁「資料庫應統一存 UTC」,並裁這一版就修、進 b4。
  • 2026-09-27:決策者補裁顯示原則——資料庫存 UTC、畫面依使用者所在地顯示;這版先固定台北,之後做個人時區設定。業界做法是前端依使用者時區轉換、後端回 UTC。
  • 2026-09-27:針對單一畫面的過渡修法作廢,時間問題全由本 FR 解。

沿革見 FR-114 的 LOG 與 git log。

§5

文件

以下全部由 build 掃資料夾產生,新增檔案重 build 即自動出現。標題連結指向渲染後的 HTML,md 連向源檔。

設計

文件 類型 標題 最後更新
design / md 設計 FR-121 全庫無時區時間欄位改 timestamptz(資料庫統一存 UTC) 2026-09-27

其他檔案:cards-made-5.json、cards-made-6.json、cards-made.json、cards-spec-5.json、cards-spec-6.json、cards-spec.json

§6

Notion 卡

卡片內容(決策紀錄、驗收條件)以 Notion 為準,本頁只記座標。

關係 卡號 標題 狀態
母案 CM-2253 全庫無時區時間欄位改 timestamptz,資料庫統一存 UTC —
子卡 CM-2254 public schema 改 timestamptz Done
子卡 CM-2255 compliance schema 改 timestamptz Done
子卡 CM-2256 survey+oscal schema 改 timestamptz Done
子卡 CM-2257 寫入端改 aware UTC、API 帶偏移、守衛 Done
子卡 CM-2258 前端時間顯示收成單一函式 Done
子卡 CM-2259 日誌分割表重建 Done
§7

關聯

相關需求: