# Data Model: REV-004 旧账务迁移映射与功能缺失分析

## 1. 模型目标

本模型用于定义旧账务迁移规划阶段的核心对象，重点覆盖：

- 旧对象如何分类
- 新系统如何承接
- 映射记录如何表达
- 功能缺失如何判定
- 迁移批次如何组织

## 2. Core Entities

### 2.1 LegacyFinanceObject

表示旧系统中的一个业务财务对象。

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `legacyTable` | string | Yes | 旧表名，如 `AT_CHARGES`、`PM_ACCOUNT_RECORDS` |
| `legacyObjectName` | string | Yes | 旧对象名称，如“营业账”“预存退款” |
| `domainCategory` | string | Yes | 领域分类：账单 / 账户 / 收费 / 调整 / 退款 / 坏账 / 发票 |
| `primaryIdentifier` | string | Yes | 旧对象主标识，如 `FeeId`、`AccLogId`、`InvoiceInfoId` |
| `businessMeaning` | string | Yes | 旧对象业务语义 |
| `containsWorkflowFields` | boolean | Yes | 是否携带审批或流程字段 |
| `containsHistoricalOnlyData` | boolean | Yes | 是否包含明显历史只读数据 |

### 2.2 TargetDomainObject

表示新系统中用于承接旧语义的目标对象。

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `targetDomain` | string | Yes | 新领域名，如 `ChargeAggregate`、`Transaction`、`OperationLog` |
| `targetPhysicalCarrier` | string | Yes | 物理承接对象，如 `biz_charge`、`bk_transaction` |
| `carrierType` | string | Yes | `online-main` / `mapping-layer` / `history-readonly` |
| `supportsOnlineProcessing` | boolean | Yes | 是否参与在线业务处理 |
| `supportsHistoricalQuery` | boolean | Yes | 是否支持历史查询 |

### 2.3 CompatibilityMappingRecord

表示旧对象与新对象之间的映射关系。

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `legacySystem` | string | Yes | 原系统标识 |
| `legacyTable` | string | Yes | 旧表名 |
| `legacyId` | string | Yes | 旧主键值 |
| `legacyBizNo` | string | No | 旧业务单号/流水号 |
| `targetDomain` | string | Yes | 目标领域 |
| `targetId` | string | No | 新主键值 |
| `targetBizNo` | string | No | 新业务单号 |
| `mappingType` | string | Yes | `one-to-one` / `many-to-one` / `one-to-many` / `readonly-only` |
| `mappingStatus` | string | Yes | `planned` / `migrated` / `verified` / `failed` |
| `migrationBatchNo` | string | Yes | 迁移批次号 |
| `tracePayload` | string | No | 扩展追溯信息 |

### 2.4 HistoricalReadonlyRecord

表示仅保留查询与审计用途的历史记录。

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `legacyTable` | string | Yes | 原表名 |
| `legacyId` | string | Yes | 原主键 |
| `legacyStatus` | string | No | 原状态 |
| `originalIdentifiers` | string[] | Yes | 原单号、原账单号、原流水号等 |
| `summarySnapshot` | string | Yes | 历史摘要 |
| `queryDimensions` | string[] | Yes | 可查询维度，如客户号、账期、处理类型 |
| `readonlyReason` | string | Yes | 为什么只读保留 |

### 2.5 GapVerdict

表示旧对象相对于当前 backend 的承接状态判定。

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `legacyObjectName` | string | Yes | 旧对象名称 |
| `verdict` | string | Yes | `implemented` / `partial` / `readonly` / `missing` |
| `evidenceType` | string | Yes | `controller` / `service` / `do` / `table-mapping` / `doc-only` |
| `evidencePath` | string | Yes | 证据路径 |
| `gapDescription` | string | No | 缺失说明 |
| `recommendedAction` | string | Yes | `reuse` / `extend` / `readonly-retain` / `implement-later` |

### 2.6 MigrationBatch

表示一个迁移批次。

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `batchNo` | string | Yes | 批次编号 |
| `batchName` | string | Yes | 批次名称 |
| `scope` | string[] | Yes | 纳入对象列表 |
| `dependsOn` | string[] | No | 前置批次 |
| `validationFocus` | string[] | Yes | 校验重点 |
| `rollbackScope` | string[] | Yes | 回滚范围 |

## 3. Relationships

```text
LegacyFinanceObject
  -> maps to -> TargetDomainObject
  -> produces -> CompatibilityMappingRecord
  -> may retain as -> HistoricalReadonlyRecord
  -> is judged by -> GapVerdict

MigrationBatch
  -> groups -> LegacyFinanceObject
  -> validates -> CompatibilityMappingRecord / GapVerdict
```

## 4. Validation Rules

- 每个 `LegacyFinanceObject` 必须至少对应一种承接方式：在线主模型、兼容映射层或历史只读层之一。
- 每个被判定为 `implemented` 或 `partial` 的 `GapVerdict` 必须绑定 backend 证据路径。
- 每个 `HistoricalReadonlyRecord` 必须能返回原系统标识和最小查询维度。
- 每个 `CompatibilityMappingRecord` 必须带 `migrationBatchNo` 和 `mappingStatus`。
- 每个迁移批次必须先定义校验重点，再进入实际迁移脚本设计。

## 5. Recommended State Semantics

### 5.1 Mapping Status

```text
planned -> migrated -> verified
planned -> failed
migrated -> failed
```

### 5.2 Gap Verdict

```text
implemented
partial
readonly
missing
```

语义说明：

- `implemented`：当前 backend 已有稳定在线承接能力
- `partial`：已有部分承接，但与旧模型仍有明显差距
- `readonly`：不建议在线重建，仅保留历史查询与追溯
- `missing`：当前确实未见稳定承接能力，后续需补设计或实现