SearchAdd 文件入口

這組文件對應 SearchAdd.php。

狀態：POST /quote_requests/search_add.json 已搬到新專案，由 Endpoint/V1/SearchAdd.php 與 Lib/SearchAdd/ 主流程維護。2026-08-10 複核：LINE actor / 綁定已由 PHP 8 commit fb8897d7 完成並推到 origin/NewStagingForPHP82_search_add；尚未進入 NewStagingForPHP82 / staging。Current Legacy parity 仍剩 device-only、search_add existing-session reuse 與 inner_text 三項；另有 PHPUnit CLI session 相容性待處理。詳細見 newstaging_delta_audit_2026-08-05.md。

目的只有三個：

• 讓人快速理解 search_add API 的公開契約
• 讓後端工程師能沿著主流程排查 request、配對與後續 task
• 讓新舊版 parity 驗證有固定入口，不再依賴零散筆記

閱讀順序

如果你是第一次看這條 API，建議順序如下：

1. api_contract.md
2. request_lifecycle.md
3. match_and_finalize.md
4. async_fallbacks.md
5. legacy_alignment.md

如果你是要確認 legacy parity，直接看：

• legacy_canonical_rules.md
• legacy_rule_matrix.md
• legacy_alignment.md
• legacy_alignment_map.md
• details/README.md

文件地圖

• api_contract.md
  • 給前端、QA、串接方
  • 說明 request / response / error / 同步可見結果
• request_lifecycle.md
  • 給後端工程師
  • 說明 SearchAddHandler 主流程、early return、同步主線與後續非同步流程
• request_normalization.md
  • 專講 SearchAddRequestNormalizer / SearchAddInput
• match_and_finalize.md
  • 專講 auto quote、narrow、bid finalize
• async_fallbacks.md
  • 專講 newQuoteRequest、manual / related fallback 等非同步流程
• legacy_alignment.md
  • 對齊狀態表、baseline 抓法、固定驗證順序
• legacy_canonical_rules.md
  • 以 legacy runtime 單向整理完整規則、順序、sync / async 邊界與 side effects
• legacy_rule_matrix.md
  • legacy rule ledger；判斷是否漏規則時先看這份，不以 current 對照表取代
• details/README.md
  • 分段追 search_add 新舊程式對應；每個 detail 頁固定寫 legacy / current / side effect / contract
• authorized_manual_verification.md
  • authorized flow 的手動驗證、Postman、DB 檢查與清資料
• legacy_alignment_map.md
  • topic-level 對照索引
• newstaging_delta_audit_2026-08-05.md
  • Current Legacy NewStaging 最新差異；LINE、device、session、inner_text 的實作範圍與測試清單

核心原則

• search_add 的 success response 只代表同步主線完成，不代表所有 legacy 後續流程都已同步反映在 response 內
• manual / related fallback 屬於後續 newQuoteRequest task，不應直接以當次 response 是否有 non-narrow bid 判斷流程缺漏
• legacy parity 必須先有 legacy canonical rule，再做 current mapping；只做 new / legacy 行號對照不能證明 legacy 規則完整
• legacy parity 判斷要分三層看：
  • request normalize / create
  • sync auto / narrow / finalize
  • async fallback / downstream task