清晨四點半,昨天的訂單開始排隊

商店昨天有人成交,也有人退貨。會員等級計算完成後,回饋活動的工作才剛開始:哪些訂單要給回饋,哪些已給的回饋要收回?

這個問題由 PromotionRewardBatchDispatcherV2Job 接手。它像一位值早班的調度員,先核對訂單與活動,再把工作分給後面的給點、給券和回收 Job。調度員只負責整理與派發;點數和券是否真的變動,要看下游執行結果。

這個 Job 手上的三件事

箭頭表示資料與工作去向。這張圖是責任總覽,實際處理順序會在後面逐段展開。

排程以商店和 CalculateDate 為單位。上游 PromotionRewardActiveCrmShopDispatcherJob 逐商店建立 PromotionRewardBatchDispatcherV2 Task,事件的 Source 帶著 ShopId、CalculateDate、CreatedBy。其中 CalculateDate 決定要讀哪一天的子單;它不等於這個 Job 真正起跑的時間。

先點名,再分隊

調度員打開的不是「昨天成立的訂單」清冊,而是昨天完成會員等級計算的有效子單。這批資料到手後,才有正向與負向之分。

04:30 起跑,查詢範圍停在午夜

2026-11-02 00:00

查詢下界,包含這個時刻。

2026-11-03 00:00

查詢上界,不包含這個時刻。

2026-11-03 04:30

Job 實際起跑;不會因此多查到 00:00 至 04:30 的子單。

假設 CalculateDate=2026-11-03。篩選欄位是 CrmSalesOrderSlaveCalculateMemberTierDateTime,不是訂單完成時間。

程式用 GetCrmSalesOrderSlavesByDateAsync(ShopId, CalculateDate) 取得指定商店、CrmSalesOrderSlaveValidFlag=true,且會員等級計算時間落在上述區間的子單。若一筆都沒有,這次調度就到此結束。

正向單與負向單,怎麼分?

先看 PurchaseType 與 TypeMemo,再看勾稽欄位

正向分類不檢查 CrmSalesOrderSlaveOriginalCrmSalesOrderSlaveId;負向分類一定要求該欄位不等於 0。
CrmSalesOrderSlavePurchaseType CrmSalesOrderSlaveTypeMemo 分類
Normal Normal、Others、Other、Ignored、Gift、空字串 正向
Return Coupon、Point 正向
Return 前述一般類 負向,但還要有勾稽子單 ID
Normal Coupon、Point 負向,但還要有勾稽子單 ID

所以,一筆 Normal 加一般類的子單,即使 CrmSalesOrderSlaveOriginalCrmSalesOrderSlaveId 有值,仍被視為正向候選。負向候選則相反,欄位若為 0,連第一輪名單都進不去;欄位有值也只表示「寫了要勾稽的 ID」,尚不能保證查得到對應子單。

五個集合,像五次逐步核對的名單

負向名單怎麼一路收斂

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 的查詢會先去重,再分批讀取。

訂單是昨天進名單,活動卻要看當時

昨日完成會員等級計算,只決定哪些子單被拿出來檢查。真正要比對哪檔活動,還得回到那張訂單完成的時刻。

正、逆流程各拿哪個完成時間

正向時間欄位為 CrmSalesOrderTradesOrderFinishDateTime;逆向為對應子單的 CrmSalesOrderSlaveTradesOrderFinishDateTime。候選活動限固定點數、比例點數、優惠券三類。

正流程先取本批主單最早與最晚的完成時間,逆流程則取 originOrderSlaves 對應資料的最早與最晚完成時間,各自向活動 API 查候選活動。拿到候選名單後,程式先用執行當天的凌晨四點做活動開始時間門檻;最後才對每張主單或每筆對應子單,檢查完成時間是否落在活動有效期內。四點限制的是活動何時開始,並不限制訂單的完成時間。

晚一天執行,哪裡會變?

同一個 CalculateDate,活動門檻可能向後移

原定 11/03 執行

活動開始時間須不晚於 11/03 04:00。

實際 11/04 才執行

活動開始時間門檻變成 11/04 04:00;CalculateDate 仍帶 11/03,子單查詢區間不變。

逐筆比對仍要過關

活動須由 API 回傳,且訂單完成時間落在活動有效期,才可能建立請求。

例如 11/03 12:00 開始的活動,晚一天執行時可能多通過四點門檻;若訂單在活動開始前已完成,仍不匹配。

這個差異來自 DateTime.Now,不是 CalculateDate。同一批訂單若延後處理,活動候選名單可能不同。至於被填成未來的完成時間,這段 Job 與 PromotionService 沒有額外的「不得晚於現在」檢查;只要其他查詢與活動期間條件都成立,仍可能產生請求。這是依程式碼推演,未以真實資料驗證。

一張主單,可能走進不只一檔活動

正流程逐張看主單完成當時有哪些活動。每組符合的「主單 × 活動」都變成一筆待派發的回饋請求。

ProcessPromotionRewardByOrders 如何寫出請求

同一主單符合多檔活動時,每檔活動各建一筆請求。這裡只整理請求,尚未計算回饋金額,也尚未給點或給券。

為什麼先查 MemberId?

CRM 主單上的 CrmSalesOrderCrmMemberId 是訂單的會員線索,派發階段卻要用 NineYi 的 MemberId 分組。程式先批次建立兩者的對照,再把 MemberId 寫進請求。如此,同會員、同商店、同活動的多張訂單才會被放進同一批,依 OrderDateTime 由早到晚交給下游處理。

同一會員的兩張主單如何排隊

12:00,主單 100

CRM 會員對應 NineYi MemberId=9001,符合活動 300。

13:00,主單 102

同樣是會員 9001、商店 125、活動 300。

派發時合成一個會員批次

以 (9001, 125, 300) 分組,先處理主單 100,再處理主單 102。

時間與 ID 是示意值。ProcessPromotionRewardByOrders 先建請求;排序發生在 Dispatcher 的會員分組階段。

若 CRM 會員映射不到 NineYi MemberId,方法仍把請求加入 requests 並記警告。到後面的會員分組,MemberId <= 0 才被略過,該筆不會上傳 S3,也不會產生對應的處理 Task。

RelatedOrderSlaveIdList:把跨主單的負向子單帶進來

為什麼主單 100 的請求會帶上子單 201

只有活動走重算模式,且負向子單所屬主單不同於目前主單,才從 returnOrderSlaves 取其 ID;舊模式傳空清單。

判斷使用兩個欄位:負向子單的 CrmSalesOrderSlaveOriginalCrmSalesOrderId 必須等於目前主單 ID;它自己的 CrmSalesOrderSlaveCrmSalesOrderId 又必須不同於目前主單 ID。符合後把 CrmSalesOrderSlaveId 去重,放進 RelatedOrderSlaveIdList。這裡取的是全部 returnOrderSlaves,不是 filtered 名單;同主單的負向子單不會從這個清單額外帶入。

展開一筆正向請求的示意資料
1
2
3
4
5
6
7
8
9
10
11
12
13
{
"ShopId": 125,
"CrmSalesOrderId": 100,
"OrderDateTime": "2025-06-27T12:00:00",
"PromotionEngineId": 300,
"PromotionEngineType": "RewardReachPriceWithPoint2",
"RewardFlowEnum": "Reward",
"OrderTypeDefEnum": "Others",
"RelatedOrderSlaveIdList": [201],
"MemberId": 9001,
"TradesOrderGroupCode": "",
"S3Key": ""
}

OrderDateTime 取自主單完成時間;S3Key 此時仍為空。這是程式碼推演的範例,沒有查真實訂單或活動。

這筆清單之後會隨完整請求上傳 S3。下游給點或給券 Job 下載後,OthersCrmSalesOrderPromotionRewardCalculateService 會依清單查子單,再確認勾稽主單與子單關係是否對得上,才加入該次計算。

退貨來了,先找它當初對應哪一筆

回收不能只看今天這筆負向子單。程式要先找到它勾稽的子單,再回到那筆資料完成時,確認當時有哪些活動。

ProcessRecycleByOrderSalves 的檢查次序

每筆負向子單與每檔符合的活動都會各自判斷。圖中的「略過這筆」是當前組合不建立請求,不代表整批 Job 停止。

方法先合併負向子單與查回的對應子單,批次準備 CRM 會員 ID 到 NineYi MemberId 的映射;真正寫入回收請求時,用的是對應子單上的 CrmSalesOrderSlaveCrmMemberId。接著以 originSalesOrderSlaves 的完成時間範圍查候選活動,逐筆用 CrmSalesOrderSlaveOriginalCrmSalesOrderSlaveId 找對應子單,再拿該子單的完成時間比對活動期間。

重算與舊模式,分界就在 filtered 名單

活動模式 目前負向子單 結果
重算 不在 filteredReturnOrderSlaves 不另建回收請求;它勾稽的主單已在本批 normalOrders。
重算 在 filteredReturnOrderSlaves 建立獨立回收請求。
舊模式 不論是否在 filtered 找到對應子單與在期活動後,建立回收請求。

給券活動的 IsRecalculateMode 直接為 true;其他活動依 PromotionReward/CalculateSwitch 設定,以活動開始時間判斷。重算分支若整個 filtered 名單為空,也會直接跳過獨立回收。這張表的前提是:負向子單已找到對應資料,且至少有一檔當時有效的活動。

子單 201 的一趟模擬旅程

找到負向子單 201

它的 CrmSalesOrderSlaveOriginalCrmSalesOrderSlaveId=101。

查回對應子單 101

完成時間為 2026-11-03 12:00;會員映射到 MemberId=9001。

活動 300 當時有效

假設活動走重算,且子單 201 在 filtered 名單。

留下回收請求一筆

請求指出子單 201、活動 300、會員 9001,等待 Dispatcher 分派。

這是靜態情境模擬,並非資料庫、活動 API 或 NMQ 的實際執行紀錄。
展開這筆回收請求的示意資料
1
2
3
4
5
6
7
8
9
10
11
12
13
{
"ShopId": 125,
"CrmSalesOrderSlaveId": 201,
"OrderCreateDate": "2026-11-03T12:00:00",
"PromotionId": 300,
"PromotionEngineType": "RewardReachPriceWithPoint2",
"EventName": "Return",
"TriggerDatetime": "2026-11-04T04:30:00",
"TSCode": "",
"OrderTypeDefEnum": "Others",
"MemberId": 9001,
"S3Key": ""
}

OrderCreateDate 這個欄位名稱容易讓人聯想到成立時間,這裡實際放的是子單 101 的 CrmSalesOrderSlaveTradesOrderFinishDateTime。TriggerDatetime 在建構時讀取 DateTime.Now,示意值不會剛好等於真實時間。

回收請求加入 requests,仍不表示點數已回收。若會員映射失敗,請求仍加入清單;Dispatcher 後續只把 MemberId > 0 的請求分組派發。

名單備妥後,工作分批出發

正向與逆向請求先各自整理。完整資料放在 S3,NMQ Task 只帶能找到那份資料的索引;回饋先走,回收稍後,稽核再接手。

Dispatcher 到下游 Job 的交接

建立 Task 與下游完成業務是兩個階段。正向各組按 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?

排程相對的是實際執行時間

約 04:30:回饋處理 Task

建立後不設定 BookingTime,可進入排隊。

約 11:00:回收 Task、回饋分派稽核 Task

各自以建立時的 DateTime.Now + 6 小時 30 分 預約。

約 14:30:回收分派稽核 Task

以建立時的 DateTime.Now + 10 小時 預約。

約 15:00:給點回收稽核 Task

以建立時的 DateTime.Now + 10 小時 30 分 預約。

時間是以 04: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 建立紀錄。因此,對這種情境,讓回收先跑有討論空間。

兩筆工作看的是不同主單的回饋紀錄

圖中以點數活動為例,假設主單 100 的 DDB 回饋紀錄確實存在。filteredReturnOrderSlaves 只檢查勾稽主單 ID 不在本批 normalOrders,本身不查紀錄是否存在,也沒有直接比較日期。

目前程式先建立未設定 BookingTime 的正向 Task,再建立約六個半小時後的回收 Task。若只把兩種處理 Task 的 BookingTime 對調,建立 Task 的程式順序仍是正向先、回收後,預期執行時段則變成回收先、正向後。這是排程提案,不是目前行為。

04:30 起跑時,對調 BookingTime 的時間軸

約 04:30:回收 Task 可開始排隊

負向子單 201 嘗試讀取主單 100 的既有回饋紀錄。

約 11:00:本批正向 Task 才到 BookingTime

新主單 102 的回饋此時才可能開始處理;NMQ 實際起跑仍受佇列影響。

約 11:00:現行回饋稽核也已到 BookingTime

若只交換處理 Task 的時間、稽核不動,稽核可能早於主單 102 的回饋完成。

這是依目前排程規則推演的假設情境。原有回收分派稽核與點數回收稽核仍分別約在 14:30、15:00。

真正的分界不在「今天的正向 Job 跑完了嗎」,而在回收指向的那張主單是否已有可處理的回饋紀錄。點數回收查不到 DDB 給點紀錄會拋錯;給券回收查不到 DDB 給券紀錄也會拋錯。即使查得到,還要符合各自的回饋狀態與後續回收條件。

範圍 先跑回收的判斷
重算模式,且負向子單在 filteredReturnOrderSlaves 通常指向本批以外的正向主單;若該主單的回饋紀錄已備妥,沒有等待本批新正向 Task 的直接依賴。
重算模式,但負向子單不在 filtered 逆流程本來就不為這筆另建回收 Task,由本批正流程處理。
舊模式 不看 filtered。負向子單可能勾稽本批正向主單;若其回饋紀錄尚未建立,立即回收可能失敗。

所以,「重算模式的 filtered 回收先跑」與「所有回收都先跑」是兩個不同提案。若要選擇性提前,Dispatcher 還需能辨認每筆回收請求所屬模式;目前 RecycleRequestEntity 沒有直接保存重算模式欄位。若把所有正向 Task 改成六個半小時後才跑,也必須重新安排回饋稽核,不能讓稽核與正向處理同時起跑。這些都是設計上的待確認條件,並非已驗證的改動結果。

查看本篇對照的主要程式碼

PromotionRewardBatchDispatcherV2Job.cs 負責查詢、分類、分組、S3 與 NMQ 派發;PromotionService.cs 的 ProcessPromotionRewardByOrders 和 ProcessRecycleByOrderSalves 負責活動比對與請求建立;RecycleLoyaltyPointsV2.cs 是點數回收下游入口。