fujian_water_biz_doc/docs/guides/REV004_IMPLEMENTATION_HANDOFF.md

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 的任务提示模板

任务背景
当前正在推进 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