# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Flutter 人脸识别插件，封装虹软 (ArcSoft) Face SDK，提供 Android 平台的人脸检测、识别、活体检测功能。

## Build Commands

```bash
# Analyze Dart code
flutter analyze

# Run Dart unit tests
flutter test

# Analyze example app
cd example && flutter analyze lib/main.dart

# Run example app on Android device
cd example && flutter run

# Build example APK
cd example && flutter build apk
```

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                      Flutter (Dart)                         │
│  ┌─────────────┐    ┌──────────────────┐                    │
│  │   arc.dart  │───▶│ ArcPlatform      │ (abstract)         │
│  │  (Public API)│    └────────┬─────────┘                    │
│  └─────────────┘             │                               │
│                    ┌────────▼─────────┐                      │
│                    │ MethodChannelArc │                      │
│                    │ (Method Channel)  │                      │
│                    └────────┬─────────┘                      │
└─────────────────────────────┼───────────────────────────────┘
                              │ Method Channel: "arc"
┌─────────────────────────────┼───────────────────────────────┐
│                      Android (Java)                         │
│                    ┌────────▼─────────┐                      │
│                    │   ArcPlugin      │                      │
│                    │ (Method Handler) │                      │
│                    └────────┬─────────┘                      │
│                    ┌────────▼─────────┐                      │
│                    │ FaceEngineManager│ (Singleton)          │
│                    └────────┬─────────┘                      │
│                    ┌────────▼─────────┐                      │
│                    │  ArcSoft SDK     │                      │
│                    │ (arcsoft_face.jar)│                      │
│                    └──────────────────┘                      │
└─────────────────────────────────────────────────────────────┘
```

## Key Files

| Layer | File | Purpose |
|-------|------|---------|
| Public API | `lib/arc.dart` | 用户调用的主要接口 |
| Platform Interface | `lib/arc_platform_interface.dart` | 平台抽象接口定义 |
| Method Channel | `lib/arc_method_channel.dart` | Flutter 与原生通信 |
| Android Plugin | `android/src/.../ArcPlugin.java` | 处理 Method Channel 调用 |
| Engine Manager | `android/src/.../FaceEngineManager.java` | 虹软 SDK 单例管理 |
| Data Model | `android/src/.../FaceInfo.java` | 人脸信息数据模型 |
| Error Codes | `android/src/.../FaceErrorCode.java` | 586个错误码枚举 |

## Adding New API

1. **Dart Interface**: Add method to `arc_platform_interface.dart`
2. **Dart Implementation**: Add method to `arc_method_channel.dart`
3. **Public API**: Expose method in `arc.dart`
4. **Android Handler**: Add case in `ArcPlugin.java` `onMethodCall()`
5. **Android Logic**: Add method in `FaceEngineManager.java`

## ArcSoft SDK Configuration

SDK 需要三个密钥（从虹软控制台获取）:
- `appId`: 应用 ID
- `sdkKey`: SDK 密钥
- `activeKey`: 激活密钥

## API Methods

| Method | Purpose |
|--------|---------|
| `activeOnline()` | 在线激活 SDK |
| `init()` | 初始化人脸识别引擎 |
| `detectFaces()` | 人脸检测 + RGB 活体检测 |
| `extractFaceFeature()` | 提取人脸特征 (512字节) |
| `compareFaceFeature()` | 1:1 特征比对，返回相似度 |
| `registerFaceFeature()` | 注册特征到人脸库 (1:N) |

## Thresholds (Recommended by ArcSoft)

| 功能 | 阈值 |
|------|------|
| 人脸比对 (生活照) | 0.8 |
| 人脸比对 (证件照) | 0.82 |
| RGB 活体检测 | 0.5 |
| IR 活体检测 | 0.5 |

## Combined Mask Values

```java
ASF_FACE_DETECT     = 0x00000001  // 人脸检测
ASF_FACE_RECOGNITION= 0x00000004  // 人脸识别
ASF_AGE            = 0x00000008  // 年龄检测
ASF_GENDER         = 0x00000010  // 性别检测
ASF_LIVENESS       = 0x00000080  // RGB 活体检测
// 组合: 0x9D = 人脸检测 + 识别 + 年龄 + 性别 + 活体
```

## Image Format

- 格式: NV21 (Android camera default)
- 格式代码: 2050
- 宽度必须是4的倍数，高度必须是2的倍数