4.9 KiB
4.9 KiB
Research: sw-business-bank 银行代扣文件传输配置能力
研究目标
本轮研究只解决“配置承接 + 统一解析 + 审计落点 + 文档闭环”，不把真实银行生产联调、完整 SFTP/FTP 客户端接入或私有文件报文解析扩展进当前范围。
基线与现状
- backend 基线固定为：
water-backendbranch001-sys009-withholding-closure@84493513c1d06936210ab7e697985d38958ba5ee - 当前
BankWithholdingServiceImpl在业务方法内硬编码生成送盘、回盘、对账路径，未复用统一解析层。 - 当前批次对象已能保存送盘/回盘/对账文件名与路径，但未统一保存协议与目录。
- 当前配置加载已沿用 Spring profile + Nacos 导入方式，可承接环境级默认规则。
ChannelApiConfigDO.extParams已存在但当前为空对象，可作为银行通道级覆盖配置的最小 carrier。
现有实现问题归纳
- 路径硬编码散落在
BankWithholdingServiceImpl中，无法支撑运行时切换。 - 送盘、回盘、对账各自拼接路径，缺少统一优先级与字段级回退规则。
- 审计仅留存文件名与路径，无法完整表达本轮要求的“协议 + 目录 + 路径 + 文件名”。
- 当前 backend 尚未存在成熟的 SFTP/FTP 传输适配层，本轮不宜把联调闭环与传输客户端实现一并扩大到必交付。
配置承接方案比选
Decision: 默认规则沿用 Spring profile + Nacos
Rationale:
- 现有应用已通过
application-{profile}.yaml+ Nacos 导入配置，具备最低接入成本。 - 环境级默认规则更适合由 profile/Nacos 承接，避免在业务表中固化所有默认配置。
Alternatives considered:
- 完全新建独立文件传输配置表：当前范围过重，且与既有配置中心能力重复。
Decision: 通道/租户覆盖优先复用 ChannelApiConfigDO.extParams
Rationale:
- 现有
ChannelApiConfigDO已具备银行通道维度配置语义，extParams可以作为最小增量承接文件传输覆盖规则。 - 复用既有对象可降低本轮 schema 扩张与治理成本。
Alternatives considered:
- 新增专门的文件传输策略表：对当前 brownfield 需求来说过重。
- 把所有覆盖规则继续塞入 service 常量：无法满足统一解析与运行时切换。
Decision: 路径模板仅支持固定变量集合
Rationale:
- 当前已澄清只允许固定变量白名单，可显著降低解析复杂度与安全风险。
- 更适合形成稳定测试样本与正式文档说明。
Alternatives considered:
- 自由表达式模板：与已澄清约束冲突，且增加安全与维护风险。
- 完全固定路径：无法满足租户、通道、日期分化需求。
Decision: 配置缺失或连接信息不完整时立即阻断
Rationale:
- 已澄清的失败策略要求立即阻断当前文件动作，避免静默回退或进入不确定人工补救状态。
- 有利于验证工件给出明确失败结论。
Alternatives considered:
- 仅记日志继续流程：会削弱审计与问题定位能力。
- 自动回退到其他租户/通道配置：存在误用配置风险。
决策结论
- 引入统一解析入口，输入上下文、输出最终解析结果。
- 作用域优先级固定为：
TENANT_CHANNEL > TENANT > CHANNEL > DEFAULT。 - 上层覆盖不完整时采用字段级回退，而不是整组失败。
- 配置变更仅影响新发起文件动作，已开始或已落库批次沿用原解析结果。
- 审计只保存最终实际使用的协议、目录、路径、文件名，不强制留存配置版本或完整快照。
对正式文档的影响
12_REV_Detailed.md：补齐REV-008的文件通道配置、路径分化、运行时切换与仍待补证边界。03_Interface_Design.md：补齐文件交换能力边界、解析优先级、失败规则与审计说明，不新增外部接口编号。04_Security_Design.md：补齐协议选择、凭据管理、敏感配置禁入仓库、优先 SFTP / 兼容 FTP 的治理口径。05_Deployment_Design.md：补齐 profile/Nacos 承接、银行文件交换通道、环境差异、白名单与本地临时/归档目录职责说明。
Cross-Repo Impact
water-docs- 更新正式主文档与治理台账，形成可评审的规格闭环。
water-backendApiTypeEnum新增文件传输配置类型。ChannelApiConfigExtParams扩展作用域、业务类型、连接字段、目录字段。- 新增
config/filetransfer/与service/filetransfer/解析器。 BankWithholdingServiceImpl从硬编码目录切换到统一解析入口，并固化 send/back/reconcile 审计字段。
风险与 Deferred
- 真实 SFTP/FTP 客户端与网络连通性联调：Deferred
BankCollection托收链路对等改造：Deferred- 生产凭据、证书、白名单开通：Deferred
ARCHIVE / LOCAL_TEMP的独立持久化审计对象：Deferred，但当前可先纳入统一解析能力范围