# 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
