# 火山引擎视频服务 - 缺失功能检查报告

## 📋 检查日期：2025-12-09

根据《火山引擎视频服务开发计划.md》，对照实际已完成的代码，以下是**详细的缺失功能清单**。

---

## ✅ 已完成部分（核心后端）

### 阶段 1：数据库与类型系统扩展 ✅ 100%
- ✅ AI Provider 类型枚举（volcano-video）
- ✅ AiModel 表扩展（capabilities、defaultParams）
- ✅ Message 表扩展（视频存储字段）
- ✅ TypeScript 类型定义（types/ai.ts）
- ✅ 数据库迁移脚本（0018_add_volcano_video_support.sql）

### 阶段 2：核心 Provider 开发 ✅ 100%
- ✅ volcano-video.ts（完整实现）
- ✅ 图片处理（URL → Base64 + S3）
- ✅ 参数构建（--ratio、--dur等）
- ✅ 任务创建和轮询
- ✅ 同步/流式生成

### 阶段 3：视频永久存储系统 ✅ 100%
- ✅ 视频归档服务（video-archiver.ts）
- ✅ 定时归档任务（video-archive-job.ts）
- ✅ 归档API路由（/api/jobs/archive-videos）
- ✅ Vercel Cron配置（vercel.json）

### 阶段 7：管理后台配置 ✅ 50%（部分完成）
- ✅ AI Provider API 验证（支持 volcano-video）
- ❌ **AI Model API 模型能力配置**（未实现）
- ❌ **前端UI增强**（未实现）

---

## ❌ 缺失功能详细清单

### **【高优先级 P0】阶段 6：Chat API 集成** - 0% 完成

#### 6.1 generate_video Tool 定义 ❌
**文件**：`app/(chat)/api/chat/route.ts`  
**缺失内容**：
```typescript
// 需要新增 generate_video Tool
{
  name: 'generate_video',
  description: '生成视频，支持文生视频、图生视频等多种模式',
  parameters: {
    type: 'object',
    properties: {
      prompt: { type: 'string', description: '视频生成提示词' },
      mode: { 
        type: 'string', 
        enum: ['text-to-video', 'first-frame', 'first-last-frame', 'reference-images'] 
      },
      images: { type: 'array', items: { type: 'string' } },
      resolution: { type: 'string', enum: ['480p', '720p', '1080p'], default: '720p' },
      ratio: { type: 'string', enum: ['16:9', '4:3', '1:1', '3:4', '9:16', '21:9'] },
      duration: { type: 'number', minimum: 2, maximum: 12, default: 5 }
    },
    required: ['prompt', 'mode']
  }
}
```

**影响**：无法通过聊天界面调用视频生成功能。

---

#### 6.2 智能模型选择逻辑 ❌
**文件**：`app/(chat)/api/chat/route.ts`  
**缺失函数**：
- `getCompatibleModel(mode, provider)`：根据生成模式选择合适的模型
- `selectBestModel(models, mode)`：从多个模型中选择最佳模型
- `validateParamsAgainstCapabilities(params, model)`：参数验证

**影响**：无法根据用户选择的模式自动匹配最佳模型。

---

#### 6.3 Tool 执行逻辑 ❌
**文件**：`app/(chat)/api/chat/route.ts`  
**缺失内容**：
```typescript
case 'generate_video': {
  const { prompt, mode, images, ...params } = toolCall.args;
  
  // 1. 根据生成模式自动选择合适的模型
  const compatibleModel = await getCompatibleModel(mode, 'volcano-video');
  
  // 2. 验证参数是否符合模型能力
  validateParamsAgainstCapabilities(params, compatibleModel);
  
  // 3. 根据模式处理图片输入
  const options = buildVideoOptions(mode, images, prompt, params, compatibleModel.modelId);
  
  // 4. 调用视频生成（流式输出进度）
  const result = await generateVideoWithProgress(options);
  
  // 5. 保存临时视频URL到数据库
  await saveVideoMessage({
    chatId: message.chatId,
    role: 'assistant',
    temporaryVideoUrl: result.videoUrl,
    videoMetadata: { taskId, duration, resolution, ratio },
    videoStorageStatus: 'temporary'
  });
  
  // 6. 返回视频链接和预览组件
  return formatVideoToolResult(result);
}
```

**影响**：完全无法生成视频。

---

#### 6.4 保存视频消息到数据库 ❌
**文件**：`app/(chat)/api/chat/route.ts`  
**缺失函数**：
```typescript
async function saveVideoMessage(data: {
  chatId: string;
  role: 'assistant';
  temporaryVideoUrl: string;
  videoMetadata: { taskId, duration, resolution, ratio };
  videoStorageStatus: 'temporary';
}) {
  await db.insert(message).values({
    chatId: data.chatId,
    role: data.role,
    content: `生成的视频`,
    temporaryVideoUrl: data.temporaryVideoUrl,
    videoMetadata: data.videoMetadata,
    videoStorageStatus: data.videoStorageStatus,
    createdAt: new Date(),
  });
}
```

**影响**：视频生成后无法保存到数据库，归档系统无法工作。

---

### **【高优先级 P1】阶段 4：前端参数栏开发** - 0% 完成

#### 4.1 VideoParamsBar 组件 ❌
**文件**：`components/video-params-bar.tsx`（**完全缺失**）  
**需要实现**：
- 横向参数栏布局（模式/分辨率/宽高比/时长/运镜等）
- 动态显示/隐藏选项（根据模型能力）
- 参数实时验证和提示
- 本地存储保存用户偏好

**预计代码量**：~300-500 行

---

#### 4.2 集成到聊天界面 ❌
**文件**：`app/(chat)/page.tsx` 或相关聊天组件  
**缺失内容**：
- 动态图片上传按钮（根据模式显示不同按钮）
  - 文生视频：隐藏图片上传
  - 图生视频-首帧：显示 `[+ 图片]`
  - 首尾帧：显示 `[+ 首帧] [+ 尾帧]`
  - 参考图：显示 `[+ 参考图 (0/4)]`
- 参数栏显示/隐藏控制（仅当选择 volcano-video 模型时显示）
- 参数实时同步到消息发送

**影响**：用户无法在前端界面调整视频参数。

---

#### 4.3 动态 Placeholder 提示 ❌
**文件**：相关聊天输入组件  
**缺失函数**：
```typescript
function getPlaceholder(modelType?: string, mode?: VideoGenerationMode): string {
  if (modelType !== 'volcano-video') return '输入消息...';
  
  switch (mode) {
    case 'text-to-video':
      return '输入文字，描述你想创作的画面内容、运动方式等。';
    case 'first-frame':
      return '描述如何让图片动起来。例如：女孩睁开眼，头发被风吹动。';
    case 'first-last-frame':
      return '描述镜头运动轨迹。例如：360度环绕运镜。';
    case 'reference-images':
      return '描述如何融合参考图元素。';
    default:
      return '输入视频生成提示词...';
  }
}
```

---

### **【中优先级 P2】阶段 5：视频预览组件** - 50% 完成

#### 5.1 视频预览组件 ✅ 部分完成
**文件**：`components/video-preview.tsx`（**已存在**）  
**已有功能**：
- ✅ 视频播放器
- ✅ 下载按钮
- ✅ 全屏播放

**缺失功能**：
- ❌ 封面图显示（使用首帧或尾帧）
- ❌ 悬停显示元数据（分辨率、时长、文件大小）
- ❌ 编辑按钮（类似图片编辑功能）

---

#### 5.2 加载动画组件 ✅ 已复用
**文件**：`components/qianwen-video-loading.tsx`  
**状态**：✅ 可直接复用，无需额外开发

---

### **【中优先级 P2】阶段 7：管理后台配置** - 50% 完成

#### 7.1 AI Provider API ✅ 已完成
**文件**：`app/api/admin/ai-providers/route.ts`  
**状态**：✅ 已支持 volcano-video 类型验证

---

#### 7.2 AI Model API 模型能力配置 ❌
**文件**：`app/api/admin/ai-models/route.ts`  
**缺失内容**：
- ❌ capabilities 字段的 Zod 验证
- ❌ defaultParams 字段的 Zod 验证
- ❌ POST/PUT 接口支持保存模型能力配置

**示例缺失代码**：
```typescript
const modelConfigSchema = z.object({
  modelId: z.string(),
  displayName: z.string(),
  providerId: z.string().uuid(),
  
  // 🆕 模型能力配置（视频模型专用）
  capabilities: z.object({
    supportedModes: z.array(z.enum([
      'text-to-video', 'first-frame', 'first-last-frame', 'reference-images'
    ])),
    supportedResolutions: z.array(z.enum(['480p', '720p', '1080p'])),
    supportedRatios: z.array(z.enum(['16:9', '4:3', '1:1', '3:4', '9:16', '21:9'])),
    durationRange: z.object({ min: z.number(), max: z.number() }),
    supportWatermark: z.boolean(),
    supportCameraFixed: z.boolean(),
    supportSeed: z.boolean(),
    supportReturnLastFrame: z.boolean(),
    maxReferenceImages: z.number().optional()
  }).optional(),
  
  // 🆕 默认参数配置
  defaultParams: z.object({
    resolution: z.enum(['480p', '720p', '1080p']).default('720p'),
    ratio: z.enum(['16:9', '4:3', '1:1', '3:4', '9:16', '21:9']).default('16:9'),
    duration: z.number().min(2).max(12).default(5),
    watermark: z.boolean().default(true),
    cameraFixed: z.boolean().default(false)
  }).optional()
});
```

---

#### 7.3 前端UI增强 ❌
**文件**：`app/(admin)/settings/admin-settings-client.tsx` 或相关管理页面  
**缺失内容**：
- ❌ 添加模型时配置能力参数的UI表单
- ❌ 支持的功能复选框（文生视频/图生视频等）
- ❌ 支持的参数配置（分辨率/宽高比/时长范围等）
- ❌ 默认参数设置表单
- ❌ 预设模板快速应用功能

**影响**：管理员无法通过UI配置模型能力，只能手动修改数据库。

---

### **【低优先级 P3】阶段 8：测试与优化** - 0% 完成

#### 8.1 单元测试 ❌
**缺失内容**：
- volcano-video.ts 的单元测试
- video-archiver.ts 的单元测试
- 参数验证逻辑测试

---

#### 8.2 集成测试 ❌
**缺失内容**：
- 完整的视频生成流程测试
- 归档任务测试
- S3存储集成测试

---

#### 8.3 性能优化 ❌
**缺失内容**：
- 视频下载超时优化
- 并发归档数量调整
- 数据库查询索引优化验证

---

## 📊 完成度统计

| 阶段 | 描述 | 完成度 | 状态 |
|------|------|--------|------|
| 阶段 1 | 数据库与类型系统扩展 | 100% | ✅ 已完成 |
| 阶段 2 | 核心 Provider 开发 | 100% | ✅ 已完成 |
| 阶段 3 | 视频永久存储系统 | 100% | ✅ 已完成 |
| **阶段 4** | **前端参数栏开发** | **0%** | ❌ **未开始** |
| 阶段 5 | 视频预览组件 | 50% | ⚠️ 部分完成 |
| **阶段 6** | **Chat API 集成** | **0%** | ❌ **未开始** |
| 阶段 7 | 管理后台配置 | 50% | ⚠️ 部分完成 |
| 阶段 8 | 测试与优化 | 0% | ❌ 未开始 |

**总体完成度：约 50%**（核心后端完成，前端和集成未完成）

---

## 🚨 核心阻塞问题

### ⚠️ 无法使用的原因
目前用户**完全无法使用视频生成功能**，因为：

1. **Chat API 未集成 generate_video Tool** ❌
   - 聊天界面无法触发视频生成
   - 即使调用 Provider 也无法保存到数据库

2. **前端参数栏未开发** ❌
   - 用户无法选择生成模式
   - 无法上传图片
   - 无法调整参数（分辨率/时长等）

3. **管理后台配置不完整** ❌
   - 管理员无法添加视频模型
   - 无法配置模型能力

---

## 🎯 优先级开发建议

### **Phase 1：核心功能（1-2天）- 必须完成**
1. ✅ Chat API 集成（generate_video Tool）
   - Tool 定义
   - 执行逻辑
   - 数据库保存
   - 智能模型选择

### **Phase 2：最小可用UI（2-3天）- 必须完成**
2. ✅ 简化版参数栏
   - 基础模式选择（下拉菜单）
   - 图片上传按钮（根据模式动态显示）
   - 基础参数调整（分辨率/时长）

3. ✅ 管理后台基础配置
   - AI Model API 支持 capabilities/defaultParams
   - 简单的表单支持添加模型能力

### **Phase 3：完整体验（3-4天）- 可选优化**
4. ⚠️ 完整参数栏（横向布局、高级选项）
5. ⚠️ 管理后台UI完善（预设模板、参数验证）
6. ⚠️ 视频预览组件增强（元数据显示）

### **Phase 4：测试与优化（1-2天）- 可选**
7. ⚠️ 功能测试
8. ⚠️ 性能优化

---

## 📋 立即行动清单

### 🔴 紧急（P0）- 无此功能无法使用
- [ ] 实现 Chat API generate_video Tool
- [ ] 实现智能模型选择逻辑
- [ ] 实现视频消息保存到数据库

### 🟠 重要（P1）- 基础可用性
- [ ] 创建简化版 VideoParamsBar 组件
- [ ] 集成参数栏到聊天界面
- [ ] 实现动态图片上传按钮
- [ ] 扩展 AI Model API 支持 capabilities

### 🟡 优化（P2）- 增强体验
- [ ] 完善视频预览组件（元数据显示）
- [ ] 完善管理后台UI（模型能力配置表单）
- [ ] 添加预设模板功能

### 🟢 可选（P3）- 锦上添花
- [ ] 单元测试
- [ ] 性能优化
- [ ] 错误处理增强

---

## 📝 总结

**核心问题**：
- ❌ **Chat API 完全未集成**：无法调用视频生成
- ❌ **前端参数栏完全缺失**：用户无法操作
- ❌ **管理后台配置不完整**：无法添加模型

**建议方案**：
1. **优先完成 Phase 1**（Chat API集成），实现基础功能
2. **然后完成 Phase 2**（简化版UI），达到最小可用状态
3. **最后完成 Phase 3/4**（完整体验和优化）

**预计剩余工作量**：
- Phase 1：1-2 天（高优先级）
- Phase 2：2-3 天（高优先级）
- Phase 3/4：4-6 天（可选优化）

**总计**：约 7-11 天完成完整功能（最少需要 3-5 天达到最小可用状态）

---

**报告生成时间**：2025-12-09  
**检查范围**：完整对比开发计划文档  
**检查结果**：缺失约 50% 功能（主要是前端和API集成）