188 lines
16 KiB
Markdown
188 lines
16 KiB
Markdown
# Feature Specification: sw-business-bank 银行代扣文件传输配置能力
|
||
|
||
**Feature Branch**: `010-bank-transfer-config`
|
||
**Created**: 2026-03-23
|
||
**Status**: Implemented
|
||
**Input**: User description: "/speckit-specify 实现 sw-business-bank 银行代扣文件传输配置能力，支持 SFTP/FTP 双协议、租户与银行通道维度的目录分化、统一路径解析与运行时配置切换"
|
||
|
||
## Document Scope & Sources *(mandatory)*
|
||
|
||
- **Target documents**:
|
||
- `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`
|
||
- `docs/design/00_Management/03_Task_Checklist.md`
|
||
- `specs/010-bank-transfer-config/spec.md`
|
||
- **Primary source of truth**:
|
||
- `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`
|
||
- `.specify/memory/constitution.md`
|
||
- **Reference sources**:
|
||
- `docs/guides/BACKEND_CURRENT_STATUS.md`
|
||
- `docs/design/04_Appendix/Archive/03_Design_Docs/营业收费管理系统-概要设计说明书20250912.md`
|
||
- `../water-backend/sw-business-bank/sw-business-bank-server/src/main/resources/application.yaml`
|
||
- `../water-backend/sw-business-bank/sw-business-bank-server/src/main/resources/application-dev.yaml`
|
||
- `../water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/service/bankwithholding/BankWithholdingServiceImpl.java`
|
||
- **Scope decision**: 本次需求在范围内。其目标是在既有 `REV-008` / `SYS-009` 银行代扣能力基础上补齐文件传输配置、路径分化与运行时切换能力，并将结果回写到现有正式主文档，不新增平行正式稿。
|
||
|
||
## Repository Scope *(mandatory)*
|
||
|
||
- **Target repos**:
|
||
- `water-docs`: Required
|
||
- `water-backend`: Required
|
||
- `water-frontend`: Not Required
|
||
- **Expected delivery type**: Mixed
|
||
- **Out of scope for this round**:
|
||
- 真实银行生产联调、白名单开通与正式网络连通性验收
|
||
- 具体银行私有文件报文格式的逐字段解析补完
|
||
- `BankCollection` 托收链路与前端运营页面同步改造
|
||
- 新建独立的正式主文档替代现有接口设计、详细设计、部署设计或安全设计主文档
|
||
|
||
## Code Baseline *(mandatory for brownfield work)*
|
||
|
||
- **Backend baseline**: `water-backend` `001-sys009-withholding-closure` @ `84493513c1d06936210ab7e697985d38958ba5ee`
|
||
- **Frontend baseline**: N/A
|
||
- **Baseline capture rule**: 所有“已支持”“待实现”“运行时可切换”“仍需联调补证”的判断，必须绑定到本次 backend baseline，并在验证工件中标明对应配置入口、路径解析入口和最小验证结果。
|
||
|
||
## Evidence Scope *(mandatory)*
|
||
|
||
- **Document evidence required**:
|
||
- `specs/010-bank-transfer-config/spec.md`
|
||
- `docs/design/02_Detailed_Design/12_REV_Detailed.md` 中 `REV-008` 银行代扣文件通道与路径分化口径
|
||
- `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` 中运行环境、配置中心与文件通道部署口径
|
||
- 管理台账中的进度记录与任务状态更新
|
||
- **Backend evidence required**:
|
||
- `sw-business-bank` 现有送盘、回盘、对账路径生成逻辑的基线证据
|
||
- 新增的文件传输配置承接入口、路径解析入口与协议选择入口
|
||
- 至少覆盖默认配置、租户覆盖、通道覆盖、阶段目录解析的自动化验证
|
||
- 最小编译或测试验证结果
|
||
- **Frontend evidence required**:
|
||
- N/A
|
||
- **Verification artifacts required**:
|
||
- `specs/010-bank-transfer-config/baseline.md`
|
||
- `specs/010-bank-transfer-config/backend-validation.md`
|
||
- `specs/010-bank-transfer-config/docs-validation.md`
|
||
- `specs/010-bank-transfer-config/final-verdict.md`
|
||
|
||
## Clarifications
|
||
|
||
### Session 2026-03-23
|
||
|
||
- Q: 运行时配置切换应如何作用于已开始或已落库的批次？ → A: 配置变更仅对新发起的文件动作生效；已开始或已落库的批次继续沿用原解析结果。
|
||
- Q: 目录规则中的路径模板应支持多大范围的动态能力？ → A: 仅支持固定变量集合，例如 `{tenantId}`、`{companyId}`、`{channelCode}`、`{yyyyMMdd}`、`{yyyyMM}`、`{batchNo}`、`{fileName}`。
|
||
- Q: 审计追溯时，除最终解析结果外，是否必须额外留存配置版本或完整配置快照？ → A: 只留存最终实际使用的协议、目录、文件路径与文件名，不强制留存配置版本号或完整配置快照。
|
||
- Q: 当配置缺失或协议连接信息不完整时，系统应如何处理当前文件动作？ → A: 立即阻断本次文件动作，返回明确配置错误，由调用方或运维后续处理。
|
||
|
||
## User Scenarios & Testing *(mandatory)*
|
||
|
||
### User Story 1 - 配置外部化管理银行文件通道 (Priority: P1)
|
||
|
||
作为银行代扣运维或实施人员，我需要把文件传输协议、连接信息和各阶段目录从代码中抽离到运行时配置中，这样我可以在不同环境、不同租户或不同银行通道下复用同一套业务实现，而不必为目录差异反复改代码。
|
||
|
||
**Why this priority**: 这是本次需求的核心。如果协议和目录仍散落在代码里，后续租户扩展、银行切换和运维交接都会继续依赖人工改码，无法形成稳定可交付能力。
|
||
|
||
**Independent Test**: 评审人仅根据规格和验证工件，即可确认系统已经定义了外部化的协议、连接与目录配置边界，并明确哪些目录允许默认值、租户覆盖和通道覆盖。
|
||
|
||
**Acceptance Scenarios**:
|
||
|
||
1. **Given** 系统存在送盘、回盘、对账等不同文件阶段，**When** 运维为某银行通道配置文件传输规则，**Then** 各阶段目录必须可独立定义，而不是共用单一路径。
|
||
2. **Given** 某租户沿用通道默认目录，另一租户需要独立目录，**When** 两者并行运行，**Then** 租户专属配置只影响自身，不影响其他租户或默认通道配置。
|
||
|
||
---
|
||
|
||
### User Story 2 - 运行时统一解析路径与协议 (Priority: P2)
|
||
|
||
作为后端运行服务，我需要在执行送盘、回盘、对账等文件动作时，按统一规则解析当前应使用的协议、连接和目录，这样相同业务动作在不同租户、机构、通道和日期条件下都能得到一致、可追踪的文件路径。
|
||
|
||
**Why this priority**: 仅有配置项但没有统一解析规则，会导致送盘、回盘、对账继续各自拼接路径，最终形成新的散乱实现，无法真正支持运行时切换。
|
||
|
||
**Independent Test**: 通过自动化验证或人工核对工件，可以独立判断默认规则、覆盖优先级、缺省回退和配置缺失时的失败行为是否定义清晰。
|
||
|
||
**Acceptance Scenarios**:
|
||
|
||
1. **Given** 同一银行通道下存在全局默认目录和租户级覆盖目录，**When** 服务解析某租户的送盘路径，**Then** 必须优先使用更具体的覆盖规则，并在未覆盖的阶段回退到低优先级配置。
|
||
2. **Given** 文件传输协议可在 SFTP 和 FTP 间选择，**When** 某通道切换协议但业务动作不变，**Then** 服务必须按新协议选择相应连接信息，而不要求修改业务代码路径拼接逻辑。
|
||
|
||
---
|
||
|
||
### User Story 3 - 形成可审计的文档与验证闭环 (Priority: P3)
|
||
|
||
作为项目治理与评审人员，我需要正式文档、基线和验证工件同步更新，这样后续计划、任务拆解和联调准备都能直接复用统一口径，而不需要再次解释当前能力边界。
|
||
|
||
**Why this priority**: 文件传输配置能力既影响实现，也影响接口边界、安全与部署口径；如果只改代码不回写正式文档，后续评审和联调会再次出现“设计与实现脱节”。
|
||
|
||
**Independent Test**: 仅检查 `specs/010-bank-transfer-config/` 工件和被更新的正式文档，即可确认本轮的目标、基线、验证结果、剩余风险和台账同步情况。
|
||
|
||
**Acceptance Scenarios**:
|
||
|
||
1. **Given** 本轮涉及银行文件通道配置与路径解析能力扩展，**When** 功能完成，**Then** 正式文档必须明确协议选择、目录分化、凭据管理和未完成的真实联调边界。
|
||
2. **Given** 本轮属于 brownfield 功能增强，**When** 收尾，**Then** 管理台账必须记录本次范围、最小验证结果和后续待补证事项。
|
||
|
||
---
|
||
|
||
### Edge Cases
|
||
|
||
- 当某租户仅覆盖送盘目录而未覆盖回盘、对账目录时，系统必须对未覆盖阶段回退到更低优先级配置，而不是产生空路径。
|
||
- 当租户级覆盖与通道级覆盖同时存在且指向不同目录时，系统必须有固定优先级，避免不同动作解析结果不一致。
|
||
- 当协议已切换但对应连接信息不完整时，系统必须阻断本次文件动作，并给出可定位的失败原因，而不是沿用旧协议静默执行。
|
||
- 当配置在批次处理中发生变更时，系统必须保证已开始或已落库的批次继续沿用原解析结果，避免送盘、回盘和对账记录跨版本漂移。
|
||
- 当业务日期参与目录分层时，系统必须保证同一批次的记录路径与实际执行路径一致，避免送盘记录、回盘记录和对账记录彼此无法追溯。
|
||
- 当目录规则引用动态变量时，系统必须仅允许使用预先定义并已文档化的固定变量集合，禁止使用未声明的自由表达式或任意脚本化拼装。
|
||
- 当目录规则引用未声明变量时，系统必须立即阻断当前文件动作并返回可诊断错误。
|
||
- 当系统进行审计追溯时，必须能够还原某次文件动作最终实际使用的协议、目录、文件路径与文件名；本轮不以配置版本号或完整配置快照作为强制留存项。
|
||
- 当运行环境、租户、机构和银行通道的组合未命中任何有效配置时，系统必须立即阻断当前文件动作并返回明确的配置缺失结论，而不是回退到错误租户或错误通道的目录。
|
||
|
||
## Assumptions
|
||
|
||
- 本轮优先覆盖 `BankWithholding` 代扣链路，不要求同时完成 `BankCollection` 托收链路对等改造。
|
||
- 运行时配置中心沿用当前 `sw-business-bank` 已使用的配置加载方式，不在本轮重新定义新的配置基础设施。
|
||
- 文件传输目录分化至少覆盖送盘、回盘、对账、归档和本地临时目录五类场景。
|
||
- 本轮对 `ARCHIVE` 与 `LOCAL_TEMP` 至少要求具备统一解析能力与验证覆盖，不强制新增独立持久化审计对象。
|
||
- 真实银行账号、密码、密钥和网络连通性仍按环境安全流程管理，本轮只定义正式口径与承接能力，不把真实凭据写入仓库文档。
|
||
|
||
## Requirements *(mandatory)*
|
||
|
||
### Functional Requirements
|
||
|
||
- **FR-001**: 系统必须支持将银行代扣文件传输的协议、连接信息和阶段目录从业务代码中外部化管理。
|
||
- **FR-002**: 系统必须支持 SFTP 与 FTP 两种文件传输模式，并允许按银行通道选择其一作为当前生效模式。
|
||
- **FR-003**: 系统必须支持分别定义送盘、回盘、对账、归档和本地临时目录，而不是把所有文件动作绑定到同一路径。
|
||
- **FR-004**: 系统必须支持全局默认规则、银行通道规则、租户规则，以及租户下银行通道规则四级配置表达能力。
|
||
- **FR-005**: 系统必须定义固定的目录解析优先级，使更具体的配置覆盖更通用的配置，且解析结果在所有文件阶段上保持一致。
|
||
- **FR-006**: 系统必须根据当前运行上下文解析文件路径；该上下文至少包括租户、机构、银行通道、业务类型（businessType）、文件阶段和业务日期。
|
||
- **FR-007**: 系统必须支持在目录规则中引用命名上下文变量；变量集合必须限定为预先定义、可文档化的固定变量，不支持自由表达式或脚本化模板能力。
|
||
- **FR-008**: 系统必须支持在不修改业务代码的前提下切换文件传输协议或目录规则；配置变更仅对新发起的文件动作生效，已开始或已落库的批次必须继续沿用原解析结果。
|
||
- **FR-009**: 系统必须在每次送盘、回盘、对账等文件动作中留存实际使用的协议、目录、文件路径与文件名，以便后续审计和问题追踪；本轮不强制留存配置版本号或完整配置快照。
|
||
- **FR-010**: 当上层覆盖配置未完整定义所有目录时，系统必须对缺失项回退到下一级有效配置，而不是生成空值或错误拼接路径。
|
||
- **FR-011**: 当当前协议缺少必要连接信息或未命中任何有效目录规则时，系统必须立即阻断当前文件动作并返回可诊断的配置错误结论，由调用方或运维后续处理。
|
||
- **FR-012**: 正式文档必须同步说明该能力属于 `REV-008` / `SYS-009` 的实现增强，并明确其与真实银行文件解析、生产联调和运行态样本补证的边界关系。
|
||
- **FR-013**: 正式文档必须同步说明文件传输凭据、协议选择和环境配置属于安全与部署约束的一部分，不得将敏感凭据写入正式文档或默认仓库配置样例。
|
||
- **FR-014**: 验证工件必须覆盖默认规则、租户覆盖、通道覆盖、租户-通道覆盖、字段级回退、协议切换、非法变量失败和配置缺失失败等场景中的最小样本。
|
||
- **FR-015**: 重要正式文档修改完成后，必须更新 `docs/design/00_Management/01_Project_Progress.md` 的变更记录；当本轮任务项达到可关闭状态时，必须更新 `docs/design/00_Management/03_Task_Checklist.md`。
|
||
- **FR-016**: 变更完成后必须执行与改动范围匹配的最小校验，至少包括被修改正式文档的单文件校验；涉及链接或 Mermaid 变化时，必须补充对应校验。
|
||
|
||
### Key Entities *(include if feature involves data)*
|
||
|
||
- **File Transfer Policy**: 描述协议、连接信息来源、目录规则与覆盖优先级的一组正式配置对象。
|
||
- **Directory Resolution Context**: 一次文件动作在解析目录时使用的上下文信息，包含租户、机构、通道、业务类型（businessType）、文件阶段和业务日期等要素。
|
||
- **Stage Directory Rule**: 面向送盘、回盘、对账、归档或本地临时目录的单阶段路径规则，可被默认规则或覆盖规则承接。
|
||
- **Override Scope**: 用于表达默认、通道、租户和租户-通道四种不同粒度配置来源的作用域对象。
|
||
- **Resolved File Location**: 某次具体文件动作最终得到的协议、目录和文件路径结果，用于执行与审计追溯。
|
||
- **Verification Artifact**: 记录基线、验证步骤、验证结果和最终结论的工件文件。
|
||
|
||
## Success Criteria *(mandatory)*
|
||
|
||
### Measurable Outcomes
|
||
|
||
- **SC-001**: 评审人能够从规格与验证工件中明确识别 5 类文件阶段（送盘、回盘、对账、归档、本地临时）各自的目录承接规则。
|
||
- **SC-002**: 至少 3 组不同作用域组合（默认、租户覆盖、通道覆盖或租户-通道覆盖）能够被独立验证，并得到不相同且可解释的解析结果。
|
||
- **SC-003**: 协议从一种传输模式切换到另一种传输模式时，不需要修改业务代码即可完成后续执行路径选择。
|
||
- **SC-004**: 验证工件能够独立说明目录解析优先级、缺省回退规则和配置缺失时的失败结论，评审人无需阅读源代码即可判断行为是否正确。
|
||
- **SC-005**: 本轮产出的正式文档、基线工件、验证工件和台账记录全部可定位，且规格中不保留 `[NEEDS CLARIFICATION]` 标记。
|