nl-im-service/internal/model/types.go

/**
 * package model
 * 作用：定义全系统通用的数据结构（PO 与 DTO）。
 * 规范：所有字段均采用 snake_case (下划线命名) 以保持 DB 和 JSON 的高度一致性。
 */
package model

import "time"

// ==========================================
// 数据库实体 (PO - Persistent Object)
// ==========================================

/**
 * ChatMessage
 * 对应数据库表：chat_messages
 * 作用：持久化存储聊天记录，包括文本、多媒体和信令状态。
 */
type ChatMessage struct {
	// 消息唯一标识 ID
	ID uint `gorm:"primaryKey;comment:消息唯一标识ID" json:"id"`
	// 房间ID，用于标识聊天室或会话
	RoomID string `gorm:"type:varchar(100);index;comment:房间ID" json:"room_id"`
	// 发送者用户ID
	SenderUserID string `gorm:"type:varchar(100);index;comment:发送者用户ID" json:"sender_user_id"`
	// 接收者用户ID
	ReceiverUserID string `gorm:"type:varchar(100);index;comment:接收者用户ID" json:"receiver_user_id"`
	// 消息类型 (0:文本, 1:图片, 2:音频, 3:视频, 4:处方, 5:病例, 6:视频通话, 7:语音通话, 8:文件)
	MessageType int `gorm:"type:int;comment:消息类型" json:"message_type"`
	// 消息内容或信令数据
	Content string `gorm:"type:text;comment:消息内容" json:"content"`
	// 存储富文本元数据（如URL预览信息的JSON字符串: {"title":"...","image":"..."}）
	Extra string `gorm:"type:text;comment:扩展字段，存储JSON格式的元数据" json:"extra"`
	// 通话时长(秒)，仅在通话类型的消息中有效
	Duration int `gorm:"type:int;comment:通话时长(秒)" json:"duration"`
	// 关联的通话ID (用于串联信令)
	CallID string `gorm:"type:varchar(100);index;comment:关联的通话ID" json:"call_id"`
	// 通话状态 (invite, accepted, ended, rejected, offer, answer, candidate, hangup, etc.)
	CallStatus string `gorm:"type:varchar(50);comment:通话状态" json:"call_status"`
	// 创建时间，自动生成
	CreatedAt time.Time `gorm:"autoCreateTime;comment:创建时间" json:"created_at"`
}

// ==========================================
// 交互数据传输对象 (DTO - Data Transfer Object)
// ==========================================

/**
 * WsPayload
 * 作用：WebSocket 传输的最外层通用载荷。
 * 逻辑：根据 RequestType 字段决定如何解析 Data。
 */
type WsPayload struct {
	// 请求类型: "bind", "heartbeat", "send_message", "receive_message"
	RequestType string `json:"request_type"`
	// 具体数据载荷，结构取决于 RequestType
	Data interface{} `json:"data"`
}

/**
 * SendMessageReq
 * 作用：客户端发送消息或信令的请求参数结构。
 */
type SendMessageReq struct {
	// [新增] 发送端的 WebSocket ClientID，用于在多端同步时排除自己
	SenderClientID string `json:"sender_client_id,omitempty"`

	// 指定目标客户端ID (选填，用于点对点精确控制)
	TargetClientID string `json:"target_client_id,omitempty"`
	// 指定目标用户ID (选填，用于发送给用户的所有设备)
	ReceiverUserID string `json:"receiver_user_id,omitempty"`
	// 房间ID
	RoomID string `json:"room_id"`
	// 消息类型
	MessageType int `json:"message_type"`
	// 内容
	Content string `json:"content"`
	// 时长
	Duration int `json:"duration"`

	// WebRTC 信令专用字段: 通话唯一ID
	CallID string `json:"call_id,omitempty"`
	// WebRTC 信令专用字段: 信令状态 (invite, offer, answer, candidate, hangup)
	CallStatus string `json:"call_status,omitempty"`
}

/**
 * UrlMeta
 * 作用：URL 预览元数据结构 (存储在 Extra 字段中)
 */
type UrlMeta struct {
	// 标题
	Title string `json:"title"`
	// 描述
	Description string `json:"description"`
	// 图片链接
	Image string `json:"image"`
	// 原始URL
	Url string `json:"url"`
}

/**
 * BindReq
 * 作用：用户绑定请求参数。
 */
type BindReq struct {
	// 用户ID
	UserID string `json:"user_id"`
	// WebSocket握手后获得的临时ID
	ClientID string `json:"client_id"`
}

/**
 * ICEServerConfig
 * 作用：返回给前端的 TURN/STUN 配置信息。
 */
type ICEServerConfig struct {
	// TURN服务器地址列表
	Urls []string `json:"urls"`
	// 鉴权用户名
	Username string `json:"username,omitempty"`
	// 鉴权密码
	Credential string `json:"credential,omitempty"`
}

/**
 * UserContact
 * 作用：模拟联系人结构
 */
type UserContact struct {
	// 用户唯一ID
	ID string `json:"id"`
	// 用户名称
	Name string `json:"name"`
	// 用户头像URL或字符
	Avatar string `json:"avatar"`
	// 用户描述或签名
	Desc string `json:"desc"`
}

/**
 * ClusterMessage
 * 作用：内部通信，Redis Pub/Sub 集群消息转发结构。
 */
type ClusterMessage struct {
	// 发出该消息的源节点ID
	SenderNodeID string `json:"sender_node_id"`
	// 目标用户ID
	TargetUserID string `json:"target_user_id"`
	// 原始消息体 (WsPayload)
	Payload interface{} `json:"payload"`
}

// ==========================================
// 常量定义
// ==========================================

const (
	// Redis Key 前缀: 用户所在节点映射 (Hash结构或String结构)
	KeyUserNodeMap = "ws:user:node:"
	// Redis Channel: 集群广播频道
	ChanClusterBroadcast = "ws:cluster:broadcast"
)