arc/.planning/phase-1/PLAN.md

Phase 1: 新增虹软人脸注册接口

目标

在Android端新增虹软SDK的1:N人脸注册功能，支持单张和批量注册人脸特征到人脸库，供后续人脸搜索使用。

背景

现有代码结构

Flutter层 (lib/arc.dart)
    ↓ MethodChannel
Android插件层 (ArcPlugin.java)
    ↓
人脸引擎管理 (FaceEngineManager.java)
    ↓
虹软SDK (FaceEngine)

已实现功能

• ✅ activeOnline - SDK在线激活
• ✅ init - 引擎初始化
• ✅ detectFaces - 人脸检测 + RGB活体
• ✅ extractFaceFeature - 特征提取
• ✅ compareFaceFeature - 1:1特征比对

待实现功能

• ❌ registerFaceFeature - 注册人脸到1:N库
• ❌ 批量注册支持

---

虹软SDK接口说明

根据虹软文档（docs/虹软人脸识别接口文档.md）：

registerFaceFeature（单张）

int registerFaceFeature(FaceFeatureInfo faceFeatureInfo)

参数说明：

参数	类型	描述
faceFeatureInfo	FaceFeatureInfo	人脸搜索信息

FaceFeatureInfo 结构：

• searchId - 唯一标识符
• featureData - 人脸特征数据
• faceTag - 附属信息（可选）

返回值： 成功返回 ErrorInfo.MOK（0）

registerFaceFeature（批量）

int registerFaceFeature(List<FaceFeatureInfo> faceFeatureInfoList)

---

实现任务

Task 1: FaceEngineManager.java 新增人脸注册方法

文件： android/src/main/java/com/xiarui/arc/FaceEngineManager.java

新增方法：

/**
 * 注册单张人脸特征到人脸库
 * @param searchId 唯一标识符（用于后续搜索匹配）
 * @param featureData 人脸特征数据（从extractFaceFeature获取）
 * @param faceTag 附属信息（可选，如用户名、员工ID等）
 * @return 错误码（0表示成功）
 */
public int registerFaceFeature(int searchId, byte[] featureData, String faceTag)

/**
 * 批量注册人脸特征到人脸库
 * @param faceInfoList 人脸信息列表，每项包含searchId、featureData、faceTag
 * @return 错误码（0表示成功）
 */
public int registerFaceFeatureBatch(List<Map<String, Object>> faceInfoList)

Task 2: ArcPlugin.java 新增MethodChannel处理

文件： android/src/main/java/com/xiarui/arc/ArcPlugin.java

新增处理：

1. 在 onMethodCall 的 switch 中添加：

   • registerFaceFeature - 单张注册
   • registerFaceFeatureBatch - 批量注册

2. 实现处理方法：

private void handleRegisterFaceFeature(MethodCall call, Result result)
private void handleRegisterFaceFeatureBatch(MethodCall call, Result result)

Task 3: Flutter层API暴露

文件： lib/arc.dart

新增方法：

/// 注册单张人脸特征到人脸库
/// [searchId] 唯一标识符（用于后续搜索匹配）
/// [featureData] 人脸特征数据（从extractFaceFeature获取）
/// [faceTag] 附属信息（可选）
/// 返回包含 success, errorCode, message 的 Map
Future<Map<String, dynamic>?> registerFaceFeature({
  required int searchId,
  required Uint8List featureData,
  String? faceTag,
})

/// 批量注册人脸特征到人脸库
/// [faceList] 人脸列表，每项包含 searchId, featureData, faceTag(可选)
/// 返回包含 success, errorCode, message 的 Map
Future<Map<String, dynamic>?> registerFaceFeatureBatch({
  required List<Map<String, dynamic>> faceList,
})

Task 4: 更新 arc_method_channel.dart

文件： lib/arc_method_channel.dart

新增对应的 MethodChannel 调用实现。

---

验收标准

1. ✅ 单张人脸注册成功后，可通过 searchId 在人脸库中找到对应特征
2. ✅ 批量注册支持一次注册多张人脸
3. ✅ 重复 searchId 注册时返回适当的错误提示（虹软SDK会忽略重复）
4. ✅ 参数校验：searchId 有效、featureData 非空
5. ✅ Flutter层可正常调用并获取返回结果
6. ✅ 代码包含完整的方法级注释

---

注意事项

1. 重复注册：根据虹软文档，如果底库中已存在相同 searchId，SDK会忽略。如需更新，需调用 updateFaceFeature 接口。

2. 引擎初始化：人脸注册功能需要引擎初始化时包含 ASF_FACE_RECOGNITION 属性（当前默认掩码 0x85 已包含）。

3. 特征数据来源：featureData 需要通过 extractFaceFeature 接口获取，且建议使用 extractType=0（REGISTER模式）提取的特征。

4. 人脸库规模：虹软推荐人脸库在1万以内效果更佳。

---

依赖文件

• 虹软SDK: android/libs/arcsoft_face.jar
• 错误码定义: android/src/main/java/com/xiarui/arc/FaceErrorCode.java
• 接口文档: docs/虹软人脸识别接口文档.md