MoonTVPlus/WATCH_ROOM_README.md

观影室功能 - 实现文档

当前实现状态 ✅

已完成的核心功能

1. 后端架构

• ✅ Socket.IO 服务器逻辑 (src/lib/watch-room-server.ts)

  • 房间创建、加入、离开
  • 成员管理
  • 消息转发（播放状态、聊天消息）
  • 心跳机制和自动清理

• ✅ 两种服务器模式

  • 内部服务器: 集成在 Next.js 应用中 (server.js)
  • 外部服务器: 独立运行的 Node.js 服务器 (server/watch-room-standalone-server.js)

2. 前端功能

• ✅ 全局状态管理 (WatchRoomProvider)

• ✅ React Hook (useWatchRoom)

• ✅ 观影室首页 (/watch-room)

  • 创建房间
  • 加入房间
  • 房间列表

• ✅ UI 组件

  • 创建房间弹窗
  • 加入房间弹窗
  • 房间列表页面
  • 聊天悬浮窗（全局）

• ✅ 导航集成

  • 侧边栏添加观影室入口
  • 底部导航栏添加观影室入口

3. 功能特性

• ✅ LocalStorage 自动重连
• ✅ 心跳机制（每5秒）
• ✅ 房主断开5分钟后自动删除房间
• ✅ 文字聊天
• ✅ 表情发送
• ✅ 响应式设计（移动端+电脑端）

---

使用方法

1. 启动开发服务器

# 使用内部 Socket.IO 服务器（推荐）
pnpm dev

# 或者使用外部 Socket.IO 服务器
pnpm watch-room:server  # 在另一个终端运行
# 然后修改配置使用外部服务器

2. 访问观影室

1. 打开浏览器访问 http://localhost:3000
2. 点击侧边栏或底部导航的"观影室"按钮
3. 选择：
   • 创建房间: 输入房间信息和昵称
   • 加入房间: 输入房间号和昵称
   • 房间列表: 查看所有公开房间

3. 房间功能

创建或加入房间后:

• 右下角会出现聊天按钮
• 点击聊天按钮打开聊天窗口
• 可以发送文字和表情

---

待实现功能 🚧

高优先级（核心功能）

• ⏳ 播放同步功能 - 修改 src/app/play/page.tsx

  • 房主播放、暂停、进度同步
  • 房主换集、换源同步
  • 房员禁用播放器控制
  • 房员自动跟随房主进度

• ⏳ 直播同步功能 - 修改 src/app/live/page.tsx

  • 房主切换频道同步
  • 房员自动跟随频道

• ⏳ 管理面板配置

  • 添加观影室开关
  • 配置服务器类型（内部/外部）
  • 外部服务器地址和鉴权配置

中优先级（增强功能）

• ⏳ WebRTC 语音聊天

  • P2P 连接
  • 服务器中转回退
  • 麦克风和喇叭控制

• ⏳ 房间成员列表

  • 显示在线成员
  • 显示房主标识

• ⏳ 权限控制优化

  • 房员禁用某些操作
  • 房主踢人功能（可选）

低优先级（优化）

• ⏳ 错误处理和重连优化
• ⏳ 性能优化
• ⏳ 更多表情支持

---

技术架构

后端

• Socket.IO 4.8.1: WebSocket 通信
• Next.js Custom Server: 集成 Socket.IO
• Node.js: 独立服务器支持

前端

• React 18: UI 框架
• TypeScript: 类型安全
• Socket.IO Client: WebSocket 客户端
• Tailwind CSS: 样式框架
• Lucide React: 图标库

数据流

用户操作 → React Hook (useWatchRoom)
         ↓
   Socket.IO Client
         ↓
   Socket.IO Server (watch-room-server.ts)
         ↓
   房间成员 ← WebSocket 推送

---

文件结构

src/
├── types/
│   └── watch-room.ts                    # TypeScript 类型定义
├── lib/
│   ├── watch-room-server.ts             # Socket.IO 服务器逻辑
│   └── watch-room-socket.ts             # Socket 客户端管理
├── hooks/
│   └── useWatchRoom.ts                  # React Hook
├── components/
│   ├── WatchRoomProvider.tsx            # 全局状态管理
│   └── watch-room/
│       ├── CreateRoomModal.tsx          # 创建房间弹窗
│       ├── JoinRoomModal.tsx            # 加入房间弹窗
│       └── ChatFloatingWindow.tsx       # 聊天悬浮窗
└── app/
    └── watch-room/
        ├── page.tsx                     # 观影室首页
        └── list/
            └── page.tsx                 # 房间列表页面

server.js                                 # Next.js 自定义服务器
server/
└── watch-room-standalone-server.js       # 独立 Socket.IO 服务器

---

配置项

环境变量

# Socket.IO 配置（可选）
WATCH_ROOM_ENABLED=true
WATCH_ROOM_SERVER_TYPE=internal  # 或 external
WATCH_ROOM_EXTERNAL_URL=http://your-server:3001
WATCH_ROOM_EXTERNAL_AUTH=your_secret_key

运行时配置（将在管理面板中添加）

interface WatchRoomConfig {
  enabled: boolean;                // 是否启用观影室
  serverType: 'internal' | 'external';  // 服务器类型
  externalServerUrl?: string;      // 外部服务器地址
  externalServerAuth?: string;     // 外部服务器鉴权密钥
}

---

测试清单

基础功能测试

• 创建房间
• 加入房间（正确密码）
• 加入房间（错误密码）
• 查看房间列表
• 发送文字消息
• 发送表情
• 心跳机制
• 刷新页面自动重连

播放同步测试（待实现）

• 房主播放/暂停同步
• 房主进度跳转同步
• 房主换集同步
• 房主换源同步
• 房员操作同步给全员

直播同步测试（待实现）

• 房主切换频道同步
• 房员自动跟随频道

移动端测试

• 底部导航显示正常
• 聊天窗口适配移动端
• 创建/加入弹窗适配移动端
• 房间列表页面适配移动端

---

下一步计划

1. 实现播放同步 (src/app/play/page.tsx)

   • 集成 useWatchRoom Hook
   • 监听播放器事件并同步
   • 接收服务器播放状态更新

2. 实现直播同步 (src/app/live/page.tsx)

   • 监听频道切换事件
   • 同步频道状态

3. 添加管理面板配置

   • 在 src/app/admin/page.tsx 添加观影室配置项
   • 保存配置到数据库

4. 实现 WebRTC 语音聊天

   • 创建 WebRTC 连接管理
   • 添加麦克风/喇叭控制按钮
   • 实现服务器中转回退

---

已知问题

1. 播放同步功能未实现: 需要修改 play 和 live 页面
2. 管理面板配置未添加: 目前使用默认配置（启用内部服务器）
3. 语音聊天未实现: 仅支持文字和表情

---

贡献

欢迎提交 Issue 和 Pull Request！

---

最后更新: 2025-12-06