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

4.7 KiB
Raw Blame History

Quickstart: sw-business-bank 银行代扣文件传输配置能力

1. 固定基线

  1. 在 water-docs 中确认当前 feature 为 010-bank-transfer-config。
  2. 在 water-backend 中固定 branch 与 commit：
    • branch：001-sys009-withholding-closure
    • commit：84493513c1d06936210ab7e697985d38958ba5ee

2. 阅读必要上下文

  • docs/design/00_Management/01_Project_Progress.md
  • docs/design/00_Management/03_Task_Checklist.md
  • 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
  • spec.md
  • research.md
  • data-model.md

3. 准备最小配置样本

准备 7 组配置样本：

  1. 默认规则
  2. 租户覆盖规则
  3. 通道覆盖规则
  4. 租户-通道覆盖规则
  5. 协议切换样本（SFTP -> FTP 或 FTP -> SFTP）
  6. 非法模板变量样本（例如 {unknown}）
  7. 已落库批次配置切换回归样本

要求：

  • 目录分化至少覆盖 send/back/reconcile/archive/localTemp
  • 变量仅使用固定白名单
  • 准备 1 组缺失连接信息样本用于失败验证

4. 执行 backend 验证

最少验证以下场景：

  1. 默认规则命中：无覆盖时使用默认协议与目录
  2. 租户覆盖命中：租户覆盖仅影响本租户
  3. 通道覆盖命中：通道覆盖优先于默认
  4. 租户-通道覆盖命中：最具体规则优先
  5. 字段级回退：仅覆盖 sendDir 时，其余阶段回退上一级
  6. 协议切换：同一业务动作切换协议后不改业务拼路径代码
  7. 配置缺失失败：缺协议、缺 host、缺目录时立即阻断
  8. 非法变量失败：目录模板命中未声明变量时立即阻断
  9. 已落库批次不漂移：送盘后切换配置，再处理同批次回盘时仍沿用批次已固化目录

5. 执行文档校验

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

6. 执行 backend 最小验证

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 test

6.1 执行 Docker 文件通道 Smoke

启动 Docker 测试环境：

docker compose -f infra/docker/bank-transfer-test/compose.yaml up -d

执行 Java SFTP smoke：

mvn -f /Volumes/Dpan/github/water-workspace/water-backend/sw-business-bank/sw-business-bank-server/pom.xml \
  -DincludeScope=runtime dependency:build-classpath \
  -Dmdep.outputFile=/tmp/sw-business-bank-server.cp

java -cp "$(cat /tmp/sw-business-bank-server.cp):/Volumes/Dpan/github/water-workspace/water-backend/sw-business-bank/sw-business-bank-server/target/classes" \
  cn.com.emsoft.sw.bankbusiness.tools.BankTransferSftpSmokeCli \
  --local-file /Volumes/Dpan/github/water-workspace/water-docs/infra/docker/bank-transfer-test/tmp/sample.txt \
  --host 127.0.0.1 \
  --port 2222 \
  --username demo \
  --password demo123 \
  --send-dir /upload/{companyId} \
  --company-id C001 \
  --channel-code 00001 \
  --batch-no SMOKE010 \
  --business-date 2026-03-24 \
  --remote-file-name smoke-cli-sample.txt

执行 Java FTP smoke：

java -cp "$(cat /tmp/sw-business-bank-server.cp):/Volumes/Dpan/github/water-workspace/water-backend/sw-business-bank/sw-business-bank-server/target/classes" \
  cn.com.emsoft.sw.bankbusiness.tools.BankTransferFtpSmokeCli \
  --local-file /Volumes/Dpan/github/water-workspace/water-docs/infra/docker/bank-transfer-test/tmp/sample.txt \
  --host 127.0.0.1 \
  --port 2121 \
  --username demo \
  --password demo123 \
  --send-dir {companyId} \
  --company-id C001 \
  --channel-code 00001 \
  --batch-no SMOKE010FTP \
  --business-date 2026-03-24 \
  --remote-file-name smoke-cli-ftp-sample.txt

当前已验证结论：

  • SFTP roundtrip 通过
  • FTP roundtrip 通过
  • 上传后再下载的样本 SHA256 一致

7. 汇总验证工件

  • baseline.md
  • backend-validation.md
  • docs-validation.md
  • final-verdict.md

8. 通过标准

  • 五类核心验证场景全部有证据
  • 文档校验通过
  • backend 编译通过
  • 正式文档与验证结论一致
  • 台账已同步