mhCardReader/江苏医保社保卡读取流程说明.md

江苏医保社保卡读取流程说明

概述

本文档描述基于 HeaSecReadInfo.dll 作为主DLL的江苏医保社保卡读取完整流程。该流程参考华视读卡器的设计模式，但专门适配江苏医保的业务需求。

技术架构

核心组件

江苏医保社保卡系统
├── 主DLL: HeaSecReadInfo.dll
├── 业务类: JiangSuSocialCardBusiness.cs
├── 控制器: JiangSuSocialCardController.cs  
└── API路由: /api/jiangsu/*

与华视读卡器对比

对比项	华视读卡器	江苏医保社保卡
主DLL	termb.dll	HeaSecReadInfo.dll
设备类型	身份证读卡器	社保卡读卡器
数据格式	身份证标准格式	38号文标准格式
业务复杂度	相对简单	复杂(含PIN、网络)
API前缀	/api/huashi/*	/api/jiangsu/*

详细流程

1. 系统初始化流程

1.1 华视读卡器初始化（参考）

// 华视读卡器：简单端口初始化
int CVR_InitComm(int Port);  // 端口号1001-1016为USB

1.2 江苏医保初始化（实现）

// 江苏医保：复杂JSON配置初始化
long Init(string pInitInfo, char* pErrMsg);

// 配置示例
{
  "IP": "192.168.100.100",
  "PORT": 8080,
  "TIMEOUT": 120,
  "LOG_PATH": "C:\\logs\\jiangsu\\",
  "CARD_PASSTYPE": "1",
  "EC_URL": "https://fuwu-test.nhsa.gov.cn/localcfc/api/hsecfc/localQrCodeQuery",
  "API_NAME": "api-powersi-test-pri",
  "API_VERSION": "1.0.0",
  "ACCESS_KEY": "your_access_key",
  "SECRETKEY": "your_secret_key", 
  "ORG_ID": "your_org_id",
  "AREA_CODE": "320100"
}

1.3 API调用

POST http://localhost:8321/api/jiangsu/init
Content-Type: application/json

{
  "IP": "192.168.100.100",
  "PORT": 8080,
  "ORG_ID": "定点编号",
  "ACCESS_KEY": "访问密钥",
  "SECRETKEY": "秘钥"
}

2. 读卡流程

2.1 华视读卡器流程（参考）

华视读卡器读卡流程:
1. CVR_InitComm(port)     // 初始化连接
2. CVR_Authenticate()     // 卡认证 
3. CVR_Read_Content(1)    // 读卡操作
4. GetPeopleName()        // 获取姓名
5. GetPeopleIDCode()      // 获取身份证号

2.2 江苏医保读卡流程（实现）

江苏医保读卡流程:
1. Init(jsonConfig)           // 初始化系统
2. VerifyPIN() [可选]         // 验证PIN码
3. ReadCardBas()              // 读取社保卡基本信息
4. Parse38DocumentFormat()    // 解析38号文格式

2.3 核心函数实现

// 主要P/Invoke声明
[DllImport("HeaSecReadInfo.dll", EntryPoint = "Init")]
private extern static Int32 Init(string pInitInfo, StringBuilder pErrMsg);

[DllImport("HeaSecReadInfo.dll", EntryPoint = "ReadCardBas")]
private extern static Int32 ReadCardBas(StringBuilder pCardInfo, StringBuilder pBusiCardInfo);

[DllImport("HeaSecReadInfo.dll", EntryPoint = "VerifyPIN")]
private extern static Int32 VerifyPIN(StringBuilder pOutBuff);

2.4 数据格式处理

// 38号文格式解析
// 格式：发卡地区|社保号|卡号|卡识别码|姓名|复位信息|版本|发卡日期|有效期|终端机号|设备号|
string[] parts = cardData.Split('|');
var result = new {
    issueArea = parts[0],           // 发卡地区
    socialSecurityNumber = parts[1], // 社保号
    cardNumber = parts[2],          // 卡号
    name = parts[4],               // 姓名
    issueDate = parts[7],          // 发卡日期
    validDate = parts[8]           // 有效期
};

3. API接口设计

3.1 完整API列表

江苏医保社保卡API接口:
├── POST /api/jiangsu/init              # 初始化系统
├── POST /api/jiangsu/readcard          # 读取社保卡
├── POST /api/jiangsu/verifypin         # 验证PIN码
├── POST /api/jiangsu/changepin         # 修改PIN码
├── POST /api/jiangsu/getpersoninfo     # 四合一读取
├── GET  /api/jiangsu/status            # 设备状态
├── POST /api/jiangsu/reset             # 重置内部状态
├── GET  /api/jiangsu/simple            # 简化调用
├── GET  /api/jiangsu/health            # 健康检查
└── GET  /api/jiangsu/help              # API帮助

3.2 核心API示例

读取社保卡：

POST http://localhost:8321/api/jiangsu/readcard
Content-Type: application/json

{
  "autoVerifyPIN": false
}

成功响应：

{
  "code": 200,
  "message": "社保卡读取成功",
  "device": "江苏医保社保卡读卡器",
  "data": {
    "region": "JiangSu",
    "issueArea": "320100",
    "socialSecurityNumber": "111111198101011110",
    "cardNumber": "X00000019",
    "name": "张三",
    "issueDate": "2010-10-01",
    "validDate": "2020-10-01",
    "busiCardInfo": "业务卡串数据",
    "rawData": "原始38号文数据"
  },
  "timestamp": "2023-12-01 10:30:00"
}

4. 错误处理

4.1 错误码设计

错误码范围分配:
├── 1000-1999: 初始化相关错误
├── 2000-2999: 读卡相关错误  
├── 3000-3999: PIN码相关错误
├── 4000-4999: PIN修改相关错误
├── 5000-5999: 个人信息获取错误
├── 6000-6999: 状态重置错误
├── 7000-7999: 状态获取错误
├── 8000-8999: 简化调用错误
└── 9000-9999: 健康检查错误

4.2 典型错误处理

{
  "code": 2001,
  "message": "社保卡读取失败，错误码: 123",
  "device": "江苏医保社保卡读卡器",
  "errorCode": 123,
  "timestamp": "2023-12-01 10:30:00"
}

5. 业务特色功能

5.1 PIN码管理

// 验证PIN码
public static JObject VerifyCardPIN()

// 修改PIN码  
public static JObject ChangeCardPIN()

5.2 四合一介质支持

// 支持多种介质类型
public static JObject GetPersonInfo(string mediaType, string inputData)

// 介质类型:
// - socialcard: 社保卡
// - electronicvoucher: 电子凭证
// - electronicsocialcard: 电子社保卡
// - idcard: 身份证

5.3 38号文数据格式

标准38号文格式（11个字段）:
发卡地区|社保号|卡号|卡识别码|姓名|复位信息|版本|发卡日期|有效期|终端机号|设备号|

示例:
320100|111111198101011110|X00000019|320100D15600000500BF7C7A48FB4966|张三|00814E43238697159900BF7C7A|1.00|20101001|20201001|410100813475|终端设备号|

6. 部署和集成

6.1 DLL文件部署

必需文件:
├── HeaSecReadInfo.dll     # 主DLL
├── 其他辅助DLL            # 根据实际需要
└── 配置文件               # Config.ini等

6.2 项目集成

// 1. 添加业务类到项目
JiangSuSocialCardBusiness.cs

// 2. 添加控制器到项目  
JiangSuSocialCardController.cs

// 3. 确保路由注册
// 在Global.asax或Startup.cs中确保Web API路由正常

7. 测试验证

7.1 基础功能测试

# 1. 健康检查
curl http://localhost:8321/api/jiangsu/health

# 2. 初始化系统
curl -X POST http://localhost:8321/api/jiangsu/init \
  -H "Content-Type: application/json" \
  -d '{"IP":"192.168.100.100","PORT":8080}'

# 3. 读取社保卡
curl -X POST http://localhost:8321/api/jiangsu/readcard \
  -H "Content-Type: application/json" \
  -d '{"autoVerifyPIN":false}'

# 4. 简化调用
curl http://localhost:8321/api/jiangsu/simple?action=readcard

7.2 业务流程测试

完整业务流程测试:
1. 系统初始化 ✓
2. 设备状态检查 ✓  
3. PIN码验证 ✓
4. 社保卡读取 ✓
5. 数据格式验证 ✓

8. 与现有系统集成

8.1 独立性设计

江苏医保系统与现有系统隔离:
├── 独立的命名空间
├── 独立的API路由 (/api/jiangsu/*)
├── 独立的错误码范围
├── 不影响现有长沙医保功能
└── 可以并行运行

8.2 统一访问入口

// 在EntryController中可以添加路由分发
[HttpPost]
[Route("readcard")]
public string ReadCard(string region = "changsha")
{
    switch(region.ToLower())
    {
        case "changsha":
            return SsCardBusiness.ReadCard();
        case "jiangsu":  
            var result = JiangSuSocialCardBusiness.ReadSocialCard();
            return result.ToString();
        default:
            return "不支持的地区";
    }
}

总结

江苏医保社保卡读取流程基于 HeaSecReadInfo.dll 实现，参考华视读卡器的设计模式，但针对医保业务进行了专门的适配：

1. 复杂初始化: 支持完整的JSON配置参数
2. 38号文格式: 标准的医保数据格式
3. PIN码管理: 支持PIN验证和修改
4. 四合一支持: 多种介质类型
5. 完整API: 10个核心接口
6. 独立部署: 不影响现有系统

该流程为江苏医保社保卡读取提供了完整、可靠的技术解决方案。