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

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

Quick task: 260330-ld1

.planning/PROJECT.md

@@ -0,0 +1,38 @@
+# ArcSoft Face Recognition Plugin
+
+## What This Is
+
+Flutter 人脸识别插件，基于 ArcSoft SDK 实现 Android 平台的人脸检测和识别功能。
+
+## Core Value
+
+提供简单易用的 Flutter 人脸识别 API，封装 ArcSoft SDK 的复杂性。
+
+## Requirements
+
+### Validated
+
+- ✓ 人脸检测 - existing
+- ✓ 人脸特征提取 - existing
+- ✓ 活体检测 - existing
+
+### Active
+
+- [ ] 在 example 应用中添加人脸注册功能
+- [ ] 显示检测到的人脸 ID
+
+### Out of Scope
+
+- iOS 平台支持 — 当前仅 Android
+
+## Context
+
+Flutter 插件项目，使用 Method Channel 与 Android 原生层通信。
+
+## Constraints
+
+- **Platform**: Android only (minSdk 24+)
+- **SDK**: ArcSoft Face Recognition SDK
+
+---
+*Last updated: 2026-03-30 after initialization*

.planning/REQUIREMENTS.md

@@ -0,0 +1,30 @@
+# Requirements: ArcSoft Face Recognition Plugin
+
+**Defined:** 2026-03-30
+**Core Value:** 提供简单易用的 Flutter 人脸识别 API
+
+## v1 Requirements
+
+### Example App Enhancements
+
+- [ ] **EXAM-01**: 用户可以在预览页面看到注册按钮
+- [ ] **EXAM-02**: 点击注册按钮可以注册检测到的人脸，使用随机 ID
+- [ ] **EXAM-03**: 预览页面显示检测到的人脸对应的 ID
+
+## Out of Scope
+
+| Feature | Reason |
+|---------|--------|
+| iOS support | Current scope is Android only |
+| Persistent storage | Demo functionality only |
+
+## Traceability
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| EXAM-01 | Quick Task | Pending |
+| EXAM-02 | Quick Task | Pending |
+| EXAM-03 | Quick Task | Pending |
+
+---
+*Requirements defined: 2026-03-30*

.planning/ROADMAP.md

@@ -0,0 +1,21 @@
+# Roadmap: ArcSoft Face Recognition Plugin
+
+**Created:** 2026-03-30
+**Milestone:** v0.1.0 - Example App Enhancement
+
+## Phase 1: Example App Enhancement
+
+**Goal:** 在 example 应用中添加人脸注册和 ID 显示功能
+
+### Requirements Covered
+- EXAM-01: 注册按钮
+- EXAM-02: 注册功能（随机 ID）
+- EXAM-03: 显示人脸 ID
+
+### Success Criteria
+1. 用户可以在预览页面看到注册按钮
+2. 点击注册后生成随机 ID 并显示
+3. 检测到的人脸显示对应 ID
+
+---
+*Roadmap created: 2026-03-30*

.planning/STATE.md

@@ -0,0 +1,27 @@
+# Project State
+
+**Project:** ArcSoft Face Recognition Plugin
+**Last activity:** 2026-03-30 - Initialized project
+
+## Current Phase
+
+**Phase:** 1 - Example App Enhancement
+**Status:** Ready to start
+**Started:** Not yet
+
+### Progress
+
+| Metric | Value |
+|--------|-------|
+| Requirements | 3 active |
+| Phases | 1 total |
+| Progress | 0% |
+
+### Quick Tasks Completed
+
+| # | Description | Date | Commit | Directory |
+|---|-------------|------|--------|-----------|
+| 260330-ld1 | 在example的人脸识别预览页面增加注册按钮和人脸ID显示 | 2026-03-30 | - | [260330-ld1-example-id-id](./quick/260330-ld1-example-id-id/) |
+
+---
+*State initialized: 2026-03-30*

.planning/config.json

@@ -0,0 +1,13 @@
+{
+  "mode": "yolo",
+  "granularity": "standard",
+  "parallelization": true,
+  "commit_docs": true,
+  "model_profile": "balanced",
+  "workflow": {
+    "research": false,
+    "plan_check": false,
+    "verifier": false,
+    "nyquist_validation": false
+  }
+}

.planning/phase-1/PLAN.md

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

.planning/quick/260330-ld1-example-id-id/260330-ld1-PLAN.md

@@ -0,0 +1,27 @@
+# Quick Task 260330-ld1: Example App 人脸注册功能
+
+## Task Description
+在example的人脸识别预览页面增加一个注册按钮，id使用随机数。同时预览页面应该显示检测到的人脸对应的id。
+
+## Files to Modify
+- `example/lib/main.dart` - 添加注册按钮和人脸ID显示
+
+## Tasks
+
+### Task 1: 添加人脸ID存储和随机生成逻辑
+- **file**: `example/lib/main.dart`
+- **action**: 添加 `Map<int, String>` 存储人脸ID映射，添加随机ID生成函数
+- **verify**: 编译通过
+
+### Task 2: 添加注册按钮和ID显示UI
+- **file**: `example/lib/main.dart`
+- **action**: 在底部信息区域添加注册按钮，显示检测到的人脸ID列表
+- **verify**: UI 正确显示，按钮可点击
+
+### Task 3: 实现注册功能
+- **file**: `example/lib/main.dart`
+- **action**: 点击注册按钮为当前检测到的人脸生成随机ID并存储，更新UI显示
+- **verify**: 注册后显示随机生成的ID
+
+---
+*Plan created: 2026-03-30*

.planning/quick/260330-ld1-example-id-id/260330-ld1-SUMMARY.md

@@ -0,0 +1,32 @@
+# Quick Task 260330-ld1: Summary
+
+## Task
+在example的人脸识别预览页面增加一个注册按钮，id使用随机数。同时预览页面应该显示检测到的人脸对应的id。
+
+## Changes Made
+
+### `example/lib/main.dart`
+1. **添加导入**: `dart:math` 用于生成随机ID
+2. **添加状态变量**:
+   - `_faceIdMap`: 存储人脸特征到ID的映射
+   - `_currentFaceIds`: 当前帧检测到的人脸ID列表
+   - `_random`: 随机数生成器
+3. **添加方法**:
+   - `_generateRandomFaceId()`: 生成格式为 `F + 8位随机数字` 的人脸ID
+   - `_getFaceKey()`: 根据人脸矩形区域生成特征标识
+4. **更新检测逻辑**: 在检测到人脸时更新 `_currentFaceIds` 列表
+5. **更新UI**:
+   - 添加人脸ID显示区域（使用彩色标签区分已注册/未注册状态）
+   - 添加注册按钮（点击为未注册人脸生成随机ID）
+
+## How It Works
+1. 摄像头实时检测人脸
+2. 检测到的人脸初始显示为"未注册"（橙色标签）
+3. 用户点击"注册人脸"按钮
+4. 为所有未注册的人脸生成随机ID（绿色标签显示）
+
+## Verification
+- `flutter analyze lib/main.dart` - No issues found
+
+---
+*Completed: 2026-03-30*