《MMO 服务器开发》11.1 频道模型与权限

// file: internal/chat/channel.go
// tier: L1
// verify: go test ./internal/chat/

package chat

import (
	"errors"
	"sort"
)

// 卷二共享的内部类型。本章自包含，命名与全卷约定保持一致。
type (
	PlayerID   uint64
	InstanceID uint64
	PartyID    uint64
	GuildID    uint64
)

// ChannelKind 是聊天频道的类型。前五个可由玩家发起，最后一个只允许服务端发。
type ChannelKind uint8

const (
	ChanWorld   ChannelKind = iota // 世界：全服可见
	ChanLocal                      // 当前：同一地图实例内
	ChanParty                      // 队伍
	ChanGuild                      // 公会
	ChanPrivate                    // 私聊
	ChanSystem                     // 系统公告：仅服务端可发
)

func (k ChannelKind) String() string {
	switch k {
	case ChanWorld:
		return "world"
	case ChanLocal:
		return "local"
	case ChanParty:
		return "party"
	case ChanGuild:
		return "guild"
	case ChanPrivate:
		return "private"
	case ChanSystem:
		return "system"
	}
	return "unknown"
}

var (
	ErrBadChannel    = errors.New("chat: unknown channel kind")
	ErrUnknownPlayer = errors.New("chat: speaker is not in the world")
	ErrNoSuchTarget  = errors.New("chat: private target does not exist")
	ErrNotInParty    = errors.New("chat: speaker has no party")
	ErrNotInGuild    = errors.New("chat: speaker has no guild")
)

// World 是投递所需的最小世界视图：谁在哪、谁和谁同队同会。
// 真实服务端由场景、队伍、公会三个子系统各自维护，这里合并成一份便于验证。
type World struct {
	Players map[PlayerID]struct{}
	Scene   map[PlayerID]InstanceID
	Party   map[PlayerID]PartyID
	Guild   map[PlayerID]GuildID
}

// ChatMessage 是进入投递管线的一条聊天消息。
type ChatMessage struct {
	From   PlayerID
	Kind   ChannelKind
	Target uint64 // 私聊=目标 PlayerID，队伍=PartyID，公会=GuildID
	Body   string
}

// Recipients 解析出一条消息的收件人集合（去重、升序，便于测试与回放）。
// 注意它只回答「发给谁」，不回答「能不能发」——权限由 CanSpeak 负责。
func Recipients(w *World, m ChatMessage) ([]PlayerID, error) {
	switch m.Kind {
	case ChanWorld, ChanSystem:
		return w.all(), nil
	case ChanLocal:
		scene, ok := w.Scene[m.From]
		if !ok {
			return nil, ErrUnknownPlayer
		}
		return w.members(func(p PlayerID) bool { return w.Scene[p] == scene }), nil
	case ChanParty:
		pid, ok := w.Party[m.From]
		if !ok {
			return nil, ErrNotInParty
		}
		return w.members(func(p PlayerID) bool { return w.Party[p] == pid }), nil
	case ChanGuild:
		gid, ok := w.Guild[m.From]
		if !ok {
			return nil, ErrNotInGuild
		}
		return w.members(func(p PlayerID) bool { return w.Guild[p] == gid }), nil
	case ChanPrivate:
		target := PlayerID(m.Target)
		if _, ok := w.Players[target]; !ok {
			return nil, ErrNoSuchTarget
		}
		return []PlayerID{target}, nil
	}
	return nil, ErrBadChannel
}

func (w *World) all() []PlayerID {
	out := make([]PlayerID, 0, len(w.Players))
	for p := range w.Players {
		out = append(out, p)
	}
	sortIDs(out)
	return out
}

func (w *World) members(pred func(PlayerID) bool) []PlayerID {
	var out []PlayerID
	for p := range w.Players {
		if pred(p) {
			out = append(out, p)
		}
	}
	sortIDs(out)
	return out
}

func sortIDs(ids []PlayerID) {
	sort.Slice(ids, func(i, j int) bool { return ids[i] < ids[j] })
}

// file: internal/chat/permission.go
// tier: L1
// verify: go test ./internal/chat/

package chat

import "errors"

// Speaker 是发言人的最小快照。权限判断只看这几个字段，
// 不碰实体运行时——聊天域不该为了鉴权去解引用一个可能已下线的实体。
type Speaker struct {
	ID       PlayerID
	Level    int
	Party    PartyID
	HasParty bool
	Guild    GuildID
	HasGuild bool
	Muted    bool
}

// ChannelPolicy 是一个频道的发言规则。规则是数据，不是 if-else 硬编码，
// 这样才能随活动、赛季、VIP 等级热更新。
type ChannelPolicy struct {
	Kind       ChannelKind
	MinLevel   int  // 低于该等级不可发言；0 表示不限
	NeedParty  bool // 必须已入队
	NeedGuild  bool // 必须已入会
	ServerOnly bool // 仅服务端可发（系统公告）
}

var (
	ErrMuted       = errors.New("chat: speaker is muted")
	ErrLevelTooLow = errors.New("chat: speaker level is too low")
	ErrNeedParty   = errors.New("chat: speaker must be in a party")
	ErrNeedGuild   = errors.New("chat: speaker must be in a guild")
	ErrServerOnly  = errors.New("chat: channel is server-only")
)

// CanSpeak 判断发言人是否满足频道规则，返回第一个不满足的原因。
// 顺序刻意固定：先看禁言（最重的处罚），再看频道本身的准入。
func CanSpeak(s Speaker, p ChannelPolicy) error {
	if s.Muted {
		return ErrMuted
	}
	if p.ServerOnly {
		return ErrServerOnly
	}
	if s.Level < p.MinLevel {
		return ErrLevelTooLow
	}
	if p.NeedParty && !s.HasParty {
		return ErrNeedParty
	}
	if p.NeedGuild && !s.HasGuild {
		return ErrNeedGuild
	}
	return nil
}

// file: internal/chat/wire.go
// tier: L1
// verify: go test ./internal/chat/

package chat

import "encoding/binary"

// 卷二沿用卷一定稿的命令号，不得改写。
const (
	CmdChatSend uint16 = 0x0301 // 客户端 -> 服务端
	CmdChatRecv uint16 = 0x0302 // 服务端 -> 客户端
)

// HeaderSize 是卷一固定头的长度：length(4) | cmd(2) | seq(4) | flags(1)。
const HeaderSize = 11

// EncodeRecv 把一条聊天消息编成 CmdChatRecv 帧：
// 固定头 + from(8, BE) + kind(1) + body(UTF-8)。
// length 统计 cmd+seq+flags+payload，不含 length 字段自身的 4 字节。
func EncodeRecv(seq uint32, from PlayerID, kind ChannelKind, body string) []byte {
	payload := make([]byte, 0, 9+len(body))
	var id [8]byte
	binary.BigEndian.PutUint64(id[:], uint64(from))
	payload = append(payload, id[:]...)
	payload = append(payload, byte(kind))
	payload = append(payload, body...)

	frame := make([]byte, HeaderSize+len(payload))
	binary.BigEndian.PutUint32(frame[0:4], uint32(7+len(payload)))
	binary.BigEndian.PutUint16(frame[4:6], CmdChatRecv)
	binary.BigEndian.PutUint32(frame[6:10], seq)
	frame[10] = 0 // flags 留给分片与压缩
	copy(frame[HeaderSize:], payload)
	return frame
}

// snippet: internal/chat/dispatch.go（投递主循环，节选）

func Dispatch(send func(to PlayerID, frame []byte) error, w *World, m ChatMessage, seq uint32) error {
	to, err := Recipients(w, m)
	if err != nil {
		return err // 没入队、私聊目标不存在等，直接回错误给调用方
	}
	frame := EncodeRecv(seq, m.From, m.Kind, m.Body)
	for _, r := range to {
		if err := send(r, frame); err != nil {
			// 一个收件人写失败（掉线、缓冲满）不该中断整条广播。
			// 真实的 seq 由每条连接的出站计数器提供，这里从参数传入。
			_ = err
		}
	}
	return nil
}