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

2.4 KiB

Raw Blame History

REV004 违约金规则确认（2026-04-15）

结论

当前后续实现应以以下业务规则作为真值：

违约金 = 欠缴水费金额 × 0.1‰ × 逾期天数

该规则意味着：

按日计收，不是按月滚动
计算基数是欠缴水费金额
不含违约金本身
不得利滚利

业务前提

违约金产生需满足：

逾期未缴
经供水单位通知后仍未缴

对 REV004 的实现影响

1. 计算模型

后续 late-fee reduce 的设计与实现，应以“按日计收”模型展开，而不是“按月滚动”模型。

2. date-mode 减免理解

lateFeeType=2（按日期）应理解为：

对指定日期区间内对应的逾期天数区间做减免
先计算该区间理论应收违约金
再形成：
- lateFeeBefore
- reduceAmount
- lateFeeAfter

3. 需要补齐/确认的系统要素

除现有：

lateFeeBeginDate
lateFee
penaltyCoefficient

还应确认或补齐：

欠缴本金
通知状态 / 通知时间
逾期起算日
逾期天数
上限规则（如部分地区 30%）
60 日后续处置边界

与当前仓库现状的关系

当前已确认存在的模型字段

ChargeDO.lateFeeBeginDate
ChargeDO.lateFee
CostComponentDO.penaltyCoefficient

当前未确认存在的现成实现

仓库中尚未确认存在：

明确的“按日计收违约金”统一计算器
明确的“按日期区间重算违约金”统一服务

因此，当前应将该规则视为：

业务规则真值输入
后续需要据此补正式实现

使用建议

后续 PRD / 设计稿 / 代码实现，不建议再使用“按月滚动”表述；应统一表述为：

按日计收、按区间减免、按期累计结果

追加确认（2026-04-15）

系数来源模型

已进一步确认：

逐项重算违约金时，系数来源为 CostComponentDO.penaltyCoefficient。
取数链路为：ChargeDetailDO.costComponentCode -> CostComponentDO.code -> penaltyCoefficient。

参与计算范围

所有未缴费用项都参与。
不收违约金的费用项，不做额外白名单过滤，而是通过 penaltyCoefficient = 0 自然贡献 0。

汇总口径

每个费用项先单独计算违约金；
每项先四舍五入到分；
最后再求和。

当前仓库状态

已确认存在上述模型链路；
但尚未发现现成“逐项按日期重算违约金”的统一实现。

2.4 KiB Raw Blame History Unescape Escape