聆聽線上成單事件派送回饋
一張訂單敲門,回饋要交給誰?
成單事件只帶來訂單資料。活動要先找出來,才知道接下來該派給哪一個回饋 Job。
一張訂單剛成立,系統收到 OrderCreated 事件。事件帶來商店、TG 編號與訂單成立時間,卻沒有附上「應參加哪些活動」的答案。
一則事件,如何變成多筆工作
flowchart LR event["OrderCreated:一張 TG"] --> dispatcher["Dispatcher 找當時有效的活動"] dispatcher --> point["送點活動:建立給點 Task"] dispatcher --> coupon["送券活動:建立給券 Task"] point --> pointJob["給點 Job 算門檻與回饋"] coupon --> couponJob["給券 Job 算門檻與回饋"]
PromotionRewardLoyaltyPointsDispatcherV2 像派件員。它先看訂單當時有哪些活動,再把每檔活動交給對應的子 Task。名稱裡雖有 LoyaltyPoints,實際上也派送優惠券。
派件員不計算最後該給幾點、幾張券,也不親自發放。真正的門檻判斷與回饋紀錄由下游 Job 處理。
先核對時間,再讓活動各自處理
同一張訂單可能遇到多檔活動。先拆成獨立工作,才不用把所有計算都擠在一個 dispatcher 裡。
OrderCreated 事件只說「這張 TG 成立了」,沒有說「請交給活動 101」。Dispatcher 得先判斷訂單成立時間是否落在每檔活動的期間內。
時間對不上,就不會建立這檔活動的 Task
flowchart LR
order["訂單成立時間 OrderDateTime"] --> gate{"落在活動開始與結束之間?"}
gate -->|"否"| skip["略過這檔活動"]
gate -->|"是"| type{"活動類型"}
type -->|"送點"| point["給點 Task"]
type -->|"送券"| coupon["給券 Task"]
point --> reward["下游再判斷是否真正達標"]
coupon --> reward
若把每個「訂單 × 活動」組合的讀規則、算條件、發回饋都放進 dispatcher,活動越多,單一 Job 就跑越久;其中一檔卡住,後面的活動也得等。現在由 dispatcher 先篩時間與類型,再讓各筆子 Task 處理完整規則。
派送階段仍逐筆 await CreateAsync。若建立某筆子 Task 失敗,當次尚未派出的活動仍會受影響。
10:00 查活動,10:03 才開始的怎麼辦?
候選活動會快取 5 分鐘。查詢先往未來多看 30 分鐘,避免稍後成立的訂單找不到剛開始的活動。
PromotionEngineService 透過 Promotion Service 的 POST api/promotion-rules/ongoing-list 取得候選活動,按商店快取 5 分鐘。遠端查詢從執行當下往前 7 天,一直查到執行當下往後 30 分鐘。往前是為了涵蓋 ATM 等非即時付款的時間差;往後則是替快取期間即將開始的活動預留位置。
把時鐘撥到 10:00
查詢終點設為 10:30,讓已存在、預定 10:03 開始的活動先進清單。
這檔活動已在候選清單裡,不必等快取過期後重新查詢。
仍讀同一份快取,但用這張訂單的 OrderDateTime 再比一次活動期間。
進了候選清單,也不能提早命中
| 訂單時間 | 活動開始 | 結果 |
|---|---|---|
| 10:00 | 10:03 | 尚未開始,排除 |
| 10:04 | 10:03 | 時間對得上,可以派送 |
活動若在快取建立後才新增,既有快取不會因 30 分鐘緩衝而立即更新;仍須等後續刷新。
點數走點數,券走券
同樣是時間有效的活動,類型不同,派去的 Job 不同;點數活動還多一道 ExtendInfo 檢查。
活動類型決定派送方向
flowchart LR
matched["時間有效的活動"] --> kind{"TypeDef 是哪一種?"}
kind -->|"固定點數或比例點數"| info{"ExtendInfo 有值?"}
info -->|"否"| skip["不建立給點 Task"]
info -->|"是"| point["PromotionRewardLoyaltyPointsV2"]
kind -->|"優惠券"| coupon["PromotionRewardCoupon"]
point --> booking{"GroupCode 非空白?"}
coupon --> booking
booking -->|"是"| later["BookingTime 加 5 分 10 秒"]
booking -->|"否"| normal["不設定 BookingTime"]
Dispatcher 先逐檔建立點數 Task,再處理優惠券。每檔活動各有一筆 PromotionRewardRequestEntity:
交給子 Job 的資料
| 欄位 | 來源 |
|---|---|
ShopId | 成單事件的商店 |
TradesOrderGroupCode | 成單事件的 TG 編號 |
OrderDateTime | 訂單成立時間 |
PromotionEngineId | 這一檔活動的 ID |
EventSource | OrderCreated |
活動有非空白 GroupCode 時,程式視為佔額活動,將 BookingTime 設為建立當下的 UTC 時間再加 5 分 10 秒。多出的 10 秒,是為了避免剛好 5 分鐘時立即執行。
同一張 TG,最後分出幾張工作單?
用三檔候選活動走一次,就能看見時間、ExtendInfo 與 GroupCode 各自在哪一步發揮作用。
假設 10:04 有一張 TG 成立,同一商店有三檔候選活動。以下是示意情境,不是實際執行結果。
三檔活動逐一點名
| 活動 | 當時情況 | Dispatcher 的動作 |
|---|---|---|
| 送點活動甲 | 10:03 開始,且有 ExtendInfo | 建立一筆給點 Task |
| 送點活動乙 | 時間有效,但沒有 ExtendInfo | 不建立給點 Task |
| 送券活動丙 | 時間有效,且有 GroupCode | 建立一筆給券 Task,安排約 5 分 10 秒後執行 |
這張 TG 的交接順序
OrderCreated 提供商店、TG 與訂單時間。
核對活動時間與類型,再處理 ExtendInfo 等派送條件。
一檔活動一筆 Task;各自判斷門檻、計算並處理回饋。
訂單取消了,先前的回饋怎麼辦?
成單時派出去的點數與券,遇到取消或退貨還有另一位派件員接手。它找出訂單成立當時有效的活動,再把回收工作交給對應的 Job。
RecycleLoyaltyPointsDispatcherV2 接收 OrderCancelled 或 OrderReturned 事件。事件提供商店與子單 TSCode;取消時間取 CancelDateTime,退貨時間取 ReturnedDateTime。缺少子單代碼或無法取得對應的事件時間時,這次派送就到此結束。
回收派件員如何找到工作
flowchart LR
event["取消或退貨:一張 TS"] --> time["用 TSCode 查訂單成立時間"]
time --> activities["找成立當時有效的點數與券活動"]
activities --> found{"有符合的活動?"}
found -->|"否"| done["結束,不建立 Task"]
found -->|"是"| kind{"活動類型"}
kind -->|"固定點數或比例點數"| info{"ExtendInfo 有值?"}
info -->|"否"| skip["不建立點數回收 Task"]
info -->|"是"| points["RecycleLoyaltyPointsV2"]
kind -->|"優惠券"| coupon["PromotionRecycleCoupon"]
ExtendInfo 檢查;優惠券分支沒有這道檢查。回收派件員先向 ERP 查 TSCode 的訂單成立時間,再用商店與該時間查活動。每檔入選活動各形成一筆 RecycleRequestEntity,同時帶著訂單成立時間與取消/退貨發生時間。前者用來找活動,後者交給下游處理回收。
兩位派件員的交接差異
| 情境 | 找活動的時間 | 建立的子 Task |
|---|---|---|
| 訂單成立,派送回饋 | 事件中的 OrderDateTime | PromotionRewardLoyaltyPointsV2 或 PromotionRewardCoupon |
| 訂單取消或退貨,派送回收 | 由 TSCode 查得的訂單成立時間 | RecycleLoyaltyPointsV2 或 PromotionRecycleCoupon |
這支 Job 只建立回收 Task,不直接扣回點數或收回券。點數與券的派送分支並行執行,各分支內逐筆建立 Task;真正的回收結果仍由下游 Job 決定。



