DeliveryAd型のAPIレスポンスにフィールド名を送信漏れし、全ての広告が「(無題の広告)」のまま配信された

受信側がcaption ?? titleのフォールバックを実装していても、送信側のAPIレスポンス型にtitleフィールド自体が無ければ、全件が「(無題の広告)」のまま無言で配信され続ける。

結論

配信先（v2）は「広告タイトルの caption が無ければ title を採用する」というフォールバックを1ヶ月前から実装済みだったが、送信元（portal）のレスポンス型そのものに title フィールドが存在せず、配信される広告は全件が caption: null ＝既定値のまま届いていた。 フォールバック自体は正しく動く設計で、受信側のコードは何も壊れていない。欠けていたのは、フォールバックに渡す値を送信側が一度も送っていなかったという、型レベルの送信漏れだった。

症状

キミテラス-v2 の広告配信は portal → v2 への K3 連携経由で行われる。v2 側の受信スキーマは、2026-06-14 の時点で次のように title を受理し、caption が無ければ title を caption として採用するフォールバックをすでに備えていた。

caption: nullableTrimmed(CAPTION_MAX),
// portal 素材タイトル（広告名）。「(無題の広告)」修正（運営整理 §4 / K3）: ads に専用の title 列は持たず
// **caption に流用**する（ユーザー判断 2026-06-14）。caption が明示指定されていればそれを優先し、無ければ
// title を caption として採用する（下の正規化）。月次レポート PDF は caption 未設定時のみ「(無題の広告)」に倒す。
title: nullableTrimmed(CAPTION_MAX),

実際のマッピングも、同じコミットで次の通り組まれている。

// 「(無題の広告)」修正: caption が無ければ portal 素材タイトル(title)を caption として採用する
// （title 専用列は持たず caption に一本化）。両方 null なら null（PDF が「(無題の広告)」に倒す）。
caption: a.caption ?? a.title,

ところが送信元の portal 側は、2026-07-25 まで DeliveryAd 型に title フィールドそのものを持っていなかった。

displayOrder: number;
/** Supabase 署名 URL（10 分有効）。v2 が GCS に再ホストする */
assetFetchUrl: string;
caption: string | null;
linkUrl: string | null;

caption は常に null で送られていたため（後述）、v2 側のフォールバック a.caption ?? a.title は null ?? undefined を評価することになり、caption は空のまま広告が配信されていた。型が合っているのでランタイムエラーは出ず、zod のバリデーションも通る。

この caption: null は、社内向け ops ダッシュボードの反応集計テーブルと、月次レポート PDF の両方で可視化される。

広告 (配信割当) ごとの反応。枠名は広告のタイトル
(caption)、未設定は「（無題の広告）」。既定は反応が多い順。
...
<strong key="caption">{a.caption ?? "（無題の広告）"}</strong>,

/** caption 未設定 / 削除済 広告の表示名 (CSV / 画面 `/admin/reports` と揃える)。 */
const UNTITLED_AD_LABEL = "（無題の広告）";
...
return caption ?? UNTITLED_AD_LABEL;

顧客向けの配信そのものにエラーは出ないが、この2つの社内画面を見ると、広告の枠名が全件「（無題の広告）」になっていることが分かる。

原因

送信側のコードを遡ると、DB からの creative 取得クエリ自体が title 列を選択していなかった。

const { data: creative, error: creErr } = await admin
  .from("creatives")
  .select("id, company_id, media_type, duration_sec, file_path, title, status")
  .eq("id", creativeId)
  .maybeSingle();

このコミット（cf19ac2）より前は、.select("id, company_id, media_type, duration_sec, file_path") と title を含んでいなかった。取得していない値は当然レスポンスにも組み込めず、送信時の構築処理でも caption: null が固定で設定されていた。

title: ((creative.title as string | null) ?? "").trim().slice(0, 60) || null,
caption: null,
linkUrl: null,

つまり経路は「DB からの取得クエリに列が無い → portal の型に title フィールドが無い → 送信 payload に値が乗らない → v2 側で caption が null のまま」という、1ステップ目の欠落がそのまま最後まで伝播する構造だった。v2 側の受信スキーマと変換ロジックは2026-06-14の時点で正しく実装されていたため、この間の約1ヶ月間、「受信側は対応済み、送信側だけが値を送っていない」という状態が続いていたことになる。

直し方

DB クエリに title 列を追加し、portal の型にも title: string | null を明示した上で、契約上限（60字）に合わせてトリムする処理を送信側に追加した。

.select("id, company_id, media_type, duration_sec, file_path, title, status")

/**
 * 素材タイトル（広告名）。K3 契約（partner-api-contract.md §3.4）は「portal は素材タイトルを
 * 必ず title（または caption）で送ること」。v2 は caption ?? title で ads.caption に流用し、
 * 月次レポート PDF の「（無題の広告）」フォールバックを両方 null の場合だけに限定する。≤60字。
 */
title: string | null;

// v2 の zod は title >60 字を 400（恒久）で弾くため、送信側で契約上限に切り詰める。
title: ((creative.title as string | null) ?? "").trim().slice(0, 60) || null,

受信側のフォールバックコードは一切変更していない。送信側が契約通りに title を送るようになった時点で、既存のフォールバックがそのまま機能し始めている。

再発防止

根拠ファイルには、この欠落を検知する仕組み（型レベルのスキーマ同期チェックや、送受信間の契約テストなど）についての記述は無い。修正はこの1点を含む9件の欠陥をまとめて棚卸しした監査コミットの一部として行われており、個別の再発防止策は明記されていない。

構造的に見れば、この種の欠落が見つかりにくいのは、受信側と送信側が別リポジトリ（v2 と portal）に分かれており、どちらの型チェックも「相手が何を送ってくるか／相手が何を受け取れるか」を跨いで検証しないためだ。送信側の型にフィールドが無くても、それ自体は単体のコンパイルエラーにならず、受信側が null をフォールバックで静かに吸収してしまうと、契約の片側だけが未実装のまま長期間気づかれずに残る。