4. 医保接口适配与协议转换

医保接口适配与协议转换，是医疗支付平台能否稳定接入医保核心系统、移动支付中心和处方流转平台的关键工程环节。国家医保局接口规范通常以统一报文格式、统一交易编码、统一安全机制为约束，但医院内部系统、第三方支付渠道、处方流转平台各自的数据模型、通信协议和字段语义并不一致。适配层的职责，不是简单转发请求，而是把外部标准协议翻译成内部可执行的服务调用，再把内部结果反向封装成符合医保规范的响应。

一、三类对接对象的差异

医保核心系统一般通过国家或省级医保平台暴露 HTTP/HTTPS 接口，采用 JSON 或 XML 报文，要求商户号、终端号、医保结算 ID、人员编号、险种类型、医疗类别等字段严格符合规范。移动支付中心更关注支付订单、退款、对账和渠道回调，常用 RESTful 接口与异步通知，字段围绕交易流水、支付渠道、金额、状态展开。处方流转平台则围绕处方编号、药品明细、开方机构、审方状态、取药方式组织数据，强调处方状态机和流转轨迹。

三者虽然都涉及“交易”，但主键、状态语义和幂等策略不同。例如医保核心系统的“结算”以医保结算 ID 为主键，移动支付中心以支付订单号为主键，处方流转平台以处方编号为主键。适配层必须建立统一内部模型，把外部标识映射为平台内部业务主键，并维护映射关系表，避免同一笔业务在不同系统中被重复处理。

二、适配层的核心转换机制

适配层通常由协议接入网关、字段映射引擎、路由与幂等控制器、统一内部服务模型四部分组成。协议接入网关负责 HTTPS 通信、签名验签、报文解析和限流；字段映射引擎负责把外部字段翻译为内部字段；路由与幂等控制器根据业务类型选择目标服务，并保证同一请求只被处理一次；统一内部服务模型则把结算、支付、处方三类业务抽象为平台可复用的领域对象。

以医保结算为例，外部请求可能包含 mdtrt_id、psn_no、insutype、med_type、fee_amt 等字段。适配层需要把 mdtrt_id 映射为内部就诊流水号，把 psn_no 映射为患者主索引，把 insutype 转换为平台险种编码，把 fee_amt 从元转换为分。若外部金额单位是元且保留两位小数，内部统一用整数分存储，避免浮点误差。

状态转换同样关键。医保核心系统可能返回“结算成功”“结算失败”“待确认”等状态，移动支付中心可能返回“支付成功”“支付中”“已退款”，处方流转平台可能返回“已开方”“已审方”“已取药”。适配层需要把这些状态归一为平台统一状态机，例如“待支付—支付中—已支付—已退款—已关闭”，并保留原始状态码用于审计。

三、幂等与重试设计

医保交易对幂等要求极高。同一笔结算请求因网络超时被重复提交时，不能产生两次结算。适配层通常以“业务类型 + 外部主键 + 操作类型”生成幂等键，写入 Redis 或数据库唯一索引。若幂等键已存在且请求参数一致，直接返回首次处理结果；若参数不一致，则拒绝并记录冲突日志。

重试策略需要区分可重试与不可重试异常。网络超时、连接拒绝、限流等属于可重试异常，可采用指数退避重试，例如首次 1 秒、第二次 2 秒、第三次 4 秒，最多 3 次。参数校验失败、签名错误、业务规则拒绝等属于不可重试异常，应立即返回错误，避免无效重试放大系统压力。

四、配置示例与结果判断

下面给出一个适配层字段映射配置片段，用于说明医保结算请求到内部服务的转换规则。该配置为教学示例，实际字段以国家医保局最新接口规范为准。

{
  "adapter": "medical-insurance",
  "version": "v1.0",
  "mappings": [
    {"source": "mdtrt_id", "target": "visitNo", "type": "string"},
    {"source": "psn_no", "target": "patientId", "type": "string"},
    {"source": "insutype", "target": "insuranceType", "type": "code",
     "dict": {"310": "职工医保", "390": "居民医保"}},
    {"source": "med_type", "target": "medicalCategory", "type": "code",
     "dict": {"11": "普通门诊", "21": "普通住院"}},
    {"source": "fee_amt", "target": "totalAmount", "type": "money",
     "unit": "yuan_to_cent"}
  ],
  "idempotentKey": "medical-insurance:{mdtrt_id}:settle",
  "retry": {"maxAttempts": 3, "backoff": "exponential", "baseDelayMs": 1000}
}

判断适配是否成功，可以观察三个结果：第一，内部服务是否收到符合领域模型的请求，字段类型和编码是否正确；第二，幂等键是否生效，重复请求是否返回同一结果；第三，异常码是否被正确转换，例如医保返回“人员信息不存在”时，平台是否转换为可读的业务错误并记录原始报文。若这三个结果都符合预期，说明适配层基本可用。

五、协议转换的边界与治理

协议转换不是无限兼容。适配层应明确支持的国家医保接口版本、报文格式和交易类型，超出范围的请求直接拒绝并提示升级。每次医保规范升级，应先更新字段映射字典和状态码对照表，再通过回归测试验证结算、退款、对账三条主链路。对于移动支付中心和处方流转平台，同样需要维护各自的适配版本和兼容矩阵，避免一个渠道变更影响全局。

从工程实践看，适配层最好独立部署，与业务服务解耦。这样医保接口变更时，只需调整适配层配置和转换逻辑，不必改动结算、支付、处方等核心服务。适配层还应提供健康检查、流量监控和熔断降级能力，当医保核心系统响应变慢时，及时保护平台内部服务不被拖垮。