消費者打開購物車,系統整理此刻要買的商品,交出第一把鑰匙。按下結帳後,另一把鑰匙帶著這次交易走向付款頁。兩把鑰匙都叫 unique key,卻分別守著購物車與結帳流程。先看它們各自指向什麼,再循著程式的交接路線往下走。

CART 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 寫入;空車與全售完的情況見「第一把鑰匙的程式路徑」。
CHECKOUT KEY
第二把鑰匙,連起同一次結帳
按下結帳後,Cart Domain 需要一份可操作的結帳資料,MWeb 則需要能載入的付款流程。兩邊共用流程 key,資料各自保存。

一個流程 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
OVERVIEW
先有購物車,再有結帳流程
第一把鑰匙讓購物車可以反覆讀取與重算;第二把鑰匙標記一次已開始的結帳。下面把 API 的交接與資料有效時間分開看。

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 天
本文的「進購物車」特指 create API,不涵蓋商品加入購物車之前所有前端操作;呼叫方如何保存兩種 key,也不在這次後端追查範圍。表中的設定來自程式碼與設定檔,未以實際 Redis 內容驗證。
CART TRACE
Cart Domain 決定沿用,還是造一把新鑰匙
這條鏈路有兩個要分開看的動作:先把 key 放進 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"]

程式呼叫的先後

  1. Shopping CartsController.Create 交給 CartService.CartCreateAsync 建立 CartContext。
  2. Shopping CartCreateProcessor 透過 DomainApiHelper 呼叫 Cart Domain api/carts/create,並把回傳 Data 放進 context.Data。
  3. Cart Domain CartsController.Create 呼叫 CartService.CartCreateAsync;GetCart 流程先跑 CartCreateProcessor,後段有 CacheCartDataProcessor。
  4. Cart Domain 以 context.CartUniqueKey ?? Guid.NewGuid().ToString() 決定 key,放入 context.Data.CartUniqueKey,再由 Shopping 回傳 CartEntity。

一般 Cart create 的 CartContext 未預填 key,所以會新建;代客下單或保留既有 context key 的情境可能沿用。正常商品分支會走到 CacheCartDataProcessor;空車或全售完可能提前中斷。Cart Service 因金流或物流重新計算時,也會傳入既有 CartUniqueKey。

CHECKOUT TRACE
WebStore 發出流程 key,Cart Domain 接住它
從 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。

PAYLITE
WebAPI 交付的是一段付款流程
Cart Domain 自己產生 GUID 並不困難。現行 MWeb 還需要 PayLite 建好的 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。

若改由 Cart Domain 產生 CheckoutUniqueKey,需修改 V3 契約,讓 WebAPI 接受並使用同一 key,並檢查其他呼叫端與驗證方式。若連 PayLite 呼叫都移除,則驗證、context 建立與存取、排隊及付款入口也要一併遷移或重設。這是改造方向,不是目前行為。
STORAGE
付款流程放在哪裡?
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
這些保存時間與路由來自程式碼及設定檔,尚未核對實際部署環境的 Redis 內容。
TWO CONTEXTS
同一把流程鑰匙,開的是兩份資料
Cart Domain 維護結帳頁當下的選擇;WebStore 維護 MWeb 能接續的付款流程。共用 key 讓兩邊指向同一次結帳,不代表資料同步成同一份。

資料與責任對照

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 最初暫存的版本。