spi

type ConnectionAuthenticator interface {
	// Authenticate 从 HTTP 请求中提取并解密 token
	// 返回解密后的连接身份声明；token 不存在/无效/篡改/过期时返回 error
	Authenticate(r *http.Request) (*ConnectionClaims, error)
}

type ConnectionClaims struct {
	UserID    string `json:"uid"`           // 用户ID（必填）
	UserType  string `json:"utp,omitempty"` // 用户类型（默认 visitor）
	DeviceID  string `json:"did,omitempty"` // 设备ID
	AppID     string `json:"aid,omitempty"` // 应用ID（最上层隔离维度，默认 "__default_app__"）
	Namespace string `json:"tid,omitempty"` // 命名空间ID（默认 "default"，用于命名空间隔离与消息过滤）
	GroupID   string `json:"gid,omitempty"` // 群组ID（可选，支持逗号分隔多群组"g1,g2,g3"；用于群组消息过滤与连接时自动加入）
	ExpiresAt int64  `json:"exp,omitempty"` // 过期时间（Unix 秒；签发时自动填充，解密后校验）
}

type ConnectionQualityStore interface {
	// Upsert 创建或更新质量记录（首次连接建初始零值行 QualityScore=100，重连 reconnect_count+1）
	Upsert(ctx context.Context, quality *models.ConnectionQuality) error

	// BatchUpdateHeartbeats 批量更新 Ping 统计与活跃时间（单事务，心跳时间戳由 ConnectionStore 写 connect 表）
	BatchUpdateHeartbeats(ctx context.Context, entries []*models.HeartbeatUpdateEntry) error

	// BatchIncrementStats 批量递增消息/字节统计（单事务）
	BatchIncrementStats(ctx context.Context, entries []*models.StatsIncrementEntry) error

	// BatchAddErrors 批量记录连接错误（单事务）
	// 同一连接的多次错误由调用方在攒批 flush 时合并为一条 ErrorUpdateEntry（count 累加、保留最新错误）
	BatchAddErrors(ctx context.Context, entries []*models.ErrorUpdateEntry) error

	// BatchFinalizeOnDisconnect 批量断开终评（唯一入口，单条 FinalizeOnDisconnect 已废弃）
	// 停机路径逐连接终评 = 每连接 3 条 SQL（SELECT quality + SELECT duration + UPDATE score），
	// 26w 连接 = 78w 条 SQL 在停机窗口直打 DB，是滚动更新期 DB 过载的主源；
	// 批量化后 3 SQL/连接 → 每块 1 条 IN 读 + 1 条 CASE WHEN 写（Go 内算分），
	// duration 由调用方从 MarkDisconnectedBatch 返回的 entries 带入（与 SQL 写入值同源，无需读回）
	BatchFinalizeOnDisconnect(ctx context.Context, entries []*models.DisconnectionEntry) error

	// GetByConnectionID 根据连接ID获取质量记录
	GetByConnectionID(ctx context.Context, connectionID string) (*models.ConnectionQuality, error)

	// GetByUserID 根据用户ID获取所有质量记录
	GetByUserID(ctx context.Context, userID string) ([]*models.ConnectionQuality, error)

	// GetHighErrorRateConnections 获取高错误率连接
	GetHighErrorRateConnections(ctx context.Context, errorThreshold int, limit int) ([]*models.ConnectionQuality, error)

	// GetFrequentReconnectConnections 获取频繁重连的连接
	GetFrequentReconnectConnections(ctx context.Context, reconnectThreshold int, limit int) ([]*models.ConnectionQuality, error)

	// Close 关闭仓库
	Close() error
}

type ConnectionStore interface {

	// Upsert 创建或更新连接记录（首次连接创建，重连时更新）
	Upsert(ctx context.Context, record *models.ConnectionRecord) error

	// BatchMarkDisconnected 批量标记断连终态（CASE WHEN 单 SQL 合并）
	// 断连终态唯一写入口：正常注销经 DisconnectionBatcher 攒批 flush，停机路径分块直调；
	// 写 duration/disconnected_at/is_abnormal 供质量终评（FinalizeOnDisconnect）读，
	// connectedAt 由调用方从内存 Client 快照带入（省前置 SELECT）；
	// IN 影响 0 行（记录已被清理）静默返回；批内同连接去重保留最后（终态以最后一次为准）
	BatchMarkDisconnected(ctx context.Context, entries []*models.DisconnectionEntry) error

	// BatchUpdateHeartbeats 批量更新心跳时间戳（connect 表 last_ping_at，单 SQL）
	BatchUpdateHeartbeats(ctx context.Context, entries []*models.HeartbeatUpdateEntry) error

	// GetByConnectionID 根据连接ID获取连接记录
	GetByConnectionID(ctx context.Context, connectionID string) (*models.ConnectionRecord, error)

	// GetByUserID 根据用户ID获取所有连接记录（支持多设备）
	GetByUserID(ctx context.Context, userID string) ([]*models.ConnectionRecord, error)

	// GetActiveByUserID 根据用户ID获取所有活跃连接记录
	GetActiveByUserID(ctx context.Context, userID string) ([]*models.ConnectionRecord, error)

	// List 通用列表查询（支持条件过滤）
	List(ctx context.Context, opts *models.ConnectionQueryOptions) ([]*models.ConnectionRecord, error)

	// Count 统计连接数（支持条件过滤）
	Count(ctx context.Context, opts *models.ConnectionQueryOptions) (int64, error)

	// GetConnectionStats 获取连接统计信息（仅 connect 身份维度，质量维度由 ConnectionQualityStore 补充）
	GetConnectionStats(ctx context.Context, startTime, endTime time.Time) (*models.ConnectionStats, error)

	// GetConnectionStatsByID 根据连接ID获取单个连接的统计信息
	GetConnectionStatsByID(ctx context.Context, connectionID string) (*models.UserConnectionStats, error)

	// GetUserConnectionStats 获取用户所有连接的汇总统计
	GetUserConnectionStats(ctx context.Context, userID string) (*models.UserConnectionStats, error)

	// GetNodeConnectionStats 获取节点连接统计
	GetNodeConnectionStats(ctx context.Context, nodeID string) (*models.NodeConnectionStats, error)

	// BatchUpsert 批量创建或更新连接记录
	BatchUpsert(ctx context.Context, records []*models.ConnectionRecord) error

	// CleanupInactiveRecords 清理非活跃记录
	CleanupInactiveRecords(ctx context.Context, before time.Time) (int64, error)

	// Close 关闭仓库，停止后台任务
	Close() error
}

type DeliverEnvelope struct {
	Intent        DeliverIntent      `json:"intent"`                   // 投递意图，空值消费端按路由字段推导
	Publisher     string             `json:"publisher"`                // 发布者标识（审计与 ACL 主体，必填）
	PublishedAt   time.Time          `json:"published_at"`             // 发布时刻（消费端时延监控）
	ExcludeSender bool               `json:"exclude_sender,omitempty"` // 广播排除发送者连接
	Hops          uint8              `json:"hops,omitempty"`           // 转发跳数防环
	Message       *models.HubMessage `json:"message"`
}

type DeliverIntent uint8

type EventBus interface {
	// Publish 发布投递指令，同步返回表示 MQ 已接收（At-Least-Once 前提）
	// topic 路由由信封 Intent + Message 投递等级自动决定
	Publish(ctx context.Context, env *DeliverEnvelope) error

	// Subscribe 订阅投递指令，handler 返回 error 时按实现的 NACK 语义重投
	// queue 语义（TopicDeliver）与 fanout 语义（TopicBroadcast）由 topic 参数区分
	Subscribe(ctx context.Context, topic EventBusTopic, handler EventHandler) error

	// Close 优雅关闭：排空在途消息、退出订阅循环
	Close() error
}

type EventBusTopic string

type EventHandler func(ctx context.Context, env *DeliverEnvelope) error

type GroupStore interface {
	// CreateGroup 创建群组（存储元信息，若已存在则覆盖）
	// group.AppID/Namespace 为空时自动填充默认值
	CreateGroup(ctx context.Context, group *models.Group) error

	// GetGroup 获取群组元信息
	GetGroup(ctx context.Context, appID, namespace, groupID string) (*models.Group, error)

	// DisbandGroup 解散群组（删除元信息、成员集合、命名空间索引及各成员的反向索引）
	DisbandGroup(ctx context.Context, appID, namespace, groupID string) error

	// AddMembers 添加成员到群组（同时更新成员的反向索引与命名空间索引）
	AddMembers(ctx context.Context, appID, namespace, groupID string, userIDs []string) error

	// RemoveMembers 从群组移除成员（同时清理成员的反向索引）
	RemoveMembers(ctx context.Context, appID, namespace, groupID string, userIDs []string) error

	// GetMembers 获取群组所有成员ID
	GetMembers(ctx context.Context, appID, namespace, groupID string) ([]string, error)

	// GetUserGroups 获取用户在指定 (appID, namespace) 下加入的所有群组ID
	GetUserGroups(ctx context.Context, appID, namespace, userID string) ([]string, error)

	// IsMember 判断用户是否为群组成员
	IsMember(ctx context.Context, appID, namespace, groupID, userID string) (bool, error)

	// GetMemberCount 获取群组成员数量
	GetMemberCount(ctx context.Context, appID, namespace, groupID string) (int64, error)

	// GetNamespaceGroups 获取 (appID, namespace) 下所有群组ID
	GetNamespaceGroups(ctx context.Context, appID, namespace string) ([]string, error)

	// GetAllNamespaces 获取指定 appID 下所有有群组的命名空间ID（用于该 app 的全命名空间广播）
	GetAllNamespaces(ctx context.Context, appID string) ([]string, error)

	// GetMultiGroupMembers 批量获取多个群组的成员（跨 namespace 聚合，两段 Pipeline 共 2 次网络往返）
	// 同一 groupID 可在多个 namespace 下各建实例（业务侧按租户建组），本方法按 (appID, groupIDs)
	// 跨 ns 聚合所有实例的成员并合并去重；返回 map[groupID][]memberIDs，无实例的 gid 该 key 缺失
	GetMultiGroupMembers(ctx context.Context, appID string, groupIDs []string) (map[string][]string, error)

	// EnsureSystemGroup 确保系统保留组存在（__ 前缀，agent/observer 自动加入前初始化）
	// 幂等：不存在则创建，已存在则返回 nil
	EnsureSystemGroup(ctx context.Context, appID, namespace, groupID string) error

	// SetInvalidateNotifier 注入拓扑写路径失效回调（拓扑写本地逐出后触发，供跨节点失效广播聚合）
	// 持本地缓存的实现（GroupMemberCache）存回调并在写路径统一触发；无本地缓存的裸仓储 no-op 丢弃
	SetInvalidateNotifier(fn func(appID, groupID string))

	// InvalidateTopology 逐出该群组的本地缓存拓扑（跨节点失效广播的消费入口）
	// 纯逐出不写负缓存：失效原因是拓扑变更（含建组/增成员），写负缓存会把新实例误报为无实例；
	// 无本地缓存的裸仓储 no-op
	InvalidateTopology(appID, groupID string)
}

type HubStats interface {

	// UpdateConnectionStats 批量更新连接统计（总连接数+1、活跃连接数、心跳时间）
	UpdateConnectionStats(ctx context.Context, nodeID string, activeCount int64) error

	// IncrementTotalConnections 增加总连接数
	IncrementTotalConnections(ctx context.Context, nodeID string, delta int64) error

	// SetActiveConnections 设置当前活跃连接数
	SetActiveConnections(ctx context.Context, nodeID string, count int64) error

	// IncrementMessagesSent 增加已发送消息数
	IncrementMessagesSent(ctx context.Context, nodeID string, delta int64) error

	// IncrementMessagesReceived 增加已接收消息数
	IncrementMessagesReceived(ctx context.Context, nodeID string, delta int64) error

	// IncrementBroadcastsSent 增加已发送广播数
	IncrementBroadcastsSent(ctx context.Context, nodeID string, delta int64) error

	// RegisterNode 注册节点并初始化统计信息（设置启动时间、添加到节点集合）
	RegisterNode(ctx context.Context, nodeID string, startTime int64) error

	// GetNodeStats 获取指定节点的统计信息
	GetNodeStats(ctx context.Context, nodeID string) (*models.NodeStats, error)

	// GetAllNodesStats 获取所有节点的统计信息
	GetAllNodesStats(ctx context.Context) (map[string]*models.NodeStats, error)

	// GetTotalStats 获取集群总统计信息（所有节点汇总）
	GetTotalStats(ctx context.Context) (*models.ClusterStats, error)

	// CleanupNodeStats 清理已下线节点的统计数据
	CleanupNodeStats(ctx context.Context, nodeID string) error

	// UpdateNodeHeartbeat 更新节点心跳时间
	UpdateNodeHeartbeat(ctx context.Context, nodeID string) error

	// GetActiveNodes 获取活跃的节点列表（基于心跳）
	GetActiveNodes(ctx context.Context, timeout time.Duration) ([]string, error)
}

type Logger logger.ILogger

type MessageQueue interface {
	// Enqueue 入队消息
	Enqueue(ctx context.Context, queueName string, msg *models.HubMessage) error

	// Dequeue 出队消息（阻塞式，带看门狗锁保证消息不会因消费者崩溃而丢失）
	// timeout 为最长阻塞等待时间，超时返回 (nil, nil)
	Dequeue(ctx context.Context, queueName string, timeout time.Duration) (*models.HubMessage, error)

	// DequeueBatch 批量出队（非阻塞，单次往返）
	// 返回条数不足 count 表示队列已空
	DequeueBatch(ctx context.Context, queueName string, count int) ([]*models.HubMessage, error)

	// GetLength 获取队列当前长度
	GetLength(ctx context.Context, queueName string) (int64, error)

	// Clear 清空队列
	Clear(ctx context.Context, queueName string) error

	// Peek 查看队列头部消息（不移除）
	Peek(ctx context.Context, queueName string) (*models.HubMessage, error)
}

type MessageRole string

type MessageSink interface {

	// CreateBatch 批量创建消息发送记录（outbox 攒批 flush 用，一条 SQL 写整批；
	CreateBatch(ctx context.Context, records []*models.MessageSendRecord) error

	// FindByID 根据自增ID查找
	FindByID(ctx context.Context, id uint) (*models.MessageSendRecord, error)

	// FindByMessageID 根据消息ID+接收者复合键查找（P2P 同一 message_id 为每个 receiver 各建一条记录）
	FindByMessageID(ctx context.Context, key models.MessageRecordKey) (*models.MessageSendRecord, error)

	// QueryRecords 查询消息记录（支持按状态、发送者、接收者、节点IP、客户端IP等条件过滤）
	QueryRecords(ctx context.Context, filter *models.MessageRecordFilter) ([]*models.MessageSendRecord, error)

	// FindRetryable 查找可重试的记录
	FindRetryable(ctx context.Context, limit int) ([]*models.MessageSendRecord, error)

	// DeleteExpired 删除过期的记录
	DeleteExpired(ctx context.Context) (int64, error)

	// Delete 删除记录
	Delete(ctx context.Context, id uint) error

	// DeleteByMessageID 根据消息ID删除
	DeleteByMessageID(ctx context.Context, messageID string) error

	// BatchUpdateStatus 批量更新消息状态（按复合键批量定位；相同 status/reason/errorMsg 用一条 SQL；
	// 状态更新唯一路径，经 MessageStatusUpdater 攒批调用，单条 UpdateStatus 已移除）
	BatchUpdateStatus(ctx context.Context, keys []models.MessageRecordKey, status models.MessageSendStatus, reason models.FailureReason, errorMsg string) error

	// ClaimStaleSending 原子认领超时的 sending 记录（仅当状态仍为 sending 时按复合键更新）
	// 返回实际认领成功的复合键列表（状态已被并发方更新则不认领）
	ClaimStaleSending(ctx context.Context, keys []models.MessageRecordKey, newStatus models.MessageSendStatus, reason models.FailureReason, errorMsg string) ([]models.MessageRecordKey, error)

	// IncrementRetry 增加重试次数（按复合键定位单条记录）
	IncrementRetry(ctx context.Context, key models.MessageRecordKey, attempt models.RetryAttempt) error

	// GetStatistics 获取统计信息
	GetStatistics(ctx context.Context) (map[string]int64, error)

	// CleanupOld 清理旧记录
	CleanupOld(ctx context.Context, before time.Time) (int64, error)

	// Close 关闭仓库，停止后台任务
	Close() error
}

type OfflineMessageFilter struct {
	// UserID 用户ID
	UserID string
	// Role 查询视角（接收者/发送者）
	Role MessageRole
	// AppID 应用ID（空表示查询所有应用）
	AppID string
	// Namespace 命名空间ID（空表示所有命名空间）
	Namespace string
	// GroupID 群组ID（空表示非群组消息或所有消息）
	GroupID string
	// Limit 数量限制
	Limit int
	// Cursor 分页游标（message_id）
	Cursor string
	// Statuses 消息状态列表，为空则待处理状态
	Statuses []models.MessageSendStatus
	// ExcludeExhausted 排除重试耗尽的消息（retry_count >= max_retry，毒消息死信）
	// 推送失败由 UpdatePushStatus 原子递增 retry_count，超限后不再进入推送流程
	// max_retry <= 0 视为不限制
	ExcludeExhausted bool
}

type OfflineQueue interface {
	// StoreOfflineMessage 存储离线消息（双写 Redis + MySQL）
	// 落入 ctx 的 (ns, group) 对应的分区：Redis key = ns:group:userID
	StoreOfflineMessage(ctx context.Context, userID string, msg *models.HubMessage) error

	// DrainOfflineQueue 排空 Redis 队列（单组 FIFO，仅 Redis，不触及 MySQL）
	// 按 ctx 的单个 (ns, group) 出队，limit<=0 表示一次取尽
	// 调用方按组循环调用（hub replay 枚举用户所有 group + P2P）
	DrainOfflineQueue(ctx context.Context, userID string, limit int) ([]*models.HubMessage, error)

	// GetOfflineMessages 查询 MySQL 离线消息（跨组，命名空间内该用户全部 group）
	// limit: >0 最多返回指定数量；<=0 最多 1 万条
	// cursor: 上次返回的最后一条 message_id，空串表示从头
	// 返回 nextCursor 为空表示无更多数据
	GetOfflineMessages(ctx context.Context, userID string, limit int, cursor string) ([]*models.HubMessage, string, error)

	// DeleteOfflineMessages 按消息ID删除已推送的离线消息（MySQL，跨组按 message_id 删）
	DeleteOfflineMessages(ctx context.Context, userID string, messageIDs []string) error

	// GetOfflineMessageCount 获取离线消息数量（MySQL 跨组计数，MySQL 为双写超集故计数准确）
	GetOfflineMessageCount(ctx context.Context, userID string) (int64, error)

	// ClearOfflineMessages 清空用户的离线消息
	// groupIDs: 用户在该命名空间下的全部 group + "" (P2P)，逐组清 Redis + 一次清 MySQL
	ClearOfflineMessages(ctx context.Context, userID string, groupIDs []string) error

	// UpdatePushStatus 更新离线消息推送状态
	// pushErr: 推送结果错误,nil表示成功,非nil表示失败
	UpdatePushStatus(ctx context.Context, messageIDs []string, pushErr error) error
}

type OfflineStore interface {
	// Save 保存离线消息
	Save(ctx context.Context, record *models.OfflineMessageRecord) error

	// BatchSave 批量保存离线消息
	BatchSave(ctx context.Context, records []*models.OfflineMessageRecord) error

	// QueryMessages 查询离线消息（支持按接收者/发送者、分页、状态过滤）
	QueryMessages(ctx context.Context, filter *OfflineMessageFilter) ([]*models.OfflineMessageRecord, error)

	// DeleteByMessageIDs 批量删除离线消息（按应用+命名空间+接收者）
	DeleteByMessageIDs(ctx context.Context, appID, namespace, receiverID string, messageIDs []string) error

	// GetCountByReceiver 获取用户作为接收者的离线消息数量
	GetCountByReceiver(ctx context.Context, appID, namespace, receiverID string) (int64, error)

	// GetCountBySender 获取用户作为发送者的离线消息数量
	GetCountBySender(ctx context.Context, appID, namespace, senderID string) (int64, error)

	// ClearByReceiver 清空用户作为接收者的所有离线消息
	ClearByReceiver(ctx context.Context, appID, namespace, receiverID string) error

	// DeleteExpired 删除过期的离线消息
	DeleteExpired(ctx context.Context) (int64, error)

	// UpdatePushStatus 更新离线消息推送状态
	// status: 消息状态(pending/success/failed)
	// errorMsg: 错误信息(失败时)
	UpdatePushStatus(ctx context.Context, messageIDs []string, status models.MessageSendStatus, errorMsg string) error

	// CleanupOld 清理 before 之前的旧记录
	CleanupOld(ctx context.Context, before time.Time) (int64, error)

	// Close 关闭仓库，停止后台任务
	Close() error
}

type OnlineStore interface {

	// SetClientOnline 设置客户端在线（支持多设备）
	SetClientOnline(ctx context.Context, client *models.Client) error

	// SetClientOffline 设置指定客户端离线
	SetClientOffline(ctx context.Context, client *models.Client) error

	// SetOffline 设置用户所有客户端离线
	SetOffline(ctx context.Context, userID string) error

	// GetClient 获取客户端信息
	GetClient(ctx context.Context, clientID string) (*models.Client, error)

	// GetClientOwner 获取 clientID 当前归属节点（上线脚本写入 owner key）
	// 返回空串表示无归属记录（旧数据或已过期）；用于检测同 clientID 跨节点迁移
	GetClientOwner(ctx context.Context, clientID string) (string, error)

	// GetUserClients 获取用户的所有在线客户端
	GetUserClients(ctx context.Context, userID string) ([]*models.Client, error)

	// UpdateClientHeartbeat 更新客户端心跳
	UpdateClientHeartbeat(ctx context.Context, clientID string) error

	// IsUserOnline 检查用户是否在线（任意设备，按 ctx 路由信封 appID+namespace 隔离）
	// 路径自适应：有路由信封时走 L1 offset 缓存 → GETBIT（命中零网络），
	// 无路由信封走 unscoped GETBIT；位即真相，无 ZSET 兜底
	IsUserOnline(ctx context.Context, userID string) (bool, error)

	// BatchIsUserOnline 批量在线判定，返回 map[userID]bool（含全部查询的 userID）
	// Pipeline 实现：offset 解析（L1+HGET）→ GETBIT，两次往返覆盖 N 个用户（全命中 L1 时一次）
	BatchIsUserOnline(ctx context.Context, userIDs []string) (map[string]bool, error)

	// GetAllOnlineUsers 获取所有在线用户ID列表
	GetAllOnlineUsers(ctx context.Context) ([]string, error)

	// GetOnlineCount 获取在线用户总数
	GetOnlineCount(ctx context.Context) (int64, error)

	// GetOnlineUsersByType 根据用户类型获取在线用户
	GetOnlineUsersByType(ctx context.Context, userType models.UserType) ([]string, error)

	// GetUserNodes 获取用户所在的所有节点（支持多设备）
	GetUserNodes(ctx context.Context, userID string) ([]string, error)

	// BatchGetUserNodes 批量获取多个用户所在的所有节点（Pipeline 优化，避免 N+1 查询）
	// 返回 map[userID][]nodeIDs，未找到的 userID 不在 map 中
	BatchGetUserNodes(ctx context.Context, userIDs []string) (map[string][]string, error)

	// GetNodeClients 获取节点的所有在线客户端
	GetNodeClients(ctx context.Context, nodeID string) ([]*models.Client, error)

	// GetNodeUsers 获取节点的所有在线用户ID
	GetNodeUsers(ctx context.Context, nodeID string) ([]string, error)

	// BatchSetClientsOnline 批量设置客户端在线（全量：JSON 序列化 + SETEX client 详情）
	BatchSetClientsOnline(ctx context.Context, clients []*models.Client) error

	// RenewClientsOnline 心跳批量续期（轻量路径：跳过序列化/压缩/SETEX，仅续期索引与 bitmap）
	// client:<id> 键缺失（过期/淘汰）的客户端内部自动走全量重建，自愈语义与 BatchSetClientsOnline 一致
	// 供心跳高频刷新使用，千万级连接下避免每周期全量重写 client 详情
	RenewClientsOnline(ctx context.Context, clients []*models.Client) error

	// BatchSetClientsOffline 批量设置客户端离线
	BatchSetClientsOffline(ctx context.Context, clientIDs []string) error

	// BatchSetClientsOfflineWithInfo 批量设置客户端离线（使用已知的客户端信息）
	// 客户端信息已知时使用，避免从 Redis 查询，确保即使 client key 已被删除也能清理 bitmap 位与索引
	BatchSetClientsOfflineWithInfo(ctx context.Context, clients []*models.Client) error

	// CleanupExpired 清理当前节点的过期客户端
	CleanupExpired(ctx context.Context, nodeID string) (int64, error)
}

type RouteAdvisor interface {
	// NodeOf 返回用户连接所在节点；空列表 = 离线/未知（投共享 topic 或直接离线）
	NodeOf(ctx context.Context, appID, namespace, userID string) []string
}

type StoreDeps struct {
	// Redis Redis 客户端（纯 RDBMS 部署时为 nil）
	Redis redis.UniversalClient
	// DB GORM 实例（纯 Redis 部署时为 nil）
	DB *gorm.DB
}

type StoreHooks interface {
	// Configure 用给定依赖装配该适配器负责的全部仓库
	//
	// 返回:
	//   - error: 仅在该适配器所需依赖齐备却构造失败时返回；
	//     依赖缺失（如纯 Redis 场景无 DB）应直接跳过并返回 nil
	Configure(ctx context.Context, hub StoreTarget, deps StoreDeps) error
}

type StoreTarget interface {
	SetOnlineStatusRepository(store OnlineStore)
	SetHubStatsRepository(store HubStats)
	SetGroupRepository(store GroupStore)
	SetWorkloadRepository(store WorkloadStore)
	SetMessageRecordRepository(sink MessageSink)
	SetConnectionRecordRepository(store ConnectionStore)
	SetConnectionQualityRepository(store ConnectionQualityStore)
	SetOfflineMessageHandler(queue OfflineQueue)
}

type WorkloadStore interface {
	// ReloadAgentWorkload 重新加载客服工作负载（客服上线时调用）
	// 优先级：Redis > DB > 默认值 0；从持久化存储恢复负载，不存在则初始化为 0 并同步 ZSet
	ReloadAgentWorkload(ctx context.Context, agentID string) (int64, error)

	// ForceSetAgentWorkload 强制设置客服工作负载（慎用，会覆盖现有值）
	// 直接覆盖 Redis 和 ZSet 中的负载值，异步同步到 DB
	ForceSetAgentWorkload(ctx context.Context, agentID string, workload int64) error

	// GetAgentWorkload 获取客服工作负载
	GetAgentWorkload(ctx context.Context, agentID string) (int64, error)

	// IncrementAgentWorkload 增加客服工作负载
	IncrementAgentWorkload(ctx context.Context, agentID string) error

	// DecrementAgentWorkload 减少客服工作负载
	DecrementAgentWorkload(ctx context.Context, agentID string) error

	// GetLeastLoadedAgent 获取负载最小的在线客服
	GetLeastLoadedAgent(ctx context.Context, onlineAgents []string, dimension models.WorkloadDimension) (string, int64, error)

	// AcquireLeastLoadedAgent 原子地选择负载最小的在线客服并将其负载 +1
	//
	// 与 GetLeastLoadedAgent 的区别：
	//   - GetLeastLoadedAgent 只读，纯查询，返回后业务侧还需单独调用 IncrementAgentWorkload，
	//     这会导致"读-改-写"之间存在 TOCTOU 窗口，多进程/多 goroutine 并发时读到同一份旧负载快照，
	//     选出同一个客服，造成工单扎堆分配到同一人（负载均衡不均）
	//   - AcquireLeastLoadedAgent 在同一段 Lua 中完成 "选中 + 所有维度原子 +1"，
	//     Redis 单线程保证跨进程原子，是分布式场景下负载均衡分配的正确做法
	//
	// 返回值:
	//   - agentID: 被选中的客服 ID
	//   - workload: 选中客服在选中前的 realtime 负载值（用于日志/监控）
	//   - error: 执行失败的错误
	//
	// 业务失败回滚：调用方应在后续业务失败时调用 DecrementAgentWorkload 回滚此次预扣减
	AcquireLeastLoadedAgent(ctx context.Context, onlineAgents []string, dimension models.WorkloadDimension) (string, int64, error)

	// RemoveAgentWorkload 移除客服负载记录（客服下线时调用）
	// 只删除 ZSet 记录，保留 string key 以便重新上线时恢复
	RemoveAgentWorkload(ctx context.Context, agentID string) error

	// GetAllAgentWorkloads 获取所有客服负载（按负载升序）
	GetAllAgentWorkloads(ctx context.Context, limit int64) ([]models.WorkloadInfo, error)
}