# same-screen

**Repository Path**: crystonesc/same-screen

## Basic Information

- **Project Name**: same-screen
- **Description**: 基于 WebSocket 实现的会议同屏功能演示，支持会控人员控制所有参会者的 PDF 查看状态。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-03-29
- **Last Updated**: 2026-04-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 无纸化会议系统 - 同屏功能 Demo

基于 WebSocket 实现的会议同屏功能演示，支持会控人员控制所有参会者的 PDF 查看状态。

## 功能特性

- 会控人员可开启/关闭同屏模式
- 同屏模式下，参会人员屏幕实时跟随会控人员操作
- 支持 PDF 翻页、缩放同步
- 同屏模式下参会人员操作被锁定
- 实时显示在线人数和连接状态

## 技术栈

| 层级 | 技术 |
|------|------|
| 后端 | Python + FastAPI + WebSocket |
| 前端 | JavaScript + PDF.js |
| 通信 | WebSocket 双向实时通信 |

## 项目结构

```
same-screen/
├── app.py                 # FastAPI 后端主程序
├── requirements.txt       # Python 依赖
├── README.md             # 使用说明
├── static/
│   ├── css/
│   │   └── style.css     # 样式文件
│   └── js/
│       ├── common.js     # 公共逻辑（WebSocket管理、PDF渲染）
│       ├── controller.js # 会控端逻辑
│       └── viewer.js     # 参会端逻辑
└── templates/
    ├── index.html        # 首页（角色选择）
    ├── controller.html   # 会控端页面
    └── viewer.html       # 参会端页面
```

## 环境要求

- Python 3.8+
- 现代浏览器（Chrome、Firefox、Edge 等）

## 安装与运行

### 1. 安装依赖

```bash
cd same-screen
pip install -r requirements.txt
```

### 2. 启动服务

```bash
python app.py
```

服务启动后，访问 http://localhost:8000

### 3. 使用流程

#### 会控人员操作步骤

1. 打开浏览器访问 `http://localhost:8000`
2. 输入会议ID（如 `demo-meeting-001`）
3. 点击 **会控人员入口** 进入会控端
4. 上传 PDF 文件或点击 **加载示例PDF**
5. 点击 **开启同屏** 按钮启动同屏模式
6. 进行翻页、缩放等操作，参会者将实时同步

#### 参会人员操作步骤

1. 打开浏览器访问 `http://localhost:8000`
2. 输入相同的会议ID
3. 点击 **参会人员入口** 进入参会端
4. 等待会控人员开启同屏
5. 同屏开启后，屏幕将自动跟随会控人员操作

## 多人测试

可以在不同浏览器或浏览器标签页中打开多个参会端，模拟多人会议场景：

```
会控端: http://localhost:8000/controller/demo-meeting-001
参会端: http://localhost:8000/viewer/demo-meeting-001
```

## 同步状态说明

| 同步项 | 说明 |
|--------|------|
| 文档 | 会控端加载的 PDF 文档 |
| 页码 | 当前查看的页码 |
| 缩放 | PDF 缩放比例 |
| 滚动 | 页面滚动位置 |

## API 说明

### WebSocket 端点

```
ws://localhost:8000/ws/{meeting_id}/{client_id}?is_controller=true/false
```

### 消息类型

| 类型 | 方向 | 说明 |
|------|------|------|
| `INIT_STATE` | 服务端→客户端 | 初始化状态 |
| `STATE_UPDATE` | 双向 | 状态更新（页码、缩放等） |
| `TOGGLE_SYNC` | 客户端→服务端 | 切换同屏模式 |
| `SYNC_MODE_CHANGED` | 服务端→客户端 | 同屏模式变更通知 |
| `USER_JOIN` | 服务端→客户端 | 用户加入通知 |
| `USER_LEAVE` | 服务端→客户端 | 用户离开通知 |

## 扩展建议

如需在生产环境使用，建议：

1. **身份认证**：添加用户登录和权限验证
2. **会议管理**：增加会议创建、列表、权限控制等功能
3. **PDF 存储**：将 PDF 存储在服务端，通过 URL 分发
4. **负载均衡**：使用 Redis 等实现多实例状态共享
5. **HTTPS**：生产环境启用 HTTPS 和 WSS

## 常见问题

**Q: 示例 PDF 加载失败？**  
A: 示例 PDF 来自外部网络，请确保网络连接正常，或直接上传本地 PDF 文件。

**Q: 参会端没有同步？**  
A: 请确认会控端已开启同屏模式，且会议ID一致。

**Q: WebSocket 连接失败？**  
A: 检查服务是否正常启动，防火墙是否放行 8000 端口。