tangweijie/fujian_water_biz_doc
1
0
Fork 0
Code Issues Pull Requests 12 Actions Packages Projects Releases 1 Wiki Activity
fujian_water_biz_doc/docs/evidence/rev004-accounting/rev004-accountprocess-interface-truth-matrix-2026-04-13.md
tangweijie 3eccab2cf9 docs: 文档治理统一 — AGENTS.md 生命周期规则 + 模块归档 + DDL 修正 
1. AGENTS.md 更新
   - water-docs: 新增 specs/ 与 docs/design/ 生命周期规则章节
   - water-backend: 更新协作引用（建设期/建成后、evidence 模块化）

2. specs/ 重复合并
   - 006-reminder-event-design 合并入 003-rev006-reminder-event-design
   - 001-rev004-accounting 删除冗余 data-model.md + contracts/
   - 002-rev005-invoice-flow 删除冗余 data-model.md + contracts/

3. evidence 按模块归档
   - 35 个 REV-004 文件归入 evidence/rev004-accounting/
   - 7 个通用 bugfix 文件归入 evidence/bugfix/ 和 bugfix/frontend/
   - 新建 rev005-invoice/、rev006-reminder/、rev007-statistics/ 目录

4. guides/ 清理
   - 14 个 REV004_*.md 移入 evidence/rev004-accounting/

5. 遗留文件处理
   - docs/research/ 归档到 Archive/06_Migration_Plans/
   - backend-check detached worktrees 清理

6. 交叉引用修复
   - 006-reminder-event-design → 003-rev006-reminder-event-design
   - docs/guides/REV004_ → docs/evidence/rev004-accounting/REV004_

7. DB 设计文档修正（01_Database_Design.md）
   - biz_invoice 明确为开票配置表，非发票记录表
   - 新增 biz_invoice_record 为发票申请/结果主表
   - 新增 biz_charge_invoice_rel 账单-发票关联说明
   - REV-005 承接口径表名全部修正

8. 发票审计证据
   - 新增 evidence/rev005-invoice/2026-06-16-invoice-document-audit.md
2026-06-16 11:47:16 +08:00

9.1 KiB
Raw Blame History

REV004 / accountProcess 接口真值矩阵（2026-04-13）

目的

给前端/联调/验收一个“当前代码真实口径”矩阵：

  • 哪个页面/弹窗对应哪些接口
  • 每个接口当前稳定返回哪些关键字段
  • 哪些字段已经被真实库测试覆盖
  • 哪些地方仍然是页面编排层面的剩余缺口

口径来源：water-backend 当前控制器 + Req/RespVO + 已落地真实库 canary。

一、页面 / 弹窗 -> 接口映射

1. 预存调整页

查询区

  • GET /admin-api/business/accounting-adjust/prestorage-page
  • GET /admin-api/business/accounting-adjust/prestorage-stat
  • GET /admin-api/business/accounting-adjust/prestorage-detail?id={id}

动作区

  • POST /admin-api/business/accounting-adjust/prestorage-submit
  • POST /admin-api/business/accounting-adjust/prestorage-revoke
  • GET /admin-api/business/accounting-adjust/prestorage-process?adjustmentNo=...
  • GET /admin-api/business/accounting-adjust/prestorage-attachments?adjustmentNo=...

维护区

  • POST /prestorage-customer-update
  • POST /prestorage-meter-update
  • POST /prestorage-billing-update
  • POST /prestorage-discount-update
  • POST /prestorage-cost-component-update

2. 已销调整页

查询区

  • GET /admin-api/business/accounting-adjust/sold-page
  • GET /admin-api/business/accounting-adjust/sold-stat

动作区

  • POST /admin-api/business/accounting-adjust/sold-submit
  • POST /admin-api/business/accounting-adjust/sold-batch-revoke

3. 未销调整页

查询区

  • GET /admin-api/business/accounting-adjust/unsold-page
  • GET /admin-api/business/accounting-adjust/unsold-stat

动作区（按弹窗切换）

  • 调整：POST /unsold-adjust-submit
  • 分账：POST /unsold-split-submit
  • 违约金减免：POST /unsold-late-fee-reduce-submit
  • 价差调整：POST /unsold-price-diff-submit
  • 呆坏账：POST /unsold-bad-debt-submit

批量区

  • POST /unsold-adjust-batch-submit
  • POST /unsold-split-batch-submit
  • POST /unsold-late-fee-reduce-batch-submit
  • POST /unsold-price-diff-batch-submit
  • POST /unsold-bad-debt-batch-submit

4. 账务日志页

查询区

  • GET /admin-api/business/accounting-adjust/log-page
  • GET /admin-api/business/accounting-adjust/log-stat
  • GET /admin-api/business/accounting-adjust/log-detail?adjustmentNo=...

二次动作弹窗

  • 转退款：POST /admin-api/business/accounting-adjust/log-refund
  • 转预存：POST /admin-api/business/accounting-adjust/log-prestorage
  • 撤销：POST /admin-api/business/accounting-adjust/log-revoke

辅助弹窗

  • GET /admin-api/business/accounting-adjust/log-process?adjustmentNo=...
  • GET /admin-api/business/accounting-adjust/log-attachments?adjustmentNo=...

二、关键返回字段真值

A. 通用动作返回 AccountingAdjustRespVO

适用：

  • prestorage-submit
  • sold-submit
  • unsold-*submit
  • log-refund
  • log-prestorage

当前稳定字段：

  • adjustmentNo：主联调键
  • objectType：对象类型；未销调整 AMOUNT/USAGE 场景可能为空，其他场景一般有值
  • resultStatus：推荐前端主读字段
  • approvalStatus
  • writeBackStatus
  • approvalRequired
  • resultObjectNo
  • msg
  • status：兼容旧字段
  • message：兼容旧字段

前端推荐：

  • 优先读 resultStatus / approvalStatus / writeBackStatus / msg
  • status / message 仅做兼容保底

B. 撤销 / 审批动作返回 AccountingAdjustActionRespVO

适用：

  • prestorage-revoke
  • log-revoke

当前稳定字段：

  • adjustmentNo
  • objectType
  • actionType（当前撤销返回 REVOKE）
  • approvalStatus
  • resultStatus
  • writeBackStatus
  • message
  • actionTime

C. 预存分页 AccountingAdjustPrestoragePageRespVO

关键字段：

  • id
  • adjustmentNo
  • custId
  • workOrderStatus
  • adjustmentType
  • custCode / custName / custAddress
  • targetCustCode
  • adjustAmount / preBalance / postBalance
  • adjustReason / remark
  • createTime / creatorName
  • canRevoke / canViewAttachment

补充：

  • prestorage-detail 在上面基础上增加：
    • objectType
    • resultStatus
    • approvalStatus
    • writeBackStatus
    • processInstanceId
    • attachmentRefs

D. 已销分页 AccountingAdjustSoldPageRespVO

关键字段：

  • id
  • custId
  • accountMonth
  • custCode / custName / custAddress
  • waterNature
  • billedWaterVolume
  • actualAmount
  • billedAmount
  • penaltyAmount
  • collectionMethod
  • collector
  • collectionDate
  • canAdjust
  • canBatchRevoke

注意：

  • 已销查询页不是调整日志页，所以这里没有 adjustmentNo
  • sold-submit 提交后，前端若要看申请单号，应跳到 log-* 维度或使用提交返回值保存的 adjustmentNo

E. 未销分页 AccountingAdjustUnsoldPageRespVO

关键字段：

  • id
  • custId
  • custCode / custName / custAddress
  • waterType
  • accountMonth
  • waterVolume
  • totalAmount / billAmount / penaltyAmount
  • waterFee / sewageFee / garbageFee / resourcesFee / overPlanFee / seasonalSupplement
  • canAdjust / canSplit / canLateFeeReduce / canPriceDiffAdjust / canBadDebtAdjust

F. 日志分页 AccountingAdjustLogPageRespVO

关键字段：

  • id
  • adjustmentNo
  • accountMonth
  • custId / custCode / custName / custAddress
  • accountTypeCode / accountType
  • processMethodCode / processMethod
  • amount
  • description
  • registrant / handler
  • handleTime / createTime
  • statusCode / status
  • targetCustCode
  • originalPrestore / newPrestore
  • originalBill / newBill
  • originalWaterVolume / newWaterVolume
  • originalPenalty / newPenalty
  • billChange / waterVolumeChange / penaltyChange
  • canRevoke / canRefund / canPrestore

G. 日志详情 AccountingAdjustLogDetailRespVO

在日志分页基础上增加：

  • objectType
  • resultStatus
  • approvalStatus
  • writeBackStatus
  • originalTranSeq
  • originalSysTranSeq
  • attachmentRefs
  • details[]

H. 流程 / 附件

AccountingAdjustProcessRespVO

关键字段：

  • adjustmentNo
  • objectType
  • adjustType
  • chargeId
  • actionAmount
  • resultStatus
  • approvalStatus
  • writeBackStatus
  • taskId
  • processState
  • latestMessage
  • latestOperationTime
  • stages[]

AccountingAdjustAttachmentRespVO

关键字段：

  • adjustmentNo
  • ref
  • resolved
  • id / name / link / size / extension
  • message

三、当前已经被真实库测试证明的字段/链路

已证明

预存

  • prestorage-submit 返回 adjustmentNo/resultStatus/writeBackStatus
  • prestorage-page 可见新记录
  • prestorage-stat 可统计到 refundCount
  • prestorage-detail 可按 id 回看 resultStatus/writeBackStatus
  • prestorage-revoke 可回滚余额并生成撤销日志

已销

  • sold-submit 返回 adjustmentNo/resultStatus=PENDING_APPROVAL
  • sold-page 可见原账单，且 canBatchRevoke=true
  • sold-stat 可统计 totalCount / totalActualAmount
  • sold-batch-revoke 可按营业账 ID 执行撤销

未销

  • 五类 submit 均已跑通真实库 happy path：
    • adjust
    • split
    • late-fee-reduce
    • price-diff
    • bad-debt
  • 动作返回值与 operat_log 写入已被验证

日志

  • log-page / log-stat / log-detail / log-process / log-attachments 已形成一组真实库联动回看
  • log-refund、log-prestorage、log-revoke 已打通闭环
  • log-detail 中 originalTranSeq / attachmentRefs 已被验证

四、前端使用建议（当前真值口径）

1. 提交后立即展示

提交类动作完成后，前端应优先使用提交响应里的：

  • adjustmentNo
  • resultStatus
  • approvalStatus
  • writeBackStatus
  • msg

2. 页面列表回看

  • 预存页：查 prestorage-page
  • 已销页：查 sold-page
  • 未销页：查 unsold-page
  • 若要看“申请/动作留痕”，查 log-page

3. 二次动作弹窗

  • 日志页弹窗（退款/转预存/撤销）都应以 adjustmentNo 作为主键
  • 已销批量撤销当前以 chargeIds[] 为入参，不是 adjustmentNo[]

4. 状态口径

  • 预存页 workOrderStatus：0未处理 / 1已审核 / 2已完成 / 3已撤销
  • 通用动作结果：
    • resultStatus
    • approvalStatus
    • writeBackStatus
  • 日志页状态：
    • statusCode/status 为页面状态投影，不等于 workOrderStatus

五、剩余缺口

  1. 还没有做“前端弹窗 A/B/C 切换路径”的 UI 级编排，只做到了接口级真实库链路。
  2. 还没有把所有字段做成“页面元素 -> 字段 -> 接口 -> 证据”的逐项勾稽表。
  3. 若后续要做最终验收，建议再补一版：
    • 弹窗功能分组矩阵
    • 字段级 contract/assertion matrix

六、证据索引

  • 集成测试 bootstrap 与累计验证：
    • docs/evidence/rev004-accountprocess-integration-testing-bootstrap-2026-04-13.md
  • 代码位置：
    • sw-business-server/src/main/java/.../accountProcess/*Controller.java
    • sw-business-server/src/main/java/.../accountProcess/vo/*ReqVO.java
    • sw-business-server/src/main/java/.../accountProcess/vo/*RespVO.java
    • sw-business-server/src/test/java/.../integration/rev004/accountprocess/Rev004AccountProcessCanaryQueryIntegrationTest.java