N分粒度スケジューラとユーザー設定時刻のマッチング設計(許容窓と冪等化)
バックエンド
設計判断
通知
「ユーザーが任意の時刻(分単位)を設定し、cron / スケジューラは N 分粒度でしか起動できない」場合のマッチング設計。
許容窓の決め方: 実行時刻と設定時刻の差を ±floor(N/2) 分まで許容すると、任意の設定分がちょうど 1 つの実行枠にだけマッチする(窓幅が grid 間隔と一致するため、取りこぼしも二重マッチも理論上起きない)。例: 5 分粒度なら ±2 分。
それでも冪等化が必須な理由: スケジューラの起動は分単位でずれることがあり(遅延起動・リトライ)、窓の境界をまたぐと二重送信や取りこぼしが起きる。対策として「最終実行日時」をストレージに記録し、前回から最小間隔(例: 同一枠の二重発火防止に数時間)未満ならスキップする。この記録は隔週・隔月などの「N 回に 1 回」系インターバル判定にもそのまま流用できる(前回から interval×周期 − 1日 未満ならスキップ、のように 1 周期弱のマージンを取ると時刻ずれに頑健)。
落とし穴: サーバレス実行環境は通常 UTC。スケジュール定義の timeZone 指定は「起動タイミング」にしか効かず、コード内の Date は UTC のままなので、曜日・時刻の比較はタイムゾーン補正してから行う。曜日の数値規約(JS は 0=日曜、ISO は 1=月曜〜7=日曜)の変換漏れも定番のバグ。
検証方法: 設定時刻を数分後にして実機で待つ前に、関数をローカル/エミュレータで現在時刻を引数化して呼び、境界値(窓の両端、週またぎ、日曜)でマッチ判定だけ単体確認すると速い。