《游戏服务端架构·品类、状态与拓扑》8.3 异步结算、离线收益与补算

口径 A：UTC 自然日              -> 全球统一重置，玩家本地体验不一致
口径 B：赛区时区自然日          -> 本地 00:00 重置，符合玩家预期
口径 C：滚动 24 小时            -> 与“每日”语义不符，跨时区活动难对齐

库存' = clamp(库存 + 产出 - 消耗, 0, 仓库上限)
溢出   = max(库存 + 产出 - 消耗 - 仓库上限, 0)

// file: internal/settle/settle.go
// tier: L1
// verify: go test ./internal/settle/
package settle

import (
	"crypto/sha256"
	"encoding/hex"
	"errors"
	"fmt"
	"time"

	"gsarchlab/internal/offline"
)

var (
	ErrInvalidConfig = errors.New("settle: invalid config")
	ErrClockRollback = errors.New("settle: clock moved backwards")
	ErrInvalidGrant  = errors.New("settle: invalid compensation")
	ErrExpired       = errors.New("settle: compensation expired")
)

// Config is the SLG economy contract. DailyCap is the per-local-day production
// cap from the generic time model; StorageCap is the warehouse limit; Upkeep is
// paid continuously out of stock.
type Config struct {
	ProductionPerHour float64
	UpkeepPerHour     float64
	StorageCap        float64
	DailyCap          float64
	MaxWindow         time.Duration
	Location          *time.Location
	Version           int
}

type Result struct {
	PlayerID  string
	From      time.Time
	To        time.Time
	Gross     float64
	Upkeep    float64
	Stored    float64
	Overflow  float64
	Days      int
	Capped    bool
	Truncated bool
	Key       string
}

// Settle replays one settlement window. The caller must pass server-recorded
// lastSettled and a server time; client clocks are never an input. A retry must
// replay the same (from, to) pair, which is what makes the key stable.
func Settle(playerID string, lastSettled, now time.Time, stock float64, cfg Config) (Result, error) {
	if playerID == "" || cfg.ProductionPerHour < 0 || cfg.UpkeepPerHour < 0 ||
		cfg.DailyCap <= 0 || cfg.StorageCap <= 0 || cfg.MaxWindow < 0 {
		return Result{}, ErrInvalidConfig
	}
	if now.Before(lastSettled) {
		return Result{}, ErrClockRollback
	}
	loc := cfg.Location
	if loc == nil {
		loc = time.UTC
	}
	from := lastSettled
	truncated := false
	if cfg.MaxWindow > 0 && now.Sub(from) > cfg.MaxWindow {
		from = now.Add(-cfg.MaxWindow)
		truncated = true
	}

	acc := offline.AccrueInZone(from, now, cfg.ProductionPerHour, cfg.DailyCap, loc)
	upkeep := cfg.UpkeepPerHour * now.Sub(from).Hours()
	stored := stock + acc.Amount - upkeep
	overflow := 0.0
	if stored < 0 {
		stored = 0
	}
	if stored > cfg.StorageCap {
		overflow = stored - cfg.StorageCap
		stored = cfg.StorageCap
	}

	return Result{
		PlayerID:  playerID,
		From:      from,
		To:        now,
		Gross:     acc.Amount,
		Upkeep:    upkeep,
		Stored:    stored,
		Overflow:  overflow,
		Days:      acc.Days,
		Capped:    acc.Capped,
		Truncated: truncated,
		Key:       key(playerID, from, now, cfg, loc),
	}, nil
}

// key covers the window, the economy contract and the timezone. It deliberately
// does not include stock: after a successful write the client may retry with
// the old lastSettled, and the stock has already changed.
func key(playerID string, from, to time.Time, cfg Config, loc *time.Location) string {
	raw := fmt.Sprintf("%s|%d|%d|%.4f|%.4f|%.4f|%.4f|%d|%s",
		playerID, from.UnixNano(), to.UnixNano(),
		cfg.ProductionPerHour, cfg.UpkeepPerHour,
		cfg.StorageCap, cfg.DailyCap, cfg.Version, loc.String())
	sum := sha256.Sum256([]byte(raw))
	return hex.EncodeToString(sum[:])
}

// Ledger is the idempotency boundary for one player. It is intentionally not
// concurrency-safe: a player's settlement is serialized by the owning shard.
type Ledger struct {
	applied map[string]Result
	claimed map[string]time.Time
}

func NewLedger() *Ledger {
	return &Ledger{applied: make(map[string]Result), claimed: make(map[string]time.Time)}
}

// Apply returns the first result for a key and applied=false on a replay.
func (l *Ledger) Apply(r Result) (Result, bool) {
	if l.applied == nil {
		l.applied = make(map[string]Result)
	}
	if prev, ok := l.applied[r.Key]; ok {
		return prev, false
	}
	l.applied[r.Key] = r
	return r, true
}

// Compensation is an operator-issued grant such as a maintenance apology. It
// is separate from natural production so the two can be reconciled.
type Compensation struct {
	GrantID   string
	PlayerID  string
	Amount    float64
	ExpiresAt time.Time
}

// Claim grants a compensation once. An expired grant is an error, not a silent
// zero, because the operator needs to see rejected claims.
func (l *Ledger) Claim(c Compensation, now time.Time) (bool, error) {
	if c.GrantID == "" || c.PlayerID == "" || c.Amount <= 0 {
		return false, ErrInvalidGrant
	}
	if !c.ExpiresAt.IsZero() && now.After(c.ExpiresAt) {
		return false, ErrExpired
	}
	if l.claimed == nil {
		l.claimed = make(map[string]time.Time)
	}
	if _, ok := l.claimed[c.GrantID]; ok {
		return false, nil
	}
	l.claimed[c.GrantID] = now
	return true, nil
}

形态 A：客户端重试登录，服务端重新取 now
形态 B：定时任务重跑同一批次，使用批次内固定的 now

$ cd .local/checks/gsarch-lab
$ gofmt -l internal/settle
$ go test -count=1 ./internal/settle/
ok  	gsarchlab/internal/settle	0.649s