app-cloudep-wallet-service/pkg/domain/repository/wallet.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 {
	// Init 初始化錢包（如建立可用、凍結、未確認等錢包）
	Init(ctx context.Context, uid, asset, brand string) ([]entity.Wallet, error)
	// All 查詢所有錢包餘額
	All(ctx context.Context) ([]entity.Wallet, error)
	// Get 查詢單一或多種類型的餘額
	Get(ctx context.Context, kinds []wallet.Types) ([]entity.Wallet, error)
	// GetWithLock 查詢鎖定後的錢包（交易使用）
	GetWithLock(ctx context.Context, kinds []wallet.Types) ([]entity.Wallet, error)
	// LocalBalance 查詢記憶中的快取值（非查資料庫）
	LocalBalance(kind wallet.Types) decimal.Decimal
	// LockByIDs 根據錢包 ID 鎖定（資料一致性用）
	LockByIDs(ctx context.Context, ids []int64) ([]entity.Wallet, error)
	// CheckReady 檢查錢包是否已經存在並準備好
	CheckReady(ctx context.Context) (bool, error)
	// Add 加值與扣款邏輯（含業務類別）
	Add(kind wallet.Types, orderID string, amount decimal.Decimal) error
	Sub(kind wallet.Types, orderID string, amount decimal.Decimal) error
	// AddTransaction 新增一筆交易紀錄（建立資料）
	AddTransaction(txID int64, orderID string, brand string, business wallet.BusinessName, kind wallet.Types, amount decimal.Decimal)
	//// PendingTransactions 查詢尚未執行的交易清單（會在 Execute 中一次提交）
	//PendingTransactions() []entity.WalletTransaction

	// Commit 提交所有操作（更新錢包與新增交易紀錄）
	Commit(ctx context.Context) error
}