vault backup: 2026-05-26 01:18:18

2026-05-26 01:18:18 +08:00
parent 669d3b4400
commit 7cdf0ec9a4
4 changed files with 850 additions and 3 deletions
--- a/prop-acc/scenarios/billing/audit-activitylog-trace.md
+++ b/prop-acc/scenarios/billing/audit-activitylog-trace.md
@@ -0,0 +1,311 @@
+---
+title: prop-acc · billing · 场景 - activitylog 审计追溯
+aliases:
+  - activitylog 审计
+  - 操作日志查询
+  - audit-activitylog-trace
+  - 场景-activitylog 追溯
+tags:
+  - 场景
+  - prop-acc
+  - 账单
+  - 审计
+  - 合规
+audience:
+  - 业务人员
+  - 财务
+  - 审计师
+  - 法务
+status: 已发布
+sub_feature: billing
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 场景:activitylog 审计追溯
+
+billing 模块**首次启用** `spatie/laravel-activitylog`(prop-acc 其他模块仅用 meta JSON)。所有关键操作(作废 / 批删 / 挂起 / 恢复 / 收款 / 创建)记 activitylog,审计 / 内审 / 法务可**精准追溯**:谁 / 什么时候 / 在哪 / 改了什么。
+
+## 典型情境
+
+> [!example] 真实情境
+> 5 月 20 日,内审师审计 5 月嘉禾花园账单数据,发现:
+>
+> - 5 月 15 日有一次**批量删除 92 张账单**(`bulk_deleted`)
+> - 同日有 5 条 **bill voided**(账单作废)
+> - 还有几张账单的 status 从 Suspended → Unpaid(恢复)
+>
+> 审计师要查清:
+> - 谁操作的?
+> - 操作的原因?
+> - 影响了哪些具体账单?
+> - 是否合规?
+
+## 业务人员 / 审计师视角
+
+### 第 1 步:确定查询维度
+
+- **谁操作**:`causer_id`(操作员)
+- **什么时候**:`created_at` 范围
+- **操作类型**:`event`(created / voided / bulk_deleted / suspended / resumed / collected / split)
+- **针对哪个对象**:`subject_type` + `subject_id`(单条操作)/ properties.affected_bill_nos(批量)
+- **操作详情**:`properties` JSON 字段
+
+### 第 2 步:运行 SQL 查询
+
+#### 查询 1:某员工某月所有操作
+
+```sql
+SELECT
+    id,
+    event,
+    subject_type,
+    subject_id,
+    properties,
+    created_at
+FROM activity_log
+WHERE causer_id = ?    -- 王主管 ID
+  AND created_at BETWEEN '2026-05-01' AND '2026-05-31 23:59:59'
+ORDER BY created_at DESC;
+```
+
+返回:
+
+| id | event | subject | properties (节选) | created_at |
+|---|---|---|---|---|
+| 1023 | bulk_deleted | (null) | mode=DeleteAndVoid, reason="...", deleted=92, voided=5 | 2026-05-15 14:32 |
+| 1022 | voided | Bill #500 | reason="业务调整", from_status=Partial | 2026-05-15 14:31 |
+| 1021 | collected | Bill #321 | amount=800, channel=微信 | 2026-05-10 11:23 |
+| ... | ... | ... | ... | ... |
+
+#### 查询 2:某 Bill 的所有操作历史
+
+```sql
+SELECT
+    event,
+    causer_id,
+    properties,
+    created_at
+FROM activity_log
+WHERE subject_type = 'App\\Models\\Bill'
+  AND subject_id = ?    -- 具体 Bill ID
+ORDER BY created_at ASC;
+```
+
+返回该 Bill 的**全生命周期**:created → collected → voided 等。
+
+#### 查询 3:批量删除的详情
+
+```sql
+SELECT
+    causer_id,
+    properties->>'$.mode' AS mode,
+    properties->>'$.reason' AS reason,
+    properties->>'$.total_selected' AS selected,
+    properties->>'$.deleted_count' AS deleted,
+    properties->>'$.voided_count' AS voided,
+    properties->>'$.blocked_count' AS blocked,
+    JSON_LENGTH(properties->'$.affected_bill_nos') AS affected_count,
+    created_at
+FROM activity_log
+WHERE event = 'bulk_deleted'
+  AND created_at BETWEEN ? AND ?
+ORDER BY created_at DESC;
+```
+
+可看出**每次批删**的统计 + 原因。
+
+#### 查询 4:某 bill_no 是否被批删 / 作废过
+
+```sql
+SELECT *
+FROM activity_log
+WHERE event = 'bulk_deleted'
+  AND JSON_CONTAINS(
+      properties->'$.affected_bill_nos',
+      JSON_QUOTE('B-202605-501-001 [DELETED]')
+  );
+```
+
+或:
+
+```sql
+-- 灵活模糊匹配
+SELECT *
+FROM activity_log
+WHERE event = 'bulk_deleted'
+  AND properties->'$.affected_bill_nos' LIKE '%B-202605-501-001%';
+```
+
+可追溯到**已物理删的 Bill** 是何时被谁删的。
+
+### 第 3 步:解读 properties
+
+不同 event 的 properties 结构不同:
+
+| event | properties 主要字段 |
+|---|---|
+| `created`(账单创建)| `bill_no, amount, fee_type_id, resident_id` |
+| `collected`(收款)| `amount, channel, receipt_id` |
+| `voided`(单作废)| `reason, from_status, to_status, bill_no, amount, paid_amount` |
+| `suspended`(挂起)| `reason, from_status, to_status, bill_no` |
+| `resumed`(恢复)| `reason, from_status, to_status, bill_no` |
+| `split`(拆账单)| `target_resident, amount_split, original_bill_id, new_bill_id` |
+| `bulk_deleted`(批删)| `mode, reason, total_selected, deleted_count, voided_count, blocked_count, affected_bill_nos[]` |
+
+详见 [[smart-bulk-delete-design]]"activitylog 设计"段。
+
+### 第 4 步:出审计报告
+
+```markdown
+# 2026 年 5 月 嘉禾花园账单操作审计报告
+
+## 审计范围
+- 时段:2026-05-01 至 2026-05-31
+- 模块:billing
+- 关注操作:bulk_deleted, voided
+
+## 高敏操作统计
+- 批量删除(bulk_deleted):2 次
+  - 5/15 王主管:92 删 + 5 作废,原因"5 月 1 日 Replace 策略误用清理"
+  - 5/28 李经理:30 删,原因"测试数据清理"
+- 单条作废(voided):8 次
+  - 大多与上述批删事件关联
+  - 1 次独立:5/22 王主管作废 Bill #321(原因:陈先生纠纷调解结果)
+
+## 异常发现
+- 无未授权操作(所有 bulk_deleted 操作员均有 bill.bulkDelete 权限)
+- 无超规模操作(单次最多 92 张,合规)
+- 所有操作都填了 reason(合规)
+
+## 合规结论
+- ✅ 所有高敏操作均有 audit trail
+- ✅ 操作员权限符合岗位
+- ✅ 原因填写规范
+
+## 建议
+- 长期保留 activitylog(至少 7 年,与会计档案同周期)
+- 季度审计抽查
+```
+
+## 业户视角
+
+业户**通常不直接接触** activitylog。但**法律纠纷时**:
+
+- 业户对某账单的操作有疑问 → 业户可申请查看 activitylog
+- 物业有义务**留存 + 展示**操作历史(透明化、可追溯)
+- 业户/法院通过 activitylog 评估物业操作合规性
+
+## 法务 / 监管视角
+
+| 用途 | 怎么用 |
+|---|---|
+| **司法纠纷举证** | 业户起诉物业不当操作 → 物业拿 activitylog 证明操作合规 |
+| **政府监管检查** | 检查批量删除 / 作废操作是否合理 |
+| **行业自律审计** | 行业协会定期抽查 |
+| **内部审计** | 财务总监 / 审计部门定期审 |
+
+## 与 prop-acc 其他模块的对比
+
+| 模块 | 审计方案 |
+|---|---|
+| **billing(本)** | **activitylog + meta** |
+| deposit | meta JSON(`force_closed_*` / `freeze_reason` 等)|
+| prepaid | meta JSON(`freeze_reason` / `unfreeze_reason`)|
+| meter | meta JSON(`decommission_reason`)|
+| adhoc | meta JSON 或 `voided_at` 字段 |
+
+billing 的 activitylog 是 prop-acc **首个启用 spatie 审计日志的模块**(issue.md Q6 标志性改进)。其他模块**可以借鉴**(未来若启用,有 billing 实施经验)。
+
+## activitylog 表结构(spatie 标准)
+
+```sql
+CREATE TABLE activity_log (
+    id BIGINT PRIMARY KEY,
+    log_name VARCHAR(255),
+    description TEXT,            -- 简单描述
+    subject_type VARCHAR(255),   -- 对象类(Bill)
+    subject_id BIGINT,           -- 对象 ID
+    causer_type VARCHAR(255),    -- 操作员类(User)
+    causer_id BIGINT,            -- 操作员 ID
+    properties JSON,             -- 详情(reason / amount / etc.)
+    event VARCHAR(255),          -- 自定义事件名
+    batch_uuid VARCHAR(36),      -- 可关联多条 log
+    created_at TIMESTAMP,
+    updated_at TIMESTAMP,
+    INDEX idx_subject(subject_type, subject_id),
+    INDEX idx_causer(causer_type, causer_id),
+    INDEX idx_event(event),
+    INDEX idx_created_at(created_at)
+);
+```
+
+## 数据保留与归档
+
+> [!warning] activitylog 表会快速增长
+> 每次高敏操作 1 条 + 收款 / 创建 / 编辑等可能也加 → 数据增长快。
+>
+> 建议:
+>
+> - **生产环境**:保留 1-3 年热数据(查询性能优)
+> - **冷数据归档**:超 1 年的迁到 archive 表 / 对象存储
+> - **永久保留**:某些事件(bulk_deleted / voided)**法定 7+ 年**
+>
+> 当前未实施归档,数据量大后需要运维介入。
+
+## 常见问题
+
+> [!question] activitylog 与 meta JSON 的关系?
+> 互补:
+>
+> | 方面 | activitylog | meta JSON |
+> |---|---|---|
+> | 保留多久 | 全平台共表(易归档)| 与对象同存(无法独立归档)|
+> | 查询性能 | 按时间 / 类型查快 | 在对象上 random access 快 |
+> | 关联多个对象 | ✅(properties 数组) | ❌(只在自己 meta)|
+> | 跨模块查询 | ✅ | ❌(各模块字段不同)|
+> | 操作上下文 | ✅(causer_id 直接)| ❌(若没存)|
+>
+> 推荐:meta 存"对象当前状态的辅助"(如 voided_at);activitylog 存"事件链"(谁干了什么)。两者不冲突。
+
+> [!question] 业务人员如何看 activitylog?
+> 当前**没有 UI**(spatie 包提供数据存储,UI 需自建)。审计师 / 业务方查询:
+>
+> - 直接 SQL(本场景示范)
+> - 让运维查 / 出导出
+> - 未来加 `ActivityLogResource` Filament UI(优先级看需求)
+
+> [!question] activitylog 能改 / 删吗?
+> 系统层面**理论上可改**(就是普通表)。**合规上不应改**(篡改审计 = 大罪)。
+>
+> 高级实施:用**append-only**表(数据库层面 disallow UPDATE/DELETE)+ 定期写校验和(若数据被改可发现)。当前未实施。
+
+> [!question] 跨模块审计能合并查吗?
+> 可以(activitylog 是全平台共表)。但其他模块当前**没启用 activitylog**(用 meta),所以跨模块审计**目前只看 bill 模块**。未来若其他模块启用,可统一查。
+
+> [!question] activitylog 与系统日志(Laravel log)的差异?
+> | 维度 | activitylog | Laravel log |
+> |---|---|---|
+> | 内容 | 业务事件(带 subject / causer / properties) | 技术日志(error / debug / info)|
+> | 持久化 | 数据库 | 文件 / 集中日志服务 |
+> | 业务查询 | ✅ 结构化,SQL 查 | ❌ 全文搜索 |
+> | 合规价值 | **高** | 低(辅助排错)|
+>
+> 两者并存,各管各的。activitylog 关注**业务操作**,Laravel log 关注**系统行为**。
+
+## 异常分支
+
+- 发现疑似篡改 → 物业内部审计 + 法务介入
+- 数据量太大查询慢 → 归档老数据
+- 业户申请查 activitylog → 出报告(由审计师 / 法务出)
+- 长期审计需求 → 加 `ActivityLogResource` UI(未来扩展)
+
+## 相关文档
+
+- [[smart-bulk-delete-design]](核心 activitylog 设计)
+- [[delete-vs-void-dual-track]]
+- [[bulk-delete-batch-mistake]]
+- [[void-paid-bill]]
+- [[suspend-bill]]
+- [[resume-bill]]
+- [[audit-monthly-billing-vs-collection]]
--- a/prop-acc/scenarios/billing/audit-monthly-billing-vs-collection.md
+++ b/prop-acc/scenarios/billing/audit-monthly-billing-vs-collection.md
@@ -0,0 +1,294 @@
+---
+title: prop-acc · billing · 场景 - 月度账单生成 vs 收款对比
+aliases:
+  - 账单 vs 收款对比
+  - MonthlyBillingVsCollectionChart
+  - 收款率
+  - audit-monthly-billing-vs-collection
+  - 场景-月度账单收款对比
+tags:
+  - 场景
+  - prop-acc
+  - 账单
+  - 审计
+audience:
+  - 业务人员
+  - 财务
+  - 管理层
+status: 已发布
+sub_feature: billing
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 场景:月度账单生成 vs 收款对比
+
+物业**月度报表**核心指标 —— **本月生成多少账单 vs 本月收到多少款**。`MonthlyBillingVsCollectionChart` Widget 直观对比。是评估**收款率 / 应收账款健康度**的标准动作。
+
+## 典型情境
+
+> [!example] 真实情境
+> 5 月底,王主管打开 dashboard 看 `MonthlyBillingVsCollectionChart`:
+>
+> - 本月生成账单:¥120,000(300 户 × 平均 ¥400)
+> - 本月已收款:¥95,000
+> - **收款率:79.2%**
+> - **应收账款增长**:¥25,000(120 - 95)
+>
+> 与 4 月对比:
+> - 4 月生成:¥118,000,4 月收:¥110,000(93.2%)
+> - **5 月收款率下降 14%**,需排查原因
+
+## Widget 显示
+
+`MonthlyBillingVsCollectionChart`(在 BillingDashboard 或主 Dashboard):
+
+```
+2026 年月度账单 vs 收款对比图
+
+         |  生成  |  收款  | 收款率
+2026-01  | 120k   | 115k   | 95.8%
+2026-02  | 119k   | 117k   | 98.3%
+2026-03  | 121k   | 113k   | 93.4%
+2026-04  | 118k   | 110k   | 93.2%
+2026-05  | 120k   |  95k   | 79.2%  ⚠️ 异常
+
+(柱状图)
+```
+
+可下钻看:
+
+- 按费用类型分布(物业费 vs 水电气 vs 临时)
+- 按业户类别(住宅 vs 商铺)
+- 按收款方式(现金 / 微信 / 预存款抵 / 其他)
+- 逾期账单累计金额
+
+## 业务人员视角
+
+### 第 1 步:看 Widget
+
+每月初(5/1-5/3)看上月数据。
+
+### 第 2 步:对比历史
+
+| 月份 | 收款率 | 趋势 |
+|---|---|---|
+| 4 月 | 93.2% | 平稳 |
+| 3 月 | 93.4% | 平稳 |
+| 2 月 | 98.3% | 高 |
+| 1 月 | 95.8% | 高 |
+| **5 月** | **79.2%** | **断崖** |
+
+5 月异常,需要排查。
+
+### 第 3 步:排查原因
+
+可能原因:
+
+| 原因 | 排查方式 |
+|---|---|
+| **逾期账单激增** | 看 `OverdueBillsListWidget`,看 5 月逾期累计 |
+| **某费用类型收款率低** | 按费用类型下钻 |
+| **某社区收款率低** | 多社区时按社区下钻 |
+| **某收款渠道异常** | 看渠道分布,例如微信掉单 |
+| **季节性**(例如春节后回流缓)| 与去年同月对比 |
+| **集抄数据异常**(导致账单虚高)| 看 [[../meter/exception-high-consumption]] |
+| **业务方调整 RatePlan**(账单变高,业户抗拒)| 看 RatePlan 变更日志 |
+
+### 第 4 步:出月度报告
+
+给物业总经理 / 财务总监:
+
+```markdown
+# 2026 年 5 月 嘉禾花园收款月报
+
+## 总览
+- 应收账款生成:¥120,000(300 户)
+- 实际收款:¥95,000
+- 收款率:79.2%(同比 -14% / 环比 -14%)
+
+## 异常分析
+- 主要原因:5 月物业费 RatePlan 上调(¥3 → ¥3.5),业户抗拒
+- 60 户拒绝按新价付,只付旧价部分 → Partial 状态激增
+- 业主大会沟通中,预计 6 月底有结果
+
+## 已采取措施
+- 暂停涨价部分的催收(挂起 60 户的差额账单)
+- 6 月初业主大会重新讨论
+
+## 预测
+- 6 月若按新价确认,收款率回升 90%+
+- 6 月若需妥协 → 走批量作废涨价部分 + 重建按旧价
+
+## 资金影响
+- 应收账款余额从 4 月底 ¥35,000 升至 5 月底 ¥60,000
+- 风险:占用物业现金流 + 6 月人员工资 / 维修 可能紧张
+```
+
+## SQL 报表查询
+
+### 本月生成账单总额
+
+```sql
+SELECT SUM(amount) AS billed_total
+FROM acc_bills
+WHERE community_id = ?
+  AND billing_period_start BETWEEN '2026-05-01' AND '2026-05-31'
+  AND status != 'void';
+```
+
+### 本月收款总额
+
+```sql
+SELECT SUM(actual_amount) AS collected_total
+FROM acc_collection_orders
+WHERE community_id = ?
+  AND collection_type = 'Bill'
+  AND status = 'completed'
+  AND completed_at BETWEEN '2026-05-01' AND '2026-05-31 23:59:59';
+```
+
+### 收款率
+
+```sql
+-- 本月生成的账单的本月收款率(注意:可能本月生成的下月才付,本月也可能付上月生成的)
+-- 标准公式:本月收款总额 / 本月生成总额
+```
+
+更精准的"本月生成 → 本月收"对比需要 join,看具体业务定义。
+
+### 按费用类型分布
+
+```sql
+SELECT
+    ft.name AS fee_type,
+    SUM(b.amount) AS billed,
+    SUM(b.paid_amount) AS paid,
+    SUM(b.amount - b.paid_amount) AS outstanding,
+    ROUND(SUM(b.paid_amount) * 100.0 / NULLIF(SUM(b.amount), 0), 2) AS rate_pct
+FROM acc_bills b
+JOIN fee_types ft ON b.fee_type_id = ft.id
+WHERE b.community_id = ?
+  AND b.billing_period_start BETWEEN '2026-05-01' AND '2026-05-31'
+  AND b.status != 'void'
+GROUP BY ft.name
+ORDER BY billed DESC;
+```
+
+返回:
+
+| fee_type | billed | paid | outstanding | rate_pct |
+|---|---|---|---|---|
+| 物业费 | 100,000 | 75,000 | 25,000 | 75.0% |
+| 水费 | 8,000 | 7,500 | 500 | 93.8% |
+| 电费 | 10,000 | 9,500 | 500 | 95.0% |
+| 燃气 | 2,000 | 1,950 | 50 | 97.5% |
+| 杂费 | 0 | 0 | 0 | N/A |
+
+立刻能看出**物业费是问题**(其他费用收款率 90%+)。
+
+## 关联 Widgets
+
+| Widget | 用途 |
+|---|---|
+| **`MonthlyBillingVsCollectionChart`**(本场景)| 整体趋势 |
+| `BillingStatsOverviewWidget` | 总数 + 总额 + 收款率快照 |
+| `FeeTypeRevenueDistributionChart` | 按费用类型分布(饼图)|
+| `OverdueBillsListWidget` | 逾期清单 |
+| `MonthlyRevenueTrendChart` | 月度收入趋势(长期看 12 月)|
+
+业务人员**月初看一圈**:整体 → 类别 → 逾期 → 长期趋势。
+
+## 业户视角
+
+业户**不直接看这种报表**。但物业**可能公布**(透明化):
+
+- 业主大会汇报"上月物业费收款率 X%"
+- 在小区公告栏公示
+- 在业主群发月度总结
+
+收款率高 → 业户感觉"物业团结" 反之有疑虑。
+
+## 财务视角
+
+### 财务关心的核心指标
+
+| 指标 | 目标 | 含义 |
+|---|---|---|
+| **收款率** | > 90%(目标 95%+)| 月度收款 / 月度账单 |
+| **应收账款余额** | < 2 个月账单合计 | 累计欠款,反映现金流压力 |
+| **逾期账单占比** | < 10% | 长期不付的比例 |
+| **平均逾期天数** | < 30 | 收款时效 |
+
+### 与会计核算的衔接
+
+billing 报表与会计科目映射:
+
+| 报表项 | 会计科目 |
+|---|---|
+| 本月生成账单总额 | "应收账款"(借方)+ "营业收入"(贷方,权责发生制) |
+| 本月收款总额 | "现金 / 银行存款"(借方)+ "应收账款"(贷方) |
+| 应收账款余额 | "应收账款"账户余额 |
+
+报表为财务月度结账提供数据。
+
+## 趋势分析
+
+```mermaid
+xychart-beta
+    title "嘉禾花园 6 个月账单 vs 收款"
+    x-axis [Jan, Feb, Mar, Apr, May]
+    y-axis "金额(千元)" 0 --> 150
+    bar [120, 119, 121, 118, 120]
+    line [115, 117, 113, 110, 95]
+```
+
+异常点(5 月)立刻可见。趋势线告诉管理层何时介入。
+
+## 常见问题
+
+> [!question] 收款率多低算异常?
+> 看历史基线 + 行业标准:
+> - 健康物业:90%+
+> - 一般物业:80-90%
+> - 问题物业:< 80%
+>
+> 单月波动 5-10% 正常(春节后 / 大额账单后);连续 2-3 月低于基线 = 严重问题。
+
+> [!question] 本月生成的账单本月没付完算异常吗?
+> 不一定。账单 due_at 通常是月底 + 宽限期(到下月中旬)。**本月内付清率 < 100% 是常态**。重要的是**到期前付清率**。
+
+> [!question] 报表数据与银行账户对账不一致怎么办?
+> 排查:
+> - 是否有 CO 状态 = Completed 但银行未到账(在途资金)
+> - 是否有 CO 创建错(状态 Failed 但 amount 异常)
+> - 是否有 fund_source=prepaid 的(账面收款但银行没动)
+> - 是否有手工调账 / tinker 操作
+
+> [!question] Widget 数据**慢**怎么办?
+> 大数据量(100k+ 账单)时 SQL 可能慢。优化:
+> - 加索引(`community_id`, `billing_period_start`, `status`)
+> - 用物化视图(定时刷新)
+> - 引入 OLAP 工具(BI dashboard 专门处理)
+>
+> 当前数据量不大,Widget 直接 SQL 应能秒级出。
+
+> [!question] 多社区合并看怎么办?
+> Widget 通常按当前 Panel 的 community_id 过滤。**多社区合并**需要管理 Panel 角色(无社区限制)+ Widget 显示总览(可下钻到具体社区)。
+
+## 异常分支
+
+- 收款率低 + 逾期多 → 走 [[exception-overdue-bills|催收]]
+- 单业户 Partial 多 → [[exception-partial-payment|跟进部分付]]
+- 收款率异常(数据 bug)→ [[audit-activitylog-trace|查 activitylog]] 排查异常操作
+- 长期低收款率 → 业务方反思 RatePlan / 服务质量
+
+## 相关文档
+
+- [[exception-overdue-bills]]
+- [[exception-partial-payment]]
+- [[audit-activitylog-trace]]
+- [[bill-six-state-machine]]
+- [[bill-vs-collection-order]]
+- [[../prepaid/audit-low-balance-and-overdue]]
+- [[../deposit/audit-monthly-deposit-balance]]
--- a/prop-acc/scenarios/billing/exception-overdue-bills.md
+++ b/prop-acc/scenarios/billing/exception-overdue-bills.md
@@ -0,0 +1,242 @@
+---
+title: prop-acc · billing · 场景 - 逾期账单清单 + 催收流程
+aliases:
+  - 逾期账单
+  - 催收
+  - OverdueBillsListWidget
+  - exception-overdue-bills
+  - 场景-逾期账单催收
+tags:
+  - 场景
+  - prop-acc
+  - 账单
+  - 催收
+audience:
+  - 业务人员
+  - 财务
+  - 业户
+status: 已发布
+sub_feature: billing
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 场景:逾期账单清单 + 催收流程
+
+业户**到期未付**的账单进入逾期清单(`OverdueBillsListWidget`),业务人员**分级催收**:温和提醒 → 严肃催告 → 法律手段。是物业**应收账款管理**的核心。
+
+## 典型情境
+
+> [!example] 真实情境
+> 5 月 16 日(物业费 due_at = 5/15 后第 1 天),王主管打开 dashboard:
+>
+> - `OverdueBillsListWidget` 显示**当前逾期 25 户**(本月物业费 + 部分上月遗留)
+> - 合计欠款 ¥18,500
+> - 平均逾期天数 1-30 天不等
+
+## 业务人员视角
+
+### 第 1 步:打开 Dashboard / Widget
+
+后台 → Dashboard → `OverdueBillsListWidget`(可能在主 Dashboard 或财务 Dashboard)。
+
+Widget 显示:
+
+| 列 | 内容 |
+|---|---|
+| 业户 / 房号 | 12-3-501 张阿姨 |
+| 账单号 | B-202605-501-001 |
+| 费用类型 | 物业费 / 水费 / ... |
+| 账单金额 | ¥800 |
+| 已付金额 | ¥0(Unpaid)/ ¥300(Partial)|
+| 剩余应付 | ¥800 / ¥500 |
+| 到期日 | 5/15 |
+| **逾期天数** | 1 天 / 7 天 / 30 天 / ... |
+| 状态 | Unpaid / Partial |
+
+排序通常**按逾期天数降序**(最严重的先)。
+
+### 第 2 步:分级催收
+
+```mermaid
+flowchart TD
+  A[逾期账单清单] --> B{逾期天数}
+
+  B -->|1-7 天<br/>🟢 温和| C[小程序 / 微信 / 短信<br/>友好提醒]
+  B -->|8-30 天<br/>🟡 严肃| D[电话联系 + 上门拜访<br/>面谈了解原因]
+  B -->|31-90 天<br/>🔴 严重| E[正式催告函<br/>+ 加收滞纳金<br/>+ 部分服务受限]
+  B -->|>90 天<br/>⚫ 法律| F[律师函 / 司法起诉<br/>+ 业户失信记录]
+
+  C --> G{业户响应}
+  D --> G
+  E --> G
+  F --> G
+
+  G -->|付款| H[走 collect-payment-single]
+  G -->|协商| I[Suspend Bill + 等协议]
+  G -->|无响应| J[升级催收]
+  G -->|拒付不可调和| K[法律 + 长期 Suspend]
+```
+
+### 第 3 步:具体催收动作
+
+#### 🟢 温和(1-7 天)
+
+- 自动 推送 / 短信(由系统定时任务,若实现)
+- "张阿姨您好,您的 5 月物业费 ¥800 已逾期,请尽快付清"
+
+#### 🟡 严肃(8-30 天)
+
+- 物业管家电话联系
+- 上门拜访(若联系不上)
+- 了解逾期原因 + 协商付款时间表
+- 若业户有困难 → [[suspend-bill|挂起]] + 协议分期
+
+#### 🔴 严重(31-90 天)
+
+- 物业法务部门介入
+- 出具正式催告函(纸质 + 电子)
+- 可加滞纳金(看物业合同 / 业主大会决议)
+- 部分服务限制(如停水电、限制电梯使用,具体看物业政策 + 法律允许度)
+
+#### ⚫ 法律(>90 天)
+
+- 委托律师事务所
+- 律师函
+- 司法起诉(物业 vs 业户)
+- 法院判决 → 强制执行
+
+### 第 4 步:更新跟进记录
+
+业务人员每次催收**在系统记录**(若有催收日志功能):
+
+- 催收时间 / 方式 / 业户反馈
+- 下次跟进时间
+
+(当前实施可能在 Bill.memo 或单独表,看代码。)
+
+## 业户视角
+
+### 您可能收到的
+
+#### 温和提醒
+
+> 张阿姨您好,您的 2026 年 5 月物业费 ¥800 已于 5/15 到期,请尽快通过以下方式付清:
+> - 微信小程序
+> - 到前台
+> - 预存款充值后自动扣
+>
+> 您预存款余额仅 ¥200,不够付。
+
+#### 严肃催告
+
+> 张阿姨,您 5 月物业费 ¥800 已逾期 15 天,请于本周内付清。如有困难请联系物业 XXX 协商。
+
+#### 严重催告
+
+> [正式催告函]
+> 您 2026 年 5 月物业费 ¥800 已严重逾期 60 天,根据物业管理合同第 X 条,我司将:
+> 1. 加收滞纳金 ¥XX
+> 2. 限制您的部分物业服务
+> 3. 若 X 月 X 日前仍未付清,我司将启动法律程序追讨
+>
+> 请尽快处理。
+
+### 您要做什么
+
+- 立即付款(若能力允许)
+- 与物业协商(若有困难)
+- **不要** 不闻不问(代价升级)
+
+## 滞纳金 / 罚息
+
+> [!info] 滞纳金的合规边界
+> 物业能否收滞纳金看:
+> - 物业管理合同条款(常见日利率 0.05% 或类似)
+> - 业主大会决议
+> - 国家 / 地方法规(不能高于法定上限)
+>
+> 系统层面**可能不直接管滞纳金**(看实现)。若收滞纳金 → 通常**另开账单**(走 [[create-single-bill-manual]])"滞纳金:¥X(5 月物业费逾期 X 天)"。
+
+## 部分服务限制的合规
+
+物业**限制服务**(停水电 / 限电梯)需谨慎:
+
+| 限制 | 合规性 |
+|---|---|
+| 限制小程序业户自助功能(查询 / 报修) | 合规(物业自主决定)|
+| 拒绝业户业务申请(开停车证等)| 合规 |
+| 停水(若物业有控制权)| 多数地区**不合规**(基本生活用水有法律保护)|
+| 停电 | 同上,且通常电网在国家电网,物业无权停 |
+| 限制电梯使用 | 部分地区合规,部分不合规 |
+| 公布逾期业户名单 | 部分合规(看公开范围 + 业主大会决议)|
+
+**严格合规咨询当地法律**。系统**不强制**这些限制,由物业流程决定。
+
+## 长期逾期的处理
+
+| 时长 | 处置 |
+|---|---|
+| 0-30 天 | 常规催收 |
+| 30-90 天 | 升级催收 + 必要时 [[suspend-bill|挂起]] |
+| 90+ 天 | 法律程序 + 长期挂起 |
+| > 2 年 | 评估**作废 / 走司法判决执行** |
+| > 5 年(诉讼时效)| 法律时效问题,通常作废 |
+
+## 与 prepaid 模块的关系
+
+如果业户**预存款够付** 但因故没自动抵扣(job 没跑 / 业户冻结 / 跨社区) → 账单逾期。**典型案例**:[[../prepaid/audit-low-balance-and-overdue]] 场景中提到。
+
+业务人员看到逾期账单时,应先查业户预存款余额:
+
+- 足够付:**手动触发** [[collect-via-prepaid-auto]] 抵扣(快速解决)
+- 不够付:走标准催收
+
+## 自动催收 job(待补)
+
+> [!info] 自动化机会
+> 当前催收**靠人工**(看 widget + 一一联系)。可加自动化:
+>
+> - **定时任务**:每天扫逾期账单 → 按逾期天数分级 → 自动推送 / 短信
+> - **滞纳金自动计算**:每日跑 → 给逾期账单加滞纳金
+> - **批量催告函生成**:选中 N 个业户 → 一次生成所有催告函(PDF / 邮件)
+>
+> 当前 issue.md 未明确实施。
+
+## 常见问题
+
+> [!question] Widget 上的逾期天数怎么算?
+> `(NOW() - bill.due_at).days`(SQL 层算)。若 due_at 还没到 → 不在 widget。
+
+> [!question] Suspended 状态的账单算逾期吗?
+> **不算**。Widget 通常过滤 `status IN (Unpaid, Partial)`,Suspended 不在。
+
+> [!question] 业户付了一部分但仍逾期算不算?
+> Partial 状态 + 仍欠款 + 过 due_at = 算逾期。Widget 显示"剩余应付"。
+
+> [!question] 滞纳金怎么记账?
+> 单独建账单(`bill_type=OneTime`,`fee_type=滞纳金`)。详见 [[create-single-bill-manual]] "情境 2:违规罚款" 模式(滞纳金类似)。
+
+> [!question] 业户长期失联,催收记录怎么留?
+> 物业内部催收日志(纸质 / Excel)。系统层面无强制要求(若 issue.md 未实现催收日志功能)。法律纠纷时这些日志是关键证据。
+
+> [!question] 业主大会决议某些业户免缴怎么办?
+> 业务上:走 [[void-paid-bill|作废]] 该账单(附决议号)。系统层面不区分"免缴"vs"其他作废"(都是 Void 状态)。
+
+## 异常分支
+
+- 业户响应付款 → [[collect-payment-single]]
+- 业户协商分期 → [[exception-partial-payment]]
+- 业户失联 → [[suspend-bill]]
+- 法律手段 → 走线下,系统记录 + [[void-paid-bill]]
+- 业户预存款够付 → [[collect-via-prepaid-auto]] 手动触发
+
+## 相关文档
+
+- [[bill-six-state-machine]]
+- [[exception-partial-payment]]
+- [[suspend-bill]]
+- [[void-paid-bill]]
+- [[collect-payment-single]]
+- [[collect-via-prepaid-auto]]
+- [[../prepaid/audit-low-balance-and-overdue]](类似的预警审计场景)