quick-share/docs/06-文件传输（拖拽-分片-进度-下载）.md

06 - 文件传输（拖拽 / 分片 / 进度 / 下载）

功能目标

• 支持拖拽上传、粘贴文件、发送文件元数据与分片内容。
• 接收端显示进度并可下载（本地重组 Blob）。

前端（Vue）

• 入口组件
  • FileDropZone.vue：拖拽、粘贴；触发 file-selected 事件。
• 分片与发送
  • fileChunker.js：按 chunkSize 切片（文档示例：64KB）。
  • 发送流程：
    1. 生成 fileId
    2. 发送 FILE 元数据到 /app/room/{roomCode}/message
    3. 循环发送 CHUNK 到 /app/room/{roomCode}/file/chunk
• 进度显示（建议）
  • 发送端：sentChunks / totalChunks
  • 接收端：receivedChunks / totalChunks
  • 通过消息列表中的文件卡片展示（进度条 + 状态：接收中/完成/失败）。
• 接收与下载（建议实现方式）
  • 建立 fileId -> { meta, chunks[] } 缓存
  • 收到所有分片后，按顺序拼接为 Uint8Array/Blob
  • 使用 URL.createObjectURL(blob) 生成下载链接

后端（Spring Boot）

• 转发策略
  • 元数据：作为 FILE 消息广播到房间 topic。
  • 分片：作为 CHUNK 消息转发（可用独立 topic 或统一 topic）。
• 限制与风控（建议）
  • 单文件最大值（默认 100MB，可配置）。
  • 分片大小（默认 64KB，可配置）。
  • 频率限制（防止刷分片）。

协议与数据

• FILE.payload：fileId/fileName/fileSize/mimeType/totalChunks
• CHUNK.payload：fileId/chunkIndex/data(base64)

边界与注意点

• Base64 膨胀：Base64 会增加体积（约 33%），大文件会更慢；如需优化可改二进制 WebSocket（后续增强）。
• 并行多文件：以 fileId 隔离缓存即可并行；UI 需支持多文件卡片。
• 断线续传：当前协议未定义续传（可选增强：chunk ack / 断点续传）。