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

3.8 KiB

Raw Blame History

REV004 late-fee formal-table 真实库阻塞说明（2026-04-15）

状态更新：该阻塞已于 2026-04-15 当天解除，本文保留为阻塞发生记录。

结论

当前 late-fee reduce 代码侧与定向单测已通过，但真实数据库集成验证被环境缺表阻塞，阻塞点不是代码逻辑，而是目标库未部署 formal-table。

已通过的验证

编译

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

定向测试

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

结果：PASS（24 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#unsoldLateFeeReduceDateModeApprove_shouldPersistFormalTableSummary \
  test

失败原因

报错核心：

relation "biz_latefee_reduce_detail" does not exist

在测试前置 / 后置 SQL sql/rev004/accountprocess/00_reset.sql 中，已经尝试执行：

DELETE FROM biz_latefee_reduce_detail ...
DELETE FROM biz_latefee_reduce ...

这说明：

代码侧已经按 formal-table 路径推进
测试脚本也已经按 formal-table 假设编写
但真实库中尚未存在这些表

当前判断

代码逻辑不是当前 blocker。
真实 DB 环境未部署 biz_latefee_reduce / biz_latefee_reduce_detail 是当前 canary 唯一主要阻塞。
在部署 formal-table 之前，真实库层面的 late-fee canary 无法拉绿。

建议下一步

先确认真实库是否允许部署：
- biz_latefee_reduce
- biz_latefee_reduce_detail
若允许部署，再重跑 canary。
若暂不允许部署，则当前阶段只能以 compile + unit/integration mock/local 证据为主，明确标注“真实库阻塞未消除”。

后续结果回写（阻塞已解除）

已完成动作

补充并执行 sql/rev004/REV004_latefee_formal_tables_deploy.sql
修复测试 SQL fixture：
- 00_reset.sql
- 02_latefee_formal_tables.sql
- 03_latefee_formal_reset.sql
补充 late-fee formal-table 查询兜底与 request log adjustmentNo 明细一致性

解除阻塞后的真实库验证

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