# Contract: 银行文件传输配置合同

## 目标

定义本轮 feature 允许承接的文件传输配置结构，作为 backend 实施与文档回写的共同约束。

## 作用域模型

支持以下四级作用域：

1. `DEFAULT`
2. `CHANNEL`
3. `TENANT`
4. `TENANT_CHANNEL`

优先级从高到低为：

`TENANT_CHANNEL > TENANT > CHANNEL > DEFAULT`

## 支持协议

- `SFTP`
- `FTP`

说明：
- 正式设计优先推荐 `SFTP`
- `FTP` 仅作为兼容协议表达能力保留

## 连接字段最小集合

- `protocol`
- `host`
- `port`
- `username`
- `credentialRef`
- `passiveMode`（FTP 可选）
- `enabled`

说明：
- 仓库工件与正式文档不得写入明文密码、密钥、证书
- 真实凭据通过环境配置或配置中心引用承接
- 命中协议下要求 `host/port/username/credentialRef` 齐备，否则立即阻断当前文件动作

## 目录字段最小集合

- `sendDir`
- `backDir`
- `reconcileDir`
- `archiveDir`
- `localTempDir`

## 业务类型约束

- `businessType`

说明：
- 本轮统一使用 `WITHHOLDING`
- 合同保留该字段，便于后续托收链路平移时复用同一解析器

## 固定变量白名单

仅允许以下变量：

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

禁止：
- 自由表达式
- 任意脚本化拼装
- 未声明变量

## 推荐 extParams 承接结构

```json
{
  "scopeType": "CHANNEL",
  "tenantId": "optional",
  "businessType": "WITHHOLDING",
  "protocol": "SFTP",
  "host": "example-host",
  "port": 22,
  "username": "config-ref-user",
  "credentialRef": "bank.transfer.xxx",
  "sendDir": "/withholding/{companyId}",
  "backDir": "/withholding/{companyId}/back",
  "reconcileDir": "/withholding/{companyId}/reconcile",
  "archiveDir": "/withholding/{companyId}/archive",
  "localTempDir": "/data/tmp/withholding/{yyyyMMdd}",
  "enabled": true
}
```

说明：
- 示例仅用于字段结构表达，不代表真实配置值
- 真实 host、账户、凭据引用名应由运行环境承接