tangweijie/fujian_water_biz_doc
1
0
Fork 0
Code Issues Pull Requests 12 Actions Packages Projects Releases 1 Wiki Activity
fujian_water_biz_doc/specs/008-rev004-legacy-finance-migration/plan.md

7.8 KiB
Raw Blame History

Implementation Plan: REV-004 旧账务迁移映射与功能缺失分析

Branch: 008-rev004-legacy-finance-migration | Date: 2026-03-23 | Spec: /specs/008-rev004-legacy-finance-migration/spec.md Input: Feature specification from /specs/008-rev004-legacy-finance-migration/spec.md

Note: This plan is document-first and brownfield-evidence aware. The current round focuses on migration planning artifacts rather than migration code execution.

Summary

本轮围绕 REV-004 旧账务迁移规划形成一套可直接衔接后续实施的 planning 产物，核心目标有两项：一是明确旧账务对象如何形成迁移映射，按在线主模型、兼容映射层和历史只读层三层承接；二是明确当前 backend 相对旧模型存在的已承接能力、弱映射点和功能缺失，避免后续把“旧表未原样存在”误判为“必须整表重建”。

本次计划输出以现有正式文档和 backend 证据为准：继续保持 REV-004 账务处理一期的统一控制模型，不新增独立账本引擎，不直接写迁移脚本；后续迁移实施按“映射矩阵先行、批次设计其次、试迁与校验最后”的顺序组织。

Repository Scope

  • Formal workflow home: water-docs
  • Target repos in scope:
    • water-docs: Yes
    • water-backend: Yes
    • water-frontend: No
  • Primary delivery mode: Document closure / Code evidence alignment

Code Baseline

  • Backend baseline: water-backend HEAD @ 1c47b922ceca9256482b7f5d2a39040fd2ef99e2
  • Frontend baseline: water-frontend HEAD @ ae65939045449894c0fccab53fee08521e538ddd
  • Baseline capture plan: 所有功能缺失或已承接判断都绑定到当前 backend baseline，并在 research.md 中记录代码路径、DO、Controller、Service 或测试证据。

Technical Context

Primary Work Product: 迁移规划工件，包括研究结论、迁移数据模型、映射合同、缺失分析合同和执行 quickstart。 Source of Truth Documents:

  • specs/008-rev004-legacy-finance-migration/spec.md
  • .specify/memory/constitution.md
  • 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/guides/BACKEND_TABLE_MAPPING.md Reference Sources:
  • docs/design/04_Appendix/Archive/05_Data_Dictionary/营收数据字典.md
  • docs/guides/REV004_LEGACY_FINANCE_MIGRATION_PLAN_V0.md
  • docs/design/00_Management/07_Migration_Mapping_Template.md
  • water-backend/sw-business/.../ChargeController.java
  • water-backend/sw-business/.../ChargeServiceImpl.java
  • water-backend/sw-business/.../ChargeServiceAccountingAdjustTest.java Validation Commands:
  • make validate-file FILE=specs/008-rev004-legacy-finance-migration/spec.md
  • make validate-file FILE=specs/008-rev004-legacy-finance-migration/plan.md
  • make validate-file FILE=specs/008-rev004-legacy-finance-migration/research.md
  • make validate-file FILE=specs/008-rev004-legacy-finance-migration/data-model.md
  • make validate-file FILE=specs/008-rev004-legacy-finance-migration/quickstart.md
  • make check-links Target Scope:
  • REV-004 旧账务迁移映射方法
  • REV-004 相关旧对象的功能缺失判定
  • 映射矩阵结构、迁移分批、最小校验动作
  • 历史只读与迁移验收查询边界 Project Type: 文档治理仓库 + 多仓实现协作 Constraints:
  • 不新增平行正式主稿
  • 不发明超出主文档与 Archive 交集的新业务规则
  • 本轮不写迁移脚本、不改 backend 业务代码
  • 历史查询接口只读，不承担状态修正
  • 不把旧表未原样存在直接等同于功能缺失
  • 相对路径与现有 IF-* 编号体系保持稳定 Scale/Scope: 跨文档 migration planning，覆盖 1 份 spec、1 份 plan、1 份 research、1 份 data-model、2 份 contracts 和 1 份 quickstart。

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

  • 主文档归属已确认：本轮 planning 产物落在 specs/008-rev004-legacy-finance-migration/，后续正式结论仍应回写 12_REV_Detailed.md、03_Interface_Design.md、01_Database_Design.md，不新增平行正式主稿。
  • 多仓范围已确认：本轮涉及 water-docs 规划工件与 water-backend 取证，不涉及 water-frontend。
  • 代码基线已确认：backend 和 frontend baseline 已记录，用于绑定当前实现判断和排除前端范围。
  • Archive 使用方式合规：营收数据字典.md 仅作为旧模型来源和迁移核对依据，不直接替代正式口径。
  • 一致性影响已列出：已识别旧对象命名、新旧状态映射、账单/流水/发票关系、历史查询接口口径与功能缺失判定标准。
  • 校验与台账动作已规划：已明确 planning 产物最小校验命令；本轮仅生成规划工件，暂不强制更新 01_Project_Progress.md 与 03_Task_Checklist.md。

Project Structure

Feature Artifacts

specs/008-rev004-legacy-finance-migration/
├── spec.md
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
└── contracts/
    ├── rev004-legacy-mapping-contract.md
    └── rev004-gap-assessment-contract.md

Repository Touchpoints

water-docs/
├── docs/design/
├── docs/guides/REV004_LEGACY_FINANCE_MIGRATION_PLAN_V0.md
├── docs/guides/BACKEND_TABLE_MAPPING.md
└── .specify/

water-backend/
└── sw-business/sw-business-server/src/main/java/...

Structure Decision:

  • spec.md：定义迁移映射规划与功能缺失分析的边界、验收和工件范围。
  • plan.md：组织本轮研究、设计、合同和 quickstart 结构。
  • research.md：沉淀迁移分层模型、映射形成方法、功能缺失判定标准和现状结论。
  • data-model.md：定义迁移映射对象、历史只读对象、缺失判定对象和批次对象。
  • contracts/rev004-legacy-mapping-contract.md：固化旧对象到新对象的映射矩阵结构与字段规则。
  • contracts/rev004-gap-assessment-contract.md：固化功能缺失判定的字段、取值和证据要求。
  • quickstart.md：给后续迁移实施前的工件准备、批次顺序和最小校验动作提供统一入口。

Phase 0: Research & Alignment

Research Inputs

  • 如何从“旧表平移”转成“语义映射 + 三层承接”？
  • 哪些旧对象可视为已被当前 backend 语义承接？
  • 哪些旧对象属于弱映射或真正功能缺失？
  • 迁移验收需要保留哪些最小查询字段和关系？
  • 后续迁移实施前必须先补哪些映射矩阵？

Deliverables

  • research.md

Phase 1: Design & Contracts

Planned Artifacts

  • data-model.md
  • contracts/rev004-legacy-mapping-contract.md
  • contracts/rev004-gap-assessment-contract.md
  • quickstart.md

Design Decisions

  • 采用“在线主模型 + 兼容映射层 + 历史只读层”三层迁移结构。
  • 映射单元以旧业务对象语义为主，不以旧表名平移为主。
  • 功能缺失按“已承接 / 部分承接 / 历史只读 / 功能缺失”四类判定。
  • 后续迁移实施优先补映射矩阵和批次设计，再进入脚本开发与试迁。

Validation Plan

  • Document validation: make validate-file FILE=specs/008-rev004-legacy-finance-migration/<file>.md、make check-links
  • Backend validation: 本轮以代码路径与测试证据核对为主，N/A for compile
  • Frontend validation: N/A
  • Evidence output: research.md、data-model.md、contracts/*、quickstart.md

Ledger Sync Plan

  • Project progress update required: No
  • Task checklist update required: No
  • Evidence or verification summary update required: No

Complexity Tracking

本计划未发生 Constitution 违规项，无需豁免说明。