外部に出ている値を「システム内部のフィールド」で検証して誤診しないための手順

外部サービス（チャネルマネージャ／予約システム／広告配信／在庫連携）に値を送り込む自動化で、 「送った値が正しく外に出ているか」を内部フィールドで確認すると、高確率で誤った結論に到達する。 実際にこれで「対象の 7/8 が 6割高で売られている」と誤診し、危うく一律 33% の値下げを実行しかけた。 本書はその失敗の再現条件と、確実に潰す検証手順をまとめる。

1. 何が起きるか（失敗の型）

内部APIが返すレコードには、次の3種類が混在している。名前からは区別できない。

種類	例	外の見え方との関係
入力値	自分が書き込んだ値	一致するとは限らない
派生値	他レコードから係数で導出された値	用途が限定されている（特定チャネル専用など）
参考値	外部ソース由来のヒント値・推奨値	販売には一切使われない

fieldA / fieldB のような没個性な名前で並ぶため、エンティティをまたいで同じ名前のフィールドを比較すると、 違う意味のものを比べてしまう。

実例:

• エンティティX の fieldB = 実際の販売値
• エンティティY の fieldB = 特定チャネル専用に 1.5倍で導出された派生値（販売値は fieldA の方）
• エンティティX の fieldA = 外部ソース由来の参考値（販売に未使用）

→ 「X.fieldB(=6000) と Y.fieldB(=9000) を比べたら Y が 1.5倍だ」＝完全な誤り。 実際は X も Y も同じ値で売られていた。

2. 係数は「エンティティ単位」ではなく「チャネル単位」で入っていることが多い

上記の 1.5倍は、実は特定の販売チャネル向けルールにだけ設定されており、 全エンティティに等しく掛かっていた。「一部のエンティティだけ高い」という理解自体が誤り。

ルール一覧の実体（各エンティティが個別に保持）:
  [1] チャネルA向け  → 参照元.fieldB × 1.0
  [2] チャネルB向け  → 参照元.fieldB × 1.5   ★これが係数の正体
  [3] チャネルC向け  → 参照元.fieldB × 1.0
  [4] 自社直販向け   → 参照元.fieldB × 1.0

チェック観点: 係数を見つけたら「どのエンティティに付いているか」ではなく **「どのチャネルのルールに付いているか」**を必ず確認する。

3. 設定が「見えていなかった」真因 — 黙って切られる

この係数を長期間見つけられなかった原因は、レスポンスの無言の切り捨てだった。

切り捨て箇所	症状
自作ゲートウェイの slice(0, N)	N件でぴったり止まる。エラーは出ない
文字数上限での substring(0, LIMIT)	JSON が途中で切れて JSON.parse が失敗、または前半だけ解釈される

実測: 全設定を含むレスポンスは 235,780 字あったが、45,000 字で切られていたため 係数を持つセクションに一度も到達していなかった。上限を上げるだけでは足りず、継ぎ足しが必要。

対策: offset ページングで全文を取得する（擬似コード）

buffer = ""
offset = 0
loop:
    res = call_gateway(path, offset)
    assert res.offset == offset          # offset が無視されていたら即エラーにする
    buffer += res.chunk
    offset = length(buffer)
    if offset >= res.totalLength: break
assert length(buffer) == res.totalLength  # 継ぎ足し漏れを検出
parse(buffer)

必須: ①応答に「全体長」と「切り捨てフラグ」を持たせる ②offset が無視されていたら例外にする （ゲートウェイが未デプロイだと黙って先頭を返し続け、無限ループか誤ったデータになる） ③件数上限のあるAPIは期間・条件を分割し、各回が上限未満であることを確認してから集計する。

4. 正しい検証手順（この順で全部やる）

手順1: 「消費者向けエンドポイント」を使う

内部レコードではなく、チャネル／顧客が実際に受け取る形を返すエンドポイントを探して使う。 在庫・予約系なら「指定条件で購入可能な選択肢とその価格を返す」API がそれにあたる。

GET /<consumer-facing-offers>?<entityFilter>&<condition params>
→ 各エンティティごとに「実際に提示される値」が返る

得られるもの: 派生も参考値も解決済みの、外に出ている本物の値。

手順2: 全エンティティ × 全条件で突き合わせる（代表1件で判断しない）

一致 N件 / 不一致 0件 / 販売なし M件 / 参照データなし 0件

• 代表1エンティティで「反映OK」と言わない。 係数やルールはエンティティごとに違い得る。
• 「販売なし」を不一致と混同しない。 在庫切れ・条件外は正常な状態。分けて数える。
• 期待値側（意図した値）のデータが無い区間は 参照データなし として別カウントし、 暗黙に一致扱いしない。

手順3: ブラウザで実描画を確認する

APIが正しくても、外に出ている画面が壊れていることはある（文字化け・二重表示・描画崩れ）。 ヘッドレスブラウザで実際のページを開き、スクリーンショットを保存して自分で目視する。

node <verify-tool> "<consumer-facing URL>" \
  --expect "<出ているはずの文字列>" \
  --not-expect "<残っていてはいけない旧値>" \
  --shot out.png --wait 9000

• テキスト抽出だけで済ませない。画像を必ず開く。
• --not-expect に旧値を入れると、キャッシュ残留・部分反映を検出できる。
• 外部の大手サービスは自動アクセスを遮断することが多い。 自社が管理する消費者向けページ（直販ページ等）なら確実に開けるので、まずそこを押さえる。

5. 検証器そのものが誤診を追認する罠

「毎回不一致が出て警報が形骸化する」ことを嫌って、 検証器に「この係数は正常」とモデルを書き込むと、以後その乖離を永久に報告しなくなる。 形骸化を防ぐつもりで、警報を自分で殺すことになる。

原則: 検証器の期待値は「意図した値（自分が決めた設定）」に置く。 「外部システムがどう振る舞うか」を期待値に写してはいけない。 外部の振る舞いをモデル化するなら、それは別の情報として併記し、判定基準にはしない。

6. チェックリスト

• 比較しているフィールドは、エンティティ間で同じ意味か（派生値・参考値が混ざっていないか）
• レスポンスは全文取得したか（件数上限・文字数上限で切られていないか、全体長と突き合わせたか）
• 係数・特殊ルールは「エンティティ単位」か「チャネル単位」か確認したか
• 消費者向けエンドポイントで検証したか（内部レコードで済ませていないか）
• 全エンティティ × 全条件で数えたか（代表1件で判断していないか）
• 「対象外・在庫なし」を不一致と分けて数えたか
• ブラウザ実描画のスクショを自分で目視したか
• 検証器の期待値は「意図した値」か（外部の振る舞いを写していないか）

7. 誤診に気づけた決め手

「同じ条件で外に出ている実際の値」を取り直したことの一点に尽きる。 内部フィールドをいくら丁寧に読み比べても、比べているものが違えば結論は出ない。

外に出ている状態を語るときは、外から取る。 内部の値は状態の説明であって、状態そのものではない。