# 監視の想定値を「復元」せず、日次スナップショットの実値で照合する（偽警報の根絶） ## どんな問題を解くか 「送った値」と「実際に起きた値」の差を毎朝見張る監視（価格と成約額・配信設定と実配信・在庫と実売など）で、 **想定値side に「今日の値」を使うと偽警報が出る**。今日の値は、測ろうとしている事象自身 （予約・成約・イベント）のせいで動くからだ。例: 動的価格エンジンは予約が1件入ると同じ日の価格を 上げる。すると新しい予約は必ず「大幅値引きで売れた」ように見える。 第一段階の対策として「事象発生時点の値を計算で復元する」（発生時点より前のデータだけで 係数を再計算する）方式があるが、**復元には構造的な限界がある**: - 後にキャンセル・削除された状態を再現できない（現存データだけで数え直すため） - 発生時点だけ有効だった一時的な倍率・特別設定を再現できない - 「当時の値 = 今日の値 × 係数比」という仮定自体が壊れる個体が残る 実際、復元方式を入れても説明できない −47% の乖離が1件残り、原因は永久に検証不能と決着した。 **根治は、実値を毎日残すことだけ。** ## 作るもの（3点） ### 1. 日次スナップショットツール（追記型 JSONL・冪等） - 監視対象の「送っている値」（価格表・配信設定など）を、今日から N 日先まで API で取得し、 1日1行の JSON として追記する: {"snapshotDate":"YYYY-MM-DD","takenAt":"","values":{"<日付>":<値>,...}} - **冪等にする**: 同じ snapshotDate の行が既にあれば書かずに正常終了（読む側は同一日の最後の行を使う）。 - **不完全な取得を書かない**: 値が入っている日数が下限（例: 30日）未満なら exit 1 で書き込まない。 欠けたスナップショットは後日の判定を汚す。 - 429（レート制限）だけ数回リトライ。他の例外は即失敗。 - 出力先はスクリプト位置基準の既定パス + `--file` で上書き可能に（夜間ジョブが別の作業ツリーから 呼ぶ場合に、成果物だけ共有側へ着地させるため）。 ### 2. 監視側の判定を「実値優先」に切り替える - 事象（予約・成約）ごとに `takenAt <= 事象発生時刻` を満たす**最新**のスナップショットを引く。 ただし発生時刻との差が **48時間を超えたら無効**（古すぎて実値と言えない）。この選択関数は 純関数にして export し、テスト可能にする。 - スナップショットが引けた事象だけで警報を判定する（チャネル別中央値・最少サンプル数などの 既存ロジックはそのまま）。 - **引けない事象は判定から外す**。全事象が引けなければ **exit 2（判定不能）** で止まり、 「実値スナップショットが無く判定不能（蓄積開始 <最古の日付>）」と正直に出す。 **ここが要点: 判定できない日に警報ゼロを装わない。** - 旧方式（復元）は参考値として全行に併記する。新旧の差分が1件ずつ見えるので、移行初日に 「復元パスに回帰が無いこと」を旧記録との突き合わせで検証できる。 ### 3. 夜間ジョブへの組み込み - 毎朝の監視ジョブで、**判定の直前に**スナップショットを1回取得する（順序が大事。 判定→取得の順だと当日作成の事象が永久に判定不能になる）。 - スナップショット取得が失敗しても監視ジョブ全体は止めない（判定側が exit 2 で止まるだけ）。 - 夜間ジョブが「main 固定の作業ツリー」から走る構成なら、変更を main に入れるまで効かない。 デプロイ後に `git cat-file -e origin/main:<新ファイル>` で反映を確認する。 ## 検証チェックリスト（実装した日に全部やる） 1. スナップショット1回目を本番 API で取得 → 行が書かれ、2回目の実行が「既に取得済み」で exit 0（冪等） 2. 監視を `--days 1` で実行 → **exit 2**（実値0件を正直に報告）が出ること。初日は exit 2 が正解 3. 過去窓（`--days 7` など）で実行 → 復元参考値が既存の記録と一致すること（回帰なし） 4. 夜間ジョブと同一コマンドで通し実行 → exit 0・レポートにスナップショット行と判定行が出る 5. 翌朝ゲートを1件積む: 2日目の行が自動で増えたか・判定が exit 2 以外を返し始めたか ## 落とし穴 - **「発生時刻より前の最新」を選ぶこと。** 発生日と同じ日のスナップショットでも、取得時刻が 発生より後なら使ってはいけない（事象自身が動かした後の値になる）。 - 途中で書式が壊れた行は無視して続行する（JSONL の1行破損で全体を止めない）。 - 蓄積開始より前の事象は永久に判定不能のまま。それを「異常」と騒がない。exit 2 が数日続く ときだけ蓄積の停止を疑い、行数とジョブのログで切り分ける。 - 監視値のファイルが肥大するのを嫌って値を丸めたり間引いたりしない。判定に使うのは生値。 ---