# WebSocket Service 使用指南

## 启动服务

### 作为前台应用程序运行

```bash
# Windows
WebSocketService.exe

# Linux
./WebSocketService
```

### 作为后台服务运行

```bash
# Windows - 安装并启动服务
WebSocketService.exe --install
net start idreaderserver

# Linux - 作为守护进程运行
./WebSocketService --daemon
```

## 连接WebSocket

默认情况下，服务监听端口17798。可以使用任何WebSocket客户端连接到：

```
ws://localhost:17798/
```

## API调用

所有API调用都通过JSON格式的WebSocket消息进行。

### 基本消息格式

```json
{
  "_act": "action_name",
  "_tflag": "optional_transaction_flag"
}
```

### 响应格式

```json
{
  "_act": "action_name",
  "_tflag": "optional_transaction_flag",
  "code": 0,
  "info": "Success message",
  "functionName": "action_name",
  "retData": {}
}
```

### 身份证读取示例

```json
{
  "_act": "readIDCard"
}
```

响应:
```json
{
  "_act": "readIDCard",
  "code": 0,
  "info": "读取身份证成功",
  "functionName": "readIDCard",
  "retData": {
    "document_type": "1",
    "name": "张三",
    "gender": "男",
    "ethnic_group": "汉",
    "birth": "19900101",
    "address": "北京市朝阳区某某街道",
    "idNumber": "110101199001011234",
    "issuing_authority": "北京市公安局",
    "validity_date_from": "20200101",
    "validity_date_to": "20300101",
    "photoBase64": "base64_encoded_photo_data"
  }
}
```

### 获取设备能力

```json
{
  "_act": "getCapabilities"
}
```

响应:
```json
{
  "_act": "getCapabilities",
  "code": 0,
  "info": "获取设备能力成功",
  "functionName": "getCapabilities",
  "retData": {
    "version": "1.0.0",
    "capabilities": ["device", "idcard"]
  }
}
```

## 支持的API操作

### 身份证操作
- `readIDCard` - 读取身份证
- `readIDCardEX` - 读取身份证扩展信息

### CPU卡操作
- `cpuPowerOn` - CPU卡上电
- `cpuPowerOff` - CPU卡下电
- `cpuApdu` - 发送APDU命令
- `cpuReset` - CPU卡复位

### 非接触式CPU卡操作
- `mcardPowerOn` - 非接触式CPU卡上电
- `mcardRun` - 发送APDU命令

### 磁条卡操作
- `magRead` - 读取磁条卡
- `magWrite` - 写入磁条卡

### M1卡操作
- `cardM1Find` - 寻卡
- `cardM1Auth` - 认证
- `cardM1Read` - 读取数据块
- `cardM1Write` - 写入数据块
- `cardM1Inc` - 增值操作
- `cardM1Dec` - 减值操作

### 4442/4428卡操作
- `card44PowerOn` - 上电
- `card44PowerOff` - 下电
- `card44Read` - 读取数据
- `card44Write` - 写入数据
- `card44AuthPIN` - PIN认证
- `card44EditPIN` - 修改PIN
- `card44ReadPro` - 读取保护数据
- `card44WritePro` - 写入保护数据

### ISO15693卡操作
- `card15693Find` - 寻卡
- `card15693Read` - 读取数据块
- `card15693Write` - 写入数据块
- `card15693Info` - 获取卡片信息

### 设备控制
- `version` - 获取版本信息
- `serialNum` - 获取序列号
- `closeAnt` - 关闭天线
- `openAnt` - 打开天线
- `beep` - 蜂鸣器
- `openPort` - 打开端口
- `closePort` - 关闭端口
- `getCapabilities` - 获取设备能力

## 错误处理

错误响应格式:
```json
{
  "_act": "action_name",
  "code": 400,
  "info": "Error message",
  "functionName": "action_name"
}
```

常见错误代码:
- `0` - 成功
- `400` - 请求错误
- `404` - 未知操作
- `500` - 服务器内部错误

## 配置

配置文件 `config/server.conf` 包含以下主要配置项:

```ini
[server]
port = 17798

[logging]
log_level = INFO
log_file = websocket_service.log

[modules]
idcard = true
cpu-contact = false
```

## 日志

日志文件默认位于 `logs/websocket_service.log`，包含不同级别的日志信息：

- DEBUG - 调试信息
- INFO - 一般信息
- WARNING - 警告信息
- ERROR - 错误信息
- FATAL - 致命错误信息