Quartz 5

endpoint_migration_checklist

4 min read

endpoint migration checklist

目的

這份 checklist 用於把 legacy CakePHP endpoint 搬到 pro360_api_82，或確認 new API 是否已相容 legacy path。

1. 確認 legacy 使用情境

  1. 查正式 / staging access log，確認 path 是否仍有流量。
  2. 記錄 legacy URL pattern，但不要把一次性 token / session 放進文件。
  3. 確認 HTTP method、.json / .xml format、path params、named params、body params。

2. 找 legacy controller / action

  1. 查 app/Config/routes.php。
  2. 查 app/Config/cms_routes.php。
  3. 依 CakePHP convention 找 controller/action。
  4. 追 controller action 內使用的 model/domain method。
  5. 記錄 actor：consumer、provider、requestor、admin、worker。

3. 找 new API route

  1. 查 Lib/Common/RouterRule/Mapping.php 是否已有 legacy-compatible path。
  2. 若有 mapping，確認：
t -> Endpoint/V1 file
r -> action / rewritten params
  1. 若沒有 mapping，確認 Origin / File fallback 是否可解析。
  2. 查 Endpoint/V1/<Endpoint>.php 是否有 action method。
  3. 確認 endpoint 如何讀：
rawParams
named params
POST body
headers

4. 決定是否補 Mapping.php

需要補 mapping 的常見情況：

  • legacy URL 和 new endpoint/action 名稱不同。
  • path params 需要改寫成 named params。
  • legacy URL 沒有 /v1/，但不能靠 File fallback 穩定解析。
  • 同一 endpoint action 需要支援舊 URL pattern。
  • change_status 這類 filter path 需要拆到多個 action。

不一定需要補 mapping 的情況：

  • File fallback 已能穩定解析 legacy-compatible path。
  • Origin path 是新 API 原生 path，且外部 client 沒有 legacy 相容需求。

5. 對照 auth / session / headers

確認 legacy 與 new API 是否一致：

X-PRO360-Rest-Api-Key
X-PRO360-User-Session-Token
security hash
global API key exception
request owner / provider guard

詳細規則見 專案身份驗證方式。

6. 對照 response contract

確認：

success body
success body 是否允許多出欄位
error code
status/message key
HTTP status
extends/context fields
bank_result_code / bank_result_msg

不要只看 exception message；legacy controller handler 可能會把 message key 翻譯成文字。

不要用其他 filter / endpoint 的 response pattern 推論這支 API。例如 legacy 成功只回 {"status":"Success"} 時，new API 不可自行新增 error:0。

詳細規則見 api_response_contract。

7. 對照 side effect

至少確認：

main table state
activity
transaction / payment
message
event_queue / event_queue_log_1..event_queue_log_4
task_event_queue / task_event_queue_log
application log

Queue 驗證要接受 queue 或 log 任一存在。

8. 實作與測試

  1. 優先重用既有 domain method。
  2. 若補 route，更新 Mapping.php。
  3. 補 endpoint action 時保持 legacy response contract。
  4. 補 PHPUnit 覆蓋 guard、成功 path、主要 side effect。
  5. 涉及 queue 時測試接受 queue-or-log。
  6. 涉及 DB / schema 查詢時依 repo AGENTS 規則使用容器 PHP + DBFactory。

9. 文件更新

  1. 專案 migration docs 記錄 legacy/new 對照、測試狀態、暫時性 migration 結論。
  2. Common Process Documents 只抽長期規則。
  3. 若是 route 規則，更新本資料夾。
  4. 若是付款、queue、auth、設定，更新對應共同文件。

最小檢查表

[ ] legacy URL / method / params 已確認
[ ] legacy controller/action 已確認
[ ] legacy model/domain method 已確認
[ ] new Mapping.php 已查
[ ] new endpoint/action 已查
[ ] 是否需補 Mapping 已決定
[ ] rawParams / params / body 對照完成
[ ] auth/session/security hash 對照完成
[ ] response contract 對照完成
[ ] success response 是否可多欄位已明確確認
[ ] DB side effect 對照完成
[ ] queue/log 判斷規則已納入測試
[ ] 專案 migration docs 已更新
[ ] 長期規則已抽到 Common Process Documents

Trace 範例

  • 案例/provider_accept_narrow_match：示範如何從外部 URL 查 ALB/access log、找 legacy CakePHP controller/action、對照 new API RouterV3 / Mapping / File fallback，並確認 path params 如何進 endpoint。

Graph View

Backlinks