legacy_alignment

SearchAdd Legacy Alignment

這份文件只保留高訊號結論。

目的：

• 說明哪些主題已完成 legacy 對齊
• 提供新舊入口
• 告訴維護者應看哪個 test

topic-level 對照索引看 legacy_alignment_map.md。

legacy 完整規則與執行順序以 legacy_canonical_rules.md 和 legacy_rule_matrix.md 為準。這份 alignment 只回答「目前 current mapping / tests 對齊狀態」，不能用來證明 legacy 規則沒有遺漏。

狀態定義

• verified
  • 已回查 legacy code
  • 已確認 current 對應入口
  • 已有測試或明確驗證依據
• needs_review
  • 尚未完成最後確認
• gap
  • 已確認 Current Legacy 與 PHP 8 行為不同，尚未實作或尚缺 reviewer decision

Alignment Table

Topic	Legacy	Current	Status	Verification	Notes
request_normalize	QuoteRequestsController::search_add()	SearchAddRequestNormalizer + SearchAddInput	verified	SearchAddInputTest, SearchAddStep2IntegrationTest	checkbox / multi-select、FormSummary、phone、landing page、match_type 已對齊
actor_resolution	QuoteRequestsController::search_add() actor/login branches	CredentialActorResolver + AutoSignupService	gap	CredentialActorResolverTest, SearchAddLineIdentityRepositoryIntegrationTest, SearchAddStep8IntegrationTest	PHP 8 fb8897d7 已完成 LINE / line_users；尚餘 device-only 與 existing-session reuse 差異。見 newstaging_delta_audit_2026-08-05.md。
request_create	QuoteRequestsController::search_add() request create section	QuoteRequestCreator	verified	SearchAddStep2IntegrationTest	request row 主欄位、location、fee 相關同步值已對齊
request_side_writers	controller request-side writes	request-side writers under SearchAddHandler	gap	SearchAddStep4IntegrationTest	NewStaging inner_text 需另寫 quote_request_inners 並從 downstream Form 移除；PHP 8 尚未實作。
auto_quote_match	QuoteService::_handleAutoQuoteMatch()	AutoQuoteMatcher	verified	SearchAddStep5IntegrationTest	candidate pool、narrow 邊界、一般 auto quote 的 charge / debt transaction metadata 已對齊
bid_finalize	QuoteService::handleAutoQuote()	QuoteBidFinalizer + BidPricingResolver	verified	SearchAddStep6IntegrationTest	price_note、pricing_unit、quote flags 已核對
special_flows	controller special branches	SpecialFlowDispatcher + processors	verified	SearchAddStep7IntegrationTest, SearchAddStep8IntegrationTest, TapPayCreditCardApiTest	authorized / preserve / direct reserve / direct user / booking 已核對；authorized 已對齊 processWantToContactProvider() 主線、付款 decision、receipt / notify payload 與 gateway result mapping；booking auto_quote_sent_count 已回到 matcher 主線更新
manual_related_fallback	checkR1ManualMatchStartNoAutoQuote() + _handleNewQuoteRequest()	SearchAddHandler + QuoteRequest + NewQuoteRequestHandler	verified	SearchAddStep9IntegrationTest	這是 async fallback，不屬於同步 response 保證

判讀提醒

• 不要把同步 response 和 async fallback 混在一起判斷
• staging case 只能輔助，不應取代 code trace 與 test
• 任何 verified topic 都應能在 map 與 test 中找到對應依據

固定驗證順序

每個 topic 至少都要回答這 5 件事：

1. legacy 真正入口在哪裡
2. current 對應入口在哪裡
3. 這段屬於同步行為還是 async 行為
4. 已有哪些測試覆蓋
5. 目前狀態是 verified 還是 needs_review

固定排查順序：

1. 先確認 rule 是否已存在於 legacy_rule_matrix.md
2. 若 rule 尚未完成 legacy 單向 audit，先更新 canonical rule，不直接改 current mapping
3. 再確認 topic 是否已存在於 legacy_alignment_map.md
4. 開 legacy 檔案確認真正入口，不要只看舊文件描述
5. 開 current 檔案確認對應入口與責任邊界
6. 確認這段屬於：
   • request normalize
   • sync auto / narrow / finalize
   • async fallback
   • special flow
   • shared downstream method
7. 找對應 test；沒有 test 就不能標 verified
8. 最後才更新這份 alignment 與 map

禁止事項：

• 不要只憑 staging response 就標記 verified
• 不要把 async flow 誤寫成同步 response 契約
• 不要把排查過程日誌直接塞進 alignment 主文件
• 不要讓同一個 topic 同時散落在多份文件，用 map 當單一真相來源
• 不要用 current 對照表反推 legacy 完整規則；必須先回到 canonical rule
• migration 建立新資料列時，不可用 SELECT * FROM <table> ... LIMIT 1 抓既有 row 當 insert template；必須用 explicit allowlist 欄位，逐欄對應 legacy 或 schema default

Baseline 抓取方式

如果要做舊版 / 新版 parity baseline，固定用同一套順序：

1. 用舊版呼叫 search_add
2. 保留完整 request / response
3. 記下至少：
   • quote_request_id
   • 必要時加 user_id
4. 先抓主表：
   • quote_requests
   • quote_form_submissions
   • quote_form_submission_fields
   • quote_request_match_infos
   • read_segment_9_matches
   • quote_bids
   • quote_activities
   • task_queue
   • 其他該 case 特有 downstream tables
5. 再用新版送同一組 request
6. 用同一份表清單抓新版結果

最低比對單位固定分三層：

1. request materialization
2. sync match result
3. async / downstream result

判讀原則：

• 先比 request materialization，再比 bid，不要反過來
• 先看 provider 名單，再看 bid 欄位
• search_add 當次 response 不等於全部流程完成
• async fallback 要用 task_queue 與後續寫表一起判斷