From 7cdf0ec9a4482b9ca1411f8430abfe4343580383 Mon Sep 17 00:00:00 2001 From: Willie Date: Tue, 26 May 2026 01:18:18 +0800 Subject: [PATCH] vault backup: 2026-05-26 01:18:18 --- .obsidian/workspace.json | 6 +- .../billing/audit-activitylog-trace.md | 311 ++++++++++++++++++ .../audit-monthly-billing-vs-collection.md | 294 +++++++++++++++++ .../billing/exception-overdue-bills.md | 242 ++++++++++++++ 4 files changed, 850 insertions(+), 3 deletions(-) create mode 100644 prop-acc/scenarios/billing/audit-activitylog-trace.md create mode 100644 prop-acc/scenarios/billing/audit-monthly-billing-vs-collection.md create mode 100644 prop-acc/scenarios/billing/exception-overdue-bills.md diff --git a/.obsidian/workspace.json b/.obsidian/workspace.json index c867517..1577ca6 100644 --- a/.obsidian/workspace.json +++ b/.obsidian/workspace.json @@ -197,6 +197,9 @@ }, "active": "849c5ff8936a2b67", "lastOpenFiles": [ + "prop-acc/scenarios/billing/audit-activitylog-trace.md", + "prop-acc/scenarios/billing/audit-monthly-billing-vs-collection.md", + "prop-acc/scenarios/billing/exception-overdue-bills.md", "prop-acc/scenarios/billing/exception-partial-payment.md", "prop-acc/scenarios/billing/bulk-delete-batch-mistake.md", "prop-acc/scenarios/billing/void-paid-bill.md", @@ -222,9 +225,6 @@ "prop-acc/scenarios/meter/audit-meters-needing-reading.md", "prop-acc/scenarios/meter/exception-readings-locked-after-bill.md", "prop-acc/scenarios/meter/exception-high-consumption.md", - "prop-acc/scenarios/meter/generate-bill-min-max-cap.md", - "prop-acc/scenarios/meter/generate-bill-with-multiplier.md", - "prop-acc/scenarios/meter/generate-bill-tiered-pricing.md", "prop-acc/scenarios/meter", "prop-acc/concepts/meter", "prop-acc/scenarios/prepaid", diff --git a/prop-acc/scenarios/billing/audit-activitylog-trace.md b/prop-acc/scenarios/billing/audit-activitylog-trace.md new file mode 100644 index 0000000..ad8b8a3 --- /dev/null +++ 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]] diff --git a/prop-acc/scenarios/billing/audit-monthly-billing-vs-collection.md b/prop-acc/scenarios/billing/audit-monthly-billing-vs-collection.md new file mode 100644 index 0000000..bdac082 --- /dev/null +++ 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]] diff --git a/prop-acc/scenarios/billing/exception-overdue-bills.md b/prop-acc/scenarios/billing/exception-overdue-bills.md new file mode 100644 index 0000000..2c69ef0 --- /dev/null +++ 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 天
🟢 温和| C[小程序 / 微信 / 短信
友好提醒] + B -->|8-30 天
🟡 严肃| D[电话联系 + 上门拜访
面谈了解原因] + B -->|31-90 天
🔴 严重| E[正式催告函
+ 加收滞纳金
+ 部分服务受限] + B -->|>90 天
⚫ 法律| F[律师函 / 司法起诉
+ 业户失信记录] + + 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]](类似的预警审计场景)