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

## 设计原则

- 优先复用现有配置载体和批次对象，不新增独立正式主表作为第一选择。
- 本轮以逻辑实体 + 现有物理承接关系表达设计，不把真实密钥或密码写入文档。
- 以“默认规则 + 覆盖规则 + 解析上下文 + 解析结果”构成最小可实现模型。

## 逻辑实体

### 1. FileTransferPolicy

**说明**：环境默认文件传输策略，来源于 Spring profile + Nacos。

**字段**：
- `policyId`：默认可固定为 `default`
- `scopeType`：`DEFAULT`
- `protocol`：`SFTP | FTP`
- `host`
- `port`
- `username`
- `credentialRef`：凭据引用名，不存明文
- `passiveMode`：FTP 可选
- `sendDir`
- `backDir`
- `reconcileDir`
- `archiveDir`
- `localTempDir`
- `enabled`
- `remark`

### 2. FileTransferOverride

**说明**：银行通道/租户维度覆盖规则，建议复用 `bk_channel_api_config.ext_params`。

**字段**：
- `configId`
- `tenantId`：可为空，空表示非租户专属
- `channelId`
- `scopeType`：`CHANNEL | TENANT | TENANT_CHANNEL`
- `businessType`：默认本轮为 `WITHHOLDING`
- `protocol`：可选覆盖
- `host`
- `port`
- `username`
- `credentialRef`
- `passiveMode`
- `sendDir`
- `backDir`
- `reconcileDir`
- `archiveDir`
- `localTempDir`
- `enabled`
- `remark`

**物理承接建议**：
- 使用 `ChannelApiConfigDO.extParams`
- 通过独立 `apiType` 表示“文件传输配置”，避免与交易接口配置混用

### 3. DirectoryResolutionContext

**说明**：一次文件动作解析路径与协议时使用的上下文。

**字段**：
- `tenantId`
- `companyId`
- `channelId`
- `channelCode`
- `businessType`
- `stage`：`SEND | BACK | RECONCILE | ARCHIVE | LOCAL_TEMP`
- `businessDate`
- `batchNo`
- `fileName`

### 4. ResolvedFileLocation

**说明**：统一解析器输出的最终可执行目标。

**字段**：
- `sourceScope`：命中的作用域层级
- `protocol`
- `host`
- `port`
- `username`
- `credentialRef`
- `resolvedDir`
- `resolvedPath`
- `fileName`
- `resolvedAt`

## 枚举

### TransferStage
- `SEND`
- `BACK`
- `RECONCILE`
- `ARCHIVE`
- `LOCAL_TEMP`

### TransferScope
- `DEFAULT`
- `CHANNEL`
- `TENANT`
- `TENANT_CHANNEL`

### TransferProtocol
- `SFTP`
- `FTP`

## 固定变量白名单

- `{tenantId}`
- `{companyId}`
- `{channelCode}`
- `{yyyyMMdd}`
- `{yyyyMM}`
- `{batchNo}`
- `{fileName}`

## 现有物理对象扩展建议

### `WithholdingBatchDO` / `bk_withholding_batch`

**现状已具备**：
- `sendFileName`
- `sendFilePath`
- `backFileName`
- `backFilePath`

**建议新增**：
- `sendProtocol`
- `sendDir`
- `backProtocol`
- `backDir`

**说明**：
- 送盘创建时同步固化 `sendProtocol/sendDir/sendFilePath` 与 `backProtocol/backDir`，确保后续已落库批次不因配置切换而漂移。

### `ReconcileBatchDO` / `bk_reconcile_batch`

**现状已具备**：
- `fileName`
- `filePath`

**建议新增**：
- `protocol`
- `dir`

**说明**：
- 对账批次在回盘处理阶段固化最终 `protocol/dir/filePath/fileName`，形成最小审计闭环。

## 关系

- `FileTransferPolicy` 提供环境默认协议与目录。
- `FileTransferOverride` 对默认规则做按字段覆盖。
- `DirectoryResolutionContext` 驱动统一解析。
- `ResolvedFileLocation` 由解析器生成。
- `WithholdingBatchDO` 持久化送盘/回盘解析结果。
- `ReconcileBatchDO` 持久化对账解析结果。

## Cross-Repo Impact

- `water-docs`
  - 回写 `REV-008` 详设、接口设计、安全设计、部署设计与治理台账。
- `water-backend`
  - `ChannelApiConfigExtParams` 承接四级作用域、业务类型、协议、连接字段与五类目录。
  - `BankTransferPathResolver` 负责默认规则、覆盖优先级、字段级回退与变量校验。
  - `BankWithholdingServiceImpl` 改为消费统一解析结果并固化 send/back/reconcile 审计字段。

## 最小实现结论

- 本轮不建议新增独立“文件传输策略表”。
- 以 `profile/Nacos + ChannelApiConfigDO.extParams + 现有批次表增量字段` 完成 brownfield 最小落地。