140 lines
4.7 KiB
Markdown
140 lines
4.7 KiB
Markdown
# 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 编译通过
|
||
- 正式文档与验证结论一致
|
||
- 台账已同步
|