momentry_studio/FACE_MOVE_DIAGNOSIS_REPORT.md

Face Move/Merge 功能诊断报告

日期: 2026-07-25 状态: 已完成显示文本改进，待验证数据流

---

✅ 已完成：显示文本改进

改进内容

修改前: F{trace_id}（如 F13） 修改后: Face{trace_id}（如 Face13）

修改位置

行号	位置	修改前	修改后
143	Face Detail Modal	file_uuid:F13	file_uuid:Face13
262	Cluster Strip Fallback	F13	Face13
264	Cluster Strip Label	F13 GroupName	Face13 GroupName

保留的位置

Line 105: Frame range 显示

<span>F{{ t.start_frame }}–{{ t.end_frame }}</span>

• 保持不变，因为这是 Frame 编号范围
• 示例：F2219–2225

---

🔍 数据流分析

理想数据流

Core API
  ↓
返回: trace_ids = [13, 14, 15]  (i64[])
  ↓
前端存储
  ↓
clusterTracesMap["13"] = {trace_id: 13, ...}
  ↓
用户选择
  ↓
selectedFaces.push("file_uuid:13")
  ↓
API 调用
  ↓
merge_trace(file_uuid, source_id=13, target_id=...)

---

关键检查点

检查点 1: 数据存储

代码位置: PeopleView.vue Line 914-920

clusterTracesMap.value = {}
for (const t of allTraces) {
  clusterTracesMap.value[String(t.trace_id)] = t
}

验证要点:

• ✅ t.trace_id 应该是 integer（如 13）
• ✅ String(t.trace_id) 应该是 "13"（不是 "Face13"）

---

检查点 2: 用户选择

代码位置: PeopleView.vue Line 1507-1515

function toggleFaceSelection(t: any) {
  const key = `${t.file_uuid}:${t.trace_id}`
  const idx = selectedFaces.value.indexOf(key)
  if (idx >= 0) {
    selectedFaces.value.splice(idx, 1)
  } else {
    selectedFaces.value.push(key)
  }
}

验证要点:

• ✅ t.trace_id 应该是 integer（如 13）
• ✅ key 应该是 "file_uuid:13"（不是 "file_uuid:Face13"）

---

检查点 3: API 调用

代码位置: PeopleView.vue Line 1810-1827

const traceList: { file_uuid: string; trace_id: number }[] = []
for (const key of selectedFaces.value) {
  const [file_uuid, trace_id] = key.split(':')
  traceList.push({ file_uuid, trace_id: parseInt(trace_id) })
}

for (const t of traceList) {
  await apiCall('merge_trace', { 
    file_uuid: t.file_uuid, 
    source_id: t.trace_id, 
    target_id: targetTraceId 
  })
}

验证要点:

• ✅ key.split(':') 应该得到 ["file_uuid", "13"]
• ✅ parseInt("13") 应该是 13（不是 NaN）
• ✅ API 参数应该正确

---

🧪 浏览器验证方案

方案 1: 检查 selectedFaces 格式

// 1. 打开 PeopleView 页面
// 2. 选择一个 Face（如 Face13）
// 3. 打开浏览器控制台，执行：

const app = document.querySelector('#app').__vueParentComponent
const peopleView = app.ctx.$root.$children[0]

// 检查 selectedFaces
console.log('=== selectedFaces 内容 ===')
console.log('selectedFaces:', peopleView.selectedFaces)
console.log('First key:', peopleView.selectedFaces[0])

// 检查 key 格式
const [file_uuid, trace_id_str] = peopleView.selectedFaces[0].split(':')
console.log('file_uuid:', file_uuid)
console.log('trace_id (string):', trace_id_str)
console.log('trace_id (parsed):', parseInt(trace_id_str))

// 预期结果：
// selectedFaces = ["84d838f260e1881a0daa55fabbc8e434:13"]
// trace_id (string) = "13"
// trace_id (parsed) = 13

---

方案 2: 检查数据源

// 检查 clusterTracesMap
console.log('=== clusterTracesMap ===')
console.log('Keys:', Object.keys(peopleView.clusterTracesMap))
const firstKey = Object.keys(peopleView.clusterTracesMap)[0]
console.log('First key:', firstKey)
console.log('Data:', peopleView.clusterTracesMap[firstKey])

// 检查 trace_id 类型
const trace = peopleView.clusterTracesMap[firstKey]
console.log('trace_id:', trace.trace_id, typeof trace.trace_id)

// 预期结果：
// Keys = ["13", "14", "15"]
// First key = "13"
// trace_id = 13 (number)

---

方案 3: 测试 Move 功能

// 1. 选择几个 Faces
// 2. 点击 Move 按钮
// 3. 选择目标 Group
// 4. 打开 Network 面板，观察请求

// 预期结果：
// URL: POST /api/v1/file/84d8.../trace/13/merge/142
// 参数正确，API 调用成功

---

📊 潜在问题假设

假设 1: 数据源错误

问题: Core API 返回的 trace_id 格式不正确

验证: 检查 Core API 响应

curl "http://localhost:3002/api/v1/file/84d838f260e1881a0daa55fabbc8e434/face-groups"

预期: trace_ids 应该是 [13, 14, 15]（integer array）

---

假设 2: 显示文本污染数据

问题: 显示文本 "Face13" 污染了数据层

验证: 检查 selectedFaces 内容

• 如果发现 "file_uuid:Face13"，说明数据被污染
• 应该改为 "file_uuid:13"

---

假设 3: 前端转换错误

问题: 前端某处错误地处理了 trace_id

验证: 检查所有 trace_id 相关代码

• 数据加载处
• 用户选择处
• API 调用处

---

✅ 已确认的正确实现

Core API 规格

Endpoint: POST /api/v1/file/:file_uuid/trace/:trace_id/merge/:target_trace_id

参数类型:

• file_uuid: string（无连字符）
• trace_id: integer
• target_trace_id: integer

示例:

POST /api/v1/file/c36f35685177c981aa139b66bbbccc5b/trace/142/merge/396

---

Face Group 数据结构

Endpoint: GET /api/v1/file/:file_uuid/face-groups

响应:

{
  "face_groups": [{
    "group_id": 1,
    "trace_ids": [13, 14, 15],  // i64[] - integer array
    "trace_count": 3,
    "representative_trace": 13
  }]
}

---

📝 下一步行动

立即执行

1. 浏览器验证: 使用上述验证方案检查 selectedFaces 格式
2. 数据流追踪: 如果发现问题，定位具体污染位置
3. API 测试: 测试 Move 功能是否正常工作

---

如果发现问题

1. 数据污染: 修复数据存储逻辑
2. API 参数错误: 修正 API 调用参数
3. 其他问题: 根据验证结果修复

---

📞 联系方式

Studio Team: 已完成显示文本改进 Core Team: 提供 API 规格确认

测试环境: http://localhost:5173 API 环境: http://localhost:3002

---

生成时间: 2026-07-25 状态: 显示改进已完成，等待数据流验证