hyapp-server/services/wallet-service/internal/domain/ledger/wallet_query.go

package ledger

import (
	"strings"
)

// RechargeBill 是充值账单的只读投影；充值事实由 wallet_recharge_records 保存。
type RechargeBill struct {
	AppCode                string
	TransactionID          string
	CommandID              string
	RechargeType           string
	Status                 string
	ExternalRef            string
	UserID                 int64
	SellerUserID           int64
	SellerRegionID         int64
	TargetRegionID         int64
	PolicyID               int64
	PolicyVersion          string
	CurrencyCode           string
	CoinAmount             int64
	USDMinorAmount         int64
	ExchangeCoinAmount     int64
	ExchangeUSDMinorAmount int64
	CreatedAtMS            int64
}

// ListRechargeBillsQuery 是后台查询所有充值渠道账单的筛选条件。
type ListRechargeBillsQuery struct {
	AppCode      string
	UserID       int64
	SellerUserID int64
	RegionID     int64
	RechargeType string
	Status       string
	Keyword      string
	StartAtMS    int64
	EndAtMS      int64
	Page         int32
	PageSize     int32
}

// WalletFeatureFlags 是 App 钱包入口的开关投影；首版由 wallet-service 固定返回，后续可迁移到配置表。
type WalletFeatureFlags struct {
	RechargeEnabled        bool
	DiamondExchangeEnabled bool
}

// WalletOverview 是我的页和钱包首页共同使用的轻量摘要。
type WalletOverview struct {
	Balances     []AssetBalance
	FeatureFlags WalletFeatureFlags
}

// WalletValueSummary 是我的页钱包卡片的最小余额投影。
type WalletValueSummary struct {
	CoinAmount  int64
	UpdatedAtMS int64
}

// GiftWallResource 是礼物墙展示所需的资源快照字段，避免读取接口再依赖资源配置实时状态。
type GiftWallResource struct {
	AppCode           string
	ResourceID        int64
	ResourceCode      string
	ResourceType      string
	Name              string
	Status            string
	Grantable         bool
	GrantStrategy     string
	WalletAssetType   string
	WalletAssetAmount int64
	UsageScopes       []string
	AssetURL          string
	PreviewURL        string
	AnimationURL      string
	MetadataJSON      string
	SortOrder         int32
	CreatedAtMS       int64
	UpdatedAtMS       int64
}

// GiftWallItem 是当前用户收到礼物的按 gift_id 聚合投影。
type GiftWallItem struct {
	GiftID               string
	GiftName             string
	ResourceID           int64
	Resource             GiftWallResource
	ResourceSnapshotJSON string
	GiftTypeCode         string
	PresentationJSON     string
	GiftCount            int64
	TotalValue           int64
	TotalCoinValue       int64
	TotalDiamondValue    int64
	// TotalGiftPoint 是历史礼物墙字段，新送礼不再累加，保留用于旧数据展示兼容。
	TotalGiftPoint    int64
	TotalHeatValue    int64
	ChargeAssetType   string
	LastPriceVersion  string
	FirstReceivedAtMS int64
	LastReceivedAtMS  int64
	SortOrder         int32
}

// UserGiftWall 汇总礼物墙首屏需要的全量统计和按礼物类型聚合列表。
type UserGiftWall struct {
	Items             []GiftWallItem
	GiftKindCount     int64
	GiftTotalCount    int64
	TotalValue        int64
	TotalCoinValue    int64
	TotalDiamondValue int64
	// TotalGiftPoint 是历史礼物墙汇总字段，新送礼不再累加，保留用于旧数据展示兼容。
	TotalGiftPoint int64
	TotalHeatValue int64
}

// DiamondExchangeRule 是钻石兑换金币或余额的固定规则投影。
type DiamondExchangeRule struct {
	ExchangeType  string
	FromAssetType string
	ToAssetType   string
	FromAmount    int64
	ToAmount      int64
	Enabled       bool
}

// WalletTransaction 是钱包流水页按用户分录查询的投影。
type WalletTransaction struct {
	EntryID            int64
	TransactionID      string
	BizType            string
	AssetType          string
	AvailableDelta     int64
	FrozenDelta        int64
	AvailableAfter     int64
	FrozenAfter        int64
	CounterpartyUserID int64
	RoomID             string
	CreatedAtMS        int64
}

// ListWalletTransactionsQuery 描述 App 钱包流水分页条件。
type ListWalletTransactionsQuery struct {
	AppCode   string
	UserID    int64
	AssetType string
	Page      int32
	PageSize  int32
}

// AssetBalance 是账户当前可用/冻结余额投影。
type AssetBalance struct {
	AppCode         string
	UserID          int64
	AssetType       string
	AvailableAmount int64
	FrozenAmount    int64
	Version         int64
	UpdatedAtMs     int64
}

// AdminCreditAssetCommand 是后台手动调账的最小审计命令，Amount 为正数入账、负数扣账。
type AdminCreditAssetCommand struct {
	AppCode        string
	CommandID      string
	TargetUserID   int64
	AssetType      string
	Amount         int64
	OperatorUserID int64
	Reason         string
	EvidenceRef    string
}

// ValidAssetType 限定账本允许落账的资产类型，避免写入任意字符串资产。
func ValidAssetType(assetType string) bool {
	switch assetType {
	case AssetCoin, AssetCoinSellerCoin, AssetRobotCoin, AssetGiftPoint, AssetHostSalaryUSD, AssetAgencySalaryUSD, AssetBDSalaryUSD, AssetAdminSalaryUSD:
		return true
	default:
		return false
	}
}

// ValidSalaryAssetType 只允许身份工资美元钱包进入工资兑换和转币商链路，避免普通金币或币商库存被误扣。
func ValidSalaryAssetType(assetType string) bool {
	switch strings.ToUpper(strings.TrimSpace(assetType)) {
	case AssetHostSalaryUSD, AssetAgencySalaryUSD, AssetBDSalaryUSD, AssetAdminSalaryUSD:
		return true
	default:
		return false
	}
}