《互联网产品的服务端架构·交易、增长与平台化》9.3 退订、频控与合规

// file: internal/reach/unsubscribe.go
// tier: L1
// verify: go test ./internal/reach/

package reach

import (
	"errors"
	"fmt"
)

var (
	// ErrInvalidCapWindow 表示频控窗口不是正数。
	ErrInvalidCapWindow = errors.New("reach: cap window must be positive")
	// ErrInvalidCapMax 表示频控上限为负数。
	ErrInvalidCapMax = errors.New("reach: cap max must not be negative")
	// ErrClockRegression 表示历史发送时间晚于当前时间，通常意味着时钟回拨
	// 或上游事件乱序，继续计数会得到不可信的结果。
	ErrClockRegression = errors.New("reach: send time is later than now")
)

// Pref 是用户对一个渠道的订阅偏好。同一用户同一渠道可能有多条记录，
// 以切片中最后一条为准；OptOut 为 true 表示明确退订。
type Pref struct {
	UserID  string
	Channel string
	OptOut  bool
}

// Cap 是单渠道的频控配置。WindowSeconds 是统计窗口，Max 是窗口内允许的
// 最大发送次数；Max 为 0 表示不限制次数。窗口是左开右闭区间
// (now-WindowSeconds, now]，与归因的闭区间刻意不同。
type Cap struct {
	WindowSeconds int64
	Max           int
}

// Allowed 判断用户在某个渠道是否仍可接收营销消息。没有任何偏好记录时
// 默认允许；同一用户同一渠道只看最后一条 Pref，后写入的偏好覆盖先写入的。
//
// 发送链路必须先调用 Allowed，再调用 AllowSend。退订是合规要求，优先级
// 高于频控：用户已经退订时，即使频控仍有余量也不能发送。
func Allowed(prefs []Pref, userID, channel string) bool {
	allowed := true
	for _, p := range prefs {
		if p.UserID == userID && p.Channel == channel {
			allowed = !p.OptOut
		}
	}
	return allowed
}

// AllowSend 判断在当前时间 now 是否还能向用户发送一条营销消息。history
// 是该用户在该渠道上的历史发送时间，顺序不限；窗口内的每一次发送都计数，
// 不区分成功与失败，避免失败重试绕过频控。
//
// 返回错误的情况有三类：窗口非正数、上限为负数、历史时间晚于 now。最后
// 一类对应时钟回拨或事件乱序，必须让调用方停下来，而不是静默少算。
func AllowSend(history []int64, now int64, c Cap) (bool, error) {
	if c.WindowSeconds <= 0 {
		return false, fmt.Errorf("%w: %d", ErrInvalidCapWindow, c.WindowSeconds)
	}
	if c.Max < 0 {
		return false, fmt.Errorf("%w: %d", ErrInvalidCapMax, c.Max)
	}
	for _, at := range history {
		if at > now {
			return false, fmt.Errorf("%w: %d > %d", ErrClockRegression, at, now)
		}
	}
	if c.Max == 0 {
		return true, nil
	}

	lower := now - c.WindowSeconds
	sent := 0
	for _, at := range history {
		if at > lower && at <= now {
			sent++
		}
	}
	return sent < c.Max, nil
}

// file: internal/reach/unsubscribe_test.go
// tier: L1
// verify: go test ./internal/reach/

package reach

import (
	"errors"
	"testing"
)

func TestAllowedDefaultsToTrue(t *testing.T) {
	if !Allowed(nil, "u1", "sms") {
		t.Fatal("Allowed with no prefs = false; want true")
	}
}

func TestAllowedLastPrefWins(t *testing.T) {
	prefs := []Pref{
		{UserID: "u1", Channel: "sms", OptOut: false},
		{UserID: "u1", Channel: "sms", OptOut: true},
		{UserID: "u1", Channel: "sms", OptOut: false},
	}
	if !Allowed(prefs, "u1", "sms") {
		t.Fatal("last pref opt-in = false; want true")
	}

	prefs = append(prefs, Pref{UserID: "u1", Channel: "sms", OptOut: true})
	if Allowed(prefs, "u1", "sms") {
		t.Fatal("last pref opt-out = true; want false")
	}
}

func TestAllowedScopesUserAndChannel(t *testing.T) {
	prefs := []Pref{
		{UserID: "u1", Channel: "sms", OptOut: true},
		{UserID: "u1", Channel: "push", OptOut: false},
		{UserID: "u2", Channel: "sms", OptOut: false},
	}
	if Allowed(prefs, "u1", "sms") {
		t.Fatal("u1 sms = true; want opted out")
	}
	if !Allowed(prefs, "u1", "push") {
		t.Fatal("u1 push = false; want allowed")
	}
	if !Allowed(prefs, "u2", "sms") {
		t.Fatal("u2 sms = false; want allowed")
	}
}

func TestAllowSendZeroMaxIsUnlimited(t *testing.T) {
	history := []int64{999, 999, 999}
	ok, err := AllowSend(history, 1000, Cap{WindowSeconds: 60, Max: 0})
	if err != nil {
		t.Fatalf("AllowSend = %v, want nil", err)
	}
	if !ok {
		t.Fatal("Max=0 = false; want true")
	}
}

func TestAllowSendWindowIsHalfOpen(t *testing.T) {
	// 窗口 (940, 1000]：940 不计，941 和 1000 都计。
	history := []int64{940, 941, 1000}
	ok, err := AllowSend(history, 1000, Cap{WindowSeconds: 60, Max: 3})
	if err != nil {
		t.Fatalf("AllowSend = %v, want nil", err)
	}
	if !ok {
		t.Fatal("sent=2 max=3 = false; want true")
	}
	if ok, _ := AllowSend(history, 1000, Cap{WindowSeconds: 60, Max: 2}); ok {
		t.Fatal("sent=2 max=2 = true; want false")
	}
}

func TestAllowSendIgnoresOldSends(t *testing.T) {
	history := []int64{100, 939, 950}
	ok, err := AllowSend(history, 1000, Cap{WindowSeconds: 60, Max: 1})
	if err != nil {
		t.Fatalf("AllowSend = %v, want nil", err)
	}
	if ok {
		t.Fatal("one send in window max=1 = true; want false")
	}
}

func TestAllowSendRejectsClockRegression(t *testing.T) {
	history := []int64{1000, 1001}
	_, err := AllowSend(history, 1000, Cap{WindowSeconds: 60, Max: 1})
	if !errors.Is(err, ErrClockRegression) {
		t.Fatalf("AllowSend = %v; want ErrClockRegression", err)
	}
}

func TestAllowSendRejectsBadConfig(t *testing.T) {
	if _, err := AllowSend(nil, 1000, Cap{WindowSeconds: 0, Max: 1}); !errors.Is(err, ErrInvalidCapWindow) {
		t.Fatalf("window=0 = %v; want ErrInvalidCapWindow", err)
	}
	if _, err := AllowSend(nil, 1000, Cap{WindowSeconds: 60, Max: -1}); !errors.Is(err, ErrInvalidCapMax) {
		t.Fatalf("max=-1 = %v; want ErrInvalidCapMax", err)
	}
}

go test ./internal/reach/ -run '^Test(Allowed|AllowSend)' -count=1 -v

=== RUN   TestAllowedDefaultsToTrue
--- PASS: TestAllowedDefaultsToTrue (0.00s)
=== RUN   TestAllowedLastPrefWins
--- PASS: TestAllowedLastPrefWins (0.00s)
=== RUN   TestAllowedScopesUserAndChannel
--- PASS: TestAllowedScopesUserAndChannel (0.00s)
=== RUN   TestAllowSendZeroMaxIsUnlimited
--- PASS: TestAllowSendZeroMaxIsUnlimited (0.00s)
=== RUN   TestAllowSendWindowIsHalfOpen
--- PASS: TestAllowSendWindowIsHalfOpen (0.00s)
=== RUN   TestAllowSendIgnoresOldSends
--- PASS: TestAllowSendIgnoresOldSends (0.00s)
=== RUN   TestAllowSendRejectsClockRegression
--- PASS: TestAllowSendRejectsClockRegression (0.00s)
=== RUN   TestAllowSendRejectsBadConfig
--- PASS: TestAllowSendRejectsBadConfig (0.00s)
PASS
ok  	webapp/internal/reach	0.242s