Scoreboard/server/internal/realtime/protocol.go

// Package realtime 实现 /ws 实时同步中心。
//
// 协议以 devdocs/05-接口与实时协议.md 第 1–5 节为唯一规范：
// 版本号取自 change_log.id，客户端按 version 去重，增量补不上就回落全量快照。
package realtime

import (
	"encoding/json"
	"fmt"
	"time"
)

// 事件名与协议第 3 节的表格一一对应。
const (
	EventHello          = "hello"
	EventSnapshot       = "snapshot"
	EventCatchup        = "catchup"
	EventChange         = "change"
	EventResync         = "resync"
	EventAck            = "ack"
	EventHeartbeat      = "heartbeat"
	EventDisplayCommand = "display:command"
)

// 房间名。admin:<userId> 由 AdminRoom 生成，用于定向通知。
//
// admin:<userId> 目前没有生产推送方（只有测试用 BroadcastTo 往它发过消息）：
// 保留它是因为 devdocs/05 §1 把「admin:<userId>（定向通知）」写成了协议的一部分，
// 要删就得连着文档一起改，而文档不在本轮可改范围内——见审查清单 C36。
const (
	RoomDisplay = "display"
	RoomAdmin   = "admin"
)

// AdminRoom 返回某个管理端用户的定向房间名。
//
// 只有带会话的管理端连接会加入这个房间（见 handleHello），身份来自会话而非客户端自报；
// 「guest 不能进管理端房间」这条鉴权语义由测试钉住，删房间会一起删掉那条覆盖。
func AdminRoom(userID int64) string { return fmt.Sprintf("admin:%d", userID) }

// 连接角色。
const (
	RoleDisplay = "display"
	RoleAdmin   = "admin"
)

// change.action 取值。
const (
	ActionUpsert  = "upsert"
	ActionVoid    = "void"
	ActionReplace = "replace"
)

// display:command 支持的 action。
const (
	CmdGoto       = "goto"
	CmdLock       = "lock"
	CmdUnlock     = "unlock"
	CmdReload     = "reload"
	CmdAnnounce   = "announce"
	CmdShowDetail = "show-detail"
	CmdHideDetail = "hide-detail"
	// CmdAnnounceClear 清除当前公告：服务端同时清设置里的持久值并广播给大屏。
	CmdAnnounceClear = "announce_clear"
)

var displayActions = map[string]bool{
	CmdGoto:          true,
	CmdLock:          true,
	CmdUnlock:        true,
	CmdReload:        true,
	CmdAnnounce:      true,
	CmdAnnounceClear: true,
	CmdShowDetail:    true,
	CmdHideDetail:    true,
}

// ValidDisplayAction 判断 display:command 的 action 是否在协议清单内。
func ValidDisplayAction(action string) bool { return displayActions[action] }

// envelope 是所有消息的统一外壳：{ "event": "...", "data": { ... } }。
type envelope struct {
	Event string          `json:"event"`
	Data  json.RawMessage `json:"data,omitempty"`
}

// encode 把事件名与载荷打包成一条文本帧。
func encode(event string, data any) ([]byte, error) {
	raw, err := json.Marshal(data)
	if err != nil {
		return nil, fmt.Errorf("编码 %s 载荷: %w", event, err)
	}
	return json.Marshal(envelope{Event: event, Data: raw})
}

// helloPayload 是 C→S 的 hello 载荷。
//
// role 只是「申请」：服务端以会话身份为准，未登录连接申请 admin 会被拒绝，
// 因此这里没有 userId —— 定向房间的 userId 只能来自会话。
// instanceId / page / screen 是协议字段之外的可选扩展：注册表要记「谁在线、在哪一页、哪块屏」，
// 老客户端不带这几个字段也能正常工作。
type helloPayload struct {
	Role        string `json:"role"`
	LastVersion *int64 `json:"lastVersion,omitempty"`
	DisplayKey  string `json:"displayKey,omitempty"`
	InstanceID  string `json:"instanceId,omitempty"`
	Page        string `json:"page,omitempty"`
	// Screen 是 Console 从 URL 带下来的屏号（screen=<display.id>），局域网浏览器留空。
	Screen string `json:"screen,omitempty"`
}

// ackPayload 是 C→S 的 ack 载荷；服务端据此识别慢客户端。
type ackPayload struct {
	Version int64 `json:"version"`
}

// Change 是变更的最小单元；Version 只用于服务端排序与去重，不上线路。
type Change struct {
	Entity  string          `json:"entity"`
	ID      int64           `json:"id,omitempty"`
	Action  string          `json:"action"`
	Data    json.RawMessage `json:"data,omitempty"`
	Version int64           `json:"-"`
}

// changePayload 是 change 事件的载荷。
type changePayload struct {
	Version int64    `json:"version"`
	Changes []Change `json:"changes"`
}

// catchupPayload 是 catchup 事件的载荷。
type catchupPayload struct {
	FromVersion int64    `json:"fromVersion"`
	Version     int64    `json:"version"`
	Changes     []Change `json:"changes"`
}

// heartbeatPayload 是 heartbeat 事件的载荷。
type heartbeatPayload struct {
	Version    int64  `json:"version"`
	ServerTime string `json:"serverTime"`
}

// DisplayCommand 是下发给大屏的 display:command 载荷。
type DisplayCommand struct {
	Action  string          `json:"action"`
	Payload json.RawMessage `json:"payload,omitempty"`
}

// NewDisplayCommand 构造一条大屏指令；action 不在协议清单内时返回错误。
func NewDisplayCommand(action string, payload any) (DisplayCommand, error) {
	if !ValidDisplayAction(action) {
		return DisplayCommand{}, fmt.Errorf("未知的大屏指令 %q", action)
	}
	cmd := DisplayCommand{Action: action}
	if payload != nil {
		raw, err := json.Marshal(payload)
		if err != nil {
			return DisplayCommand{}, fmt.Errorf("编码大屏指令 %s 的 payload: %w", action, err)
		}
		cmd.Payload = raw
	}
	return cmd, nil
}

// pageFromPayload 从 goto 指令的 payload 里取目标页名，兼容字符串与对象两种写法。
func pageFromPayload(payload json.RawMessage) string {
	if len(payload) == 0 {
		return ""
	}
	var s string
	if err := json.Unmarshal(payload, &s); err == nil {
		return s
	}
	var obj struct {
		Page string `json:"page"`
	}
	if err := json.Unmarshal(payload, &obj); err == nil {
		return obj.Page
	}
	return ""
}

func nowISO(t time.Time) string { return t.Format(time.RFC3339Nano) }