feat: 迁移渠道画像累计指标和玩家付费分层

internal/biz/biz.go

@@ -11,4 +11,4 @@ import (
 )
 
 // ProviderSet is biz providers.
-var ProviderSet = wire.NewSet(system.ProviderSet, payment.ProviderSet, integration.ProviderSet, task.ProviderSet, business.NewUserPreferenceUsecase, business.NewAccountUsecase, business.NewBindingUsecase, business.NewPasswordResetUsecase, business.NewBusinessPromoteUsecase, business.NewAlertRuleUsecase, business.NewAlertRecordUsecase, business.NewActivationUsecase, business.NewChannelUsecase, business.NewBusinessPortraitUsecase)
+var ProviderSet = wire.NewSet(system.ProviderSet, payment.ProviderSet, integration.ProviderSet, task.ProviderSet, business.NewUserPreferenceUsecase, business.NewAccountUsecase, business.NewBindingUsecase, business.NewPasswordResetUsecase, business.NewBusinessPromoteUsecase, business.NewAlertRuleUsecase, business.NewAlertRecordUsecase, business.NewActivationUsecase, business.NewChannelUsecase, business.NewBusinessPortraitUsecase, business.NewChannelPortraitUsecase)

internal/biz/business/business_portrait.go

@@ -101,6 +101,8 @@ type PortraitStatistics struct {
 	Available                 bool
 }
 type PortraitReportScope struct {
+	Root                    *Channel
+	NoCompare               bool
 	Pairs                   []PlatformKey
 	Sources                 []string
 	IncludeSub, IDCardDedup bool

internal/biz/business/channel.go

@@ -40,6 +40,7 @@ type Channel struct {
 	BindingAccount, BindingUserName         string
 	GameCount, PlayerCount                  *int64
 	TotalPayAmount                          *string
+	CreatedUnix, LastLoginUnix              *int64
 }
 
 func (c *Channel) BusinessDisplayName() string {
@@ -100,6 +101,7 @@ type ChannelGame struct {
 type ChannelGameScope struct {
 	Root                    *Channel
 	IncludeSub, IDCardDedup bool
+	BeginDate               string
 	EndDate                 string
 }
 type ChannelRepo interface {
@@ -327,6 +329,10 @@ func (uc *ChannelUsecase) Games(ctx context.Context, key ChannelKey) ([]*Channel
 	if err != nil {
 		return nil, err
 	}
+	return normalizeChannelGames(games)
+}
+
+func normalizeChannelGames(games []*ChannelGame) ([]*ChannelGame, error) {
 	amounts := map[uint64]*big.Rat{}
 	for _, game := range games {
 		game.RegisterCount = min(game.RegisterCount, int64(2147483647))

internal/biz/business/channel_portrait.go

@@ -0,0 +1,312 @@
+package business
+
+import (
+	"context"
+	"math/big"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/go-kratos/kratos/v3/errors"
+)
+
+type ChannelPortraitBasic struct {
+	Channel   *Channel
+	Parent    *Channel
+	GameCount *int64
+}
+type ChannelPortraitMetrics struct{ Register, PayAmount, PayRate, Active *PortraitMetric }
+type ChannelPayTier struct {
+	Tier, Label string
+	Count       int64
+	Ratio       string
+}
+type ChannelPortrait struct {
+	Basic                   *ChannelPortraitBasic
+	Period                  string
+	Metrics                 *ChannelPortraitMetrics
+	RegisterTrend, PayTrend []*PortraitTrend
+	GameDistribution        []*ChannelGame
+	PayTiers                []*ChannelPayTier
+	Available               bool
+	UnavailableReason       string
+}
+type ChannelIdentityPay struct {
+	UserID *uint64
+	IDCard *string
+	Amount string
+}
+type ChannelTierData struct {
+	RegisterKeys  []string
+	FallbackCount int64
+	Payments      []*ChannelIdentityPay
+	Available     bool
+}
+type ChannelPortraitRepo interface {
+	GameCount(context.Context, ChannelKey) (*int64, error)
+	EarliestDate(context.Context, ChannelGameScope) (string, bool, error)
+	TierData(context.Context, ChannelGameScope) (*ChannelTierData, error)
+}
+type ChannelPortraitUsecase struct {
+	repo        ChannelPortraitRepo
+	channels    ChannelRepo
+	reports     BusinessPortraitRepo
+	accounts    *AccountUsecase
+	preferences *UserPreferenceUsecase
+	now         func() time.Time
+}
+
+func NewChannelPortraitUsecase(repo ChannelPortraitRepo, channels ChannelRepo, reports BusinessPortraitRepo, accounts *AccountUsecase, preferences *UserPreferenceUsecase) *ChannelPortraitUsecase {
+	return &ChannelPortraitUsecase{repo: repo, channels: channels, reports: reports, accounts: accounts, preferences: preferences, now: time.Now}
+}
+func normalizeChannelPortraitPeriod(period string) string {
+	switch value := strings.ToLower(strings.TrimSpace(period)); value {
+	case "today", "yesterday", "last7", "last30", "total":
+		return value
+	}
+	return "today"
+}
+func ChannelLevelLabel(level *int) string {
+	if level == nil {
+		return ""
+	}
+	return map[int]string{1: "一级渠道", 2: "二级渠道", 3: "三级渠道"}[*level]
+}
+func ChannelStatusLabel(status *int) string {
+	if status == nil {
+		return ""
+	}
+	return map[int]string{0: "待审核", 1: "正常", -2: "驳回", -3: "商务新增"}[*status]
+}
+func ChannelTypeLabel(registerType *int) string {
+	if registerType == nil {
+		return ""
+	}
+	if *registerType == 1 {
+		return "公会"
+	}
+	return "个人"
+}
+func ChannelUnixTime(value *int64) *time.Time {
+	if value == nil || *value <= 0 {
+		return nil
+	}
+	t := time.Unix(*value, 0).In(portraitLocation)
+	return &t
+}
+func unavailableChannelPortrait(p *ChannelPortrait, reason string) *ChannelPortrait {
+	p.Available = false
+	p.UnavailableReason = reason
+	p.Metrics = nil
+	p.RegisterTrend = []*PortraitTrend{}
+	p.PayTrend = []*PortraitTrend{}
+	p.GameDistribution = []*ChannelGame{}
+	p.PayTiers = []*ChannelPayTier{}
+	return p
+}
+func (uc *ChannelPortraitUsecase) Portrait(ctx context.Context, key ChannelKey, period string) (*ChannelPortrait, error) {
+	source, err := NormalizePlatform(key.SourceDB)
+	if err != nil {
+		return nil, err
+	}
+	key.SourceDB = source
+	actor, account, err := uc.accounts.actor(ctx)
+	if err != nil {
+		return nil, err
+	}
+	viewer := portraitUserScope(account)
+	viewer.All = actor.AuthorityID == 888
+	root, err := uc.channels.Find(ctx, viewer, key)
+	if err != nil {
+		return nil, err
+	}
+	period = normalizeChannelPortraitPeriod(period)
+	profile := &ChannelPortrait{Basic: &ChannelPortraitBasic{Channel: root}, Period: period, Available: true, RegisterTrend: []*PortraitTrend{}, PayTrend: []*PortraitTrend{}, GameDistribution: []*ChannelGame{}, PayTiers: []*ChannelPayTier{}}
+	if (root.Level == nil || *root.Level != 1) && root.ParentID > 0 {
+		parent, err := uc.channels.Find(ctx, UserScope{All: true}, ChannelKey{SourceDB: source, ID: root.ParentID})
+		if err != nil && !errors.IsNotFound(err) {
+			return nil, err
+		}
+		profile.Basic.Parent = parent
+	}
+	if root.BusierID > 0 {
+		bindings, err := uc.reports.Bindings(ctx, viewer, []string{source}, &PlatformKey{SourceDB: source, BusierID: root.BusierID})
+		if err != nil {
+			return nil, err
+		}
+		if len(bindings) > 0 {
+			b := bindings[0]
+			root.BusierUserID = &b.UserID
+			root.BindingAccount = b.Account
+			owner, err := uc.accounts.repo.Find(ctx, b.UserID)
+			if err != nil && !errors.IsNotFound(err) {
+				return nil, err
+			}
+			if owner != nil {
+				root.BindingUserName = owner.Username
+			}
+		}
+	}
+	profile.Basic.GameCount, err = uc.repo.GameCount(ctx, key)
+	if err != nil {
+		return nil, err
+	}
+	if profile.Basic.GameCount == nil {
+		return unavailableChannelPortrait(profile, "推广游戏数据尚未接入，渠道画像指标暂不可用"), nil
+	}
+	pref, err := uc.preferences.Current(ctx)
+	if err != nil {
+		return nil, err
+	}
+	now := uc.now()
+	today := now.In(portraitLocation).Format("2006-01-02")
+	cumulative := ChannelGameScope{Root: root, IncludeSub: pref.IncludeSubPromote, IDCardDedup: pref.IDCardDedup, EndDate: today}
+	begin, available, err := uc.repo.EarliestDate(ctx, cumulative)
+	if err != nil {
+		return nil, err
+	}
+	if !available {
+		return unavailableChannelPortrait(profile, "日汇总数据尚未接入，渠道画像指标暂不可用"), nil
+	}
+	if begin == "" {
+		begin = today
+	}
+	cumulative.BeginDate = begin
+	ranges := portraitRanges(period, now)
+	if period == "total" {
+		ranges.Begin, err = time.ParseInLocation("2006-01-02", begin, portraitLocation)
+		if err != nil {
+			return nil, ErrStorage
+		}
+		ranges.Hourly = false
+		ranges.CompareLabel = ""
+	}
+	stats, err := uc.reports.Statistics(ctx, PortraitReportScope{Root: root, Sources: []string{source}, IncludeSub: pref.IncludeSubPromote, IDCardDedup: pref.IDCardDedup, Range: ranges, NoCompare: period == "total"})
+	if err != nil {
+		return nil, err
+	}
+	if !stats.Available {
+		return unavailableChannelPortrait(profile, "汇总或趋势数据尚未接入，渠道画像指标暂不可用"), nil
+	}
+	profile.Metrics, err = channelPortraitMetrics(stats, ranges.CompareLabel, period != "total")
+	if err != nil {
+		return nil, err
+	}
+	profile.RegisterTrend, err = portraitTrend(stats.RegisterSeries, ranges, false)
+	if err != nil {
+		return nil, err
+	}
+	profile.PayTrend, err = portraitTrend(stats.PaySeries, ranges, true)
+	if err != nil {
+		return nil, err
+	}
+	games, err := uc.channels.Games(ctx, cumulative)
+	if err != nil {
+		if err == ErrChannelReportsUnavailable {
+			return unavailableChannelPortrait(profile, "推广游戏汇总数据尚未接入"), nil
+		}
+		return nil, err
+	}
+	profile.GameDistribution, err = normalizeChannelGames(games)
+	if err != nil {
+		return nil, err
+	}
+	tiers, err := uc.repo.TierData(ctx, cumulative)
+	if err != nil {
+		return nil, err
+	}
+	if !tiers.Available {
+		return unavailableChannelPortrait(profile, "付费分层所需的注册或支付数据尚未接入"), nil
+	}
+	profile.PayTiers, err = buildChannelPayTiers(source, pref.IDCardDedup, tiers)
+	return profile, err
+}
+func channelPortraitMetrics(stats *PortraitStatistics, label string, compare bool) (*ChannelPortraitMetrics, error) {
+	base, err := portraitMetrics(stats, label)
+	if err != nil {
+		return nil, err
+	}
+	active, err := portraitRateCard(strconv.FormatInt(min(stats.Current.Active, int64(2147483647)), 10), strconv.FormatInt(min(stats.Previous.Active, int64(2147483647)), 10), label)
+	if err != nil {
+		return nil, err
+	}
+	result := &ChannelPortraitMetrics{Register: base.Register, PayAmount: base.PayAmount, PayRate: base.PayRate, Active: active}
+	if !compare {
+		for _, card := range []*PortraitMetric{result.Register, result.PayAmount, result.PayRate, result.Active} {
+			card.CompareValue = nil
+			card.ChangeDiff = nil
+			card.ChangeRate = nil
+			card.CompareLabel = ""
+		}
+	}
+	return result, nil
+}
+func buildChannelPayTiers(source string, dedup bool, data *ChannelTierData) ([]*ChannelPayTier, error) {
+	keys := map[string]bool{}
+	for _, key := range data.RegisterKeys {
+		keys[key] = true
+	}
+	denominator := int64(len(keys))
+	if denominator == 0 {
+		denominator = min(data.FallbackCount, int64(2147483647))
+	}
+	counts := []int64{0, 0, 0, 0}
+	if len(keys) == 0 {
+		counts[3] = denominator
+	} else {
+		payByKey := map[string]*big.Rat{}
+		for _, payment := range data.Payments {
+			var key string
+			if dedup {
+				if payment.IDCard == nil {
+					continue
+				}
+				key = normalizeIDCard(*payment.IDCard)
+				if key == "" {
+					continue
+				}
+			} else {
+				if payment.UserID == nil {
+					continue
+				}
+				key = source + "|" + strconv.FormatUint(*payment.UserID, 10)
+			}
+			amount, err := portraitNumber(payment.Amount)
+			if err != nil {
+				return nil, err
+			}
+			amount, _ = portraitNumber(portraitDecimal(amount, 2))
+			if payByKey[key] == nil {
+				payByKey[key] = new(big.Rat)
+			}
+			payByKey[key].Add(payByKey[key], amount)
+		}
+		for key := range keys {
+			pay := payByKey[key]
+			if pay == nil {
+				pay = new(big.Rat)
+			}
+			switch {
+			case pay.Cmp(big.NewRat(10000, 1)) >= 0:
+				counts[0]++
+			case pay.Cmp(big.NewRat(1000, 1)) >= 0:
+				counts[1]++
+			case pay.Sign() > 0:
+				counts[2]++
+			default:
+				counts[3]++
+			}
+		}
+	}
+	result := []*ChannelPayTier{}
+	codes := []string{"whale", "mid", "small", "free"}
+	labels := []string{"大R", "中R", "小R", "免费"}
+	for i, code := range codes {
+		ratio := "0.0"
+		if denominator > 0 {
+			ratio = portraitDecimal(new(big.Rat).Mul(big.NewRat(counts[i], denominator), big.NewRat(100, 1)), 1)
+		}
+		result = append(result, &ChannelPayTier{Tier: code, Label: labels[i], Count: counts[i], Ratio: ratio})
+	}
+	return result, nil
+}

internal/biz/business/channel_portrait_test.go

@@ -0,0 +1,120 @@
+package business
+
+import (
+	"context"
+	"testing"
+	"time"
+)
+
+type channelPortraitRepoFake struct {
+	count     *int64
+	first     string
+	tiers     *ChannelTierData
+	tierScope ChannelGameScope
+}
+
+func (r *channelPortraitRepoFake) GameCount(context.Context, ChannelKey) (*int64, error) {
+	return r.count, nil
+}
+func (r *channelPortraitRepoFake) EarliestDate(context.Context, ChannelGameScope) (string, bool, error) {
+	return r.first, true, nil
+}
+func (r *channelPortraitRepoFake) TierData(_ context.Context, s ChannelGameScope) (*ChannelTierData, error) {
+	r.tierScope = s
+	return r.tiers, nil
+}
+
+type portraitChannelReaderFake struct {
+	ChannelRepo
+	rows      map[ChannelKey]*Channel
+	gameScope ChannelGameScope
+}
+
+func (r *portraitChannelReaderFake) Find(_ context.Context, scope UserScope, key ChannelKey) (*Channel, error) {
+	if !scope.All && scope.SelfID == 99 {
+		return nil, ErrChannelScope
+	}
+	row := r.rows[key]
+	if row == nil {
+		return nil, ErrChannelNotFound
+	}
+	copy := *row
+	return &copy, nil
+}
+func (r *portraitChannelReaderFake) Games(_ context.Context, s ChannelGameScope) ([]*ChannelGame, error) {
+	r.gameScope = s
+	return []*ChannelGame{{ID: 1, Name: "游戏", RegisterCount: 1, PayAmount: "12.00"}}, nil
+}
+func channelPortraitFixture() (*ChannelPortraitUsecase, *channelPortraitRepoFake, *portraitChannelReaderFake, *portraitRepoFake) {
+	base, reports := portraitFixture()
+	key := ChannelKey{SourceDB: "lx", ID: 101}
+	parent := ChannelKey{SourceDB: "lx", ID: 100}
+	count := int64(1)
+	channels := &portraitChannelReaderFake{rows: map[ChannelKey]*Channel{key: {ChannelKey: key, Account: "child", Nickname: "子渠道", Level: intPointer(2), Status: intPointer(-3), ParentID: 100, BusierID: 14}, parent: {ChannelKey: parent, Account: "parent", Level: intPointer(1)}}}
+	repo := &channelPortraitRepoFake{count: &count, first: "2026-11-01", tiers: &ChannelTierData{Available: true, RegisterKeys: []string{"A"}}}
+	uc := NewChannelPortraitUsecase(repo, channels, reports, base.accounts, base.preferences)
+	uc.now = func() time.Time { return time.Date(2026, 11, 3, 12, 0, 0, 0, portraitLocation) }
+	return uc, repo, channels, reports
+}
+func TestChannelPortraitTotalHasNoComparisonAndKeepsCumulativeParts(t *testing.T) {
+	uc, repo, channels, reports := channelPortraitFixture()
+	p, err := uc.Portrait(accountContext(7, 901), ChannelKey{SourceDB: "lx", ID: 101}, "total")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if p.Period != "total" || !reports.scope.NoCompare || reports.scope.Root.ID != 101 || len(reports.scope.Pairs) != 0 {
+		t.Fatal("累计模式或渠道范围错误")
+	}
+	if reports.scope.Range.Begin.Format("2006-01-02") != "2026-11-01" || len(p.RegisterTrend) != 3 || p.Metrics.Active.Value != "3" || p.Metrics.Active.CompareValue != nil || p.Metrics.PayAmount.ChangeRate != nil {
+		t.Fatal("累计卡片不应带环比，趋势应从最早汇总开始")
+	}
+	if p.Basic.Parent == nil || p.Basic.Parent.Account != "parent" || p.Basic.Channel.BusinessDisplayName() != "leaf" {
+		t.Fatal("上级渠道或归属商务资料未正确补齐")
+	}
+	p, err = uc.Portrait(accountContext(7, 901), ChannelKey{SourceDB: "lx", ID: 101}, "last7")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(p.RegisterTrend) != 7 || channels.gameScope.BeginDate != "2026-11-01" || repo.tierScope.BeginDate != "2026-11-01" || reports.scope.Range.Begin.Format("2006-01-02") != "2026-10-28" {
+		t.Fatal("日期切换不应把游戏分布或分层改成当期口径")
+	}
+}
+func TestChannelPortraitMissingDataAndVisibility(t *testing.T) {
+	uc, repo, _, _ := channelPortraitFixture()
+	repo.count = nil
+	p, err := uc.Portrait(accountContext(7, 901), ChannelKey{SourceDB: "lx", ID: 101}, "today")
+	if err != nil || p.Available || p.Metrics != nil || p.Basic.Channel.Account != "child" {
+		t.Fatal("缺业务数据时应保留已读取资料，不造零指标")
+	}
+	if _, err := uc.Portrait(accountContext(99, 901), ChannelKey{SourceDB: "lx", ID: 101}, "today"); err != ErrChannelScope {
+		t.Fatal("越权渠道画像被放行")
+	}
+	if normalizeChannelPortraitPeriod("thismonth") != "today" || normalizeChannelPortraitPeriod("TOTAL") != "total" {
+		t.Fatal("渠道周期范围与商务画像混用")
+	}
+}
+func TestChannelPayTiersUseRegisteredIdentitiesAndExactThresholds(t *testing.T) {
+	data := &ChannelTierData{RegisterKeys: []string{"A-x", "A-x", "B", "C", "D", "E", "F"}, Payments: []*ChannelIdentityPay{{IDCard: stringPointer(" A-X "), Amount: "9999.50"}, {IDCard: stringPointer("A-x"), Amount: "0.50"}, {IDCard: stringPointer("B"), Amount: "1000.00"}, {IDCard: stringPointer("C"), Amount: "0.01"}, {IDCard: stringPointer("D"), Amount: "0"}, {IDCard: stringPointer("E"), Amount: "-1"}, {IDCard: stringPointer("outside"), Amount: "999999"}}}
+	tiers, err := buildChannelPayTiers("lx", true, data)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := []int64{1, 1, 1, 3}
+	for i, tier := range tiers {
+		if tier.Count != want[i] {
+			t.Fatalf("分层边界、归一或成员范围错误: %+v", tiers)
+		}
+	}
+	if tiers[0].Ratio != "16.7" || tiers[3].Ratio != "50.0" {
+		t.Fatal("分层比例应独立保留一位，不强行凑整")
+	}
+	id1, id2, id4 := uint64(1), uint64(2), uint64(4)
+	tiers, err = buildChannelPayTiers("lx", false, &ChannelTierData{RegisterKeys: []string{"lx|1", "lx|2", "lx|3"}, Payments: []*ChannelIdentityPay{{UserID: &id1, Amount: "1000"}, {UserID: &id2, Amount: "999.99"}, {UserID: &id4, Amount: "100000"}}})
+	if err != nil || tiers[0].Count != 0 || tiers[1].Count != 1 || tiers[2].Count != 1 || tiers[3].Count != 1 {
+		t.Fatal("模式0必须使用带平台前缀的原始用户 ID，未注册身份不参与分层")
+	}
+	tiers, err = buildChannelPayTiers("lx", false, &ChannelTierData{FallbackCount: 5})
+	if err != nil || tiers[3].Count != 5 || tiers[3].Ratio != "100.0" {
+		t.Fatal("无身份列表时应保留原回退的免费人数")
+	}
+}