8.6 KiB
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 结论、延后正式文档回写；被放弃，因为本轮目标是形成可交付、可评审的正式文档闭环。