# External Integrations

**Analysis Date:** 2026-03-30

## APIs & External Services

**人脸识别 SDK:**
- 虹软 (ArcSoft) 人脸识别 SDK - 离线人脸检测、特征提取、活体检测
  - SDK 库: `arcsoft_face.jar`, `libarcsoft_face.so`
  - 版本: 基于 2024年1月版本
  - Auth: 需要 AppId、SdkKey、ActiveKey（从虹软开放平台获取）
  - 激活方式: 在线激活（`FaceEngine.activeOnline()`）
  - 官方文档: https://ai.arcsoft.com.cn

**图像处理工具:**
- 虹软图像处理工具库 - 图像格式转换和处理
  - SDK 库: `arcsoft_image_util.jar`, `libarcsoft_image_util.so`

## Data Storage

**Databases:**
- 无数据库集成 - 人脸特征数据存储在内存中（人脸库）

**Face Feature Database (In-Memory):**
- 人脸库存储: 通过 `FaceEngine.registerFaceFeature()` 注册到 SDK 内部内存
- 数据结构: `FaceFeatureInfo(searchId, featureData, faceTag)`
- 搜索能力: 1:N 人脸搜索（SDK 内置）
- 注意: 人脸库数据在引擎释放后丢失，不持久化

**File Storage:**
- 虹软 SDK 激活文件存储于设备本地（SDK 自动管理）
- 位置: Android 设备内部存储（SDK 控制）

**Caching:**
- None - 无缓存层

## Authentication & Identity

**Auth Provider:**
- 虹软 SDK 激活机制 - 设备绑定激活
  - Implementation: 在线激活验证 AppId + SdkKey + ActiveKey
  - 激活文件: 设备指纹绑定，单设备单激活
  - 错误处理: `FaceErrorCode` 枚举定义完整错误码映射

**激活状态检查:**
```dart
// 激活成功条件: errorCode == 0 或 errorCode == 90114 (已激活)
result['success'] = errorCode == 0 || errorCode == 90114;
```

**激活流程:**
1. 调用 `Arc.activeOnline(appId, sdkKey, activeKey)`
2. Flutter MethodChannel 传递参数到 Android
3. Android 调用 `FaceEngine.activeOnline(context, activeKey, appId, sdkKey)`
4. SDK 与虹软服务器验证并生成激活文件
5. 返回激活结果 Map

## Monitoring & Observability

**Error Tracking:**
- 错误码枚举系统 - `FaceErrorCode.java`（完整错误码映射）
- 分类: 通用错误、SDK基础错误、人脸识别错误、激活错误、网络错误、离线授权错误

**Logs:**
- Android Logcat 输出（`FaceEngineManager.java` 使用 `android.util.Log`）
- Flutter debugPrint 输出（示例应用）
- 日志级别: Info, Error

**关键日志点:**
- SDK 初始化结果: `FaceEngineManager.init()`
- 人脸检测结果: `FaceEngineManager.detectFaces()`
- RGB 活体检测结果: `FaceEngineManager.getLiveness()`
- 特征提取结果: `FaceEngineManager.extractFaceFeature()`
- 人脸比对结果: `FaceEngineManager.compareFaceFeature()`

## CI/CD & Deployment

**Hosting:**
- 本地 Flutter 插件包 - 不发布到 pub.dev（私有包）
- `publish_to: 'none'`（示例应用）

**CI Pipeline:**
- None - 无 CI 配置文件

**Build Commands:**
```bash
flutter pub get          # 获取依赖
flutter test             # 运行 Flutter 单元测试
flutter build apk        # 构建 Android APK
cd android && ./gradlew test  # 运行 Android 单元测试
```

## Environment Configuration

**Required env vars (SDK 激活):**
- AppId: 虹软开放平台申请的应用 ID
- SdkKey: 虹软开放平台申请的 SDK 密钥
- ActiveKey: 激活密钥（可选，部分场景需要）

**示例应用配置（硬编码）:**
```dart
// example/lib/main.dart
final String _appId = '4nPFuS2TYAQh9werHL2qbKjtTH9nnoixk7G6yqSUyjVH';
final String _sdkKey = 'aWMTT3coxNQFETg9f3BGHCiBznAApXmcHFF3J5yQbsZ';
final String _activeKey = 'NEAT7AU4KLCEK682';
```

**Secrets location:**
- 当前: 硬编码在示例应用（不推荐生产使用）
- 建议: 通过环境变量或安全存储传递

## Webhooks & Callbacks

**Incoming:**
- None - 无外部 webhook

**Outgoing:**
- None - 无外部 API 调用（SDK 激活除外）

## Flutter-Native Communication

**Method Channel:**
- Channel 名称: `'arc'`
- 定义文件: `lib/arc_method_channel.dart`
- 实现: `MethodChannelArc` 类

**支持的方法:**
| 方法名 | 功能 | 参数 |
|--------|------|------|
| `getPlatformVersion` | 获取平台版本 | 无 |
| `activeOnline` | SDK 在线激活 | appId, sdkKey, activeKey |
| `init` | 初始化人脸引擎 | detectMode, orient, maxFaceNum, combinedMask |
| `detectFaces` | 人脸检测+RGB活体 | data, width, height, format |
| `extractFaceFeature` | 特征提取 | data, width, height, rect, faceId, extractType, mask |
| `compareFaceFeature` | 特征比对 | featureData1, featureData2, compareModel |
| `registerFaceFeature` | 单张人脸注册 | searchId, featureData, faceTag |
| `registerFaceFeatureBatch` | 批量人脸注册 | faceList |

**数据格式:**
- 图像数据: NV21 格式（`Uint8List`）
- 特征数据: SDK 定义长度（`Uint8List`）
- 返回值: `Map<String, dynamic>` 格式统一

## Image Format Requirements

**NV21 格式约束:**
- 图像宽度必须是 4 的倍数
- 图像高度必须是 2 的倍数（NV21 格式）
- 格式码: 2050 (`FaceEngine.CP_PAF_NV21`)

**Camera Integration (Example):**
- 使用 `camera` 插件获取摄像头图像流
- `ImageFormatGroup.nv21` 设置图像格式
- `CameraPreviewScreen` 处理实时图像流检测

---

*Integration audit: 2026-03-30*