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