# Contract: REV-004 旧账务迁移映射矩阵

## 1. 目标

本合同用于统一旧账务对象到新系统承接对象的映射矩阵结构，供后续迁移实施、校验和差异定位复用。

## 2. 映射矩阵字段

| Field | Required | Description |
| --- | --- | --- |
| `legacyTable` | Yes | 旧表名 |
| `legacyObjectName` | Yes | 旧对象名称 |
| `legacyPrimaryKey` | Yes | 旧主键字段 |
| `legacyBusinessKey` | No | 旧业务单号 / 流水号 / 外部单号 |
| `legacyMeaning` | Yes | 业务语义说明 |
| `targetDomain` | Yes | 新承接领域 |
| `targetCarrier` | Yes | 新承接物理对象或只读对象 |
| `carrierLayer` | Yes | `online-main` / `mapping-layer` / `history-readonly` |
| `mappingType` | Yes | `one-to-one` / `many-to-one` / `one-to-many` / `readonly-only` |
| `statusMappingRequired` | Yes | 是否需要状态映射 |
| `identifierMappingRequired` | Yes | 是否需要新旧标识映射 |
| `historicalRetentionRequired` | Yes | 是否必须保留历史只读 |
| `evidenceSource` | Yes | backend / doc / archive 证据来源 |
| `migrationAction` | Yes | `migrate-online` / `retain-readonly` / `mapping-only` / `implement-later` |
| `riskNote` | No | 风险说明 |

## 3. 填写规则

- 不允许只填写旧表名，不说明业务语义。
- 每个旧对象必须明确进入哪个承接层。
- 若 `carrierLayer = online-main`，必须明确在线主模型对象和主键映射规则。
- 若 `carrierLayer = history-readonly`，必须明确最小查询维度和原始标识保留要求。
- 若 `mappingAction = implement-later`，必须附功能缺失理由和后续建议。

## 4. 最小保留字段要求

对于需要迁移或只读保留的旧对象，最少保留以下类型字段：

- 原单据标识
- 原账单标识
- 原流水标识
- 处理类型
- 处理原因
- 处理前后金额或水量
- 申请时间、审批时间、生效时间
- 经办人
- 附件或依据引用

## 5. 示例判定

| legacyObjectName | targetDomain | carrierLayer | migrationAction | 说明 |
| --- | --- | --- | --- | --- |
| 预存退款 | AccountingRequest / Transaction | online-main + history-readonly | migrate-online | 核心退款结果需在线承接，旧审批细节可只读保留 |
| 价差调整明细 | ChargeAggregate / OperationLog | online-main + mapping-layer | migrate-online | 调整结果进入账单主对象，旧明细字段保留映射 |
| 特账明细 | HistoricalReadonlyRecord | history-readonly | retain-readonly | 当前未见稳定在线承接能力 |