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-accounting-adjust-standard-layer-code-bootstrap-2026-04-15.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

7.6 KiB
Raw Blame History

REV004 账务调整统一标准层 — 第一批代码启动证据（2026-04-15）

本轮新增代码

标准层 helper

  • sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/accountingadjust/standard/AccountingAdjustSemanticMapper.java
  • sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/accountingadjust/standard/AccountingAdjustDictResolver.java
  • sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/accountingadjust/standard/AccountingAdjustStatusResolver.java

late-fee reduce formal-table 申请态/审批态基础

  • sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/dal/dataobject/latefeereduce/LateFeeReduceDO.java
  • sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/dal/dataobject/latefeereducedetail/LateFeeReduceDetailDO.java
  • sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/dal/mysql/latefeereduce/LateFeeReduceMapper.java
  • sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/dal/mysql/latefeereducedetail/LateFeeReduceDetailMapper.java
  • sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/accountingadjust/latefeereduce/LateFeeReduceFormalizationService.java

已接入主链 / 读模型

  • AccountingAdjustProcessServiceImpl
  • AccountingAdjustActionServiceImpl
  • AccountingAdjustQueryServiceImpl
  • AccountingAdjustLogProcessServiceImpl
  • AccountingAdjustProcessRespVO
  • AccountingAdjustDetailRespVO
  • AccountingAdjustLogDetailRespVO
  • AccountingAdjustPageRespVO
  • AccountingAdjustLogPageRespVO

对应测试

  • AccountingAdjustSemanticMapperTest
  • AccountingAdjustDictResolverTest
  • AccountingAdjustStatusResolverTest
  • LateFeeReduceFormalizationServiceTest
  • AccountingAdjustQueryServiceImplTest
  • AccountingAdjustLogProcessServiceImplTest
  • AccountingAdjustProcessServiceImplTest（定向方法）
  • AccountingAdjustActionServiceImplTest（late-fee approval 定向方法）

本轮目标

  1. 完成 Task-01 标准层 helper 最小实现
  2. 将字典/状态 helper 接入 late-fee 相关读模型
  3. 接入 late-fee reduce formal-table 申请态写入
  4. 接入审批通过后 formal-table 最小更新闭环
  5. 补 page / log-page 摘要字段试点

新鲜验证证据

1. 编译

执行：

rm -rf sw-business/sw-business-server/target/generated-sources \
       sw-business/sw-business-server/target/generated-test-sources
mkdir -p sw-business/sw-business-server/target/generated-sources/annotations
mvn -pl sw-business/sw-business-server -DskipTests compile

结果：PASS

2. 定向测试

执行：

mvn -pl sw-business/sw-business-server \
  -Dtest=AccountingAdjustQueryServiceImplTest,AccountingAdjustLogProcessServiceImplTest,AccountingAdjustProcessServiceImplTest#createUnsoldLateFeeReduce_shouldPassDateModeFieldsToUnifiedChargeService+createUnsoldLateFeeReduce_shouldRejectMixedAmountAndDateMode+batchCreateUnsoldLateFeeReduce_shouldMergeBatchOuterFieldsIntoItems+getProcess_shouldExposeLateFeeDisplayFieldsFromUnifiedSnapshot,AccountingAdjustActionServiceImplTest#approve_lateFeeReduceShouldOnlyUpdateLateFee,LateFeeReduceFormalizationServiceTest,AccountingAdjustSemanticMapperTest,AccountingAdjustDictResolverTest,AccountingAdjustStatusResolverTest \
  test

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

当前结论

本轮已把第一批试点推进到：

  • helper 已落地
  • helper 已接入 late-fee 相关读模型
  • late-fee formal-table 申请态写入已接入提交主链
  • 审批通过后 formal-table 最小更新闭环已接入
  • page / log-page 摘要字段试点已补
  • compile 通过
  • 定向测试通过

下一步

  1. 继续推进 lateFeeType=2 按日期模式真正计算闭环
  2. 补 formal-table 中 before/reduce/after 的更精确计算与状态更新

追加说明（date-mode 精确计算规则）

当前实现口径

  • 使用 LateFeeDateModeCalculator
  • 所有未缴费用项参与计算
  • 逐项通过 ChargeDetailDO.costComponentCode -> CostComponentDO.penaltyCoefficient 取系数
  • penaltyCoefficient = 0 的费用项自然贡献 0
  • 每项先四舍五入到分，最后汇总
  • lateFeeBefore / lateFeeAfter 使用区间口径，而不是整账单总值口径

已覆盖边界测试

  • 多费用项逐项计算并汇总
  • 起算日晚于用户选择开始日时自动裁剪有效区间
  • 0 系数费用项混合场景
  • 计算结果大于当前 lateFee 时，reduceAmount 按当前 lateFee 封顶
  • 截止日早于有效起算日时返回 0

2026-04-15 补充进展：真实库 canary 拉绿

本轮补充代码

  • sw-business/sw-business-server/src/test/resources/sql/rev004/accountprocess/00_reset.sql
  • sw-business/sw-business-server/src/test/resources/sql/rev004/accountprocess/02_latefee_formal_tables.sql
  • sw-business/sw-business-server/src/test/resources/sql/rev004/accountprocess/03_latefee_formal_reset.sql
  • sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/accountingadjust/latefeereduce/LateFeeReduceFormalizationService.java
  • sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/accountingadjust/AccountingAdjustQueryServiceImpl.java
  • sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/service/charge/ChargeServiceImpl.java
  • sw-business/sw-business-server/src/test/java/cn/com/emsoft/sw/business/integration/rev004/accountprocess/Rev004AccountProcessCanaryQueryIntegrationTest.java

修复点

  1. 真实库 SQL fixture 兼容性

    • 去掉 00_reset.sql 中会被 Spring ScriptUtils 误切分的 DO $$ ... $$
    • 新增 03_latefee_formal_reset.sql，把 late-fee formal table 的清理独立出来
    • 02_latefee_formal_tables.sql 改为无 DO $$ 的约束重建方式

  2. formal-table 查询兜底

    • 当 AccountingAdjustQueryServiceImpl 无法仅从 biz_operat_log(_detail) 聚合出 LATE_FEE_REDUCE 详情时， 改为继续从：
      • biz_latefee_reduce
      • biz_latefee_reduce_detail 回退构造详情对象

  3. request log 的 adjustmentNo 明细一致性

    • ChargeServiceImpl#recordAccountingAdjustOperatLog(...) 中， adjustmentNo 改为以 oldValue = null, newValue = adjustmentNo 记入日志明细， 避免被“旧值=新值则跳过”逻辑误过滤

新鲜验证

定向编译

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

结果：PASS

定向单测

mvn -pl sw-business/sw-business-server \
  -Dtest=AccountingAdjustQueryServiceImplTest,LateFeeReduceFormalizationServiceTest,AccountingAdjustActionServiceImplTest#approve_lateFeeReduceDateModeShouldReduceCurrentLateFeeAndUpdateFormalTable \
  test

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

真实数据库 canary

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 clean \
  -Dtest=Rev004AccountProcessCanaryQueryIntegrationTest#unsoldLateFeeReduceDateModeApprove_shouldPersistFormalTableSummary \
  test

结果：PASS

canary 覆盖到的链路

  • 未销违约金减免（按日期）提交
  • request log 写入 adjustmentNo
  • biz_latefee_reduce / biz_latefee_reduce_detail 申请态落单
  • 审批通过
  • formal table 主表 / 明细表更新为成功态

当前结论更新

REV004 late-fee date-mode 这条最小闭环已从：

  • 代码与单测通过 推进到：
  • 真实库 canary 通过

当前剩余风险已不再是“缺表阻塞”，而是后续是否要把更多对象（坏账 / 核销 / 价差）也迁移到 formal-table 路线。