Unix時間とタイムゾーン

🌍 UTCとローカル時間の役割分担

保存はUTC、表示は利用者のタイムゾーンという棲み分けが基本です。

押さえるポイント

• ✅ Unix時間は常にUTC基準。ローカル時刻は「表示時の変換」で決まる。
• ✅ サーバー側の内部処理・DB保存はUTC統一が安全（時差やDSTに左右されない）。
• ✅ UIやメール、レポートなど利用者向け出力で初めてローカルTZを適用する。

🗄️ 保存・API・ログの方針

どこでタイムゾーンを決め、どう伝えるかを決めておくと混乱が減ります。

DB保存

• 💾 整数のUnix秒/ミリ秒でUTC保存するか、`timestamp with time zone` をUTC固定で保存する。
• 💾 `timestamp without time zone` にローカル時刻を入れると後でTZがわからなくなりやすい。

API/メッセージ

• 🔗 ISO8601はオフセット付きで返す（例: `2024-02-29T12:00:00+09:00`）。
• 🔗 整数のUnix時間を返す場合は、単位（秒/ミリ秒）を明記し、UTC基準であることを仕様書に書く。

ログ/監視

• 📜 解析しやすいようUTCで統一するか、UTCとローカルの両方を出す。
• 📜 ログフォーマットにタイムゾーン（`Z` か `+09:00`）を含める。

🔧 変換の具体例

コマンドやコードでTZを明示すると、意図しないローカル設定に影響されにくくなります。

シェル

• 💻 `TZ=Asia/Tokyo date -d @1735689600 +"%Y-%m-%d %H:%M:%S %Z"` # JST表示
• 💻 `date -u -d @1735689600 +"%Y-%m-%dT%H:%M:%SZ"` # UTC表示

アプリでの扱い

• 🧭 パース時は入力文字列のオフセットを尊重し、内部ではUTCに正規化する。
• 🧭 表示時にユーザーのTZを適用する。ブラウザなら Intl API、バックエンドはユーザー設定を参照。

⚠️ よくある落とし穴

デフォルトTZの違いやDST、曖昧な文字列パースでバグが起きやすいです。

主な注意点

• 🚧 OS/コンテナのTZがUTCだと思い込んでいたらJSTだった（あるいは逆）。イメージビルド時に明示設定する。
• 🚧 DST地域でローカル時間が1日24時間にならない日があり、加算・差分がずれる。
• 🚧 TZ未指定の日時文字列をパースすると環境のデフォルトTZに依存してしまう。
• 🚧 ブラウザとサーバーで違うTZが使われ、同じUnix秒を異なるローカル時刻として表示してしまう。

🧪 テストと運用のコツ

TZを変えても意図通りかを確認するテストを持っておくと安心です。

チェック項目

• 📝 UTC/JSTの双方で同じUnix秒が意図通りのローカル時刻になるかをテストする。
• 📝 DSTを跨ぐ地域のサンプルデータ（例: `America/New_York`）で加算・差分を検証する。
• 📝 文字列パース時にTZ未指定が混じっていないかをバリデーションする。