docs: face_detections deprecation plan - analysis and future migration
Analysis Results: - 12 PostgreSQL fallback functions (TKG builders) - 11 API modules with direct queries - Identity binding: critical dependency Current Status: - Cannot deprecate now (Production stability) - PostgreSQL fallback necessary - Qdrant collection empty (0 points) Recommendations: - Keep PostgreSQL fallback for safety - Document migration path - New features use Qdrant/TKG - Gradual migration in future (6+ months) Migration Priority: - P1: identity_binding.rs (TKG-based) - P2: identity_agent_api.rs - P3: identity_api.rs - P4: Other APIs Conclusion: face_detections cannot be deprecated yet due to: - Production Qdrant empty - API dependencies (identity binding) - Stability requirements Status: Draft (no immediate deprecation)
This commit is contained in:
Accusys
189
docs_v1.0/DESIGN/FACE_DETECTIONS_DEPRECATION_PLAN.md
Normal file
189
docs_v1.0/DESIGN/FACE_DETECTIONS_DEPRECATION_PLAN.md
Normal file
@@ -0,0 +1,189 @@
|
||||
---
|
||||
title: face_detections Table Deprecation Plan
|
||||
version: 1.0
|
||||
date: 2026-06-21
|
||||
author: OpenCode
|
||||
status: Draft
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
`face_detections` 表在 TKG Phase 0-2.7 迁移后，大部分功能已迁移到 Qdrant。本文档规划后续 deprecation 策略。
|
||||
|
||||
## Current Usage Analysis
|
||||
|
||||
### TKG Builders (PostgreSQL Fallback)
|
||||
|
||||
**状态**: 可保留作为 fallback
|
||||
|
||||
| Function | 用途 | 状态 |
|
||||
|----------|------|------|
|
||||
| `build_face_trace_nodes_from_pg()` | Fallback | ⚠️ 保留 |
|
||||
| `build_gaze_trace_nodes_from_pg()` | Fallback | ⚠️ 保留 |
|
||||
| `build_lip_trace_nodes_from_pg()` | Fallback | ⚠️ 保留 |
|
||||
| `build_co_occurrence_edges_from_pg()` | Fallback | ⚠️ 保留 |
|
||||
| `build_face_face_edges_from_pg()` | Fallback | ⚠️ 保留 |
|
||||
| `build_speaker_face_edges_from_pg()` | Fallback | ⚠️ 保留 |
|
||||
|
||||
**总计**: 12 fallback functions
|
||||
|
||||
**建议**: 保留 PostgreSQL fallback，作为 Qdrant 失败时的备用方案。
|
||||
|
||||
### API Endpoints (Direct Queries)
|
||||
|
||||
**状态**: 需要迁移或保留
|
||||
|
||||
| Module | 功能 | 依赖程度 | 迁移难度 |
|
||||
|--------|------|---------|----------|
|
||||
| `files.rs` | 文件处理 | 高 | 中等 |
|
||||
| `five_w1h_agent_api.rs` | Five W1H agent | 中 | 低 |
|
||||
| `identities.rs` | Identity 管理 | 高 | 高 |
|
||||
| `identity_agent_api.rs` | Identity Agent | 高 | 高 |
|
||||
| `identity_api.rs` | Identity API | 高 | 高 |
|
||||
| `identity_binding.rs` | Face binding | **非常高** | **非常高** |
|
||||
| `media_api.rs` | Media API | 中 | 中 |
|
||||
| `scan.rs` | Scan 功能 | 低 | 低 |
|
||||
| `tmdb_api.rs` | TMDb API | 中 | 中 |
|
||||
| `trace_agent_api.rs` | Trace Agent | 高 | 中 |
|
||||
|
||||
**总计**: 11 modules with direct queries
|
||||
|
||||
**关键依赖**:
|
||||
- **Identity binding**: 使用 `face_detections.trace_id` 进行 face binding
|
||||
- **Identity Agent**: 使用 `face_detections.trace_id` 进行 identity matching
|
||||
|
||||
### Identity Binding Dependencies
|
||||
|
||||
**最关键依赖**: `src/api/identity_binding.rs`
|
||||
|
||||
**用途**:
|
||||
- `bind_identity_trace()`: 绑定 identity 到 trace_id
|
||||
- `unbind_identity()`: 解绑 identity
|
||||
- Face ↔ Identity mapping
|
||||
|
||||
**现状**:
|
||||
- Phase 2.3 已迁移到 TKG nodes properties
|
||||
- 但 identity binding API 仍使用 face_detections 查询
|
||||
|
||||
**迁移方案**:
|
||||
1. 查询 TKG nodes by identity_id
|
||||
2. 更新 TKG nodes properties
|
||||
3. 移除 face_detections 查询
|
||||
|
||||
## Deprecation Strategy
|
||||
|
||||
### Phase A: Documentation (Immediate)
|
||||
|
||||
- [x] 标记 `face_detections` 为 deprecated (in docs)
|
||||
- [x] 文档说明迁移路径
|
||||
- [x] 保留 PostgreSQL fallback
|
||||
|
||||
### Phase B: Gradual Migration (Future)
|
||||
|
||||
**优先级**:
|
||||
|
||||
| Priority | Module | Migration | Timeline |
|
||||
|----------|--------|-----------|----------|
|
||||
| P1 | identity_binding.rs | TKG-based binding | TBD |
|
||||
| P2 | identity_agent_api.rs | TKG-based matching | TBD |
|
||||
| P3 | identity_api.rs | TKG queries | TBD |
|
||||
| P4 | Other APIs | Case-by-case | TBD |
|
||||
|
||||
### Phase C: Removal (Long-term)
|
||||
|
||||
**条件**:
|
||||
- 所有 API endpoints 迁移完成
|
||||
- TKG-only architecture 完全稳定
|
||||
- 经过充分测试验证
|
||||
|
||||
**时间**: TBD (至少 6 个月后)
|
||||
|
||||
## Current Status
|
||||
|
||||
### What We Can Deprecate Now
|
||||
|
||||
**Nothing**: 所有功能仍有 PostgreSQL fallback 或 API dependencies
|
||||
|
||||
**原因**:
|
||||
1. Production Qdrant collection 为空 (0 points)
|
||||
2. PostgreSQL fallback 是必要的安全机制
|
||||
3. Identity binding APIs 依赖 face_detections
|
||||
|
||||
### What We Keep
|
||||
|
||||
- ✅ PostgreSQL fallback functions
|
||||
- ✅ face_detections table
|
||||
- ✅ populate_face_detections_from_face_json (Phase 0)
|
||||
|
||||
### What We Document
|
||||
|
||||
- ⚠️ face_detections deprecated (but still used)
|
||||
- ⚠️ New features should use Qdrant/TKG
|
||||
- ⚠️ Migration path documented
|
||||
|
||||
## Recommendations
|
||||
|
||||
### Immediate Actions
|
||||
|
||||
1. **标记为 deprecated**: 在 AGENTS.md 中说明
|
||||
2. **文档迁移路径**: 记录 TKG-based alternatives
|
||||
3. **保留 fallback**: 确保 Production 稳定性
|
||||
|
||||
### Short-term Actions
|
||||
|
||||
1. **测试新视频**: 注册新视频验证 Qdrant-based
|
||||
2. **监控 Production**: 观察 PostgreSQL fallback 使用率
|
||||
3. **性能对比**: Qdrant vs PostgreSQL
|
||||
|
||||
### Long-term Actions
|
||||
|
||||
1. **API migration**: 逐步迁移 identity binding APIs
|
||||
2. **数据迁移**: 批量迁移现有数据到 Qdrant
|
||||
3. **最终移除**: 在验证完成后移除 face_detections
|
||||
|
||||
## Migration Path for Identity Binding
|
||||
|
||||
### Current Implementation
|
||||
|
||||
```rust
|
||||
// identity_binding.rs
|
||||
let trace_id = sqlx::query_scalar(
|
||||
"SELECT trace_id FROM face_detections WHERE ..."
|
||||
)
|
||||
```
|
||||
|
||||
### Future Implementation (TKG-based)
|
||||
|
||||
```rust
|
||||
// Query TKG nodes with identity_id
|
||||
let nodes = sqlx::query_as(
|
||||
"SELECT id, external_id FROM tkg_nodes
|
||||
WHERE file_uuid=$1 AND node_type='face_trace'
|
||||
AND properties->>'identity_id' IS NOT NULL"
|
||||
)
|
||||
```
|
||||
|
||||
**优势**:
|
||||
- 无需 face_detections
|
||||
- TKG-only architecture
|
||||
- 性能更好 (TKG nodes 缓存)
|
||||
|
||||
## Conclusion
|
||||
|
||||
**当前**: face_detections **不能** deprecated
|
||||
- PostgreSQL fallback 必要
|
||||
- API endpoints 仍有依赖
|
||||
- Production 稳定性优先
|
||||
|
||||
**未来**: 逐步迁移到 TKG-only
|
||||
- 按优先级迁移 API endpoints
|
||||
- 验证后考虑移除 face_detections
|
||||
- 至少 6 个月后评估
|
||||
|
||||
**建议**: 保持现状，文档化迁移路径，新功能使用 Qdrant/TKG。
|
||||
|
||||
---
|
||||
|
||||
**状态**: Draft (不执行 deprecation)
|
||||
**原因**: Production 稳定性 + API dependencies
|
||||
**下一步**: 文档化 + 测试新视频
|
||||
Reference in New Issue
Block a user