SearchAdd Detail 文件
這個目錄用來補齊 search_add 的新舊程式對應。
上層文件維持高訊號結論：
- index.md
- legacy_canonical_rules.md
- legacy_rule_matrix.md
- legacy_alignment.md
- legacy_alignment_map.md
detail 頁負責把每段 migration 拆到可以 code review、補測試、查 DB baseline 的粒度。
注意：detail 頁是 current / legacy 對照文件，不是 legacy 完整規則來源。判斷是否漏 legacy 規則、順序或 shared helper side effect 時，先看 canonical rule matrix，再回到對應 detail 頁補 current mapping。
拆分原則
search_add 不寫成單一大文件。這支 API 同時包含 actor、建單、form、match、付款、通知、async fallback；如果全部塞在一頁，之後很難看出哪段已對齊、哪段仍待驗。
固定拆成下列主題：
| 文件 | 主題 | 狀態 |
|---|---|---|
| 00_overview.md | detail 文件地圖與同步 / async 邊界 | checked |
| 01_request_normalization.md | raw request 正規化與 SearchAddInput | checked |
| 02_actor_resolution.md | session / credential / auto signup actor 解析 | gap：LINE 已完成；device-only / existing-session reuse 待處理 |
| 03_pre_create_guards.md | 建單前 category / form / risk / conflict guard | checked |
| 04_request_create.md | 建立 quote_requests 主表 | checked |
| 05_request_side_writers.md | form、landing、summary、tracking 等 request side writers | gap：NewStaging inner_text |
| 06_auto_quote_match.md | auto quote / narrow match / 同步收費 | checked |
| 06_auto_quote_filters.md | auto quote filter、narrow 候選池與補位規則 | checked |
| 07_bid_finalize.md | bid finalize、price note、pricing unit、cache / activity | checked |
| 08_special_flows.md | authorized / preserve / direct reserve / direct user / booking | checked |
| 09_async_fallbacks.md | manual / related fallback 與 queue / worker 邊界 | checked |
| 10_response_contract.md | success / warning / error response 格式 | checked |
每篇固定格式
每篇 detail 都應該包含：
## 快速結論## 新舊程式對應## 行號對照## Side Effects## 不可改變的契約## Verification## 待確認 / 風險
## 行號對照 優先使用這個格式：
| new 行號 | 對應 legacy | 職責 |
|---|---|---|
120-131 | 3725-3734 | 讀取資料或建立 payload。 |
規則：
- 行號可以漂移；文件要保留「區塊職責」，review 時以職責為主、行號為定位輔助。
- 如果 current 把 legacy 一段拆到多個 class，表格中直接列多列，不要硬合併。
- 如果尚未確認精確 legacy 行號，先寫
待補，不要假裝已對齊。 - 發現 current 與 legacy 語意不一致時，直接寫進
待確認 / 風險。 - 發現 detail 裡有 legacy 規則但 legacy_rule_matrix.md 尚未建 rule，先補 rule，再補 detail。
寫法規則
- legacy 來源以目前指定的
NewStagingcheckout 為準：/Users/mattsu/Documents/Site/get-lancer-docker-2/get-lancer/app/Plugin/Quotes/...
- current 來源以 PHP 8.2 專案為準：
/Users/mattsu/Documents/Site/pro360_api_82/...
verified必須同時有 code trace 與 test / baseline 依據。checked表示本文件的 current / legacy 行號與既有測試規則已在 2026-05-15 逐段核對；仍可在各 detail 的待確認 / 風險留 SQL-level 或案例-level 補強項。checked不等於 canonical legacy rule 完整；若 canonical matrix 仍標needs_legacy_reaudit，就表示還需要從 legacy 單向補完規則。- 不確定的地方先標
待確認，不要硬寫成一致。 - response contract 一律記錄實際 public payload，不只記內部 exception key。
- queue / worker 結果要接受 queue 或 log 任一存在，避免把 worker 已搬走誤判成未送。
Current Legacy branch
- 2026-08-05 起，本輪 search_add parity 以 Legacy
NewStaging為準。 - NewStaging delta 主文件：newstaging_delta_audit_2026-08-05.md。
checked的舊結論若和 delta 文件衝突，以最新 Legacy code trace 與 delta 文件為準；未實作前不可標回verified。