線下回饋活動的每日調度中心
清晨四點半,昨天的訂單開始排隊
商店昨天有人成交,也有人退貨。會員等級計算完成後,回饋活動的工作才剛開始:哪些訂單要給回饋,哪些已給的回饋要收回?
這個問題由 PromotionRewardBatchDispatcherV2Job 接手。它像一位值早班的調度員,先核對訂單與活動,再把工作分給後面的給點、給券和回收 Job。調度員只負責整理與派發;點數和券是否真的變動,要看下游執行結果。
這個 Job 手上的三件事
flowchart LR event["會員等級計算完成事件"] --> dispatcher["每日調度 Job"] orders["CRM 訂單"] --> dispatcher activity["回饋活動"] --> dispatcher dispatcher --> classify["辨認正向與負向訂單"] dispatcher --> match["比對當時有效的活動"] dispatcher --> tasks["建立回饋、回收與稽核 Task"]
排程以商店和 CalculateDate 為單位。上游 PromotionRewardActiveCrmShopDispatcherJob 逐商店建立 PromotionRewardBatchDispatcherV2 Task,事件的 Source 帶著 ShopId、CalculateDate、CreatedBy。其中 CalculateDate 決定要讀哪一天的子單;它不等於這個 Job 真正起跑的時間。
先點名,再分隊
調度員打開的不是「昨天成立的訂單」清冊,而是昨天完成會員等級計算的有效子單。這批資料到手後,才有正向與負向之分。
04:30 起跑,查詢範圍停在午夜
查詢下界,包含這個時刻。
查詢上界,不包含這個時刻。
Job 實際起跑;不會因此多查到 00:00 至 04:30 的子單。
CalculateDate=2026-11-03。篩選欄位是 CrmSalesOrderSlaveCalculateMemberTierDateTime,不是訂單完成時間。程式用 GetCrmSalesOrderSlavesByDateAsync(ShopId, CalculateDate) 取得指定商店、CrmSalesOrderSlaveValidFlag=true,且會員等級計算時間落在上述區間的子單。若一筆都沒有,這次調度就到此結束。
正向單與負向單,怎麼分?
先看 PurchaseType 與 TypeMemo,再看勾稽欄位
flowchart TD
child["本批有效子單"] --> kind{"PurchaseType 與 TypeMemo"}
kind -->|"Normal 配一般類,或 Return 配折扣類"| positive["正向候選子單"]
kind -->|"Return 配一般類,或 Normal 配折扣類"| linked{"勾稽子單 ID 不等於 0?"}
kind -->|"其他組合"| outside["不進本 Job 的正逆集合"]
linked -->|"是"| negative["負向候選子單"]
linked -->|"否"| outside
CrmSalesOrderSlaveOriginalCrmSalesOrderSlaveId;負向分類一定要求該欄位不等於 0。CrmSalesOrderSlavePurchaseType |
CrmSalesOrderSlaveTypeMemo |
分類 |
|---|---|---|
Normal |
Normal、Others、Other、Ignored、Gift、空字串 |
正向 |
Return |
Coupon、Point |
正向 |
Return |
前述一般類 | 負向,但還要有勾稽子單 ID |
Normal |
Coupon、Point |
負向,但還要有勾稽子單 ID |
所以,一筆 Normal 加一般類的子單,即使 CrmSalesOrderSlaveOriginalCrmSalesOrderSlaveId 有值,仍被視為正向候選。負向候選則相反,欄位若為 0,連第一輪名單都進不去;欄位有值也只表示「寫了要勾稽的 ID」,尚不能保證查得到對應子單。
五個集合,像五次逐步核對的名單
負向名單怎麼一路收斂
flowchart TD
candidates["allReturnOrderSlaves:負向候選子單"] --> mains["returnOrders:查到的有效 Others 主單"]
mains --> passed["returnOrderSlaves:所屬主單通過檢查的負向子單"]
candidates --> passed
passed --> origin["originOrderSlaves:依勾稽子單 ID 查回的有效子單"]
passed --> check{"勾稽主單在本批 normalOrders?"}
check -->|"是"| together["重算模式:本批正流程一起處理"]
check -->|"否"| filtered["filteredReturnOrderSlaves:逆流程嘗試獨立回收"]
originOrderSlaves 是另外查回的資料,不是從 returnOrderSlaves 再篩出的子集合。圖中最後的分流只決定重算模式的獨立回收。| 名單 | 實際裝的是什麼 | 留給下一步做什麼 |
|---|---|---|
allReturnOrderSlaves |
符合負向欄位組合、且勾稽子單 ID 不為 0 的候選子單 |
查這些子單所屬主單。 |
returnOrders |
同商店、有效、CrmSalesOrderTypeDef=Others 的主單 |
確認候選子單能否繼續。 |
returnOrderSlaves |
所屬主單出現在 returnOrders 的負向子單 |
正流程可讀其關聯 ID;逆流程以它逐筆比對。 |
originOrderSlaves |
依 CrmSalesOrderSlaveOriginalCrmSalesOrderSlaveId 查回的有效子單 |
取得當時的完成時間與 CRM 會員 ID。 |
filteredReturnOrderSlaves |
勾稽主單不在本批 normalOrders 的負向子單 |
重算模式下嘗試獨立回收。 |
正向那一邊也會用候選子單的 CrmSalesOrderSlaveCrmSalesOrderId 查主單;同商店、有效且類型為 Others 的主單,才進 normalOrders。因此 normalOrders 與 returnOrders 都裝主單,兩者來源子單不同。
假設負向子單 201 的 CrmSalesOrderSlaveOriginalCrmSalesOrderId=100。主單 100 在本批 normalOrders,子單 201 就不進 filtered;主單 100 不在,才進 filtered。程式比的是本批主單 ID,沒有直接比較兩筆子單的日期。
舊模式仍會從 returnOrderSlaves 逐筆找對應子單與活動,不看 filtered 名單;不能把 filtered 當成所有回收請求的唯一入口。主單與子單 ID 的查詢會先去重,再分批讀取。
訂單是昨天進名單,活動卻要看當時
昨日完成會員等級計算,只決定哪些子單被拿出來檢查。真正要比對哪檔活動,還得回到那張訂單完成的時刻。
正、逆流程各拿哪個完成時間
flowchart LR main["正向:本批 normalOrders 主單"] --> mainTime["主單完成時間"] origin["逆向:originOrderSlaves 對應子單"] --> originTime["對應子單完成時間"] mainTime --> range["先查時間範圍內的候選活動"] originTime --> range range --> gate["排除開始時間晚於執行當日 04:00 的活動"] gate --> final["逐筆檢查:活動開始 ≤ 完成時間 ≤ 活動結束"]
CrmSalesOrderTradesOrderFinishDateTime;逆向為對應子單的 CrmSalesOrderSlaveTradesOrderFinishDateTime。候選活動限固定點數、比例點數、優惠券三類。正流程先取本批主單最早與最晚的完成時間,逆流程則取 originOrderSlaves 對應資料的最早與最晚完成時間,各自向活動 API 查候選活動。拿到候選名單後,程式先用執行當天的凌晨四點做活動開始時間門檻;最後才對每張主單或每筆對應子單,檢查完成時間是否落在活動有效期內。四點限制的是活動何時開始,並不限制訂單的完成時間。
晚一天執行,哪裡會變?
同一個 CalculateDate,活動門檻可能向後移
活動開始時間須不晚於 11/03 04:00。
活動開始時間門檻變成 11/04 04:00;CalculateDate 仍帶 11/03,子單查詢區間不變。
活動須由 API 回傳,且訂單完成時間落在活動有效期,才可能建立請求。
這個差異來自 DateTime.Now,不是 CalculateDate。同一批訂單若延後處理,活動候選名單可能不同。至於被填成未來的完成時間,這段 Job 與 PromotionService 沒有額外的「不得晚於現在」檢查;只要其他查詢與活動期間條件都成立,仍可能產生請求。這是依程式碼推演,未以真實資料驗證。
一張主單,可能走進不只一檔活動
正流程逐張看主單完成當時有哪些活動。每組符合的「主單 × 活動」都變成一筆待派發的回饋請求。
ProcessPromotionRewardByOrders 如何寫出請求
flowchart TD
mains["normalSalesOrders"] --> member["把 CRM 會員 ID 對應到 NineYi MemberId"]
member --> activity["按主單完成時間查活動"]
activity --> matched{"這張主單在活動期間完成?"}
matched -->|"否"| skip["不建立這組請求"]
matched -->|"是"| mode{"活動走重算模式?"}
mode -->|"是"| related["帶入跨主單勾稽的負向子單 ID"]
mode -->|"否"| empty["RelatedOrderSlaveIdList 留空"]
related --> request["建立 PromotionRewardRequestEntity"]
empty --> request
為什麼先查 MemberId?
CRM 主單上的 CrmSalesOrderCrmMemberId 是訂單的會員線索,派發階段卻要用 NineYi 的 MemberId 分組。程式先批次建立兩者的對照,再把 MemberId 寫進請求。如此,同會員、同商店、同活動的多張訂單才會被放進同一批,依 OrderDateTime 由早到晚交給下游處理。
同一會員的兩張主單如何排隊
CRM 會員對應 NineYi MemberId=9001,符合活動 300。
同樣是會員 9001、商店 125、活動 300。
以 (9001, 125, 300) 分組,先處理主單 100,再處理主單 102。
ProcessPromotionRewardByOrders 先建請求;排序發生在 Dispatcher 的會員分組階段。若 CRM 會員映射不到 NineYi MemberId,方法仍把請求加入 requests 並記警告。到後面的會員分組,MemberId <= 0 才被略過,該筆不會上傳 S3,也不會產生對應的處理 Task。
RelatedOrderSlaveIdList:把跨主單的負向子單帶進來
為什麼主單 100 的請求會帶上子單 201
flowchart LR main["正在算主單 100"] --> reward["主單 100 的回饋請求"] returnMain["負向主單 200"] --> child["負向子單 201"] child -->|"勾稽主單 ID 指向 100"| reward reward --> list["RelatedOrderSlaveIdList = [201]"]
returnOrderSlaves 取其 ID;舊模式傳空清單。判斷使用兩個欄位:負向子單的 CrmSalesOrderSlaveOriginalCrmSalesOrderId 必須等於目前主單 ID;它自己的 CrmSalesOrderSlaveCrmSalesOrderId 又必須不同於目前主單 ID。符合後把 CrmSalesOrderSlaveId 去重,放進 RelatedOrderSlaveIdList。這裡取的是全部 returnOrderSlaves,不是 filtered 名單;同主單的負向子單不會從這個清單額外帶入。
展開一筆正向請求的示意資料
1 | { |
OrderDateTime 取自主單完成時間;S3Key 此時仍為空。這是程式碼推演的範例,沒有查真實訂單或活動。
這筆清單之後會隨完整請求上傳 S3。下游給點或給券 Job 下載後,OthersCrmSalesOrderPromotionRewardCalculateService 會依清單查子單,再確認勾稽主單與子單關係是否對得上,才加入該次計算。
退貨來了,先找它當初對應哪一筆
回收不能只看今天這筆負向子單。程式要先找到它勾稽的子單,再回到那筆資料完成時,確認當時有哪些活動。
ProcessRecycleByOrderSalves 的檢查次序
flowchart TD
start["負向子單與勾稽對應子單"] --> exists{"兩組資料都有?"}
exists -->|"否"| stop["直接返回"]
exists -->|"是"| member["準備 CRM 與 NineYi 會員對照"]
member --> activity["按 originSalesOrderSlaves 完成時間查活動"]
activity --> link{"這筆負向子單找得到對應子單與在期活動?"}
link -->|"否"| next["略過這筆"]
link -->|"是"| mode{"這檔活動走重算模式?"}
mode -->|"是"| filtered{"這筆在 filteredReturnOrderSlaves?"}
filtered -->|"否"| next
filtered -->|"是"| request["建立回收請求"]
mode -->|"否,舊模式"| request
方法先合併負向子單與查回的對應子單,批次準備 CRM 會員 ID 到 NineYi MemberId 的映射;真正寫入回收請求時,用的是對應子單上的 CrmSalesOrderSlaveCrmMemberId。接著以 originSalesOrderSlaves 的完成時間範圍查候選活動,逐筆用 CrmSalesOrderSlaveOriginalCrmSalesOrderSlaveId 找對應子單,再拿該子單的完成時間比對活動期間。
重算與舊模式,分界就在 filtered 名單
| 活動模式 | 目前負向子單 | 結果 |
|---|---|---|
| 重算 | 不在 filteredReturnOrderSlaves |
不另建回收請求;它勾稽的主單已在本批 normalOrders。 |
| 重算 | 在 filteredReturnOrderSlaves |
建立獨立回收請求。 |
| 舊模式 | 不論是否在 filtered | 找到對應子單與在期活動後,建立回收請求。 |
給券活動的 IsRecalculateMode 直接為 true;其他活動依 PromotionReward/CalculateSwitch 設定,以活動開始時間判斷。重算分支若整個 filtered 名單為空,也會直接跳過獨立回收。這張表的前提是:負向子單已找到對應資料,且至少有一檔當時有效的活動。
子單 201 的一趟模擬旅程
它的 CrmSalesOrderSlaveOriginalCrmSalesOrderSlaveId=101。
完成時間為 2026-11-03 12:00;會員映射到 MemberId=9001。
假設活動走重算,且子單 201 在 filtered 名單。
請求指出子單 201、活動 300、會員 9001,等待 Dispatcher 分派。
展開這筆回收請求的示意資料
1 | { |
OrderCreateDate 這個欄位名稱容易讓人聯想到成立時間,這裡實際放的是子單 101 的 CrmSalesOrderSlaveTradesOrderFinishDateTime。TriggerDatetime 在建構時讀取 DateTime.Now,示意值不會剛好等於真實時間。
回收請求加入 requests,仍不表示點數已回收。若會員映射失敗,請求仍加入清單;Dispatcher 後續只把 MemberId > 0 的請求分組派發。
名單備妥後,工作分批出發
正向與逆向請求先各自整理。完整資料放在 S3,NMQ Task 只帶能找到那份資料的索引;回饋先走,回收稍後,稽核再接手。
Dispatcher 到下游 Job 的交接
sequenceDiagram participant D as Dispatcher participant S as S3 participant Q as NMQ participant W as 下游 Job D->>D: 先整理正向請求,再整理逆向請求 D->>D: 依會員、商店、活動分組 D->>S: 上傳每組完整請求 S-->>D: 上傳成功 D->>Q: 建立含 S3Key 的處理 Task Note over Q,W: BookingTime 到達後才可能開始處理 Note over Q,W: 下游 Job 取得已預約的 Task Data W->>S: 依 S3Key 下載完整請求 S-->>W: 回傳請求清單 W->>W: 逐筆進入回饋或回收處理
OrderDateTime 排序;回收各組保留原請求順序。回饋以 (MemberId, ShopId, PromotionEngineId) 分組;回收以 (MemberId, ShopId, PromotionId) 分組。每組的完整請求清單先上傳 S3,Task Data 只帶商店、會員、活動、類型與 S3Key 等代表資料。S3 key 形如 {環境}/PromotionRewardBatchDispatcherV2/{ShopId}/{MemberId}/{活動ID}/{Guid}.json;環境值為 PP 時會寫成 Prod。上傳失敗會記錄錯誤並拋例外,不能當成已成功派發。
| 活動類型 | 回饋 Task | 回收 Task |
|---|---|---|
RewardReachPriceWithPoint2、RewardReachPriceWithRatePoint2 |
PromotionRewardLoyaltyPointsV2PriorityLow |
RecycleLoyaltyPointsV2PriorityLow |
RewardReachPriceWithCoupon |
PromotionRewardCouponPriorityLow |
PromotionRecycleCouponPriorityLow |
若活動類型沒有對應 JobName,S3 資料已上傳,但程式只記警告,不建立該組處理 Task。MemberId <= 0 的請求在上傳前被略過。這兩種情況的請求仍可能留在原始清單;稽核是否排程,看的正是原始回饋或回收清單是否非空。
四點半起跑,各種 Task 約何時 Booking?
排程相對的是實際執行時間
建立後不設定 BookingTime,可進入排隊。
各自以建立時的 DateTime.Now + 6 小時 30 分 預約。
以建立時的 DateTime.Now + 10 小時 預約。
以建立時的 DateTime.Now + 10 小時 30 分 預約。
DateTime.Now,查詢與 S3 上傳也會耗時;NMQ 真正執行時間另受佇列與 Worker 影響。| 何時建立稽核 Task | JobName | 帶入的時間資料 |
|---|---|---|
| 回饋請求清單非空 | AuditPromotionRewardLoyaltyPointsDispatchV2 |
ExecuteTime=CalculateDate.Date。 |
| 回收請求清單非空 | AuditPromotionRecycleDispatch |
ExecuteTime=CalculateDate.Date。 |
| 回收請求清單非空 | BatchAuditLoyaltyPoints |
StartDateTime=CalculateDate.Date.AddDays(-1),EndDateTime=CalculateDate.Date。 |
CalculateDate 決定查詢哪批子單,也成為稽核 Task 的資料日期;DateTime.Now 決定活動四點門檻與各 Task 的預約時間。兩個時間各司其職,延後執行時尤其要分清。
如果讓回收先出發呢?
想像主單 100 在先前批次參加了點數活動 300。今天收到負向子單 201,其 CrmSalesOrderSlaveOriginalCrmSalesOrderId=100;今天還有另一張新主單 102 要領活動 300 的回饋。若重算模式把 201 放進 filteredReturnOrderSlaves,它要回收的是主單 100 的回饋,並不需要等主單 102 的正向 Job 建立紀錄。因此,對這種情境,讓回收先跑有討論空間。
兩筆工作看的是不同主單的回饋紀錄
flowchart TB previous["先前批次<br/>主單 100"] --> oldRecord["活動 300<br/>主單 100 回饋紀錄"] negative["本批負向<br/>子單 201"] -->|"勾稽主單 100"| oldRecord newOrder["本批新主單<br/>102"] --> newRecord["活動 300<br/>主單 102 回饋紀錄"]
100 的 DDB 回饋紀錄確實存在。filteredReturnOrderSlaves 只檢查勾稽主單 ID 不在本批 normalOrders,本身不查紀錄是否存在,也沒有直接比較日期。目前程式先建立未設定 BookingTime 的正向 Task,再建立約六個半小時後的回收 Task。若只把兩種處理 Task 的 BookingTime 對調,建立 Task 的程式順序仍是正向先、回收後,預期執行時段則變成回收先、正向後。這是排程提案,不是目前行為。
04:30 起跑時,對調 BookingTime 的時間軸
負向子單 201 嘗試讀取主單 100 的既有回饋紀錄。
新主單 102 的回饋此時才可能開始處理;NMQ 實際起跑仍受佇列影響。
若只交換處理 Task 的時間、稽核不動,稽核可能早於主單 102 的回饋完成。
真正的分界不在「今天的正向 Job 跑完了嗎」,而在回收指向的那張主單是否已有可處理的回饋紀錄。點數回收查不到 DDB 給點紀錄會拋錯;給券回收查不到 DDB 給券紀錄也會拋錯。即使查得到,還要符合各自的回饋狀態與後續回收條件。
| 範圍 | 先跑回收的判斷 |
|---|---|
重算模式,且負向子單在 filteredReturnOrderSlaves |
通常指向本批以外的正向主單;若該主單的回饋紀錄已備妥,沒有等待本批新正向 Task 的直接依賴。 |
| 重算模式,但負向子單不在 filtered | 逆流程本來就不為這筆另建回收 Task,由本批正流程處理。 |
| 舊模式 | 不看 filtered。負向子單可能勾稽本批正向主單;若其回饋紀錄尚未建立,立即回收可能失敗。 |
所以,「重算模式的 filtered 回收先跑」與「所有回收都先跑」是兩個不同提案。若要選擇性提前,Dispatcher 還需能辨認每筆回收請求所屬模式;目前 RecycleRequestEntity 沒有直接保存重算模式欄位。若把所有正向 Task 改成六個半小時後才跑,也必須重新安排回饋稽核,不能讓稽核與正向處理同時起跑。這些都是設計上的待確認條件,並非已驗證的改動結果。
查看本篇對照的主要程式碼
PromotionRewardBatchDispatcherV2Job.cs 負責查詢、分類、分組、S3 與 NMQ 派發;PromotionService.cs 的 ProcessPromotionRewardByOrders 和 ProcessRecycleByOrderSalves 負責活動比對與請求建立;RecycleLoyaltyPointsV2.cs 是點數回收下游入口。



