《游戏服务端架构·品类、状态与拓扑》4.3 离线推进与时间旅行：SLG 的补算

如果 finishAt <= now：完成，产出按新等级从 finishAt 起算
如果 finishAt >  now：仍在进行，剩余时间 = finishAt - now

[lastSeen, finishAt)  旧产率
[finishAt, now)       新产率

// file: internal/offline/accrue.go
// tier: L1
// verify: go test ./internal/offline/
package offline

import "time"

// Accrual is the result of replaying offline production. Amount is the total
// granted now, Seconds is the replayed duration, Days is the number of local
// calendar segments crossed, Capped reports whether any segment hit the daily
// cap, and RolledBack reports a non-forward clock.
type Accrual struct {
	Amount     float64
	Seconds    float64
	Days       int
	Capped     bool
	RolledBack bool
}

// Accrue replays production in UTC. Callers that run a regional server should
// use AccrueInZone with the same location that defines their daily reset.
func Accrue(lastSeen, now time.Time, ratePerHour, cap float64) Accrual {
	return AccrueInZone(lastSeen, now, ratePerHour, cap, time.UTC)
}

// AccrueInZone walks the interval one local calendar day at a time. Each day
// has its own cap, so a player who returns after a week does not receive seven
// days of production compressed into one day's cap, and does not receive more
// than seven daily caps either.
//
// The loop must never be replaced by a single now.Sub(lastSeen) calculation:
// that loses the day boundary, cannot apply a per-day cap, and makes the
// result depend on which timezone happens to run the settlement job.
func AccrueInZone(lastSeen, now time.Time, ratePerHour, cap float64, loc *time.Location) Accrual {
	if loc == nil {
		loc = time.UTC
	}
	if !now.After(lastSeen) {
		// Equal timestamps mean a duplicate request; earlier timestamps mean
		// the clock moved backwards. Both must grant nothing.
		return Accrual{RolledBack: true}
	}
	if ratePerHour <= 0 || cap <= 0 {
		return Accrual{}
	}

	var out Accrual
	cursor := lastSeen
	for cursor.Before(now) {
		year, month, day := cursor.In(loc).Date()
		dayStart := time.Date(year, month, day, 0, 0, 0, 0, loc)
		nextDay := dayStart.AddDate(0, 0, 1)

		segmentEnd := now
		if nextDay.Before(now) {
			segmentEnd = nextDay
		}
		seconds := segmentEnd.Sub(cursor).Seconds()
		if seconds < 0 {
			seconds = 0
		}

		amount := seconds / 3600 * ratePerHour
		if amount > cap {
			amount = cap
			out.Capped = true
		}
		out.Amount += amount
		out.Seconds += seconds
		out.Days++
		cursor = segmentEnd
	}
	return out
}

// file: internal/offline/accrue_test.go
// tier: L1
// verify: go test ./internal/offline/
package offline

import (
	"testing"
	"time"
)

func mustZone(t *testing.T, name string, offset time.Duration) *time.Location {
	t.Helper()
	return time.FixedZone(name, int(offset.Seconds()))
}

func TestAccrueNormal(t *testing.T) {
	start := time.Date(2026, 10, 20, 8, 0, 0, 0, time.UTC)
	got := Accrue(start, start.Add(2*time.Hour), 120, 1000)
	if got.Amount != 240 {
		t.Fatalf("amount=%v, want 240", got.Amount)
	}
	if got.Days != 1 || got.Capped || got.RolledBack {
		t.Fatalf("got %+v", got)
	}
}

func TestAccrueHitsDailyCap(t *testing.T) {
	start := time.Date(2026, 10, 20, 0, 0, 0, 0, time.UTC)
	got := Accrue(start, start.Add(10*time.Hour), 100, 500)
	if got.Amount != 500 {
		t.Fatalf("amount=%v, want 500", got.Amount)
	}
	if !got.Capped {
		t.Fatal("Capped=false, want true")
	}
}

func TestAccrueClockRollback(t *testing.T) {
	now := time.Date(2026, 10, 20, 12, 0, 0, 0, time.UTC)
	got := Accrue(now.Add(time.Hour), now, 100, 500)
	if got.Amount != 0 || !got.RolledBack {
		t.Fatalf("got %+v, want zero and RolledBack", got)
	}
	if same := Accrue(now, now, 100, 500); same.Amount != 0 || !same.RolledBack {
		t.Fatalf("equal timestamps: %+v", same)
	}
}

func TestAccrueResetsCapAcrossDay(t *testing.T) {
	loc := mustZone(t, "UTC+8", 8*time.Hour)
	start := time.Date(2026, 10, 20, 23, 30, 0, 0, loc)
	got := AccrueInZone(start, start.Add(time.Hour), 100, 60, loc)
	// 30 minutes before midnight and 30 minutes after each earn 50, and each
	// local day carries its own cap of 60. Without a day boundary the total
	// would be clamped to 60 instead of 100.
	if got.Amount != 100 {
		t.Fatalf("amount=%v, want 100", got.Amount)
	}
	if got.Days != 2 {
		t.Fatalf("days=%d, want 2", got.Days)
	}
	if got.Capped {
		t.Fatalf("capped=true, want false: %+v", got)
	}
}

func TestAccrueTimezoneChangesDayBoundary(t *testing.T) {
	// 15:30Z-16:30Z is one hour inside UTC but crosses midnight in UTC+8.
	start := time.Date(2026, 10, 20, 15, 30, 0, 0, time.UTC)
	end := start.Add(time.Hour)

	utc := AccrueInZone(start, end, 100, 1000, time.UTC)
	east := AccrueInZone(start, end, 100, 1000, mustZone(t, "UTC+8", 8*time.Hour))

	if utc.Amount != 100 || east.Amount != 100 {
		t.Fatalf("amount utc=%v east=%v, want 100/100", utc.Amount, east.Amount)
	}
	if utc.Days != 1 || east.Days != 2 {
		t.Fatalf("days utc=%d east=%d, want 1/2", utc.Days, east.Days)
	}
}

$ cd .local/checks/gsarch-lab
$ gofmt -l internal/offline
$ go vet ./internal/offline
$ go test ./internal/offline/ -v -count=1
=== RUN   TestAccrueNormal
--- PASS: TestAccrueNormal (0.00s)
=== RUN   TestAccrueHitsDailyCap
--- PASS: TestAccrueHitsDailyCap (0.00s)
=== RUN   TestAccrueClockRollback
--- PASS: TestAccrueClockRollback (0.00s)
=== RUN   TestAccrueResetsCapAcrossDay
--- PASS: TestAccrueResetsCapAcrossDay (0.00s)
=== RUN   TestAccrueTimezoneChangesDayBoundary
--- PASS: TestAccrueTimezoneChangesDayBoundary (0.00s)
PASS
ok  	gsarchlab/internal/offline	0.393s

grant_id = hash(player_id, last_seen_unix, now_unix, economy_version)

BEGIN
  SELECT last_seen FROM player_economy WHERE player_id = ? FOR UPDATE
  -- 计算 Accrue
  INSERT INTO economy_ledger(grant_id, player_id, amount, source, created_at)
  UPDATE player_economy SET last_seen = ?, version = version + 1
COMMIT

库存快照变化
  == 在线产出 + 离线补算 + 战斗掉落 + 商店购买 - 消耗 - 过期