models

type AgentWorkloadModel struct {
	ID                uint              `gorm:"primaryKey;autoIncrement;comment:自增主键" json:"id"`
	Namespace         string            `` /* 166-byte string literal not displayed */
	AgentID           string            `gorm:"column:agent_id;size:255;not null;index:idx_ns_agent_dimension_time;comment:客服ID" json:"agent_id"`
	WorkloadDimension WorkloadDimension `` /* 131-byte string literal not displayed */
	TimeKey           string            `` /* 154-byte string literal not displayed */
	Workload          int64             `gorm:"column:workload;not null;default:0;index;comment:当前负载" json:"workload"`
	CreatedAt         time.Time         `gorm:"column:created_at;not null;comment:创建时间" json:"created_at"`
	UpdatedAt         time.Time         `gorm:"column:updated_at;not null;comment:更新时间" json:"updated_at"`
}

type BroadcastResult struct {
	Total      int              // 总用户数量
	Success    int              // 成功发送数量
	Offline    int              // 离线用户数量
	Failed     int              // 发送失败数量
	Errors     map[string]error // 错误详情 map[userID]error
	OfflineIDs []string         // 离线用户ID列表
	FailedIDs  []string         // 发送失败的用户ID列表
}

type BroadcastType string

type BusinessCategory string

type Client struct {
	ID             string          `json:"id"`                  // 客户端ID
	UserID         string          `json:"user_id"`             // 用户ID
	AppID          string          `json:"app_id,omitempty"`    // 应用ID（最上层隔离维度，入口层归一化为 DefaultAppID，用于应用间消息隔离）
	Namespace      string          `json:"namespace"`           // 命名空间ID（默认 "default"，类似 k8s namespace，用于观察者过滤与命名空间隔离）
	GroupID        string          `json:"group_id,omitempty"`  // 默认群组ID（普通用户=连接后自动加入；观察者=订阅的观察群组，空=观察整个命名空间）
	GroupIDs       []string        `json:"group_ids,omitempty"` // 连接时自动加入的全部群组列表（管理端一人多组场景）；GetGroupIDs 回退链：GroupIDs→[GroupID]→[DefaultGroupID]
	UserType       UserType        `json:"user_type"`           // 用户类型
	VIPLevel       VIPLevel        `json:"vip_level"`           // VIP等级
	Role           UserRole        `json:"role"`                // 用户角色
	ClientIP       string          `json:"client_ip"`           // 客户端IP
	Conn           *websocket.Conn `json:"-"`                   // WebSocket连接（不序列化，仅WS使用）
	ConnectedAt    time.Time       `json:"connected_at"`        // 连接时间
	Status         UserStatus      `json:"status"`              // 用户状态
	Department     Department      `json:"department"`          // 部门
	Skills         []Skill         `json:"skills"`              // 技能列表
	MaxTickets     int             `json:"max_tickets"`         // 最大工单数
	NodeID         string          `json:"node_id"`             // 所在节点ID
	NodeIP         string          `json:"node_ip"`             // 所在节点IP
	NodePort       int             `json:"node_port"`           // 所在节点端口
	ClientType     ClientType      `json:"client_type"`         // 客户端类型（web/mobile/desktop）
	ConnectionType ConnectionType  `json:"connection_type"`     // 连接类型（websocket/sse）
	// Metadata 惰性分配：NewClient 不预建 map（省 ~300B/conn），首次写入经
	// SetMetadataValue/WithMetadataMap 惰性创建；序列化边界输出空对象保持 JSON 形态不变
	Metadata map[string]interface{} `json:"metadata"` // 元数据
	SendChan chan []byte            `json:"-"`        // 发送通道（不序列化，仅WS使用）
	CtrlCh   chan []byte            `json:"-"`        // 控制通道（必达级：KickOut/ForceOffline/Ack 等；写泵 select 前优先排空，容量见 constants.CtrlChanCapacity）
	PongCh   chan []byte            `json:"-"`        // pong 控制帧队列（不序列化，cap 1；读协程收到协议级 PING 后非阻塞投递，写泵统一写出——gorilla 单写者模式）
	DoneCh   chan struct{}          `json:"-"`        // 生命周期关闭信号（注销时 close，写泵 select 退出；数据通道永不 close，消除 send/close 竞态）
	Context  context.Context        `json:"-"`        // 上下文（不序列化）

	CloseMu sync.Mutex `json:"-"` // 保护channel关闭的互斥锁（不序列化）

	// SSE 专用字段（仅当 ConnectionType 为 SSE 时使用）
	SSEWriter    http.ResponseWriter `json:"-"` // SSE Writer（不序列化）
	SSEFlusher   http.Flusher        `json:"-"` // SSE Flusher（不序列化）
	SSEMessageCh chan *HubMessage    `json:"-"` // SSE 消息通道（不序列化）
	SSECloseCh   chan struct{}       `json:"-"` // SSE 关闭通道（不序列化）
	// contains filtered or unexported fields
}

type ClientType string

type ClusterStats struct {
	TotalNodes        int          `json:"total_nodes"`
	ActiveNodes       int          `json:"active_nodes"`
	TotalConnections  int64        `json:"total_connections"`
	ActiveConnections int64        `json:"active_connections"`
	MessagesSent      int64        `json:"messages_sent"`
	MessagesReceived  int64        `json:"messages_received"`
	BroadcastsSent    int64        `json:"broadcasts_sent"`
	NodesStats        []*NodeStats `json:"nodes_stats"`
	UpdateTime        time.Time    `json:"update_time"`
}

type ConnectionQuality struct {
	// ========== 关联标识 ==========
	ID           uint64 `gorm:"primaryKey;autoIncrement;comment:自增主键" json:"id"`
	ConnectionID string `` /* 147-byte string literal not displayed */
	UserID       string `gorm:"column:user_id;size:64;index;comment:用户ID(冗余索引，便于按用户查质量)" json:"user_id"`

	// ========== 多租户/命名空间隔离 ==========
	// 与 connect 表 + Bitmap 分桶维度一致，支持按 app+namespace 查连接质量
	// 索引名与 connect 表区分（SQLite/PostgreSQL 索引名为库级作用域，重名会建表失败）
	AppID     string `` /* 139-byte string literal not displayed */
	Namespace string `` /* 138-byte string literal not displayed */

	// ========== 质量指标 ==========
	ReconnectCount   int     `gorm:"column:reconnect_count;default:0;comment:重连次数" json:"reconnect_count"`
	MessagesSent     int64   `gorm:"column:messages_sent;default:0;comment:发送消息总数" json:"messages_sent"`
	MessagesReceived int64   `gorm:"column:messages_received;default:0;comment:接收消息总数" json:"messages_received"`
	BytesSent        int64   `gorm:"column:bytes_sent;default:0;comment:发送字节数" json:"bytes_sent"`
	BytesReceived    int64   `gorm:"column:bytes_received;default:0;comment:接收字节数" json:"bytes_received"`
	AveragePingMs    float64 `gorm:"column:average_ping_ms;comment:平均Ping延迟(毫秒)" json:"average_ping_ms,omitempty"`
	MaxPingMs        float64 `gorm:"column:max_ping_ms;comment:最大Ping延迟(毫秒)" json:"max_ping_ms,omitempty"`
	MinPingMs        float64 `gorm:"column:min_ping_ms;comment:最小Ping延迟(毫秒)" json:"min_ping_ms,omitempty"`
	PacketLossRate   float64 `gorm:"column:packet_loss_rate;comment:丢包率(%)" json:"packet_loss_rate,omitempty"`

	// ========== 错误信息 ==========
	ErrorCount  int        `gorm:"column:error_count;default:0;comment:错误次数" json:"error_count"`
	LastError   string     `gorm:"column:last_error;type:text;comment:最后错误信息" json:"last_error,omitempty"`
	LastErrorAt *time.Time `gorm:"column:last_error_at;comment:最后错误时间" json:"last_error_at,omitempty"`

	// ========== 评分与活跃时间 ==========
	QualityScore float64    `gorm:"column:quality_score;index;comment:连接质量评分(0-100)" json:"quality_score"`
	LastActiveAt *time.Time `gorm:"column:last_active_at;index;comment:最后活跃时间(供清理)" json:"last_active_at,omitempty"`

	// ========== 系统字段 ==========
	CreatedAt time.Time `gorm:"autoCreateTime;comment:记录创建时间" json:"created_at"`
	UpdatedAt time.Time `gorm:"autoUpdateTime;comment:记录更新时间" json:"updated_at"`
}

type ConnectionQueryOptions struct {
	UserID     string // 用户ID过滤
	NodeID     string // 节点ID过滤
	IsActive   *bool  // 是否活跃（nil表示不过滤）
	IsAbnormal *bool  // 是否异常（nil表示不过滤）
	ClientIP   string // 客户端IP过滤
	Limit      int    // 限制数量
	Offset     int    // 偏移量
	OrderBy    string // 排序字段（默认 connected_at DESC）
}

type ConnectionRecord struct {
	// ========== 基础标识信息 ==========
	ID           uint64 `gorm:"primaryKey;autoIncrement;comment:自增主键" json:"id"`
	ConnectionID string `` /* 130-byte string literal not displayed */
	UserID       string `gorm:"column:user_id;size:64;not null;index;comment:用户ID(同一用户可有多条记录)" json:"user_id"`

	// ========== 多租户/命名空间隔离 ==========
	// 与 Bitmap 在线状态层分桶维度一致，支持按 app+namespace 过滤连接
	AppID     string `gorm:"column:app_id;size:64;index:idx_app_namespace;comment:应用ID(多租户隔离,与 Bitmap 分桶一致)" json:"app_id"`
	Namespace string `gorm:"column:namespace;size:64;index:idx_app_namespace;comment:命名空间(与 Bitmap 分桶一致)" json:"namespace"`

	// ========== 服务器节点信息 ==========
	NodeID   string `gorm:"column:node_id;size:100;index;comment:服务器节点ID" json:"node_id"`
	NodeIP   string `gorm:"column:node_ip;size:45;comment:服务器IP" json:"node_ip"`
	NodePort int    `gorm:"column:node_port;comment:服务器端口" json:"node_port"`

	// ========== 客户端信息 ==========
	ClientIP   string     `gorm:"column:client_ip;size:45;index;comment:客户端IP地址(用于索引查询)" json:"client_ip"`
	ClientType ClientType `gorm:"column:client_type;size:20;comment:客户端类型(web/mobile/desktop/sdk)" json:"client_type"`

	// ========== 连接协议信息 ==========
	Protocol ConnectionType `gorm:"column:protocol;size:20;default:websocket;comment:协议类型(websocket/sse/http)" json:"protocol"`

	// ========== 连接时间信息 ==========
	ConnectedAt    time.Time  `gorm:"column:connected_at;index;not null;comment:连接建立时间" json:"connected_at"`
	DisconnectedAt *time.Time `gorm:"column:disconnected_at;index;comment:断开连接时间" json:"disconnected_at,omitempty"`
	Duration       int64      `gorm:"column:duration;comment:连接持续时长(秒)" json:"duration,omitempty"`
	LastPingAt     *time.Time `gorm:"column:last_ping_at;comment:最后心跳时间" json:"last_ping_at,omitempty"`
	LastPongAt     *time.Time `gorm:"column:last_pong_at;comment:最后Pong响应时间" json:"last_pong_at,omitempty"`

	// ========== 断开连接信息 ==========
	DisconnectReason string `` /* 142-byte string literal not displayed */
	DisconnectCode   int    `gorm:"column:disconnect_code;comment:断开代码" json:"disconnect_code,omitempty"`

	// ========== 状态标识 ==========
	IsActive        bool `gorm:"column:is_active;index;comment:是否活跃连接" json:"is_active"`
	IsForcedOffline bool `gorm:"column:is_forced_offline;comment:是否被强制下线" json:"is_forced_offline"`
	IsAbnormal      bool `gorm:"column:is_abnormal;index;comment:是否异常断开" json:"is_abnormal"`

	// ========== 元数据 ==========
	Metadata sqlbuilder.MapAny `gorm:"column:metadata;type:json;comment:请求元数据JSON(包含所有HTTP头信息)" json:"metadata,omitempty"`

	// ========== 系统字段 ==========
	CreatedAt time.Time `gorm:"autoCreateTime;comment:记录创建时间" json:"created_at"`
	UpdatedAt time.Time `gorm:"autoUpdateTime;comment:记录更新时间" json:"updated_at"`
}

type ConnectionStats struct {
	TotalConnections      int64   `json:"total_connections"`       // 总连接数
	ActiveConnections     int64   `json:"active_connections"`      // 活跃连接数
	AverageDuration       float64 `json:"average_duration"`        // 平均连接时长(秒)
	TotalMessagesSent     int64   `json:"total_messages_sent"`     // 总发送消息数（拆表后零填充，跨表补充由调用方）
	TotalMessagesReceived int64   `json:"total_messages_received"` // 总接收消息数（拆表后零填充）
	TotalBytesSent        int64   `json:"total_bytes_sent"`        // 总发送字节数（拆表后零填充）
	TotalBytesReceived    int64   `json:"total_bytes_received"`    // 总接收字节数（拆表后零填充）
	AveragePingMs         float64 `json:"average_ping_ms"`         // 平均Ping延迟（拆表后零填充）
	AbnormalRate          float64 `json:"abnormal_rate"`           // 异常断开率
	AverageReconnectCount float64 `json:"average_reconnect_count"` // 平均重连次数（拆表后零填充）
}

type ConnectionStatus string

type ConnectionType string

type DeliverResult struct {
	Mode      DeliveryMode // 投递模式
	AppID     string       // 应用ID（已归一化）
	Namespace string       // 命名空间ID（全局广播时为空）
	GroupIDs  []string     // 群组ID列表（非群组场景为空）

	// P2P / 群组可靠投递场景（per-member 统计）
	TotalMembers   int // 目标成员数（P2P=1，群组=去重后成员数，广播=0）
	OnlineMembers  int // 在线成员数（至少在一个节点有连接）
	OfflineMembers int // 离线成员数
	Sent           int // 在线且成功投递数（含跨节点路由）
	StoredOffline  int // 离线成员存储离线消息数
	Failed         int // 投递失败数（在线但队列满等）

	// 广播场景（fire-and-forget 本地成功投递数）
	// 群组广播/命名空间广播/全局广播的本地送达数；全局广播为异步，此值为 0
	LocalDelivered int

	// 群组广播场景：可聚合档消息已入本地聚合窗口（drain 窗口批量扇出，LocalDelivered 不含窗口内消息；跨节点意图照常已发出）
	Aggregated bool

	Errors []error // 投递过程中的错误
}

type DeliveryGuarantee int8

type DeliveryMode int

type Department string

type DisconnectReason string

type DisconnectionEntry struct {
	ConnectionID   string
	ConnectedAt    time.Time
	DisconnectedAt time.Time
	Reason         DisconnectReason
	Code           int
}

type DistributedMessage struct {
	Type          OperationType `json:"type"`                     // 操作类型
	NodeID        string        `json:"node_id"`                  // 源节点ID
	TargetID      string        `json:"target_id"`                // 目标ID（用户ID、节点ID等）
	TraceID       string        `json:"trace_id,omitempty"`       // 全链路追踪ID（从 ctx 自动注入，跨节点序列化携带）
	Message       *HubMessage   `json:"message"`                  // 消息数据（用于 send_message, broadcast, observer_notify）
	Reason        string        `json:"reason"`                   // 原因
	Timestamp     time.Time     `json:"timestamp"`                // 时间戳
	AppID         string        `json:"app_id,omitempty"`         // 应用ID（最上层隔离维度，路由信封携带，空=全局共享）
	Namespace     string        `json:"namespace,omitempty"`      // 命名空间ID（路由信封携带，空=全命名空间广播，非空=指定命名空间）
	GroupIDs      []string      `json:"group_ids,omitempty"`      // 群组ID列表（支持多群组，观察者可订阅多个组；空表示无群组操作）
	ExcludeSender bool          `json:"exclude_sender,omitempty"` // 是否排除发送者（跨节点群组广播 PubSub 兜底携带，与 gRPC BroadcastGroupRequest 对齐）
	SenderID      string        `json:"sender_id,omitempty"`      // 发送者ID（排除发送者时用，跨节点 PubSub 兜底场景）
}

type ErrorSeverity string

type ErrorUpdateEntry struct {
	ConnectionID string
	ErrorCount   int64
	LastError    string
	LastErrorAt  time.Time
}

type EventStatus string

type FailureReason string

type Group struct {
	AppID      string                 `json:"app_id"`             // 应用ID（默认 "__default_app__"）
	Namespace  string                 `json:"namespace"`          // 命名空间ID（默认 "default"）
	GroupID    string                 `json:"group_id"`           // 群组ID（命名空间内唯一）
	Name       string                 `json:"name"`               // 群组名称
	OwnerID    string                 `json:"owner_id"`           // 群主用户ID
	MaxMembers int                    `json:"max_members"`        // 最大成员数（0 表示不限）
	CreatedAt  time.Time              `json:"created_at"`         // 创建时间
	Metadata   map[string]interface{} `json:"metadata,omitempty"` // 扩展元数据
}

type GroupObserverStats struct {
	GroupID       string           `json:"group_id"`       // 群组ID
	TotalUsers    int              `json:"total_users"`    // 该群组下观察者用户数
	TotalDevices  int              `json:"total_devices"`  // 该群组下观察者设备数
	ObserverStats []*ObserverStats `json:"observer_stats"` // 群组级观察者详细统计
}

type GroupSendResult struct {
	AppID          string  // 应用ID
	GroupID        string  // 群组ID
	TotalMembers   int     // 群组总成员数
	OnlineMembers  int     // 在线成员数（至少在一个节点有连接）
	OfflineMembers int     // 离线成员数
	Sent           int     // 在线且成功投递数（含跨节点路由）
	StoredOffline  int     // 离线成员存储离线消息数
	Failed         int     // 投递失败数（在线但队列满等）
	Errors         []error // 投递过程中的错误
}

type HeartbeatUpdateEntry struct {
	ConnectionID string
	PingTime     *time.Time
	PingMs       float64 // >0 时更新 average/max/min_ping_ms
}

type HubHealthInfo struct {
	Status           string `json:"status"`
	IsRunning        bool   `json:"is_running"`
	WebSocketCount   int    `json:"websocket_count"`
	SSECount         int    `json:"sse_count"`
	TotalConnections int    `json:"total_connections"`
	NodeID           string `json:"node_id"`
}

type HubMessage struct {
	// ========== 标识与路由（热点字段，置于头部以利用 cache line） ==========
	ID           string      `json:"id"`                      // 消息ID（用于ACK）
	TraceID      string      `json:"trace_id,omitempty"`      // 全链路追踪ID（从 ctx 自动注入，跨节点序列化携带）
	MessageType  MessageType `json:"message_type"`            // 消息类型
	Sender       string      `json:"sender"`                  // 发送者 (从上下文获取)
	SenderName   string      `json:"sender_name"`             // 发送者昵称
	SenderType   UserType    `json:"sender_type"`             // 发送者类型
	SenderClient string      `json:"sender_client,omitempty"` // 发送者客户端ID（多端同步标识）
	Receiver     string      `json:"receiver"`                // 接收者用户ID
	ReceiverName string      `json:"receiver_name"`           // 接收者昵称
	ReceiverType UserType    `json:"receiver_type"`           // 接收者用户类型

	// ========== 接收与节点路由 ==========
	ReceiverClient string `json:"receiver_client,omitempty"` // 接收者客户端ID
	ReceiverNode   string `json:"receiver_node,omitempty"`   // 接收者所在节点ID
	SessionID      string `json:"session_id"`                // 会话ID

	// ========== 内容 ==========
	Content string `json:"content"` // 消息内容

	// ========== 扩展数据（8 字节对齐字段） ==========
	Data     map[string]interface{} `json:"data,omitempty"` // 扩展数据（包含 content_extra、metadata、media_info）
	CreateAt time.Time              `json:"create_at"`      // 创建时间

	// ========== 消息ID与序列 ==========
	MessageID    string `json:"message_id"`                // 业务消息ID
	ReplyToMsgID string `json:"reply_to_msg_id,omitempty"` // 回复的消息ID
	SeqNo        int64  `json:"seq_no"`                    // 消息序列号

	// ========== 类型与策略（string，16 字节对齐） ==========
	Priority      Priority      `json:"priority"`                 // 优先级
	Source        MessageSource `json:"source,omitempty"`         // 消息来源(online/offline)
	PushType      PushType      `json:"push_type,omitempty"`      // 推送类型
	BroadcastType BroadcastType `json:"broadcast_type,omitempty"` // 广播类型（会话成员/全站）

	// ========== 路由信封（投递精确隔离，跨节点随消息体携带） ==========
	// ctx 路由元数据在异步队列消费时会丢失，故信封必须随消息体流转。
	// 入口层注入（InjectRoute），投递/跨节点/离线回放统一从 msg 取。
	// 隔离层次：AppID(应用) > Namespace(租户) > GroupID(平台) > UserID
	// 空 AppID = 全局共享（老部署兼容，不参与 appId 严格匹配过滤）
	AppID     string   `json:"app_id,omitempty"`    // 应用ID（最上层隔离维度，空=全局共享）
	Namespace string   `json:"namespace,omitempty"` // 命名空间ID（空=全局，已归一化时非空）
	GroupIDs  []string `json:"group_ids,omitempty"` // 群组ID列表（P2P 为 nil；单群组 len==1；多群组 len>1）

	// ========== 标志区（1 字节对齐字段集中末尾，零 padding） ==========
	DeliveryGuarantee   DeliveryGuarantee `json:"delivery_guarantee,omitempty"`    // 送达分级（必达/普通/高频流式；零值走决策树推导，详见 delivery_guarantee.go）
	RequireAck          bool              `json:"require_ack,omitempty"`           // 是否需要ACK确认
	SkipDatabaseStorage bool              `json:"skip_database_storage,omitempty"` // 是否跳过主数据库存储
	SkipSendToClient    bool              `json:"skip_send_to_client,omitempty"`   // 是否跳过发送到客户端
	// contains filtered or unexported fields
}

type HubStats struct {
	// 连接统计
	TotalClients     int64 `json:"total_clients"`     // 总客户端数
	WebSocketClients int64 `json:"websocket_clients"` // WebSocket客户端数
	SSEClients       int64 `json:"sse_clients"`       // SSE客户端数
	AgentConnections int64 `json:"agent_connections"` // 座席连接数

	// 消息统计
	MessagesSent     int64 `json:"messages_sent"`     // 已发送消息数
	MessagesReceived int64 `json:"messages_received"` // 已接收消息数
	BroadcastsSent   int64 `json:"broadcasts_sent"`   // 已发送广播数
	QueuedMessages   int   `json:"queued_messages"`   // 排队消息数

	// 其他统计
	OnlineUsers int   `json:"online_users"` // 在线用户数
	Uptime      int64 `json:"uptime"`       // 运行时间(秒)
}

type IDGenerator interface {
	GenerateTraceID() string
	GenerateSpanID() string
	GenerateRequestID() string
	GenerateCorrelationID() string
}

type KickUserResult struct {
	Success           bool // 是否成功执行（幂等：用户已不在线亦为 true）
	NotificationSent  bool // 踢出通知是否已写入发送通道（sendNotification=true 时）
	KickedConnections int  // 本节点触发注销的连接数（0=用户已不在线，幂等达成）
}

type MessageClassification struct {
	Type             MessageType      `json:"type"`
	Priority         MessagePriority  `json:"priority"`
	VIPLevel         VIPLevel         `json:"vip_level"`
	UrgencyLevel     UrgencyLevel     `json:"urgency_level"`
	BusinessCategory BusinessCategory `json:"business_category"`
	Timestamp        int64            `json:"timestamp"`
	UserID           string           `json:"user_id,omitempty"`
}

type MessagePriority int

type MessageRecordFilter struct {
	// Status 按状态查询（可选）
	Status *MessageSendStatus
	// Sender 按发送者查询（可选）
	Sender string
	// Receiver 按接收者查询（可选）
	Receiver string
	// NodeIP 按节点IP查询（可选）
	NodeIP string
	// ClientIP 按客户端IP查询（可选）
	ClientIP string
	// Limit 查询数量限制
	Limit int
	// OrderDesc 是否降序排序（默认降序，false为升序）
	OrderDesc bool
}

type MessageRecordKey struct {
	// MessageID 消息ID（全局唯一，群发场景同一消息的所有成员记录共享）
	MessageID string
	// Receiver 接收者ID（广播类记录为空串）
	Receiver string
}

type MessageSendRecord struct {
	ID            uint                           `gorm:"primaryKey;autoIncrement;comment:主键,唯一标识每条发送记录" json:"id"`                                        // 主键(唯一)
	SessionID     string                         `gorm:"column:session_id;size:255;not null;index;comment:会话ID" json:"session_id"`                        // 会话ID
	MessageID     string                         `gorm:"index:idx_message_id_receiver;size:255;not null;comment:业务消息ID,用于关联业务系统" json:"message_id"`       // 业务消息ID(可重复,支持多次发送记录)
	HubID         string                         `gorm:"index;size:255;not null;comment:Hub内部消息ID,用于ACK确认和日志追踪" json:"hub_id"`                            // Hub内部消息ID(可重复)
	Namespace     string                         `gorm:"index;size:128;not null;default:'';comment:命名空间,用于多租户/业务隔离" json:"namespace"`                     // 命名空间
	GroupID       string                         `gorm:"index;size:255;not null;default:'';comment:业务群组ID,P2P消息为空" json:"group_id"`                       // 业务群组ID
	MessageData   string                         `gorm:"type:text;comment:原始消息数据,类型为文本" json:"message_data"`                                              // 原始消息数据
	Sender        string                         `gorm:"index;size:255;comment:发送者ID" json:"sender"`                                                      // 发送者ID
	Receiver      string                         `gorm:"index:idx_message_id_receiver;size:255;comment:接收者ID" json:"receiver"`                            // 接收者ID
	MessageType   MessageType                    `gorm:"index;size:50;comment:消息类型" json:"message_type"`                                                  // 消息类型
	Source        MessageSource                  `gorm:"index;size:20;not null;default:'online';comment:消息来源(online/offline)" json:"source"`              // 消息来源
	NodeIP        string                         `gorm:"index;size:100;comment:服务器节点IP地址" json:"node_ip"`                                                 // 服务器节点IP地址
	ClientIP      string                         `gorm:"index;size:100;comment:客户端IP地址" json:"client_ip"`                                                 // 客户端IP地址
	Status        MessageSendStatus              `gorm:"index:idx_status_create_time;size:50;not null;default:'pending';comment:当前状态,不能为空" json:"status"` // 当前状态
	CreateTime    time.Time                      `gorm:"index:idx_status_create_time;not null;comment:创建时间" json:"create_time"`                           // 创建时间
	FirstSendTime *time.Time                     `gorm:"index;comment:首次发送时间" json:"first_send_time"`                                                     // 首次发送时间
	LastSendTime  *time.Time                     `gorm:"index;comment:最后发送时间" json:"last_send_time"`                                                      // 最后发送时间
	SuccessTime   *time.Time                     `gorm:"index;comment:成功时间" json:"success_time"`                                                          // 成功时间
	RetryCount    int                            `gorm:"default:0;comment:重试次数" json:"retry_count"`                                                       // 重试次数
	MaxRetry      int                            `gorm:"default:3;comment:最大重试次数" json:"max_retry"`                                                       // 最大重试次数
	FailureReason FailureReason                  `gorm:"size:50;comment:失败原因" json:"failure_reason"`                                                      // 失败原因
	ErrorMessage  string                         `gorm:"type:text;comment:错误信息,类型为文本" json:"error_message"`                                               // 错误信息
	RetryHistory  sqlbuilder.Slice[RetryAttempt] `gorm:"type:json;comment:重试历史,类型为JSON" json:"retry_history"`                                             // 重试历史
	ExpiresAt     *time.Time                     `gorm:"index;comment:过期时间" json:"expires_at"`                                                            // 过期时间
	Metadata      sqlbuilder.MapAny              `gorm:"type:json;comment:扩展元数据,类型为JSON" json:"metadata"`                                                 // 扩展元数据
	CustomFields  sqlbuilder.MapAny              `gorm:"type:json;comment:用户自定义字段,类型为JSON" json:"custom_fields"`                                          // 用户自定义字段
	Tags          sqlbuilder.StringSlice         `gorm:"type:json;comment:标签,类型为JSON" json:"tags"`                                                        // 标签
	ExtraData     string                         `gorm:"type:text;comment:额外数据,类型为文本" json:"extra_data"`                                                  // 额外数据
	CreatedAt     time.Time                      `gorm:"comment:记录创建时间" json:"created_at"`                                                                // 创建时间
	UpdatedAt     time.Time                      `gorm:"comment:记录最后更新时间" json:"updated_at"`                                                              // 最后更新时间
}

type MessageSendStatus string

type MessageSource string

type MessageStatus string

type MessageType string

type NamespaceObserverStats struct {
	Namespace     string               `json:"namespace"`      // 命名空间
	TotalUsers    int                  `json:"total_users"`    // 该命名空间下观察者用户数
	TotalDevices  int                  `json:"total_devices"`  // 该命名空间下观察者设备数
	GroupStats    []GroupObserverStats `json:"group_stats"`    // 按群组分组的观察者统计
	ObserverStats []*ObserverStats     `json:"observer_stats"` // 命名空间级（非群组级）观察者详细统计
}

type NodeConnectionStats struct {
	NodeID                string  `json:"node_id"`                 // 节点ID
	NodeIP                string  `json:"node_ip"`                 // 节点IP
	NodePort              int     `json:"node_port"`               // 节点端口
	TotalConnections      int64   `json:"total_connections"`       // 总连接数
	ActiveConnections     int64   `json:"active_connections"`      // 活跃连接数
	DisconnectedCount     int64   `json:"disconnected_count"`      // 已断开连接数
	AbnormalCount         int64   `json:"abnormal_count"`          // 异常断开数
	AbnormalRate          float64 `json:"abnormal_rate"`           // 异常断开率(%)
	TotalMessagesSent     int64   `json:"total_messages_sent"`     // 拆表后零填充
	TotalMessagesReceived int64   `json:"total_messages_received"` // 拆表后零填充
	TotalBytesSent        int64   `json:"total_bytes_sent"`        // 拆表后零填充
	TotalBytesReceived    int64   `json:"total_bytes_received"`    // 拆表后零填充
	TotalErrors           int64   `json:"total_errors"`            // 拆表后零填充
	ErrorRate             float64 `json:"error_rate"`              // 拆表后零填充
	AveragePingMs         float64 `json:"average_ping_ms"`         // 拆表后零填充
	MaxPingMs             float64 `json:"max_ping_ms"`             // 拆表后零填充
	MinPingMs             float64 `json:"min_ping_ms"`             // 拆表后零填充
	AverageDuration       float64 `json:"average_duration"`        // 平均连接时长(秒)
	TotalReconnects       int64   `json:"total_reconnects"`        // 拆表后零填充
	AverageReconnectCount float64 `json:"average_reconnect_count"` // 拆表后零填充
	ConnectionQuality     float64 `json:"connection_quality"`      // 拆表后零填充
}

type NodeInfo struct {
	ID          string     `json:"id"`
	IPAddress   string     `json:"ip_address"`
	Port        int        `json:"port"`
	Status      NodeStatus `json:"status"`
	LoadScore   float64    `json:"load_score"`
	LastSeen    time.Time  `json:"last_seen"`
	Connections int64      `json:"connections"`
}

type NodeStats struct {
	NodeID            string    `json:"node_id" redis:"-"`
	TotalConnections  int64     `json:"total_connections" redis:"total_connections"`
	ActiveConnections int64     `json:"active_connections" redis:"active_connections"`
	MessagesSent      int64     `json:"messages_sent" redis:"messages_sent"`
	MessagesReceived  int64     `json:"messages_received" redis:"messages_received"`
	BroadcastsSent    int64     `json:"broadcasts_sent" redis:"broadcasts_sent"`
	StartTime         int64     `json:"start_time" redis:"start_time"`
	LastHeartbeat     time.Time `json:"last_heartbeat" redis:"-"`
	Uptime            int64     `json:"uptime" redis:"-"` // 运行时间(秒),计算字段
}

type NodeStatus string

type ObserverManagerStats struct {
	TotalObservers      int                                `json:"total_observers"`      // 观察者用户总数
	TotalDevices        int                                `json:"total_devices"`        // 观察者设备总数
	TotalNotifications  int64                              `json:"total_notifications"`  // 总通知次数
	FailedNotifications int64                              `json:"failed_notifications"` // 失败通知次数
	DroppedMessages     int64                              `json:"dropped_messages"`     // 丢弃消息数（缓冲区满）
	NamespaceStats      map[string]*NamespaceObserverStats `json:"namespace_stats"`      // 按命名空间分组的观察者统计
}

type ObserverStats struct {
	ObserverID  string    `json:"observer_id"`
	ClientID    string    `json:"client_id"`
	Namespace   string    `json:"namespace"`          // 命名空间
	GroupID     string    `json:"group_id,omitempty"` // 群组ID（空=命名空间级观察者）
	ConnectedAt time.Time `json:"connected_at"`
	BufferSize  int       `json:"buffer_size"`
	BufferUsage int       `json:"buffer_usage"`
	IsConnected bool      `json:"is_connected"`
	UserType    string    `json:"user_type"`
	ClientType  string    `json:"client_type"`
}

type OfflineMessageRecord struct {
	ID             uint              `gorm:"primaryKey;autoIncrement;comment:主键,唯一标识离线消息记录" json:"id"`
	MessageID      string            `gorm:"column:message_id;size:64;not null;uniqueIndex:idx_message_app_ns_receiver;comment:业务消息ID" json:"message_id"`
	Sender         string            `gorm:"index;size:255;comment:发送者ID" json:"sender"`
	Receiver       string            `` /* 132-byte string literal not displayed */
	AppID          string            `` /* 219-byte string literal not displayed */
	Namespace      string            `` /* 172-byte string literal not displayed */
	GroupID        string            `` /* 136-byte string literal not displayed */
	SessionID      string            `gorm:"column:session_id;size:64;not null;index;comment:会话ID" json:"session_id"`
	CompressedData []byte            `gorm:"not null;comment:压缩完整的HubMessage JSON数据" json:"-"`
	Status         MessageSendStatus `gorm:"column:status;size:20;not null;default:'user_offline';index;comment:消息状态,复用MessageSendStatus" json:"status"`
	RetryCount     int               `gorm:"column:retry_count;default:0;comment:推送重试次数" json:"retry_count"`
	MaxRetry       int               `gorm:"column:max_retry;default:3;comment:最大重试次数" json:"max_retry"`
	ScheduledAt    time.Time         `gorm:"column:scheduled_at;not null;comment:消息计划发送的时间" json:"scheduled_at"`
	ExpireAt       time.Time         `gorm:"column:expire_at;not null;index;comment:消息过期时间" json:"expire_at"`
	FirstPushAt    *time.Time        `gorm:"column:first_push_at;index;comment:首次推送时间" json:"first_push_at,omitempty"`
	LastPushAt     *time.Time        `gorm:"column:last_push_at;index;comment:最后推送时间(成功或失败都更新)" json:"last_push_at,omitempty"`
	ErrorMessage   string            `gorm:"column:error_message;type:text;comment:推送失败的错误信息" json:"error_message,omitempty"`
	CreatedAt      time.Time         `gorm:"autoCreateTime;comment:记录创建时间" json:"created_at"`
	UpdatedAt      time.Time         `gorm:"autoUpdateTime;comment:记录最后更新时间" json:"updated_at"`
}

type OperationType string

type Priority string

type PriorityStats struct {
	Critical int `json:"critical"` // 关键优先级数量
	Urgent   int `json:"urgent"`   // 紧急优先级数量
	High     int `json:"high"`     // 高优先级数量
	Normal   int `json:"normal"`   // 普通优先级数量
	Low      int `json:"low"`      // 低优先级数量
	Total    int `json:"total"`    // 总数量
}

type PushType string

type QueueType string

type RetryAttempt struct {
	AttemptNumber int           `json:"attempt_number"` // 第几次重试
	Timestamp     time.Time     `json:"timestamp"`      // 重试时间
	Duration      time.Duration `json:"duration"`       // 本次重试耗时
	Error         string        `json:"error"`          // 错误信息
	Success       bool          `json:"success"`        // 是否成功
}

type SendAttempt struct {
	AttemptNumber int
	StartTime     time.Time
	Duration      time.Duration
	Error         error
	Success       bool
}

type SendResult struct {
	Success       bool
	Attempts      []SendAttempt
	TotalRetries  int
	TotalDuration time.Duration
	FinalError    error
	DeliveredAt   time.Time
	StoredOffline bool // 消息因用户离线而存储到离线队列（群组可靠投递据此分类在线/离线，避免预检查 N 次 Redis）
}

type Skill string

type StatsIncrementEntry struct {
	ConnectionID     string
	MessagesSent     int64
	MessagesReceived int64
	BytesSent        int64
	BytesReceived    int64
}

type TicketAssignedEvent struct {
	TicketID   string    `json:"ticket_id"`
	UserID     string    `json:"user_id"`
	AgentID    string    `json:"agent_id"`
	SessionID  string    `json:"session_id"`
	Priority   int       `json:"priority"`
	AssignedAt time.Time `json:"assigned_at"`
	NodeID     string    `json:"node_id"`
}

type TicketAssignedEventHandler func(event *TicketAssignedEvent) error

type TicketAssignmentFailedEvent struct {
	TicketID  string    `json:"ticket_id"`
	UserID    string    `json:"user_id"`
	SessionID string    `json:"session_id"`
	Reason    string    `json:"reason"`
	Timestamp time.Time `json:"timestamp"`
	NodeID    string    `json:"node_id"`
}

type TicketAssignmentFailedEventHandler func(event *TicketAssignmentFailedEvent) error

type TicketQueueEvent struct {
	TicketID  string    `json:"ticket_id"`
	UserID    string    `json:"user_id"`
	SessionID string    `json:"session_id"`
	Priority  int       `json:"priority"`
	Timestamp time.Time `json:"timestamp"`
	NodeID    string    `json:"node_id"`
}

type TicketQueueEventHandler func(event *TicketQueueEvent) error

type UrgencyLevel string

type UserConnectionStats struct {
	UserID            string     `json:"user_id"`
	IsActive          bool       `json:"is_active"`
	ConnectedAt       time.Time  `json:"connected_at"`
	DisconnectedAt    *time.Time `json:"disconnected_at,omitempty"`
	Duration          int64      `json:"duration"`
	ReconnectCount    int        `json:"reconnect_count"`    // 拆表后零填充
	ErrorCount        int        `json:"error_count"`        // 拆表后零填充
	MessagesSent      int64      `json:"messages_sent"`      // 拆表后零填充
	MessagesReceived  int64      `json:"messages_received"`  // 拆表后零填充
	AveragePingMs     float64    `json:"average_ping_ms"`    // 拆表后零填充
	ConnectionQuality float64    `json:"connection_quality"` // 拆表后零填充
}

type UserRole string

type UserStatus string

type UserStatusEvent struct {
	UserID    string      `json:"user_id"`
	UserType  UserType    `json:"user_type"`
	EventType EventStatus `json:"event_type"`
	Timestamp time.Time   `json:"timestamp"`
	NodeID    string      `json:"node_id"`
	ClientID  string      `json:"client_id,omitempty"` // 可选：客户端ID
}

type UserStatusEventHandler func(event *UserStatusEvent) error

type UserType string

type VIPLevel string

type WelcomeMessage struct {
	Title    string                 `json:"title"`    // 欢迎标题
	Content  string                 `json:"content"`  // 欢迎内容
	Data     map[string]interface{} `json:"data"`     // 扩展数据
	Priority Priority               `json:"priority"` // 消息优先级
}

type WelcomeMessageProvider interface {
	// GetWelcomeMessage 获取欢迎消息
	// 参数: userID 用户ID, userRole 用户角色, userType 用户类型, extraData 扩展数据
	// 返回: 欢迎消息内容, 是否启用欢迎消息, 错误信息
	GetWelcomeMessage(userID string, userRole UserRole, userType UserType, extraData map[string]interface{}) (*WelcomeMessage, bool, error)

	// RefreshConfig 刷新配置 - 当数据库配置更新时调用
	RefreshConfig() error
}

type WelcomeTemplate struct {
	Title       string                 `json:"title"`        // 欢迎标题
	Content     string                 `json:"content"`      // 欢迎内容
	MessageType MessageType            `json:"message_type"` // 消息类型
	Data        map[string]interface{} `json:"data"`         // 扩展数据
	Enabled     bool                   `json:"enabled"`      // 是否启用
	Variables   []string               `json:"variables"`    // 支持的变量列表，如: {user_name}, {time}
}

type WorkloadDimension string

type WorkloadInfo struct {
	AgentID      string    `json:"agent_id"`    // 客服ID
	Workload     int64     `json:"workload"`    // 当前工作负载
	LastUpdateAt time.Time `json:"last_update"` // 最后更新时间
}