From fe851528df62a8f325baabcf2d99ad88abc3e5bd Mon Sep 17 00:00:00 2001 From: leon <916117771@qq.com> Date: Mon, 30 Mar 2026 16:58:54 +0800 Subject: [PATCH] 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 --- .planning/debug/face-registration-failure.md | 106 +++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 .planning/debug/face-registration-failure.md diff --git a/.planning/debug/face-registration-failure.md b/.planning/debug/face-registration-failure.md new file mode 100644 index 0000000..0832043 --- /dev/null +++ b/.planning/debug/face-registration-failure.md @@ -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 + + +- 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] \ No newline at end of file