tangweijie/fujian_water_biz_doc

tangweijie a26f65a3d8 docs: 收口 REV-004 一期正式文档与交付闭环

统一 REV-004 一期范围、接口口径、数据库承接口径与追溯关系，
并补齐执行手册、quickstart、tasks 及治理台账，完成可执行交付闭环。

2026-03-13 15:02:29 +08:00

4.6 KiB

Raw Blame History

Phase 0 Research: REV-004 账务处理一期

Decision 1: 一期范围严格收敛到 `REV-004` + `IF-REV-007`

Decision: 一期仅覆盖水量调整、金额调整、退款、冲正、坏账申请五类场景，并以 IF-REV-007 作为统一账务处理入口。
Rationale: spec.md、12_REV_Detailed.md、03_Interface_Design.md 与 REV004_ACCOUNTING_EXECUTION_PLAYBOOK.md 对该范围已形成交集口径；继续扩展到 IF-REV-008、IF-REV-011 或 IF-CS-*、IF-METER-* 会超出一期边界。
Alternatives considered:
- 扩展为账务平台级改造：超范围。
- 按旧系统菜单全量恢复所有账务对象：不符合“保守补完”原则。

Decision 2: 先统一共性能力，再按场景分批组织后续实施计划

Decision: 后续实施计划采用“共性能力先统一、场景能力再分批”的组织方式。
Rationale: 各场景共享留痕、原始依据、结果状态、回写状态、接口与数据库口径；先统一这些共性能力，才能避免场景拆解后产生重复建模和状态不一致。
Alternatives considered:
- 先做退款或冲正单场景：容易固化局部口径。
- 所有场景并行拆分：放大一致性风险。

Decision 3: 在线主模型复用 `biz_charge` + `biz_operat_log`，不新增独立账务台账表族

Decision: 一期在线主模型以 biz_charge、biz_charge_detail、biz_operat_log、biz_operat_log_detail 为主承接，退款/冲正等场景按流程与留痕处理，不新建平行细表。
Rationale: 01_Database_Design.md 已明确旧系统精细账务台账按历史只读保留，新发生业务由在线主模型与日志承接；12_REV_Detailed.md 也要求未识别为独立实体的对象只保留业务场景语义。
Alternatives considered:
- 新增预存退款/价差调整/分账调整明细表：违背一期最小闭环原则。
- 机械平移旧系统全部账务表：与当前正式主文档不一致。

Decision 4: 退款/冲正必须联动原交易校验

Decision: 退款、冲正等涉及原支付修正的场景，统一依赖 bk_transaction* 进行原交易存在性、状态与可处理性校验。
Rationale: 12_REV_Detailed.md 要求退款、冲正与原支付流水及渠道状态联动；执行手册把“原交易存在性 / 可退金额 / 状态可调性”列为一期关键缺口。
Alternatives considered:
- 仅按账单状态处理：审计与对账风险高。
- 各场景独立定义交易校验：口径会分裂。

Decision 5: 审批/BPM 一期只保留能力位

Decision: 一期仅保留 approvalRequired、PENDING_APPROVAL 等能力位和边界说明，不展开完整审批流程、节点或流转规则，也不强接 BPM。
Rationale: spec.md 已明确审批相关内容本轮仅保留能力位；执行手册说明 BPM 只有在审批场景、流程 key、回写规则确认后才实接。
Alternatives considered:
- 一期直接实接 BPM：前提不足。
- 完全忽略审批：与详设、接口和规格不一致。

Decision 6: 本轮验收入口以文档与计划质量为准

Decision: 本轮验收入口限定为文档一致性、计划可拆解性与台账可回写性，不以 backend 代码完成度作为前提。
Rationale: 当前 feature 已在 clarify 中明确“文档收敛 + 生成实施计划，但先不改 backend 代码”。
Alternatives considered:
- 以代码落地作为本轮验收：不符合当前阶段目标。

Decision 7: Plan 阶段的最小校验以文档门禁为主

Decision: quickstart 与计划中的最小校验以 make validate-file、make check-links、make validate-mermaid 为主，不引入构建、导出或代码编译命令。
Rationale: Constitution 要求按文档改动范围执行最小校验；当前 plan 阶段的交付对象仍是文档设计产物。
Alternatives considered:
- 使用全量 make validate 或导出命令：成本过高，且不属于当前最小门禁。
- 加入 backend 构建/测试命令：超出本轮范围。

Decision 8: Project Progress / Task Checklist 仅在正式变更或任务闭环时更新

Decision: 仅生成 speckit plan/research 产物时不强制更新 01_Project_Progress.md 和 03_Task_Checklist.md；待正式主文档修订落地或任务拆解/完成时再更新。
Rationale: 台账应承载正式里程碑和任务闭环，而不是记录计划草稿流水。
Alternatives considered:
- 在 plan 阶段立即更新全部台账：噪音过大。
- 完全不考虑台账更新：不符合宪法闭环要求。