# ChatGPT Ads 提案XML仕様 v1.4

本XMLは、顧客ごとの提案内容を移植可能な形で保持するためのデータ形式です。OpenAI Ads Managerへの一括入稿フォーマットではありません。VeReachの提案画面を駆動し、事実、前提、予測、意思決定、週次レビューを1つの監査可能なファイルにまとめます。

## 設計原則

1. 戦略より先に `evidenceCatalog` を定義し、重要な主張は必ず1件以上の根拠IDを参照します。
2. `focus.weight` の合計は100とします。FOCUSはオーディエンス区分ではなく、`変えたい事業状態 × 検証イベント` です。
3. `adGroup.allocation` の合計は100とします。診断可能性を担保するため、**1 Ad Group = 1 Context Hint = 1つの単一意図**を厳守します。
4. Context Hintには、設定理由とその意味境界を代表するQuery Bankを含めます。Queryは意味的カバレッジを説明する仮説であり、完全一致キーワードではありません。
5. すべての推定値に信頼度を付与します。推定週間機会は配信対象となり得る会話機会であり、表示回数の保証ではありません。
6. 週次指標には `actual`、`expected`、`previous` を保持し、当期の乖離と前期比較を画面上で確認できるようにします。

## ルート要素とメタデータ

- `chatgptAdProposal/@id`：提案を一意に識別する固定ID。
- `chatgptAdProposal/@version`：提案XMLのセマンティックバージョン。
- `metadata`：顧客名、製品名、通貨、ロケール、作成日、有効期限、作成者。

## 根拠情報の分類

- `official`：OpenAIの製品・ポリシーに関する公式文書。
- `account`：広告主アカウントのAds Managerエクスポートまたは計測データ。
- `client`：顧客の公式製品ページ、ブリーフ、一次情報。
- `model`：VeReachによる推論、シミュレーション、機会量推定、推奨事項。

`confidence` は `high`、`medium`、`low` のいずれかです。ChatGPT Adsは更新頻度の高いベータ製品であるため、根拠の確認日 `asOf` を必須とします。

## Campaign

`campaign` はAds Managerの主要設定を保持します。対象は、最適化目標（`CPM`、`CPC`、`oCPC`）、予算、日次最低予算、国、期間、コンバージョンイベント、アトリビューション注記、提案上のガードレールです。通貨は `metadata/currency` を継承します。

## 校正データと予測ロジック

`calibration` には、予測の基準となる実績期間とKPIを保存します。HAWKサンプルは、2026-08-19〜2026-08-21のアカウント実績を使用します。

- 表示回数：14,328
- クリック：232
- コンバージョン：5
- 消化金額：19,580.51円
- CTR：1.62%
- CPC：84.40円
- CPM：1,366.59円

`modelAnnotations` は予測値に関する必須開示事項です。推奨する計算順序は次のとおりです。

1. Context Hintごとに週間の候補会話機会を推定する。
2. ブランドセーフティおよび配信適格性の条件を適用する。
3. 意味的に近いAd Group間の重複を補正する。
4. 直近のアカウント実績でCTR、CPC、CVRを校正する。
5. Campaign予算をFOCUSの重みで一次配分し、Ad Groupの機会量、意図価値、学習必要量で再配分する。
6. 単一の保証値ではなく、中心値と不確実性レンジを提示する。

## FOCUS

各 `focus` は以下を保持します。

- `objective`：変化させたい事業または運用上の状態。
- `target`：成果を検証する計測イベント。
- `thesis`：戦略仮説を1文で示したもの。
- `rationale`：根拠に基づく提案理由。
- `weight`：Campaign予算に対する配分率。
- `inventory` / `inventoryBand`：週間機会の中心推定値と不確実性レンジ。
- `confidence`：0〜100のモデル信頼度。
- `sources`：半角スペース区切りの根拠ID。

## Ad Group、Context Hint、Query Bank

各 `adGroup` は1つのFOCUSを参照し、ステータス、予算配分、上限入札、推定週間機会、CTR/CPC/CVR、予測クリック、予測コンバージョン、根拠、1件のContext Hint、クリエイティブを保持します。中心推定値には必ず `inventoryBand`、`cpcBand`、`cpmBand`、`conversionBand`、0〜100の `confidence` を併記し、計画値と保証値を明確に区別します。

各 `contextHint` は以下を保持します。

- ChatGPT AdsのContext Hint欄に設定できる自然言語の説明文。
- 当該Hintを設定する理由。
- Ad Group内の予算配分率。
- 週間機会の推定値と信頼度。
- 想定ユーザー、意図段階、週間機会、配分を持つ代表Query。

`query/@keyword` には、可視化用の短い語句を任意で設定できます。画面ではクラウド上に短い語句を表示し、ツールチップと詳細領域に完全な自然言語Queryを表示します。`weeklyVolume` は重複を含む表現単位のモデル値であり、実測検索ボリュームではありません。Hint内またはポートフォリオ全体で単純合算してはいけません。重複補正後の計画値は `adGroup.inventory` を使用します。

Queryの意図段階は `explore`（情報収集）、`compare`（比較検討）、`decide`（導入判断）の3種類です。1つのHint内のQuery配分は合計100とします。Ad GroupはContext Hintを1件だけ持つため、そのHintの配分は100です。

HAWKサンプルは、5つのFOCUS、各FOCUSにつき6つの単一意図Ad Group、合計150件の日本語Queryで構成されます。各Hintには、課題認識から比較、導入判断までを代表する5件のQueryを30/25/20/15/10で配分します。これらは人手でレビューした戦略モデリング例であり、ユーザーログ、完全一致キーワード、OpenAIによる配信保証ではありません。

## 週次レビュー

`weeklyReview` は上書きせず、期間ごとに追加します。各指標は次の値を比較します。

任意の `summary` には、顧客向け画面に表示する `headline`、`description`、`statusLabel` を保存できます。未指定時は製品名とレビュー状態から汎用表示を生成し、別顧客の文言を補完することはありません。

- `actual`：経過期間における実績値。
- `expected`：同じ経過期間に合わせて補正した想定値。
- `previous`：比較可能な前期値。
- `betterDirection`：`higher` または `lower` のどちらが望ましいか。

各Actionには、優先度、ライフサイクル `status`、担当者、期限、対象Ad Group、実施内容、完了条件を設定します。`status` は `proposed`、`approved`、`applied`、`verified` のいずれかで、UI上の一時状態ではなくXMLに保存します。

`changes` は意思決定と成果をつなぐ監査履歴です。対象Ad Group、変更項目、変更前後の値、適用日、理由、観測結果、状態（検証待ちの `applied` または検証済みの `verified`）を保持します。`finding` → `adGroupReview` → `change` → `result` によって、Signal → Decision → Change → Verificationの最適化ループを構成します。

`adGroupReviews` は、顧客向けの週次意思決定レイヤーです。各 `adGroupReview` は1つのAd Groupを参照し、以下を必須とします。

- `verdict`：拡大、維持、最適化、テストなどの短い運用判断。
- `signal`：判断の根拠となるシグナル。
- `adjustment`：予算または入札の具体的な変更方向。
- `recommendation`：次に実行する施策。

アプリは最新の `weeklyReview` を表示し、過去分はXML内に保持します。

## 読み込み時の検証

MVPは、XMLの整形式、必須要素、日付、通貨・ロケール、列挙値、数値範囲、IDの一意性、FOCUS配分とAd Group予算配分の合計、Source/FOCUS/Ad Groupの参照整合性、1 Ad Groupにつき1 Context Hintの制約、Context Hint配分、Query配分をブラウザ上で厳格に検証します。欠損値を別顧客のデータで補完することはありません。メタデータ、根拠、Campaign設定、校正データ、注記、FOCUS、Ad Group、Context Hint、Query、クリエイティブ、最新の週次レビュー、Ad Group別判断、変更履歴、Actionを読み込みます。

XSDは構造上の正式な契約であり、CIまたは提案生成パイプラインで完全検証に使用してください。現在のMVPが表示しない任意フィールドも、上流の生成処理では保持してください。互換性を破る変更では `version` のメジャーバージョンを更新します。

## 責任範囲

ChatGPT Adsの推定機会、オークション配信、CPC/CPM、コンバージョン、予算消化は、広告主アカウントで実績が確認されるまで予測値です。`model` の値を公式情報として表示しないでください。Context Hintを完全一致キーワードとして扱わず、配信対象となり得る会話機会を保証表示回数として提示しないでください。