diff --git a/docs/design/01_Overview/03_Summary_Design.md b/docs/design/01_Overview/03_Summary_Design.md index ac3fc0a..369c6c4 100644 --- a/docs/design/01_Overview/03_Summary_Design.md +++ b/docs/design/01_Overview/03_Summary_Design.md @@ -147,7 +147,7 @@ retrieval_priority: P0 - 业务服务层：SYS-001 统一平台、SYS-002 营收业务系统、SYS-003 手机抄表APP、SYS-004 微网厅系统、SYS-005 工单管理系统、SYS-006 表务管理系统、SYS-007 报装业务系统 -- 基础服务层：SYS-008 发票服务子系统（统一开票）、SYS-009 支付与银行结算子系统（统一聚合支付/退款/渠道适配/第三方支付平台/银行代扣/夜间批量代扣/对账/加解密/支付回调）、SYS-010 消息服务子系统（统一短信/邮件/站内信/模板消息/微信通知/数科系统对接）、注册/配置中心、任务调度等基础服务 +- 基础服务层：SYS-008 发票服务子系统（统一开票）、SYS-009 支付与银行结算子系统（统一聚合支付/退款/渠道适配/第三方支付平台/银行实时收费、代扣/托收签解约、批次与对账契约、加解密与支付回调，夜间批量代扣/完整对账结算按后续完善项管理）、SYS-010 消息服务子系统（统一短信/邮件/站内信/模板消息/微信通知/数科系统对接）、注册/配置中心、任务调度等基础服务   通过系统的建设，实现福建省水投数字科技有限公司客户服务管理领域的业务流程梳理再造、组织架构的优化、管理制度的建设、绩效考核标准的建设。构建以客户为中心的一体化服务体系，将客户的所有信息进行有机的关联，方便企业对营收信息进行综合分析和管理，为客户提供更多、更便捷、更主动的个性化服务，提高客户服务的质量和客户满意度。 @@ -161,7 +161,7 @@ retrieval_priority: P0 - **表务管理系统**：设备档案、表务全生命周期管理 - **报装业务系统**：覆盖报装申请、踏勘、施工、验收、通水与档案归档的端到端流程,支持调用泛微进行合同签订，电子签章，支持各租户自定义报装流程和表单定义 - **发票服务子系统**（基础服务）：统一开票网关与供应商适配（现优先对接航天，预留博思），回执与存证 -- **支付与银行对接子系统**（基础服务）：统一支付/退款、银行代扣送盘/回盘、对账处理、加解密签名,第三方支付平台（微信、支付宝），支持夜间进行批量代扣 +- **支付与银行对接子系统**（基础服务）：统一支付/退款、银行实时收费、代扣/托收签解约、送盘/回盘/对账契约、加解密签名与第三方支付平台（微信、支付宝）；夜间批量代扣和完整结算闭环按后续完善项管理 - **消息服务子系统**（基础服务）：统一短信/邮件/站内信/模板消息，下行推送与到达回执，供各业务子系统调用（如营收业务系统催缴），微信信息通知，对接数科已建系统通知（OA、智水擎，水投数科 app） ### 功能范围 @@ -206,6 +206,7 @@ retrieval_priority: P0 #### SYS-009 支付与银行结算子系统（基础服务） - 聚合支付/退款、渠道适配（微信/支付宝/银联聚合等）、第三方支付平台（微信、支付宝）、支付结果通知、银行代扣（送盘/回盘）、支持夜间进行批量代扣、对账文件处理、加解密/签名 +- 当前实现侧已确认聚合支付基础能力、银行欠费查询/缴费、`BankWithholding` 六条银行入口（客户状态查询、送盘、送盘状态查询、取消送盘、回盘、回盘状态查询）、代扣/托收签约解约和后台资源管理具备证据；其中 `BankCollection` 平行链路、夜间批量代扣、完整对账与结算仍按部分实现或后续完善项管理 #### SYS-010 消息服务子系统（基础服务） @@ -747,7 +748,7 @@ graph TB | SYS-006 | 表务管理系统 | 设备档案、表务全生命周期管理 | 自行开发 | | SYS-007 | 报装业务系统 | 报装流程管理、合同签订与电子签章、工程管理、档案管理 | 自行开发 | | SYS-008 | 发票服务子系统 | 统一开票网关、供应商适配器（优先对接航天）、回执处理与存证 | 自行开发 | -| SYS-009 | 支付与银行结算子系统 | 聚合支付/退款、渠道适配（微信/支付宝/银联）、支付通知、银行代扣送盘/回盘、夜间批量代扣、对账处理、加解密签名 | 自行开发 | +| SYS-009 | 支付与银行结算子系统 | 聚合支付/退款、渠道适配（微信/支付宝/银联）、支付通知、银行实时收费、代扣/托收签解约、送盘/回盘/对账契约、加解密签名；夜间批量代扣与完整结算闭环按后续完善项管理 | 自行开发 | | SYS-010 | 消息服务子系统 | 短信/邮件/站内信模板与发送、回执查询、批量推送 | 自行开发 | ### 子系统间关系 @@ -3675,14 +3676,14 @@ graph TD ## 任务概述 -  支付与银行结算子系统（SYS-009）统一承载聚合支付/退款、渠道适配（微信/支付宝/银联聚合）、支付回调验签入账，以及银行代扣（送盘/回盘）、支持夜间进行批量代扣、对账文件处理与安全加解密/签名，向上对营收/微网厅等系统提供标准化支付与结算能力。 +  支付与银行结算子系统（SYS-009）统一承载聚合支付/退款、渠道适配（微信/支付宝/银联聚合）、支付回调验签入账，以及银行实时收费、代扣/托收签约解约、送盘/回盘/对账契约与安全加解密/签名，向上对营收/微网厅等系统提供标准化支付与结算能力。夜间批量代扣、完整回盘状态补偿、对账差异处理与结算确认当前仍按后续完善项管理。 ## 设计概述 ### 总体约束 - 多渠道聚合：统一接入微信/支付宝/银联聚合 -- 统一结算：批量代扣送回盘、批量对账文件处理、差异对齐 +- 统一结算：统一维护批次、回盘、对账和差异语义，完整结算闭环按后续完善项推进 - 安全合规：签名/验签、加解密、回调防重放、幂等 - 高可用：基础重试补偿机制 @@ -3692,7 +3693,7 @@ graph TD ### 子系统外部接口（SYS-009） -  支付与银行结算子系统作为统一的支付能力中心，为上游业务系统提供聚合支付、银行代扣、退款处理、对账管理等全方位的支付结算服务。系统与微信支付、支付宝、银联聚合及各大银行系统对接，提供安全可靠的支付解决方案。 +  支付与银行结算子系统作为统一的支付能力中心，为上游业务系统提供聚合支付、银行实时收费、代扣/托收签解约、退款处理、对账管理等支付结算服务。以下接口表表达的是正式设计目标边界，其中聚合支付、实时收费查询/缴费、代扣/托收签解约已具备较明确实现证据；`BankWithholding` 六条银行入口已形成最小实现态闭环，托收平行链路、对账和完整结算闭环仍按部分实现或后续完善项管理。 | 接口编号 | 接口名称 | 功能描述 | 调用方 | 接口协议 | 输入参数 | 输出结果 | |---|---|---|---|---|---|---| @@ -3700,9 +3701,9 @@ graph TD | IF-PAY-002 | 统一关单接口 | 订单关闭和撤销处理 | 营收系统/微网厅 | HTTP/REST | 订单号、关闭原因、操作类型 | 关单状态、退款信息、处理结果 | | IF-PAY-003 | 统一退款接口 | 原路退款和部分退款处理 | 营收系统/微网厅 | HTTP/REST | 原订单号、退款金额、退款原因 | 退款单号、退款状态、预计到账时间 | | IF-PAY-004 | 支付回调接口 | 接收渠道支付结果回调 | 微信/支付宝/银联 | HTTP/REST | 回调数据、签名、时间戳 | 处理确认、业务更新状态 | -| IF-PAY-005 | 批量代扣送盘接口 | 银行批量代扣文件发送 | 营收业务系统 | HTTP/REST/SFTP | 代扣清单、客户签约信息、扣款金额 | 送盘状态、批次号、预计处理时间 | -| IF-PAY-006 | 批量代扣回盘接口 | 银行代扣结果回盘处理 | 银行系统 | HTTP/REST/SFTP | 回盘文件、处理结果、失败原因 | 解析结果、状态更新、异常处理 | -| IF-PAY-007 | 批量对账文件接口 | 银行对账文件处理分析 | 银行系统/营收系统 | HTTP/REST/SFTP | 对账文件、对账日期、差异规则 | 对账结果、差异明细、调整建议 | +| IF-PAY-005 | 批量代扣送盘接口 | 银行批量代扣文件发送 | 营收业务系统 | HTTP/REST/SFTP | 代扣清单、客户签约信息、扣款金额 | 送盘状态、批次号、预计处理时间（`BankWithholding` 已具备最小实现态闭环；真实文件通道联调仍待补证） | +| IF-PAY-006 | 批量代扣回盘接口 | 银行代扣结果回盘处理 | 银行系统 | HTTP/REST/SFTP | 回盘文件、处理结果、失败原因 | 解析结果、状态更新、异常处理（`BankWithholding` 已具备最小实现态闭环；真实文件解析与异常补偿仍待补证） | +| IF-PAY-007 | 批量对账文件接口 | 银行对账文件处理分析 | 银行系统/营收系统 | HTTP/REST/SFTP | 对账文件、对账日期、差异规则 | 对账结果、差异明细、调整建议（当前仍按部分实现或后续完善项管理） | | IF-PAY-008 | 加解密签名接口 | 支付数据安全处理 | 内部模块调用 | HTTP/REST | 待处理数据、加密类型、签名算法 | 处理结果、安全凭证、验证状态 | ## 子系统架构设计 @@ -3831,6 +3832,7 @@ graph TD - 差异识别与异常记录 - 冲正/补记建议生成 - 对账报告与追踪链路告警 +- 当前阶段按目标能力保留正式设计口径，不直接表述为已形成完整闭环 #### PAY-006: 加解密/签名 diff --git a/docs/design/03_Technical_Design/01_Database_Design.md b/docs/design/03_Technical_Design/01_Database_Design.md index 771c05b..84ff12a 100644 --- a/docs/design/03_Technical_Design/01_Database_Design.md +++ b/docs/design/03_Technical_Design/01_Database_Design.md @@ -1223,6 +1223,8 @@ retrieval_priority: P0 | `bk_reconcile_diff` | `batch_id`, `trade_no`, `diff_type`, `diff_amount` | 对账差异 | | `bk_settlement_batch` | `batch_no`, `channel_code`, `settlement_date`, `settlement_status` | 结算批次 | +> 当前实现边界说明：`bk_*` 表族已形成较完整的对象承接口径，且签约、解约、交易流水与后台资源管理具备明确实现证据；但送盘、回盘、对账、结算等业务编排仍缺少完整闭环与统一迁移证据，数据库专项不得据此倒推出“银行协同已全部落地”。 + diff --git a/specs/007-sys009-design-align/baseline.md b/specs/007-sys009-design-align/baseline.md new file mode 100644 index 0000000..856fbf1 --- /dev/null +++ b/specs/007-sys009-design-align/baseline.md @@ -0,0 +1,31 @@ +# Baseline: SYS-009设计整合与实现对齐 + +## Repository Baselines + +| Repo | Branch | Commit | Role in This Feature | +|------|--------|--------|----------------------| +| `water-docs` | `007-sys009-design-align` | working tree | 正式规格、计划与后续文档修订入口 | +| `water-backend` | `develop` | `68ab72ae6330e33afa0fec3817c0605829973ec2` | `SYS-009` 当前实现证据基线 | +| `water-frontend` | `develop` | `ae65939045449894c0fccab53fee08521e538ddd` | 范围排除依据，仅说明本轮不承接银行运营界面 | + +## Baseline Rules + +1. 所有实现成熟度判断均以 `water-backend` 当前 commit 为准。 +2. 若后续代码基线变化，必须同步更新本文件和 `final-verdict.md`。 +3. frontend 不作为本轮正式承接范围，只保留“无完整银行批次/回盘/对账运营界面”的边界说明。 + +## Key Evidence Anchors + +- 实时收费： + - `../water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/controller/app/payceb/PayCebController.java` + - `../water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/service/payceb/PayCebServiceImpl.java` +- 代扣： + - `../water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/controller/app/bankwithholding/BankWithholdingController.java` + - `../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/controller/app/bankcollection/BankCollectionController.java` + - `../water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/service/bankcollection/BankCollectionServiceImpl.java` +- 表结构与后台运营： + - `../water-backend/sw-business-bank/docs/建表sql.sql` + - `../water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/controller/admin/` + diff --git a/specs/007-sys009-design-align/checklists/requirements.md b/specs/007-sys009-design-align/checklists/requirements.md new file mode 100644 index 0000000..b6aa057 --- /dev/null +++ b/specs/007-sys009-design-align/checklists/requirements.md @@ -0,0 +1,36 @@ +# Specification Quality Checklist: SYS-009设计整合与实现对齐 + +**Purpose**: Validate specification completeness and quality before proceeding to planning +**Created**: 2026-03-20 +**Feature**: [spec.md](../spec.md) + +## Content Quality + +- [x] No implementation details (languages, frameworks, APIs) +- [x] Focused on user value and business needs +- [x] Written for non-technical stakeholders +- [x] All mandatory sections completed + +## Requirement Completeness + +- [x] No [NEEDS CLARIFICATION] markers remain +- [x] Requirements are testable and unambiguous +- [x] Success criteria are measurable +- [x] Success criteria are technology-agnostic (no implementation details) +- [x] All acceptance scenarios are defined +- [x] Edge cases are identified +- [x] Scope is clearly bounded +- [x] Dependencies and assumptions identified + +## Feature Readiness + +- [x] All functional requirements have clear acceptance criteria +- [x] User scenarios cover primary flows +- [x] Feature meets measurable outcomes defined in Success Criteria +- [x] No implementation details leak into specification + +## Notes + +- Validation iteration 1 passed. +- Mandatory sections are complete, no clarification markers remain, and the scope is bounded to formal document integration plus backend evidence alignment. +- Implementation file paths are used only as brownfield evidence anchors, not as prescribed implementation work for this round. diff --git a/specs/007-sys009-design-align/contracts/sys009-capability-alignment.md b/specs/007-sys009-design-align/contracts/sys009-capability-alignment.md new file mode 100644 index 0000000..97a43d3 --- /dev/null +++ b/specs/007-sys009-design-align/contracts/sys009-capability-alignment.md @@ -0,0 +1,30 @@ +# Contract: SYS-009 Capability Alignment + +## Purpose + +定义外部 `SYS-009` 能力簇与本仓库正式文档落点之间的最小对齐契约，供后续文档修订、任务拆解和验收复用。 + +## Alignment Matrix + +| Capability | Formal Domain | Primary Formal Target | Secondary Target | Expected Verdict Types | +|-----------|---------------|-----------------------|------------------|------------------------| +| 实时收费查询/缴费 | `REV-003` | `docs/design/02_Detailed_Design/12_REV_Detailed.md` | `docs/design/03_Technical_Design/03_Interface_Design.md` `IF-EXT-003` | 已实现 / 部分实现 | +| 当日未对账红冲 | `REV-003` | `docs/design/03_Technical_Design/03_Interface_Design.md` | `docs/design/02_Detailed_Design/12_REV_Detailed.md` | 部分实现 / 文档先行 | +| 代扣签约 | `REV-008` | `docs/design/02_Detailed_Design/12_REV_Detailed.md` | `docs/design/03_Technical_Design/03_Interface_Design.md` | 已实现 / 部分实现 | +| 代扣解约 | `REV-008` | `docs/design/02_Detailed_Design/12_REV_Detailed.md` | `docs/design/03_Technical_Design/03_Interface_Design.md` | 已实现 / 部分实现 | +| 代扣客户状态查询 | `REV-008` | `docs/design/03_Technical_Design/03_Interface_Design.md` | `docs/design/02_Detailed_Design/12_REV_Detailed.md` | 部分实现 / 文档先行 | +| 送盘 | `REV-008` | `docs/design/03_Technical_Design/03_Interface_Design.md` `IF-EXT-001` | `docs/design/02_Detailed_Design/12_REV_Detailed.md` | 部分实现 | +| 送盘状态查询 | `REV-008` | `docs/design/03_Technical_Design/03_Interface_Design.md` | `docs/design/02_Detailed_Design/12_REV_Detailed.md` | 部分实现 / 文档先行 | +| 取消送盘 | `REV-008` | `docs/design/03_Technical_Design/03_Interface_Design.md` | `docs/design/02_Detailed_Design/12_REV_Detailed.md` | 部分实现 / 文档先行 | +| 回盘 | `REV-008` | `docs/design/03_Technical_Design/03_Interface_Design.md` `IF-EXT-002` | `docs/design/02_Detailed_Design/12_REV_Detailed.md` | 部分实现 | +| 回盘状态查询 | `REV-008` | `docs/design/03_Technical_Design/03_Interface_Design.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/01_Database_Design.md` | 部分实现 | +| 结算状态协同 | `REV-008` | `docs/design/02_Detailed_Design/12_REV_Detailed.md` | `docs/design/03_Technical_Design/01_Database_Design.md` | 文档先行 / 部分实现 | + +## Contract Rules + +1. 任何能力簇都必须先映射到既有正式主文档，再允许写入计划、任务和验收结论。 +2. 若外部设计存在而 backend 缺少闭环实现，正式文档必须保留目标设计边界，同时显式标注当前成熟度。 +3. 不允许为单个能力簇创建新的平行正式文档。 +4. 若能力簇涉及 `bk_*` 表族，数据库设计只补承接口径，不下沉到实现脚本级细节。 + diff --git a/specs/007-sys009-design-align/contracts/sys009-status-verdicts.md b/specs/007-sys009-design-align/contracts/sys009-status-verdicts.md new file mode 100644 index 0000000..03e991e --- /dev/null +++ b/specs/007-sys009-design-align/contracts/sys009-status-verdicts.md @@ -0,0 +1,37 @@ +# Contract: SYS-009 Status Verdicts + +## Purpose + +定义能力簇状态判定的统一准则，避免在主文档、验证工件和后续任务中出现不同口径。 + +## Verdict Definitions + +| Verdict | Required Evidence | Disallowed Shortcut | +|--------|-------------------|---------------------| +| 已实现 | 具备明确路由/入口、核心业务校验、数据写入或状态更新、结果回写或留痕 | 仅有表结构、仅有后台管理页面、仅有 DTO | +| 部分实现 | 具备接口骨架、DTO、服务接口、部分业务逻辑或局部闭环，但存在 TODO、空实现、未打通的外部文件/状态处理 | 仅凭“将来准备实现”的设计说明 | +| 文档先行 | 有正式设计目标和对象口径，但当前未定位到足够代码证据支撑 | 以外部参考文档直接推断已实现 | + +## Capability Verdicts For This Feature + +| Capability | Initial Verdict | Evidence Anchor | +|-----------|-----------------|-----------------| +| 实时收费查询 | 已实现 | `PayCebController#getChargeSearch` / `PayCebServiceImpl#getChargeSearch` | +| 实时收费缴费 | 已实现 | `PayCebController#getChargeOffs` / `PayCebServiceImpl#getChargeOffs` | +| 代理收费对账 | 部分实现 | `PayCebController#paymentCheck` TODO，占位未闭环 | +| 代扣签约 | 已实现 | `BankWithholdingController#signing` / `BankWithholdingServiceImpl#signing` | +| 代扣解约 | 已实现 | `BankWithholdingController#termination` / `BankWithholdingServiceImpl#termination` | +| 代扣客户状态查询 | 已实现 | `BankWithholdingController#customerCheck` / `BankWithholdingServiceImpl#customerCheck` | +| 送盘 | 已实现 | `BankWithholdingController#sendDisc` / `BankWithholdingServiceImpl#sendDisc` | +| 送盘状态查询 | 已实现 | `BankWithholdingController#sendDiscCheck` / `BankWithholdingServiceImpl#sendDiscCheck` | +| 取消送盘 | 已实现 | `BankWithholdingController#cancelDisc` / `BankWithholdingServiceImpl#cancelDisc` | +| 回盘 | 已实现 | `BankWithholdingController#backDisc` / `BankWithholdingServiceImpl#backDisc` | +| 回盘状态查询 | 已实现 | `BankWithholdingController#backDiscCheck` / `BankWithholdingServiceImpl#backDiscCheck` | +| 托收平行链路 | 部分实现 | `BankCollection*` 路径已存在，成熟度未全闭环 | +| 运营侧批次/对账/结算管理 | 已具备入口 | `WithholdingBatchController` / `ReconcileBatchController` / `SettlementBatchController` | + +## Contract Rules + +1. 主文档中同一能力簇的 verdict 必须与 `final-verdict.md` 保持一致。 +2. 若后续代码变化导致 verdict 升降级，必须同时更新基线和依据。 +3. `已具备入口` 不是独立 verdict，只能作为 supporting note，最终仍需归入三类正式 verdict 之一。 diff --git a/specs/007-sys009-design-align/data-model.md b/specs/007-sys009-design-align/data-model.md new file mode 100644 index 0000000..a9ed0ae --- /dev/null +++ b/specs/007-sys009-design-align/data-model.md @@ -0,0 +1,113 @@ +# Data Model: SYS-009设计整合与实现对齐 + +## 1. Source Capability + +### Purpose + +表示外部 `water-bank-api-doc` 中一个可被正式文档吸收的银行协同能力簇。 + +### Fields + +| Field | Description | Validation | +|------|-------------|------------| +| `capability_id` | 能力标识，如 `REALTIME_PAY`、`WITHHOLD_SIGNING` | 必填，唯一 | +| `capability_name` | 能力名称 | 必填 | +| `business_domain` | 业务归属，如 `REV-003`、`REV-008` | 必填，必须落在当前正式模块范围内 | +| `source_docs` | 来源文档列表 | 至少 1 个 | +| `formal_targets` | 正式承接文档与章节 | 至少 1 个 | +| `current_status` | 当前实现状态 | 必填，取值仅限 `已实现` / `部分实现` / `文档先行` | +| `notes` | 边界说明 | 可选 | + +### Relationships + +- 一个 `Source Capability` 必须映射到至少一个 `Formal Document Section` +- 一个 `Source Capability` 可以关联多个 `Backend Evidence Item` + +## 2. Formal Document Section + +### Purpose + +表示本仓库中承接 `SYS-009` 设计整合结论的正式章节或表格位置。 + +### Fields + +| Field | Description | Validation | +|------|-------------|------------| +| `document_path` | 正式文档路径 | 必填，必须是既有主文档或治理文档 | +| `section_anchor` | 章节锚点或节标题 | 必填 | +| `section_type` | 章节类型，如范围摘要、业务流程、接口契约、数据对象 | 必填 | +| `update_intent` | 本轮更新意图 | 必填 | +| `consistency_impacts` | 受影响的一致性项 | 至少 1 项 | + +### Relationships + +- 一个 `Formal Document Section` 可承接多个 `Source Capability` +- 一个 `Formal Document Section` 可引用多个 `Backend Evidence Item` + +## 3. Backend Evidence Item + +### Purpose + +表示用于判定当前实现状态的代码或表结构证据。 + +### Fields + +| Field | Description | Validation | +|------|-------------|------------| +| `evidence_path` | 证据文件路径 | 必填 | +| `evidence_type` | 类型，如 `controller`、`service`、`table_sql`、`admin_entry` | 必填 | +| `capability_scope` | 覆盖的能力簇 | 必填 | +| `maturity_signal` | 成熟度信号，如完整实现、TODO、骨架接口、表结构已具备 | 必填 | +| `baseline_sha` | 对应 backend 基线 | 必填 | +| `remarks` | 备注 | 可选 | + +### State Interpretation + +| Maturity Signal | Verdict | +|----------------|---------| +| 完整请求处理 + 业务校验 + 数据写入/状态更新 + 日志留痕 | 已实现 | +| 有路由 / DTO / service 接口 / 部分逻辑，但存在 TODO 或空实现 | 部分实现 | +| 只有正式设计目标，没有明确代码证据 | 文档先行 | + +## 4. Alignment Verdict + +### Purpose + +表示对单个能力簇的正式对齐结论。 + +### Fields + +| Field | Description | Validation | +|------|-------------|------------| +| `capability_id` | 对应能力标识 | 必填 | +| `formal_target` | 正式落点 | 必填 | +| `verdict` | 对齐结论 | 必填，取值仅限 `已实现` / `部分实现` / `文档先行` | +| `basis_summary` | 判定依据摘要 | 必填 | +| `follow_up_action` | 后续动作 | 必填 | + +### State Transitions + +```text +文档先行 -> 部分实现 -> 已实现 +``` + +触发条件： +- `文档先行 -> 部分实现`：出现 controller/service/DTO/表结构等明确工程骨架 +- `部分实现 -> 已实现`：业务链路、状态更新和留痕闭环完成，且有稳定代码证据 + +## 5. Verification Artifact + +### Purpose + +表示本轮用于追踪计划、研究、对齐和结论的工件。 + +### Fields + +| Field | Description | Validation | +|------|-------------|------------| +| `artifact_name` | 工件名称 | 必填 | +| `artifact_path` | 工件路径 | 必填 | +| `artifact_role` | 作用，如基线、研究、契约、最终结论 | 必填 | +| `depends_on` | 依赖工件 | 可选 | +| `completion_rule` | 何时可判定完成 | 必填 | + diff --git a/specs/007-sys009-design-align/final-verdict.md b/specs/007-sys009-design-align/final-verdict.md new file mode 100644 index 0000000..2b34040 --- /dev/null +++ b/specs/007-sys009-design-align/final-verdict.md @@ -0,0 +1,56 @@ +# Final Verdict: SYS-009设计整合与实现对齐 + +## Current Implementation Verdict + +本轮已完成正式主文档修订、实现边界回写、`BankWithholding` 六条银行入口补齐及最小编译验证，当前结论如下： + +- `PayCeb`：基础实时查询/缴费闭环已实现，对账回传未实现。 +- `BankWithholding`：签约、解约、客户状态查询、送盘、送盘状态查询、取消送盘、回盘、回盘状态查询均已具备 controller/service 路由、核心校验、批次/明细状态更新或留痕能力，已形成最小实现态闭环。 +- `BankCollection`：与代扣平行，整体为部分实现。 +- `bk_*` 表族与后台管理入口：对象层与资源管理层基本齐备，可支撑代扣批处理状态管理，但仍不能替代真实银行文件联调与运行态样本证据。 +- 正式文档回写仍采用“目标设计边界 + 当前成熟度注记”的双层表达，并将实现态闭环与运行态风险分层记录。 + +## Completed Changes + +1. 已修订 `docs/design/02_Detailed_Design/12_REV_Detailed.md`，补充 `REV-003`、`REV-008` 的实现边界与当前成熟度说明。 +2. 已修订 `docs/design/03_Technical_Design/03_Interface_Design.md`，补充签约、解约、状态查询、取消送盘、回盘状态和当前状态说明。 +3. 已修订 `docs/design/03_Technical_Design/01_Database_Design.md`，明确 `bk_*` 表族对象齐备但业务编排未闭环的边界。 +4. 已修订 `docs/design/01_Overview/03_Summary_Design.md`，将 `SYS-009` 从强实现表述收敛为“已落地能力 + 后续完善项”口径。 +5. 已修订 `specs/007-sys009-design-align/plan.md`、`research.md`、`quickstart.md`，同步范围、工件和执行结果。 +6. 已复核 backend `BankWithholdingController`、`BankWithholdingServiceImpl`、`TransactionMapper` 与相关 DTO/DO/Mapper，实现 `customerCheck`、`sendDisc`、`sendDiscCheck`、`cancelDisc`、`backDisc`、`backDiscCheck` 六条银行入口从 TODO/null 到实现态闭环的升级。 + +## Validation Results + +- `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md`：通过，0 个问题 +- `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md`：通过，0 个问题 +- `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md`：通过，0 个问题 +- `make validate-file FILE=docs/design/01_Overview/03_Summary_Design.md`：通过，0 个问题 +- `make check-links`：通过，仓库级链接检查无问题 +- `make validate-mermaid`：通过，Mermaid 语法验证无问题 +- `mvn -f /Volumes/Dpan/github/water-workspace/water-backend/sw-business-bank/pom.xml -pl sw-business-bank-server -am -DskipTests compile`：通过，backend 最小编译验证成功 +- `mvn -f /Volumes/Dpan/github/water-workspace/water-backend/sw-business-bank/pom.xml -pl sw-business-bank-server -am test`：通过，当前模块无失败测试（本轮输出为 `No tests to run`） + +## Governance Sync + +1. 已回写 `docs/design/00_Management/01_Project_Progress.md`，记录本轮 `SYS-009` 设计整合、银行代扣六条入口实现态闭环与剩余运行态风险。 +2. 已回写 `docs/design/00_Management/03_Task_Checklist.md`，登记本轮任务闭环状态、六条银行入口补齐结果与最小验证结论。 +3. 已回写 `specs/007-sys009-design-align/contracts/sys009-status-verdicts.md`，将 `BankWithholding` 六条银行入口 verdict 与当前实现态证据同步。 + +## Remaining Risks + +1. `PayCeb` 当前仅可确认欠费查询与缴费处理闭环，对账回传仍未落地。 +2. `BankWithholding` 六条银行入口虽已形成最小实现态闭环，但 `backDisc` 仍为最小化结果分发实现，尚未接入真实银行回盘文件解析、SFTP/文件通道联调和运行态样本补证。 +3. `BankCollection` 仍处于部分实现状态；与 `BankWithholding` 平行的托收闭环尚未同步补齐。 +4. `bk_*` 表族和后台资源管理入口已具备对象层基础，但不能替代银行 app 协同闭环的运行态验证证据。 + +## Feature Artifacts Produced + +- `spec.md` +- `plan.md` +- `baseline.md` +- `research.md` +- `data-model.md` +- `quickstart.md` +- `contracts/sys009-capability-alignment.md` +- `contracts/sys009-status-verdicts.md` +- `tasks.md` diff --git a/specs/007-sys009-design-align/plan.md b/specs/007-sys009-design-align/plan.md new file mode 100644 index 0000000..24fcbba --- /dev/null +++ b/specs/007-sys009-design-align/plan.md @@ -0,0 +1,126 @@ +# Implementation Plan: [FEATURE] + +**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link] +**Input**: Feature specification from `/specs/[###-feature-name]/spec.md` + +**Note**: This template is filled in by the `/speckit.plan` command. For this project, planning is document-first and multi-repo aware. + +## Summary + +[Extract from feature spec: primary requirement + target documents + intended update approach] + +## Repository Scope + +- **Formal workflow home**: `water-docs` +- **Target repos in scope**: + - `water-docs`: [Yes / No] + - `water-backend`: [Yes / No] + - `water-frontend`: [Yes / No] +- **Primary delivery mode**: [Document closure / Code evidence alignment / Backend implementation / Frontend implementation / Mixed] + +## Code Baseline + +- **Backend baseline**: [commit SHA / branch / N/A] +- **Frontend baseline**: [commit SHA / branch / N/A] +- **Baseline capture plan**: [How code evidence will be tied to a stable commit] + +## Technical Context + +**Primary Work Product**: [Markdown design docs, management docs, evidence files, backend code, frontend code] +**Source of Truth Documents**: [List the authoritative docs that this change must align with] +**Reference Sources**: [Archive/guides/other references allowed for verification] +**Validation Commands**: [e.g., make validate-file FILE=..., make check-links, make validate-mermaid, compile/build/test commands] +**Target Scope**: [specific chapters, main docs, code modules, or verification slices] +**Project Type**: 文档治理仓库 + 多仓实现协作 +**Constraints**: [no new parallel formal docs, no invented business rules, relative links only, branch rules, baseline rules] +**Scale/Scope**: [single document / cross-document / multi-repo / verification-heavy] + +## Constitution Check + +*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.* + +- [ ] **主文档归属已确认**：正式结论优先落在 `water-docs` 既有主文档或治理文档，不新增平行正式稿。 +- [ ] **多仓范围已确认**：已明确本轮是否涉及 `water-backend`、`water-frontend`，以及各自只是取证还是需要改代码。 +- [ ] **代码基线已确认**：backend/frontend 的 commit 或 branch 基线已记录，避免文档结论失去实现版本锚点。 +- [ ] **Archive 使用方式合规**：Archive 仅作为来源/核对输入，不直接替代正式口径。 +- [ ] **一致性影响已列出**：已识别系统名称、数据库口径、编号、图表、链接、术语、接口契约等受影响项。 +- [ ] **校验与台账动作已规划**：已明确需要执行的文档校验、代码验证、evidence 更新，以及是否需要更新 `01_Project_Progress.md` / `03_Task_Checklist.md`。 + +## Project Structure + +### Feature Artifacts + +```text +specs/[###-feature]/ +├── spec.md +├── plan.md +├── research.md +├── data-model.md +├── quickstart.md +├── contracts/ +├── tasks.md +└── verification.md / final-verdict.md +``` + +### Repository Touchpoints + +```text +water-docs/ +├── docs/design/ +├── specs/ +└── .specify/ + +water-backend/ +└── [backend modules in scope] + +water-frontend/ +└── [frontend modules in scope] +``` + +**Structure Decision**: [Document the exact files or modules to be updated and the reason each is in scope] + +## Phase 0: Research & Alignment + +### Research Inputs + +- [List unresolved questions about docs, backend, frontend, baseline, or validation] + +### Deliverables + +- `research.md` +- [Optional evidence note if brownfield code audit is required] + +## Phase 1: Design & Contracts + +### Planned Artifacts + +- `data-model.md` +- `contracts/*` +- `quickstart.md` +- `verification.md` or `final-verdict.md` if the feature is verification-heavy + +### Design Decisions + +- [List the intended docs-first and multi-repo decisions] + +## Validation Plan + +- **Document validation**: [make validate-file / check-links / mermaid checks] +- **Backend validation**: [compile / unit test / smoke / N/A] +- **Frontend validation**: [build / lint / typecheck / smoke / N/A] +- **Evidence output**: [baseline.md / docs-validation.md / backend-validation.md / frontend-validation.md / final-verdict.md] + +## Ledger Sync Plan + +- **Project progress update required**: [Yes / No] +- **Task checklist update required**: [Yes / No] +- **Evidence or verification summary update required**: [Yes / No] + +## Complexity Tracking + +> **Fill ONLY if Constitution Check has violations that must be justified** + +| Violation | Why Needed | Simpler Alternative Rejected Because | +|-----------|------------|-------------------------------------| +| [e.g., temporary appendix doc] | [current need] | [why existing main doc could not safely absorb it] | +| [e.g., Archive citation exception] | [specific traceability reason] | [why normal main-doc source was insufficient] | diff --git a/specs/007-sys009-design-align/quickstart.md b/specs/007-sys009-design-align/quickstart.md new file mode 100644 index 0000000..5b48664 --- /dev/null +++ b/specs/007-sys009-design-align/quickstart.md @@ -0,0 +1,83 @@ +# Quickstart: SYS-009设计整合与实现对齐 + +## 1. 准备上下文 + +1. 在 `water-docs` 根目录确认当前分支为 `007-sys009-design-align`。 +2. 阅读以下文件： + - `docs/design/00_Management/01_Project_Progress.md` + - `docs/design/00_Management/02_Delivery_Standards.md` + - `docs/design/00_Management/03_Task_Checklist.md` + - `docs/design/01_Overview/03_Summary_Design.md` + - `docs/design/02_Detailed_Design/12_REV_Detailed.md` + - `docs/design/03_Technical_Design/01_Database_Design.md` + - `docs/design/03_Technical_Design/03_Interface_Design.md` + +## 2. 固定代码基线 + +1. 记录 backend 分支和 commit： + - `git -C ../water-backend rev-parse --abbrev-ref HEAD` + - `git -C ../water-backend rev-parse HEAD` +2. 如仅做范围说明，可记录 frontend 分支和 commit： + - `git -C ../water-frontend rev-parse --abbrev-ref HEAD` + - `git -C ../water-frontend rev-parse HEAD` +3. 将结果写入 `baseline.md` 与 `final-verdict.md`。 + +## 3. 收集对齐证据 + +1. 核对外部设计来源： + - `/Users/tangweijie/github/water-bank-api-doc/营收系统缴费接口.md` + - `/Users/tangweijie/github/water-bank-api-doc/营收系统接口规范设计文档.md` +2. 核对 backend 关键证据： + - `../water-backend/sw-business-bank/sw-business-bank-server/src/main/java/.../controller/app/payceb/PayCebController.java` + - `../water-backend/sw-business-bank/sw-business-bank-server/src/main/java/.../service/payceb/PayCebServiceImpl.java` + - `../water-backend/sw-business-bank/sw-business-bank-server/src/main/java/.../controller/app/bankwithholding/BankWithholdingController.java` + - `../water-backend/sw-business-bank/sw-business-bank-server/src/main/java/.../service/bankwithholding/BankWithholdingServiceImpl.java` + - `../water-backend/sw-business-bank/docs/建表sql.sql` +3. 按“已实现 / 部分实现 / 文档先行”归档能力簇结论。 + +## 4. 更新正式文档 + +1. 在 `12_REV_Detailed.md` 补 `REV-003` 与 `REV-008` 的能力边界与成熟度说明。 +2. 在 `03_Interface_Design.md` 补签约、解约、状态查询、取消送盘、对账文件规则等接口契约。 +3. 在 `01_Database_Design.md` 补 `bk_*` 表族与外部能力簇的承接口径。 +4. 在 `03_Summary_Design.md` 同步 `SYS-009` 范围摘要和外部接口表。 + +## 5. 生成与更新证据工件 + +1. 更新或新增： + - `baseline.md` + - `research.md` + - `data-model.md` + - `contracts/*` + - `final-verdict.md` +2. 若本轮已完成正式文档修订，同步更新： + - `docs/design/00_Management/01_Project_Progress.md` + - `docs/design/00_Management/03_Task_Checklist.md` + +## 6. 执行校验 + +1. `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md` +2. `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md` +3. `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md` +4. `make validate-file FILE=docs/design/01_Overview/03_Summary_Design.md` +5. `make check-links` +6. `make validate-mermaid` + +## 7. 形成最终结论 + +1. 在 `final-verdict.md` 汇总： + - 本轮基线 + - 已整合的能力簇 + - 每个能力簇的成熟度结论 + - 已更新的正式文档 + - 已执行的校验 + - 剩余未闭环项 + +## 8. 当前已执行结果 + +- 已完成 `12_REV_Detailed.md`、`03_Interface_Design.md`、`01_Database_Design.md`、`03_Summary_Design.md` 的 SYS-009 正式口径修订。 +- 已完成以下单文件校验并通过： + - `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md` + - `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md` + - `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md` + - `make validate-file FILE=docs/design/01_Overview/03_Summary_Design.md` diff --git a/specs/007-sys009-design-align/research.md b/specs/007-sys009-design-align/research.md new file mode 100644 index 0000000..3f1fd23 --- /dev/null +++ b/specs/007-sys009-design-align/research.md @@ -0,0 +1,77 @@ +# Phase 0 Research: SYS-009设计整合与实现对齐 + +## 1. 外部设计归并路径 + +Decision：实时收费能力归并到 `docs/design/02_Detailed_Design/12_REV_Detailed.md` 的 `REV-003 营业收费`，并在 `docs/design/03_Technical_Design/03_Interface_Design.md` 的 `IF-EXT-003 银行实时收费接口` 承接查询、缴费和当日未对账红冲约束。 +Rationale：实时收费首先影响账单查询、缴费处理和收费结果回写，业务归属在收费主链路；外部资料新增的是银行协议细节，不需要为其新建独立 `SYS-009` 正式章节。 +Alternatives considered：全部并入 `REV-008`；被放弃，因为这样会弱化实时收费与营业收费核销主链的关联。 + +Decision：代扣签约/解约归并到 `docs/design/02_Detailed_Design/12_REV_Detailed.md` 的 `REV-008 代收与银行业务`，并在 `docs/design/03_Technical_Design/03_Interface_Design.md` 增补签约、解约接口小节。 +Rationale：`bk_withholding_agreement` 已是正式数据库对象，但当前接口专项缺少签约/解约契约，外部资料正好补足该缺口。 +Alternatives considered：归入客户资料模块；被放弃，因为签解约属于银行协同交易动作，不是客户主数据维护。 + +Decision：送盘/回盘继续以 `IF-EXT-001`、`IF-EXT-002` 为主承接，在接口专项中补充批次号、文件名、时间窗口和文件交互规则，在 `REV-008` 中保留业务主流程。 +Rationale：正式文档已有批次下发和回盘时序，外部资料主要补的是操作细节和文件规则。 +Alternatives considered：在概要设计扩写送盘/回盘细节；被放弃，因为概要设计不适合承载文件交互细节。 + +Decision：送盘状态查询、回盘状态查询、代扣客户状态查询、取消送盘统一归并到 `docs/design/03_Technical_Design/03_Interface_Design.md`，并在 `REV-008` 中仅保留业务边界和状态流转说明。 +Rationale：这些能力本质是外部协同补偿和批次生命周期控制，最适合作为正式接口契约补充。 +Alternatives considered：只在详细设计文字说明中顺带提及；被放弃，因为无法形成可验收的接口边界。 + +Decision：对账能力在接口专项中补对账文件规则、文件命名和应答约束，结算能力保持正式文档现有抽象，不凭空制造外部结算报文。 +Rationale：外部资料对对账文件和对账请求定义较清晰，但未提供独立结算报文；正式文档当前以 `bk_settlement_batch` 和结算状态协同承接更稳妥。 +Alternatives considered：把对账与结算都写成独立外部接口；被放弃，因为当前证据不足，会制造新的正式口径风险。 + +## 2. 当前 backend 实现成熟度 + +Decision：`PayCeb` 应判定为“已实现（基础闭环）”，但代理收费对账仅为“部分实现”。 +Rationale：`PayCebController` + `PayCebServiceImpl` 已完成欠费查询、缴费的解密、反序列化、业务校验、调用 `ChargeApi`/`CustApi`/`DeptApi`、流水唯一性控制和交易日志留痕；`paymentCheck` 仍为 TODO，占位返回。正式文档应写成“实时查询与缴费已实现，对账回传未实现”，而不是笼统写“PayCeb 全部已完成”。 +Alternatives considered：将整个实时收费能力统一标记为“部分实现”；被放弃，因为查询/缴费确有真实闭环，不应被 TODO 对账能力整体拉低。 + +Decision：代扣签约与解约可判定为“已实现”，代扣客户状态查询、送盘、送盘状态查询、取消送盘、回盘、回盘状态查询均判定为“部分实现”。 +Rationale：`BankWithholdingController` 与 `BankWithholdingServiceImpl` 中签约/解约已完成解密、报文解析、机构/客户/协议校验、协议写入或状态更新、交易日志留痕；其余能力保留 controller TODO 和 service 空实现。 +Alternatives considered：将除签约外的全部能力标记为“文档先行”；被放弃，因为 app controller 路由、DTO 和服务接口已存在，说明已进入骨架实现阶段。 + +Decision：银行托收路径与代扣路径结构平行，成熟度整体为“部分实现”。 +Rationale：`BankCollectionController` / `BankCollectionServiceImpl` 具备签约、解约、客户状态查询、送盘、回盘、取消等接口与服务定义，但完整实现闭环尚不统一成熟。 +Alternatives considered：本轮不写托收；被放弃，因为外部设计和正式文档都把托收作为 `REV-008` 范围一部分。 + +Decision：`bk_*` 表族应判定为“表结构与对象层基本齐备，但业务编排仅部分实现”。 +Rationale：`bk_payment_channel`、`bk_channel_api_config`、`bk_channel_route_rule`、`bk_channel_statistics`、`bk_transaction*`、`bk_withholding_*`、`bk_reconcile_*`、`bk_settlement_batch` 均有 DO/Mapper，且 `sw-business-bank/docs/建表sql.sql` 给出完整建表脚本；但仓库内未见正式迁移脚本统一落位，Mapper XML 也未体现送盘/回盘/对账/结算完整编排。 +Alternatives considered：直接判为“已实现”；被放弃，因为对象齐备不等于业务闭环跑通。也不适合降为“文档先行”，因为交易与协议对象已被真实使用。 + +Decision：后台运营管理对象可判定为“已具备运营侧入口”，但不能据此推断银行 app 协同闭环已完成。 +Rationale：`WithholdingAgreementController`、`WithholdingBatchController`、`ReconcileBatchController`、`SettlementBatchController` 等管理入口已存在，同时后台资源管理层已覆盖交易、协议、批次、明细、对账差异和结算台账。 +Alternatives considered：把后台运营入口视为所有能力已完成的证据；被放弃，因为 app 协议处理、文件交互和状态补偿仍有明显未实现部分。 + +## 3. 正式文档回写策略 + +Decision：正式文档采用“目标设计边界 + 当前成熟度注记”的双层表达。 +Rationale：如果只写设计，会掩盖实现缺口；如果只写现状，会丢失外部设计应承接的正式边界。 +Alternatives considered：只在 `specs/` 中记录成熟度，不回写主文档；被放弃，因为主文档才是正式评审入口。 + +Decision：在 `01_Database_Design.md` 中仅补对象承接与成熟度说明，不新增 DDL 级细节。 +Rationale：当前数据库主文档已明确 `bk_*` 表族口径，本轮重点是把外部设计能力映射到既有对象。 +Alternatives considered：复写外部设计中的示例表结构；被放弃，因为会破坏文档抽象层次。 + +Decision：最终结论以 `final-verdict.md` 汇总，并以 `baseline.md` 锚定 backend 版本。 +Rationale：后续 `/speckit.tasks` 和验收时需要直接复用统一结论。 +Alternatives considered：把所有证据都散落在 plan 或 spec 中；被放弃，因为不利于后续追踪。 + +## 4. 回写重点 + +Decision：`docs/design/01_Overview/03_Summary_Design.md` 对 `SYS-009` 只能保留保守表述。 +Rationale：当前可安全声明的是聚合支付基础能力、银行欠费查询/缴费、代扣/托收签解约、后台资源管理已具备；夜间批量代扣、送盘/回盘、对账、结算不能继续使用“完整支持”的强表述。 +Alternatives considered：延续现有强描述；被放弃，因为会高估实现成熟度。 + +Decision：`docs/design/03_Technical_Design/03_Interface_Design.md` 需显式拆分 `PayCeb Query/Pay`、`PayCheck`、`BankWithholding/BankCollection Signing/Termination` 与其余预留接口。 +Rationale：只有把接口分层定级，后续评审和联调才不会把签解约已实现误读成送盘/回盘/对账也已完成。 +Alternatives considered：仅在 `final-verdict.md` 说明；被放弃，因为正式接口文档本身需要承担契约边界。 + +Decision：`docs/design/03_Technical_Design/01_Database_Design.md` 保留 `bk_*` 为真实承接口径，但要补“业务编排与正式迁移证据仍不完整”的边界。 +Rationale：数据库对象确实存在，但不能让读者从表族完整推断业务闭环完成。 +Alternatives considered：删弱 `bk_*` 口径；被放弃，因为会低估当前真实承接基础。 + +Decision：正式文档修订已按上述研究结论完成首轮回写，并通过 4 份主文档单文件校验。 +Rationale：当前 `12_REV_Detailed.md`、`03_Interface_Design.md`、`01_Database_Design.md`、`03_Summary_Design.md` 已分别补入成熟度边界、接口扩展说明和数据库承接口径说明，验证了研究结论可直接落入正式主文档。 +Alternatives considered：先只保留 research 结论、延后正式文档回写；被放弃，因为本轮目标是形成可交付、可评审的正式文档闭环。 diff --git a/specs/007-sys009-design-align/spec.md b/specs/007-sys009-design-align/spec.md new file mode 100644 index 0000000..6c2990c --- /dev/null +++ b/specs/007-sys009-design-align/spec.md @@ -0,0 +1,168 @@ +# 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]` 标记，且范围边界、依赖来源、验证动作和台账更新责任均可直接执行。 diff --git a/specs/007-sys009-design-align/tasks.md b/specs/007-sys009-design-align/tasks.md new file mode 100644 index 0000000..15211a8 --- /dev/null +++ b/specs/007-sys009-design-align/tasks.md @@ -0,0 +1,195 @@ +# Tasks: SYS-009设计整合与实现对齐 + +**Input**: Design documents from `/specs/007-sys009-design-align/` +**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/007-sys009-design-align/` +- Backend modules: `water-backend/...` +- Frontend modules: `water-frontend/...` + +## Phase 1: Scope, Baseline & Source Confirmation + +**Purpose**: Confirm the source-of-truth set, repo boundary, required reading set, and code baselines before editing anything. + +- [x] T001 阅读 `/Volumes/Dpan/github/water-workspace/water-docs/docs/design/00_Management/01_Project_Progress.md`、`/Volumes/Dpan/github/water-workspace/water-docs/docs/design/00_Management/02_Delivery_Standards.md`、`/Volumes/Dpan/github/water-workspace/water-docs/docs/design/00_Management/03_Task_Checklist.md` +- [x] T002 阅读 `/Volumes/Dpan/github/water-workspace/water-docs/docs/design/01_Overview/03_Summary_Design.md`、`/Volumes/Dpan/github/water-workspace/water-docs/docs/design/02_Detailed_Design/12_REV_Detailed.md`、`/Volumes/Dpan/github/water-workspace/water-docs/docs/design/03_Technical_Design/01_Database_Design.md`、`/Volumes/Dpan/github/water-workspace/water-docs/docs/design/03_Technical_Design/03_Interface_Design.md` +- [x] T003 [P] 阅读 `/Volumes/Dpan/github/water-workspace/water-docs/docs/design/00_Management/04_Writing_Guide.md`、`/Volumes/Dpan/github/water-workspace/water-docs/docs/design/00_Management/08_AI_Agent_Maintenance_SOP.md`、`/Volumes/Dpan/github/water-workspace/water-docs/docs/design/00_Management/10_AI_Retrieval_Whitelist.md`、`/Volumes/Dpan/github/water-workspace/water-docs/docs/design/00_Management/11_Main_Doc_Chapter_Index.md` +- [x] T004 Confirm target documents, target repos, user story priorities, and exact chapter targets from `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/spec.md` +- [x] T005 Confirm governing source-of-truth documents, range intersection basis, external references, and validation commands from `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/plan.md` +- [x] T006 [P] Record the stable repo baselines and key evidence anchors in `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/baseline.md` +- [x] T007 [P] Confirm the formal alignment contract and verdict rules in `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/contracts/sys009-capability-alignment.md` and `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/contracts/sys009-status-verdicts.md` + +--- + +## Phase 2: Shared Foundation + +**Purpose**: Establish the shared alignment baseline for docs, code evidence, and verification outputs. + +- [x] T008 Normalize capability names, verdict vocabulary, and `REV-003` / `REV-008` / `SYS-009` responsibility terms in `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/research.md` +- [x] T009 [P] Prepare the implementation/evidence checklist and execution order in `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/quickstart.md` +- [x] T010 [P] Prepare the final evidence output skeleton in `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/final-verdict.md` + +--- + +## Phase 3: User Story 1 - 整合正式设计口径 (Priority: P1) 🎯 MVP + +**Goal**: 将外部 `SYS-009` 设计吸收进现有正式主文档，使正式评审不再依赖仓外资料。 + +**Independent Test**: 仅阅读 `12_REV_Detailed.md`、`03_Interface_Design.md`、`03_Summary_Design.md`，即可定位实时收费、签解约、送盘/回盘、状态查询、取消送盘、对账/结算的正式口径和章节入口。 + +### Implementation for User Story 1 + +- [x] T011 [US1] 更新 `/Volumes/Dpan/github/water-workspace/water-docs/docs/design/02_Detailed_Design/12_REV_Detailed.md`，补齐 `REV-003` 实时收费与 `REV-008` 代扣/托收/送盘/回盘/对账/结算的正式业务边界 +- [x] T012 [US1] 更新 `/Volumes/Dpan/github/water-workspace/water-docs/docs/design/03_Technical_Design/03_Interface_Design.md`，补齐签约、解约、客户状态查询、送盘状态查询、取消送盘、回盘状态查询和对账文件规则 +- [x] T013 [US1] 更新 `/Volumes/Dpan/github/water-workspace/water-docs/docs/design/01_Overview/03_Summary_Design.md`，同步 `SYS-009` 范围摘要和外部接口表的正式描述 +- [x] T014 [US1] 同步 `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/contracts/sys009-capability-alignment.md` 中的正式落点结论，确保与主文档实际章节一致 +- [x] T015 [US1] 运行 `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md` 并将结果记录到 `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/final-verdict.md` +- [x] T016 [US1] 运行 `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md` 和 `make validate-file FILE=docs/design/01_Overview/03_Summary_Design.md` 并将结果记录到 `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/final-verdict.md` + +**Checkpoint**: User Story 1 is independently reviewable with formal `SYS-009` design integrated into the main documents. + +--- + +## Phase 4: User Story 2 - 对齐当前实现边界 (Priority: P2) + +**Goal**: 将当前 backend 的真实成熟度结论回写到正式文档和证据工件，避免高估 `SYS-009` 完成度。 + +**Independent Test**: 对照正式文档与 `final-verdict.md`，评审人能够独立判断 `PayCeb`、`BankWithholding`、`BankCollection`、`bk_*` 表族和后台管理入口分别处于什么成熟度。 + +### Implementation for User Story 2 + +- [x] T017 [US2] 核对 `/Volumes/Dpan/github/water-workspace/water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/controller/app/payceb/PayCebController.java` 和 `/Volumes/Dpan/github/water-workspace/water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/service/payceb/PayCebServiceImpl.java`，确认实时收费查询/缴费/对账的成熟度结论 +- [x] T018 [P] [US2] 核对 `/Volumes/Dpan/github/water-workspace/water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/controller/app/bankwithholding/BankWithholdingController.java` 和 `/Volumes/Dpan/github/water-workspace/water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/service/bankwithholding/BankWithholdingServiceImpl.java`，确认代扣签解约与其余接口的成熟度结论 +- [x] T019 [P] [US2] 核对 `/Volumes/Dpan/github/water-workspace/water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/controller/app/bankcollection/BankCollectionController.java` 和 `/Volumes/Dpan/github/water-workspace/water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/service/bankcollection/BankCollectionServiceImpl.java`，确认托收平行链路的成熟度结论 +- [x] T020 [P] [US2] 核对 `/Volumes/Dpan/github/water-workspace/water-backend/sw-business-bank/docs/建表sql.sql` 与 `/Volumes/Dpan/github/water-workspace/water-backend/sw-business-bank/sw-business-bank-server/src/main/java/cn/com/emsoft/sw/bankbusiness/controller/admin/` 下后台管理入口，确认 `bk_*` 表族和资源管理层边界 +- [x] T021 [US2] 更新 `/Volumes/Dpan/github/water-workspace/water-docs/docs/design/03_Technical_Design/01_Database_Design.md`，补充 `bk_*` 表族“对象层齐备但业务编排仅部分实现”的边界说明 +- [x] T022 [US2] 更新 `/Volumes/Dpan/github/water-workspace/water-docs/docs/design/03_Technical_Design/03_Interface_Design.md` 与 `/Volumes/Dpan/github/water-workspace/water-docs/docs/design/01_Overview/03_Summary_Design.md`，将 `PayCeb`、`BankWithholding`、`BankCollection` 的真实成熟度回写为保守口径 +- [x] T023 [US2] 更新 `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/final-verdict.md` 与 `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/contracts/sys009-status-verdicts.md`，固化本轮实现边界结论 +- [x] T024 [US2] 运行 `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md` 并将 backend 证据核对结果写入 `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/final-verdict.md` +- [x] T025 [US2] 运行 `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md` 和 `make validate-file FILE=docs/design/01_Overview/03_Summary_Design.md` 并将结果记录到 `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/final-verdict.md` + +**Checkpoint**: User Story 2 is independently reviewable and all maturity statements are tied to concrete backend evidence. + +--- + +## Phase 5: User Story 3 - 形成可审计证据链 (Priority: P3) + +**Goal**: 形成可复用的基线、验证、台账和交付摘要，使后续任务和验收可以直接沿用。 + +**Independent Test**: 仅检查 `specs/007-sys009-design-align/` 和治理台账，即可确认本轮基线、修订范围、验证动作和剩余未闭环项。 + +### Implementation for User Story 3 + +- [x] T026 [US3] 更新 `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/baseline.md`，确认最终使用的 backend/frontend 基线和关键证据路径 +- [x] T027 [P] [US3] 更新 `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/quickstart.md`，使执行顺序、验证命令和回填位置与实际修订结果一致 +- [x] T028 [P] [US3] 更新 `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/research.md` 与 `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/data-model.md`，确保研究结论和实体模型与最终正式口径一致 +- [x] T029 [US3] 更新 `/Volumes/Dpan/github/water-workspace/water-docs/docs/design/00_Management/01_Project_Progress.md`，记录本轮 `SYS-009` 设计整合与实现对齐变更摘要 +- [x] T030 [US3] 更新 `/Volumes/Dpan/github/water-workspace/water-docs/docs/design/00_Management/03_Task_Checklist.md`，回写本轮任务闭环状态和后续待办边界 +- [x] T031 [US3] 复核 `/Volumes/Dpan/github/water-workspace/water-docs/docs/design/00_Management/01_Project_Progress.md` 与 `/Volumes/Dpan/github/water-workspace/water-docs/docs/design/00_Management/03_Task_Checklist.md` 的更新内容，并将治理同步结果记录到 `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/final-verdict.md` +- [x] T032 [US3] 汇总已修改文件、校验结果、成熟度结论和剩余风险到 `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/final-verdict.md` + +**Checkpoint**: All planning evidence, governance records, and final conclusions are independently reviewable. + +--- + +## Final Phase: Verification & Closure + +**Purpose**: Ensure repository-wide consistency, baseline traceability, and final verdict output. + +- [x] T033 [P] Re-check source-of-truth alignment across `/Volumes/Dpan/github/water-workspace/water-docs/docs/design/01_Overview/03_Summary_Design.md`, `/Volumes/Dpan/github/water-workspace/water-docs/docs/design/02_Detailed_Design/12_REV_Detailed.md`, `/Volumes/Dpan/github/water-workspace/water-docs/docs/design/03_Technical_Design/01_Database_Design.md`, and `/Volumes/Dpan/github/water-workspace/water-docs/docs/design/03_Technical_Design/03_Interface_Design.md` +- [x] T034 [P] Run `make check-links` and `make validate-mermaid` and record the repository-wide results in `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/final-verdict.md` +- [x] T035 Re-check backend baseline SHAs, evidence citations, and governance sync results in `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/baseline.md` and `/Volumes/Dpan/github/water-workspace/water-docs/specs/007-sys009-design-align/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 user stories +- **Phase 3: User Story 1**: Depends on Phase 2; MVP slice +- **Phase 4: User Story 2**: Depends on Phase 3 because mature capability wording must align to the integrated formal design +- **Phase 5: User Story 3**: Depends on Phase 3 and Phase 4 because evidence and governance must reflect final doc/evidence state +- **Final Phase**: Depends on all selected user stories being complete + +### User Story Completion Order + +`US1 -> US2 -> US3` + +### Within Each User Story + +- Complete formal doc edits before validation +- Complete backend evidence inspection before maturity wording is finalized +- Complete governance updates after document and evidence conclusions stabilize +- Complete final verdict updates after validation and ledger sync are done + +### Parallel Opportunities + +- `T003`, `T006`, and `T007` can run in parallel after baseline reading +- `T009` and `T010` can run in parallel +- In US2, `T018`, `T019`, and `T020` can run in parallel because they inspect different capability slices +- In US3, `T027` and `T028` can run in parallel because they touch different feature artifacts +- In the final phase, `T033` and `T034` can run in parallel + +## Parallel Execution Examples + +### User Story 1 + +```text +Run T015 after T011 completes +Run T016 after T012 and T013 complete +``` + +### User Story 2 + +```text +Run T018, T019, and T020 together +Run T021 and T022 after T017-T020 complete +Run T023-T025 after T021 and T022 complete +``` + +### User Story 3 + +```text +Run T027 and T028 together +Run T029 and T030 after T026-T028 complete +Run T031 after T029 and T030 complete +Run T032 after T031 complete +``` + +## Implementation Strategy + +### MVP First + +1. Finish Phase 1 and Phase 2 +2. Deliver US1 only: 先完成正式设计整合，让主文档成为单一评审入口 +3. Validate US1 before moving to US2 + +### Incremental Delivery + +1. US1: 正式设计口径收拢 +2. US2: 当前实现成熟度对齐 +3. US3: 证据链和治理台账闭环 + +### Notes + +- Every task preserves the single-source-of-truth model in `water-docs` +- Archive and external docs are used for verification and traceability, not direct formal replacement +- `water-backend` only provides implementation evidence in this round +- Validation, evidence, and ledger tasks are mandatory and already included