Align REV004 dictionaries with current interface semantics
Document the minimal dictionary additions and field-binding rules needed to let REV004 front-end queries and dropdowns use system-managed object and status semantics while continuing to reuse the existing legacy reason/type dictionaries. Constraint: Existing dictionary taxonomy must remain stable for historical pages Constraint: REV004 needs explicit object/status dictionaries plus a redink reason set for FE binding Rejected: Rename legacy dictionaries into a new unified taxonomy | too broad for this delivery and risks breaking existing pages Rejected: Keep object/status values as code-only enums | insufficient for frontend dictionary binding Confidence: high Scope-risk: narrow Reversibility: clean Directive: `payment_reason` is only a transitional binding for `WRITTENOFF_ADJUST`; introduce a dedicated writtenoff reason dictionary only when that object stabilizes long-term Tested: Applied `sql/rev004_account_adjust_dict_seed.sql` to sw_system test DB and verified inserted dict types/data Not-tested: Frontend page consumption against the new dictionary bindings
This commit is contained in:
parent
9d2ecf1cf6
commit
d0ee1cbc17
131
docs/guides/REV004_DICT_BINDING_MATRIX.md
Normal file
131
docs/guides/REV004_DICT_BINDING_MATRIX.md
Normal file
@ -0,0 +1,131 @@
|
||||
# REV004 字典绑定矩阵
|
||||
|
||||
## 1. 文档目的
|
||||
|
||||
本文件用于明确 REV004 当前接口、前端查询条件与下拉口径，应如何绑定到系统字典。
|
||||
|
||||
原则：
|
||||
- 旧字典能承接的继续承接；
|
||||
- 旧字典承接不了的，仅最小新增；
|
||||
- 不迁移旧字典体系；
|
||||
- 不要求所有旧页面一次性切换。
|
||||
|
||||
---
|
||||
|
||||
## 2. 本轮新增字典
|
||||
|
||||
| 字典类型 | 用途 |
|
||||
|---|---|
|
||||
| `redink_reason` | 红冲/冲正原因 |
|
||||
| `account_adjust_object_type` | REV004 当前开放对象类型 |
|
||||
| `account_adjust_result_status` | REV004 结果状态 |
|
||||
| `account_adjust_approval_status` | REV004 审批状态 |
|
||||
| `account_adjust_writeback_status` | REV004 回写状态 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 继续复用的旧字典
|
||||
|
||||
| 字典类型 | 用途 |
|
||||
|---|---|
|
||||
| `deposit_reason` | 预付费退款原因 |
|
||||
| `late_fee_reason` | 违约金减免原因 |
|
||||
| `price_reason` | 价差调整原因 |
|
||||
| `separate_reason` | 分账/拆分原因 |
|
||||
| `separate_type` | 分账调整方式（按水量 / 按费用组成） |
|
||||
| `knotty_reason` | 呆坏账原因 |
|
||||
| `knotty_type` | 呆坏账类型（呆账/坏账/纠纷账） |
|
||||
| `payment_reason` | 已销/核销调整原因（当前作为核销调整过渡复用） |
|
||||
| `proc_type` | 账务处理方式 |
|
||||
| `business_type` | 业务大类归属 |
|
||||
|
||||
---
|
||||
|
||||
## 4. REV004 接口字段绑定矩阵
|
||||
|
||||
### 4.1 核心接口字段
|
||||
|
||||
| 字段 | 字段语义 | 绑定字典 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `objectType` | 调整对象 | `account_adjust_object_type` | 前端对象筛选、标签显示、下拉选择主来源 |
|
||||
| `resultStatus` | 处理结果状态 | `account_adjust_result_status` | 前端结果状态筛选、展示主来源 |
|
||||
| `approvalStatus` | 审批状态 | `account_adjust_approval_status` | 前端审批角标/审批筛选主来源 |
|
||||
| `writeBackStatus` | 回写状态 | `account_adjust_writeback_status` | 前端回写状态展示与筛选主来源 |
|
||||
| `reasonCode` | 调整原因编码 | **按 objectType 动态绑定** | 不统一绑一个 reason 字典，而是按对象类型切换 |
|
||||
|
||||
---
|
||||
|
||||
### 4.2 `reasonCode` 动态绑定规则
|
||||
|
||||
| objectType | 绑定字典 | 说明 |
|
||||
|---|---|---|
|
||||
| `PREPAID_REFUND` | `deposit_reason` | 复用预存调整原因中的退款语义 |
|
||||
| `REDINK_RECORD` | `redink_reason` | 旧库缺少红冲原因专属字典，本轮新增 |
|
||||
| `BAD_DEBT_RECORD` | `knotty_reason` | 复用呆坏账原因 |
|
||||
| `WRITTENOFF_ADJUST` | `payment_reason` | 当前过渡复用；若后续核销长期独立，可再拆专属字典 |
|
||||
| `PRICE_DIFF_ADJUST` | `price_reason` | 复用价差调整原因 |
|
||||
| `LATE_FEE_REDUCE` | `late_fee_reason` | 复用违约金减免原因 |
|
||||
| `SPLIT_ADJUST` | `separate_reason` | 复用分账调整原因 |
|
||||
|
||||
---
|
||||
|
||||
### 4.3 与辅助类型字段的关系
|
||||
|
||||
| 使用场景 | 字段/语义 | 绑定字典 |
|
||||
|---|---|---|
|
||||
| 违约金减免二级方式 | 按金额 / 按日期 | `late_fee_type` |
|
||||
| 分账调整二级方式 | 按水量 / 按费用组成 | `separate_type` |
|
||||
| 呆坏账细分类型 | 呆账 / 坏账 / 纠纷账 | `knotty_type` |
|
||||
| 账务结果处理动作 | 转预存 / 转退款 / 转销账 / 线下退款 | `proc_type` |
|
||||
| 历史业务归类 / 大类筛选 | 预存调整 / 呆坏账 / 违约金减免 / 价差调整 / 已销调整 / 分账调整 | `business_type` |
|
||||
|
||||
> 说明：`business_type` 不作为 `objectType` 的替代来源。
|
||||
> `objectType` 以 `account_adjust_object_type` 为主，`business_type` 仅作为旧页面/旧日志/业务大类归类兼容口径。
|
||||
|
||||
---
|
||||
|
||||
## 5. 前端下拉与查询接入建议
|
||||
|
||||
### 5.1 建议读取接口
|
||||
|
||||
- 字典数据接口：
|
||||
- `GET /admin-api/system/dict-data/simple-list`
|
||||
|
||||
### 5.2 页面建议
|
||||
|
||||
#### REV004 查询页
|
||||
- 对象类型下拉：`account_adjust_object_type`
|
||||
- 结果状态下拉：`account_adjust_result_status`
|
||||
- 审批状态下拉：`account_adjust_approval_status`
|
||||
- 回写状态下拉：`account_adjust_writeback_status`
|
||||
|
||||
#### REV004 办理弹窗
|
||||
- 原因下拉：根据当前 `objectType` 动态切换字典类型
|
||||
- 例如：`PRICE_DIFF_ADJUST -> price_reason`
|
||||
|
||||
---
|
||||
|
||||
## 6. 非目标说明
|
||||
|
||||
本轮不做：
|
||||
- 旧字典批量改名
|
||||
- 历史页面一次性切换到新字典
|
||||
- 旧业务表字段语义迁移
|
||||
- 全账务领域统一字典重构
|
||||
|
||||
---
|
||||
|
||||
## 7. 当前特别说明
|
||||
|
||||
### `WRITTENOFF_ADJUST`
|
||||
当前建议临时复用：
|
||||
- `payment_reason`
|
||||
|
||||
这是过渡方案，不代表“核销调整”和“已销调整”语义完全等价。
|
||||
若后续核销调整独立场景长期存在，建议再单独补：
|
||||
- `writtenoff_reason`
|
||||
|
||||
### `REDINK_RECORD`
|
||||
当前库中无现成“红冲原因/冲正原因”专属字典，故本轮新增：
|
||||
- `redink_reason`
|
||||
|
||||
73
sql/rev004_account_adjust_dict_seed.sql
Normal file
73
sql/rev004_account_adjust_dict_seed.sql
Normal file
@ -0,0 +1,73 @@
|
||||
-- REV004 account adjust dictionaries
|
||||
-- Target DB: sw_system (PostgreSQL)
|
||||
-- Purpose:
|
||||
-- 1) Reuse existing legacy reason/type/proc/business dictionaries
|
||||
-- 2) Add the minimal new dictionaries needed for REV004 object/status semantics
|
||||
-- Note:
|
||||
-- This script is idempotent by (type) and (dict_type, value) checks.
|
||||
|
||||
BEGIN;
|
||||
|
||||
-- ============================================================
|
||||
-- 1. Dict types
|
||||
-- ============================================================
|
||||
INSERT INTO system_dict_type (name, type, status, remark, creator, updater, category)
|
||||
SELECT v.name, v.type, 0, v.remark, 'omx', 'omx', 'REV004'
|
||||
FROM (VALUES
|
||||
('红冲原因', 'redink_reason', 'REV004 红冲/冲正原因'),
|
||||
('账务调整对象类型', 'account_adjust_object_type', 'REV004 objectType 字典'),
|
||||
('账务调整结果状态', 'account_adjust_result_status', 'REV004 resultStatus 字典'),
|
||||
('账务调整审批状态', 'account_adjust_approval_status', 'REV004 approvalStatus 字典'),
|
||||
('账务调整回写状态', 'account_adjust_writeback_status', 'REV004 writeBackStatus 字典')
|
||||
) AS v(name, type, remark)
|
||||
WHERE NOT EXISTS (
|
||||
SELECT 1 FROM system_dict_type t WHERE t.type = v.type AND t.deleted = 0
|
||||
);
|
||||
|
||||
-- ============================================================
|
||||
-- 2. Dict data
|
||||
-- ============================================================
|
||||
INSERT INTO system_dict_data (sort, label, value, dict_type, status, color_type, css_class, remark, creator, updater)
|
||||
SELECT v.sort, v.label, v.value, v.dict_type, 0, v.color_type, v.css_class, v.remark, 'omx', 'omx'
|
||||
FROM (VALUES
|
||||
-- redink_reason
|
||||
(10, '收费错误', '1', 'redink_reason', 'danger', '', 'REV004 红冲原因'),
|
||||
(20, '用户拒缴', '2', 'redink_reason', 'warning', '', 'REV004 红冲原因'),
|
||||
(30, '银行撤销', '3', 'redink_reason', 'warning', '', 'REV004 红冲原因'),
|
||||
(40, '网络异常', '4', 'redink_reason', 'info', '', 'REV004 红冲原因'),
|
||||
(90, '其它', '9', 'redink_reason', 'default', '', 'REV004 红冲原因'),
|
||||
|
||||
-- account_adjust_object_type
|
||||
(10, '预付费退款', 'PREPAID_REFUND', 'account_adjust_object_type', 'success', '', 'REV004 objectType'),
|
||||
(20, '红冲记录', 'REDINK_RECORD', 'account_adjust_object_type', 'danger', '', 'REV004 objectType'),
|
||||
(30, '坏账申请', 'BAD_DEBT_RECORD', 'account_adjust_object_type', 'warning', '', 'REV004 objectType'),
|
||||
(40, '核销调整', 'WRITTENOFF_ADJUST', 'account_adjust_object_type', 'warning', '', 'REV004 objectType'),
|
||||
(50, '价差调整', 'PRICE_DIFF_ADJUST', 'account_adjust_object_type', 'info', '', 'REV004 objectType'),
|
||||
(60, '违约金减免', 'LATE_FEE_REDUCE', 'account_adjust_object_type', 'info', '', 'REV004 objectType'),
|
||||
(70, '账单拆分', 'SPLIT_ADJUST', 'account_adjust_object_type', 'primary', '', 'REV004 objectType'),
|
||||
|
||||
-- account_adjust_result_status
|
||||
(10, '成功', 'SUCCESS', 'account_adjust_result_status', 'success', '', 'REV004 resultStatus'),
|
||||
(20, '待审批', 'PENDING_APPROVAL', 'account_adjust_result_status', 'warning', '', 'REV004 resultStatus'),
|
||||
(30, '失败', 'FAIL', 'account_adjust_result_status', 'danger', '', 'REV004 resultStatus'),
|
||||
|
||||
-- account_adjust_approval_status
|
||||
(10, '无需审批', 'NOT_REQUIRED', 'account_adjust_approval_status', 'default', '', 'REV004 approvalStatus'),
|
||||
(20, '待审批', 'PENDING_APPROVAL', 'account_adjust_approval_status', 'warning', '', 'REV004 approvalStatus'),
|
||||
(30, '审批通过', 'APPROVED', 'account_adjust_approval_status', 'success', '', 'REV004 approvalStatus'),
|
||||
(40, '审批驳回', 'REJECTED', 'account_adjust_approval_status', 'danger', '', 'REV004 approvalStatus'),
|
||||
|
||||
-- account_adjust_writeback_status
|
||||
(10, '已回写', 'UPDATED', 'account_adjust_writeback_status', 'success', '', 'REV004 writeBackStatus'),
|
||||
(20, '待回写', 'PENDING', 'account_adjust_writeback_status', 'warning', '', 'REV004 writeBackStatus'),
|
||||
(30, '已跳过', 'SKIPPED', 'account_adjust_writeback_status', 'default', '', 'REV004 writeBackStatus')
|
||||
) AS v(sort, label, value, dict_type, color_type, css_class, remark)
|
||||
WHERE NOT EXISTS (
|
||||
SELECT 1
|
||||
FROM system_dict_data d
|
||||
WHERE d.dict_type = v.dict_type
|
||||
AND d.value = v.value
|
||||
AND d.deleted = 0
|
||||
);
|
||||
|
||||
COMMIT;
|
||||
Loading…
x
Reference in New Issue
Block a user