江苏医保接口autoInit参数使用说明

概述

为江苏医保接口新增了 autoInit 可选参数，实现智能化初始化功能，让接口使用更加便捷，同时保持向后兼容性。

新增功能

ReadSocialCard方法签名更新

// 旧版本
public static JObject ReadSocialCard(bool autoVerifyPIN = false)

// 新版本
public static JObject ReadSocialCard(bool autoVerifyPIN = false, bool autoInit = false)

autoInit参数说明

类型: bool
默认值: false（保持向后兼容）
作用: 控制是否自动处理初始化逻辑

使用模式

1. 严格模式（默认，向后兼容）

// autoInit = false（默认）
var result = JiangSuSocialCardBusiness.ReadSocialCard(false, false);
// 或者简写（利用默认参数）
var result = JiangSuSocialCardBusiness.ReadSocialCard();

特点：

要求用户先调用 Initialize() 方法初始化
如果未初始化，返回错误码 1002
保持原有严格的RESTful API设计
返回详细的错误提示和建议

返回示例（未初始化时）：

{
  "success": false,
  "code": 1002,
  "message": "江苏医保系统未初始化，请先调用初始化接口",
  "device": "江苏医保社保卡读卡器",
  "interface": "江苏医保接口 v0.9.9.15",
  "interfaceType": "medical",
  "initMode": "strict",
  "suggestion": "请先调用 Initialize() 方法或设置 autoInit=true 启用自动初始化"
}

2. 智能模式（新增功能）

// autoInit = true
var result = JiangSuSocialCardBusiness.ReadSocialCard(false, true);

特点：

自动检测初始化状态
如果未初始化，自动调用 Initialize() 方法
使用默认配置进行初始化
用户友好的智能设计

返回示例（自动初始化成功）：

{
  "success": true,
  "code": 200,
  "message": "社保卡读取成功",
  "device": "江苏医保社保卡读卡器",
  "interface": "江苏医保接口 v0.9.9.15",
  "interfaceType": "medical",
  "initMode": "auto",
  "autoInitSuccess": true,
  "data": { /* 社保卡数据 */ }
}

返回示例（自动初始化失败）：

{
  "success": false,
  "code": 1002,
  "message": "江苏医保系统自动初始化失败，请检查设备连接",
  "device": "江苏医保社保卡读卡器",
  "interface": "江苏医保接口 v0.9.9.15",
  "interfaceType": "medical",
  "initMode": "auto",
  "autoInitError": "具体初始化失败原因"
}

HTTP接口支持

GET方法新增路由

# 新增的自动初始化路由
GET /readcard/jiangsu/readcard_auto         # autoInit=true, autoVerifyPIN=false
GET /readcard/jiangsu/readcard_auto_pin     # autoInit=true, autoVerifyPIN=true

# 原有路由（保持向后兼容）
GET /readcard/jiangsu/readcard              # autoInit=false, autoVerifyPIN=false
GET /readcard/jiangsu/readcard_pin          # autoInit=false, autoVerifyPIN=true

POST方法参数

{
  "action": "readcard",
  "autoVerifyPIN": false,
  "autoInit": true
}

测试界面更新

江苏医保卡测试按钮

原功能: 测试江苏医保接口的自动初始化功能
当前行为: 点击按钮使用 autoInit=true 模式
显示信息: 清楚标注使用的初始化模式和参数

请求参数显示

{
  "action": "ReadSocialCard",
  "device": "江苏医保HeaSecReadInfo.dll",
  "interface": "江苏医保接口 v0.9.9.15",
  "autoInit": true,
  "autoVerifyPIN": false,
  "mode": "智能模式（支持自动初始化）",
  "note": "测试新增的autoInit参数，自动处理初始化逻辑"
}

设计理念对比

江苏医保接口（严格模式）

设计理念: RESTful API最佳实践
初始化: 显式初始化，分离关注点
适用场景: 企业级应用，需要精确控制初始化时机
优点: 清晰的状态管理，便于错误处理

江苏医保接口（智能模式）

设计理念: 用户友好，开箱即用
初始化: 智能自动化，降低使用门槛
适用场景: 快速集成，简单应用
优点: 减少用户代码，提高开发效率

江苏人社接口（默认智能）

设计理念: 人社部标准，智能化优先
初始化: 默认自动初始化
适用场景: 标准化集成
优点: 符合行业标准，使用简单

代码示例

示例1：保持原有用法（严格模式）

// 1. 显式初始化
var initResult = JiangSuSocialCardBusiness.Initialize();
if (!(bool)initResult["success"]) {
    // 处理初始化失败
    return;
}

// 2. 读取社保卡
var readResult = JiangSuSocialCardBusiness.ReadSocialCard(false);

示例2：使用新的智能模式

// 一步完成：自动初始化 + 读卡
var readResult = JiangSuSocialCardBusiness.ReadSocialCard(false, true);

// 检查结果
if ((bool)readResult["success"]) {
    // 读卡成功
    var cardData = readResult["data"];
    
    // 检查是否进行了自动初始化
    if (readResult["autoInitSuccess"] != null) {
        Console.WriteLine("已自动完成初始化");
    }
} else {
    // 处理失败情况
    Console.WriteLine($"读卡失败: {readResult["message"]}");
}

示例3：HTTP调用

// 严格模式
fetch('/readcard/jiangsu/readcard')

// 智能模式
fetch('/readcard/jiangsu/readcard_auto')

// POST方式（智能模式）
fetch('/readcard/jiangsu', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        action: 'readcard',
        autoInit: true,
        autoVerifyPIN: false
    })
})

技术实现细节

初始化共享状态

private static bool isInitialized = false;
private static JiangSuConfig currentConfig = null;

江苏医保和江苏人社接口共享初始化状态
一次初始化，两种接口都可使用
使用相同的HeaSecReadInfo.dll和配置参数

自动初始化逻辑

if (!isInitialized && autoInit) {
    var autoInitResult = Initialize();
    if (!(bool)autoInitResult["success"]) {
        // 返回自动初始化失败的详细信息
        result["autoInitError"] = autoInitResult["message"];
        result["initMode"] = "auto";
        return result;
    } else {
        result["autoInitSuccess"] = true;
        result["initMode"] = "auto";
    }
}

响应数据标记

所有响应都包含以下标记字段：

interface: "江苏医保接口 v0.9.9.15"
interfaceType: "medical"
initMode: "strict" | "auto" | "manual"

向后兼容性

✅ 完全向后兼容

原有代码无需修改
原有HTTP接口正常工作
默认参数保持原有行为
新功能为可选增强

总结

通过新增 autoInit 参数，江苏医保接口现在提供了两种使用模式：

严格模式（默认）：保持原有RESTful设计，向后兼容
智能模式（可选）：自动化初始化，降低使用门槛

用户可以根据自己的需求选择合适的模式，既保证了企业级应用的严格性，又提供了快速集成的便利性。

江苏医保autoInit参数使用说明.md 7.0 KB Cronologia Originale