《游戏服务端架构·核心系统与契约》7.3 每日重置、时区与赛季

last=2026-10-26, now=2026-10-29 12:00, limit=2
-> [10-27, 10-28], truncated=true

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

import (
	"errors"
	"fmt"
	"time"
)

// Policy is one reset rule. A policy has exactly one location: mixing the
// server's local time with UTC is how a reset lands on the wrong day.
type Policy struct {
	Location *time.Location
	Hour     int
	Minute   int
}

var (
	ErrNoLocation    = errors.New("dailyreset: nil location")
	ErrBadClock      = errors.New("dailyreset: hour/minute out of range")
	ErrBadKey        = errors.New("dailyreset: bad window key")
	ErrBadLimit      = errors.New("dailyreset: limit must be positive")
	ErrEmptyKey      = errors.New("dailyreset: empty key")
	ErrBadSeason     = errors.New("dailyreset: invalid season")
	ErrNotContiguous = errors.New("dailyreset: seasons are not contiguous")
)

func (p Policy) validate() error {
	if p.Location == nil {
		return ErrNoLocation
	}
	if p.Hour < 0 || p.Hour > 23 || p.Minute < 0 || p.Minute > 59 {
		return ErrBadClock
	}
	return nil
}

// Window is a half-open interval [Start, End) with a date key in the policy's
// location. The key is the idempotency key of the reset job.
type Window struct {
	Key   string
	Start time.Time
	End   time.Time
}

func (w Window) Contains(t time.Time) bool {
	return !t.Before(w.Start) && t.Before(w.End)
}

func windowForDate(p Policy, year int, month time.Month, day int) Window {
	start := time.Date(year, month, day, p.Hour, p.Minute, 0, 0, p.Location)
	end := time.Date(year, month, day+1, p.Hour, p.Minute, 0, 0, p.Location)
	return Window{Key: start.Format("2006-01-02"), Start: start, End: end}
}

// WindowAt returns the window containing t. The comparison is done on local
// wall time, so a player at 04:59 belongs to the previous day's window when
// the reset hour is 05:00.
func WindowAt(p Policy, t time.Time) (Window, error) {
	if err := p.validate(); err != nil {
		return Window{}, err
	}
	local := t.In(p.Location)
	w := windowForDate(p, local.Year(), local.Month(), local.Day())
	if local.Before(w.Start) {
		w = windowForDate(p, local.Year(), local.Month(), local.Day()-1)
	}
	return w, nil
}

// CatchUp lists the windows after last up to the one containing now. A capped
// result reports truncation instead of silently skipping the remaining days.
func CatchUp(p Policy, last string, now time.Time, limit int) ([]Window, bool, error) {
	if limit <= 0 {
		return nil, false, ErrBadLimit
	}
	if err := p.validate(); err != nil {
		return nil, false, err
	}
	current, err := WindowAt(p, now)
	if err != nil {
		return nil, false, err
	}
	if last == "" {
		return []Window{current}, false, nil
	}
	day, err := time.ParseInLocation("2006-01-02", last, p.Location)
	if err != nil {
		return nil, false, fmt.Errorf("%w: %q", ErrBadKey, last)
	}
	var out []Window
	for offset := 1; ; offset++ {
		w := windowForDate(p, day.Year(), day.Month(), day.Day()+offset)
		if w.Start.After(current.Start) {
			break
		}
		out = append(out, w)
		if len(out) == limit {
			next := windowForDate(p, day.Year(), day.Month(), day.Day()+offset+1)
			return out, !next.Start.After(current.Start), nil
		}
	}
	return out, false, nil
}

// Ledger records completed reset keys. Execute runs fn at most once per key.
// fn must still be idempotent: a crash between its side effect and the ledger
// write makes the next retry run it again.
type Ledger struct {
	done map[string]bool
}

func NewLedger() *Ledger {
	return &Ledger{done: map[string]bool{}}
}

func (l *Ledger) Execute(key string, fn func() error) (bool, error) {
	if key == "" {
		return false, ErrEmptyKey
	}
	if l.done[key] {
		return false, nil
	}
	if err := fn(); err != nil {
		return false, err
	}
	l.done[key] = true
	return true, nil
}

func (l *Ledger) Done(key string) bool {
	return l.done[key]
}

type Season struct {
	ID    string
	Start time.Time
	End   time.Time
}

func (s Season) Contains(t time.Time) bool {
	return !t.Before(s.Start) && t.Before(s.End)
}

// SeasonTable requires ordered, contiguous seasons. A gap would leave players
// with no active season; an overlap would let two ranks claim the same time.
type SeasonTable struct {
	seasons []Season
}

func NewSeasonTable(seasons []Season) (*SeasonTable, error) {
	for i, s := range seasons {
		if s.ID == "" || !s.Start.Before(s.End) {
			return nil, fmt.Errorf("%w: %q", ErrBadSeason, s.ID)
		}
		if i > 0 && !seasons[i-1].End.Equal(s.Start) {
			return nil, fmt.Errorf("%w: %q ends at %s, %q starts at %s", ErrNotContiguous, seasons[i-1].ID, seasons[i-1].End, s.ID, s.Start)
		}
	}
	return &SeasonTable{seasons: append([]Season(nil), seasons...)}, nil
}

func (t *SeasonTable) At(at time.Time) (Season, bool) {
	for _, s := range t.seasons {
		if s.Contains(at) {
			return s, true
		}
	}
	return Season{}, false
}

func (t *SeasonTable) byID(id string) (Season, bool) {
	for _, s := range t.seasons {
		if s.ID == id {
			return s, true
		}
	}
	return Season{}, false
}

type Reward struct {
	PlayerID string
	Amount   int64
	Claimed  bool
}

// Settlement is the result of closing one season pair. Carry holds unclaimed
// rewards keyed by player; the caller delivers them with an explicit expiry.
type Settlement struct {
	From  string
	To    string
	Carry map[string]int64
	Total int64
}

func Settle(table *SeasonTable, fromID, toID string, rewards []Reward) (Settlement, error) {
	if table == nil {
		return Settlement{}, ErrBadSeason
	}
	from, ok := table.byID(fromID)
	if !ok {
		return Settlement{}, fmt.Errorf("%w: %q", ErrBadSeason, fromID)
	}
	to, ok := table.byID(toID)
	if !ok {
		return Settlement{}, fmt.Errorf("%w: %q", ErrBadSeason, toID)
	}
	if !from.End.Equal(to.Start) {
		return Settlement{}, fmt.Errorf("%w: %q -> %q", ErrNotContiguous, fromID, toID)
	}
	out := Settlement{From: fromID, To: toID, Carry: map[string]int64{}}
	for _, r := range rewards {
		if r.PlayerID == "" || r.Amount < 0 {
			return Settlement{}, fmt.Errorf("%w: reward %q amount %d", ErrBadSeason, r.PlayerID, r.Amount)
		}
		if r.Claimed {
			continue
		}
		out.Carry[r.PlayerID] += r.Amount
		out.Total += r.Amount
	}
	return out, nil
}