docs(rev004): add guides and handoff documents

docs/guides/REV004_ACCOUNTING_ADJUST_API_DELTA.md

@@ -0,0 +1,301 @@
+# REV004 本次新增/增强接口清单
+
+## 文档目的
+整理本次 REV004 在后端新增的接口，以及对已有接口的增强点，方便前端联调、测试验收和后续文档沉淀。
+
+---
+
+## 一、结论概览
+
+### 1. 本次真正新增的接口
+本次**真正新增的 HTTP 路由共 4 个**，均为**分账专属接口**：
+
+1. `POST /admin-api/business/split-adjust/submit`
+2. `GET /admin-api/business/split-adjust/page`
+3. `GET /admin-api/business/split-adjust/detail`
+4. `GET /admin-api/business/split-adjust/result`
+
+### 2. 本次增强的已有接口
+已有的 `/admin-api/business/accounting-adjust/*` 路由中，本次主要增强了：
+- 未销分账提交能力
+- 未销违约金减免提交/批量提交能力
+- 调整详情/分页/日志/流程查询返回字段
+- late-fee formal-table 查询兜底能力
+
+---
+
+## 二、本次新增接口
+
+## 2.1 分账专属提交
+- **方法**：`POST`
+- **路径**：`/admin-api/business/split-adjust/submit`
+- **作用**：发起分账申请
+- **说明**：与旧的 `accounting-adjust/unsold-split-submit` 相比，这是更明确的分账专属入口
+
+### 典型用途
+- 前端分账弹窗直接调用
+- 后续独立分账页或分账台账页调用
+
+---
+
+## 2.2 分账专属分页
+- **方法**：`GET`
+- **路径**：`/admin-api/business/split-adjust/page`
+- **作用**：分页查询分账单列表
+
+### 典型用途
+- 分账专属列表页
+- 分账查询台账
+- 分账历史记录页
+
+---
+
+## 2.3 分账专属详情
+- **方法**：`GET`
+- **路径**：`/admin-api/business/split-adjust/detail`
+- **作用**：查询分账详情
+
+### 入参
+- `splitAdjustNo`：分账单号
+- `adjustmentNo`：兼容旧口径的调整单号
+
+### 说明
+优先面向新的分账编号口径，同时兼容旧的 `adjustmentNo` 查询方式。
+
+---
+
+## 2.4 分账执行结果
+- **方法**：`GET`
+- **路径**：`/admin-api/business/split-adjust/result`
+- **作用**：查询分账执行结果
+
+### 入参
+- `splitAdjustNo`
+- `adjustmentNo`
+
+### 典型用途
+- 提交后查看执行状态
+- 审批通过后查看分账结果明细
+- 前端结果弹窗/详情页展示
+
+---
+
+## 三、本次增强的已有接口
+
+## 3.1 未销分账提交
+- **方法**：`POST`
+- **路径**：`/admin-api/business/accounting-adjust/unsold-split-submit`
+
+### 本次增强点
+新增支持：
+- `splitItems`
+
+### 说明
+原先是未销调整页里的分账动作入口，本次增强后可承载更稳定的拆分明细提交语义。
+
+---
+
+## 3.2 未销违约金减免提交
+- **方法**：`POST`
+- **路径**：`/admin-api/business/accounting-adjust/unsold-late-fee-reduce-submit`
+
+### 本次增强点
+新增支持：
+- `applicant`
+- `contactMobile`
+
+### 说明
+用于补齐前端页面上申请人、联系电话等基础申请信息。
+
+---
+
+## 3.3 未销违约金减免批量提交
+- **方法**：`POST`
+- **路径**：`/admin-api/business/accounting-adjust/unsold-late-fee-reduce-batch-submit`
+
+### 本次增强点
+
+#### 外层批量字段
+新增支持：
+- `applyReason`
+- `remark`
+- `applicant`
+- `contactMobile`
+- `attachmentRefs`
+- `lateFeeType`
+
+#### item 明细字段
+新增支持：
+- `startDate`
+- `endDate`
+
+### 说明
+该接口本次补齐了“按金额 / 按日期”两种减免模式所需字段，尤其适用于：
+- 批量违约金减免
+- 按日期区间计算减免
+- 提交时保留申请人与联系电话信息
+
+---
+
+## 3.4 调整详情接口
+- **方法**：`GET`
+- **路径**：`/admin-api/business/accounting-adjust/get`
+
+### 本次增强点
+返回字段增强，且对于 `LATE_FEE_REDUCE`：
+- 当仅依赖 operat_log 无法完整聚合时
+- 可回退到 formal-table：
+  - `biz_latefee_reduce`
+  - `biz_latefee_reduce_detail`
+- 继续组装详情返回
+
+### 作用
+保证违约金减免在 formal-table 路线下，详情页仍可稳定展示。
+
+---
+
+## 3.5 调整分页接口
+- **方法**：`GET`
+- **路径**：`/admin-api/business/accounting-adjust/page`
+
+### 本次增强点
+返回字段增强，便于前端稳定展示状态、原因标签、违约金减免展示字段等。
+
+---
+
+## 3.6 日志相关接口
+### 典型路径
+- `GET /admin-api/business/accounting-adjust/log-page`
+- `GET /admin-api/business/accounting-adjust/log-detail`
+- `GET /admin-api/business/accounting-adjust/log-process`
+- `GET /admin-api/business/accounting-adjust/log-attachments`
+
+### 本次增强点
+返回字段增强，支持：
+- 更完整的调整状态展示
+- 附件、申请信息、原因标签等展示
+- 对 formal-table / 新标准层字段的兼容展示
+
+---
+
+## 3.7 预存流程/附件接口
+### 典型路径
+- `GET /admin-api/business/accounting-adjust/prestorage-process`
+- `GET /admin-api/business/accounting-adjust/prestorage-attachments`
+
+### 本次增强点
+返回字段增强，与统一标准层读模型保持一致。
+
+---
+
+## 四、本次重点新增/增强字段
+
+## 4.1 提交类入参字段
+
+### 分账相关
+- `splitItems`
+
+### 违约金减免相关
+- `applicant`
+- `contactMobile`
+- `lateFeeType`
+- `startDate`
+- `endDate`
+
+---
+
+## 4.2 查询类返回字段
+本次新增/增强的典型返回字段包括：
+
+- `runtimeStatus`
+- `reasonCodeLabel`
+- `lateFeeType`
+- `applicant`
+- `contactMobile`
+- `startDate`
+- `endDate`
+- `splitExecution`
+
+### 说明
+其中：
+- `runtimeStatus`：统一状态展示口径
+- `reasonCodeLabel`：原因编码对应的人类可读标签
+- `splitExecution`：分账执行摘要/明细
+- `lateFeeType/startDate/endDate`：支撑违约金减免按日期模式展示
+
+---
+
+## 五、推荐给前端的理解方式
+
+## 5.1 新接口
+前端如果做**分账专属页面 / 台账 / 结果页**，建议优先使用：
+
+- `POST /business/split-adjust/submit`
+- `GET /business/split-adjust/page`
+- `GET /business/split-adjust/detail`
+- `GET /business/split-adjust/result`
+
+---
+
+## 5.2 旧接口增强
+前端如果仍基于原有 `accounting-adjust` 页面编排，则本次应重点关注：
+
+- `unsold-split-submit`：支持 `splitItems`
+- `unsold-late-fee-reduce-submit`：支持 `applicant/contactMobile`
+- `unsold-late-fee-reduce-batch-submit`：支持 `lateFeeType/startDate/endDate` 等字段
+- `page/get/log/process/detail` 等查询接口：返回字段增强
+
+---
+
+## 六、联调建议
+
+## 6.1 分账
+### 建议优先联调
+1. `POST /business/split-adjust/submit`
+2. `GET /business/split-adjust/detail`
+3. `GET /business/split-adjust/result`
+
+### 适用场景
+- 分账弹窗提交
+- 分账详情页
+- 分账结果回显
+
+---
+
+## 6.2 违约金减免
+### 建议重点联调
+1. `POST /business/accounting-adjust/unsold-late-fee-reduce-submit`
+2. `POST /business/accounting-adjust/unsold-late-fee-reduce-batch-submit`
+3. `GET /business/accounting-adjust/get`
+4. `GET /business/accounting-adjust/log-process`
+
+### 建议重点验证
+- `lateFeeType=1`（按金额）
+- `lateFeeType=2`（按日期）
+- 是否能正确展示 `applicant/contactMobile/startDate/endDate`
+- 审批后详情页是否仍能查到 formal-table 路径数据
+
+---
+
+## 七、当前边界说明
+
+## 7.1 已覆盖
+- 分账专属接口新增
+- 未销违约金减免按日期模式关键字段补齐
+- late-fee formal-table 闭环
+- 查询接口的部分标准层字段增强
+
+## 7.2 未完全覆盖
+- 其他对象类型（如坏账 / 核销 / 价差）尚未全部走 formal-table 同等级闭环
+- 全量旧页面并未全部迁移到新接口
+- 旧接口仍保留兼容口径
+
+---
+
+## 八、建议结论
+
+如果前端是做：
+- **分账专属页面**：优先接 `/business/split-adjust/*`
+- **原未销调整页中的分账/违约金减免弹窗**：继续使用 `/business/accounting-adjust/*`，但需按本次新增字段补齐请求/展示
+
+---

docs/guides/REV004_ACCOUNTING_ADJUST_FRONTEND_DEBUG_DATA.md

@@ -0,0 +1,276 @@
+# REV004 前端联调测试数据说明
+
+## 目的
+为 REV004 本次新增/增强的接口提供一套**可直接用于前端联调**的测试数据，重点覆盖：
+- 分账专属接口
+- 未销违约金减免（成功 / 待审批）
+- `accounting-adjust` 兼容查询链路
+
+对应后端脚本：
+- `water-backend/sql/rev004/REV004_accounting_adjust_frontend_debug_seed.sql`
+
+---
+
+## 一、数据设计原则
+
+本次联调数据重点保证：
+1. **客户 / 账户 / 营业账** 有真实关联
+2. **分账主表 / 明细表 / 子账单** 有真实关联
+3. **违约金减免主表 / 明细表 / 营业账 / 营业账明细** 有真实关联
+4. **operat_log / operat_log_detail** 能支撑旧查询接口联调
+5. 成功态、待审批态同时具备，方便前端测状态切换与展示分支
+
+---
+
+## 二、可直接使用的样例数据
+
+## 2.1 分账成功样例
+
+### 关键标识
+- `splitAdjustNo = REV004-SPLIT-API-001`
+- `adjustmentNo = REV004-SPLIT-API-001`
+- `sourceChargeId = 920101`
+- `customerCode = REV004_FE_SPLIT_CUST`
+
+### 数据关系
+- 源账单：`920101`
+- 分账主单：`920301`
+- 分账明细：
+  - `920311`
+  - `920312`
+  - `920313`
+- 子账单：
+  - `920102`
+  - `920103`
+  - `920104`
+
+### 业务语义
+- 原账单水量：`9.000`
+- 分成 3 笔
+- 每笔水量：`3.000`
+- 每笔金额：`60.00`
+- 状态：**审批通过 + 执行成功**
+
+### 适合联调的接口
+- `GET /admin-api/business/split-adjust/page`
+- `GET /admin-api/business/split-adjust/detail?splitAdjustNo=REV004-SPLIT-API-001`
+- `GET /admin-api/business/split-adjust/result?splitAdjustNo=REV004-SPLIT-API-001`
+- `GET /admin-api/business/accounting-adjust/get?adjustmentNo=REV004-SPLIT-API-001`
+
+---
+
+## 2.2 违约金减免成功样例
+
+### 关键标识
+- `adjustmentNo = REV004-LATEFEE-API-001`
+- `chargeId = 920105`
+- `customerCode = REV004_FE_LATE_CUST`
+
+### 数据关系
+- 客户：`920002`
+- 营业账：`920105`
+- 营业账明细：`9201001`
+- 违约金减免主单：`920401`
+- 违约金减免明细：`920411`
+- request log：`920511`
+- approve log：`920512`
+
+### 业务语义
+- 违约金减免类型：`2`（按日期）
+- 起算日期：`2026-04-01`
+- 截止日期：`2026-04-30`
+- 理论调整前违约金：`18.00`
+- 减免金额：`6.00`
+- 调整后违约金：`12.00`
+- 状态：**审批通过 + 执行成功**
+
+### 适合联调的接口
+- `GET /admin-api/business/accounting-adjust/get?adjustmentNo=REV004-LATEFEE-API-001`
+- `GET /admin-api/business/accounting-adjust/logs?adjustmentNo=REV004-LATEFEE-API-001`
+- `GET /admin-api/business/accounting-adjust/log-detail?adjustmentNo=REV004-LATEFEE-API-001`
+- `GET /admin-api/business/accounting-adjust/log-process?adjustmentNo=REV004-LATEFEE-API-001`
+
+---
+
+## 2.3 违约金减免待审批样例
+
+### 关键标识
+- `adjustmentNo = REV004-LATEFEE-API-002`
+- `chargeId = 920106`
+- `customerCode = REV004_FE_PENDING_CUST`
+
+### 数据关系
+- 客户：`920003`
+- 营业账：`920106`
+- 营业账明细：`9201002`
+- 违约金减免主单：`920402`
+- 违约金减免明细：`920412`
+- request log：`920521`
+
+### 业务语义
+- 违约金减免类型：`1`（按金额）
+- 减免金额：`5.00`
+- 状态：**待审批**
+
+### 适合联调的接口
+- `GET /admin-api/business/accounting-adjust/get?adjustmentNo=REV004-LATEFEE-API-002`
+- `GET /admin-api/business/accounting-adjust/page`
+- `GET /admin-api/business/accounting-adjust/log-page`
+
+---
+
+## 三、接口调试建议
+
+## 3.1 分账专属接口
+
+### 分页
+```http
+GET /admin-api/business/split-adjust/page?pageNo=1&pageSize=10
+```
+
+### 详情
+```http
+GET /admin-api/business/split-adjust/detail?splitAdjustNo=REV004-SPLIT-API-001
+```
+
+### 执行结果
+```http
+GET /admin-api/business/split-adjust/result?splitAdjustNo=REV004-SPLIT-API-001
+```
+
+---
+
+## 3.2 账务调整兼容查询接口
+
+### 调整详情
+```http
+GET /admin-api/business/accounting-adjust/get?adjustmentNo=REV004-LATEFEE-API-001
+GET /admin-api/business/accounting-adjust/get?adjustmentNo=REV004-LATEFEE-API-002
+GET /admin-api/business/accounting-adjust/get?adjustmentNo=REV004-SPLIT-API-001
+```
+
+### 调整分页
+```http
+GET /admin-api/business/accounting-adjust/page?pageNo=1&pageSize=20
+```
+
+### 调整日志
+```http
+GET /admin-api/business/accounting-adjust/logs?adjustmentNo=REV004-LATEFEE-API-001
+```
+
+---
+
+## 3.3 未销兼容查询
+
+### 查询分账源客户
+```http
+GET /admin-api/business/accounting-adjust/unsold-page?pageNo=1&pageSize=20&code=REV004_FE_SPLIT_CUST
+```
+
+### 查询违约金客户
+```http
+GET /admin-api/business/accounting-adjust/unsold-page?pageNo=1&pageSize=20&code=REV004_FE_LATE_CUST
+```
+
+### 查询待审批违约金客户
+```http
+GET /admin-api/business/accounting-adjust/unsold-page?pageNo=1&pageSize=20&code=REV004_FE_PENDING_CUST
+```
+
+---
+
+## 四、如果前端要直接提交流程
+
+## 4.1 可用于新发起分账的源账单
+- `sourceChargeId = 920101`
+
+### 对应源账单条件
+- 水量：`9.000`
+- 适合拆成 3 笔，每笔 `3.000`
+
+### 示例请求
+```json
+{
+  "sourceChargeId": 920101,
+  "applicant": "前端调试员",
+  "contactMobile": "13900009999",
+  "reasonCode": "1",
+  "remark": "前端直接调试新分账",
+  "attachmentRefs": ["split-fe-debug-1"],
+  "splitItems": [
+    { "seqNo": 1, "splitWater": 3.000 },
+    { "seqNo": 2, "splitWater": 3.000 },
+    { "seqNo": 3, "splitWater": 3.000 }
+  ]
+}
+```
+
+---
+
+## 4.2 可用于新发起违约金减免的源账单
+
+### 成功样例源账单
+- `chargeId = 920105`
+
+### 待审批样例源账单
+- `chargeId = 920106`
+
+### 注意
+这两笔账单都补了：
+- `biz_charge.late_fee_begin_date`
+- `biz_charge_detail`
+- `biz_charge_detail.cost_component_code = 101`
+
+而 `biz_cost_component.code = 101` 在测试库里已有：
+- `penalty_coefficient = 0.0010`
+
+因此可以支撑 `lateFeeType=2` 的按日期计算调试。
+
+### 示例请求（按日期）
+```json
+{
+  "lateFeeType": "2",
+  "applicant": "前端调试员",
+  "contactMobile": "13800009999",
+  "applyReason": "1",
+  "remark": "前端直接调试按日期减免",
+  "attachmentRefs": ["latefee-fe-debug-1"],
+  "items": [
+    {
+      "chargeId": 920105,
+      "startDate": "2026-04-01",
+      "endDate": "2026-04-30"
+    }
+  ]
+}
+```
+
+---
+
+## 五、执行方式
+
+如需把这套联调数据写入测试库，可执行：
+
+```bash
+PGPASSWORD='Em@123456' \
+psql -h 192.168.10.130 -p 5436 -U sw_system -d sw_system \
+  -v ON_ERROR_STOP=1 \
+  -f /Volumes/Dpan/github/water-workspace/water-backend/sql/rev004/REV004_accounting_adjust_frontend_debug_seed.sql
+```
+
+---
+
+## 六、当前结论
+
+这套数据已经覆盖了前端最常见的三类场景：
+1. **分账成功态**
+2. **违约金减免成功态**
+3. **违约金减免待审批态**
+
+同时兼顾：
+- 新增分账专属接口
+- 旧 `accounting-adjust` 兼容查询接口
+- 申请态 / 审批态 / 执行态的展示联调
+
+---

docs/guides/REV004_CURRENT_TRUTH_MATRIX.md

@@ -0,0 +1,90 @@
+# REV004 当前主线真值矩阵
+
+## 主线基线
+- backend：`sw-system-cloud/develop @ 9462f3a12728b83bfe31e0b74c526f4256f5b361`
+- docs：`fujian_water_biz_doc/main @ b5efa3b2480b1a0b8a00b728ac434f833787b6b4`
+- 生成时间：`2026-04-17 15:00 +08:00`
+
+## 一、对象总览
+
+| 对象 | objectType / 专属域 | formal-table 状态 | 主表 / 明细表 | 主接口状态 | strict formal-first 状态 |
+|---|---|---|---|---|---|
+| 预存调整 | prestorage | 已独立 | `biz_prestorage_adjust` / `biz_prestorage_adjust_detail` | 已接线 | 部分完成 |
+| 坏账调整 | `BAD_DEBT_RECORD` | 已独立 | `biz_bad_debt_adjust` / `biz_bad_debt_adjust_detail` | 已接线 | 主链路完成 |
+| 已销调整/核销 | `WRITTENOFF_ADJUST` | 已独立 | `biz_writtenoff_adjust` / `biz_writtenoff_adjust_detail` | 已接线 | 主链路完成 |
+| 违约金减免 | `LATE_FEE_REDUCE` | 已独立 | `biz_latefee_reduce` / `biz_latefee_reduce_detail` | 已接线 | 主链路完成 |
+| 分账调整 | `SPLIT_ADJUST` | 已独立 | `biz_split_adjust` / `biz_split_adjust_detail` | 已接线 | 专属接口完成 |
+| 价差调整 | `PRICE_DIFF_ADJUST` | 未独立 | 无 | 兼容接口 | 未完成 |
+| 红冲记录 | `REDINK_RECORD` | 未独立 | 无 | 兼容接口 | 未完成 |
+
+## 二、已独立对象明细
+
+### 1. 预存调整（退款 / 转账）
+- DDL：`sql/rev004/REV004_prestorage_formal_tables_deploy.sql`
+- 表：`biz_prestorage_adjust`、`biz_prestorage_adjust_detail`
+- 接口：
+  - `POST /admin-api/business/accounting-adjust/prestorage-submit`
+  - `POST /admin-api/business/accounting-adjust/prestorage-revoke`
+  - `GET /admin-api/business/accounting-adjust/prestorage-process`
+  - `GET /admin-api/business/accounting-adjust/prestorage-attachments`
+  - `GET /admin-api/business/accounting-adjust/prestorage-page`
+  - `GET /admin-api/business/accounting-adjust/prestorage-detail`
+- 当前判断：
+  - submit / revoke / page / detail 已是 formal-table 主链路
+  - `process / attachments` 仍保留 legacy / unified fallback
+
+### 2. 坏账调整
+- DDL：`sql/rev004/REV004_bad_debt_formal_tables_deploy.sql`
+- 表：`biz_bad_debt_adjust`、`biz_bad_debt_adjust_detail`
+- 接线口径：统一 `accounting-adjust` submit / approve / reject / page / detail
+- 当前判断：主链路已 formal-first
+
+### 3. 已销调整 / 核销
+- DDL：`sql/rev004/REV004_writtenoff_formal_tables_deploy.sql`
+- 表：`biz_writtenoff_adjust`、`biz_writtenoff_adjust_detail`
+- 接口：
+  - `POST /admin-api/business/accounting-adjust/sold-submit`
+  - `POST /admin-api/business/accounting-adjust/approve`
+  - `POST /admin-api/business/accounting-adjust/reject`
+  - `GET /admin-api/business/accounting-adjust/get`
+  - `GET /admin-api/business/accounting-adjust/page`
+- 当前判断：主链路已 formal-first，且已补事务边界 / fail-fast
+
+### 4. 违约金减免
+- DDL：`sql/rev004/REV004_latefee_formal_tables_deploy.sql`
+- 表：`biz_latefee_reduce`、`biz_latefee_reduce_detail`
+- 接口：
+  - `POST /admin-api/business/accounting-adjust/unsold-late-fee-reduce-submit`
+  - `POST /admin-api/business/accounting-adjust/unsold-late-fee-reduce-batch-submit`
+- 当前判断：formal-table 主链路已建立
+
+### 5. 分账调整
+- 表：`biz_split_adjust`、`biz_split_adjust_detail`
+- 专属接口：
+  - `POST /business/split-adjust/submit`
+  - `GET /business/split-adjust/page`
+  - `GET /business/split-adjust/detail`
+  - `GET /business/split-adjust/result`
+- 当前判断：已独立为专属对象域
+- 备注：`sql/rev004/` 目录下当前未看到单独 split deploy 脚本，说明库结构来源可能更早或另有维护路径
+
+## 三、未独立对象
+
+### 1. 价差调整 `PRICE_DIFF_ADJUST`
+- 当前仍主要走兼容接口 / 统一日志骨架
+- 尚未见独立 `biz_price_diff_adjust` / `detail` 正式主从表
+
+### 2. 红冲记录 `REDINK_RECORD`
+- 当前未见独立 formal-table 主线
+- 仍属于兼容口径对象
+
+## 四、当前最适合的后续优先级
+1. `PRICE_DIFF_ADJUST` formal-table
+2. prestorage `process / attachments` strict formal-first 收口
+3. 统一补一版“对象 → 表 → 接口 → 真值口径”对外联调说明
+
+## 五、证据锚点
+- backend 已合入：PR #77，merge sha=`9462f3a12728b83bfe31e0b74c526f4256f5b361`
+- docs 已合入：merge sha=`b5efa3b2480b1a0b8a00b728ac434f833787b6b4`
+- writtenoff fresh smoke evidence：`docs/evidence/rev004-writtenoff-formal-table-dev-db-apply-2026-04-17.md`
+- formal-table 状态矩阵：`docs/guides/REV004_FORMAL_TABLE_STATUS_MATRIX.md`

docs/guides/REV004_FRONTEND_IMPLEMENTATION_HANDOFF.md

@@ -0,0 +1,299 @@
+# REV-004 前端实现交接清单
+
+## 1. 文档定位
+
+本文用于将 `REV-004` 前端实现方案转为可直接分发给前端实现 Agent 的正式 handoff 文档。
+
+当前定位：
+- 仅覆盖 **管理后台**
+- 不覆盖微网厅 / 客户端实现
+- 用于后续在 `../water-frontend` 目录通过 `omx team` / `$team` 推进实现
+
+## 2. 当前统一口径
+
+### 2.1 已确认范围
+
+本轮前端实现只覆盖：
+
+- REV-004 管理后台统一入口页
+- REV-004 核心对象业务页
+- REV-004 扩展对象业务页
+- REV-004 历史核查 / 对账页
+- 审批状态 / 结果展示通用组件
+- 前后端联调与口径校验
+
+### 2.2 明确不纳入本轮范围
+
+以下内容不属于本轮前端实现：
+
+- 微网厅页面实现
+- 客户端交易页实现
+- 客户端审批页实现
+- 客户端对象化菜单管理能力
+- 完整 BPM 流程前端实现
+
+### 2.3 风格与实现原则
+
+本轮采用折中策略：
+
+- 核心操作路径尽量像旧系统
+- 页面组织以当前前端风格为主
+- 延续当前 **菜单级独立页面 + 查询区 + 表格区 + Dialog/Drawer 办理** 范式
+- 但 REV-004 必须比当前更对象化、更清晰
+- 不重做成完全不同的一套前端范式
+
+## 3. 页面分层方案
+
+### 3.1 统一入口层
+
+统一入口页只负责：
+
+- 对象导航
+- 待办汇总
+- 常用入口
+- 状态聚合
+
+约束：
+- **不承载主办理表单**
+- **不承载复杂对象编辑**
+
+### 3.2 对象业务页层
+
+#### 第一档独立菜单页（冻结清单）
+
+- 预存退款
+- 红冲记录
+- 已销调整
+- 坏账
+
+#### 第二档共享扩展页 / 共享查询骨架（冻结清单）
+
+- 价差调整
+- 违约金减免
+- 分账调整
+- 特账 / 特殊开账
+
+默认规则：
+- 除第一档对象外，其余对象本轮不得新增顶层菜单
+
+### 3.3 历史与核查层
+
+- 退款账结果查询
+- 跨周期水量查询
+- 历史账务台账 / 迁移核查页
+- 对账与差异定位页
+
+## 4. 页面粒度要求
+
+页面按以下粒度组织：
+
+- **列表页**：查询、筛选、导出、批量操作
+- **办理弹窗 / 抽屉**：新增、调整、撤销、审批动作
+- **详情页 / 详情抽屉**：单据详情、留痕、审批状态、附件
+- **结果页 / 查询页**：退款账、跨周期水量、历史台账、迁移核查
+
+## 5. 通用组件要求
+
+建议统一复用 / 补齐以下组件：
+
+- `AccountingObjectHeader`
+- `AccountingStatusPanel`
+- `AccountingResultSummary`
+- `AccountingApprovalBadge`
+- `AccountingAttachmentPanel`
+- `AccountingDiffTable`
+
+基础模板继续沿用：
+
+- `ContentWrap`
+- 查询表单（`el-form`）
+- 结果表格（`EnhancedTable` / `el-table`）
+- `Dialog` / `Drawer`
+
+## 6. 最小交付件
+
+执行前或执行中，至少需要形成以下 4 类交付件：
+
+### 6.1 页面清单
+字段最小结构：
+- 页面名称
+- 页面类型
+- 对应对象
+- 当前状态（现有 / 复用 / 待新增）
+
+### 6.2 路由清单
+字段最小结构：
+- 路由路径
+- 页面归属
+- 菜单归属
+- 是否顶层菜单
+
+### 6.3 通用组件清单
+字段最小结构：
+- 组件名
+- 用途
+- 复用页面
+- 是否新建
+
+### 6.4 lane ownership 清单
+字段最小结构：
+- lane 名称
+- 负责目录与页面
+- 负责组件
+- 前置依赖
+
+## 7. 四张正式执行表
+
+### 7.1 页面清单（冻结版）
+
+| 页面名称 | 页面类型 | 对应对象/用途 | 当前状态 | 目录/文件建议 | 说明 |
+|---|---|---|---|---|---|
+| REV-004 统一工作台 | 工作台页 | 统一入口、对象导航、待办汇总 | 待新增 | `src/views/accountProcess/index.vue` | 只做导航/聚合，不承载主办理表单 |
+| 预存退款页 | 列表页 + 办理弹窗 + 详情 | `PrepaidRefund` | 现有（需口径收敛） | `src/views/accountProcess/prestorageAdjustment/index.vue` / `detail.vue` | 当前名称偏“预存调整”，需向预存退款对象口径收敛 |
+| 红冲记录页 | 列表页 + 详情 | `RedinkRecord` | 现有 | `src/views/operatingCharges/redReversalRecord/index.vue` | 保留旧系统熟悉路径 |
+| 已销调整页 | 列表页 + 办理弹窗 | `WrittenoffAdjust` | 现有 | `src/views/accountProcess/soldAdjustment/index.vue` | 作为第一档独立菜单页保留 |
+| 坏账页 | 列表页 + 办理弹窗 | `BadDebtRecord` | 可复用 | `src/views/accountProcess/unsoldAdjustment/index.vue` + `components/BadDebtAdjustmentForm.vue` | 建议从未销调整页骨架中拆出独立坏账页 |
+| 价差调整扩展页 | 共享扩展页 + 办理弹窗 | `PriceDiffAdjust` | 可复用 | `src/views/accountProcess/unsoldAdjustment/index.vue` + `components/PriceAdjustmentForm.vue` | 第二档共享扩展对象 |
+| 违约金减免扩展页 | 共享扩展页 + 办理弹窗 | `LateFeeReduce` | 可复用 | `src/views/accountProcess/unsoldAdjustment/index.vue` + `components/PenaltyRemissionForm.vue` | 第二档共享扩展对象 |
+| 分账调整扩展页 | 共享扩展页 + 办理弹窗 | `SplitAdjust` | 可复用 | `src/views/accountProcess/unsoldAdjustment/index.vue` + `components/SplitAdjustmentForm.vue` | 第二档共享扩展对象 |
+| 特账 / 特殊开账页 | 列表页 / 查询页 | `SPECIAL_BILLING` | 现有（需边界重写） | `src/views/operatingCharges/specialAccountOpening/index.vue` | 保留“特殊开账”旧路径，但以当前前端组织为主 |
+| 退款账结果查询页 | 结果页 / 查询页 | `RefundBill` | 待新增 | 建议 `src/views/accountProcess/refundBill/index.vue` | 只做查询与结果消费，不做主办理入口 |
+| 跨周期水量查询页 | 查询页 | `CrossCycleWaterRecord` | 待新增 | 建议 `src/views/accountProcess/crossCycleWater/index.vue` | 只做查询/核查，不做强流程办理页 |
+| 历史账务核查页 | 核查页 | 历史账务迁移核查 | 待新增 | 建议 `src/views/accountProcess/historyAudit/index.vue` | 用于现有/历史/目标口径差异定位 |
+| 对账与差异定位页 | 核查页 | 结果差异、单据级定位 | 待新增 | 建议 `src/views/accountProcess/reconcileDiff/index.vue` | 偏联调与验收，不做业务办理 |
+
+### 7.2 路由清单（建议版）
+
+| 路由路径 | 页面归属 | 菜单归属 | 是否顶层菜单 | 当前状态 | 说明 |
+|---|---|---|---|---|---|
+| `/account-process` | REV-004 统一工作台 | 账务处理 | 否 | 待新增 | 工作台入口，聚合导航 |
+| `/account-process/prestorage-adjustment` | 预存退款页 | 账务处理 | 是 | 现有 | 建议保留现有路径或做别名兼容 |
+| `/operating-charges/red-reversal-record` | 红冲记录页 | 营业收费/账务处理 | 是 | 现有 | 可保留原有菜单认知 |
+| `/account-process/sold-adjustment` | 已销调整页 | 账务处理 | 是 | 现有 | 第一档冻结对象 |
+| `/account-process/bad-debt` | 坏账页 | 账务处理 | 是 | 待新增 | 从未销调整骨架中拆出 |
+| `/account-process/adjustment-extension/price-diff` | 价差调整扩展页 | 账务处理扩展 | 否 | 待新增 | 第二档共享扩展对象 |
+| `/account-process/adjustment-extension/late-fee-reduce` | 违约金减免扩展页 | 账务处理扩展 | 否 | 待新增 | 第二档共享扩展对象 |
+| `/account-process/adjustment-extension/split-adjust` | 分账调整扩展页 | 账务处理扩展 | 否 | 待新增 | 第二档共享扩展对象 |
+| `/operating-charges/special-account-opening` | 特账 / 特殊开账页 | 营业收费 | 否 | 现有 | 以特殊开账旧路径承接 |
+| `/account-process/refund-bill` | 退款账结果查询页 | 历史与核查 | 否 | 待新增 | 结果对象查询出口 |
+| `/account-process/cross-cycle-water` | 跨周期水量查询页 | 历史与核查 | 否 | 待新增 | 基础支撑对象查询出口 |
+| `/account-process/history-audit` | 历史账务核查页 | 历史与核查 | 否 | 待新增 | 迁移核查主入口 |
+| `/account-process/reconcile-diff` | 对账与差异定位页 | 历史与核查 | 否 | 待新增 | 联调/验收差异定位 |
+
+### 7.3 通用组件清单（冻结版）
+
+| 组件名 | 用途 | 复用页面 | 当前状态 | 说明 |
+|---|---|---|---|---|
+| `AccountingObjectHeader` | 对象标题、对象摘要、入口动作 | 统一工作台、对象列表页、详情页 | 待新增 | 统一对象头部表达 |
+| `AccountingStatusPanel` | 结果状态 / 回写状态 / 业务状态面板 | 核心对象页、扩展对象页、核查页 | 待新增 | 状态统一展示 |
+| `AccountingResultSummary` | 金额/水量/笔数汇总 | 列表页、核查页 | 待新增 | 可复用 `el-descriptions` 风格 |
+| `AccountingApprovalBadge` | 审批状态 Tag / 摘要 | 对象列表页、详情页 | 待新增 | 不展开完整 BPM，只展示边界 |
+| `AccountingAttachmentPanel` | 附件、留痕、资料展示 | 详情页、核查页 | 待新增 | 统一附件区 |
+| `AccountingDiffTable` | 金额/水量前后差异表 | 已销调整、价差调整、分账调整、核查页 | 待新增 | 差异定位核心组件 |
+| `AdjustmentForm` | 预存调整/退款办理弹窗 | `prestorageAdjustment` | 现有 | 可复用并收敛命名 |
+| `SoldAdjustmentForm` | 已销调整办理弹窗 | `soldAdjustment` | 现有 | 可直接复用 |
+| `BadDebtAdjustmentForm` | 坏账办理弹窗 | `unsoldAdjustment` / 坏账页 | 现有（待抽出） | 建议抽离到坏账页目录 |
+| `PenaltyRemissionForm` | 违约金减免办理弹窗 | 扩展对象页 | 现有（可复用） | 第二档共享组件 |
+| `PriceAdjustmentForm` | 价差调整办理弹窗 | 扩展对象页 | 现有（可复用） | 第二档共享组件 |
+| `SplitAdjustmentForm` | 分账调整办理弹窗 | 扩展对象页 | 现有（可复用） | 第二档共享组件 |
+
+### 7.4 lane ownership 清单（冻结版）
+
+| lane | 负责目录与页面 | 负责组件 | 前置依赖 | 说明 |
+|---|---|---|---|---|
+| Lane A | `src/views/accountProcess/index.vue`（若新建） | 导航卡片、入口汇总组件 | 无 | 统一入口只做导航/聚合 |
+| Lane B | `src/views/accountProcess/prestorageAdjustment/*`、`src/views/operatingCharges/redReversalRecord/*`、`src/views/accountProcess/soldAdjustment/*`、坏账页目录 | 预存退款、红冲、已销、坏账相关组件 | 接口对象命名冻结 | 第一档独立菜单对象 |
+| Lane C | 价差调整、违约金减免、分账调整、特账相关目录（待新增或共享） | `PriceAdjustmentForm`、`PenaltyRemissionForm`、`SplitAdjustmentForm`、扩展页头部组件 | Lane B 对象模式稳定 | 第二档共享扩展对象 |
+| Lane D | `src/views/accountProcess/refundBill/*`、`src/views/accountProcess/crossCycleWater/*`、`src/views/accountProcess/historyAudit/*`、`src/views/accountProcess/reconcileDiff/*`（建议） | `AccountingResultSummary`、`AccountingDiffTable`、核查类组合组件 | 接口查询口径稳定 | 历史与核查层 |
+| Lane E | 通用组件目录（建议 `src/components/accounting/*`） | `AccountingStatusPanel`、`AccountingApprovalBadge`、`AccountingAttachmentPanel` | 状态枚举初版冻结 | 通用状态/审批/附件组件 |
+| Lane F | 联调与验证脚本/样例/映射文档 | 接口映射、枚举校验、验收样例 | A/B/C/D/E 页面骨架形成 | 贯穿联调与验收 |
+
+## 8. `omx team` 执行建议
+
+### 8.1 执行目录
+
+在以下目录执行：
+
+- `../water-frontend`
+
+### 8.2 并行顺序
+
+- `Lane A / B / D / E` 可先并行
+- `Lane C` 在 `Lane B` 的对象模式稳定后进入
+- `Lane F` 最后贯穿联调与验收
+
+### 8.3 执行前提
+
+执行前必须明确：
+
+- 先冻结 **IA（信息架构）**：页面分层、菜单分组、导航关系
+- 后冻结 **DTO / 状态细节**
+- 联调阶段允许通过 `Lane F` 对接口字段、审批状态、结果枚举做受控收敛
+- 不允许反向推翻已冻结的页面分层
+
+## 9. 任务包建议
+
+### Agent A：统一入口页
+负责：
+- 统一工作台页
+- 导航聚合
+- 待办与快捷入口
+
+### Agent B：核心对象页
+负责：
+- 预存退款
+- 红冲记录
+- 已销调整
+- 坏账
+
+### Agent C：扩展对象页
+负责：
+- 价差调整
+- 违约金减免
+- 分账调整
+- 特账 / 特殊开账
+
+### Agent D：历史核查 / 对账页
+负责：
+- 退款账结果查询
+- 跨周期水量查询
+- 历史账务核查页
+- 差异定位页
+
+### Agent E：审批状态 / 结果组件
+负责：
+- 审批状态展示
+- 结果状态展示
+- 留痕 / 附件通用区
+
+### Agent F：联调与口径校验
+负责：
+- 接口口径映射
+- 枚举统一
+- 页面与接口返回一致性校验
+- 验收样例整理
+
+## 10. 验证要求
+
+执行前 / 执行中至少检查：
+
+1. 是否明确区分：
+   - 当前已有页面
+   - 可复用页面
+   - 待新增页面
+2. 是否明确区分：
+   - 第一档独立菜单对象
+   - 第二档共享扩展对象
+3. 统一入口是否只做导航 / 汇总，不承担主办理表单
+4. 是否把目标态误写成当前已实现页面
+5. `omx team` lane ownership 是否清晰，不会并行踩文件
+
+## 11. 需求依据
+
+- `.omx/plans/2026-04-07-rev004-frontend-implementation-plan.md`
+- `.omx/specs/deep-interview-rev004-frontend-modules.md`
+- `docs/design/02_Detailed_Design/12_REV_Detailed.md`
+- `docs/design/03_Technical_Design/01_Database_Design.md`
+- `docs/design/03_Technical_Design/03_Interface_Design.md`
+- `docs/design/01_Overview/03_Summary_Design.md`
+- `docs/guides/REV004_FULL_ACCOUNTING_DOMAIN_DESIGN.md`

docs/guides/REV004_FRONTEND_OMX_TEAM_PROMPTS.md

@@ -0,0 +1,363 @@
+# REV-004 前端 OMX Team 执行提示词
+
+## 1. 使用说明
+
+本文用于在 `../water-frontend` 目录直接启动 `omx team` / `$team` 时，作为 leader 与各 lane 的执行提示词模板。
+
+适用范围：
+- **仅管理后台**
+- 不包含微网厅 / 客户端实现
+- 需求依据以正式文档与 handoff 为准，不以旧手册直接替代正式设计
+
+执行前固定输入依据：
+- `docs/guides/REV004_FRONTEND_IMPLEMENTATION_HANDOFF.md`
+- `.omx/plans/2026-04-07-rev004-frontend-implementation-plan.md`
+- `.omx/specs/deep-interview-rev004-frontend-modules.md`
+- `docs/design/02_Detailed_Design/12_REV_Detailed.md`
+- `docs/design/03_Technical_Design/01_Database_Design.md`
+- `docs/design/03_Technical_Design/03_Interface_Design.md`
+- `docs/design/01_Overview/03_Summary_Design.md`
+
+---
+
+## 2. Leader 启动 Prompt
+
+```text
+任务：REV-004 管理后台前端实现
+
+工作目录：../water-frontend
+
+本轮范围：
+1. 统一入口页
+2. 核心对象页（预存退款、红冲记录、已销调整、坏账）
+3. 扩展对象页（价差调整、违约金减免、分账调整、特账/特殊开账）
+4. 历史核查 / 对账页（退款账结果、跨周期水量、历史账务核查、差异定位）
+5. 审批状态 / 结果展示组件
+6. 联调与口径校验
+
+严格约束：
+- 仅做管理后台，不做微网厅 / 客户端
+- 保持当前前端范式：菜单级独立页面 + 查询区 + 表格区 + Dialog/Drawer 办理
+- 核心操作路径尽量像旧系统，但页面组织以当前前端风格为主
+- 统一入口页只做导航 / 聚合 / 快捷入口，不承载主办理表单
+- 第一档独立菜单对象冻结为：预存退款、红冲记录、已销调整、坏账
+- 第二档共享扩展对象冻结为：价差调整、违约金减免、分账调整、特账/特殊开账
+- 除第一档对象外，其余对象本轮不得新增顶层菜单
+- 不得把目标态写成当前已落地事实
+
+交付件要求：
+1. 页面清单
+2. 路由清单
+3. 通用组件清单
+4. lane ownership 清单
+5. 实际代码变更
+6. 验证结果
+
+执行前提：
+- 先冻结 IA（页面分层、菜单分组、导航关系）
+- 后冻结 DTO / 状态细节
+- 联调阶段允许收敛接口字段、审批状态、结果枚举，但不能反向推翻页面分层
+
+请按以下 lanes 组织执行：
+- Lane A：统一入口页 / 导航聚合
+- Lane B：核心对象页
+- Lane C：扩展对象页
+- Lane D：历史核查 / 对账页
+- Lane E：审批状态 / 结果组件
+- Lane F：联调与口径校验
+
+建议并行关系：
+- A / B / D / E 先并行
+- C 在 B 的对象模式稳定后进入
+- F 最后贯穿联调与验收
+
+最终输出：
+- 各 lane 变更摘要
+- 冲突与整合说明
+- 验证结论
+```
+
+---
+
+## 3. Lane A Prompt：统一入口页 / 导航聚合
+
+```text
+你负责 REV-004 前端 Lane A：统一入口页 / 导航聚合。
+
+工作范围：
+- `src/views/accountProcess/index.vue`（若新建）
+- 导航卡片组件
+- 入口汇总组件
+
+目标：
+- 建立 REV-004 管理后台统一工作台页
+- 仅负责对象导航、待办汇总、快捷入口、状态聚合
+- 不承载主办理表单
+
+页面要求：
+- 延续现有 ContentWrap / 查询区 / 信息卡片 / 表格摘要 风格
+- 页面中明确分出：
+  - 核心对象入口
+  - 扩展对象入口
+  - 历史核查入口
+  - 审批/结果摘要入口
+- 支持跳转到各对象页，不把功能都堆在一个页面内
+
+约束：
+- 不要实现对象办理弹窗
+- 不要侵入 Lane B/C/D/E 的具体页面逻辑
+- 允许先用 mock/占位入口，但必须标清待接页面
+
+交付：
+1. 统一入口页代码
+2. 导航卡片/入口组件
+3. 页面清单与路由占位建议
+4. 需要 Lane B/C/D/E 配合的接口点
+```
+
+---
+
+## 4. Lane B Prompt：核心对象页
+
+```text
+你负责 REV-004 前端 Lane B：核心对象页。
+
+冻结范围：
+- 预存退款
+- 红冲记录
+- 已销调整
+- 坏账
+
+优先目录：
+- `src/views/accountProcess/prestorageAdjustment/*`
+- `src/views/operatingCharges/redReversalRecord/*`
+- `src/views/accountProcess/soldAdjustment/*`
+- 坏账页目录（待新增，建议从 `unsoldAdjustment` 骨架拆出）
+
+目标：
+- 将第一档核心对象做成独立菜单页 / 独立对象页
+- 页面模式保持现有后台风格：查询 + 表格 + 办理弹窗/详情
+- 统一对象页表达：状态、审批状态、附件、留痕、关联账单
+
+重点要求：
+- `prestorageAdjustment` 要向 `PrepaidRefund` 对象语义收敛
+- `redReversalRecord` 保留旧系统熟悉路径，但前端结构按现有项目规范组织
+- `soldAdjustment` 作为 `WrittenoffAdjust` 主页保留
+- 坏账页需明确从 `unsoldAdjustment` 中拆分，不要继续混在一个泛页面里
+
+约束：
+- 只处理第一档独立对象
+- 不扩展第二档对象
+- 不更改统一入口职责
+
+交付：
+1. 各对象页结构与代码调整
+2. 各页复用/新增组件清单
+3. 坏账页新建建议与落地文件路径
+4. 与 Lane E 的组件依赖点
+```
+
+---
+
+## 5. Lane C Prompt：扩展对象页
+
+```text
+你负责 REV-004 前端 Lane C：扩展对象页。
+
+冻结范围：
+- 价差调整
+- 违约金减免
+- 分账调整
+- 特账 / 特殊开账
+
+建议依附：
+- `src/views/accountProcess/unsoldAdjustment/*`
+- `src/views/operatingCharges/specialAccountOpening/*`
+- 或共享“账务调整扩展页”目录
+
+目标：
+- 将第二档对象做成共享扩展页或共享查询骨架
+- 不新增顶层菜单
+- 复用现有弹窗：
+  - `PriceAdjustmentForm`
+  - `PenaltyRemissionForm`
+  - `SplitAdjustmentForm`
+
+重点要求：
+- 页面要体现对象差异，但不要每个对象都做成完整独立模块
+- 特账 / 特殊开账保留旧路径，但界面边界要按当前前端组织重写
+- 共享页要能通过对象类型切换，不回退成完全混杂页
+
+约束：
+- 本 lane 不得把第二档对象升为顶层菜单
+- 本 lane 不负责历史核查页
+- 统一状态 / 审批展示优先复用 Lane E 组件
+
+交付：
+1. 共享扩展页方案与代码
+2. 对象切换策略
+3. 复用组件点
+4. 与 Lane B 的边界说明
+```
+
+---
+
+## 6. Lane D Prompt：历史核查 / 对账页
+
+```text
+你负责 REV-004 前端 Lane D：历史核查 / 对账页。
+
+范围：
+- 退款账结果查询页
+- 跨周期水量查询页
+- 历史账务核查页
+- 对账与差异定位页
+
+建议目录：
+- `src/views/accountProcess/refundBill/*`
+- `src/views/accountProcess/crossCycleWater/*`
+- `src/views/accountProcess/historyAudit/*`
+- `src/views/accountProcess/reconcileDiff/*`
+
+目标：
+- 建立 REV-004 历史与核查层页面
+- 页面以查询、汇总、差异定位为主
+- 不做主办理动作
+
+重点要求：
+- 支持“现有 / 历史 / 目标”口径差异定位
+- 支持对象类型、状态、审批状态、账期、时间、关联账单等查询维度
+- 页面风格延续后台列表查询页 + 汇总区 + 详情抽屉模式
+
+约束：
+- 不要把这类页面做成办理页
+- 不要侵入第一档/第二档对象主办理逻辑
+- 与 Lane F 协作时，优先暴露差异定位能力
+
+交付：
+1. 历史与核查层页面代码
+2. 查询字段清单
+3. 差异定位展示方案
+4. 对 Lane F 的验收支撑点
+```
+
+---
+
+## 7. Lane E Prompt：审批状态 / 结果组件
+
+```text
+你负责 REV-004 前端 Lane E：审批状态 / 结果展示组件。
+
+范围：
+- 通用状态组件
+- 审批 Badge
+- 结果摘要组件
+- 留痕 / 附件区组件
+
+建议目录：
+- `src/components/accounting/*`
+
+目标：
+- 统一各对象页的状态表达
+- 统一审批状态展示
+- 统一结果摘要、附件、留痕表达
+
+最小组件：
+- `AccountingStatusPanel`
+- `AccountingApprovalBadge`
+- `AccountingResultSummary`
+- `AccountingAttachmentPanel`
+- `AccountingDiffTable`
+- （可选）`AccountingObjectHeader`
+
+约束：
+- 仅展示审批边界，不展开完整 BPM 流程前端
+- 组件要能被 Lane A/B/C/D 复用
+- 不直接绑定某个具体对象页逻辑
+
+交付：
+1. 通用组件代码
+2. 组件 props 约定
+3. 复用方式说明
+4. 与各 lane 的接入示例
+```
+
+---
+
+## 8. Lane F Prompt：联调与口径校验
+
+```text
+你负责 REV-004 前端 Lane F：联调与口径校验。
+
+范围：
+- 接口映射
+- 枚举值对齐
+- 页面与返回结构一致性校验
+- 验收样例整理
+
+目标：
+- 保证前端实现与正式文档口径一致
+- 检查 objectType、状态、审批状态、结果状态等枚举是否统一
+- 检查各对象页和核查页是否把“目标态”误写成“已实现事实”
+
+重点检查：
+- 第一档对象页与第二档扩展页边界是否被破坏
+- 统一入口是否被做成主办理页
+- 历史核查页是否误入办理逻辑
+- 页面清单 / 路由清单 / 组件清单 / lane ownership 清单是否完整
+
+交付：
+1. 接口映射表
+2. 枚举值校验表
+3. 页面一致性检查结果
+4. 验收样例与问题清单
+```
+
+---
+
+## 9. 推荐启动顺序
+
+建议在 `../water-frontend` 中按以下顺序启动：
+
+1. Leader 先下发统一任务说明
+2. 并行启动：
+   - Lane A
+   - Lane B
+   - Lane D
+   - Lane E
+3. Lane B 稳定后启动 Lane C
+4. 最后启动 Lane F 贯穿联调与验收
+
+---
+
+## 10. Leader 启动提示（可直接复制）
+
+```text
+请在 ../water-frontend 中执行 REV-004 管理后台前端实现。
+
+唯一需求依据：
+- docs/guides/REV004_FRONTEND_IMPLEMENTATION_HANDOFF.md
+- .omx/plans/2026-04-07-rev004-frontend-implementation-plan.md
+- .omx/specs/deep-interview-rev004-frontend-modules.md
+- REV-004 四层正式文档
+
+范围限定：
+- 仅管理后台
+- 不做微网厅 / 客户端
+- 不做完整 BPM 前端
+
+执行原则：
+- 保持当前前端范式
+- 核心操作路径尽量像旧系统
+- 统一入口只做导航 / 聚合
+- 第一档对象独立菜单冻结，第二档对象不得升顶层菜单
+- 先冻结 IA，再收敛 DTO / 状态细节
+
+请按 Lane A-F 分工推进，并在最后统一输出：
+1. 页面清单
+2. 路由清单
+3. 通用组件清单
+4. lane ownership 清单
+5. 代码变更摘要
+6. 联调问题清单
+```

docs/guides/REV004_FRONTEND_OPEN_API_DEVELOPMENT_STANDARD.md

@@ -0,0 +1,149 @@
+# REV004 前后端开放接口开发规范（/business 域）
+
+## 1. 文档目的
+本规范用于统一 `water-backend` 对 `water-frontend` 的开放接口风格，作为后续新增、改造、评审和验收的共同标准。
+
+## 2. 适用范围
+- 后端：`sw-business/sw-business-server/src/main/java/.../controller/admin/**`
+- 前端：`water-frontend/src/api/**`、`water-frontend/src/views/**`
+- 重点域：`/business/**`
+
+## 3. 现状基线（截至 2026-04-23）
+### 3.1 导出接口现状
+- `/business` 导出映射约 **73** 个
+  - `/export-excel`：**58**（主流）
+  - `/export`：**7**（次主流）
+  - 其他：`/export-details`、`/export-check`、`/export-failed` 等
+- 导出实现主流为：
+  - `ExcelUtils.write(...)`
+  - `ExcelUtils.writeWithTemplate(...)`
+- 前端导出主流为：
+  - `request.download(...)`
+  - 失败数据回传导出：`request.postDownload(...)`
+
+### 3.2 当前特例（需治理）
+`/business/accounting-adjust` 下存在 CSV 特例：
+- `GET /business/accounting-adjust/log-export`
+- `GET /business/accounting-adjust/prestorage-export`
+
+上述接口使用手写 `writeCsv(...)`，与整体 Excel 导出主流不一致。
+
+---
+
+## 4. 对前端开放接口统一标准（V1）
+
+### 4.1 路由命名标准
+| 场景 | 标准路由 | 说明 |
+|---|---|---|
+| 分页查询 | `GET /page` | 返回 `PageResult` |
+| 详情 | `GET /get` | 单条详情 |
+| 新增 | `POST /create` | 创建资源 |
+| 更新 | `PUT /update` | 更新资源 |
+| 删除 | `DELETE /delete` | 单条删除 |
+| 导出（推荐） | `GET /export-excel` | 统一导出命名 |
+| 导出（兼容） | `GET /export` | 历史接口保留过渡 |
+| 失败数据导出 | `POST /export-failed` | 适配前端失败列表回传 |
+
+> 要求：新增接口优先 `export-excel`；历史 `export` 可保留，逐步迁移。
+
+### 4.2 返回体标准
+| 类型 | 标准 |
+|---|---|
+| 普通接口 | `CommonResult<T>` |
+| 分页接口 | `CommonResult<PageResult<T>>`（字段固定 `list`、`total`） |
+| 导出接口 | 二进制流（不包 `CommonResult`） |
+
+### 4.3 权限与审计标准
+- 导出接口权限统一：`@PreAuthorize("@ss.hasPermission('business:<module>:export')")`
+- 导出接口必须标注：`@ApiAccessLog(operateType = EXPORT)`
+
+### 4.4 参数与校验标准
+- Query 分页参数统一 `*PageReqVO`
+- 使用 `@Valid` / `@Validated` 触发参数校验
+- 必填、范围、格式使用 jakarta validation 注解
+- 日期区间优先显式双端字段；如需兼容前端 range 参数，可在 Controller 层做兼容解析
+
+### 4.5 错误处理标准
+- Controller 层禁止直抛 `IllegalArgumentException`
+- 统一使用 `ServiceException + ErrorCode`
+- 统一由 `GlobalExceptionHandler` 转换为 `CommonResult` 响应
+- 错误信息需可读、可定位、可回溯
+
+### 4.6 导出实现标准
+- 默认导出：`ExcelUtils.write(...)`
+- 模板导出：`ExcelUtils.writeWithTemplate(...)` / `ExcelUtils.writeTemplate(...)`
+- 禁止新增手写 CSV 导出实现
+
+### 4.7 前端对接标准
+- 常规：`request.get/post/put/delete`
+- 导出：`request.download`
+- 失败导出：`request.postDownload`
+- JSON 响应按 `code===200` 判成功（导出接口除外）
+
+---
+
+## 5. 开发与评审检查清单（必须执行）
+
+### 5.1 新增接口检查
+- [ ] 路由命名符合标准
+- [ ] 权限点符合 `business:<module>:<action>`
+- [ ] 参数 VO 有校验注解
+- [ ] 响应类型为 `CommonResult` 或导出流
+- [ ] 无 `IllegalArgumentException` 直抛
+
+### 5.2 导出接口检查
+- [ ] 使用 `GET /export-excel`（新接口）
+- [ ] 使用 `ExcelUtils.*` 导出
+- [ ] 标注 `@ApiAccessLog(operateType = EXPORT)`
+- [ ] 具备 `...:export` 权限
+- [ ] 前端 `request.download` 可直接对接
+
+### 5.3 联调检查
+- [ ] 同筛选条件下“分页结果”和“导出结果”口径一致
+- [ ] 导出文件可正常打开，列头与业务语义一致
+- [ ] 异常场景返回结构可被前端统一处理
+
+---
+
+## 6. 账务调整模块专项治理要求
+
+### 6.1 现状
+- `log-export` / `prestorage-export` 仍为 CSV 特例
+
+### 6.2 治理目标
+- 与 `/business` 主流导出对齐为 Excel 导出
+- 保证前端调用方式不变或最小变更
+
+### 6.3 推荐迁移策略
+1. 保留旧路由（兼容）
+2. 新增/切换到 Excel 实现（`ExcelUtils`）
+3. 增加 `@ApiAccessLog(EXPORT)`
+4. 回归通过后，再评估是否下线 CSV 旧实现
+
+---
+
+## 7. 发布门禁（DoD）
+- [ ] 编译通过
+- [ ] 导出接口静态扫描通过（权限、审计、实现方式）
+- [ ] 前后端 smoke 联调通过（至少 3 个页面）
+- [ ] 变更说明写入对应 feature 文档或 evidence
+
+---
+
+## 8. 附：可直接执行的中文命令示例
+
+```bash
+# 1）进入后端仓库
+cd /Volumes/Dpan/github/water-workspace/water-backend
+
+# 2）扫描 /business 导出接口分布
+rg -n "@GetMapping\(\"/export|@PostMapping\(\"/export|writeCsv\(|ExcelUtils\.write" sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin -S
+
+# 3）扫描是否存在 Controller 直抛 IllegalArgumentException
+rg -n "throw new IllegalArgumentException" sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin -S
+
+# 4）进入前端仓库检查下载对接
+cd /Volumes/Dpan/github/water-workspace/water-frontend
+rg -n "request\.download\(|request\.postDownload\(" src/api -S
+```
+

docs/guides/REV004_FRONTEND_QA_DEBUG_NOTICE.md

@@ -0,0 +1,94 @@
+# REV004 联调通知（短版）
+
+各位前端 / 测试同学，REV004 本轮后端能力已合入 `develop`，现在可以开始联调：
+
+---
+
+## 一、本轮已可联调
+
+### 1. 分账专属接口
+- `POST /admin-api/business/split-adjust/submit`
+- `GET /admin-api/business/split-adjust/page`
+- `GET /admin-api/business/split-adjust/detail`
+- `GET /admin-api/business/split-adjust/result`
+
+### 2. 违约金减免
+- 支持按金额 / 按日期
+- 支持申请人、联系电话、申请原因、附件
+- formal-table 闭环已打通
+
+### 3. 预存转账
+已补齐并可回显：
+- `targetCustName`
+- `targetCustAddress`
+- `applicant`
+- `contactMobile`
+- `remainingAmount`
+
+---
+
+## 二、可直接用的联调样例
+
+### 分账成功
+- `splitAdjustNo = REV004-SPLIT-API-001`
+- `adjustmentNo = REV004-SPLIT-API-001`
+
+### 违约金减免成功
+- `adjustmentNo = REV004-LATEFEE-API-001`
+
+### 违约金减免待审批
+- `adjustmentNo = REV004-LATEFEE-API-002`
+
+---
+
+## 三、测试环境
+
+- `application-dev` 指向测试库已补齐相关表结构
+- real-db canary 已通过
+
+---
+
+## 四、重点建议验证
+
+1. 分账提交 → 详情 → 结果回显
+2. 违约金减免按金额 / 按日期两种模式
+3. 预存转账提交后分页/详情回显是否完整
+4. 日志/附件/流程查询是否一致
+
+---
+
+## 五、当前边界
+
+### 已覆盖
+- 分账专属接口
+- 违约金减免 formal-table
+- 预存转账关键字段回显
+
+### 未完全覆盖
+- 预存 formal-table 还没单独建
+- 坏账 / 核销 / 价差还没全部走 formal-table 路线
+
+---
+
+## 六、反馈方式
+
+如果发现问题，请直接带：
+- 接口路径
+- 请求参数
+- 返回报文
+- 对应 `adjustmentNo / splitAdjustNo`
+
+这样后端可以直接定位。
+
+---
+
+## 七、当前 develop 版本
+
+当前 develop 已包含：
+- PR #73：late-fee formal-table 闭环
+- PR #74：预存转账字段留痕与查询回显
+
+最新 develop merge commit：
+- `0d1e6d1d92fab7b59afc1f046ab08527691e9811`
+
+---

docs/guides/REV004_IMPLEMENTATION_HANDOFF.md

@@ -0,0 +1,563 @@
+# REV-004 全量账务实现分发清单
+
+## 1. 文档目的
+
+本文用于将 `REV-004` 全量账务领域的当前正式口径，整理为可直接分发给前后端实现 Agent 的任务清单、需求边界与协作约束，避免后续实现阶段再次回到“一期最小闭环”或“旧表整表平移”的摇摆状态。
+
+## 2. 当前统一口径
+
+### 2.1 当前正式事实
+
+- 当前正式统一入口：`IF-REV-007`
+- `REV-004` 已在概要、详设、数据库、接口四层正式文档中完成首轮收口
+- 当前正式表达仍采用：
+  - 当前事实
+  - 目标设计
+  - 历史只读 / 映射层
+  三层分离口径
+
+### 2.2 当前目标对象范围
+
+当前全量账务对象范围包括：
+
+- `PrepaidRefund`
+- `RedinkRecord`
+- `WrittenoffAdjust`
+- `PriceDiffAdjust`
+- `LateFeeReduce`
+- `BadDebtRecord`
+- `SplitAdjust`
+- 特殊开账 / 特账
+- `RefundBill`
+- `CrossCycleWaterRecord`
+
+### 2.3 当前设计约束
+
+1. 不得把目标设计写成当前已全部实现事实。
+2. 当前统一入口仍是 `IF-REV-007`，不能在未明确批准前直接改成多套正式专属接口编号。
+3. 旧系统对象必须分层承接：
+   - 在线统一骨架
+   - 独立业务对象
+   - 查询投影对象
+   - 历史只读 / 映射对象
+4. Archive 原始资料为证据来源，不作为当前实现修改目标。
+
+---
+
+## 3. 分发给后端 Agent 的功能清单
+
+### BE-01 统一账务处理入口扩展
+
+**目标**
+扩展 `IF-REV-007`，使其从一期五类场景提升为可承接全量账务对象的统一入口。
+
+**需求**
+后端统一入口需支持以下对象类型：
+
+- `PREPAID_REFUND`
+- `REDINK_RECORD`
+- `WRITTENOFF_ADJUST`
+- `PRICE_DIFF_ADJUST`
+- `LATE_FEE_REDUCE`
+- `BAD_DEBT_RECORD`
+- `SPLIT_ADJUST`
+- `SPECIAL_BILLING`
+- `REFUND_BILL`
+- `CROSS_CYCLE_WATER`
+
+**最小输入要求**
+
+- `chargeId`
+- `objectType`
+- `adjustType`（兼容保留）
+- `adjustAmount`
+- `adjustUsage`
+- `sourceTradeNo`
+- `relatedBizNo`
+- `reasonCode`
+- `approvalRequired`
+- `remark`
+- `attachmentList`
+- `operatorId`
+
+**最小输出要求**
+
+- `adjustmentNo`
+- `chargeId`
+- `objectType`
+- `resultStatus`
+- `writeBackStatus`
+- `approvalRequired`
+- `approvalStatus`
+- `resultObjectNo`
+- `msg`
+
+**验收重点**
+
+- `IF-REV-007` 仍是当前统一入口
+- 不要求一次性拆专属接口
+- `objectType` 成为统一对象表达核心字段
+
+---
+
+### BE-02 账务对象服务层分派机制
+
+**目标**
+建立 `objectType -> handler/service` 分派机制。
+
+**需求**
+至少按对象族拆分内部处理逻辑：
+
+- 预存退款处理
+- 红冲处理
+- 已销调整处理
+- 价差调整处理
+- 违约金减免处理
+- 坏账处理
+- 分账调整处理
+- 特账 / 特殊开账处理
+- 退款结果对象处理
+- 跨周期水量支撑处理
+
+**验收重点**
+
+- 外部继续统一入口
+- 内部分派清晰
+- 不再把所有对象混成单一“金额调整”逻辑块
+
+---
+
+### BE-03 审批边界承接
+
+**目标**
+统一承接审批能力位，而不是直接落完整 BPM。
+
+**需求**
+至少保留：
+
+- `approvalRequired`
+- `approvalStatus`
+- `legacyTaskId`
+- `legacyStepId`
+- `legacyFlowRemark`
+
+**当前对象分层要求**
+
+- 倾向独立审批流对象：
+  - `PrepaidRefund`
+  - `BadDebtRecord`
+- 当前先保留审批能力位：
+  - `WrittenoffAdjust`
+  - `PriceDiffAdjust`
+  - `LateFeeReduce`
+  - `SplitAdjust`
+  - `RedinkRecord`
+- 不单独审批：
+  - `RefundBill`
+  - `CrossCycleWaterRecord`
+
+**验收重点**
+
+- 承接审批语义即可
+- 本轮不要求直接接完整 BPM 引擎
+
+---
+
+### BE-04 统一留痕能力增强
+
+**目标**
+强化 `biz_operat_log` / `biz_operat_log_detail` 的账务承接能力。
+
+**需求**
+至少留痕：
+
+- 对象类型
+- 目标账单
+- 原交易引用
+- 原业务单号
+- 原因说明
+- 金额/水量前后差异
+- 审批状态
+- 操作人
+- 操作时间
+- 附件依据
+
+**验收重点**
+
+- 各账务对象都能统一追溯
+- 能支撑历史查询和迁移核查
+
+---
+
+### BE-05 数据库统一骨架承接
+
+**目标**
+继续以 `biz_charge` / `biz_charge_detail` 为统一骨架，不盲目整表平移。
+
+**需求**
+后端实现需遵循：
+
+- 新发生业务优先挂统一骨架
+- 不强制每个对象立刻单独建表
+- 对目标对象允许先通过：
+  - 统一骨架
+  - 目标字段组
+  - 历史映射
+  进行承接
+
+**特别要求**
+需重点考虑后续承接的目标对象：
+
+- `AccountingWorkflowRef`
+- `AccountingLegacyMapping`
+
+---
+
+### BE-06 历史只读 / 映射层查询承接
+
+**目标**
+旧系统细粒度台账不能丢，需要有后端查询承接。
+
+**至少保留查询能力的对象**
+
+- 红冲记录
+- 预存退款历史
+- 已销调整历史
+- 价差调整历史
+- 分账调整历史
+- 违约金减免历史
+- 坏账历史
+- 退款账结果
+- 跨周期水量
+- 实时收费日志
+- 对账日志
+- IC 卡账务
+
+**验收重点**
+
+- 不要求这些对象都转成在线主写表
+- 但必须可查、可追溯、可迁移验收
+
+---
+
+### BE-07 统一查询出口能力
+
+**目标**
+准备两类查询能力：
+
+#### 第一类：业务对象查询
+
+面向：
+
+- `PrepaidRefund`
+- `RedinkRecord`
+- `WrittenoffAdjust`
+- `PriceDiffAdjust`
+- `LateFeeReduce`
+- `BadDebtRecord`
+- `SplitAdjust`
+- `RefundBill`
+
+#### 第二类：历史只读 / 投影查询
+
+面向：
+
+- 实时收费
+- 对账日志
+- 柜台结账
+- IC 卡账务
+- 历史账务台账
+
+**验收重点**
+
+- 至少按 `objectType` 可区分
+- 支持汇总对账 + 明细追溯
+
+---
+
+## 4. 分发给前端 Agent 的功能清单
+
+### FE-01 统一账务处理入口页面改造
+
+**目标**
+前端继续使用统一账务处理入口，但支持全量对象类型。
+
+**需求**
+至少支持：
+
+- 对象类型选择 / 识别
+- 按对象动态显示字段
+- 审批状态展示
+- 处理结果展示
+- 账单回写状态展示
+
+**最低对象类型支持**
+
+- 预存退款
+- 红冲
+- 已销调整
+- 价差调整
+- 违约金减免
+- 坏账
+- 分账调整
+- 特账
+- 退款账结果查询
+- 跨周期水量查询
+
+---
+
+### FE-02 对象查询页 / 结果页分层
+
+**目标**
+查询页按两层口径组织。
+
+#### 业务对象查询页
+至少展示：
+
+- 单号
+- 对象类型
+- 关联账单
+- 状态
+- 审批状态
+- 金额 / 水量差异
+- 时间
+
+#### 历史只读查询页
+至少展示：
+
+- 原单号
+- 旧系统标识
+- 来源时间
+- 映射状态
+- 查询摘要
+
+**验收重点**
+
+- 不把历史只读查询和在线处理页混成一个页面
+
+---
+
+### FE-03 审批状态展示
+
+**目标**
+统一展示审批边界，但不假设 BPM 已完整落地。
+
+**需求**
+至少展示：
+
+- 是否需要审批
+- 当前审批状态
+- 审批意见摘要（如有）
+- 历史流程引用摘要（如有）
+
+---
+
+### FE-04 统一结果表达
+
+**目标**
+在 REV-004 页面中统一表达处理结果。
+
+**至少统一展示**
+
+- `resultStatus`
+- `writeBackStatus`
+- `approvalStatus`
+- `resultObjectNo`
+- `msg`
+
+**验收重点**
+
+- 不再只显示“成功 / 失败”
+- 要能区分：
+  - 处理成功
+  - 待审批
+  - 回写失败
+  - 部分成功
+
+---
+
+### FE-05 历史迁移核查页 / 对账页
+
+**目标**
+给迁移验收和历史比对保留前端展示入口。
+
+**建议查询维度**
+
+- 客户号
+- 手机号
+- 表号
+- 账期
+- 营业所
+- 渠道
+- 业务单号
+- `objectType`
+- 状态
+- 时间范围
+
+**验收重点**
+
+- 能看汇总
+- 能点进明细
+- 能定位单据级差异
+
+---
+
+## 5. 联调 / 共同实现清单
+
+### JOINT-01 枚举与字段统一
+
+前后端统一：
+
+- `objectType`
+- `adjustType`
+- `resultStatus`
+- `writeBackStatus`
+- `approvalStatus`
+
+### JOINT-02 当前事实与目标设计分层
+
+必须明确：
+
+- 哪些对象当前只是在统一入口下承接
+- 哪些对象只是目标设计命名
+- 哪些对象当前只支持查询，不支持在线提交
+
+### JOINT-03 历史查询口径统一
+
+统一以下查询口径：
+
+- 业务对象查询
+- 历史只读查询
+- 投影查询
+- 映射查询
+
+### JOINT-04 迁移验收维度统一
+
+统一核查维度：
+
+- 对象类型
+- 状态
+- 审批状态
+- 原单号 / 新单号
+- 金额 / 水量
+- 时间
+- 关联账单
+
+---
+
+## 6. 建议拆给其他 Agent 的任务包
+
+### Agent A：后端统一入口改造
+
+负责：
+
+- `IF-REV-007` 输入输出扩展
+- `objectType` 承接
+- 统一 handler 分派机制
+
+### Agent B：后端账务查询与历史兼容
+
+负责：
+
+- 业务对象查询出口
+- 历史只读 / 投影查询出口
+- 映射层查询支撑
+
+### Agent C：后端审批 / 留痕承接
+
+负责：
+
+- `approvalRequired`
+- `approvalStatus`
+- 操作留痕增强
+- 历史流程字段承接
+
+### Agent D：前端统一账务处理页面
+
+负责：
+
+- 统一入口页面改造
+- 对象差异化表单展示
+- 统一结果展示
+
+### Agent E：前端账务查询与迁移核查页面
+
+负责：
+
+- 业务对象查询页
+- 历史只读查询页
+- 差异定位展示
+
+### Agent F：联调与口径校验
+
+负责：
+
+- 枚举值统一
+- 字段命名统一
+- 页面与接口回包一致性校验
+- 历史查询与迁移验收口径校验
+
+---
+
+## 7. 最小交付顺序建议
+
+1. 后端统一入口改造
+2. 后端查询出口改造
+3. 前端统一入口页面改造
+4. 前端查询页改造
+5. 审批 / 留痕补强
+6. 迁移验收 / 历史核查联调
+
+---
+
+## 8. 给其他 Agent 的任务提示模板
+
+```text
+任务背景
+当前正在推进 REV-004 全量账务领域实现，对应正式文档已完成四层回写：详设、数据库、接口、概要。当前正式统一入口为 IF-REV-007，目标是在不破坏当前统一入口事实的前提下，承接全量账务对象。
+
+实现约束
+1. 不要把目标设计写成当前已完全实现事实
+2. 当前统一入口仍是 IF-REV-007
+3. 全量对象包括：
+   - PrepaidRefund
+   - RedinkRecord
+   - WrittenoffAdjust
+   - PriceDiffAdjust
+   - LateFeeReduce
+   - BadDebtRecord
+   - SplitAdjust
+   - 特殊开账 / 特账
+   - RefundBill
+   - CrossCycleWaterRecord
+4. 历史对象需区分：
+   - 在线统一骨架
+   - 独立业务对象
+   - 查询投影
+   - 历史只读 / 映射层
+
+请完成
+- 你负责的子任务：[填写 Agent A/B/C/D/E/F 的任务]
+- 输出：
+  1. 变更清单
+  2. 实现口径说明
+  3. 风险点
+  4. 与正式文档是否一致
+
+文档依据
+- docs/design/02_Detailed_Design/12_REV_Detailed.md
+- docs/design/03_Technical_Design/01_Database_Design.md
+- docs/design/03_Technical_Design/03_Interface_Design.md
+- docs/design/01_Overview/03_Summary_Design.md
+- docs/guides/REV004_FULL_ACCOUNTING_DOMAIN_DESIGN.md
+```
+
+---
+
+## 9. 参考文档
+
+- `docs/design/02_Detailed_Design/12_REV_Detailed.md`
+- `docs/design/03_Technical_Design/01_Database_Design.md`
+- `docs/design/03_Technical_Design/03_Interface_Design.md`
+- `docs/design/01_Overview/03_Summary_Design.md`
+- `docs/guides/REV004_FULL_ACCOUNTING_DOMAIN_DESIGN.md`

docs/guides/REV004_PREPAID_REFUND_TRANSFER_EVIDENCE_MATRIX.md

@@ -0,0 +1,137 @@
+# REV004 预存退款/转账原系统证据与待确认规则对照表
+
+## 文档目的
+用于区分：
+1. **原系统操作文档中已有直接证据**的规则/UI 形态
+2. **当前仅来自法规口径、业务访谈或实现推断**，尚需产品/财务/制度确认的规则
+
+避免把“原系统已证明”和“待确认业务规则”混写。
+
+---
+
+## 一、证据来源
+
+主要依据：
+- `docs/design/04_Appendix/Archive/02_Manuals/营收系统_用户操作手册.md`
+- `docs/design/04_Appendix/Archive/04_Original_Attachments/营收系统_用户操作手册.md`
+
+关键章节：
+- `12.3 预存调整`
+- `3.3.4 客户欠费缴费`
+
+关键截图：
+- `营收系统_用户操作手册_images/media/image486.png`
+
+---
+
+## 二、原系统可直接证明的内容
+
+| 主题 | 结论 | 证据类型 | 说明 |
+|---|---|---|---|
+| 预存调整功能存在 | 是 | 菜单/章节 | 原系统存在【账务处理】-【预存调整】模块 |
+| 预存调整支持“新增” | 是 | 操作文案 | 文档明确说明点击“新增”后可添加预存调整 |
+| 新增时必须输入系统存在的户号 | 是 | 操作文案 | 文档明确写“户号必须是系统中存在的户号” |
+| 新增时先选客户，再自动带出客户信息 | 是 | 截图 | 从新增弹窗可见客户编号、客户名称、客户地址、用水性质、预存金额、未到账金额为联动展示结构 |
+| 预存调整分为“预存退款/预存转账”两类 | 是 | 截图 | 新增弹窗存在两个 tab：`预存退款`、`预存转账` |
+| 预存退款页需要录入申请信息 | 是 | 截图 | 可见字段：退款金额、剩余金额、申请人、联系电话、申请原因、备注、上传 |
+| 客户详情会同时展示预存与欠费统计 | 是 | 文案 | 文档明确写客户详情界面会展示预存、欠费笔数、欠费金额、应缴金额 |
+| 预存与欠费在操作视图中有关联 | 是 | 文案/UI | 从客户详情汇总展示与预存调整入口形态可推断前台操作上是联动感知的 |
+
+---
+
+## 三、当前只能视为“待确认”的规则
+
+以下规则**未在原系统操作手册中找到直接证据**，当前不能写成“原系统已确认规则”：
+
+| 规则 | 当前状态 | 说明 |
+|---|---|---|
+| 用户对预存余额享有所有权 | 待确认 | 属于法规/制度表达，非原系统操作文案 |
+| 退款必须原路返还 | 待确认 | 原系统手册未见“原路返还”明确表述 |
+| 退款不收手续费 | 待确认 | 原系统手册未见 |
+| 退款前必须先抵扣欠费 | 待确认 | 原系统手册未见明确账务顺序 |
+| 预存抵扣顺序：违约金 → 水费本金 → 其他费用 | 待确认 | 这是强财务规则，原手册未给出 |
+| 同主体、同区域、同公司才能转账 | 待确认 | 原手册仅证明“有预存转账”，未证明限制条件 |
+| 有预存则不产生坏账 | 待确认 | 属于业务推断，非原系统直接表述 |
+| 销户退款必须先清欠费再退款 | 待确认 | 原手册未见直接条文 |
+| 已核销坏账与预存退款完全独立核算 | 待确认 | 原系统操作手册未给出 |
+
+---
+
+## 四、对当前 REV004 实现/设计的建议口径
+
+### 4.1 可直接作为“原系统一致”的内容
+可以写成：
+
+1. 原系统存在**预存调整**模块
+2. 预存调整包含：
+   - 预存退款
+   - 预存转账
+3. 新增预存调整时，先选择客户/户号，再自动带出：
+   - 客户名称
+   - 客户地址
+   - 用水性质
+   - 预存金额
+   - 未到账金额
+4. 退款页需要申请信息：
+   - 申请人
+   - 联系电话
+   - 申请原因
+   - 备注
+   - 附件
+
+### 4.2 只能作为“待制度确认”的内容
+建议写成：
+
+> 以下规则依据法规理解、业务访谈或拟实现口径提出，尚未从原系统操作文档中找到直接证据，需产品/财务/制度进一步确认：
+
+- 原路返还
+- 不收手续费
+- 抵扣顺序
+- 转账主体/区域限制
+- 清欠前置规则
+- 预存与坏账/核销的强约束关系
+
+---
+
+## 五、建议给产品/财务确认的问题清单
+
+1. 预存退款是否必须**原路返还**？
+2. 预存退款是否允许**线下转账**或人工指定退款账户？
+3. 预存退款是否存在**手续费**或其他财务限制？
+4. 有欠费时，是否必须**先抵扣后退款**？
+5. 如需抵扣，抵扣顺序是否为：
+   - 违约金
+   - 水费本金
+   - 其他费用
+6. 预存转账是否仅允许：
+   - 同主体
+   - 同区域
+   - 同公司
+7. 销户退款是否必须先完成：
+   - 销户
+   - 清欠
+   - 无冻结/无争议
+8. 坏账/核销状态下，预存是否仍可退/可转？
+
+---
+
+## 六、当前结论
+
+### 已有原系统证据的部分
+- 功能存在
+- UI 形态存在
+- 关键字段存在
+- 客户选择后信息自动带出这一交互形态基本成立
+
+### 尚未有原系统直接证据的部分
+- 财务清算规则
+- 原路退款规则
+- 抵扣优先级
+- 转账限制边界
+- 与坏账/核销的强约束关系
+
+因此，当前最稳妥的做法是：
+- **UI 与字段设计**可参考原系统直接推进
+- **资金与账务规则**必须单独走确认流程
+
+---