《游戏服务端编程实践》9.1.3 背包扩展与持久化

// file: ch09/bag/persist.go
// tier: L1
// verify: go test ./ch09/bag/

package bag

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

const SnapshotVersion = 2

var ErrBadSnapshot = errors.New("bag: bad snapshot")

// SnapshotSlot 只记录非空槽位。Slot 是绝对槽位号，恢复时保持不变，
// 避免客户端缓存的槽位引用在加载后错位。
type SnapshotSlot struct {
	Slot       int    `json:"slot"`
	InstanceID uint64 `json:"instance_id"`
	ItemID     string `json:"item_id"`
	Count      int    `json:"count"`
	Bound      bool   `json:"bound,omitempty"`
	ExpireUnix int64  `json:"expire_unix,omitempty"`
}

type Snapshot struct {
	Version  int            `json:"version"`
	Capacity int            `json:"capacity"`
	NextID   uint64         `json:"next_id"`
	Slots    []SnapshotSlot `json:"slots"`
}

// Repair 记录恢复时做过的每一处修复，禁止静默丢物品。
type Repair struct {
	Slot       int
	InstanceID uint64
	ItemID     string
	Reason     string
	Lost       int
}

type RestoreReport struct {
	MigratedFrom int
	Repairs      []Repair
}

func (r RestoreReport) LostTotal() int {
	total := 0
	for _, rep := range r.Repairs {
		total += rep.Lost
	}
	return total
}

func (b *Bag) Snapshot() Snapshot {
	snap := Snapshot{Version: SnapshotVersion, Capacity: len(b.slots), NextID: b.nextID}
	for i, it := range b.slots {
		if it == nil {
			continue
		}
		s := SnapshotSlot{
			Slot:       i,
			InstanceID: it.InstanceID,
			ItemID:     it.ItemID,
			Count:      it.Count,
			Bound:      it.Bound,
		}
		if !it.ExpireAt.IsZero() {
			s.ExpireUnix = it.ExpireAt.Unix()
		}
		snap.Slots = append(snap.Slots, s)
	}
	sort.Slice(snap.Slots, func(i, j int) bool { return snap.Slots[i].Slot < snap.Slots[j].Slot })
	return snap
}

// Restore 从快照重建背包，并对损坏数据做可审计修复：
// 未知物品、非法数量直接丢弃；超堆叠截断；槽位冲突迁到空槽；
// 重复 instanceID 重新分配。每处修复都写入 report。
func Restore(defs []ItemDef, snap Snapshot) (*Bag, RestoreReport, error) {
	var report RestoreReport
	if snap.Version < 1 || snap.Version > SnapshotVersion {
		return nil, report, fmt.Errorf("%w: version %d", ErrBadSnapshot, snap.Version)
	}

	capacity := snap.Capacity
	if snap.Version == 1 && capacity <= 0 {
		for _, s := range snap.Slots {
			if s.Slot >= capacity {
				capacity = s.Slot + 1
			}
		}
		report.MigratedFrom = 1
	}
	if capacity <= 0 {
		return nil, report, fmt.Errorf("%w: capacity %d", ErrBadSnapshot, capacity)
	}
	b, err := NewBag(defs, capacity)
	if err != nil {
		return nil, report, err
	}

	maxID := snap.NextID
	for _, s := range snap.Slots {
		if s.InstanceID > maxID {
			maxID = s.InstanceID
		}
	}
	b.nextID = maxID
	seen := make(map[uint64]bool, len(snap.Slots))

	for _, s := range snap.Slots {
		def, ok := b.defs[s.ItemID]
		if !ok {
			report.Repairs = append(report.Repairs, Repair{
				Slot: s.Slot, InstanceID: s.InstanceID, ItemID: s.ItemID,
				Reason: "unknown_item", Lost: s.Count,
			})
			continue
		}
		if s.Count <= 0 {
			report.Repairs = append(report.Repairs, Repair{
				Slot: s.Slot, InstanceID: s.InstanceID, ItemID: s.ItemID,
				Reason: "invalid_count", Lost: max(s.Count, 0),
			})
			continue
		}

		count := s.Count
		if count > def.MaxStack {
			report.Repairs = append(report.Repairs, Repair{
				Slot: s.Slot, InstanceID: s.InstanceID, ItemID: s.ItemID,
				Reason: "overstack", Lost: count - def.MaxStack,
			})
			count = def.MaxStack
		}

		target := s.Slot
		if target < 0 || target >= capacity || b.slots[target] != nil {
			target = b.firstEmpty()
			if target < 0 {
				report.Repairs = append(report.Repairs, Repair{
					Slot: s.Slot, InstanceID: s.InstanceID, ItemID: s.ItemID,
					Reason: "no_space", Lost: count,
				})
				continue
			}
			report.Repairs = append(report.Repairs, Repair{
				Slot: s.Slot, InstanceID: s.InstanceID, ItemID: s.ItemID,
				Reason: "slot_conflict",
			})
		}

		id := s.InstanceID
		if id == 0 || seen[id] {
			b.nextID++
			id = b.nextID
			report.Repairs = append(report.Repairs, Repair{
				Slot: s.Slot, InstanceID: s.InstanceID, ItemID: s.ItemID,
				Reason: "duplicate_instance_id",
			})
		}
		seen[id] = true

		var expire time.Time
		if s.ExpireUnix > 0 {
			expire = time.Unix(s.ExpireUnix, 0)
		}
		b.slots[target] = &Item{
			InstanceID: id,
			ItemID:     s.ItemID,
			Count:      count,
			Bound:      s.Bound,
			ExpireAt:   expire,
		}
	}
	return b, report, nil
}

// Expand 只允许扩大容量；旧槽位索引与物品保持不变。
func (b *Bag) Expand(capacity int) error {
	if capacity <= len(b.slots) {
		return fmt.Errorf("%w: shrink %d -> %d", ErrBadCapacity, len(b.slots), capacity)
	}
	grown := make([]*Item, capacity)
	copy(grown, b.slots)
	b.slots = grown
	return nil
}