Quartz 5

10_response_contract

3 min read

SearchAdd Response Contract

快速結論

search_add response 是 public contract。移植時不能任意改 key 名稱、大小寫或成功 / 錯誤格式。

current 入口：

SearchAddHandler::handle()
-> SearchAddResult
-> Endpoint/V1/SearchAdd.php::localizeLegacySearchAddMessage()
-> json response

新舊程式對應

Legacy PHP 5.6

主要入口：

/Users/mattsu/Documents/Site/get-lancer-php56/app/Plugin/Quotes/Controller/QuoteRequestsController.php::search_add()
legacy 區段職責
success response回 error=0、message=Success、user/session/request/bid。
warning response建單成功但 abnormal scan 命中時，仍帶 request，但 error 可能不是 0。
error response回 legacy error code 與多語 message。

Current PHP 8.2

current 位置職責
Lib/SearchAdd/SearchAddResult.php:32-35error response。
Lib/SearchAdd/SearchAddResult.php:37-46success response。
Lib/SearchAdd/SearchAddResult.php:48-63success with warning response。
Lib/SearchAdd/SearchAddResult.php:78-94組 public array。
Endpoint/V1/SearchAdd.php:110-117handler result 轉 response，移除 error_key 後輸出。
Endpoint/V1/SearchAdd.php:128-161legacy error message 多語轉換。

行號對照

new 行號對應 legacy職責
SearchAddResult.php:37-46QuoteRequestsController.php:3389-3398成功 response：error=0、message=Success、user/session/request/bid。
SearchAddResult.php:48-63QuoteRequestsController.php:3399-3402建單成功但 old keyword scan 命中時，改 warning error / message。
SearchAddResult.php:78-94QuoteRequestsController.php:3389-3403組 public response array。
Endpoint/V1/SearchAdd.php:110-117QuoteRequestsController.php:3403-3405輸出 JSON response。
Endpoint/V1/SearchAdd.php:128-161QuoteRequestsController.php:1884-1891, 1901-1909, 2103-2114, 2308-2332, 2336-2418, 2424-2437legacy error code 轉多語 message；current 內部 error_key 不輸出。

Success Response

成功格式：

{
  "error": 0,
  "message": "Success",
  "user_id": 123,
  "username": "user@example.com",
  "session_id": "token",
  "QuoteRequest": {},
  "QuoteBid": []
}

注意：

  • username 不應單獨作為 parity 判斷依據。
  • QuoteBid 只代表同步主線當下可見結果。
  • async fallback 不保證已反映在同一次 response。

Warning Response

abnormal scan 命中舊關鍵字時，可能是建單成功但 response 帶 warning error。

current 對應：

SearchAddHandler.php:271-286
SearchAddResult::successWithWarning()

這類 response 仍要看 QuoteRequest 是否已建立，不可只因 error != 0 就判定建單失敗。

Error Response

錯誤格式：

{
  "error": 13,
  "message": "目前系統異常請稍後再試(13)"
}

注意：

  • error_key 是 current 內部輔助資訊，endpoint 輸出前會 unset。
  • legacy public contract 看 error 與多語後 message。
  • 不要把內部 exception key 當成前端 contract。

不可改變的契約

  • success key 使用 message，不是 status。
  • success message 是 Success。
  • QuoteRequest / QuoteBid key 大小寫不可改。
  • error response 不輸出 error_key。
  • warning response 仍可能包含 QuoteRequest / QuoteBid。

Verification

主要測試：

tests/SearchAddStep2IntegrationTest.php
tests/SearchAddStep8IntegrationTest.php

比對時確認：

  • key name
  • key casing
  • success / warning / error 的 body shape
  • legacy 多語後文字

待確認 / 風險

  • 本頁先固定 response contract；後續每補一個 special flow 實測，都要把該 flow 的 public response 範例補回來。

Graph View

Backlinks