《游戏服务端架构·核心系统与契约》8.1 好友、黑名单与关系一致性

none --follow--> following
none --request--> pending --accept--> friend
any --block--> blocked
blocked --unblock--> none        # 不恢复 friend/following

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

import (
	"errors"
	"sort"
)

// Kind is the effective relation from one role to another. Blocked always wins,
// even when the opposite direction still stores a follow edge.
type Kind int

const (
	KindNone Kind = iota
	KindFollow
	KindFriend
	KindBlocked
)

func (k Kind) String() string {
	switch k {
	case KindFollow:
		return "follow"
	case KindFriend:
		return "friend"
	case KindBlocked:
		return "blocked"
	default:
		return "none"
	}
}

var (
	ErrEmptyRole = errors.New("relationships: empty role")
	ErrSelf      = errors.New("relationships: self relation")
	ErrBlocked   = errors.New("relationships: blocked pair")
	ErrNoRequest = errors.New("relationships: no pending request")
	ErrNotFriend = errors.New("relationships: not friends")
)

// Store keeps directed edges. Friendship is two directed KindFriend edges and
// is always written as a pair; a block is a directed edge that wins every
// query regardless of direction.
type Store struct {
	edges    map[string]map[string]Kind
	requests map[string]map[string]struct{}
}

// New returns an empty store.
func New() *Store {
	return &Store{
		edges:    make(map[string]map[string]Kind),
		requests: make(map[string]map[string]struct{}),
	}
}

func (s *Store) valid(a, b string) error {
	if a == "" || b == "" {
		return ErrEmptyRole
	}
	if a == b {
		return ErrSelf
	}
	return nil
}

func (s *Store) blocked(a, b string) bool {
	return s.edges[a][b] == KindBlocked || s.edges[b][a] == KindBlocked
}

func (s *Store) set(from, to string, k Kind) {
	m := s.edges[from]
	if m == nil {
		m = make(map[string]Kind)
		s.edges[from] = m
	}
	m[to] = k
}

func (s *Store) del(from, to string) {
	if s.edges[from] == nil {
		return
	}
	delete(s.edges[from], to)
	if len(s.edges[from]) == 0 {
		delete(s.edges, from)
	}
}

func (s *Store) dropRequest(from, to string) {
	delete(s.requests[from], to)
	if len(s.requests[from]) == 0 {
		delete(s.requests, from)
	}
}

// Follow records a one-way follow edge. Any block on either side wins.
func (s *Store) Follow(from, to string) error {
	if err := s.valid(from, to); err != nil {
		return err
	}
	if s.blocked(from, to) {
		return ErrBlocked
	}
	if s.edges[from][to] == KindFriend {
		return nil
	}
	s.set(from, to, KindFollow)
	return nil
}

// RequestFriend stores a pending request. The pair is not friends yet.
func (s *Store) RequestFriend(from, to string) error {
	if err := s.valid(from, to); err != nil {
		return err
	}
	if s.blocked(from, to) {
		return ErrBlocked
	}
	if s.edges[from][to] == KindFriend && s.edges[to][from] == KindFriend {
		return nil
	}
	m := s.requests[from]
	if m == nil {
		m = make(map[string]struct{})
		s.requests[from] = m
	}
	m[to] = struct{}{}
	return nil
}

// AcceptFriend turns a pending request into two friend edges. Both edges are
// written in one in-memory step, so no state exposes a one-sided friendship.
func (s *Store) AcceptFriend(from, to string) error {
	if err := s.valid(from, to); err != nil {
		return err
	}
	if s.blocked(from, to) {
		return ErrBlocked
	}
	if _, ok := s.requests[to][from]; !ok {
		return ErrNoRequest
	}
	s.dropRequest(to, from)
	s.set(from, to, KindFriend)
	s.set(to, from, KindFriend)
	return nil
}

// AddFriend is the direct two-sided path used by GM tools and migrations.
func (s *Store) AddFriend(a, b string) error {
	if err := s.valid(a, b); err != nil {
		return err
	}
	if s.blocked(a, b) {
		return ErrBlocked
	}
	s.set(a, b, KindFriend)
	s.set(b, a, KindFriend)
	return nil
}

// Block records a directed block and removes friendship in both directions.
// Existing follows are removed too; they do not become visible again on unblock.
func (s *Store) Block(blocker, target string) error {
	if err := s.valid(blocker, target); err != nil {
		return err
	}
	if s.edges[blocker][target] != KindBlocked {
		s.del(blocker, target)
	}
	if s.edges[target][blocker] != KindBlocked {
		s.del(target, blocker)
	}
	s.dropRequest(blocker, target)
	s.dropRequest(target, blocker)
	s.set(blocker, target, KindBlocked)
	return nil
}

// Unblock removes the blocker's block edge. A friendship removed by Block is
// not restored; callers must re-add it explicitly.
func (s *Store) Unblock(blocker, target string) error {
	if err := s.valid(blocker, target); err != nil {
		return err
	}
	if s.edges[blocker][target] == KindBlocked {
		s.del(blocker, target)
	}
	return nil
}

// Effective applies precedence: block, then mutual friend, then follow.
func (s *Store) Effective(from, to string) Kind {
	if s.blocked(from, to) {
		return KindBlocked
	}
	if s.edges[from][to] == KindFriend && s.edges[to][from] == KindFriend {
		return KindFriend
	}
	if s.edges[from][to] == KindFollow {
		return KindFollow
	}
	return KindNone
}

// FriendsOf returns the sorted mutual friends of role.
func (s *Store) FriendsOf(role string) []string {
	out := make([]string, 0, 4)
	for other, k := range s.edges[role] {
		if k == KindFriend && s.edges[other][role] == KindFriend {
			out = append(out, other)
		}
	}
	sort.Strings(out)
	return out
}

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