# ThCardReader 使用说明文档

## 📋 目录
1. [功能概述](#功能概述)
2. [华视读身份证功能](#华视读身份证功能)
3. [江苏医保读社保卡功能](#江苏医保读社保卡功能)
4. [接口调用示例](#接口调用示例)
5. [错误处理](#错误处理)
6. [常见问题](#常见问题)

---

## 🎯 功能概述

ThCardReader是一个读卡服务程序，提供HTTP接口用于读取各种证件信息。本版本支持：

- **华视读身份证功能**：通过华视电子身份证读卡器读取身份证信息
- **江苏医保读社保卡功能**：通过江苏医保接口读取社保卡信息

### 服务信息
- **服务地址**：`http://localhost:8321`
- **协议**：HTTP/1.1
- **数据格式**：JSON
- **字符编码**：UTF-8

---

## 🆔 华视读身份证功能

### 功能描述
通过华视电子身份证读卡器读取二代身份证信息，包括基本信息和照片数据。

### 硬件要求
- **华视电子身份证读卡器**（USB接口）
- **USB连接**：确保读卡器正确连接并安装驱动

### API接口

#### 1. 初始化华视读卡器
```http
GET /readcard/entry?param=huashi_init_1001
```

**参数说明**：
- `1001`：USB端口号（1001-1016）

**返回示例**：
```json
{
  "code": 200,
  "message": "华视读卡器初始化成功",
  "device": "华视电子身份证读卡器",
  "port": 1001
}
```

#### 2. 读取身份证信息
```http
GET /readcard/entry?param=huashi_readcard
```

**返回示例**：
```json
{
  "code": 200,
  "type": "idcard",
  "data": "张三^男^汉^19900101^北京市朝阳区某某街道^公安部门^20200101-20300101^",
  "message": "读取身份证成功。"
}
```

**数据格式说明**：
```
data字段用"^"分隔，包含以下信息：
[0] 姓名
[1] 性别
[2] 民族
[3] 出生日期
[4] 地址
[5] 签发机关
[6] 有效期（开始日期-结束日期）
[7] 照片Base64数据（可选）
```

#### 3. 连续读卡模式
```http
GET /readcard/entry?param=huashi_continuous
```

#### 4. 获取设备状态
```http
GET /readcard/entry?param=huashi_status
```

#### 5. 关闭连接
```http
GET /readcard/entry?param=huashi_close
```

### 专用API接口

#### 简化调用方式
```http
GET /readcard/huashi/simple?action=readcard&port=1001
```

#### POST方式调用
```http
POST /readcard/huashi/readcard
Content-Type: application/json

{
  "savePath": "",
  "autoClose": true
}
```

---

## 🏥 江苏医保读社保卡功能

### 功能描述
通过江苏医保接口读取社保卡基本信息，支持自动初始化和PIN码验证。

### 硬件要求
- **江苏医保社保卡读卡器**
- **网络连接**：部分功能需要连接江苏医保平台

### API接口

#### 1. 自动初始化读社保卡（推荐）
```http
GET /readcard/jiangsu/readcard_auto
```

**特点**：
- 自动检测初始化状态
- 如未初始化，自动执行初始化
- 一步完成读卡操作

**返回示例**：
```json
{
  "success": true,
  "code": 200,
  "message": "社保卡读取成功",
  "device": "江苏医保社保卡读卡器",
  "interface": "江苏医保接口 v0.9.9.15",
  "interfaceType": "medical",
  "initMode": "auto",
  "autoInitSuccess": true,
  "data": {
    "cardInfo": "639900|111111198101011110|X00000019|...",
    "busiInfo": "业务信息数据",
    "name": "张三",
    "idCard": "111111198101011110",
    "cardNumber": "X00000019"
  },
  "timestamp": "2024-01-01 10:00:00"
}
```

#### 2. 带PIN验证的自动读卡
```http
GET /readcard/jiangsu/readcard_auto_pin
```

#### 3. 手动初始化
```http
GET /readcard/jiangsu/init
```

#### 4. 传统读卡方式
```http
GET /readcard/jiangsu/readcard
```

#### 5. 设备状态查询
```http
GET /readcard/jiangsu/status
```

#### 6. PIN码验证
```http
GET /readcard/jiangsu/verifypin
```

#### 7. PIN码修改
```http
GET /readcard/jiangsu/changepin
```

### POST方式调用

#### 带参数的读卡请求
```http
POST /readcard/jiangsu
Content-Type: application/json

{
  "action": "readcard",
  "autoVerifyPIN": false,
  "autoInit": true
}
```

#### 自定义初始化配置
```http
POST /readcard/jiangsu
Content-Type: application/json

{
  "action": "init",
  "config": {
    "IP": "10.61.165.3",
    "PORT": 8086,
    "TIMEOUT": 30,
    "ACCESS_KEY": "your_access_key",
    "SECRETKEY": "your_secret_key",
    "ORG_ID": "H32132200561",
    "AREA_CODE": "321322"
  }
}
```

### 数据格式说明

#### 社保卡数据格式（标准38号文）
```
639900|111111198101011110|X00000019|639900D15600000500BF7C7A48FB4966|张三|00814E43238697159900BF7C7A|1.00|20101001|20201001|410100813475|终端设备号|

字段说明：
[0] 发卡地区行政区划代码
[1] 社会保障号码（身份证号）
[2] 卡号
[3] 卡识别码
[4] 姓名
[5] 卡复位信息
[6] 规范版本
[7] 发卡日期
[8] 卡有效期
[9] 终端机编号
[10] 终端设备号
```

---

## 💻 接口调用示例

### JavaScript调用示例

#### 华视读身份证
```javascript
// 读取身份证
async function readIdCard() {
    try {
        const response = await fetch('http://localhost:8321/readcard/entry?param=huashi_readcard');
        const data = await response.json();
        
        if (data.code === 200) {
            // 解析身份证数据
            const idInfo = data.data.split('^');
            console.log('姓名:', idInfo[0]);
            console.log('性别:', idInfo[1]);
            console.log('民族:', idInfo[2]);
            console.log('出生日期:', idInfo[3]);
            console.log('地址:', idInfo[4]);
        } else {
            console.error('读卡失败:', data.message);
        }
    } catch (error) {
        console.error('请求异常:', error);
    }
}
```

#### 江苏医保读社保卡
```javascript
// 自动初始化读社保卡
async function readSocialCard() {
    try {
        const response = await fetch('http://localhost:8321/readcard/jiangsu/readcard_auto');
        const data = await response.json();
        
        if (data.success) {
            console.log('读卡成功:', data.data);
            if (data.autoInitSuccess) {
                console.log('已自动完成初始化');
            }
        } else {
            console.error('读卡失败:', data.message);
        }
    } catch (error) {
        console.error('请求异常:', error);
    }
}

// POST方式调用
async function readSocialCardWithPost() {
    try {
        const response = await fetch('http://localhost:8321/readcard/jiangsu', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify({
                action: 'readcard',
                autoVerifyPIN: false,
                autoInit: true
            })
        });
        
        const data = await response.json();
        console.log('读卡结果:', data);
    } catch (error) {
        console.error('请求异常:', error);
    }
}
```

### C# 调用示例

#### 华视读身份证
```csharp
using System.Net.Http;
using Newtonsoft.Json.Linq;

// 读取身份证
private async Task<JObject> ReadIdCardAsync()
{
    using (var client = new HttpClient())
    {
        string url = "http://localhost:8321/readcard/entry?param=huashi_readcard";
        string response = await client.GetStringAsync(url);
        return JObject.Parse(response);
    }
}

// 解析身份证数据
private void ParseIdCardData(JObject result)
{
    if ((int)result["code"] == 200)
    {
        string[] idInfo = result["data"].ToString().Split('^');
        string name = idInfo[0];      // 姓名
        string gender = idInfo[1];    // 性别
        string nation = idInfo[2];    // 民族
        string birthday = idInfo[3];  // 出生日期
        string address = idInfo[4];   // 地址
    }
}
```

#### 江苏医保读社保卡
```csharp
// 自动初始化读社保卡
private async Task<JObject> ReadSocialCardAsync()
{
    using (var client = new HttpClient())
    {
        string url = "http://localhost:8321/readcard/jiangsu/readcard_auto";
        string response = await client.GetStringAsync(url);
        return JObject.Parse(response);
    }
}

// POST方式调用
private async Task<JObject> ReadSocialCardWithPostAsync()
{
    using (var client = new HttpClient())
    {
        var requestData = new
        {
            action = "readcard",
            autoVerifyPIN = false,
            autoInit = true
        };
        
        var json = JsonConvert.SerializeObject(requestData);
        var content = new StringContent(json, Encoding.UTF8, "application/json");
        
        var response = await client.PostAsync("http://localhost:8321/readcard/jiangsu", content);
        var responseContent = await response.Content.ReadAsStringAsync();
        
        return JObject.Parse(responseContent);
    }
}
```

### Java 调用示例

```java
// 使用 OkHttp 库
import okhttp3.*;
import com.google.gson.Gson;

public class CardReader {
    private static final String BASE_URL = "http://localhost:8321";
    private OkHttpClient client = new OkHttpClient();
    private Gson gson = new Gson();
    
    // 华视读身份证
    public void readIdCard() throws IOException {
        Request request = new Request.Builder()
            .url(BASE_URL + "/readcard/entry?param=huashi_readcard")
            .build();
            
        try (Response response = client.newCall(request).execute()) {
            String responseBody = response.body().string();
            // 处理返回数据
            System.out.println(responseBody);
        }
    }
    
    // 江苏医保读社保卡
    public void readSocialCard() throws IOException {
        Request request = new Request.Builder()
            .url(BASE_URL + "/readcard/jiangsu/readcard_auto")
            .build();
            
        try (Response response = client.newCall(request).execute()) {
            String responseBody = response.body().string();
            // 处理返回数据
            System.out.println(responseBody);
        }
    }
}
```

---

## ⚠️ 错误处理

### 常见错误码

| 错误码 | 说明 | 解决方案 |
|--------|------|----------|
| 200 | 成功 | 正常状态 |
| 1001 | 参数错误或设备未连接 | 检查参数和设备连接 |
| 1002 | 系统未初始化 | 调用初始化接口或使用auto接口 |
| 9001 | 系统异常 | 检查日志，重启服务 |
| 3000+ | 江苏医保DLL错误 | 检查DLL文件和网络连接 |

### 错误处理示例

```javascript
function handleError(result) {
    switch(result.code) {
        case 200:
            console.log('操作成功');
            break;
        case 1001:
            console.error('设备错误，请检查读卡器连接');
            break;
        case 1002:
            console.error('系统未初始化，请先初始化');
            break;
        default:
            console.error('未知错误:', result.message);
    }
}
```

---

## ❓ 常见问题

### 1. 华视读卡器相关

**Q: 读卡器无法识别身份证？**
```
A: 检查以下几点：
   - USB连接是否正常
   - 驱动是否正确安装
   - 身份证是否正确放置
   - 尝试重新初始化：/readcard/entry?param=huashi_init_1001
```

**Q: 返回错误码1001？**
```
A: 通常是硬件问题：
   - 检查读卡器USB连接
   - 确认身份证放置正确
   - 重启读卡器驱动
```

### 2. 江苏医保相关

**Q: 自动初始化失败？**
```
A: 检查以下配置：
   - 网络连接是否正常
   - 配置参数是否正确
   - DLL文件是否完整
   - 尝试手动初始化
```

**Q: 社保卡读取失败？**
```
A: 可能的原因：
   - 社保卡未正确插入
   - 网络连接问题
   - 配置参数错误
   - 建议使用 /readcard/jiangsu/diagnose 诊断
```

### 3. 服务相关

**Q: 无法访问HTTP接口？**
```
A: 检查以下设置：
   - 程序是否以管理员权限运行
   - 防火墙是否允许8321端口
   - 端口是否被其他程序占用
```

**Q: 服务启动失败？**
```
A: 可能的解决方案：
   - 以管理员身份运行
   - 检查.NET Framework版本
   - 确保端口8321未被占用
```

---

## 📞 技术支持

### 服务信息
- **版本**：v1.0.0
- **服务端口**：8321
- **支持系统**：Windows 7/8/10/11

### 调试信息
```bash
# 健康检查
GET /readcard/huashi/health

# 华视设备状态
GET /readcard/huashi/status

# 江苏医保状态
GET /readcard/jiangsu/status

# 江苏医保诊断
GET /readcard/jiangsu/diagnose
```

### 日志文件位置
```
程序目录/NEULOGS/     # 东软日志
程序目录/TSLOG/       # 终端日志
程序目录/logs/        # 江苏医保日志
```

---

**重要提醒**：
1. 首次使用建议先测试设备连接
2. 确保以管理员权限运行程序
3. 定期检查服务状态和日志
4. 如遇问题，优先检查硬件连接和网络状态