日次AIジョブの「今日」はいつか。タイムゾーン・業務日・締切・再実行を分ける設計

編集部の実務提案

「毎朝実行」だけでは、処理の対象が決まらない

毎朝のAI集計を依頼するとき、「日本時間の朝に実行」とだけ決めることがある。しかし、動き始めた時刻が決まっても、何日分のデータを読むかは別の問いだ。海外サービスの時刻はUTC、画面は日本時間、帳票は前日の業務日という組合せなら、同じデータが異なる日へ見える。画面の表示だけを直しても、抽出条件や再実行の対象が同じとは限らない。

たとえば、予定より遅れて実行したジョブが現在日付から対象を決めると、最初の試行と再試行で違う期間を読む可能性がある。処理自体は成功していても、昨日の集計を今日の表へ書くなら業務の目的は満たしていない。時刻の正しさと、業務上の意味の正しさを別々に確認する必要がある。

本稿は、人の時差に合わせた引継ぎ一般ではなく、日次ジョブがどの期間を処理するかという契約を扱う。定刻起動、データの受付、完了判定、再実行の四つを分け、画面と台帳で同じ対象を指せるようにする。以下の業務日や締切、架空数値、受入試験は編集部の提案であり、すべての業務へ共通の締切を指定するものではない。

最初の確認は、「何時に動くか」より「この結果は何の期間か」と尋ねることだ。関係者の答えが一致しなければ、スケジュール設定を先に確定しない。経理の対象月、店舗の営業日、データ提供元の日付は異なる場合がある。どの意味を採用するかを業務側が決め、その定義を処理へ渡す順番にしよう。

編集部の実務提案

一次仕様が答える範囲と、業務で決める範囲

RFC3339は、日付と時刻、UTCオフセットを含む表記の構文を定義している[1]。これに沿う時刻が保存されていても、前日分なのか、どの締切で確定した集計なのかまでは自動的に分からない。日時の形式を採用したことと、日次業務の仕様を決めたことは別である。

Cloud Schedulerの資料は、既定のタイムゾーンがUTCで、wall clockで動くため夏時間による想定外の実行があり得ると説明する[2]。また、at-least-onceの配送で、元の予定実行時刻を再試行でも保持する情報が示されている[3]。これらは当該サービスの仕様であり、他のcronやキューが同じとは限らない。

業務側で決めるのは、どの地域のカレンダーを使うか、対象期間の境界、遅着の扱い、完了と呼ぶ条件である。基盤の時刻をUTCへ統一するだけで、その意思決定を省略しない。逆に、業務日は日本時間だから保存されるすべての瞬間も日本時間の文字列に変える、と短絡する必要もない。

仕様書では、外部サービスの事実と自社の方針を別欄へ置く。前者には原典と確認日、後者には決定者と版を残す。公式資料が改訂されたとき、どこが外部条件に依存していたかを追いやすくなる。業務側が締切を変えたときも、外部サービスの不具合と混同せずに変更の影響を説明できる。

編集部の実務提案

手順1：五つの日時を、名前で区別する

最初に、データの発生時刻、こちらが受け取った時刻、ジョブの予定実行時刻、実際の開始時刻、完了時刻を別の項目として持つ。すべてを一つのcreatedAtへ押し込めると、遅れがどこで起きたか分からない。項目名は既存の規約に合わせてよいが、その値が何を意味するかを説明できるようにする。

発生時刻は提供元が付けた値か、利用者が入力した値かを区別する。受け取った時刻はシステム側の観測として残す。提供元の時計がずれている可能性もあるため、発生時刻だけで到着の早さを判定しない。二つの時刻が同じにならないことを、異常と決めつける必要もない。

予定実行時刻と実開始は、遅延や再試行を読むために分ける。予定が深夜、実際の開始が朝でも、処理の対象期間まで朝の現在日付へ移してよいとは限らない。完了時刻は実行の終わりを表し、対象期間の終了を表すものではない。結果画面で並べる際も、ラベルを省略しない。

この五つに、対象期間の開始と終了を加えると、業務の結果と運転の履歴を分けられる。数が多く見えても、同じ値へ複数の意味を持たせるより読み違いが少ない。画面では必要なものだけを見せ、台帳では境界を保持するという役割分担ができる。表示の簡潔さのために元の意味を失わない設計にしたい。

編集部の実務提案

手順2：業務日の名前と期間を別に定義する

業務日を単なる日付文字列にせず、その日付が指す開始と終了を定義する。編集部の架空例では、業務日2026-11-07を、UTC+09:00の11月7日03時以上、11月8日03時未満の期間とする。これは午前3時を一般的に薦める意味ではなく、日付の名前と実際の境界が異なる例である。

開始以上・終了未満という半開区間にすると、ちょうど境界にあるデータを二つの期間へ同時に入れにくくなる。終了を含むかどうかを画面とSQLで別々に解釈しない。秒の端数を切り捨てて「最後の一秒」を作る方法では、より細かい精度の値を見落とす可能性がある。境界そのものを次の期間の開始として定義する。

業務日を決める地域の識別子と、実際の境界を表す瞬間も残す。ある日のUTCオフセットだけを保存して、将来のすべての日も同じ規則だと仮定しない。地域のカレンダーを使う繰返しと、固定した瞬間の記録では、必要な情報が違う。対応する日時処理の方法をチームで統一する。

ここまでで決めた内容が画面、集計、手作業の報告で一致しているかを確認する。部署ごとに対象日の意味が違うなら、一つへ無理に統一する前に、別の業務日という概念が必要かを検討する。名称を揃えるだけで、元の業務上の違いを隠さない。まず一つの具体的な日を例に、関係者へ境界を読んでもらおう。

編集部の実務提案

手順3：起動時に、対象期間を固定して渡す

ジョブが動くたびに現在時刻から対象期間を再計算するのでなく、受付時に対象の業務日、開始、終了、方針の版を決め、処理へ渡す。処理の途中で日付が変わっても、同じ仕事の対象まで変わらないようにする。日付だけでなく境界の瞬間を持てば、表示の地域を変えても何を読んだかが追える。

UTC+09:00の2026年11月7日00時30分は、UTCでは11月6日15時30分である。この編集部の算術例で、UTCの日付部分をそのまま業務日へ使えば一日ずれる。文字列の先頭を切り出す実装より、その値が何の瞬間で、どの業務定義へ変換するかを明示する。日時形式が正しいことだけでは、この取り違えは防げない。

予定時刻を使って対象を決める場合も、どの予定を信用するかを定義する。Cloud Schedulerの情報を利用するなら、正規の実行元の認証を確認したうえで、ジョブ名と元の予定時刻を扱う[3]。ヘッダーがあるだけで誰の依頼も正規と見なさない。配送の識別と、実行する権限の確認を別にする。

対象期間が固定された後は、再試行でも同じ値を引き継ぐ。新しい現在日付へ自動的に更新しない。別期間を処理する必要が出たなら、元の仕事の再試行でなく新しい依頼として記録する。利用者が結果を見るときも、実行日時と対象期間を並べれば、遅れて完成した前日分を今日分と読み違えにくくなる。

同じ瞬間を異なるオフセットで表した例も、試験へ入れるとよい。文字列の見た目が違うことを、別の日の別の出来事だと扱わない。一方、同じ日付文字列でも、地域や締切の方針が異なれば同じ対象期間とは限らない。表示の一致と、期間の一致を別の条件で確認する。

編集部の実務提案

手順4：受付締切と完了期限を分ける

受付締切は、どのデータまで今回の結果に含めるかという境界である。完了期限は、その結果をいつまでに利用できる状態へするかという約束である。どちらも午前中の時刻だからと同じ欄へ入れない。データを待つ時間と処理を進める時間が混ざると、遅れの原因と対応先が分からなくなる。

完了したという状態も定義する。AIの応答を受け取っただけか、必要項目を検証し、保存し、関係者が読める状態になったのか。報告メールの配送まで含める場合は、その確認も別に残す。すべてを一つの成功フラグにすると、結果は保存済みだが通知だけが遅い回を読み分けにくい。

締切直前に来たデータの扱いは、どの時刻で判定するかを決める。データの発生時刻なのか、こちらの受付時刻なのかによって対象は変わる。提供元が後から時刻を訂正する場合のルールも必要になる。単に日付が前日なら全部含める、という実装へ隠さず、業務で許される条件として合意する。

期限を過ぎたときは、処理を止める、暫定版を出す、遅延を表示して続ける、といった対応を業務ごとに選ぶ。継続してよい処理と、既に出した結果へ追加で副作用を起こす処理は別である。完了期限の超過を理由に、元のデータ期間を勝手に切り詰めたり、成功の時刻を書き換えたりしない。

編集部の実務提案

手順5：遅着を、次の日へ押し込む前に分類する

遅着データには、発生は期間内だが到着が遅れたもの、元の発生時刻が訂正されたもの、重複が後から見つかったものなどがある。すべてを「締切後」として同じ扱いにしない。どの結果へ影響するか、既に確定した資料を訂正する必要があるかを分ける。受付時刻を変えて過去へ入れ直す方法では、何が起きたかという履歴が失われる。

編集部の提案は、元データと到着の事実を保持し、採用した期間と採用方針を別に記録する方法だ。遅着を翌日へ回す業務もあれば、前日分の訂正版へ含める業務もある。どちらを選んだかを利用者が読めるようにする。後から方針を変える場合は、新しい版として扱い、以前の結果の前提を消さない。

遅着を待つ猶予を設けても、永久に待つ処理にしない。いつ暫定を確定へ変えるか、何をもって入力が揃ったと判断するかを決める。提供元の完了通知を使うのか、一定の締切を使うのか、その組合せかは業務条件による。未到着をゼロとして埋めることと、値が本当にゼロだったことは区別したい。

利用者へは、対象期間に加えて、データ確認の時点と暫定・確定の状態を示す方法がある。すべての内部時刻を画面へ並べる必要はないが、結果の意味に影響する条件は隠さない。昨日分の数字が変わったとき、なぜ変わったかを説明できることが、日次AI処理を業務で使う前提になる。

件数がゼロという結果にも、入力が揃って本当にゼロだった場合と、まだ何も届いていない場合がある。前者は確定結果になり得るが、後者を同じ表示にすると利用者が判断できない。ゼロ件の意味を、完了状態やデータ確認時点と組み合わせて示す。

編集部の実務提案

手順6：再試行の対象日と、副作用を固定する

再試行では、同じ仕事の識別子と対象期間を引き継ぐ。実際の試行ごとの開始、終了、エラーは別行へ残す。論理的には一つの集計でも、複数回の実行があったことを消さない。ジョブの一意性と、試行の一意性を分ければ、どこまで終わったか、何を繰り返すかを説明できる。

外部への送信や請求処理がある場合は、集計のやり直しと副作用のやり直しを分ける。結果の生成に失敗した回と、送信後に応答だけ分からなくなった回では、次の行動が違う。結果不明を失敗ゼロ件として扱い、同じ送信を新規に作る設計は避けたい。外部の状態を確認するための識別子を保持する。

予定実行時刻を含む配送情報は重複を見つける材料になるが、それだけで業務上の一意性が完成するわけではない。対象の顧客、処理種別、業務期間、採用する方針の版など、何が同じなら同じ仕事かを定義する。識別子の範囲を広げすぎると別の仕事を止め、狭すぎると重複を通す。

再実行用の画面では、現在日付だけを初期表示しない。元の対象期間、前回の状態、副作用の確認結果を見せ、同じ仕事の再試行か、新しい訂正版かを選べるようにする。操作者の意図が記録に残ると、翌日の調査で「もう一度押した」以外の説明ができる。権限の確認は各実行で行い、過去の操作履歴だけを許可証にしない。

編集部の実務提案

夏時間と「24時間後」を同じ考えで扱わない

地域の時刻で毎日同じ時刻に動かすことと、前回から一定の経過時間で動かすことは別である。夏時間を採る地域では、現地の日付の切替えと常に24時間という仮定が一致しない場合がある。Cloud Schedulerの資料も、wall clockと夏時間の影響を説明している[2]。使う基盤の仕様を確認し、カレンダー上の繰返しか経過時間の繰返しかを決める。

ある日の境界の瞬間へ24時間を足すだけで、翌日の現地締切を求める実装には注意したい。必要なのが現地カレンダーの次の日なら、その地域の規則に沿って次の境界を計算する。過去の一つのUTCオフセットを永続的な地域の規則として使わない。日時を扱うライブラリやデータの版も、再現に必要な場合は記録する。

同じ現地時刻が重なる場合、存在しない現地時刻がある場合にどうするかを、受入試験へ入れる。ここでは特定の地域の将来の切替え日を創作せず、使う地域の実データで確認する。自動補正された時刻をそのまま採用するか、明示的にエラーとするかは、業務への影響から決める。

UTCで起動する方針を採る場合も、業務期間をどの地域で読むかは残る。起動の安定性と、利用者が見る日付の意味を切り分ける。すべてをUTCへしたから日付の設計は終わり、という結論にはしない。変更後は、画面、抽出条件、通知、再実行画面が同じ対象期間を指すかを再確認する。

編集部の実務提案

月末と休日は、スケジュールの外にある業務条件

毎月の締めを日次処理へ含めるときは、月の最終日と営業上の締め日を分ける。カレンダーの月末、金融機関の営業日、社内の資料確定日は同じとは限らない。cronの式だけで、その意味まで表現できたと思わない。営業日カレンダーが必要なら、どのカレンダーを採用し、誰が更新するかを決める。

休日に実行しない場合も、データの対象期間まで消えるのか、次の実行でまとめるのかを定義する。起動を一回省いたから、その期間のデータも不要とは限らない。次回に複数期間を処理するなら、結果を期間別に残すか一つにまとめるかを決める。利用者が数字を比較できる表示を維持する。

月をまたぐ再試行では、対象月を現在の月へ取り直さない。費用や請求準備へ使う場合、後日処理した前月分がどこへ計上されたかを説明できる必要がある。ただし、会計や法令上の計上時期をシステム担当だけで決める記事ではない。業務の担当者が決めた対象期間を、処理が忠実に保持するという範囲で考える。

カレンダーを変更した場合は、過去の結果を新しい規則で黙って表示し直さない。以前の締切で確定した資料と、新しい締切で作る資料が違うことを残す。過去を再計算する必要があるなら、その対象と版を別に承認する。変更の便利さより、どの前提で数字が作られたかを追えることを優先する。

編集部の実務提案

架空ケースA：午前3時の後に再試行した集計

架空の店舗集計で、業務日11月7日の対象を11月7日03時から11月8日03時未満と定義したとする。11月8日の締め後に動く処理が途中で失敗し、再試行は同日の朝になった。実行時のカレンダー日付は11月8日だが、再試行すべき対象は元の11月7日分である。現在日付から一日引くだけという説明では、どの締切の方針かが見えにくい。

最初の受付で対象期間を固定していれば、再試行は同じ境界を使える。台帳には元の予定、最初の試行、再試行、結果の版を並べる。前の試行で保存が済んだか、通知が済んだかも分ける。朝の結果画面では「11月7日分、朝に完成」と読めるようにし、実行日だけを大きく表示しない。

このケースでは、遅着が入ったから再計算したのか、同じ入力で処理をやり直したのかも区別する。後者なら同じ結果版の再試行となり得るが、前者では新しい入力集合や訂正方針が関わる。両者を同じ再実行ボタンへ隠すと、利用者の意図が追えない。画面と台帳で違いを明示する。

試験では、初回と再試行の現在時刻だけを変え、対象の境界が変わらないことを確認する。さらに、保存後に応答を失う場合を想定し、同じ副作用が増えないかを見る。定刻に一度成功する試験だけでは、この問題を確認したことにならない。遅れた運転で意味を保てるかを受入条件へ入れる。

編集部の実務提案

架空ケースB：締切前に発生し、締切後に届いた明細

別の架空例では、明細の発生は締切の直前だが、こちらへの到着は締切後だった。発生時刻で対象を決める方針なら前の期間に関係する一方、受付時刻で確定する方針なら今回へ入らないこともある。どちらが正しいかを基盤だけでは決められない。提供元の遅延が通常どのように起こるかも業務側へ確認する。

前日分の訂正版へ入れると決めた場合、以前の結果を黙って上書きしない。訂正の版、理由、追加された明細、差分を残す。利用者が既に前の資料を使っているなら、どこへ変更を伝えるかも運用条件になる。数字だけが変わり、通知やダウンロード資料が古いままという状態を避けたい。

翌日へ回す方針の場合は、発生日と計上した業務日が違うことを保持する。元の発生時刻を書き換えて帳尻を合わせない。集計の比較では、期間の長さが同じでも遅着の件数が違う可能性がある。必要なら、その影響が分かる注記や別集計を設ける。実装の都合で業務上の意味を隠さない。

受入試験には、境界の直前、境界ちょうど、直後の発生と受付を組み合わせる。秒の端数も扱うなら、その精度で境界を確かめる。同じ明細の再配送や時刻訂正も別に試す。単純な日付一致の例だけでなく、実際に判断が分かれる条件をデータ例として合意しておくことが重要だ。

編集部の実務提案

設定変更は、実行中の仕事へ自動で混ぜない

締切を変更したり、対象地域を変えたりするときは、いつから新しい方針を採用するかを決める。すでに受付済みの仕事が古い期間を持つなら、そのまま完了させるか、止めて新しい依頼へ置き換えるかを明示する。処理の途中で最新設定を読み直し、境界だけ新しい値へ変えると、一つの仕事の前提が混ざる。

方針の版は、対象期間の決定に使ったものとして台帳へ残す。表示文言を修正しただけか、境界や遅着の採用条件を変えたかも分ける。すべての変更で再計算が必要とは限らないが、数字の意味に影響する変更を見落とさない。変更を誰が判断し、どの期間へ適用するかを業務の責任者と確認する。

再開時には、以前の方針を使ってよいかも確認する。長く停止した仕事を何日後でも自動再開する前に、対象期間がまだ必要か、関連データが保持されているか、副作用の権限が有効かを見る。予定時刻を保持することは、古い依頼を永久に実行してよいという意味ではない。

実装チームへの依頼は、設定画面だけでなく、変更履歴と実行台帳がつながる範囲にする。担当交代後も、なぜこの結果がこの境界になったかを追える状態を成果物へ含める。設定を変えられることより、変えた後に既存の仕事と矛盾しないことを、受入確認で見たい。

実行の対象期間を手動で指定できる画面には、変更前の値を確認する段階を置く。入力し直した期間が元の再試行と異なるなら、その違いを画面で示し、新しい依頼として残す。古い識別子のまま中身だけを変えると、後の重複判定と結果照合が別の意味を持ってしまう。

編集部の実務提案

受入試験は、境界・重複・遅延を一枚にする

受入試験では、通常日の成功だけでなく、境界にある入力、日付をまたぐ再試行、月末、使う地域の夏時間、設定変更を扱う。すべてを同じ試験で一度に変えず、何の条件を確かめるかを分ける。最初は少数の具体的な入力と期待結果を業務側と合意し、その例を自動試験へ引き継ぐ方法がある。

期待結果には、対象期間、採用したデータ、結果の版、副作用の回数、利用者への表示を含める。HTTPが成功したかだけでは業務上の正しさを確認できない。データの件数が同じでも、違う期間の同数データを読んでいる可能性があるため、境界や識別子も確かめる。実行が終わったことと、正しい対象を終えたことを分ける。

本番の個人情報や秘密を試験資料へそのまま入れる必要はない。架空の時刻と明細で境界の意味を確認し、実データで必要な最終確認は別の許可された範囲で行う。試験結果には値をすべて公開するのでなく、対象の版や一致確認を残す方法もある。確認できた範囲と未実施の条件を区別して報告する。

合格後も、運用の監視で予定と実際の差を読めるようにする。遅れた回があったとき、まず対象が維持されたか、副作用が重複していないか、完了の意味が保たれたかを確認する。時刻が遅かったという一事実から、すべて失敗と決めたり、成功応答だから問題なしと決めたりしない。

編集部の実務提案

運用担当へ渡すのは、cron式だけではない

引継ぎ資料には、スケジュール、地域、業務日の定義、対象境界、遅着方針、再実行の手順、確認先をまとめる。cron式のコピーだけでは、なぜその時刻で何を処理しているかが伝わらない。担当者が交代しても、一つの結果から元の実行と採用方針へ辿れることを目指す。

問い合わせの経路も、遅延の種類で分ける。データが来ていない、処理が始まらない、AI応答が遅い、保存後の通知が遅い、では調べる先が違う。利用者に毎回内部構造を説明させず、結果の識別子や対象期間から担当者が確認できる仕組みを用意する。運用上の分担と画面の表示を揃えたい。

VERSAROCへ相談する場合も、「日付がずれる」という現象だけでなく、どの画面、どの対象期間、どの実行で違いがあったかを説明できる資料が役立つ。既存システムをすべて作り直す前提ではなく、現在のデータ経路と責任の境界を整理し、修正と確認の範囲を決める。未確認の効果や費用削減率を約束する記事ではない。

最後に、通常運転と例外対応を同じ台帳で追えるようにする。再実行だけ別の手作業表へ移ると、最も確認したい履歴が分断される。担当者が「押したか」ではなく、「どの期間に何が確定し、何が未確認か」を答えられる状態が、日次AI業務を任せるための具体的な成果物になる。

編集部の実務提案

次の一歩は、一日の境界を全員で読むこと

最初からすべての時差と例外を実装する必要はない。まず実際の業務の一日を選び、対象期間、受付締切、予定実行、完了期限を一枚に描く。入力の発生と到着を数件置き、どの結果へ入るかを担当者へ読んでもらう。答えが分かれた箇所が、コードを書く前に決めるべき仕様である。

その後、遅れた開始、日付をまたぐretry、遅着の訂正を一つずつ加える。普通の日だけでなく、実際に困った日の条件へ広げる。現在時刻から何度も対象を取り直す実装になっていないか、結果が分からないときに副作用を増やさないかを確認する。例外の数を増やすことより、同じ意味を維持することを優先する。

日時形式、スケジューラ、キュー、画面は、それぞれ別の役割を持つ。どれか一つの設定が正しいだけでは、業務全体の対象日は決まらない。外部仕様を正確に読み、自社の方針を明示し、その版を実行へ渡す。この接続を設計すると、日次処理の「今日」を担当者ごとの暗黙知から外へ出せる。