商城與交易系統｜NEXUS-LEARN 技術架構

系統邊界

商城擁有商品、SKU、售賣規則、訂單及支付資料；LMS 擁有課程版本、排期容量與 enrollment。

01 / 分層架構圖

功能在技術層中的位置

01界面層 · Next.js

用戶端商品、下單、支付、訂單及席位

統一管理端商品、價格、訂單、退款及對帳

02接口層 · Node.js

商城 API目錄、商品、訂單、席位、退款

支付回調驗簽、限流、provider_txn_id 冪等

03業務功能層

商品與售賣課程投影、SKU、時效、價格快照

交易與履約訂單狀態、支付、席位、退款

04異步處理層

Node.js Worker商品同步、購買開通、退款通知、定時對帳

05資料層

commerce_db商品、SKU、價格、訂單、支付、席位、退款

物件儲存對帳檔及交易憑證

06外部與共用

內部接口LMS 課程／排期／enrollment

支付渠道FPS／PayMe 或服務商；契約待確認

圖中箭頭表示由界面經 API 及業務模組進入處理與資料層；外部交互須經受控適配器。

02 / 功能模組

具體功能與責任

商品與定價

商品建檔、課程／排期綁定、審核上下架、上架時效、早鳥和企業批量價。

訂單與支付

個人與企業下單、名額暫留、成交價快照、FPS／PayMe 回調驗簽及冪等。

席位與開通

個人付款後自動分配；企業購買後由管理員分配，學員啟用時才建立 LMS enrollment。

退款與對帳

退款審核、排期取消改期處理、權限撤銷請求、支付平台定時對帳。

03 / 系統交互

接口與資料同步

來源 → 目標	接口／方式	傳遞內容與規則
LMS → 商城	課程／排期事件	版本發佈、退役、變更、取消與容量
商城 → LMS	容量同步 API	下單前即時校驗並暫留名額
商城 → LMS	付款／席位啟用事件	建立 enrollment；失敗顯示開通異常
商城 → LMS	退款事件	停止未來學習訪問，保留歷史證據
支付渠道 → 商城	驗簽回調＋對帳檔	支付、退款和差異確認
商城 → 審計中心	Outbox 事件	改價、支付、席位分配及退款憑證

04 / 技術組成

落地約束

商品只能綁定 LMS 已發佈課程版本；排期班出售前需檢查報名截止與容量。
order_item 保存成交價、排期與學習權益快照；改價不追改已下單訂單。
付款成功與 LMS 開通採事件協作及補償，明確展示已付款、開通異常狀態。

Next.jsNode.jsTypeScriptPostgreSQLOutbox + Worker物件儲存

05 / 關鍵時序

下單、名額預留與學習開通

sequenceDiagram
    participant 買家
    participant 商城 as M4 商城
    participant LMS as M3 LMS
    participant 支付 as 支付渠道
    買家->>商城: 提交商品與排期
    商城->>LMS: ReserveSeat(schedule_id, order_id, idempotency_key, expires_at)
    LMS-->>商城: hold_id 或拒絕原因
    商城->>商城: 保存待支付訂單、成交價與權益快照
    買家->>支付: 付款
    支付-->>商城: 已驗簽回調(provider_txn_id)
    alt 付款有效且名額可確認
        商城->>LMS: ConfirmSeat(hold_id, order_id)
        商城->>商城: 確認訂單及 allocation_id
        alt 個人購買
            商城-->>LMS: SeatAssigned(allocation_id, learner_user_id)
        else 企業購買
            商城-->>買家: 席位待分配及學員啟用
            商城-->>LMS: 啟用後 SeatAssigned(allocation_id, learner_user_id)
        end
        LMS-->>商城: EnrollmentCreated 或 EnrollmentRejected
    else 付款超時、名額失效或排期取消
        商城->>LMS: ReleaseSeat(hold_id)
        商城->>商城: 取消未付款單或標記已付款開通異常
        商城-->>買家: 安排改期或退款
    end

實線為同步請求；虛線為回執或異步事件。外部接口以實際聯調契約為準。

接口／事件	資料權威與關鍵 ID	冪等、時限及失敗處理
ReserveSeat / ConfirmSeat / ReleaseSeat	LMS：schedule_id、容量、hold_id；M4：order_id、幂等鍵	預留到期依訂單支付超時配置；重複調用返回同一結果。到期釋放，已付款但名額失效轉異常單。
PaymentCompleted	M4：order_id、provider_txn_id、allocation_id	渠道交易號唯一；重複回調不再次確認名額。LMS 開通失敗保留已付款、開通異常狀態。
SeatAssigned → EnrollmentCreated/Rejected	M4：allocation_id；LMS：enrollment_id、source_allocation_id	企業席位未分配時可沒有 learner_user_id；學員啟用後才建 enrollment，重複事件不得重建。
RefundCompleted	M4：退款及席位；LMS：未來學習訪問	按席位撤銷未來訪問，保留歷史學習、證書及審計證據；定期對帳。