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