# Research: sw-business-bank 银行代扣文件传输配置能力

## 研究目标

本轮研究只解决“配置承接 + 统一解析 + 审计落点 + 文档闭环”，不把真实银行生产联调、完整 SFTP/FTP 客户端接入或私有文件报文解析扩展进当前范围。

## 基线与现状

- backend 基线固定为：`water-backend` branch `001-sys009-withholding-closure` @ `84493513c1d06936210ab7e697985d38958ba5ee`
- 当前 `BankWithholdingServiceImpl` 在业务方法内硬编码生成送盘、回盘、对账路径，未复用统一解析层。
- 当前批次对象已能保存送盘/回盘/对账文件名与路径，但未统一保存协议与目录。
- 当前配置加载已沿用 Spring profile + Nacos 导入方式，可承接环境级默认规则。
- `ChannelApiConfigDO.extParams` 已存在但当前为空对象，可作为银行通道级覆盖配置的最小 carrier。

## 现有实现问题归纳

1. 路径硬编码散落在 `BankWithholdingServiceImpl` 中，无法支撑运行时切换。
2. 送盘、回盘、对账各自拼接路径，缺少统一优先级与字段级回退规则。
3. 审计仅留存文件名与路径，无法完整表达本轮要求的“协议 + 目录 + 路径 + 文件名”。
4. 当前 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**:
- 仅记日志继续流程：会削弱审计与问题定位能力。
- 自动回退到其他租户/通道配置：存在误用配置风险。

## 决策结论

1. 引入统一解析入口，输入上下文、输出最终解析结果。
2. 作用域优先级固定为：`TENANT_CHANNEL > TENANT > CHANNEL > DEFAULT`。
3. 上层覆盖不完整时采用字段级回退，而不是整组失败。
4. 配置变更仅影响新发起文件动作，已开始或已落库批次沿用原解析结果。
5. 审计只保存最终实际使用的协议、目录、路径、文件名，不强制留存配置版本或完整快照。

## 对正式文档的影响

- `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-backend`
  - `ApiTypeEnum` 新增文件传输配置类型。
  - `ChannelApiConfigExtParams` 扩展作用域、业务类型、连接字段、目录字段。
  - 新增 `config/filetransfer/` 与 `service/filetransfer/` 解析器。
  - `BankWithholdingServiceImpl` 从硬编码目录切换到统一解析入口，并固化 send/back/reconcile 审计字段。

## 风险与 Deferred

- 真实 SFTP/FTP 客户端与网络连通性联调：Deferred
- `BankCollection` 托收链路对等改造：Deferred
- 生产凭据、证书、白名单开通：Deferred
- `ARCHIVE / LOCAL_TEMP` 的独立持久化审计对象：Deferred，但当前可先纳入统一解析能力范围