# SDK API 参考

English documentation: [SDK_API_Reference.md](SDK_API_Reference.md).

本文列出 `xin.aisu.si-m1.face` 对外公开的业务层 API。公开包为 DLL-only 形式，不包含 SDK 源码。

## 命名空间

| 命名空间 | 说明 |
|---|---|
| `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 等模型 |

## FaceModuleManager

推荐使用 `FaceModuleManager` 作为统一入口：

```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)` | 收到图片或模板数据包 |
| `OnError(FaceResultCode, string)` | 错误上报 |
| `OnRawLog(string)` | 原始 TX/RX 日志 |

## 异步服务 API

### FaceBasicService

访问路径：`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>` | 启动固件升级命令 |

### FaceVerifyService

访问路径：`manager.Verify`

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

### FaceEnrollmentService

访问路径：`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>` | 抓拍人脸后注册 |

### FaceUserService

访问路径：`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>>` | 使用扩展命令查询全部用户信息 |

### FaceQrCodeService

访问路径：`manager.QrCode`

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

### FaceImageService

访问路径：`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 照片注册 |

### FaceFeatureService

访问路径：`manager.Features`

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

### FaceUvcService

访问路径：`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>` | 读取查重状态 |

### FaceEncryptionService

访问路径：`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` | 关闭本地加密算法适配器 |

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

## 回调式 API

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

回调规则：

- 成功时调用 `success`。
- 失败时调用 `error` 并传入错误信息。
- 照片注册和特征写入支持 `progress(current, total)`。
- 回调会通过 `FaceModuleMainThreadDispatcher` 回到 Unity 主线程。

### 生命周期与通信

| 方法 | 成功回调 | 说明 |
|---|---|---|
| `ConfigureTransport(IFaceModuleTransport transport, Action success, Action<string> error)` | `Action` | 注入自定义通信层 |
| `Configure(bool useMockInEditor, string portName, int baudRate, Action success, Action<string> error)` | `Action` | 配置默认通信参数 |
| `Open(Action success, Action<string> error)` | `Action` | 打开通信 |
| `Close(Action success, Action<string> error)` | `Action` | 关闭通信 |
| `SendRawBytes(byte[] bytes, Action success, Action<string> error)` | `Action` | 发送原始 bytes |
| `WaitReady(int timeoutMs, Action success, Action<string> error)` | `Action` | 等待 READY |
| `ProbeReadyByStatus(Action<FaceModuleStatus> success, Action<string> error)` | `Action<FaceModuleStatus>` | 主动探测状态并标记 READY |

### 基础命令

| 方法 | 成功回调 | 说明 |
|---|---|---|
| `Reset(Action<FaceReply> success, Action<string> error)` | `Action<FaceReply>` | 复位模组 |
| `FaceReset(Action<FaceReply> success, Action<string> error)` | `Action<FaceReply>` | 取消当前人脸流程 |
| `GetStatus(Action<FaceModuleStatus> success, Action<string> error)` | `Action<FaceModuleStatus>` | 获取模组状态 |
| `GetVersion(Action<string> success, Action<string> error)` | `Action<string>` | 获取固件版本 |
| `GetSn(Action<string> success, Action<string> error)` | `Action<string>` | 获取设备序列号 |
| `SetDemoMode(bool enable, Action<FaceReply> success, Action<string> error)` | `Action<FaceReply>` | 设置 Demo Mode |
| `UpgradeFirmware(Action<FaceReply> success, Action<string> error)` | `Action<FaceReply>` | 启动固件升级 |

### 验证与录入

| 方法 | 成功回调 | 说明 |
|---|---|---|
| `Verify(byte timeout, Action<FaceVerifyResult> success, Action<string> error, byte maxRecognitionTimes = 30)` | `Action<FaceVerifyResult>` | 人脸验证 |
| `AutoVerify(bool enable, byte timeout, Action<FaceVerifyResult> success, Action<string> error)` | `Action<FaceVerifyResult>` | 启用或关闭自动验证 |
| `Enroll(bool admin, string userName, FaceDirection direction, byte timeout, Action<FaceEnrollResult> success, Action<string> error)` | `Action<FaceEnrollResult>` | 交互式录入 |
| `EnrollSingle(bool admin, string userName, byte timeout, Action<FaceEnrollResult> success, Action<string> error)` | `Action<FaceEnrollResult>` | 单帧录入 |
| `EnrollIntegrated(bool admin, string userName, FaceDirection direction, byte timeout, bool singleFrame, bool duplicateCheck, Action<FaceEnrollResult> success, Action<string> error)` | `Action<FaceEnrollResult>` | 集成式录入 |
| `EnrollSnapFaceImage(bool admin, string userName, Action<FaceEnrollResult> success, Action<string> error)` | `Action<FaceEnrollResult>` | 抓拍人脸后注册 |

### 用户管理

| 方法 | 成功回调 | 说明 |
|---|---|---|
| `DeleteUser(int userId, Action<FaceReply> success, Action<string> error)` | `Action<FaceReply>` | 删除指定用户 |
| `DeleteAll(Action<FaceReply> success, Action<string> error)` | `Action<FaceReply>` | 删除全部用户 |
| `GetUserInfo(int userId, Action<FaceUserInfo> success, Action<string> error)` | `Action<FaceUserInfo>` | 查询指定用户 |
| `GetAllUserIds(Action<List<int>> success, Action<string> error)` | `Action<List<int>>` | 查询全部用户 ID |
| `GetAllUserIds2(Action<List<int>> success, Action<string> error)` | `Action<List<int>>` | 使用扩展命令查询全部用户 ID |
| `GetAllUserInfos(Action<List<FaceUserInfo>> success, Action<string> error)` | `Action<List<FaceUserInfo>>` | 查询全部用户信息 |
| `GetAllUserInfos2(Action<List<FaceUserInfo>> success, Action<string> error)` | `Action<List<FaceUserInfo>>` | 使用扩展命令查询全部用户信息 |

### 二维码、图片与特征

| 方法 | 成功回调 | 说明 |
|---|---|---|
| `ScanQrCode(byte timeout, Action<string> success, Action<string> error)` | `Action<string>` | 扫描二维码 |
| `SnapUploadImage(Action<FaceImageResult> success, Action<string> error)` | `Action<FaceImageResult>` | 抓拍普通图片 |
| `SnapUploadFaceImage(Action<FaceImageResult> success, Action<string> error)` | `Action<FaceImageResult>` | 抓拍人脸图片 |
| `SnapUploadLargeImage(ImageDpi dpi, Action<FaceImageResult> success, Action<string> error)` | `Action<FaceImageResult>` | 抓拍大图 |
| `EnrollWithPhoto(byte[] photoBytes, BioType type, string userName, bool duplicateCheck, Action<FaceEnrollResult> success, Action<string> error, Action<int, int> progress = null)` | `Action<FaceEnrollResult>` | 照片注册 |
| `EnrollWithPhotoAndId(int userId, byte[] photoBytes, BioType type, string userName, bool duplicateCheck, Action<FaceEnrollResult> success, Action<string> error, Action<int, int> progress = null)` | `Action<FaceEnrollResult>` | 指定用户 ID 照片注册 |
| `ReadFeature(int userId, FeatureType type, Action<byte[]> success, Action<string> error)` | `Action<byte[]>` | 读取用户特征 |
| `WriteFeature(byte[] featureBytes, FeatureType type, string userName, Action<FaceEnrollResult> success, Action<string> error, Action<int, int> progress = null)` | `Action<FaceEnrollResult>` | 写入特征并注册 |

### UVC 与加密

| 方法 | 成功回调 | 说明 |
|---|---|---|
| `ReadUsbUvcParameters(Action<UsbUvcParameters> success, Action<string> error)` | `Action<UsbUvcParameters>` | 读取 USB/UVC 参数 |
| `SetUsbUvcParameters(UsbUvcParameters parameters, Action<FaceReply> success, Action<string> error)` | `Action<FaceReply>` | 设置 USB/UVC 参数 |
| `SetFaceLocationDisplay(bool visible, Action<FaceReply> success, Action<string> error)` | `Action<FaceReply>` | 设置人脸框显示 |
| `SetRgbLevel(byte level, Action<FaceReply> success, Action<string> error)` | `Action<FaceReply>` | 设置 RGB 等级 |
| `SetDuplicateCheck(bool enableCheck, Action<FaceReply> success, Action<string> error)` | `Action<FaceReply>` | 设置查重 |
| `ReadDuplicateCheck(Action<bool> success, Action<string> error)` | `Action<bool>` | 读取查重状态 |
| `SetReleaseEncryptionKey(byte[] key16, Action<FaceReply> success, Action<string> error)` | `Action<FaceReply>` | 设置 Release 加密密钥 |
| `SetDebugEncryptionKey(byte[] key16, Action<FaceReply> success, Action<string> error)` | `Action<FaceReply>` | 设置 Debug 加密密钥 |
| `InitEncryption(byte[] seed4, byte mode, Action<FaceReply> success, Action<string> error)` | `Action<FaceReply>` | 初始化加密 |
| `EnableEncryption(IFaceModuleCrypto crypto, Action success, Action<string> error)` | `Action` | 启用本地加密算法适配器 |
| `DisableEncryption(Action success, Action<string> error)` | `Action` | 关闭本地加密算法适配器 |

## 主要模型

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