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/plan.md

10 KiB
Raw Blame History

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 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.

  • 主文档归属已确认：正式结论回写既有主文档与治理台账，不新增平行正式稿。
  • 多仓范围已确认：本轮涉及 water-docs 与 water-backend；water-frontend 不在范围内。
  • 代码基线已确认：backend 基线固定为 develop @ b540f1f48bf2d6c28aa183749ca61231071c0942。
  • Archive 使用方式合规：Archive 仅作来源核对，不替代正式口径。
  • 一致性影响已列出：影响 REV-008 能力边界、接口说明、安全口径、部署口径、审计字段与验证工件。
  • 校验与台账动作已规划：已规划文档校验、backend 编译/测试、01_Project_Progress.md 与 03_Task_Checklist.md 更新。

Project Structure

Feature Artifacts

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

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 已通过 无