99 lines
5.9 KiB
Go
99 lines
5.9 KiB
Go
|
package repository
|
|||
|
|
|
|||
|
|
import (
|
|||
|
|
"code.30cm.net/digimon/app-cloudep-wallet-service/pkg/domain/entity"
|
|||
|
|
"code.30cm.net/digimon/app-cloudep-wallet-service/pkg/domain/wallet"
|
|||
|
|
"context"
|
|||
|
|
"github.com/shopspring/decimal"
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
// WalletReader 定義查詢錢包餘額的操作，純讀取，不涉及鎖或修改。
|
|||
|
|
type WalletReader interface {
|
|||
|
|
// AllBalances 查詢此用戶單一幣別所有錢包(可用/凍結/...)
|
|||
|
|
AllBalances(ctx context.Context) ([]entity.Wallet, error)
|
|||
|
|
// Balance 查詢單一餘額種類
|
|||
|
|
Balance(ctx context.Context, kind wallet.Types) (entity.Wallet, error)
|
|||
|
|
// Balances 查詢多個餘額種類
|
|||
|
|
Balances(ctx context.Context, kind []wallet.Types) ([]entity.Wallet, error)
|
|||
|
|
// LocalBalance 取得本地記憶體暫存餘額
|
|||
|
|
LocalBalance(kind wallet.Types) decimal.Decimal
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// WalletLocker 提供所有需要「加鎖（XLock）」的錢包操作，用於避免併發交易衝突。
|
|||
|
|
// 通常搭配交易流程使用，保證同時只有一個執行緒可以修改該錢包類型或訂單相關餘額。
|
|||
|
|
type WalletLocker interface {
|
|||
|
|
// BalanceXLock 查詢指定錢包類型的餘額，並加上排他鎖（FOR UPDATE）
|
|||
|
|
BalanceXLock(ctx context.Context, kind wallet.Types) (entity.Wallet, error)
|
|||
|
|
// BalancesXLock 查詢多個錢包類型的餘額，並加上排他鎖（FOR UPDATE）
|
|||
|
|
BalancesXLock(ctx context.Context, kind []wallet.Types) ([]entity.Wallet, error)
|
|||
|
|
// XLock 針對指定錢包紀錄 ID 加鎖（FOR UPDATE）
|
|||
|
|
XLock(ctx context.Context, id int64) (entity.Wallet, error)
|
|||
|
|
// XLocks 針對多筆錢包紀錄 ID 加鎖（FOR UPDATE）
|
|||
|
|
XLocks(ctx context.Context, ids []int64) ([]entity.Wallet, error)
|
|||
|
|
// GetAvailableBalanceXLock 查詢指定業務邏輯下的可用餘額並加鎖
|
|||
|
|
GetAvailableBalanceXLock(ctx context.Context, b wallet.BusinessName) (entity.Wallet, error)
|
|||
|
|
// GetFreezeBalanceXLock 查詢指定業務邏輯下的凍結餘額並加鎖
|
|||
|
|
GetFreezeBalanceXLock(ctx context.Context, b wallet.BusinessName) (entity.Wallet, error)
|
|||
|
|
// GetUnconfirmedBalanceXLock 查詢尚未確認（unconfirmed）的餘額並加鎖
|
|||
|
|
GetUnconfirmedBalanceXLock(ctx context.Context) (entity.Wallet, error)
|
|||
|
|
// GetOrderBalanceXLock 查詢某筆訂單的餘額資料並加鎖
|
|||
|
|
GetOrderBalanceXLock(ctx context.Context, id int64) (entity.Transaction, error)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// WalletOperator 負責錢包的餘額加減操作與訂單金額變動邏輯。
|
|||
|
|
// 此介面不包含「資料鎖定（Lock）」與「資料持久化（Execute）」等責任，單純聚焦於記錄錢包與訂單餘額的變動邏輯。
|
|||
|
|
type WalletOperator interface {
|
|||
|
|
// AddBalance 增加指定錢包類型的餘額（使用前必須已查詢該餘額並存在本地記憶體）
|
|||
|
|
AddBalance(kind wallet.Types, amount decimal.Decimal) error
|
|||
|
|
// AddBalanceSetOrderID 增加指定錢包類型的餘額並記錄訂單 ID（用於與訂單綁定的交易）
|
|||
|
|
AddBalanceSetOrderID(orderID string, kind wallet.Types, amount decimal.Decimal) error
|
|||
|
|
// AddAvailable 增加可用餘額（根據業務類型自動判斷使用哪種錢包）
|
|||
|
|
AddAvailable(b wallet.BusinessName, amount decimal.Decimal) error
|
|||
|
|
// AddFreeze 增加凍結餘額（根據業務類型自動判斷使用哪種錢包）
|
|||
|
|
AddFreeze(b wallet.BusinessName, amount decimal.Decimal) error
|
|||
|
|
// AddUnconfirmed 增加尚未確認（unconfirmed）的餘額
|
|||
|
|
AddUnconfirmed(amount decimal.Decimal) error
|
|||
|
|
// AddOrder 增加與訂單相關的餘額（僅適用於交易表中訂單類型紀錄）
|
|||
|
|
AddOrder(id int64, amount decimal.Decimal) error
|
|||
|
|
// SubAvailable 減少可用餘額（根據業務類型自動判斷使用哪種錢包）
|
|||
|
|
SubAvailable(b wallet.BusinessName, amount decimal.Decimal) error
|
|||
|
|
// SubFreeze 減少凍結餘額（根據業務類型自動判斷使用哪種錢包）
|
|||
|
|
SubFreeze(b wallet.BusinessName, amount decimal.Decimal) error
|
|||
|
|
// SubUnconfirmed 減少尚未確認（unconfirmed）的餘額
|
|||
|
|
SubUnconfirmed(amount decimal.Decimal) error
|
|||
|
|
// GetAvailableBalance 查詢某業務類型對應的可用餘額
|
|||
|
|
GetAvailableBalance(ctx context.Context, b wallet.BusinessName) (entity.Wallet, error)
|
|||
|
|
// GetFreezeBalance 查詢某業務類型對應的凍結餘額
|
|||
|
|
GetFreezeBalance(ctx context.Context, b wallet.BusinessName) (entity.Wallet, error)
|
|||
|
|
// GetUnconfirmedBalance 查詢尚未確認的餘額
|
|||
|
|
GetUnconfirmedBalance(ctx context.Context) (entity.Wallet, error)
|
|||
|
|
// GetOrderBalance 查詢與指定訂單 ID 相關的餘額紀錄（訂單錢包交易）
|
|||
|
|
GetOrderBalance(ctx context.Context, orderID string) (entity.Transaction, error)
|
|||
|
|
// CheckWallet 確認錢包是否存在（通常用於初始化前檢查）
|
|||
|
|
CheckWallet(ctx context.Context) (bool, error)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// WalletTransactional 負責執行錢包與訂單餘額的最終更新（實際寫入資料庫），
|
|||
|
|
// 並提供錢包交易紀錄的取得方法，主要用途為提交交易與後續紀錄保存。
|
|||
|
|
type WalletTransactional interface {
|
|||
|
|
// Execute 實際寫入錢包餘額的變動（例如：可用、凍結、未確認餘額等）
|
|||
|
|
// 此方法應在交易邏輯處理完畢後被呼叫，用於同步 local 記憶體中的餘額至資料庫。
|
|||
|
|
Execute(ctx context.Context) error
|
|||
|
|
// ExecuteOrder 實際寫入訂單餘額的變動（通常指向 Transaction 表中的餘額欄位）
|
|||
|
|
// 適用於與特定訂單相關的錢包操作（如訂單鎖定、釋放等）。
|
|||
|
|
ExecuteOrder(ctx context.Context) error
|
|||
|
|
// Transactions 建立錢包交易紀錄列表，用於最終寫入錢包交易表 wallet_transaction。
|
|||
|
|
// 會補齊必要的交易相關欄位（如 txID、orderID、brand、businessType）。
|
|||
|
|
Transactions(txID int64, orderID, brand string, businessType wallet.BusinessName) []entity.WalletTransaction
|
|||
|
|
// GetTransactions 回傳目前記憶體中所累積的錢包交易紀錄，用於外部查詢或後續處理。
|
|||
|
|
GetTransactions() []entity.WalletTransaction
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// UserWalletService 統整所有錢包相關功能，對外仍可以使用這個 interface。
|
|||
|
|
type UserWalletService interface {
|
|||
|
|
WalletReader
|
|||
|
|
WalletLocker
|
|||
|
|
WalletOperator
|
|||
|
|
WalletTransactional
|
|||
|
|
}
|