10 KiB
10 KiB
模板匹配结果 API 文档
概述
模板匹配结果 API 提供了完整的模板匹配结果管理功能，包括保存匹配结果、查询历史记录、管理匹配详情等操作。
数据模型
TemplateMatchingResult
模板匹配结果主要实体。
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
匹配结果状态枚举。
enum MatchingResultStatus {
Success = 'Success', // 匹配成功
PartialSuccess = 'PartialSuccess', // 部分成功
Failed = 'Failed', // 匹配失败
Cancelled = 'Cancelled' // 已取消
}
MatchingSegmentResult
成功匹配的片段结果。
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
匹配失败的片段结果。
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. 保存匹配结果
自动保存素材匹配结果到数据库。
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. 获取匹配结果详情
获取包含所有片段信息的完整匹配结果详情。
get_matching_result_detail(result_id: string): Promise<TemplateMatchingResultDetail | null>
参数说明：
result_id: 匹配结果ID
返回值： 匹配结果详情，包含成功和失败的片段信息
3. 获取项目匹配结果列表
获取指定项目的所有匹配结果。
get_project_matching_results(project_id: string): Promise<TemplateMatchingResult[]>
参数说明：
project_id: 项目ID
返回值： 匹配结果列表
4. 获取模板匹配结果列表
获取指定模板的所有匹配结果。
get_template_matching_results(template_id: string): Promise<TemplateMatchingResult[]>
参数说明：
template_id: 模板ID
返回值： 匹配结果列表
5. 获取绑定匹配结果列表
获取指定绑定的所有匹配结果。
get_binding_matching_results(binding_id: string): Promise<TemplateMatchingResult[]>
参数说明：
binding_id: 绑定ID
返回值： 匹配结果列表
6. 查询匹配结果列表
根据查询条件获取匹配结果列表。
list_matching_results(options: TemplateMatchingResultQueryOptions): Promise<TemplateMatchingResult[]>
参数说明：
options: 查询选项
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. 删除匹配结果
永久删除匹配结果。
delete_matching_result(result_id: string): Promise<boolean>
参数说明：
result_id: 匹配结果ID
返回值： 是否删除成功
8. 软删除匹配结果
软删除匹配结果（标记为不活跃）。
soft_delete_matching_result(result_id: string): Promise<boolean>
参数说明：
result_id: 匹配结果ID
返回值： 是否删除成功
9. 更新匹配结果信息
更新匹配结果的名称和描述。
update_matching_result_info(
result_id: string,
result_name?: string,
description?: string
): Promise<TemplateMatchingResult | null>
参数说明：
result_id: 匹配结果IDresult_name: 新的结果名称（可选）description: 新的结果描述（可选）
返回值： 更新后的匹配结果
10. 设置质量评分
为匹配结果设置质量评分。
set_matching_result_quality_score(
result_id: string,
quality_score: number
): Promise<TemplateMatchingResult | null>
参数说明：
result_id: 匹配结果IDquality_score: 质量评分（0-5）
返回值： 更新后的匹配结果
11. 获取匹配统计信息
获取匹配结果的统计信息。
get_matching_statistics(project_id?: string): Promise<MatchingStatistics>
参数说明：
project_id: 可选的项目ID，如果提供则只统计该项目的数据
返回值： 匹配统计信息
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. 执行匹配并自动保存
执行素材匹配并自动保存结果到数据库。
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不存在"数据库操作失败": 数据库操作出现错误"参数验证失败": 输入参数不符合要求
使用示例
保存匹配结果
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]);
查询匹配结果
// 获取项目的所有匹配结果
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',
},
});
管理匹配结果
// 更新匹配结果信息
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',
});