《互联网产品的服务端架构·交易、增长与平台化》5.3 订阅与自动续费

newPeriodEnd = max(now, PeriodEnd) + periodSeconds

// file: internal/member/subscription.go
// tier: L1
// verify: go test ./internal/member/

package member

import (
	"errors"
	"fmt"
	"math"
)

var (
	// ErrInvalidPeriod 表示 PeriodEnd 或 periodSeconds 不是正数。
	ErrInvalidPeriod = errors.New("member: invalid period")
	// ErrAutoRenewOff 表示订阅已经关闭自动续费，不能再续期。
	ErrAutoRenewOff = errors.New("member: auto renew off")
	// ErrPeriodOverflow 表示续期后的到期时间会超出 int64 上限。
	ErrPeriodOverflow = errors.New("member: period overflow")
)

// Sub 是一条订阅记录。PeriodEnd 是当前计费周期的结束时刻（Unix 秒），
// AutoRenew 表示用户是否授权下一周期自动扣费。
//
// PeriodEnd 只表示“已付费到什么时候”，不表示“权益什么时候被切断”。
// 自动续费失败、用户取消或退款时，权益是否立即失效由业务规则决定，
// 不应该靠修改 PeriodEnd 来暗示。
type Sub struct {
	UserID    string
	PlanID    string
	PeriodEnd int64
	AutoRenew bool
}

// Renew 计算续费后的订阅。now 是本次续费请求到达的时间，
// periodSeconds 是一个周期的长度。新的到期时间从 max(now, PeriodEnd)
// 起算：提前续费不会吞掉剩余天数，逾期续费也不会把过去的空档补回来。
//
// AutoRenew 为 false 时返回 ErrAutoRenewOff，原订阅不变；PeriodEnd 或
// periodSeconds 非正时返回 ErrInvalidPeriod；相加溢出返回
// ErrPeriodOverflow。成功时只修改 PeriodEnd，其余字段保持不变。
func Renew(s Sub, now, periodSeconds int64) (Sub, error) {
	if !s.AutoRenew {
		return s, fmt.Errorf("%w: user %s plan %s", ErrAutoRenewOff, s.UserID, s.PlanID)
	}
	if s.PeriodEnd <= 0 || periodSeconds <= 0 {
		return s, fmt.Errorf("%w: end=%d period=%d", ErrInvalidPeriod, s.PeriodEnd, periodSeconds)
	}

	base := s.PeriodEnd
	if now > base {
		base = now
	}
	if base > math.MaxInt64-periodSeconds {
		return s, fmt.Errorf("%w: base %d + %d", ErrPeriodOverflow, base, periodSeconds)
	}
	s.PeriodEnd = base + periodSeconds
	return s, nil
}

// Cancel 关闭自动续费，返回修改后的副本。
//
// Cancel 不会清空 PeriodEnd：用户已经付过当前周期的钱，取消续费只是
// 不再扣下一期，当前周期应当继续有效到 PeriodEnd。是否立即退款、
// 是否立即收回权益是另外的业务动作，不能和“取消续费”混为一谈。
func Cancel(s Sub) Sub {
	s.AutoRenew = false
	return s
}

// file: internal/member/subscription_test.go
// tier: L1
// verify: go test ./internal/member/

package member

import (
	"errors"
	"testing"
)

func TestRenewStartsFromPeriodEndWhenEarly(t *testing.T) {
	s := Sub{UserID: "u1", PlanID: "monthly", PeriodEnd: 1000, AutoRenew: true}
	got, err := Renew(s, 800, 3000)
	if err != nil {
		t.Fatalf("Renew = %v, want nil", err)
	}
	if got.PeriodEnd != 4000 {
		t.Fatalf("PeriodEnd = %d, want 4000", got.PeriodEnd)
	}
	if s.PeriodEnd != 1000 {
		t.Fatalf("input mutated: PeriodEnd = %d, want 1000", s.PeriodEnd)
	}
}

func TestRenewStartsFromNowWhenLapsed(t *testing.T) {
	s := Sub{UserID: "u1", PlanID: "monthly", PeriodEnd: 1000, AutoRenew: true}
	got, err := Renew(s, 5000, 3000)
	if err != nil {
		t.Fatalf("Renew = %v, want nil", err)
	}
	if got.PeriodEnd != 8000 {
		t.Fatalf("PeriodEnd = %d, want 8000", got.PeriodEnd)
	}
}

func TestRenewAtBoundaryUsesPeriodEnd(t *testing.T) {
	s := Sub{UserID: "u1", PlanID: "monthly", PeriodEnd: 1000, AutoRenew: true}
	got, err := Renew(s, 1000, 3000)
	if err != nil {
		t.Fatalf("Renew = %v, want nil", err)
	}
	if got.PeriodEnd != 4000 {
		t.Fatalf("PeriodEnd = %d, want 4000", got.PeriodEnd)
	}
}

func TestRenewRejectsAutoRenewOff(t *testing.T) {
	s := Sub{UserID: "u1", PlanID: "monthly", PeriodEnd: 1000}
	got, err := Renew(s, 1000, 3000)
	if !errors.Is(err, ErrAutoRenewOff) {
		t.Fatalf("Renew = %v, want ErrAutoRenewOff", err)
	}
	if got != s {
		t.Fatalf("got = %+v, want original %+v", got, s)
	}
}

func TestRenewRejectsInvalidPeriod(t *testing.T) {
	cases := []struct {
		name string
		sub  Sub
		now  int64
		sec  int64
	}{
		{"zero-end", Sub{PeriodEnd: 0, AutoRenew: true}, 100, 1000},
		{"negative-end", Sub{PeriodEnd: -1, AutoRenew: true}, 100, 1000},
		{"zero-period", Sub{PeriodEnd: 100, AutoRenew: true}, 100, 0},
		{"negative-period", Sub{PeriodEnd: 100, AutoRenew: true}, 100, -1},
	}
	for _, c := range cases {
		t.Run(c.name, func(t *testing.T) {
			if _, err := Renew(c.sub, c.now, c.sec); !errors.Is(err, ErrInvalidPeriod) {
				t.Fatalf("Renew = %v, want ErrInvalidPeriod", err)
			}
		})
	}
}

func TestRenewDetectsOverflow(t *testing.T) {
	max := int64(^uint64(0) >> 1)
	s := Sub{UserID: "u1", PlanID: "monthly", PeriodEnd: max, AutoRenew: true}
	if _, err := Renew(s, 0, 1); !errors.Is(err, ErrPeriodOverflow) {
		t.Fatalf("Renew = %v, want ErrPeriodOverflow", err)
	}
}

func TestCancelKeepsPeriodEnd(t *testing.T) {
	s := Sub{UserID: "u1", PlanID: "monthly", PeriodEnd: 1000, AutoRenew: true}
	got := Cancel(s)
	if got.AutoRenew {
		t.Fatal("AutoRenew should be false after Cancel")
	}
	if got.PeriodEnd != 1000 {
		t.Fatalf("PeriodEnd = %d, want 1000", got.PeriodEnd)
	}
	if !s.AutoRenew {
		t.Fatal("Cancel must not mutate the input")
	}
	if _, err := Renew(got, 1000, 3000); !errors.Is(err, ErrAutoRenewOff) {
		t.Fatalf("Renew after Cancel = %v, want ErrAutoRenewOff", err)
	}
}

cd .local/checks/webapp-lab && go test ./internal/member/ -run 'TestRenew|TestCancel' -count=1 -v

=== RUN   TestRenewStartsFromPeriodEndWhenEarly
--- PASS: TestRenewStartsFromPeriodEndWhenEarly (0.00s)
=== RUN   TestRenewStartsFromNowWhenLapsed
--- PASS: TestRenewStartsFromNowWhenLapsed (0.00s)
=== RUN   TestRenewAtBoundaryUsesPeriodEnd
--- PASS: TestRenewAtBoundaryUsesPeriodEnd (0.00s)
=== RUN   TestRenewRejectsAutoRenewOff
--- PASS: TestRenewRejectsAutoRenewOff (0.00s)
=== RUN   TestRenewRejectsInvalidPeriod
=== RUN   TestRenewRejectsInvalidPeriod/zero-end
=== RUN   TestRenewRejectsInvalidPeriod/negative-end
=== RUN   TestRenewRejectsInvalidPeriod/zero-period
=== RUN   TestRenewRejectsInvalidPeriod/negative-period
--- PASS: TestRenewRejectsInvalidPeriod (0.00s)
    --- PASS: TestRenewRejectsInvalidPeriod/zero-end (0.00s)
    --- PASS: TestRenewRejectsInvalidPeriod/negative-end (0.00s)
    --- PASS: TestRenewRejectsInvalidPeriod/zero-period (0.00s)
    --- PASS: TestRenewRejectsInvalidPeriod/negative-period (0.00s)
=== RUN   TestRenewDetectsOverflow
--- PASS: TestRenewDetectsOverflow (0.00s)
=== RUN   TestCancelKeepsPeriodEnd
--- PASS: TestCancelKeepsPeriodEnd (0.00s)
PASS
ok  	webapp/internal/member	0.310s