日付・タイムゾーンのバグ調査チェックリスト

まずここだけ（これだけで効きます）

• ズレの「幅」を数字で出した（9時間・1日・1時間・それ以外）
• 画面の表示ではなく、DBに入っている生の値を1件見た
• サーバー・DB・アプリのタイムゾーン設定を、それぞれ出力して比べた

次に確認したい

• 日時カラムの型を確認した（変換されるタイプか、されないタイプか）
• フレームワーク側の設定が、php.ini などの設定を上書きしていないか確認した
• 期間指定のSQLで、終わりが <= 月末 になっていないか見た
• 日本時間の0時〜9時にあたるデータで再現を試した
• 検証環境と本番のタイムゾーン設定が同じか確認した

余力があれば

• 月末・月初のデータで、月の加算・減算の挙動を確かめた
• 外部APIから受け取る日時に、タイムゾーンの情報（+09:00 や Z）が付いているか確認した
• コンテナで動かしている場合、イメージ内のタイムゾーンを確認した
• 直す場所を1か所に決めてから手を入れた
• 「9時間足す」のような辻褄合わせを入れていない（入れた場合は理由をコメントに残した）
• 4つの層の設定を運用ドキュメントに書き残した

最低ラインの3つが済んでいれば、もう原因は半分絞れています。残りは、余裕のある日に少しずつで大丈夫です。

日付のバグを追いかけているとき、いちばんしんどいのは「自分の書いたコードが読めていないのでは」と思えてくる時間だと思います。でも、この種のバグは読解力の問題ではありません。目に見えないところで、時計が4つ動いているだけです。見えないものは、読んでも見えなくて当たり前です。

幅を測って、生の値を見て、設定を並べる。この3つを順にやれば、たいていのズレは正体を現します。今日その1件を突き止められたなら、同じ形で困っている未来の何件かも、まとめて片づいています。全部を一度にきれいにしなくて大丈夫です。まずは、4つの時計を並べて見るところから。