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-latefee-batch-contract-formalization-implementation-2026-04-14.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

5.4 KiB
Raw Blame History

REV004 未销违约金减免批量契约补齐实施记录（2026-04-14）

目标

补齐 unsold-late-fee-reduce-batch-submit 的批量 outer 契约，使其能够承接前端页面公共表单字段，并把字段真实透传到后端执行主链，而不是只停留在 controller VO。

本次实现

1. 批量 outer 契约补齐

文件：

  • sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/accountingadjust/accountProcess/vo/AccountingAdjustUnsoldLateFeeReduceBatchSubmitReqVO.java
  • sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/accountingadjust/accountProcess/vo/AccountingAdjustUnsoldLateFeeReduceBatchItemReqVO.java

新增 outer 字段：

  • lateFeeType
  • applicant
  • contactMobile
  • applyReason
  • remark
  • attachmentRefs

明细 item 独立为专用 VO：

  • chargeId
  • adjustmentNo
  • applyReason（兼容旧逐项提交）
  • remark（兼容旧逐项提交）
  • attachmentRefs（兼容旧逐项提交）
  • lateFeeReduceAmount
  • startDate
  • endDate

2. 共享 batch 主链承接 outer 字段

文件：

  • .../AccountingAdjustBatchSubmitReqVO.java
  • .../AccountingAdjustActionController.java
  • .../AccountingAdjustProcessServiceImpl.java

处理方式：

  • controller 先把 late-fee batch outer 字段规范化映射到 generic batch DTO
  • process 主链在 executeBatchSubmit 中统一执行 outer -> item 合并
  • 统一 batch 主链承接字段：
    • reasonCode
    • reason
    • applicant
    • contactMobile
    • attachmentRefs
    • lateFeeType

这避免了“专用 VO 上有字段，但 generic batch 主链吃不到”的伪完成。

3. amount / date 模式校验补齐

文件：

  • .../AccountingAdjustProcessServiceImpl.java
  • .../AccountingAdjustReqVO.java
  • .../ChargeServiceImpl.java

规则：

  • lateFeeType=1（按金额）
    • 要求 lateFeeReduceAmount > 0
    • 不允许同时传 startDate/endDate
  • lateFeeType=2（按日期）
    • 要求 startDate/endDate 同时存在，且 endDate >= startDate
    • 不允许同时传 lateFeeReduceAmount
  • 未显式传 lateFeeType 时：
    • 若存在日期字段，推导为 2
    • 否则默认 1

4. 执行日志落地字段补齐

文件：

  • .../AccountingAdjustReqVO.java
  • .../ChargeServiceImpl.java

新增写入 operat log detail 的字段：

  • lateFeeType
  • applicant
  • contactMobile
  • startDate
  • endDate

验证结果

编译

命令：

mvn -pl sw-business/sw-business-server -DskipTests compile

结果：PASS

定向单测

命令：

mvn -pl sw-business/sw-business-server \
  -Dtest=AccountingAdjustActionControllerTest#batchCreateUnsoldLateFeeReduce_shouldReturnWrappedSuccess,AccountingAdjustProcessServiceImplTest#createUnsoldLateFeeReduce_shouldPassDateModeFieldsToUnifiedChargeService+createUnsoldLateFeeReduce_shouldRejectMixedAmountAndDateMode+batchCreateUnsoldLateFeeReduce_shouldMergeBatchOuterFieldsIntoItems \
  test

结果：PASS（4 tests, 0 fail, 0 error）

真实 DB 定向集成

命令：

REV004_IT_DB_URL=jdbc:postgresql://192.168.10.130:5436/sw_system \
REV004_IT_DB_USERNAME=sw_system \
REV004_IT_DB_PASSWORD='Em@123456' \
mvn -pl sw-business/sw-business-server \
  -Dtest=Rev004AccountProcessCanaryQueryIntegrationTest#unsoldLateFeeReduceBatchSubmit_shouldAcceptOuterFieldsAndDateModeContract \
  test

结果：PASS（1 test, 0 fail, 0 error）

集成验证确认：

  • batch outer 字段可提交
  • lateFeeType=2 date-mode 契约可进入主链
  • operat log detail 中可看到：
    • lateFeeType=2
    • applicant
    • contactMobile
    • startDate
    • endDate
    • attachmentRefs

当前边界与剩余风险

  1. 本轮重点是“提交契约 + 主链承接 + 日志落地”。
  2. lateFeeType=2 的“按日期执行态/审批回写态”尚未展开为完整金额计算逻辑；当前已确保申请态与提交链路可用。
  3. 由于仓库当前还存在其他在制改动，本轮只做了定向验证，没有把整个相关测试类全部拉绿。

结论

本轮已完成 REV004 未销违约金减免批量提交接口的主契约补齐，并把前端页面公共字段正式落到共享 batch 主链与日志记录中；可以支撑前端继续联调“按金额/按日期”两种提交形态。

追加收口（读模型展示字段）

本轮补齐

  • AccountingAdjustDetailRespVO 新增：
    • lateFeeType
    • applicant
    • contactMobile
    • startDate
    • endDate
  • AccountingAdjustLogDetailRespVO 新增同名字段
  • AccountingAdjustProcessRespVO 新增：
    • reasonCode
    • attachmentRefs
    • lateFeeType
    • applicant
    • contactMobile
    • startDate
    • endDate

读取链路

  • AccountingAdjustQueryServiceImpl：从 operat log detail 读取 late-fee 扩展字段并映射到 detail response
  • AccountingAdjustLogProcessServiceImpl：从 request/action log detail 读取 late-fee 扩展字段并映射到 log-detail response
  • AccountingAdjustProcessServiceImpl#getProcess：从 unified snapshot 读取并投影到 process response

追加验证

定向读模型单测

mvn -pl sw-business/sw-business-server \
  -Dtest=AccountingAdjustQueryServiceImplTest,AccountingAdjustLogProcessServiceImplTest,AccountingAdjustProcessServiceImplTest#getProcess_shouldExposeLateFeeDisplayFieldsFromUnifiedSnapshot \
  test

结果：PASS（7 tests, 0 fail, 0 error）