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**: 本轮工件可直接作为后续迁移脚本设计、试迁和迁移验收的规划输入。