158 lines
10 KiB
Markdown
158 lines
10 KiB
Markdown
# Implementation Plan: sw-business-bank 银行代扣文件传输配置能力
|
||
|
||
**Branch**: `010-bank-transfer-config` | **Date**: 2026-03-23 | **Spec**: [/Volumes/Dpan/github/water-workspace/water-docs/specs/010-bank-transfer-config/spec.md](./spec.md)
|
||
**Input**: Feature specification from `/Volumes/Dpan/github/water-workspace/water-docs/specs/010-bank-transfer-config/spec.md`
|
||
|
||
**Note**: This template is filled in by the `/speckit.plan` command. For this project, planning is document-first and multi-repo aware.
|
||
|
||
## Summary
|
||
|
||
在既有 `REV-008 / SYS-009` 银行代扣能力基础上，为 `sw-business-bank` 增加文件传输配置能力最小闭环：将送盘、回盘、对账、归档、本地临时五类目录从 `BankWithholdingServiceImpl` 的硬编码路径中抽离，支持 `SFTP / FTP` 双协议配置选择，支持“默认规则 + 银行通道覆盖 + 租户覆盖 + 租户-银行通道覆盖”的统一解析，明确配置变更仅影响新发起文件动作、已开始或已落库批次继续沿用原解析结果，并将正式结论回写既有主文档与治理台账，不新增平行正式稿。
|
||
|
||
## Repository Scope
|
||
|
||
- **Formal workflow home**: `water-docs`
|
||
- **Target repos in scope**:
|
||
- `water-docs`: Yes
|
||
- `water-backend`: Yes
|
||
- `water-frontend`: No
|
||
- **Primary delivery mode**: Mixed
|
||
|
||
## Code Baseline
|
||
|
||
- **Backend baseline**: `water-backend` branch `develop` @ `b540f1f48bf2d6c28aa183749ca61231071c0942`
|
||
- **Frontend baseline**: N/A
|
||
- **Baseline capture plan**: 所有“当前已支持 / 本轮新增支持 / 仍待补证”的判断均绑定上述 backend baseline，并在 `baseline.md`、`backend-validation.md`、`final-verdict.md` 中固定 branch 与 commit，确保文档结论始终锚定到可追溯实现版本。
|
||
|
||
## Technical Context
|
||
|
||
**Primary Work Product**: 正式设计文档修订、`specs/010-bank-transfer-config/` 计划工件、backend 配置承接与路径解析增强、最小编译/测试验证
|
||
**Source of Truth Documents**: `docs/design/02_Detailed_Design/12_REV_Detailed.md`、`docs/design/03_Technical_Design/03_Interface_Design.md`、`docs/design/03_Technical_Design/04_Security_Design.md`、`docs/design/03_Technical_Design/05_Deployment_Design.md`、`.specify/memory/constitution.md`
|
||
**Reference Sources**: `docs/guides/BACKEND_CURRENT_STATUS.md`、Archive 历史资料（只读核对）、`../water-backend/sw-business-bank/sw-business-bank-server/src/main/resources/application.yaml`、`../water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/service/bankwithholding/BankWithholdingServiceImpl.java`、`../water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/dal/dataobject/channelapiconfig/ChannelApiConfigDO.java`
|
||
**Validation Commands**: `make validate-file FILE=<目标文档>`、`make check-links`、`mvn -f /Volumes/Dpan/github/water-workspace/water-backend/sw-business-bank/pom.xml -pl sw-business-bank-server -am -DskipTests compile`、`mvn -f /Volumes/Dpan/github/water-workspace/water-backend/sw-business-bank/pom.xml -pl sw-business-bank-server -am -Dtest=BankTransferPathResolverTest,BankWithholdingTransferConfigTest -Dsurefire.failIfNoSpecifiedTests=false test`
|
||
**Target Scope**: 正式文档中的 `REV-008` 详设、接口设计、安全设计、部署设计、项目进度台账、任务清单台账；backend 中 `BankWithholding` 送盘/回盘/对账路径解析与审计承接、`ARCHIVE` / `LOCAL_TEMP` 的目录解析能力、`ChannelApiConfigDO.extParams` 的通道级覆盖能力、沿用 Spring profile + Nacos 的配置加载
|
||
**Project Type**: 文档治理仓库 + 多仓实现协作
|
||
**Constraints**: 不新增平行正式文档；不把真实密钥、密码、证书写入仓库；仅允许固定变量模板；配置缺失或连接信息不完整时立即阻断；配置切换仅影响新动作；审计只保留最终解析结果，不保留完整配置快照
|
||
**Scale/Scope**: cross-document + backend focused + validation-light
|
||
|
||
## Constitution Check
|
||
|
||
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
||
|
||
- [x] **主文档归属已确认**：正式结论回写既有主文档与治理台账，不新增平行正式稿。
|
||
- [x] **多仓范围已确认**：本轮涉及 `water-docs` 与 `water-backend`；`water-frontend` 不在范围内。
|
||
- [x] **代码基线已确认**：backend 基线固定为 `develop @ b540f1f48bf2d6c28aa183749ca61231071c0942`。
|
||
- [x] **Archive 使用方式合规**：Archive 仅作来源核对，不替代正式口径。
|
||
- [x] **一致性影响已列出**：影响 `REV-008` 能力边界、接口说明、安全口径、部署口径、审计字段与验证工件。
|
||
- [x] **校验与台账动作已规划**：已规划文档校验、backend 编译/测试、`01_Project_Progress.md` 与 `03_Task_Checklist.md` 更新。
|
||
|
||
## Project Structure
|
||
|
||
### Feature Artifacts
|
||
|
||
```text
|
||
specs/010-bank-transfer-config/
|
||
├── spec.md
|
||
├── plan.md
|
||
├── research.md
|
||
├── data-model.md
|
||
├── quickstart.md
|
||
├── contracts/
|
||
│ ├── bank-transfer-config-contract.md
|
||
│ └── bank-transfer-resolution-contract.md
|
||
├── tasks.md
|
||
├── baseline.md
|
||
├── backend-validation.md
|
||
├── docs-validation.md
|
||
└── final-verdict.md
|
||
```
|
||
|
||
### Repository Touchpoints
|
||
|
||
```text
|
||
water-docs/
|
||
├── docs/design/02_Detailed_Design/12_REV_Detailed.md
|
||
├── docs/design/03_Technical_Design/03_Interface_Design.md
|
||
├── docs/design/03_Technical_Design/04_Security_Design.md
|
||
├── docs/design/03_Technical_Design/05_Deployment_Design.md
|
||
├── docs/design/00_Management/01_Project_Progress.md
|
||
└── docs/design/00_Management/03_Task_Checklist.md
|
||
|
||
water-backend/
|
||
└── sw-business-bank/sw-business-bank-server/
|
||
├── src/main/java/.../service/bankwithholding/
|
||
├── src/main/java/.../dal/dataobject/channelapiconfig/
|
||
├── src/main/java/.../dal/dataobject/withholdingbatch/
|
||
├── src/main/java/.../dal/dataobject/reconcilebatch/
|
||
├── src/main/resources/
|
||
└── src/test/java/...
|
||
```
|
||
|
||
**Structure Decision**: 正式设计只更新既有主文档；backend 只做配置承接、统一解析、审计字段补齐、最小测试；不扩展 frontend；不把真实 SFTP/FTP 凭据写入仓库。
|
||
|
||
## Phase 0: Research & Alignment
|
||
|
||
### Research Inputs
|
||
|
||
- 当前硬编码路径分别在哪些方法生成，哪些 DO 已落库保存
|
||
- `ChannelApiConfigDO.extParams` 是否足以承接“通道/租户覆盖”
|
||
- 统一解析上下文是否需要显式包含业务类型（`businessType`），以及它在本轮 `BankWithholding` 场景下的最小承接方式
|
||
- 默认规则与覆盖规则的最小优先级模型如何表达
|
||
- 审计字段最少需要新增到哪些现有 DO / 表
|
||
- 非法模板变量、配置缺失、连接信息不完整与已落库批次配置切换等场景中，哪些验证必须自动化，哪些仅需文档声明为 deferred
|
||
|
||
### Deliverables
|
||
|
||
- `research.md`
|
||
- `baseline.md`
|
||
|
||
## Phase 1: Design & Contracts
|
||
|
||
### Planned Artifacts
|
||
|
||
- `data-model.md`
|
||
- `contracts/bank-transfer-config-contract.md`
|
||
- `contracts/bank-transfer-resolution-contract.md`
|
||
- `quickstart.md`
|
||
- `backend-validation.md`
|
||
- `docs-validation.md`
|
||
- `final-verdict.md`
|
||
|
||
### Design Decisions
|
||
|
||
- 默认配置来源采用 Spring profile + Nacos
|
||
- 通道/租户覆盖优先复用 `bk_channel_api_config.ext_params`
|
||
- 在 `bk_channel_api_config` 中使用专用 `apiType` 表示“文件传输配置”，避免与单笔交易 API 混用
|
||
- 新增统一解析器，输入至少包含 `tenantId/companyId/channelId/businessType/stage/businessDate/batchNo/fileName`，其中 `businessType` 对应业务类型，输出 `protocol/dir/path/fileName/sourceScope`
|
||
- 统一解析器必须覆盖 `SEND`、`BACK`、`RECONCILE`、`ARCHIVE`、`LOCAL_TEMP` 五类目录；其中 `ARCHIVE` / `LOCAL_TEMP` 本轮至少要求具备解析能力与测试覆盖，不强制新增独立持久化审计对象
|
||
- 路径模板只支持固定变量集合：`{tenantId}`、`{companyId}`、`{channelCode}`、`{yyyyMMdd}`、`{yyyyMM}`、`{batchNo}`、`{fileName}`
|
||
- 使用未声明变量时，解析器必须立即失败并返回可诊断错误
|
||
- 更具体配置覆盖更通用配置；上层不完整时逐字段回退
|
||
- `BankWithholdingServiceImpl` 只接入解析结果，不再自行拼接路径
|
||
- 配置变更仅影响新发起文件动作；已开始或已落库批次继续沿用原解析结果
|
||
- 审计只记录最终协议、目录、路径、文件名，不记录配置版本号或完整配置快照
|
||
- 缺失配置、缺失必要连接信息或命中错误作用域时直接失败，不回退到错误通道
|
||
|
||
## Validation Plan
|
||
|
||
- **Document validation**: `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md`、`make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md`、`make validate-file FILE=docs/design/03_Technical_Design/04_Security_Design.md`、`make validate-file FILE=docs/design/03_Technical_Design/05_Deployment_Design.md`、`make validate-file FILE=docs/design/00_Management/01_Project_Progress.md`、`make validate-file FILE=docs/design/00_Management/03_Task_Checklist.md`；如有跨文档链接更新再执行 `make check-links`
|
||
- **Backend validation**: 目标单元测试与服务级验证至少覆盖默认规则、租户覆盖、通道覆盖、租户-通道覆盖、字段级回退、协议切换、非法模板变量失败、配置缺失失败，以及“配置切换仅影响新动作、已落库批次不漂移”等场景；同时通过最小编译校验
|
||
- **Frontend validation**: N/A
|
||
- **Evidence output**: `baseline.md`、`backend-validation.md`、`docs-validation.md`、`final-verdict.md`
|
||
- **Conditional diagram validation**: 若本轮修改 `docs/design/` 中的 Mermaid 图表，必须执行 `make validate-mermaid` 并将结果记录到 `docs-validation.md`
|
||
|
||
## Ledger Sync Plan
|
||
|
||
- **Project progress update required**: Yes
|
||
- **Task checklist update required**: Yes
|
||
- **Evidence or verification summary update required**: Yes
|
||
- **Result summary requirement**: 完成重要变更后，结果摘要必须说明修改文件、校验结果、剩余风险与后续建议
|
||
|
||
## Complexity Tracking
|
||
|
||
> **Fill ONLY if Constitution Check has violations that must be justified**
|
||
|
||
| Violation | Why Needed | Simpler Alternative Rejected Because |
|
||
|-----------|------------|-------------------------------------|
|
||
| 无 | 本次 Constitution Check 已通过 | 无 |
|