xiaoxia-saas/tests/render_compare/README_assets.md

# 测试素材创建工具

`create_test_asset.py` 是一个自动化测试辅助工具，用于快速创建 `ready` 状态的视频素材，跳过正常的上传和转码流程，直接指定已存在于 OSS 的文件来生成可用素材。

## 适用场景

- 渲染对比测试：快速创建测试素材用于生成任务
- 性能测试：批量创建素材模拟真实场景
- 开发调试：无需真实上传文件即可测试素材相关功能

## 前置条件

1. API 服务正在运行
2. 有有效的登录 token
3. 指定的 `storage_key` 对应的文件已存在于 OSS 中
4. 用户对指定项目有访问权限

## 使用方法

### 基本用法

```bash
# 设置环境变量（可选）
export API_BASE_URL=http://localhost:8000
export API_TOKEN=your_token_here

# 创建测试素材
python tests/render_compare/create_test_asset.py \
    --project-id proj_xxx \
    --name "测试素材-30s" \
    --storage-key "assets/test/sample_30s.mp4" \
    --duration 30 \
    --file-size 10485760
```

### 完整参数示例

```bash
python tests/render_compare/create_test_asset.py \
    --base-url http://localhost:8000 \
    --token eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... \
    --project-id proj_a1b2c3d4e5f6 \
    --name "1080p测试视频-60s" \
    --storage-key "test-assets/1080p_60fps_60s.mp4" \
    --duration 60 \
    --width 1920 \
    --height 1080 \
    --fps 60 \
    --mime-type "video/mp4" \
    --file-size 52428800 \
    --codec "h264" \
    --kind video
```

### 在脚本中捕获 asset_id

```bash
# 最后一行输出为 asset_id，方便脚本捕获
ASSET_ID=$(python tests/render_compare/create_test_asset.py \
    --project-id proj_xxx \
    --name "测试素材" \
    --storage-key "test/video.mp4" \
    2>&1 | tail -1)

echo "创建的素材 ID: $ASSET_ID"
```

## 参数说明

| 参数 | 环境变量 | 必填 | 默认值 | 说明 |
|------|----------|------|--------|------|
| `--base-url` | `API_BASE_URL` | 否 | `http://localhost:8000` | API 服务地址 |
| `--token` | `API_TOKEN` | 是 | - | 登录认证 token |
| `--project-id` | - | 是 | - | 项目 ID |
| `--name` | - | 是 | - | 素材名称 |
| `--storage-key` | - | 是 | - | OSS storage_key（文件需已存在） |
| `--duration` | - | 否 | `30` | 视频时长（秒） |
| `--width` | - | 否 | `1280` | 视频宽度 |
| `--height` | - | 否 | `720` | 视频高度 |
| `--fps` | - | 否 | `25` | 帧率 |
| `--mime-type` | - | 否 | `video/mp4` | MIME 类型 |
| `--file-size` | - | 否 | `0` | 文件大小（字节） |
| `--codec` | - | 否 | - | 视频编码 |
| `--kind` | - | 否 | `video` | 素材库类型 (video/voice/image) |

## API 调用流程

脚本会依次调用以下 API：

### 1. 确保默认素材库存在

```
POST /api/v1/asset-libraries/ensure-default
Content-Type: application/json
Authorization: Bearer {token}

{
  "project_id": "proj_xxx",
  "kind": "video"
}
```

- 如果项目下已有对应类型的素材库，直接返回第一个
- 如果不存在，自动创建默认名称的素材库

### 2. 创建素材

```
POST /api/v1/assets
Content-Type: application/json
Authorization: Bearer {token}

{
  "project_id": "proj_xxx",
  "library_id": "lib_xxx",
  "name": "测试素材",
  "storage_key": "assets/test/video.mp4",
  "mime_type": "video/mp4",
  "file_size": 10485760,
  "duration": 30,
  "width": 1280,
  "height": 720,
  "fps": 25,
  "status": "ready",
  "classification_status": "pending",
  "metadata": {}
}
```

**关键点**：
- `status: "ready"` 直接跳过转码流程，立即可用
- `storage_key` 必须对应 OSS 中真实存在的文件，否则播放会失败
- `uploaded_by_user_id` 由 API 自动设置为当前登录用户

## 输出说明

脚本输出分为三部分：

1. **参数回显**：确认输入的参数是否正确
2. **执行日志**：显示每一步的执行情况
3. **结果输出**：
   - 素材详细信息（asset_id、状态、文件 URL 等）
   - 调用示例
   - 最后一行为纯 asset_id，方便脚本捕获

## 错误排查

### 常见错误

#### 401 Unauthorized
- 检查 token 是否正确且未过期
- 确认 Authorization header 格式为 `Bearer {token}`

#### 403 Forbidden
- 确认用户对该项目有访问权限
- 检查项目 ID 是否正确

#### 404 Project not found
- 项目 ID 错误或项目不存在

#### 422 Validation Error
- 检查参数格式是否正确
- 查看响应中的 detail 字段了解具体错误

### 调试技巧

脚本在 API 失败时会打印完整的响应内容，包括：
- HTTP 状态码
- 错误原因
- 响应 body 详情

如果遇到问题，请检查：
1. API 服务是否正常运行
2. base-url 是否正确（注意端口号）
3. token 是否有效
4. storage_key 对应的文件是否存在于 OSS

## 与渲染对比测试配合使用

```bash
# 1. 创建测试素材
ASSET_ID=$(python tests/render_compare/create_test_asset.py \
    --project-id proj_xxx \
    --name "渲染对比测试素材" \
    --storage-key "test-assets/base_1080p_30s.mp4" \
    --duration 30 --width 1920 --height 1080 \
    2>&1 | tail -1)

# 2. 使用该素材运行渲染对比测试
python tests/render_compare/runner.py \
    --project-id proj_xxx \
    --asset-id $ASSET_ID \
    --scenario quality_test
```

## 注意事项

1. **storage_key 必须真实存在**：脚本不会上传文件，只是创建数据库记录。如果 OSS 中没有对应文件，素材虽然状态是 ready，但无法正常播放。
2. **素材参数要准确**：duration、width、height、fps 等参数应与实际文件一致，否则可能导致后续渲染或分析出现偏差。
3. **权限检查**：确保 token 对应用户有项目的素材创建权限。
4. **清理测试数据**：测试完成后记得清理不需要的测试素材，避免占用资源。