# 制約で候補を選ぶ機能が全滅する事故を止める — 判定用属性マスタの分離と、提示前の実在庫確認 「条件に合う候補を選んで提示する」機能（駐車場・宿・レンタル機材・輸送手段・会場など）で、 **提示した候補が一件も使えない**という全滅事故を止めるための設計指示書。 対象読者は AI コーディングエージェント、および候補選定を任される AI エージェント。 --- ## 実際に起きた事故（この型が生まれた経緯） ある業務システムが、運搬車両の一覧マスタを持っていた。列は `長さ / 幅 / 高さ`。 このマスタを使って「候補地」を選定したところ、挙げた候補が**全件、物理的に入らなかった**。 原因は3つ重なっていた。 1. **同名別義**: マスタの `長さ/幅/高さ` は積載量を計算するための**内寸**だった。 候補選定に必要なのは**外寸**。名前が同じなので誰も気付かず、下流が全部ずれた。 実際の外寸は内寸の想定より **99cm 高かった**（内寸2,050mm に対し実高2,970mm）。 2. **区分の取り違え**: 対象を「大型」と決めつけて絞り込んでいたが、 公的な登録上は一段下の区分だった。**自分で候補を狭めて選択肢を失っていた**。 3. **規約による除外を見ていなかった**: 寸法が収まっていても 「特定区分の登録車はお断り」という規約で弾かれる候補が複数あった。 さらに運用面で、 4. **在庫を確認せずに順位表を出した**: 条件だけで10件を順位付けして提示したところ、 対象日は**予約制の候補が全滅**していた。順位表そのものが無価値になり、丸ごとやり直し。 --- ## 設計指示 ### 1. 「計算用の寸法」と「判定用の寸法」を別マスタに分ける 同じ `長さ/幅/高さ` でも、**容量計算に使う値**と**物理的に入るかを判定する値**は別物。 1つのテーブルに同名で同居させない。分離したうえで、**両方のファイル冒頭に用途を明記する**。 ```js /** * ⚠️ <容量マスタ> が持つ 長さ/幅/高さ は【内寸】であり、 * 入場可否・制限判定には使えない。判定は必ずこのファイルの【外寸】を使う。 */ 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. 判定は「除外理由を返す」関数にする 真偽値だけ返すと、なぜ落ちたかが分からず候補探しが進まない。 ```js 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 にした - [ ] 規約による除外を寸法と独立に判定している - [ ] 検索条件（必須・除外・確認）を機械が出力している - [ ] **候補を提示する前に対象日の実在庫を確認した** - [ ] **予約不要の代替候補を併記した** - [ ] 帳票に担当者名と連絡先が出て、未アサイン・空欄が警告される ---