# Data Model: REV-004 账务处理一期

## 建模原则

- 以逻辑实体 + 物理承接对象双层表达，避免把未确认能力误写为已落地独立表。
- 在线主模型优先复用 `biz_charge*`、`biz_operat_log*`、`bk_transaction*`。
- 审批相关内容仅保留能力位，不展开完整 BPM 流程模型。

## 实体一：AccountingRequest（账务处理申请）

### 作用
统一承接 `IF-REV-007` 的五类场景输入：水量调整、金额调整、退款、冲正、坏账申请。

### 核心字段

| 字段 | 类型 | 说明 |
|------|------|------|
| requestNo | String | 申请编号/调整业务编号 |
| adjustType | Enum | `USAGE` / `AMOUNT` / `REFUND` / `REVERSE` / `BAD_DEBT` |
| chargeId | Long | 目标账单 ID |
| sourceTradeNo | String | 原交易流水号，退款/冲正场景使用 |
| adjustAmount | Decimal | 调整金额 |
| adjustUsage | Decimal | 调整水量 |
| reasonCode | String | 调整原因编码 |
| remark | String | 调整说明 |
| attachmentList | Array<String> | 依据附件 |
| operatorId | Long | 操作人 ID |
| requestedAt | DateTime | 发起时间 |

### 校验规则
- `chargeId`、`adjustType`、`reasonCode`、`operatorId` 必填。
- `REFUND` / `REVERSE` 场景必须具备 `sourceTradeNo`。
- `adjustAmount` 与 `adjustUsage` 按场景二选一或组合使用，不允许无意义空提交。

### 状态
`submitted` → `accepted` / `rejected` → `processed` / `failed`

## 实体二：AccountingResult（账务处理结果）

### 作用
统一承接处理结果、回写结果与是否需要审批。

### 核心字段

| 字段 | 类型 | 说明 |
|------|------|------|
| adjustmentNo | String | 调整业务编号 |
| chargeId | Long | 目标账单 ID |
| resultStatus | Enum | `SUCCESS` / `PENDING_APPROVAL` / `FAIL` |
| writeBackStatus | Enum | `SUCCESS` / `IGNORE_REPEAT` / `FAIL` |
| approvalRequired | Boolean | 是否进入审批 |
| msg | String | 处理说明 |
| processedAt | DateTime | 处理时间 |

### 状态关系
- `resultStatus` 表示业务处理结果。
- `writeBackStatus` 表示账单回写结果。
- `approvalRequired=true` 时允许 `resultStatus=PENDING_APPROVAL`。

## 实体三：ChargeAggregate（账单聚合对象）

### 作用
作为 REV-004 调整、退款、冲正的主要业务承接对象。

### 物理承接
- `biz_charge`
- `biz_charge_detail`

### 核心字段

| 字段 | 来源 | 说明 |
|------|------|------|
| chargeId | `biz_charge.id` | 账单主键 |
| chargeStatus | `biz_charge` | 账单状态 |
| receivableAmount | `biz_charge` / `biz_charge_detail` | 应收金额 |
| paidAmount | 业务汇总 | 已收金额 |
| remainAmount | 业务汇总 | 剩余待支付金额 |
| detailItems | `biz_charge_detail` | 费用明细集合 |

### 关键关系
- 1 个 `ChargeAggregate` 对应多条 `biz_charge_detail`。
- 1 个 `AccountingRequest` 必须定位到 1 个 `ChargeAggregate`。

## 实体四：Transaction（原交易流水）

### 作用
为退款、冲正等场景提供原交易事实依据。

### 物理承接
- `bk_transaction`
- 关联扩展：`bk_transaction_callback`（异步回调结果核对）
- 关联扩展：`bk_transaction_exception`（异常处理状态核对）

### 核心字段

| 字段 | 说明 |
|------|------|
| tradeNo | 渠道交易流水号 |
| tradeStatus | 原交易状态 |
| tradeAmount | 原交易金额 |
| channelCode | 渠道编码 |
| occurredAt | 交易发生时间 |

### 关键规则
- `REFUND` / `REVERSE` 必须关联 `tradeNo`。
- 原交易状态必须满足“可退款/可冲正”业务前提。
- 原交易校验应同时覆盖交易主状态、回调结果与异常处理状态，不得只校验交易主表存在性。

## 实体五：OperationLog（操作留痕）

### 作用
记录账务处理前后变化、处理依据与责任归属。

### 物理承接
- `biz_operat_log`
- `biz_operat_log_detail`

### 核心字段

| 字段 | 说明 |
|------|------|
| bizType | 业务类型 |
| bizId | 业务对象 ID |
| operateUser | 操作人 |
| operateTime | 操作时间 |
| remark | 处理说明 |
| beforeValue | 调整前值 |
| afterValue | 调整后值 |
| fieldName | 字段级差异项 |

### 关键规则
- 所有 REV-004 一期场景都必须写入主日志。
- 涉及金额/水量/状态变化时应写入字段级差异明细。

## 实体六：AccountingEvidence（处理依据）

### 作用
统一描述原账单、原交易、附件、文字说明等处理依据。

### 核心字段

| 字段 | 说明 |
|------|------|
| evidenceType | 原账单 / 原交易 / 附件 / 说明 |
| sourceRef | 依据引用标识 |
| snapshotRef | 快照引用 |
| attachmentList | 附件集合 |

### 说明
该实体是逻辑约束，不要求本阶段新增物理表；由既有对象引用、附件系统与日志共同承接。

## 关系总览

```text
AccountingRequest --> ChargeAggregate
AccountingRequest --> Transaction (REFUND/REVERSE only)
AccountingRequest --> AccountingEvidence
AccountingRequest --> AccountingResult
AccountingRequest --> OperationLog
ChargeAggregate --> biz_charge_detail (1:N)
OperationLog --> biz_operat_log_detail (1:N)
```

## 状态与边界说明

- 一期仅保留审批能力位，不定义完整审批状态机。
- 旧系统精细账务对象如预存退款明细、价差调整明细、分账调整明细等，不作为一期新增实体表；仅保留业务场景、历史只读与日志承接口径。