384 lines
10 KiB
Markdown
384 lines
10 KiB
Markdown
# 模板匹配结果 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',
|
||
});
|
||
```
|