《MMO 服务器开发》15.3 红点聚合与离线同步

// file: internal/mail/reddot.go
// tier: L1
// verify: go test ./internal/mail/

package mail

import "sync"

// RedDot aggregates unread counters along a small node tree. Leaves are the
// concrete systems (mail, quest, guild, ...); an intermediate node sums its
// children; the root's count is the single number the client's tab bar shows.
type RedDot struct {
	mu     sync.Mutex
	parent map[string]string
	own    map[string]int
	sum    map[string]int
	root   string
}

// NewRedDot returns a tree with a single root node.
func NewRedDot(root string) *RedDot {
	return &RedDot{
		parent: map[string]string{root: ""},
		own:    map[string]int{root: 0},
		sum:    map[string]int{root: 0},
		root:   root,
	}
}

// Attach registers name as a child of parent. Re-attaching moves the node and
// re-propagates its current own count, so a hot-swapped subtree stays correct.
func (r *RedDot) Attach(name, parent string) {
	r.mu.Lock()
	defer r.mu.Unlock()
	old, existed := r.parent[name]
	if !existed {
		r.own[name] = 0
		r.sum[name] = 0
	} else if old == parent {
		return
	}
	if existed && old != "" {
		r.propagate(old, -r.sum[name])
	}
	r.parent[name] = parent
	r.propagate(parent, r.sum[name])
}

// Bump changes name's own count by delta and returns the new root total. A node
// that would go negative is clamped at zero, so a duplicated "read" report can
// never push the badge below zero.
func (r *RedDot) Bump(name string, delta int) int {
	r.mu.Lock()
	defer r.mu.Unlock()
	if _, ok := r.parent[name]; !ok {
		return r.sum[r.root]
	}
	if r.own[name]+delta < 0 {
		delta = -r.own[name]
	}
	r.own[name] += delta
	r.propagate(name, delta)
	return r.sum[r.root]
}

func (r *RedDot) propagate(name string, delta int) {
	for name != "" {
		r.sum[name] += delta
		name = r.parent[name]
	}
}

// Count returns the aggregated count at name.
func (r *RedDot) Count(name string) int {
	r.mu.Lock()
	defer r.mu.Unlock()
	return r.sum[name]
}

// Unread counts mails the player has not opened yet. It is the leaf value the
// mail system feeds into Bump.
func (mb *Mailbox) Unread() int {
	mb.mu.Lock()
	defer mb.mu.Unlock()
	n := 0
	for _, m := range mb.mails {
		if !m.Read {
			n++
		}
	}
	return n
}

// snippet: internal/mail/sync.go

// Change 是一次邮箱改动，带一个单调递增的版本号。
type Change struct {
	Version uint64
	Op      byte // 'A' 新增, 'R' 已读, 'C' 领取, 'D' 删除
	MailID  MailID
}

// ChangeLog 是最近改动组成的有界环形缓冲。重连的客户端带上它最后看到的版本；
// 该版本仍在环内就回增量，否则客户端必须走全量快照。把环设为有界，正是为了
// 阻止一个长期离线的账号逼服务端重放无限长的历史。
type ChangeLog struct {
	mu      sync.Mutex
	version uint64
	ring    []Change
	head    int
	full    bool
}

// Append 记录一次改动并返回它的版本号。
func (c *ChangeLog) Append(op byte, id MailID) uint64 {
	c.mu.Lock()
	defer c.mu.Unlock()
	c.version++
	c.ring[c.head] = Change{Version: c.version, Op: op, MailID: id}
	c.head = (c.head + 1) % len(c.ring)
	if c.head == 0 {
		c.full = true
	}
	return c.version
}

// Since 返回版本号大于 v 的全部改动，由旧到新。当 v 早于环内现存最旧的一条时
// ok=false：调用方必须退化成全量快照，而不是相信这个（不完整的）增量。
func (c *ChangeLog) Since(v uint64) (out []Change, ok bool) {
	c.mu.Lock()
	defer c.mu.Unlock()
	if v >= c.version {
		return nil, true
	}
	if v+1 < c.oldestLocked() {
		return nil, false
	}
	for _, ch := range c.ring {
		if ch.Version > v {
			out = append(out, ch)
		}
	}
	sort.Slice(out, func(i, j int) bool { return out[i].Version < out[j].Version })
	return out, true
}

// snippet: internal/mail/reddot_test.go（节选）

func TestChangeLogWindowOverflow(t *testing.T) {
	log := NewChangeLog(3)
	for i := 0; i < 5; i++ {
		log.Append('A', MailID(i+1))
	}
	// 版本 1 已经滑出 3 槽环形缓冲（现存最旧是 3），无法给出完整增量。
	if _, ok := log.Since(1); ok {
		t.Fatalf("Since(1) must report the delta as incomplete")
	}
	// 版本 2 需要的 3、4、5 都还在。
	if out, ok := log.Since(2); !ok || len(out) != 3 {
		t.Fatalf("Since(2) = %v, ok=%v; want 3,4,5", out, ok)
	}
}