tangweijie/fujian_water_biz_doc
1
0
Fork 0
Code Issues Pull Requests 12 Actions Packages Projects Releases 1 Wiki Activity
fujian_water_biz_doc/specs/010-bank-transfer-config/data-model.md

4.0 KiB
Raw Blame History

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 最小落地。