# API 参考

本文仅记录 AISU 830T Card Reader SDK v0.1.0 中面向 Unity 使用者的公开 API。命名空间为 `Aisu.CardReader`。

## CardReaderManager

`CardReaderManager` 是场景级读卡器管理组件。将它添加到场景中的 GameObject，并保持一个实例。

### 主要属性

```csharp
public static CardReaderManager Instance { get; }
public SerialDeviceOptions SerialOptions { get; set; }
public bool IsConnected { get; }
```

- `Instance`：当前场景中的 Manager。
- `SerialOptions`：Inspector 和代码使用的串口配置。
- `IsConnected`：当前是否已连接。

### 主要方法

```csharp
public void OpenReader();
public void CloseReader();
```

`OpenReader()` 启动读卡器连接。`CloseReader()` 关闭当前连接并停止自动重连；之后可以再次调用 `OpenReader()`。

### 事件

```csharp
public UnityEvent OnConnected { get; }
public UnityEvent OnDisconnected { get; }
public UnityEvent<SerialDeviceState> OnStateChanged { get; }
public UnityEvent<CardInfo> OnCardReceived { get; }
public UnityEvent<CardReaderErrorEventArgs> OnError { get; }
```

事件使用 `AddListener` 和 `RemoveListener`。通过 Manager 接收的 UnityEvent 在 Unity 主线程派发。

## CardReaderApi

`CardReaderApi` 是当前 `CardReaderManager` 的静态访问入口，适合在业务脚本中使用。

```csharp
public static bool IsConnected { get; }
public static void Open();
public static void Close();

public static UnityEvent OnConnected { get; }
public static UnityEvent OnDisconnected { get; }
public static UnityEvent<SerialDeviceState> OnStateChanged { get; }
public static UnityEvent<CardInfo> OnCardReceived { get; }
public static UnityEvent<CardReaderErrorEventArgs> OnError { get; }
```

`Open()` 与 `Close()` 的行为分别是启动连接和关闭连接。没有活动的 `CardReaderManager` 时，调用方法或访问事件会抛出 `InvalidOperationException`。

## SerialDeviceOptions

`SerialDeviceOptions` 是 `CardReaderManager.SerialOptions` 的配置类型。当前公开字段如下：

| 字段 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `PortName` | `string` | 无 | Windows COM 端口名称。 |
| `BaudRate` | `int` | `9600` | 波特率。 |
| `Parity` | `Parity` | `None` | 校验方式。 |
| `DataBits` | `int` | `8` | 数据位。 |
| `StopBits` | `StopBits` | `One` | 停止位。 |
| `Handshake` | `Handshake` | `None` | 握手方式。 |
| `ReadTimeout` | `int` | `100` | 读超时，单位毫秒。 |
| `WriteTimeout` | `int` | `1000` | 写超时，单位毫秒。 |
| `RtsEnable` | `bool` | `true` | 是否启用 RTS。 |
| `DtrEnable` | `bool` | `true` | 是否启用 DTR。 |
| `AutoReconnect` | `bool` | `true` | 连接异常后是否继续自动重连。 |
| `ReconnectInterval` | `int` | `1000` | 自动重连间隔，单位毫秒。 |
| `MaxPendingSendCount` | `int` | `256` | 待发送数据容量。 |

实际设备的 COM 口和 UART 参数可能不同，请以设备配置为准。

## CardInfo

`CardInfo` 是 `OnCardReceived` 提供的卡片信息：

```csharp
public CardType CardType { get; }
public byte CardTypeCode { get; }
public string CardNumber { get; }
```

- `CardType`：当前已知类型为 `CardType.EM4100`。
- `CardTypeCode`：设备上报的原始类型码。未知类型不会丢失。
- `CardNumber`：十进制卡号字符串。

### CardNumber 规则

`CardNumber` 的类型为 `string`，表示十进制卡号字符串。默认最小长度为 10 位：不足 10 位时左侧补 `0`，超过 10 位时不截断。

## CardType

```csharp
public enum CardType
{
    Unknown = 0,
    EM4100 = 0x02
}
```

## 错误事件

`OnError` 提供 `CardReaderErrorEventArgs`：

```csharp
public CardReaderException Exception { get; }
```

`Exception` 是真实异常对象。常见原因包括 COM 端口不存在、端口被其他程序占用和连接失败。相同的连接错误不会持续重复派发，但在 `AutoReconnect` 开启时 SDK 仍会继续尝试连接。

## 事件使用约定

推荐在 `OnEnable` 中使用 `AddListener` 注册，在 `OnDisable` 中使用 `RemoveListener` 解除。生命周期示例：

```csharp
private void OnEnable()
{
    CardReaderApi.OnCardReceived.AddListener(OnCardReceived);
}

private void OnDisable()
{
    CardReaderApi.OnCardReceived.RemoveListener(OnCardReceived);
}
```

`CardReaderManager` 销毁或应用退出时会自动释放串口资源。