92 lines
4.8 KiB
Go
92 lines
4.8 KiB
Go
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 // 資產代號
|
||
}
|