fujian_water_biz_doc/specs/010-bank-transfer-config/contracts/bank-transfer-config-contract.md

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 承接结构

{
  "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、账户、凭据引用名应由运行环境承接