Queue 與 Event 系統

目的

這裡整理新專案 pro360_api_82 內 queue / event 的寫入、消費、handler 與 log 規則，並在案例文件中補 legacy get-lancer-php56 對照。

這類文件適合放跨 API 共用的非同步流程。單一 API 只需要在自己的 migration 或案例文件中列出送了哪些 event，不需要重複解釋整套 queue 系統。

新舊專案界線

專案	說明
legacy `get-lancer-php56`	舊 CakePHP 專案，也有 `TaskEventQueue` / `EventQueue` model，文件中只在案例列 legacy 寫入點
新專案 `pro360_api_82`	目前搬移目標，這裡的 queue worker / handler / log 規則以新專案為主

除非文件特別標 legacy，否則路徑都指新專案 pro360_api_82。

文件地圖

文件	看什麼	入口資料表 / 程式
event_queue	notification queue 的寫入、worker、log、handler 流程	`event_queue`, `Endpoint/V1/EventQueue.php`
event_actions	`event_key` 如何對應 email / SMS / push template	`event_actions`
task_event_queue	內部資料任務、counter、badge、延遲任務	`task_event_queue`, `Endpoint/V1/TaskEventQueue.php`
event_queue_params	worker 版本與控制參數	`event_queue_params`
案例/quote_bids_want_to_contact_provider	實際 API 的 queue / event 串接案例	`Contact_Pro`, `bid_contact_count`

兩種 Queue 的差異

Queue	主要用途	Handler mapping
`event_queue`	對外通知：email、SMS、push、web push、MoEngage	先查 DB `event_actions`，再用 `template_type` 找 notification handler
`task_event_queue`	內部任務：counter、badge、資料同步、再派發 notification	直接用 `TaskEventFactory::$handlers[event_key]` 找 task handler

通用流程

共通前半段：

API / model 寫入 queue
-> cron 啟動 worker
-> worker 搬 row 到 log

event_queue 後半段：

讀 event_queue.event_key
-> 查 event_actions
-> 由 event_actions.template_type 找 NotificationFactory handler
-> handler 依 template_key 送 email / SMS / push / MoEngage
-> event_queue_log_* 記錄 status / message

task_event_queue 後半段：

讀 task_event_queue.event_key
-> 由 TaskEventFactory::$handlers[event_key] 找 handler
-> handler 更新 counter / badge / derived state，或再寫 event_queue
-> task_event_queue_log 記錄 status / message

閱讀順序

排查原則

queue row 可能已被 worker 搬到 log table。
測試機也可能有 cron / worker 正在跑，queue 可能送出後立刻被執行。
查 downstream side effect 時，要同時查 queue 與 log。
event_queue 的 worker 會寫 event_queue_log_1 到 event_queue_log_4，不要只查 event_queue_log。
task_event_queue 偏資料修正與 counter。
event_queue 偏通知派發。
event_queue 是否會送 email / SMS / push，不只看 event key，要查 event_actions。
event_key 不一定是 PHP handler 名稱；event_queue 的 handler 是由 event_actions.template_type 決定。
若有調整 queue worker 程式，確認 event_queue_params.run_version 是否要同步更新。

Queue / Log 對照

Queue	Worker log	注意
`event_queue`	`event_queue_log_1` 到 `event_queue_log_4`	notification worker 使用分片 log；不要只查 `event_queue_log` 主表
`task_event_queue`	`task_event_queue_log`	counter / badge / task worker 通常寫單一 log table

判斷 notification 是否正常時，優先順序：

主流程 DB state
-> event_queue 是否仍有 row
-> event_queue_log_1..4 是否已有 status_id / message
-> email_logs / sms_logs / push_logs 等下游實際產物

如果 event_queue 是空的，不代表沒送；可能已被 worker 消費。若只查 event_queue_log 主表也查不到，還要查 event_queue_log_1..4。

Quartz 5

Explorer

README