# 江苏医保电子凭证解码使用手册

## 📖 文档说明

本文档基于《医疗保障信息平台定点基线版医药机构接口规范 v0.9.9.15》中的1.14.6电子凭证解码接口实现，提供完整的使用指南和调用示例。

**版本信息：**
- 接口规范版本：v0.9.9.15
- ThCardReader版本：2025.06.27
- 更新日期：2025年6月27日

## 🚀 快速开始

### 1. 环境要求

- **操作系统**: Windows 10/11
- **运行环境**: .NET Framework 4.8
- **必需DLL**: HeaSecReadInfo.dll
- **服务端口**: 8321 (HTTP服务)

### 2. 服务启动

确保ThCardReader服务已启动：
```bash
# 方式1: 直接运行exe文件
ThCardReader.exe

# 方式2: 使用启动脚本
启动服务.bat
```

服务启动成功后，在浏览器访问：
```
http://localhost:8321/api/entry?param=test
```

## 🔗 接口调用

### 1. 基本调用格式

```
http://localhost:8321/api/entry?param=jiangsu_qrcode_[业务类型]
```

### 2. 支持的业务类型

| 业务代码 | 业务名称 | 应用场景 | 科室 |
|---------|----------|----------|------|
| **门诊业务** | | | |
| 01101 | 门诊挂号 | 患者挂号登记 | 挂号处 |
| 01201 | 门诊问诊 | 医生问诊记录 | 门诊科室 |
| 01202 | 预约检查 | 检查预约登记 | 门诊科室 |
| 01203 | 检查 | 各类医学检查 | 门诊科室 |
| 01204 | 治疗 | 医疗治疗服务 | 门诊科室 |
| 01301 | 门诊结算 | 门诊费用结算 | 门诊收费处 |
| 01302 | 取药 | 药房取药服务 | 门诊药房 |
| **住院业务** | | | |
| 01102 | 住院建档 | 住院患者建档 | 住院处 |
| 01103 | 入院登记 | 住院登记手续 | 住院处 |
| 01104 | 缴纳预缴金 | 住院预缴费用 | 住院处 |
| **药店业务** | | | |
| 02121 | 药店购药 | 药店零售服务 | 药店 |
| 02122 | 下载外购处方 | 处方下载服务 | 药店 |

### 3. 常用调用示例

```bash
# 门诊挂号（最常用）
http://localhost:8321/api/entry?param=jiangsu_qrcode_01101

# 门诊结算
http://localhost:8321/api/entry?param=jiangsu_qrcode_01301

# 药店购药
http://localhost:8321/api/entry?param=jiangsu_qrcode_02121

# 住院建档
http://localhost:8321/api/entry?param=jiangsu_qrcode_01102
```

## 💻 前端集成

### 1. 基础JavaScript调用

```javascript
/**
 * 调用江苏医保电子凭证解码
 * @param {string} businessType - 业务类型代码 (如: '01101')
 * @returns {Promise<Object>} - 解码结果
 */
async function callJiangsuEcDecode(businessType) {
    const url = `http://localhost:8321/api/entry?param=jiangsu_qrcode_${businessType}`;
    
    try {
        const response = await fetch(url);
        const result = await response.json();
        
        if (result.code === 200 && result.success !== false) {
            console.log('电子凭证解码成功:', result);
            return {
                success: true,
                data: result
            };
        } else {
            console.error('电子凭证解码失败:', result.message);
            return {
                success: false,
                error: result.message,
                code: result.code
            };
        }
    } catch (error) {
        console.error('调用异常:', error);
        return {
            success: false,
            error: `网络异常: ${error.message}`
        };
    }
}

// 使用示例
async function handleRegistration() {
    const result = await callJiangsuEcDecode('01101');
    if (result.success) {
        const patientData = JSON.parse(result.data.data);
        console.log('患者信息:', patientData);
        // 处理患者信息...
    } else {
        alert('读卡失败: ' + result.error);
    }
}
```

### 2. 完整的前端工具类

```javascript
/**
 * 江苏医保电子凭证解码工具类
 */
class JiangsuEcReader {
    constructor(baseUrl = 'http://localhost:8321/api/entry') {
        this.baseUrl = baseUrl;
        this.businessTypes = {
            REGISTRATION: '01101',      // 门诊挂号
            CONSULTATION: '01201',      // 门诊问诊
            SETTLEMENT: '01301',        // 门诊结算
            PHARMACY: '01302',          // 取药
            INPATIENT_FILE: '01102',    // 住院建档
            INPATIENT_REGISTER: '01103', // 入院登记
            PREPAYMENT: '01104',        // 缴纳预缴金
            STORE_PHARMACY: '02121',    // 药店购药
            PRESCRIPTION: '02122'       // 下载外购处方
        };
    }
    
    /**
     * 门诊挂号
     */
    async registration() {
        return await this.callEcDecode(this.businessTypes.REGISTRATION);
    }
    
    /**
     * 门诊结算
     */
    async settlement() {
        return await this.callEcDecode(this.businessTypes.SETTLEMENT);
    }
    
    /**
     * 药店购药
     */
    async pharmacy() {
        return await this.callEcDecode(this.businessTypes.STORE_PHARMACY);
    }
    
    /**
     * 住院建档
     */
    async inpatientFile() {
        return await this.callEcDecode(this.businessTypes.INPATIENT_FILE);
    }
    
    /**
     * 通用电子凭证解码方法
     * @param {string} businessType - 业务类型
     * @returns {Promise<Object>} - 标准化的结果对象
     */
    async callEcDecode(businessType) {
        const url = `${this.baseUrl}?param=jiangsu_qrcode_${businessType}`;
        
        try {
            const response = await fetch(url);
            const result = await response.json();
            
            if (result.code === 200) {
                // 解析患者信息
                const patientData = JSON.parse(result.data);
                
                return {
                    success: true,
                    patientInfo: {
                        idNo: patientData.idNo || '',                    // 身份证号
                        userName: patientData.userName || '',            // 姓名
                        idType: patientData.idType || '',               // 证件类型
                        ecToken: patientData.ecToken || '',             // 电子凭证令牌
                        insuOrg: patientData.insuOrg || '',             // 参保地区编码
                        ecIndexNo: patientData.ecIndexNo || '',         // 电子凭证索引号
                        gender: patientData.gender || '',               // 性别
                        birthday: patientData.birthday || '',           // 出生日期
                        nationality: patientData.nationality || '',     // 国籍
                        email: patientData.email || '',                 // 邮箱
                        extra: patientData.extra || ''                  // 扩展参数
                    },
                    businessType: result.businessType,
                    timestamp: result.timestamp,
                    device: result.device,
                    interfaceVersion: result.interfaceVersion,
                    originalData: result
                };
            } else {
                return {
                    success: false,
                    error: result.message || '电子凭证解码失败',
                    code: result.code,
                    suggestion: result.suggestion || '',
                    device: result.device || '江苏医保电子凭证解码器'
                };
            }
        } catch (error) {
            return {
                success: false,
                error: `网络异常: ${error.message}`,
                code: -1
            };
        }
    }
    
    /**
     * 检查服务状态
     */
    async checkStatus() {
        try {
            const response = await fetch(`${this.baseUrl}?param=jiangsu_status`);
            const result = await response.json();
            return result.success === true;
        } catch (error) {
            return false;
        }
    }
    
    /**
     * 系统初始化
     */
    async initialize() {
        try {
            const response = await fetch(`${this.baseUrl}?param=jiangsu_init`);
            const result = await response.json();
            return result;
        } catch (error) {
            return {
                success: false,
                error: `初始化失败: ${error.message}`
            };
        }
    }
}

// 使用示例
const ecReader = new JiangsuEcReader();

// 门诊挂号示例
ecReader.registration().then(result => {
    if (result.success) {
        console.log('患者姓名:', result.patientInfo.userName);
        console.log('身份证号:', result.patientInfo.idNo);
        console.log('参保地:', result.patientInfo.insuOrg);
    } else {
        console.error('读卡失败:', result.error);
        if (result.suggestion) {
            console.log('建议:', result.suggestion);
        }
    }
});
```

### 3. Vue.js 集成示例

```javascript
// Vue 组件示例
export default {
    name: 'JiangsuEcReader',
    data() {
        return {
            loading: false,
            patientInfo: null,
            error: null
        };
    },
    methods: {
        async readElectronicCertificate(businessType = '01101') {
            this.loading = true;
            this.error = null;
            
            try {
                const url = `http://localhost:8321/api/entry?param=jiangsu_qrcode_${businessType}`;
                const response = await this.$http.get(url);
                
                if (response.data.code === 200) {
                    const patientData = JSON.parse(response.data.data);
                    this.patientInfo = {
                        name: patientData.userName,
                        idCard: patientData.idNo,
                        gender: patientData.gender === '1' ? '男' : '女',
                        birthday: patientData.birthday,
                        insuranceArea: patientData.insuOrg,
                        ecToken: patientData.ecToken
                    };
                    this.$message.success('电子凭证读取成功');
                } else {
                    this.error = response.data.message;
                    this.$message.error('读卡失败: ' + this.error);
                }
            } catch (error) {
                this.error = '网络异常: ' + error.message;
                this.$message.error(this.error);
            } finally {
                this.loading = false;
            }
        }
    }
};
```

## 📊 返回数据格式

### 1. 成功响应

```json
{
  "code": 200,
  "message": "江苏医保电子凭证解码成功",
  "device": "江苏医保电子凭证解码器",
  "type": "qrcode",
  "originalType": "jiangsu_ec",
  "timestamp": "2025-06-27 10:30:00",
  "data": "{\"idNo\":\"320829199303301612\",\"userName\":\"张三\",\"idType\":\"01\",\"ecToken\":\"abc123456\",\"insuOrg\":\"320100\",\"ecIndexNo\":\"EC20250627001\",\"gender\":\"1\",\"birthday\":\"1993-03-30\",\"nationality\":\"156\",\"email\":\"\",\"extra\":\"{}\"}",
  "readCardResult": "{\"idNo\":\"320829199303301612\",\"userName\":\"张三\",\"idType\":\"01\",\"ecToken\":\"abc123456\",\"insuOrg\":\"320100\",\"ecIndexNo\":\"EC20250627001\",\"gender\":\"1\",\"birthday\":\"1993-03-30\",\"nationality\":\"156\",\"email\":\"\",\"extra\":\"{}\"}",
  "businessType": "01101",
  "interfaceVersion": "v0.9.9.15",
  "jiangsuOriginalData": "{\"code\":0,\"message\":\"success\",\"data\":{...}}"
}
```

### 2. 患者信息字段说明

| 字段名 | 类型 | 说明 | 示例值 |
|--------|------|------|--------|
| idNo | string | 身份证号 | "320829199303301612" |
| userName | string | 姓名 | "张三" |
| idType | string | 证件类型 | "01"(身份证) |
| ecToken | string | 电子凭证令牌 | "abc123456" |
| insuOrg | string | 参保地区编码 | "320100" |
| ecIndexNo | string | 电子凭证索引号 | "EC20250627001" |
| gender | string | 性别 | "1"(男)/"2"(女) |
| birthday | string | 出生日期 | "1993-03-30" |
| nationality | string | 国籍 | "156"(中国) |
| email | string | 邮箱 | "" |
| extra | string | 扩展参数 | "{}" |

### 3. 失败响应

```json
{
  "success": false,
  "code": 1001,
  "message": "江苏医保电子凭证业务类型【99999】无效！支持的业务类型：01101(门诊挂号)、01301(门诊结算)、02121(药店购药)等",
  "type": "qrcode",
  "device": "江苏医保电子凭证解码器"
}
```

### 4. 错误码说明

| 错误码范围 | 说明 | 处理建议 |
|-----------|------|----------|
| 1xxx | 系统级错误 | 检查初始化、配置、DLL文件 |
| 2xxx | 江苏医保接口错误 | 检查网络、认证、参数格式 |
| 3xxx | DLL调用错误 | 检查DLL文件、设备连接 |

## 🔧 系统管理

### 1. 服务状态检查

```javascript
// 检查江苏医保服务状态
async function checkJiangsuStatus() {
    const response = await fetch('http://localhost:8321/api/entry?param=jiangsu_status');
    const result = await response.json();
    return result.success;
}
```

### 2. 系统初始化

```javascript
// 手动初始化江苏医保系统
async function initializeJiangsu() {
    const response = await fetch('http://localhost:8321/api/entry?param=jiangsu_init');
    const result = await response.json();
    return result;
}
```

### 3. DLL文件检查

```javascript
// 检查DLL文件是否存在
async function checkDllFiles() {
    const response = await fetch('http://localhost:8321/api/entry?param=jiangsu_checkdll');
    const result = await response.json();
    return result;
}
```

## ⚠️ 注意事项

### 1. 环境要求

- **服务启动**: 确保ThCardReader.exe已启动并运行在8321端口
- **DLL文件**: 确保HeaSecReadInfo.dll文件存在于程序目录
- **网络连接**: 确保能够访问江苏医保服务器
- **防火墙**: 确保8321端口未被防火墙阻止

### 2. 配置要求

在实际使用前，需要正确配置以下参数：
- **ORG_ID**: 医疗机构的定点编号
- **ACCESS_KEY**: 江苏医保分配的访问密钥
- **SECRET_KEY**: 江苏医保分配的密钥
- **服务器地址**: 江苏医保服务器IP和端口

### 3. 业务规范

- **业务类型**: 只能使用江苏医保规范定义的业务类型代码
- **操作员信息**: 建议根据实际情况设置操作员ID和姓名
- **科室信息**: 系统会根据业务类型自动匹配科室名称

### 4. 错误处理

```javascript
// 推荐的错误处理方式
async function handleEcDecode(businessType) {
    try {
        const result = await callJiangsuEcDecode(businessType);
        
        if (result.success) {
            // 成功处理
            return result.data;
        } else {
            // 错误处理
            switch (result.code) {
                case 1002:
                    console.log('系统未初始化，尝试自动初始化');
                    break;
                case 1001:
                    console.log('业务类型无效:', businessType);
                    break;
                default:
                    console.log('未知错误:', result.error);
            }
            return null;
        }
    } catch (error) {
        console.error('调用异常:', error);
        return null;
    }
}
```

## 🧪 测试验证

### 1. 使用测试页面

```bash
# 打开测试页面
test_jiangsu_ec_decode.html
```

### 2. 浏览器测试

```bash
# 直接在浏览器访问
http://localhost:8321/api/entry?param=jiangsu_qrcode_01101
```

### 3. 命令行测试

```bash
# 使用curl测试
curl "http://localhost:8321/api/entry?param=jiangsu_qrcode_01101"
```

## 📞 技术支持

### 1. 常见问题

**Q: 调用返回"系统未初始化"错误？**
A: 系统会自动初始化，如果仍有问题，请检查DLL文件和网络连接。

**Q: 返回"业务类型无效"错误？**
A: 请使用规范定义的业务类型代码，参考本文档的业务类型表。

**Q: 网络连接失败？**
A: 请检查江苏医保服务器地址和网络连接状态。

### 2. 日志查看

日志文件位置：
```
logs/江苏医保读卡日志_YYYYMMDD.log
```

### 3. 联系方式

如遇技术问题，请参考：
- 接口规范文档：《医疗保障信息平台定点基线版医药机构接口规范 v0.9.9.15》
- 实现说明文档：`江苏医保电子凭证解码功能实现说明.md`

---

**文档版本**: v1.0  
**最后更新**: 2025年6月27日  
**适用版本**: ThCardReader v2025.06.27