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

17 KiB
Raw Blame History

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.

  • T001 Confirm target documents, target repos, clarified requirements, and exact chapter landing points from specs/010-bank-transfer-config/spec.md
  • 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
  • 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/
  • T004 Confirm governing source-of-truth documents, validation commands, and repo touchpoints from specs/010-bank-transfer-config/plan.md
  • T005 [P] Record backend baseline branch and commit in specs/010-bank-transfer-config/baseline.md
  • 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.

  • 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
  • T008 Confirm final validation command set and minimum scenario matrix in specs/010-bank-transfer-config/quickstart.md
  • 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
  • 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

  • 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
  • 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
  • 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
  • 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
  • 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
  • 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
  • T017 [US1] Record story-specific document validation results for config-boundary docs in specs/010-bank-transfer-config/docs-validation.md
  • 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

  • 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
  • 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
  • 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/
  • 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
  • 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
  • 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/
  • 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
  • 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
  • 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
  • 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
  • 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
  • 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
  • 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
  • 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
  • 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

  • T034 [US3] Update docs/design/00_Management/01_Project_Progress.md with this feature’s scope, baseline, minimum validation results, and remaining deferred items
  • T035 [US3] Update docs/design/00_Management/03_Task_Checklist.md to reflect the closure state for this feature’s planning and implementation checkpoints
  • T036 [US3] Finalize specs/010-bank-transfer-config/baseline.md with backend branch, commit, inspected code paths, and source-of-truth references
  • T037 [US3] Finalize specs/010-bank-transfer-config/docs-validation.md with document command results and impacted-file notes
  • 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
  • T039 [US3] Prepare specs/010-bank-transfer-config/final-verdict.md with outcome summary, delivered scope, deferred scope, risks, and recommended next actions
  • 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.

  • 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
  • T042 [P] Re-check relative links, stable anchors, and Mermaid consistency across modified files in docs/design/ and specs/010-bank-transfer-config/
  • 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
  • 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
  • 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

# 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

# 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

# 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