From d0ee1cbc17f377d0dfb2b7594c0bce2c053abe1b Mon Sep 17 00:00:00 2001
From: tangweijie <877588133@qq.com>
Date: Tue, 7 Apr 2026 17:53:06 +0800
Subject: [PATCH] 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
---
 docs/guides/REV004_DICT_BINDING_MATRIX.md | 131 ++++++++++++++++++++++
 sql/rev004_account_adjust_dict_seed.sql   |  73 ++++++++++++
 2 files changed, 204 insertions(+)
 create mode 100644 docs/guides/REV004_DICT_BINDING_MATRIX.md
 create mode 100644 sql/rev004_account_adjust_dict_seed.sql

diff --git a/docs/guides/REV004_DICT_BINDING_MATRIX.md b/docs/guides/REV004_DICT_BINDING_MATRIX.md
new file mode 100644
index 0000000..d1afb29
--- /dev/null
+++ b/docs/guides/REV004_DICT_BINDING_MATRIX.md
@@ -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`
+
diff --git a/sql/rev004_account_adjust_dict_seed.sql b/sql/rev004_account_adjust_dict_seed.sql
new file mode 100644
index 0000000..981bb3b
--- /dev/null
+++ b/sql/rev004_account_adjust_dict_seed.sql
@@ -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;