《互联网产品的服务端架构·交易、增长与平台化》9.2 召回链路与转化归因

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

package reach

import (
	"errors"
	"fmt"
)

// ErrInvalidWindow 表示归因窗口不是正数。窗口为 0 或负数时，任何“最近
// 一次触点”都没有意义，必须让调用方显式修正配置。
var ErrInvalidWindow = errors.New("reach: attribution window must be positive")

// Touch 是一次营销触点，例如推送、短信、弹窗或优惠券曝光。At 是服务端
// 收到触点事件的时间，Campaign 是活动标识。同一次活动可能对同一用户产生
// 多条触点，归因只关心窗口内最近的一条。
type Touch struct {
	UserID   string
	Campaign string
	At       int64
}

// Attribute 返回 userID 在归因窗口内的最后一次触点所属活动。窗口是闭区间
// [now-windowSeconds, now]：恰好落在窗口起点和 now 上的触点都算，未来时间
// 的触点不算。
//
// 同一时刻有多条触点时，取 Campaign 字典序最小的一条，保证结果与输入顺序
// 无关、可复现。窗口内没有触点时返回空字符串和 nil 错误，调用方据此把
// 回流记为自然量，而不是硬塞给某个活动。
func Attribute(touches []Touch, userID string, now, windowSeconds int64) (string, error) {
	if windowSeconds <= 0 {
		return "", fmt.Errorf("%w: %d", ErrInvalidWindow, windowSeconds)
	}

	since := now - windowSeconds
	bestCampaign := ""
	var bestAt int64
	found := false

	for _, t := range touches {
		if t.UserID != userID {
			continue
		}
		if t.At < since || t.At > now {
			continue
		}
		switch {
		case !found:
		case t.At > bestAt:
		case t.At == bestAt && t.Campaign < bestCampaign:
		default:
			continue
		}
		bestCampaign = t.Campaign
		bestAt = t.At
		found = true
	}

	if !found {
		return "", nil
	}
	return bestCampaign, nil
}

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

package reach

import (
	"errors"
	"testing"
)

func TestAttributePicksLatestTouch(t *testing.T) {
	touches := []Touch{
		{UserID: "u1", Campaign: "push-old", At: 900},
		{UserID: "u1", Campaign: "push-new", At: 980},
		{UserID: "u2", Campaign: "other", At: 990},
	}
	got, err := Attribute(touches, "u1", 1000, 120)
	if err != nil {
		t.Fatalf("Attribute = %v, want nil", err)
	}
	if got != "push-new" {
		t.Fatalf("Attribute = %q; want push-new", got)
	}
}

func TestAttributeWindowIsClosed(t *testing.T) {
	touches := []Touch{
		{UserID: "u1", Campaign: "outside", At: 879},
		{UserID: "u1", Campaign: "start", At: 880},
		{UserID: "u1", Campaign: "now", At: 1000},
	}
	got, err := Attribute(touches, "u1", 1000, 120)
	if err != nil {
		t.Fatalf("Attribute = %v, want nil", err)
	}
	if got != "now" {
		t.Fatalf("Attribute = %q; want now", got)
	}

	onlyStart := []Touch{{UserID: "u1", Campaign: "start", At: 880}}
	got, err = Attribute(onlyStart, "u1", 1000, 120)
	if err != nil || got != "start" {
		t.Fatalf("start boundary = %q, %v; want start, nil", got, err)
	}
}

func TestAttributeIgnoresFutureTouch(t *testing.T) {
	touches := []Touch{
		{UserID: "u1", Campaign: "past", At: 990},
		{UserID: "u1", Campaign: "future", At: 1001},
	}
	got, err := Attribute(touches, "u1", 1000, 120)
	if err != nil {
		t.Fatalf("Attribute = %v, want nil", err)
	}
	if got != "past" {
		t.Fatalf("Attribute = %q; want past", got)
	}
}

func TestAttributeTieBreaksByCampaign(t *testing.T) {
	touches := []Touch{
		{UserID: "u1", Campaign: "sms-b", At: 990},
		{UserID: "u1", Campaign: "sms-a", At: 990},
		{UserID: "u1", Campaign: "push-z", At: 990},
	}
	got, err := Attribute(touches, "u1", 1000, 120)
	if err != nil {
		t.Fatalf("Attribute = %v, want nil", err)
	}
	if got != "push-z" {
		t.Fatalf("Attribute = %q; want push-z (lexicographically smallest)", got)
	}
}

func TestAttributeNoTouchIsNatural(t *testing.T) {
	got, err := Attribute(nil, "u1", 1000, 120)
	if err != nil {
		t.Fatalf("Attribute = %v, want nil", err)
	}
	if got != "" {
		t.Fatalf("Attribute = %q; want empty for natural traffic", got)
	}
}

func TestAttributeRejectsBadWindow(t *testing.T) {
	for _, w := range []int64{0, -1} {
		if _, err := Attribute(nil, "u1", 1000, w); !errors.Is(err, ErrInvalidWindow) {
			t.Fatalf("window=%d err = %v; want ErrInvalidWindow", w, err)
		}
	}
}

go test ./internal/reach/ -run '^TestAttribute' -count=1 -v

=== RUN   TestAttributePicksLatestTouch
--- PASS: TestAttributePicksLatestTouch (0.00s)
=== RUN   TestAttributeWindowIsClosed
--- PASS: TestAttributeWindowIsClosed (0.00s)
=== RUN   TestAttributeIgnoresFutureTouch
--- PASS: TestAttributeIgnoresFutureTouch (0.00s)
=== RUN   TestAttributeTieBreaksByCampaign
--- PASS: TestAttributeTieBreaksByCampaign (0.00s)
=== RUN   TestAttributeNoTouchIsNatural
--- PASS: TestAttributeNoTouchIsNatural (0.00s)
=== RUN   TestAttributeRejectsBadWindow
--- PASS: TestAttributeRejectsBadWindow (0.00s)
PASS
ok  	webapp/internal/reach	0.240s