《MMO 服务器开发》13.2 公会仓库与捐献流水

// file: internal/guild/storage.go
// tier: L1
// verify: go test ./internal/guild/ -run 'TestWarehouse|TestLedger|TestStore' -v

package guild

import (
	"errors"
	"time"
)

// ItemID is a config-table item id, not a bag instance id (卷二共享约定).
type ItemID uint32

var (
	ErrBadAmount     = errors.New("amount must be positive")
	ErrWarehouseFull = errors.New("warehouse slot capacity reached")
	ErrNotEnoughItem = errors.New("not enough items in warehouse")
	ErrWithdrawLimit = errors.New("daily withdraw limit reached")
)

// Warehouse is a guild-shared item store keyed by config item id. capacity caps
// the number of distinct item types, not the total count: stacking a million
// potions in one slot costs one slot.
type Warehouse struct {
	slots    map[ItemID]int64
	capacity int
}

func NewWarehouse(capacity int) *Warehouse {
	if capacity <= 0 {
		capacity = 100
	}
	return &Warehouse{slots: make(map[ItemID]int64), capacity: capacity}
}

// Deposit adds count of item id. It fails only when a brand-new type would exceed
// the slot capacity; stacking onto an existing slot never does.
func (w *Warehouse) Deposit(id ItemID, count int64) error {
	if count <= 0 {
		return ErrBadAmount
	}
	cur, ok := w.slots[id]
	if !ok && len(w.slots) >= w.capacity {
		return ErrWarehouseFull
	}
	w.slots[id] = cur + count
	return nil
}

// Withdraw removes count of item id, reporting ErrNotEnoughItem instead of going
// negative. Empty slots are deleted so the type count is accurate.
func (w *Warehouse) Withdraw(id ItemID, count int64) error {
	if count <= 0 {
		return ErrBadAmount
	}
	cur, ok := w.slots[id]
	if !ok || cur < count {
		return ErrNotEnoughItem
	}
	if cur == count {
		delete(w.slots, id)
	} else {
		w.slots[id] = cur - count
	}
	return nil
}

func (w *Warehouse) Count(id ItemID) int64 { return w.slots[id] }
func (w *Warehouse) Types() int            { return len(w.slots) }

// DonationEntry is one append-only donation record. Seq is monotonic and is the
// id the client uses to paginate the ledger.
type DonationEntry struct {
	Seq      uint64
	PlayerID PlayerID
	ItemID   ItemID
	Count    int64
	Gold     int64
	At       time.Time
}

// Ledger records donations idempotently. The same request id never produces two
// entries, so a client retry cannot double a member's contribution.
type Ledger struct {
	entries []DonationEntry
	seq     uint64
	byReq   map[uint64]uint64   // requestID -> Seq
	total   map[PlayerID]uint64 // 累计贡献点
}

func NewLedger() *Ledger {
	return &Ledger{byReq: make(map[uint64]uint64), total: make(map[PlayerID]uint64)}
}

// Donate appends a donation for reqID. If reqID was seen before, it returns the
// original entry with dup=true and changes nothing. Contribution points are
// item count + gold; the weighting is a placeholder for the economy table.
func (l *Ledger) Donate(reqID uint64, p PlayerID, item ItemID, count, gold int64, at time.Time) (DonationEntry, bool, error) {
	if count < 0 || gold < 0 || (count == 0 && gold == 0) {
		return DonationEntry{}, false, ErrBadAmount
	}
	if seq, ok := l.byReq[reqID]; ok {
		return l.entries[seq-1], true, nil
	}
	l.seq++
	e := DonationEntry{Seq: l.seq, PlayerID: p, ItemID: item, Count: count, Gold: gold, At: at}
	l.entries = append(l.entries, e)
	l.byReq[reqID] = e.Seq
	l.total[p] += uint64(count) + uint64(gold)
	return e, false, nil
}

func (l *Ledger) Contribution(p PlayerID) uint64 { return l.total[p] }
func (l *Ledger) Len() int                       { return len(l.entries) }

// Entries returns a copy so callers cannot mutate the ledger's backing array.
func (l *Ledger) Entries() []DonationEntry {
	out := make([]DonationEntry, len(l.entries))
	copy(out, l.entries)
	return out
}

// GuildStore wires a warehouse and a ledger to a roster so permission checks,
// idempotency and daily limits all live in one place. The ordering inside each
// method is deliberate and load-bearing.
type GuildStore struct {
	guild     *Guild
	wh        *Warehouse
	ledger    *Ledger
	dailyCap  int64
	withdrawn map[PlayerID]int64 // 今日已提数量
}

func NewGuildStore(g *Guild, wh *Warehouse, dailyWithdrawCap int64) *GuildStore {
	return &GuildStore{guild: g, wh: wh, ledger: NewLedger(), dailyCap: dailyWithdrawCap, withdrawn: make(map[PlayerID]int64)}
}

// Deposit puts items into the shared warehouse and records the donation in the
// same call. The idempotency check comes FIRST: if it ran after the stock write,
// a retry would add the items twice before noticing the duplicate.
func (s *GuildStore) Deposit(actor PlayerID, reqID uint64, item ItemID, count int64, at time.Time) (DonationEntry, bool, error) {
	if !s.guild.can(actor, PermStorageDeposit) {
		return DonationEntry{}, false, ErrPermissionDenied
	}
	if seq, ok := s.ledger.byReq[reqID]; ok {
		return s.ledger.entries[seq-1], true, nil
	}
	if err := s.wh.Deposit(item, count); err != nil {
		return DonationEntry{}, false, err
	}
	return s.ledger.Donate(reqID, actor, item, count, 0, at)
}

// Withdraw lets a permitted member take items out, capped per player per day.
// The cap is checked before the stock write so a rejected withdraw leaves the
// warehouse untouched.
func (s *GuildStore) Withdraw(actor PlayerID, item ItemID, count int64) error {
	if !s.guild.can(actor, PermStorageWithdraw) {
		return ErrPermissionDenied
	}
	if count <= 0 {
		return ErrBadAmount
	}
	if s.dailyCap > 0 && s.withdrawn[actor]+count > s.dailyCap {
		return ErrWithdrawLimit
	}
	if err := s.wh.Withdraw(item, count); err != nil {
		return err
	}
	s.withdrawn[actor] += count
	return nil
}

// ResetDaily clears the per-player withdraw counters. The scheduler that calls it
// at the 04:00 boundary is the topic of 10.3.
func (s *GuildStore) ResetDaily() { clear(s.withdrawn) }

// snippet: internal/guild/storage_test.go（节选）

func TestStoreDepositThenWithdraw(t *testing.T) {
	g := NewGuild(1, "g", 100, "leader", JoinOpen, 10, base)
	g.RequestJoin(101, "m", base)
	s := NewGuildStore(g, NewWarehouse(10), 50)

	// A plain member may deposit but not withdraw.
	if _, _, err := s.Deposit(101, 1, 7, 100, base); err != nil {
		t.Fatalf("member deposit: %v", err)
	}
	if err := s.Withdraw(101, 7, 1); !errors.Is(err, ErrPermissionDenied) {
		t.Fatalf("member withdraw: want ErrPermissionDenied, got %v", err)
	}
	if err := g.SetRank(100, 101, RankOfficer); err != nil {
		t.Fatalf("promote: %v", err)
	}
	if err := s.Withdraw(101, 7, 30); err != nil {
		t.Fatalf("officer withdraw 30: %v", err)
	}
	if err := s.Withdraw(101, 7, 30); !errors.Is(err, ErrWithdrawLimit) {
		t.Fatalf("second withdraw: want ErrWithdrawLimit, got %v", err)
	}
	s.ResetDaily()
	if err := s.Withdraw(101, 7, 30); err != nil {
		t.Fatalf("after reset: %v", err)
	}
}

func TestStoreRetriedDepositAddsStockOnce(t *testing.T) {
	g := NewGuild(1, "g", 100, "leader", JoinOpen, 10, base)
	s := NewGuildStore(g, NewWarehouse(10), 0)
	if _, _, err := s.Deposit(100, 9, 3, 4, base); err != nil {
		t.Fatalf("deposit: %v", err)
	}
	if _, dup, err := s.Deposit(100, 9, 3, 4, base); err != nil || !dup {
		t.Fatalf("retry deposit: dup=%v err=%v", dup, err)
	}
	if got := s.wh.Count(3); got != 4 {
		t.Fatalf("stock = %d, want 4 (added once)", got)
	}
}