mhCardReader/江苏宿迁沭阳铭和医院的华视读卡器完整使用指南.md

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

📋 概述

华视电子身份证读卡器是独立集成到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. 基本调用流程

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

请求参数:

{
    "port": 1001
}

成功响应:

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

错误响应:

{
    "code": 1001,
    "message": "端口打开失败，请检查读卡器连接",
    "errorCode": 2
}

2. 读取身份证

接口: POST /api/huashi/readcard

请求参数:

{
    "savePath": "C:/photos"
}

成功响应:

{
    "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

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

请求参数:

{
    "savePath": "C:/photos"
}

4. 获取设备状态

接口: GET /api/huashi/status

响应:

{
    "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调用

// 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客户端调用

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调用示例

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项目中集成和使用华视电子身份证读卡器，实现与现有医保业务的完美并存。