feat(example): 添加人脸注册按钮和ID显示功能

- 添加注册按钮,点击生成随机人脸ID(格式:F + 8位数字)
- 实时显示检测到的人脸对应的ID
- 使用彩色标签区分已注册(绿色)和未注册(橙色)状态

Quick task: 260330-ld1
This commit is contained in:
2026-03-30 15:28:31 +08:00
parent 3c2bb02e33
commit 184c3a9f16
9 changed files with 1099 additions and 0 deletions

163
.planning/phase-1/PLAN.md Normal file
View File

@@ -0,0 +1,163 @@
# 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单张
```java
int registerFaceFeature(FaceFeatureInfo faceFeatureInfo)
```
**参数说明:**
| 参数 | 类型 | 描述 |
|------|------|------|
| faceFeatureInfo | FaceFeatureInfo | 人脸搜索信息 |
**FaceFeatureInfo 结构:**
- `searchId` - 唯一标识符
- `featureData` - 人脸特征数据
- `faceTag` - 附属信息(可选)
**返回值:** 成功返回 `ErrorInfo.MOK`0
### registerFaceFeature批量
```java
int registerFaceFeature(List<FaceFeatureInfo> faceFeatureInfoList)
```
---
## 实现任务
### Task 1: FaceEngineManager.java 新增人脸注册方法
**文件:** `android/src/main/java/com/xiarui/arc/FaceEngineManager.java`
**新增方法:**
```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. 实现处理方法:
```java
private void handleRegisterFaceFeature(MethodCall call, Result result)
private void handleRegisterFaceFeatureBatch(MethodCall call, Result result)
```
### Task 3: Flutter层API暴露
**文件:** `lib/arc.dart`
**新增方法:**
```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`