package usecase import ( "code.30cm.net/digimon/app-cloudep-wallet-service/pkg/domain/wallet" "context" "github.com/shopspring/decimal" ) // WalletTransferUseCase 處理錢包資產轉移的核心業務邏輯(支援多種錢包操作) type WalletTransferUseCase interface { // Process 處理一次完整的錢包轉帳(含內部轉帳、跨使用者轉帳) Process(ctx context.Context, req WalletTransferRequest) error // Withdraw 出金操作(從錢包扣款) Withdraw(ctx context.Context, tx WalletTransferRequest) error // Deposit 入金操作(錢包加值) Deposit(ctx context.Context, tx WalletTransferRequest) error // DepositUnconfirmed 入金至未確認餘額(如轉帳待確認、預約加值) DepositUnconfirmed(ctx context.Context, tx WalletTransferRequest) error // Freeze 將資產從可用餘額移動至凍結餘額(常用於下單等鎖倉需求) Freeze(ctx context.Context, tx WalletTransferRequest) error // AppendFreeze 追加凍結金額(已有凍結金額的情況下再次追加) AppendFreeze(ctx context.Context, tx WalletTransferRequest) error // UnFreeze 將凍結金額移回可用餘額(如訂單取消) UnFreeze(ctx context.Context, tx WalletTransferRequest) error // RollbackFreeze 將凍結金額退回,並作為取消交易的一部分 RollbackFreeze(ctx context.Context, tx WalletTransferRequest) error // RollbackFreezeAddAvailable 退回凍結金額並補回可用金額(全額退款流程) RollbackFreezeAddAvailable(ctx context.Context, tx WalletTransferRequest) error // CancelFreeze 取消凍結操作(不轉移回可用餘額,只做作廢處理) CancelFreeze(ctx context.Context, tx WalletTransferRequest) error // Unconfirmed 將未確認金額移回可用餘額(例如:加值完成確認) Unconfirmed(ctx context.Context, tx WalletTransferRequest) error // Balance 查詢目前錢包餘額(含可用與不可用) Balance(ctx context.Context, req BalanceReq) ([]Balance, error) // HistoryBalance 查詢歷史錢包快照(指定時間前的餘額狀態) HistoryBalance(ctx context.Context, req BalanceReq) ([]Balance, error) // BalanceByAssets 查詢使用者特定資產的各錢包類型餘額 BalanceByAssets(ctx context.Context, uid, cryptoCode string, walletTypes []wallet.Types) (BalanceAssetsResp, error) // CheckBalance 驗證可用餘額是否足夠(通常用於風控前置驗證) CheckBalance(ctx context.Context, tx WalletTransferRequest) error // GetTodayWithdraw 查詢使用者今日累積出金額 GetTodayWithdraw(ctx context.Context, uid, toCrypto string) (TodayWithdrawResp, error) } // WalletTransferRequest 表示一次錢包轉帳的請求資料 type WalletTransferRequest struct { ReferenceOrderID string // 對應的訂單編號,可為空(非訂單觸發) FromUID string // 付款方 UID ToUID string // 收款方 UID,若為錢包內部轉帳可與 FromUID 相同 Asset string // 資產代號(例如 BTC、ETH、TWD 等) Amount decimal.Decimal // 轉移金額(正數,系統控制正負方向) PostTransferBalance decimal.Decimal // 轉帳後餘額(可選填,便於日誌追蹤與審計) TxType wallet.TxType // 交易類型(如入金、出金、轉帳等) Business wallet.BusinessName // 業務場景類型(如合約、模擬、一般用途等) Brand string // 所屬品牌(支援多品牌架構) FromWalletType wallet.Types // 扣款來源錢包類型 ToWalletType wallet.Types // 收款目標錢包類型 } // BalanceReq 表示查詢錢包餘額的請求參數 type BalanceReq struct { UID string // 使用者 UID Asset string // 指定資產(如 BTC) BeforeHour int // 幾小時前的快照(若查歷史快照) } // Balance 表示錢包的當前或歷史餘額狀態 type Balance struct { Asset string // 資產代號 Available decimal.Decimal // 可用餘額 Unavailable UnavailableBalance // 不可用餘額(凍結、未確認) UpdateTime int64 // 更新時間(Unix 時間戳) } // UnavailableBalance 表示錢包中不可用的部分 type UnavailableBalance struct { Freeze decimal.Decimal // 凍結金額(如掛單中) Unconfirmed decimal.Decimal // 未確認金額(如等待轉帳) } // BalanceAssetsResp 表示使用者所有錢包類型在某資產的總和 type BalanceAssetsResp struct { Balances map[string]decimal.Decimal // 各錢包類型對應的餘額 Asset string // 查詢的資產代號 } // TodayWithdrawResp 表示使用者今天的累積出金結果 type TodayWithdrawResp struct { Withdraw decimal.Decimal // 今日總出金金額 Asset string // 資產代號 }