docs(debug): archive resolved session - face-registration-failure
Root cause: detectFaces missing faceData field caused error 81929
Fix commit: 86e268a
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
106
.planning/debug/face-registration-failure.md
Normal file
106
.planning/debug/face-registration-failure.md
Normal file
@@ -0,0 +1,106 @@
|
|||||||
|
---
|
||||||
|
status: resolved
|
||||||
|
trigger: "点击注册人脸按钮时显示'特征提取失败'"
|
||||||
|
created: 2026-03-30T00:00:00Z
|
||||||
|
updated: 2026-03-30T00:30:00Z
|
||||||
|
resolved: 2026-03-30T00:30:00Z
|
||||||
|
commit: 86e268a
|
||||||
|
---
|
||||||
|
|
||||||
|
## Root Cause
|
||||||
|
`FaceEngineManager.convertFaceInfoToList` 未返回 `faceData` 字段，
|
||||||
|
导致 `extractFaceFeature` 调用时缺少虹软 SDK 必需的人脸数据，返回错误码 81929
|
||||||
|
|
||||||
|
## Fix
|
||||||
|
- FaceEngineManager.java: 添加 `map.put("faceData", faceInfo.getFaceData())`
|
||||||
|
- ArcPlugin.java: 接收并传递 `faceData` 参数
|
||||||
|
- Dart API: `extractFaceFeature` 添加 `faceData` 参数
|
||||||
|
|
||||||
|
## Verification
|
||||||
|
用户确认修复成功: 注册人脸显示"注册成功"
|
||||||
|
|
||||||
|
## Symptoms
|
||||||
|
expected: 人脸特征被提取并存储到本地，显示"注册成功"
|
||||||
|
actual: 显示"特征提取失败"
|
||||||
|
errors: 特征提取失败
|
||||||
|
reproduction: 1) 打开示例应用 2) 激活SDK 3) 初始化引擎 4) 开始人脸识别 5) 检测到人脸且活体检测通过 6) 点击"注册人脸"按钮 7) 显示"特征提取失败"
|
||||||
|
started: 一直存在，从未正常工作过
|
||||||
|
|
||||||
|
## Eliminated
|
||||||
|
<!-- APPEND only -->
|
||||||
|
|
||||||
|
- hypothesis: Flutter端读取人脸角度时使用了错误的key名"orient"
|
||||||
|
evidence: 修复key名后用户反馈仍然失败
|
||||||
|
timestamp: 2026-03-30T00:09:00Z
|
||||||
|
|
||||||
|
## Evidence
|
||||||
|
- timestamp: 2026-03-30T00:01:00Z
|
||||||
|
checked: FaceEngineManager.java convertFaceInfoToList方法 (第244-262行)
|
||||||
|
found: Android端返回的人脸信息Map包含key "faceOrientation" (第256行: map.put("faceOrientation", faceInfo.getOrient()))
|
||||||
|
implication: Flutter端应该使用"faceOrientation"作为key来读取人脸角度
|
||||||
|
|
||||||
|
- timestamp: 2026-03-30T00:02:00Z
|
||||||
|
checked: main.dart _registerFace方法 (第542行)
|
||||||
|
found: Flutter端使用错误的key "orient"读取人脸角度: faceOrientation: _currentFaceInfo!['orient'] as int? ?? 0
|
||||||
|
implication: 由于key不匹配，_currentFaceInfo!['orient']返回null，faceOrientation始终使用默认值0
|
||||||
|
|
||||||
|
- timestamp: 2026-03-30T00:03:00Z
|
||||||
|
checked: main.dart _verifyFace方法 (第607行)
|
||||||
|
found: 同样的问题: faceOrientation: _currentFaceInfo!['orient'] as int? ?? 0
|
||||||
|
implication: 验证功能也受此bug影响
|
||||||
|
|
||||||
|
- timestamp: 2026-03-30T00:09:00Z
|
||||||
|
checked: 用户反馈
|
||||||
|
found: 修复key名后仍然显示"特征提取失败"
|
||||||
|
implication: key名修复正确但不是根本原因，需要进一步调查SDK调用失败的真实原因
|
||||||
|
|
||||||
|
- timestamp: 2026-03-30T00:10:00Z
|
||||||
|
checked: arc.dart 和 arc_method_channel.dart API定义
|
||||||
|
found: extractFaceFeature方法有format参数且有默认值2050，Flutter端调用时不需要显式传递
|
||||||
|
implication: format参数问题不是根因
|
||||||
|
|
||||||
|
- timestamp: 2026-03-30T00:13:00Z
|
||||||
|
checked: FaceEngineManager.java convertFaceInfoToList方法
|
||||||
|
found: 返回的Map包含完整字段: rectLeft, rectTop, rectRight, rectBottom, faceOrientation, faceId
|
||||||
|
implication: 参数命名正确，需要查看SDK实际返回的错误码
|
||||||
|
|
||||||
|
- timestamp: 2026-03-30T00:14:00Z
|
||||||
|
checked: ArcPlugin.handleExtractFaceFeature方法原代码
|
||||||
|
found: 调用SDK时直接使用format参数，如果format为null会传递null值
|
||||||
|
implication: 可能导致SDK调用失败
|
||||||
|
|
||||||
|
- timestamp: 2026-03-30T00:15:00Z
|
||||||
|
checked: 添加详细日志后的代码
|
||||||
|
found: 1) format参数添加了null检查和默认值 2) 添加了所有参数的日志打印 3) Flutter端显示详细错误码
|
||||||
|
implication: 用户可以看到具体错误码，帮助定位真正原因
|
||||||
|
|
||||||
|
- timestamp: 2026-03-30T00:18:00Z
|
||||||
|
checked: 错误码 81929 (0x14009) = MERR_FSDK_FACEFEATURE_FACEDATA
|
||||||
|
found: 根据虹软文档，这个错误表示"人脸特征检测人脸信息错误"，意味着传入 extractFaceFeature 的 FaceInfo 中缺少必要的 faceData 字段
|
||||||
|
implication: 这是根本原因！虹软 SDK 需要 FaceInfo 中包含 detectFaces 返回的 faceData 字段才能进行特征提取
|
||||||
|
|
||||||
|
- timestamp: 2026-03-30T00:19:00Z
|
||||||
|
checked: FaceEngineManager.convertFaceInfoToList 方法
|
||||||
|
found: 该方法只返回了 rectLeft, rectTop, rectRight, rectBottom, faceOrientation, faceId，没有返回 faceData 字段
|
||||||
|
implication: faceData 字段缺失导致特征提取失败
|
||||||
|
|
||||||
|
- timestamp: 2026-03-30T00:20:00Z
|
||||||
|
checked: ArcPlugin.handleExtractFaceFeature 方法
|
||||||
|
found: 构建 FaceInfo 对象时只设置了 rect, orient, faceId，没有设置 faceData
|
||||||
|
implication: 传给 SDK 的 FaceInfo 对象缺少关键的 faceData 字段
|
||||||
|
|
||||||
|
- timestamp: 2026-03-30T00:22:00Z
|
||||||
|
checked: 虹软文档 FaceInfo 数据结构
|
||||||
|
found: FaceInfo 包含 byte[] faceData 字段，文档说明这是"人脸数据"，用于特征提取
|
||||||
|
implication: faceData 是 SDK 在人脸检测时生成的内部数据，特征提取时必须使用
|
||||||
|
|
||||||
|
- timestamp: 2026-03-30T00:25:00Z
|
||||||
|
checked: 修复后的代码
|
||||||
|
found: 1) FaceEngineManager.convertFaceInfoToList 添加了 faceData 字段返回 2) ArcPlugin.handleExtractFaceFeature 接收并设置 faceData 3) Flutter API 添加了 faceData 参数 4) 示例应用传递 faceData
|
||||||
|
implication: 修复完成，等待用户验证
|
||||||
|
|
||||||
|
## Resolution
|
||||||
|
root_cause: FaceEngineManager.convertFaceInfoToList 方法未返回 faceData 字段，导致 extractFaceFeature 调用时缺少虹软 SDK 必需的人脸数据。错误码 81929 (MERR_FSDK_FACEFEATURE_FACEDATA) 表明 FaceInfo 中缺少用于特征提取的关键数据。
|
||||||
|
fix: 1) FaceEngineManager.convertFaceInfoToList: 添加 faceData 字段到返回的 Map 中 2) ArcPlugin.handleExtractFaceFeature: 接收 faceData 参数并设置到 FaceInfo 对象 3) Flutter API (arc.dart, arc_platform_interface.dart, arc_method_channel.dart): 添加 faceData 参数 4) main.dart: 在调用 extractFaceFeature 时传递 faceData
|
||||||
|
verification: flutter analyze 通过（1个 info 级别警告）
|
||||||
|
files_changed: [android/src/main/java/com/xiarui/arc/FaceEngineManager.java, android/src/main/java/com/xiarui/arc/ArcPlugin.java, lib/arc.dart, lib/arc_platform_interface.dart, lib/arc_method_channel.dart, example/lib/main.dart, test/arc_test.dart]
|
||||||
Reference in New Issue
Block a user