168 lines
5.3 KiB
Markdown
168 lines
5.3 KiB
Markdown
# 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)
|
||
```
|
||
|
||
## 状态与边界说明
|
||
|
||
- 一期仅保留审批能力位，不定义完整审批状态机。
|
||
- 旧系统精细账务对象如预存退款明细、价差调整明细、分账调整明细等，不作为一期新增实体表；仅保留业务场景、历史只读与日志承接口径。
|