174 lines
4.0 KiB
Markdown
174 lines
4.0 KiB
Markdown
# 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 最小落地。
|