# 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. 已落库批次配置切换后继续沿用原回盘目录