付款前先留名額,付款後才談給券

同一筆回饋券,會跟著訂單從未付款走到已付款;活動若有名額限制,還得先確認佔額紀錄。

顧客建立訂單、還沒付款時,系統就會收到 OrderPlaced 事件;等付款成功,才會收到 OrderCreated 事件。回饋券也跟著這兩個時間點分工:需要限量名額的活動先佔額,付款成功後再進入給券流程。PromotionRewardCouponJob 負責處理這兩步。

先看這兩個事件如何接力:

事件進來後,Job 分別做什麼

這是責任總覽;發券前還會檢查紀錄狀態、回饋時間與訂單現況。

同一筆訂單的三個時間點

已建單、未付款:OrderPlaced

商店建立佔額活動時會配 GroupCode。分派器只找有此欄位的在期活動,先嘗試保留名額並留下紀錄。

付款成功:OrderCreated

分派器找所有 RewardReachPriceWithCoupon 活動。有佔額的接續舊紀錄;沒有佔額的在這一步試算、建檔。

佔額活動的給券任務:再等 5 分 10 秒

兩個事件各自建立任務,付款成功時不能假設佔額紀錄已寫好。

線上佔額活動若找不到先前紀錄,Job 會拒絕給券。程式註解只說明額外 10 秒是避免剛好排在 5 分鐘時任務立即執行,沒有交代為何選 5 分鐘。

同一支 Job,兩種任務大小

付款成功帶來一張訂單;回饋時間到了,分派器可能把同會員、同活動的多張訂單排成一隊。

同樣是進入 PromotionRewardCouponJob,任務裡裝的資料卻不一定一樣。付款成功的 OrderCreated 入口,通常是一筆任務處理一張訂單與一個活動;到了回饋紀錄的 BookingTime,則可能把同一會員、同一活動的多張訂單放進一筆任務。兩條路徑如下:

即時與回饋時間入口的任務大小

上方是一張訂單的任務;下方是按會員、活動分組的任務。

兩個 BookingTime 指的是不同時間

5 分 10 秒NMQ 任務的預約執行時間,讓佔額任務有機會先留下紀錄。
回饋時間DynamoDB 紀錄的 BookingTime,用來挑出已到期的待回饋訂單。
回饋時間分派器先排序同組訂單再存 S3。Job 依清單處理,不重新排序;即使只有一張,也走 S3 批次入口。

同一支 Job 會收到單筆任務,也會收到一組訂單。處理順序要看任務帶的是單張訂單資料,還是會員與 S3 清單索引。

查看任務欄位各自負責什麼
欄位 在流程裡負責什麼
ShopId、PromotionEngineId、OrderDateTime 找到訂單成立時適用的活動規則,並用來試算
OrderTypeDefEnum 區分訂單來源;ECom 用 TradesOrderGroupCode,Others 用 CrmSalesOrderId
EventSource 決定入口;OrderPlaced 走佔額,其餘走給券。沒提供時預設為 OrderCreated
RewardFlowEnum 預設為 Reward;試算服務在 Recycle 時改用未回收訂單計算,但這個 Job 仍以 EventSource 決定主分支
MemberId、S3Key 會員編號大於 0 且 S3 鍵值非空白,才會從 S3 下載多筆訂單
PromotionEngineType、RelatedOrderSlaveIdList 線下訂單試算會用到;計算服務也會檢查活動類型

不論入口是哪一種,實際處理前都會先鎖住「活動加訂單」,再讀規則與 DynamoDB 紀錄,避免同一筆回饋同時被兩個任務處理。

先保留,再確認能不能發

未付款時只嘗試佔額。付款成功後,Job 才依紀錄狀態與回饋時間決定要等待還是給券。

OrderPlaced:先替訂單保留額度

訂單已建立、還沒付款。Job 在這一步只確認資格並嘗試保留名額,流程到寫入紀錄為止。

付款前如何留下佔額紀錄

這一步只寫回饋紀錄,不呼叫 SCM 發券。

試算會取得券種、張數、回饋時間與子單資訊。此時線上訂單的 ERP 資料尚未產生,Job 會從 WebStore 取單。這一步不呼叫發券 API,也不建立績效 Task。

對限量活動來說,這一步的意義是先替尚未付款的訂單爭取名額;名額保留下來,也還不能當成券已經發給會員。付款成功後,另一個任務才會接手。

程式位置:PromotionRewardCouponJob.cs:259-317,597-645、PromotionRewardCalculateServiceBase.cs:245-372、EComOrderPromotionRewardCalculateService.cs:231-257、CouponService.cs:477-546。

OrderCreated 或未帶事件來源:確認何時能發券

付款成功後,Job 要先看佔額紀錄是否已留下。上一節提到的回饋時間批次任務,也會從「讀取紀錄」走進同一段給券流程。

付款後如何走向發券

付款成功也可能先等待;只有待回饋且時間已到才進入給券方法。

圖中省略了兩個細節:

  • 首次建檔:非佔額活動與線下訂單會重新試算;符合活動,且不需佔額或佔額成功時,才建立績效 Task。
  • 會員核對:線上訂單的會員編號若與紀錄不同,Job 會查目前的會員資料,更新這次發券使用的編號;查不到就拋錯。

績效 Task 建立失敗只記錄錯誤,不會讓給券主流程立刻中斷。程式位置:PromotionRewardCouponJob.cs:323-453,461-499,647-678。

因此「付款成功」只代表可以開始檢查回饋,並不等於立刻拿到券。WaitToReward 還要通過回饋時間與訂單狀態的檢查,才會走到真正的發券方法。

狀態記下回饋走到哪一步

保留名額、等待發券、真正發完,是不同階段。看狀態時,先分清楚會員是否已經拿到券。

回饋紀錄像一張進度單。它先記下是否中活動、是否佔到額度;等到發券時間,才記下最後有沒有把券送完。不同情況會留下不同狀態:

查看各種情境對應的主表狀態
發生什麼事 主表狀態 接下來怎麼走
試算沒有中活動 Unmatch 不發券
中活動,且不需要預先佔額 WaitToReward 等 BookingTime 到了再處理
中活動,但佔額失敗 MatchWithoutQuota 不發券,也不計入應給券統計
線上訂單佔額成功 Occupy 等 OrderCreated 轉成 WaitToReward
線下訂單佔額成功 WaitToReward 到了回饋時間後處理
券已全部發出 Reward 給券完成
只發出部分券 WaitToReward 保留已給張數,依失敗原因安排後續處理
線上整單取消或退貨,且已無可給明細 Cancel 不發券;佔額活動返還額度

從保留名額到發券完成

WaitToReward 表示尚待處理,並不代表會員已拿到券。

這些狀態記的是回饋走到哪一步,不只是成功或失敗。Occupy 表示名額已保留、仍在等付款後接手;WaitToReward 表示可以等待給券,但券尚未送出。因此,Unmatch 與 MatchWithoutQuota 不進入發券,WaitToReward 也不能當作已發券。

取消還沒定案,券先不要走

給券前若碰到處理中的取消或退貨,Job 先把下一次檢查時間往後移。

逆流程還在處理時,這次給券如何收場

先查四種單據

取消申請、取消單、退貨申請、退貨單;其中任一流程未結束,就先停下發券。

回饋時間往後一天

主表 BookingTime 加一天,狀態仍是 WaitToReward。

下次再看結果

這次不改 TotalCouponQty、GivenCouponQty,也不返還佔額。

一天是下次檢查時間,不代表取消或退貨一定會在一天內結束。

先等逆流程定案,能避免對可能被取消的訂單發券,也避免太早放回已保留的活動名額。

訂單已全退,名額也該回去

即使任務走在正向給券流程,發券前看見整單已取消或退貨,也會停下來處理佔額返還。

這個判斷仍發生在正向給券流程中,即使 RewardFlowEnum=Reward,Job 也會在發券前確認子單是否仍有可給明細。

什麼時候改成 Cancel,並返還名額

沒有可給明細,才走整單取消分支;仍有可給明細時走一般給券流程。

模擬訂單 TG250625T00005 的四個動作

確認取消已完成

GetCancelOrderSlaves 取得 TS-A、TS-B;沒有進行中的逆流程。

可給明細已歸零

兩筆明細都已取消或退貨,沒有仍應給券的明細。

停止發券,返還佔額

ProcessAllOrderCanceledAsync 改為 Cancel;活動 7307 的 GroupCode=POOL-A,因此呼叫 ReverseOccupyQuotaAsync。

寫回結果

FinalizeCouponRewardProcessAsync 更新紀錄與統計,不因券未發完而拋 Redo。

這是依程式碼推演的情境,並非實際訂單執行紀錄。

狀態變了,原本應給張數仍保留

WaitToReward → Cancel主表狀態
5 → 5主表 TotalCouponQty
0 → 0主表 GivenCouponQty
這次一張券都沒有發。Info 的 GivenCouponQty 不增加,CanceledCouponQty 也不由這段正流程直接增加。

Cancel 表示這筆回饋已終止。TotalCouponQty=5 保留原本試算的張數,不能單靠它推斷還有券待發。

線上訂單還會變,給券前得再看一次

線上子單可能出貨、取消或退貨;線下訂單在這段流程視為已完成,因此兩種入口需要的檢查不同。

OrderTypeDefEnum 決定方法入口。線上訂單付款後還可能出貨、取消或退貨,因此得核對子單與逆流程;線下訂單在此段流程視為完成,直接進入發券核心。

兩種訂單如何抵達同一套發券核心

線上路徑多了訂單狀態檢查;能發券時,兩條路徑共用張數計算與 SCM 發券核心。
查看線上與線下的逐項差異
比較項目 線上:ProcessRewardCouponAsync 線下:ProcessCrmOrderRewardCouponAsync
發券前 檢查取消申請、取消單、退貨申請與退貨單 不做這段檢查,直接進入發券核心
逆流程仍在處理 BookingTime 順延一天,本次不發券 沒有對應分支
已整單取消或退貨,且無可給明細 改成 Cancel;佔額活動返還額度 沒有對應分支
可以發券 呼叫 ExecuteCouponRewardCoreAsync 呼叫同一個核心方法
發券後 更新明細、主表與已給券統計;整單取消會影響是否拋出 Redo 例外 使用相同更新方法,但沒有整單取消分支

線下方法雖然接收 locationName、crmSalesOrderCode,目前方法內並沒有讀取它們;這兩個參數不影響這段 DispatchAsync 請求或 DynamoDB 狀態。

一張一張發,成功幾張就記幾張

Worker 先算還差多少券,再逐張呼叫 SCM;回應裡的成功張數,才會推動已給張數前進。

應給五張,已給兩張,這次只補三張

總共應給 5 張

主表 TotalCouponQty=5。

已成功發出 2 張

主表 GivenCouponQty=2。

這次還要嘗試 3 張

5 - 2 = 3;每張各呼叫一次 DispatchAsync,請求 Qty=1。

部分成功會留在已給張數裡。下一次任務按差額補發,不重新從第一張開始。

Worker 呼叫 SCM 的 /v2/ECoupon/Dispatch,請求帶商店、會員、券 ID、新產生的 EventCode 與 SourceDef=PromotionWorker。

每張券的回應如何影響最後的紀錄

有收到一般失敗回應時,不自動重試該張;仍讀取可取得的成功張數。圖中省略重試上限與特殊例外,見下方明細。
查看 SCM 回傳欄位與 Worker 的判斷
回傳欄位 Worker 如何使用
Status 不是 Success 就記錄錯誤,再檢查是否為券庫不足;一般失敗回應不會自動重試
ErrorMessage 比對「券已發送一空/完畢」等多語言文字;若判定券不足,停止後續發券
Data.SuccessCount 累加本次成功張數,之後加到主表與 Info 表的 GivenCouponQty
Data.FailCount 累加供日誌與結果比對,不直接決定主表狀態
Data.ECouponSlaves[].Id 記下實際發出的券序號
Data.ReturnCode 回傳模型有這個欄位,但這段 Worker 沒拿它做判斷

Status 用來辨識錯誤與是否停止;真正增加已給張數的是 Data.SuccessCount。呼叫過 API,並不代表會員已收到券。

查看券不足、部分成功與例外的後續處理
給券結果 主表與後續處理
應給張數全數發完 主表與明細改為 Reward,累加 Info 表已給券張數
只發出部分,且不是券庫不足 保留已給張數與 WaitToReward,拋出可釋放鎖的失敗例外,供後續 Redo
券庫不足 停止呼叫發券 API,保留 WaitToReward;符合條件時重新安排 BookingTime。若活動在排除清單或已超過活動結束後 90 天,則保留原時間並記錄原因
活動或通路不符合、線下查不到訂單 釋放鎖,結束本次處理
線上佔額紀錄或會員資料缺失 釋放鎖並拋出失敗例外
其他未分類例外 記錄 MetricsLog 並重新拋出;這個 catch 本身沒有釋放鎖

券不足時拋出的例外會由 Job 釋放鎖並結束本次任務。其他給券未完成的情況則會釋放鎖後重新拋出。

一張訂單的帳,和整檔活動的帳

主表追單筆訂單,Info 表累加同活動、同券的多筆訂單。兩邊都叫「應給」,範圍卻不同。

主表追一筆訂單在一個活動中的回饋;PromotionRewardCouponInfo 則把同商店、同活動、同一種券的多筆訂單加在一起,key 是 ShopId_PromotionEngineId_ECouponId。

兩張訂單的張數,怎麼加到同一筆 Info

假設兩張訂單屬於同一商店、活動與券。這是正常建立與發券路徑的數字示例,並非實際 DynamoDB 紀錄。
查看主表與 Info 表各欄位的用途
欄位 代表的張數
主表 TotalCouponQty 這筆訂單試算應給幾張;正常發券不改動
主表 GivenCouponQty 這筆訂單至今實際成功發出幾張
Info ShouldGiveCouponQty 同商店、活動、券的累計應給張數;符合條件的新紀錄會把該筆 TotalCouponQty 加進來
Info GivenCouponQty 同商店、活動、券的累計已給張數;每次只加本次實際成功張數
Info CanceledCouponQty 供重算流程記錄取消張數;正流程整單取消不會直接增加它

主表回答「這張訂單下次還要補幾張」;Info 表回答「這檔活動的這種券累計應給、已給多少張」。不能把單筆主表的 TotalCouponQty 當成 Info 的 ShouldGiveCouponQty。

正流程發現整單取消時,主表可能改為 Cancel,但 TotalCouponQty 不會在這裡歸零,Info 的 CanceledCouponQty 也不會直接增加。因此不能把 Info 的 ShouldGiveCouponQty - GivenCouponQty 直接當成「接下來一定會發出的張數」。取消或退貨後的重算是另一段流程,會嘗試依新的應給張數調整主表與 Info 統計。

退貨後從五張重算成三張,差額在哪裡遺失

重算前:應給 5,已給 0

假設 Info 只有這筆訂單,ShouldGiveCouponQty=5、CanceledCouponQty=0。

退貨重算:應給變成 3

第一個方法先把主表 TotalCouponQty 從 5 改成 3。

更新 Info 時,舊張數已不在

下一個方法把同一欄位的 3 當成原本張數,算出 3 - 3 = 0。

依目前程式碼推演,Info 仍是 ShouldGive 5、Canceled 0;若記下少掉的兩張,Canceled 應加到 2。尚未用實際資料驗證。
查看重算前後的欄位數字
欄位 重算前 依目前程式碼推演 若正確記下減少的 2 張
主表 TotalCouponQty 5 3 3
主表 GivenCouponQty 0 0 0
Info ShouldGiveCouponQty 5 5 5
Info CanceledCouponQty 0 0 2

UpdateBasedOnCalculation 先改主表,才從同一物件取「原本張數」更新 Info。呼叫順序可確認舊張數會遺失;實際資料是否已受影響,仍需重算測試或查詢紀錄。程式位置:CouponService.cs:801-855,869-915,1059-1107。