正式給券回饋設計
付款前先留名額,付款後才談給券
同一筆回饋券,會跟著訂單從未付款走到已付款;活動若有名額限制,還得先確認佔額紀錄。
顧客建立訂單、還沒付款時,系統就會收到 OrderPlaced 事件;等付款成功,才會收到 OrderCreated 事件。回饋券也跟著這兩個時間點分工:需要限量名額的活動先佔額,付款成功後再進入給券流程。PromotionRewardCouponJob 負責處理這兩步。
先看這兩個事件如何接力:
事件進來後,Job 分別做什麼
flowchart TD
A["OrderPlaced:已建單,未付款"] --> B["佔額活動分派"]
C["OrderCreated:付款成功"] --> D["回饋活動分派"]
E["批次或預約回饋"] --> F["低優先權任務"]
B --> G["PromotionRewardCouponJob"]
D --> G
F --> G
G --> H{"事件是 OrderPlaced?"}
H -- "是" --> I["佔額並寫入回饋紀錄"]
H -- "否" --> J["讀取或建立紀錄,檢查回饋時間"]
J --> M{"狀態與時間都允許給券?"}
M -- "是" --> K["呼叫 SCM API 發券"]
M -- "否" --> N["等待或略過本次給券"]
I --> L[("DynamoDB 回饋資料")]
J --> L
K --> L
同一筆訂單的三個時間點
商店建立佔額活動時會配 GroupCode。分派器只找有此欄位的在期活動,先嘗試保留名額並留下紀錄。
分派器找所有 RewardReachPriceWithCoupon 活動。有佔額的接續舊紀錄;沒有佔額的在這一步試算、建檔。
兩個事件各自建立任務,付款成功時不能假設佔額紀錄已寫好。
同一支 Job,兩種任務大小
付款成功帶來一張訂單;回饋時間到了,分派器可能把同會員、同活動的多張訂單排成一隊。
同樣是進入 PromotionRewardCouponJob,任務裡裝的資料卻不一定一樣。付款成功的 OrderCreated 入口,通常是一筆任務處理一張訂單與一個活動;到了回饋紀錄的 BookingTime,則可能把同一會員、同一活動的多張訂單放進一筆任務。兩條路徑如下:
即時與回饋時間入口的任務大小
flowchart TD
A["OrderCreated:付款成功"] --> B["每張訂單、每個回饋券活動建立任務"]
B --> C{"活動有 GroupCode?"}
C -- "有" --> D["NMQ 任務排在 5 分 10 秒後"]
C -- "沒有" --> E["NMQ 任務未設定預約時間"]
D --> F["單筆請求:一張訂單與一個活動"]
E --> F
G["DynamoDB 回饋紀錄的 BookingTime 進入查詢時段"] --> H["分派器找出 WaitToReward 紀錄"]
H --> I["依商店、會員、活動分組"]
I --> J["組內按訂單時間排序,清單存入 S3"]
J --> K["每組建立一筆低優先權任務"]
K --> L["批次請求:一組訂單與一個活動"]
F --> M["PromotionRewardCouponJob"]
L --> M
M --> N{"任務帶會員編號與 S3Key?"}
N -- "否" --> O["直接處理這張訂單"]
N -- "是" --> P["下載 S3 清單,依序逐筆處理"]
O --> Q["共用給券處理流程"]
P --> Q
兩個 BookingTime 指的是不同時間
同一支 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 在這一步只確認資格並嘗試保留名額,流程到寫入紀錄為止。
付款前如何留下佔額紀錄
flowchart TD
A["OrderPlaced:尚未付款"] --> B["取得鎖與活動規則"]
B --> C{"活動有 GroupCode?"}
C -- "沒有" --> Z["略過佔額"]
C -- "有" --> D{"DynamoDB 已有回饋紀錄?"}
D -- "有" --> Y["結束,避免重複佔額"]
D -- "沒有" --> E["取訂單與會員資料,試算回饋券"]
E --> F{"符合活動?"}
F -- "沒有" --> G["記為 Unmatch"]
F -- "有" --> H["呼叫 OccupyQuotaAsync"]
H --> I{"回傳 Redeemed?"}
I -- "有" --> J["記為 Occupy"]
I -- "沒有" --> K["記為 MatchWithoutQuota"]
G --> L["寫入 DynamoDB 回饋紀錄"]
J --> L
K --> L
試算會取得券種、張數、回饋時間與子單資訊。此時線上訂單的 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 要先看佔額紀錄是否已留下。上一節提到的回饋時間批次任務,也會從「讀取紀錄」走進同一段給券流程。
付款後如何走向發券
flowchart TD
A["OrderCreated 或回饋時間批次任務"] --> B["取得鎖與活動規則,讀取 DynamoDB"]
B --> C{"已有回饋紀錄?"}
C -- "沒有" --> D{"線上佔額活動?"}
D -- "是" --> E["報錯:不能跳過付款前佔額"]
D -- "否" --> F["重新試算,依規則佔額並建立紀錄"]
C -- "有" --> G{"狀態是 Occupy?"}
F --> G
G -- "是" --> H["建立績效 Task,轉為 WaitToReward"]
G -- "否" --> I{"狀態是 WaitToReward?"}
H --> I
I -- "否" --> J["停止,不進入給券"]
I -- "是" --> K{"線上訂單且要求完成後回饋?"}
K -- "是" --> L["依訂單狀態重算 BookingTime"]
K -- "否" --> M{"回饋時間到了?"}
L --> M
M -- "沒有" --> N["保留 WaitToReward,繼續等待"]
M -- "到了" --> O{"線上或線下訂單?"}
O -- "線上" --> P["核對子單與會員資料"]
P --> Q["ProcessRewardCouponAsync"]
O -- "線下" --> R["取得門市與 CRM 訂單代碼"]
R --> S["ProcessCrmOrderRewardCouponAsync"]
圖中省略了兩個細節:
- 首次建檔:非佔額活動與線下訂單會重新試算;符合活動,且不需佔額或佔額成功時,才建立績效 Task。
- 會員核對:線上訂單的會員編號若與紀錄不同,Job 會查目前的會員資料,更新這次發券使用的編號;查不到就拋錯。
績效 Task 建立失敗只記錄錯誤,不會讓給券主流程立刻中斷。程式位置:PromotionRewardCouponJob.cs:323-453,461-499,647-678。
因此「付款成功」只代表可以開始檢查回饋,並不等於立刻拿到券。WaitToReward 還要通過回饋時間與訂單狀態的檢查,才會走到真正的發券方法。
狀態記下回饋走到哪一步
保留名額、等待發券、真正發完,是不同階段。看狀態時,先分清楚會員是否已經拿到券。
回饋紀錄像一張進度單。它先記下是否中活動、是否佔到額度;等到發券時間,才記下最後有沒有把券送完。不同情況會留下不同狀態:
查看各種情境對應的主表狀態
| 發生什麼事 | 主表狀態 | 接下來怎麼走 |
|---|---|---|
| 試算沒有中活動 | Unmatch |
不發券 |
| 中活動,且不需要預先佔額 | WaitToReward |
等 BookingTime 到了再處理 |
| 中活動,但佔額失敗 | MatchWithoutQuota |
不發券,也不計入應給券統計 |
| 線上訂單佔額成功 | Occupy |
等 OrderCreated 轉成 WaitToReward |
| 線下訂單佔額成功 | WaitToReward |
到了回饋時間後處理 |
| 券已全部發出 | Reward |
給券完成 |
| 只發出部分券 | WaitToReward |
保留已給張數,依失敗原因安排後續處理 |
| 線上整單取消或退貨,且已無可給明細 | Cancel |
不發券;佔額活動返還額度 |
從保留名額到發券完成
stateDiagram-v2
[*] --> Unmatch: 未中活動
[*] --> MatchWithoutQuota: 中活動但佔額失敗
[*] --> Occupy: 線上中活動且佔額成功
[*] --> WaitToReward: 無須預佔或線下佔額成功
Occupy --> WaitToReward: OrderCreated
WaitToReward --> WaitToReward: 未到時間、逆流程進行中或發券未完成
WaitToReward --> Reward: 已給張數達應給張數
WaitToReward --> Cancel: 線上整單取消或退貨
這些狀態記的是回饋走到哪一步,不只是成功或失敗。Occupy 表示名額已保留、仍在等付款後接手;WaitToReward 表示可以等待給券,但券尚未送出。因此,Unmatch 與 MatchWithoutQuota 不進入發券,WaitToReward 也不能當作已發券。
取消還沒定案,券先不要走
給券前若碰到處理中的取消或退貨,Job 先把下一次檢查時間往後移。
逆流程還在處理時,這次給券如何收場
取消申請、取消單、退貨申請、退貨單;其中任一流程未結束,就先停下發券。
主表 BookingTime 加一天,狀態仍是 WaitToReward。
這次不改 TotalCouponQty、GivenCouponQty,也不返還佔額。
先等逆流程定案,能避免對可能被取消的訂單發券,也避免太早放回已保留的活動名額。
訂單已全退,名額也該回去
即使任務走在正向給券流程,發券前看見整單已取消或退貨,也會停下來處理佔額返還。
這個判斷仍發生在正向給券流程中,即使 RewardFlowEnum=Reward,Job 也會在發券前確認子單是否仍有可給明細。
什麼時候改成 Cancel,並返還名額
flowchart TD
A["線上訂單到給券時間"] --> B{"取消或退貨仍在處理?"}
B -->|"是"| C["順延一天,不發券"]
B -->|"否"| D{"有取消明細且無可給明細?"}
D -->|"否"| E["繼續一般給券流程"]
D -->|"是"| F["主表與明細改 Cancel,不呼叫發券 API"]
F --> G{"活動有 GroupCode?"}
G -->|"有"| H["返還先前佔用的名額"]
G -->|"沒有"| I["無須返還佔額"]
H --> J["寫回結果,不以未發完券拋 Redo"]
I --> J
模擬訂單 TG250625T00005 的四個動作
GetCancelOrderSlaves 取得 TS-A、TS-B;沒有進行中的逆流程。
兩筆明細都已取消或退貨,沒有仍應給券的明細。
ProcessAllOrderCanceledAsync 改為 Cancel;活動 7307 的 GroupCode=POOL-A,因此呼叫 ReverseOccupyQuotaAsync。
FinalizeCouponRewardProcessAsync 更新紀錄與統計,不因券未發完而拋 Redo。
狀態變了,原本應給張數仍保留
GivenCouponQty 不增加,CanceledCouponQty 也不由這段正流程直接增加。Cancel 表示這筆回饋已終止。TotalCouponQty=5 保留原本試算的張數,不能單靠它推斷還有券待發。
線上訂單還會變,給券前得再看一次
線上子單可能出貨、取消或退貨;線下訂單在這段流程視為已完成,因此兩種入口需要的檢查不同。
OrderTypeDefEnum 決定方法入口。線上訂單付款後還可能出貨、取消或退貨,因此得核對子單與逆流程;線下訂單在此段流程視為完成,直接進入發券核心。
兩種訂單如何抵達同一套發券核心
flowchart TD
A["OrderTypeDefEnum"] --> B{"訂單來源?"}
B -->|"ECom 線上"| C["ProcessRewardCouponAsync"]
B -->|"Others 線下"| D["ProcessCrmOrderRewardCouponAsync"]
C --> E{"取消或退貨仍在處理?"}
E -->|"是"| F["BookingTime 順延一天"]
E -->|"否"| G{"整單已取消且無可給明細?"}
G -->|"是"| H["Cancel,佔額活動返還名額"]
G -->|"否"| I["ExecuteCouponRewardCoreAsync"]
D --> I
I --> J["更新明細、主表與已給券統計"]
查看線上與線下的逐項差異
| 比較項目 | 線上:ProcessRewardCouponAsync |
線下:ProcessCrmOrderRewardCouponAsync |
|---|---|---|
| 發券前 | 檢查取消申請、取消單、退貨申請與退貨單 | 不做這段檢查,直接進入發券核心 |
| 逆流程仍在處理 | BookingTime 順延一天,本次不發券 |
沒有對應分支 |
| 已整單取消或退貨,且無可給明細 | 改成 Cancel;佔額活動返還額度 |
沒有對應分支 |
| 可以發券 | 呼叫 ExecuteCouponRewardCoreAsync |
呼叫同一個核心方法 |
| 發券後 | 更新明細、主表與已給券統計;整單取消會影響是否拋出 Redo 例外 | 使用相同更新方法,但沒有整單取消分支 |
線下方法雖然接收 locationName、crmSalesOrderCode,目前方法內並沒有讀取它們;這兩個參數不影響這段 DispatchAsync 請求或 DynamoDB 狀態。
一張一張發,成功幾張就記幾張
Worker 先算還差多少券,再逐張呼叫 SCM;回應裡的成功張數,才會推動已給張數前進。
應給五張,已給兩張,這次只補三張
主表 TotalCouponQty=5。
主表 GivenCouponQty=2。
5 - 2 = 3;每張各呼叫一次 DispatchAsync,請求 Qty=1。
Worker 呼叫 SCM 的 /v2/ECoupon/Dispatch,請求帶商店、會員、券 ID、新產生的 EventCode 與 SourceDef=PromotionWorker。
每張券的回應如何影響最後的紀錄
flowchart TD
A["計算剩餘張數"] --> B["每張券呼叫 DispatchAsync,Qty=1"]
B --> C{"得到什麼結果?"}
C -->|"一般回應"| D["讀取 Data.SuccessCount 與券序號"]
C -->|"券庫不足"| E["停止後續發券"]
C -->|"指定連線或逾時例外"| F["本張券指數退避重試"]
F --> B
D --> G["迴圈結束後累加 GivenCouponQty"]
E --> G
G --> H{"GivenCouponQty 達 TotalCouponQty?"}
H -->|"是"| I["記為 Reward"]
H -->|"否"| J["保留 WaitToReward,按失敗原因處理"]
查看 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
flowchart LR A["訂單 A:應給 2,已給 2"] -->|"應給 +2"| C["Info ShouldGive = 5"] B["訂單 B:應給 3,已給 1"] -->|"應給 +3"| C A -->|"已給 +2"| D["Info Given = 3"] B -->|"已給 +1"| D
查看主表與 Info 表各欄位的用途
| 欄位 | 代表的張數 |
|---|---|
主表 TotalCouponQty |
這筆訂單試算應給幾張;正常發券不改動 |
主表 GivenCouponQty |
這筆訂單至今實際成功發出幾張 |
Info ShouldGiveCouponQty |
同商店、活動、券的累計應給張數;符合條件的新紀錄會把該筆 TotalCouponQty 加進來 |
Info GivenCouponQty |
同商店、活動、券的累計已給張數;每次只加本次實際成功張數 |
Info CanceledCouponQty |
供重算流程記錄取消張數;正流程整單取消不會直接增加它 |
主表回答「這張訂單下次還要補幾張」;Info 表回答「這檔活動的這種券累計應給、已給多少張」。不能把單筆主表的 TotalCouponQty 當成 Info 的 ShouldGiveCouponQty。
正流程發現整單取消時,主表可能改為 Cancel,但 TotalCouponQty 不會在這裡歸零,Info 的 CanceledCouponQty 也不會直接增加。因此不能把 Info 的 ShouldGiveCouponQty - GivenCouponQty 直接當成「接下來一定會發出的張數」。取消或退貨後的重算是另一段流程,會嘗試依新的應給張數調整主表與 Info 統計。
退貨後從五張重算成三張,差額在哪裡遺失
假設 Info 只有這筆訂單,ShouldGiveCouponQty=5、CanceledCouponQty=0。
第一個方法先把主表 TotalCouponQty 從 5 改成 3。
下一個方法把同一欄位的 3 當成原本張數,算出 3 - 3 = 0。
查看重算前後的欄位數字
| 欄位 | 重算前 | 依目前程式碼推演 | 若正確記下減少的 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。



