fujian_water_biz_doc/specs/007-sys009-design-align/spec.md

# Feature Specification: SYS-009设计整合与实现对齐

**Feature Branch**: `007-sys009-design-align`
**Created**: 2026-03-20
**Status**: Draft
**Input**: User description: "我需要将 /Users/tangweijie/github/water-bank-api-doc 这里的SYS-009的设计整合到我们文档里面来,并且和现在实现的代码进行对其"

## 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/01_Database_Design.md`
  - `docs/design/01_Overview/03_Summary_Design.md`
  - `docs/design/00_Management/01_Project_Progress.md`
  - `docs/design/00_Management/03_Task_Checklist.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/01_Database_Design.md`
  - `docs/design/00_Management/01_Project_Progress.md`
  - `docs/design/00_Management/03_Task_Checklist.md`
- **Reference sources**:
  - `/Users/tangweijie/github/water-bank-api-doc/营收系统缴费接口.md`
  - `/Users/tangweijie/github/water-bank-api-doc/营收系统接口规范设计文档.md`
  - `/Users/tangweijie/github/water-bank-api-doc/docs/README.md`
  - `docs/guides/BACKEND_CURRENT_STATUS.md`
  - `docs/guides/BACKEND_TABLE_MAPPING.md`
  - `docs/design/04_Appendix/Archive/03_Design_Docs/营业收费管理系统-概要设计说明书20250912.md`
  - `docs/design/04_Appendix/Archive/04_Original_Attachments/营收系统_需求规格说明书.md`
- **Scope decision**: 本次需求在范围内，范围判断以 `docs/design/01_Overview/03_Summary_Design.md` 与 `docs/design/04_Appendix/Archive/03_Design_Docs/营业收费管理系统-概要设计说明书20250912.md` 的交集为准；`SYS-009` 实时收费、代扣、托收、对账相关能力在交集范围内，可进入现有正式主文档整合与当前 backend 实现对齐，不新建平行正式文档。

## Repository Scope *(mandatory)*

- **Target repos**:
  - `water-docs`: Required
  - `water-backend`: Required
  - `water-frontend`: Not Required
- **Expected delivery type**: Document closure / Code evidence alignment
- **Out of scope for this round**:
  - 直接修改 `../water-backend` 或 `../water-frontend` 业务代码
  - 新建独立的“SYS-009 正式主文档”替代现有主文档
  - 在无实现证据的前提下把高级银行接口写成“已完成”
  - 为银行批次、回盘、对账、结算补做前端运营页面设计

## Code Baseline *(mandatory for brownfield work)*

- **Backend baseline**: `water-backend` `develop` @ `68ab72ae6330e33afa0fec3817c0605829973ec2`
- **Frontend baseline**: `water-frontend` `develop` @ `ae65939045449894c0fccab53fee08521e538ddd`（仅用于范围判断，不作为本轮正式承接基线）
- **Baseline capture rule**: 所有“已实现 / 部分实现 / 文档先行”判断都必须绑定到本次记录的 backend commit SHA，并在后续验证工件中写明对应代码路径与判定理由。

## Evidence Scope *(mandatory)*

- **Document evidence required**:
  - `specs/007-sys009-design-align/spec.md`
  - 正式文档中与 `SYS-009`、`REV-008`、外部银行接口相关的修订章节
  - 管理台账中的变更记录与任务状态更新
- **Backend evidence required**:
  - 实时收费接口证据：`PayCebController`、`PayCebServiceImpl`
  - 银行代扣接口证据：`BankWithholdingController`、`BankWithholdingServiceImpl`
  - 银行托收接口证据：`BankCollectionController`、`BankCollectionServiceImpl`
  - 数据对象证据：`docs/建表sql.sql`、`bk_transaction*`、`bk_withholding_*`、`bk_reconcile_*`、`bk_settlement_batch`
  - 运营侧入口证据：`WithholdingAgreementController`、`WithholdingBatchController`、`ReconcileBatchController`、`SettlementBatchController`
- **Frontend evidence required**:
  - 非强制
  - 如需说明边界，仅记录当前客户代扣资料维护入口与缺失的银行批次运营界面，不形成 frontend 改造范围
- **Verification artifacts required**:
  - `specs/007-sys009-design-align/baseline.md`
  - `specs/007-sys009-design-align/final-verdict.md`

## User Scenarios & Testing *(mandatory)*

### User Story 1 - 整合正式设计口径 (Priority: P1)

作为文档评审人，我需要在现有正式主文档中看到 `SYS-009` 银行侧能力的统一设计口径，这样我可以用一套正式材料评审实时收费、代扣、送盘、回盘、对账与结算能力，而不是同时维护外部原始资料和仓内多份描述。

**Why this priority**: 这是本次需求的核心目标；如果正式文档不先吸收 `SYS-009` 设计，后续代码评审、验收和任务拆解都会继续依赖仓外资料，无法形成单一交付入口。

**Independent Test**: 仅阅读更新后的正式主文档，即可定位 `SYS-009` 相关能力范围、接口边界、关键数据对象和与 `REV-003` / `REV-008` 的关系，无需再依赖仓外原始接口文档。

**Acceptance Scenarios**:

1. **Given** 正式文档目前仅概括了 `SYS-009` 的实时收费、代扣、对账、结算能力，**When** 本次整合完成，**Then** 正式文档必须明确承接外部来源中的实时收费、代扣签约/解约、送盘、回盘、对账、状态查询与取消等关键能力簇。
2. **Given** 外部 `water-bank-api-doc` 存在银行协议与接口细节，**When** 设计被回写到正式主文档，**Then** 必须保持当前文档编号、术语和主文档结构稳定，而不是新增平行主稿。

---

### User Story 2 - 对齐当前实现边界 (Priority: P2)

作为技术评审人，我需要知道 `SYS-009` 哪些设计已经被当前 backend 实现承接、哪些只是接口骨架或数据模型已具备、哪些仍然只是文档先行，这样我可以据此安排后续开发和验收范围。

**Why this priority**: 仅有设计整合但没有实现对齐，会把“接口存在”“代码完成”“数据表已建”混为一谈，直接影响后续任务排序和风险判断。

**Independent Test**: 对照文档中的对齐结论和 backend 验证工件，评审人应能独立判断实时收费、代扣签约/解约、客户状态查询、送盘、回盘、对账等能力分别处于哪种状态。

**Acceptance Scenarios**:

1. **Given** backend 已存在 `PayCeb*` 与 `BankWithholding*` 代码入口，**When** 文档完成对齐，**Then** 文档必须区分“已实现”“部分实现”“文档先行”三类状态，而不能统一写成“已支持”。
2. **Given** backend 中部分接口仍为 TODO 或占位返回，**When** 文档回写正式口径，**Then** 必须把这些能力标记为待补实现或仅保留设计边界，不能误写为已落地闭环。

---

### User Story 3 - 形成可审计证据链 (Priority: P3)

作为项目治理人员，我需要这次整合留下可追溯的基线、验证和结论工件，这样后续 `/speckit.plan`、任务拆解和验收结论都能直接复用，不再重复做同一轮对齐判断。

**Why this priority**: 没有基线和验证工件，正式文档即使更新，也难以证明它对应的是哪一版实现和哪些证据。

**Independent Test**: 只检查 `specs/007-sys009-design-align/` 下的工件与管理台账，即可确认本轮使用的代码基线、核对过的证据路径以及最终结论。

**Acceptance Scenarios**:

1. **Given** 本轮需要引用外部设计与当前代码，**When** 验证结束，**Then** 必须能从工件中看到代码基线、证据路径、结论和未闭环项。
2. **Given** 正式主文档发生重要更新，**When** 本轮收尾，**Then** `01_Project_Progress.md` 与 `03_Task_Checklist.md` 必须同步回写本次变更摘要和收尾状态。

---

### Edge Cases

- 当 `water-bank-api-doc` 的接口设计比当前正式文档更细，但 backend 仅实现了其中一部分时，正式文档必须同时保留目标设计边界和当前实现状态，不能只保留其一。
- 当外部设计文档的 OpenAPI 版本遗漏了对账、客户状态查询、取消送盘、状态查询等高级接口时，应回退到原始 Markdown 接口说明核对，而不是误判这些能力“不在设计范围”。
- 当 backend 已有 `bk_*` 表族和后台管理控制器，但银行 app 侧接口仍是 TODO 时，文档必须避免把“后台对象存在”直接等同为“银行协同闭环完成”。
- 当 frontend 只存在客户代扣资料维护入口而不存在银行批次、回盘、对账运营页面时，正式文档必须明确这是当前范围边界，而不是默认这些页面已落地。

## Assumptions

- 本轮“整合 `SYS-009` 设计”是指回写到现有正式主文档体系，而不是创建新的正式交付主稿。
- 当前实现对齐以 `water-backend` 为主要证据来源，因为银行协议接口、交易流水、批次、回盘、对账和结算对象都集中在 backend。
- 对于 controller/service 中仍为 TODO 的能力，本轮会按“部分实现”或“文档先行”处理，而不会要求在本轮直接补代码。
- `water-bank-api-doc` 是本轮银行接口语义的重要参考，但正式口径仍以本仓库主文档编号、术语和边界约束为准。

## Requirements *(mandatory)*

### Functional Requirements

- **FR-001**: 规格必须明确本轮将修改的正式主文档，并以现有主文档为唯一正式承接入口。
- **FR-002**: 规格必须覆盖外部 `SYS-009` 来源中的关键银行能力簇，至少包括实时收费、缴费结果处理、代扣签约/解约、客户状态查询、送盘、送盘状态查询、取消送盘、回盘、回盘状态查询、对账与结算。
- **FR-003**: 规格必须定义每个关键能力簇在当前实现中的状态标签，且状态标签至少区分“已实现”“部分实现”“文档先行”三类。
- **FR-004**: 规格必须要求正式文档中的接口、时序、数据对象和模块描述与当前 backend 的 `bk_transaction*`、`bk_withholding_*`、`bk_reconcile_*`、`bk_settlement_batch` 等对象口径一致。
- **FR-005**: 规格必须要求正式文档保持当前编号和引用体系稳定，不得为本轮整合发明新的并行编号规则或新的平行正式文档。
- **FR-006**: 规格必须记录 backend 基线版本，并要求所有实现判断可追溯到具体代码路径和该基线版本。
- **FR-007**: 规格必须限定本轮以文档修订和代码证据核对为主，不直接包含 backend 或 frontend 业务代码改造。
- **FR-008**: 规格必须要求在正式文档中明确实时收费与银行代扣是不同协同路径，避免把查询/缴费、送盘/回盘、对账/结算混写为同一处理流程。
- **FR-009**: 规格必须要求当外部设计与当前实现不一致时，正式文档优先表达当前可落地边界，并对未落地能力保留清晰的待实现说明。
- **FR-010**: 规格必须要求正式文档同步说明 `REV-003`、`REV-008` 与 `SYS-009` 之间的职责边界，避免把营收业务规则、银行渠道协议和聚合支付职责混淆。
- **FR-011**: 规格必须要求在本轮输出验证工件，至少包括代码基线、正式文档校验、backend 证据核对和最终结论。
- **FR-012**: 规格必须要求重要正式文档修改完成后，更新 `docs/design/00_Management/01_Project_Progress.md` 的变更记录。
- **FR-013**: 规格必须要求当本轮任务项达到可关闭状态时，更新 `docs/design/00_Management/03_Task_Checklist.md` 的任务说明。
- **FR-014**: 规格必须要求对变更后的正式文档执行适用的最小校验动作，包括单文件校验、链接检查或 Mermaid 检查。

### Key Entities *(include if feature involves data)*

- **Source Capability**: 外部 `water-bank-api-doc` 中定义的一个银行协同能力簇，例如实时收费、代扣签约、送盘、回盘、对账。
- **Formal Document Section**: 本仓库正式主文档中承接 `SYS-009` 设计的章节或表格单元，是本轮最终交付的正式落点。
- **Backend Evidence Item**: 用于证明当前实现状态的 controller、service、数据对象、建表 SQL 或管理入口。
- **Alignment Verdict**: 对单个能力簇给出的实现结论，取值为“已实现”“部分实现”“文档先行”之一。
- **Code Baseline**: 用于锚定本轮对齐判断的相邻代码仓提交版本。
- **Verification Artifact**: 本轮在 `specs/007-sys009-design-align/` 下生成的基线、验证和最终结论文档。

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: 正式文档中至少明确 5 组 `SYS-009` 能力簇的承接口径，且每组能力簇都能映射到目标文档中的具体章节或表格位置。
- **SC-002**: 每个被纳入正式文档的 `SYS-009` 能力簇都至少关联 1 个外部来源和 1 个当前代码证据，或明确标注其仅为文档先行能力。
- **SC-003**: 评审人能够基于本轮工件独立判断实时收费、代扣签约/解约、送盘、回盘、对账、结算各自属于“已实现”“部分实现”还是“文档先行”。
- **SC-004**: 本轮基线、文档验证、backend 证据核对和最终结论工件全部具备明确文件名和用途，后续无需重新定义验证结构即可进入 `/speckit.plan`。
- **SC-005**: 本轮规格中不保留 `[NEEDS CLARIFICATION]` 标记，且范围边界、依赖来源、验证动作和台账更新责任均可直接执行。