fujian_water_biz_doc/specs/010-bank-transfer-config/tasks.md

# 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