# SI-M1 Face SDK 接口文档

本文列出 SDK 对业务层推荐使用的公开 API。命名空间统一为 `Aisu.SIM1.Face.*`。

## 1. 命名空间

| 命名空间 | 说明 |
|---|---|
| `Aisu.SIM1.Face.Core` | Manager、配置、回调适配、日志、主线程调度 |
| `Aisu.SIM1.Face.Commands` | 业务服务、命令服务、加密接口 |
| `Aisu.SIM1.Face.Protocol` | 协议枚举、封包、拆包、编码工具 |
| `Aisu.SIM1.Face.Transport` | 通信接口、串口、Mock |
| `Aisu.SIM1.Face.Models` | Reply、Note、用户、验证、录入、图片、UVC 等模型 |

## 2. FaceModuleManager

`FaceModuleManager` 是 SDK 推荐的统一入口。

```csharp
using Aisu.SIM1.Face.Core;
```

### 属性

| 属性 | 类型 | 说明 |
|---|---|---|
| `Basic` | `FaceBasicService` | 基础命令服务 |
| `Verify` | `FaceVerifyService` | 人脸验证服务 |
| `Enrollment` | `FaceEnrollmentService` | 人脸录入服务 |
| `Users` | `FaceUserService` | 用户管理服务 |
| `QrCode` | `FaceQrCodeService` | 二维码服务 |
| `Images` | `FaceImageService` | 图片抓拍与照片注册服务 |
| `Features` | `FaceFeatureService` | 特征读写服务 |
| `Uvc` | `FaceUvcService` | UVC 和高级参数服务 |
| `Encryption` | `FaceEncryptionService` | 加密相关服务 |
| `Callback` | `FaceModuleCallbackAdapter` | 回调式 API 适配 |
| `IsOpen` | `bool` | 通信是否打开 |
| `IsReady` | `bool` | 是否收到 READY |
| `CurrentStatus` | `FaceModuleStatus` | 当前模组状态 |
| `LastError` | `string` | 最近错误文本 |
| `CurrentCommand` | `string` | 当前命令名 |
| `Config` | `FaceModuleConfig` | 当前运行配置 |
| `Settings` | `FaceSdkSettings` | 当前绑定配置资产 |

### 方法

| 方法 | 说明 |
|---|---|
| `ConfigureTransport(IFaceModuleTransport transport)` | 注入自定义通信层 |
| `Configure(bool useMockInEditor, string portName, int baudRate)` | 兼容旧代码的快速配置入口 |
| `ApplySettings(FaceSdkSettings sdkSettings)` | 应用 ScriptableObject 配置并重建 transport |
| `Open()` | 打开通信 |
| `Close()` | 关闭通信 |
| `WaitReadyAsync(int timeoutMs = 5000)` | 等待 READY NOTE |
| `ProbeReadyByStatusAsync()` | 主动查询状态并标记 READY |
| `SendRawBytes(byte[] bytes)` | 发送原始协议 bytes |
| `RefreshStatus()` | 异步刷新 `CurrentStatus` |

### 事件

| 事件 | 说明 |
|---|---|
| `OnReady` | 首次 READY |
| `OnStatusChanged(FaceModuleStatus)` | 当前状态变化 |
| `OnReplyReceived(FaceReply)` | 收到 REPLY 包 |
| `OnNoteReceived(FaceNote)` | 收到 NOTE 包 |
| `OnFaceStateUpdated(FaceFaceStateNote)` | 收到人脸状态 NOTE |
| `OnQrCodeReceived(string)` | 收到二维码 NOTE |
| `OnFeatureReceived(byte[])` | 收到读取特征数据包 |
| `OnDataPacketReceived(FacePacket)` | 收到 ImageOrTemplate 数据包 |
| `OnError(FaceResultCode, string)` | 错误上报 |
| `OnRawLog(string)` | 原始 TX / RX 日志 |

## 3. 基础服务 FaceBasicService

访问路径：

```csharp
manager.Basic
```

| 方法 | 返回 | 说明 |
|---|---|---|
| `ResetAsync()` | `Task<FaceReply>` | 复位模组 |
| `FaceResetAsync()` | `Task<FaceReply>` | 取消当前人脸流程 |
| `GetStatusAsync()` | `Task<FaceModuleStatus>` | 获取模组状态 |
| `GetVersionAsync()` | `Task<string>` | 获取固件版本 |
| `GetSnAsync()` | `Task<string>` | 获取设备序列号 |
| `SetDemoModeAsync(bool enable)` | `Task<FaceReply>` | 设置 Demo Mode |
| `UpgradeFirmwareAsync()` | `Task<FaceReply>` | 启动固件升级命令 |

## 4. 验证服务 FaceVerifyService

访问路径：

```csharp
manager.Verify
```

| 方法 | 返回 | 说明 |
|---|---|---|
| `VerifyAsync(byte timeout, byte maxRecognitionTimes = 30)` | `Task<FaceVerifyResult>` | 单次人脸验证 |
| `AutoVerifyAsync(bool enable, byte timeout)` | `Task<FaceVerifyResult>` | 启用或关闭自动验证 |

## 5. 录入服务 FaceEnrollmentService

访问路径：

```csharp
manager.Enrollment
```

| 方法 | 返回 | 说明 |
|---|---|---|
| `EnrollAsync(bool admin, string userName, FaceDirection direction, byte timeout)` | `Task<FaceEnrollResult>` | 交互式多方向录入 |
| `EnrollSingleAsync(bool admin, string userName, byte timeout)` | `Task<FaceEnrollResult>` | 单帧录入 |
| `EnrollIntegratedAsync(bool admin, string userName, FaceDirection direction, byte timeout, bool singleFrame = false, bool duplicateCheck = true)` | `Task<FaceEnrollResult>` | 集成式录入 |
| `EnrollSnapFaceImageAsync(bool admin, string userName)` | `Task<FaceEnrollResult>` | 抓拍人脸后注册 |

## 6. 用户服务 FaceUserService

访问路径：

```csharp
manager.Users
```

| 方法 | 返回 | 说明 |
|---|---|---|
| `DeleteUserAsync(int userId)` | `Task<FaceReply>` | 删除指定用户 |
| `DeleteAllAsync()` | `Task<FaceReply>` | 删除全部用户 |
| `GetUserInfoAsync(int userId)` | `Task<FaceUserInfo>` | 查询用户信息 |
| `GetAllUserIdsAsync()` | `Task<List<int>>` | 查询用户 ID 列表 |
| `GetAllUserIds2Async()` | `Task<List<int>>` | 使用扩展命令查询用户 ID 列表 |
| `GetAllUserInfosAsync()` | `Task<List<FaceUserInfo>>` | 查询全部用户详情 |
| `GetAllUserInfos2Async()` | `Task<List<FaceUserInfo>>` | 使用扩展命令查询全部用户详情 |

## 7. 二维码服务 FaceQrCodeService

访问路径：

```csharp
manager.QrCode
```

| 方法 | 返回 | 说明 |
|---|---|---|
| `ScanQrCodeAsync(byte timeout)` | `Task<string>` | 扫描二维码并返回内容 |

## 8. 图片服务 FaceImageService

访问路径：

```csharp
manager.Images
```

| 方法 | 返回 | 说明 |
|---|---|---|
| `SnapUploadImageAsync()` | `Task<FaceImageResult>` | 抓拍普通图片 |
| `SnapUploadFaceImageAsync()` | `Task<FaceImageResult>` | 抓拍人脸图片 |
| `SnapUploadLargeImageAsync(ImageDpi dpi)` | `Task<FaceImageResult>` | 抓拍大图 |
| `EnrollWithPhotoAsync(byte[] photoBytes, BioType type, string userName = null, bool duplicateCheck = true, Action<int, int> onProgress = null)` | `Task<FaceEnrollResult>` | 照片注册 |
| `EnrollWithPhotoAndIdAsync(int userId, byte[] photoBytes, BioType type, string userName = null, bool duplicateCheck = true, Action<int, int> onProgress = null)` | `Task<FaceEnrollResult>` | 指定用户 ID 照片注册 |

## 9. 特征服务 FaceFeatureService

访问路径：

```csharp
manager.Features
```

| 方法 | 返回 | 说明 |
|---|---|---|
| `ReadFeatureAsync(int userId, FeatureType type)` | `Task<byte[]>` | 读取指定用户特征 |
| `WriteFeatureAsync(byte[] featureBytes, FeatureType type, string userName = null, Action<int, int> onProgress = null)` | `Task<FaceEnrollResult>` | 写入特征并注册 |

## 10. UVC 和高级参数 FaceUvcService

访问路径：

```csharp
manager.Uvc
```

| 方法 | 返回 | 说明 |
|---|---|---|
| `ReadUsbUvcParametersAsync()` | `Task<UsbUvcParameters>` | 读取 USB / UVC 参数 |
| `SetUsbUvcParametersAsync(UsbUvcParameters parameters)` | `Task<FaceReply>` | 设置 USB / UVC 参数 |
| `SetFaceLocationDisplayAsync(bool visible)` | `Task<FaceReply>` | 设置人脸框显示 |
| `SetRgbLevelAsync(byte level)` | `Task<FaceReply>` | 设置 RGB 阈值 |
| `SetDuplicateCheckAsync(bool enableCheck)` | `Task<FaceReply>` | 设置查重 |
| `ReadDuplicateCheckAsync()` | `Task<bool>` | 读取查重状态 |

## 11. 加密服务 FaceEncryptionService

访问路径：

```csharp
manager.Encryption
```

| 方法 | 返回 | 说明 |
|---|---|---|
| `SetReleaseEncryptionKeyAsync(byte[] key16)` | `Task<FaceReply>` | 设置 Release 加密密钥 |
| `SetDebugEncryptionKeyAsync(byte[] key16)` | `Task<FaceReply>` | 设置 Debug 加密密钥 |
| `InitEncryptionAsync(byte[] seed4, byte mode)` | `Task<FaceReply>` | 初始化加密流程 |
| `EnableEncryption(IFaceModuleCrypto crypto)` | `void` | 设置本地加密算法适配器 |
| `DisableEncryption()` | `void` | 关闭本地加密算法适配器 |

`IFaceModuleCrypto`：

```csharp
public interface IFaceModuleCrypto
{
    byte[] Encrypt(byte[] plainBytes);
    byte[] Decrypt(byte[] encryptedBytes);
    byte[] GenerateSessionKey(byte[] seed4, byte[] encKey16);
}
```

## 12. 回调式 API

`FaceModuleManager.Callback` 适合 Unity Button、旧项目回调风格或不方便使用 `await` 的业务。

```csharp
manager.Callback.Verify(
    timeout: 10,
    success: result => Debug.Log(result.UserId),
    error: message => Debug.LogError(message));
```

回调特点：

- 所有 API 统一使用 `success` 和 `error`。
- 照片注册、特征写入支持 `progress(current, total)`。
- 回调会通过 `FaceModuleMainThreadDispatcher` 回到 Unity 主线程。

## 13. 主要模型

| 类型 | 说明 |
|---|---|
| `FaceReply` | REPLY 包解析结果 |
| `FaceNote` | NOTE 包解析结果 |
| `FaceFaceStateNote` | 人脸状态 NOTE |
| `FaceUserInfo` | 用户 ID、姓名、管理员标记 |
| `FaceVerifyResult` | 验证结果、用户信息、开锁状态 |
| `FaceEnrollResult` | 录入结果、用户 ID、方向 |
| `FaceImageResult` | 图片 bytes、Texture2D、用户 ID |
| `UsbUvcParameters` | USB / UVC 参数 |
| `FaceCommandException` | 命令 REPLY 非成功时抛出的异常 |

## 14. 协议和通信底层

业务层通常不需要直接使用底层 API。需要协议调试或自定义通信时可使用：

| 类型 | 说明 |
|---|---|
| `FacePacketBuilder` | 封包 |
| `FacePacketParser` | 拆包 |
| `FaceProtocolEncoding` | 用户名、ID、结果文本等编码工具 |
| `IFaceModuleTransport` | 通信接口 |
| `SerialPortTransport` | 串口实现 |
| `MockFaceModuleTransport` | Mock 实现 |