4. 文件生成方法

付款文件生成不是“把数据导出成文件”这么简单。银行对付款文件的格式、字段顺序、金额精度、字符集、校验位都有严格要求，任何一个环节出错都可能导致整批付款被退回。本节围绕数据准备、模板设计、批量生成、校验规则四个环节，讲清一条可落地、可复用的文件生成流水线。

一、核心原理：文件生成是一条“数据→模板→实例→校验”的流水线

付款文件本质上是结构化数据在固定契约下的序列化结果。所谓契约，就是银行接口规范：哪些字段必填、字段长度多少、金额保留几位小数、日期用什么格式、收款账号是否允许空格。文件生成方法的核心，就是把业务数据按契约映射到模板，再批量实例化，最后用校验规则兜底。

这条流水线有三个关键特征：

• 单向性：数据准备不通过，模板再漂亮也没用；模板字段错位，批量生成只会批量出错。
• 可重复性：同一批数据、同一模板、同一规则，必须生成完全一致的文件，便于对账和审计。
• 可拦截性：校验规则要在文件发送前拦截问题，而不是等银行退回后再人工排查。

二、数据准备：把“业务数据”变成“可生成数据”

数据准备阶段的目标是输出一张字段齐全、类型正确、无脏数据的中间表。常见来源包括 ERP 应付模块、财务系统付款申请单、Excel 手工台账。无论来源如何，都要完成以下动作：

1. 字段映射：把业务字段映射到银行字段。例如“收款方名称”对应“收款人名称”，“开户行”需要拆分为“开户行行号”和“开户行名称”。
2. 类型清洗：金额统一为 Decimal，账号去除空格和连字符，日期统一为 YYYYMMDD。
3. 空值处理：必填字段为空直接标记为错误行，不允许用默认值静默填充。
4. 去重与合并：同一收款账号、同一金额、同一日期的重复付款要合并或拦截。

下面是一个数据准备后的中间表示例（JSON 片段），字段名已按银行规范对齐：

{
  "batch_no": "PAY20250612001",
  "payer_account": "6222020200112233445",
  "payer_name": "某某科技有限公司",
  "pay_date": "20250612",
  "total_count": 3,
  "total_amount": "15800.00",
  "details": [
    {"seq": 1, "payee_account": "6217000010001234567", "payee_name": "张三", "amount": "5000.00", "bank_code": "102100099996"},
    {"seq": 2, "payee_account": "6228480402567890123", "payee_name": "李四", "amount": "6800.00", "bank_code": "103100000026"},
    {"seq": 3, "payee_account": "6212260200098765432", "payee_name": "王五", "amount": "4000.00", "bank_code": "105100000017"}
  ]
}

三、模板设计：固定契约与可变占位分离

模板设计的核心思想是把银行契约固化下来，把业务数据留成占位符。模板通常分为三类：

模板类型	典型格式	适用场景	设计要点
定长文本模板	.txt / .dat	人行大小额、部分银企直连	字段定长、右补空格或左补零，严禁中文全角
分隔符模板	.csv / .txt	批量代发、内部过渡文件	分隔符不能出现在字段值中，需转义或拦截
结构化模板	.xml / .json	现代银企直连、API 对接	标签名、命名空间、编码必须与接口文档一致

以定长文本为例，模板中每一行代表一条明细，字段按固定宽度拼接。设计时要特别注意：金额字段通常要求“左补零、右对齐”，账号字段要求“右补空格、左对齐”，两者方向相反，极易写错。

# 定长模板字段定义（示例）
字段          起始位  长度  对齐方式  填充字符
交易序号      1       6     右对齐    0
收款账号      7       32    左对齐    空格
收款人名称    39      60    左对齐    空格
金额          99      15    右对齐    0
开户行行号    114     12    左对齐    空格

四、批量生成：从模板到文件实例

批量生成阶段要做的是循环渲染 + 汇总计算 + 文件落盘。推荐流程如下：

1. 读取中间表，按批次号分组。
2. 计算批次汇总：总笔数、总金额、最大金额、最小金额。
3. 逐行渲染模板，生成明细行。
4. 拼接文件头、明细、文件尾，写入目标文件。
5. 记录生成日志：文件名、批次号、笔数、金额、生成时间、操作人。

批量生成最容易出问题的地方是汇总金额与明细金额不一致。因此生成后必须立即做一次“自校验”：文件尾的总金额是否等于所有明细金额之和，总笔数是否等于明细行数。

# 生成日志示例
2025-06-12 10:23:01 INFO  batch=PAY20250612001 file=pay_20250612001.txt
2025-06-12 10:23:01 INFO  detail_count=3 total_amount=15800.00
2025-06-12 10:23:01 INFO  self_check=passed
2025-06-12 10:23:01 INFO  md5=8f14e45fceea167a5a36dedd4bea2543

五、校验规则：发送前的最后一道闸门

校验规则分为单字段校验、跨字段校验、批次级校验三层。建议按以下清单逐项落实：

• 单字段：必填非空、长度合规、字符集合规、金额大于 0、账号仅数字。
• 跨字段：收款账号与开户行行号匹配、付款账号与付款人名称匹配、金额精度一致。
• 批次级：总笔数与明细行数一致、总金额与明细合计一致、批次号唯一、文件大小未超限。
• 业务级：收款人是否在黑名单、是否超过单笔限额、是否重复付款。

校验失败时，不要只抛一个“文件生成失败”，而要输出可定位的错误清单：行号、字段名、错误原因、原始值。这样业务人员才能快速修正后重新生成。

# 校验错误清单示例
行号  字段        错误原因              原始值
2     收款账号    长度不足 19 位        621700001000123
5     金额        金额必须大于 0         0.00
8     开户行行号  行号不存在             999999999999

六、案例复盘：一次批量代发失败的原因分析

某公司使用定长文本模板生成代发工资文件，银行退回提示“文件格式错误”。排查后发现三个问题叠加：

1. 模板中金额字段设计为左对齐，实际银行要求右对齐左补零。
2. 部分收款人姓名包含生僻字，文件编码用了 GBK，但银行要求 UTF-8。
3. 文件尾总金额用浮点数计算，与明细合计存在 0.01 元尾差。

复盘结论：模板设计必须以银行接口文档为唯一依据，不能凭经验假设；编码和金额精度要在数据准备阶段就统一；校验规则要覆盖“格式、编码、金额”三类高频问题。把这三类规则前置到生成环节，才能把退回率降到最低。

把上述四个环节固化为标准作业流程后，付款文件生成就从“每次手工拼文件”变成“可重复、可校验、可追溯”的工程化能力。下一批付款到来时，你只需要关注数据本身，而不是反复调试文件格式。