# 江苏医保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个核心函数： ```csharp // 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个必需参数（全部大写）： ```json { "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方式示例**: ```javascript // 初始化 fetch('http://localhost:8321/readcard/jiangsu/init') // 读取社保卡 fetch('http://localhost:8321/readcard/jiangsu/readcard') // 获取状态 fetch('http://localhost:8321/readcard/jiangsu/status') ``` **POST方式示例**: ```javascript // 带配置的初始化（严格按照规范使用大写参数名） 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格式： ```json { "success": true, "code": 200, "message": "操作成功", "device": "江苏医保社保卡读卡器", "data": { ... }, "timestamp": "2024-01-01 12:00:00" } ``` ### 前端兼容格式 通过`ConvertJiangSuDataToStandardFormat`方法，自动转换为前端期望的`^`分隔格式： ``` 社保卡号^姓名^身份证号^性别^民族^生日^地址^发卡日期^有效期^发卡机构^照片Base64^^ ``` ### 38号文格式支持 严格按照38号文标准解析社保卡数据，使用管道符`|`分隔： ``` 卡号|姓名|身份证号|性别|民族|出生日期|地址|发卡日期|有效期|发卡机构|照片 ``` ## 🔄 **智能重置策略** 集成了智能重置策略，支持： 1. **系统启动时初始化一次** 2. **保持状态连续读卡** 3. **连续失败自动重置** (阈值可配置) 4. **手动重置选项** ```javascript // 智能读卡示例（在前端实现） 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码操作测试 - 四合一介质测试 - 智能重置策略测试 ### 使用方法 1. **启动ThCardReader应用** (端口8321) 2. **在浏览器中打开** `jiangsu_test.html` 3. **按序测试各项功能** ## 📁 **文件部署要求** ### DLL文件 确保以下DLL文件位于应用程序目录或系统PATH中： - `HeaSecReadInfo.dll` (主DLL) - 相关依赖DLL（根据江苏医保提供的文档） ### 配置文件 可选的配置文件（JSON格式）： ```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" } } } ``` ## 🔒 **安全注意事项** 1. **DLL文件验证**: 使用官方提供的HeaSecReadInfo.dll 2. **网络配置**: 确保ecUrl指向正确的江苏医保服务器 3. **日志路径**: 确保日志目录有写入权限 4. **错误处理**: 所有DLL调用都有完整的异常处理 ## 📈 **性能特点** - **内存管理**: 按规范要求分配缓冲区（2048、8192、1024字节） - **状态管理**: 智能的初始化状态保持 - **错误恢复**: 连续失败自动重置机制 - **兼容性**: 与现有长沙医保系统完全独立 ## 🎯 **使用建议** 1. **首次使用**: 先调用初始化接口 2. **日常使用**: 直接调用读卡接口 3. **异常处理**: 利用智能重置策略 4. **定期维护**: 可选择每日重置一次 这样的集成既保持了与现有系统的兼容性，又提供了江苏医保的完整功能支持，严格遵循官方规范要求。