hyapp-server/services/activity-service/internal/domain/inviteactivity/invite_activity.go

package inviteactivity

const (
	TierStatusActive   = "active"
	TierStatusInactive = "inactive"

	RewardTypeRecharge      = "recharge"
	RewardTypeValidInvite   = "valid_invite"
	RewardTypeInviteInviter = "invite_inviter"
	RewardTypeInvitee       = "invite_invitee"

	ClaimStatusPending = "pending"
	ClaimStatusGranted = "granted"
	ClaimStatusFailed  = "failed"

	ReasonEligible        = "eligible"
	ReasonAlreadyConsumed = "already_consumed"
	ReasonNoRelation      = "no_invite_relation"
	ReasonDuplicate       = "duplicate"

	EventTypeWalletRechargeRecorded = "WalletRechargeRecorded"
	EventTypeUserInvited            = "UserInvited"
	EventTypeUserInviteBecameValid  = "UserInviteBecameValid"
)

// Tier 是邀请活动的金币奖励档位；不同 reward_type 使用不同门槛字段。
type Tier struct {
	TierID                    int64
	AppCode                   string
	RewardType                string
	TierCode                  string
	TierName                  string
	ThresholdCoinAmount       int64
	ThresholdValidInviteCount int64
	RewardCoinAmount          int64
	Status                    string
	SortOrder                 int32
	CreatedAtMS               int64
	UpdatedAtMS               int64
}

// Config 是当前 App 的邀请活动配置。
type Config struct {
	AppCode                          string
	Enabled                          bool
	PerInviteInviterRewardCoinAmount int64
	PerInviteInviteeRewardCoinAmount int64
	Tiers                            []Tier
	UpdatedByAdminID                 int64
	CreatedAtMS                      int64
	UpdatedAtMS                      int64
}

// Progress 是邀请人在一个 UTC 自然月内的邀请活动累计。
type Progress struct {
	AppCode                 string
	CycleKey                string
	UserID                  int64
	TotalRechargeCoinAmount int64
	ValidInviteCount        int64
	ClaimedRewardCoinAmount int64
	UpdatedAtMS             int64
}

// Claim 是用户点击领取后创建的钱包发奖事实。
type Claim struct {
	ClaimID                   string
	AppCode                   string
	CycleKey                  string
	UserID                    int64
	RewardType                string
	CommandID                 string
	TierID                    int64
	TierCode                  string
	TierName                  string
	ThresholdCoinAmount       int64
	ThresholdValidInviteCount int64
	ReachedValue              int64
	RewardCoinAmount          int64
	Status                    string
	WalletCommandID           string
	WalletTransactionID       string
	FailureReason             string
	GrantedAtMS               int64
	CreatedAtMS               int64
	UpdatedAtMS               int64
}

// RechargeEvent 是 wallet_outbox 进入邀请活动的成功充值事实。
type RechargeEvent struct {
	AppCode            string
	EventID            string
	EventType          string
	TransactionID      string
	CommandID          string
	InvitedUserID      int64
	InviterUserID      int64
	RechargeCoinAmount int64
	RechargeType       string
	PayloadJSON        string
	OccurredAtMS       int64
}

// ValidInviteEvent 是 user_outbox 里“被邀请用户首次成为有效邀请”的事实。
type ValidInviteEvent struct {
	AppCode       string
	EventID       string
	EventType     string
	InvitedUserID int64
	InviterUserID int64
	PayloadJSON   string
	OccurredAtMS  int64
}

// InviteEvent 是 user_outbox 里“邀请关系首次绑定”的事实；它不依赖被邀请人后续是否充值达标。
type InviteEvent struct {
	AppCode       string
	EventID       string
	EventType     string
	InvitedUserID int64
	InviterUserID int64
	InviteCode    string
	Source        string
	PayloadJSON   string
	OccurredAtMS  int64
}

// Cycle 表达 UTC 自然月周期边界。
type Cycle struct {
	Key     string
	StartMS int64
	EndMS   int64
}

// StatusResult 是 App H5 页面读取的完整邀请活动状态。
type StatusResult struct {
	Config       Config
	Progress     Progress
	Claims       []Claim
	Cycle        Cycle
	ServerTimeMS int64
}

// ConsumeResult 表达一次事件是否被写入进度。
type ConsumeResult struct {
	Consumed bool
	Reason   string
}

// ClaimQuery 是后台领取记录查询条件。
type ClaimQuery struct {
	Status     string
	RewardType string
	UserID     int64
	CycleKey   string
	Page       int32
	PageSize   int32
}

// LeaderboardEntry 是邀请活动月榜的一行，只统计已经达到有效邀请标准的邀请人数。
type LeaderboardEntry struct {
	RankNo                  int32
	UserID                  int64
	ValidInviteCount        int64
	TotalRechargeCoinAmount int64
}

// LeaderboardQuery 是邀请活动月榜分页条件；CycleKey 为空时由 service 使用当前 UTC 月。
type LeaderboardQuery struct {
	CycleKey string
	Page     int32
	PageSize int32
}

// LeaderboardResult 是邀请活动月榜查询结果。
type LeaderboardResult struct {
	Entries      []LeaderboardEntry
	Total        int64
	CycleKey     string
	ServerTimeMS int64
}