feat: 更新 FaceFilterSettings TypeScript 类型定义为三段式统一结构
变更内容： - 创建 src/types/faceFilter.ts 类型定义文件 - 新增 UiFilterRules, ProcessingThresholds, TraceSettings 三个子结构 - 更新 FaceFilterSettings 为三段式统一结构 - min_confidence 范围从 0-100 改为 0.0-1.0 - min_size 重命名为 min_bbox_size - 新增字段: max_confidence, max_bbox_size, source, backend_status 向后兼容性： - FaceFilterSettingsMigration.fromLegacy() 自动转换旧格式 - FaceFilterSettingsMigration.defaults() 提供默认值 - 保留向后兼容字段（deprecated 标记） 更新文件： - src/composables/useFaceFilter.ts: 使用新类型，更新变量名 - src/components/FaceFilterPanel.vue: 更新导入和变量引用 - docs/FACE_FILTER_SETTINGS_MIGRATION_GUIDE.md: 完整迁移指南 测试： - ✅ TypeScript 编译通过 - ✅ Vite build 成功 对应 Core API commit: 86c776ce
This commit is contained in:
367
docs/FACE_FILTER_SETTINGS_MIGRATION_GUIDE.md
Normal file
367
docs/FACE_FILTER_SETTINGS_MIGRATION_GUIDE.md
Normal file
@@ -0,0 +1,367 @@
|
||||
# Face Filter Settings Migration Guide
|
||||
|
||||
## 概述
|
||||
|
||||
本文档说明如何从旧版 FaceFilterSettings 迁移到新的三段式统一结构。
|
||||
|
||||
**相关 Git Commit:**
|
||||
- Core API: `86c776ce` - feat: 更新 FaceFilterSettings 为三段式统一结构
|
||||
- Studio: 更新 TypeScript 类型和 composable
|
||||
|
||||
---
|
||||
|
||||
## 变更内容
|
||||
|
||||
### 1. 数据结构变更
|
||||
|
||||
#### 旧版结构
|
||||
```typescript
|
||||
interface SingleFrameFSSettings {
|
||||
single_frame_trace_vlm_enabled: boolean;
|
||||
single_frame_trace_group_enabled: boolean;
|
||||
single_frame_trace_unassigned_enabled: boolean;
|
||||
single_trace_group_filter_enabled: boolean;
|
||||
}
|
||||
|
||||
interface QuickFilterRules {
|
||||
min_confidence?: number; // 可能是 0-100
|
||||
max_confidence?: number;
|
||||
min_bbox_size?: number;
|
||||
max_bbox_size?: number;
|
||||
source?: string;
|
||||
backend_status?: string;
|
||||
}
|
||||
```
|
||||
|
||||
#### 新版结构
|
||||
```typescript
|
||||
interface UiFilterRules {
|
||||
min_confidence: number; // 0.0-1.0 (强制)
|
||||
max_confidence?: number; // 0.0-1.0
|
||||
min_bbox_size: number; // 重命名自 min_size
|
||||
max_bbox_size?: number;
|
||||
source?: string;
|
||||
backend_status?: string;
|
||||
}
|
||||
|
||||
interface ProcessingThresholds {
|
||||
min_confidence: number;
|
||||
max_confidence?: number;
|
||||
min_bbox_size: number;
|
||||
max_bbox_size?: number;
|
||||
}
|
||||
|
||||
interface TraceSettings {
|
||||
single_frame_trace_vlm_enabled: boolean;
|
||||
single_frame_trace_group_enabled: boolean;
|
||||
single_frame_trace_unassigned_enabled: boolean;
|
||||
single_trace_group_filter_enabled: boolean;
|
||||
}
|
||||
|
||||
interface FaceFilterSettings {
|
||||
ui_filter_rules: UiFilterRules;
|
||||
processing_thresholds: ProcessingThresholds;
|
||||
trace_settings: TraceSettings;
|
||||
|
||||
// 向后兼容字段
|
||||
min_confidence: number;
|
||||
max_confidence?: number;
|
||||
min_bbox_size: number;
|
||||
max_bbox_size?: number;
|
||||
source?: string;
|
||||
backend_status?: string;
|
||||
|
||||
single_frame_trace_vlm_enabled: boolean;
|
||||
single_frame_trace_group_enabled: boolean;
|
||||
single_frame_trace_unassigned_enabled: boolean;
|
||||
single_trace_group_filter_enabled: boolean;
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 字段变更
|
||||
|
||||
| 旧字段 | 新字段 | 说明 |
|
||||
|--------|--------|------|
|
||||
| `min_size` | `min_bbox_size` | 重命名 |
|
||||
| `min_confidence` (0-100) | `min_confidence` (0.0-1.0) | 范围变更 |
|
||||
| - | `max_confidence` | 新增 |
|
||||
| - | `max_bbox_size` | 新增 |
|
||||
| - | `source` | 新增 |
|
||||
| - | `backend_status` | 新增 |
|
||||
|
||||
---
|
||||
|
||||
## 迁移步骤
|
||||
|
||||
### Step 1: 更新 TypeScript 类型定义
|
||||
|
||||
**文件:** `/Users/accusys/momentry_studio/src/types/faceFilter.ts`
|
||||
|
||||
**已完成:** ✅
|
||||
|
||||
- 创建新的类型定义
|
||||
- 提供 `FaceFilterSettingsMigration` 迁移工具类
|
||||
|
||||
### Step 2: 更新 Composable
|
||||
|
||||
**文件:** `/Users/accusys/momentry_studio/src/composables/useFaceFilter.ts`
|
||||
|
||||
**已完成:** ✅
|
||||
|
||||
**主要变更:**
|
||||
|
||||
1. **导入新类型:**
|
||||
```typescript
|
||||
import type {
|
||||
FaceFilterSettings,
|
||||
UiFilterRules,
|
||||
FileProfileResponse
|
||||
} from '@/types/faceFilter';
|
||||
import { FaceFilterSettingsMigration } from '@/types/faceFilter';
|
||||
```
|
||||
|
||||
2. **更新类型导出:**
|
||||
```typescript
|
||||
export type { UiFilterRules, FaceFilterSettings };
|
||||
```
|
||||
|
||||
3. **更新变量名:**
|
||||
- `singleFrameSettings` → `faceFilterSettings`
|
||||
- `singleFrameSettingsLoading` → `faceFilterSettingsLoading`
|
||||
- `singleFrameSettingsError` → `faceFilterSettingsError`
|
||||
- `singleFrameSettingsModified` → `faceFilterSettingsModified`
|
||||
|
||||
4. **更新函数签名:**
|
||||
```typescript
|
||||
// 旧版
|
||||
function quickFilter(faces: FaceMetadata[], rules: QuickFilterRules)
|
||||
|
||||
// 新版
|
||||
function quickFilter(faces: FaceMetadata[], rules: UiFilterRules)
|
||||
```
|
||||
|
||||
5. **更新 API 调用:**
|
||||
```typescript
|
||||
// 旧版
|
||||
async function updateFileProfile(fileUuid: string, faceFilter: Partial<SingleFrameFSSettings>)
|
||||
|
||||
// 新版
|
||||
async function updateFileProfile(fileUuid: string, faceFilter: Partial<FaceFilterSettings>)
|
||||
```
|
||||
|
||||
### Step 3: 更新 Vue 组件
|
||||
|
||||
**文件:** `/Users/accusys/momentry_studio/src/components/FaceFilterPanel.vue`
|
||||
|
||||
**已完成:** ✅
|
||||
|
||||
**主要变更:**
|
||||
|
||||
1. **更新导入:**
|
||||
```typescript
|
||||
// 旧版
|
||||
import { useFaceFilter, type QuickFilterRules } from '../composables/useFaceFilter';
|
||||
|
||||
// 新版
|
||||
import { useFaceFilter, type UiFilterRules } from '../composables/useFaceFilter';
|
||||
```
|
||||
|
||||
2. **更新变量名:**
|
||||
- 所有 `singleFrameSettings` → `faceFilterSettings`
|
||||
- 所有 `singleFrameSettingsLoading` → `faceFilterSettingsLoading`
|
||||
- 所有 `singleFrameSettingsError` → `faceFilterSettingsError`
|
||||
- 所有 `singleFrameSettingsModified` → `faceFilterSettingsModified`
|
||||
|
||||
---
|
||||
|
||||
## 向后兼容性
|
||||
|
||||
### 1. API 响应兼容
|
||||
|
||||
**Rust 端 (`from_legacy()` 方法):**
|
||||
|
||||
```rust
|
||||
pub fn from_legacy(
|
||||
legacy_min_confidence: f32,
|
||||
legacy_min_size: u32,
|
||||
trace_settings: Option<TraceSettings>
|
||||
) -> Self {
|
||||
// 自动转换 0-100 到 0.0-1.0
|
||||
let normalized_confidence = if legacy_min_confidence > 1.0 {
|
||||
legacy_min_confidence / 100.0
|
||||
} else {
|
||||
legacy_min_confidence
|
||||
};
|
||||
|
||||
Self {
|
||||
ui_filter_rules: UiFilterRules {
|
||||
min_confidence: normalized_confidence,
|
||||
min_bbox_size: legacy_min_size,
|
||||
...
|
||||
},
|
||||
processing_thresholds: ProcessingThresholds {
|
||||
min_confidence: normalized_confidence,
|
||||
min_bbox_size: legacy_min_size,
|
||||
...
|
||||
},
|
||||
trace_settings: trace_settings.unwrap_or_default(),
|
||||
// 向后兼容字段
|
||||
min_confidence: normalized_confidence,
|
||||
min_bbox_size: legacy_min_size,
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. TypeScript 端兼容
|
||||
|
||||
**`FaceFilterSettingsMigration` 类:**
|
||||
|
||||
```typescript
|
||||
export class FaceFilterSettingsMigration {
|
||||
static fromLegacy(legacy: LegacySettings): FaceFilterSettings {
|
||||
let minConf = legacy.min_confidence ?? 0.5;
|
||||
|
||||
// 自动转换范围
|
||||
if (minConf > 1.0) {
|
||||
minConf = minConf / 100;
|
||||
}
|
||||
|
||||
return {
|
||||
ui_filter_rules: { min_confidence: minConf, ... },
|
||||
processing_thresholds: { min_confidence: minConf, ... },
|
||||
trace_settings: { ... },
|
||||
// 向后兼容字段
|
||||
min_confidence: minConf,
|
||||
...
|
||||
};
|
||||
}
|
||||
|
||||
static defaults(): FaceFilterSettings {
|
||||
return {
|
||||
ui_filter_rules: { min_confidence: 0.5, min_bbox_size: 80 },
|
||||
processing_thresholds: { min_confidence: 0.5, min_bbox_size: 80 },
|
||||
trace_settings: {
|
||||
single_frame_trace_vlm_enabled: true,
|
||||
...
|
||||
},
|
||||
min_confidence: 0.5,
|
||||
min_bbox_size: 80,
|
||||
...
|
||||
};
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 测试验证
|
||||
|
||||
### 1. TypeScript 编译
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
**结果:** ✅ 通过
|
||||
|
||||
### 2. 功能测试
|
||||
|
||||
需要测试的功能点:
|
||||
|
||||
- [ ] 加载文件 profile，验证新结构
|
||||
- [ ] 保存 face filter settings
|
||||
- [ ] Auto-save 功能（500ms debounce）
|
||||
- [ ] UI 过滤规则应用
|
||||
- [ ] Trace 设置开关
|
||||
|
||||
### 3. API 兼容性测试
|
||||
|
||||
测试场景:
|
||||
1. Core API 返回新格式 → Studio 正常解析
|
||||
2. Core API 返回旧格式 → Studio 自动转换（`from_legacy()`）
|
||||
3. Studio 发送新格式 → Core API 正常处理
|
||||
|
||||
---
|
||||
|
||||
## 注意事项
|
||||
|
||||
### 1. Confidence 范围
|
||||
|
||||
**旧版:** 0-100 (整数)
|
||||
**新版:** 0.0-1.0 (浮点数)
|
||||
|
||||
**转换逻辑:**
|
||||
- 如果值 > 1.0，自动除以 100
|
||||
- Rust 和 TypeScript 端都有转换逻辑
|
||||
|
||||
### 2. 字段名变更
|
||||
|
||||
**`min_size` → `min_bbox_size`**
|
||||
|
||||
这个变更影响:
|
||||
- API 请求体
|
||||
- 数据库字段
|
||||
- 前端代码
|
||||
|
||||
**建议:** 使用向后兼容字段，避免破坏性变更
|
||||
|
||||
### 3. 三段式结构
|
||||
|
||||
新的三段式结构:
|
||||
- `ui_filter_rules` - UI 显示和交互
|
||||
- `processing_thresholds` - 后端处理配置
|
||||
- `trace_settings` - Trace 处理配置
|
||||
|
||||
**用途:**
|
||||
- 未来可扩展更多配置
|
||||
- 分离关注点
|
||||
- 更好的可维护性
|
||||
|
||||
---
|
||||
|
||||
## 待办事项
|
||||
|
||||
### P0 (必须完成)
|
||||
- [x] TypeScript 类型定义
|
||||
- [x] useFaceFilter composable 更新
|
||||
- [x] FaceFilterPanel.vue 更新
|
||||
- [x] TypeScript 编译验证
|
||||
|
||||
### P1 (推荐完成)
|
||||
- [ ] 完整功能测试
|
||||
- [ ] API 兼容性测试
|
||||
- [ ] 文档更新
|
||||
|
||||
### P2 (未来优化)
|
||||
- [ ] UI 组件优化（支持三段式结构）
|
||||
- [ ] 性能优化
|
||||
- [ ] 单元测试
|
||||
|
||||
---
|
||||
|
||||
## 相关文件
|
||||
|
||||
### Core API (Rust)
|
||||
- `/Users/accusys/momentry_core/src/core/file_profile.rs` - 数据结构定义
|
||||
- `/Users/accusys/momentry_core/src/api/identities.rs` - API 端点
|
||||
- `/Users/accusys/momentry_core/src/api/profile.rs` - Profile API
|
||||
|
||||
### Studio (TypeScript)
|
||||
- `/Users/accusys/momentry_studio/src/types/faceFilter.ts` - 类型定义
|
||||
- `/Users/accusys/momentry_studio/src/composables/useFaceFilter.ts` - Composable
|
||||
- `/Users/accusys/momentry_studio/src/components/FaceFilterPanel.vue` - UI 组件
|
||||
|
||||
---
|
||||
|
||||
## 联系方式
|
||||
|
||||
如有问题，请联系:
|
||||
- Core API Team: core@momentry.ai
|
||||
- Studio Team: studio@momentry.ai
|
||||
- Slack: #face-filter-migration
|
||||
|
||||
---
|
||||
|
||||
**最后更新:** 2026-10-09
|
||||
**文档版本:** v1.0
|
||||
Reference in New Issue
Block a user