video-flow-b/scripts/README.md

# 批量视频导出脚本

这个脚本用于批量处理项目ID，生成剪辑计划并调用导出接口，实现自动化的视频处理流程。

## 功能特性

- ✅ 批量处理多个项目ID
- ✅ 自动生成剪辑计划（调用 `/edit-plan/generate-by-project` 接口）
- ✅ 自动调用导出接口（调用 `/api/export/stream` 接口）
- ✅ 支持并发处理，提高效率
- ✅ 完整的错误处理和重试机制
- ✅ 实时进度跟踪和日志记录
- ✅ 生成详细的处理报告
- ✅ 支持从命令行或文件读取项目ID

## 文件说明

- `batch-export.js` - JavaScript版本的主脚本（推荐使用）
- `batch-video-export.ts` - TypeScript版本的主脚本
- `batch-config.example.env` - 配置文件示例
- `projects.example.txt` - 项目ID列表文件示例

## 快速开始

### 1. 配置环境变量

复制配置文件并填入实际值：

```bash
cp scripts/batch-config.example.env scripts/batch-config.env
```

编辑 `batch-config.env` 文件：

```env
# API配置
API_BASE_URL=https://your-api-domain.com
AUTH_TOKEN=your-actual-auth-token
USER_ID=your-actual-user-id

# 处理配置
CONCURRENCY=3          # 并发处理数量
MAX_RETRIES=3          # 最大重试次数
RETRY_DELAY=5000       # 重试间隔（毫秒）

# 导出配置
EXPORT_QUALITY=standard # 导出质量: standard | high | ultra

# 输出配置
OUTPUT_DIR=./batch-export-output  # 输出目录
```

### 2. 准备项目ID列表

**方法一：命令行参数**
```bash
node scripts/batch-export.js --projects "project-001,project-002,project-003"
```

**方法二：文件列表**

创建项目ID文件：
```bash
cp scripts/projects.example.txt scripts/projects.txt
```

编辑 `projects.txt` 文件：
```text
project-001
project-002
project-003
project-004
# project-005  # 注释行会被忽略
```

然后运行：
```bash
node scripts/batch-export.js --file scripts/projects.txt
```

### 3. 运行脚本

加载环境变量并运行：

```bash
# 加载配置文件
source scripts/batch-config.env

# 运行脚本
node scripts/batch-export.js --projects "project-001,project-002"
```

或者一次性运行：

```bash
API_BASE_URL=https://your-api.com AUTH_TOKEN=your-token node scripts/batch-export.js --projects "project-001,project-002"
```

## 使用方法

### 命令行选项

```bash
# 使用项目ID参数
node scripts/batch-export.js --projects "id1,id2,id3"

# 使用文件列表
node scripts/batch-export.js --file projects.txt
```

### 环境变量配置

| 变量名 | 说明 | 默认值 | 必填 |
|--------|------|--------|------|
| `API_BASE_URL` | API基础URL | - | ✅ |
| `AUTH_TOKEN` | 认证Token | - | ✅ |
| `USER_ID` | 用户ID | - | ✅ |
| `CONCURRENCY` | 并发处理数量 | 3 | ❌ |
| `MAX_RETRIES` | 最大重试次数 | 3 | ❌ |
| `RETRY_DELAY` | 重试间隔(毫秒) | 5000 | ❌ |
| `EXPORT_QUALITY` | 导出质量 | standard | ❌ |
| `OUTPUT_DIR` | 输出目录 | ./batch-export-output | ❌ |

## 工作流程

脚本会按以下步骤处理每个项目：

1. **生成剪辑计划**
   - 调用 `/edit-plan/generate-by-project` 接口
   - 支持自动重试（最多10分钟，8秒间隔）
   - 等待剪辑计划生成完成

2. **构建导出请求**
   - 解析剪辑计划中的时间线信息
   - 构建符合API规范的导出请求数据
   - 包含视频片段、字幕、转场等信息

3. **调用导出接口**
   - 调用 `/api/export/stream` 流式导出接口
   - 实时处理SSE事件流
   - 监控导出进度

4. **轮询导出状态**
   - 如果SSE未返回完整结果，自动轮询进度
   - 调用 `/api/export/task/{taskId}/progress` 接口
   - 等待导出完成并获取视频URL

## 输出文件

脚本运行后会在输出目录生成以下文件：

- `batch-export-{timestamp}.log` - 详细日志文件
- `batch-report-{timestamp}.json` - 处理结果报告

### 报告格式示例

```json
{
  "timestamp": "2023-12-07T10:30:00.000Z",
  "config": {
    "concurrency": 3,
    "maxRetries": 3,
    "exportQuality": "standard"
  },
  "results": {
    "total": 5,
    "completed": 4,
    "failed": 1,
    "errors": [
      {
        "projectId": "project-005",
        "error": "剪辑计划生成失败"
      }
    ]
  },
  "projects": [
    {
      "projectId": "project-001",
      "status": "completed",
      "videoUrl": "https://example.com/video1.mp4",
      "duration": 125.5
    }
  ]
}
```

## 错误处理

脚本包含完善的错误处理机制：

### 自动重试
- 剪辑计划生成失败：最多重试10分钟
- 导出接口调用失败：根据配置重试
- 网络错误：自动重试

### 错误类型
- **剪辑计划生成失败**：API返回错误或超时
- **导出接口错误**：请求格式错误或服务器错误
- **网络连接错误**：网络不稳定或服务不可用
- **认证错误**：Token无效或过期

### 故障恢复
- 单个项目失败不影响其他项目处理
- 详细错误日志帮助定位问题
- 支持断点续传（可以只处理失败的项目）

## 性能优化

### 并发控制
- 默认并发数为3，可根据服务器性能调整
- 避免同时处理太多项目导致服务器压力

### 内存管理
- 流式处理SSE响应，避免内存积累
- 及时释放不需要的数据

### 网络优化
- 合理的重试间隔，避免频繁请求
- 长连接处理SSE流

## 故障排除

### 常见问题

1. **认证失败**
   ```
   错误：HTTP 401: Unauthorized
   解决：检查 AUTH_TOKEN 是否正确
   ```

2. **API地址错误**
   ```
   错误：ENOTFOUND your-api-domain.com
   解决：检查 API_BASE_URL 是否正确
   ```

3. **剪辑计划生成超时**
   ```
   错误：获取剪辑计划超时，已重试75次
   解决：检查项目状态，可能需要更长等待时间
   ```

4. **Node.js版本问题**
   ```
   错误：fetch is not defined
   解决：升级到 Node.js 18+ 或安装 node-fetch
   ```

### 调试技巧

1. **查看详细日志**
   ```bash
   tail -f batch-export-output/batch-export-*.log
   ```

2. **测试单个项目**
   ```bash
   node scripts/batch-export.js --projects "single-project-id"
   ```

3. **检查API连通性**
   ```bash
   curl -H "Authorization: Bearer $AUTH_TOKEN" $API_BASE_URL/health
   ```

## 高级用法

### 自定义配置

可以通过修改脚本中的配置对象来自定义更多选项：

```javascript
const config = {
  apiBaseUrl: process.env.API_BASE_URL,
  token: process.env.AUTH_TOKEN,
  // 自定义超时时间
  requestTimeout: 30000,
  // 自定义User-Agent
  userAgent: 'BatchVideoExporter/1.0',
  // 其他配置...
};
```

### 集成到CI/CD

可以将脚本集成到自动化流程中：

```yaml
# GitHub Actions 示例
- name: Batch Export Videos
  env:
    API_BASE_URL: ${{ secrets.API_BASE_URL }}
    AUTH_TOKEN: ${{ secrets.AUTH_TOKEN }}
    USER_ID: ${{ secrets.USER_ID }}
  run: |
    node scripts/batch-export.js --file projects.txt
```

## 注意事项

1. **资源使用**：批量处理会消耗较多服务器资源，建议在低峰期运行
2. **网络稳定性**：确保网络连接稳定，避免长时间处理中断
3. **存储空间**：确保有足够的存储空间保存日志和报告文件
4. **API限制**：注意API的调用频率限制，避免被限流
5. **数据备份**：重要项目建议先备份，避免处理过程中数据丢失

## 许可证

MIT License