imeepos/mixvideo-v2
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

feat: 实现模板匹配结果保存和管理功能

Browse Source 
- 新增模板匹配结果数据模型和数据库表结构
- 实现匹配结果Repository层，支持CRUD操作和查询
- 实现匹配结果Service层，提供业务逻辑和统计功能
- 新增Tauri命令接口，支持前端调用
- 实现前端TypeScript类型定义
- 更新MaterialMatchingService，支持自动保存匹配结果
- 新增前端管理界面组件：
  - TemplateMatchingResultManager: 主管理界面
  - TemplateMatchingResultCard: 结果卡片组件
  - TemplateMatchingResultDetailModal: 详情模态框
  - TemplateMatchingResultStatsPanel: 统计面板
- 编写完整的单元测试
- 新增API文档

功能特性：
- 保存匹配结果到数据库，包含成功和失败片段详情
- 支持匹配结果的查询、过滤、排序和分页
- 提供匹配统计信息和质量评分
- 支持软删除和批量操作
- 完整的前端管理界面，支持查看、编辑、删除操作
This commit is contained in:
imeepos
2025-07-16 13:34:32 +08:00
parent 1eebc98853
commit 1d6de409ed
21 changed files with 3895 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

383
docs/api/template-matching-result-api.md Normal file
View File

@@ -0,0 +1,383 @@
# 模板匹配结果 API 文档
## 概述
模板匹配结果 API 提供了完整的模板匹配结果管理功能，包括保存匹配结果、查询历史记录、管理匹配详情等操作。
## 数据模型
### TemplateMatchingResult
模板匹配结果主要实体。
```typescript
interface TemplateMatchingResult {
id: string; // 匹配结果唯一标识
project_id: string; // 项目ID
template_id: string; // 模板ID
binding_id: string; // 绑定ID
result_name: string; // 结果名称
description?: string; // 结果描述
total_segments: number; // 总片段数
matched_segments: number; // 匹配成功片段数
failed_segments: number; // 匹配失败片段数
success_rate: number; // 成功率（百分比）
used_materials: number; // 使用的素材数量
used_models: number; // 使用的模特数量
matching_duration_ms: number; // 匹配耗时（毫秒）
quality_score?: number; // 质量评分（0-5）
status: MatchingResultStatus; // 匹配状态
metadata?: string; // 额外元数据（JSON格式）
created_at: string; // 创建时间
updated_at: string; // 更新时间
is_active: boolean; // 是否激活
}
```
### MatchingResultStatus
匹配结果状态枚举。
```typescript
enum MatchingResultStatus {
Success = 'Success', // 匹配成功
PartialSuccess = 'PartialSuccess', // 部分成功
Failed = 'Failed', // 匹配失败
Cancelled = 'Cancelled' // 已取消
}
```
### MatchingSegmentResult
成功匹配的片段结果。
```typescript
interface MatchingSegmentResult {
id: string; // 片段结果ID
matching_result_id: string; // 关联的匹配结果ID
track_segment_id: string; // 模板轨道片段ID
track_segment_name: string; // 轨道片段名称
material_segment_id: string; // 匹配到的素材片段ID
material_id: string; // 素材ID
material_name: string; // 素材名称
model_id?: string; // 模特ID
model_name?: string; // 模特名称
match_score: number; // 匹配评分（0-1）
match_reason: string; // 匹配原因
segment_duration: number; // 片段时长（微秒）
start_time: number; // 开始时间（微秒）
end_time: number; // 结束时间（微秒）
properties?: string; // 片段属性（JSON格式）
created_at: string; // 创建时间
updated_at: string; // 更新时间
}
```
### MatchingFailedSegmentResult
匹配失败的片段结果。
```typescript
interface MatchingFailedSegmentResult {
id: string; // 失败片段结果ID
matching_result_id: string; // 关联的匹配结果ID
track_segment_id: string; // 模板轨道片段ID
track_segment_name: string; // 轨道片段名称
matching_rule_type: string; // 匹配规则类型
matching_rule_data?: string; // 匹配规则数据（JSON格式）
failure_reason: string; // 失败原因
failure_details?: string; // 失败详情（JSON格式）
segment_duration: number; // 片段时长（微秒）
start_time: number; // 开始时间（微秒）
end_time: number; // 结束时间（微秒）
created_at: string; // 创建时间
updated_at: string; // 更新时间
}
```
## API 接口
### 1. 保存匹配结果
自动保存素材匹配结果到数据库。
```typescript
save_matching_result(
service_result: MaterialMatchingResult,
result_name: string,
description?: string,
matching_duration_ms: number
): Promise<TemplateMatchingResult>
```
**参数说明：**
- `service_result`: 素材匹配服务返回的匹配结果
- `result_name`: 结果名称
- `description`: 可选的结果描述
- `matching_duration_ms`: 匹配耗时（毫秒）
**返回值：** 保存后的模板匹配结果
### 2. 获取匹配结果详情
获取包含所有片段信息的完整匹配结果详情。
```typescript
get_matching_result_detail(result_id: string): Promise<TemplateMatchingResultDetail | null>
```
**参数说明：**
- `result_id`: 匹配结果ID
**返回值：** 匹配结果详情，包含成功和失败的片段信息
### 3. 获取项目匹配结果列表
获取指定项目的所有匹配结果。
```typescript
get_project_matching_results(project_id: string): Promise<TemplateMatchingResult[]>
```
**参数说明：**
- `project_id`: 项目ID
**返回值：** 匹配结果列表
### 4. 获取模板匹配结果列表
获取指定模板的所有匹配结果。
```typescript
get_template_matching_results(template_id: string): Promise<TemplateMatchingResult[]>
```
**参数说明：**
- `template_id`: 模板ID
**返回值：** 匹配结果列表
### 5. 获取绑定匹配结果列表
获取指定绑定的所有匹配结果。
```typescript
get_binding_matching_results(binding_id: string): Promise<TemplateMatchingResult[]>
```
**参数说明：**
- `binding_id`: 绑定ID
**返回值：** 匹配结果列表
### 6. 查询匹配结果列表
根据查询条件获取匹配结果列表。
```typescript
list_matching_results(options: TemplateMatchingResultQueryOptions): Promise<TemplateMatchingResult[]>
```
**参数说明：**
- `options`: 查询选项
```typescript
interface TemplateMatchingResultQueryOptions {
project_id?: string; // 项目ID过滤
template_id?: string; // 模板ID过滤
binding_id?: string; // 绑定ID过滤
status?: MatchingResultStatus; // 状态过滤
limit?: number; // 限制数量
offset?: number; // 偏移量
search_keyword?: string; // 搜索关键词
sort_by?: string; // 排序字段
sort_order?: string; // 排序顺序
}
```
### 7. 删除匹配结果
永久删除匹配结果。
```typescript
delete_matching_result(result_id: string): Promise<boolean>
```
**参数说明：**
- `result_id`: 匹配结果ID
**返回值：** 是否删除成功
### 8. 软删除匹配结果
软删除匹配结果（标记为不活跃）。
```typescript
soft_delete_matching_result(result_id: string): Promise<boolean>
```
**参数说明：**
- `result_id`: 匹配结果ID
**返回值：** 是否删除成功
### 9. 更新匹配结果信息
更新匹配结果的名称和描述。
```typescript
update_matching_result_info(
result_id: string,
result_name?: string,
description?: string
): Promise<TemplateMatchingResult | null>
```
**参数说明：**
- `result_id`: 匹配结果ID
- `result_name`: 新的结果名称（可选）
- `description`: 新的结果描述（可选）
**返回值：** 更新后的匹配结果
### 10. 设置质量评分
为匹配结果设置质量评分。
```typescript
set_matching_result_quality_score(
result_id: string,
quality_score: number
): Promise<TemplateMatchingResult | null>
```
**参数说明：**
- `result_id`: 匹配结果ID
- `quality_score`: 质量评分（0-5）
**返回值：** 更新后的匹配结果
### 11. 获取匹配统计信息
获取匹配结果的统计信息。
```typescript
get_matching_statistics(project_id?: string): Promise<MatchingStatistics>
```
**参数说明：**
- `project_id`: 可选的项目ID，如果提供则只统计该项目的数据
**返回值：** 匹配统计信息
```typescript
interface MatchingStatistics {
total_results: number; // 总结果数
successful_results: number; // 成功结果数
total_segments: number; // 总片段数
matched_segments: number; // 匹配片段数
total_materials: number; // 总素材数
total_models: number; // 总模特数
average_success_rate: number; // 平均成功率
}
```
### 12. 执行匹配并自动保存
执行素材匹配并自动保存结果到数据库。
```typescript
execute_material_matching_with_save(
request: MaterialMatchingRequest,
result_name: string,
description?: string
): Promise<[MaterialMatchingResult, TemplateMatchingResult | null]>
```
**参数说明：**
- `request`: 素材匹配请求
- `result_name`: 结果名称
- `description`: 可选的结果描述
**返回值：** 包含匹配结果和保存结果的元组
## 错误处理
所有 API 接口都会返回 `Result<T, String>` 类型，其中错误信息为字符串格式。常见错误包括：
- `"模板匹配结果不存在"`: 指定的匹配结果ID不存在
- `"项目不存在"`: 指定的项目ID不存在
- `"模板不存在"`: 指定的模板ID不存在
- `"数据库操作失败"`: 数据库操作出现错误
- `"参数验证失败"`: 输入参数不符合要求
## 使用示例
### 保存匹配结果
```typescript
import { invoke } from '@tauri-apps/api/core';
// 执行匹配并保存结果
const result = await invoke('execute_material_matching_with_save', {
request: {
project_id: 'project-1',
template_id: 'template-1',
binding_id: 'binding-1',
overwrite_existing: false,
},
resultName: '我的匹配结果',
description: '这是一个测试匹配结果',
});
console.log('匹配结果:', result[0]);
console.log('保存结果:', result[1]);
```
### 查询匹配结果
```typescript
// 获取项目的所有匹配结果
const results = await invoke('get_project_matching_results', {
projectId: 'project-1',
});
// 获取匹配结果详情
const detail = await invoke('get_matching_result_detail', {
resultId: 'result-1',
});
// 查询匹配结果（带过滤条件）
const filteredResults = await invoke('list_matching_results', {
options: {
project_id: 'project-1',
status: 'Success',
limit: 10,
offset: 0,
sort_by: 'created_at',
sort_order: 'desc',
},
});
```
### 管理匹配结果
```typescript
// 更新匹配结果信息
await invoke('update_matching_result_info', {
resultId: 'result-1',
resultName: '更新后的名称',
description: '更新后的描述',
});
// 设置质量评分
await invoke('set_matching_result_quality_score', {
resultId: 'result-1',
qualityScore: 4.5,
});
// 软删除匹配结果
await invoke('soft_delete_matching_result', {
resultId: 'result-1',
});
```