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

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

## 协议定义
### 基础消息格式
```json
{
  "type": "TEXT | FILE | IMAGE | SYSTEM | CHUNK",
  "senderId": "uuid",
  "senderName": "用户昵称",
  "timestamp": 1706345600000,
  "payload": {}
}
```

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

### 文件元数据（FILE）
```json
{
  "type": "FILE",
  "senderId": "uuid",
  "senderName": "用户A",
  "timestamp": 1706345600000,
  "payload": {
    "fileId": "uuid",
    "fileName": "document.pdf",
    "fileSize": 2621440,
    "mimeType": "application/pdf",
    "totalChunks": 10
  }
}
```

### 文件分片（CHUNK）
```json
{
  "type": "CHUNK",
  "senderId": "uuid",
  "payload": {
    "fileId": "uuid",
    "chunkIndex": 0,
    "data": "base64EncodedChunkData"
  }
}
```

### 系统消息（SYSTEM）
```json
{
  "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 渲染。