docs: map existing codebase
This commit is contained in:
158
.planning/codebase/INTEGRATIONS.md
Normal file
158
.planning/codebase/INTEGRATIONS.md
Normal file
@@ -0,0 +1,158 @@
|
||||
# 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*
|
||||
Reference in New Issue
Block a user