《游戏服务端架构·核心系统与契约》8.2 公会、权限与仓库

Begin ──► Ticket{role, epoch, version}
   │            │
   │            ├─ role changed ──► ErrStale
   │            ├─ vault moved  ──► ErrStale
   │            └─ ok ───────────► Commit: stock ± delta, version++
   └─ closed ─────────────────────► ErrClosed

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

import (
	"errors"
	"sync"
)

// Role is ordered from least to most privileged.
type Role int

const (
	RoleNone Role = iota
	RoleMember
	RoleOfficer
	RoleLeader
)

func (r Role) String() string {
	switch r {
	case RoleMember:
		return "member"
	case RoleOfficer:
		return "officer"
	case RoleLeader:
		return "leader"
	default:
		return "none"
	}
}

// Perm is a permission bit. Roles receive the smallest set they need: members
// may deposit, officers may also withdraw and manage people, the leader alone
// may disband.
type Perm uint32

const (
	PermDeposit Perm = 1 << iota
	PermWithdraw
	PermInvite
	PermKick
	PermDisband
)

var roleGrants = map[Role]Perm{
	RoleMember:  PermDeposit,
	RoleOfficer: PermDeposit | PermWithdraw | PermInvite | PermKick,
	RoleLeader:  PermDeposit | PermWithdraw | PermInvite | PermKick | PermDisband,
}

// Can reports whether the role holds every bit in p.
func (r Role) Can(p Perm) bool { return roleGrants[r]&p == p }

var (
	ErrEmpty      = errors.New("guildvault: empty guild id or role")
	ErrClosed     = errors.New("guildvault: guild is closed")
	ErrNotMember  = errors.New("guildvault: actor is not a member")
	ErrForbidden  = errors.New("guildvault: permission denied")
	ErrStale      = errors.New("guildvault: ticket is stale")
	ErrStock      = errors.New("guildvault: insufficient stock")
	ErrAmount     = errors.New("guildvault: amount must be non-zero")
	ErrItem       = errors.New("guildvault: empty item")
	ErrExists     = errors.New("guildvault: target is already a member")
	ErrLastLeader = errors.New("guildvault: cannot demote the leader")
)

// Ticket captures the permission epoch and vault version observed by Begin.
// Commit refuses the movement if either moved, so a role change or a competing
// vault operation cannot be applied against a stale decision.
type Ticket struct {
	Actor string
	Role  Role
	Epoch uint64
	Seen  uint64
}

// Guild is an in-memory aggregate. The mutex protects the maps; the ticket is
// the cross-RPC optimistic check, not a replacement for it.
type Guild struct {
	mu      sync.Mutex
	id      string
	closed  bool
	version uint64
	members map[string]Role
	epochs  map[string]uint64
	vault   map[string]int64
}

// New creates a guild whose only member is the leader.
func New(id, leader string) (*Guild, error) {
	if id == "" || leader == "" {
		return nil, ErrEmpty
	}
	return &Guild{
		id:      id,
		members: map[string]Role{leader: RoleLeader},
		epochs:  map[string]uint64{leader: 1},
		vault:   make(map[string]int64),
	}, nil
}

// Join adds a member. Officers and the leader may invite; the new member gets
// the least privileged role.
func (g *Guild) Join(actor, target string) error {
	g.mu.Lock()
	defer g.mu.Unlock()
	if g.closed {
		return ErrClosed
	}
	if !g.members[actor].Can(PermInvite) {
		return ErrForbidden
	}
	if target == "" {
		return ErrEmpty
	}
	if _, ok := g.members[target]; ok {
		return ErrExists
	}
	g.members[target] = RoleMember
	g.epochs[target] = 1
	return nil
}

// SetRole demotes or promotes an existing member. Only the leader may call it;
// changing the leader itself needs Transfer. Every change bumps the target's
// permission epoch, which invalidates tickets already handed out.
func (g *Guild) SetRole(actor, target string, role Role) error {
	g.mu.Lock()
	defer g.mu.Unlock()
	if g.closed {
		return ErrClosed
	}
	if g.members[actor] != RoleLeader {
		return ErrForbidden
	}
	current, ok := g.members[target]
	if !ok {
		return ErrNotMember
	}
	if current == RoleLeader {
		return ErrLastLeader
	}
	if role != RoleMember && role != RoleOfficer {
		return ErrForbidden
	}
	if current == role {
		return nil
	}
	g.members[target] = role
	g.epochs[target]++
	return nil
}

// Begin snapshots the caller's role, permission epoch and the vault version.
func (g *Guild) Begin(actor string) (Ticket, error) {
	g.mu.Lock()
	defer g.mu.Unlock()
	if g.closed {
		return Ticket{}, ErrClosed
	}
	role, ok := g.members[actor]
	if !ok {
		return Ticket{}, ErrNotMember
	}
	return Ticket{Actor: actor, Role: role, Epoch: g.epochs[actor], Seen: g.version}, nil
}

// Commit applies a signed movement: positive deposits, negative withdraws.
// It revalidates every fact the caller relied on before doing any work.
func (g *Guild) Commit(t Ticket, item string, delta int64) error {
	g.mu.Lock()
	defer g.mu.Unlock()
	if g.closed {
		return ErrClosed
	}
	if item == "" {
		return ErrItem
	}
	if delta == 0 {
		return ErrAmount
	}
	role, ok := g.members[t.Actor]
	if !ok {
		return ErrNotMember
	}
	if role != t.Role || g.epochs[t.Actor] != t.Epoch {
		return ErrStale
	}
	if g.version != t.Seen {
		return ErrStale
	}
	if delta > 0 && !role.Can(PermDeposit) {
		return ErrForbidden
	}
	if delta < 0 && !role.Can(PermWithdraw) {
		return ErrForbidden
	}
	next := g.vault[item] + delta
	if next < 0 {
		return ErrStock
	}
	if next == 0 {
		delete(g.vault, item)
	} else {
		g.vault[item] = next
	}
	g.version++
	return nil
}

// Stock returns the current amount of one item.
func (g *Guild) Stock(item string) int64 {
	g.mu.Lock()
	defer g.mu.Unlock()
	return g.vault[item]
}

// Snapshot returns a copy of the vault for reporting.
func (g *Guild) Snapshot() map[string]int64 {
	g.mu.Lock()
	defer g.mu.Unlock()
	out := make(map[string]int64, len(g.vault))
	for item, qty := range g.vault {
		out[item] = qty
	}
	return out
}

// Closed reports whether the guild has been disbanded.
func (g *Guild) Closed() bool {
	g.mu.Lock()
	defer g.mu.Unlock()
	return g.closed
}

$ cd .local/checks/gsarch-lab
$ gofmt -l internal/guildvault
$ go vet ./internal/guildvault/...
$ go test -count=1 ./internal/guildvault/
ok  	gsarchlab/internal/guildvault