《MMO 服务器开发》10.3 每日重置与时区窗口

 游戏时区 +08:00，重置点 05:00

 ...── 04:59 ──┤ 05:00 ├── 12:00 ── 23:00 ── 04:59 ──┤ 05:00 ├── ...
      └─────────── 日键 = N ────────────┘  └──── 日键 = N+1 ────┘
                     ▲ 重置在这里发生，且只发生一次

// file: internal/quest/reset.go
// tier: L1
// verify: go test ./internal/quest/

package quest

import "time"

// ResetSchedule describes when daily and weekly quests roll over. The roll is
// anchored to a *fixed* UTC offset and a fixed time-of-day, never to the host's
// local zone: every process in the fleet must flip at the same instant no matter
// where the box sits, otherwise two shards disagree about which day it is and a
// player can claim yesterday's dailies twice by hopping servers.
type ResetSchedule struct {
	Offset  time.Duration // fixed UTC offset, e.g. 8h for a CN-region realm
	DailyAt time.Duration // time-of-day for the daily roll, e.g. 5h = 05:00
	Weekday time.Weekday  // day the weekly roll lands on, e.g. time.Monday
}

// CNRegion is the default realm schedule: reset at 05:00, offset +08:00. 05:00
// is chosen over midnight so the "yesterday" a player sees at 01:00 still counts
// as the same day.
func CNRegion() ResetSchedule {
	return ResetSchedule{Offset: 8 * time.Hour, DailyAt: 5 * time.Hour, Weekday: time.Monday}
}

// DailyKey returns an integer that increments exactly once per daily boundary.
// Two instants share a key iff they fall in the same daily window, so a reset is
// just "the key changed" — no arithmetic on the wall clock is needed at the call
// site, and a duplicated tick cannot fire it twice.
func (s ResetSchedule) DailyKey(t time.Time) int64 {
	shifted := t.UTC().Add(s.Offset - s.DailyAt)
	return floorDiv(shifted.Unix(), 86400)
}

// WeeklyKey is the same idea one level up: the key increments when the schedule's
// weekday boundary is crossed.
func (s ResetSchedule) WeeklyKey(t time.Time) int64 {
	shifted := t.UTC().Add(s.Offset - s.DailyAt)
	day := floorDiv(shifted.Unix(), 86400)
	// shifted is a UTC-labelled instant, so its weekday is the realm-local one.
	delta := (int(shifted.Weekday()) - int(s.Weekday) + 7) % 7
	return floorDiv(day-int64(delta), 7)
}

// TimeToNextDaily returns how long until the next daily boundary, in (0, 24h].
// This is the number the client shows as "dailies reset in 3h 12m". It is a
// duration, not an instant, so it survives the client's clock being wrong.
func (s ResetSchedule) TimeToNextDaily(t time.Time) time.Duration {
	shifted := t.UTC().Add(s.Offset - s.DailyAt)
	sec := shifted.Unix()
	next := (floorDiv(sec, 86400) + 1) * 86400
	return time.Duration(next-sec) * time.Second
}

// Tracker watches a schedule and fires callbacks exactly once per boundary
// crossing. It stores only the last observed keys, so a backward wall-clock step
// (an NTP correction) cannot re-fire a reset that already happened: the key would
// have to *change*, and moving the clock back to a previous day is absorbed as
// "still the same window". The monotonic gameplay timeline from vol-1 14.1
// supplies elapsed time for combat and buffs; this tracker is the one place that
// deliberately reads the calendar, and it reads it in a key-compare, not a
// subtract, so a stepping clock is harmless.
type Tracker struct {
	sched  ResetSchedule
	day    int64
	week   int64
	primed bool
}

// NewTracker builds a tracker already primed at t, so the first Tick after
// startup does not fire a spurious reset.
func NewTracker(s ResetSchedule, t time.Time) *Tracker {
	return &Tracker{sched: s, day: s.DailyKey(t), week: s.WeeklyKey(t), primed: true}
}

// Tick compares the current keys against the last ones and reports which
// boundaries were crossed. Call it on every world tick; crossing two days at once
// (a server that was paused) is reported as a single daily event. Only *forward*
// key movement fires: a backward wall-clock step (an NTP correction) leaves the
// last key untouched, so when the clock comes back the boundary does not re-fire.
func (t *Tracker) Tick(now time.Time) (daily, weekly bool) {
	d := t.sched.DailyKey(now)
	w := t.sched.WeeklyKey(now)
	if !t.primed {
		t.day, t.week, t.primed = d, w, true
		return false, false
	}
	if d > t.day {
		daily = true
		t.day = d
	}
	if w > t.week {
		weekly = true
		t.week = w
	}
	return daily, weekly
}

// floorDiv is integer division that rounds toward negative infinity, matching
// the way calendar days are counted before the Unix epoch.
func floorDiv(a, b int64) int64 {
	q := a / b
	if a%b != 0 && (a < 0) != (b < 0) {
		q--
	}
	return q
}

// snippet: 每日状态以日键为版本，跨天自动失效

type DailyState struct {
	Key  int64            // the DailyKey this state belongs to
	Done map[QuestID]bool // dailies already claimed in this window
}

// ResetIfStale returns true and clears the state when the day has turned over.
func (d *DailyState) ResetIfStale(key int64) bool {
	if d.Key == key {
		return false
	}
	d.Key = key
	d.Done = map[QuestID]bool{}
	return true
}

// snippet: internal/quest/reset_test.go（节选）

func TestTrackerFiresOncePerBoundary(t *testing.T) {
	tr := NewTracker(CNRegion(), at(2026, 10, 8, 4, 59))

	if d, w := tr.Tick(at(2026, 10, 8, 4, 59)); d || w {
		t.Fatalf("same window fired: daily=%v weekly=%v", d, w)
	}
	if d, w := tr.Tick(at(2026, 10, 8, 5, 0)); !d || w {
		t.Fatalf("05:00 daily=%v weekly=%v, want daily only", d, w)
	}
	if d, _ := tr.Tick(at(2026, 10, 8, 5, 0)); d {
		t.Fatal("same boundary fired twice")
	}
	// Backward NTP step must not re-arm the boundary.
	if d, _ := tr.Tick(at(2026, 10, 8, 4, 0)); d {
		t.Fatal("backward clock step re-fired the daily reset")
	}
	if d, _ := tr.Tick(at(2026, 10, 8, 5, 0)); d {
		t.Fatal("clock recovery re-fired the daily reset")
	}
}