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) Transactions( txID int64, orderID string, brand string, businessType wallet.BusinessName, ) []entity.WalletTransaction // Commit 提交所有操作(更新錢包與新增交易紀錄) Commit(ctx context.Context) error // CommitOrder 提交所有訂單 CommitOrder(ctx context.Context) error }