企业系统与银行核心系统的直联对接：协议差异、报文解析、适配器设计、支付状态机、安全体系与多银行管理
企业系统（ERP/司库/费控）与银行核心系统之间建立专用通信通道，让企业在自己的系统里直接完成查询、转账、对账等操作，无需登录网银。
| 功能大类 | 具体能力 | 业务场景 | 使用频率 |
|---|---|---|---|
| 账户查询 | 余额查询、当日明细、历史明细 | 资金看板、实时头寸 | 极高（实时） |
| 支付结算 | 单笔付款、批量付款、定时付款 | 集中支付、工资代发、供应商付款 | 高 |
| 收款管理 | 到账通知、收款认领、自动核销 | 收款与应收匹配 | 高 |
| 电子回单 | 获取银行电子回单（PDF/图片） | 自动归档、与业务单据匹配 | 中 |
| 资金归集 | 自动归集、自动下拨、定存 | 现金池管理 | 中 |
| 票据业务 | 电票签发、背书、贴现、托收 | 票据池、供应链金融 | 中 |
| 外汇业务 | 结汇、售汇、远期、期权 | 外汇资金管理 | 低 |
| 对账文件 | 获取银行对账单文件 | 自动对账 | 高（日终） |
| 代发业务 | 代发工资、代发奖金 | HR 系统联动 | 低（月度） |
| 授信/融资 | 查询授信额度、放款、还款 | 融资管理 | 低 |
业务层只看到"支付""查询"等统一接口，不需要知道对接的是哪家银行。适配层负责把统一接口翻译成各家银行的私有报文格式。
新增一家银行 = 新增一个 Adapter，不改动业务代码。
这是银行直连开发中最大的痛点：每家银行接口协议完全不同。
| 维度 | 差异表现 | 影响 |
|---|---|---|
| 传输协议 | HTTP/HTTPS、Socket 长连接、MQ、FTP | 适配层需要支持多种通信方式 |
| 报文格式 | XML、JSON、定长报文、ISO 8583 | 每种格式需要对应的解析器 |
| 加密方式 | RSA、SM2、DES、3DES、AES | 每家银行的密钥体系和加解密流程不同 |
| 签名方式 | 数字证书、U 盾、硬件加密机（HSM） | 签名/验签的实现路径不同 |
| 编码规则 | GBK、UTF-8、GB18030 | 报文解析时的编码转换 |
| 日期格式 | yyyyMMdd、yyyyMMddHHmmss、Unix 时间戳 | 统一时间处理 |
| 金额精度 | 分（整型）、元（2 位小数）、4 位小数 | 金额转换和精度对齐 |
| 文件格式 | CSV、TXT（定长/分隔）、Excel、PDF | 对账文件解析器 |
| 响应模式 | 同步返回、异步轮询、主动推送 | 支付状态追踪逻辑不同 |
| 错误码 | 每家银行完全不同的错误码体系 | 需要统一的错误码映射表 |
| 银行 | 传输方式 | 报文格式 | 加密 | 特点 |
|---|---|---|---|---|
| 工商银行 | HTTPS / 专线 | XML | RSA + SM2 | 接口文档相对规范，功能覆盖全面 |
| 建设银行 | HTTPS / 专线 | XML / 定长 | RSA + 3DES | 对账文件格式特殊，定长报文解析复杂 |
| 农业银行 | HTTPS / Socket | XML | RSA + SM2 | Socket 长连接模式，需维护连接池 |
| 中国银行 | HTTPS | XML / JSON | RSA | 外汇业务接口丰富 |
| 招商银行 | HTTPS | JSON | RSA | 接口设计现代，JSON 格式友好 |
| 交通银行 | HTTPS / 专线 | XML | RSA + SM4 | 国密支持较早 |
| 模式 | 说明 | 适用场景 | 状态追踪 |
|---|---|---|---|
| 同步 | 发送请求，等待银行实时返回结果 | 余额查询、单笔小额支付 | 直接根据返回码判断成功/失败 |
| 异步 | 发送请求，银行先返回受理结果，后续通知最终结果 | 大额支付、批量支付 | 需要轮询查询或等待银行主动推送 |
| 文件 | 上传/下载文件（对账单、批量明细） | 日终对账、批量代发 | 通过文件处理状态判断 |
这是银行直连最复杂的业务逻辑。一笔支付从发起到最终到账，经历多个状态转换。最棘手的是"超时未知"状态。
[初始化]
↓
[待审批] → 审批拒绝 → [已取消]
↓ 审批通过
[待发送]
↓ 发送到银行
[已发送]
↓
┌──────────────────────────────────────────┐
│ 银行处理 │
│ → 银行受理 → 交易成功 → [已到账] │
│ → 银行处理中 → 交易成功 → [已到账] │
│ → [超时未知] │
│ → 银行拒绝 → [交易失败] │
└──────────────────────────────────────────┘
场景：请求已发送到银行，但在超时时间内没有收到银行响应。钱到底扣没扣？不知道。
处理策略：
1. 主动查询：用企业流水号查询银行交易状态
2. 等待轮询：设定查询间隔（如每 30 秒查一次，最多查 N 次）
3. 人工介入：多次查询仍无法确认时，生成异常工单，人工联系银行确认
4. 幂等保护：同一笔业务不允许重复发送，必须等确认后再决定重试或取消
宁可多查，不可重发。重复付款的损失远大于查询的延迟。在超时未知状态下，绝对不能直接重发支付指令。
一个批量文件包含 N 笔支付，银行返回的是整体受理状态 + 逐笔结果：
- 文件级状态：已接收 / 处理中 / 处理完成 / 处理失败
- 明细级状态：每笔各自的成功/失败/退回
需要两层级联的状态管理：先等文件级处理完成，再逐笔更新明细状态。
企业私钥：用于签名请求报文。存储在硬件加密机（HSM）中，绝不落地明文。
银行公钥证书：用于验签银行响应报文。银行定期更换，需监控有效期。
会话密钥：部分银行使用动态会话密钥加密报文体，每次交易协商。
密钥轮换：定期更换密钥对（通常每年），旧密钥过期前完成切换。
| 实体 | 核心字段 | 说明 |
|---|---|---|
| 银行通道（BankChannel） |
银行代码、银行名称 连接方式（专线/VPN/HTTPS） 企业签约号、证书信息 IP 白名单、超时配置、重试策略 |
一家银行的一个签约关系。同一银行可能有多个签约（不同分公司）。 |
| 银行账户（BankAccount） |
账号、账户名称 账户类型（基本户/一般户/专用户/临时户） 币种（CNY/USD/EUR） 关联银行通道、签约状态 实时余额（缓存）、最后更新时间 |
企业在银行开立的账户。一个通道下可以有多个账户。 |
| 接口定义（BankInterface） |
交易代码（银行原始码） 标准交易类型（查询/支付/对账/...） 报文模板（请求/响应） 加密配置、签名配置 |
每家银行的每个交易接口定义。适配层的核心配置。 |
| 银行交易流水（BankTransaction） |
企业流水号（我方生成） 银行流水号（银行返回） 交易类型、金额、币种 交易状态、银行返回码 请求报文（原始留存） 响应报文（原始留存） 发起时间、完成时间 关联业务单据号 |
每笔与银行交互的完整记录。报文留存用于审计和排查。 |
| 对账文件（ReconciliationFile） |
文件日期、银行代码 文件类型（日终对账单/交易明细） 原始文件内容 解析状态、解析结果明细 对账结果（匹配/未匹配/差异） |
银行提供的日终对账文件。每日自动下载、解析、对账。 |
| 错误码映射（ErrorCodeMapping） |
银行代码、银行原始错误码 标准错误分类 错误描述、处理建议 |
把各银行的私有错误码统一映射到标准分类。 |
银行直连涉及多方系统，必须通过流水号串联全链路：
- 业务单号：业务系统生成（如付款申请单号）
- 支付流水号：司库/支付平台生成（一笔业务可能拆分为多笔支付）
- 企业流水号：发送给银行的唯一标识（幂等控制的关键）
- 银行流水号：银行返回的交易流水号（用于查询和追溯）
关键规则：同一笔支付，企业流水号不能变。重试必须用同一个企业流水号查询，不能生成新的。
多银行对接的核心是"统一接口 + 多适配器"。业务层不关心银行差异，适配器负责翻译。
配置驱动：报文模板、字段映射、加密配置都做成配置项，不在代码里硬编码。新增银行尽量只加配置，不改代码。
报文模板化：用模板引擎（如 Freemarker/Velocity）定义每家银行的报文格式，运行时动态填充参数。
字段映射表：统一字段名 ↔ 银行私有字段名的映射关系，存在数据库/配置文件中。
全报文留存：每笔交易的请求报文和响应报文必须完整保存，用于审计和问题排查。
内部账和银行账必须每日核对。对账不是报表，是纠偏机制。
| 对账结果 | 含义 | 处理方式 |
|---|---|---|
| 匹配成功 | 企业流水与银行流水一一对应，金额一致 | 自动确认，更新状态 |
| 企业有银行无 | 企业记录了支付，银行对账单没有 | 可能银行处理延迟 → 次日再查或人工确认 |
| 银行有企业无 | 银行有交易记录，企业没有 | 可能是银行端扣费、利息、或其他被动交易 → 自动补录 |
| 金额不一致 | 双方都有记录但金额不同 | 可能是手续费差异、汇率差异 → 人工核实 |
国密普及: 越来越多银行支持 SM2/SM3/SM4 国密算法，逐步替代 RSA/SHA-256。
API 化: 银行开放银行（Open Banking）趋势下，RESTful JSON 接口逐渐替代传统 XML 报文。
标准统一: 央行推动金融标准化，报文格式和接口规范趋向统一（但完全统一还有很长的路）。
RPA 辅助: 对于不支持直连的小银行，用 RPA 模拟网银操作获取数据，作为直连的补充。
实时对账: 从日终批量对账走向准实时对账，更快发现差异。
银企直联 SaaS: 第三方平台提供统一银企直联服务，降低中小企业的对接成本。
报文硬编码: 把报文格式写死在代码里，新增银行就要改代码、发版，维护成本指数级增长。
超时处理缺失: 没有完善的超时状态机和查询机制，积累大量悬挂交易。
密钥管理随意: 私钥明文存储在服务器上，或密钥轮换流程不健全。