From 6423eeed77997406508f6dea1117bc66e9e788f6 Mon Sep 17 00:00:00 2001 From: Momentry Studio Date: Fri, 9 Oct 2026 15:13:50 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=9B=B4=E6=96=B0=20FaceFilterSettings?= =?UTF-8?q?=20TypeScript=20=E7=B1=BB=E5=9E=8B=E5=AE=9A=E4=B9=89=E4=B8=BA?= =?UTF-8?q?=E4=B8=89=E6=AE=B5=E5=BC=8F=E7=BB=9F=E4=B8=80=E7=BB=93=E6=9E=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 变更内容： - 创建 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 --- docs/FACE_FILTER_SETTINGS_MIGRATION_GUIDE.md | 367 +++++++++++++++++++ src/components/FaceFilterPanel.vue | 28 +- src/composables/useFaceFilter.ts | 279 +++++++------- src/types/faceFilter.ts | 198 ++++++++++ 4 files changed, 702 insertions(+), 170 deletions(-) create mode 100644 docs/FACE_FILTER_SETTINGS_MIGRATION_GUIDE.md create mode 100644 src/types/faceFilter.ts diff --git a/docs/FACE_FILTER_SETTINGS_MIGRATION_GUIDE.md b/docs/FACE_FILTER_SETTINGS_MIGRATION_GUIDE.md new file mode 100644 index 0000000..6eaa4ec --- /dev/null +++ b/docs/FACE_FILTER_SETTINGS_MIGRATION_GUIDE.md @@ -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) + +// 新版 +async function updateFileProfile(fileUuid: string, faceFilter: Partial) +``` + +### 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 +) -> 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 \ No newline at end of file diff --git a/src/components/FaceFilterPanel.vue b/src/components/FaceFilterPanel.vue index 4eb45c2..1bed999 100644 --- a/src/components/FaceFilterPanel.vue +++ b/src/components/FaceFilterPanel.vue @@ -108,7 +108,7 @@