fujian_water_biz_doc/specs/008-rev004-legacy-finance-migration/spec.md

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

Feature Branch: 008-rev004-legacy-finance-migration Created: 2026-03-23 Status: Draft Input: User description: "帮我根据这份文档进行规划下 怎么形成迁移 映射 ?以及是否存在功能缺失"

Document Scope & Sources (mandatory)

• Target documents:
  • docs/guides/REV004_LEGACY_FINANCE_MIGRATION_PLAN_V0.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
  • specs/008-rev004-legacy-finance-migration/spec.md
  • specs/008-rev004-legacy-finance-migration/plan.md
  • specs/008-rev004-legacy-finance-migration/research.md
  • specs/008-rev004-legacy-finance-migration/data-model.md
  • specs/008-rev004-legacy-finance-migration/quickstart.md
  • specs/008-rev004-legacy-finance-migration/contracts/
• 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/guides/BACKEND_TABLE_MAPPING.md
  • .specify/memory/constitution.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
  • docs/design/04_Appendix/Archive/03_Design_Docs/营业收费管理系统-概要设计说明书20250912.md
• Scope decision: In scope。本轮聚焦 REV-004 旧账务模型迁移规划，明确迁移映射如何形成、哪些旧对象进入在线主模型、哪些仅保留历史只读、以及当前 backend 相对旧模型存在的功能缺失；本轮不直接执行数据迁移脚本，不进入 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:
  • 直接开发迁移程序、ETL 脚本或数据库批处理脚本
  • 在本轮为旧账务台账逐表重建新的在线实体表族
  • 重建完整会计总账、明细账或借贷分录引擎
  • 前端迁移、前端兼容页面和前端查询适配

Code Baseline (mandatory for brownfield work)

• Backend baseline: water-backend HEAD @ 1c47b922ceca9256482b7f5d2a39040fd2ef99e2
• Frontend baseline: water-frontend HEAD @ ae65939045449894c0fccab53fee08521e538ddd（仅用于范围排除）
• Baseline capture rule: 所有“已实现 / 部分实现 / 文档先行 / 历史只读”判断都必须绑定当前 backend baseline，并在研究结论中写明对应代码路径、DO/Controller/Service 或表映射证据。

Evidence Scope (mandatory)

• Document evidence required:
  • specs/008-rev004-legacy-finance-migration/spec.md
  • specs/008-rev004-legacy-finance-migration/plan.md
  • specs/008-rev004-legacy-finance-migration/research.md
  • specs/008-rev004-legacy-finance-migration/data-model.md
  • specs/008-rev004-legacy-finance-migration/contracts/rev004-legacy-mapping-contract.md
  • specs/008-rev004-legacy-finance-migration/contracts/rev004-gap-assessment-contract.md
  • specs/008-rev004-legacy-finance-migration/quickstart.md
• Backend evidence required:
  • ChargeController.java
  • ChargeServiceImpl.java
  • ChargeServiceAccountingAdjustTest.java
  • ChargeDO.java
  • ChargeDetailDO.java
  • OperatLogDO.java
  • OperatLogDetailDO.java
  • PriceCostAdjustmentDO.java
  • PriceTierAdjustmentDO.java
  • bk_transaction* 相关实现与文档映射
• Frontend evidence required:
  • N/A
• Verification artifacts required:
  • research.md
  • data-model.md
  • contracts/*
  • quickstart.md

User Scenarios & Testing (mandatory)

User Story 1 - 形成旧到新的迁移映射方法 (Priority: P1)

作为迁移方案设计人员，我需要先把旧账务模型中的账单、账户、收费、调整、退款、坏账和发票对象映射到新系统的承接层、映射层和历史只读层，这样后续迁移时不会陷入“旧表逐表平移”或“语义丢失”的两种极端。

Why this priority: 如果迁移映射方法不先锁定，后续迁移脚本、校验方案和实现拆解都会失去统一基线。

Independent Test: 审阅者仅通过 research.md、data-model.md 与迁移映射合同，即可判断每类旧账务对象的承接方式、映射规则和保留层次。

Acceptance Scenarios:

1. Given 旧系统账务对象存在大量“汇总表 + 明细表 + 流程字段”组合， When 本轮规划完成， Then 审阅者能够明确哪些对象进入在线主模型、哪些仅作为历史只读、哪些只保留映射关系。
2. Given 新系统 REV-004 当前采用统一账务控制模型， When 评审迁移方案， Then 不会再要求按旧表名原样重建全部在线表族。

---

User Story 2 - 判定功能缺失与实现成熟度 (Priority: P2)

作为技术评审人员，我需要看到旧账务模型相对于当前 backend 的功能缺失、弱映射点和已存在承接能力，这样后续才能区分“需要开发”“仅需迁移”“只需历史查询保留”三类工作。

Why this priority: 如果不区分功能缺失与仅缺表名映射，容易把迁移工程误做成无边界的功能重构。

Independent Test: 审阅者仅通过 research.md 和功能缺失合同，即可判断哪些 REV-004 相关能力已经存在、哪些属于部分实现、哪些仍然缺失。

Acceptance Scenarios:

1. Given backend 已存在 /business/charge/accounting-adjust 与相关测试， When 审阅本轮结论， Then 能明确退款、冲正、坏账申请等核心场景已具备一定承接能力，但并未完整覆盖旧模型所有精细台账对象。
2. Given 数据字典中存在退款账、特账、跨周期水量、坏账明细等旧对象， When 审阅缺失分析， Then 能明确哪些只是独立表缺失、哪些属于在线能力缺失、哪些应保留为历史只读。

---

User Story 3 - 为后续迁移实施提供执行入口 (Priority: P3)

作为后续实施负责人，我需要一套可以直接衔接迁移脚本开发和验收的规划工件，包括分批策略、映射矩阵、最小校验动作和差异定位入口，这样后续不会重复讨论方案框架。

Why this priority: 没有执行入口，本轮规划只能停留在概念层，无法顺利进入试迁、校验和差异修正阶段。

Independent Test: 审阅者仅通过 plan.md 与 quickstart.md，即可明确后续迁移实施的批次顺序、必做矩阵和最小校验动作。

Acceptance Scenarios:

1. Given 后续需要开发迁移脚本或数据校验脚本， When 阅读本轮计划， Then 能直接知道应先产出哪些映射矩阵、按什么批次迁移、如何做最小校验。
2. Given 当前阶段仍以规划为主， When 审阅本轮结果， Then 能明确本轮尚未进入实际数据迁移执行，也不会把迁移脚本视为已完成产物。

---

Edge Cases

• 当旧对象在数据字典中存在，但 backend 未看到同名独立表时，必须区分“语义已承接”“弱映射承接”和“功能缺失”，不得直接判定为必须原样重建。
• 当旧对象同时携带业务结果、审批流程和页面冗余字段时，必须拆分在线承接字段、历史只读字段和追溯映射字段，避免单表平移污染新模型。
• 当退款、冲正等场景与原交易、发票或收费结果强关联时，必须保留原交易标识与新标识映射关系，避免迁移后审计断链。
• 当历史查询需要支持迁移验收时，不得把历史只读接口设计成状态变更接口。

Requirements (mandatory)

Functional Requirements

• FR-001: Specification MUST identify the exact migration-planning artifacts to be produced under specs/008-rev004-legacy-finance-migration/.
• FR-002: Specification MUST identify 12_REV_Detailed.md、03_Interface_Design.md、01_Database_Design.md、BACKEND_TABLE_MAPPING.md as the main source-of-truth inputs for migration planning.
• FR-003: Specification MUST define the migration scope by old object categories rather than by flat table copy lists only.
• FR-004: Specification MUST record backend code baseline and use it to judge whether a capability is implemented, partially implemented, or document-first.
• FR-005: Specification MUST preserve the single-source-of-truth model and MUST NOT assume creation of new parallel formal main documents.
• FR-006: Specification MUST define a three-layer migration model: online main model, compatibility mapping layer, and historical readonly layer.
• FR-007: Specification MUST define at least one mapping contract for old object to new object, field/state mapping, and identifier traceability.
• FR-008: Specification MUST define how functionality gaps are judged, including distinctions between missing table, weak mapping, and missing business capability.
• FR-009: Specification MUST define the minimum retention set for legacy migration, including original identifiers, original bill/transaction references, before/after values, operator, timestamps, and approval traces where applicable.
• FR-010: Specification MUST define the migration batch order and minimum validation actions before implementation.
• FR-011: Specification MUST require readonly historical query capability for migration acceptance and traceability.
• FR-012: Specification MUST list the applicable validation commands for the planning artifacts.

Key Entities (include if feature involves data)

• Legacy Finance Object: 数据字典中的旧账务对象，如营业账、预存退款、已销调整、坏账、发票关系等。
• Online Main Model: 新系统中继续承接在线业务处理的标准对象。
• Compatibility Mapping Record: 用于保存旧标识、新标识、状态映射、来源类型和迁移批次的映射记录。
• Historical Readonly Record: 仅保留查询与审计能力、不再作为在线处理主对象的历史记录。
• Gap Verdict: 对旧对象在当前 backend 中的承接状态判定，如已承接、部分承接、历史只读、功能缺失。
• Migration Batch: 数据迁移执行的分批单元，用于控制顺序、校验和回滚。

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: 审阅者可依据本轮工件明确至少 8 类旧账务对象的承接方式和迁移层次。
• SC-002: 审阅者可依据本轮工件明确至少 5 类 REV-004 相关旧对象是否存在已实现、部分实现或功能缺失。
• SC-003: 审阅者可依据本轮工件直接列出至少 4 份后续迁移实施前必须补齐的映射矩阵或校验工件。
• SC-004: 本轮工件不把“旧表未原样落地”等同于“功能完全缺失”，能够区分语义承接与结构缺失。
• SC-005: 本轮工件可直接作为后续迁移脚本设计、试迁和迁移验收的规划输入。