# 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`