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
|
||
}
|