# Tasks: sw-business-bank 银行代扣文件传输配置能力 **Input**: Design documents from `/specs/010-bank-transfer-config/` **Prerequisites**: plan.md (required), spec.md (required), research.md, data-model.md, contracts/, quickstart.md **Validation**: Validation and evidence tasks are NOT optional. Every feature task set MUST include the applicable document validation, code validation, ledger-sync, and final-verdict tasks. **Organization**: Tasks are grouped by user story so each slice can be completed, reviewed, and validated independently. ## Format: `[ID] [P?] [Story] Description` - **[P]**: Can run in parallel (different files, no dependencies) - **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3) - Include exact file paths in descriptions ## Path Conventions - Formal workflow: `water-docs/` - Main documents: `docs/design/01_Overview/`, `docs/design/02_Detailed_Design/`, `docs/design/03_Technical_Design/` - Governance documents: `docs/design/00_Management/` - Feature artifacts: `specs/010-bank-transfer-config/` - Backend modules: `../water-backend/...` - Frontend modules: `../water-frontend/...` ## Phase 1: Scope, Baseline & Source Confirmation **Purpose**: Confirm the source-of-truth set, repo boundary, governance prerequisites, and code baselines before editing anything. - [x] T001 Confirm target documents, target repos, clarified requirements, and exact chapter landing points from `specs/010-bank-transfer-config/spec.md` - [x] T002 Read `docs/design/00_Management/01_Project_Progress.md`, `docs/design/00_Management/02_Delivery_Standards.md`, and `docs/design/00_Management/03_Task_Checklist.md` before any formal document edits - [x] T003 Read `docs/design/00_Management/04_Writing_Guide.md`, `docs/design/00_Management/08_AI_Agent_Maintenance_SOP.md`, `docs/design/00_Management/10_AI_Retrieval_Whitelist.md`, and `docs/design/00_Management/11_Main_Doc_Chapter_Index.md` before structural updates in `docs/design/` - [x] T004 Confirm governing source-of-truth documents, validation commands, and repo touchpoints from `specs/010-bank-transfer-config/plan.md` - [x] T005 [P] Record backend baseline branch and commit in `specs/010-bank-transfer-config/baseline.md` - [x] T006 [P] Map cross-document and cross-repo impacts in `specs/010-bank-transfer-config/research.md` and `specs/010-bank-transfer-config/data-model.md` --- ## Phase 2: Shared Foundation **Purpose**: Establish the shared alignment baseline for docs, code evidence, and verification outputs. - [x] T007 Normalize terminology, scope priority, protocol vocabulary, and audit field naming in `specs/010-bank-transfer-config/plan.md` and `specs/010-bank-transfer-config/contracts/bank-transfer-resolution-contract.md` - [x] T008 Confirm final validation command set and minimum scenario matrix in `specs/010-bank-transfer-config/quickstart.md` - [x] T009 Create verification placeholders and expected evidence sections in `specs/010-bank-transfer-config/backend-validation.md`, `specs/010-bank-transfer-config/docs-validation.md`, and `specs/010-bank-transfer-config/final-verdict.md` - [x] T010 [P] Inspect current backend landing files for implementation scope in `../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/withholdingbatch/WithholdingBatchDO.java`, `../water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/dal/dataobject/reconcilebatch/ReconcileBatchDO.java`, and `../water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/dal/dataobject/channelapiconfig/ChannelApiConfigExtParams.java` --- ## Phase 3: User Story 1 - 配置外部化管理银行文件通道 (Priority: P1) 🎯 MVP **Goal**: 建立银行代扣文件传输的外部化配置边界，并把默认规则、通道覆盖、租户覆盖与目录字段合同回写到正式文档和 backend 配置模型中。 **Independent Test**: 评审人仅通过规格、合同、正式文档与配置模型，即可确认系统支持 `SFTP/FTP`、五类目录、四级作用域和固定变量白名单，且不需要阅读解析实现细节。 ### Implementation for User Story 1 - [x] T011 [US1] Update `docs/design/02_Detailed_Design/12_REV_Detailed.md` to describe `REV-008` file transfer configuration scopes, stage directories, and fixed template variable rules - [x] T012 [US1] Update `docs/design/03_Technical_Design/04_Security_Design.md` to define protocol selection, credential reference rules, and secret-handling constraints for bank file transfer config - [x] T013 [US1] Update `docs/design/03_Technical_Design/05_Deployment_Design.md` to document Spring profile + Nacos default config loading, channel override source, and environment responsibilities - [x] T014 [P] [US1] Refine config contract details in `specs/010-bank-transfer-config/contracts/bank-transfer-config-contract.md` and scope/entity alignment in `specs/010-bank-transfer-config/data-model.md` - [x] T015 [US1] Extend `../water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/dal/dataobject/channelapiconfig/ChannelApiConfigExtParams.java` to carry file transfer protocol, connection fields, stage directories, scope type, and tenant-specific override fields - [x] T016 [US1] Update `../water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/dal/dataobject/channelapiconfig/ChannelApiConfigDO.java` and `../water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/dal/type/ChannelApiConfigExtParamsTypeHandler.java` to support a dedicated file-transfer `apiType` and persistence of the new extParams structure - [x] T017 [US1] Record story-specific document validation results for config-boundary docs in `specs/010-bank-transfer-config/docs-validation.md` - [x] T018 [US1] Record backend configuration-model evidence and baseline notes in `specs/010-bank-transfer-config/backend-validation.md` **Checkpoint**: User Story 1 is independently reviewable with both document and configuration-model evidence aligned. --- ## Phase 4: User Story 2 - 运行时统一解析路径与协议 (Priority: P2) **Goal**: 为送盘、回盘、对账建立统一的文件传输解析入口，支持协议切换、作用域优先级、字段级回退、失败阻断与审计结果落库。 **Independent Test**: 通过自动化验证与批次对象落值结果，可独立确认默认规则、租户覆盖、通道覆盖、租户-通道覆盖、协议切换、非法变量失败与配置缺失失败行为全部符合 spec。 ### Implementation for User Story 2 - [x] T019 [US2] Update `docs/design/03_Technical_Design/03_Interface_Design.md` to document runtime resolution priority, failure behavior, and audit outputs for file exchange actions - [x] T020 [P] [US2] Sync resolution rules and audit expectations in `specs/010-bank-transfer-config/contracts/bank-transfer-resolution-contract.md` and `specs/010-bank-transfer-config/quickstart.md` - [x] T021 [US2] Add file transfer properties, enums, context, and resolver classes under `../water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/config/filetransfer/` and `../water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/service/filetransfer/` - [x] T022 [US2] Align 业务类型（`businessType`） handling across `specs/010-bank-transfer-config/data-model.md`, `specs/010-bank-transfer-config/contracts/bank-transfer-resolution-contract.md`, and `../water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/service/filetransfer/` resolution context definitions - [x] T023 [US2] Refactor `../water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/service/bankwithholding/BankWithholdingServiceImpl.java` to consume unified resolved protocol/dir/path results instead of hardcoded send/back/reconcile path builders - [x] T024 [US2] Implement `ARCHIVE` and `LOCAL_TEMP` stage resolution support under `../water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/service/filetransfer/` - [x] T025 [US2] Extend `../water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/dal/dataobject/withholdingbatch/WithholdingBatchDO.java` and `../water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/dal/dataobject/reconcilebatch/ReconcileBatchDO.java` to persist final protocol and directory audit fields together with resolved paths - [x] T026 [US2] Update `../water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/dal/mysql/withholdingbatch/WithholdingBatchMapper.java` and `../water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/dal/mysql/reconcilebatch/ReconcileBatchMapper.java` when newly added DO audit fields are not automatically persisted by the existing mapper definitions - [x] T027 [P] [US2] Create resolver-focused tests in `../water-backend/sw-business-bank/sw-business-bank-server/src/test/java/cn/com/emsoft/sw/bankbusiness/service/filetransfer/BankTransferPathResolverTest.java` - [x] T028 [P] [US2] Add `ARCHIVE` and `LOCAL_TEMP` stage coverage to `../water-backend/sw-business-bank/sw-business-bank-server/src/test/java/cn/com/emsoft/sw/bankbusiness/service/filetransfer/BankTransferPathResolverTest.java` - [x] T029 [P] [US2] Add invalid-template-variable failure cases to `../water-backend/sw-business-bank/sw-business-bank-server/src/test/java/cn/com/emsoft/sw/bankbusiness/service/filetransfer/BankTransferPathResolverTest.java` - [x] T030 [P] [US2] Create integration-oriented service tests in `../water-backend/sw-business-bank/sw-business-bank-server/src/test/java/cn/com/emsoft/sw/bankbusiness/service/bankwithholding/BankWithholdingTransferConfigTest.java` - [x] T031 [US2] Add persisted-batch config-switch regression cases to `../water-backend/sw-business-bank/sw-business-bank-server/src/test/java/cn/com/emsoft/sw/bankbusiness/service/bankwithholding/BankWithholdingTransferConfigTest.java` - [x] T032 [US2] Check whether `../water-backend/sw-business-bank/sw-business-bank-server/src/test/resources/application-unit-test.yaml` and `../water-backend/sw-business-bank/sw-business-bank-server/src/test/resources/sql/create_tables.sql` already support withholding/reconcile test coverage and new audit fields; update them if the new tests cannot run against the current fixtures - [x] T033 [US2] Run story-specific backend validation commands and capture compile/test results in `specs/010-bank-transfer-config/backend-validation.md` **Checkpoint**: User Story 2 is independently reviewable and validated. --- ## Phase 5: User Story 3 - 形成可审计的文档与验证闭环 (Priority: P3) **Goal**: 形成正式文档、治理台账、基线工件和最终 verdict 的一致闭环，使本轮增强能力可追溯、可评审、可归档。 **Independent Test**: 仅检查正式文档、台账和 `specs/010-bank-transfer-config/` 下工件，即可确认范围、基线、验证结果、剩余 deferred 项和后续建议全部齐备。 ### Implementation for User Story 3 - [x] T034 [US3] Update `docs/design/00_Management/01_Project_Progress.md` with this feature’s scope, baseline, minimum validation results, and remaining deferred items - [x] T035 [US3] Update `docs/design/00_Management/03_Task_Checklist.md` to reflect the closure state for this feature’s planning and implementation checkpoints - [x] T036 [US3] Finalize `specs/010-bank-transfer-config/baseline.md` with backend branch, commit, inspected code paths, and source-of-truth references - [x] T037 [US3] Finalize `specs/010-bank-transfer-config/docs-validation.md` with document command results and impacted-file notes - [x] T038 [US3] Finalize `specs/010-bank-transfer-config/backend-validation.md` with separate evidence sections for default rule, tenant override, channel override, tenant-channel override, field-level fallback, protocol switch, invalid-template-variable failure, config-missing failure, and persisted-batch config-switch regression - [x] T039 [US3] Prepare `specs/010-bank-transfer-config/final-verdict.md` with outcome summary, delivered scope, deferred scope, risks, and recommended next actions - [x] T040 [US3] Run story-specific document validation for `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`, and `docs/design/00_Management/03_Task_Checklist.md`, then capture results in `specs/010-bank-transfer-config/docs-validation.md` **Checkpoint**: All planned updates are independently reviewable and validated. --- ## Final Phase: Verification & Closure **Purpose**: Ensure repository-wide consistency, baseline traceability, and final verdict output. - [x] T041 [P] Re-check source-of-truth alignment across `specs/010-bank-transfer-config/spec.md`, `specs/010-bank-transfer-config/plan.md`, `specs/010-bank-transfer-config/tasks.md`, and all modified formal documents - [x] T042 [P] Re-check relative links, stable anchors, and Mermaid consistency across modified files in `docs/design/` and `specs/010-bank-transfer-config/` - [x] T043 [P] Re-check backend baseline SHA, compile/test outputs, and evidence completeness in `specs/010-bank-transfer-config/baseline.md` and `specs/010-bank-transfer-config/backend-validation.md` - [x] T044 [P] Run `make validate-mermaid` and capture results in `specs/010-bank-transfer-config/docs-validation.md` if any Mermaid diagrams are added or modified in `docs/design/`; if no Mermaid diagrams are changed, record `N/A` with a brief reason in `specs/010-bank-transfer-config/docs-validation.md` - [x] T045 Prepare final closure summary and verdict sign-off in `specs/010-bank-transfer-config/final-verdict.md` --- ## Dependencies & Execution Order ### Phase Dependencies - **Phase 1: Scope, Baseline & Source Confirmation**: No dependencies; MUST finish before edits - **Phase 2: Shared Foundation**: Depends on Phase 1 and MUST finish before story execution - **Phase 3: User Story 1**: Depends on Phase 2 and is the MVP slice - **Phase 4: User Story 2**: Depends on User Story 1 config model/contract completion - **Phase 5: User Story 3**: Depends on User Story 1 and User Story 2 evidence being available - **Final Phase**: Depends on all selected user stories being complete ### Within Each User Story - Complete formal/contract updates before validation capture - Complete backend model or resolver work before service integration and tests - Complete code/test validation before ledger closure and final verdict updates - Record evidence before marking closure tasks done ### Parallel Opportunities - `T005` and `T006` can run in parallel once the feature scope is confirmed - `T014` can run in parallel with `T015`-`T016` after User Story 1 document intent is fixed - `T020` can run in parallel with `T021` after User Story 2 contract shape is confirmed - `T027`-`T030` can run in parallel after resolver and service integration points are stable - `T041`, `T042`, `T043`, and `T044` can run in parallel during final closure ## Parallel Execution Examples ### User Story 1 ```bash # Parallel after config boundary is agreed Task: T014 Refine contracts/data-model Task: T015 Extend ChannelApiConfigExtParams Task: T016 Update DO/type handler persistence ``` ### User Story 2 ```bash # Parallel after resolver design is fixed Task: T027 Create BankTransferPathResolverTest Task: T028 Add ARCHIVE and LOCAL_TEMP coverage Task: T029 Add invalid-template-variable failure cases Task: T030 Create BankWithholdingTransferConfigTest Task: T031 Add persisted-batch config-switch regression cases Task: T032 Check and update test fixtures ``` ### Final Closure ```bash # Parallel final checks Task: T041 Re-check source-of-truth alignment Task: T042 Re-check links and Mermaid consistency Task: T043 Re-check backend baseline and validation completeness Task: T044 Run conditional Mermaid validation ``` ## Implementation Strategy ### MVP First 1. Finish Phase 1 and Phase 2 to lock source-of-truth, baseline, validation plan, and evidence targets 2. Deliver **User Story 1** first as the MVP: formalize configuration scopes, fixed variables, and backend config carrier 3. Deliver **User Story 2** next: implement unified runtime resolution, audit persistence, and automated tests 4. Deliver **User Story 3** last: close governance, evidence, and verdict artifacts ### Incremental Delivery - After **US1**, reviewers can confirm whether the configuration model and formal doc scope are acceptable - After **US2**, reviewers can confirm runtime behavior and backend evidence independently - After **US3**, the feature is ready for governance review and handoff ## Notes - Every task set MUST preserve the single-source-of-truth model in `water-docs` - Archive is for verification and traceability, not direct formal output replacement - `../water-backend/` consumes and evidences the official spec; it does not replace formal docs - Validation, evidence, baseline, and ledger tasks are mandatory for this feature - Frontend is out of scope unless the user explicitly expands repository scope