diff --git a/docs/guides/REV004_ACCOUNTING_ADJUST_API_DELTA.md b/docs/guides/REV004_ACCOUNTING_ADJUST_API_DELTA.md new file mode 100644 index 0000000..1eecaec --- /dev/null +++ b/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/*`，但需按本次新增字段补齐请求/展示 + +--- diff --git a/docs/guides/REV004_ACCOUNTING_ADJUST_FRONTEND_DEBUG_DATA.md b/docs/guides/REV004_ACCOUNTING_ADJUST_FRONTEND_DEBUG_DATA.md new file mode 100644 index 0000000..83f0677 --- /dev/null +++ b/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` 兼容查询接口 +- 申请态 / 审批态 / 执行态的展示联调 + +--- diff --git a/docs/guides/REV004_CURRENT_TRUTH_MATRIX.md b/docs/guides/REV004_CURRENT_TRUTH_MATRIX.md new file mode 100644 index 0000000..6eda2da --- /dev/null +++ b/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` diff --git a/docs/guides/REV004_FRONTEND_IMPLEMENTATION_HANDOFF.md b/docs/guides/REV004_FRONTEND_IMPLEMENTATION_HANDOFF.md new file mode 100644 index 0000000..0e7189d --- /dev/null +++ b/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` diff --git a/docs/guides/REV004_FRONTEND_OMX_TEAM_PROMPTS.md b/docs/guides/REV004_FRONTEND_OMX_TEAM_PROMPTS.md new file mode 100644 index 0000000..3d07d3a --- /dev/null +++ b/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. 联调问题清单 +``` diff --git a/docs/guides/REV004_FRONTEND_OPEN_API_DEVELOPMENT_STANDARD.md b/docs/guides/REV004_FRONTEND_OPEN_API_DEVELOPMENT_STANDARD.md new file mode 100644 index 0000000..ff89051 --- /dev/null +++ b/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` | +| 分页接口 | `CommonResult>`（字段固定 `list`、`total`） | +| 导出接口 | 二进制流（不包 `CommonResult`） | + +### 4.3 权限与审计标准 +- 导出接口权限统一：`@PreAuthorize("@ss.hasPermission('business::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::` +- [ ] 参数 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 +``` + diff --git a/docs/guides/REV004_FRONTEND_QA_DEBUG_NOTICE.md b/docs/guides/REV004_FRONTEND_QA_DEBUG_NOTICE.md new file mode 100644 index 0000000..eb9e356 --- /dev/null +++ b/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` + +--- diff --git a/docs/guides/REV004_FULL_ACCOUNTING_DOMAIN_DESIGN.md b/docs/guides/REV004_FULL_ACCOUNTING_DOMAIN_DESIGN.md new file mode 100644 index 0000000..d371b99 --- /dev/null +++ b/docs/guides/REV004_FULL_ACCOUNTING_DOMAIN_DESIGN.md @@ -0,0 +1,1741 @@ +# REV-004 全量账务领域设计骨架 + +## 1. 文档定位 + +本文档用于在现有 `REV-004` 一期设计基础上，补充一份面向“完整承载旧系统账务业务”的全量账务领域设计骨架，作为后续分批细化、正式文档回写、数据迁移设计和 backend 实施拆解的统一底稿。 + +本文件不是新的正式主文档替代稿，而是： + +- 对旧系统账务建模方式的结构化承接草案 +- 对新系统账务领域目标对象的统一设计骨架 +- 对“统一核心模型 + 独立业务实体 + 查询投影 + 历史映射”路线的落地说明 + +## 2. 设计目标 + +本设计面向以下目标： + +1. 完整承载旧系统账务相关业务，而不是仅覆盖一期最小闭环。 +2. 避免机械平移旧系统全部物理表结构，控制新系统领域复杂度。 +3. 在统一账务核心骨架下，为强业务场景保留正式业务实体。 +4. 保留旧系统台账查询、审批追溯、统计核对和历史迁移能力。 +5. 为后续正式主文档、数据库设计、接口设计和 backend 实施提供统一口径。 + +## 2.1 当前冻结范围 + +本轮冻结后的设计范围固定如下： + +1. 覆盖**旧系统账务相关全部业务对象**，不再局限于 `REV-004` 一期五类场景。 +2. 同时纳入以下 4 类设计内容： + - 领域对象与目标表设计 + - 接口承接设计 + - 审批 / BPM 承接设计 + - 历史迁移与查询兼容设计 +3. 当前首要产物固定为 `docs/guides/REV004_FULL_ACCOUNTING_DOMAIN_DESIGN.md`，作为全量账务领域设计的统一工作底稿。 +4. 后续允许按本底稿分批回写正式主文档，但当前阶段不直接把本稿视为正式交付主稿。 + +## 2.2 当前非目标 + +本轮明确不直接纳入以下内容： + +1. backend 实现代码 +2. 数据库建表 SQL / migration 脚本 +3. 历史迁移执行脚本 +4. 在正式目录旁保留 `*_old.md`、`*_v1.md` 等平行正式稿 +5. 复制一整套旧版正式文档目录作为运行中的第二真源 + +## 3. 来源与对齐基线 + +### 3.1 正式来源 + +- `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` + +### 3.2 历史与核对来源 + +- `docs/design/04_Appendix/Archive/05_Data_Dictionary/营收数据字典.md` +- `docs/guides/REV004_LEGACY_FINANCE_MIGRATION_PLAN_V0.md` +- `docs/guides/BACKEND_TABLE_MAPPING.md` + +> 约束说明：以上历史来源仅用于**读取、核对、抽取和追溯**，不作为本轮直接修改目标；尤其 `Archive/05_Data_Dictionary/营收数据字典.md` 只读不改。 + +### 3.3 当前统一判断 + +1. 旧系统账务建模是典型的“场景台账型”模型。 +2. 新系统若要完整承载旧业务，不适合只保留一期统一主模型。 +3. 新系统也不应机械复制旧系统全部账务表族作为主写模型。 +4. 更合理的路线是： + - 统一核心账务骨架 + - 独立业务实体承接强场景 + - 查询投影承接旧菜单和旧报表 + - 历史映射承接旧主键和迁移追溯 + +### 3.4 真源边界与职责切分 + +当前真源边界固定如下： + +| 文档层 | 当前职责 | +|---|---| +| `specs/001-rev004-accounting/` | 继续约束 `REV-004` 一期最小闭环，不被本底稿覆盖或替代 | +| `specs/008-rev004-legacy-finance-migration/` | 继续约束旧账务迁移映射方法、缺失判定、迁移矩阵与批次策略 | +| `docs/guides/REV004_FULL_ACCOUNTING_DOMAIN_DESIGN.md` | 当前阶段唯一全量账务领域设计工作底稿 | +| `docs/design/*` 正式主文档 | 最终正式交付真源；仅在达到冻结条件后按批次回写 | + +### 3.5 正式回写与旧版保留规则 + +后续若启动正式主文档回写，必须遵守： + +1. 正式主文档回写前，旧版仅通过以下两种方式保留： + - Git 历史 + - `Archive/` 快照 +2. 不在正式目录中制造平行旧版文件。 +3. 每次正式回写前必须先冻结： + - 统一术语 + - 对象清单 + - 关系图 + - 回写范围 +4. 每次正式回写必须有明确的快照记录： + - 原文件路径 + - 快照日期 + - 快照归档路径 + - 对应回写批次号 + +## 4. 术语与口径统一 + +### 4.1 当前统一术语 + +| 术语 | 当前统一口径 | +|---|---| +| 账务处理 | 新系统中的控制骨架与统一处理能力总称 | +| 账务主单 | 一次账务处理申请/受理/执行过程的统一骨架对象 | +| 账务明细 | 账务主单影响的账单、流水、金额、水量等对象明细 | +| 业务实体 | 在业务上具备独立生命周期、审批、查询入口或强语义边界的对象 | +| 查询投影 | 面向旧菜单、旧报表、运营统计的查询/聚合对象 | +| 历史映射 | 旧系统表主键、单号、流程号与新系统对象的映射关系 | + +### 4.2 本文采用的分层术语 + +| 分层 | 说明 | +|---|---| +| `L1 核心抽象层` | 统一账务处理主单、明细、流程引用、留痕、期间、映射等骨架对象 | +| `L2 独立业务层` | 必须保留独立业务语义的正式账务实体 | +| `L3 查询投影层` | 面向历史查询、统计分析、旧菜单兼容的投影对象 | +| `L4 历史映射层` | 承接旧主键、旧单号、旧流程号和迁移批次追溯 | + +### 4.3 本文固定术语替换规则 + +为避免后续继续漂移，本文固定以下规则： + +1. “全量账务领域设计”默认指向**旧系统账务全部业务对象的目标态设计**。 +2. “一期口径”默认仅指 `specs/001-rev004-accounting/` 中的 `REV-004` 一期边界。 +3. “迁移设计”默认指 `specs/008-rev004-legacy-finance-migration/` 中的迁移方法、映射与缺失分析，不替代目标领域模型。 +4. “正式业务实体”指在新系统中保留独立业务语义、生命周期或查询入口的对象，不等同于旧表一比一平移。 +5. “查询投影”指服务旧菜单、旧报表、统计核查的只读或聚合承接对象，不作为新业务主写模型。 + +## 5. 旧系统账务建模特征 + +根据历史数据字典，旧系统账务域具备以下特征： + +1. 账务对象以业务场景为中心拆分，而非统一领域模型。 +2. 大量场景采用“汇总表 + 明细表”成对建模。 +3. 普遍嵌入流程字段： + - `TaskId` + - `StepId` + - `FlowRemark` +4. 普遍嵌入处理字段： + - `ProcType` + - `ProcPerson` + - `ProcDate` + - `ProcRemark` +5. 普遍围绕既有账单/流水修正： + - `FeeId` + - `NewFeeId` + - `AccountLogId` + - `TargetAccountLogId` +6. 普遍保留账务周期： + - `BillMonth` + +因此，旧系统账务模型本质上是： + +> 面向菜单和审批流的场景台账体系，而不是统一账务中心模型。 + +## 6. 目标建模总原则 + +### 6.1 必须坚持的原则 + +1. 不机械平移旧系统全部物理表结构作为新系统主写模型。 +2. 不把所有旧场景都压缩到一个通用表中导致语义丢失。 +3. 不让兼容层反客为主，直接成为新业务主写模型。 +4. 对强生命周期、强审批、强查询入口、强差异结构场景保留独立业务实体。 +5. 对旧系统高频查询和报表口径，必须提供查询投影承接。 +6. 对历史数据迁移，必须保留主键、单号、流程号级别的映射关系。 + +### 6.2 设计路线 + +新系统全量账务领域采用以下路线： + +```text +统一核心账务骨架 + + 独立业务实体 + + 查询投影对象 + + 历史映射对象 +``` + +## 7. 领域分层设计 + +### 7.1 L1 核心抽象层 + +建议保留以下统一骨架对象： + +| 对象 | 作用 | +|---|---| +| `AccountingCase` | 统一账务处理主单骨架，承接申请、状态、审批、结果 | +| `AccountingCaseDetail` | 统一账务处理明细骨架，承接受影响账单/流水/差异 | +| `AccountingWorkflowRef` | 统一审批流引用与流程状态 | +| `AccountingOperationLog` | 统一账务操作留痕 | +| `AccountingLegacyMapping` | 统一历史映射关系 | +| `BillingPeriod` | 统一账务年月与期间控制对象 | +| `AccountingProcTypeDict` | 统一处理方式字典 | + +### 7.2 L2 独立业务层 + +建议保留以下正式业务实体： + +| 对象 | 是否建议独立 | 说明 | +|---|---|---| +| `PrepaidRefund` / `PrepaidRefundDetail` | 是 | 预存退款生命周期独立 | +| `RedinkRecord` / `RedinkRecordDetail` | 是 | 红冲是强审计、强查询对象 | +| `WrittenoffAdjust` / `WrittenoffAdjustDetail` | 是 | 已销调整与普通金额调整不同 | +| `PriceDiffAdjust` / `PriceDiffAdjustDetail` | 是 | 涉及调价号、阶梯、累计量 | +| `LateFeeReduce` / `LateFeeReduceDetail` | 是 | 违约金减免具备独立业务语义 | +| `BadDebtRecord` / `BadDebtRecordDetail` | 是 | 坏账是财务强对象 | +| `SplitAdjust` / `SplitAdjustDetail` | 是 | 分账结构差异大 | +| `SpecialBillingType`（挂接 `Charge` / `ChargeDetail`） | 否，优先不独立 | 特账更符合特殊开账产生的特殊账单/收费类型 | +| `RefundBill` | 是 | 退款账是结果型正式对象 | +| `CrossCycleWaterRecord` | 是 | 跨周期水量是独立基础数据对象，不是强流程型业务单 | + +### 7.3 L3 查询投影层 + +建议保留以下查询/统计对象： + +| 对象 | 说明 | +|---|---| +| `RealtimeCollectionBatch` | 实时收费汇总 | +| `RealtimeCollectionLog` | 实时收费日志 | +| `RealtimeCollectionLogDetail` | 实时收费明细 | +| `PaymentCheckLog` | 对账日志 | +| `CollectionSummaryView` | 收费汇总/收费小计/收费明细投影 | +| `DifficultDuplicateBillView` | 疑难重笔账投影 | + +### 7.4 L4 历史映射层 + +建议统一保留： + +| 对象 | 说明 | +|---|---| +| `AccountingLegacyMapping` | 映射旧表、旧主键、旧父级主键、旧单号、旧流程号与新对象 | + +### 7.5 旧账务对象全量分层矩阵 + +下表用于把旧系统账务对象统一归入 `L1/L2/L3/L4`，作为后续对象设计、接口承接、审批承接和迁移承接的共同基础。 + +| 旧对象 | 旧表/表族 | 目标分层 | 当前建议归类 | 归层依据 | +|---|---|---|---|---| +| 营业账 | 账务信息域 / 营业账 | `L1` | 核心抽象对象 | 所有账务处理的核心账单承接对象 | +| 营业账明细 | 账务信息域 / 营业账明细 | `L1` | 核心抽象对象 | 账务明细与费用项承接对象 | +| 账务年月 | 系统相关 / 账务年月表 | `L1` | 核心抽象对象 | 账务期间控制与账期闭环基础对象 | +| 账务处理方式 | 字典 / `ProcType` | `L1` | 核心抽象对象 | 多个账务场景共享处理动作语义 | +| 预存退款 | `PM_ACCOUNT_RECORDS` | `L2` | 独立业务实体 | 生命周期、审批、处理方式、账户流水引用独立 | +| 预存退款详情 | `PM_ACCOUNT_RECORD_DETAILS` | `L2` | 独立业务实体明细 | 直接承接受影响客户、金额、流水、账期 | +| 已销调整汇总 | `PM_PAYMENT_RECORDS` | `L2` | 独立业务实体 | 已收费后修正语义独立 | +| 已销调整明细 | `PM_PAYMENT_RECORD_DETAILS` | `L2` | 独立业务实体明细 | 原账单/新账单/原流水/目标流水关系强 | +| 价差调整汇总 | `PM_PRICE_RECORDS` | `L2` | 独立业务实体 | 调价号、阶梯、累计量等规则独立 | +| 价差调整明细 | `PM_PRICE_RECORD_DETAILS` | `L2` | 独立业务实体明细 | 前后金额、滞纳金、账单差额变化独立 | +| 账单-违约金减免汇总 | `PM_LATEFEE_RECORDS` | `L2` | 独立业务实体 | 减免类型、起止时间、审批独立 | +| 账单-违约金减免详情 | `PM_LATEFEE_RECORD_DETAILS` | `L2` | 独立业务实体明细 | 调整前后违约金差异独立 | +| 账单-呆坏账汇总 | 呆坏账汇总表 | `L2` | 独立业务实体 | 财务处置与审批语义独立 | +| 账单-呆坏账详情 | 呆坏账详情表 | `L2` | 独立业务实体明细 | 坏账账龄、状态、核销差异明细独立 | +| 红冲表 | `PM_REDINK_ENTRYS` | `L2` | 独立业务实体 | 柜面核账、审计、历史追溯高频入口 | +| 红冲明细 | 红冲相关明细 | `L2` | 独立业务实体明细 | 红冲影响的收费/账单/金额明细需独立承接 | +| 分账调整汇总 | 分账调整汇总 | `L2` | 独立业务实体 | 分摊规则与目标对象结构差异大 | +| 分账调整明细 | 分账调整明细 | `L2` | 独立业务实体明细 | 目标账单/目标客户/金额分摊强绑定 | +| 特账 | 特账 | `L1` | 主模型扩展类型 | 更符合特殊开账产生的特殊账单/收费类型 | +| 特账明细 | 特账明细 | `L1` | 主模型扩展明细 | 通过账单主明细 + 类型/来源字段承接 | +| 退款账 | 退款账 | `L2` | 独立业务实体 | 结果型账务对象，不只是退款动作日志 | +| 跨周期水量 | 跨周期水量 | `L2` | 独立基础数据对象 | 服务跨账期计费、阶梯累计和账单重算 | +| 阶梯累计量 | 阶梯累计量 | `L2` | 独立业务实体或基础规则对象 | 影响阶梯计费和账务重算逻辑 | +| 实时收费汇总表 | `PM_REALTIME_SUBTOTALS` | `L3` | 查询投影对象 | 汇总查询、对账核查和渠道台账 | +| 实时收费日志表 | `PM_REALTIMES` | `L3` | 查询投影对象 | 渠道交易与实时收费日志 | +| 实时收费日志明细表 | `PM_REALTIMES_DETAILS` | `L3` | 查询投影对象 | 账单级交易明细查询 | +| 对账日志 | `PM_PAYMENT_LOGS` | `L3` | 查询投影对象 | 对账过程和结果日志更适合只读承接 | +| 收费汇总 | 收费汇总 | `L3` | 查询投影对象 | 统计聚合与柜面核查口径 | +| 收费小计 | 收费小计 | `L3` | 查询投影对象 | 班结、阶段汇总、日终核查口径 | +| 收费明细 | 收费明细 | `L3` | 查询投影对象 | 更适合由收费/交易对象投影形成 | +| 疑难重笔账 | 疑难重笔账 / 汇总 | `L3` | 查询投影对象 | 偏核查治理而非在线主业务 | +| IC 卡充退表 | IC 卡账务表族 | `L3`（旧系统已确认存在） | 历史只读查询对象 | 旧系统正式存在；当前新系统按历史只读 + 映射层承接 | +| IC 卡充退账明细 | IC 卡账务表族 | `L3`（旧系统已确认存在） | 历史只读查询对象 | 旧系统正式存在；当前新系统按历史只读 + 映射层承接 | +| IC 卡结余记录 | IC 卡账务表族 | `L3`（旧系统已确认存在） | 查询投影对象 | 旧系统正式存在，当前更偏查询和历史核对 | +| IC 卡操作日志 | IC 卡账务表族 | `L3`（旧系统已确认存在） | 查询投影对象 | 旧系统正式存在，当前更偏日志与审计核查 | +| 旧主键/旧单号/旧流程号映射 | 所有旧账务对象 | `L4` | 历史映射对象 | 服务历史迁移、追溯和新旧标识映射 | + +### 7.6 当前冻结的分层判断规则 + +为避免后续对象继续漂移，分层判断暂时冻结为以下规则： + +1. 满足以下任一条件的对象，优先判为 `L2 独立业务层`： + - 生命周期独立 + - 审批流独立 + - 历史查询入口独立 + - 明细结构明显异于通用账务明细 +2. 满足以下任一条件的对象，优先判为 `L3 查询投影层`： + - 以查询、汇总、对账、统计、核查为主 + - 不适合作为新系统主写模型 + - 适合从 `Charge`、`Transaction`、日志对象投影生成 +3. 仅承接新旧标识映射、迁移批次和追溯关系的对象，固定归 `L4`。 +4. `L1` 只保留跨场景共用骨架，不吸收具备强独立语义的业务对象。 +5. 当旧对象本质是账单来源类型、收费类型或开账类型时，优先挂接到既有主模型扩展字段，不单独提升为 `L2` 正式业务实体。 + +## 8. 正式业务实体清单 + +### 8.1 建议正式保留的核心业务实体 + +| 实体 | 旧系统来源 | 独立原因 | 承接重点 | +|---|---|---|---| +| `PrepaidRefund` | `PM_ACCOUNT_RECORDS*` | 预存退款申请、处理、退款方式和账户流水引用独立 | 原流水、目标流水、退款金额、退款类型 | +| `RedinkRecord` | `PM_REDINK_ENTRYS` | 红冲是柜面核账和审计的高频入口 | 红冲单号、原收费、红冲金额、红冲原因 | +| `WrittenoffAdjust` | `PM_PAYMENT_RECORDS*` | 已销调整涉及已收金额、抵扣、滞纳金、原/新账单 | 原账单、新账单、原流水、处理方式 | +| `PriceDiffAdjust` | `PM_PRICE_RECORDS*` | 价差调整涉及价格体系差异与重算规则 | 调价号、价格口径、累计量、前后金额差异 | +| `LateFeeReduce` | `PM_LATEFEE_RECORDS*` | 违约金减免业务边界清晰 | 减免类型、起止时间、前后违约金 | +| `BadDebtRecord` | `呆坏账表族` | 财务处置和审批语义独立 | 坏账原因、坏账类型、账龄、核销状态 | +| `SplitAdjust` | `分账调整表族` | 分摊结构差异显著 | 原账单、目标账单、分摊金额、规则 | +| `SpecialBillingType`（挂接 `Charge` / `ChargeDetail`） | `特账表族` | 更接近特殊开账形成的特殊账单/收费类型 | 来源类型、业务类型、特账类型、状态、关联账单 | +| `RefundBill` | `退款账` | 结果型账务对象 | 退款形成后的正式账务结果 | +| `CrossCycleWaterRecord` | `跨周期水量` | 账务重算与阶梯累计支撑对象 | 周期跨度、客户、账单影响范围 | + +### 8.2 正式业务实体与统一骨架关系 + +```mermaid +flowchart LR + classDef core fill:#eef2ff,stroke:#4f46e5,color:#312e81,stroke-width:1.2px; + classDef biz fill:#eff6ff,stroke:#2563eb,color:#1e3a8a,stroke-width:1.2px; + classDef base fill:#ecfdf5,stroke:#059669,color:#14532d,stroke-width:1.2px; + classDef query fill:#f5f3ff,stroke:#7c3aed,color:#4c1d95,stroke-width:1.2px; + classDef support fill:#fff7ed,stroke:#ea580c,color:#7c2d12,stroke-width:1.2px; + + subgraph CORE[统一骨架层] + AC[AccountingCase]:::core + ACD[AccountingCaseDetail]:::core + AWF[AccountingWorkflowRef]:::core + ALOG[AccountingOperationLog]:::core + AMAP[AccountingLegacyMapping]:::support + PERIOD[BillingPeriod]:::support + end + + subgraph BASE[基础业务对象] + CHARGE[Charge]:::base + CDETAIL[ChargeDetail]:::base + TRANS[Transaction]:::base + ALOGSRC[AccountLog]:::base + CUST[Customer]:::base + end + + subgraph BIZ[正式业务实体] + PR[PrepaidRefund]:::biz + RED[RedinkRecord]:::biz + WA[WrittenoffAdjust]:::biz + PDA[PriceDiffAdjust]:::biz + LFR[LateFeeReduce]:::biz + BDR[BadDebtRecord]:::biz + SA[SplitAdjust]:::biz + RB[RefundBill]:::biz + CCW[CrossCycleWaterRecord]:::biz + end + + subgraph QUERY[查询投影对象] + RTCB[RealtimeCollectionBatch]:::query + RTCL[RealtimeCollectionLog]:::query + PCL[PaymentCheckLog]:::query + end + + AC --> ACD + AC --> AWF + AC --> ALOG + AC --> PERIOD + AC --> AMAP + + PR --> AC + RED --> AC + WA --> AC + PDA --> AC + LFR --> AC + BDR --> AC + SA --> AC + RB --> AC + CCW --> AC + + ACD --> CHARGE + ACD --> CDETAIL + ACD --> TRANS + ACD --> ALOGSRC + AC --> CUST + + RTCB --> TRANS + RTCL --> TRANS + PCL --> TRANS +``` + +### 8.3 正式业务实体详细骨架 + +下表用于定义每个正式业务实体的最小业务结构，作为后续数据库表设计与接口设计的共同基础。 + +#### 8.3.1 `PrepaidRefund` / `PrepaidRefundDetail` + +| 项目 | 设计建议 | +|---|---| +| 主表角色 | 预存退款申请主单，承接申请、审批、退款状态与统一账务主单关联 | +| 明细表角色 | 记录受影响客户、退款金额、原账户流水、目标流水、处理方式与账期 | +| 主表关键字段组 | 单号：`refund_no`；申请：`applicant_id/name/mobile`；业务：`refund_type`、`apply_reason_code`、`remark`；流程：`approval_task_id`、`approval_step_id`、`approval_remark`；统一骨架：`accounting_case_id` | +| 明细表关键字段组 | 对象：`cust_id/cust_code`；金额：`refund_amount`、`surplus_deposit`、`uncheck_amount`；流水：`source_account_log_id`、`target_account_log_id`；处理：`proc_type`、`proc_person`、`proc_time`、`proc_remark`；期间：`bill_month` | +| 主外键关系 | 主表 `id` -> 明细表 `refund_id`；主表 `accounting_case_id` -> `biz_accounting_case.id` | +| 核心状态字段 | `refund_status`：`DRAFT/SUBMITTED/PENDING_APPROVAL/APPROVED/REFUNDING/SUCCESS/FAIL/CANCELLED` | +| 主要依赖对象 | `AccountingCase`、`AccountLog`、`Customer`、必要时关联 `Transaction` | + +#### 8.3.2 `RedinkRecord` / `RedinkRecordDetail` + +| 项目 | 设计建议 | +|---|---| +| 主表角色 | 红冲主对象，承接红冲申请、红冲结果、经办人与汇总金额 | +| 明细表角色 | 记录原收费、原账单、红冲金额、红冲原因、影响范围 | +| 主表关键字段组 | 单号：`redink_no`；柜面：`org_id`、`cashier_id`；操作：`redink_user_id`、`redink_time`；金额：`redink_amount_total`、`redink_count`；统一骨架：`accounting_case_id` | +| 明细表关键字段组 | 原对象：`source_charge_id`、`source_collection_id`、`source_transaction_id`；金额：`redink_amount`；原因：`reason_code/reason_text`；追溯：`source_bill_no`、`source_trade_no` | +| 主外键关系 | 主表 `id` -> 明细表 `redink_record_id`；主表 `accounting_case_id` -> `biz_accounting_case.id` | +| 核心状态字段 | `redink_status`：`SUBMITTED/PENDING_APPROVAL/APPROVED/SUCCESS/FAIL/CANCELLED` | +| 主要依赖对象 | `AccountingCase`、`Charge`、`Transaction`、`Collection` | + +#### 8.3.3 `WrittenoffAdjust` / `WrittenoffAdjustDetail` + +| 项目 | 设计建议 | +|---|---| +| 主表角色 | 已销调整主单，承接已收费后账单修正 | +| 明细表角色 | 记录原账单、新账单、原流水、目标流水、实收/抵扣/滞纳金差异 | +| 主表关键字段组 | 单号：`writtenoff_adjust_no`；申请：`applicant_id/name/mobile`；业务：`apply_reason_code`、`remark`；流程：`approval_*`；统一骨架：`accounting_case_id` | +| 明细表关键字段组 | 账单：`source_charge_id`、`target_charge_id`；金额：`bill_amount_before/after`、`actual_amount_before/after`、`deduction_amount_before/after`、`late_fee_before/after`；流水：`source_account_log_id`、`target_account_log_id`；处理：`proc_type` | +| 主外键关系 | 主表 `id` -> 明细表 `writtenoff_adjust_id`；主表 `accounting_case_id` -> `biz_accounting_case.id` | +| 核心状态字段 | `adjust_status`：`SUBMITTED/PENDING_APPROVAL/APPROVED/PROCESSING/SUCCESS/FAIL` | +| 主要依赖对象 | `AccountingCase`、`Charge`、`ChargeDetail`、`AccountLog`、必要时 `Transaction` | + +#### 8.3.4 `PriceDiffAdjust` / `PriceDiffAdjustDetail` + +| 项目 | 设计建议 | +|---|---| +| 主表角色 | 价差调整主单，承接价格体系变化带来的账务修正 | +| 明细表角色 | 记录调价前后账单金额、滞纳金、是否阶梯、是否影响累计量 | +| 主表关键字段组 | 单号：`price_diff_no`；价格：`price_list_id`、`price_code`、`is_ladder`、`is_change_total`；申请/流程字段；统一骨架：`accounting_case_id` | +| 明细表关键字段组 | 账单：`charge_id`、`new_charge_id`；金额：`bill_amount_before/after`、`extended_amount_before/after`、`late_fee_before/after`；客户：`cust_id/cust_code`；期间：`bill_month` | +| 主外键关系 | 主表 `id` -> 明细表 `price_diff_adjust_id`；主表 `accounting_case_id` -> `biz_accounting_case.id` | +| 核心状态字段 | `price_diff_status`：`SUBMITTED/PENDING_APPROVAL/APPROVED/PROCESSING/SUCCESS/FAIL` | +| 主要依赖对象 | `AccountingCase`、`Charge`、`PriceTemplate/PriceCategory`、必要时 `CrossCycleWaterRecord`、`LadderAccumulate` | + +#### 8.3.5 `LateFeeReduce` / `LateFeeReduceDetail` + +| 项目 | 设计建议 | +|---|---| +| 主表角色 | 违约金减免主单 | +| 明细表角色 | 记录减免对象、起止时间、原违约金、减免金额、调整后违约金 | +| 主表关键字段组 | 单号：`latefee_reduce_no`；申请：`applicant_*`；业务：`late_fee_type`、`apply_reason_code`、`remark`；流程：`approval_*`；统一骨架：`accounting_case_id` | +| 明细表关键字段组 | 对象：`charge_id`、`cust_id`；期间：`bill_month`、`start_date`、`end_date`；金额：`late_fee_before`、`reduce_amount`、`late_fee_after`；处理：`proc_type/proc_person/proc_time` | +| 主外键关系 | 主表 `id` -> 明细表 `latefee_reduce_id`；主表 `accounting_case_id` -> `biz_accounting_case.id` | +| 核心状态字段 | `reduce_status`：`SUBMITTED/PENDING_APPROVAL/APPROVED/SUCCESS/FAIL` | +| 主要依赖对象 | `AccountingCase`、`Charge` | + +#### 8.3.6 `BadDebtRecord` / `BadDebtRecordDetail` + +| 项目 | 设计建议 | +|---|---| +| 主表角色 | 呆坏账申请/认定/核销主单 | +| 明细表角色 | 记录账龄、账单、客户状态、核销状态、处理结果 | +| 主表关键字段组 | 单号：`bad_debt_no`；业务：`bad_debt_type`、`reason_code`、`remark`；申请与流程字段；统一骨架：`accounting_case_id` | +| 明细表关键字段组 | 对象：`charge_id`、`cust_id`；账龄：`aging_days/aging_bucket`；状态：`charge_status_before/after`、`writeoff_status`；金额：`receivable_amount`、`late_fee_amount` | +| 主外键关系 | 主表 `id` -> 明细表 `bad_debt_record_id`；主表 `accounting_case_id` -> `biz_accounting_case.id` | +| 核心状态字段 | `bad_debt_status`：`SUBMITTED/PENDING_APPROVAL/APPROVED/EFFECTIVE/WRITTEN_OFF/REJECTED/CANCELLED` | +| 主要依赖对象 | `AccountingCase`、`Charge`、`Customer` | + +#### 8.3.7 `SplitAdjust` / `SplitAdjustDetail` + +| 项目 | 设计建议 | +|---|---| +| 主表角色 | 分账调整主单，承接分摊或目标账单重分配 | +| 明细表角色 | 记录原账单、目标账单、分摊规则、金额和目标客户 | +| 主表关键字段组 | 单号：`split_adjust_no`；业务：`split_rule_type`、`reason_code`、`remark`；流程字段；统一骨架：`accounting_case_id` | +| 明细表关键字段组 | 原对象：`source_charge_id`；目标对象：`target_charge_id`、`target_cust_id`；金额：`split_amount`；规则：`split_ratio/split_basis`；处理：`proc_type` | +| 主外键关系 | 主表 `id` -> 明细表 `split_adjust_id`；主表 `accounting_case_id` -> `biz_accounting_case.id` | +| 核心状态字段 | `split_status`：`SUBMITTED/PENDING_APPROVAL/APPROVED/PROCESSING/SUCCESS/FAIL` | +| 主要依赖对象 | `AccountingCase`、`Charge`、`Customer` | + +#### 8.3.8 特殊开账 / 特账承接方式（挂接 `Charge` / `ChargeDetail`） + +| 项目 | 设计建议 | +|---|---| +| 承接角色 | 不建议单独建正式主表；优先作为 `Charge` / `ChargeDetail` 的扩展类型承接 | +| 核心语义 | 特账更符合“特殊开账场景下形成的特殊账单/收费类型” | +| 关键字段组 | `source_type = SPECIAL_BILLING`、`fee_type = SPECIAL`、`special_bill_type`、`reason_code`、`remark`、`operator_id` | +| 明细承接 | 通过 `ChargeDetail` 继续承接金额、水量、费用组成、状态差异 | +| 主外键关系 | 不新增独立主外键；挂接在 `biz_charge` / `biz_charge_detail` 上 | +| 核心状态字段 | 继承 `Charge` / `ChargeDetail` 主状态；必要时补特殊来源状态枚举 | +| 主要依赖对象 | `Charge`、`ChargeDetail`、`Customer`、`OperationLog` | + +#### 8.3.9 `RefundBill` + +| 项目 | 设计建议 | +|---|---| +| 主表角色 | 退款形成后的正式账务结果对象 | +| 是否建议独立明细表 | 可后续根据业务量判断，当前可先不单独建 detail | +| 关键字段组 | 单号：`refund_bill_no`；来源：`source_refund_id/source_trade_no/source_charge_id`；金额：`refund_amount`；状态：`refund_bill_status`；结果：`effective_time`、`settlement_flag` | +| 主外键关系 | `accounting_case_id` -> `biz_accounting_case.id`；必要时关联 `PrepaidRefund` 或 `Transaction` | +| 核心状态字段 | `CREATED/EFFECTIVE/CANCELLED/SETTLED` | +| 主要依赖对象 | `AccountingCase`、`Transaction`、`Charge` | + +#### 8.3.10 `CrossCycleWaterRecord` + +| 项目 | 设计建议 | +|---|---| +| 主表角色 | 跨周期水量基础数据对象 / 账单重算支撑对象 | +| 是否建议独立明细表 | 暂可不拆，后续如存在多段分配规则再拆 detail | +| 关键字段组 | 单号：`cross_cycle_water_no`；对象：`cust_id`、`meter_id`、`charge_id`；期间：`source_bill_month`、`target_bill_month`；数量：`water_volume`；原因：`reason_code` | +| 主外键关系 | 可关联 `Charge`、`MeterRead/ReadingData`、必要时关联 `AccountingCase` | +| 核心状态字段 | `CALCULATED/APPLIED/ROLLED_BACK`（表示计算与应用状态，不表示独立审批流状态） | +| 主要依赖对象 | `Charge`、`ChargeDetail`、`ReadingData`、`BillingPeriod`、必要时 `PriceDiffAdjust` / `LadderAccumulate` | + +## 9. 目标表设计骨架 + +### 9.1 L1 核心骨架表 + +| 目标表 | 角色 | 说明 | +|---|---|---| +| `biz_accounting_case` | 主单骨架表 | 统一账务处理主单 | +| `biz_accounting_case_detail` | 明细骨架表 | 统一账务处理明细 | +| `biz_accounting_workflow_ref` | 审批引用表 | 统一审批流引用 | +| `biz_accounting_legacy_mapping` | 历史映射表 | 旧对象映射 | +| `biz_billing_period` | 账务期间表 | 统一账务年月、期间控制 | +| `biz_accounting_proc_type` | 处理方式字典 | 承接旧 `ProcType` 及新枚举扩展 | + +### 9.2 L2 独立业务表 + +| 目标表 | 是否建议明细表 | 对应旧系统表 | +|---|---|---| +| `biz_prepaid_refund` | 是 | `PM_ACCOUNT_RECORDS` | +| `biz_prepaid_refund_detail` | 是 | `PM_ACCOUNT_RECORD_DETAILS` | +| `biz_redink_record` | 是 | `PM_REDINK_ENTRYS` + 关联明细 | +| `biz_redink_record_detail` | 是 | 红冲相关明细 | +| `biz_writtenoff_adjust` | 是 | `PM_PAYMENT_RECORDS` | +| `biz_writtenoff_adjust_detail` | 是 | `PM_PAYMENT_RECORD_DETAILS` | +| `biz_price_diff_adjust` | 是 | `PM_PRICE_RECORDS` | +| `biz_price_diff_adjust_detail` | 是 | `PM_PRICE_RECORD_DETAILS` | +| `biz_latefee_reduce` | 是 | `PM_LATEFEE_RECORDS` | +| `biz_latefee_reduce_detail` | 是 | `PM_LATEFEE_RECORD_DETAILS` | +| `biz_bad_debt_record` | 是 | 账单-呆坏账表族 | +| `biz_bad_debt_record_detail` | 是 | 账单-呆坏账表族 | +| `biz_split_adjust` | 是 | 分账调整汇总 | +| `biz_split_adjust_detail` | 是 | 分账调整明细 | +| 特账 / 特账明细 | 否 | 优先由 `biz_charge` / `biz_charge_detail` + 类型字段承接 | +| `biz_refund_bill` | 视情况 | 退款账 | +| `biz_cross_cycle_water_record` | 视情况 | 跨周期水量 | + +### 9.3 L3 查询投影表/视图 + +| 目标对象 | 建议类型 | 说明 | +|---|---|---| +| `vw_collection_summary` | 视图/物化视图 | 收费汇总、小计、明细 | +| `vw_realtime_collection_batch` | 视图/投影表 | 实时收费汇总 | +| `vw_realtime_collection_log` | 视图/投影表 | 实时收费日志 | +| `vw_payment_check_log` | 视图/投影表 | 对账日志 | +| `vw_difficult_duplicate_bill` | 视图 | 疑难重笔账 | + +## 10. 核心状态机骨架 + +### 10.1 统一账务主单状态 + +建议统一状态： + +```text +DRAFT +-> SUBMITTED +-> PENDING_APPROVAL +-> APPROVED / REJECTED +-> PROCESSING +-> SUCCESS / FAIL / CANCELLED +``` + +### 10.2 业务实体扩展状态 + +独立业务对象可在统一状态之上保留扩展状态，例如： + +- `PrepaidRefund` + - 待审核 + - 待退款 + - 部分退款 + - 退款完成 + - 退款失败 +- `BadDebtRecord` + - 待申请 + - 待审批 + - 已认定 + - 已核销 + - 已撤销 +- `RedinkRecord` + - 已受理 + - 已红冲 + - 红冲失败 + +## 11. 旧系统到新系统的映射策略 + +### 11.1 映射原则 + +1. 旧主键必须保留映射。 +2. 旧汇总表与明细表关系必须可追溯。 +3. 旧单号、旧流程号、旧审批号必须可回查。 +4. 新系统正式业务实体与统一骨架必须同时建立映射。 + +### 11.1A 迁移承接方式枚举 + +本设计冻结以下 4 类迁移承接方式： + +| 承接方式 | 含义 | +|---|---| +| `online-main` | 进入新系统统一核心模型或独立业务实体，参与在线业务处理 | +| `projection-only` | 不做在线主写，仅形成查询投影或聚合对象 | +| `history-readonly` | 只保留历史查询、比对和审计追溯能力 | +| `mapping-only` | 仅保留新旧标识映射，不提供独立在线处理或查询入口 | + +### 11.2 建议映射字段 + +`biz_accounting_legacy_mapping` 至少包含： + +| 字段 | 说明 | +|---|---| +| `legacy_table` | 原表名 | +| `legacy_id` | 原主键 | +| `legacy_parent_id` | 原父级主键 | +| `legacy_no` | 原业务单号 | +| `legacy_task_id` | 原流程任务号 | +| `new_case_id` | 新账务主单 ID | +| `new_case_detail_id` | 新账务明细 ID | +| `new_biz_object_type` | 新业务对象类型 | +| `new_biz_object_id` | 新业务对象 ID | +| `tenant_id` | 租户 | +| `migration_batch_no` | 迁移批次号 | + +### 11.3 旧对象迁移承接矩阵（冻结版） + +| 旧对象 | 目标承接方式 | 新系统承接对象 | 说明 | +|---|---|---|---| +| 营业账 | `online-main` | `Charge` / `AccountingCase` | 继续作为账务处理核心依附对象 | +| 营业账明细 | `online-main` | `ChargeDetail` / `AccountingCaseDetail` | 继续承接费用项级差异 | +| 预存退款 | `online-main` | `PrepaidRefund` + `AccountingCase` | 独立业务实体 + 统一骨架双承接 | +| 预存退款详情 | `online-main` | `PrepaidRefundDetail` + `AccountingCaseDetail` | 保留退款金额、流水与账期差异 | +| 已销调整汇总 | `online-main` | `WrittenoffAdjust` + `AccountingCase` | 独立业务实体承接 | +| 已销调整明细 | `online-main` | `WrittenoffAdjustDetail` + `AccountingCaseDetail` | 保留原/新账单与流水关系 | +| 价差调整汇总 | `online-main` | `PriceDiffAdjust` + `AccountingCase` | 保留调价号与规则边界 | +| 价差调整明细 | `online-main` | `PriceDiffAdjustDetail` + `AccountingCaseDetail` | 保留金额与滞纳金前后差异 | +| 账单-违约金减免汇总 | `online-main` | `LateFeeReduce` + `AccountingCase` | 作为正式业务实体保留 | +| 账单-违约金减免详情 | `online-main` | `LateFeeReduceDetail` + `AccountingCaseDetail` | 保留违约金前后差异与期间 | +| 账单-呆坏账汇总 | `online-main` | `BadDebtRecord` + `AccountingCase` | 保留坏账申请/认定/核销路径 | +| 账单-呆坏账详情 | `online-main` | `BadDebtRecordDetail` + `AccountingCaseDetail` | 保留账龄和状态差异 | +| 红冲表 | `online-main` | `RedinkRecord` + `AccountingCase` | 作为独立高频对象保留 | +| 红冲明细 | `online-main` | `RedinkRecordDetail` + `AccountingCaseDetail` | 记录红冲影响范围与金额 | +| 分账调整汇总 | `online-main` | `SplitAdjust` + `AccountingCase` | 分账规则独立保留 | +| 分账调整明细 | `online-main` | `SplitAdjustDetail` + `AccountingCaseDetail` | 保留分摊目标与金额 | +| 特账 | `online-main` | `Charge` / `ChargeDetail` + 类型字段 | 作为特殊开账产生的特殊账单/收费类型承接 | +| 特账明细 | `online-main` | `ChargeDetail` + 类型字段 | 不单独建主表，保留明细级差异与查询口径 | +| 退款账 | `online-main` | `RefundBill` + `AccountingCase` | 作为结果型正式对象承接 | +| 跨周期水量 | `online-main` | `CrossCycleWaterRecord` | 作为独立基础数据对象保留，不视为独立流程型业务单 | +| 阶梯累计量 | `online-main` 或 `projection-only` | 规则/累计量对象（待细化） | 后续需判断是正式对象还是规则支撑对象 | +| 实时收费汇总表 | `projection-only` | `RealtimeCollectionBatch` | 主要服务查询和对账 | +| 实时收费日志表 | `projection-only` | `RealtimeCollectionLog` | 主要服务渠道日志查询 | +| 实时收费日志明细表 | `projection-only` | `RealtimeCollectionLogDetail` | 主要服务账单级交易查询 | +| 对账日志 | `projection-only` | `PaymentCheckLog` | 保留对账过程查询 | +| 收费汇总 / 收费小计 / 收费明细 | `projection-only` | `CollectionSummaryView` | 通过收费/交易对象聚合形成 | +| 疑难重笔账 | `history-readonly` | `DifficultDuplicateBillView` | 先保留核查与追溯语义 | +| IC 卡账务表族 | `history-readonly`（旧系统已确认存在） | IC 卡兼容查询对象 | 旧系统正式存在；当前固定为历史只读 + 映射层承接 | +| 旧主键 / 单号 / 流程号映射 | `mapping-only` | `AccountingLegacyMapping` | 用于追溯、迁移校验和批次核对 | + +### 11.4 映射记录最小约束 + +每条迁移映射至少应明确： + +1. 原对象名称与原表名 +2. 原主键和原业务键 +3. 当前目标承接方式 +4. 当前目标对象 +5. 是否保留历史只读查询 +6. 是否需要状态映射 +7. 是否需要新旧标识映射 +8. 迁移批次号 +9. 证据来源（Archive / backend / 正式文档 / guides） + +## 12. 查询兼容策略 + +### 12.1 兼容目标 + +为旧业务菜单、历史台账、财务核查和报表导出提供以下兼容能力： + +1. 仍能按旧场景查询： + - 预存退款 + - 已销调整 + - 价差调整 + - 违约金减免 + - 呆坏账 + - 红冲 +2. 仍能按客户、账期、站点、处理方式、状态、审批结果检索。 +3. 仍能按汇总/明细双层视角导出。 + +### 12.2 兼容方式 + +建议采用： + +- 独立业务实体承接在线主写 +- 视图/投影表承接旧查询口径 +- 映射表承接旧主键追溯 + +### 12.3 历史只读边界 + +以下对象当前冻结为“历史只读或兼容查询优先”，不直接作为新系统主写模型： + +| 对象 | 当前边界 | 说明 | +|---|---|---| +| 疑难重笔账 | 历史只读 | 主要服务核查与比对 | +| 对账日志 | 查询投影优先 | 不建议单独作为在线主写业务对象 | +| 实时收费汇总/日志/明细 | 查询投影优先 | 主要服务渠道查询、差异核对和日志追溯 | +| 收费汇总/收费小计/收费明细 | 查询投影优先 | 主要服务统计和柜面核查 | +| IC 卡账务表族 | 历史只读（旧系统已确认存在） | 旧系统已有完整建模；当前固定为历史只读 + 映射层承接 | + +### 12.4 查询兼容出口设计 + +建议对旧系统高频查询口径提供统一查询出口： + +| 查询主题 | 建议出口 | 说明 | +|---|---|---| +| 预存退款查询 | `PrepaidRefund` + 明细查询接口/视图 | 同时支持主单和明细 | +| 已销调整查询 | `WrittenoffAdjust` + 明细查询接口/视图 | 支持原账单与新账单差异定位 | +| 价差调整查询 | `PriceDiffAdjust` + 明细查询接口/视图 | 支持按调价号、账期、客户查询 | +| 违约金减免查询 | `LateFeeReduce` + 明细查询接口/视图 | 支持按减免类型和账期查询 | +| 呆坏账查询 | `BadDebtRecord` + 明细查询接口/视图 | 支持账龄、状态、审批结果查询 | +| 红冲查询 | `RedinkRecord` + 明细查询接口/视图 | 支持原单号、红冲金额、经办人、时间查询 | +| 实时收费与对账查询 | `RealtimeCollection*` / `PaymentCheckLog` | 作为渠道与对账投影出口 | + +### 12.5 查询兼容规则 + +1. 旧查询口径优先通过独立业务实体或查询投影承接，不直接回退为“查旧表”。 +2. 历史只读对象必须至少支持： + - 原单号 + - 客户 + - 账期 + - 状态 + - 金额/水量摘要 + - 经办人 + - 时间 +3. 兼容查询接口不得承担状态变更职责。 +4. 兼容查询结果中必须能追溯到： + - 新对象 ID + - 旧对象标识 + - 迁移批次号（如适用） + +### 12.6 迁移批次设计骨架 + +建议迁移实施仍按以下批次组织： + +| 批次 | 范围 | 目标 | +|---|---|---| +| Batch 1 | 营业账、营业账明细、期间、账户流水主关系 | 锁定主键和核心关系 | +| Batch 2 | 收费结果、交易流水、实时收费与对账日志 | 锁定收费与交易追溯链 | +| Batch 3 | 账务处理主对象：退款、红冲、已销调整、价差调整、违约金减免、坏账、分账、特账 | 锁定全量账务业务承接对象 | +| Batch 4 | 退款账、跨周期水量、阶梯累计量及其他基础或结果对象 | 锁定补充账务基础对象 | +| Batch 5 | 历史只读对象、兼容视图、查询出口与校验报表 | 锁定旧菜单和历史核查口径 | + +### 12.7 接口承接设计原则 + +全量账务对象的接口承接采用以下原则： + +1. **统一入口优先承接共性动作** + 当前统一账务处理入口仍以 `IF-REV-007` 为基础骨架，优先承接共性的提交、校验、结果表达和留痕逻辑。 +2. **强独立业务对象允许拆专属接口族** + 对生命周期、审批、查询入口明显独立的对象，可在后续阶段拆出专属接口，而不是永久挤在 `IF-REV-007` 下。 +3. **查询投影对象只走只读接口** + 汇总、日志、对账、历史只读对象不得承担状态变更职责。 +4. **外部协同继续经既有专题系统承接** + 支付退款、银行对账、发票作废/红冲等，不在账务领域内部重复造一套外部接口体系。 + +### 12.8 接口承接分层矩阵 + +| 对象 | 当前统一承接入口 | 后续建议专属接口 | 查询接口策略 | 外部协同关系 | +|---|---|---|---|---| +| `PrepaidRefund` | `IF-REV-007` 提交退款类场景 | 建议后续拆 `IF-REV-014` 预存退款申请/处理接口 | 独立查询接口或查询视图 | 支付退款结果仍需联动 `bk_transaction*` | +| `RedinkRecord` | 当前可先挂 `IF-REV-007` 修正场景 | 建议后续拆 `IF-REV-015` 红冲处理接口 | 必须独立查询接口 | 与收费、结账、退款链协同 | +| `WrittenoffAdjust` | `IF-REV-007` | 可保留在统一入口内 | 独立查询接口或视图 | 必要时联动原交易和收费结果 | +| `PriceDiffAdjust` | `IF-REV-007` | 建议后续拆 `IF-REV-016` 价差调整接口 | 独立查询接口或视图 | 关联价格体系与账单重算 | +| `LateFeeReduce` | `IF-REV-007` | 视实施复杂度决定是否拆专属接口 | 独立查询接口或视图 | 无强外部协同，主要内部审批/账单联动 | +| `BadDebtRecord` | `IF-REV-007` | 建议后续拆 `IF-REV-017` 坏账申请/认定接口 | 独立查询接口或视图 | 无强外部协同，主要内部审批/核销联动 | +| `SplitAdjust` | `IF-REV-007` 或与账单调整同入口 | 建议后续拆 `IF-REV-018` 分账调整接口 | 独立查询接口或视图 | 主要内部账单分摊，不依赖外部系统 | +| 特账（特殊开账类型） | 不走 `IF-REV-007`；优先挂 `IF-REV-005` / 开账主模型扩展 | 不建议单独拆特账处理接口 | 历史查询与账单查询兼容出口即可 | 与收费、打印、发票链联动 | +| `RefundBill` | 不建议直接提交；由退款处理结果派生 | 可后续拆只读结果接口 | 建议独立查询接口 | 结果对象需联动支付退款结果与账单状态 | +| `CrossCycleWaterRecord` | 不建议作为用户直接提交接口 | 作为账单重算/计费内部对象，不拆前台业务接口 | 仅内部查询或管理查询 | 与账单生成、价差调整、阶梯累计联动 | +| `RealtimeCollectionBatch/Log/Detail` | 不走 `IF-REV-007` | 无需拆账务处理接口 | 只读查询接口 | 与支付、银行、柜台收费链联动 | +| `PaymentCheckLog` | 不走 `IF-REV-007` | 无需拆账务处理接口 | 只读查询接口 | 与银行对账、支付协同接口联动 | +| IC 卡账务表族 | 当前不纳入在线主写接口 | 暂不定义 | 历史只读查询 | 当前仅按历史只读 + 映射层承接 | + +### 12.9 统一入口与专属入口边界 + +#### 继续保留在 `IF-REV-007` 的对象 + +以下对象在当前阶段继续由 `IF-REV-007` 承接更合理： + +- `WrittenoffAdjust` +- `LateFeeReduce` +- `PrepaidRefund`（在未拆专属接口前） +- `BadDebtRecord`（在未拆专属接口前） + +原因： +- 已有正式接口骨架 +- 与当前 `REV-004` 正式主文档一致 +- 有利于先稳定共性输入、结果表达和留痕规则 + +#### 建议后续拆专属接口的对象 + +以下对象更适合后续拆专属接口： + +- `PrepaidRefund` +- `RedinkRecord` +- `PriceDiffAdjust` +- `BadDebtRecord` +- `SplitAdjust` + +原因： +- 生命周期更独立 +- 查询入口更独立 +- 输入输出结构已开始明显偏离统一账务调整接口 + +### 12.10 查询接口口径 + +建议后续统一采用两类查询接口： + +1. **业务对象查询接口** + 面向： + - 预存退款 + - 已销调整 + - 价差调整 + - 违约金减免 + - 呆坏账 + - 红冲 + - 分账调整 + - 退款账 + +2. **历史只读 / 投影查询接口** + 面向： + - 收费汇总/小计/明细 + - 实时收费汇总/日志/明细 + - 对账日志 + - IC 卡账务表族 + - 疑难重笔账 + +### 12.11 与当前正式接口文档的关系 + +当前正式接口文档 `docs/design/03_Technical_Design/03_Interface_Design.md` 的约束仍然成立： + +1. `IF-REV-007` 仍是当前正式账务处理统一入口。 +2. 发票作废/红冲仍由 `REV-005` / `SYS-008` 体系承接，不在本节重复定义税控协同接口。 +3. 支付退款、银行交易、回调、对账仍以 `bk_transaction*`、`SYS-009` 和外部支付/银行接口体系为准。 +4. 本节仅定义**全量账务领域未来的接口承接方向**，不把专属接口直接写成当前已落地事实。 + +### 12.12 审批 / BPM 承接原则 + +全量账务领域的审批 / BPM 承接采用以下原则： + +1. **当前正式口径继续有效** + 当前正式文档中，`IF-REV-007` 仍只保留： + - `approvalRequired` + - `PENDING_APPROVAL` + 等能力位与边界说明。 +2. **全量设计允许引入分层审批承接模型** + 不再把所有对象一概压缩成“只保留能力位”，而是按对象语义区分审批承接方式。 +3. **旧审批流字段优先保留为可追溯字段** + 旧系统中的： + - `TaskId` + - `StepId` + - `FlowRemark` + 先统一承接到审批引用 / 历史追溯对象中。 +4. **不是所有对象都需要独立 BPM** + 强流程型对象可独立审批；基础数据对象和查询投影对象不强接 BPM。 + +### 12.13 审批承接分层矩阵 + +| 对象 | 审批承接方式 | 当前判断 | 说明 | +|---|---|---|---| +| `PrepaidRefund` | 独立审批流对象 | 建议独立审批流 | 旧系统存在申请、查询、作废语义，生命周期独立 | +| `RedinkRecord` | 审批能力位对象 | 当前保留能力位，后续可升级 | 红冲业务强独立，但是否独立 BPM 仍可后续决策 | +| `WrittenoffAdjust` | 审批能力位对象 | 当前保留能力位 | 已销调整可先沿用统一审批边界 | +| `PriceDiffAdjust` | 审批能力位或独立审批流对象 | 倾向审批能力位 + 后续可升级 | 价差调整规则复杂，但不必立即拆完整 BPM | +| `LateFeeReduce` | 审批能力位对象 | 当前保留能力位 | 旧系统有审批语义，先统一承接到能力位 | +| `BadDebtRecord` | 独立审批流对象 | 建议独立审批流 | 坏账申请天然是财务审批对象 | +| `SplitAdjust` | 审批能力位对象 | 当前保留能力位 | 分账规则复杂，但可先保留统一审批位 | +| 特账（特殊开账类型） | 不单独承接审批流 | 由主模型来源类型和留痕承接 | 特账更像特殊开账类型，不单独抽流程 | +| `RefundBill` | 不单独承接审批流 | 结果对象 | 审批由退款申请/处理对象带出 | +| `CrossCycleWaterRecord` | 不单独承接审批流 | 基础数据对象 | 若需审批，由关联业务场景带出，不自行承接 | +| `RealtimeCollection*` | 无审批流 | 查询/投影对象 | 只读对象，不承接流程 | +| `PaymentCheckLog` | 无审批流 | 查询/投影对象 | 只读对象，不承接流程 | +| IC 卡账务表族 | 无在线审批流 | 当前历史只读 + 映射承接 | 不在当前在线承接范围内 | + +### 12.14 统一审批引用对象设计 + +建议统一通过 `AccountingWorkflowRef` 承接审批相关引用，至少保留： + +| 字段 | 说明 | +|---|---| +| `accountingCaseId` | 关联账务主单 | +| `workflowType` | 审批类型 / 流程模板类型 | +| `approvalRequired` | 是否需要审批 | +| `approvalStatus` | `PENDING_APPROVAL`、`APPROVED`、`REJECTED` 等 | +| `legacyTaskId` | 旧 `TaskId` | +| `legacyStepId` | 旧 `StepId` | +| `legacyFlowRemark` | 旧 `FlowRemark` | +| `currentTaskId` | 新流程任务 ID（若后续接入） | +| `currentStepKey` | 新流程节点标识（若后续接入） | +| `approvalComment` | 当前审批意见 | +| `approvedBy` | 审批人 | +| `approvedAt` | 审批时间 | + +### 12.15 审批冻结规则 + +当前冻结以下规则： + +1. 在正式主文档未回写前，不把全量账务领域中的审批模型写成“当前已落地 BPM 事实”。 +2. 当前 guides 底稿允许写： + - 哪些对象需要独立审批流 + - 哪些对象只保留审批能力位 + - 哪些对象仅保留历史审批痕迹 +3. 旧审批流字段必须保留历史追溯能力，不能在迁移设计中直接丢弃。 +4. 后续正式回写时，审批承接需分两个层级写法： + - 当前实现边界 + - 目标设计边界 + +## 13. 与当前正式文档的关系 + +### 13.1 当前已对齐项 + +- `REV-004` 是账务处理域的正式模块编号 +- `IF-REV-007` 是统一账务处理入口 +- `biz_charge*`、`bk_transaction*`、`biz_operat_log*` 是当前正式主文档已经确认的承接对象 + +### 13.2 当前需要后续回写的正式文档 + +后续若该骨架进一步确认，应分批回写： + +1. `docs/design/02_Detailed_Design/12_REV_Detailed.md` +2. `docs/design/03_Technical_Design/01_Database_Design.md` +3. `docs/design/03_Technical_Design/03_Interface_Design.md` +4. `docs/design/01_Overview/03_Summary_Design.md` + +### 13.3 正式回写冻结门禁 + +任一正式主文档启动回写前，至少同时满足以下冻结门禁： + +1. **术语冻结**：账务主对象、审批术语、迁移术语、查询兼容术语已在本底稿中统一，不再存在同义并列写法。 +2. **对象清单冻结**：本批次涉及的业务对象、历史对象、投影对象已明确归层，不存在“是否保留/是否独立”的悬置项。 +3. **关系图冻结**：本批次涉及对象与 `Charge`、`ChargeDetail`、`Transaction`、`AccountingWorkflowRef`、`AccountingLegacyMapping` 的关系已稳定。 +4. **回写范围冻结**：明确本批次只改哪些正式文档、哪些章节、哪些表格、哪些图，不跨批次扩散。 +5. **现状/目标边界冻结**：已明确哪些内容属于“当前正式事实”，哪些内容属于“目标设计口径”，避免把 guides 目标态直接写成现状。 +6. **校验清单冻结**：已明确本批次最小校验动作、校验顺序、台账更新条件。 + +若任一门禁未满足，则允许继续在 `docs/guides/REV004_FULL_ACCOUNTING_DOMAIN_DESIGN.md` 底稿迭代，但不得直接改正式主文档。 + +### 13.4 正式回写批次与顺序 + +建议正式回写严格按以下顺序推进： + +| 批次号 | 目标文档 | 回写重点 | 启动前冻结重点 | 最小校验动作 | +|---|---|---|---|---| +| `RWB-01` | `docs/design/02_Detailed_Design/12_REV_Detailed.md` | 对象边界、场景职责、审批边界、关系骨架 | 对象清单、关系图、状态机 | `make validate-file FILE=docs/design/02_Detailed_Design/12_REV_Detailed.md` | +| `RWB-02` | `docs/design/03_Technical_Design/01_Database_Design.md` | 主表/明细表、索引关注点、历史映射字段、查询投影结构 | 实体字段骨架、表关系、迁移承接方式 | `make validate-file FILE=docs/design/03_Technical_Design/01_Database_Design.md` | +| `RWB-03` | `docs/design/03_Technical_Design/03_Interface_Design.md` | 统一入口 / 专属入口 / 查询接口口径 | 接口承接矩阵、查询出口、现状/目标边界 | `make validate-file FILE=docs/design/03_Technical_Design/03_Interface_Design.md` | +| `RWB-04` | `docs/design/01_Overview/03_Summary_Design.md` | 领域摘要、模块职责、总体口径收敛 | 前三批回写已稳定 | `make validate-file FILE=docs/design/01_Overview/03_Summary_Design.md` | + +冻结顺序必须遵守： + +- 先详设，再数据库，再接口，再总体摘要 +- 上一批未完成校验和基线登记前，不启动下一批 +- 总体摘要只做收敛摘要，不反向引入尚未在详设/数据库/接口文档落地的新事实 + +### 13.5 Archive 快照清单与命名规则 + +正式回写前必须先做 Archive 快照，且快照只用于留档，不作为并行真源。每批至少登记以下信息： + +| 字段 | 说明 | +|---|---| +| `batchNo` | 回写批次号，如 `RWB-01` | +| `sourceFile` | 被回写的正式文档原路径 | +| `snapshotDate` | 快照日期，格式 `YYYY-MM-DD` | +| `sourceCommit` | 回写前 docs 仓基线 commit | +| `snapshotArchivePath` | 快照归档路径 | +| `scopeSummary` | 本批次回写范围摘要 | +| `validatedBy` | 执行校验的责任人/执行方式 | +| `validationResult` | 校验结果摘要 | + +快照命名建议采用： + +`--.md` + +例如： + +- `2026-04-03-RWB-01-12_REV_Detailed.md` +- `2026-04-03-RWB-02-01_Database_Design.md` + +冻结规则： + +1. 快照放入 `Archive/` 下按批次建立的快照目录，不在正式目录旁生成 `*_old.md`、`*_bak.md`、`*_v1.md`。 +2. 同一正式文档若二次回写，必须重新生成新快照，不覆盖旧快照。 +3. 快照记录必须能反查到回写前基线 commit 和对应 guides 章节。 + +### 13.6 基线记录规则 + +每批正式回写必须固定基线，至少包括： + +1. **docs 仓基线**：当前 `water-docs` commit SHA。 +2. **关联实现基线**：若本批次引用了 backend / frontend 已落地实现口径，则同步记录： + - `../water-backend/` commit SHA + - `../water-frontend/` commit SHA +3. **验证日期**：本批次完成校验的日期。 +4. **证据入口**：本批次所引用的 spec / guide / Archive 证据清单。 + +基线记录原则： + +- guides 底稿迭代阶段可以不写入 `Project_Progress`； +- 只有当正式回写批次完成冻结、完成快照、完成最小校验后，才在 `docs/design/00_Management/01_Project_Progress.md` 记正式里程碑； +- 若回写过程中发现对象边界再次变化，应回退到 guides 底稿继续收敛，而不是直接在正式文档中边改边定。 + +### 13.7 单批回写执行模板 + +建议每次正式回写都按以下模板执行： + +1. 确认本批次 `batchNo`、目标文档、回写范围。 +2. 检查 13.3 冻结门禁是否全部满足。 +3. 记录 docs / backend / frontend 基线 commit（若适用）。 +4. 生成 Archive 快照并登记快照路径。 +5. 根据 guides 底稿定向回写正式文档，不跨批次顺手扩写。 +6. 按既定顺序执行最小校验： + - 目标正式文档 `make validate-file` + - `docs/guides/REV004_FULL_ACCOUNTING_DOMAIN_DESIGN.md` 复核 + - 若涉及跨文档锚点/引用变更，再补充 `make check-links` 或小范围链接检查 +7. 校验通过后，更新 `Project_Progress` 里程碑或相应治理台账。 +8. 在批次总结中记录：变更摘要、剩余未回写项、下一批前置条件。 + +### 13.8 `RWB-01` 回写准备：`12_REV_Detailed.md` 范围拆解 + +`RWB-01` 当前只做**详设层回写准备**，目标是先把 `docs/design/02_Detailed_Design/12_REV_Detailed.md` 中 `REV-004 账务处理` 章节的回写范围拆清楚，不在本步骤直接改正式详设正文。 + +#### 13.8.1 本批次锁定的目标章节 + +`RWB-01` 只允许触达 `12_REV_Detailed.md` 中以下小节： + +| 目标章节 | 当前状态 | `RWB-01` 准备动作 | +|---|---|---| +| `## REV-004 账务处理` | 一期最小闭环口径 | 保持模块编号不变，仅准备章节内容扩展方案 | +| `### 功能说明` | 仅覆盖五类一期场景 | 准备扩展为“当前正式边界 + 全量目标对象边界”双层写法 | +| `### 业务流程` | 当前为统一流程图 | 评估是否保留统一流程图并增加分层说明，当前不拆多张场景流程图 | +| `### 关键规则` | 一期规则为主 | 准备补充全量对象承接、审批边界、查询兼容边界 | +| `### 核心数据` | 以 `biz_charge*` / `bk_transaction*` / `biz_operat_log*` 为主 | 准备补充正式业务实体骨架、审批引用、历史映射承接 | +| `### 主要场景` | 仅五类场景 | 准备扩展为全量账务正式场景清单 | +| `### 迁移补充（旧系统承接）` | 旧对象承接矩阵较粗 | 准备替换为更完整的分层承接口径 | +| `### 接口映射` | 维持 `IF-REV-007` / `IF-REV-006` | 准备补充“当前统一入口 + 后续专属入口趋势”说明 | +| `### 落地边界` | 一期实现边界 | 准备改为“当前已落地 / 部分落地 / 目标设计”三层边界 | + +#### 13.8.2 本批次明确纳入范围 + +`RWB-01` 进入正式回写时，准备纳入以下内容： + +1. **对象边界改写**：将 `REV-004` 从“一期五类场景”改写为“当前正式边界仍以统一处理为主、目标设计覆盖全量账务对象”。 +2. **场景清单扩写**：把以下对象纳入详设层正式场景说明： + - `PrepaidRefund` + - `RedinkRecord` + - `WrittenoffAdjust` + - `PriceDiffAdjust` + - `LateFeeReduce` + - `BadDebtRecord` + - `SplitAdjust` + - 特殊开账 / 特账承接方式 + - `RefundBill` + - `CrossCycleWaterRecord` +3. **审批边界写法收敛**：把“审批能力位”和“独立审批流对象”的区分补入详设，但仍不把目标 BPM 写成当前已实现事实。 +4. **迁移承接写法收敛**：把旧对象归层（`L1/L2/L3/L4`）和承接方式（在线主模型 / projection-only / history-readonly / mapping-only）翻译成详设可读语言。 +5. **现状/目标双层表达**：每个关键小节都要同时说明： + - 当前正式实现边界 + - 目标全量设计边界 + +#### 13.8.3 本批次明确排除范围 + +`RWB-01` 不纳入以下动作： + +1. 不修改 `REV-001`、`REV-002`、`REV-003`、`REV-005`、`REV-008` 等其他模块章节。 +2. 不在 `12_REV_Detailed.md` 中直接展开数据库字段级设计；字段级细化留给 `RWB-02`。 +3. 不在本批次新增正式接口编号、接口协议细节、入参出参结构；接口细化留给 `RWB-03`。 +4. 不把目标独立业务实体直接宣称为 backend 已落地物理表。 +5. 不展开完整 BPM 节点流转、审批表结构、流程引擎实现细节。 + +#### 13.8.4 guides 到 `12_REV_Detailed.md` 的回写映射 + +| guides 来源章节 | `12_REV_Detailed.md` 目标小节 | 回写目标 | +|---|---|---| +| `8.1`、`8.2`、`8.3` | `### 功能说明`、`### 主要场景`、`### 核心数据` | 把正式业务实体清单翻译成详设层业务边界与对象说明 | +| `10.1`、`10.2` | `### 关键规则` | 把统一状态机和扩展状态翻译成详设规则表述 | +| `11.1A`、`11.3`、`12.6` | `### 迁移补充（旧系统承接）` | 把迁移承接矩阵翻译成旧系统对象承接说明 | +| `12.7` ～ `12.11` | `### 接口映射`、`### 落地边界` | 保留当前统一入口事实，并增加未来接口拆分趋势说明 | +| `12.12` ～ `12.15` | `### 功能说明`、`### 关键规则`、`### 落地边界` | 明确审批能力位 / 独立审批流 / 历史痕迹三类边界 | +| `13.3` ～ `13.7` | `RWB-01` 执行准备，不直接写入详设正文 | 用于约束批次执行，不直接转抄到正式文档 | + +#### 13.8.5 `RWB-01` 正式改写前的最小准备清单 + +在真正开始改 `12_REV_Detailed.md` 前，至少先完成以下准备： + +1. 为 `REV-004` 章节生成本批次 Archive 快照。 +2. 固定本次回写基线 commit。 +3. 先起草 `REV-004` 小节的新旧对照提纲： + - 保留段 + - 改写段 + - 新增段 + - 暂缓段 +4. 明确当前章节中哪些表述必须保留“一期已落地”措辞，哪些内容可以新增“目标设计”措辞。 +5. 完成后只执行 `12_REV_Detailed.md` 单文件校验，不顺带修改其他正式主文档。 + +#### 13.8.6 `RWB-01` 回写后的验收点 + +`RWB-01` 真正落地时，应至少满足以下验收点： + +1. `REV-004` 章节不再只停留在一期五类场景。 +2. 全量账务核心对象已在详设层可见，但未越级写入字段级数据库设计。 +3. 当前实现边界与目标设计边界可以明确区分。 +4. `IF-REV-007` 当前统一入口事实仍保留，没有被误写成“已完全拆专属接口”。 +5. 审批/BPM 仍保持保守写法，没有把未来流程设计误写成当前事实。 + +#### 13.8.7 `REV-004` 小节新旧对照提纲 + +为后续正式改写 `12_REV_Detailed.md`，当前先冻结以下“保留 / 改写 / 新增 / 暂缓”提纲： + +##### 一、保留段 + +以下内容应保留，但允许做措辞收敛： + +| 当前小节 | 保留原因 | 保留方式 | +|---|---|---| +| `## REV-004 账务处理` 标题与模块编号 | 已是正式模块编号，不应改动 | 原位保留 | +| `### 业务流程` 的统一处理主线 | 统一申请、校验、执行、回写、留痕主线仍成立 | 保留现有统一流程图，再补充“适用于全量对象统一处理主线”的文字说明 | +| `### 关键规则` 中“以账单/交易/日志为统一承接骨架” | 属于当前正式口径核心 | 保留并扩展，不推翻 | +| `### 接口映射` 中 `IF-REV-007`、`IF-REV-006` 的当前事实 | 当前正式接口事实已成立 | 原事实保留，再增加目标趋势说明 | +| `### 落地边界` 中“已落地 / 部分落地 / 文档先行”的写法方向 | 适合承接现状/目标双层表达 | 保留三层写法，但重写对象内容 | + +##### 二、改写段 + +以下内容应整体改写，不再沿用现有一期限定表述： + +| 当前小节 | 当前问题 | 改写方向 | +|---|---|---| +| `### 功能说明` | 只描述一期五类场景，范围过窄 | 改为“当前正式统一处理边界 + 全量目标对象边界”双层说明 | +| `### 关键规则` 第 1 条 | 明确限定一期五类场景 | 改为“当前以统一处理入口承接，目标覆盖全量账务对象” | +| `### 关键规则` 第 6 条 | 将特账、跨周期水量、退款账统一按“未见独立表”处理，口径过粗 | 改为按对象分别说明：特账挂主开账模型、跨周期水量为基础数据对象、退款账为结果对象 | +| `### 核心数据` | 只列出骨架表，缺少正式业务实体层 | 改为“统一骨架 + 独立业务实体 + 审批引用 + 历史映射”四层表述 | +| `### 主要场景` | 仅五类场景，无法承接全量账务 | 改写为全量正式场景矩阵 | +| `### 迁移补充（旧系统承接）` | 仅列少量对象且承接粒度粗 | 改写为按对象分层承接与迁移方式说明 | + +##### 三、新增段 + +以下内容建议在现有小节内部新增，不额外新增新的顶级章节： + +| 归属小节 | 建议新增内容 | 目的 | +|---|---|---| +| `### 功能说明` | “当前正式边界 / 目标设计边界”双段说明 | 避免把目标态误写成现状 | +| `### 关键规则` | 审批承接分层规则 | 把审批能力位 / 独立审批流 / 历史痕迹区分清楚 | +| `### 核心数据` | `AccountingWorkflowRef`、`AccountingLegacyMapping` | 把审批引用和历史映射纳入详设语义层 | +| `### 主要场景` | 全量对象清单表 | 让 `REV-004` 可见完整账务对象族 | +| `### 迁移补充（旧系统承接）` | `L1/L2/L3/L4` 分层说明 + 承接方式枚举 | 和 guides 的迁移策略对齐 | +| `### 接口映射` | “继续保留统一入口”与“后续专属接口趋势”双段说明 | 为 `RWB-03` 接口回写留接口 | +| `### 落地边界` | “当前已落地 / 部分落地 / 目标设计”三段清单 | 保留保守口径并表达目标态 | + +##### 四、暂缓段 + +以下内容当前明确暂缓到后续批次，不在 `RWB-01` 写入正式详设： + +| 暂缓主题 | 暂缓原因 | 预计批次 | +|---|---|---| +| 主表/明细表字段级设计 | 属于数据库设计层，不属于详设层首批回写 | `RWB-02` | +| 独立接口编号、接口协议、报文结构 | 属于接口设计层 | `RWB-03` | +| BPM 节点流转、审批表结构、引擎实现 | 当前只冻结承接边界，不展开实现 | 后续 BPM 专题 / 非 `RWB-01` | +| IC 卡账务在线承接设计 | 当前已冻结为历史只读 + 映射层 | 暂不进入正式在线详设 | +| 报表口径与查询视图细节 | 属于查询/数据库联合专题 | `RWB-02` 或后续专题 | + +##### 五、正式改写时的段落重组建议 + +`REV-004` 正式改写时，建议采用以下段落重组顺序： + +1. `### 功能说明`：先写当前正式边界，再写目标全量边界。 +2. `### 业务流程`：保留统一流程图，补充“适配全量对象”的说明。 +3. `### 关键规则`：按统一骨架、交易校验、结果表达、审批边界、对象承接边界重排。 +4. `### 核心数据`：从“骨架对象”扩展到“骨架 + 独立业务实体 + 审批引用 + 映射对象”。 +5. `### 主要场景`：改成正式业务对象矩阵。 +6. `### 迁移补充（旧系统承接）`：改成旧对象分层承接矩阵。 +7. `### 接口映射`：保留当前统一入口事实，并提示后续接口拆分方向。 +8. `### 落地边界`：明确当前已落地、部分落地、目标设计三层。 + +### 13.9 `RWB-02` 回写准备：`01_Database_Design.md` 范围拆解 + +`RWB-02` 当前只做**数据库专项回写准备**，目标是先把 `docs/design/03_Technical_Design/01_Database_Design.md` 中与账务领域相关的回写范围拆清楚，不在本步骤直接改正式数据库正文。 + +#### 13.9.1 本批次锁定的目标章节 + +`RWB-02` 只允许优先触达 `01_Database_Design.md` 中以下章节： + +| 目标章节 | 当前状态 | `RWB-02` 准备动作 | +|---|---|---| +| `## SYS-002 开账、收费与票据表` | 已形成 `biz_charge*` / `biz_invoice*` / `biz_operat_log*` 统一口径 | 准备扩展为“统一骨架 + 独立业务实体 + 历史映射/查询投影”双层数据库口径 | +| `### biz_charge (营业账主表)` | 当前偏开账/账单主结果对象 | 准备补充其作为全量账务统一骨架主表的承接边界 | +| `### biz_charge_detail (营业账明细表)` | 当前偏开账明细表达 | 准备补充其对特账、价差、违约金等费用差异承接边界 | +| `### biz_operat_log / biz_operat_log_detail` | 当前为一期留痕口径 | 准备升级为全量账务留痕主承接对象说明 | +| `### 旧系统历史台账迁移与只读查询口径` | 当前已区分在线保留 / 历史只读 | 准备补全 `L2/L3/L4` 分层和承接方式枚举 | +| `### 业务表索引` | 当前以现有骨架表索引为主 | 准备补充全量账务查询与映射字段索引关注点 | +| `### 历史数据分区策略` / `### 数据归档策略` | 当前偏通用策略 | 准备补充账务历史映射和查询投影的归档边界说明 | + +#### 13.9.2 本批次明确纳入范围 + +`RWB-02` 进入正式回写时，准备纳入以下内容： + +1. **统一骨架增强**：明确 `biz_charge`、`biz_charge_detail` 不仅承接开账结果，也作为全量账务统一骨架主表/明细表。 +2. **正式业务实体承接矩阵**：把 `PrepaidRefund`、`RedinkRecord`、`WrittenoffAdjust`、`PriceDiffAdjust`、`LateFeeReduce`、`BadDebtRecord`、`SplitAdjust`、特殊开账 / 特账、`RefundBill`、`CrossCycleWaterRecord` 映射到数据库专项的承接方式。 +3. **审批引用 / 历史映射承接**：为 `AccountingWorkflowRef`、`AccountingLegacyMapping` 增加数据库专项承接口径，至少落到“目标对象 / 待补字段 / 历史映射字段”层。 +4. **历史只读 / 查询投影收敛**：把实时收费、对账日志、IC 卡账务等对象按 `projection-only`、`history-readonly`、`mapping-only` 分类写清。 +5. **索引与查询关注点**：补充按账务主单、原单据、审批状态、旧单据映射、账单结果查询的索引关注点，但不在本批次展开完整 DDL。 + +#### 13.9.3 本批次明确排除范围 + +`RWB-02` 不纳入以下动作： + +1. 不在正式数据库文档中直接新增完整建表 SQL、DDL 草案或迁移脚本。 +2. 不为所有目标业务对象立刻宣称“已存在独立物理表”；可采用“目标对象 / 待补字段 / 历史只读”写法。 +3. 不展开接口协议、接口编号、请求响应结构；该部分留给 `RWB-03`。 +4. 不展开 BPM 引擎表结构、流程节点表、审批流引擎实现。 +5. 不修改无关专题（如移动端、METER/INST 专题）现有章节。 + +#### 13.9.4 guides 到 `01_Database_Design.md` 的回写映射 + +| guides 来源章节 | `01_Database_Design.md` 目标小节 | 回写目标 | +|---|---|---| +| `8.1`、`8.2`、`8.3` | `### biz_charge`、`### biz_charge_detail`、`### 旧系统历史台账迁移与只读查询口径` | 把正式业务实体清单翻译成数据库专项承接矩阵 | +| `9.1`、`9.2`、`9.3` | `### biz_charge`、`### biz_charge_detail`、历史只读/投影章节 | 把目标表设计骨架翻译成主表/明细表/投影/映射数据库说明 | +| `10.1`、`10.2` | `### biz_charge`、`### biz_operat_log*` 说明段 | 把状态机要求转化为状态字段、结果字段、审批字段关注点 | +| `11.1A`、`11.3`、`12.1`～`12.6` | `### 旧系统历史台账迁移与只读查询口径` | 对齐迁移承接方式、查询兼容出口和批次设计骨架 | +| `12.12`～`12.15` | `### biz_operat_log*`、目标审批引用对象说明 | 补审批引用对象的数据库承接边界 | +| `13.3`～`13.7` | `RWB-02` 执行准备，不直接写入数据库正文 | 用于约束回写顺序、快照、基线与验证 | + +#### 13.9.5 `RWB-02` 正式改写前的最小准备清单 + +在真正开始改 `01_Database_Design.md` 前，至少先完成以下准备： + +1. 为 `01_Database_Design.md` 生成本批次 Archive 快照。 +2. 固定本次回写基线 commit。 +3. 起草数据库专项的新旧对照提纲： + - 保留段 + - 改写段 + - 新增段 + - 暂缓段 +4. 明确哪些内容只能写成“目标承接口径 / 待补字段”，不能写成“已存在真实表结构”。 +5. 完成后只执行 `01_Database_Design.md` 单文件校验，不顺带改接口设计和总体设计。 + +#### 13.9.6 `RWB-02` 回写后的验收点 + +`RWB-02` 真正落地时，应至少满足以下验收点： + +1. 数据库专项不再只停留在“一期 REV-004 不新增独立细表”的被动描述。 +2. 全量账务对象已在数据库专项中有明确承接方式：在线骨架、目标对象、查询投影或历史映射。 +3. `biz_charge`、`biz_charge_detail`、`biz_operat_log*` 的账务承接边界得到加强，但未误写为所有对象都已物理落表。 +4. `AccountingWorkflowRef`、`AccountingLegacyMapping` 至少在数据库专项中被正式命名并建立承接边界。 +5. 历史只读、查询投影、IC 卡账务等对象的数据库边界表达清楚，不与在线主写口径混淆。 + +#### 13.9.7 `01_Database_Design.md` 新旧对照提纲 + +为后续正式改写 `01_Database_Design.md`，当前先冻结以下“保留 / 改写 / 新增 / 暂缓”提纲： + +##### 一、保留段 + +以下内容应保留，但允许做措辞收敛： + +| 当前小节 | 保留原因 | 保留方式 | +|---|---|---| +| `## SYS-002 开账、收费与票据表` | 已是正式数据库专题入口 | 原位保留，扩展其账务领域职责 | +| `### biz_charge`、`### biz_charge_detail` 现有真实表说明 | 已与当前 backend / 正式文档对齐 | 保留真实表事实，再增加目标承接口径 | +| `### biz_operat_log / biz_operat_log_detail` 留痕口径 | 仍是当前正式留痕主入口 | 保留并扩展为全量账务留痕骨架 | +| `### 旧系统历史台账迁移与只读查询口径` 的章节位置 | 已经是迁移承接的正式入口 | 原位保留，改写内部矩阵和边界 | +| `### 业务表索引` 中现有索引写法 | 已反映当前真实表事实 | 保留现状索引，再补充目标关注点 | + +##### 二、改写段 + +以下内容应整体改写或增强： + +| 当前小节 | 当前问题 | 改写方向 | +|---|---|---| +| `> REV-004 承接口径` | 仍停留在“一期不新增独立细表” | 改为“当前统一骨架 + 全量目标对象承接矩阵” | +| `### biz_charge` / `### biz_charge_detail` 的说明 | 偏开账/账单生成语义 | 增强为全量账务统一骨架语义 | +| `### biz_operat_log*` 边界说明 | 仅覆盖一期留痕 | 改为覆盖全量账务操作留痕、审批留痕、原单据关联 | +| `### 旧系统历史台账迁移与只读查询口径` | 对象粒度仍较粗 | 改为按对象 + 分层 + 承接方式说明 | +| `### 业务表索引` | 缺少旧单据映射、审批状态、结果对象查询关注点 | 增补索引关注点说明 | + +##### 三、新增段 + +以下内容建议在现有章节中新增，不单独新增新的数据库专题大章： + +| 归属小节 | 建议新增内容 | 目的 | +|---|---|---| +| `### biz_charge` / `### biz_charge_detail` | 目标承接字段组说明 | 对齐主表/明细表如何承接全量账务对象 | +| `### biz_operat_log*` | 全量账务留痕字段关注点 | 明确处理类型、原交易引用、审批痕迹、附件依据 | +| 迁移与只读查询章节 | `AccountingLegacyMapping` | 正式命名历史映射承接对象 | +| 迁移与只读查询章节 | `AccountingWorkflowRef` 的数据库关注点 | 为审批引用对象留数据库专题锚点 | +| 索引与归档章节 | 账务查询投影 / 历史映射索引和归档关注点 | 让后续 DDL 与报表承接有明确方向 | + +##### 四、暂缓段 + +以下内容当前明确暂缓到后续批次或实现阶段，不在 `RWB-02` 写入正式数据库文档： + +| 暂缓主题 | 暂缓原因 | 预计批次 | +|---|---|---| +| 完整独立实体表 DDL | 当前只冻结承接边界和待补字段，不直接下沉为实现脚本 | 后续实现 / 专项 DDL | +| 专属接口入参出参与表字段一一映射 | 属于接口专题 | `RWB-03` | +| BPM 引擎表 / 节点表 / 流转表 | 当前不展开完整审批实现 | 后续 BPM 专题 | +| IC 卡账务在线主写表设计 | 当前冻结为历史只读 + 映射层 | 暂不进入在线数据库设计 | +| 报表视图最终字段清单 | 需要结合统计/查询专题再收敛 | `RWB-04` 或后续专题 | + +##### 五、正式改写时的段落重组建议 + +`01_Database_Design.md` 正式改写时，建议采用以下重组顺序： + +1. 先保留 `SYS-002 开账、收费与票据表` 的现状真实表事实。 +2. 在 `biz_charge` / `biz_charge_detail` 下补充“统一骨架承接边界”。 +3. 在 `biz_operat_log*` 下补充“全量账务留痕和审批痕迹关注点”。 +4. 重写“旧系统历史台账迁移与只读查询口径”为对象分层矩阵。 +5. 在索引、归档、历史数据策略处补充账务映射和查询投影关注点。 + +### 13.10 `RWB-03` 回写准备：`03_Interface_Design.md` 范围拆解 + +`RWB-03` 当前只做**接口专项回写准备**，目标是先把 `docs/design/03_Technical_Design/03_Interface_Design.md` 中与账务领域相关的回写范围拆清楚，不在本步骤直接改正式接口正文。 + +#### 13.10.1 本批次锁定的目标章节 + +`RWB-03` 只允许优先触达 `03_Interface_Design.md` 中以下章节： + +| 目标章节 | 当前状态 | `RWB-03` 准备动作 | +|---|---|---| +| `### IF-REV-007 账务调整接口` | 当前仍是一期五类场景统一入口 | 准备扩展为“当前统一入口事实 + 全量对象承接边界”双层接口写法 | +| `### IF-REV-007 请求/响应参数` | 当前参数偏一期通用处理 | 准备补充全量对象通用字段、审批边界字段、结果对象区分字段 | +| `## 历史查询与迁移校验接口口径` | 当前已形成历史查询原则 | 准备补充全量账务对象查询出口、历史只读 / 投影查询口径 | +| `## 数据对象与表口径` | 当前偏现有骨架表 | 准备补充目标对象、审批引用对象、历史映射对象的接口层命名边界 | +| `## 实现状态说明` | 当前已落地 / 部分落地 / 文档先行 | 准备同步收敛“当前统一入口已落地、专属接口为后续目标” | +| `### IF-CS-002 历史账单查询接口`（必要时） | 当前偏账单/费用历史查询 | 仅在需要时补充与全量账务历史查询的边界关系，不改其主职责 | + +#### 13.10.2 本批次明确纳入范围 + +`RWB-03` 进入正式回写时，准备纳入以下内容： + +1. **统一入口边界增强**：保留 `IF-REV-007` 当前正式统一入口事实，同时明确其当前承接全量账务对象的统一入口地位。 +2. **对象承接矩阵接口化**：把 `PrepaidRefund`、`RedinkRecord`、`WrittenoffAdjust`、`PriceDiffAdjust`、`LateFeeReduce`、`BadDebtRecord`、`SplitAdjust`、特殊开账 / 特账、`RefundBill`、`CrossCycleWaterRecord` 映射到接口承接方式。 +3. **当前统一入口 / 后续专属接口双层写法**：数据库和详设已经回写的对象，在接口文档中要明确： + - 当前是否继续挂 `IF-REV-007` + - 后续是否建议拆专属接口 +4. **查询接口分层**：把“业务对象查询接口”和“历史只读 / 投影查询接口”分层口径正式写入接口专项。 +5. **审批能力位边界**：把 `approvalRequired`、`approvalStatus`、审批引用语义纳入接口边界，但不展开 BPM 流程实现。 + +#### 13.10.3 本批次明确排除范围 + +`RWB-03` 不纳入以下动作： + +1. 不直接新增一整套新的正式接口编号族，除非文档明确写成“后续建议编号 / 后续拆分方向”。 +2. 不展开完整 BPM API、审批节点流转 API、流程引擎接口。 +3. 不展开数据库字段级设计；该部分已由 `RWB-02` 承接。 +4. 不修改与账务无关的 `CS`、`METER`、`INST` 主接口章节。 +5. 不把目标专属接口误写成当前 backend 已完整提供的既成事实。 + +#### 13.10.4 guides 到 `03_Interface_Design.md` 的回写映射 + +| guides 来源章节 | `03_Interface_Design.md` 目标小节 | 回写目标 | +|---|---|---| +| `8.1`、`8.2`、`8.3` | `### IF-REV-007`、`## 数据对象与表口径` | 把正式业务实体清单翻译成接口承接边界 | +| `10.1`、`10.2` | `### IF-REV-007 响应参数`、状态约束说明 | 把统一状态机与扩展状态翻译成接口结果状态语义 | +| `12.7`～`12.11` | `### IF-REV-007`、历史查询章节、实现状态说明 | 对齐统一入口、专属入口趋势和查询接口分层 | +| `12.12`～`12.15` | `### IF-REV-007 请求/响应参数`、约束说明 | 对齐审批能力位、审批状态与接口边界 | +| `13.3`～`13.7` | `RWB-03` 执行准备，不直接写入接口正文 | 用于约束快照、基线、验证和回写顺序 | + +#### 13.10.5 `RWB-03` 正式改写前的最小准备清单 + +在真正开始改 `03_Interface_Design.md` 前，至少先完成以下准备： + +1. 为 `03_Interface_Design.md` 生成本批次 Archive 快照。 +2. 固定本次回写基线 commit。 +3. 起草接口专项的新旧对照提纲： + - 保留段 + - 改写段 + - 新增段 + - 暂缓段 +4. 明确哪些内容可以写成“当前统一入口事实”，哪些内容只能写成“后续专属接口方向”。 +5. 完成后只执行 `03_Interface_Design.md` 单文件校验，不顺带改总体设计。 + +#### 13.10.6 `RWB-03` 回写后的验收点 + +`RWB-03` 真正落地时，应至少满足以下验收点： + +1. `IF-REV-007` 不再只对应一期五类场景，而是能表达全量账务对象的统一入口边界。 +2. 当前统一入口事实与后续专属接口方向可以清楚区分。 +3. 历史查询与迁移校验接口口径已能覆盖全量账务对象的查询出口。 +4. 审批能力位、审批状态和结果状态语义已在接口文档中形成统一口径。 +5. 未把目标专属接口误写成当前 backend 已完整落地能力。 + +#### 13.10.7 `03_Interface_Design.md` 新旧对照提纲 + +为后续正式改写 `03_Interface_Design.md`，当前先冻结以下“保留 / 改写 / 新增 / 暂缓”提纲： + +##### 一、保留段 + +以下内容应保留，但允许做措辞收敛： + +| 当前小节 | 保留原因 | 保留方式 | +|---|---|---| +| `### IF-REV-007 账务调整接口` 的接口编号 | 已是当前正式接口编号 | 原位保留，不随意改号 | +| `IF-REV-007` 当前统一入口事实 | 已与详设/数据库正式文档对齐 | 保留事实，再扩展对象边界 | +| `## 历史查询与迁移校验接口口径` 章节位置 | 已是查询承接的正式入口 | 原位保留，增强全量账务查询出口 | +| `## 实现状态说明` 中“已落地 / 部分落地 / 文档先行”结构 | 适合承接现状/目标分层表达 | 保留结构，重写账务对象内容 | + +##### 二、改写段 + +以下内容应整体改写或增强： + +| 当前小节 | 当前问题 | 改写方向 | +|---|---|---| +| `### IF-REV-007 账务调整接口` 功能描述 | 仍限定在一期五类场景 | 改为“当前统一入口 + 全量账务对象承接边界” | +| `### IF-REV-007` 请求/响应参数 | 参数仍偏一期通用处理 | 增强为支持对象类型、审批边界、结果状态表达 | +| `## 数据对象与表口径` | 对目标对象、审批引用、映射对象命名不足 | 增补全量对象接口层命名边界 | +| `## 历史查询与迁移校验接口口径` | 还未显式覆盖全量账务对象查询分层 | 增强为业务对象查询 + 历史只读 / 投影查询双层口径 | +| `## 实现状态说明` | 尚未体现统一入口与专属接口的双层状态 | 改为“当前统一入口已落地 / 专属接口为后续方向” | + +##### 三、新增段 + +以下内容建议在现有章节中新增，不单独新开一套正式接口大章： + +| 归属小节 | 建议新增内容 | 目的 | +|---|---|---| +| `### IF-REV-007` | 对象承接矩阵 | 明确哪些对象当前挂统一入口 | +| `### IF-REV-007 请求/响应参数` | `objectType`、`approvalStatus`、`resultStatus` 等语义说明 | 强化全量对象的统一表达能力 | +| 历史查询章节 | 全量账务对象查询出口分层表 | 明确业务对象查询与历史只读查询的边界 | +| 实现状态章节 | “后续专属接口方向”说明 | 为后续接口拆分留正式口径 | + +##### 四、暂缓段 + +以下内容当前明确暂缓到后续批次或实现阶段，不在 `RWB-03` 写入正式接口文档： + +| 暂缓主题 | 暂缓原因 | 预计批次 | +|---|---|---| +| 全套专属接口编号正式发布 | 当前仍以统一入口为正式事实 | 后续接口专题 | +| BPM API / 审批流 API | 当前只冻结审批能力位边界 | 后续 BPM 专题 | +| 与目标数据库字段的一一映射表 | 会使接口文档过度下沉到数据库层 | 后续实现 / 补充专题 | +| IC 卡账务在线接口 | 当前冻结为历史只读 + 映射层 | 暂不进入在线接口设计 | +| 查询报表的最终导出字段清单 | 需结合统计/查询专题进一步收敛 | `RWB-04` 或后续专题 | + +##### 五、正式改写时的段落重组建议 + +`03_Interface_Design.md` 正式改写时，建议采用以下重组顺序： + +1. 先保留 `IF-REV-007` 当前统一入口的正式事实。 +2. 在接口说明中扩展全量对象承接边界。 +3. 在请求/响应参数中补充对象类型、审批边界、结果状态语义。 +4. 重写历史查询与迁移校验章节，使其覆盖全量账务对象查询出口。 +5. 在实现状态说明中明确“当前已落地 / 后续专属接口方向”。 + +### 13.11 `RWB-04` 回写准备：`03_Summary_Design.md` 范围拆解 + +`RWB-04` 当前只做**总体摘要回写准备**，目标是先把 `docs/design/01_Overview/03_Summary_Design.md` 中与 REV-004 账务领域相关的摘要口径拆清楚，不在本步骤之外扩写超过概要层。 + +#### 13.11.1 本批次锁定的目标章节 + +`RWB-04` 只允许优先触达以下章节： + +| 目标章节 | 当前状态 | `RWB-04` 准备动作 | +|---|---|---| +| `主要接口定义`（总体接口表） | 缺少 `IF-REV-007` | 补入统一账务处理入口摘要定义 | +| `子系统2设计: 营收业务系统 -> 子系统外部接口` | 缺少 `IF-REV-007` | 同步补入 REV-004 对外接口摘要口径 | +| `营收核心模块群` 概述 | 仍保留“一期先聚焦”旧摘要 | 改为“当前统一入口 + 全量对象目标边界”双层摘要 | +| `营收核心模块群` 模块列表 | `REV-004` 描述过窄 | 扩展为全量账务对象承接摘要 | +| `#### REV-004: 账务处理` | 仅写未销账调整/分账/预付款退款/呆坏账 | 改为概要层的对象族 + 承接边界描述 | + +#### 13.11.2 本批次明确纳入范围 + +`RWB-04` 进入正式回写时，准备纳入以下内容： + +1. 在概要层明确 `IF-REV-007` 当前仍是 REV-004 正式统一入口。 +2. 将 `REV-004` 的摘要从“一期五类处理”提升为“当前统一入口 + 全量账务对象目标边界”。 +3. 在概要层列出核心对象族，但不下沉到数据库字段、接口参数、BPM 节点细节。 +4. 同步收敛“当前已落地 / 目标设计 / 历史只读”的高层边界。 + +#### 13.11.3 本批次明确排除范围 + +`RWB-04` 不纳入以下动作： + +1. 不在概要设计中重复详设/数据库/接口的字段级细节。 +2. 不新增专门的账务关系图或复杂流程图，除非为消除明显口径冲突所必需。 +3. 不把目标对象写成已全部实现的既成事实。 +4. 不修改与 REV-004 无关的子系统摘要章节。 + +#### 13.11.4 guides 到 `03_Summary_Design.md` 的回写映射 + +| guides 来源章节 | `03_Summary_Design.md` 目标小节 | 回写目标 | +|---|---|---| +| `8.1`、`8.2`、`8.3` | 营收核心模块群概述、`REV-004` 模块描述 | 把正式业务实体清单翻译成概要层对象族摘要 | +| `12.7`～`12.11` | 主要接口定义、营收业务系统子系统外部接口 | 把统一入口与查询分层趋势翻译成概要层接口摘要 | +| `12.12`～`12.15` | `REV-004` 模块描述 | 把审批能力位/审批边界翻译成概要层约束说明 | +| `13.3`～`13.7` | `RWB-04` 执行准备，不直接写入概要正文 | 用于约束快照、基线和验证 | + +#### 13.11.5 `RWB-04` 正式改写前的最小准备清单 + +在真正开始改 `03_Summary_Design.md` 前，至少先完成以下准备： + +1. 为 `03_Summary_Design.md` 生成本批次 Archive 快照。 +2. 固定本次回写基线 commit。 +3. 明确概要层只写模块职责、接口摘要、实现边界，不越级展开。 +4. 完成后执行 `03_Summary_Design.md` 单文件校验，并复核与前三批正式文档口径一致。 + +## 14. 逐步细化计划 + +建议按以下顺序继续细化： + +### 第一步：对象定版 + +完成以下事项： + +- 确认正式业务实体清单 +- 确认哪些对象保留汇总/明细双表 +- 确认哪些对象只保留查询投影 + +### 第二步：字段骨架定版 + +逐对象补齐： + +- 主键 +- 单号 +- 状态 +- 原对象引用 +- 审批字段 +- 金额/水量前后差异字段 +- 查询索引字段 + +### 第三步：关系与状态机定版 + +逐对象明确： + +- 与 `Charge` / `ChargeDetail` / `Transaction` / `AccountLog` 的关系 +- 与统一骨架的关系 +- 与审批流的关系 +- 状态机 + +### 第四步：迁移方案定版 + +逐对象明确： + +- 旧表映射 +- 历史迁移规则 +- 兼容查询规则 +- 报表承接方式 + +### 第五步：正式文档回写 + +将已定版内容分批同步到： + +- 详细设计 +- 数据库设计 +- 接口设计 +- 总体设计摘要 + +执行顺序固定为： + +1. 先完成 `RWB-01` 详设回写，稳定对象边界与审批边界。 +2. 再完成 `RWB-02` 数据库回写，落主表/明细表/映射字段骨架。 +3. 再完成 `RWB-03` 接口回写，收敛统一入口、专属入口与查询接口。 +4. 最后完成 `RWB-04` 总体摘要回写，只做总览收敛。 + +每一批回写都必须按以下顺序校验： + +1. 回写前确认冻结门禁、批次号、目标章节与 Archive 快照。 +2. 回写后先执行目标文档 `make validate-file`。 +3. 再复核 `docs/guides/REV004_FULL_ACCOUNTING_DOMAIN_DESIGN.md` 与正式文档是否一致。 +4. 如改动了跨文档引用或标题锚点，再执行小范围链接检查。 +5. 校验通过后再更新 `Project_Progress` 或相关治理台账。 + +## 15. 当前待确认问题 + +以下问题按当前证据收敛为两类：已可冻结结论 / 仍待确认问题。 + +### 15.1 已可冻结结论 + +#### 15.1.1 红冲 + +- **结论**：`红冲` 继续作为**独立正式业务对象**保留。 +- **依据**： + - 操作手册明确存在独立菜单 `【营业收费】-【红冲记录】`，并支持查询、导出和详情展开。 + - `12_REV_Detailed.md` 明确红冲记录是收费差错追溯的重要入口。 +- **当前冻结判断**： + - 红冲作为独立业务对象保留。 + - 红冲查询能力必须独立保留。 + - 是否需要**单独审批流**，当前仍保留为待确认；本轮仅冻结“红冲不是普通附属字段，而是独立场景对象”。 + +#### 15.1.2 分账调整 + +- **结论**：`分账调整` 继续作为**独立正式业务对象**保留，并且**明确存在多个分摊策略**。 +- **依据**： + - 操作手册明确在 `未销调整 > 分账` 中支持： + - 按水量分账 + - 按费用组成分账 + - `12_REV_Detailed.md` 已把分账调整视为“费用组成重分摊场景”承接。 +- **当前冻结判断**： + - 分账调整必须保留独立业务语义。 + - 分账调整后续应补**规则表或规则字段组**，因为至少已存在两类分摊策略，不宜只靠单一通用明细字段兜底。 + +#### 15.1.3 违约金减免 + +- **结论**：`违约金减免` 继续作为**独立正式业务对象**保留。 +- **依据**： + - 操作手册明确存在独立能力，并支持： + - 按金额 + - 按日期 + - 批量处理 + - 数据字典中存在 `PM_LATEFEE_RECORDS` / `PM_LATEFEE_RECORD_DETAILS`。 +- **当前冻结判断**： + - 违约金减免不应再退化为普通金额调整子类型。 + - 其主单/明细结构保留合理。 + +#### 15.1.4 价差调整 + +- **结论**：`价差调整` 继续作为**独立正式业务对象**保留。 +- **依据**： + - 操作手册明确支持： + - 调价号 + - 用水性质 + - 阶梯计费勾选 + - 数据字典存在 `PM_PRICE_RECORDS` / `PM_PRICE_RECORD_DETAILS` + - `12_REV_Detailed.md` 已把价差调整作为“重算与差额修正场景”承接。 +- **当前冻结判断**： + - 价差调整必须保留独立业务语义。 + - 其与价格体系、阶梯计费和累计量关系应在后续字段设计中继续展开。 + +#### 15.1.5 呆坏账调整 + +- **结论**：`呆坏账` 继续作为**独立正式业务对象**保留。 +- **依据**： + - 操作手册明确至少区分： + - 呆账 + - 坏账 + - 纠纷账 + - 且可恢复性不同。 + - 数据字典中有独立表族；`12_REV_Detailed.md` 已按坏账申请与生效场景承接。 +- **当前冻结判断**： + - `BadDebtRecord` 必须保留独立主单与明细承接。 + - `呆账/坏账/纠纷账` 至少应作为类型枚举保留。 + +#### 15.1.6 已销调整 / 预存调整 / 账务日志 + +- **结论**：三者在旧系统中都属于账务处理主模块下的正式子模块，应在新系统设计中保留独立业务语义或独立查询入口。 +- **依据**： + - 操作手册账务处理章节明确把： + - 未销调整 + - 已销调整 + - 预存调整 + - 账务日志 + 作为正式功能子模块描述。 +- **当前冻结判断**： + - `已销调整` 继续保留为正式业务实体。 + - `预存调整` 至少需要在后续继续明确它与 `PrepaidRefund`、账户调整、余额迁移之间的边界。 + - `账务日志` 继续作为统一查询/审计出口保留。 + +### 15.2 仍待确认问题 + +#### 15.1.7 特账 + +- **结论**：`特账` 更符合“**特殊开账产生的特殊账单 / 收费类型**”，不建议直接定义为独立 `L2` 账务处理实体。 +- **依据**： + - 操作手册和需求文档明确存在 `特殊开账`，并说明其主要针对罚款类型、可直接开账、可直接收费。 + - 数据字典中 `FeeType` 明确包含 `3 = 特账`，说明它更接近账单/收费类型，而不是独立申请单。 + - 当前正式文档 `12_REV_Detailed.md`、`01_Database_Design.md` 已倾向于把特殊开账统一挂到 `biz_charge` / `biz_charge_detail` 承接。 +- **当前冻结判断**： + - 特账优先由 `Charge` / `ChargeDetail` 主模型承接。 + - 应通过 `sourceType`、`feeType`、`specialBillType`、`reasonCode` 等字段区分。 + - 不建议当前先独立建设 `SpecialAccountRecord` / `SpecialAccountRecordDetail`。 + +#### 15.2.2 退款账 + +- **当前状态**：已可冻结为**结果型正式账务对象**。 +- **原因**： + - 数据字典存在 `AT_REFUNDS`，并出现 `RefundId`、`RefundNumber`、`RefundPrice` 等字段，说明旧系统存在正式退款结果对象，而不是只有退款动作。 + - 旧需求文档同时出现： + - 账务退款 + - 预付款退款 + - 多缴退款 / 错误缴费退款等退款语义 + 说明退款在旧系统中不是单一按钮，而是一组正式业务场景。 + - `specs/008` 中 `AT_REFUNDS` 被映射为旧对象 `退款账`，并被视为弱映射/当前缺口之一。 +- **当前冻结判断**： + - `退款账` 与 `PrepaidRefund` 不是同一概念。 + - `PrepaidRefund` 更偏退款申请/处理流程对象。 + - `RefundBill` 应作为退款处理完成后形成的**正式账务结果对象**保留。 + - `RefundBill` 至少应承接： + - 原账单 / 原收费 / 原交易关系 + - 退款金额 + - 退款状态 + - 退款时间 + - 退款人员 + - 退款单号 / 退款流水号 +- **后续待细化点**： + - 哪几类退款场景共用同一 `RefundBill` + - 是否需要独立明细表 + - 与 `Transaction`、`Charge`、收费明细中退费记录的关系如何建模 + +#### 15.2.3 跨周期水量 + +- **当前状态**：已可冻结为**独立基础数据对象**。 +- **原因**： + - 数据字典将其放在“账务信息”层，而不是“收费、账务处理”动作层。 + - 字段包含 `PriceCode`、`PriceItemId`、`LevelType`、`LevelIndex`、`StartWater`、`EndWater`、`UsedWater`、`LeftWater`、`IsSystemComputed`，更符合跨账期计费、阶梯累计和账单重算支撑对象特征。 + - 当前正式文档虽然未把它认定为已实现独立表，但也未否定其业务语义，只是避免误写为现成在线实体。 +- **当前冻结判断**： + - `CrossCycleWaterRecord` 应保留为独立基础数据对象。 + - 它不是强流程型业务单，不宜按退款/红冲/坏账那种申请单模式建模。 + - 若后续涉及审批，应由关联业务场景（如价差调整、未销调整）带出，而不是由跨周期水量对象自身承接审批流。 + +#### 15.2.4 IC 卡账务 + +- **当前状态**：旧系统正式存在，当前按**历史只读 + 映射层**承接。 +- **原因**： + - 操作手册未检索到 `IC卡` 相关账务入口，因此无法证明它仍是当前营收主操作流程的一部分。 + - 数据字典存在 `IC卡充退表`、`IC卡充退账明细表`、`IC卡结余记录`、`IC卡操作日志`。 + - Archive `数据库设计.md` 还给出了 `IC卡表-biz_smartcard`、`IC卡充退表-biz_smartcard_log`、`IC卡充退帐明细表-biz_smartcard_log_detail`、`IC卡结余记录-biz_smartcard_odd_log`、`IC卡操作日志-biz_smartcard_operate_log` 的完整建模说明。 + - `BACKEND_TABLE_MAPPING.md` 当前将其列为旧系统账务中的明显缺口之一。 +- **当前冻结判断**： + - IC 卡账务在旧系统中属于正式对象族。 + - 当前新系统设计不将其纳入在线主写模型。 + - 当前统一按**历史只读查询 + 新旧标识映射**承接。 + - 后续如业务范围发生变化，再单独评估是否升级为独立子域。 + +## 16. 本文档当前状态说明 + +本文档当前完成的是： + +- 目标建模路线定版 +- 分层结构定版 +- 正式业务实体清单定版 +- 关系图骨架定版 +- 目标表设计骨架定版 +- 后续逐步细化路径定版 + +本文档当前尚未完成的是： + +- 每个实体字段级完整设计 +- 数据库物理字段逐列定义 +- 完整接口合同拆分 +- 完整迁移 SQL/脚本设计 +- backend 代码实现方案 diff --git a/docs/guides/REV004_IMPLEMENTATION_HANDOFF.md b/docs/guides/REV004_IMPLEMENTATION_HANDOFF.md new file mode 100644 index 0000000..8e03129 --- /dev/null +++ b/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` diff --git a/docs/guides/REV004_PREPAID_REFUND_TRANSFER_EVIDENCE_MATRIX.md b/docs/guides/REV004_PREPAID_REFUND_TRANSFER_EVIDENCE_MATRIX.md new file mode 100644 index 0000000..d4f07f3 --- /dev/null +++ b/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 与字段设计**可参考原系统直接推进 +- **资金与账务规则**必须单独走确认流程 + +---