# 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. 执行文档校验

```bash
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 最小验证

```bash
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 测试环境：

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

执行 Java SFTP smoke：

```bash
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：

```bash
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 编译通过
- 正式文档与验证结论一致
- 台账已同步