SearchAdd Legacy Canonical Rules
這份文件定義 search_add legacy audit 的判斷方式。
核心原則：先建立 legacy 本身的完整規則，再做 current 對照。
details/* 的 new / legacy 行號對照只能證明「已看到的點是否對齊」，不能證明 legacy 規則沒有漏。
文件分工
| 文件 | 用途 |
|---|---|
| legacy_canonical_rules.md | 定義 audit 方法、phase 順序、驗證面。 |
| legacy_rule_matrix.md | 逐條列 legacy rule、狀態、source、current owner、測試與缺口。 |
| legacy_alignment.md | 高層 topic 對齊摘要。 |
| legacy_alignment_map.md | topic-level mapping。 |
| details/README.md | current / legacy 分段對照與 code review 細節。 |
Audit Workflow
每次檢查或修改 search_add parity，照這個順序：
- 先看 legacy_rule_matrix.md 是否已有 rule。
- 如果沒有 rule，先新增 rule，狀態標
needs_legacy_reaudit。 - 只讀 legacy code，補齊：
- source 行號
- precondition
- 執行順序
- sync / async 邊界
- side effects
- rollback / retry 邊界
- 再回 current 找 owner class / method。
- 補 test 或 baseline。
- 最後才更新
details/*與legacy_alignment.md。
禁止用 current 實作反推 legacy 完整規則。
Status
| Status | 意義 |
|---|---|
needs_legacy_reaudit | 從既有 migration docs 反推，尚未從 legacy code 單向 audit 完成。 |
legacy_traced | 已從 legacy code 補齊 source、precondition、順序與 side effect。 |
current_mapped | 已完成 legacy trace，且已對到 current owner；測試或 helper 細節可能仍可補強。 |
verified | legacy trace、current mapping、測試或 baseline 都完成。 |
gap | 已知 current 行為或測試覆蓋不足。 |
Phase Timeline
phase number 是文件用的穩定排序，不代表 legacy 原始行號。
| Phase | 名稱 | 責任 |
|---|---|---|
| 000 | input normalization | raw request、form payload、summary、phone / landing / match type raw 值。 |
| 100 | actor resolution | session、credential、social login、auto signup、login side effects。 |
| 200 | pre-create guards | category / form / request conflict / risk 類建單前 guard。 |
| 300 | request fee and type preparation | category 規則、match type、fee 欄位、request 建立前必要資料。 |
| 400 | quote request create | 建立 quote_requests 主表與直接依賴欄位。 |
| 500 | request side writers | form submission、summary、tracking、abuse、abnormal scan、landing / actor side log。 |
| 600 | auto quote matching | provider candidate、auto quote filter、narrow fallback、additional narrow 補位。 |
| 700 | bid finalize | bid row、pricing、price note、activity、cache / counter。 |
| 800 | special flows | preserve、authorized contact、direct reserve、direct user、booking 類特殊入口。 |
| 900 | async fallback | newQuoteRequest、newNarrowMatch、manual / related fallback。 |
| 1000 | response contract | success / warning / error response、public message mapping。 |
| 1100 | shared downstream methods | contact provider、payment、transaction、subscription log、notification、external event。 |
High-Risk Order
先 audit 這幾條，因為最容易漏 shared side effect 或順序：
| Priority | Rule | 風險 |
|---|---|---|
| 1 | SA-LEGACY-1101 shared contact provider method | payment、transaction、notification、external event 都藏在 shared helper。 |
| 2 | SA-LEGACY-0802 authorized contact branch | search_add special flow 會進 shared contact method。 |
| 3 | SA-LEGACY-0803 direct reserve branch | 有 match 前 budget、reserve rows、contact payment、fallback。 |
| 4 | SA-LEGACY-0804 direct user branch | caller fee / budget option 會影響 shared contact method。 |
| 5 | SA-LEGACY-0601 auto quote candidate and filter order | provider pool 與 filter order 會影響後續所有 bid。 |
| 6 | SA-LEGACY-0701 bid finalize and pricing fields | pricing、activity、counter 容易只比到部分欄位。 |
| 7 | SA-LEGACY-0901 async fallback | response 成功不代表 worker side effect 已完成。 |
Verification Surface
每條 rule 不能只看 API response。最低驗證面如下：
| 類型 | 必查內容 |
|---|---|
| request materialization | quote_requests、form submission、summary、match info |
| sync match | provider pool、quote_bids、bid flags、pricing、activity、counter |
| payment / contact | transactions、quote_user_subscription_logs、wallet、credit card / TapPay result、application log |
| async / notification | queue-or-log 任一存在、payload / template、worker log |
| external side effect | 對應 util / event log；若無法實送，需有 mock 或明確待確認 |