90 lines
4.8 KiB
Go
90 lines
4.8 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"
|
||
|
||
"gorm.io/gorm"
|
||
)
|
||
|
||
type Wallet struct {
|
||
Brand string // 品牌/平台（區分多租戶、多品牌情境）
|
||
UID string // 使用者 UID
|
||
Asset string // 資產代號，可為 BTC、ETH、GEM_RED、GEM_BLUE、POINTS ,USD, TWD 等....
|
||
Balance decimal.Decimal // 餘額（使用高精度 decimal 避免浮點誤差）
|
||
Type wallet.Types // 錢包類型
|
||
}
|
||
|
||
// WalletRepository 是錢包的總入口，負責查詢、初始化與跨帳戶查詢邏輯
|
||
type WalletRepository interface {
|
||
// NewDB 建立新的 DB 實例（提供給需要操作 tx 的場景）
|
||
NewDB() *gorm.DB
|
||
// Session 取得單一使用者資產的錢包服務（非交易模式）
|
||
//📌 使用場景：
|
||
// 用在 不需要交易機制的場景，例如：
|
||
// 純查詢錢包餘額，查詢快取、Log、統計報表，非敏感資料更新，失敗可以重試的情境
|
||
// ✅ 優點：
|
||
// 簡單快速、使用預設的資料庫連線
|
||
// 不用包 Transaction ，沒有 Rollback 負擔
|
||
Session(uid, asset string) UserWalletService
|
||
// SessionWithTx 在資料庫交易內取得錢包服務
|
||
// 📌 使用場景：
|
||
// 用在 資料需要一致性與原子性保證的邏輯中，例如：
|
||
// 加值與扣款（同時操作多個錢包）檢查餘額後立刻寫入交易記錄，綁定訂單與錢包扣款的行為
|
||
// 所有與 Add/Commit 有關的處理，與其他模組（訂單、KYC）共用一個 transaction
|
||
// ✅ 優點：
|
||
// 保障操作過程中不被其他並發操作影響
|
||
// 可控制 rollback 行為避免中間失敗導致不一致
|
||
// 可組合複雜操作（如：更新錢包同時寫入交易紀錄）
|
||
SessionWithTx(db *gorm.DB, uid, asset string) UserWalletService
|
||
// Transaction 資料庫交易包裝器（確保交易一致性）
|
||
Transaction(fn func(db *gorm.DB) error) error
|
||
// InitWallets 初始化使用者的所有錢包類型（如可用、凍結等）
|
||
InitWallets(ctx context.Context, param []Wallet) error
|
||
// QueryBalances 查詢特定資產的錢包餘額
|
||
QueryBalances(ctx context.Context, req BalanceQuery) ([]entity.Wallet, error)
|
||
// QueryBalancesByUIDs 查詢多個使用者在特定資產下的錢包餘額
|
||
QueryBalancesByUIDs(ctx context.Context, uids []string, req BalanceQuery) ([]entity.Wallet, error)
|
||
//// GetDailyTxAmount 查詢使用者今日交易總金額（指定類型與業務）
|
||
//GetDailyTxAmount(ctx context.Context, uid string, txTypes []domain.TxType, business wallet.BusinessName) ([]entity.Wallet, error)
|
||
}
|
||
|
||
// BalanceQuery 是查詢餘額時的篩選條件
|
||
type BalanceQuery struct {
|
||
UID string // 使用者 ID
|
||
Asset string // 資產類型（Crypto、寶石等）
|
||
Kinds []wallet.Types // 錢包類型（如可用、凍結等）
|
||
}
|
||
|
||
// UserWalletService 定義了一個「單一使用者、單一資產」的錢包操作合約
|
||
type UserWalletService interface {
|
||
// InitializeWallets 為新使用者初始化所有錢包類型並寫入資料庫
|
||
InitializeWallets(ctx context.Context, brand string) ([]entity.Wallet, error)
|
||
// GetAllBalances 查詢此使用者此資產下所有錢包類型的當前餘額
|
||
GetAllBalances(ctx context.Context) ([]entity.Wallet, error)
|
||
// GetBalancesForTypes 查詢指定錢包類型的一組餘額（不加鎖）
|
||
GetBalancesForTypes(ctx context.Context, kinds []wallet.Types) ([]entity.Wallet, error)
|
||
// GetBalancesForUpdate 查詢並鎖定指定錢包類型（FOR UPDATE）
|
||
GetBalancesForUpdate(ctx context.Context, kinds []wallet.Types) ([]entity.Wallet, error)
|
||
// CurrentBalance 從本地緩存取得某種錢包類型的餘額
|
||
CurrentBalance(kind wallet.Types) decimal.Decimal
|
||
// IncreaseBalance 增加指定錢包類型的餘額，並累積一筆交易紀錄
|
||
IncreaseBalance(kind wallet.Types, orderID string, amount decimal.Decimal) error
|
||
// DecreaseBalance 減少指定錢包類型的餘額（等同於 IncreaseBalance 的負數版本）
|
||
DecreaseBalance(kind wallet.Types, orderID string, amount decimal.Decimal) error
|
||
// PrepareTransactions 為所有暫存交易紀錄填上 TXID/OrderID/Brand/BusinessType，並回傳可落庫的切片
|
||
PrepareTransactions(
|
||
txID int64,
|
||
orderID, brand string,
|
||
businessType wallet.BusinessName,
|
||
) []entity.WalletTransaction
|
||
// PersistBalances 將本地緩存中所有錢包最終餘額批次寫入資料庫
|
||
PersistBalances(ctx context.Context) error
|
||
// PersistOrderBalances 將本地緩存中所有訂單相關餘額批次寫入 transaction 表
|
||
PersistOrderBalances(ctx context.Context) error
|
||
// HasAvailableBalance 確認此使用者此資產是否已有可用餘額錢包
|
||
HasAvailableBalance(ctx context.Context) (bool, error)
|
||
}
|