warren/momentry_core
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases 2 Wiki Activity

cleanup: remove dead code and duplicate docs

Browse Source 
- Remove session-ses_2f27.md (161KB raw session log)
- Remove 49 ROOT_* duplicate files across REFERENCE/
- Remove 14 duplicate files between REFERENCE/ root and history/
- Remove asr_legacy.rs (dead code, replaced by asr.rs)
- Remove src/core/worker/ (duplicate JobWorker)
- Remove src/core/layers/ (empty directory)
- Remove 4 .bak files in src/
- Remove 7 dead private methods in worker/processor.rs
- Remove backup directory from git tracking
This commit is contained in:
Warren
2026-05-04 01:31:21 +08:00
parent ee81e343ce
commit e75c4d6f07
3270 changed files with 35190 additions and 53367 deletions
Download Patch File Download Diff File Expand all files Collapse all files

442
docs_v1.0/API/PEOPLE_API_MARCOM_MAPPING.md
View File

@@ -1,442 +0,0 @@
# People API 设计方案 (marcom 需求等效映射)
**日期**: 2026-04-28
**状态**: 设计阶段
**目的**: 根据 marcom 团队需求，在符合现有架构的前提下提供等效 API
---
## 设计原则
1. **遵循 RESTful 规范**: 使用标准 HTTP 方法 (GET, POST, PATCH, DELETE)
2. **统一路径前缀**: `/api/v1/people`
3. **响应格式统一**: `{ success: bool, message: string, data: any }`
4. **向后兼容**: 现有 API 保持不变，新 API 扩展功能
5. **符合 Identity 系统**: 与 `identities` 表和 `identity_bindings` 表集成
---
## API 对照表
### 1. GET /people/candidates (候选人物)
**marcom 需求**: 获取待确认的人物候选列表
**等效 API**:
```
GET /api/v1/people/candidates?file_uuid={uuid}&limit={n}
```
**功能**:
- 返回待确认的人物身份候选
- 包含 face cluster、speaker cluster 的匹配建议
- 状态: `pending`, `suggested`, `unmatched`
**响应示例**:
```json
{
"success": true,
"message": "Found 15 candidates",
"data": {
"candidates": [
{
"candidate_id": "face_cluster_1",
"type": "face",
"suggested_identity": {
"id": 123,
"name": "张曼玉",
"confidence": 0.92
},
"appearance_count": 45,
"status": "pending"
}
],
"total": 15
}
}
```
**实现**: 扩展现有 `/api/v1/people/suggest`
---
### 2. GET /people (人物列表)
**marcom 需求**: 获取所有人物列表
**等效 API**:
```
GET /api/v1/people?file_uuid={uuid}&limit={n}&offset={n}&status={status}
```
**功能**:
- 返回人物身份列表
- 支持按 file_uuid 筛选
- 支持分页
- 支持按状态筛选 (confirmed, pending, all)
**响应示例**:
```json
{
"success": true,
"message": "Found 8 persons",
"data": {
"persons": [
{
"identity_id": "Person_17",
"name": "张曼玉",
"appearance_count": 45,
"total_duration": 350.2,
"is_confirmed": true
}
],
"total": 8
}
}
```
**实现**: 现有 `/api/v1/people/list` 已支持
---
### 3. GET /people/{identity_id} (人物详情)
**marcom 需求**: 获取人物详情
**等效 API**:
```
GET /api/v1/people/{identity_id}?file_uuid={uuid}
```
**功能**:
- 返回人物详细信息
- 包含出场时间线
- 包含关联的 face/speaker
- 包含缩略图
**响应示例**:
```json
{
"success": true,
"data": {
"identity_id": "Person_17",
"name": "张曼玉",
"face_identity_id": 123,
"speaker_id": "SPEAKER_00",
"appearance_count": 45,
"total_duration": 350.2,
"first_appearance_time": 10.5,
"last_appearance_time": 360.2,
"timeline": [...],
"thumbnails": [...]
}
}
```
**实现**: 现有 `/api/v1/people/:person_id` 已支持
---
### 4. POST /people (创建人物)
**marcom 需求**: 手动创建新人物
**等效 API**:
```
POST /api/v1/people
Body: { "name": "张曼玉", "file_uuid": "xxx", "metadata": {...} }
```
**功能**:
- 创建新人物身份
- 关联到指定视频
- 支持添加 metadata (角色名、演员名等)
**响应示例**:
```json
{
"success": true,
"message": "Person created",
"data": {
"identity_id": "Person_99",
"name": "张曼玉",
"file_uuid": "xxx"
}
}
```
**实现**: 需新增，参考 `CreatePersonIdentityRequest`
---
### 5. PATCH /people/{identity_id} (更新人物)
**marcom 需求**: 更新人物信息
**等效 API**:
```
PATCH /api/v1/people/{identity_id}
Body: { "name": "新名字", "is_confirmed": true, "metadata": {...} }
```
**功能**:
- 更新人物名称
- 确认人物身份
- 更新 metadata
**实现**: 现有 `/api/v1/people/:person_id` (PATCH) 已支持
---
### 6. POST /people/merge (合并人物)
**marcom 需求**: 合并多个人物为一个
**等效 API**:
```
POST /api/v1/people/merge
Body: {
"target_identity_id": "Person_17",
"source_identity_ids": ["Person_18", "Person_19"]
}
```
**功能**:
- 合并多个人物身份
- 转移所有出场记录
- 更新统计数据
**实现**: 现有 `/api/v1/people/merge` 已支持
---
### 7. POST /people/skip (跳过人物)
**marcom 需求**: 跳过某个候选人物（不处理）
**等效 API**:
```
POST /api/v1/people/skip
Body: { "candidate_id": "face_cluster_2", "reason": "非人物" }
```
**功能**:
- 标记候选为"已跳过"
- 记录跳过原因
- 不创建人物身份
**响应示例**:
```json
{
"success": true,
"message": "Candidate skipped",
"data": {
"candidate_id": "face_cluster_2",
"status": "skipped",
"reason": "非人物"
}
}
```
**实现**: 需新增，扩展候选管理功能
---
### 8. POST /people/{identity_id}/remove-face (移除人脸)
**marcom 需求**: 从人物身份中移除特定人脸绑定
**等效 API**:
```
POST /api/v1/people/{identity_id}/unbind
Body: { "binding_type": "face", "binding_value": "face_123" }
```
**功能**:
- 解绑人脸与人物身份的关联
- 人脸回到候选状态
- 更新人物出场统计
**响应示例**:
```json
{
"success": true,
"message": "Face unbound",
"data": {
"identity_id": "Person_17",
"unbound_face": "face_123",
"updated_appearance_count": 42
}
}
```
**实现**: 需新增，参考现有 `UnbindIdentityRequest`
---
### 9. POST /people/split-face (分离人脸)
**marcom 需求**: 将人脸从现有人物分离为新人物
**等效 API**:
```
POST /api/v1/people/split
Body: {
"source_identity_id": "Person_17",
"face_ids": ["face_123", "face_124"],
"new_identity_name": "新人物"
}
```
**功能**:
- 从现有人物分离指定人脸
- 创建新人物身份
- 转移出场记录
**实现**: 现有 `/api/v1/people/:person_id/split` 部分支持
---
### 10. GET /people/{identity_id}/resolve (解决冲突)
**marcom 需求**: 获取人物的冲突/歧义信息
**等效 API**:
```
GET /api/v1/people/{identity_id}/conflicts
```
**功能**:
- 返回人物身份的潜在冲突
- 显示相似人脸/声音的匹配
- 提供解决方案建议
**响应示例**:
```json
{
"success": true,
"data": {
"identity_id": "Person_17",
"conflicts": [
{
"type": "similar_face",
"conflicting_identity": "Person_18",
"similarity": 0.85,
"suggestion": "merge"
}
],
"resolution_options": ["merge", "keep_separate", "skip"]
}
}
```
**实现**: 需新增
---
### 11. POST /search (搜索)
**marcom 需求**: 搜索人物
**等效 API**:
```
POST /api/v1/people/search
Body: {
"query": "张",
"filters": { "type": "people", "file_uuid": "xxx" },
"limit": 20
}
```
**功能**:
- 搜索人物身份
- 支持按名称、类型、视频筛选
- 返回匹配结果
**实现**: 现有 `/api/v1/identities/search` 已支持，建议扩展
---
### 12. GET /people/status (人物状态)
**marcom 需求**: 获取人物处理状态统计
**等效 API**:
```
GET /api/v1/people/status?file_uuid={uuid}
```
**功能**:
- 返回人物处理统计
- 待确认数量、已确认数量、跳过数量
- 合并历史
**响应示例**:
```json
{
"success": true,
"data": {
"file_uuid": "xxx",
"total_candidates": 15,
"confirmed": 8,
"pending": 5,
"skipped": 2,
"merge_count": 3,
"split_count": 1
}
}
```
**实现**: 需新增
---
## 实现优先级
| 优先级 | API | 状态 | 预估工时 |
|--------|-----|------|----------|
| **P0** | GET /people | ✅ 已有 | 0h |
| **P0** | GET /people/{identity_id} | ✅ 已有 | 0h |
| **P0** | PATCH /people/{identity_id} | ✅ 已有 | 0h |
| **P0** | POST /people/merge | ✅ 已有 | 0h |
| **P1** | GET /people/candidates | ⚠️ 扩展 | 2h |
| **P1** | POST /people | ❌ 新增 | 2h |
| **P1** | POST /people/search | ⚠️ 扩展 | 1h |
| **P2** | POST /people/skip | ❌ 新增 | 2h |
| **P2** | POST /people/{identity_id}/unbind | ❌ 新增 | 2h |
| **P2** | POST /people/split | ⚠️ 扩展 | 1h |
| **P2** | GET /people/{identity_id}/conflicts | ❌ 新增 | 3h |
| **P2** | GET /people/status | ❌ 新增 | 2h |
**总预估**: ~13h (P1+P2)
---
## 数据库表需求
现有表结构支持大部分需求，可能需要扩展：
```sql
-- 建议新增: candidates 表 (候选管理)
CREATE TABLE person_candidates (
id BIGSERIAL PRIMARY KEY,
file_uuid VARCHAR(36) NOT NULL,
candidate_type VARCHAR(20), -- 'face', 'speaker'
candidate_id VARCHAR(50), -- 'face_cluster_1', 'speaker_2'
suggested_identity_id BIGINT,
confidence FLOAT,
status VARCHAR(20), -- 'pending', 'confirmed', 'skipped'
skip_reason TEXT,
created_at TIMESTAMP,
updated_at TIMESTAMP
);
```
---
## 参考文档
- `docs_v1.0/ARCHITECTURE/MOMENTRY_CORE_ARCHITECTURE_V2.md` - Identity 系统设计
- `docs_v1.0/ARCHITECTURE/PERSON_IDENTITY_INTEGRATION.md` - Person Identity 整合
- `src/api/person_identity.rs` - 现有 API 实现
- `src/api/identity_binding.rs` - 身份绑定 API