fujian_water_biz_doc/docs/guides/REV004_FRONTEND_IMPLEMENTATION_HANDOFF.md

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