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

163 lines
7.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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. 编译
执行：
```bash
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. 定向测试
执行：
```bash
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` 记入日志明细，
避免被“旧值=新值则跳过”逻辑误过滤
### 新鲜验证
#### 定向编译
```bash
mvn -pl sw-business/sw-business-server -DskipTests compile
```
结果：**PASS**
#### 定向单测
```bash
mvn -pl sw-business/sw-business-server \
-Dtest=AccountingAdjustQueryServiceImplTest,LateFeeReduceFormalizationServiceTest,AccountingAdjustActionServiceImplTest#approve_lateFeeReduceDateModeShouldReduceCurrentLateFeeAndUpdateFormalTable \
test
```
结果：**PASS（8 tests, 0 fail, 0 error）**
#### 真实数据库 canary
```bash
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 路线。
Reference in New Issue View Git Blame Copy Permalink