# 江苏医保电子凭证查询业务流程规范

## 1. 总体业务流程

### 1.1 流程概述
本文档基于《医疗保障信息平台定点基线版医药机构接口规范 v0.9.9.15》中的1.14.6电子凭证解码接口，结合现有泰和医院业务流程，制定江苏医保电子凭证查询的标准业务流程。

### 1.2 适用范围
- 江苏省内医保定点医疗机构
- 支持电子凭证的医保业务场景
- 符合国家医保局电子凭证技术标准

### 1.3 业务价值
- 简化患者就医流程，无需携带实体社保卡
- 提升医院服务效率和患者满意度
- 符合医保信息化发展趋势

## 2. 系统架构与集成

### 2.1 系统组件
```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   前端HIS系统   │────│  ThCardReader   │────│   江苏医保DLL   │
│                 │    │   读卡服务      │    │  HeaSecReadInfo │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │
                        ┌─────────────────┐
                        │   医保平台服务   │
                        │   (江苏省)      │
                        └─────────────────┘
```

### 2.2 集成接口
- **前端调用**: `http://localhost:8321/api/entry?param=qrcode_[业务代码]`
- **后端函数**: `EcQuery(char* pInData, char* pOutData)`
- **业务转换**: 泰和医院格式 ↔ 江苏医保格式

## 3. 电子凭证查询详细流程

### 3.1 前端发起流程

#### 3.1.1 用户操作
1. 患者打开医保电子凭证（支付宝/微信/医保APP）
2. 展示二维码供扫描设备读取
3. 操作员在HIS系统中选择"电子凭证"读卡方式
4. 系统扫描患者电子凭证二维码

#### 3.1.2 前端请求参数
```javascript
// 前端调用示例
const requestUrl = 'http://localhost:8321/api/entry?param=qrcode_01101'
// 其中 01101 为业务类型编码（门诊挂号）

axios.get(requestUrl)
  .then(response => {
    // 处理返回结果
    handleQrCodeResult(response.data)
  })
  .catch(error => {
    // 错误处理
    handleError(error)
  })
```

### 3.2 ThCardReader服务处理流程

#### 3.2.1 参数解析与验证
```csharp
// EntryController.cs 中的处理逻辑
public JObject Get(string param)
{
    // 1. 解析参数
    string[] temps = param.Split('_');
    string type = temps[0]; // qrcode
    string businessCode = temps.Length > 1 ? temps[1] : "01101";
    
    // 2. 验证业务代码
    if (!IsValidBusinessCode(businessCode)) {
        return CreateErrorResponse(1001, "无效的业务代码");
    }
    
    // 3. 调用江苏医保电子凭证查询
    return ProcessEcQuery(businessCode);
}
```

#### 3.2.2 江苏医保接口调用
```csharp
private JObject ProcessEcQuery(string businessCode)
{
    try
    {
        // 1. 构建输入参数
        var inputData = new
        {
            data = new
            {
                orgId = "[医保定点编号]",        // 定点编号
                businessType = businessCode,   // 业务类型
                operatorId = "system001",      // 操作员编号  
                operatorName = "系统管理员",    // 操作员姓名
                officeId = "32760",           // 科室编号
                officeName = GetDepartmentName(businessCode) // 科室名称
            },
            transType = "ec.query",
            orgId = "[医保定点编号]"
        };
        
        // 2. JSON序列化
        string jsonInput = JsonConvert.SerializeObject(inputData);
        
        // 3. 调用DLL函数
        StringBuilder outputBuffer = new StringBuilder(8192);
        int result = EcQuery(jsonInput, outputBuffer);
        
        // 4. 处理返回结果
        if (result == 0)
        {
            return ProcessEcQuerySuccess(outputBuffer.ToString());
        }
        else
        {
            return CreateErrorResponse(result, "电子凭证查询失败");
        }
    }
    catch (Exception ex)
    {
        return CreateErrorResponse(1001, $"电子凭证查询异常: {ex.Message}");
    }
}
```

### 3.3 数据格式转换流程

#### 3.3.1 江苏医保格式转泰和医院格式
```csharp
private JObject ProcessEcQuerySuccess(string jiangsuResponse)
{
    try
    {
        // 1. 解析江苏医保返回数据
        var jiangsuData = JsonConvert.DeserializeObject<JObject>(jiangsuResponse);
        
        if ((int)jiangsuData["code"] != 0)
        {
            return CreateErrorResponse((int)jiangsuData["code"], 
                jiangsuData["message"]?.ToString() ?? "电子凭证查询失败");
        }
        
        // 2. 提取患者信息
        var patientData = jiangsuData["data"];
        
        // 3. 转换为泰和医院期望的格式
        var taiheData = new
        {
            idNo = patientData["idNo"]?.ToString() ?? "",
            userName = patientData["userName"]?.ToString() ?? "",
            idType = patientData["idType"]?.ToString() ?? "",
            ecToken = patientData["ecToken"]?.ToString() ?? "",
            insuOrg = patientData["insuOrg"]?.ToString() ?? "",
            gender = patientData["gender"]?.ToString() ?? "",
            birthday = patientData["birthday"]?.ToString() ?? ""
        };
        
        // 4. 构建标准返回格式
        return new JObject
        {
            ["code"] = 200,
            ["message"] = "电子凭证查询成功",
            ["data"] = JsonConvert.SerializeObject(taiheData),
            ["type"] = "qrcode",
            ["device"] = "江苏医保电子凭证",
            ["originalType"] = "jiangsu_ec"
        };
    }
    catch (Exception ex)
    {
        return CreateErrorResponse(1001, $"数据转换异常: {ex.Message}");
    }
}
```

### 3.4 前端数据处理流程

#### 3.4.1 响应数据解析
```javascript
function handleQrCodeResult(response) {
    if (response.code === 200) {
        // 成功处理
        const patientInfo = JSON.parse(response.data);
        
        // 填充患者信息到表单
        fillPatientForm({
            idNo: patientInfo.idNo,
            userName: patientInfo.userName,
            gender: patientInfo.gender,
            birthday: patientInfo.birthday,
            insuOrg: patientInfo.insuOrg,
            ecToken: patientInfo.ecToken  // 保存令牌用于后续医保交易
        });
        
        // 显示成功提示
        showSuccessMessage('电子凭证读取成功');
        
    } else {
        // 错误处理
        showErrorMessage(response.message || '电子凭证读取失败');
    }
}
```

## 4. 业务场景适配

### 4.1 门诊业务流程

#### 4.1.1 挂号场景 (01101)
```
患者展示电子凭证 → 扫描二维码 → 获取患者信息 → 
自动填充挂号单 → 确认信息 → 完成挂号 → 打印凭条
```

#### 4.1.2 门诊结算场景 (01301)
```
患者展示电子凭证 → 扫描二维码 → 获取医保信息 → 
调用医保结算接口 → 使用ecToken进行认证 → 完成结算
```

### 4.2 住院业务流程

#### 4.2.1 住院建档场景 (01102)
```
患者展示电子凭证 → 扫描二维码 → 获取身份信息 → 
创建住院档案 → 绑定电子凭证 → 住院期间免卡使用
```

### 4.3 药店业务流程

#### 4.3.1 药店购药场景 (02121)
```
患者展示电子凭证 → 扫描二维码 → 验证参保信息 → 
药品销售 → 医保结算 → 完成购药
```

## 5. 错误处理与异常流程

### 5.1 常见错误场景

#### 5.1.1 网络连接错误
- **错误描述**: 无法连接江苏医保平台
- **处理方案**: 检查网络连接，重试机制，提示用户稍后重试

#### 5.1.2 二维码过期
- **错误描述**: 电子凭证二维码已过期
- **处理方案**: 提示患者刷新电子凭证，重新扫描

#### 5.1.3 参保地不匹配
- **错误描述**: 患者参保地与当前定点不匹配
- **处理方案**: 提示异地就医流程，引导办理相关手续

### 5.2 错误处理代码示例
```javascript
function handleQrCodeError(error) {
    const errorMap = {
        1001: '系统错误，请联系管理员',
        1002: '网络连接失败，请稍后重试', 
        1003: '电子凭证已过期，请刷新后重试',
        1004: '参保地不匹配，请咨询医保办'
    };
    
    const errorCode = error.code || 1001;
    const errorMessage = errorMap[errorCode] || error.message || '未知错误';
    
    // 显示用户友好的错误提示
    ElMessageBox.alert(errorMessage, '电子凭证读取失败', {
        type: 'error',
        showCancelButton: false
    });
}
```

## 6. 配置与部署

### 6.1 系统配置要求

#### 6.1.1 江苏医保DLL配置
```ini
# Config.ini 配置示例
[MEDICAL_INSURANCE]
ORG_ID=[医保定点编号]           # 定点编号
API_NAME=api-powersi-test-pri # CSB API名称
API_VERSION=1.0.0            # API版本
ACCESS_KEY=your_access_key_here
SECRET_KEY=your_secret_key_here
AREA_CODE=320100             # 行政区划代码

[NETWORK]
IP=192.168.100.100           # 服务端IP
PORT=8080                    # 服务端端口
TIMEOUT=120                  # 超时时间(秒)

[SYSTEM]
LOG_PATH=C:\\NEULOGS\\       # 日志路径
CARD_PASSTYPE=1              # 密码验证方式
```

#### 6.1.2 ThCardReader服务配置
```xml
<!-- App.config -->
<appSettings>
    <add key="JiangSuDllPath" value="HeaSecReadInfo.dll" />
    <add key="DefaultOrgId" value="[医保定点编号]" />
    <add key="DefaultOperatorId" value="system001" />
    <add key="DefaultOfficeId" value="32760" />
    <add key="LogLevel" value="Info" />
</appSettings>
```

### 6.2 部署检查清单

#### 6.2.1 环境检查
- [ ] Windows 10/11 操作系统
- [ ] .NET Framework 4.8
- [ ] 管理员权限运行
- [ ] 网络连接正常
- [ ] 端口8321未被占用

#### 6.2.2 文件检查
- [ ] ThCardReader.exe 主程序
- [ ] HeaSecReadInfo.dll 江苏医保DLL
- [ ] Config.ini 配置文件
- [ ] 相关依赖DLL文件
- [ ] 日志目录写权限

#### 6.2.3 功能测试
- [ ] 服务启动正常
- [ ] 电子凭证扫描功能
- [ ] 数据格式转换正确
- [ ] 错误处理机制
- [ ] 日志记录功能

## 7. 监控与维护

### 7.1 日志监控
- 监控电子凭证查询成功率
- 记录响应时间和性能指标
- 追踪错误发生频率和类型

### 7.2 定期维护
- 定期检查配置参数是否正确
- 更新医保平台接口信息
- 维护业务代码映射关系

### 7.3 应急处理
- 制定网络中断应急预案
- 准备备用读卡方式（实体社保卡）
- 建立技术支持联系机制

## 8. 合规与安全

### 8.1 数据安全
- 患者敏感信息加密传输
- ecToken等令牌信息安全存储
- 日志脱敏处理

### 8.2 医保合规
- 严格按照医保局规范执行
- 定期接受医保部门检查
- 保持与最新政策同步

### 8.3 技术规范
- 遵循国家医保信息化标准
- 符合江苏省医保技术要求
- 保持与平台接口版本同步