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