fujian_water_biz_doc/specs/010-bank-transfer-config/contracts/bank-transfer-resolution-contract.md

Contract: 银行文件传输统一解析合同

目标

定义文件动作在运行时如何根据上下文解析最终协议、目录和路径，作为 backend 统一解析器与验证工件的判定依据。

输入上下文

统一解析器至少接收以下字段：

• tenantId
• companyId
• channelId
• channelCode
• businessType
• stage
• businessDate
• batchNo
• fileName

其中 stage 取值范围为：

• SEND
• BACK
• RECONCILE
• ARCHIVE
• LOCAL_TEMP

作用域优先级

命中顺序固定为：

TENANT_CHANNEL > TENANT > CHANNEL > DEFAULT

字段级回退规则

• 更高优先级作用域可以只覆盖部分字段
• 未覆盖字段必须回退到下一级有效配置
• 不允许因为局部缺失而直接生成空路径

协议切换规则

• 同一业务动作应由统一解析结果决定最终协议
• 业务代码不再自行判断 SFTP/FTP
• 配置变更仅影响新发起文件动作
• 已开始或已落库批次继续沿用原解析结果
• 对已创建代扣批次，送盘阶段预解析并固化的回盘目录/协议不得因后续配置切换而漂移

失败规则

遇到以下任一条件时，系统必须立即阻断当前文件动作并返回可诊断错误：

• 未命中任何有效配置
• 当前协议缺少必要连接信息
• 当前阶段目录解析为空
• 模板使用了未声明变量

审计输出

统一解析结果至少输出：

• protocol
• host
• port
• username
• credentialRef
• resolvedDir
• resolvedPath
• fileName
• sourceScope

说明：

• 本轮只强制保存最终实际使用的协议、目录、路径、文件名
• 不强制保存配置版本号或完整配置快照

批次对象映射

• WithholdingBatchDO：承接送盘/回盘的最终协议、目录、路径、文件名
• ReconcileBatchDO：承接对账文件的最终协议、目录、路径、文件名

最小验证场景

1. 默认规则命中
2. 租户覆盖命中
3. 通道覆盖命中
4. 租户-通道覆盖命中
5. 字段级回退
6. 协议切换
7. 配置缺失失败
8. 非法模板变量失败
9. 已落库批次配置切换后继续沿用原回盘目录