# 播课功能 API 接口规范

## 设计原则

**触发即可，Coze工作流直接写数据库**
- 管理员点击"生成播课"触发Coze工作流
- 后端API只负责触发，立即返回
- Coze工作流生成完成后直接更新数据库（无需后端介入）

## API 端点

### 1. 触发播课生成

**接口**: `POST /api/v1/courses/{course_id}/generate-broadcast`

**权限**: manager、admin

**请求参数**:
- Path: `course_id` (int) - 课程ID

**响应数据**:
```json
{
  "code": 200,
  "message": "播课生成已启动",
  "data": {
    "message": "播课生成工作流已启动，生成完成后将自动更新"
  }
}
```

**说明**:
- 立即返回，不等待生成完成
- Coze工作流会异步处理并直接写数据库

---

### 2. 获取播课信息

**接口**: `GET /api/v1/courses/{course_id}/broadcast`

**权限**: 所有登录用户

**请求参数**:
- Path: `course_id` (int) - 课程ID

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "has_broadcast": true,
    "mp3_url": "https://example.com/broadcast.mp3",
    "generated_at": "2025-10-14T12:00:00Z"
  }
}
```

**字段说明**:
- `has_broadcast` (boolean): 是否有播课
- `mp3_url` (string): 播课音频URL
- `generated_at` (string): 生成时间

---

## 数据库表结构

### courses 表

播课相关字段：

| 字段名 | 类型 | 说明 |
|--------|------|------|
| broadcast_audio_url | varchar(500) | 播课音频URL |
| broadcast_generated_at | datetime | 播课生成时间 |

**更新方式**: Coze工作流直接执行SQL更新

**SQL示例**:
```sql
UPDATE courses 
SET 
  broadcast_audio_url = '{mp3_url}', 
  broadcast_generated_at = NOW(), 
  updated_at = NOW() 
WHERE id = {course_id}
```

---

## Coze 工作流配置

### 数据库连接信息

- **主机**: `aiedu.ireborn.com.cn`
- **端口**: `3306`
- **数据库**: `kaopeilian`
- **用户**: `root`
- **密码**: `Kaopeilian2025!@#`

### 工作流参数

- **workflow_id**: `7561161554420482088`
- **space_id**: `7474971491470688296`
- **输入参数**: `course_id` (字符串)
- **输出**: 无（直接写数据库）

---

## 前端交互流程

1. **触发生成**
   - 管理员点击"生成播课"按钮
   - 调用 `POST /generate-broadcast`
   - 显示提示："播课生成已启动，完成后会自动更新"

2. **查看结果**
   - 用户刷新页面或重新进入
   - 调用 `GET /broadcast` 获取最新状态
   - 如果 `has_broadcast=true` 则显示"已生成"和播放链接

---

## 错误处理

| HTTP 状态码 | 说明 | 处理方式 |
|------------|------|---------|
| 404 | 课程不存在 | 提示用户 |
| 500 | 触发失败 | 提示用户稍后重试 |

---

## 日期

创建: 2025-10-14  
更新: 2025-10-14 - 简化为触发模式
