# 华视电子身份证读卡器完整使用指南

## 📋 概述

华视电子身份证读卡器是独立集成到ThCardReader项目中的身份证读取解决方案，与现有的医保业务（SSCard.dll和NationECCode.dll）完全分离，不会影响原有功能。

---

## 🔧 环境配置

### 1. DLL文件部署

需要将以下华视SDK文件部署到项目输出目录（通常是`bin/x86/Debug/`或`bin/x86/Release/`）：

| 文件名 | 优先级 | 说明 |
|--------|---------|------|
| `termb.dll` | ⭐⭐⭐⭐⭐ | 主要API库（核心）|
| `sdtapi.dll` | ⭐⭐⭐⭐ | 安全模块通信 |
| `WltRs.dll` | ⭐⭐⭐ | 照片解码功能 |
| `SysInfo.dll` | ⭐⭐ | 系统信息支持 |

### 2. 硬件连接

#### 端口配置
| 端口类型 | 端口范围 | 说明 |
|----------|----------|------|
| 串口 | 1-16 | 对应COM1-COM16 |
| USB | 1001-1016 | 对应USB口1-16 |

**推荐配置：使用USB端口1001（USB口1）**

---

## 🚀 快速开始

### 1. 启动服务

ThCardReader项目启动后，华视读卡器API会自动加载，监听地址：`http://localhost:8321`

### 2. 基本调用流程

```mermaid
graph TD
    A[启动ThCardReader] --> B[初始化华视读卡器]
    B --> C{初始化成功?}
    C -->|是| D[放置身份证]
    C -->|否| E[检查硬件连接]
    D --> F[读取身份证]
    F --> G[获取身份证信息]
    G --> H[保存照片可选]
    H --> I[完成]
    E --> B
```

---

## 📡 API接口文档

### 基础URL
```
http://localhost:8321
```

### 1. 初始化读卡器

**接口**: `POST /api/huashi/init`

**请求参数**:
```json
{
    "port": 1001
}
```

**成功响应**:
```json
{
    "code": 200,
    "message": "华视读卡器初始化成功，端口: USB1",
    "port": 1001,
    "device": "华视电子身份证读卡器"
}
```

**错误响应**:
```json
{
    "code": 1001,
    "message": "端口打开失败，请检查读卡器连接",
    "errorCode": 2
}
```

### 2. 读取身份证

**接口**: `POST /api/huashi/readcard`

**请求参数**:
```json
{
    "savePath": "C:/photos"
}
```

**成功响应**:
```json
{
    "code": 200,
    "type": "huashi_idcard",
    "message": "华视读卡器读取身份证成功",
    "device": "华视电子身份证读卡器",
    "data": {
        "name": "张三",
        "sex": "男",
        "nation": "汉",
        "birthday": "19900101",
        "idCode": "110101199001011234",
        "address": "北京市东城区某某街道123号",
        "department": "北京市公安局东城分局",
        "startDate": "20200101",
        "endDate": "20300101",
        "sexCode": "1",
        "nationCode": "01",
        "certType": ""
    }
}
```

### 3. 连续读卡模式

**接口**: `POST /api/huashi/readcard/continuous`

**优点**: 不需要每次拿起放下卡片，适合批量读取

**请求参数**:
```json
{
    "savePath": "C:/photos"
}
```

### 4. 获取设备状态

**接口**: `GET /api/huashi/status`

**响应**:
```json
{
    "code": 200,
    "initialized": true,
    "port": 1001,
    "portDescription": "USB1",
    "deviceStatus": "正常",
    "statusCode": 1,
    "device": "华视电子身份证读卡器",
    "samId": "12345678"
}
```

### 5. 关闭连接

**接口**: `POST /api/huashi/close`

### 6. 获取帮助文档

**接口**: `GET /api/huashi/help`

### 7. 健康检查

**接口**: `GET /api/huashi/health`

---

## 💻 客户端调用示例

### JavaScript/AJAX调用

```javascript
// 1. 初始化读卡器
async function initReader() {
    const response = await fetch('http://localhost:8321/api/huashi/init', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            port: 1001
        })
    });
    
    const result = await response.json();
    console.log('初始化结果:', result);
    return result;
}

// 2. 读取身份证
async function readIdCard() {
    const response = await fetch('http://localhost:8321/api/huashi/readcard', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            savePath: 'C:/photos'
        })
    });
    
    const result = await response.json();
    console.log('读卡结果:', result);
    return result;
}

// 3. 完整使用流程
async function useHuaShiReader() {
    try {
        // 初始化
        const initResult = await initReader();
        if (initResult.code !== 200) {
            throw new Error(initResult.message);
        }
        
        // 读卡
        console.log('请放置身份证...');
        const readResult = await readIdCard();
        if (readResult.code === 200) {
            console.log('读取成功:', readResult.data);
            console.log('姓名:', readResult.data.name);
            console.log('身份证号:', readResult.data.idCode);
        } else {
            console.error('读卡失败:', readResult.message);
        }
    } catch (error) {
        console.error('操作异常:', error.message);
    }
}
```

### C# HTTP客户端调用

```csharp
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;

class HuaShiClient
{
    private static readonly HttpClient client = new HttpClient();
    private const string BaseUrl = "http://localhost:8321";

    public static async Task<JObject> InitReader(int port = 1001)
    {
        var request = new { port = port };
        var json = JsonConvert.SerializeObject(request);
        var content = new StringContent(json, Encoding.UTF8, "application/json");
        
        var response = await client.PostAsync($"{BaseUrl}/api/huashi/init", content);
        var result = await response.Content.ReadAsStringAsync();
        
        return JObject.Parse(result);
    }

    public static async Task<JObject> ReadIdCard(string savePath = "")
    {
        var request = new { savePath = savePath };
        var json = JsonConvert.SerializeObject(request);
        var content = new StringContent(json, Encoding.UTF8, "application/json");
        
        var response = await client.PostAsync($"{BaseUrl}/api/huashi/readcard", content);
        var result = await response.Content.ReadAsStringAsync();
        
        return JObject.Parse(result);
    }

    public static async Task<JObject> GetStatus()
    {
        var response = await client.GetAsync($"{BaseUrl}/api/huashi/status");
        var result = await response.Content.ReadAsStringAsync();
        
        return JObject.Parse(result);
    }

    // 使用示例
    public static async Task Example()
    {
        try
        {
            // 初始化
            var initResult = await InitReader(1001);
            Console.WriteLine($"初始化结果: {initResult}");

            if ((int)initResult["code"] == 200)
            {
                // 读卡
                Console.WriteLine("请放置身份证...");
                var readResult = await ReadIdCard("C:/photos");
                Console.WriteLine($"读卡结果: {readResult}");

                if ((int)readResult["code"] == 200)
                {
                    var data = readResult["data"];
                    Console.WriteLine($"姓名: {data["name"]}");
                    Console.WriteLine($"身份证号: {data["idCode"]}");
                }
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine($"操作异常: {ex.Message}");
        }
    }
}
```

### Python调用示例

```python
import requests
import json

class HuaShiClient:
    def __init__(self, base_url="http://localhost:8321"):
        self.base_url = base_url
    
    def init_reader(self, port=1001):
        """初始化读卡器"""
        url = f"{self.base_url}/api/huashi/init"
        data = {"port": port}
        response = requests.post(url, json=data)
        return response.json()
    
    def read_id_card(self, save_path=""):
        """读取身份证"""
        url = f"{self.base_url}/api/huashi/readcard"
        data = {"savePath": save_path}
        response = requests.post(url, json=data)
        return response.json()
    
    def get_status(self):
        """获取设备状态"""
        url = f"{self.base_url}/api/huashi/status"
        response = requests.get(url)
        return response.json()
    
    def close_reader(self):
        """关闭读卡器"""
        url = f"{self.base_url}/api/huashi/close"
        response = requests.post(url)
        return response.json()

# 使用示例
def main():
    client = HuaShiClient()
    
    try:
        # 初始化
        init_result = client.init_reader(1001)
        print(f"初始化结果: {init_result}")
        
        if init_result.get('code') == 200:
            # 读卡
            print("请放置身份证...")
            read_result = client.read_id_card("C:/photos")
            print(f"读卡结果: {read_result}")
            
            if read_result.get('code') == 200:
                data = read_result.get('data', {})
                print(f"姓名: {data.get('name')}")
                print(f"身份证号: {data.get('idCode')}")
            
            # 关闭连接
            client.close_reader()
    
    except Exception as e:
        print(f"操作异常: {e}")

if __name__ == "__main__":
    main()
```

---

## 🎯 支持的证件类型

| 证件类型 | certType标识 | 说明 |
|----------|--------------|------|
| 居民身份证 | "" | 普通身份证 |
| 外国人永久居留证 | "I" | 外国人证件 |
| 港澳台居民居住证 | "J" | 港澳台证件 |
| 新版外国人居留证 | "Y" | 新版外国人证件 |

---

## 📊 返回字段说明

| 字段名 | 类型 | 说明 | 示例 |
|--------|------|------|------|
| name | string | 姓名 | "张三" |
| sex | string | 性别 | "男" |
| nation | string | 民族 | "汉" |
| birthday | string | 出生日期 | "19900101" |
| idCode | string | 身份证号 | "110101199001011234" |
| address | string | 地址 | "北京市东城区..." |
| department | string | 签发机关 | "北京市公安局..." |
| startDate | string | 有效开始日期 | "20200101" |
| endDate | string | 有效截止日期 | "20300101" |
| sexCode | string | 性别代码 | "1"(男) "2"(女) |
| nationCode | string | 民族代码 | "01"(汉族) |
| certType | string | 证件类别 | ""(身份证) "I"(外国人) |

---

## ⚠️ 注意事项

### 1. 与现有系统的关系

- ✅ **完全独立**：华视读卡器API独立运行，不影响现有医保业务
- ✅ **并行使用**：可以与SSCard.dll和NationECCode.dll同时使用
- ✅ **端口分离**：使用独立的API路径`/api/huashi/*`

### 2. 硬件要求

- 📌 需要华视电子身份证读卡器硬件设备
- 📌 设备驱动程序已正确安装
- 📌 四个DLL文件部署到正确位置

### 3. 性能建议

- ⏱️ 卡认证循环间隔 > 300ms
- ⏱️ 查询卡片状态间隔 > 600ms
- 💡 使用连续读卡模式提高效率
- 💾 合理设置照片保存路径

### 4. 错误处理

| 错误代码 | 说明 | 解决方案 |
|----------|------|----------|
| 2 | 端口打开失败 | 检查读卡器连接和端口号 |
| -2 | DLL加载失败 | 检查termb.dll等文件是否存在 |
| 2 | 寻卡失败 | 重新放置身份证 |
| 3 | 选卡失败 | 重新放置身份证 |
| 4 | 设备未连接 | 检查硬件连接 |

### 5. 开发建议

- 🔄 使用异步调用避免界面阻塞
- 🛡️ 添加适当的错误处理和重试机制
- 📸 照片保存失败不影响主要功能
- 🔍 定期检查设备状态确保可用性

---

## 🔧 故障排除

### 常见问题及解决方案

**Q1: 初始化失败，提示"端口打开失败"**
- 检查读卡器USB连接是否正常
- 确认设备管理器中读卡器设备正常
- 尝试其他USB端口（1001-1016）

**Q2: 提示"动态库加载失败"**
- 确认termb.dll等四个DLL文件在正确位置
- 检查DLL文件版本是否与硬件匹配
- 确认操作系统位数与DLL位数一致

**Q3: 认证失败，无法读卡**
- 重新放置身份证，确保卡片平整
- 检查身份证芯片是否损坏
- 尝试使用连续读卡模式

**Q4: 无法获取照片**
- 确认WltRs.dll照片解码库已部署
- 检查照片保存路径权限
- 部分身份证可能不含照片信息

---

## 📞 技术支持

- **华视厂商支持**: 13723716489 何工
- **项目集成支持**: 参考本文档进行配置
- **API接口文档**: 访问 `GET /api/huashi/help` 获取完整接口信息

---

**通过本指南，您可以完整地在ThCardReader项目中集成和使用华视电子身份证读卡器，实现与现有医保业务的完美并存。**