quick-share/docs/04-消息协议与消息分发（统一Message模型）.md

04 - 消息协议与消息分发（统一 Message 模型）

功能目标

• 定义统一消息格式（便于扩展与兼容）。
• 服务端负责房间维度的消息广播/转发。
• 前端按 type 分发渲染与业务处理。

协议定义

基础消息格式

{
  "type": "TEXT | FILE | IMAGE | SYSTEM | CHUNK",
  "senderId": "uuid",
  "senderName": "用户昵称",
  "timestamp": 1706345600000,
  "payload": {}
}

文本消息（TEXT）

{
  "type": "TEXT",
  "senderId": "uuid",
  "senderName": "用户A",
  "timestamp": 1706345600000,
  "payload": {
    "content": "要传输的文本内容",
    "isChunk": false,
    "chunkIndex": 0,
    "totalChunks": 1
  }
}

文件元数据（FILE）

{
  "type": "FILE",
  "senderId": "uuid",
  "senderName": "用户A",
  "timestamp": 1706345600000,
  "payload": {
    "fileId": "uuid",
    "fileName": "document.pdf",
    "fileSize": 2621440,
    "mimeType": "application/pdf",
    "totalChunks": 10
  }
}

文件分片（CHUNK）

{
  "type": "CHUNK",
  "senderId": "uuid",
  "payload": {
    "fileId": "uuid",
    "chunkIndex": 0,
    "data": "base64EncodedChunkData"
  }
}

系统消息（SYSTEM）

{
  "type": "SYSTEM",
  "payload": {
    "event": "USER_JOIN | USER_LEAVE | ERROR",
    "message": "xxx 加入了房间",
    "userList": [{"id": "uuid", "name": "用户A"}]
  }
}

前端分发（Vue）

• 入口：RoomView 的 handleMessage(msg) 或等价逻辑。
• 分发规则（示例）
  • SYSTEM：更新 userList，并向消息列表追加系统提示。
  • TEXT：追加文本消息（区分 me/other）。
  • FILE：追加文件卡片（显示名称、大小、下载按钮、进度）。
  • CHUNK：写入文件缓存并更新进度；完成后合并为 Blob。

后端分发（Spring Boot）

• 控制器：WebSocketController
  • /message：广播常规消息到 /topic/room/{roomCode}
  • /file/chunk：转发分片到文件通道或同房间通道
• 补齐与校验（建议）
  • 服务端补齐 timestamp，必要时校验 type/payload 的字段完整性、大小限制与频率限制。

边界与注意点

• 通道设计一致性：若采用“文件独立 topic”，前端需额外 subscribe；若统一走房间 topic，需在 payload 内携带 fileId 并做路由分发。
• 大消息：避免一次性发送超大 payload；统一走分片策略。
• 安全：前端渲染文本必须转义，禁止把用户内容当 HTML 渲染。