quick-share/docs/01-整体架构与核心概念.md

01 - 整体架构与核心概念

目标与范围

• 目标：在 VNC/远程桌面、内网隔离等场景下，提供基于浏览器的轻量数据传输能力，通过 WebSocket 实现多端实时同步。
• 范围：文本、文件（分片）、图片预览、剪贴板读取/粘贴、在线用户列表、历史记录（本地）。

架构概览

发送端浏览器(Vue)  <——WebSocket(STOMP/SockJS)——>  服务端(Spring Boot)  <——>  接收端浏览器(Vue)
                                  │
                                  └—— 同一房间号(roomCode)隔离广播

核心概念

• 房间（Room）：数据传输隔离空间，通过 6 位数字 roomCode 标识。
• 会话（Session）：WebSocket 连接实例，通常以 sessionId 识别。
• 消息（Message）：传输数据单元，支持 TEXT/FILE/IMAGE/SYSTEM/CHUNK。

关键数据流

• 加入房间：客户端连接成功后发送 /app/room/{roomCode}/join → 服务端更新房间用户 → 广播 SYSTEM(USER_JOIN + userList) 到 /topic/room/{roomCode}。
• 发送消息：客户端发送 /app/room/{roomCode}/message（TEXT/FILE/IMAGE/SYSTEM）→ 服务端补齐时间戳并广播到 /topic/room/{roomCode}。
• 文件分片：客户端发送 /app/room/{roomCode}/file/chunk（CHUNK）→ 服务端转发到 /topic/room/{roomCode}/file/{fileId}（或同房间通道内约定字段分发）。

非功能性要求（NFR）

• 可用性：断线自动重连；重连后需重新 join。
• 性能：大文本/大文件分片；限制单文件大小与分片大小；避免 UI 卡顿（增量渲染/节流）。
• 安全：默认不落库；房间过期；XSS 防护；可选 WSS/Origin 校验。