uniquekey 設計
消費者打開購物車,系統整理此刻要買的商品,交出第一把鑰匙。按下結帳後,另一把鑰匙帶著這次交易走向付款頁。兩把鑰匙都叫 unique key,卻分別守著購物車與結帳流程。先看它們各自指向什麼,再循著程式的交接路線往下走。
CartUniqueKey 對應一次建立或讀取購物車時的 CartEntity。它不是會員永久固定的購物車編號。商品如何變成購物車快照?
flowchart LR A["ShoppingCart 商品"] --> B["Cart Domain 計算"] B --> C["CartEntity 快照"] D["CartUniqueKey 沿用或新建"] --> C C --> E["CartCache Redis"] C --> F["Shopping 回傳給呼叫方"]
一般進車流程會依會員,或免登入情境的 UnloginId,從 ShoppingCart table 取商品,再計算出 CartEntity。同一位會員再次進車,可能取得另一個 key。CartEntity 除了商品與數量,也包含勾選狀態、不可購買商品、價格、促銷與優惠券計算結果,以及金流、物流選擇。它會隨操作重新計算與更新。
| 追查點 | 現行實作 |
|---|---|
| 產生位置 | Cart Domain CartCreateProcessor |
| 產生條件 | context.CartUniqueKey ?? Guid.NewGuid().ToString();已有 key 就沿用 |
| 取得入口 | Shopping POST /api/carts/create 呼叫 Cart Domain POST /api/carts/create |
| 用途 | 找回 CartEntity、組成 Redis 快取 key、帶入 checkout create |
CheckoutUniqueKey。產生 CartUniqueKey 也不保證每個分支都完成 Redis 寫入;空車與全售完的情況見「第一把鑰匙的程式路徑」。一個流程 key,分別落在哪裡?
flowchart LR A["CartUniqueKey"] -->|"讀取"| B["CartEntity"] B -->|"建立"| C["CheckoutEntity"] D["WebStore PayLite"] -->|"產生"| E["CheckoutUniqueKey"] E -->|"儲存索引"| C E -->|"儲存索引"| F["PayProcessContext"] E -->|"放入 k"| G["MWeb 付款 URL"]
CheckoutEntity 繼承 CartEntity,再加入 CheckoutUniqueKey、信用卡顯示資訊等結帳欄位。WebStore 的 PayProcessContext 則供 MWeb 付款頁與後續付款處理使用。CheckoutUniqueKey 不是從 CartUniqueKey 複製或轉換而來;WebStore 會為這次流程另外產生 GUID,Cart Domain 再採用回傳的值。
| 追查點 | 現行實作 |
|---|---|
| 產生位置 | WebStore WebAPI PayLiteController.RequestPayProcessUrlV3 進入的共用方法 |
| 寫入位置 | PayProcessContext.UniqueKey、ContextId、付款 URL 的 k |
| 取得入口 | Shopping POST /api/checkout/create 帶 CartUniqueKey;Cart Domain 呼叫 PayLite |
| 用途 | 查找 CheckoutEntity,並讓 MWeb 找到同次的 PayProcessContext |
API 交接表
| 階段 | 入口與帶入值 | 回傳或使用的值 |
|---|---|---|
| 進購物車 | Shopping POST /api/carts/create;不要求先提供 CartUniqueKey |
CartEntity.CartUniqueKey |
| 讀購物車 | Shopping GET /api/carts?cartUniqueKey=... |
既有 CartUniqueKey |
| 建立結帳 | Shopping POST /api/checkout/create;帶 CartUniqueKey |
CheckoutCreateResponse.UniqueKey,即 CheckoutUniqueKey,以及付款 URL |
| 讀結帳 | Shopping GET /api/checkout?checkoutUniqueKey=... |
既有 CheckoutUniqueKey |
有效時間各由誰決定?
| 資料 | 邏輯或實體期限 | 已查到的設定 |
|---|---|---|
CartEntity、CheckoutEntity |
邏輯有效時間從 ShoppingDateTimeUtc 起算 30 分鐘 |
Redis 實體 TTL 由 CacheExpireSetting:CoreData.ExpireMinutes 控制;TW Prod 30 分鐘,HK/MY Prod 60 分鐘 |
PayProcessContext |
WebStore 暫存期限,與上列分開 | ShoppingCart.TmpData.RedisExpiredDays 預設 7 天;本機 WebAPI Prod 設定 3 天 |
CartEntity,再視流程分支決定是否走到快取寫入。產生與快取的分支
flowchart TD
A["CartCreateProcessor"] --> B{"context.CartUniqueKey 有值?"}
B -->|"有"| C["沿用既有 key"]
B -->|"沒有"| D["Guid.NewGuid"]
C --> E["寫入 context.Data.CartUniqueKey"]
D --> E
E --> F{"購物車內容"}
F -->|"正常商品"| G["CacheCartDataProcessor 儲存"]
F -->|"空車或全售完"| H["可能提早中斷 Processor"]
程式呼叫的先後
- Shopping
CartsController.Create交給CartService.CartCreateAsync建立CartContext。 - Shopping
CartCreateProcessor透過DomainApiHelper呼叫 Cart Domainapi/carts/create,並把回傳Data放進context.Data。 - Cart Domain
CartsController.Create呼叫CartService.CartCreateAsync;GetCart流程先跑CartCreateProcessor,後段有CacheCartDataProcessor。 - Cart Domain 以
context.CartUniqueKey ?? Guid.NewGuid().ToString()決定 key,放入context.Data.CartUniqueKey,再由 Shopping 回傳CartEntity。
一般 Cart create 的 CartContext 未預填 key,所以會新建;代客下單或保留既有 context key 的情境可能沿用。正常商品分支會走到 CacheCartDataProcessor;空車或全售完可能提前中斷。Cart Service 因金流或物流重新計算時,也會傳入既有 CartUniqueKey。
CartUniqueKey 找到購物車後,Cart Domain 呼叫 PayLite。WebStore 建立流程、暫存 context,並把新 key 放進網址,讓 Cart Domain 與 MWeb 都能接續。跨系統呼叫時序
sequenceDiagram participant S as Shopping participant C as Cart Domain participant W as WebStore PayLite S->>C: checkout/create 帶 CartUniqueKey C->>C: 檢查過期並讀 CartEntity C->>W: RequestPayProcessUrlV3 W->>W: 建 PayProcessContext 並產生 GUID W->>W: 暫存 context,URL 加入 k W-->>C: 回傳付款 URL C->>C: 解析 k,儲存 CheckoutEntity C-->>S: 回傳 UniqueKey 與 URL
| 圖中階段 | 對應程式與資料 |
|---|---|
| Shopping 送出 | CheckoutController.Create → CheckoutService.CheckoutCreateAsync → CheckoutCreateApiProcessor |
| Cart 讀車 | CheckOutService.Create 檢查快取期限;GetCartAndCalculateProcessor 用 CartUniqueKey 讀 CartEntity |
| Cart 轉接 | DoPayProcessFlowProcessor 轉成舊 WebStore 格式,呼叫 PayLite/RequestPayProcessUrlV3 |
| WebStore 發 key | PayLiteController.RequestPayProcessUrlV3 進入共用 RequestPayProcessUrl;Guid.NewGuid().ToString() 寫入 payProcessContext.UniqueKey、ContextId 與 URL 的 k |
| Cart 採用 | 從 URL 解析 k,經 HK/MY 特殊處理後填入 CheckoutEntity.CheckoutUniqueKey 並存 Redis;CheckOutService.Create 回傳 UniqueKey,Shopping 取 Response.Data.UniqueKey |
Cart Domain 接收並採用這把 key;現行流程真正產生它的是 WebStore。
PayProcessContext、排隊資訊與付款頁入口,才能用網址上的 k 繼續。PayLite 做完哪些事?
flowchart TD
A["Cart Domain 傳入 ShoppingCartClientEntity"] --> B["PayLite 檢查登入、次數、購物車與贈品條件"]
B -->|"檢查不通過"| X["回傳對應 API 結果"]
B -->|"可建立流程"| C["建立 PayProcessContext 並產生 GUID"]
C --> D["依設定取得排隊票券"]
D --> E["IUserDataHelper.Save 暫存流程"]
E --> F{"能立即結帳?"}
F -->|"可以"| G["回傳 /V2/Pay?k=..."]
F -->|"需要排隊"| H["回傳排隊頁 URL"]
| 檢查與產物 | 補充 |
|---|---|
| 登入、呼叫次數、空車、贈品庫存與運費、超重 | 可能回傳 API0001、API0006、API0007 等結果 |
PayProcessContext |
包含購物車、會員、拆單等資訊;流程 GUID 不是 CartUniqueKey |
| 排隊票券 | 依設定決定付款頁或排隊頁 |
IUserDataHelper.Save |
暫存 context 與結帳可用性資料 |
| 付款 URL | 依裝置與商店取得網域,讓 k 指向同一次流程 |
為什麼不能只在 Cart 產生?
現行 V3 Action 接收轉換後的購物車資料,沒有接收 Cart 指定的 checkout key;共用方法仍會自行執行 Guid.NewGuid().ToString()。若 Cart 先造 GUID,WebAPI 仍會用自己的 key 保存 PayProcessContext、取得排隊票券並組付款 URL。Cart 的 GUID 無法找到那份資料。
MWeb V2 PayController.Index(string k) 以 k 呼叫 PayProcessService.GetPayProcess;排隊頁 LandingV2(string k) 也以會員 ID 與 k 載入 PayProcessContext。依現行程式碼推論,只建立 Cart 的 CheckoutEntity 或 GUID,付款頁就缺少可讀的 WebStore context。
CheckoutUniqueKey,需修改 V3 契約,讓 WebAPI 接受並使用同一 key,並檢查其他呼叫端與驗證方式。若連 PayLite 呼叫都移除,則驗證、context 建立與存取、排隊及付款入口也要一併遷移或重設。這是改造方向,不是目前行為。PayProcess-20190918180000 是固定的快取類型名稱。真正把某位會員的一次付款流程找回來的,是會員 ID 加上當次的流程 key。Redis key 的三段結構
| 固定前綴與類型 | 會員 | 流程 |
|---|---|---|
TmpData:PayProcess-20190918180000 |
{memberId} |
{checkoutUniqueKey} |
1 | TmpData:PayProcess-20190918180000:{memberId}:{checkoutUniqueKey} |
PayLite 呼叫 IUserDataHelper.Save(PayProcessContextEntity.CacheTypeName, payProcessContext)。Redis 實作依 TmpData:{dataType}:{memberId}:{uniqueKey} 組 key。ShoppingCart.TmpData.RedisExpiredDays 控制保存天數,程式預設 7 天;本機 WebAPI Prod 設定 3 天。
實際寫到哪個 provider?
flowchart TD
A["IUserDataHelper.Save"] --> B{"EnableRedis?"}
B -->|"否"| C["檔案實作"]
B -->|"是"| D{"EnableRedisReroute?"}
D -->|"否"| E["Redis Data"]
D -->|"是"| F["按尾字元分流 Data 或 Data2"]
F --> G["Data2 讀取失敗則回查 Data"]
WebAPI Prod 的 PayProcess.UserData.EnableRedis 設定為 true。檔案實作的路徑是:
1 | {File.Path.Tmp}/PayProcess-20190918180000/PayProcess-20190918180000_{memberId}_{checkoutUniqueKey}.txt |
資料與責任對照
Cart Domain CheckoutEntity |
WebStore PayProcessContext |
|
|---|---|---|
| 工作 | Shopping 結帳頁操作、成單前檢核 | MWeb 付款頁、付款處理與成單後續 |
| 內容 | 繼承 CartEntity 的商品、優惠、金物流與金額,另有結帳欄位 |
含轉換後的 ShoppingCartV2,可承載付款方式、交易、訂單與流程狀態 |
| 更新者 | checkout/get、pay-set、配送等 Cart API |
WebStore 付款流程 Processor |
| 儲存 | Cart 專案 CartCache Redis Hash |
WebStore IUserDataHelper;本機 WebAPI Prod 設定使用 Redis |
| 查詢 key | Core:CheckoutEntity-20230207:{shopId}:{memberId}:{checkoutUniqueKey} |
TmpData:PayProcess-20190918180000:{memberId}:{流程key} |
建立、操作、付款、成單
sequenceDiagram participant C as Cart Domain participant W as WebStore participant M as MWeb C->>W: PayLite 建立付款流程 W->>W: 暫存 PayProcessContext W-->>C: 回傳流程 key 與 URL C->>C: 儲存 CheckoutEntity C->>C: 結帳頁操作更新 CheckoutEntity M->>W: 以 URL 的 k 載入付款流程 W-->>M: 提供 PayProcessContext C->>C: 成單前讀取並檢核 CheckoutEntity C->>W: CompleteForNewCartV2 傳入轉換後資料
更換付款方式時,Cart Domain 以 CheckoutUniqueKey 找 CheckoutEntity,更新 SelectedCheckoutPayTypeGroup;不能推定每次修改都同步寫入 WebStore 暫存的 context。MWeb 以 URL 的 k 載入自己的 PayProcessContext,不直接讀 Cart 的 CheckoutEntity。成立訂單時,Cart 再讀取、檢核 CheckoutEntity,轉成 WebStore 接受的 PayProcessContext 格式送往 CompleteForNewCartV2,所以傳入的資料不只是 PayLite 最初暫存的版本。



