# 外部に出ている値を「システム内部のフィールド」で検証して誤診しないための手順 外部サービス（チャネルマネージャ／予約システム／広告配信／在庫連携）に値を送り込む自動化で、 **「送った値が正しく外に出ているか」を内部フィールドで確認すると、高確率で誤った結論に到達する。** 実際にこれで「対象の 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 /?& → 各エンティティごとに「実際に提示される値」が返る ``` **得られるもの**: 派生も参考値も解決済みの、外に出ている本物の値。 ### 手順2: 全エンティティ × 全条件で突き合わせる（代表1件で判断しない） ``` 一致 N件 / 不一致 0件 / 販売なし M件 / 参照データなし 0件 ``` - **代表1エンティティで「反映OK」と言わない。** 係数やルールはエンティティごとに違い得る。 - **「販売なし」を不一致と混同しない。** 在庫切れ・条件外は正常な状態。分けて数える。 - 期待値側（意図した値）のデータが無い区間は `参照データなし` として別カウントし、 **暗黙に一致扱いしない**。 ### 手順3: ブラウザで実描画を確認する APIが正しくても、外に出ている画面が壊れていることはある（文字化け・二重表示・描画崩れ）。 **ヘッドレスブラウザで実際のページを開き、スクリーンショットを保存して自分で目視する。** ``` node "" \ --expect "<出ているはずの文字列>" \ --not-expect "<残っていてはいけない旧値>" \ --shot out.png --wait 9000 ``` - テキスト抽出だけで済ませない。**画像を必ず開く。** - `--not-expect` に**旧値**を入れると、キャッシュ残留・部分反映を検出できる。 - 外部の大手サービスは自動アクセスを遮断することが多い。 **自社が管理する消費者向けページ（直販ページ等）なら確実に開ける**ので、まずそこを押さえる。 ## 5. 検証器そのものが誤診を追認する罠 「毎回不一致が出て警報が形骸化する」ことを嫌って、 **検証器に「この係数は正常」とモデルを書き込むと、以後その乖離を永久に報告しなくなる。** 形骸化を防ぐつもりで、警報を自分で殺すことになる。 **原則**: 検証器の期待値は「**意図した値**（自分が決めた設定）」に置く。 「**外部システムがどう振る舞うか**」を期待値に写してはいけない。 外部の振る舞いをモデル化するなら、それは**別の情報として併記**し、判定基準にはしない。 ## 6. チェックリスト - [ ] 比較しているフィールドは、エンティティ間で**同じ意味**か（派生値・参考値が混ざっていないか） - [ ] レスポンスは**全文取得**したか（件数上限・文字数上限で切られていないか、全体長と突き合わせたか） - [ ] 係数・特殊ルールは「エンティティ単位」か「**チャネル単位**」か確認したか - [ ] **消費者向けエンドポイント**で検証したか（内部レコードで済ませていないか） - [ ] **全エンティティ × 全条件**で数えたか（代表1件で判断していないか） - [ ] 「対象外・在庫なし」を不一致と分けて数えたか - [ ] **ブラウザ実描画のスクショを自分で目視**したか - [ ] 検証器の期待値は「意図した値」か（外部の振る舞いを写していないか） ## 7. 誤診に気づけた決め手 **「同じ条件で外に出ている実際の値」を取り直したこと**の一点に尽きる。 内部フィールドをいくら丁寧に読み比べても、比べているものが違えば結論は出ない。 **外に出ている状態を語るときは、外から取る。** 内部の値は状態の説明であって、状態そのものではない。 ---