江苏医保HeaSecReadInfo.dll集成说明

📋 项目概述

已成功将江苏医保社保卡读取功能集成到ThCardReader项目中，基于HeaSecReadInfo.dll作为主DLL，严格按照江苏医保规范v0.9.9.15实现。

🔧 集成的文件

1. 核心业务类

文件: ThCardReader/JiangSuSocialCardBusiness.cs
功能:
- 封装HeaSecReadInfo.dll的5个核心函数
- 提供标准化的JSON接口
- 实现38号文格式数据解析
- 支持四合一介质

2. API控制器

文件: ThCardReader/JiangSuController.cs
功能:
- 提供GET/POST方式调用
- 与现有项目架构保持一致
- 支持URL参数传递

3. 入口控制器更新

文件: ThCardReader/EntryController.cs
新增: 支持jiangsu类型调用
格式转换: 自动转换为前端期望的^分隔格式

4. 项目配置

文件: ThCardReader/ThCardReader.csproj
更新: 添加新类文件的编译包含

🎯 核心功能实现

DLL函数映射

严格按照江苏医保规范实现的5个核心函数：

// 1.14.1 初始化
[DllImport("HeaSecReadInfo.dll", EntryPoint = "Init")]
private extern static Int32 Init(string pInitInfo, StringBuilder pErrMsg);

// 1.14.2 读社保卡基本信息  
[DllImport("HeaSecReadInfo.dll", EntryPoint = "ReadCardBas")]
private extern static Int32 ReadCardBas(StringBuilder pCardInfo, StringBuilder pBusiCardInfo);

// 1.14.3 检验PIN码
[DllImport("HeaSecReadInfo.dll", EntryPoint = "VerifyPIN")]
private extern static Int32 VerifyPIN(StringBuilder pOutBuff);

// 1.14.4 修改PIN码
[DllImport("HeaSecReadInfo.dll", EntryPoint = "ChangePIN")]
private extern static Int32 ChangePIN(StringBuilder pOutBuff);

// 1.14.8 四合一介质获得个人信息
[DllImport("HeaSecReadInfo.dll", EntryPoint = "GetPersonInfo")]
private extern static Int32 GetPersonInfo(string pInData, StringBuilder pOutData);

配置参数

严格按照江苏医保规范v0.9.9.15的13个必需参数（全部大写）：

{
  "IP": "192.168.100.100",
  "PORT": 8080,
  "TIMEOUT": 120,
  "LOG_PATH": "C:\\log\\",
  "EC_URL": "https://fuwu-test.nhsa.gov.cn/localcfc/api/hsecfc/localQrCodeQuery",
  "CARD_PASSTYPE": "1",
  "API_NAME": "api-powersi-test-pri",
  "API_VERSION": "1.0.0",
  "ACCESS_KEY": "043a6d5927174ab5a7681b193b9fe0e3",
  "SECRETKEY": "ZugfjXENyvGIQYdB+hFB+s9JL0A=",
  "ORG_ID": "",
  "EXT": "",
  "AREA_CODE": "320100"
}

参数说明:

IP: 医疗保障平台提供的服务端IP地址
PORT: 医疗保障平台提供的服务端端口
TIMEOUT: 单位秒，访问服务端超时时间
LOG_PATH: 动态库日志目录（不能超过三级，必须英文，有写权限）
EC_URL: 电子凭证中台URL
CARD_PASSTYPE: 社保卡验证密码方式（1：验证卡pin，2：验证数据库密码）
API_NAME: CSB的_api_name
API_VERSION: CSB的_api_version
ACCESS_KEY: CSB的_api_access_key
SECRETKEY: CSB的secretKey
ORG_ID: 定点编号
EXT: JSON对象字符串（预留）
AREA_CODE: 定点所属行政区划代码

🌐 API接口说明

URL调用方式 (GET)

与现有系统保持一致的调用方式：

基础URL: http://localhost:8321/readcard/entry/{type}_{action}

支持的调用:

jiangsu_init - 初始化系统
jiangsu_readcard - 读取社保卡
jiangsu_readcard_pin - 读卡并验证PIN
jiangsu_verifypin - 验证PIN码
jiangsu_changepin - 修改PIN码
jiangsu_status - 获取设备状态
jiangsu_reset - 重置系统状态
jiangsu_getpersoninfo - 四合一介质获取个人信息

控制器调用方式 (GET/POST)

基础URL: http://localhost:8321/readcard/jiangsu/{action}

GET方式示例:

// 初始化
fetch('http://localhost:8321/readcard/jiangsu/init')

// 读取社保卡
fetch('http://localhost:8321/readcard/jiangsu/readcard')

// 获取状态
fetch('http://localhost:8321/readcard/jiangsu/status')

POST方式示例:

// 带配置的初始化（严格按照规范使用大写参数名）
fetch('http://localhost:8321/readcard/jiangsu', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        action: 'init',
        config: {
            "IP": "192.168.100.100",
            "PORT": 8080,
            "TIMEOUT": 120,
            "LOG_PATH": "C:\\log\\",
            "EC_URL": "https://fuwu-test.nhsa.gov.cn/localcfc/api/hsecfc/localQrCodeQuery",
            "CARD_PASSTYPE": "1",
            "API_NAME": "api-powersi-test-pri",
            "API_VERSION": "1.0.0",
            "ACCESS_KEY": "043a6d5927174ab5a7681b193b9fe0e3",
            "SECRETKEY": "ZugfjXENyvGIQYdB+hFB+s9JL0A=",
            "ORG_ID": "",
            "EXT": "",
            "AREA_CODE": "320100"
        }
    })
})

// 带PIN验证的读卡
fetch('http://localhost:8321/readcard/jiangsu', {
    method: 'POST', 
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        action: 'readcard',
        autoVerifyPIN: true
    })
})

📊 数据格式

返回格式统一化

所有接口返回统一的JSON格式：

{
  "success": true,
  "code": 200,
  "message": "操作成功",
  "device": "江苏医保社保卡读卡器", 
  "data": { ... },
  "timestamp": "2024-01-01 12:00:00"
}

前端兼容格式

通过ConvertJiangSuDataToStandardFormat方法，自动转换为前端期望的^分隔格式：

社保卡号^姓名^身份证号^性别^民族^生日^地址^发卡日期^有效期^发卡机构^照片Base64^^

38号文格式支持

严格按照38号文标准解析社保卡数据，使用管道符|分隔：

卡号|姓名|身份证号|性别|民族|出生日期|地址|发卡日期|有效期|发卡机构|照片

🔄 智能重置策略

集成了智能重置策略，支持：

系统启动时初始化一次
保持状态连续读卡
连续失败自动重置 (阈值可配置)
手动重置选项

// 智能读卡示例（在前端实现）
let consecutiveFailures = 0;
const MAX_FAILURES = 3;

async function smartReadCard() {
    try {
        const response = await fetch('/readcard/entry/jiangsu_readcard');
        const result = await response.json();
        
        if (result.code === 200) {
            consecutiveFailures = 0; // 成功后重置
            return result;
        } else {
            consecutiveFailures++;
            if (consecutiveFailures >= MAX_FAILURES) {
                // 自动重置并重新初始化
                await fetch('/readcard/entry/jiangsu_reset');
                await fetch('/readcard/entry/jiangsu_init');
                consecutiveFailures = 0;
            }
            throw new Error(result.message);
        }
    } catch (error) {
        // 错误处理
        throw error;
    }
}

🧪 测试验证

测试页面

提供了完整的测试页面：jiangsu_test.html

包含功能：

系统状态检查
初始化配置测试
读卡功能测试
PIN码操作测试
四合一介质测试
智能重置策略测试

使用方法

启动ThCardReader应用 (端口8321)
在浏览器中打开 jiangsu_test.html
按序测试各项功能

📁 文件部署要求

DLL文件

确保以下DLL文件位于应用程序目录或系统PATH中：

HeaSecReadInfo.dll (主DLL)
相关依赖DLL（根据江苏医保提供的文档）

配置文件

可选的配置文件（JSON格式）：

{
  "jiangsu": {
    "defaultConfig": {
      "ip": "192.168.1.100",
      "port": "8080",
      "timeout": "30000",
      "logPath": "C:\\logs\\jiangsu_medical.log",
      "ecUrl": "https://fuwu.nhsa.gov.cn",
      "orgCode": "H32010000001"
    }
  }
}

🔒 安全注意事项

DLL文件验证: 使用官方提供的HeaSecReadInfo.dll
网络配置: 确保ecUrl指向正确的江苏医保服务器
日志路径: 确保日志目录有写入权限
错误处理: 所有DLL调用都有完整的异常处理

📈 性能特点

内存管理: 按规范要求分配缓冲区（2048、8192、1024字节）
状态管理: 智能的初始化状态保持
错误恢复: 连续失败自动重置机制
兼容性: 与现有长沙医保系统完全独立

🎯 使用建议

首次使用: 先调用初始化接口
日常使用: 直接调用读卡接口
异常处理: 利用智能重置策略
定期维护: 可选择每日重置一次

这样的集成既保持了与现有系统的兼容性，又提供了江苏医保的完整功能支持，严格遵循官方规范要求。

江苏医保HeaSecReadInfo集成说明.md 8.6 KB Permalink History Raw