制約で候補を選ぶ機能が全滅する事故を止める — 判定用属性マスタの分離と、提示前の実在庫確認

「条件に合う候補を選んで提示する」機能（駐車場・宿・レンタル機材・輸送手段・会場など）で、 提示した候補が一件も使えないという全滅事故を止めるための設計指示書。

対象読者は AI コーディングエージェント、および候補選定を任される AI エージェント。

---

実際に起きた事故（この型が生まれた経緯）

ある業務システムが、運搬車両の一覧マスタを持っていた。列は 長さ / 幅 / 高さ。 このマスタを使って「候補地」を選定したところ、挙げた候補が全件、物理的に入らなかった。

原因は3つ重なっていた。

1. 同名別義: マスタの 長さ/幅/高さ は積載量を計算するための内寸だった。 候補選定に必要なのは外寸。名前が同じなので誰も気付かず、下流が全部ずれた。 実際の外寸は内寸の想定より 99cm 高かった（内寸2,050mm に対し実高2,970mm）。
2. 区分の取り違え: 対象を「大型」と決めつけて絞り込んでいたが、 公的な登録上は一段下の区分だった。自分で候補を狭めて選択肢を失っていた。
3. 規約による除外を見ていなかった: 寸法が収まっていても 「特定区分の登録車はお断り」という規約で弾かれる候補が複数あった。

さらに運用面で、

4. 在庫を確認せずに順位表を出した: 条件だけで10件を順位付けして提示したところ、 対象日は予約制の候補が全滅していた。順位表そのものが無価値になり、丸ごとやり直し。

---

設計指示

1. 「計算用の寸法」と「判定用の寸法」を別マスタに分ける

同じ 長さ/幅/高さ でも、容量計算に使う値と物理的に入るかを判定する値は別物。 1つのテーブルに同名で同居させない。分離したうえで、両方のファイル冒頭に用途を明記する。

/**
 * ⚠️ <容量マスタ> が持つ 長さ/幅/高さ は【内寸】であり、
 *    入場可否・制限判定には使えない。判定は必ずこのファイルの【外寸】を使う。
 */
const EXTERIOR_SPECS = {
  '<対象A>': {
    lengthMm: 4690, widthMm: 1690, heightMm: 2970,
    weightKg: 6145,
    registrationClass: '<公的区分>',   // 区分は推測せず一次資料から
    feeClass: '<料金区分>',
    confirmed: true,                    // 一次資料で裏取り済みか
    note: '実高は付帯装備込み2,970mm。登録簿上の1,980mmを使わないこと'
  },
  '<対象B>': { /* ... */ confirmed: false }  // 代表値は必ず false
};

confirmed を必ず持たせる。 代表値・推定値と一次資料の実測値を混ぜない。 帳票に出すときは confirmed:false に「（代表値・要確認）」を付ける。

2. 一次資料から取る。二次情報の区分ラベルを信じない

• 寸法・重量・区分は登録簿・仕様書・現物のマニュアルから取る
• 同一項目で資料が食い違うことがある。上の事故では登録簿の高さ（1,980mm）と 運用マニュアルの高さ（2,970mm）が違い、運用マニュアル側が正しかった （付帯装備を後付けしていたため）。保守的な方（大きい方）を採用する
• 候補側サイトの「〇〇対応」バッジは当てにならない。同じ候補が 一方のサイトで「大型可」、公式仕様で「高さ2.1m制限」と表示されていた実例がある。 必ず数値の制限表記に当たる

3. 判定は「除外理由を返す」関数にする

真偽値だけ返すと、なぜ落ちたかが分からず候補探しが進まない。

function evaluateCandidate(targets, candidate) {
  // candidate: { name, lengthMm, widthMm, heightLimitMm(null=制限なし),
  //              形態, 24時間利用可, 夜間継続利用可, 除外区分 }
  return { ok, ng: ['<落ちた理由と数値>'], warn: ['<条件付きで使える理由>'] };
}

• heightLimitMm が null（制限なし）なら通す
• クリアランスが閾値未満なら ok にせず warn にする。 上の事故対象は「制限300cm に対し実高297cm」という候補を挙げてしまった。 3cm は運用上ゼロと同じ。30cm 未満は非推奨として明示する
• 規約による除外（除外区分）は寸法と独立に判定する。 寸法が通っても規約で落ちる候補があるため

4. 検索条件そのものを機械が出力する

人間が条件を口伝えすると毎回抜ける。必須・除外・確認の3分類で自動生成し、帳票に印字する。

【検索条件】長さ<最大>以上 / 幅<最大>以上 / 高さ制限なし（または<実高+30cm>以上）
【必須】<形態の指定> / 24時間利用可 / 夜間継続利用可
【除外】<高さ制限が構造的に低い形態> / <営業時間が区切られる施設> / <1枠しかない個人提供型>
【確認】連続利用の上限時間（規約） / 台数分を同一場所で取れるか /
        <除外区分>お断りの規約がないか / 近隣配慮が要る立地か

除外リストは構造的に落ちるカテゴリを列挙する。上の事故では 立体・地下・機械式が高さ2.0〜2.1m で全滅し、施設併設型は夜間閉鎖で全滅した。 カテゴリ単位で最初から外すのが探索コストを最も下げた。

5. 候補を提示する前に、対象日の実在庫を確認する

これを飛ばすと、条件が完璧な順位表がまるごと無駄になる。

• 予約制サービスは詳細ページに日付ごとの 空／満／予約不可 が出る。出す前に対象日を見る
• 「全日満」を示す文言（例:「予約の空きがありません」）を検出したら、その候補は落とす
• 空きが確認できなかった候補は、確認済みと混ぜず「空き未確認」と明記する。推測で ○ にしない
• 予約制が満のときに備え、予約不要（先着）の候補を必ず併記する。 予約制だけを並べると満車のとき打つ手がゼロになる
• 予約不要は当日満車のリスクがあるので、収容数の多い大箱を優先する

6. 帳票に「担当者と連絡先」を出す

候補や手配が決まっても、「これは誰が担当か」が帳票に無いと人力照合が発生する。 上の事故と同じ現場で、チャットに「これの担当は誰か」という問い合わせが繰り返し出ていた。 担当者表は別シートに存在していたのに、帳票側に出ていないのが原因だった。

• 担当者マスタ（既存の名簿シート等）から、役割名に担当キーワードを含む行を拾う
• 役割名から対象を判定する別名辞書を持つ（表記ゆれが必ずある）
• 未アサインの対象と、連絡先が空欄の担当者を警告付きで出す。 空欄を黙って飛ばすと、抜けたまま当日を迎える
• 列は位置ではなくヘッダ名で解決する（完全一致→前方一致）。現場は列を足す

---

検証手順

1. 判定関数の単体テスト
   • 制限なし → ok
   • 制限が実寸をわずかに上回る（クリアランス閾値未満）→ warn に数値付きで出る
   • 制限が実寸を下回る → ng
   • 構造的に落ちる形態 → ng
   • 規約による除外区分に該当 → ng（該当対象名が理由に入る）
2. 担当者取得の単体テスト
   • ヘッダに説明文が付いていても前方一致で解決できる
   • 同名列が2つあると警告が出て左側が採用される
   • 必須列が無いと missing が警告に入る
   • 別名辞書で表記ゆれが吸収される
3. 実データで1件通し、帳票に 「検索条件 / 必須 / 除外 / 確認」「担当者と連絡先」「未確認項目」が出ることを目視確認

チェックリスト

• 容量計算用と判定用の寸法を別マスタに分け、両方に用途コメントを書いた
• 各値に confirmed を持たせ、代表値と実測値を区別した
• 区分は一次資料から取り、推測で「大きい方の区分」に寄せていない
• 資料間で値が食い違う場合、保守的な方を採用した
• 判定関数が除外理由を数値付きで返す
• クリアランス閾値を設け、僅差を warn にした
• 規約による除外を寸法と独立に判定している
• 検索条件（必須・除外・確認）を機械が出力している
• 候補を提示する前に対象日の実在庫を確認した
• 予約不要の代替候補を併記した
• 帳票に担当者名と連絡先が出て、未アサイン・空欄が警告される