new API routing

目的

整理 pro360_api_82 的 API path 如何對應到 endpoint / action。

這份文件聚焦 new API routing。若要從 legacy path 搬移 endpoint，請先看 endpoint_migration_checklist；legacy CakePHP route 規則見 legacy_cakephp_routing。

主要來源：

Lib/Common/RouterV3.php
Lib/Common/RouterRule/Mapping.php
Lib/Common/RouterRule/Origin.php
Lib/Common/RouterRule/File.php
Lib/Common/RouterRule/RouterRuleAbstract.php
Lib/Common/Router.php
Lib/Common/RouterV2.php

目前查 API path 優先看 RouterV3.php 與 RouterRule/*。

RouterV3 主規則

RouterV3::dispatch() 會先做：

removeQueryString()
removeLanguageCode()
denyDDOS()

然後依序套用：

PRO360\Common\RouterRule\Mapping
PRO360\Common\RouterRule\Origin
PRO360\Common\RouterRule\File

只要其中一個 rule 成功，就用該 rule 產生：

endpointName
actionName
preRoutes
rawParams
params

因此 migration 時不能只看 Endpoint/V1/*.php 是否有 method；也要先確認 path 是否被 Mapping.php 特別改寫。

Mapping.php

Mapping.php 是 legacy path / 特殊 path 的明確對照表。

每條 mapping 通常包含：

'legacy/path/pattern' => [
    'r' => 'rewritten/action/params',
    't' => 'V1/EndpointFile.php',
]

欄位意義：

key	意義
`r`	rewrite 後的 action / path params
`t`	要 include 的 endpoint file

例子：

quote_requests/search_add.json
-> r = index
-> t = V1/SearchAdd.php

quote_bids/change_status/read/{id}.json
-> QuoteBids::change_status_read()

Mapping.php 也會把 path params 改寫成 rawParams / named params。例如：

quote_bids/change_status/archive/123.json
-> change_status_archive/quote_bid_id/123/filter/archive

Origin.php

Origin.php 處理比較直接的 /v1/<endpoint>/<action> 類 path。

規則重點：

path 必須符合 ^(v[0-9]+)/([0-9a-zA-Z_]+)
endpoint file 由 path 推導
action 由剩餘 path 第一段推導

如果 path extension 是 .json / .xml，會先移除 extension。

.orig / .bak 會被視為危險 extension 並 redirect / log。

File.php

File.php 是 fallback rule，會嘗試依 path 找 endpoint file。

重點：

如果第一段不是 vN 或 admin，會自動補 v1

這就是為什麼有些舊 path 即使不在 Mapping.php，仍可能靠 endpoint file / action method 被解析。

Router.php / RouterV2.php

Router.php 和 RouterV2.php 是舊版 router 實作或相容實作。新查 path 時優先看 RouterV3.php，但遇到老流程、CLI compose、或特殊 entrypoint 時仍可能需要回查。

從 new endpoint 找外部 URL

先查 Mapping.php 是否有 legacy compatible path。
再查是否可用 /v1/<endpoint>/<action>.json 或 fallback path。
注意 Mapping.php 可能會把同一 endpoint action 暴露成多個 URL。
最後查 AWS ALB access log、專案 migration overview 或既有 access log 紀錄，確認實際流量 path。

目前 pro360_api_82 可從 Endpoint/V1/In.php::load_api_logs() 看到 ALB log 匯入線索；來源是 pro360-alb-logs 的 Application Load Balancer log，匯入後會寫到 alb_log2s。實際統計結果屬於 migration evidence，放專案 migration detail，不放在這份長期 route 規則文件。

常見陷阱

有 endpoint method 不代表 legacy path 一定能打到它。
沒有 Mapping.php 不代表 path 一定不能用，可能走 File fallback。
Mapping.php 會改寫 action 名與 params，不能只用 URL 字面判斷。
.json extension 會被 router 移除或處理，不一定是 raw path 的一部分。
多語系 path 可能先被 RouterV3::removeLanguageCode() 改寫。
rawParams 和 named params 來源不同，migration 時要追到 endpoint 實際怎麼讀。

和其他文件的關係

API auth header / session：專案身份驗證方式
業務流程入口：業務流程
route not found / exclude method log：Log 與告警流程
legacy routing：legacy_cakephp_routing
endpoint migration checklist：endpoint_migration_checklist
project config source：pro360_api_82

Quartz 5

Explorer

new_api_routing