# 江苏医保读社保卡基本信息功能文档

## 概述

本文档基于《医疗保障信息平台定点基线版医药机构接口规范 v0.9.9.15》，专门提取江苏医保读社保卡相关功能。与项目中长沙医保的SSCard.dll功能对应，江苏医保使用不同的动态库实现相同的读卡业务。

## 动态库说明

### 预期动态库名称
- **主库**: 可能为 `JSMedInsurance.dll`、`JiangSuCard.dll` 或 `NationECCode_JS.dll`
- **辅助库**: 可能包含读卡器驱动、加密解密、网络通信等相关DLL

### 与长沙医保对比
| 项目 | 长沙医保 | 江苏医保 |
|------|----------|----------|
| 主要DLL | SSCard.dll | 待确定（可能多个DLL） |
| 初始化方式 | 简单URL+用户 | 复杂JSON配置 |
| 数据格式 | 自定义格式 | 标准38号文格式 |
| 业务复杂度 | 相对简单 | 功能更全面 |

## 核心功能模块

### 1. 初始化功能

#### 1.1 函数定义
```c
long WINAPI Init(char* pInitInfo, char* pErrMsg);
```

#### 1.2 与长沙医保对比
**长沙医保初始化:**
```csharp
[DllImport("SSCard.dll", EntryPoint = "Init")]
private extern static Int32 Init(string pUrl, string pUser);
```

**江苏医保初始化（预期）:**
```csharp
[DllImport("JSMedInsurance.dll", EntryPoint = "Init")]
private extern static Int32 Init(string pInitInfo, StringBuilder pErrMsg);
```

#### 1.3 初始化参数 (JSON格式)
```json
{
  "IP": "192.168.100.100",
  "PORT": 8080,
  "TIMEOUT": 120,
  "LOG_PATH": "C:\\log\\",
  "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": "043a6d5927174ab5a7681b193b9fe0e3",
  "SECRETKEY": "ZugfjXENyvGIQYdB+hFB+s9JL0A=",
  "ORG_ID": "定点编号",
  "AREA_CODE": "320100"
}
```

#### 1.4 关键配置参数说明
| 参数 | 说明 | 是否必填 | 示例值 |
|------|------|----------|--------|
| IP | 医保平台服务端IP | Y | 192.168.100.100 |
| PORT | 服务端端口 | Y | 8080 |
| TIMEOUT | 超时时间(秒) | Y | 120 |
| LOG_PATH | 日志目录 | Y | C:\\log\\ |
| CARD_PASSTYPE | 密码验证方式 | Y | 1:验证卡pin 2:验证数据库密码 |
| EC_URL | 电子凭证中台URL | Y | 国家医保局提供 |
| ORG_ID | 定点编号 | Y | 医院/药店编号 |
| AREA_CODE | 行政区划代码 | Y | 320100(南京) |

### 2. 读社保卡基本信息

#### 2.1 函数定义
```c
long WINAPI ReadCardBas(char* pCardInfo, char* pBusiCardInfo);
```

#### 2.2 与长沙医保对比
**长沙医保读卡:**
```csharp
[DllImport("SSCard.dll", EntryPoint = "ReadCardBas")]
private extern static Int32 ReadCardBas(StringBuilder pOutBuff, int nOutBuffLen, StringBuilder pSignBuff, int nSignBuffLen);
```

**江苏医保读卡（预期）:**
```csharp
[DllImport("JSMedInsurance.dll", EntryPoint = "ReadCardBas")]
private extern static Int32 ReadCardBas(StringBuilder pCardInfo, StringBuilder pBusiCardInfo);
```

#### 2.3 输出参数说明

**pCardInfo - 社保卡基本信息**
- **格式**: 管道符(|)分隔的标准38号文格式
- **内容**: 发卡地区行政区划代码|社会保障号码|卡号|卡识别码|姓名|卡复位信息|规范版本|发卡日期|卡有效期|终端机编号|终端设备号|
- **示例**: `639900|111111198101011110|X00000019|639900D15600000500BF7C7A48FB4966|张三|00814E43238697159900BF7C7A|1.00|20101001|20201001|410100813475|终端设备号|`
- **内存分配**: 建议2048字节，不能小于2048

**pBusiCardInfo - 业务卡串信息**
- **用途**: 后续医保业务交易使用的加密卡串
- **格式**: 加密后的Base64字符串
- **内存分配**: 建议8192字节，不能小于8192

#### 2.4 返回值
- `0`: 成功
- `非0`: 失败，具体错误码需参考动态库文档

### 3. PIN码管理功能

#### 3.1 验证PIN码
```c
long WINAPI VerifyPIN(char *pOutBuff);
```

**验证规则:**
- 本参保地持卡人: 必须校验密码
- 异地就医人员: 按本地医保局要求决定是否验证
- 连续6次错误后卡片自动锁定

#### 3.2 修改PIN码
```c
long WINAPI ChangePIN(char *pOutBuff);
```

**使用条件:**
- 需要原密码验证通过
- 新密码和确认密码必须一致
- 本参保地持卡人可以修改
- 异地就医人员按本地要求

### 4. 处方信息读取功能

#### 4.1 读社保卡基本信息和处方信息
```c
long WINAPI ReadCardBasRx(char* pInput, char* pCardInfo, char* pRxInfo);
```

**输入参数格式:**
`定点机构登记人姓名|定点机构登记人证件类型|定点机构登记人证件号码|医疗机构编码|代办人姓名|代办人身份证类型|代办人身份证类型|收费端电脑IP|CaInfo|his软件开发商|`

**处方信息输出:**
`处方登记流水号|处方过期时间|`

### 5. 四合一介质支持

#### 5.1 获取个人信息
```c
long WINAPI GetPersonInfo(char* pInData, char* pOutData);
```

**支持介质类型:**
1. **社保卡**: 返回CardInfo和BusiCardInfo
2. **电子凭证**: 返回身份证号、姓名、令牌等
3. **电子社保卡**: 返回社保号、电子社保卡Token等
4. **身份证**: 返回身份证信息和业务身份证信息

## C#集成实现建议

### 1. 江苏医保业务类结构
```csharp
public class JiangSuMedInsuranceBusiness
{
    // P/Invoke声明
    [DllImport("JSMedInsurance.dll", EntryPoint = "Init", CharSet = CharSet.Ansi)]
    private extern static Int32 Init(string pInitInfo, StringBuilder pErrMsg);
    
    [DllImport("JSMedInsurance.dll", EntryPoint = "ReadCardBas", CharSet = CharSet.Ansi)]
    private extern static Int32 ReadCardBas(StringBuilder pCardInfo, StringBuilder pBusiCardInfo);
    
    [DllImport("JSMedInsurance.dll", EntryPoint = "VerifyPIN", CharSet = CharSet.Ansi)]
    private extern static Int32 VerifyPIN(StringBuilder pOutBuff);
    
    [DllImport("JSMedInsurance.dll", EntryPoint = "ChangePIN", CharSet = CharSet.Ansi)]
    private extern static Int32 ChangePIN(StringBuilder pOutBuff);
    
    [DllImport("JSMedInsurance.dll", EntryPoint = "GetPersonInfo", CharSet = CharSet.Ansi)]
    private extern static Int32 GetPersonInfo(string pInData, StringBuilder pOutData);
    
    // 业务方法
    public string InitializeSystem(JiangSuConfig config) { }
    public ReadCardResult ReadSocialSecurityCard() { }
    public bool VerifyCardPIN() { }
    public bool ChangeCardPIN() { }
    public PersonInfo GetPersonInfoByMedia(MediaType mediaType) { }
}
```

### 2. 配置类
```csharp
public class JiangSuConfig
{
    public string IP { get; set; }
    public int PORT { get; set; }
    public int TIMEOUT { get; set; }
    public string LOG_PATH { get; set; }
    public string CARD_PASSTYPE { get; set; }
    public string EC_URL { get; set; }
    public string API_NAME { get; set; }
    public string API_VERSION { get; set; }
    public string ACCESS_KEY { get; set; }
    public string SECRETKEY { get; set; }
    public string ORG_ID { get; set; }
    public string AREA_CODE { get; set; }
    
    public string ToJson()
    {
        return JsonConvert.SerializeObject(this);
    }
}
```

### 3. 数据模型
```csharp
public class JiangSuCardInfo
{
    public string IssueAreaCode { get; set; }      // 发卡地区行政区划代码
    public string SocialSecurityNumber { get; set; } // 社会保障号码
    public string CardNumber { get; set; }         // 卡号
    public string CardId { get; set; }            // 卡识别码
    public string Name { get; set; }              // 姓名
    public string CardResetInfo { get; set; }     // 卡复位信息
    public string SpecVersion { get; set; }       // 规范版本
    public string IssueDate { get; set; }         // 发卡日期
    public string ValidDate { get; set; }         // 卡有效期
    public string TerminalId { get; set; }        // 终端机编号
    public string DeviceId { get; set; }          // 终端设备号
    public string BusiCardInfo { get; set; }      // 业务卡串
    
    public static JiangSuCardInfo ParseFromString(string cardInfoString, string busiCardInfo)
    {
        // 解析管道符分隔的字符串
        string[] parts = cardInfoString.Split('|');
        if (parts.Length >= 11)
        {
            return new JiangSuCardInfo
            {
                IssueAreaCode = parts[0],
                SocialSecurityNumber = parts[1],
                CardNumber = parts[2],
                CardId = parts[3],
                Name = parts[4],
                CardResetInfo = parts[5],
                SpecVersion = parts[6],
                IssueDate = parts[7],
                ValidDate = parts[8],
                TerminalId = parts[9],
                DeviceId = parts[10],
                BusiCardInfo = busiCardInfo
            };
        }
        return null;
    }
}
```

## 系统集成步骤

### 1. 动态库部署
1. 确定江苏医保提供的具体DLL文件名称
2. 将所有相关DLL文件部署到应用程序目录
3. 确保DLL的架构(x86/x64)与应用程序一致

### 2. 配置管理
1. 在配置文件中添加江苏医保相关配置
2. 支持多地区医保配置切换
3. 提供配置验证功能

### 3. 异常处理
1. 实现统一的错误码处理
2. 提供友好的错误信息提示
3. 记录详细的操作日志

### 4. 测试验证
1. 单元测试各个功能模块
2. 集成测试完整读卡流程
3. 异常场景测试（网络断开、卡片故障等）

## 与长沙医保的差异对比

| 功能点 | 长沙医保(SSCard.dll) | 江苏医保 |
|--------|----------------------|----------|
| 初始化复杂度 | 简单(URL+用户) | 复杂(13个配置参数) |
| 数据格式标准 | 自定义 | 国家标准38号文 |
| PIN码管理 | 不支持 | 支持验证和修改 |
| 多介质支持 | 仅社保卡 | 四合一(社保卡+电子凭证+电子社保卡+身份证) |
| 处方信息 | 不支持 | 支持读取处方信息 |
| 加密卡串 | 简单格式 | Base64加密格式 |
| 网络依赖 | 本地处理 | 需要网络连接医保平台 |

## 注意事项

1. **DLL依赖**: 江苏医保可能包含多个DLL，需要确保所有依赖库都正确部署
2. **网络配置**: 需要确保能够访问江苏医保平台和电子凭证中台
3. **证书配置**: 可能需要配置数字证书用于安全通信
4. **日志管理**: 动态库会生成日志，需要合理配置日志目录
5. **版本兼容**: 注意规范版本(version1.1、version1.2)的兼容性处理
6. **行政区划**: AREA_CODE需要根据具体医院/药店所在地区配置