From 1a6a7369b95797bf0496a6220be9bfdb7bc89824 Mon Sep 17 00:00:00 2001
From: MatrixSeven <hacker.kill07@gmail.com>
Date: Sun, 1 Mar 2026 00:08:29 +0800
Subject: [PATCH] =?UTF-8?q?=E6=96=B0=E5=A2=9E=E6=88=BF=E9=97=B4=E9=AA=8C?=
 =?UTF-8?q?=E8=AF=81=E5=B7=A5=E5=85=B7=E5=87=BD=E6=95=B0=EF=BC=8C=E5=8C=85?=
 =?UTF-8?q?=E5=90=AB=E6=88=BF=E9=97=B4=E4=BB=A3=E7=A0=81=E6=A0=BC=E5=BC=8F?=
 =?UTF-8?q?=E9=AA=8C=E8=AF=81=E5=92=8C=E6=88=BF=E9=97=B4=E7=8A=B6=E6=80=81?=
 =?UTF-8?q?=E6=A3=80=E6=9F=A5=E9=80=BB=E8=BE=91?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ARCHITECTURE.md                               |  737 ++++++++++
 FRONTEND_ANALYSIS.md                          |  471 +++++++
 PROTOCOL_ANALYSIS.md                          | 1237 +++++++++++++++++
 .../src/components/WebRTCConnectionStatus.tsx |  185 ---
 .../src/components/WebRTCFileTransfer.tsx     |  348 +----
 .../webrtc/WebRTCDesktopReceiver.tsx          |  106 +-
 .../components/webrtc/WebRTCFileReceive.tsx   |   53 +-
 .../components/webrtc/WebRTCFileUpload.tsx    |   11 +-
 .../components/webrtc/WebRTCTextReceiver.tsx  |   34 +-
 chuan-next/src/hooks/connection/index.ts      |    1 -
 .../hooks/connection/useConnectionState.ts    |  137 --
 .../src/hooks/connection/useRoomConnection.ts |   65 +-
 .../connection/useSharedWebRTCManager.ts      |   38 +-
 .../connection/useWebRTCConnectionCore.ts     |    2 +-
 .../connection/useWebRTCDataChannelManager.ts |    2 +-
 .../hooks/connection/useWebRTCStateManager.ts |   78 --
 .../hooks/connection/useWebRTCTrackManager.ts |    2 +-
 .../hooks/file-transfer/useFileListSync.ts    |   10 +-
 .../file-transfer/useFileStateManager.ts      |   10 +-
 .../file-transfer/useFileTransferBusiness.ts  |   11 +-
 chuan-next/src/hooks/ui/webRTCStore.ts        |   22 +-
 chuan-next/src/lib/api-utils.ts               |  144 --
 chuan-next/src/lib/client-api.ts              |  119 --
 chuan-next/src/lib/room-utils.ts              |   94 ++
 chuan-next/src/types/index.ts                 |   21 +-
 25 files changed, 2697 insertions(+), 1241 deletions(-)
 create mode 100644 ARCHITECTURE.md
 create mode 100644 FRONTEND_ANALYSIS.md
 create mode 100644 PROTOCOL_ANALYSIS.md
 delete mode 100644 chuan-next/src/components/WebRTCConnectionStatus.tsx
 delete mode 100644 chuan-next/src/hooks/connection/useConnectionState.ts
 delete mode 100644 chuan-next/src/hooks/connection/useWebRTCStateManager.ts
 delete mode 100644 chuan-next/src/lib/api-utils.ts
 delete mode 100644 chuan-next/src/lib/client-api.ts
 create mode 100644 chuan-next/src/lib/room-utils.ts

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
new file mode 100644
index 0000000..e73f3ca
--- /dev/null
+++ b/ARCHITECTURE.md
@@ -0,0 +1,737 @@
+# 文件快传（Chuan）— 系统架构与技术设计文档
+
+> 最后更新：2025-08-02
+
+---
+
+## 一、项目总览
+
+**文件快传（Chuan）** 是一个基于 **WebRTC P2P** 的文件传输应用。核心设计理念：**所有实际数据（文件、文字、桌面画面）均通过 WebRTC 点对点直传，服务器仅承担信令中继和房间管理职责**。
+
+### 技术栈
+
+| 层级 | 技术选型 |
+|------|---------|
+| 后端 | Go 1.21 · chi/v5 路由 · gorilla/websocket |
+| 前端 | Next.js 15 · React 19 · TypeScript · Tailwind CSS 4 |
+| 状态管理 | Zustand 5 + React useState/useRef |
+| UI 组件 | shadcn/ui (Radix UI) · Lucide Icons |
+| P2P 通信 | WebRTC DataChannel（文件/文字）· MediaStream（桌面共享）|
+| 部署 | 双模式：Next.js 开发模式 / Go 嵌入前端静态文件 |
+
+### 核心特性
+
+| 功能 | 实现方式 |
+|------|---------|
+| 文件传输 | WebRTC DataChannel · 256KB 分块 · CRC32 校验 · ACK 确认 |
+| 文本消息 | WebRTC DataChannel · 实时双向同步 · 打字状态 |
+| 桌面共享 | WebRTC MediaStream · getDisplayMedia · renegotiation |
+| ICE 配置 | 默认 5 个 STUN · 支持自定义 STUN/TURN · localStorage 持久化 |
+
+---
+
+## 二、系统架构
+
+### 2.1 整体架构图
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│                        Go 后端 (:8080)                               │
+│  ┌──────────────┐  ┌───────────────────┐  ┌─────────────────────┐  │
+│  │  REST API     │  │  WebSocket 信令    │  │  静态文件服务        │  │
+│  │  /api/*       │  │  /api/ws/webrtc   │  │  go:embed frontend  │  │
+│  │               │  │  /ws/webrtc       │  │                     │  │
+│  │ - create-room │  │                   │  │  SPA 回退 index.html │  │
+│  │ - room-info   │  │  纯中继 转发消息   │  │                     │  │
+│  └──────────────┘  └───────────────────┘  └─────────────────────┘  │
+│                              │                                       │
+│              ┌───────────────┼───────────────┐                       │
+│              │   内存房间管理  (sync.RWMutex)  │                       │
+│              │   map[string]*WebRTCRoom       │                       │
+│              │   1小时过期 · 5分钟定时清理     │                       │
+│              └───────────────────────────────┘                       │
+└──────────────────────────────────────────────────────────────────────┘
+        │ WebSocket                                    │ WebSocket
+        │ (信令: offer/answer/ice-candidate)            │
+        ▼                                              ▼
+┌───────────────┐          WebRTC P2P          ┌───────────────┐
+│  发送方浏览器   │ ◄══════════════════════════► │  接收方浏览器   │
+│               │   DataChannel (文件/文字)      │               │
+│  Next.js App  │   MediaStream (桌面共享)       │  Next.js App  │
+└───────────────┘                              └───────────────┘
+```
+
+### 2.2 数据流向
+
+```
+1. 控制平面 (HTTP):  浏览器 ──── REST API ────→ Go 后端    (房间创建/查询)
+2. 信令平面 (WS):    浏览器 ←──── WebSocket ──→ Go 后端    (SDP/ICE 交换)
+3. 数据平面 (P2P):   浏览器 ◄═══ DataChannel ══► 浏览器     (文件/文字直传)
+4. 媒体平面 (P2P):   浏览器 ◄═══ MediaStream ══► 浏览器     (桌面画面直传)
+```
+
+**关键设计：数据平面完全绕过服务器，文件和文字内容不经服务器中转。**
+
+---
+
+## 三、后端设计
+
+### 3.1 目录结构
+
+```
+cmd/
+├── main.go          # 入口：参数解析 → 配置 → 路由 → 启动服务器
+├── config.go        # 配置管理：命令行 > 环境变量 > .chuan.env > 默认值
+├── router.go        # chi 路由注册 + 中间件 + 前端静态服务
+└── server.go        # HTTP Server 封装 + 优雅关闭 (SIGINT/SIGTERM)
+
+internal/
+├── handlers/
+│   └── handlers.go  # HTTP/WebSocket 请求处理（薄层，委托给 service）
+├── models/
+│   └── models.go    # 数据模型：WebRTCRoom、WebRTCClient、RoomStatus
+├── services/
+│   └── webrtc_service.go  # 核心信令服务：房间管理 + WebSocket 消息转发
+└── web/
+    └── frontend.go  # go:embed 嵌入前端 + SPA 回退
+```
+
+### 3.2 API 端点
+
+| 方法 | 路径 | 功能 | 请求/响应 |
+|------|------|------|-----------|
+| `POST` | `/api/create-room` | 创建房间 | `{}` → `{success, code, message}` |
+| `GET` | `/api/room-info?code=XXX` | 查询房间状态 | → `{success, status: RoomStatus}` |
+| `GET` | `/api/webrtc-room-status?code=XXX` | 同上（别名）| 同上 |
+| `WS` | `/api/ws/webrtc?code=&role=` | WebRTC 信令 | WebSocket 双向 |
+| `WS` | `/ws/webrtc?code=&role=` | 同上（兼容路径）| 同上 |
+| `GET` | `/*` | 前端静态文件 | SPA 回退 |
+
+### 3.3 房间管理
+
+- **房间代码**：6 位，字符集 `123456789ABCDEFGHIJKLMNPQRSTUVWXYZ`（排除 0 和 O，避免混淆）
+- **房间容量**：最多 2 人（1 sender + 1 receiver）
+- **过期策略**：创建后 1 小时过期，每 5 分钟后台清理
+- **存储方式**：纯内存 `map[string]*WebRTCRoom` + `sync.RWMutex`，无数据库
+
+### 3.4 WebSocket 信令协议
+
+#### 连接 URL
+```
+ws[s]://host/api/ws/webrtc?code=ROOM_CODE&role=sender|receiver&channel=shared
+```
+
+#### 服务端 → 客户端
+
+| type | payload | 触发时机 |
+|------|---------|---------|
+| `peer-joined` | `{ role }` | 对方加入房间 |
+| `disconnection` | `{ role, message }` | 对方断开连接 |
+| `error` | `{ message }` | 房间不存在 / 已满 / 参数无效 |
+
+#### 客户端 ↔ 客户端（经服务端纯转发）
+
+| type | payload | 说明 |
+|------|---------|------|
+| `offer` | `RTCSessionDescription` | SDP Offer |
+| `answer` | `RTCSessionDescription` | SDP Answer |
+| `ice-candidate` | `RTCIceCandidate` | ICE 候选地址 |
+
+**服务端对 offer/answer/ice-candidate 消息不做任何解析，仅中继转发给房间内另一方。**
+
+---
+
+## 四、前端设计（重点）
+
+### 4.1 目录结构
+
+```
+chuan-next/src/
+├── app/                            # Next.js App Router
+│   ├── page.tsx                    # 入口页（SSG）
+│   ├── layout.tsx                  # 根布局（字体、Toast、Umami 统计）
+│   ├── globals.css                 # 全局样式 + 动画定义
+│   ├── HomePage.tsx                # 主页面组件（Tab 管理 + WebRTC 状态）
+│   ├── HomePageWrapper.tsx         # Suspense 包裹（SSR 兼容）
+│   └── api/                        # Next.js API Routes（开发模式代理）
+│       ├── create-room/route.ts    # → GO_BACKEND_URL/api/create-room
+│       ├── room-info/route.ts      # → GO_BACKEND_URL/api/room-info
+│       ├── room-status/route.ts    # → GO_BACKEND_URL/api/room-status
+│       ├── create-text-room/route.ts
+│       ├── get-text-content/route.ts
+│       └── update-files/route.ts
+│
+├── components/                     # UI 组件
+│   ├── WebRTCFileTransfer.tsx      # 文件传输整合组件（659行）
+│   ├── WebRTCTextImageTransfer.tsx # 文字+图片传输整合组件
+│   ├── DesktopShare.tsx            # 桌面共享整合组件
+│   ├── Hero.tsx                    # 页头（标题、GitHub 链接）
+│   ├── webrtc/                     # WebRTC 功能子组件
+│   │   ├── WebRTCFileUpload.tsx    # 文件发送 UI
+│   │   ├── WebRTCFileReceive.tsx   # 文件接收 UI
+│   │   ├── WebRTCTextSender.tsx    # 文字发送 UI
+│   │   ├── WebRTCTextReceiver.tsx  # 文字接收 UI
+│   │   ├── WebRTCDesktopSender.tsx # 桌面共享发送 UI
+│   │   ├── WebRTCDesktopReceiver.tsx # 桌面共享接收 UI
+│   │   └── WebRTCSettings.tsx      # ICE 服务器配置 UI
+│   └── ui/                         # 基础 UI 组件 (shadcn/ui)
+│       ├── button.tsx              # 按钮（6种 variant）
+│       ├── tabs.tsx                # 标签页（Radix Tabs）
+│       ├── input.tsx               # 输入框
+│       ├── card.tsx                # 卡片
+│       ├── dialog.tsx              # 对话框
+│       ├── progress.tsx            # 进度条
+│       ├── textarea.tsx            # 文本域
+│       ├── toast.tsx               # Toast (Radix)
+│       ├── toast-simple.tsx        # 轻量 Toast (自定义)
+│       ├── toaster.tsx             # Toast 渲染
+│       └── confirm-dialog.tsx      # 确认对话框
+│
+├── hooks/                          # 自定义 Hooks（核心逻辑层）
+│   ├── index.ts                    # 统一导出
+│   ├── connection/                 # WebRTC 连接管理
+│   │   ├── useSharedWebRTCManager.ts      # 整合入口
+│   │   ├── useWebRTCConnectionCore.ts     # 核心连接（WS + PeerConnection）
+│   │   ├── useWebRTCDataChannelManager.ts # DataChannel 管理 + 消息路由
+│   │   ├── useWebRTCTrackManager.ts       # MediaStream 轨道管理
+│   │   ├── useWebRTCStateManager.ts       # Zustand store 封装
+│   │   ├── useRoomConnection.ts           # 加入房间逻辑
+│   │   ├── useConnectionState.ts          # 连接状态变化处理
+│   │   └── useWebRTCSupport.ts            # 浏览器 WebRTC 检测
+│   ├── file-transfer/              # 文件传输业务
+│   │   ├── useFileTransferBusiness.ts     # 核心：分块传输 + CRC32 + ACK
+│   │   ├── useFileListSync.ts             # 文件列表实时同步
+│   │   └── useFileStateManager.ts         # 文件状态（选中/下载/进度）
+│   ├── text-transfer/              # 文字传输业务
+│   │   └── useTextTransferBusiness.ts     # 实时文字同步 + 打字状态
+│   ├── desktop-share/              # 桌面共享业务
+│   │   └── useDesktopShareBusiness.ts     # getDisplayMedia + 轨道管理
+│   ├── settings/                   # 设置
+│   │   ├── useIceServersConfig.ts         # ICE 服务器配置 + localStorage
+│   │   └── useWebRTCConfigSync.ts         # 配置变更监听
+│   └── ui/                         # UI 相关
+│       ├── webRTCStore.ts                 # Zustand 全局状态
+│       ├── useURLHandler.ts               # URL 参数管理
+│       ├── useTabNavigation.ts            # Tab 切换管理
+│       └── useConfirmDialog.ts            # 确认对话框 Hook
+│
+├── lib/                            # 工具库
+│   ├── config.ts                   # 环境配置（API URL / WS URL 动态计算）
+│   ├── utils.ts                    # cn() 样式合并
+│   ├── client-api.ts               # ClientAPI 封装
+│   ├── api-utils.ts                # apiFetch() 统一请求
+│   └── webrtc-support.ts           # WebRTC 支持检测
+│
+└── types/
+    └── index.ts                    # 全局类型定义
+```
+
+### 4.2 组件层次结构
+
+```
+RootLayout (layout.tsx)
+  └─ ToastProvider (toast-simple.tsx)
+       └─ HomePageWrapper (Suspense)
+            └─ HomePage
+                 ├─ Hero                           # 页头
+                 ├─ WebRTCUnsupportedModal          # WebRTC 不支持提示
+                 ├─ ConfirmDialog                   # Tab 切换确认
+                 └─ Tabs (5个标签)
+                      │
+                      ├─ [Tab: webrtc] WebRTCFileTransfer
+                      │    ├─ 模式切换 (发送/接收)
+                      │    ├─ [发送模式] WebRTCFileUpload
+                      │    │    ├─ 拖拽上传区域 / 文件列表
+                      │    │    ├─ RoomInfoDisplay (取件码 + 二维码 + 复制)
+                      │    │    ├─ ConnectionStatus (连接状态)
+                      │    │    └─ 传输进度条
+                      │    └─ [接收模式] WebRTCFileReceive
+                      │         ├─ 取件码输入 (6位)
+                      │         ├─ ConnectionStatus (连接状态)
+                      │         └─ 文件列表 + 下载按钮
+                      │
+                      ├─ [Tab: message] WebRTCTextImageTransfer
+                      │    ├─ 模式切换 (发送/接收)
+                      │    ├─ [发送模式] WebRTCTextSender
+                      │    │    ├─ Textarea 编辑器
+                      │    │    ├─ 图片发送按钮
+                      │    │    └─ RoomInfoDisplay
+                      │    └─ [接收模式] WebRTCTextReceiver
+                      │         ├─ 取件码输入
+                      │         └─ 实时文字显示 + 图片接收
+                      │
+                      ├─ [Tab: desktop] DesktopShare
+                      │    ├─ 模式切换 (共享/查看)
+                      │    ├─ [共享模式] WebRTCDesktopSender
+                      │    │    └─ 选择屏幕 → 开始共享
+                      │    └─ [查看模式] WebRTCDesktopReceiver
+                      │         └─ DesktopViewer (video 标签)
+                      │
+                      ├─ [Tab: wechat] WeChatGroup
+                      │    └─ 微信群二维码
+                      │
+                      └─ [Tab: settings] WebRTCSettings
+                           └─ ICE 服务器配置表单
+```
+
+### 4.3 Hooks 架构（核心设计）
+
+前端逻辑层采用 **分层 Hooks 架构**，自底向上组合：
+
+```
+                    ┌─────────────────────────────┐
+                    │    Zustand Store             │  ← 最底层：全局状态
+                    │    (webRTCStore.ts)           │
+                    │    isConnected, isConnecting  │
+                    │    currentRoom, error         │
+                    └──────────────┬──────────────┘
+                                   │
+            ┌──────────────────────┼──────────────────────┐
+            │                      │                      │
+   ┌────────▼────────┐  ┌─────────▼──────────┐  ┌───────▼─────────┐
+   │ StateManager     │  │ DataChannelManager  │  │ TrackManager     │
+   │ (Zustand 封装)    │  │ (消息路由 + 收发)    │  │ (媒体轨道管理)    │
+   └────────┬────────┘  └─────────┬──────────┘  └───────┬─────────┘
+            │                      │                      │
+            └──────────────────────┼──────────────────────┘
+                                   │
+                    ┌──────────────▼──────────────┐
+                    │ ConnectionCore               │  ← WebSocket + PeerConnection
+                    │ (useWebRTCConnectionCore)     │     信令处理 + ICE 交换
+                    └──────────────┬──────────────┘
+                                   │
+                    ┌──────────────▼──────────────┐
+                    │ SharedWebRTCManager          │  ← 整合入口（4合1）
+                    │ (useSharedWebRTCManager)      │     返回统一 WebRTCConnection
+                    └──────────────┬──────────────┘
+                                   │
+          ┌────────────────────────┼────────────────────────┐
+          │                        │                        │
+ ┌────────▼────────┐   ┌──────────▼──────────┐   ┌────────▼────────┐
+ │ FileTransfer     │   │ TextTransfer         │   │ DesktopShare     │
+ │ Business         │   │ Business             │   │ Business         │
+ │ (文件分块+校验)    │   │ (实时同步文字)         │   │ (屏幕采集+推流)    │
+ └────────┬────────┘   └──────────┬──────────┘   └────────┬────────┘
+          │                        │                        │
+          └────────────────────────┼────────────────────────┘
+                                   │
+                    ┌──────────────▼──────────────┐
+                    │ 业务级组件 (TSX)              │
+                    │ WebRTCFileTransfer.tsx 等     │
+                    └─────────────────────────────┘
+```
+
+#### 4.3.1 连接层 — `useWebRTCConnectionCore`
+
+**职责**：管理 WebSocket 信令连接 + RTCPeerConnection 生命周期。
+
+```
+connect(code, role)
+    │
+    ├─ 1. WebSocket 连接到 ws://host/api/ws/webrtc?code=XXX&role=YYY
+    │
+    ├─ 2. 收到 "peer-joined" → 创建 RTCPeerConnection
+    │      └─ ICE 服务器从 getIceServersConfig() 获取
+    │
+    ├─ 3. Sender 创建 DataChannel → 创建 Offer
+    │      Receiver 等待 ondatachannel
+    │
+    ├─ 4. offer/answer/ice-candidate 通过 WebSocket 交换
+    │
+    ├─ 5. ICE 连接建立 → DataChannel open → 连接完成
+    │
+    └─ 6. 断开时：发送 disconnection → 清理 PeerConnection
+```
+
+#### 4.3.2 数据通道层 — `useWebRTCDataChannelManager`
+
+**职责**：管理 DataChannel 消息的路由分发。
+
+**核心设计：多 channel 路由**
+
+所有 JSON 消息通过 `channel` 字段路由到不同的业务处理器：
+
+```typescript
+// 消息格式
+{
+  channel: "file-transfer" | "text-transfer" | "desktop-share",
+  type: "具体消息类型",
+  payload: { ... }
+}
+```
+
+```
+DataChannel.onmessage
+    │
+    ├─ typeof data === 'string' → JSON.parse
+    │   ├─ channel === 'file-transfer' → fileTransferHandler
+    │   ├─ channel === 'text-transfer' → textTransferHandler
+    │   └─ channel === 'desktop-share' → desktopShareHandler
+    │
+    └─ typeof data === ArrayBuffer → 二进制数据
+        └─ 优先路由到 'file-transfer' handler（文件块数据）
+```
+
+**注意**：三个功能（文件/文字/桌面）共享同一个 DataChannel（`shared-channel`），而非各自创建独立通道。
+
+#### 4.3.3 轨道管理层 — `useWebRTCTrackManager`
+
+**职责**：管理 MediaStream 轨道（仅桌面共享使用）。
+
+- `addTrack(track, stream)` — 添加视频/音频轨道
+- `removeTrack(sender)` — 移除轨道
+- `createOfferNow()` — 添加轨道后触发重协商
+- `onTrack` 回调 — 接收远程媒体流
+
+### 4.4 状态管理设计
+
+采用 **三层状态模型**：
+
+| 层级 | 技术 | 用途 | 示例 |
+|------|------|------|------|
+| 全局共享状态 | Zustand | WebRTC 连接状态 | `isConnected`, `currentRoom`, `error` |
+| 组件级状态 | React useState | UI 交互状态 | `selectedFiles`, `mode`, `progress` |
+| 引用状态 | React useRef | 回调/缓冲区/定时器 | `receiveBufferRef`, `messageHandlers`, 防抖 timer |
+
+#### Zustand Store 结构
+
+```typescript
+interface WebRTCState {
+  // 连接状态
+  isConnected: boolean;       // 总体连接状态
+  isConnecting: boolean;      // 正在连接中
+  isWebSocketConnected: boolean;  // WebSocket 层连接
+  isPeerConnected: boolean;   // PeerConnection 层连接
+
+  // 错误状态
+  error: string | null;
+  canRetry: boolean;
+
+  // 房间信息
+  currentRoom: { code: string; role: 'sender' | 'receiver' } | null;
+
+  // Actions
+  updateState(partial: Partial<WebRTCState>): void;
+  setCurrentRoom(room: { code: string; role: string } | null): void;
+  resetToInitial(): void;
+}
+```
+
+### 4.5 文件传输详细设计
+
+#### 4.5.1 DataChannel 消息协议
+
+**file-transfer channel 消息类型：**
+
+| 方向 | type | payload | 说明 |
+|------|------|---------|------|
+| S→R | `file-list` | `FileInfo[]` | 发送方文件列表（实时同步） |
+| R→S | `file-request` | `{ fileId, fileName }` | 接收方请求下载 |
+| S→R | `file-metadata` | `{ id, name, size, type }` | 文件元信息 |
+| S→R | `file-chunk-info` | `{ fileId, chunkIndex, totalChunks, checksum }` | 块元信息（含 CRC32） |
+| S→R | *(二进制)* | `ArrayBuffer` (≤256KB) | 文件块数据 |
+| R→S | `file-chunk-ack` | `{ fileId, chunkIndex, success, checksum }` | 块确认（含校验结果） |
+| S→R | `file-complete` | `{ fileId }` | 文件传输完成 |
+
+#### 4.5.2 传输参数
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| 块大小 | 256 KB | 每个 chunk 的最大字节数 |
+| 最大重试 | 5 次 | 单个 chunk 校验失败后的重试上限 |
+| 退避策略 | 指数退避 | 重试间隔指数增长 |
+| 校验算法 | CRC32 | 每个 chunk 独立校验 |
+| 流控 | 自适应 | 根据平均传输速度动态调整发送间隔 |
+| DataChannel 配置 | `ordered: true, maxRetransmits: 3` | 有序可靠传输 |
+
+#### 4.5.3 完整传输时序
+
+```
+发送方                              信令服务器                           接收方
+  │                                     │                                 │
+  │  1. POST /api/create-room           │                                 │
+  │ ──────────────────────────────────► │                                 │
+  │ ◄── {success: true, code: "AB12CD"} │                                 │
+  │                                     │                                 │
+  │  2. WS connect (role=sender)        │                                 │
+  │ ═══════════════════════════════════► │                                 │
+  │                                     │                                 │
+  │                                     │  3. GET /api/room-info?code=... │
+  │                                     │ ◄────────────────────────────── │
+  │                                     │ ── {success, status} ─────────► │
+  │                                     │                                 │
+  │                                     │  4. WS connect (role=receiver)  │
+  │                                     │ ◄═══════════════════════════════ │
+  │                                     │                                 │
+  │  5. ◄── peer-joined ──             │  ── peer-joined ──►             │
+  │                                     │                                 │
+  │  6. 创建 PeerConnection + DataChannel                                 │
+  │  7. 创建 SDP Offer                                                    │
+  │  ═══ offer ═══════════════════════► │ ═══ offer ═══════════════════► │
+  │                                     │                                 │
+  │                                     │  8. 创建 PeerConnection         │
+  │                                     │  9. 设置 Remote/Local SDP       │
+  │  ◄═══ answer ══════════════════════ │ ◄═══ answer ═════════════════ │
+  │                                     │                                 │
+  │  10. ICE Candidate 交换 ◄═══════════╋══════════════════════════════► │
+  │                                     │                                 │
+  │  ══════════ DataChannel OPEN ═══════╪══════════════════════════════ │
+  │                                     │                                 │
+  │  11. file-list ─────────────────────┼────────────────────────────────► │
+  │      [{id, name, size, type}, ...]  │                                 │
+  │                                     │                                 │
+  │  ◄─────────────────────────────────┼──── 12. file-request ────────── │
+  │      {fileId, fileName}             │                                 │
+  │                                     │                                 │
+  │  13. file-metadata ────────────────┼────────────────────────────────► │
+  │      {id, name, size, type}         │                                 │
+  │                                     │                                 │
+  │  ╔══ 循环每个 chunk ═══════════════╪════════════════════════════════╗ │
+  │  ║  14. file-chunk-info ───────────┼──────────────────────────────► ║ │
+  │  ║      {fileId, chunkIndex,        │                              ║ │
+  │  ║       totalChunks, checksum}     │                              ║ │
+  │  ║                                  │                              ║ │
+  │  ║  15. [ArrayBuffer 256KB] ───────┼──────────────────────────────► ║ │
+  │  ║                                  │                              ║ │
+  │  ║  ◄───────────────────────────────┼── 16. file-chunk-ack ─────── ║ │
+  │  ║      {fileId, chunkIndex,        │      success, checksum}      ║ │
+  │  ║                                  │                              ║ │
+  │  ║  [如果 success=false, 指数退避重试，最多5次]                      ║ │
+  │  ╚══════════════════════════════════╪══════════════════════════════╝ │
+  │                                     │                                 │
+  │  17. file-complete ────────────────┼────────────────────────────────► │
+  │      {fileId}                       │                                 │
+  │                                     │                   18. 组装 Blob  │
+  │                                     │                       → File   │
+  │                                     │                       → 下载    │
+```
+
+#### 4.5.4 文件列表同步机制
+
+发送方选择文件后，文件列表会 **实时同步** 到接收方：
+
+```
+发送方文件变更 → useFileListSync hook
+    │
+    ├─ 150ms 防抖（debounce）
+    │
+    ├─ 比对新旧文件列表（避免无变更的冗余同步）
+    │
+    └─ 通过 DataChannel 发送 file-list 消息
+        │
+        └─ 接收方更新 UI 展示文件列表
+```
+
+### 4.6 文字传输详细设计
+
+#### 4.6.1 DataChannel 消息协议
+
+**text-transfer channel 消息类型：**
+
+| 方向 | type | payload | 说明 |
+|------|------|---------|------|
+| S→R | `text-sync` | `{ text: string }` | 实时文本内容同步 |
+| 双向 | `text-typing` | `{ typing: boolean }` | 打字状态指示 |
+
+#### 4.6.2 实时同步机制
+
+```
+发送方 Textarea 输入
+    │
+    ├─ onChange → handleTextInputChange()
+    │
+    ├─ 调用 textTransfer.sendTextSync(text)
+    │   └─ DataChannel 发送 { channel: "text-transfer", type: "text-sync", payload: { text } }
+    │
+    ├─ 同时发送 text-typing: { typing: true }
+    │   └─ 1秒后自动发送 text-typing: { typing: false }
+    │
+    └─ 接收方
+        ├─ onTextSync 回调 → 更新显示文本
+        └─ onTyping 回调 → 显示 "对方正在输入..." 动画
+```
+
+**图片传输**：复用文件传输的 `file-transfer` channel，图片作为文件发送。
+
+### 4.7 桌面共享详细设计
+
+```
+发送方
+    │
+    ├─ navigator.mediaDevices.getDisplayMedia({ video: true, audio: true })
+    │
+    ├─ 获取 MediaStream → 提取 video/audio Track
+    │
+    ├─ trackManager.addTrack(track, stream)
+    │   └─ peerConnection.addTrack()
+    │
+    ├─ trackManager.createOfferNow()  ← 触发 SDP 重协商
+    │   └─ 新 Offer → WebSocket → 对方 → Answer → WebSocket → 本方
+    │
+    └─ 接收方
+        ├─ ontrack 事件 → 获取远程 MediaStream
+        └─ <video> 元素播放 → DesktopViewer 组件
+```
+
+### 4.8 ICE 配置设计
+
+#### 默认 STUN 服务器
+
+```typescript
+const DEFAULT_ICE_SERVERS = [
+  { urls: 'stun:stun.easyvoip.com:3478' },
+  { urls: 'stun:stun.miwifi.com:3478' },
+  { urls: 'stun:stun.l.google.com:19302' },
+  { urls: 'stun:stun1.l.google.com:19302' },
+  { urls: 'stun:global.stun.twilio.com:3478' },
+];
+```
+
+#### 用户自定义
+
+- 通过 WebRTCSettings 界面添加 STUN/TURN 服务器
+- 配置持久化到 `localStorage`（key: `webrtc-ice-config`）
+- `getIceServersConfig()` 导出给非 React 代码使用
+- 配置变更后提示用户断开重连
+
+### 4.9 环境适配设计
+
+```
+                    ┌─────────────────────────────────────────┐
+                    │           config.ts 环境判断              │
+                    │                                         │
+                    │  isStaticMode = Next.js 构建输出判断      │
+                    │  isDev = NODE_ENV === 'development'      │
+                    └────────────────┬────────────────────────┘
+                                     │
+                   ┌─────────────────┼─────────────────┐
+                   │                 │                 │
+          ┌────────▼────────┐ ┌─────▼──────┐ ┌───────▼───────┐
+          │ 开发模式          │ │ SSG 静态模式 │ │ 嵌入 Go 模式   │
+          │ (yarn dev)       │ │ (build:ssg) │ │ (go run)      │
+          │                  │ │             │ │               │
+          │ API:             │ │ API:        │ │ API:          │
+          │ /api/* → Next.js │ │ 直连 Go     │ │ 同源 /api/*   │
+          │ API Route 代理   │ │ 后端地址     │ │               │
+          │                  │ │             │ │               │
+          │ WS:              │ │ WS:         │ │ WS:           │
+          │ ws://localhost   │ │ 当前域名     │ │ 当前域名       │
+          │ :8080/...        │ │ ws[s]://    │ │ ws[s]://      │
+          └──────────────────┘ └─────────────┘ └───────────────┘
+```
+
+#### URL 动态计算逻辑
+
+```typescript
+// API URL
+getApiUrl() → 
+  开发模式 ? '/api'  (通过 Next.js API Route 代理到 GO_BACKEND_URL)
+  静态模式 ? getDirectBackendUrl() + '/api'  (直连 Go 后端)
+
+// WebSocket URL
+getWsUrl() →
+  开发模式 ? 'ws://localhost:8080'  (直连 Go 后端 WS)
+  静态模式 ? 'ws[s]://' + window.location.host  (同源)
+```
+
+### 4.10 URL 路由设计
+
+前端通过 URL 参数控制功能和模式：
+
+```
+/?type=webrtc&mode=send            → 文件传输-发送模式
+/?type=webrtc&mode=receive         → 文件传输-接收模式
+/?type=webrtc&mode=receive&code=ABC123  → 自动填入取件码
+/?type=message&mode=send           → 文字消息-发送模式
+/?type=desktop&mode=send           → 桌面共享-共享模式
+```
+
+**URL 参数映射**：
+- `type`: `webrtc` | `message` | `desktop` | `wechat` | `settings` → 对应 Tab
+- `mode`: `send` | `receive` → 发送/接收子模式
+- `code`: 6 位取件码 → 自动填入并可自动加入房间
+
+---
+
+## 五、关键设计决策
+
+### 5.1 为什么用纯 P2P？
+
+- **隐私**：文件内容不经服务器，用户数据零留存
+- **成本**：服务器仅做信令，带宽成本极低
+- **性能**：局域网环境下可接近网卡极限速度
+
+### 5.2 为什么共享单个 DataChannel？
+
+三个功能（文件/文字/桌面控制）共享同一个 `shared-channel`，通过 JSON `channel` 字段路由：
+
+- **简化连接管理**：只需建立一次 P2P 连接
+- **减少信令开销**：无需为每个功能单独协商
+- **统一状态管理**：连接/断开状态全局一致
+
+### 5.3 为什么用 CRC32 + ACK？
+
+WebRTC DataChannel 本身基于 SCTP（配置为 `ordered: true, maxRetransmits: 3`），已有一定可靠性。额外的 CRC32 + ACK 是 **应用层二次保障**：
+
+- 防止极端情况下 SCTP 重传仍失败后的数据损坏
+- 提供块级粒度的错误恢复（只重传失败的块，无需从头开始）
+- 接收方独立验证数据完整性
+
+### 5.4 为什么 256KB 块大小？
+
+- WebRTC DataChannel 最大消息大小约 256KB（不同浏览器有差异）
+- 小块有利于进度反馈的精度
+- 小块降低单次重传的代价
+
+### 5.5 为什么关闭 React Strict Mode？
+
+```typescript
+// next.config.ts
+reactStrictMode: false
+```
+
+React 18+ Strict Mode 会在开发环境 **双重调用** effect，导致：
+- WebSocket 连接被创建两次
+- PeerConnection 生命周期混乱
+- DataChannel 状态不一致
+
+---
+
+## 六、部署模式
+
+### 模式一：开发模式
+
+```bash
+# 终端 1：Go 后端
+go run cmd/main.go          # :8080
+
+# 终端 2：Next.js 前端
+cd chuan-next && yarn dev   # :3000 (turbopack)
+```
+
+前端 API 调用链：`浏览器 → localhost:3000/api/* → Next.js API Route → localhost:8080/api/*`
+
+### 模式二：生产模式（Go 嵌入前端）
+
+```bash
+cd chuan-next && yarn build:ssg    # 输出到 out/
+cp -r out/ ../internal/web/frontend/  # 复制到 Go embed 目录
+go build -o chuan cmd/*.go         # 编译
+./chuan                            # :8080 同时提供 API + 前端
+```
+
+所有请求都由 Go 单进程处理，前端静态文件通过 `go:embed` 嵌入二进制。
+
+---
+
+## 七、安全与限制
+
+| 维度 | 现状 |
+|------|------|
+| 加密 | WebRTC 自带 DTLS 加密，P2P 数据全程加密传输 |
+| 认证 | 无用户认证，仅靠 6 位取件码 |
+| 房间安全 | 取件码空间 34^6 ≈ 15 亿，暴力破解概率低 |
+| 数据留存 | 服务器零数据留存，所有文件仅在浏览器内存/临时存储 |
+| 并发限制 | 每房间最多 2 人，单进程内存管理 |
+| 文件大小 | 受限于浏览器内存（大文件需接收方有足够内存组装 Blob）|
+| NAT 穿透 | 依赖 STUN 服务器，对称 NAT 需 TURN 服务器（默认未配置）|
diff --git a/FRONTEND_ANALYSIS.md b/FRONTEND_ANALYSIS.md
new file mode 100644
index 0000000..db8fca5
--- /dev/null
+++ b/FRONTEND_ANALYSIS.md
@@ -0,0 +1,471 @@
+# 前端代码架构分析 & 优化计划
+
+> 最后更新：2026-02-28
+
+---
+
+## 目录
+
+- [一、全局数据](#一全局数据)
+- [二、文件清单与行数](#二文件清单与行数)
+- [三、核心问题分析](#三核心问题分析)
+  - [3.1 过度抽象的连接层（5 层 Hook 嵌套）](#31-过度抽象的连接层5-层-hook-嵌套)
+  - [3.2 "Shared" 名不副实 — 多处独立创建连接](#32-shared-名不副实--多处独立创建连接)
+  - [3.3 WebRTCFileTransfer 组件是复杂度炸弹](#33-webrtcfiletransfer-组件是复杂度炸弹)
+  - [3.4 到处重复的类型定义和验证逻辑](#34-到处重复的类型定义和验证逻辑)
+  - [3.5 useTabNavigation 不应耦合连接管理](#35-usetabnavigation-不应耦合连接管理)
+  - [3.6 其他问题汇总](#36-其他问题汇总)
+- [四、优化计划](#四优化计划)
+  - [Phase 1：消除重复、统一类型](#phase-1消除重复统一类型)
+  - [Phase 2：扁平化 Hook 层](#phase-2扁平化-hook-层)
+  - [Phase 3：拆分超级组件](#phase-3拆分超级组件)
+  - [Phase 4：基础设施清理](#phase-4基础设施清理)
+- [五、优化总览](#五优化总览)
+
+---
+
+## 一、全局数据
+
+| 指标 | 数值 |
+|------|------|
+| 总行数 | **11,776 行** (69 个 .ts/.tsx 文件) |
+| Hooks 文件 | **19 个**, ~3,500 行 |
+| 组件文件 | **20 个**, ~5,500 行 |
+| `console.log/warn/error` | **428 处** |
+| `useEffect` 调用 | **75 处** |
+| `setTimeout` / 延时等待 | **28 处** |
+| `FileInfo` 接口重复定义 | **7 处** |
+
+---
+
+## 二、文件清单与行数
+
+### 2.1 Hooks 层（19 个文件，~3,500 行）
+
+#### Connection 模块（8 个文件，~1,640 行）
+
+| 文件 | 行数 | 关键导出 | 职责 |
+|------|------|----------|------|
+| `hooks/connection/index.ts` | 5 | 4 个 re-export | 桶文件 |
+| `hooks/connection/useWebRTCConnectionCore.ts` | **569** | `useWebRTCConnectionCore()` | **最大最复杂的 hook** — WebSocket 连接、PeerConnection 创建、信令消息处理(offer/answer/ICE/peer-joined/disconnection)、房间管理 |
+| `hooks/connection/useWebRTCDataChannelManager.ts` | **355** | `useWebRTCDataChannelManager()` | 数据通道创建(sender/receiver 分支)、消息/二进制数据分发、通道注册 |
+| `hooks/connection/useWebRTCTrackManager.ts` | 229 | `useWebRTCTrackManager()` | 媒体轨道添加/移除、createOffer、onTrack 轮询重试 |
+| `hooks/connection/useWebRTCStateManager.ts` | 77 | `useWebRTCStateManager()` | 对 zustand store 的薄封装 |
+| `hooks/connection/useSharedWebRTCManager.ts` | 118 | `useSharedWebRTCManager()` → `WebRTCConnection` | **门面模式** — 组合 4 个子 manager，暴露统一的 `WebRTCConnection` 接口 |
+| `hooks/connection/useConnectionState.ts` | 137 | `useConnectionState()` | 连接错误展示/状态清理的 side-effect hook |
+| `hooks/connection/useRoomConnection.ts` | 110 | `useRoomConnection()` | 房间验证逻辑(HTTP check + connect) |
+| `hooks/connection/useWebRTCSupport.ts` | 40 | `useWebRTCSupport()` | WebRTC 浏览器兼容性检测 |
+
+**复杂度观察：**
+
+- `useWebRTCConnectionCore.ts` 是**整个代码库最复杂的文件（569 行）**。它在 `ws.onmessage` 中处理了 7 种信令消息类型，每种都有嵌套的 `if/else` 分支处理 sender/receiver 角色、reconnect 状态、PeerConnection 是否存在。特别是 `answer` 处理（约 L268-L350），有 3 层 `if/else` 嵌套 + 异常恢复逻辑。
+- `useWebRTCDataChannelManager` 中 sender 和 receiver 的 `onerror` 处理器是**完全重复的代码**（各约 30 行相同的 `switch` 语句）。
+- `useWebRTCTrackManager.onTrack` 中有**轮询重试机制**（50 次 × 每 100ms），是一种脆弱的模式。
+
+#### File-Transfer 模块（4 个文件，~916 行）
+
+| 文件 | 行数 | 关键导出 | 职责 |
+|------|------|----------|------|
+| `hooks/file-transfer/index.ts` | 4 | re-export | 桶文件 |
+| `hooks/file-transfer/useFileTransferBusiness.ts` | **676** | `useFileTransferBusiness(connection)` | **第二大 hook** — 文件分块传输(256KB chunks)、CRC32 校验和、ACK 确认、重试(5 次指数退避)、流控、进度追踪 |
+| `hooks/file-transfer/useFileStateManager.ts` | 171 | `useFileStateManager()` | 文件选择、文件列表维护、进度状态管理 |
+| `hooks/file-transfer/useFileListSync.ts` | 65 | `useFileListSync()` | 防抖式文件列表同步 |
+
+**复杂度观察：**
+
+- `useFileTransferBusiness` 内含**自实现的 CRC32 校验算法**（`calculateChecksum`, `simpleChecksum`）和完整的**可靠传输协议**（ACK/重传/超时/流控），这本质上是在应用层重建了 TCP 的功能。
+- `useFileStateManager` 有 3 个 `useEffect` 都在监听并同步文件列表，任何一个变化都可能触发链式更新，存在复杂的依赖关系。
+
+#### Text-Transfer 模块（2 个文件，~177 行）
+
+| 文件 | 行数 | 关键导出 |
+|------|------|----------|
+| `hooks/text-transfer/index.ts` | 2 | re-export |
+| `hooks/text-transfer/useTextTransferBusiness.ts` | 175 | `useTextTransferBusiness(connection)` |
+
+结构简洁。发送 `text-sync` 和 `text-typing` 消息。连接状态从 `connection` 参数同步。
+
+#### Desktop-Share 模块（2 个文件，~545 行）
+
+| 文件 | 行数 | 关键导出 |
+|------|------|----------|
+| `hooks/desktop-share/index.ts` | 2 | re-export |
+| `hooks/desktop-share/useDesktopShareBusiness.ts` | **543** | `useDesktopShareBusiness()` |
+
+**复杂度观察：**
+
+- 与 file-transfer/text-transfer 不同，**桌面共享直接内部调用** `useSharedWebRTCManager()`，而非从外部接收一个 `connection` 参数。这导致了**不一致的依赖注入模式**。
+- `setupVideoSending` 中有大量 `await new Promise(resolve => setTimeout(resolve, ...))` 等待连接稳定的代码（500ms + 2000ms），是一种脆弱的时序控制。
+
+#### Settings 模块（3 个文件，~283 行）
+
+| 文件 | 行数 | 关键导出 |
+|------|------|----------|
+| `hooks/settings/index.ts` | 3 | re-export |
+| `hooks/settings/useIceServersConfig.ts` | 251 | `useIceServersConfig()`, `getIceServersConfig()` |
+| `hooks/settings/useWebRTCConfigSync.ts` | 29 | `useWebRTCConfigSync()` |
+
+`useIceServersConfig` 同时导出 hook（React 组件用）和独立函数 `getIceServersConfig()`（非组件代码用），设计合理。
+
+#### UI 模块（5 个文件，~496 行）
+
+| 文件 | 行数 | 关键导出 |
+|------|------|----------|
+| `hooks/ui/webRTCStore.ts` | 46 | `useWebRTCStore` (zustand) |
+| `hooks/ui/useTabNavigation.ts` | 183 | `useTabNavigation()` |
+| `hooks/ui/useURLHandler.ts` | 210 | `useURLHandler()` |
+| `hooks/ui/useConfirmDialog.ts` | 52 | `useConfirmDialog()` |
+| `hooks/ui/index.ts` | 5 | re-export |
+
+**复杂度观察：**
+
+- `useTabNavigation` **内部调用了** `useSharedWebRTCManager()` 和 `useURLHandler()` 和 `useConfirmDialog()`，使得一个 "UI Tab 导航" hook 深度耦合了 WebRTC 连接管理逻辑。
+- `useURLHandler` 是泛型 hook，支持 `modeConverter` 进行模式映射（如 desktop share 的 `share/view` ↔ `send/receive`）。
+
+---
+
+### 2.2 组件层（20 个文件，~5,500 行）
+
+#### 顶层业务组件
+
+| 文件 | 行数 | 关键导出 | 职责 |
+|------|------|----------|------|
+| `components/WebRTCFileTransfer.tsx` | **658** | `WebRTCFileTransfer` | **最大的组件** — 文件传输页面容器，组合 7 个 hooks + 2 个子组件 |
+| `components/WebRTCTextImageTransfer.tsx` | 104 | `WebRTCTextImageTransfer` | 文本传输页面容器，较简洁 |
+| `components/DesktopShare.tsx` | 199 | `DesktopShare` (default) | 桌面共享页面容器，含 `useScreenShareSupport` 内部 hook |
+| `components/WebRTCSettings.tsx` | 565 | `WebRTCSettings` (default) | ICE 服务器配置页（自包含，含 `AddServerModal` 内部组件） |
+
+#### WebRTC 子组件（纯展示/交互层）
+
+| 文件 | 行数 | 职责 |
+|------|------|------|
+| `components/webrtc/WebRTCFileUpload.tsx` | 357 | 发送方文件列表 UI（拖拽上传、文件展示、取件码展示） |
+| `components/webrtc/WebRTCFileReceive.tsx` | 399 | 接收方取件码输入 + 文件下载列表 UI |
+| `components/webrtc/WebRTCTextSender.tsx` | **465** | 文本发送方（**内含自己的连接管理逻辑**） |
+| `components/webrtc/WebRTCTextReceiver.tsx` | **385** | 文本接收方（**内含自己的连接管理逻辑**） |
+| `components/webrtc/WebRTCDesktopSender.tsx` | 325 | 桌面共享发送方 |
+| `components/webrtc/WebRTCDesktopReceiver.tsx` | 370 | 桌面共享接收方（**含重复的房间验证逻辑**） |
+
+**复杂度观察：**
+
+- `WebRTCTextSender` 和 `WebRTCTextReceiver` **各自独立调用** `useSharedWebRTCManager()`，然后创建 `useTextTransferBusiness(connection)` 和 `useFileTransferBusiness(connection)`。这意味着**每个子组件都创建了自己的独立 WebRTC 连接实例**。
+- `WebRTCDesktopReceiver` 中有两处几乎完全相同的房间验证逻辑（`handleJoinViewing` 和 `autoJoin` useEffect），代码重复约 ~80 行。
+- `WebRTCFileReceive` 中也有独立的房间验证代码（`validatePickupCode`），与 `useRoomConnection` 中的 `checkRoomStatus` 功能重复。
+
+#### 共享/展示组件
+
+| 文件 | 行数 | 职责 |
+|------|------|------|
+| `components/ConnectionStatus.tsx` | 241 | 连接状态 UI（3 种模式：full/compact/inline） |
+| `components/WebRTCConnectionStatus.tsx` | 185 | WebRTC 连接状态 UI + `WebRTCStatusIndicator` |
+| `components/RoomInfoDisplay.tsx` | 123 | 取件码/QR 码展示通用组件 |
+| `components/QRCodeDisplay.tsx` | 68 | QR 码 canvas 渲染 |
+| `components/DesktopViewer.tsx` | **546** | 桌面视频播放器（全屏/统计/控制/鼠标隐藏） |
+| `components/Hero.tsx` | 42 | 页面顶部标题/链接 |
+| `components/RoomStatusDisplay.tsx` | 39 | 房间实时状态展示 |
+| `components/WebRTCUnsupportedModal.tsx` | 186 | 浏览器不支持 WebRTC 弹窗 |
+| `components/WeChatGroup.tsx` | 68 | 微信群二维码页 |
+
+`ConnectionStatus` 和 `WebRTCConnectionStatus` 是**两个独立的连接状态组件**，功能高度重叠但接口不同：前者使用 zustand store，后者接受 `WebRTCConnection` prop。
+
+---
+
+### 2.3 页面层
+
+| 文件 | 行数 | 职责 |
+|------|------|------|
+| `app/page.tsx` | 13 | 入口，渲染 `HomePageWrapper` |
+| `app/HomePageWrapper.tsx` | 14 | Suspense 包装层 |
+| `app/HomePage.tsx` | 206 | **主页面** — Tab 布局，渲染 5 个 Tab 内容 |
+| `app/layout.tsx` | 40 | RootLayout + `ToastProvider` |
+| `app/help/HelpPage.tsx` | 761 | 帮助页面 |
+
+### 2.4 Types
+
+`types/index.ts`（51 行）— 定义了 `FileInfo`, `TransferProgress`, `RoomStatus`, `FileChunk`, `WebSocketMessage`, `UseWebSocketReturn`。
+
+**问题：** `FileInfo` 类型在此文件中定义了一次，但在 `WebRTCFileTransfer.tsx`、`WebRTCFileUpload.tsx`、`WebRTCFileReceive.tsx`、`useFileTransferBusiness.ts`、`useFileStateManager.ts`、`useFileListSync.ts` 中各自**重新定义了完全相同的 `FileInfo` 接口**（至少 7 处重复定义）。`UseWebSocketReturn` 类型实际没有被任何代码使用。
+
+### 2.5 Lib 工具层
+
+| 文件 | 行数 | 职责 |
+|------|------|------|
+| `lib/config.ts` | 150 | 环境配置、URL 构造（`getWsUrl`, `getBackendUrl` 等） |
+| `lib/api-utils.ts` | 144 | 统一 fetch 封装（`apiFetch`, `apiGet`, `apiPost`...) |
+| `lib/client-api.ts` | 119 | `ClientAPI` 类（OOP style API 封装） |
+| `lib/webrtc-support.ts` | 162 | WebRTC 特性检测 + 浏览器信息 |
+| `lib/utils.ts` | 6 | `cn()` — tailwind 合并工具 |
+| `lib/static-config.ts` | 35 | 静态/动态页面路由定义 |
+
+**问题：** `api-utils.ts` 和 `client-api.ts` 是**两套并行的 API 调用方案**。`ClientAPI` 是 class-based 封装，`apiFetch` 是函数式封装，功能完全重叠。实际代码中组件大多直接调用 `fetch()`，两个 utils 文件利用率低。
+
+---
+
+## 三、核心问题分析
+
+### 3.1 过度抽象的连接层（5 层 Hook 嵌套）
+
+从 UI 按钮点击到实际网络传输，需穿越 **5 层抽象**：
+
+```
+组件 (WebRTCFileTransfer)                      658 行
+  └→ useFileTransferBusiness(connection)         676 行
+      └→ useSharedWebRTCManager()                 118 行  ← 门面
+          ├→ useWebRTCStateManager()                77 行  ← zustand 薄封装
+          ├→ useWebRTCDataChannelManager()         355 行  ← DC 管理
+          ├→ useWebRTCTrackManager()               229 行  ← 轨道管理
+          └→ useWebRTCConnectionCore()             569 行  ← WS+信令+PC
+```
+
+`useWebRTCStateManager` 只是对 47 行的 zustand store 做了 `useCallback` 包装，**额外增加 77 行代码但零业务价值**。`useSharedWebRTCManager` 又对 4 个子 manager 做了一层门面包装。
+
+**状态流动图：**
+
+```
+zustand Store (webRTCStore)
+    ↑ 写入
+useWebRTCStateManager
+    ↑ 使用
+useWebRTCConnectionCore / useWebRTCDataChannelManager
+    ↑ 组合
+useSharedWebRTCManager  →  返回 WebRTCConnection 对象
+    ↑ 调用                              ↓ 传入
+组件层                      useFileTransferBusiness(connection)
+(WebRTCFileTransfer)       useTextTransferBusiness(connection)
+    ↓ 使用                  useDesktopShareBusiness() ← 内部直接调用 Manager
+useFileStateManager
+useFileListSync
+useConnectionState
+useRoomConnection
+useURLHandler
+useTabNavigation
+```
+
+### 3.2 "Shared" 名不副实 — 多处独立创建连接
+
+`useSharedWebRTCManager()` 在 **4 处被独立调用**，每次返回新实例：
+
+| 调用位置 | 文件 | 行号 | 问题 |
+|----------|------|------|------|
+| 文件传输 | `WebRTCFileTransfer.tsx` | L37 | 文件传输的连接 |
+| 文字发送 | `WebRTCTextSender.tsx` | L34 | **自己创建连接** |
+| 文字接收 | `WebRTCTextReceiver.tsx` | L40 | **自己创建连接** |
+| 桌面共享 | `useDesktopShareBusiness.ts` | L15 | 在 hook 内部直接调用 |
+
+每个组件各自调用 `useSharedWebRTCManager()` → 各自创建独立的 PeerConnection 和 DataChannel。**"shared" 名不副实** —— hook 每次调用返回新实例。
+
+而 `useDesktopShareBusiness` 是**第四种模式**：在 hook 内部自行调用 `useSharedWebRTCManager()`，与 file/text 模块的依赖注入模式不一致。
+
+### 3.3 WebRTCFileTransfer 组件是复杂度炸弹
+
+658 行的组件内：
+
+- **使用 7 个 Hook**：`useSharedWebRTCManager`, `useFileTransferBusiness`, `useFileListSync`, `useFileStateManager`, `useRoomConnection`, `useURLHandler`, `useConnectionState`
+- **9 个 `useEffect`**：多个 effect 监听重叠的状态（`isConnected`, `isConnecting`, `error`），一次状态变化触发多个 effect 连锁执行
+- **与 `useConnectionState` 完全重复的错误处理**
+
+`WebRTCFileTransfer.tsx` 第 316-368 行的错误处理 if/else 链：
+
+```typescript
+// 组件内的错误处理 (L316-L368)
+if (error.includes('WebSocket')) {
+  errorMessage = '服务器连接失败...';
+} else if (error.includes('数据通道')) { ... }
+```
+
+与 `useConnectionState.ts` 第 46-64 行**完全相同**：
+
+```typescript
+// Hook 内的错误处理 (L46-L64) — 一模一样的 if/else
+if (error.includes('WebSocket')) {
+  errorMessage = '服务器连接失败...';
+} else if (error.includes('数据通道')) { ... }
+```
+
+**结果：同一个错误被 Toast 弹出两次。**
+
+**9 个 useEffect 明细：**
+
+| # | 监听依赖 | 职责 | 问题 |
+|---|---------|------|------|
+| 1 | `onFileListReceived, mode` | 文件列表接收 | 正常 |
+| 2 | `onFileReceived, updateFileStatus` | 文件接收完成 | 正常 |
+| 3 | `onFileProgress, mode, isConnected, error` | 进度更新 | 正常 |
+| 4 | `onFileRequested, mode, selectedFiles, ...` | 文件请求处理 | 正常 |
+| 5 | `error, mode, showToast, lastError` | 错误处理 | ⚠️ 与 useConnectionState 重复 |
+| 6 | `isWebSocketConnected, isConnected, isConnecting, ...` | 连接状态清理 | ⚠️ 与 useConnectionState 重复 |
+| 7 | `isConnected, isPeerConnected, isConnecting, ...` | 日志输出 | ⚠️ 纯日志，可删除 |
+| 8 | `connection.isPeerConnected, mode, syncFileListToReceiver` | P2P 建立时同步 | 正常 |
+| 9 | `selectedFiles, mode, pickupCode` | 文件选择变化同步 | ⚠️ 与 useFileStateManager 部分重复 |
+
+### 3.4 到处重复的类型定义和验证逻辑
+
+**`FileInfo` 接口在 7 个文件中各自定义**，且字段不完全一致：
+
+| 文件 | 行号 | 字段差异 |
+|------|------|---------|
+| `types/index.ts` | L2 | `export interface FileInfo` — **无 status/progress**，有 lastModified |
+| `WebRTCFileTransfer.tsx` | L13 | `interface FileInfo` — **有 status/progress** |
+| `WebRTCFileUpload.tsx` | L10 | `interface FileInfo` — 有 status/progress |
+| `WebRTCFileReceive.tsx` | L10 | `interface FileInfo` — 有 status/progress |
+| `useFileListSync.ts` | L3 | `interface FileInfo` — 有 status/progress |
+| `useFileStateManager.ts` | L3 | `interface FileInfo` — 有 status/progress |
+| `useFileTransferBusiness.ts` | L25 | `interface FileInfo` — 有 status/progress |
+
+**房间验证逻辑至少有 4 处重复实现**：
+
+| 位置 | 函数名 | 行数 |
+|------|--------|------|
+| `hooks/connection/useRoomConnection.ts` | `checkRoomStatus` + `joinRoom` | ~60 行 |
+| `components/webrtc/WebRTCFileReceive.tsx` | `validatePickupCode` | ~40 行 |
+| `components/webrtc/WebRTCTextReceiver.tsx` | `joinRoom` | ~50 行 |
+| `components/webrtc/WebRTCDesktopReceiver.tsx` | `handleJoinViewing` + `autoJoin` | ~80 行 |
+
+### 3.5 useTabNavigation 不应耦合连接管理
+
+`useTabNavigation.ts` 是一个 **UI 导航 hook**，却 import 并调用了：
+- `useSharedWebRTCManager()` — 获取 `disconnect` 方法
+- `useWebRTCStore` — 直接读取连接状态
+- `useURLHandler()` — URL 管理
+- `useConfirmDialog()` — 确认弹窗
+
+Tab 切换逻辑不应该知道 WebRTC 的存在，连接生命周期应由更上层管理。
+
+### 3.6 其他问题汇总
+
+| 问题 | 严重程度 | 详情 |
+|------|---------|------|
+| **428 条 console.log** 散布在生产代码 | 🟡 中 | 使用 emoji 前缀（如 🔧🚀📤），无级别控制，生产环境产生大量噪音 |
+| **两个功能重叠的连接状态组件** | 🟡 中 | `ConnectionStatus`（241 行，使用 zustand）+ `WebRTCConnectionStatus`（185 行，使用 prop），426 行总计 |
+| **两套 API 封装并存** | 🟡 中 | `api-utils.ts`（函数式）+ `client-api.ts`（class-based），263 行，但组件大多直接用 `fetch()` |
+| **`types/index.ts` 中的死代码** | 🟢 低 | `UseWebSocketReturn` 等类型无人引用 |
+| **28 处 `setTimeout` 作为同步机制** | 🟡 中 | 500ms/2000ms 硬编码等待连接稳定，在低性能设备上可能不够，在高性能设备上浪费时间 |
+| **`useWebRTCTrackManager.onTrack` 轮询** | 🟢 低 | 50 次 × 100ms 轮询等待轨道就绪，应改为事件驱动 |
+| **DataChannel `onerror` 处理重复** | 🟡 中 | sender 和 receiver 分支中约 30 行完全相同的 switch 语句 |
+
+---
+
+## 四、优化计划
+
+### Phase 1：消除重复、统一类型
+
+> 影响大，改动小。预估耗时：半天。
+
+| 任务 | 预估时间 | 效果 |
+|------|---------|------|
+| 统一 `FileInfo`（含 status/progress）到 `types/index.ts`，删除 7 处重复定义 | 30min | **-60 行**，消除类型漂移 |
+| 抽取 `validateRoom(code)` 通用函数，替代 4 处房间验证 | 30min | **-200 行** |
+| 合并 `ConnectionStatus` + `WebRTCConnectionStatus` 为一个组件 | 1h | **-150 行** |
+| 删除 `useConnectionState` hook，其逻辑已在组件中重复 | 15min | **-138 行**，修复双重 Toast |
+| 删除 `api-utils.ts` 或 `client-api.ts`，统一为一套 | 30min | **-140 行** |
+
+**Phase 1 预估净减少：~690 行**
+
+---
+
+### Phase 2：扁平化 Hook 层
+
+> 核心改造，风险中等。预估耗时：1-2 天。
+
+**目标：5 层 → 3 层**
+
+```
+当前 5 层:
+  组件 → 业务Hook → SharedManager → SubManagers(4个) → Native API
+
+目标 3 层:
+  组件 → 业务Hook → useWebRTCConnection(合并) → Native API
+```
+
+**具体步骤：**
+
+1. **删除 `useWebRTCStateManager`（77 行）**
+   - 直接在 `useWebRTCConnectionCore` 中使用 `useWebRTCStore`
+   - 一个 hook 包装另一个 hook 再包装 zustand store 毫无必要
+
+2. **合并 `useSharedWebRTCManager` + `useWebRTCConnectionCore`**
+   - `useSharedWebRTCManager` 只是 4 个子模块的胶水代码
+   - 将其与 `useWebRTCConnectionCore` 合并为 `useWebRTCConnection`
+   - 内联数据通道和轨道管理逻辑
+   - 用清晰的函数分组而非文件拆分来组织代码
+
+3. **统一连接注入模式**
+   - 让 `useDesktopShareBusiness` 也改为接受 `connection` 参数
+   - 与 file/text 保持一致
+
+**改造后的目标结构：**
+
+```
+hooks/
+  useWebRTCConnection.ts    ← 合并后的唯一连接 hook (~600行)
+  useFileTransfer.ts         ← file-transfer 业务
+  useTextTransfer.ts         ← text-transfer 业务
+  useDesktopShare.ts         ← desktop 业务（接受 connection 参数）
+  useIceServersConfig.ts     ← 保留
+  webRTCStore.ts             ← 保留（直接使用，不再包装）
+  useURLHandler.ts           ← 保留
+  useTabNavigation.ts        ← 删除 WebRTC 依赖
+  useConfirmDialog.ts        ← 保留
+```
+
+**预估净减少：~400 行 + 消除 2 层抽象**
+
+---
+
+### Phase 3：拆分超级组件
+
+> 降低单文件复杂度。预估耗时：1 天。
+
+**`WebRTCFileTransfer.tsx`（658 行）→ 拆分为：**
+
+| 新文件 | 职责 | 预估行数 |
+|--------|------|----------|
+| `WebRTCFileTransfer.tsx` | 仅做 mode 切换 + 子组件渲染 | ~60 行 |
+| `useSenderLogic.ts` | 房间创建 + 文件列表同步 | ~150 行 |
+| `useReceiverLogic.ts` | 加入房间 + 下载管理 | ~120 行 |
+| `useTransferEffects.ts` | 集中管理 useEffect | ~100 行 |
+
+**9 个 `useEffect` 优化为 4 个：**
+
+| 当前 | 优化后 |
+|------|--------|
+| `onFileListReceived` effect | → 合并到 `useTransferEffects` |
+| `onFileReceived` effect | → 合并到 `useTransferEffects` |
+| `onFileProgress` effect | → 合并到 `useTransferEffects` |
+| `onFileRequested` effect | → 合并到 `useTransferEffects` |
+| 错误处理 effect × 2 (重复) | → 删除 1 个，保留 1 个 |
+| 连接日志 effect × 2 | → 删除（改用 logger 工具） |
+| `selectedFiles` 同步 effect | → 保留，移入 `useSenderLogic` |
+
+---
+
+### Phase 4：基础设施清理
+
+> 代码卫生。预估耗时：半天。
+
+| 任务 | 效果 |
+|------|------|
+| 引入 `logger.ts` 工具（dev 输出 / prod 静默），替换 428 个 `console.log` | 清洁生产日志 |
+| 把 `setTimeout` 同步替换为事件监听 Promise（监听 `connectionstatechange` / `datachannel.open`） | 消除脆弱时序 |
+| `useTabNavigation` 改为通过回调通知父组件处理断连，不直接依赖 WebRTC | 关注点分离 |
+| 清理 `types/index.ts` 中未使用的类型 | 减少死代码 |
+| DataChannel `onerror` 提取为共享处理器 | -30 行重复 |
+
+---
+
+## 五、优化总览
+
+| Phase | 目标 | 代码影响 | 难度 | 耗时 |
+|-------|------|---------|------|------|
+| **Phase 1** | 消除重复 | **-690 行** | ⭐ 低 | 半天 |
+| **Phase 2** | 扁平化 Hook 层 5→3 | **-400 行** + 结构简化 | ⭐⭐⭐ 高 | 1-2 天 |
+| **Phase 3** | 拆分超级组件 | 0（重组织） | ⭐⭐ 中 | 1 天 |
+| **Phase 4** | 基础设施 | **-428 行** console.log | ⭐ 低 | 半天 |
+
+**总预估**：
+- 代码量：11,776 行 → ~10,000 行（减少 ~15%）
+- 抽象层数：5 层 → 3 层
+- useEffect：75 个 → ~50 个
+- console.log：428 处 → 0（替换为 logger）
+- FileInfo 定义：7 处 → 1 处
+- 房间验证实现：4 处 → 1 处
diff --git a/PROTOCOL_ANALYSIS.md b/PROTOCOL_ANALYSIS.md
new file mode 100644
index 0000000..c658148
--- /dev/null
+++ b/PROTOCOL_ANALYSIS.md
@@ -0,0 +1,1237 @@
+# 文件快传（Chuan）— 传输协议接口分析文档
+
+> 最后更新：2025-08-02
+
+---
+
+## 目录
+
+- [一、协议总览](#一协议总览)
+- [二、HTTP REST API 接口](#二http-rest-api-接口)
+- [三、WebSocket 信令协议](#三websocket-信令协议)
+- [四、DataChannel P2P 消息协议](#四datachannel-p2p-消息协议)
+- [五、二进制传输协议](#五二进制传输协议)
+- [六、可靠传输机制](#六可靠传输机制)
+- [七、桌面共享 MediaStream 协议](#七桌面共享-mediastream-协议)
+- [八、优缺点分析](#八优缺点分析)
+- [九、设计评价](#九设计评价)
+- [十、优化建议](#十优化建议)
+
+---
+
+## 一、协议总览
+
+系统通信分为 **四个平面**，各自承担不同职责：
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│                           通信协议栈                                      │
+│                                                                          │
+│  ┌─────────────┐  ┌─────────────┐  ┌──────────────┐  ┌──────────────┐  │
+│  │  控制平面     │  │  信令平面     │  │  数据平面      │  │  媒体平面      │  │
+│  │  HTTP REST   │  │  WebSocket   │  │  DataChannel  │  │  MediaStream │  │
+│  │              │  │              │  │               │  │              │  │
+│  │  房间管理     │  │  SDP/ICE     │  │  文件/文字     │  │  桌面共享      │  │
+│  │  状态查询     │  │  连接/断开    │  │  P2P 直传     │  │  P2P 视频流   │  │
+│  │              │  │              │  │               │  │              │  │
+│  │  浏览器↔服务器 │  │  浏览器↔服务器 │  │  浏览器↔浏览器  │  │  浏览器↔浏览器  │  │
+│  └─────────────┘  └─────────────┘  └──────────────┘  └──────────────┘  │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+### 消息类型汇总
+
+| 平面 | 协议 | 消息类型数量 | 方向 |
+|------|------|------------|------|
+| 控制平面 | HTTP | 2 个端点 | 浏览器 → 服务器 |
+| 信令平面 | WebSocket | 6 种消息类型 | 双向 (经服务器中继) |
+| 数据平面 | DataChannel | 10 种消息类型 + 二进制流 | P2P 双向 |
+| 媒体平面 | MediaStream | 0 自定义消息 (纯 SDP 重协商) | P2P 单向 |
+
+---
+
+## 二、HTTP REST API 接口
+
+### 2.1 创建房间
+
+```
+POST /api/create-room
+Content-Type: application/json
+```
+
+**请求体**：`{}` (空 JSON，后端忽略所有字段)
+
+**成功响应** (200)：
+```json
+{
+  "success": true,
+  "code": "A1B2C3",
+  "message": "房间创建成功"
+}
+```
+
+**错误响应** (405 方法不允许)：
+```json
+{
+  "success": false,
+  "message": "方法不允许"
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `success` | `boolean` | 是否成功 |
+| `code` | `string` | 6 位房间码，字符集 `123456789ABCDEFGHIJKLMNPQRSTUVWXYZ` |
+| `message` | `string` | 描述信息 |
+
+**房间码生成规则**：
+- 字符集排除 `0`（零）和 `O`（大写字母），避免视觉混淆
+- 长度固定 6 位
+- 随机生成，保证与现有房间不重复
+- 代码空间：34^6 ≈ 15.4 亿种组合
+
+---
+
+### 2.2 查询房间状态
+
+```
+GET /api/room-info?code={ROOM_CODE}
+GET /api/webrtc-room-status?code={ROOM_CODE}
+```
+
+两个端点指向同一个 Handler。
+
+**成功响应** (200，房间存在)：
+```json
+{
+  "success": true,
+  "exists": true,
+  "sender_online": true,
+  "receiver_online": false,
+  "is_room_full": false,
+  "created_at": "2025-08-02T15:00:00Z"
+}
+```
+
+**错误响应** (200，房间不存在)：
+```json
+{
+  "success": false,
+  "exists": false,
+  "message": "房间不存在或已过期"
+}
+```
+
+**错误响应** (400，缺少参数)：
+```json
+{
+  "success": false,
+  "message": "缺少房间代码"
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `sender_online` | `boolean` | 发送方 WebSocket 是否连接中 |
+| `receiver_online` | `boolean` | 接收方 WebSocket 是否连接中 |
+| `is_room_full` | `boolean` | 两方是否都在线 |
+| `created_at` | `string` (ISO 8601) | 房间创建时间 |
+
+---
+
+### 2.3 Next.js API 代理层
+
+开发模式下，Next.js 作为代理转发到 Go 后端：
+
+| Next.js 路由 | 代理目标 |
+|---------------|----------|
+| `POST /api/create-room` | `POST {GO_BACKEND_URL}/api/create-room` |
+| `GET /api/room-info?code=X` | `GET {GO_BACKEND_URL}/api/room-info?code=X` |
+| `GET /api/get-text-content?code=X` | `GET {GO_BACKEND_URL}/api/get-text-content?code=X` |
+
+生产模式下前端与 Go 后端同源部署，无需代理。
+
+---
+
+## 三、WebSocket 信令协议
+
+### 3.1 连接建立
+
+**URL 格式**：
+```
+ws[s]://{host}/api/ws/webrtc?code={ROOM_CODE}&role={sender|receiver}&channel=shared
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `code` | string | ✅ | 6 位房间码 |
+| `role` | string | ✅ | `"sender"` 或 `"receiver"` |
+| `channel` | string | ❌ | 固定值 `"shared"` (前端始终传递) |
+
+**连接验证流程**：
+```
+WebSocket 升级请求
+    │
+    ├─ code 为空 → 发送 error → 关闭连接
+    ├─ role 不是 sender/receiver → 发送 error → 关闭连接
+    ├─ 房间不存在 → 发送 error → 关闭连接
+    ├─ 房间已过期 → 删除房间 → 发送 error → 关闭连接
+    ├─ 对应角色已有人在线 → 发送 error → 关闭连接
+    │
+    └─ 验证通过
+        ├─ 注册客户端到房间
+        └─ 通知对方: peer-joined
+```
+
+**兼容路由**：`/ws/webrtc` 和 `/api/ws/webrtc` 指向同一个 Handler。
+
+---
+
+### 3.2 信令消息类型
+
+所有信令消息共享统一的 JSON 结构（Go 端定义）：
+
+```json
+{
+  "type": "string",
+  "from": "string",
+  "to": "string",
+  "payload": {}
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `type` | `string` | 消息类型标识 |
+| `from` | `string` | 发送者客户端 ID（服务端自动填充） |
+| `to` | `string` | 接收者客户端 ID（服务端自动填充） |
+| `payload` | `object` | 消息负载 |
+
+**服务端转发机制**：对 `offer`、`answer`、`ice-candidate` 等客户端消息，服务端 **不解析 payload**，仅中继转发给房间内另一方，并自动填充 `from` 和 `to` 字段。
+
+---
+
+#### 3.2.1 `error` — 服务端 → 客户端
+
+```json
+{
+  "type": "error",
+  "message": "连接参数无效"
+}
+```
+
+| 触发条件 | message 内容 |
+|----------|-------------|
+| code 或 role 为空 | `"连接参数无效"` |
+| 房间不存在 | `"房间不存在"` |
+| 房间已过期 | `"房间已过期"` |
+| 角色已被占用 | `"房间已满或角色被占用"` |
+
+---
+
+#### 3.2.2 `peer-joined` — 服务端 → 客户端
+
+```json
+{
+  "type": "peer-joined",
+  "from": "webrtc_client_1234567890",
+  "payload": {
+    "role": "receiver"
+  }
+}
+```
+
+**触发**：一方加入房间后，服务端通知已在房间内的另一方。
+
+**客户端处理逻辑**：
+
+| 情况 | 动作 |
+|------|------|
+| sender 收到 `role: "receiver"` | 创建 PeerConnection → 创建 DataChannel → 创建 Offer → 发起 P2P 连接 |
+| receiver 收到 `role: "sender"` | 创建 PeerConnection → 等待 Offer |
+
+---
+
+#### 3.2.3 `offer` — sender → (服务端中继) → receiver
+
+```json
+{
+  "type": "offer",
+  "from": "webrtc_client_XXX",
+  "to": "webrtc_client_YYY",
+  "payload": {
+    "type": "offer",
+    "sdp": "v=0\r\no=- 1234567890 ..."
+  }
+}
+```
+
+**发送时机**：
+1. 初始连接建立时（sender 创建 PeerConnection 后）
+2. 桌面共享添加/移除轨道后（SDP 重协商）
+
+**Offer 发送策略**：
+- 创建 Offer → 设置 LocalDescription → 等待 ICE 收集完成 → 发送完整 SDP
+- ICE 收集超时 5 秒，超时后发送当前已收集的 SDP
+- Offer 配置：`{ offerToReceiveAudio: true, offerToReceiveVideo: true }`
+
+---
+
+#### 3.2.4 `answer` — receiver → (服务端中继) → sender
+
+```json
+{
+  "type": "answer",
+  "from": "webrtc_client_YYY",
+  "to": "webrtc_client_XXX",
+  "payload": {
+    "type": "answer",
+    "sdp": "v=0\r\no=- 9876543210 ..."
+  }
+}
+```
+
+**特殊处理**：如果收到 answer 时当前信令状态已经是 `stable`（可能由于并发重协商），会自动重新创建 Offer 再处理。
+
+---
+
+#### 3.2.5 `ice-candidate` — 双向中继
+
+```json
+{
+  "type": "ice-candidate",
+  "from": "webrtc_client_XXX",
+  "to": "webrtc_client_YYY",
+  "payload": {
+    "candidate": "candidate:842163049 1 udp ...",
+    "sdpMid": "0",
+    "sdpMLineIndex": 0,
+    "usernameFragment": "abc123"
+  }
+}
+```
+
+**发送时机**：`RTCPeerConnection.onicecandidate` 事件触发时。
+
+**⚠️ 已知问题**：如果收到 ICE 候选时 `remoteDescription` 尚未设置，当前代码仅打印日志，**没有实现 ICE 候选缓存队列**。
+
+---
+
+#### 3.2.6 `disconnection` — 双向
+
+**服务端 → 客户端**（对方断开时）：
+```json
+{
+  "type": "disconnection",
+  "from": "webrtc_client_XXX",
+  "payload": {
+    "role": "sender",
+    "message": "对方已停止传输"
+  }
+}
+```
+
+**客户端 → 服务端**（主动断开时）：
+```json
+{
+  "type": "disconnection",
+  "payload": {
+    "reason": "用户主动断开"
+  }
+}
+```
+
+**客户端处理**：关闭 PeerConnection，但保持 WebSocket 连接（允许对方重连后恢复）。
+
+---
+
+### 3.3 信令时序图
+
+```
+sender 浏览器              Go 信令服务器             receiver 浏览器
+     │                          │                          │
+     │   WS connect             │                          │
+     │   ?code=X&role=sender    │                          │
+     ├─────────────────────────►│                          │
+     │   ♦ 注册到房间            │                          │
+     │                          │                          │
+     │                          │   WS connect             │
+     │                          │   ?code=X&role=receiver  │
+     │                          │◄─────────────────────────┤
+     │                          │   ♦ 注册到房间            │
+     │                          │                          │
+     │   peer-joined            │   peer-joined            │
+     │   {role:"receiver"}      │   {role:"sender"}        │
+     │◄─────────────────────────┤──────────────────────────►│
+     │                          │                          │
+     │   ♦ 创建 PC + DC         │                          │
+     │   ♦ createOffer          │                          │
+     │                          │                          │
+     │   offer (SDP)            │                          │
+     ├─────────────────────────►│──────────────────────────►│
+     │                          │   ♦ setRemoteDesc        │
+     │                          │   ♦ createAnswer          │
+     │                          │                          │
+     │                          │   answer (SDP)            │
+     │◄─────────────────────────┤◄──────────────────────────┤
+     │   ♦ setRemoteDesc        │                          │
+     │                          │                          │
+     │   ice-candidate ◄════════╪═══════════════════════════╡  (双向多次)
+     │   ice-candidate ════════►╪═══════════════════════════►│
+     │                          │                          │
+     │   ════════ DataChannel OPEN ═════════════════════════│
+     │                          │                          │
+     │         *** P2P 直连建立，后续数据不经服务器 ***         │
+```
+
+---
+
+## 四、DataChannel P2P 消息协议
+
+### 4.1 DataChannel 配置
+
+| 属性 | 值 | 说明 |
+|------|-----|------|
+| 通道名称 | `"shared-channel"` | 所有功能共享单一通道 |
+| `ordered` | `true` | 消息保序 |
+| `maxRetransmits` | `3` | SCTP 层最大重传次数 |
+| 创建方 | sender | `pc.createDataChannel()` |
+| 接收方 | receiver | `pc.ondatachannel` 事件 |
+
+### 4.2 消息路由机制
+
+所有 DataChannel JSON 消息共享统一格式：
+
+```typescript
+interface WebRTCMessage {
+  type: string;       // 消息类型
+  payload: any;       // 消息负载
+  channel?: string;   // 通道标识（用于路由）
+}
+```
+
+**路由逻辑**：
+
+```
+DataChannel.onmessage(event)
+    │
+    ├─ event.data 是 string
+    │   └─ JSON.parse → WebRTCMessage
+    │       ├─ 有 channel 字段 → 分发给对应通道的 messageHandler
+    │       └─ 无 channel 字段 → 广播给所有已注册的 messageHandler
+    │
+    └─ event.data 是 ArrayBuffer
+        └─ 优先路由到 'file-transfer' 的 dataHandler
+           （无 file-transfer handler 时，路由到第一个注册的 dataHandler）
+```
+
+**已注册通道**：
+
+| 通道名称 | 注册 Hook | 处理的消息类型 |
+|----------|-----------|--------------|
+| `"file-transfer"` | `useFileTransferBusiness` | `file-metadata`, `file-chunk-info`, `file-chunk-ack`, `file-complete`, `file-list`, `file-request` + 二进制 |
+| `"text-transfer"` | `useTextTransferBusiness` | `text-sync`, `text-typing` |
+
+---
+
+### 4.3 文件传输消息 (`channel: "file-transfer"`)
+
+#### 4.3.1 `file-list` — 文件列表同步
+
+**方向**：sender → receiver  
+**触发**：发送方文件选择变更后（150ms 防抖）
+
+```json
+{
+  "type": "file-list",
+  "channel": "file-transfer",
+  "payload": [
+    {
+      "id": "file_1709123456789_a1b2c3d4e",
+      "name": "document.pdf",
+      "size": 1048576,
+      "type": "application/pdf",
+      "status": "ready",
+      "progress": 0
+    }
+  ]
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `payload[].id` | `string` | 文件唯一 ID |
+| `payload[].name` | `string` | 文件名 |
+| `payload[].size` | `number` | 文件大小（字节） |
+| `payload[].type` | `string` | MIME 类型 |
+| `payload[].status` | `string` | `"ready"` / `"downloading"` / `"completed"` |
+| `payload[].progress` | `number` | 0-100 传输进度 |
+
+---
+
+#### 4.3.2 `file-request` — 文件下载请求
+
+**方向**：receiver → sender  
+**触发**：接收方点击"下载"按钮
+
+```json
+{
+  "type": "file-request",
+  "channel": "file-transfer",
+  "payload": {
+    "fileId": "file_1709123456789_a1b2c3d4e",
+    "fileName": "document.pdf"
+  }
+}
+```
+
+---
+
+#### 4.3.3 `file-metadata` — 文件元信息
+
+**方向**：sender → receiver  
+**触发**：开始传输单个文件时
+
+```json
+{
+  "type": "file-metadata",
+  "channel": "file-transfer",
+  "payload": {
+    "id": "file_1709123456789_a1b2c3d4e",
+    "name": "document.pdf",
+    "size": 1048576,
+    "type": "application/pdf"
+  }
+}
+```
+
+**接收方处理**：
+- 初始化 `receivingFiles` Map 条目
+- 计算 totalChunks = `Math.ceil(size / CHUNK_SIZE)`
+- 创建 chunks 数组 `new Array(totalChunks)`
+- 设置 `isTransferring: true`
+
+---
+
+#### 4.3.4 `file-chunk-info` — 块元信息
+
+**方向**：sender → receiver  
+**触发**：发送每个文件块前（紧跟二进制数据）
+
+```json
+{
+  "type": "file-chunk-info",
+  "channel": "file-transfer",
+  "payload": {
+    "fileId": "file_1709123456789_a1b2c3d4e",
+    "chunkIndex": 0,
+    "totalChunks": 0,
+    "checksum": "a1b2c3d4"
+  }
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `fileId` | `string` | 文件 ID |
+| `chunkIndex` | `number` | 块索引（0-based） |
+| `totalChunks` | `number` | **⚠️ 当前恒为 0**，实际总数在 metadata 中 |
+| `checksum` | `string` | CRC32 校验和（8 字符十六进制） |
+
+**⚠️ 设计问题**：`totalChunks` 字段存在但未被正确填充，详见[优缺点分析](#81-协议设计缺陷)。
+
+---
+
+#### 4.3.5 二进制块数据 (`ArrayBuffer`)
+
+**方向**：sender → receiver  
+**紧跟在对应的 `file-chunk-info` 消息之后发送**
+
+- **格式**：纯原始字节，无任何头部或封装
+- **大小**：≤ 256KB（`CHUNK_SIZE = 256 * 1024`），最后一块可能更小
+- **切片方式**：`file.slice(chunkIndex * CHUNK_SIZE, min((chunkIndex + 1) * CHUNK_SIZE, file.size))`
+
+**关联机制**：接收方通过 `expectedChunk.current` 引用关联：
+1. 收到 `file-chunk-info` → 存入 `expectedChunk.current`
+2. 收到 `ArrayBuffer` → 读取 `expectedChunk.current`，验证校验和
+3. 如果收到 `ArrayBuffer` 但 `expectedChunk.current === null` → 打印警告，**丢弃数据**
+
+---
+
+#### 4.3.6 `file-chunk-ack` — 块确认
+
+**方向**：receiver → sender  
+**触发**：接收方处理完每个二进制块后
+
+**成功**：
+```json
+{
+  "type": "file-chunk-ack",
+  "channel": "file-transfer",
+  "payload": {
+    "fileId": "file_xxx",
+    "chunkIndex": 0,
+    "success": true,
+    "checksum": "a1b2c3d4"
+  }
+}
+```
+
+**失败**（校验和不匹配）：
+```json
+{
+  "type": "file-chunk-ack",
+  "channel": "file-transfer",
+  "payload": {
+    "fileId": "file_xxx",
+    "chunkIndex": 0,
+    "success": false,
+    "checksum": "e5f6g7h8"
+  }
+}
+```
+
+---
+
+#### 4.3.7 `file-complete` — 传输完成
+
+**方向**：sender → receiver  
+**触发**：所有块都收到 ACK 确认后
+
+```json
+{
+  "type": "file-complete",
+  "channel": "file-transfer",
+  "payload": {
+    "fileId": "file_1709123456789_a1b2c3d4e"
+  }
+}
+```
+
+**接收方处理**：
+1. 从 `receivingFiles` 取出所有 chunks
+2. `new Blob(chunks, { type: metadata.type })`
+3. `new File([blob], metadata.name, { type: metadata.type })`
+4. 触发 `fileReceivedCallbacks`
+5. 清理 `receivingFiles` Map 条目
+
+---
+
+#### 4.3.8 `sync-request` — 同步请求
+
+**方向**：双向  
+**触发**：DataChannel 打开后延迟 300ms  
+**⚠️ 无 `channel` 字段**，会被广播给所有 handler
+
+```json
+{
+  "type": "sync-request",
+  "payload": {
+    "timestamp": 1709123456789
+  }
+}
+```
+
+**⚠️ 设计问题**：当前没有任何 handler 处理此消息类型，详见[优缺点分析](#83-废弃代码)。
+
+---
+
+### 4.4 文字传输消息 (`channel: "text-transfer"`)
+
+#### 4.4.1 `text-sync` — 文本同步
+
+**方向**：单向（发送方 → 接收方）  
+**触发**：用户编辑 textarea 时实时发送
+
+```json
+{
+  "type": "text-sync",
+  "channel": "text-transfer",
+  "payload": {
+    "text": "输入的文本内容..."
+  }
+}
+```
+
+**特点**：每次发送 **完整文本内容**，不是增量差异。
+
+---
+
+#### 4.4.2 `text-typing` — 打字状态
+
+**方向**：双向  
+**触发**：开始输入时发送 `true`，停止输入 1 秒后发送 `false`
+
+```json
+{
+  "type": "text-typing",
+  "channel": "text-transfer",
+  "payload": {
+    "typing": true
+  }
+}
+```
+
+---
+
+## 五、二进制传输协议
+
+### 5.1 文件分块策略
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| `CHUNK_SIZE` | `256 * 1024` (256KB) | 块大小上限 |
+| 总块数计算 | `Math.ceil(fileSize / CHUNK_SIZE)` | 向上取整 |
+| 切片方式 | `File.slice(start, end)` | 使用 Blob API |
+| 发送顺序 | 严格顺序 (0 → 1 → 2 → ...) | 串行逐块发送 |
+
+### 5.2 CRC32 校验算法
+
+```typescript
+function calculateChecksum(data: ArrayBuffer): string {
+  const buffer = new Uint8Array(data);
+  let crc = 0xFFFFFFFF;
+  for (let i = 0; i < buffer.length; i++) {
+    crc ^= buffer[i];
+    for (let j = 0; j < 8; j++) {
+      crc = crc & 1 ? (crc >>> 1) ^ 0xEDB88320 : crc >>> 1;
+    }
+  }
+  return (crc ^ 0xFFFFFFFF).toString(16).padStart(8, '0');
+}
+```
+
+| 项目 | 说明 |
+|------|------|
+| 算法 | CRC-32 (IEEE 802.3 / ITU-T V.42 反射多项式) |
+| 多项式 | `0xEDB88320` |
+| 输入 | 整个块的 `ArrayBuffer`（最大 256KB） |
+| 输出 | 8 字符十六进制字符串（前补零） |
+| 校验点 | 发送方发送前计算 → 接收方收到后重新计算 → 比对 |
+
+**备用函数** `simpleChecksum()`：仅计算前 1000 字节的简单字节求和。**当前未被调用**。
+
+### 5.3 消息与二进制数据的关联
+
+```
+DataChannel 消息流:
+  ┌──────────────────┐     ┌──────────────────┐
+  │  file-chunk-info │────►│  ArrayBuffer      │
+  │  (JSON string)   │     │  (binary data)    │
+  │                  │     │                    │
+  │  fileId: "xxx"   │     │  [原始文件字节]     │
+  │  chunkIndex: 0   │     │  最大 256KB        │
+  │  checksum: "..." │     │                    │
+  └──────────────────┘     └──────────────────┘
+         ▲                         ▲
+         │                         │
+     必须先到达               必须紧跟其后
+```
+
+接收方使用 `useRef(expectedChunk)` 维护关联状态：
+
+```
+          ┌─────────────────────────────────────────────┐
+          │ expectedChunk.current                        │
+          │                                             │
+  null ───┤  收到 file-chunk-info → 设置 {fileId,       │
+          │                          chunkIndex,         │
+          │                          expectedChecksum}   │
+          │                                             │
+  set ────┤  收到 ArrayBuffer →                          │
+          │    读取 expectedChunk →                      │
+          │    计算 CRC32 →                              │
+          │    比较校验和 →                               │
+          │    发送 ACK →                                │
+          │    重置为 null                               │
+          └─────────────────────────────────────────────┘
+```
+
+---
+
+## 六、可靠传输机制
+
+### 6.1 传输参数
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| `CHUNK_SIZE` | 256KB | 块大小 |
+| `MAX_RETRIES` | 5 | 单块最大重试次数 |
+| `RETRY_DELAY` | 1000ms | 基础重试延迟 |
+| `ACK_TIMEOUT` | 5000ms | ACK 等待超时 |
+
+### 6.2 ACK 协议流程
+
+```
+sendChunkWithAck(fileId, chunkIndex, chunkData)
+    │
+    ├─ 1. 检查通道状态 (closed → 立即失败)
+    │
+    ├─ 2. 注册 ACK 回调到 chunkAckCallbacks Map
+    │      key = "${fileId}-${chunkIndex}"
+    │
+    ├─ 3. 设置 ACK_TIMEOUT (5000ms) 超时定时器
+    │
+    ├─ 4. 发送 file-chunk-info (JSON)
+    │
+    ├─ 5. 发送 chunkData (ArrayBuffer)
+    │
+    └─ 6. 等待 Promise resolve
+         │
+         ├─ 收到 ACK (success: true)  → resolve(true)
+         ├─ 收到 ACK (success: false) → resolve(false)
+         └─ 超时 (5000ms)             → resolve(false)
+```
+
+### 6.3 重试策略 — 指数退避
+
+```
+发送块 → ACK 失败或超时
+    │
+    ├─ retryCount < MAX_RETRIES (5)?
+    │   ├─ 是 → 等待退避延迟 → 重新发送同一块
+    │   └─ 否 → 抛出异常，终止整个文件传输
+    │
+    └─ 退避延迟计算:
+        delay = min(RETRY_DELAY × 2^(retryCount-1), 10000)
+        
+        第 1 次重试: 1000ms
+        第 2 次重试: 2000ms
+        第 3 次重试: 4000ms
+        第 4 次重试: 8000ms
+        第 5 次重试: 10000ms (上限)
+```
+
+### 6.4 自适应流控
+
+```typescript
+// 速度计算 — 指数移动平均 (EMA)
+speed = (chunkBytes / 1024) / timeDiff           // 当前块速度 KB/s
+averageSpeed = averageSpeed * 0.7 + speed * 0.3  // 平滑 (α=0.3)
+
+// 延迟计算
+expectedTime = (chunkSize / 1024) / averageSpeed  // 期望耗时
+actualTime = now - lastChunkTime                   // 实际耗时
+delay = max(0, expectedTime - actualTime)          // 需要额外等待
+
+// 仅在 delay > 10ms 时执行，上限 100ms
+if (delay > 10) await sleep(min(delay, 100))
+```
+
+### 6.5 传输状态追踪
+
+每个正在传输的文件维护一个 `TransferStatus`：
+
+```typescript
+interface TransferStatus {
+  fileId: string;
+  fileName: string;
+  totalChunks: number;
+  sentChunks: Set<number>;          // 已发送的块索引
+  acknowledgedChunks: Set<number>;  // 已收到 ACK 的块索引
+  failedChunks: Set<number>;        // 失败的块索引
+  lastChunkTime: number;            // 最后发送时间戳
+  retryCount: Map<number, number>;  // 块索引 → 重试次数
+  averageSpeed: number;             // EMA 平均速度 (KB/s)
+}
+```
+
+### 6.6 错误恢复矩阵
+
+| 错误类型 | 处理方式 | 恢复策略 |
+|----------|---------|---------|
+| CRC32 校验失败 | 发送 `ACK {success: false}` | 发送方重试该块（指数退避） |
+| ACK 超时 (5s) | `sendChunkWithAck` resolve(false) | 同上，重试该块 |
+| 超过 5 次重试 | 抛出异常 | **终止整个文件传输** |
+| DataChannel 关闭 | 立即抛出 `'数据通道已关闭'` | **终止传输**，更新错误状态 |
+| WebRTC 断连 | 检测到 connecting 状态 | 打印警告，**继续尝试发送** |
+| 传输完整性不匹配 | `acknowledgedChunks.size ≠ totalChunks` | **抛出异常** |
+| 收到二进制但无前置 chunk-info | `expectedChunk === null` | **丢弃数据**，打印警告 |
+| 收到重复块 | `chunks[index] !== undefined` | **跳过**，不重复计数 |
+
+---
+
+## 七、桌面共享 MediaStream 协议
+
+### 7.1 架构特点
+
+桌面共享 **完全不使用 DataChannel 自定义消息**，纯粹依赖 WebRTC 原生的 MediaStream + SDP 重协商机制。
+
+### 7.2 开始共享流程
+
+```
+发送方                                              接收方
+  │                                                    │
+  │  1. getDisplayMedia({video, audio})                │
+  │     └─ cursor: 'always'                            │
+  │     └─ displaySurface: 'monitor'                   │
+  │                                                    │
+  │  2. pc.addTrack(videoTrack, stream)               │
+  │  3. pc.addTrack(audioTrack, stream)  // 可选       │
+  │                                                    │
+  │  4. await 500ms (等待轨道完全添加)                   │
+  │                                                    │
+  │  5. createOfferNow()                               │
+  │     └─ pc.createOffer({                            │
+  │         offerToReceiveAudio: true,                 │
+  │         offerToReceiveVideo: true                  │
+  │       })                                           │
+  │     └─ pc.setLocalDescription                      │
+  │     └─ 等待 ICE 收集 (最多5秒)                      │
+  │                                                    │
+  │  6. WS: offer (含新的媒体 SDP) ─────────────────────►│
+  │                                                    │  7. setRemoteDescription
+  │                                                    │  8. createAnswer
+  │◄────────────────────────────────── WS: answer       │
+  │  9. setRemoteDescription                           │
+  │                                                    │
+  │  10. await 2000ms (等待重协商完成)                    │
+  │                                                    │  11. pc.ontrack 事件
+  │                                                    │      └─ 获取远程 MediaStream
+  │                                                    │      └─ 设置到 <video> 元素
+```
+
+### 7.3 getDisplayMedia 配置
+
+```typescript
+{
+  video: {
+    cursor: 'always',          // 始终显示鼠标
+    displaySurface: 'monitor', // 默认选择整个屏幕
+  },
+  audio: {
+    echoCancellation: false,   // 禁用回声消除
+    noiseSuppression: false,   // 禁用噪声抑制
+    autoGainControl: false,    // 禁用自动增益
+  }
+}
+```
+
+### 7.4 切换桌面源
+
+```
+1. getDisplayMedia(newConfig) → 获取新的 MediaStream
+2. 停止旧流: localStream.getTracks().forEach(t => t.stop())
+3. pc.removeTrack(oldSender)
+4. pc.addTrack(newVideoTrack, newStream)
+5. createOfferNow() → SDP 重新协商
+```
+
+### 7.5 停止共享
+
+```
+1. 停止所有本地轨道: localStream.getTracks().forEach(t => t.stop())
+2. pc.removeTrack(sender) 移除所有 sender
+3. （接收方通过 track.ended 事件感知）
+```
+
+---
+
+## 八、优缺点分析
+
+### 8.1 协议设计缺陷
+
+| 问题 | 严重程度 | 说明 |
+|------|---------|------|
+| **`file-chunk-info.totalChunks` 恒为 0** | 🟡 中 | 发送时填入 0，接收方需从 metadata 自行计算。字段存在但无效，增加了协议理解难度 |
+| **ICE 候选缓存缺失** | 🔴 高 | 如果 ICE 候选先于 remoteDescription 到达，直接被丢弃。在高延迟环境下可能导致连接失败 |
+| **`sync-request` 消息无人处理** | 🟡 中 | DataChannel 打开后会发送此消息，但没有任何 handler 处理，是无效消息 |
+| **`simpleChecksum` 函数未使用** | 🟢 低 | 代码中定义了备用校验函数但从未调用，属于死代码 |
+| **文本同步发送全量内容** | 🟡 中 | 每次按键都发送完整文本，在大文本场景下带宽浪费严重 |
+| **二进制数据仅通过时序关联** | 🟡 中 | chunk-info 和 binary data 的关联完全依赖消息顺序，若 DataChannel 出现消息乱序（理论上 `ordered: true` 可避免），则数据关联会错误 |
+
+### 8.2 架构优点
+
+| 优点 | 说明 |
+|------|------|
+| **纯 P2P 零服务器中转** | 文件/文字/视频全部直传，隐私性极佳，服务器成本极低 |
+| **单 DataChannel 多路复用** | 通过 `channel` 字段路由，避免多连接管理复杂性 |
+| **可靠传输双重保障** | SCTP 底层重传 + 应用层 CRC32 ACK，数据完整性有保证 |
+| **自适应流控** | EMA 平滑速度 + 动态延迟，避免缓冲区溢出 |
+| **信令服务器极简** | Go 后端仅做纯中继，不解析 payload，职责清晰 |
+| **优雅断连处理** | 双方都有断连通知，可区分主动断开和异常断连 |
+| **环境自适应** | 开发/静态/嵌入三种模式自动切换 API 和 WS 地址 |
+| **ICE 可配置** | 支持用户自定义 STUN/TURN 服务器，适应不同网络环境 |
+
+### 8.3 架构缺点
+
+| 缺点 | 影响 | 说明 |
+|------|------|------|
+| **串行逐块传输** | 性能瓶颈 | 每个块必须等 ACK 才发下一个，RTT 越高吞吐越低。100ms RTT 下理论上限 ≈ 256KB/100ms = 2.5MB/s |
+| **大文件内存问题** | 可用性 | 接收方需在内存中缓存所有 chunks 直到文件组装，1GB 文件需 1GB+ 内存 |
+| **单连接瓶颈** | 性能 | 三个功能共享一个 DataChannel，桌面共享重协商可能影响文件传输 |
+| **无断点续传** | 可用性 | 连接断开后无法恢复传输，必须从头开始 |
+| **无并发文件传输** | 体验 | 一次只能传一个文件，多文件必须排队 |
+| **房间仅限 2 人** | 扩展性 | 无法支持一对多或多对多传输 |
+| **无加密层控制** | 安全 | 完全依赖 WebRTC 内建 DTLS，无法自定义加密策略 |
+| **6位取件码无鉴权** | 安全 | 知道取件码就能加入房间，无额外身份验证 |
+| **无传输速度展示** | 体验 | 有 `averageSpeed` 计算但未暴露给 UI 显示 |
+
+---
+
+## 九、设计评价
+
+### 9.1 协议分层设计 — ⭐⭐⭐⭐ (优秀)
+
+```
+应用层 (file-list / file-request / text-sync)
+    │
+可靠传输层 (file-chunk-info + CRC32 + ACK + 重试)
+    │
+路由层 (channel 字段分发)
+    │
+传输层 (WebRTC DataChannel, ordered + maxRetransmits:3)
+    │
+加密层 (DTLS, WebRTC 内建)
+```
+
+分层清晰，每层职责明确。路由层用 `channel` 字段实现了轻量级的多路复用，避免了管理多个 DataChannel 的复杂性。
+
+### 9.2 可靠性设计 — ⭐⭐⭐⭐ (优秀)
+
+- SCTP 底层提供有序传输 + 最多 3 次重传
+- 应用层 CRC32 提供端到端完整性验证
+- 指数退避重试避免了网络抖动时的重试风暴
+- ACK 超时兜底，避免无限等待
+
+两层保障设计合理，但 **串行 ACK 导致了性能瓶颈**。
+
+### 9.3 错误处理 — ⭐⭐⭐ (良好)
+
+覆盖了校验失败、超时、通道关闭、完整性验证等场景。但缺少：
+- 网络波动后的自动重连
+- 断点续传能力
+- 部分传输的清理/恢复
+
+### 9.4 可扩展性 — ⭐⭐ (一般)
+
+- channel 路由机制容易添加新功能
+- 但单 DataChannel + 串行传输限制了扩展空间
+- 房间模型硬编码 2 人，难以支持多人协作
+
+### 9.5 安全性 — ⭐⭐⭐ (良好)
+
+- P2P 直传 + DTLS 加密保障了传输安全
+- 服务器零数据留存
+- 但取件码空间可能被暴力扫描，缺少速率限制
+
+---
+
+## 十、优化建议
+
+### 10.1 🔴 关键优化 — 滑动窗口并发传输
+
+**现状**：串行逐块等待 ACK，RTT 直接决定吞吐上限。
+
+**建议**：实现类似 TCP 的滑动窗口机制：
+
+```
+当前：   [send chunk 0] → [wait ACK 0] → [send chunk 1] → [wait ACK 1] → ...
+                                ▲ 100ms RTT 下吞吐上限 2.5MB/s
+
+优化后： [send 0][send 1][send 2][send 3]  ← 窗口大小 = 4
+              [ACK 0][ACK 1]
+                  [send 4][send 5]          ← 窗口向前滑动
+                                ▲ 窗口=4 时理论吞吐 10MB/s
+```
+
+**实现要点**：
+- 维护发送窗口 `windowSize` (初始 4, 根据丢包率动态调整)
+- 每个 in-flight chunk 独立超时
+- 窗口内的块可并发发送，但需保证接收方能正确关联
+
+**预估收益**：吞吐量提升 3-8 倍。
+
+---
+
+### 10.2 🔴 关键优化 — 二进制帧协议
+
+**现状**：chunk-info (JSON) + binary data (ArrayBuffer) 通过**时序**关联，依赖消息顺序。
+
+**建议**：将元数据编码进二进制帧头部，合并为单个消息：
+
+```
+当前：
+  [JSON: file-chunk-info]  →  [ArrayBuffer: raw data]
+  两条消息，时序依赖
+
+优化后：
+  [ArrayBuffer: header + data]
+  单条消息，自包含
+
+帧格式：
+  ┌──────────────┬───────────┬───────────┬──────────┬─────────────┐
+  │ magic (2B)   │ fileId    │ chunkIdx  │ checksum │ payload     │
+  │ 0xCF 0xDA    │ len(2B)   │ (4B)      │ (4B)     │ (变长)      │
+  │              │ + string  │ uint32    │ CRC32    │ 文件数据     │
+  └──────────────┴───────────┴───────────┴──────────┴─────────────┘
+```
+
+**收益**：
+- 消除时序依赖风险
+- 减少消息数量（每块 2→1）
+- 减少 JSON 序列化/反序列化开销
+- 为滑动窗口提供帧级标识
+
+---
+
+### 10.3 🟡 重要优化 — ICE 候选缓存队列
+
+**现状**：remoteDescription 未设置时，收到的 ICE 候选直接打印日志丢弃。
+
+**建议**：
+
+```typescript
+const pendingCandidates = useRef<RTCIceCandidate[]>([]);
+
+// 收到 ICE 候选时
+if (pc.remoteDescription) {
+  await pc.addIceCandidate(candidate);
+} else {
+  pendingCandidates.current.push(candidate);
+}
+
+// 设置 remoteDescription 后
+await pc.setRemoteDescription(desc);
+for (const c of pendingCandidates.current) {
+  await pc.addIceCandidate(c);
+}
+pendingCandidates.current = [];
+```
+
+**收益**：避免在高延迟网络下丢失 ICE 候选导致连接失败。
+
+---
+
+### 10.4 🟡 重要优化 — 流式文件写入
+
+**现状**：接收方将所有 chunks 缓存在内存数组中，文件完成后合并为 Blob。大文件占用大量内存。
+
+**建议**：使用 `StreamSaver.js` 或 OPFS (Origin Private File System) 流式写入磁盘：
+
+```typescript
+// 使用 File System Access API
+const handle = await window.showSaveFilePicker({ suggestedName: fileName });
+const writable = await handle.createWritable();
+
+// 每收到一个 chunk
+await writable.write(chunkData);  // 直接写入磁盘
+
+// 传输完成
+await writable.close();
+```
+
+**收益**：内存使用从 O(fileSize) 降低到 O(chunkSize)，支持 GB 级文件传输。
+
+---
+
+### 10.5 🟡 重要优化 — 文本增量同步
+
+**现状**：每次按键发送完整文本内容。10KB 的文本每按一次键发送 10KB+。
+
+**建议**：使用操作变换 (OT) 或 CRDT，或最简单的 diff：
+
+```typescript
+// 简易 diff 方案
+function createTextDiff(oldText: string, newText: string) {
+  // 找到最长公共前缀和后缀
+  let prefixLen = 0;
+  while (prefixLen < oldText.length && prefixLen < newText.length 
+         && oldText[prefixLen] === newText[prefixLen]) prefixLen++;
+  
+  let suffixLen = 0;
+  while (suffixLen < oldText.length - prefixLen 
+         && suffixLen < newText.length - prefixLen
+         && oldText[oldText.length - 1 - suffixLen] === newText[newText.length - 1 - suffixLen]) 
+    suffixLen++;
+  
+  return {
+    offset: prefixLen,
+    deleteCount: oldText.length - prefixLen - suffixLen,
+    insertText: newText.slice(prefixLen, newText.length - suffixLen || undefined)
+  };
+}
+
+// 消息格式
+{
+  "type": "text-diff",
+  "channel": "text-transfer",
+  "payload": {
+    "offset": 5,
+    "deleteCount": 0,
+    "insertText": "a",
+    "version": 42
+  }
+}
+```
+
+**收益**：带宽消耗从 O(textLength) 降低到 O(editSize)。
+
+---
+
+### 10.6 🟢 建议优化 — chunk-info.totalChunks 修复
+
+**现状**：`file-chunk-info.payload.totalChunks` 恒为 0。
+
+**建议**：正确填入实际值：
+
+```typescript
+// 发送时
+payload: {
+  fileId,
+  chunkIndex,
+  totalChunks: Math.ceil(file.size / CHUNK_SIZE),  // 填入实际值
+  checksum
+}
+```
+
+**收益**：协议自洽，接收方可直接从 chunk-info 获取总数，无需依赖先前的 metadata。
+
+---
+
+### 10.7 🟢 建议优化 — 清理死代码
+
+| 待清理项 | 位置 |
+|----------|------|
+| `simpleChecksum()` 函数 | `useFileTransferBusiness.ts` |
+| `sync-request` 消息发送逻辑 | `useWebRTCDataChannelManager.ts` |
+| `file-chunk-info.totalChunks` 赋值为 0 | `useFileTransferBusiness.ts` |
+
+---
+
+### 10.8 🟢 建议优化 — 传输速度 UI 展示
+
+**现状**：`averageSpeed` 已在 `TransferStatus` 中计算，但未暴露给 UI。
+
+**建议**：在文件传输进度条旁边显示实时速度：
+
+```
+📄 document.pdf    ███████░░░░░ 65%    12.3 MB/s    剩余 ~3s
+```
+
+---
+
+### 10.9 🟢 建议优化 — 房间安全加固
+
+| 措施 | 说明 |
+|------|------|
+| **连接速率限制** | 同一 IP 每分钟最多尝试 N 次房间连接 |
+| **房间码验证延迟** | 错误码时增加响应延迟（如 1s），阻止暴力扫描 |
+| **可选密码保护** | 创建房间时可设置密码，加入时需输入 |
+| **HMAC 签名** | 房间码 + 时间戳的 HMAC 签名，防止伪造 |
+
+---
+
+### 10.10 优化优先级总览
+
+| 优先级 | 优化项 | 预估收益 | 实现难度 |
+|--------|--------|---------|---------|
+| 🔴 P0 | 滑动窗口并发传输 | 吞吐量 3-8x | 高 |
+| 🔴 P0 | 二进制帧协议 | 消除时序依赖 + 减少消息量 | 中 |
+| 🟡 P1 | ICE 候选缓存 | 连接成功率提升 | 低 |
+| 🟡 P1 | 流式文件写入 | GB 文件支持 | 中 |
+| 🟡 P1 | 文本增量同步 | 带宽节约 > 90% | 中 |
+| 🟢 P2 | totalChunks 修复 | 协议一致性 | 极低 |
+| 🟢 P2 | 清理死代码 | 代码质量 | 极低 |
+| 🟢 P2 | 速度 UI 展示 | 用户体验 | 低 |
+| 🟢 P2 | 房间安全加固 | 安全性 | 中 |
diff --git a/chuan-next/src/components/WebRTCConnectionStatus.tsx b/chuan-next/src/components/WebRTCConnectionStatus.tsx
deleted file mode 100644
index 1578be4..0000000
--- a/chuan-next/src/components/WebRTCConnectionStatus.tsx
+++ /dev/null
@@ -1,185 +0,0 @@
-import React from 'react';
-import { AlertCircle, Wifi, WifiOff, Loader2, RotateCcw } from 'lucide-react';
-import { WebRTCConnection } from '@/hooks/connection/useSharedWebRTCManager';
-
-interface Props {
-  webrtc: WebRTCConnection;
-  className?: string;
-}
-
-/**
- * WebRTC连接状态显示组件
- * 显示详细的连接状态、错误信息和重试按钮
- */
-export function WebRTCConnectionStatus({ webrtc, className = '' }: Props) {
-  const {
-    isConnected,
-    isConnecting,
-    isWebSocketConnected,
-    isPeerConnected,
-    error,
-    canRetry,
-    retry
-  } = webrtc;
-
-  // 状态图标
-  const getStatusIcon = () => {
-    if (isConnecting) {
-      return <Loader2 className="h-4 w-4 animate-spin text-blue-500" />;
-    }
-    
-    if (error) {
-      // 区分信息提示和错误
-      if (error.includes('对方已离开房间') || error.includes('已离开房间')) {
-        return <WifiOff className="h-4 w-4 text-yellow-500" />;
-      }
-      return <AlertCircle className="h-4 w-4 text-red-500" />;
-    }
-    
-    if (isPeerConnected) {
-      return <Wifi className="h-4 w-4 text-green-500" />;
-    }
-    
-    if (isWebSocketConnected) {
-      return <Wifi className="h-4 w-4 text-yellow-500" />;
-    }
-    
-    return <WifiOff className="h-4 w-4 text-gray-400" />;
-  };
-
-  // 状态文本
-  const getStatusText = () => {
-    if (error) {
-      return error;
-    }
-    
-    if (isConnecting) {
-      return '正在连接...';
-    }
-    
-    if (isPeerConnected) {
-      return 'P2P连接已建立';
-    }
-    
-    if (isWebSocketConnected) {
-      return '信令服务器已连接';
-    }
-    
-    return '未连接';
-  };
-
-  // 状态颜色
-  const getStatusColor = () => {
-    if (error) {
-      // 区分信息提示和错误
-      if (error.includes('对方已离开房间') || error.includes('已离开房间')) {
-        return 'text-yellow-600';
-      }
-      return 'text-red-600';
-    }
-    if (isConnecting) return 'text-blue-600';
-    if (isPeerConnected) return 'text-green-600';
-    if (isWebSocketConnected) return 'text-yellow-600';
-    return 'text-gray-600';
-  };
-
-  const handleRetry = async () => {
-    try {
-      await retry();
-    } catch (error) {
-      console.error('重试连接失败:', error);
-    }
-  };
-
-  return (
-    <div className={`flex items-center justify-between p-3 bg-white border rounded-lg ${className}`}>
-      <div className="flex items-center gap-2">
-        {getStatusIcon()}
-        <span className={`text-sm font-medium ${getStatusColor()}`}>
-          {getStatusText()}
-        </span>
-      </div>
-      
-      {/* 连接详细状态指示器 */}
-      <div className="flex items-center gap-1">
-        {/* WebSocket状态 */}
-        <div 
-          className={`w-2 h-2 rounded-full ${
-            isWebSocketConnected ? 'bg-green-400' : 'bg-gray-300'
-          }`}
-          title={isWebSocketConnected ? 'WebSocket已连接' : 'WebSocket未连接'}
-        />
-        
-        {/* P2P状态 */}
-        <div 
-          className={`w-2 h-2 rounded-full ${
-            isPeerConnected ? 'bg-green-400' : 'bg-gray-300'
-          }`}
-          title={isPeerConnected ? 'P2P连接已建立' : 'P2P连接未建立'}
-        />
-        
-        {/* 重试按钮 */}
-        {canRetry && (
-          <button
-            onClick={handleRetry}
-            disabled={isConnecting}
-            className="ml-2 p-1 text-gray-500 hover:text-blue-500 disabled:opacity-50 disabled:cursor-not-allowed"
-            title="重试连接"
-          >
-            <RotateCcw className={`h-3 w-3 ${isConnecting ? 'animate-spin' : ''}`} />
-          </button>
-        )}
-      </div>
-    </div>
-  );
-}
-
-/**
- * 简单的连接状态指示器（用于空间受限的地方）
- */
-export function WebRTCStatusIndicator({ webrtc, className = '' }: Props) {
-  const { isPeerConnected, isConnecting, error } = webrtc;
-  
-  if (error) {
-    // 区分信息提示和错误
-    if (error.includes('对方已离开房间') || error.includes('已离开房间')) {
-      return (
-        <div className={`flex items-center gap-1 ${className}`}>
-          <div className="w-2 h-2 bg-yellow-400 rounded-full" />
-          <span className="text-xs text-yellow-600">对方已离开</span>
-        </div>
-      );
-    }
-    return (
-      <div className={`flex items-center gap-1 ${className}`}>
-        <div className="w-2 h-2 bg-red-400 rounded-full animate-pulse" />
-        <span className="text-xs text-red-600">连接错误</span>
-      </div>
-    );
-  }
-  
-  if (isConnecting) {
-    return (
-      <div className={`flex items-center gap-1 ${className}`}>
-        <div className="w-2 h-2 bg-blue-400 rounded-full animate-pulse" />
-        <span className="text-xs text-blue-600">连接中</span>
-      </div>
-    );
-  }
-  
-  if (isPeerConnected) {
-    return (
-      <div className={`flex items-center gap-1 ${className}`}>
-        <div className="w-2 h-2 bg-green-400 rounded-full" />
-        <span className="text-xs text-green-600">已连接</span>
-      </div>
-    );
-  }
-  
-  return (
-    <div className={`flex items-center gap-1 ${className}`}>
-      <div className="w-2 h-2 bg-gray-300 rounded-full" />
-      <span className="text-xs text-gray-600">未连接</span>
-    </div>
-  );
-}
diff --git a/chuan-next/src/components/WebRTCFileTransfer.tsx b/chuan-next/src/components/WebRTCFileTransfer.tsx
index db9426c..edd6ffe 100644
--- a/chuan-next/src/components/WebRTCFileTransfer.tsx
+++ b/chuan-next/src/components/WebRTCFileTransfer.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import React, { useState, useEffect, useRef, useCallback, useMemo } from 'react';
-import { useSharedWebRTCManager, useConnectionState, useRoomConnection } from '@/hooks/connection';
+import { useSharedWebRTCManager, useRoomConnection } from '@/hooks/connection';
 import { useFileTransferBusiness, useFileListSync, useFileStateManager } from '@/hooks/file-transfer';
 import { useURLHandler } from '@/hooks/ui';
 import { Button } from '@/components/ui/button';
@@ -9,15 +9,7 @@ import { useToast } from '@/components/ui/toast-simple';
 import { Upload, Download } from 'lucide-react';
 import { WebRTCFileUpload } from '@/components/webrtc/WebRTCFileUpload';
 import { WebRTCFileReceive } from '@/components/webrtc/WebRTCFileReceive';
-
-interface FileInfo {
-  id: string;
-  name: string;
-  size: number;
-  type: string;
-  status: 'ready' | 'downloading' | 'completed';
-  progress: number;
-}
+import type { FileInfo } from '@/types';
 
 export const WebRTCFileTransfer: React.FC = () => {
   const { showToast } = useToast();
@@ -101,23 +93,6 @@ export const WebRTCFileTransfer: React.FC = () => {
     onAutoJoinRoom: joinRoom
   });
 
-  useConnectionState({
-    isWebSocketConnected,
-    isConnected,
-    isConnecting,
-    error: error || '',
-    pickupCode,
-    fileListLength: fileList.length,
-    currentTransferFile,
-    setCurrentTransferFile,
-    updateFileListStatus: setFileList
-  });
-
-  // 生成文件ID
-  const generateFileId = () => {
-    return Date.now().toString(36) + Math.random().toString(36).substr(2);
-  };
-
   // 创建房间 (发送模式)
   const generateCode = async () => {
     if (selectedFiles.length === 0) {
@@ -189,286 +164,87 @@ export const WebRTCFileTransfer: React.FC = () => {
     // URL处理逻辑已经移到 hook 中
   };
 
-    // 处理文件列表更新
+  // === 注册所有数据通道回调 ===
   useEffect(() => {
-    const cleanup = onFileListReceived((fileInfos: FileInfo[]) => {
-      console.log('=== 收到文件列表更新 ===');
-      console.log('文件列表:', fileInfos);
-      
-      if (mode === 'receive') {
-        setFileList(fileInfos);
-      }
-    });
-
-    return cleanup;
-  }, [onFileListReceived, mode]);
-
-  // 处理文件接收
-  useEffect(() => {
-    const cleanup = onFileReceived((fileData: { id: string; file: File }) => {
-      console.log('=== 接收到文件 ===');
-      console.log('文件:', fileData.file.name, 'ID:', fileData.id);
-      
-      // 更新下载的文件
-      setDownloadedFiles(prev => new Map(prev.set(fileData.id, fileData.file)));
-      
-      // 更新文件状态
-      updateFileStatus(fileData.id, 'completed', 100);
-    });
-
-    return cleanup;
-  }, [onFileReceived, updateFileStatus]);
-
-  // 监听文件级别的进度更新
-  useEffect(() => {
-    const cleanup = onFileProgress((progressInfo) => {
-      // 检查连接状态，如果连接断开则忽略进度更新
-      if (!isConnected || error) {
-        console.log('连接已断开，忽略进度更新:', progressInfo.fileName);
-        return;
-      }
-
-      console.log('=== 文件进度更新 ===');
-      console.log('文件:', progressInfo.fileName, 'ID:', progressInfo.fileId, '进度:', progressInfo.progress);
-      
-      // 更新当前传输文件信息
-      setCurrentTransferFile({
-        fileId: progressInfo.fileId,
-        fileName: progressInfo.fileName,
-        progress: progressInfo.progress
-      });
-      
-      // 更新文件进度
-      updateFileProgress(progressInfo.fileId, progressInfo.fileName, progressInfo.progress);
-      
-      // 当传输完成时清理
-      if (progressInfo.progress >= 100 && mode === 'send') {
-        setCurrentTransferFile(null);
-      }
-    });
-
-    return cleanup;
-  }, [onFileProgress, mode, isConnected, error, updateFileProgress]);
-
-  // 处理文件请求（发送方监听）
-  useEffect(() => {
-    const cleanup = onFileRequested((fileId: string, fileName: string) => {
-      console.log('=== 收到文件请求 ===');
-      console.log('文件:', fileName, 'ID:', fileId, '当前模式:', mode);
-      
-      if (mode === 'send') {
-        // 检查连接状态
+    const cleanups = [
+      onFileListReceived((fileInfos: FileInfo[]) => {
+        if (mode === 'receive') setFileList(fileInfos);
+      }),
+      onFileReceived((fileData: { id: string; file: File }) => {
+        setDownloadedFiles(prev => new Map(prev.set(fileData.id, fileData.file)));
+        updateFileStatus(fileData.id, 'completed', 100);
+      }),
+      onFileProgress((progressInfo) => {
+        if (!isConnected || error) return;
+        setCurrentTransferFile({
+          fileId: progressInfo.fileId,
+          fileName: progressInfo.fileName,
+          progress: progressInfo.progress
+        });
+        updateFileProgress(progressInfo.fileId, progressInfo.fileName, progressInfo.progress);
+        if (progressInfo.progress >= 100 && mode === 'send') {
+          setCurrentTransferFile(null);
+        }
+      }),
+      onFileRequested((fileId: string, fileName: string) => {
+        if (mode !== 'send') return;
         if (!isConnected || error) {
-          console.log('连接已断开，无法发送文件');
           showToast('连接已断开，无法发送文件', "error");
           return;
         }
-
-        console.log('当前选中的文件列表:', selectedFiles.map(f => f.name));
-        
-        // 在发送方的selectedFiles中查找对应文件
         const file = selectedFiles.find(f => f.name === fileName);
-        
         if (!file) {
-          console.error('找不到匹配的文件:', fileName);
-          console.log('可用文件:', selectedFiles.map(f => `${f.name} (${f.size} bytes)`));
           showToast(`无法找到文件: ${fileName}`, "error");
           return;
         }
-        
-        console.log('找到匹配文件，开始发送:', file.name, 'ID:', fileId, '文件大小:', file.size);
-        
-        // 更新发送方文件状态为downloading - 统一使用updateFileStatus
         updateFileStatus(fileId, 'downloading', 0);
-        
-        // 发送文件
         try {
           sendFile(file, fileId);
-          
-          // 移除不必要的Toast - 传输开始状态在UI中已经显示
         } catch (sendError) {
           console.error('发送文件失败:', sendError);
           showToast(`发送文件失败: ${fileName}`, "error");
-          
-          // 重置文件状态 - 统一使用updateFileStatus
           updateFileStatus(fileId, 'ready', 0);
         }
-      } else {
-        console.warn('接收模式下收到文件请求，忽略');
+      })
+    ];
+    return () => cleanups.forEach(cleanup => cleanup());
+  }, [onFileListReceived, onFileReceived, onFileProgress, onFileRequested,
+      mode, isConnected, error, selectedFiles, sendFile, showToast,
+      updateFileStatus, updateFileProgress]);
+
+  // === 错误处理和连接状态清理 ===
+  const lastErrorRef = useRef<string>('');
+  useEffect(() => {
+    // 处理新错误
+    if (error && error !== lastErrorRef.current) {
+      lastErrorRef.current = error;
+      const errorMap: [string, string][] = [
+        ['WebSocket', '服务器连接失败，请检查网络连接或稍后重试'],
+        ['数据通道', '数据通道连接失败，请重新尝试连接'],
+        ['连接超时', '连接超时，请检查网络状况或重新尝试'],
+        ['连接失败', 'WebRTC连接失败，可能是网络环境限制，请尝试刷新页面'],
+        ['信令错误', '信令服务器错误，请稍后重试'],
+        ['创建连接失败', '无法建立P2P连接，请检查网络设置'],
+      ];
+      const matched = errorMap.find(([key]) => error.includes(key));
+      showToast(matched ? matched[1] : error, "error");
+    }
+
+    // 连接断开时清理传输状态
+    const isDisconnected = pickupCode && !isConnecting && (!isConnected || error);
+    if (isDisconnected && (fileList.length > 0 || currentTransferFile)) {
+      if (!error && !isWebSocketConnected) {
+        showToast('与服务器的连接已断开，请重新连接', "error");
       }
-    });
-
-    return cleanup;
-  }, [onFileRequested, mode, selectedFiles, sendFile, isConnected, error, showToast, updateFileStatus]);
-
-  // 处理连接错误
-  const [lastError, setLastError] = useState<string>('');
-  useEffect(() => {
-    if (error && error !== lastError) {
-      console.log('=== 连接错误处理 ===');
-      console.log('错误信息:', error);
-      console.log('当前模式:', mode);
-      
-      // 根据错误类型显示不同的提示
-      let errorMessage = error;
-      
-      if (error.includes('WebSocket')) {
-        errorMessage = '服务器连接失败，请检查网络连接或稍后重试';
-      } else if (error.includes('数据通道')) {
-        errorMessage = '数据通道连接失败，请重新尝试连接';
-      } else if (error.includes('连接超时')) {
-        errorMessage = '连接超时，请检查网络状况或重新尝试';
-      } else if (error.includes('连接失败')) {
-        errorMessage = 'WebRTC连接失败，可能是网络环境限制，请尝试刷新页面';
-      } else if (error.includes('信令错误')) {
-        errorMessage = '信令服务器错误，请稍后重试';
-      } else if (error.includes('创建连接失败')) {
-        errorMessage = '无法建立P2P连接，请检查网络设置';
-      }
-      
-      // 显示错误提示
-      showToast(errorMessage, "error");
-      setLastError(error);
-      
-      // 如果是严重连接错误，清理传输状态
-      if (error.includes('连接失败') || error.includes('数据通道连接失败') || error.includes('WebSocket')) {
-        console.log('严重连接错误，清理传输状态');
-        setCurrentTransferFile(null);
-        
-        // 重置所有正在传输的文件状态
-        setFileList(prev => prev.map(item => 
-          item.status === 'downloading' 
-            ? { ...item, status: 'ready' as const, progress: 0 }
-            : item
-        ));
-      }
-    }
-  }, [error, mode, showToast, lastError]);
-
-
-
-  // 监听连接状态变化和清理传输状态
-  useEffect(() => {
-    console.log('=== 连接状态变化 ===');
-    console.log('WebSocket连接状态:', isWebSocketConnected);
-    console.log('WebRTC连接状态:', isConnected);
-    console.log('连接中状态:', isConnecting);
-    
-    // 当连接断开或有错误时，清理所有传输状态
-    const shouldCleanup = (!isWebSocketConnected && !isConnected && !isConnecting && pickupCode) || 
-                         ((!isConnected && !isConnecting) || error);
-    
-    if (shouldCleanup) {
-      const hasCurrentTransfer = !!currentTransferFile;
-      const hasFileList = fileList.length > 0;
-      
-      // 只有在之前有连接活动时才显示断开提示和清理状态
-      if (hasFileList || hasCurrentTransfer) {
-        if (!isWebSocketConnected && pickupCode) {
-          showToast('与服务器的连接已断开，请重新连接', "error");
-        }
-        
-        console.log('连接断开，清理传输状态');
-        
-        if (currentTransferFile) {
-          setCurrentTransferFile(null);
-        }
-        
-        // 重置所有正在下载的文件状态
-        setFileList(prev => {
-          const hasDownloadingFiles = prev.some(item => item.status === 'downloading');
-          if (hasDownloadingFiles) {
-            console.log('重置正在传输的文件状态');
-            return prev.map(item => 
-              item.status === 'downloading' 
-                ? { ...item, status: 'ready' as const, progress: 0 }
-                : item
-            );
-          }
-          return prev;
-        });
-      }
-    }
-    
-    // WebSocket连接成功时的提示
-    if (isWebSocketConnected && isConnecting && !isConnected) {
-      console.log('WebSocket已连接，正在建立P2P连接...');
-    }
-    
-  }, [isWebSocketConnected, isConnected, isConnecting, pickupCode, error, showToast, currentTransferFile, fileList.length]);
-
-  // 监听连接状态变化并提供日志
-  useEffect(() => {
-    console.log('=== WebRTC连接状态变化 ===');
-    console.log('连接状态:', {
-      isConnected,
-      isConnecting,
-      isWebSocketConnected,
-      pickupCode,
-      mode,
-      selectedFilesCount: selectedFiles.length,
-      fileListCount: fileList.length
-    });
-  }, [isConnected, connection.isPeerConnected, isConnecting, isWebSocketConnected, pickupCode, mode, selectedFiles.length, fileList.length]);
-
-  // 监听P2P连接建立时的状态变化
-  useEffect(() => {
-    if (connection.isPeerConnected && mode === 'send' && fileList.length > 0) {
-      console.log('P2P连接已建立，数据通道首次打开，初始化文件列表');
-      // 数据通道第一次打开时进行初始化
-      syncFileListToReceiver(fileList, '数据通道初始化');
-    }
-  }, [connection.isPeerConnected, mode, syncFileListToReceiver]);
-
-  // 监听fileList大小变化并同步
-  useEffect(() => {
-    if (connection.isPeerConnected && mode === 'send' && pickupCode) {
-      console.log('fileList大小变化，同步到接收方:', fileList.length);
-      syncFileListToReceiver(fileList, 'fileList大小变化');
-    }
-  }, [fileList.length, connection.isPeerConnected, mode, pickupCode, syncFileListToReceiver]);
-
-  // 监听selectedFiles变化，同步更新fileList并发送给接收方
-  useEffect(() => {
-    // 只有在发送模式下且已有房间时才处理文件列表同步
-    if (mode !== 'send' || !pickupCode) return;
-
-    console.log('=== selectedFiles变化，同步文件列表 ===', {
-      selectedFilesCount: selectedFiles.length,
-      fileListCount: fileList.length,
-      selectedFileNames: selectedFiles.map(f => f.name)
-    });
-
-    // 根据selectedFiles创建新的文件信息列表
-    const newFileInfos: FileInfo[] = selectedFiles.map(file => {
-      // 尝试找到现有的文件信息，保持已有的状态
-      const existingFileInfo = fileList.find(info => info.name === file.name && info.size === file.size);
-      return existingFileInfo || {
-        id: generateFileId(),
-        name: file.name,
-        size: file.size,
-        type: file.type,
-        status: 'ready' as const,
-        progress: 0
-      };
-    });
-
-    // 检查文件列表是否真正发生变化
-    const fileListChanged = 
-      newFileInfos.length !== fileList.length ||
-      newFileInfos.some(newFile => 
-        !fileList.find(oldFile => oldFile.name === newFile.name && oldFile.size === newFile.size)
-      );
-
-    if (fileListChanged) {
-      console.log('文件列表发生变化，更新:', {
-        before: fileList.map(f => f.name),
-        after: newFileInfos.map(f => f.name)
+      setCurrentTransferFile(null);
+      setFileList(prev => {
+        const hasDownloading = prev.some(item => item.status === 'downloading');
+        return hasDownloading
+          ? prev.map(item => item.status === 'downloading' ? { ...item, status: 'ready' as const, progress: 0 } : item)
+          : prev;
       });
-      
-      setFileList(newFileInfos);
     }
-  }, [selectedFiles, mode, pickupCode]);
+  }, [error, isConnected, isConnecting, isWebSocketConnected, pickupCode, showToast, currentTransferFile, fileList.length]);
 
   // 请求下载文件（接收方调用）
   const requestFile = (fileId: string) => {
diff --git a/chuan-next/src/components/webrtc/WebRTCDesktopReceiver.tsx b/chuan-next/src/components/webrtc/WebRTCDesktopReceiver.tsx
index 6d7eee6..4bd0982 100644
--- a/chuan-next/src/components/webrtc/WebRTCDesktopReceiver.tsx
+++ b/chuan-next/src/components/webrtc/WebRTCDesktopReceiver.tsx
@@ -8,6 +8,7 @@ import { useToast } from '@/components/ui/toast-simple';
 import { useDesktopShareBusiness } from '@/hooks/desktop-share';
 import DesktopViewer from '@/components/DesktopViewer';
 import { ConnectionStatus } from '@/components/ConnectionStatus';
+import { validateRoomCode, checkRoomStatus, handleNetworkError } from '@/lib/room-utils';
 
 interface WebRTCDesktopReceiverProps {
   className?: string;
@@ -37,8 +38,9 @@ export default function WebRTCDesktopReceiver({ className, initialCode, onConnec
     const trimmedCode = inputCode.trim();
     
     // 检查房间代码格式
-    if (!trimmedCode || trimmedCode.length !== 6) {
-      showToast('请输入正确的6位房间代码', "error");
+    const validationError = validateRoomCode(trimmedCode);
+    if (validationError) {
+      showToast(validationError, "error");
       return;
     }
 
@@ -53,35 +55,9 @@ export default function WebRTCDesktopReceiver({ className, initialCode, onConnec
     try {
       console.log('[DesktopShareReceiver] 开始验证房间状态...');
       
-      // 先检查房间状态
-      const response = await fetch(`/api/room-info?code=${trimmedCode}`);
-      
-      if (!response.ok) {
-        throw new Error(`HTTP ${response.status}: 无法检查房间状态`);
-      }
-      
-      const result = await response.json();
-      
+      const result = await checkRoomStatus(trimmedCode);
       if (!result.success) {
-        let errorMessage = result.message || '房间不存在或已过期';
-        if (result.message?.includes('expired')) {
-          errorMessage = '房间已过期，请联系发送方重新创建';
-        } else if (result.message?.includes('not found')) {
-          errorMessage = '房间不存在，请检查房间代码是否正确';
-        }
-        showToast(errorMessage, "error");
-        return;
-      }
-      
-      // 检查房间是否已满
-      if (result.is_room_full) {
-        showToast('当前房间人数已满，正在传输中无法加入，请稍后再试', "error");
-        return;
-      }
-      
-      // 检查发送方是否在线
-      if (!result.sender_online) {
-        showToast('发送方不在线，请确认房间代码是否正确或联系发送方', "error");
+        showToast(result.error || '房间验证失败', "error");
         return;
       }
       
@@ -94,26 +70,11 @@ export default function WebRTCDesktopReceiver({ className, initialCode, onConnec
       showToast('已加入桌面共享', 'success');
     } catch (error) {
       console.error('[DesktopShareReceiver] 加入观看失败:', error);
-      
-      let errorMessage = '加入观看失败';
-      if (error instanceof Error) {
-        if (error.message.includes('network') || error.message.includes('fetch')) {
-          errorMessage = '网络连接失败，请检查网络状况';
-        } else if (error.message.includes('timeout')) {
-          errorMessage = '请求超时，请重试';
-        } else if (error.message.includes('HTTP 404')) {
-          errorMessage = '房间不存在，请检查房间代码';
-        } else if (error.message.includes('HTTP 500')) {
-          errorMessage = '服务器错误，请稍后重试';
-        } else {
-          errorMessage = error.message;
-        }
-      }
-      
+      const errorMessage = error instanceof Error ? handleNetworkError(error) : '加入观看失败';
       showToast(errorMessage, 'error');
     } finally {
       setIsLoading(false);
-      setIsJoiningRoom(false); // 重置加入房间状态
+      setIsJoiningRoom(false);
     }
   }, [desktopShare, inputCode, isJoiningRoom, showToast]);
 
@@ -148,8 +109,9 @@ export default function WebRTCDesktopReceiver({ className, initialCode, onConnec
         const trimmedCode = initialCode.trim();
         
         // 检查房间代码格式
-        if (!trimmedCode || trimmedCode.length !== 6) {
-          showToast('房间代码格式不正确', "error");
+        const validationError = validateRoomCode(trimmedCode);
+        if (validationError) {
+          showToast(validationError, "error");
           return;
         }
         
@@ -157,36 +119,11 @@ export default function WebRTCDesktopReceiver({ className, initialCode, onConnec
         console.log('[WebRTCDesktopReceiver] 检测到初始代码，开始验证并自动加入:', trimmedCode);
         
         try {
-          // 先检查房间状态
           console.log('[WebRTCDesktopReceiver] 验证房间状态...');
-          const response = await fetch(`/api/room-info?code=${trimmedCode}`);
-          
-          if (!response.ok) {
-            throw new Error(`HTTP ${response.status}: 无法检查房间状态`);
-          }
-          
-          const result = await response.json();
+          const result = await checkRoomStatus(trimmedCode);
           
           if (!result.success) {
-            let errorMessage = result.message || '房间不存在或已过期';
-            if (result.message?.includes('expired')) {
-              errorMessage = '房间已过期，请联系发送方重新创建';
-            } else if (result.message?.includes('not found')) {
-              errorMessage = '房间不存在，请检查房间代码是否正确';
-            }
-            showToast(errorMessage, "error");
-            return;
-          }
-          
-          // 检查房间是否已满
-          if (result.is_room_full) {
-            showToast('当前房间人数已满，正在传输中无法加入，请稍后再试', "error");
-            return;
-          }
-          
-          // 检查发送方是否在线
-          if (!result.sender_online) {
-            showToast('发送方不在线，请确认房间代码是否正确或联系发送方', "error");
+            showToast(result.error || '房间验证失败', "error");
             return;
           }
           
@@ -198,22 +135,7 @@ export default function WebRTCDesktopReceiver({ className, initialCode, onConnec
           showToast('已加入桌面共享', 'success');
         } catch (error) {
           console.error('[WebRTCDesktopReceiver] 自动加入观看失败:', error);
-          
-          let errorMessage = '自动加入观看失败';
-          if (error instanceof Error) {
-            if (error.message.includes('network') || error.message.includes('fetch')) {
-              errorMessage = '网络连接失败，请检查网络状况';
-            } else if (error.message.includes('timeout')) {
-              errorMessage = '请求超时，请重试';
-            } else if (error.message.includes('HTTP 404')) {
-              errorMessage = '房间不存在，请检查房间代码';
-            } else if (error.message.includes('HTTP 500')) {
-              errorMessage = '服务器错误，请稍后重试';
-            } else {
-              errorMessage = error.message;
-            }
-          }
-          
+          const errorMessage = error instanceof Error ? handleNetworkError(error) : '自动加入观看失败';
           showToast(errorMessage, 'error');
         } finally {
           setIsLoading(false);
diff --git a/chuan-next/src/components/webrtc/WebRTCFileReceive.tsx b/chuan-next/src/components/webrtc/WebRTCFileReceive.tsx
index 945245e..f290954 100644
--- a/chuan-next/src/components/webrtc/WebRTCFileReceive.tsx
+++ b/chuan-next/src/components/webrtc/WebRTCFileReceive.tsx
@@ -6,15 +6,8 @@ import { Input } from '@/components/ui/input';
 import { Download, FileText, Image, Video, Music, Archive } from 'lucide-react';
 import { useToast } from '@/components/ui/toast-simple';
 import { ConnectionStatus } from '@/components/ConnectionStatus';
-
-interface FileInfo {
-  id: string;
-  name: string;
-  size: number;
-  type: string;
-  status: 'ready' | 'downloading' | 'completed';
-  progress: number;
-}
+import { checkRoomStatus } from '@/lib/room-utils';
+import type { FileInfo } from '@/types';
 
 const getFileIcon = (mimeType: string) => {
   if (mimeType.startsWith('image/')) return <Image className="w-5 h-5 text-white" />;
@@ -68,50 +61,18 @@ export function WebRTCFileReceive({
   const validatePickupCode = async (code: string): Promise<boolean> => {
     try {
       setIsValidating(true);
-      
       console.log('开始验证取件码:', code);
-      const response = await fetch(`/api/room-info?code=${code}`);
-      const data = await response.json();
       
-      console.log('验证响应:', { status: response.status, data });
+      const result = await checkRoomStatus(code);
       
-      if (!response.ok || !data.success) {
-        let errorMessage = data.message || '取件码验证失败';
-        
-        // 特殊处理房间人数已满的情况
-        if (data.message?.includes('房间人数已满') || data.message?.includes('正在传输中无法加入')) {
-          errorMessage = '当前房间人数已满，正在传输中无法加入，请稍后再试';
-        } else if (data.message?.includes('expired')) {
-          errorMessage = '房间已过期，请联系发送方重新创建';
-        } else if (data.message?.includes('not found')) {
-          errorMessage = '房间不存在，请检查取件码是否正确';
-        }
-        
-        // 显示toast错误提示
-        showToast(errorMessage, 'error');
-        
-        console.log('验证失败:', errorMessage);
+      if (!result.success) {
+        showToast(result.error || '取件码验证失败', 'error');
+        console.log('验证失败:', result.error);
         return false;
       }
       
-      // 检查房间是否已满
-      if (data.is_room_full) {
-        const errorMessage = '当前房间人数已满，正在传输中无法加入，请稍后再试';
-        showToast(errorMessage, 'error');
-        console.log('房间已满:', errorMessage);
-        return false;
-      }
-      
-      console.log('取件码验证成功:', data.room);
+      console.log('取件码验证成功');
       return true;
-    } catch (error) {
-      console.error('验证取件码时发生错误:', error);
-      const errorMessage = '网络错误，请检查连接后重试';
-      
-      // 显示toast错误提示
-      showToast(errorMessage, 'error');
-      
-      return false;
     } finally {
       setIsValidating(false);
     }
diff --git a/chuan-next/src/components/webrtc/WebRTCFileUpload.tsx b/chuan-next/src/components/webrtc/WebRTCFileUpload.tsx
index 01ddb0b..a94f9c8 100644
--- a/chuan-next/src/components/webrtc/WebRTCFileUpload.tsx
+++ b/chuan-next/src/components/webrtc/WebRTCFileUpload.tsx
@@ -5,16 +5,7 @@ import { Button } from '@/components/ui/button';
 import { Upload, FileText, Image, Video, Music, Archive, X } from 'lucide-react';
 import RoomInfoDisplay from '@/components/RoomInfoDisplay';
 import { ConnectionStatus } from '@/components/ConnectionStatus';
-
-
-interface FileInfo {
-  id: string;
-  name: string;
-  size: number;
-  type: string;
-  status: 'ready' | 'downloading' | 'completed';
-  progress: number;
-}
+import type { FileInfo } from '@/types';
 
 const getFileIcon = (mimeType: string) => {
   if (mimeType.startsWith('image/')) return <Image className="w-5 h-5 text-white" />;
diff --git a/chuan-next/src/components/webrtc/WebRTCTextReceiver.tsx b/chuan-next/src/components/webrtc/WebRTCTextReceiver.tsx
index 2d1f8fe..0955d9b 100644
--- a/chuan-next/src/components/webrtc/WebRTCTextReceiver.tsx
+++ b/chuan-next/src/components/webrtc/WebRTCTextReceiver.tsx
@@ -9,6 +9,7 @@ import { Input } from '@/components/ui/input';
 import { useToast } from '@/components/ui/toast-simple';
 import { MessageSquare, Image, Download } from 'lucide-react';
 import { ConnectionStatus } from '@/components/ConnectionStatus';
+import { checkRoomStatus } from '@/lib/room-utils';
 
 interface WebRTCTextReceiverProps {
   initialCode?: string;
@@ -136,39 +137,22 @@ export const WebRTCTextReceiver: React.FC<WebRTCTextReceiverProps> = ({
     try {
       console.log('=== 开始加入房间 ===', code);
       
-      // 验证房间
-      const response = await fetch(`/api/room-info?code=${code}`);
-      const roomData = await response.json();
-      
-      if (!response.ok) {
-        let errorMessage = roomData.error || '房间不存在或已过期';
-        
-        // 特殊处理房间人数已满的情况
-        if (roomData.message?.includes('房间人数已满') || roomData.message?.includes('正在传输中无法加入')) {
-          errorMessage = '当前房间人数已满，正在传输中无法加入，请稍后再试';
-        } else if (roomData.message?.includes('expired')) {
-          errorMessage = '房间已过期，请联系发送方重新创建';
-        } else if (roomData.message?.includes('not found')) {
-          errorMessage = '房间不存在，请检查取件码是否正确';
-        }
-        
-        throw new Error(errorMessage);
-      }
-      
-      // 检查房间是否已满
-      if (roomData.is_room_full) {
-        throw new Error('当前房间人数已满，正在传输中无法加入，请稍后再试');
+      const result = await checkRoomStatus(code);
+      if (!result.success) {
+        showToast(result.error || '加入房间失败', "error");
+        return;
       }
 
-      console.log('=== 房间验证成功 ===', roomData);
+      console.log('=== 房间验证成功 ===');
       setPickupCode(code);
       
       // 连接到房间
       await connectAll(code, 'receiver');
       
-    } catch (error: any) {
+    } catch (error: unknown) {
       console.error('加入房间失败:', error);
-      showToast(error.message || '加入房间失败', "error");
+      const message = error instanceof Error ? error.message : '加入房间失败';
+      showToast(message, "error");
     } finally {
       setIsValidating(false);
     }
diff --git a/chuan-next/src/hooks/connection/index.ts b/chuan-next/src/hooks/connection/index.ts
index 276b402..4d7127f 100644
--- a/chuan-next/src/hooks/connection/index.ts
+++ b/chuan-next/src/hooks/connection/index.ts
@@ -1,5 +1,4 @@
 // 连接相关的hooks
-export { useConnectionState } from './useConnectionState';
 export { useRoomConnection } from './useRoomConnection';
 export { useSharedWebRTCManager } from './useSharedWebRTCManager';
 export { useWebRTCSupport } from './useWebRTCSupport';
diff --git a/chuan-next/src/hooks/connection/useConnectionState.ts b/chuan-next/src/hooks/connection/useConnectionState.ts
deleted file mode 100644
index e8182de..0000000
--- a/chuan-next/src/hooks/connection/useConnectionState.ts
+++ /dev/null
@@ -1,137 +0,0 @@
-import { useState, useEffect, useCallback } from 'react';
-import { useToast } from '@/components/ui/toast-simple';
-
-interface UseConnectionStateProps {
-  isWebSocketConnected: boolean;
-  isConnected: boolean;
-  isConnecting: boolean;
-  error: string;
-  pickupCode: string;
-  fileListLength: number;
-  currentTransferFile: any;
-  setCurrentTransferFile: (file: any) => void;
-  updateFileListStatus: (callback: (prev: any[]) => any[]) => void;
-}
-
-export const useConnectionState = ({
-  isWebSocketConnected,
-  isConnected,
-  isConnecting,
-  error,
-  pickupCode,
-  fileListLength,
-  currentTransferFile,
-  setCurrentTransferFile,
-  updateFileListStatus
-}: UseConnectionStateProps) => {
-  const { showToast } = useToast();
-  const [lastError, setLastError] = useState<string>('');
-
-  // 处理连接错误
-  useEffect(() => {
-    if (error && error !== lastError) {
-      console.log('=== 连接错误处理 ===');
-      console.log('错误信息:', error);
-      
-      // 根据错误类型显示不同的提示
-      let errorMessage = error;
-      
-      if (error.includes('WebSocket')) {
-        errorMessage = '服务器连接失败，请检查网络连接或稍后重试';
-      } else if (error.includes('数据通道')) {
-        errorMessage = '数据通道连接失败，请重新尝试连接';
-      } else if (error.includes('连接超时')) {
-        errorMessage = '连接超时，请检查网络状况或重新尝试';
-      } else if (error.includes('连接失败')) {
-        errorMessage = 'WebRTC连接失败，可能是网络环境限制，请尝试刷新页面';
-      } else if (error.includes('信令错误')) {
-        errorMessage = '信令服务器错误，请稍后重试';
-      } else if (error.includes('创建连接失败')) {
-        errorMessage = '无法建立P2P连接，请检查网络设置';
-      }
-      
-      // 显示错误提示
-      showToast(errorMessage, "error");
-      setLastError(error);
-      
-      // 如果是严重连接错误，清理传输状态
-      if (error.includes('连接失败') || error.includes('数据通道连接失败') || error.includes('WebSocket')) {
-        console.log('严重连接错误，清理传输状态');
-        setCurrentTransferFile(null);
-        
-        // 重置所有正在传输的文件状态
-        updateFileListStatus((prev: any[]) => prev.map(item => 
-          item.status === 'downloading' 
-            ? { ...item, status: 'ready' as const, progress: 0 }
-            : item
-        ));
-      }
-    }
-  }, [error, lastError, showToast, setCurrentTransferFile, updateFileListStatus]);
-
-  // 监听连接状态变化和清理传输状态
-  useEffect(() => {
-    console.log('=== 连接状态变化 ===');
-    console.log('WebSocket连接状态:', isWebSocketConnected);
-    console.log('WebRTC连接状态:', isConnected);
-    console.log('连接中状态:', isConnecting);
-    
-    // 当连接断开或有错误时，清理所有传输状态
-    const shouldCleanup = (!isWebSocketConnected && !isConnected && !isConnecting && pickupCode) || 
-                         ((!isConnected && !isConnecting) || error);
-    
-    if (shouldCleanup) {
-      const hasCurrentTransfer = !!currentTransferFile;
-      const hasFileList = fileListLength > 0;
-      
-      // 只有在之前有连接活动时才显示断开提示和清理状态
-      if (hasFileList || hasCurrentTransfer) {
-        if (!isWebSocketConnected && pickupCode) {
-          showToast('与服务器的连接已断开，请重新连接', "error");
-        }
-        
-        console.log('连接断开，清理传输状态');
-        
-        if (currentTransferFile) {
-          setCurrentTransferFile(null);
-        }
-        
-        // 重置所有正在下载的文件状态
-        updateFileListStatus((prev: any[]) => {
-          const hasDownloadingFiles = prev.some(item => item.status === 'downloading');
-          if (hasDownloadingFiles) {
-            console.log('重置正在传输的文件状态');
-            return prev.map(item => 
-              item.status === 'downloading' 
-                ? { ...item, status: 'ready' as const, progress: 0 }
-                : item
-            );
-          }
-          return prev;
-        });
-      }
-    }
-    
-    // WebSocket连接成功时的提示
-    if (isWebSocketConnected && isConnecting && !isConnected) {
-      console.log('WebSocket已连接，正在建立P2P连接...');
-    }
-    
-  }, [isWebSocketConnected, isConnected, isConnecting, pickupCode, error, showToast, currentTransferFile, fileListLength, setCurrentTransferFile, updateFileListStatus]);
-
-  // 监听连接状态变化并提供日志
-  useEffect(() => {
-    console.log('=== WebRTC连接状态变化 ===');
-    console.log('连接状态:', {
-      isConnected,
-      isConnecting,
-      isWebSocketConnected,
-      pickupCode,
-      fileListLength
-    });
-  }, [isConnected, isConnecting, isWebSocketConnected, pickupCode, fileListLength]);
-
-  return {
-    lastError
-  };
-};
diff --git a/chuan-next/src/hooks/connection/useRoomConnection.ts b/chuan-next/src/hooks/connection/useRoomConnection.ts
index 2dee633..19eed10 100644
--- a/chuan-next/src/hooks/connection/useRoomConnection.ts
+++ b/chuan-next/src/hooks/connection/useRoomConnection.ts
@@ -1,5 +1,6 @@
 import { useState, useCallback } from 'react';
 import { useToast } from '@/components/ui/toast-simple';
+import { validateRoomCode, checkRoomStatus } from '@/lib/room-utils';
 
 interface UseRoomConnectionProps {
   connect: (code: string, role: 'sender' | 'receiver') => void;
@@ -11,61 +12,6 @@ export const useRoomConnection = ({ connect, isConnecting, isConnected }: UseRoo
   const { showToast } = useToast();
   const [isJoiningRoom, setIsJoiningRoom] = useState(false);
 
-  const validateRoomCode = (code: string): string | null => {
-    const trimmedCode = code.trim();
-    if (!trimmedCode || trimmedCode.length !== 6) {
-      return '请输入正确的6位取件码';
-    }
-    return null;
-  };
-
-  const checkRoomStatus = async (code: string) => {
-    const response = await fetch(`/api/room-info?code=${code}`);
-    
-    if (!response.ok) {
-      throw new Error(`HTTP ${response.status}: 无法检查房间状态`);
-    }
-    
-    const result = await response.json();
-    
-    if (!result.success) {
-      let errorMessage = result.message || '房间不存在或已过期';
-      if (result.message?.includes('expired')) {
-        errorMessage = '房间已过期，请联系发送方重新创建';
-      } else if (result.message?.includes('not found')) {
-        errorMessage = '房间不存在，请检查取件码是否正确';
-      }
-      throw new Error(errorMessage);
-    }
-    
-    // 检查房间是否已满
-    if (result.is_room_full) {
-      throw new Error('当前房间人数已满，正在传输中无法加入');
-    }
-    
-    if (!result.sender_online) {
-      throw new Error('发送方不在线，请确认取件码是否正确或联系发送方');
-    }
-
-    return result;
-  };
-
-  const handleNetworkError = (error: Error): string => {
-    if (error.message.includes('network') || error.message.includes('fetch')) {
-      return '网络连接失败，请检查网络状况';
-    } else if (error.message.includes('timeout')) {
-      return '请求超时，请重试';
-    } else if (error.message.includes('HTTP 404')) {
-      return '房间不存在，请检查取件码';
-    } else if (error.message.includes('HTTP 500')) {
-      return '服务器错误，请稍后重试';
-    } else if (error.message.includes('房间人数已满') || error.message.includes('正在传输中无法加入')) {
-      return '当前房间人数已满，正在传输中无法加入，请稍后再试';
-    } else {
-      return error.message;
-    }
-  };
-
   // 加入房间 (接收模式)
   const joinRoom = useCallback(async (code: string) => {
     console.log('=== 加入房间 ===');
@@ -88,7 +34,12 @@ export const useRoomConnection = ({ connect, isConnecting, isConnected }: UseRoo
     
     try {
       console.log('检查房间状态...');
-      await checkRoomStatus(code.trim());
+      const result = await checkRoomStatus(code.trim());
+      
+      if (!result.success) {
+        showToast(result.error || '检查房间状态失败', "error");
+        return;
+      }
       
       console.log('房间状态检查通过，开始连接...');
       connect(code.trim(), 'receiver');
@@ -96,7 +47,7 @@ export const useRoomConnection = ({ connect, isConnecting, isConnected }: UseRoo
       
     } catch (error) {
       console.error('检查房间状态失败:', error);
-      const errorMessage = error instanceof Error ? handleNetworkError(error) : '检查房间状态失败';
+      const errorMessage = error instanceof Error ? error.message : '检查房间状态失败';
       showToast(errorMessage, "error");
     } finally {
       setIsJoiningRoom(false);
diff --git a/chuan-next/src/hooks/connection/useSharedWebRTCManager.ts b/chuan-next/src/hooks/connection/useSharedWebRTCManager.ts
index c084190..a94f0b8 100644
--- a/chuan-next/src/hooks/connection/useSharedWebRTCManager.ts
+++ b/chuan-next/src/hooks/connection/useSharedWebRTCManager.ts
@@ -1,5 +1,5 @@
-import { useCallback } from 'react';
-import { useWebRTCStateManager } from './useWebRTCStateManager';
+import { useCallback, useMemo } from 'react';
+import { useWebRTCStore, type WebRTCStateManager } from '../ui/webRTCStore';
 import { useWebRTCDataChannelManager, WebRTCMessage } from './useWebRTCDataChannelManager';
 import { useWebRTCTrackManager } from './useWebRTCTrackManager';
 import { useWebRTCConnectionCore } from './useWebRTCConnectionCore';
@@ -50,8 +50,27 @@ export interface WebRTCConnection {
  * 整合所有模块，提供统一的接口
  */
 export function useSharedWebRTCManager(): WebRTCConnection {
-  // 创建各个管理器实例
-  const stateManager = useWebRTCStateManager();
+  // 直接从 zustand store 创建状态管理器
+  const store = useWebRTCStore();
+  const stateManager: WebRTCStateManager = useMemo(() => ({
+    getState: () => ({
+      isConnected: store.isConnected,
+      isConnecting: store.isConnecting,
+      isWebSocketConnected: store.isWebSocketConnected,
+      isPeerConnected: store.isPeerConnected,
+      error: store.error,
+      canRetry: store.canRetry,
+      currentRoom: store.currentRoom,
+    }),
+    updateState: store.updateState,
+    setCurrentRoom: store.setCurrentRoom,
+    resetToInitial: store.resetToInitial,
+    isConnectedToRoom: (roomCode: string, role: 'sender' | 'receiver') =>
+      store.currentRoom?.code === roomCode &&
+      store.currentRoom?.role === role &&
+      store.isConnected,
+  }), [store]);
+
   const dataChannelManager = useWebRTCDataChannelManager(stateManager);
   const trackManager = useWebRTCTrackManager(stateManager);
   const connectionCore = useWebRTCConnectionCore(
@@ -60,8 +79,15 @@ export function useSharedWebRTCManager(): WebRTCConnection {
     trackManager
   );
 
-  // 获取当前状态
-  const state = stateManager.getState();
+  // 从 store 获取当前状态
+  const state = {
+    isConnected: store.isConnected,
+    isConnecting: store.isConnecting,
+    isWebSocketConnected: store.isWebSocketConnected,
+    isPeerConnected: store.isPeerConnected,
+    error: store.error,
+    canRetry: store.canRetry,
+  };
 
   // 创建 createOfferNow 方法
   const createOfferNow = useCallback(async () => {
diff --git a/chuan-next/src/hooks/connection/useWebRTCConnectionCore.ts b/chuan-next/src/hooks/connection/useWebRTCConnectionCore.ts
index 6e6910c..ffbc6e3 100644
--- a/chuan-next/src/hooks/connection/useWebRTCConnectionCore.ts
+++ b/chuan-next/src/hooks/connection/useWebRTCConnectionCore.ts
@@ -2,7 +2,7 @@
 import { useRef, useCallback } from 'react';
 import { getWsUrl } from '@/lib/config';
 import { getIceServersConfig } from '../settings/useIceServersConfig';
-import { WebRTCStateManager } from './useWebRTCStateManager';
+import { WebRTCStateManager } from '../ui/webRTCStore';
 import { WebRTCDataChannelManager, WebRTCMessage } from './useWebRTCDataChannelManager';
 import { WebRTCTrackManager } from './useWebRTCTrackManager';
 
diff --git a/chuan-next/src/hooks/connection/useWebRTCDataChannelManager.ts b/chuan-next/src/hooks/connection/useWebRTCDataChannelManager.ts
index 585a764..e25f7b8 100644
--- a/chuan-next/src/hooks/connection/useWebRTCDataChannelManager.ts
+++ b/chuan-next/src/hooks/connection/useWebRTCDataChannelManager.ts
@@ -1,5 +1,5 @@
 import { useRef, useCallback } from 'react';
-import { WebRTCStateManager } from './useWebRTCStateManager';
+import { WebRTCStateManager } from '../ui/webRTCStore';
 
 // 消息类型
 export interface WebRTCMessage {
diff --git a/chuan-next/src/hooks/connection/useWebRTCStateManager.ts b/chuan-next/src/hooks/connection/useWebRTCStateManager.ts
deleted file mode 100644
index 15aa43e..0000000
--- a/chuan-next/src/hooks/connection/useWebRTCStateManager.ts
+++ /dev/null
@@ -1,78 +0,0 @@
-import { useCallback } from 'react';
-import { useWebRTCStore } from '../ui/webRTCStore';
-
-// 基础连接状态
-export interface WebRTCState {
-  isConnected: boolean;
-  isConnecting: boolean;
-  isWebSocketConnected: boolean;
-  isPeerConnected: boolean;
-  error: string | null;
-  canRetry: boolean;
-}
-
-/**
- * WebRTC 状态管理器
- * 负责连接状态的统一管理
- */
-export interface WebRTCStateManager {
-  // 获取当前状态
-  getState: () => WebRTCState;
-  
-  // 更新状态
-  updateState: (updates: Partial<WebRTCState>) => void;
-  
-  // 设置当前房间
-  setCurrentRoom: (room: { code: string; role: 'sender' | 'receiver' } | null) => void;
-  
-  // 重置到初始状态
-  resetToInitial: () => void;
-  
-  // 检查是否已连接到指定房间
-  isConnectedToRoom: (roomCode: string, role: 'sender' | 'receiver') => boolean;
-}
-
-/**
- * WebRTC 状态管理 Hook
- * 封装对 webRTCStore 的操作，提供状态更新和查询的统一接口
- */
-export function useWebRTCStateManager(): WebRTCStateManager {
-  const webrtcStore = useWebRTCStore();
-
-  const getState = useCallback((): WebRTCState => {
-    return {
-      isConnected: webrtcStore.isConnected,
-      isConnecting: webrtcStore.isConnecting,
-      isWebSocketConnected: webrtcStore.isWebSocketConnected,
-      isPeerConnected: webrtcStore.isPeerConnected,
-      error: webrtcStore.error,
-      canRetry: webrtcStore.canRetry,
-    };
-  }, [webrtcStore]);
-
-  const updateState = useCallback((updates: Partial<WebRTCState>) => {
-    webrtcStore.updateState(updates);
-  }, [webrtcStore]);
-
-  const setCurrentRoom = useCallback((room: { code: string; role: 'sender' | 'receiver' } | null) => {
-    webrtcStore.setCurrentRoom(room);
-  }, [webrtcStore]);
-
-  const resetToInitial = useCallback(() => {
-    webrtcStore.resetToInitial();
-  }, [webrtcStore]);
-
-  const isConnectedToRoom = useCallback((roomCode: string, role: 'sender' | 'receiver') => {
-    return webrtcStore.currentRoom?.code === roomCode &&
-      webrtcStore.currentRoom?.role === role &&
-      webrtcStore.isConnected;
-  }, [webrtcStore]);
-
-  return {
-    getState,
-    updateState,
-    setCurrentRoom,
-    resetToInitial,
-    isConnectedToRoom,
-  };
-}
\ No newline at end of file
diff --git a/chuan-next/src/hooks/connection/useWebRTCTrackManager.ts b/chuan-next/src/hooks/connection/useWebRTCTrackManager.ts
index 083871d..a9e6a33 100644
--- a/chuan-next/src/hooks/connection/useWebRTCTrackManager.ts
+++ b/chuan-next/src/hooks/connection/useWebRTCTrackManager.ts
@@ -1,5 +1,5 @@
 import { useCallback, useRef } from 'react';
-import { WebRTCStateManager } from './useWebRTCStateManager';
+import { WebRTCStateManager } from '../ui/webRTCStore';
 
 /**
  * WebRTC 媒体轨道管理器
diff --git a/chuan-next/src/hooks/file-transfer/useFileListSync.ts b/chuan-next/src/hooks/file-transfer/useFileListSync.ts
index 6e9edc5..3fa6944 100644
--- a/chuan-next/src/hooks/file-transfer/useFileListSync.ts
+++ b/chuan-next/src/hooks/file-transfer/useFileListSync.ts
@@ -1,13 +1,5 @@
 import { useRef, useCallback, useEffect } from 'react';
-
-interface FileInfo {
-  id: string;
-  name: string;
-  size: number;
-  type: string;
-  status: 'ready' | 'downloading' | 'completed';
-  progress: number;
-}
+import type { FileInfo } from '@/types';
 
 interface UseFileListSyncProps {
   sendFileList: (fileInfos: FileInfo[]) => void;
diff --git a/chuan-next/src/hooks/file-transfer/useFileStateManager.ts b/chuan-next/src/hooks/file-transfer/useFileStateManager.ts
index 0583839..be3dc2f 100644
--- a/chuan-next/src/hooks/file-transfer/useFileStateManager.ts
+++ b/chuan-next/src/hooks/file-transfer/useFileStateManager.ts
@@ -1,13 +1,5 @@
 import { useState, useCallback, useEffect } from 'react';
-
-interface FileInfo {
-  id: string;
-  name: string;
-  size: number;
-  type: string;
-  status: 'ready' | 'downloading' | 'completed';
-  progress: number;
-}
+import type { FileInfo } from '@/types';
 
 interface UseFileStateManagerProps {
   mode: 'send' | 'receive';
diff --git a/chuan-next/src/hooks/file-transfer/useFileTransferBusiness.ts b/chuan-next/src/hooks/file-transfer/useFileTransferBusiness.ts
index e91282f..03804a1 100644
--- a/chuan-next/src/hooks/file-transfer/useFileTransferBusiness.ts
+++ b/chuan-next/src/hooks/file-transfer/useFileTransferBusiness.ts
@@ -1,5 +1,6 @@
 import { useState, useCallback, useRef, useEffect } from 'react';
 import type { WebRTCConnection } from '../connection/useSharedWebRTCManager';
+import type { FileInfo } from '@/types';
 
 // 文件传输状态
 interface FileTransferState {
@@ -21,16 +22,6 @@ interface FileReceiveProgress {
   progress: number;
 }
 
-// 文件信息
-interface FileInfo {
-  id: string;
-  name: string;
-  size: number;
-  type: string;
-  status: 'ready' | 'downloading' | 'completed';
-  progress: number;
-}
-
 // 文件元数据
 interface FileMetadata {
   id: string;
diff --git a/chuan-next/src/hooks/ui/webRTCStore.ts b/chuan-next/src/hooks/ui/webRTCStore.ts
index 49d5787..d392133 100644
--- a/chuan-next/src/hooks/ui/webRTCStore.ts
+++ b/chuan-next/src/hooks/ui/webRTCStore.ts
@@ -1,20 +1,32 @@
 import { create } from 'zustand';
 
-interface WebRTCState {
+export interface WebRTCState {
   isConnected: boolean;
   isConnecting: boolean;
   isWebSocketConnected: boolean;
   isPeerConnected: boolean;
   error: string | null;
-  canRetry: boolean;  // 新增：是否可以重试
+  canRetry: boolean;
   currentRoom: { code: string; role: 'sender' | 'receiver' } | null;
 }
 
+/**
+ * WebRTC 状态管理器接口
+ * 供 ConnectionCore / DataChannelManager / TrackManager 作为参数使用
+ */
+export interface WebRTCStateManager {
+  getState: () => WebRTCState;
+  updateState: (updates: Partial<WebRTCState>) => void;
+  setCurrentRoom: (room: { code: string; role: 'sender' | 'receiver' } | null) => void;
+  resetToInitial: () => void;
+  isConnectedToRoom: (roomCode: string, role: 'sender' | 'receiver') => boolean;
+}
+
 interface WebRTCStore extends WebRTCState {
   updateState: (updates: Partial<WebRTCState>) => void;
   setCurrentRoom: (room: { code: string; role: 'sender' | 'receiver' } | null) => void;
   reset: () => void;
-  resetToInitial: () => void;  // 新增：完全重置到初始状态
+  resetToInitial: () => void;
 }
 
 const initialState: WebRTCState = {
@@ -23,7 +35,7 @@ const initialState: WebRTCState = {
   isWebSocketConnected: false,
   isPeerConnected: false,
   error: null,
-  canRetry: false,  // 初始状态下不需要重试
+  canRetry: false,
   currentRoom: null,
 };
 
@@ -42,5 +54,5 @@ export const useWebRTCStore = create<WebRTCStore>((set) => ({
   
   reset: () => set(initialState),
   
-  resetToInitial: () => set(initialState),  // 完全重置到初始状态
+  resetToInitial: () => set(initialState),
 }));
diff --git a/chuan-next/src/lib/api-utils.ts b/chuan-next/src/lib/api-utils.ts
deleted file mode 100644
index b1c0191..0000000
--- a/chuan-next/src/lib/api-utils.ts
+++ /dev/null
@@ -1,144 +0,0 @@
-/**
- * API 调用工具函数
- * 统一处理开发模式和静态模式下的API调用
- */
-
-import { config, getApiUrl, getDirectBackendUrl, getWsUrl } from './config';
-
-/**
- * 统一的 fetch 函数，自动处理不同环境下的API调用
- */
-export async function apiFetch(
-  endpoint: string, 
-  options: RequestInit = {}
-): Promise<Response> {
-  let url: string;
-  
-  // 检查是否在客户端
-  const isClient = typeof window !== 'undefined';
-  
-  // 检查是否为静态导出模式 - 修复开发模式判断
-  const isStaticExport = 
-    process.env.NEXT_EXPORT === 'true' ||
-    (process.env.NODE_ENV === 'production' && isClient && !window.location.origin.includes('localhost:3000'));
-  
-  if (isClient) {
-    if (isStaticExport) {
-      // 静态模式：直接调用后端
-      url = getDirectBackendUrl(endpoint);
-    } else {
-      // 开发模式：通过 Next.js API 路由
-      url = getApiUrl(endpoint);
-    }
-  } else {
-    // 服务器端：直接调用后端
-    url = getDirectBackendUrl(endpoint);
-  }
-
-  console.log(`[API] 模式检查: isClient=${isClient}, isStatic=${isStaticExport}`);
-  console.log(`[API] 调用: ${endpoint} -> ${url}`);
-  
-  return fetch(url, {
-    ...options,
-    headers: {
-      'Content-Type': 'application/json',
-      ...options.headers,
-    },
-  });
-}
-
-/**
- * GET 请求
- */
-export async function apiGet(endpoint: string, options: RequestInit = {}): Promise<Response> {
-  return apiFetch(endpoint, {
-    ...options,
-    method: 'GET',
-  });
-}
-
-/**
- * POST 请求
- */
-export async function apiPost(
-  endpoint: string, 
-  data?: any, 
-  options: RequestInit = {}
-): Promise<Response> {
-  return apiFetch(endpoint, {
-    ...options,
-    method: 'POST',
-    body: data ? JSON.stringify(data) : undefined,
-  });
-}
-
-/**
- * PUT 请求
- */
-export async function apiPut(
-  endpoint: string, 
-  data?: any, 
-  options: RequestInit = {}
-): Promise<Response> {
-  return apiFetch(endpoint, {
-    ...options,
-    method: 'PUT',
-    body: data ? JSON.stringify(data) : undefined,
-  });
-}
-
-/**
- * DELETE 请求
- */
-export async function apiDelete(endpoint: string, options: RequestInit = {}): Promise<Response> {
-  return apiFetch(endpoint, {
-    ...options,
-    method: 'DELETE',
-  });
-}
-
-/**
- * 文件上传请求
- */
-export async function apiUpload(
-  endpoint: string, 
-  formData: FormData, 
-  options: RequestInit = {}
-): Promise<Response> {
-  // 文件上传不设置 Content-Type，让浏览器自动设置
-  const { headers, ...restOptions } = options;
-  
-  return apiFetch(endpoint, {
-    ...restOptions,
-    method: 'POST',
-    body: formData,
-    headers: headers, // 不包含 Content-Type
-  });
-}
-
-/**
- * 获取 WebSocket URL
- */
-export function getWebSocketUrl(): string {
-  return getWsUrl(); // 使用实时获取的 WebSocket URL
-}
-
-/**
- * 显示当前API配置信息（调试用）
- */
-export function debugApiConfig() {
-  const isClient = typeof window !== 'undefined';
-  const isStaticExport = 
-    process.env.NEXT_EXPORT === 'true' ||
-    process.env.NODE_ENV === 'production' && !process.env.NEXT_PUBLIC_API_BASE_URL?.includes('localhost:3000') ||
-    (isClient && !window.location.pathname.startsWith('/api/'));
-  
-  console.log('[API Debug] 配置信息:', {
-    isClient,
-    isStaticExport,
-    config: config.api,
-    environment: process.env.NODE_ENV,
-    nextExport: process.env.NEXT_EXPORT,
-    currentUrl: isClient ? window.location.href : 'server-side',
-  });
-}
diff --git a/chuan-next/src/lib/client-api.ts b/chuan-next/src/lib/client-api.ts
deleted file mode 100644
index a9e58a3..0000000
--- a/chuan-next/src/lib/client-api.ts
+++ /dev/null
@@ -1,119 +0,0 @@
-/**
- * 客户端 API 工具类
- * 用于在静态导出模式下直接与 Go 后端通信
- */
-
-import { config } from './config';
-
-interface ApiResponse {
-  success: boolean;
-  message?: string;
-  data?: unknown;
-}
-
-export class ClientAPI {
-  private baseUrl: string;
-
-  constructor() {
-    // 根据环境选择合适的API地址
-    if (config.isStatic) {
-      // 静态模式：直接连接 Go 后端
-      this.baseUrl = config.api.directBackendUrl;
-    } else {
-      // 开发模式：通过 Next.js API 路由
-      this.baseUrl = config.api.baseUrl;
-    }
-  }
-
-  /**
-   * 发送 POST 请求
-   */
-  async post(endpoint: string, data: unknown): Promise<ApiResponse> {
-    const url = this.baseUrl.replace(/\/$/, '') + (endpoint.startsWith('/') ? endpoint : `/${endpoint}`);
-    
-    try {
-      const response = await fetch(url, {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-        },
-        body: JSON.stringify(data),
-      });
-
-      if (!response.ok) {
-        throw new Error(`HTTP error! status: ${response.status}`);
-      }
-
-      return await response.json() as ApiResponse;
-    } catch (error) {
-      console.error('API request failed:', error);
-      throw error;
-    }
-  }
-
-  /**
-   * 发送 GET 请求
-   */
-  async get(endpoint: string): Promise<ApiResponse> {
-    const url = this.baseUrl.replace(/\/$/, '') + (endpoint.startsWith('/') ? endpoint : `/${endpoint}`);
-    
-    try {
-      const response = await fetch(url, {
-        method: 'GET',
-        headers: {
-          'Content-Type': 'application/json',
-        },
-      });
-
-      if (!response.ok) {
-        throw new Error(`HTTP error! status: ${response.status}`);
-      }
-
-      return await response.json() as ApiResponse;
-    } catch (error) {
-      console.error('API request failed:', error);
-      throw error;
-    }
-  }
-
-  /**
-   * 创建房间（简化版本）- 后端会忽略传入的参数
-   */
-  async createRoom(): Promise<ApiResponse> {
-    return this.post('/api/create-room', {});
-  }
-
-  /**
-   * 获取文本内容
-   */
-  async getTextContent(code: string): Promise<ApiResponse> {
-    return this.get(`/api/get-text-content?code=${code}`);
-  }
-
-  /**
-   * 更新文本内容
-   */
-  async updateTextContent(code: string, content: string): Promise<ApiResponse> {
-    return this.post('/api/update-text-content', {
-      code: code,
-      content: content
-    });
-  }
-
-  /**
-   * 获取房间信息
-   */
-  async getRoomInfo(code: string): Promise<ApiResponse> {
-    return this.get(`/api/room-info?code=${code}`);
-  }
-
-  /**
-   * 获取WebRTC房间状态
-   */
-  async getWebRTCRoomStatus(code: string): Promise<ApiResponse> {
-    return this.get(`/api/webrtc-room-status?code=${code}`);
-  }
-}
-
-// 导出单例实例
-export const clientAPI = new ClientAPI();
diff --git a/chuan-next/src/lib/room-utils.ts b/chuan-next/src/lib/room-utils.ts
new file mode 100644
index 0000000..bc1b57f
--- /dev/null
+++ b/chuan-next/src/lib/room-utils.ts
@@ -0,0 +1,94 @@
+/**
+ * 房间验证工具函数
+ * 统一房间代码验证和房间状态检查逻辑
+ */
+
+export interface RoomValidationResult {
+  success: boolean;
+  error?: string;
+  data?: Record<string, unknown>;
+}
+
+/**
+ * 验证房间代码格式
+ */
+export function validateRoomCode(code: string): string | null {
+  const trimmedCode = code.trim();
+  if (!trimmedCode || trimmedCode.length !== 6) {
+    return '请输入正确的6位取件码';
+  }
+  return null;
+}
+
+/**
+ * 检查房间状态（调用 /api/room-info）
+ * 统一处理房间不存在、过期、已满、发送方不在线等情况
+ */
+export async function checkRoomStatus(code: string): Promise<RoomValidationResult> {
+  try {
+    const response = await fetch(`/api/room-info?code=${code}`);
+
+    if (!response.ok) {
+      return {
+        success: false,
+        error: `HTTP ${response.status}: 无法检查房间状态`,
+      };
+    }
+
+    const result = await response.json();
+
+    if (!result.success) {
+      let errorMessage = result.message || '房间不存在或已过期';
+      if (result.message?.includes('房间人数已满') || result.message?.includes('正在传输中无法加入')) {
+        errorMessage = '当前房间人数已满，正在传输中无法加入，请稍后再试';
+      } else if (result.message?.includes('expired')) {
+        errorMessage = '房间已过期，请联系发送方重新创建';
+      } else if (result.message?.includes('not found')) {
+        errorMessage = '房间不存在，请检查取件码是否正确';
+      }
+      return { success: false, error: errorMessage };
+    }
+
+    // 检查房间是否已满
+    if (result.is_room_full) {
+      return {
+        success: false,
+        error: '当前房间人数已满，正在传输中无法加入，请稍后再试',
+      };
+    }
+
+    // 检查发送方是否在线
+    if (!result.sender_online) {
+      return {
+        success: false,
+        error: '发送方不在线，请确认取件码是否正确或联系发送方',
+      };
+    }
+
+    return { success: true, data: result };
+  } catch (error) {
+    const message =
+      error instanceof Error
+        ? handleNetworkError(error)
+        : '检查房间状态失败';
+    return { success: false, error: message };
+  }
+}
+
+/**
+ * 网络错误统一处理
+ */
+export function handleNetworkError(error: Error): string {
+  if (error.message.includes('network') || error.message.includes('fetch')) {
+    return '网络连接失败，请检查网络状况';
+  } else if (error.message.includes('timeout')) {
+    return '请求超时，请重试';
+  } else if (error.message.includes('HTTP 404')) {
+    return '房间不存在，请检查取件码';
+  } else if (error.message.includes('HTTP 500')) {
+    return '服务器错误，请稍后重试';
+  } else if (error.message.includes('房间人数已满') || error.message.includes('正在传输中无法加入')) {
+    return '当前房间人数已满，正在传输中无法加入，请稍后再试';
+  }
+  return error.message;
+}
diff --git a/chuan-next/src/types/index.ts b/chuan-next/src/types/index.ts
index 9bb5167..4994778 100644
--- a/chuan-next/src/types/index.ts
+++ b/chuan-next/src/types/index.ts
@@ -4,6 +4,8 @@ export interface FileInfo {
   name: string;
   size: number;
   type: string;
+  status: 'ready' | 'downloading' | 'completed';
+  progress: number;
   lastModified?: number;
 }
 
@@ -30,22 +32,3 @@ export interface RoomStatus {
   }[];
   created_at: string;
 }
-
-export interface FileChunk {
-  offset: number;
-  data: Uint8Array;
-}
-
-export interface WebSocketMessage {
-  type: string;
-  payload: Record<string, unknown>;
-}
-
-// WebSocket 钩子状态
-export interface UseWebSocketReturn {
-  websocket: WebSocket | null;
-  isConnected: boolean;
-  connect: (code: string, role: 'sender' | 'receiver') => void;
-  disconnect: () => void;
-  sendMessage: (message: WebSocketMessage) => void;
-}