直播功能 API 设计文档

链接与协议（请优先阅读）

WebSocket 链接

本地开发（ws）：

javascript

const ws = new WebSocket('ws://localhost:8000/live/{session_id}/ws?token=<jwt_token>');

线上环境（wss）：

javascript

const ws = new WebSocket('wss://api.your-domain.com/live/{session_id}/ws?token=<jwt_token>');

说明：

session_id 为直播会话 ID（路径参数）。
token 为鉴权票据（查询参数），建议使用后端签发的 JWT。服务端将基于 token 识别用户身份与权限。
使用标准 WebSocket 协议，无自定义子协议，消息文本为 JSON 字符串。

消息协议

封包约定：所有消息均为 JSON 文本，包含 type 字段表示消息类型。
客户端 → 服务端（Client → Server）
- 心跳：
  json
```
{ "type": "ping" }
```
- 聊天（仅文本）：
  json
```
{ "type": "chat", "message": "Hello everyone!" }
```

服务端 → 客户端（Server → Client）

课件同步 courseware_sync：

json

{
  "type": "courseware_sync",
  "session_id": 1,
  "chapter_id": 1,
  "step_id": 1,
  "page": 5,
  "timestamp": "2025-01-01T10:00:00Z"
}

聊天消息 chat_message：

json

{
  "type": "chat_message",
  "session_id": 1,
  "message": "Hello everyone!",
  "user_id": 1,
  "username": "teacher",
  "timestamp": "2025-01-01T10:00:00Z"
}

参与者更新 participant_update：

json

{
  "type": "participant_update",
  "session_id": 1,
  "user_id": 1,
  "is_online": true,
  "timestamp": "2025-01-01T10:00:00Z"
}

直播状态 live_status：

json

{
  "type": "live_status",
  "session_id": 1,
  "status": "live",
  "current_chapter_id": 1,
  "current_page": 5,
  "timestamp": "2025-01-01T10:00:00Z"
}

以上消息结构与字段定义对应 app/schemas/live.py 内的 Pydantic 模型： CoursewareSyncMessage、ChatMessage、ParticipantUpdateMessage、LiveStatusMessage。

连接生命周期与建议

建连成功后，服务端会立即发送一条 live_status，包含当前章节/页面等状态。
心跳：客户端可每 30 秒发送一次 { "type": "ping" }，服务端回复 { "type": "pong" }。
断线重连：建议采用指数退避（如 1s/2s/4s/8s 上限 30s）。
发送限额：WS 聊天仅支持文本消息；单条消息长度建议 ≤ 1000 字符（与 REST 接口一致）。

概述

直播功能允许教师创建直播会话，学生可以实时观看课件并与教师互动。主要特性包括：

教师端开启直播，学生端同步观看课件
实时聊天互动
课件页面同步
参与者管理
权限控制

数据模型

LiveSession (直播会话)

id: 会话ID
course_id: 关联课程ID
teacher_id: 教师ID
class_id: 班级ID（可选）
title: 直播标题
description: 直播描述
status: 直播状态（preparing/live/paused/ended）
scheduled_start_time: 计划开始时间
actual_start_time: 实际开始时间
actual_end_time: 实际结束时间
current_chapter_id: 当前章节ID
current_step_id: 当前步骤ID
current_page: 当前页面
allow_student_chat: 是否允许学生聊天
allow_screen_share: 是否允许屏幕共享
max_participants: 最大参与者数量

LiveParticipant (直播参与者)

id: 参与者ID
session_id: 会话ID
user_id: 用户ID
is_online: 是否在线
joined_at: 加入时间
left_at: 离开时间
can_chat: 是否可以聊天
can_ask_questions: 是否可以提问

LiveChatMessage (聊天消息)

id: 消息ID
session_id: 会话ID
user_id: 用户ID
message: 消息内容
message_type: 消息类型（text/question/answer）
is_visible: 是否可见
is_answered: 是否已回答

API 接口

1. 直播会话管理

创建直播会话

http

POST /live
Authorization: Bearer <token>
Content-Type: application/json

{
  "course_id": 1,
  "class_id": 1,
  "title": "数学直播课",
  "description": "讲解二次函数",
  "scheduled_start_time": "2025-01-01T10:00:00Z",
  "allow_student_chat": true,
  "allow_screen_share": true,
  "max_participants": 50
}

获取直播会话列表

http

GET /live?course_id=1&status=live&page=1&size=20
Authorization: Bearer <token>

获取直播会话详情

http

GET /live/{session_id}
Authorization: Bearer <token>

更新直播会话

http

PUT /live/{session_id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "更新后的标题",
  "description": "更新后的描述"
}

删除直播会话

http

DELETE /live/{session_id}
Authorization: Bearer <token>

2. 直播状态管理

开始直播

http

POST /live/{session_id}/start
Authorization: Bearer <token>

暂停直播

http

POST /live/{session_id}/pause
Authorization: Bearer <token>

结束直播

http

POST /live/{session_id}/end
Authorization: Bearer <token>

3. 课件同步

同步课件到学生端

http

POST /live/{session_id}/sync-courseware
Authorization: Bearer <token>
Content-Type: application/json

{
  "chapter_id": 1,
  "step_id": 1,
  "page": 5,
  "description": "讲解第5页内容"
}

4. 参与者管理

加入直播会话

http

POST /live/{session_id}/join
Authorization: Bearer <token>

离开直播会话

http

POST /live/{session_id}/leave
Authorization: Bearer <token>

获取参与者列表

http

GET /live/{session_id}/participants
Authorization: Bearer <token>

5. 聊天功能

发送聊天消息

http

POST /live/{session_id}/chat
Authorization: Bearer <token>
Content-Type: application/json

{
  "message": "老师，这个问题我不太理解",
  "message_type": "question"
}

获取聊天消息历史

http

GET /live/{session_id}/chat?page=1&size=50
Authorization: Bearer <token>

6. 统计信息

获取直播统计信息

http

GET /live/{session_id}/stats
Authorization: Bearer <token>

7. WebSocket 连接

建立 WebSocket 连接

javascript

const ws = new WebSocket('ws://localhost:8000/live/{session_id}/ws?token=<jwt_token>');

ws.onopen = function() {
    console.log('WebSocket connected');
};

ws.onmessage = function(event) {
    const message = JSON.parse(event.data);
    
    switch(message.type) {
        case 'courseware_sync':
            // 处理课件同步
            syncCourseware(message.chapter_id, message.step_id, message.page);
            break;
        case 'chat_message':
            // 处理聊天消息
            displayChatMessage(message);
            break;
        case 'participant_update':
            // 处理参与者状态更新
            updateParticipantStatus(message);
            break;
        case 'live_status':
            // 处理直播状态更新
            updateLiveStatus(message);
            break;
    }
};

// 发送消息
ws.send(JSON.stringify({
    type: 'chat',
    message: 'Hello everyone!'
}));

WebSocket 消息类型

1. 课件同步消息

json

{
  "type": "courseware_sync",
  "session_id": 1,
  "chapter_id": 1,
  "step_id": 1,
  "page": 5,
  "timestamp": "2025-01-01T10:00:00Z"
}

2. 聊天消息

json

{
  "type": "chat_message",
  "session_id": 1,
  "message": "Hello everyone!",
  "user_id": 1,
  "username": "teacher",
  "timestamp": "2025-01-01T10:00:00Z"
}

3. 参与者状态更新

json

{
  "type": "participant_update",
  "session_id": 1,
  "user_id": 1,
  "is_online": true,
  "timestamp": "2025-01-01T10:00:00Z"
}

4. 直播状态更新

json

{
  "type": "live_status",
  "session_id": 1,
  "status": "live",
  "current_chapter_id": 1,
  "current_page": 5,
  "timestamp": "2025-01-01T10:00:00Z"
}

权限控制

教师权限

创建、更新、删除自己的直播会话
开始、暂停、结束直播
同步课件到学生端
查看直播统计信息
管理参与者权限

学生权限

加入有权限的直播会话
发送聊天消息（如果允许）
查看聊天历史
接收课件同步

管理员权限

查看所有直播会话
管理所有直播会话

使用流程

教师端流程

创建直播会话
设置直播参数（标题、描述、权限等）
开始直播
同步课件页面
与学生互动聊天
结束直播

学生端流程

查看可参与的直播会话
加入直播会话
接收课件同步
参与聊天互动
离开直播会话

技术实现

后端技术栈

FastAPI: Web 框架
SQLAlchemy: ORM
WebSocket: 实时通信
PostgreSQL: 数据库

前端集成建议

WebSocket 客户端连接管理
课件页面同步显示
聊天界面实现
参与者状态显示
直播状态指示器

扩展功能

未来可扩展的功能

录制回放功能
屏幕共享
白板功能
投票互动
文件共享
多语言支持
移动端适配
直播质量自适应

直播功能 API 设计文档 ​

链接与协议（请优先阅读） ​

WebSocket 链接 ​

消息协议 ​

连接生命周期与建议 ​

概述 ​

数据模型 ​

LiveSession (直播会话) ​

LiveParticipant (直播参与者) ​

LiveChatMessage (聊天消息) ​

API 接口 ​

1. 直播会话管理 ​

创建直播会话 ​

获取直播会话列表 ​

获取直播会话详情 ​

更新直播会话 ​

删除直播会话 ​

2. 直播状态管理 ​

开始直播 ​

暂停直播 ​

结束直播 ​

3. 课件同步 ​

同步课件到学生端 ​

4. 参与者管理 ​

加入直播会话 ​

离开直播会话 ​

获取参与者列表 ​

5. 聊天功能 ​

发送聊天消息 ​

获取聊天消息历史 ​

6. 统计信息 ​

获取直播统计信息 ​

7. WebSocket 连接 ​

建立 WebSocket 连接 ​

WebSocket 消息类型 ​

1. 课件同步消息 ​

2. 聊天消息 ​

3. 参与者状态更新 ​

4. 直播状态更新 ​

权限控制 ​

教师权限 ​

学生权限 ​

管理员权限 ​

使用流程 ​

教师端流程 ​

学生端流程 ​

技术实现 ​

后端技术栈 ​

前端集成建议 ​

扩展功能 ​

未来可扩展的功能 ​

直播功能 API 设计文档

链接与协议（请优先阅读）

WebSocket 链接

消息协议

连接生命周期与建议

概述

数据模型

LiveSession (直播会话)

LiveParticipant (直播参与者)

LiveChatMessage (聊天消息)

API 接口

1. 直播会话管理

创建直播会话

获取直播会话列表

获取直播会话详情

更新直播会话

删除直播会话

2. 直播状态管理

开始直播

暂停直播

结束直播

3. 课件同步

同步课件到学生端

4. 参与者管理

加入直播会话

离开直播会话

获取参与者列表

5. 聊天功能

发送聊天消息

获取聊天消息历史

6. 统计信息

获取直播统计信息

7. WebSocket 连接

建立 WebSocket 连接

WebSocket 消息类型

1. 课件同步消息

2. 聊天消息

3. 参与者状态更新

4. 直播状态更新

权限控制

教师权限

学生权限

管理员权限

使用流程

教师端流程

学生端流程

技术实现

后端技术栈

前端集成建议

扩展功能

未来可扩展的功能