vault backup: 2026-05-26 01:23:19

写 16 个场景到 prop-acc/scenarios/billing/,覆盖 5 类业务:

📝 账单创建(3):
- create-periodic-property-fee(月度物业费 300 户批量,SkipExisting 默认策略)
- create-meter-bill-auto(抄表自动生成计量账单,与 meter pipeline 衔接)
- create-single-bill-manual(电梯维修分摊 / 罚款 / 跨期补开 三典型情境)

💰 收款(3):
- collect-payment-single(单张收款,Modal + 数据示例 + 部分付场景)
- collect-payment-batch(同业户多账单一次收款,1 个 CO + N 个 COBill)
- collect-via-prepaid-auto(billing × prepaid 跨模块联动,fund_source=prepaid)

✂️ 账单调整(3):
- split-bill(房东/租户分摊场景,SplitBillAction 全转/部分拆模式)
- suspend-bill(纠纷/失联 SuspendBillAction,与 Unpaid/Partial 状态守护)
- resume-bill(智能恢复 Unpaid / Partial,suspend_history 数组设计)

🗑️ 删除 / 作废(3):
- delete-bill-unpaid(物理删 canBeDeleted=Unpaid+无付款,activitylog 留 bill_no)
- void-paid-bill(Partial 作废可用 + Paid 作废需手工/tinker 流程的局限)
- bulk-delete-batch-mistake(智能批删 Modal 三档分类 + 完整 activitylog 实战)

🛡️ 异常 / 审计(4):
- exception-partial-payment(Partial 状态完整生命周期 + 多次补付流水)
- exception-overdue-bills(OverdueBillsListWidget + 分级催收 +
  滞纳金合规 + 服务限制合规边界)
- audit-monthly-billing-vs-collection(收款率核心指标 + SQL 报表 +
  与会计科目映射)
- audit-activitylog-trace(spatie activitylog 实战查询 +
  与 meta JSON 对比 + 跨模块审计 + 法务用途)

每篇结构:典型情境 → 业户/业务/财务/审计视角 → 系统流程(mermaid) →
SQL 报表 / 数据示例 → 常见问题 → 异常分支 → 相关文档(WikiLinks)。

billing 独特设计在场景中持续强调:
- 6 状态机的状态流转(Unpaid → Partial → Paid;Suspended ↔ Unpaid;Void 终态)
- 多对多关联(CollectionOrderBill 中间表 + allocated_amount 语义)
- 删 vs 作废双轨制(双层守护 + 业务场景区分)
- 智能批删 Modal(预检查三档分类 + 必填原因 + 单条 activitylog 含 affected_bill_nos)
- spatie activitylog 审计(properties JSON 跨模块查询)
- 跨子模块联动(meter → billing,prepaid → billing,billing → CollectionOrder)

收尾:
- prop-acc/maps/billing-knowledge-map.md:16 场景全部 ✅
- prop-acc/maps/knowledge-map.md:billing 行状态改 "✅ 23 篇"
- prop-acc/index.md:同步

billing 子模块完整覆盖:6 概念 + 16 场景 + 1 知识地图 = 23 篇。

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.obsidian/workspace.json

@@ -13,12 +13,12 @@
             "state": {
               "type": "markdown",
               "state": {
-                "file": "prop-acc/scenarios/prepaid/deposit-first-time.md",
+                "file": "prop-acc/maps/billing-knowledge-map.md",
                 "mode": "source",
                 "source": false
               },
               "icon": "lucide-file",
-              "title": "deposit-first-time"
+              "title": "billing-knowledge-map"
             }
           }
         ]
@@ -94,7 +94,7 @@
             "state": {
               "type": "backlink",
               "state": {
-                "file": "prop-acc/scenarios/prepaid/deposit-first-time.md",
+                "file": "prop-acc/maps/billing-knowledge-map.md",
                 "collapseAll": false,
                 "extraContext": false,
                 "sortOrder": "alphabetical",
@@ -104,7 +104,7 @@
                 "unlinkedCollapsed": true
               },
               "icon": "links-coming-in",
-              "title": "Backlinks for deposit-first-time"
+              "title": "Backlinks for billing-knowledge-map"
             }
           },
           {
@@ -113,12 +113,12 @@
             "state": {
               "type": "outgoing-link",
               "state": {
-                "file": "prop-acc/scenarios/prepaid/deposit-first-time.md",
+                "file": "prop-acc/maps/billing-knowledge-map.md",
                 "linksCollapsed": false,
                 "unlinkedCollapsed": true
               },
               "icon": "links-going-out",
-              "title": "Outgoing links from deposit-first-time"
+              "title": "Outgoing links from billing-knowledge-map"
             }
           },
           {
@@ -156,13 +156,13 @@
             "state": {
               "type": "outline",
               "state": {
-                "file": "prop-acc/scenarios/prepaid/deposit-first-time.md",
+                "file": "prop-acc/maps/billing-knowledge-map.md",
                 "followCursor": false,
                 "showSearch": false,
                 "searchQuery": ""
               },
               "icon": "lucide-list",
-              "title": "Outline of deposit-first-time"
+              "title": "Outline of billing-knowledge-map"
             }
           },
           {
@@ -195,8 +195,27 @@
       "obsidian-git:Open Git source control": false
     }
   },
-  "active": "849c5ff8936a2b67",
+  "active": "b06ed69835363258",
   "lastOpenFiles": [
+    "prop-acc/index.md",
+    "prop-acc/scenarios/prepaid/deposit-first-time.md",
+    "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",
+    "prop-acc/scenarios/billing/delete-bill-unpaid.md",
+    "prop-acc/scenarios/billing/resume-bill.md",
+    "prop-acc/scenarios/billing/suspend-bill.md",
+    "prop-acc/scenarios/billing/split-bill.md",
+    "prop-acc/scenarios/billing/collect-via-prepaid-auto.md",
+    "prop-acc/scenarios/billing/collect-payment-batch.md",
+    "prop-acc/scenarios/billing/collect-payment-single.md",
+    "prop-acc/scenarios/billing/create-single-bill-manual.md",
+    "prop-acc/scenarios/billing/create-meter-bill-auto.md",
+    "prop-acc/scenarios/billing/create-periodic-property-fee.md",
+    "prop-acc/scenarios/billing",
     "prop-acc/maps/billing-knowledge-map.md",
     "prop-acc/concepts/billing/smart-bulk-delete-design.md",
     "prop-acc/concepts/billing/delete-vs-void-dual-track.md",
@@ -206,32 +225,13 @@
     "prop-acc/concepts/billing/bill-six-state-machine.md",
     "prop-acc/concepts/billing",
     "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/read-with-photo-proof.md",
-    "prop-acc/scenarios/meter/read-via-iot-remote-source.md",
-    "prop-acc/scenarios/meter/read-batch-via-excel-import.md",
-    "prop-acc/scenarios/meter/read-single-meter-manual.md",
-    "prop-acc/scenarios/meter/decommission-without-replacement.md",
-    "prop-acc/scenarios/meter/replace-broken-meter.md",
-    "prop-acc/scenarios/meter/register-single-meter.md",
-    "prop-acc/scenarios/meter/init-new-community-batch.md",
     "prop-acc/scenarios/meter",
-    "prop-acc/maps/meter-knowledge-map.md",
-    "prop-acc/concepts/meter/decommission-and-locking.md",
-    "prop-acc/concepts/meter/reading-source-and-photo-proof.md",
-    "prop-acc/concepts/meter/bill-generation-pipeline.md",
-    "prop-acc/concepts/meter/multiplier-and-tiered-pricing.md",
     "prop-acc/concepts/meter",
     "prop-acc/scenarios/prepaid",
     "prop-acc/concepts/prepaid",
     "prop-acc/scenarios/deposit",
     "prop-acc/concepts/deposit",
     "prop-acc/scenarios/adhoc",
-    "prop-acc/concepts/adhoc",
+    "prop-acc/concepts/adhoc"
-    "resident-portal/scenarios"
   ]
 }

prop-acc/index.md

@@ -27,7 +27,7 @@ last_review: 2026-05-25
 | **保证金**   | 装修押金等代管资金,完工后退还  | [deposit 知识地图](maps/deposit-knowledge-map.md) | ✅ 25 篇 |
 | **预存款**   | 业户预存,自动抵扣月度账单    | [prepaid 知识地图](maps/prepaid-knowledge-map.md) | ✅ 23 篇 |
 | **计量表**   | 水表/电表/燃气表,抄表生成账单 | [meter 知识地图](maps/meter-knowledge-map.md)    | ✅ 21 篇 |
-| **账单**    | 周期性账单 + 计量账单     | [billing 知识地图](maps/billing-knowledge-map.md) | 🟡 6 概念已完成,16 场景待补 |
+| **账单**    | 周期性账单 + 计量账单     | [billing 知识地图](maps/billing-knowledge-map.md) | ✅ 23 篇 |
 | **收款订单**  | 一次收款的支付方式、银行账户记录 | _待补_                                          | 🚧     |
 | **收据**    | 成功收款后生成的凭证       | _待补_                                          | 🚧     |
 

prop-acc/maps/billing-knowledge-map.md

@@ -60,40 +60,38 @@ code_version: 2026-05-22
 | [删除 vs 作废双轨制](../concepts/billing/delete-vs-void-dual-track.md) | 物理删(Unpaid 无付款)vs 作废(留状态留审计)的设计哲学 |
 | [智能批量删除设计](../concepts/billing/smart-bulk-delete-design.md) | 预检查三档分类 + 必填原因 + activitylog 完整审计 |
 
-## 场景手册(16 篇,**待补充 ✋**)
+## 场景手册(16 篇,**全部完成 ✅**)
-
-> 🚧 概念骨架已就位,场景文档将在下一轮(轮 2)产出。预定结构如下。
 
 ### 📝 账单创建(3 篇)
 
-- 🚧 [月度物业费批量生成(`GeneratePeriodicBillsAction`)](../scenarios/billing/create-periodic-property-fee.md)
+- ✅ [月度物业费批量生成(`GeneratePeriodicBillsAction`)](../scenarios/billing/create-periodic-property-fee.md)
-- 🚧 [抄表自动生成计量账单(走 meter pipeline)](../scenarios/billing/create-meter-bill-auto.md)
+- ✅ [抄表自动生成计量账单(走 meter pipeline)](../scenarios/billing/create-meter-bill-auto.md)
-- 🚧 [手动建单(临时收费 / 调整账单)](../scenarios/billing/create-single-bill-manual.md)
+- ✅ [手动建单(临时收费 / 调整账单)](../scenarios/billing/create-single-bill-manual.md)
 
 ### 💰 收款(3 篇)
 
-- 🚧 [单张账单收款(`CollectPaymentAction`)](../scenarios/billing/collect-payment-single.md)
+- ✅ [单张账单收款(`CollectPaymentAction`)](../scenarios/billing/collect-payment-single.md)
-- 🚧 [同业户多账单批量收款(`BatchCollectPaymentAction`)](../scenarios/billing/collect-payment-batch.md)
+- ✅ [同业户多账单批量收款(`BatchCollectPaymentAction`)](../scenarios/billing/collect-payment-batch.md)
-- 🚧 [预存款抵扣自动收款(关联 prepaid)](../scenarios/billing/collect-via-prepaid-auto.md)
+- ✅ [预存款抵扣自动收款(关联 prepaid)](../scenarios/billing/collect-via-prepaid-auto.md)
 
 ### ✂️ 账单调整(3 篇)
 
-- 🚧 [拆账单(`SplitBillAction`,租户与房东分摊)](../scenarios/billing/split-bill.md)
+- ✅ [拆账单(`SplitBillAction`,租户与房东分摊)](../scenarios/billing/split-bill.md)
-- 🚧 [挂起账单(业户失联 / 纠纷)](../scenarios/billing/suspend-bill.md)
+- ✅ [挂起账单(业户失联 / 纠纷)](../scenarios/billing/suspend-bill.md)
-- 🚧 [恢复挂起的账单](../scenarios/billing/resume-bill.md)
+- ✅ [恢复挂起的账单](../scenarios/billing/resume-bill.md)
 
 ### 🗑️ 删除 / 作废(3 篇)
 
-- 🚧 [物理删除未付账单(误建立刻删)](../scenarios/billing/delete-bill-unpaid.md)
+- ✅ [物理删除未付账单(误建立刻删)](../scenarios/billing/delete-bill-unpaid.md)
-- 🚧 [作废已付账单(走作废 + 退款)](../scenarios/billing/void-paid-bill.md)
+- ✅ [作废已付账单(走作废 + 退款)](../scenarios/billing/void-paid-bill.md)
-- 🚧 [批量误建,智能 Modal 三档清理](../scenarios/billing/bulk-delete-batch-mistake.md)
+- ✅ [批量误建,智能 Modal 三档清理](../scenarios/billing/bulk-delete-batch-mistake.md)
 
 ### 🛡️ 异常 / 审计(4 篇)
 
-- 🚧 [部分付状态处理(Partial)](../scenarios/billing/exception-partial-payment.md)
+- ✅ [部分付状态处理(Partial)](../scenarios/billing/exception-partial-payment.md)
-- 🚧 [逾期账单清单 + 催收(`OverdueBillsListWidget`)](../scenarios/billing/exception-overdue-bills.md)
+- ✅ [逾期账单清单 + 催收(`OverdueBillsListWidget`)](../scenarios/billing/exception-overdue-bills.md)
-- 🚧 [月度账单生成 vs 收款对比(`MonthlyBillingVsCollectionChart`)](../scenarios/billing/audit-monthly-billing-vs-collection.md)
+- ✅ [月度账单生成 vs 收款对比(`MonthlyBillingVsCollectionChart`)](../scenarios/billing/audit-monthly-billing-vs-collection.md)
-- 🚧 [activitylog 审计追溯](../scenarios/billing/audit-activitylog-trace.md)
+- ✅ [activitylog 审计追溯](../scenarios/billing/audit-activitylog-trace.md)
 
 ## 跨域引用
 
@@ -139,6 +137,9 @@ code_version: 2026-05-22
 
 ---
 
-> [!info] 概念已完成,场景待补
+> [!success] billing 子模块:6 概念 + 16 场景 + 1 知识地图 = **23 篇完成**
-> 本轮(轮 1)产出:6 个概念 + 本子模块地图 + 域总图更新。
+>
-> 下一轮(轮 2)产出:16 个场景文档,基于本知识地图骨架填充。
+> 写作日期:2026-05-26
+> 对应代码版本:2026-05-22(详见 `packages/prop-acc/issue.md` Q6 段,最详细 issue 之一)
+>
+> 如果发现遗漏的场景或需要补充的细节,告诉我,可以单独补充新文档。

prop-acc/maps/knowledge-map.md

@@ -23,7 +23,7 @@ last_review: 2026-05-25
 | prepaid | 预存款 | 业户预存,自动抵扣月度账单 | [prepaid 知识地图](prepaid-knowledge-map.md) | ✅ 16 场景 + 6 概念 + 1 地图 = 23 篇 |
 | deposit | 保证金 | 装修押金等代管资金,完工后退还 | [deposit 知识地图](deposit-knowledge-map.md) | ✅ 18 场景 + 6 概念 + 1 地图 = 25 篇 |
 | meter | 计量表 | 水表/电表/燃气表,抄表生成账单 | [meter 知识地图](meter-knowledge-map.md) | ✅ 14 场景 + 6 概念 + 1 地图 = 21 篇 |
-| billing | 账单 | 周期性账单 + 计量账单 | [billing 知识地图](billing-knowledge-map.md) | 🟡 6 概念已完成,16 场景待补 |
+| billing | 账单 | 周期性账单 + 计量账单 | [billing 知识地图](billing-knowledge-map.md) | ✅ 16 场景 + 6 概念 + 1 地图 = 23 篇 |
 | payment-order | 收款订单 | 一次收款的支付方式、银行账户记录 | _待补_ | 🚧 |
 | receipt | 收据 | 成功收款后生成的凭证 | _待补_ | 🚧 |
 

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]]

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]]

prop-acc/scenarios/billing/bulk-delete-batch-mistake.md

@@ -0,0 +1,267 @@
+---
+title: prop-acc · billing · 场景 - 批量误建,智能 Modal 三档分类清理
+aliases:
+  - 批量删除账单
+  - BulkDeleteBillsAction 实战
+  - 智能批删
+  - bulk-delete-batch-mistake
+  - 场景-批量删除账单
+tags:
+  - 场景
+  - prop-acc
+  - 账单
+  - 删除
+  - 批量
+audience:
+  - 业务人员
+  - 财务
+status: 已发布
+sub_feature: billing
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 场景:批量误建,智能 Modal 三档分类清理
+
+业务人员**误触发批量生成**(例如点了一次"生成 5 月物业费"后忘了又点了一次,导致每户有两张同样账单),需要清理。走 `BulkDeleteBillsAction` 的智能 Modal,自动按状态分三档处理。
+
+## 典型情境
+
+> [!example] 真实情境
+> 王主管 5 月 1 日上午点了"生成 5 月物业费"批量(已生成 300 张)。下午接电话被打断,**忘了之前已经生成**,又点了一次 → 系统按 `SkipExisting` 策略**全部跳过**(因为已存在)。
+>
+> **但**:王主管 Modal 没看清,选了 `Replace` 策略 → 系统 **作废原 300 张 + 重新生成 300 张** → 同业户有重复账单(状态 Void 的旧账单 + Unpaid 的新账单)。
+>
+> 业务人员发现后需清理 300 张 Void 状态的旧账单。
+
+或者:
+
+> [!example] 真实情境(更典型)
+> 业务人员手工建了 100 张维修分摊账单,分摊金额算错,需要全部清理重建。
+
+## 业务人员视角
+
+### 第 1 步:筛选要清理的账单
+
+后台 → 账单 → 列表 → 用过滤(按期次 / 状态 / 费用类型 / 生成时间)选出要清理的批。
+
+例:5 月物业费 + Void 状态 + 创建时间 today → 300 张 Void 旧账单。
+
+### 第 2 步:选中
+
+Table 上**勾选**这 300 张(全选 / 多选)。
+
+### 第 3 步:触发批量删除
+
+顶部 **"批量删除"** 按钮(`BulkDeleteBillsAction`)。
+
+> [!warning] 权限守护
+> 需要 `bill.bulkDelete` **独立高敏权限**(`Policy::deleteAny`)。普通业务人员可能没此权限,需主管 / 财务总监操作。
+>
+> 详见 [[smart-bulk-delete-design]]"权限设计"段。
+
+### 第 4 步:智能 Modal(关键)
+
+Modal 自动**预检查**所选账单 + 分三档:
+
+```
+批量删除账单 (选中 300 张)
+
+预检查统计:
+  ✅ 可删:     200 张  (Unpaid + 无付款关联)
+  ⚠️ 需作废:   50 张   (Void 已经 / Partial 已经 = 状态)
+  ❌ 跳过:      50 张   (Paid 已付 / 其他异常)
+
+请选择处理模式:
+  ⚪ 仅删除可删的(200 张物理删,100 张跳过)
+  ⚫ 删可删 + 作废需作废的(200 删 + 50 作废,50 跳过)
+
+批量操作原因(必填,审计留痕):
+[多行输入框:
+  5 月 1 日批量生成时误选 Replace 策略,
+  导致 300 张旧账单 Void。现批量清理。
+]
+
+⚠️ 注意:
+  - 物理删除不可恢复(但 activitylog 保留 bill_no)
+  - 作废不可撤销
+  - 跳过的账单不动
+
+[取消]  [确认执行]
+```
+
+### 第 5 步:选模式 + 提交
+
+业务人员看到统计,做决定:
+
+| 选 | 业务效果 |
+|---|---|
+| 仅删可删的 | 200 物理删,100 暂留(包括 50 已作废的 + 50 跳过的)|
+| 删可删 + 作废需作废 | 200 物理删,50 翻 Void(变作废),50 跳过 |
+
+填原因 → 提交。
+
+### 第 6 步:看执行结果
+
+系统返回:
+
+```
+批量操作完成:
+- 物理删除:200 张
+- 作废:50 张(若选 DeleteAndVoid)
+- 跳过:50 张
+
+详细 bill_no 见 activitylog(本次操作)。
+```
+
+## 系统流程
+
+```mermaid
+sequenceDiagram
+    participant 业务
+    participant Filament
+    participant Modal
+    participant Action[BulkDeleteBillsAction 业务层]
+    participant Activity
+    participant DB
+
+    业务->>Filament: BillsList → 选 300 张 → 批量删除
+    Filament->>Modal: 预检查(分类三档)
+    Modal->>Filament: 显示 ✅200 ⚠️50 ❌50
+
+    业务->>Modal: 选模式 + 填原因 + 提交
+    Modal->>Action: handle(bills, mode, reason, user)
+
+    Action->>Action: 再次分类(防 UI 缓存过期)
+
+    Action->>DB: 开启事务
+
+    loop 200 可删
+      Action->>DB: bill.delete()
+    end
+
+    alt mode = DeleteAndVoid
+      loop 50 可作废
+        Action->>Action: VoidBillAction.handle(bill, reason, user)
+        Action->>Activity: log voided(单条)
+      end
+    end
+
+    Action->>Activity: log bulk_deleted(总体 + affected_bill_nos 数组)
+    Action->>DB: 提交
+
+    Action-->>Filament: 结果 + 通知
+    Filament-->>业务: 显示"200 删 / 50 作废 / 50 跳过"
+```
+
+## activitylog 设计
+
+详见 [[smart-bulk-delete-design]]"activitylog 设计"段。
+
+**单条 bulk_deleted log**(批量操作只一条):
+
+```json
+{
+  "log_name": "default",
+  "subject_type": null,
+  "subject_id": null,
+  "event": "bulk_deleted",
+  "causer_id": 42,  // 王主管 ID
+  "properties": {
+    "mode": "DeleteAndVoid",
+    "reason": "5 月 1 日批量生成时误选 Replace,300 张 Void 清理",
+    "total_selected": 300,
+    "deleted_count": 200,
+    "voided_count": 50,
+    "blocked_count": 50,
+    "affected_bill_nos": [
+      "B-202605-501-001 [DELETED]",
+      "B-202605-502-001 [DELETED]",
+      ...
+      "B-202605-501-002 [VOIDED]",
+      ...
+      "B-202605-501-003 [SKIPPED]",
+      ...
+    ]
+  }
+}
+```
+
+`affected_bill_nos` 是数组,每条标记处理结果。事后可完整还原。
+
+**同时,每张被作废的 Bill 还各有一条 voided log**(VoidBillAction 内部触发,subject=bill)。
+
+## 业户视角
+
+业户**通常不感知**:
+
+- 被物理删的 200 张:业户未付款,通常未通知 → 无感
+- 被作废的 50 张:业户**可能**收到通知(看物业策略),或无感
+- 跳过的 50 张:不动,不影响
+
+**理想**:批量误建及时清理 → 业户全程无感 → 物业体面化解错误。
+
+**不理想**:清理前业户已经收到推送 + 已付款 → 跳过(Paid 不可删 / 不可作废)→ 需要走单独的"已付作废 + 退款"流程([[void-paid-bill]])。
+
+## 与单删 / 单作废的对比
+
+| 维度 | [[delete-bill-unpaid|单删]] | [[void-paid-bill|单作废]] | **智能批删(本)** |
+|---|---|---|---|
+| 一次操作多少张 | 1 | 1 | **多张(N)** |
+| 权限 | `bill.delete` | `bill.void` | **`bill.bulkDelete`(独立高敏)** |
+| 处理混合状态 | 无(只删 1 张)| 无 | **✅ 三档分类自动** |
+| activitylog | 1 条单条 | 1 条单条 | **1 条总体 + N 条单条** |
+| 业务人员效率 | 低(逐张)| 低 | **高(一次)** |
+| 业务人员风险 | 低 | 低 | **中(影响面大)** |
+
+## 常见问题
+
+> [!question] 批删的"跳过"档具体包括哪些?
+> `canBeDeleted=false && canBeVoided=false`:
+>
+> - **Paid**(已付清,无法走任何"消除"路径,需走专门退款流程)
+> - **Void**(已经作废,无需重复)
+> - **Processing**(罕见,处理中,等回调)
+>
+> 跳过的账单不动,业务人员需单独处理。
+
+> [!question] 实际执行时与 Modal 预检查不一致(其他人在中间改了)?
+> Action 内部**再次分类**(防 UI 缓存过期),实际按最新状态分。可能与 Modal 显示统计**略有差异**(但极少)。
+
+> [!question] 批删后想撤销?
+> - **物理删的**:不可恢复(数据没了)
+> - **作废的**:不可撤销(Void 终态)
+> - 唯一办法:重新创建(走 [[create-periodic-property-fee]] 或 [[create-single-bill-manual]])
+>
+> 信息可从 activitylog 还原(bill_no / amount 等)。
+
+> [!question] 批删的影响面太大会有审批吗?
+> 系统层面**无审批流**。靠**权限控制**(只主管 / 财务总监能批删)+ **必填原因**(留审计)+ **Modal 预检查统计**(让操作者看到影响面后决策)。
+>
+> 业务上若需"超过 100 张需双签",需扩展加审批 workflow。
+
+> [!question] 批删失败怎么办?
+> 事务内执行,某张失败 → 整批回滚。事务边界是**全成功或全失败**。
+>
+> 例外:`Action` 实现可能优化为"个别失败不影响其他",但破坏原子性 → 通常不推荐。
+
+> [!question] activitylog 表太多 bulk_deleted 怎么管?
+> 每次批删一条 log(总体 + affected_bill_nos)。即使 100 次批删 = 100 条 log。**不会爆表**。
+>
+> 但 voided 的子 log(每张作废一条) = 大量。批删 50 张作废 = 50 条 voided log。归档策略详见 [[smart-bulk-delete-design]]。
+
+## 异常分支
+
+- 单张删 → [[delete-bill-unpaid]]
+- 单张作废 → [[void-paid-bill]]
+- 跳过的 Paid 账单要消除 → [[void-paid-bill|Paid 作废 + 退款]](当前手工)
+- 批删后想审计 → [[audit-activitylog-trace]]
+
+## 相关文档
+
+- [[smart-bulk-delete-design]](核心概念)
+- [[delete-vs-void-dual-track]]
+- [[delete-bill-unpaid]]
+- [[void-paid-bill]]
+- [[bill-six-state-machine]]
+- [[audit-activitylog-trace]]

prop-acc/scenarios/billing/collect-payment-batch.md

@@ -0,0 +1,257 @@
+---
+title: prop-acc · billing · 场景 - 同业户多账单批量收款
+aliases:
+  - 批量收款
+  - BatchCollectPaymentAction
+  - 一次付多张
+  - collect-payment-batch
+  - 场景-同业户批量收款
+tags:
+  - 场景
+  - prop-acc
+  - 账单
+  - 收款
+audience:
+  - 业户
+  - 业务人员
+status: 已发布
+sub_feature: billing
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 场景:同业户多账单批量收款
+
+业户**本月有多张账单**(物业费 + 水电气费 + 其他),想**一次性付清**。业务人员走 `BatchCollectPaymentAction`,**一笔 CollectionOrder 关联多张 Bill**(走 CollectionOrderBill 多对多)。
+
+## 典型情境
+
+> [!example] 真实情境
+> 张阿姨本月有 4 张账单:
+>
+> | 账单 | 金额 |
+> |---|---|
+> | 5 月物业费 | ¥800 |
+> | 5 月水费 | ¥54 |
+> | 5 月电费 | ¥168 |
+> | 5 月燃气 | ¥30 |
+> | **合计** | **¥1,052** |
+>
+> 张阿姨到前台:"4 张账单我一次性付清,微信扫码"。业务人员**1 笔操作**完成 4 张账单收款。
+
+## 业户视角
+
+### 第 1 步:告诉业务人员要付哪些
+
+> "我把本月 4 张账单都付了,微信扫码"
+
+### 第 2 步:确认金额
+
+业务人员说:"4 张账单合计 ¥1,052,微信扫这个码"。
+
+### 第 3 步:微信付
+
+业户扫码 → 输密码 / 指纹 → 付 ¥1,052。
+
+### 第 4 步:拿收据
+
+可能是:
+
+- 一张 Receipt 含 4 行明细(物业费 ¥800 / 水费 ¥54 / ...)
+- 或 4 张独立 Receipt(每张账单一张)
+
+具体看实现。**业户体验上前者更好**(一张收据看全部)。
+
+## 业务人员视角
+
+### 第 1 步:找业户
+
+后台 → 业户 → 找到张阿姨 → "她的账单"标签 → 看到 4 张 Unpaid。
+
+或:后台 → 账单 → 列表 → 过滤业户=张阿姨 + 状态=Unpaid。
+
+### 第 2 步:选中多张账单
+
+Table 上勾选 4 张账单 → 顶部 **"批量收款"** 按钮(`BatchCollectPaymentAction`)。
+
+或:后台 → 业户视图 → "批量收款"(若 UI 支持单业户聚合)。
+
+### 第 3 步:Modal 表单
+
+| 字段 | 填什么 |
+|---|---|
+| **选中账单数** | 4 张(显示)|
+| **合计金额** | ¥1,052(自动算)|
+| **支付方式** | 微信 |
+| **收款银行账户** | 物业微信账户 |
+| **备注** | 选填,如 "业户本月全套缴" |
+
+### 第 4 步:提交
+
+系统在**一个事务**内:
+
+1. 校验每张 Bill 可付(`canBePaid()`)
+2. 建 **1 个 CollectionOrder**(`type=Bill`,`actual_amount=+1052`,`status=Completed`)
+3. 建 **4 个 CollectionOrderBill**(每张账单一个,各自 `allocated_amount` = 该账单金额)
+4. 4 张 Bill 各自 `paid_amount = amount`,`status = Paid`
+5. 触发 `CollectionOrderCompleted` 事件
+6. Listener 建 Receipt(可能含 4 个 line_items)
+
+### 第 5 步:给收据
+
+后台找到 Receipt → 打印 / 微信发。
+
+## 系统流程
+
+```mermaid
+sequenceDiagram
+    participant 业户
+    participant 业务
+    participant Filament
+    participant Action[BatchCollectPaymentAction]
+    participant DB
+
+    业务->>Filament: BillsList → 选 4 张 → 批量收款
+    Filament->>Action: handle(bills, channel, bank)
+    Action->>Action: 每张 Bill 校验 canBePaid
+
+    Action->>DB: 开启事务
+    Action->>DB: 1. 建 CollectionOrder(+1052, Completed)
+
+    loop 每张 Bill
+      Action->>DB: 2. 建 CollectionOrderBill(allocated=bill.amount)
+      Action->>DB: 3. Bill.paid_amount = amount, status=Paid
+    end
+
+    Action->>Listener: 4. 触发 CollectionOrderCompleted
+    Listener->>DB: 5. 建 Receipt(line_items × 4)
+    Action->>DB: 提交事务
+
+    Filament-->>业务: 成功通知
+    业务-->>业户: 收据(含 4 项明细)
+```
+
+## 数据示例
+
+收款后:
+
+### CollectionOrder(1 条)
+
+```
+id: 67890
+collection_type: Bill
+actual_amount: +1052
+payment_channel: 微信
+status: Completed
+meta.fund_source: external
+```
+
+### CollectionOrderBill(4 条)
+
+| collection_order_id | bill_id | allocated_amount |
+|---|---|---|
+| 67890 | 物业费 Bill | 800 |
+| 67890 | 水费 Bill | 54 |
+| 67890 | 电费 Bill | 168 |
+| 67890 | 燃气 Bill | 30 |
+
+### Bill(4 条更新)
+
+每张 paid_amount = amount,status = Paid。
+
+### Receipt(1 条,4 行明细)
+
+```
+collection_order_id: 67890
+amount: +1052
+line_items: [
+  { 物业费(5月), 800 },
+  { 水费(5月), 54 },
+  { 电费(5月), 168 },
+  { 燃气(5月), 30 },
+]
+```
+
+## 与单张收款的对比
+
+| 维度 | [[collect-payment-single|单张]] | **批量(本场景)** |
+|---|---|---|
+| Modal 选账单 | 1 张(从 ViewBill 进入)| **多张**(Table 勾选)|
+| CollectionOrder | 1 个 | 1 个(共用)|
+| CollectionOrderBill | 1 个 | **N 个**(每张一个)|
+| 业务人员操作 | 单笔 | 一笔 |
+| 业户体验 | 一张一张付(慢)| 一次付清(快)|
+
+**批量收款的好处**:业户体验更好(一次付),业务人员工作量更小。**唯一前提**:业户愿意一次付清。
+
+## 不同支付方式的分摊
+
+业户支付的钱**自动按账单原金额比例分摊** 到各 Bill。不需要业务人员手动分配。
+
+例:¥1,052 微信付 → 4 个 CollectionOrderBill 各自 allocated_amount = 该账单 amount(全额分配)。
+
+### 如果业户付不够(部分批量付)
+
+业户只想付 ¥600(不够 ¥1,052)→ 业务人员有几种选择:
+
+| 策略 | 操作 |
+|---|---|
+| **优先付物业费**(默认?)| ¥600 全部分配给物业费 Bill(部分付)|
+| **按比例分摊** | 600 × 800/1052 = 456 给物业费,600 × 54/1052 = 31 给水费, ... |
+| **业务人员手动决定** | 给业务人员选哪张账单付多少 |
+
+当前实现的具体策略看代码。**业务上建议优先付到期早的**(避免逾期)。
+
+> [!info] 批量收款的"部分付"复杂度
+> 上述场景比单张部分付更复杂。当前 `BatchCollectPaymentAction` 可能**只支持全额批量**(若金额够付所有选中账单 → 全付;不够 → 走单张部分付逐张操作)。看实现。
+
+## 业务人员视角:Modal 的预检查
+
+类似 [[smart-bulk-delete-design|智能批删]] 的预检查思路:
+
+- 选中 4 张账单 → Modal 显示"总计 ¥1,052"
+- 选中包含已 Paid 的账单 → Modal 显示"4 选 + 1 已付跳过"
+- 选中包含 Suspended → Modal 提示 "该账单挂起,无法收款"
+
+> [!info] 当前实现的成熟度
+> `BatchCollectPaymentAction` 的智能 Modal 程度看实现。可能比 `BulkDeleteBillsAction` 简单(批删有 issue.md Q6 详细设计,批收款未单独描述)。
+
+## 常见问题
+
+> [!question] 选中跨业户的多张账单能批量收款吗?
+> 业务上**不应该**(不同业户付的钱不能混)。系统层面应**校验同业户**,否则拒绝。
+>
+> 例外:**家属代付**场景(儿子来付父母账单)→ 业务上算同业户的钱。
+
+> [!question] 批量收款失败一半怎么办?
+> 事务内**全成功或全失败**。任一 Bill 校验失败(例如某张已 Paid)→ 整笔回滚 → 业户的钱不被收。
+>
+> 实施上可能优化为"部分成功"(只失败的跳过),但破坏事务原子性,通常不推荐。
+
+> [!question] 业户支付的钱比账单合计**多**?
+> Modal 守护应限制金额 ≤ 合计。如果业务上业户故意多给:
+>
+> - 找零给业户(系统层面只收账单的金额)
+> - **或转入业户预存款账户**(若有此自动逻辑)
+
+> [!question] 不同期次的账单能一起付吗?
+> 可以(账单状态都是 Unpaid 即可)。例如付 4 月物业费 + 5 月物业费 + 5 月水电气。
+
+> [!question] 批量收款的 activitylog 怎么记?
+> 一条 CollectionOrder 的 activitylog(event=created)+ 每张 Bill 状态变化的 log。可在 SQL 反查 affected_bill_ids。
+
+## 异常分支
+
+- 单张付 → [[collect-payment-single]]
+- 部分付 → [[exception-partial-payment]]
+- 预存款抵 → [[collect-via-prepaid-auto]]
+- 业户全付不起,挑某张付 → 走 [[collect-payment-single]] 逐张
+- 收错了想撤 → [[void-paid-bill]](已付作废 + 退款)
+
+## 相关文档
+
+- [[bill-vs-collection-order]]
+- [[collect-payment-single]]
+- [[collect-via-prepaid-auto]]
+- [[exception-partial-payment]]
+- [[../prepaid/auto-deduction-design]]

prop-acc/scenarios/billing/collect-payment-single.md

@@ -0,0 +1,258 @@
+---
+title: prop-acc · billing · 场景 - 单张账单收款
+aliases:
+  - 单张收款
+  - 收款
+  - CollectPaymentAction
+  - collect-payment-single
+  - 场景-单张账单收款
+tags:
+  - 场景
+  - prop-acc
+  - 账单
+  - 收款
+audience:
+  - 业户
+  - 业务人员
+status: 已发布
+sub_feature: billing
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 场景:单张账单收款
+
+业户**单张账单付款**(物业费 / 水费 / 电费的某一张),业务人员后台触发 `CollectPaymentAction`。最基础高频的收款场景。
+
+## 典型情境
+
+> [!example] 真实情境
+> 张阿姨 5 月物业费 ¥800 账单已生成,她下午到物业前台:
+>
+> - "我交 5 月物业费"
+> - 业务人员小李打开张阿姨账户 → 找到 5 月物业费账单 → 收款
+
+## 业户视角
+
+### 第 1 步:到前台 / 小程序
+
+带:
+
+- 钱(现金 / 微信 / POS 卡)
+- 房号 / 姓名(身份证)
+
+### 第 2 步:告诉业务人员要付哪张账单
+
+> "我交 5 月物业费"
+
+业务人员从系统找到对应账单。
+
+### 第 3 步:确认金额 + 付款方式
+
+业务人员告诉张阿姨:
+
+> "您 5 月物业费 ¥800,请选付款方式"
+
+| 付款方式 | 操作 |
+|---|---|
+| 现金 | 给钱 → 找零 |
+| 微信扫码 | 业务人员出示物业收款码 → 业户扫 |
+| POS 刷卡 | 业户给银行卡 → POS 机刷 |
+| 银行转账 | 业户给凭证(线下转账已到账)|
+
+### 第 4 步:拿收据
+
+- 纸质:**当场打印**
+- 电子:发到业户微信 / 邮箱
+
+> [!success] 完成
+> 账单状态从 Unpaid → Paid。业户带收据离开,5 分钟内搞定。
+
+## 业务人员视角
+
+### 第 1 步:找账单
+
+后台 → 账单 → 列表 → 按业户姓名 / 房号 / 期次过滤 → 找到张阿姨的 5 月物业费(Unpaid,¥800)→ 进 `ViewBill`。
+
+或者:
+
+- 后台 → 业户 → 找到张阿姨 → "她的账单"标签 → 看 Unpaid 列表 → 选
+
+### 第 2 步:点击 `CollectPaymentAction`(标签"收款")
+
+右上角状态管理组。
+
+> [!warning] 按钮可见性
+> `CollectPaymentAction` 守护:`canBePaid()`(Unpaid / Partial)+ `->authorize('collect')`。Paid / Void / Suspended / Processing 灰化。
+
+Modal 表单:
+
+| 字段 | 填什么 |
+|---|---|
+| **收款金额** | ¥800(默认全额,可改为部分)|
+| **支付方式(`payment_channel_id`)** | 现金 / 微信 / POS / 银行转账 |
+| **收款银行账户(`bank_account_id`)** | 微信/POS/转账选对应银行账户;现金可空 |
+| **收款备注** | 选填,如"业户现场付款" |
+
+### 第 3 步:提交
+
+系统在**一个事务**内:
+
+1. 校验 Bill 可付(`canBePaid` = Unpaid / Partial)
+2. 校验金额 ≤ Bill 剩余应付(`amount - paid_amount`)
+3. 建 `CollectionOrder`(`type=Bill`,`actual_amount=+800`,`status=Completed`,`payment_channel`,`meta.fund_source=external`)
+4. 建 `CollectionOrderBill`(`bill_id`,`collection_order_id`,`allocated_amount=800`)
+5. 更新 `Bill.paid_amount += 800`
+6. 更新 `Bill.status`:若 paid_amount = amount → `Paid`;若 < amount → `Partial`
+7. 触发 `CollectionOrderCompleted` 事件
+8. Listener 自动建 `Receipt` + `ReceiptItem`(文案"物业费 ¥800")
+9. 写 activitylog(可选,具体看实现)
+
+### 第 4 步:给业户收据
+
+后台找到新生成 Receipt → 打印 / 微信发。
+
+## 系统流程
+
+```mermaid
+sequenceDiagram
+    participant 业户
+    participant 业务[业务人员]
+    participant Filament
+    participant Action[CollectPaymentAction]
+    participant DB
+    participant Listener
+
+    业户->>业务: 付物业费 800
+    业务->>Filament: ViewBill → CollectPaymentAction(modal)
+    Filament->>Action: handle(bill, 800, channel, bank)
+    Action->>Action: canBePaid()? Unpaid=true
+    Action->>Action: 800 ≤ remaining(800)? yes
+
+    Action->>DB: 开启事务
+    Action->>DB: 1. 建 CollectionOrder(type=Bill, +800, Completed)
+    Action->>DB: 2. 建 CollectionOrderBill(allocated=800)
+    Action->>DB: 3. Bill.paid_amount=800
+    Action->>DB: 4. Bill.status=Paid(800=800)
+    Action->>Listener: 5. 触发 CollectionOrderCompleted
+    Listener->>DB: 6. 建 Receipt("物业费 ¥800")
+    Action->>DB: 提交事务
+
+    Filament-->>业务: 成功通知
+    业务-->>业户: 收据
+```
+
+## 部分付场景(business 上常见)
+
+业户只想付 ¥300(全额 ¥800):
+
+```
+Modal 表单:
+- 收款金额:300(手动改)
+- 支付方式:现金
+- 备注:"暂时只能付一部分"
+```
+
+提交后:
+
+- Bill.paid_amount = 300
+- Bill.status: Unpaid → **Partial**
+- 建 CollectionOrder(+300)+ CollectionOrderBill(allocated=300)
+
+业户后续补付 ¥500 → 同样走 `CollectPaymentAction` → 第 2 笔 CollectionOrderBill → Bill 收齐 → Paid。
+
+详见 [[exception-partial-payment]]。
+
+## 数据示例(完整流水)
+
+业户付 ¥800 后:
+
+### Bill 表
+
+| 字段 | 值 |
+|---|---|
+| `id` | 12345 |
+| `amount` | 800 |
+| `paid_amount` | 800 |
+| `status` | Paid |
+
+### CollectionOrderBill 表
+
+| 字段 | 值 |
+|---|---|
+| `bill_id` | 12345 |
+| `collection_order_id` | 67890 |
+| `allocated_amount` | 800 |
+
+### CollectionOrder 表
+
+| 字段 | 值 |
+|---|---|
+| `id` | 67890 |
+| `collection_type` | Bill |
+| `actual_amount` | +800 |
+| `payment_channel_id` | 微信 |
+| `status` | Completed |
+| `meta.fund_source` | external |
+
+### Receipt 表
+
+| 字段 | 值 |
+|---|---|
+| `collection_order_id` | 67890 |
+| `amount` | +800 |
+| line_items | [{ 物业费(5月), 800 }] |
+
+## 常见问题
+
+> [!question] 业户付的钱与账单金额不一致(多付 / 少付)?
+> | 情况 | 处置 |
+> |---|---|
+> | 少付 | 走部分付 Partial 状态;后续补付 |
+> | **多付** | **不应该**(Modal 守护 `amount ≤ remaining`)。如果业务上业户给的钱多,**找零给业户**(系统层面只收账单的金额) |
+
+> [!question] 业户付错账单(本想付物业费,付到电费)?
+> 业务人员可:
+> - 立即作废这笔 CollectionOrder(走 [[void-paid-bill]] 类似流程)+ 重新对正确账单收款
+> - 或者**留这笔不动**(资金确实到账)+ 业务人员手工调整 CollectionOrderBill 的 allocated_amount(危险,会破坏审计)
+>
+> **推荐第一种**(走作废 + 重收)。
+
+> [!question] Frozen Bill 能收款吗?
+> 不能。`canBePaid()` 只允许 Unpaid / Partial。Suspended 状态需先 [[resume-bill|恢复]]。
+
+> [!question] 已付的 Bill 能再收款吗?
+> 不能。`canBePaid()` Paid 时返 false。理论上 Bill 已经付清。
+
+> [!question] 业户预存款够付,业务人员怎么操作?
+> 看自动 / 手动:
+> - 自动(待补的 [[../prepaid/auto-deduction-design|预存款自动抵扣 job]]):业务人员不操作,系统自动
+> - 手动:业务人员在 `ViewBill` → 走 `CollectPaymentAction` 选"预存款抵扣"(或专用 Action)→ 详见 [[collect-via-prepaid-auto]]
+
+> [!question] 收款时 PaymentChannel 写错(选了微信实际是现金)?
+> CollectionOrder 一经创建**通常不可改**字段。错了:
+> - 走作废(详见 [[void-paid-bill]])+ 重新建
+> - 或 tinker 改字段(运维 + 留审计)
+>
+> 预防:Modal 提交前再三确认。
+
+> [!question] activitylog 记什么?
+> 详见 [[smart-bulk-delete-design]] activitylog 设计。CollectPayment 通常也记一条 activitylog:event=collected,properties 含 amount / payment_channel / receipt_id。
+
+## 异常分支
+
+- 部分付场景 → [[exception-partial-payment]]
+- 批量付(多张账单一起付)→ [[collect-payment-batch]]
+- 预存款抵 → [[collect-via-prepaid-auto]]
+- 收款错了想撤 → [[void-paid-bill]]
+- Bill 挂起中无法收 → [[resume-bill]]
+- 逾期账单催收 → [[exception-overdue-bills]]
+
+## 相关文档
+
+- [[bill-six-state-machine]]
+- [[bill-vs-collection-order]]
+- [[exception-partial-payment]]
+- [[collect-payment-batch]]
+- [[collect-via-prepaid-auto]]
+- [[../adhoc/collection-order-and-receipt]]

prop-acc/scenarios/billing/collect-via-prepaid-auto.md

@@ -0,0 +1,267 @@
+---
+title: prop-acc · billing · 场景 - 预存款抵扣自动收款
+aliases:
+  - 预存款抵账单
+  - 自动抵扣收款
+  - collect-via-prepaid-auto
+  - 场景-预存款自动抵扣
+tags:
+  - 场景
+  - prop-acc
+  - 账单
+  - 收款
+  - 跨子模块
+audience:
+  - 业户
+  - 业务人员
+  - 财务
+status: 已发布
+sub_feature: billing
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 场景:预存款抵扣自动收款
+
+业户**预存款余额够付账单**,系统(理想是自动 job,当前是业务人员手动触发)走 `ConsumeFromPrepaidAccountAction` 抵扣账单。这是 billing × prepaid **两子模块联动**的核心场景。
+
+> [!info] 本场景跨两个模块
+> - **billing 视角**:Bill 从 Unpaid → Paid,看似与普通收款一样
+> - **prepaid 视角**:PrepaidAccount.balance 减,走 consume 流水
+>
+> 详见 [[../prepaid/consume-monthly-property-bill]] 完整流程。本场景从 billing 角度补充。
+
+## 典型情境
+
+> [!example] 真实情境
+> 张阿姨预存款账户余额 ¥3,400,5 月物业费 ¥800。
+>
+> 手动模式:王主管在张阿姨预存款账户上点 `ConsumeAction`,选 5 月物业费 → 抵扣完成 → 账单 Paid。
+>
+> 自动模式(待补 [[../prepaid/auto-deduction-design]]):月初 1 日凌晨 job 自动跑 → 张阿姨账单当月自动扣 → 早晨业户收到推送"5 月物业费 ¥800 已抵扣,余额 ¥2,600"。
+
+## billing 视角
+
+### Bill 的变化
+
+| 字段 | 变化前 | 变化后 |
+|---|---|---|
+| `status` | Unpaid | Paid |
+| `paid_amount` | 0 | 800 |
+| 关联的 CollectionOrderBill | 0 个 | 1 个(allocated=800)|
+| 关联的 CollectionOrder | 0 个 | 1 个(type=Bill, meta.fund_source=prepaid)|
+| 关联的 Receipt | 0 个 | 1 个("物业费 ¥800") |
+
+**与普通收款的唯一差异**:CollectionOrder 的 `meta.fund_source = 'prepaid'`(而非默认 `external`)。
+
+### CollectionOrder 的特殊性
+
+```yaml
+id: 67890
+collection_type: Bill         # 仍是 Bill 视角(不是 Prepaid)
+actual_amount: +800            # 正数
+payment_channel: null          # 不走外部支付渠道
+status: Completed
+meta:
+  fund_source: prepaid         # 标资金来源
+  prepaid_account_id: 123
+  prepaid_transaction_id: 456
+```
+
+详见 [[../prepaid/consume-via-bill-collection-type]]"CollectionOrder.type=Bill 设计"段。
+
+### Receipt 文案
+
+与现金 / 微信付的收据**长一样**:
+
+```
+物业费(5月)¥800
+```
+
+业户**感知不到**资金来源差异。这是有意设计 —— "业户付清账单"的统一感受。
+
+## prepaid 视角(简述)
+
+详见 [[../prepaid/consume-monthly-property-bill]] 完整流程。
+
+- 校验账户 `canOperate()`(Active)
+- 校验余额够付(`balance >= 800`)
+- 校验跨社区(Bill 与 Account 同 community)
+- 建 `PrepaidTransaction(type=consume, amount=800, related_bill_id, balance 3400→2600)`
+- 更新 `PrepaidAccount.balance = 2600`
+- 同步 Bill 状态翻 Paid(通过 CollectionOrder + CollectionOrderBill)
+
+## 业户视角
+
+### 您会感受到什么
+
+| 模式 | 感知 |
+|---|---|
+| **自动(待补)** | 月初推送"5 月物业费 ¥800 已自动从预存款扣,余额 ¥2,600" |
+| **手动** | 同上,只是触发时间不固定(看业务人员何时操作)|
+
+### 与现金付的差异
+
+| 维度 | 现金付 | **预存款抵** |
+|---|---|---|
+| 业户操作 | 到前台 + 给钱 | **无操作**(自动) |
+| 业户感知 | "我付了" | **"已抵扣"**(被动) |
+| Receipt | "物业费 ¥800" | **"物业费 ¥800"**(相同) |
+| 业务人员介入 | 多(收钱 + 录入) | **无**(自动 job)/ 中(手动) |
+| 时长 | 业户上门 + 5 分钟办理 | 0 秒(自动)/ 5 分钟(手动) |
+
+## 业务人员视角
+
+### 手动模式
+
+业务人员在 `ViewPrepaidAccount`(预存款账户详情页):
+
+1. 看到张阿姨账户余额 ¥3,400
+2. 点击 `ConsumeAction`(预存款上的)
+3. Modal 选 Bill = "5 月物业费 ¥800"
+4. 提交 → 系统自动跑完整链路
+
+> [!info] 这个 Action 不在 billing 模块
+> `ConsumeAction` 是 prepaid 模块的 Filament Action,在 `PrepaidAccounts/Actions/`。billing 模块的 `CollectPaymentAction` 是普通收款用的(走外部 PaymentChannel)。两者**协作完成**预存款抵扣场景。
+>
+> 详见 [[../prepaid/consume-monthly-property-bill]]"业务人员视角"。
+
+### 自动模式(待补)
+
+业务人员**几乎不操作**(产品价值的最大体现)。月初看 dashboard 报告:
+
+```
+2026 年 6 月 1 日 PrepaidAutoDeductionJob 报告
+- 候选账户:500
+- 全抵成功:380(76%)
+- 部分抵 / 跳过:80(16%)
+- 账户冻结跳过:8(2%)
+- 失败:0
+```
+
+逐个跟进失败 / 跳过的(走 [[../prepaid/audit-low-balance-and-overdue|低余额预警]] 等)。
+
+## 系统流程(手动)
+
+```mermaid
+sequenceDiagram
+    participant 业务
+    participant Filament
+    participant ConsumeAction[Prepaid 的 ConsumeAction]
+    participant ConsumeFromPrepaid[ConsumeFromPrepaidAccountAction]
+    participant Bill
+    participant PrepaidAccount
+    participant DB
+    participant Listener
+
+    业务->>Filament: ViewPrepaidAccount → ConsumeAction(选 Bill, 800)
+    Filament->>ConsumeFromPrepaid: handle(account, bill, 800)
+    ConsumeFromPrepaid->>PrepaidAccount: canOperate() ? Active=true
+    ConsumeFromPrepaid->>PrepaidAccount: community_id match? yes
+    ConsumeFromPrepaid->>PrepaidAccount: balance >= 800? yes
+
+    ConsumeFromPrepaid->>DB: 开启事务
+    ConsumeFromPrepaid->>DB: 1. 建 CollectionOrder(type=Bill, +800, meta.fund_source=prepaid)
+    ConsumeFromPrepaid->>DB: 2. 建 CollectionOrderBill(allocated=800)
+    ConsumeFromPrepaid->>PrepaidAccount: 3. consume(bill, 800)
+    PrepaidAccount->>DB: 建 PrepaidTransaction(consume, 3400→2600, related_bill_id)
+    PrepaidAccount->>DB: 更新 balance=2600
+    ConsumeFromPrepaid->>Bill: 4. recordPayment(800)
+    Bill->>DB: paid_amount=800, status=Paid
+    ConsumeFromPrepaid->>Listener: 5. 触发 CollectionOrderCompleted
+    Listener->>DB: 6. 建 Receipt("物业费 ¥800")
+    ConsumeFromPrepaid->>DB: 提交事务
+
+    Filament-->>业务: 成功
+```
+
+## 自动 job 流程(待实现)
+
+```mermaid
+sequenceDiagram
+    participant Scheduler
+    participant Job[PrepaidAutoDeductionJob]
+    participant Bills
+    participant Action[ConsumeFromPrepaidAccountAction]
+
+    Note over Scheduler: 2026-06-01 00:30
+
+    Scheduler->>Job: dispatch
+    Job->>Bills: SELECT 未付账单(community_id, resident_id 匹配预存款)
+
+    loop 每户
+      Job->>Bills: 按 due_at 升序查未付账单
+      loop 每张账单
+        alt 余额够
+          Job->>Action: handle(account, bill, bill.amount)
+          Note over Action: 同手动模式的链路
+        else 余额不够
+          Job->>Job: 跳过
+        end
+      end
+    end
+
+    Job-->>Scheduler: 完成 + 报告
+```
+
+详见 [[../prepaid/auto-deduction-design]] + [[../prepaid/consume-batch-auto-monthly]]。
+
+## 与单张 / 批量收款的对比
+
+| 维度 | [[collect-payment-single|单张]] | [[collect-payment-batch|批量]] | **预存款抵(本)** |
+|---|---|---|---|
+| 业务人员操作 | 单张点 CollectPayment | 多选 + BatchCollect | 手动 ConsumeAction / 自动 job |
+| 触发位置 | ViewBill | BillsList | **ViewPrepaidAccount** / 定时任务 |
+| 资金来源 | 现金 / 微信 / POS / 转账 | 同 | **预存款余额** |
+| CollectionOrder.meta.fund_source | external | external | **prepaid** |
+| 业户感知 | 主动付 | 主动付 | **被动收到通知** |
+| 频率 | 高 | 中 | **未来最高(自动 job)** |
+
+## 常见问题
+
+> [!question] 业户预存款不够付,但快有了(等到本月底)怎么办?
+> 业务上不应等。可:
+>
+> - 提示业户立即充值预存款([[../prepaid/deposit-additional-topup]])
+> - 业户用其他方式付(现金 / 微信)
+> - 部分抵(如果 Bill 支持部分付,见 [[exception-partial-payment]])
+
+> [!question] 业户希望某些账单不要从预存款扣(例如不接受被自动扣电费)?
+> 当前自动 job 待实现,实施时**可加白名单 / 黑名单机制**:
+> - 业户可设置"只允许物业费自动扣"
+> - 其他费用(水电气)留给业户主动付
+>
+> issue.md 未明确需求,看业务方反馈。
+
+> [!question] 预存款抵扣的 Bill 后续要作废怎么办?
+> 走 [[void-paid-bill|作废已付账单]] 流程,但**退款方向不同**:
+> - 不退现金 / 微信
+> - **退回预存款**(走 PrepaidAccount::deposit 反向充值)
+> - 详见 [[void-paid-bill]]"已付作废 + 预存款退还"段
+
+> [!question] 业户跨社区,A 社区有预存款 ¥5000,B 社区欠物业费 ¥800,能跨社区抵吗?
+> **不能**。详见 [[../prepaid/exception-cross-community-consume]]"跨社区消费防御"段。
+
+> [!question] 自动 job 跑的时候,业户同时去前台付现金,会重复收款吗?
+> 看时序 + 锁机制:
+> - 若 job 已锁 Bill(乐观锁)→ 前台收款失败(Bill 状态可能已变 Paid)
+> - 若 job 没锁 → 可能并发问题(罕见,需排查具体实现)
+>
+> **预防**:业务人员收款前看 Bill 当前状态,Paid 就不收。
+
+## 异常分支
+
+- 业户预存款不够 → 业务推 [[../prepaid/deposit-additional-topup]] 或走现金
+- 业户预存款冻结 → [[../prepaid/exception-refund-on-frozen|冻结无法抵]]
+- 跨社区抵企图 → [[../prepaid/exception-cross-community-consume|系统拦截]]
+- 抵后想撤 → [[void-paid-bill]] + 预存款回填
+
+## 相关文档
+
+- [[bill-vs-collection-order]]
+- [[../prepaid/consume-via-bill-collection-type]]
+- [[../prepaid/consume-monthly-property-bill]]
+- [[../prepaid/auto-deduction-design]]
+- [[../prepaid/consume-batch-auto-monthly]]
+- [[collect-payment-single]]
+- [[void-paid-bill]]

prop-acc/scenarios/billing/create-meter-bill-auto.md

@@ -0,0 +1,253 @@
+---
+title: prop-acc · billing · 场景 - 抄表自动生成计量账单
+aliases:
+  - 计量账单生成
+  - 抄表后建账单
+  - create-meter-bill-auto
+  - 场景-计量账单自动生成
+tags:
+  - 场景
+  - prop-acc
+  - 账单
+  - 创建
+  - 计量账单
+audience:
+  - 业务人员
+  - 财务
+  - 抄表员
+status: 已发布
+sub_feature: billing
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 场景:抄表自动生成计量账单
+
+抄表数据进入系统后(`MeterReading`),触发 `GenerateBillsFromMeterReadingsAction` 自动建账单。**核心机制在 meter 模块的[bill-generation-pipeline](../concepts/meter/bill-generation-pipeline.md)**,本场景描述 billing 模块的**对接视角**。
+
+## 典型情境
+
+> [!example] 真实情境
+> 嘉禾花园 5 月底:
+>
+> - 1,200 张表的本月抄表全部完成
+>   - 1,160 张走集抄([[../meter/read-via-iot-remote-source]])
+>   - 40 张走手抄([[../meter/read-single-meter-manual]] + [[../meter/read-batch-via-excel-import]])
+> - 系统在抄表完成后**自动触发**:`GenerateBillsFromMeterReadingsAction`(批量,1,200 张 reading → 1,200 张 Bill)
+> - 王主管看到的:**1,200 张计量账单已就绪**,无需手工建
+
+## 业务人员视角
+
+### 自动模式(默认)
+
+业务人员**几乎不操作**:
+
+1. 抄表完成 → 抄表 Action / Importer 内部触发 `GenerateBillsFromMeterReadingsAction`
+2. 系统逐张 reading 算金额(走 [[../meter/multiplier-and-tiered-pricing|倍率+阶梯+min/max]] 三层算法)
+3. 建 Bill,sourceable=MeterReading,bill_type=Meter
+4. reading.bill_id 回写
+5. 报告"已生成 1,200 张计量账单"
+
+### 手动模式(罕见)
+
+某些情况下业务人员需要**手动触发**:
+
+- 抄表数据补录后(集抄掉线 + 后续补抄)
+- 部分 reading 之前生成 Bill 失败后重试
+- 测试 / 验证
+
+后台 → 账单 → 列表 → 顶部 "从 reading 生成账单" 按钮(若有 UI)→ 选 reading 范围 → 提交。
+
+### 第 1 步:核对 reading 完成
+
+抄表完成后(月底):
+
+- 看 `MetersNeedingReadingListWidget`:本月待抄数 = 0
+- 看 `MeterReadingsList`:本月 reading 数 = 1,200
+
+### 第 2 步:确认账单生成
+
+抄表 Action 自动触发后:
+
+- 看 `BillsList`,过滤 `bill_type=Meter` + 本月期次 → 应有 1,200 张
+- 看每张账单的 `sourceable_id` 指向对应 reading
+
+### 第 3 步:异常处理
+
+| 异常 | 处置 |
+|---|---|
+| 某 reading 没生成 Bill(状态:`reading.bill_id=null`)| 排查原因(RatePlan 缺失?业户没绑定?)→ 修复 → 重新触发 |
+| 某 Bill 金额异常(高出预期 10 倍)| 排查 multiplier / 阶梯配置,可能要 [[exception-readings-locked-after-bill|修正流程]] |
+| 大面积失败(>10%)| 系统级问题,联系运维 |
+
+## 业户视角
+
+业户**月底/月初**收到水电气账单:
+
+> 陈先生您好,您的 2026 年 5 月费用账单已生成:
+>
+> - 水费:¥54(用水 12 吨)
+> - 电费:¥168(用电 280 度)
+> - 燃气费:¥35(用气 15 立方)
+>
+> 合计 ¥257,请于 6 月 15 日前付清。
+
+业户**不知道**这些账单是抄表自动生成的(后端透明)。他看到的就是"几张需要付的账单"。
+
+## 系统流程(完整链路)
+
+```mermaid
+sequenceDiagram
+    participant 集抄/抄表员
+    participant MeterAction[抄表 Action / Importer]
+    participant GenBills[GenerateBillsFromMeterReadingsAction]
+    participant Calc[MeterBillCalculator]
+    participant Service[MeterBillGenerationService]
+    participant DB
+
+    Note over 集抄/抄表员: 本月抄表完成
+
+    集抄/抄表员->>MeterAction: 推送 / 录入 reading 数据
+    MeterAction->>DB: 建 MeterReading(bill_id=null)
+    MeterAction->>GenBills: 触发(刚建的 reading 列表)
+
+    loop 每个 reading
+      GenBills->>Service: generateBillForReading(reading)
+      Service->>Calc: calculate(consumption, ratePlan)
+      Calc-->>Service: amount
+      Service->>DB: 建 Bill(bill_type=Meter, sourceable=reading, status=Unpaid)
+      Service->>DB: 更新 reading.bill_id = bill.id
+    end
+
+    GenBills-->>MeterAction: 报告(N 张生成,M 张失败)
+```
+
+详细分层见 [[../meter/bill-generation-pipeline]]"Calculator + Service + Action"段。
+
+## 与 meter 模块的关系
+
+| 维度 | meter 模块 | **billing 模块(本场景)** |
+|---|---|---|
+| 主对象 | Meter + MeterReading | **Bill** |
+| 责任 | 抄表 + 算用量 | **建账单 + 后续收款** |
+| 触发 | 抄表 Action / Importer | 由 meter 模块触发 |
+| 共享 | sourceable_type='MeterReading' | sourceable_id 指向 reading |
+
+billing 模块对计量账单**没有**自己的创建 Action UI(由 meter 模块的 `GenerateBillsFromMeterReadingsAction` 完全负责)。billing 模块只**接收** sourceable 标记 + 提供后续 [[collect-payment-single|收款]] / [[exception-overdue-bills|催收]] 流程。
+
+## 计量账单的特殊处理
+
+### 1. sourceable 关联
+
+```php
+// Bill 字段
+sourceable_type = 'App\Models\MeterReading'
+sourceable_id = 12345
+```
+
+可双向反查:
+
+```php
+// 从 Bill 看 reading
+$bill->sourceable;  // → MeterReading 实例
+
+// 从 reading 看 Bill
+$reading->bill;  // → Bill 实例(通过 reading.bill_id)
+```
+
+### 2. bill_type=Meter
+
+| 字段 | 值 |
+|---|---|
+| `bill_type` | `Meter`(BillType 枚举) |
+| 业务分类 | 水费 / 电费 / 燃气费(由 fee_type_id 决定具体)|
+| 报表分类 | 进"水电气收入"科目 |
+
+### 3. 期次
+
+计量账单的 `billing_period_start / end` 通常对应**抄表期次**(例如:本期抄表是 5/26 - 上期 4/28 = 期次 4/29 - 5/26)。具体看实现。
+
+## 异常分支
+
+### 异常 1:reading 已生成 Bill,重复触发
+
+```php
+// GenerateBillsFromMeterReadingsAction
+foreach ($readings as $reading) {
+    if ($reading->bill_id !== null) {
+        $skipped[] = ['reading' => $reading, 'reason' => 'already_billed'];
+        continue;
+    }
+    // ...
+}
+```
+
+已有 Bill 的 reading 直接 skip。不会重复建。
+
+### 异常 2:RatePlan 不存在
+
+某 fee_type 没配 RatePlan:
+
+```php
+$ratePlan = $feeType->currentRatePlan;
+if (! $ratePlan) {
+    throw new RatePlanNotFoundException();
+}
+```
+
+Service 抛错,Action 捕获后 skip 该 reading + 报告。业务人员需先配 RatePlan 再重试。
+
+### 异常 3:asset 没绑业户(`community_asset_users` 缺失)
+
+```php
+$resident = $this->findCurrentResident($asset);
+if (! $resident) {
+    // 视设计:抛 / 建匿名 Bill(无 resident_id)/ 跳过
+}
+```
+
+通常**跳过**(看具体实现),业务人员先绑业户再重试。
+
+### 异常 4:已落账的 reading 数据错
+
+走 [[../meter/exception-readings-locked-after-bill|修正流程]]:作废 Bill → 改 reading → 重生成 Bill。复杂,需运维介入。
+
+## 常见问题
+
+> [!question] 触发时机:抄表 Action 内部 / 单独定时?
+> 当前实现:**抄表 Action 完成后立即触发**(同事务或紧接事务)。
+>
+> 优点:数据立即一致(reading + Bill 同步出现)。
+> 缺点:抄表 Action 性能 = 抄表 + 建账单两段时间。
+>
+> 替代方案:定时任务(每月固定时间扫所有未生成账单的 reading)。当前未采用。
+
+> [!question] 业户对计量账单金额有疑问怎么办?
+> 业务人员可:
+>
+> - 给业户看抄表照片(`reading.photo_url`)
+> - 给业户看 RatePlan(单价配置)
+> - 重算给业户看(用 Calculator 算法)
+>
+> 若证实数据错 → 走 [[../meter/exception-readings-locked-after-bill|修正流程]]。
+
+> [!question] 与周期账单(物业费)冲突吗?
+> 不冲突。两者 BillType 不同(`Periodic` vs `Meter`),fee_type 不同(物业费 vs 水电气),sourceable 不同(null vs MeterReading)。各走各的生成路径,各自独立账单。
+
+> [!question] 业户预存款抵这种账单的优先级?
+> 看 [[../prepaid/consume-batch-auto-monthly|预存款自动抵扣 job]] 的策略:
+>
+> - 按 `due_at` 升序(早到期的先抵)
+> - 计量账单与物业费的 due_at 通常相近(都是月底 + 宽限期)
+> - 哪个早抵哪个
+
+## 相关文档
+
+- [[bill-types-and-sources]]
+- [[bill-vs-collection-order]]
+- [[../meter/bill-generation-pipeline]]
+- [[../meter/multiplier-and-tiered-pricing]]
+- [[../meter/exception-readings-locked-after-bill]]
+- [[create-periodic-property-fee]]
+- [[create-single-bill-manual]]
+- [[collect-payment-batch]](业户可能水电气一起付)

prop-acc/scenarios/billing/create-periodic-property-fee.md

@@ -0,0 +1,230 @@
+---
+title: prop-acc · billing · 场景 - 月度物业费 300 户批量生成
+aliases:
+  - 批量生成物业费
+  - 月度物业费生成
+  - create-periodic-property-fee
+  - GeneratePeriodicBillsAction 实战
+  - 场景-月度物业费生成
+tags:
+  - 场景
+  - prop-acc
+  - 账单
+  - 创建
+  - 周期账单
+audience:
+  - 业务人员
+  - 财务
+status: 已发布
+sub_feature: billing
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 场景:月度物业费 300 户批量生成
+
+每月 1 日,物业为社区**所有业户**批量生成本月物业费账单。走 `GeneratePeriodicBillsAction`,默认 `SkipExisting` 策略。
+
+## 典型情境
+
+> [!example] 真实情境
+> 5 月 1 日上午 9 点,嘉禾花园物业财务王主管打开后台:
+>
+> - 300 户业户(住宅 + 商铺)
+> - 物业费 RatePlan:住宅 ¥3 / m²(平均面积 100 m² → ¥300),商铺 ¥8 / m²
+> - 王主管:**1 次点击 + 1 个 Modal**,300 张账单全部建好
+
+## 业务人员视角
+
+### 第 1 步:打开 BillsList
+
+后台 → 账单 → 列表 → 顶部 **"批量生成周期账单"** 按钮(`GeneratePeriodicBillsAction`)。
+
+### 第 2 步:Modal 填参数
+
+| 参数 | 填什么 |
+|---|---|
+| **期次(billing_period)** | 2026 年 5 月(start: 5/1, end: 5/31)|
+| **费用类型(fee_type_id)** | 物业费(下拉选)|
+| **社区范围(community_id)** | 嘉禾花园 |
+| **业户范围** | 全社区业户(默认)|
+| **合并策略(merge_strategy)** | `SkipExisting`(默认,详见 [[periodic-bill-generation]])|
+| 备注 | 选填,如 "5 月例行物业费生成" |
+| **到期日(due_at)** | 6 月 15 日(本月 + 15 天宽限期)|
+
+### 第 3 步:提交
+
+> [!warning] Policy 守护
+> 按钮 `->authorize('create', Bill::class)`,需要 `bill.create` 权限。
+
+系统执行(后台逻辑):
+
+```mermaid
+flowchart TD
+  A[扫描候选业户清单<br/>SELECT * FROM community_user_profiles<br/>WHERE community_id=? AND status=active] --> B[300 业户]
+
+  B --> C[每户:]
+  C --> D{该户该期次<br/>已有 Bill?}
+  D -->|是| E[Skip(默认策略)]
+  D -->|否| F[查 RatePlan 算金额<br/>3 * 100 = 300]
+  F --> G[建 Bill]
+  G --> H[活动日志]
+
+  E --> I[报告]
+  H --> I
+```
+
+### 第 4 步:看结果报告
+
+```
+2026 年 5 月物业费生成完成
+
+✅ 已生成:298 张
+⏭️ 已跳过:2 张(本月已存在,SkipExisting 策略)
+❌ 失败:0 张
+
+总金额:¥120,400
+平均每户:¥401
+```
+
+### 第 5 步:抽样核对
+
+业务人员抽 2-3 张账单看金额是否对(尤其 RatePlan 改过后)。
+
+### 第 6 步:推送给业户
+
+视物业策略:
+
+- 自动推送(若集成微信公众号 / 小程序)
+- 或单独触发"通知本月账单"动作
+
+## 系统流程
+
+```mermaid
+sequenceDiagram
+    participant 王主管
+    participant Filament
+    participant Action[GeneratePeriodicBillsAction]
+    participant DB
+    participant Notify[通知服务]
+
+    王主管->>Filament: 批量生成周期账单 → Modal 填参数 → 提交
+    Filament->>Action: handle(community, feeType, period, strategy)
+    Action->>DB: 扫描候选业户清单
+
+    loop 每户
+      Action->>DB: 查该户该期次是否已有 Bill
+      alt 已有
+        Action->>Action: 按策略处理(默认 Skip)
+      else 无
+        Action->>DB: 查 RatePlan + 算金额
+        Action->>DB: 建 Bill (status=Unpaid, period, due_at)
+      end
+    end
+
+    Action->>Notify: 触发"批量账单已生成"通知(可选)
+    Action-->>Filament: 报告(生成 / 跳过 / 失败统计)
+    Filament-->>王主管: Modal 显示统计
+```
+
+## 业户视角
+
+业户 5 月 1 日 / 2 日陆续收到推送:
+
+> 张阿姨您好,您的 2026 年 5 月物业费 ¥300 已生成,请于 6 月 15 日前付清。
+>
+> 可选付款方式:
+> - 微信小程序付
+> - 到前台付现金 / 微信 / POS
+> - 您预存款余额 ¥1,200 足够,可自动抵扣(若开通自动抵扣)
+
+业户可选:
+
+- 立即付([[collect-payment-single]] / [[collect-payment-batch]])
+- 等到期日前付
+- 不付 → 到期日后变逾期([[exception-overdue-bills]])
+
+## 异常处理
+
+### 部分业户失败(RatePlan 缺失)
+
+| 异常 | 处置 |
+|---|---|
+| 某户没分配 RatePlan(新业户)| Action 跳过该户 + 报告标记 → 业务人员手动配 RatePlan 后单独生成 |
+| 某户面积字段缺失 | 同上 |
+| 系统级故障(DB / 内存)| Action 抛错 + 部分生成的 Bill 在事务内回滚 |
+
+### Merge 策略案例(进阶)
+
+如果业务人员想"同业户的物业费 + 电视费 + 网络费**合并到一张账单**":
+
+- Modal 选 `merge_strategy = Merge`
+- 系统找到已生成的物业费 Bill,把电视费 / 网络费**追加进同一张 Bill**(amount 累加)
+- 业户看到的是一张合并账单 ¥XX(明细几项)
+
+详见 [[periodic-bill-generation]]"策略 2:Merge"段。
+
+### Replace 策略案例(罕见)
+
+业务人员发现 5 月物业费 RatePlan 配错了 → 选 `merge_strategy = Replace`:
+
+- 找到已有 Bill → **作废**(VoidBillAction)
+- 按新 RatePlan 重新生成
+
+> [!warning] Replace 风险
+> Replace 对**已付的 Bill** 慎用,会让业户已付的钱"卡在 Void 状态",需配套退款流程。
+
+## 常见问题
+
+> [!question] 同一户能否生成两次同期次同费用类型?
+> 业务上不应(违反一户一月一物业费规则)。系统层面通常有 unique 索引拦截。SkipExisting 策略也避免重复。
+
+> [!question] 一次生成失败一半怎么办?
+> Action 内部对单户失败容错(跳过失败户,继续其他),不会因一户失败回滚全部。报告会列出失败户,业务人员单独处理。
+
+> [!question] 周期账单生成后想推迟到期日?
+> Bill 创建后 `due_at` 字段**通常可编辑**(若 status=Unpaid)。批量改可能需要专门的"批量推迟到期日" Action(当前没,可手工逐张改或运维 tinker)。
+
+> [!question] 业务人员忘了月初生成怎么办?
+> 月中或月底再触发,系统正常生成(due_at 仍按原计划,可能立即逾期)。业户体验不好(账单晚到),需提前通知。
+
+> [!question] 自动化(Scheduled Job)有吗?
+> issue.md Q6 未明确(meter 和 prepaid 也都有"自动化待补"的待办)。当前**手动触发**。未来可加:
+>
+> - 月初 1 日 00:30 自动触发(类似 prepaid 自动抵扣)
+> - 触发后立即触发预存款抵扣(无缝)
+> - 业户次日早收到推送
+
+> [!question] 业户拒绝接收推送怎么办?
+> 系统层面不影响(账单仍在,可在小程序 / 后台查)。推送只是触达手段。业户拒收推送 → 物业改用电话 / 短信 / 上门通知。
+
+> [!question] 不同费用类型(物业费 + 电视费)能一次性都生成吗?
+> 当前 `GeneratePeriodicBillsAction` 一次只生成**一个费用类型**。批量需触发多次(物业费 1 次 + 电视费 1 次 + ...)。或者业务方反馈后增加"多费用类型批量"功能。
+
+## 与计量账单生成的对比
+
+| 维度 | 本场景(周期账单)| [[create-meter-bill-auto|计量账单]] |
+|---|---|---|
+| 触发 | 业务人员手动 | 抄表完成后自动 / 批量 |
+| 金额 | 固定(RatePlan)| 浮动(用量计算)|
+| 数量 | 每户每期 1 张 | 每抄表 1 张 |
+| sourceable | null(或周期任务 ID)| MeterReading |
+| 频率 | 月度 1 次 | 看抄表频率 |
+
+## 异常分支
+
+- 计量账单生成 → [[create-meter-bill-auto]]
+- 临时手动建单 → [[create-single-bill-manual]]
+- 业务人员要批量删错的 → [[bulk-delete-batch-mistake]]
+- 业户收到账单要付款 → [[collect-payment-single]]
+
+## 相关文档
+
+- [[periodic-bill-generation]]
+- [[bill-six-state-machine]]
+- [[bill-types-and-sources]]
+- [[create-meter-bill-auto]]
+- [[collect-payment-single]]
+- [[bulk-delete-batch-mistake]]
+- [[../meter/bill-generation-pipeline]]
+- [[../prepaid/auto-deduction-design]](账单生成下游消费)

prop-acc/scenarios/billing/create-single-bill-manual.md

@@ -0,0 +1,214 @@
+---
+title: prop-acc · billing · 场景 - 手动建单(临时收费/调整账单)
+aliases:
+  - 手动建账单
+  - 临时账单
+  - create-single-bill-manual
+  - 场景-手动建账单
+tags:
+  - 场景
+  - prop-acc
+  - 账单
+  - 创建
+audience:
+  - 业务人员
+  - 财务
+status: 已发布
+sub_feature: billing
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 场景:手动建单(临时收费/调整账单)
+
+业务上**不属于周期任务、不属于抄表**的临时收费,通过 `CreateBill` 后台**手工建一张账单**。例如:维修费分摊、特别活动费、单次罚款、跨期补开账单。
+
+## 典型情境
+
+> [!example] 真实情境(一):公共维修费分摊
+> 嘉禾花园 3 单元电梯坏了维修,总成本 ¥15,000。物业公司决定**全单元 30 户业户分摊**(每户 ¥500)。这种"临时性的、不属周期 / 抄表"的费用,业务人员逐户手工建账单(或选定业户清单后批量手工)。
+
+> [!example] 真实情境(二):个别业户的特别罚款
+> 张阿姨违反小区车位管理规定(占用应急车位 1 小时),物业罚款 ¥100。业务人员单独给张阿姨建一张账单。
+
+> [!example] 真实情境(三):跨期补开账单
+> 业务人员发现陈先生 4 月物业费没生成(系统月初批量时陈先生数据有问题),5 月才发现。需补开 4 月账单。
+
+## 业务人员视角
+
+### 第 1 步:打开 CreateBill
+
+后台 → 账单 → 列表 → 顶部 **"新建"** 按钮 → 进 `CreateBill` 页面。
+
+### 第 2 步:填表单(`BillForm`)
+
+| 字段 | 填什么 |
+|---|---|
+| **社区(community_id)** | 嘉禾花园(若多社区可选)|
+| **业户(resident_id)** | 张阿姨(下拉选)|
+| **房屋(asset_id)** | 12-3-501(自动带入或手选)|
+| **费用类型(fee_type_id)** | 选合适的 FeeType(物业费 / 杂费 / 罚款 / ...) |
+| **账单类型(bill_type)** | 通常选 `OneTime` 或 `Adjustment`(看 BillType 枚举)|
+| **金额(amount)** | ¥500(电梯维修分摊)|
+| **期次** | 选填(临时账单可不填,或填发生月)|
+| **到期日(due_at)** | 6 月 15 日 |
+| **备注(memo)** | **强烈推荐填**,说明缘由,如 "3 单元电梯维修分摊(2026-05),总成本 ¥15,000 ÷ 30 户" |
+
+> [!warning] Policy 守护
+> `CreateBill` 需要 `bill.create` 权限。
+
+### 第 3 步:提交
+
+系统:
+
+1. 校验字段(business / asset / fee_type 存在)
+2. 建 Bill(`status=Unpaid`,`sourceable_type=null` / 或自定义)
+3. 写 activitylog(单条 Bill 创建,subject=Bill)
+4. 跳到 `ViewBill` 页面
+
+### 第 4 步:通知业户
+
+通常需要业务人员**单独通知**(临时账单不在月度自动推送范围内):
+
+- 微信 / 短信:"张阿姨,您本月有一笔电梯维修分摊费 ¥500,请于 6 月 15 日前付清"
+- 附备注说明
+
+### 第 5 步:批量手工建(电梯维修分摊场景)
+
+如果是分摊给 30 户业户,逐户建效率低。当前没有"批量手动建" UI,只能:
+
+- 逐户走 `CreateBill`(30 次)
+- 或运维 tinker 脚本(SQL 批量 INSERT)
+- 或要求业务方加"批量手工建"功能
+
+未来可加:`BulkCreateBillsAction`(给定业户清单 + 模板 → 批量建)。
+
+## 系统流程
+
+```mermaid
+sequenceDiagram
+    participant 业务[业务人员]
+    participant Filament
+    participant CreateBill
+    participant Activity[activitylog]
+    participant DB
+
+    业务->>Filament: ListBills → 新建 → CreateBill
+    Filament->>CreateBill: 渲染 form
+    业务->>CreateBill: 填业户 / 金额 / 备注 / 提交
+    CreateBill->>DB: 校验 fields
+    CreateBill->>DB: 建 Bill(status=Unpaid, bill_type=OneTime, sourceable=null)
+    CreateBill->>Activity: log(event=created, subject=Bill)
+    CreateBill-->>Filament: 跳转 ViewBill
+    Filament-->>业务: 显示新账单
+```
+
+## 业户视角
+
+业户收到通知:
+
+> 张阿姨您好,您本月有一笔账单:
+> - 电梯维修分摊费:¥500
+> - 备注:3 单元电梯维修分摊
+> - 到期日:6 月 15 日
+>
+> 请通过微信小程序 / 前台 / 预存款 任选方式付款。
+
+业户:
+
+- 看明白 → 付([[collect-payment-single]])
+- 不接受 → 投诉 / 走纠纷流程(可能 [[suspend-bill]] 挂起)
+
+## 三种典型情境的不同处理
+
+### 情境 1:电梯维修分摊
+
+| 字段 | 值 |
+|---|---|
+| `bill_type` | `OneTime` |
+| `fee_type_id` | "维修分摊费"(若有此 FeeType,否则用通用"杂费")|
+| `amount` | ¥500 |
+| 备注 | 详细说明(分摊依据 + 总成本)|
+
+业务上还要**备齐资料**:维修发票、户主同意决议(若有业主大会决议)、分摊依据。这些不在系统(物业备查)。
+
+### 情境 2:违规罚款
+
+| 字段 | 值 |
+|---|---|
+| `bill_type` | `OneTime` |
+| `fee_type_id` | "罚款"(若有此 FeeType)|
+| `amount` | ¥100 |
+| 备注 | 违规事由 + 处罚依据(管理规定第 X 条) |
+
+业务上要 **业户书面确认**(违规事实),否则业户可能投诉 / 拒付。
+
+### 情境 3:跨期补开
+
+| 字段 | 值 |
+|---|---|
+| `bill_type` | `Periodic`(若是月物业费的补开)|
+| `period` | **填实际期次**(4 月)|
+| `amount` | 同正常月物业费 |
+| 备注 | "4 月物业费补开,原因 XXX" |
+
+业务人员**需要**:
+
+- 确认陈先生 4 月确实欠物业费(没有遗漏)
+- 与陈先生沟通(突然补开他可能困惑)
+
+## 与周期账单 / 计量账单的对比
+
+| 维度 | 周期账单([[create-periodic-property-fee]]) | 计量账单([[create-meter-bill-auto]]) | **手动账单(本场景)** |
+|---|---|---|---|
+| 触发 | 业务人员批量生成 | 抄表完成自动 | **业务人员单笔手工** |
+| 数量 | 一次 100-1000 张 | 一次 N 张(对应 reading 数)| **一次 1 张** |
+| 金额来源 | RatePlan + 房屋参数 | RatePlan + 用量计算 | **业务人员手填** |
+| 业务场景 | 月度固定收费 | 抄表后变动收费 | **临时收费 / 调整** |
+| sourceable | null / 周期任务 | MeterReading | **null** |
+| 频率 | 每月 1 次 | 每月 1 次 | **不定时** |
+
+## 常见问题
+
+> [!question] 手动建单和周期账单的 fee_type 重复怎么办?
+> 例如本月已经有"5 月物业费"账单,业务人员又手工建一张同 fee_type 同期次的 → 数据库 unique 约束可能拦截(若有),否则会有两张并存。
+>
+> **预防**:手动建单前确认是否已有同类账单。
+
+> [!question] 手动建单金额没限制吗?
+> 系统层面无限制。**业务上**应有审核流程(高金额 > X 元 应主管审批,但当前系统不强制此审批流)。
+
+> [!question] 跨期补开的账单影响月度报表吗?
+> 看报表的查询:
+>
+> - 按 `created_at`(账单创建时间)→ 影响 5 月报表(实际是 5 月创建)
+> - 按 `billing_period_start`(账单期次)→ 影响 4 月报表
+>
+> 不同报表用不同维度。月度对账通常按期次。
+
+> [!question] 手动建单后业户拒付?
+> 走标准流程:
+>
+> - 沟通 → 协商
+> - 不接受 → [[suspend-bill|挂起]] 等争议解决
+> - 调解失败 → 物业法务介入(走线下,系统不参与司法)
+
+> [!question] 业务人员误建一张账单怎么撤?
+> 若立即发现:[[delete-bill-unpaid|物理删除]](Unpaid 无付款)。
+> 若已发出:[[void-paid-bill|作废]](留状态留审计)。
+
+## 异常分支
+
+- 误建 → 立即删除 [[delete-bill-unpaid]]
+- 业户拒付 → [[suspend-bill]]
+- 已发现要修正金额 → 作废 + 新建 [[void-paid-bill]]
+- 批量手工建 → 待业务方提需求 + 加 BulkCreateBillsAction
+
+## 相关文档
+
+- [[bill-types-and-sources]]
+- [[bill-six-state-machine]]
+- [[create-periodic-property-fee]]
+- [[create-meter-bill-auto]]
+- [[delete-bill-unpaid]]
+- [[suspend-bill]]

prop-acc/scenarios/billing/delete-bill-unpaid.md

@@ -0,0 +1,223 @@
+---
+title: prop-acc · billing · 场景 - 物理删除未付账单(误建立刻删)
+aliases:
+  - 物理删除账单
+  - 删除未付账单
+  - delete-bill-unpaid
+  - 场景-删除未付账单
+tags:
+  - 场景
+  - prop-acc
+  - 账单
+  - 删除
+audience:
+  - 业务人员
+status: 已发布
+sub_feature: billing
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 场景:物理删除未付账单(误建立刻删)
+
+业务人员**误建**了账单(选错业户 / 写错金额 / 误触发批量生成),**立即发现**且**业户还没付**任何钱 → 走**物理删除**。`canBeDeleted()` 守护:Unpaid + 无付款关联。
+
+## 典型情境
+
+> [!example] 真实情境
+> 王主管月初手工建账单"5 月物业费 ¥800",**填错业户 ID**(应该是张阿姨,选成了陈先生)。提交后立刻发现错误。
+>
+> - 账单状态:Unpaid
+> - 业户没付过任何钱
+> - **可走物理删除**(走 [[delete-vs-void-dual-track|双轨制]] 的 delete 路径)
+> - 再重新建一张正确的(选张阿姨)
+
+## 业务人员视角
+
+### 第 1 步:发现错误
+
+| 发现时机 | 处置 |
+|---|---|
+| **立即**(几秒钟内)| 物理删(本场景)|
+| **几小时**(可能业户已收到推送)| 仍可删(若 Unpaid + 无付款)|
+| **几天**(可能业户已付)| **不可删**,走 [[void-paid-bill|作废]] |
+
+### 第 2 步:打开账单
+
+后台 → 账单 → 找到误建账单 → 进 `EditBill`(或 `ViewBill`)。
+
+### 第 3 步:点击 `DeleteAction`(标签"删除")
+
+> [!warning] 按钮可见性
+> 守护:`canBeDeleted()` = Unpaid + 无付款 + `->authorize('delete')`(`bill.delete` 权限)。
+>
+> 任何其他状态(Partial / Paid / Suspended / Void)或有任何付款关联 → 按钮**灰化**。
+
+### 第 4 步:Modal 确认
+
+```
+确认删除账单 #B-202605-501-001?
+
+⚠️ 此账单状态为 Unpaid 且无付款关联,可物理删除。
+   删除后无法恢复(但 activitylog 会保留记录)。
+
+[取消]  [确认删除]
+```
+
+### 第 5 步:提交
+
+系统:
+
+1. 再次校验 `canBeDeleted()`(防 UI 缓存过期)
+2. 物理删 Bill(从数据库消失)
+3. 写 activitylog(event=deleted,记 bill_no / amount / 操作员 / 时间)
+
+> [!info] activitylog 留什么
+> 即使 Bill 物理删了,activitylog 表还有完整记录:
+>
+> ```sql
+> SELECT * FROM activity_log
+> WHERE event = 'deleted'
+>   AND properties->>'$.bill_no' = 'B-202605-501-001';
+> ```
+>
+> 可看到"谁在什么时候删了什么账单"。详见 [[smart-bulk-delete-design]]"activitylog 设计"。
+
+### 第 6 步:重新建正确账单(若需要)
+
+走 [[create-single-bill-manual|手动建单]] 流程,选正确业户。
+
+## 系统流程
+
+```mermaid
+sequenceDiagram
+    participant 业务
+    participant Filament
+    participant Action[DeleteAction]
+    participant Bill
+    participant Activity
+    participant DB
+
+    业务->>Filament: EditBill → DeleteAction
+    Filament->>Action: handle(bill)
+    Action->>Bill: canBeDeleted()? Unpaid + 无付款 = true
+    Action->>Activity: log(event=deleted, properties={bill_no, amount, ...})
+    Action->>DB: 物理删 Bill
+    Action-->>Filament: 跳回 ListBills
+```
+
+## 业户视角
+
+业户**无感**:
+
+- 误建的账单(尤其几秒内删的)业户**根本不知道**它存在过
+- 即使业户已经收到推送,删除后再次刷新看不到了
+- 物业可选择给业户发"前述账单作废,系统误建"(可选,看业务策略)
+
+**最理想场景**:业务人员发现 → 立即删 → 业户从未感知。
+
+## `canBeDeleted` 详解
+
+`Bill::canBeDeleted()`:
+
+```php
+public function canBeDeleted(): bool
+{
+    return $this->status === BillStatus::Unpaid
+        && ! $this->hasAnyPayment();
+}
+```
+
+`hasAnyPayment()`:
+
+```php
+public function hasAnyPayment(): bool
+{
+    return $this->collectionOrderBills()->exists()
+        || $this->prepaidTransactionsRelatedToBill()->exists();
+}
+```
+
+两条都为真(Unpaid + 无付款关联) → 可删。
+
+> [!info] 为什么 Partial 不能删?
+> Partial 意味着业户已经付了一部分 → 有 CollectionOrderBill 关联 → `hasAnyPayment=true` → 拒绝物理删。
+>
+> 业户付的钱不能"凭空消失"。Partial 状态要么继续收款 → Paid;要么走 [[void-paid-bill|作废 + 退款]] 流程。
+
+## 与作废的对比
+
+| 维度 | **删除(本场景)** | [[void-paid-bill|作废]] |
+|---|---|---|
+| 适用 | Unpaid + 无付款 | 非 Paid 非 Void(基本是 Partial / Suspended) |
+| 数据库 | **从数据库消失** | 留状态 = Void |
+| activitylog | 留(event=deleted)| 留(event=voided)|
+| 业户感知 | 通常无感(未付过)| 有(看到状态 Void) |
+| 可恢复 | ❌ 不可(数据真没了)| ❌ 不可(Void 终态)|
+| 适用场景 | 误建立刻删 | 任何已付 / 有付款 / 业户已知的 |
+
+详见 [[delete-vs-void-dual-track]] 双轨制设计哲学。
+
+## 批量删除(误建一批)
+
+如果不是单张误建,而是**误触发批量生成**(例如点了一次"生成 5 月物业费"后忘了又点了一次):
+
+→ 走 [[bulk-delete-batch-mistake|智能批量删除]],走 `BulkDeleteBillsAction` 的预检查 + 三档分类。
+
+## 常见问题
+
+> [!question] 删了后悔了能恢复吗?
+> 不能(数据真的没了)。**只能重新建**(走 [[create-single-bill-manual]] 或 [[create-periodic-property-fee]])。
+>
+> 但**所有信息可从 activitylog 还原**(原 bill_no / amount / 业户 等),重建相对简单。
+
+> [!question] 业务人员误删大量账单怎么办?
+> 单删一次一张,影响有限。**批删**才容易误删大量(详见 [[smart-bulk-delete-design]] 的预检查防护)。
+>
+> 单张误删的预防:
+> - Modal 确认(默认有)
+> - 思考"是否真要删"再点
+
+> [!question] 删除有审批吗?
+> 当前**无审批流**(单签批操作)。但**权限层有控制**:`bill.delete` 是普通业务人员权限;`bill.bulkDelete` 是高敏独立权限(详见 [[smart-bulk-delete-design]])。
+
+> [!question] activitylog 表会爆掉吗?
+> 长期看会(每次单删 + 批删 + 作废 + 收款都加几条)。需归档策略(详见 [[smart-bulk-delete-design]]"常见问题"段)。
+
+> [!question] 删除影响 reading.bill_id 吗(若是计量账单)?
+> 看 cascade 设计:
+> - 若 reading 的 `bill_id` 是 FK + cascade SET NULL → 自动 nullify
+> - 若没 cascade → reading.bill_id 仍指向已删 Bill(孤儿 FK,需修复)
+>
+> 当前实施看代码。**预防**:计量账单不轻易物理删,走作废更稳妥。
+
+> [!question] 已删账单的 activitylog 怎么用?
+> ```sql
+> -- 某员工某天的全部 delete
+> SELECT
+>   id, causer_id,
+>   properties->>'$.bill_no' AS bill_no,
+>   properties->>'$.amount' AS amount,
+>   created_at
+> FROM activity_log
+> WHERE event = 'deleted'
+>   AND causer_id = ?
+>   AND created_at BETWEEN ? AND ?;
+> ```
+
+## 异常分支
+
+- 误删后想重建 → [[create-single-bill-manual]]
+- 误删一批 → 走批删的反向(无,只能 1 张张重建)
+- 不能删(有付款)→ [[void-paid-bill]]
+- 批量误建 → [[bulk-delete-batch-mistake]]
+
+## 相关文档
+
+- [[delete-vs-void-dual-track]]
+- [[smart-bulk-delete-design]]
+- [[bill-six-state-machine]]
+- [[void-paid-bill]]
+- [[bulk-delete-batch-mistake]]
+- [[audit-activitylog-trace]]
+- [[create-single-bill-manual]]

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]](类似的预警审计场景)

prop-acc/scenarios/billing/exception-partial-payment.md

@@ -0,0 +1,279 @@
+---
+title: prop-acc · billing · 场景 - 部分付状态处理(Partial)
+aliases:
+  - 部分付
+  - Partial 状态
+  - exception-partial-payment
+  - 场景-部分付账单
+tags:
+  - 场景
+  - prop-acc
+  - 账单
+  - 部分付
+audience:
+  - 业务人员
+  - 财务
+status: 已发布
+sub_feature: billing
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 场景:部分付状态处理(Partial)
+
+业户**只付了一部分**账单金额,系统状态从 Unpaid 进入 **Partial**(部分付)。后续业务人员需要跟进:**继续催收剩余款** / 提醒业户 / 或视情况调整账单。
+
+## 典型情境
+
+> [!example] 真实情境
+> 王先生(15-7-203)5 月物业费 ¥800,他到前台说"现在只能付 ¥300,剩下 ¥500 月底再补"。业务人员小李录入收款 ¥300:
+>
+> - Bill.paid_amount = 300
+> - Bill.status:Unpaid → **Partial**
+> - 建 CollectionOrderBill(allocated=300)+ CollectionOrder(+300)+ Receipt(¥300)
+>
+> 后续:王先生 5 月底再付 ¥500 → Bill.paid_amount = 800 → Bill.status: Partial → Paid。
+
+## 业户视角
+
+### 部分付场景
+
+| 业户原因 | 频率 |
+|---|---|
+| 现金不够 | 中 |
+| 短期资金紧张 | 中 |
+| 对账单部分有异议(剩余部分协商中)| 低 |
+| 拆分多次付方便记账(罕见)| 低 |
+| 业户搬走前部分清账 | 低 |
+
+### 您会感受到什么
+
+- 收据上显示**实付金额**(¥300,不是账单总额 ¥800)
+- 推送 / 小程序:"已付 ¥300,剩余 ¥500 待付"
+- 余额显示 Partial 状态(账单未完全清)
+- 月底前 reminder(若有催收机制)
+
+### 您要做什么
+
+- 在到期日前补齐剩余款
+- 走 [[collect-payment-single|继续收款]](第 2 笔 ¥500)
+- 若有困难 → 与物业沟通(协商分期 / 减免 / 挂起)
+
+## 业务人员视角
+
+### 部分付的触发
+
+走 [[collect-payment-single|单张收款]] Modal,**手动改"收款金额"小于全额**:
+
+```
+收款金额:300(改成 300,不是默认的 800)
+支付方式:现金
+```
+
+提交后:
+
+- Bill.paid_amount: 0 → 300
+- Bill.status: Unpaid → **Partial**
+
+### Partial 状态的能力
+
+| 操作 | Partial 状态 |
+|---|---|
+| `CollectPaymentAction`(继续收款)| ✅(canBePaid=true)|
+| `SuspendBillAction`(挂起)| ✅ |
+| `VoidBillAction`(作废)| ✅(canBeVoided=true,但需配套退款已付部分)|
+| `DeleteAction`(物理删)| ❌(canBeDeleted 要求 Unpaid + 无付款)|
+| `SplitBillAction`(拆账单)| 可能不允许(已付款拆分复杂,见 [[split-bill]])|
+
+### 第 2 笔收款
+
+业户来补付时:
+
+1. 找到 Partial 账单
+2. 走 `CollectPaymentAction`(状态守护 canBePaid=true,Partial 也允许)
+3. 收款金额 = ¥500(剩余应付,Modal 应默认带入 remaining)
+4. 提交 → Bill.paid_amount = 800,status: Partial → Paid
+
+### 监控 Partial 账单
+
+业务人员**定期查看** Partial 状态账单:
+
+```sql
+SELECT bill_no, resident_id, amount, paid_amount, (amount - paid_amount) AS remaining
+FROM acc_bills
+WHERE status = 'partial'
+  AND community_id = ?
+ORDER BY due_at ASC;
+```
+
+或后台 → 账单 → 过滤"状态=Partial"列表。
+
+业务人员对 Partial 业户:
+
+- 临近 due_at:发提醒
+- 已逾期:走 [[exception-overdue-bills|催收]]
+- 业户失联:走 [[suspend-bill|挂起]]
+
+## 系统流程
+
+```mermaid
+sequenceDiagram
+    participant 业户
+    participant 业务
+    participant Filament
+    participant Action[CollectPaymentAction]
+    participant DB
+
+    业户->>业务: 我只付 300(账单 800)
+    业务->>Filament: ViewBill → CollectPayment(modal,改金额=300)
+    Filament->>Action: handle(bill, 300, channel)
+    Action->>DB: 1. 建 CO(+300)+ COBill(allocated=300)
+    Action->>DB: 2. Bill.paid_amount = 300
+    Action->>DB: 3. Bill.status: Unpaid → Partial(因 300 < 800)
+
+    Note over Filament: 几周后业户补付
+
+    业户->>业务: 现在付剩下 500
+    业务->>Filament: ViewBill(Partial)→ CollectPayment(默认带 500)
+    Filament->>Action: handle(bill, 500, channel)
+    Action->>DB: 4. 建 CO(+500)+ COBill(allocated=500)
+    Action->>DB: 5. Bill.paid_amount = 800
+    Action->>DB: 6. Bill.status: Partial → Paid
+```
+
+## 数据示例(完整流水)
+
+业户付 ¥300 后:
+
+### Bill 表
+
+```
+id: 12345
+amount: 800
+paid_amount: 300
+status: Partial
+```
+
+### CollectionOrderBill(1 条)
+
+```
+bill_id: 12345
+collection_order_id: 67890
+allocated_amount: 300
+```
+
+### CollectionOrder(1 条)
+
+```
+id: 67890
+actual_amount: +300
+payment_channel: 现金
+status: Completed
+```
+
+### Receipt(1 条)
+
+```
+amount: +300
+line_items: [{ 物业费(5月)分付, 300 }]
+```
+
+业户再付 ¥500 后:
+
+### Bill 表(更新)
+
+```
+paid_amount: 800
+status: Paid  ← 收齐
+```
+
+### CollectionOrderBill(2 条总)
+
+```
+1: bill_id=12345, collection_order_id=67890, allocated=300
+2: bill_id=12345, collection_order_id=67891, allocated=500
+```
+
+业户两次付,流水**完整保留**。
+
+## 部分付的几种异常
+
+### 异常 1:业户长期不补付
+
+业户付了 ¥300 后**消失**,剩余 ¥500 长期不付:
+
+| 处置 | 路径 |
+|---|---|
+| 临时不催(可能有困难)| 不动,等业户主动 |
+| 走逾期催收 | [[exception-overdue-bills]] |
+| 业户失联 | [[suspend-bill|挂起]] |
+| 协议放弃剩余 | [[void-paid-bill|作废]](但已付 ¥300 不退,业务上协商决定)|
+
+### 异常 2:业户付错金额
+
+业户原本想付 ¥300 给物业费,误付到了水费:
+
+- 物业费 Bill 仍 Unpaid
+- 水费 Bill 多付了(超过 ¥54)
+
+处置:看实施细节,可能需手工调整 CollectionOrderBill(危险,破坏审计)。**预防**:Modal 提交前确认 Bill ID。
+
+### 异常 3:业务人员录错 paid_amount
+
+业务人员收 ¥500 现金,误录入 ¥300:
+
+- Bill.paid_amount = 300(应该 500)
+- 物业账面少记 ¥200 → 账上 vs 银行不一致
+
+处置:走 [[void-paid-bill|作废]] 原 CollectionOrder + 重录,或运维 tinker 修字段。
+
+## Partial 的边界
+
+> [!info] 严格部分付 vs 宽松部分付
+>
+> 严格实现(本系统倾向):
+> - Modal `amount` 校验 `<= remaining`
+> - 不允许超付(避免凭空多记 paid_amount)
+>
+> 宽松实现:
+> - 允许超付 → 多余部分转入业户预存款 / 留作"未分配收款"
+>
+> 当前实现看 `CollectPaymentAction` 代码。
+
+## 常见问题
+
+> [!question] 多次部分付的 Receipt 是合并还是分开?
+> **分开**(每次收款一张 Receipt)。业户拿到的是两张:
+>
+> - Receipt 1:¥300(5/15 现金付)
+> - Receipt 2:¥500(5/30 现金付)
+>
+> 不合并(合并破坏每次收款的独立凭证)。
+
+> [!question] Partial 账单挂起后能恢复继续收吗?
+> 可以。走 [[suspend-bill|挂起]] → [[resume-bill|恢复]] → 状态智能判定为 Partial(因有付款)→ 继续收款。
+
+> [!question] 部分付能预存款抵吗?
+> 看实施。理论上业户预存款余额 ¥200 + 账单剩余 ¥500 = 预存款抵 ¥200 → 仍 Partial(还差 ¥300)。需要部分抵扣功能(见 [[../prepaid/consume-multiple-bills-priority]] 部分抵讨论)。当前不一定支持。
+
+> [!question] 业户付的钱比账单总额还多(超付)?
+> 见上方"严格 vs 宽松"段。严格实现拒绝;宽松实现允许多付转入预存款。
+
+> [!question] activitylog 怎么追踪 Partial 状态历史?
+> 每次 CollectPayment 都有 log(event=collected),可看到状态从 Unpaid → Partial 的转变。
+
+## 异常分支
+
+- 单张全付 → [[collect-payment-single]](标准路径)
+- 批量付(多张一次)→ [[collect-payment-batch]]
+- 长期 Partial 无解 → [[suspend-bill]] / [[void-paid-bill]]
+- 部分付逾期催收 → [[exception-overdue-bills]]
+
+## 相关文档
+
+- [[bill-six-state-machine]]
+- [[bill-vs-collection-order]]
+- [[collect-payment-single]]
+- [[suspend-bill]]
+- [[exception-overdue-bills]]
+- [[void-paid-bill]]

prop-acc/scenarios/billing/resume-bill.md

@@ -0,0 +1,253 @@
+---
+title: prop-acc · billing · 场景 - 恢复挂起的账单
+aliases:
+  - 恢复账单
+  - ResumeBillAction
+  - 解除挂起
+  - resume-bill
+  - 场景-恢复挂起账单
+tags:
+  - 场景
+  - prop-acc
+  - 账单
+  - 调整
+audience:
+  - 业务人员
+  - 财务
+status: 已发布
+sub_feature: billing
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 场景:恢复挂起的账单
+
+[[suspend-bill|挂起]] 状态的账单,在**纠纷解决 / 业户回来**后恢复到 Unpaid / Partial,后续可正常收款。`ResumeBillAction` 对称于 SuspendBillAction。
+
+## 典型情境
+
+> [!example] 真实情境(一):业户回来了
+> 王先生(15-7-203)出国 3 个月后回来,到物业前台:"我去美国出差 3 个月,没顾上缴物业费,现在补"。
+>
+> - 王主管查看王先生账户 → 3 张挂起的物业费(Suspended)
+> - 走 `ResumeBillAction` 逐张恢复 → 状态 Suspended → Unpaid
+> - 然后走 [[collect-payment-batch|批量收款]] 一次性 ¥2,400 付清
+
+> [!example] 真实情境(二):纠纷解决
+> 陈先生与物业 5 月物业费纠纷调解结果:物业有部分过错,**协议金额 ¥600**(而不是原 ¥800)。
+>
+> - 物业要做:
+>   - 走 ResumeBill(挂起 → Unpaid)
+>   - 改账单金额(Edit Bill,若 Policy 允许 update 字段)/ 或作废原账单 + 重建 ¥600 账单
+>   - 业户付 ¥600 → 走 [[collect-payment-single]]
+
+## 业务人员视角
+
+### 第 1 步:确认恢复场景
+
+| 场景 | 后续 |
+|---|---|
+| 业户失联回来要付 | 恢复 → 收款 |
+| 纠纷解决(物业胜)| 恢复 → 收原金额 |
+| 纠纷解决(妥协)| 恢复 → 改金额(或作废+重建) |
+| 误挂起 | 恢复(reason = "误操作解除") |
+
+### 第 2 步:打开账单
+
+后台 → 账单 → 过滤"状态=Suspended" → 找到目标账单 → 进 `ViewBill`。
+
+状态显示 "🧊 Suspended",右上角只有 `ResumeBillAction` 和 `VoidBillAction` 可点。
+
+### 第 3 步:点击 `ResumeBillAction`(标签"恢复")
+
+> [!warning] 按钮可见性
+> 守护:`bill.status === Suspended` + Policy `->authorize('resume')`。
+
+Modal 表单:
+
+| 字段 | 填什么 |
+|---|---|
+| **恢复原因(reason)** | 必填,如 "业户出差回来,主动付清"|
+
+### 第 4 步:提交
+
+`ResumeBillAction` 业务层逻辑:
+
+```php
+class ResumeBillAction
+{
+    public function handle(Bill $bill, string $reason, User $user): void
+    {
+        if ($bill->status !== BillStatus::Suspended) {
+            throw new RuntimeException("账单非 Suspended 状态,不可恢复");
+        }
+
+        // 智能恢复:有部分付 → Partial;无付款 → Unpaid
+        $newStatus = $bill->paid_amount > 0
+            ? BillStatus::Partial
+            : BillStatus::Unpaid;
+
+        $bill->update([
+            'status' => $newStatus,
+            'meta' => array_merge($bill->meta ?? [], [
+                'resume_reason' => $reason,
+                'resumed_at' => now(),
+                'resumed_by' => $user->id,
+                // 可选:把这次"挂起-恢复"完整记录追加到 suspend_history 数组
+            ]),
+        ]);
+
+        activity()
+            ->performedOn($bill)
+            ->causedBy($user)
+            ->withProperties([
+                'reason' => $reason,
+                'from_status' => BillStatus::Suspended->value,
+                'to_status' => $newStatus->value,
+                'bill_no' => $bill->bill_no,
+            ])
+            ->event('resumed')
+            ->log('账单已恢复');
+    }
+}
+```
+
+### 第 5 步:通知业户(可选)
+
+恢复后立即提示业户付款:
+
+> 王先生,您的 3 张挂起账单已恢复(合计 ¥2,400),现在可以付清。
+
+### 第 6 步:走收款
+
+恢复后走 [[collect-payment-single]] 或 [[collect-payment-batch]]。
+
+## 系统流程
+
+```mermaid
+sequenceDiagram
+    participant 业户
+    participant 业务
+    participant Filament
+    participant Action[ResumeBillAction]
+    participant DB
+
+    业户->>业务: 我要付挂起的账单
+    业务->>Filament: ViewBill(Suspended)→ ResumeBillAction(modal, reason)
+    Filament->>Action: handle(bill, reason, user)
+    Action->>Action: 校验 status === Suspended
+    Action->>Action: 判定恢复后状态(Unpaid 或 Partial)
+    Action->>DB: 1. bill.status = Unpaid / Partial
+    Action->>DB: 2. bill.meta.resume_reason / resumed_at / resumed_by
+    Action->>Activity: 3. log(event=resumed)
+    Filament-->>业务: 成功
+
+    业务->>Filament: 继续走收款流程
+```
+
+## 智能恢复:Partial vs Unpaid
+
+`ResumeBillAction` 判断恢复到哪个状态:
+
+| 挂起前的状态 | 恢复后的状态 |
+|---|---|
+| Unpaid(无付款)→ Suspended | **Unpaid** |
+| Partial(部分付)→ Suspended | **Partial** |
+
+代码层用 `paid_amount > 0` 判断。这样恢复后业户的"已付部分"还在账户上。
+
+## 多次"挂起-恢复"的历史记录
+
+如果同一账单被多次挂起 / 恢复:
+
+```json
+// Bill.meta 推荐结构(看实现是否如此)
+{
+  "suspend_reason": "最近一次挂起原因",
+  "suspended_at": "最近一次挂起时间",
+  "resume_reason": "最近一次恢复原因",
+  "resumed_at": "最近一次恢复时间",
+  "suspend_history": [
+    {
+      "suspended_at": "...",
+      "suspended_by": "...",
+      "suspend_reason": "...",
+      "resumed_at": "...",
+      "resumed_by": "...",
+      "resume_reason": "..."
+    },
+    {  ...第二次... },
+    ...
+  ]
+}
+```
+
+第一次"挂-恢复"完整存进 `suspend_history` 数组,新一次的"挂"覆盖 `suspend_reason`/`suspended_at`。完整审计可追溯。
+
+> [!info] 实施细节
+> 当前 `SuspendBillAction` / `ResumeBillAction` 是否实现 `suspend_history` 数组看代码。简版实现可能只覆盖最近一次(无 history)。
+
+## 业户视角
+
+### 您会感受到什么
+
+- 收到通知"您的账单已恢复,请尽快付款"
+- 小程序"我的账单"看到状态:Suspended → Unpaid
+- 后续付款流程同正常
+
+### 业户配合
+
+业户应:
+
+- 立即付款(避免再次进入逾期)
+- 若有付款困难,提前告诉物业(可能再次挂起 + 协商)
+
+## 与其他模块的对比
+
+| 模块 | 类似 Suspend / Resume |
+|---|---|
+| **billing(本)** | SuspendBillAction / ResumeBillAction |
+| deposit | freeze / unfreeze(账户级,详见 [[../deposit/unfreeze-after-mediation]]) |
+| prepaid | FreezeAccountAction / ReactivateAccountAction([[../prepaid/unfreeze-after-verification]]) |
+| meter | 无(meter 用 decommission,不可恢复)|
+
+**billing / deposit / prepaid 都有"挂起 / 恢复"的对偶设计** —— 这是金融类业务的通用模式。
+
+## 常见问题
+
+> [!question] 恢复后业户又找不到了怎么办?
+> 走 [[exception-overdue-bills|逾期催收]] → 多次催不到 → 再 [[suspend-bill|挂起]] 一次(reason 改"再次失联")。多次"挂-恢复"循环说明业户有问题,需法律 / 走绕监管路径。
+
+> [!question] 恢复时账单期次已经过去很久(例如 5 月账单 11 月才恢复),还按原 due_at 算逾期吗?
+> 看业务策略:
+>
+> - 严格:仍按原 due_at(5 月底 + 宽限期)→ 一恢复就是逾期(可能加滞纳金)
+> - 宽松:挂起期间不算逾期 → 恢复时给新的宽限期(例如恢复后 + 7 天)
+>
+> 当前实施看 `OverdueBillsListWidget` 的判断逻辑。
+
+> [!question] 误挂起立即恢复,activitylog 显示两条(suspended + resumed)对吗?
+> 对。每次状态变化各一条 log。可在 reason 备注"误操作 + 立即恢复"。
+
+> [!question] 恢复后能直接改金额吗?
+> 看 Policy / EditBill。Unpaid 状态可能允许 Edit(改 amount)。Partial 状态(已付款部分)改金额复杂(原 paid_amount 怎么算)→ 不推荐改,改用"作废 + 重建"。
+
+> [!question] 恢复操作需要审批吗?
+> 当前**无审批流**(单签批操作)。业务上若需要审批(例如金额大),靠人员制度保障(高权限人员才操作)。
+
+## 异常分支
+
+- 误恢复(应作废)→ [[void-paid-bill]] 走作废路径
+- 恢复后改金额 → 复杂,走作废 + 重建([[create-single-bill-manual]])
+- 长期挂起最终决定作废 → [[void-paid-bill]]
+
+## 相关文档
+
+- [[suspend-bill]]
+- [[bill-six-state-machine]]
+- [[void-paid-bill]]
+- [[collect-payment-single]]
+- [[exception-overdue-bills]]
+- [[audit-activitylog-trace]]
+- [[../deposit/unfreeze-after-mediation]](deposit 同类对比)
+- [[../prepaid/unfreeze-after-verification]](prepaid 同类对比)

prop-acc/scenarios/billing/split-bill.md

@@ -0,0 +1,220 @@
+---
+title: prop-acc · billing · 场景 - 拆账单(SplitBillAction)
+aliases:
+  - 拆账单
+  - 账单分摊
+  - SplitBillAction
+  - split-bill
+  - 场景-拆账单
+tags:
+  - 场景
+  - prop-acc
+  - 账单
+  - 调整
+audience:
+  - 业务人员
+  - 财务
+status: 已发布
+sub_feature: billing
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 场景:拆账单(SplitBillAction)
+
+业户**多人共住一户**(房东 + 租户 / 合租),物业费 / 水电气**按比例分摊**到各自账户,业务人员走 `SplitBillAction` 把一张账单**拆成多张**。
+
+## 典型情境
+
+> [!example] 真实情境
+> 12-3-501 房屋:
+>
+> - 房东陈先生(产权人)
+> - 租户李先生(2026 年 1 月起租)
+>
+> 合同约定:**物业费房东付,水电气租户付**。但系统月初按"业户=陈先生"批量生成的:
+>
+> - 5 月物业费 ¥800(应给陈先生)
+> - 5 月水费 ¥54(实际应租户付)
+> - 5 月电费 ¥168(实际应租户付)
+> - 5 月燃气 ¥30(实际应租户付)
+>
+> 业务人员王主管要把后 3 张账单**重新分给租户李先生**(从陈先生的账户拆出去)。
+
+## 业务人员视角
+
+### 第 1 步:确认拆单需求
+
+业户来电话 / 合同约定:
+
+- 房东本人来报备"水电气以后租户付"
+- 看合同 / 租赁备案
+- 确认租户身份(可能已在 `community_user_profiles` 注册)
+
+### 第 2 步:逐张拆单
+
+**(本场景默认逐张拆,不是一次 SplitAll)**
+
+后台 → 账单 → 找到 5 月水费 Bill → 进 `ViewBill` → 点 `SplitBillAction`(标签"拆账单")。
+
+> [!warning] 按钮可见性
+> 看 `SplitBillAction` 守护(应该是 Unpaid + 业务权限)。Paid / Void 状态可能不允许拆(已付的钱难撤)。
+
+### 第 3 步:Modal 填参数
+
+| 字段 | 填什么 |
+|---|---|
+| **原账单** | 5 月水费 ¥54(陈先生)|
+| **拆分方式** | 按比例 / 按金额 / 按目标业户 |
+| **新业户** | 李先生(下拉选)|
+| **拆给新业户的金额** | ¥54(全部 → 全转给李先生 = 业户更换;或部分 → 拆成两张)|
+| **拆分原因** | 必填,如 "房东与租户合同约定:水费由租户付"|
+
+### 第 4 步:提交
+
+`SplitBillAction` 业务逻辑(看实现):
+
+**模式 1:全转给新业户**(本场景常见)
+
+```
+- 原 Bill #X(陈先生):状态翻 Void(原账单作废)+ 标 split_to=新 Bill ID
+- 新建 Bill #Y(李先生):amount=54, status=Unpaid
+- 关联(meta 记拆分来源)
+```
+
+**模式 2:部分拆分**(罕见)
+
+```
+- 原 Bill #X(陈先生):amount 改为 30(原 54 - 拆出 24)
+- 新建 Bill #Y(李先生):amount=24
+- 两张同存
+```
+
+> [!info] 实施细节看代码
+> `SplitBillAction` 的具体行为(全转 vs 部分拆 vs 按比例)看 `packages/prop-acc/src/Actions/Bills/SplitBillAction.php`。本文按业务场景描述。
+
+### 第 5 步:通知双方
+
+- 陈先生:"5 月水费已转给租户李先生付,您不必付了"
+- 李先生:"您 5 月水费 ¥54 新账单已生成,请于 6 月 15 日前付清"
+
+### 第 6 步:重复对电费 / 燃气
+
+逐张拆。3 张全拆完后:
+
+- 陈先生只欠 5 月物业费 ¥800
+- 李先生欠 5 月水费 + 电费 + 燃气 ¥252
+
+## 系统流程(全转模式)
+
+```mermaid
+sequenceDiagram
+    participant 业务
+    participant Filament
+    participant Action[SplitBillAction]
+    participant DB
+    participant Activity[activitylog]
+
+    业务->>Filament: ViewBill(陈先生水费)→ SplitBillAction
+    Filament->>Action: handle(bill=陈先生水费, mode=Full, target=李先生, reason)
+    Action->>Action: 校验 bill.status (Unpaid)
+    Action->>Action: 校验 target_resident 在同 community
+
+    Action->>DB: 开启事务
+    Action->>DB: 1. 原 Bill 翻 Void + meta.split_to=新 ID
+    Action->>DB: 2. 新建 Bill(target=李先生, amount=54, status=Unpaid, meta.split_from=原 ID)
+    Action->>Activity: log(event=split, properties)
+    Action->>DB: 提交
+
+    Filament-->>业务: 跳转新 Bill
+```
+
+## 业户视角
+
+### 陈先生(原账单业户)
+
+收到通知:
+
+> 陈先生您好,您的 5 月水费 ¥54 已根据合同拆给租户李先生付。您原账单已作废,无需付款。
+
+### 李先生(新账单业户)
+
+收到通知:
+
+> 李先生您好,您 5 月水费 ¥54 账单已生成(由 12-3-501 房屋的合同拆分而来),请于 6 月 15 日前付清。
+
+## 拆单的几种业务场景
+
+| 场景 | 频率 | 拆法 |
+|---|---|---|
+| **房东 / 租户合同分摊** | 中(本场景)| 按费用类型分,水电气给租户 |
+| **多业主分摊**(共有产权)| 罕见 | 按比例 |
+| **公摊费用追溯** | 中(本月才发现某费用应分摊)| 按户数 |
+| **企业内部子公司分摊**(商铺)| 罕见 | 按合同 |
+
+## 与"作废 + 重建"的对比
+
+| 维度 | 拆账单(SplitBillAction)| 作废 + 手动重建 |
+|---|---|---|
+| 单一操作 | ✅(一个 Action 完成)| ❌(走 2-3 个 Action)|
+| 关联追溯 | ✅(meta 标 split_from/to)| ❌(无系统关联)|
+| 审计 | activitylog event=split | 多条 activitylog(void + create)|
+| 灵活性 | 受 SplitBillAction 限制 | 更灵活(可改任意字段)|
+| 推荐场景 | 简单拆分(全转 / 部分按金额)| 复杂拆分 / 拆完还要改其他字段 |
+
+## 拆单后已付款的复杂情况
+
+> [!warning] 已付款 Bill 拆单的复杂度
+>
+> 如果原账单**已付一部分**(Partial 状态):
+>
+> - 原账单作废 → 已付的部分怎么办?
+> - 退还给原业户 → 走作废 + 退款([[void-paid-bill]] 类似)
+> - 新账单上记 paid_amount? 不行(原业户付的钱不该算到新业户)
+>
+> 实施上 `SplitBillAction` 可能**不允许 Partial 状态拆**(只允许 Unpaid)。看具体实现。
+>
+> **推荐**:拆单前先处理已付款(作废 + 退款 / 退现金后)再拆。
+
+## 常见问题
+
+> [!question] 拆给的业户不存在(系统里没注册)怎么办?
+> 先建业户档案(community 模块的 `community_user_profiles`)→ 然后拆。
+
+> [!question] 拆错了(应该拆给李先生,选成王先生)?
+> 看实施:
+> - 若新 Bill 仍 Unpaid → 走 [[delete-bill-unpaid|删除]] + 重拆
+> - 若已 Paid → 麻烦,需走作废 + 退款 + 重拆
+
+> [!question] 按比例自动拆所有账单(房东 50% / 租户 50% 物业费)?
+> 当前 `SplitBillAction` 应是**逐张操作**。按比例批量拆需要业务方提需求 + 加 `BulkSplitBillsAction`(待实现)。
+
+> [!question] 拆单的合规性?
+> 物业要确保:
+> - 业户合同明确分摊条款
+> - 双方书面同意拆分
+> - 物业内部审批留底
+>
+> 系统层面只管账单数据,合规由物业流程保障。
+
+> [!question] 一张账单能拆成 3+ 份吗(多人合租 3 人均摊)?
+> 看 SplitBillAction 设计。简单实现是**一次拆 2 份**(原账单 + 新账单)。要拆 3 份需 2 次操作:
+>
+> 1. 第 1 次:原账单(¥54)→ 拆出 ¥18(给租户 A),原账单剩 ¥36
+> 2. 第 2 次:原账单(¥36)→ 拆出 ¥18(给租户 B),原账单剩 ¥18(给房东自己)
+>
+> 累加得到三份 ¥18 各自归一人。
+
+## 异常分支
+
+- 拆错了 → 删除 / 作废新 Bill,原 Bill 状态可能要恢复(看实施)
+- 已付的拆 → 走 [[void-paid-bill]] 流程,复杂
+- 简单"换业户"(不拆,只改账单的 resident_id)→ 可能用 Edit Bill 直接改(若 Policy 允许),但**强烈不推荐**(破坏追溯)→ 用拆单更标准
+
+## 相关文档
+
+- [[bill-six-state-machine]]
+- [[delete-bill-unpaid]]
+- [[void-paid-bill]]
+- [[suspend-bill]]
+- [[bill-vs-collection-order]]

prop-acc/scenarios/billing/suspend-bill.md

@@ -0,0 +1,241 @@
+---
+title: prop-acc · billing · 场景 - 挂起账单(业户失联/纠纷)
+aliases:
+  - 挂起账单
+  - SuspendBillAction
+  - 暂停收款
+  - suspend-bill
+  - 场景-挂起账单
+tags:
+  - 场景
+  - prop-acc
+  - 账单
+  - 调整
+audience:
+  - 业务人员
+  - 财务
+status: 已发布
+sub_feature: billing
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 场景:挂起账单(业户失联 / 纠纷)
+
+业户**与物业有纠纷**或**长期失联**,该账单暂时**不应被收款 / 不应被催收**,但又不能直接作废(纠纷可能解决,业户可能出现)。走 `SuspendBillAction` 把账单挂起,状态 Unpaid → Suspended,后续可 [[resume-bill|恢复]]。
+
+## 典型情境
+
+> [!example] 真实情境(一):业户失联
+> 王先生(15-7-203)三个月没缴物业费(累计 3 张账单 ¥2,400 Unpaid),物业多次联系电话不通、上门无人。物业认为业户可能搬走 / 失联 / 出国,**先把这 3 张账单挂起**,避免:
+>
+> - 月度报表"应收账款"虚高(挂着收不回来)
+> - 催收资源浪费(联系不上的还反复发短信)
+> - 业户突然回来时账单仍在(不会变作废)
+
+> [!example] 真实情境(二):纠纷期间
+> 陈先生认为 5 月物业费 ¥800 不合理(物业服务质量纠纷),拒绝付。物业 / 业主委员会调解中,**挂起该账单**,等调解结果:
+> - 调解物业胜诉 → [[resume-bill|恢复]] → 业户付
+> - 调解业户胜诉 → [[void-paid-bill|作废]] → 不收
+> - 调解妥协 → 走拆账单 / 重新算金额
+
+## 业务人员视角
+
+### 第 1 步:确认挂起场景
+
+| 场景 | 是否走挂起 |
+|---|---|
+| 业户失联 1-3 个月 | ✅ 挂起(等业户出现) |
+| 业户失联 >6 个月 | 可考虑作废(看物业政策)|
+| 业户纠纷中 | ✅ 挂起 |
+| 业户拒不付 | 不挂起,走逾期催收([[exception-overdue-bills]]) |
+| 业户真的搬走永久不再来 | 走作废 / 法律手段 |
+
+### 第 2 步:打开账单
+
+后台 → 账单 → 找到 Unpaid Bill → 进 `ViewBill`。
+
+### 第 3 步:点击 `SuspendBillAction`(标签"挂起")
+
+> [!warning] 按钮可见性
+> 守护:`bill.status === Unpaid || Partial` + Policy `->authorize('suspend')`。Paid / Void / Suspended 状态灰化。
+
+Modal 表单:
+
+| 字段 | 填什么 |
+|---|---|
+| **挂起原因(reason)** | **必填且详细**,如 "业户失联 3 个月,电话不通 + 上门无人 + 微信无回应" |
+
+### 第 4 步:提交
+
+`SuspendBillAction` 业务层逻辑:
+
+```php
+class SuspendBillAction
+{
+    public function handle(Bill $bill, string $reason, User $user): void
+    {
+        if (! in_array($bill->status, [BillStatus::Unpaid, BillStatus::Partial])) {
+            throw new RuntimeException("账单状态不可挂起");
+        }
+
+        $bill->update([
+            'status' => BillStatus::Suspended,
+            'meta' => array_merge($bill->meta ?? [], [
+                'suspend_reason' => $reason,
+                'suspended_at' => now(),
+                'suspended_by' => $user->id,
+            ]),
+        ]);
+
+        activity()
+            ->performedOn($bill)
+            ->causedBy($user)
+            ->withProperties([
+                'reason' => $reason,
+                'from_status' => $bill->getOriginal('status'),
+                'to_status' => BillStatus::Suspended->value,
+                'bill_no' => $bill->bill_no,
+            ])
+            ->event('suspended')
+            ->log('账单已挂起');
+    }
+}
+```
+
+### 第 5 步:通知业户(可选)
+
+- 失联场景:不通知(联系不上,无意义)
+- 纠纷场景:通知"您的账单已挂起,等调解结果"
+
+## 系统流程
+
+```mermaid
+sequenceDiagram
+    participant 业务
+    participant Filament
+    participant Action[SuspendBillAction]
+    participant DB
+    participant Activity
+
+    业务->>Filament: ViewBill → SuspendBillAction(modal)
+    Filament->>Action: handle(bill, reason, user)
+    Action->>Action: 校验 status Unpaid/Partial
+    Action->>DB: 开启事务
+    Action->>DB: 1. bill.status=Suspended
+    Action->>DB: 2. bill.meta.suspend_reason / suspended_at / suspended_by
+    Action->>Activity: 3. log(event=suspended)
+    Action->>DB: 提交
+
+    Filament-->>业务: 成功
+```
+
+## 挂起后的能力对照
+
+| 操作 | Unpaid / Partial | **Suspended** |
+|---|---|---|
+| `CollectPaymentAction`(收款)| ✅ | ❌(`canBePaid=false`)|
+| `CollectPaymentAction`(预存款抵)| ✅ | ❌ |
+| `SuspendBillAction`(再挂起)| ✅ | ❌(已是 Suspended)|
+| `ResumeBillAction`(恢复)| ❌ | ✅ |
+| `VoidBillAction`(作废)| ✅(canBeVoided=true)| ✅ |
+| 看账单 / 看历史 | ✅ | ✅(只读)|
+| 出现在 `OverdueBillsListWidget` | ✅(若到期)| ❌(挂起不算逾期)|
+| 出现在月度账单清单 | ✅ | ✅(标 Suspended)|
+
+> [!info] Suspended 与 Overdue 的关系
+> 挂起的账单**不算逾期**(catch up 不会出现在催收清单)。但**期次仍在历史**(归属本月报表)。
+>
+> 这是**有意设计**:挂起的目的是停掉催收 + 暂时退出收款流程,但不让账单凭空消失。
+
+## 业户视角
+
+### 失联场景(无感)
+
+业户失联本来就联系不上,业务方决定挂起 → 业户**完全不知道**。等业户出现时:
+
+- 业户来电话 / 上门
+- 业务人员说"您有挂起的账单 ¥XXX,我现在帮您恢复 + 收款"
+- 走 [[resume-bill|恢复]] → 收款
+
+### 纠纷场景
+
+业户**可能收到通知**(看物业政策):
+
+> 陈先生您好,您的 5 月物业费账单已挂起(暂停收款),等纠纷调解结果。预计 X 月 Y 日前出结果。
+
+业户:
+
+- 知情 + 等待
+- 期间不会被催收
+- 调解后走 [[resume-bill|恢复]] 或 [[void-paid-bill|作废]]
+
+## 与"作废"的对比
+
+| 维度 | **挂起(Suspended,本场景)** | [[void-paid-bill|作废 Void]] |
+|---|---|---|
+| 是否可恢复 | ✅ 走 [[resume-bill]]| ❌ 终态 |
+| 业务场景 | 临时暂停(纠纷 / 失联)| 永久消除 |
+| 报表归属 | 仍在本期(标 Suspended)| 标 Void(可过滤) |
+| 后续是否能收款 | 恢复后能 | 不能(已 Void)|
+
+**简单判断**:**不确定后续怎么办 → 挂起**;**确定不再收 → 作废**。
+
+## 长期 Suspended 的处理
+
+挂起后**长期没恢复 / 没作废**的账单,业务上需要定期 review:
+
+| 挂起时长 | 推荐处置 |
+|---|---|
+| < 1 月 | 正常等待 |
+| 1-3 月 | 评估业户情况(再次联系)|
+| 3-6 月 | 决定:恢复(若有进展)/ 作废(若无希望)|
+| > 6 月 | 通常作废(或走法律手段)|
+
+可加 audit 场景:**"长期挂起账单清单"**(类似 [[../deposit/audit-long-pending-accounts]])。当前 issue.md 未明确实施,可作为未来扩展。
+
+## 常见问题
+
+> [!question] 挂起原因填得详细到什么程度?
+> **越详细越好**。审计要求 + 业户事后查询 + 业务复盘都需要。推荐结构:
+>
+> - 触发事件(纠纷 / 失联 / 其他)
+> - 已采取的联系措施(电话 / 上门 / 微信)
+> - 业务上的预期(等调解 / 等业户回来 / 等司法)
+
+> [!question] 挂起的账单已经有部分付(Partial)?
+> 看实施。SuspendBillAction 可能允许(从 Partial → Suspended)。已付的部分**不退**(只是暂停后续收款)。
+
+> [!question] 同一业户多张挂起,能批量挂吗?
+> 当前**无批量挂起 UI**。逐张走 SuspendBillAction,效率低但可控。
+>
+> 可加 `BulkSuspendBillsAction`(类似批删的设计),业务方提需求时实施。
+
+> [!question] 挂起影响 prepaid 自动抵扣 job?
+> 是。job 应**跳过 Suspended 状态**的账单。设计上看 [[../prepaid/auto-deduction-design]]。
+
+> [!question] activitylog 怎么查挂起记录?
+> ```sql
+> SELECT * FROM activity_log
+> WHERE event = 'suspended'
+>   AND created_at BETWEEN ? AND ?
+> ORDER BY created_at DESC;
+> ```
+>
+> 详见 [[audit-activitylog-trace]]。
+
+## 异常分支
+
+- 业户出现/纠纷解决 → [[resume-bill]]
+- 确定不再收 → [[void-paid-bill]]
+- 业务上误挂起 → [[resume-bill]] 撤回(reason 改"误操作")
+- 长期挂起无解 → 作废 / 法律手段(待业务方明确)
+
+## 相关文档
+
+- [[bill-six-state-machine]]
+- [[resume-bill]]
+- [[void-paid-bill]]
+- [[exception-overdue-bills]]
+- [[audit-activitylog-trace]]
+- [[../deposit/freeze-during-dispute]](类似的"暂停"模式对比)

prop-acc/scenarios/billing/void-paid-bill.md

@@ -0,0 +1,269 @@
+---
+title: prop-acc · billing · 场景 - 作废已付账单(走作废 + 退款)
+aliases:
+  - 作废账单
+  - VoidBillAction
+  - void-paid-bill
+  - 作废加退款
+  - 场景-作废已付账单
+tags:
+  - 场景
+  - prop-acc
+  - 账单
+  - 作废
+audience:
+  - 业务人员
+  - 财务
+status: 已发布
+sub_feature: billing
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 场景:作废已付账单(走作废 + 退款)
+
+业户**已付**的账单需要消除(误开账单业户付了 / 业户事后投诉成功 / 调解结果物业认错)。走**作废 + 退款**组合,留状态留审计 + 退还业户。
+
+> [!warning] 当前实施状态
+> `VoidBillAction` 本身**只翻状态 + 留 meta + 写 activitylog**(`canBeVoided=true` for **非 Paid**)。
+>
+> **Paid 状态 `canBeVoided=false`**,意味着 `VoidBillAction` 不直接处理 Paid 账单的作废。需要走**类似 meter 的修正流程**:
+>
+> - 当前手工 / tinker(运维操作)
+> - 未来扩展 `VoidPaidBillAction` 自动化(包含退款 + 红字 CO 等)
+>
+> 详见 [[delete-vs-void-dual-track]]"`canBeVoided` 的微妙之处"段。
+
+## 典型情境
+
+### 情境 1:Partial 状态作废(系统支持)
+
+> [!example] 真实情境
+> 陈先生 5 月物业费 ¥800,部分付了 ¥300(状态 Partial)。后续物业承认服务有问题,**双方协议作废账单**,退 ¥300 给业户。
+>
+> 业务流程:
+> 1. 走 `VoidBillAction`(Partial → Void)
+> 2. **手工配套退款**(给陈先生退 ¥300 现金 / 微信)
+> 3. (理想)系统自动建红字 CollectionOrder(待扩展)
+
+### 情境 2:Paid 状态作废(当前需手工)
+
+> [!example] 真实情境
+> 张阿姨 5 月物业费 ¥800 已付清(Paid)。物业发现金额算错了(应该 ¥600),**多收 ¥200**。要全额作废 + 退还 ¥800 + 重新建一张 ¥600 账单。
+>
+> 当前流程(因 canBeVoided=false for Paid,VoidBillAction 不允许):
+> 1. **运维 tinker 操作**:把 Bill 状态强制改为 Void + 记 meta
+> 2. **手工建红字 CollectionOrder**(¥-800)+ Receipt(红字)
+> 3. **物业线下退款** ¥800 给业户
+> 4. **手工建新 Bill** ¥600
+> 5. 业户付 ¥600
+>
+> 整个流程**复杂、易出错、无 UI**。issue.md Q6 未明确实施时间,标"待业务方明确"。
+
+## 业务人员视角(Partial 作废)
+
+### 第 1 步:确认作废
+
+- 协议作废(业户与物业书面达成)
+- 调解 / 司法判决物业方有责
+- 业务上的特殊情况
+
+### 第 2 步:打开账单
+
+后台 → 账单 → 找到 Partial Bill → 进 `ViewBill`。
+
+### 第 3 步:点击 `VoidBillAction`(标签"作废")
+
+> [!warning] 按钮可见性
+> 守护:`canBeVoided()` = 非 Paid 非 Void + `->authorize('void')`(`bill.void` 权限)。
+
+Modal 表单:
+
+| 字段 | 填什么 |
+|---|---|
+| **作废原因(reason)** | **必填**,如 "调解结果:物业服务质量有问题,账单作废 + 退还已付款" |
+
+### 第 4 步:提交
+
+`VoidBillAction` 业务逻辑(详见 [[delete-vs-void-dual-track]]):
+
+```php
+$bill->update([
+    'status' => BillStatus::Void,
+    'meta' => array_merge($bill->meta ?? [], [
+        'voided_reason' => $reason,
+        'voided_at' => now(),
+        'voided_by' => $user->id,
+    ]),
+]);
+
+activity()->performedOn($bill)->causedBy($user)
+    ->withProperties([
+        'reason' => $reason,
+        'from_status' => $bill->getOriginal('status'),
+        'to_status' => 'Void',
+        'bill_no' => $bill->bill_no,
+        'amount' => $bill->amount,
+        'paid_amount' => $bill->paid_amount,  // 关键:有付款需要后续退
+    ])
+    ->event('voided')
+    ->log('账单已作废');
+```
+
+### 第 5 步:手工退款(若 paid_amount > 0)
+
+VoidBillAction **本身不退钱**。业务人员后续:
+
+1. 看 activitylog 的 `paid_amount` 字段 = ¥300
+2. 联系业户确认退款方式(微信 / 现金 / 银行转账)
+3. 走线下退款(物业财务实际打钱)
+4. **理想**:建红字 CollectionOrder(`actual_amount=-300`,`type=Bill`,关联到该 Bill)+ Receipt 红字(待扩展自动化)
+
+> [!info] 当前简化做法
+> Bill 作废后:
+> - Bill 状态 = Void
+> - CollectionOrderBill 关联**不动**(审计需要)
+> - 业务人员**线下手工退款**给业户
+> - 系统中没有红字 CO / 红字 Receipt(待 `VoidPaidBillAction` 自动化)
+>
+> 财务账面**临时不一致**(Bill 是 Void 但 CO 仍是 Completed),需事后人工对账修复。
+>
+> **业务方提需求时,优先级会上来。**
+
+### 第 6 步:通知业户
+
+> 陈先生您好,您的 5 月物业费账单已作废,已付的 ¥300 我们将退还您。请确认收款方式。
+
+## 业务人员视角(Paid 作废,当前 tinker 流程)
+
+详见上方"情境 2"。当前**没自动化**:
+
+1. 评估业务必要性(确认无误后操作)
+2. 联系运维 tinker:
+   ```php
+   $bill->update([
+     'status' => BillStatus::Void,
+     'meta' => array_merge($bill->meta ?? [], [
+       'voided_reason' => $reason,
+       'voided_at' => now(),
+       'voided_by' => $user->id,
+       'manual_void' => true,  // 标记是 tinker 手工作废
+     ]),
+   ]);
+   ```
+3. 走完整退款流程(线下退 + 系统记一笔红字 CO/Receipt 若可能)
+4. 重建账单(走 [[create-single-bill-manual]])
+5. 业户付新账单
+
+## 系统流程
+
+```mermaid
+sequenceDiagram
+    participant 业务
+    participant Filament
+    participant Action[VoidBillAction]
+    participant DB
+    participant Activity
+
+    业务->>Filament: ViewBill(Partial)→ VoidBillAction
+    Filament->>Action: handle(bill, reason, user)
+    Action->>Action: 校验 canBeVoided(非 Paid 非 Void)
+    Action->>DB: 1. bill.status = Void + meta
+    Action->>Activity: 2. log(event=voided, paid_amount=300)
+    Filament-->>业务: 成功
+
+    业务->>业务: 看 activitylog paid_amount=300
+    业务->>业户: 线下退款 + 通知
+
+    Note over Action: 注:不自动建红字 CO/Receipt
+    Note over Action: 待 VoidPaidBillAction 实现
+```
+
+## 业户视角
+
+### 您会感受到什么
+
+- 收到通知"您的账单 #XXX 已作废,理由 XXX"
+- 已付的钱**未来几天**收到退款
+- 收到收据备注(若系统支持)
+- 小程序账单状态:Partial → Void
+
+### 您要做什么
+
+- 确认收款方式
+- 接收退款(银行 / 微信 / 现金)
+- 如有疑问联系物业
+
+## 与 prop-acc 其他作废的对比
+
+| 模块 | 作废 / void 机制 |
+|---|---|
+| **billing(本)** | `VoidBillAction`(非 Paid 非 Void)+ 手工退款配套(Paid 待扩展) |
+| deposit | 无单独 void;用 [[../deposit/force-close-refund|ForceClose refund]] 等机制 |
+| prepaid | 无 void;走 [[../prepaid/refund-partial-after-consume|refund]] |
+| meter | 无 void(reading 不可改,见 [[../meter/exception-readings-locked-after-bill]])|
+| adhoc | 走 [[../adhoc/cancel-amount-error-redo|VoidAction]](类似 billing 设计)|
+
+bill 的 void 是**最完整的"账单作废"设计**,但 Paid 的作废**仍待补**(整个 prop-acc 通用问题:已收款的"反向"流程都不够成熟)。
+
+## 已知限制(issue.md Q6 待补)
+
+- **VoidBillAction 不处理 Paid 状态**:`canBeVoided=false`,需走专门流程(未实现)
+- **作废后红字 CO + Receipt 自动生成**:未实现,需手工
+- **退款金额自动算 / 自动建红字凭证**:未实现
+- **BulkRefundBillsAction**(批量退款):未实现,issue.md 标优先级低
+
+## 常见问题
+
+> [!question] 作废后业户已付款怎么记账?
+> 当前(简版):
+> - Bill 状态 = Void
+> - CollectionOrderBill 关联保留(`allocated_amount=300`)
+> - 物业账面"已收 ¥300"(从 CO 角度)= 实际"应退给业户"
+>
+> 财务月度对账时需**人工识别这种情况**(账上有钱但 Bill 已 void = 待退款)。
+>
+> 未来自动化后:作废 + 同时建红字 CO(¥-300)抵消原 CO,账面归零。
+
+> [!question] 作废能撤销吗?
+> 不能(Void 是终态,详见 [[bill-six-state-machine]])。如需"恢复":新建一张同信息 Bill。
+
+> [!question] 已付 + 已被预存款抵的 Bill 作废,怎么退到预存款?
+> 自动化未实现。手工流程:
+>
+> 1. tinker 作废 Bill
+> 2. 给业户预存款手工 deposit(走 [[../prepaid/deposit-additional-topup]] 把 ¥800 充回预存款)
+> 3. 备注"账单作废退还"
+>
+> 系统层面:理想是自动反向(`PrepaidAccount::reverseConsume` 之类),未实现。
+
+> [!question] activitylog 怎么查作废历史?
+> ```sql
+> SELECT * FROM activity_log
+> WHERE event = 'voided'
+>   AND properties->>'$.bill_no' = ?
+> ORDER BY created_at DESC;
+> ```
+
+> [!question] 业户对作废结果不满意?
+> 已作废不可逆。业户:
+> - 走司法 / 仲裁
+> - 业务方重新协商(可能再建新账单)
+
+## 异常分支
+
+- Unpaid 无付款 → [[delete-bill-unpaid|物理删]] 更干净
+- 批量作废 → [[bulk-delete-batch-mistake]] 选 DeleteAndVoid 模式
+- 业户拒绝接受作废 → 协商 / 司法
+- Paid 作废自动化 → 待业务方明确 + 实施 VoidPaidBillAction
+
+## 相关文档
+
+- [[delete-vs-void-dual-track]]
+- [[smart-bulk-delete-design]]
+- [[bill-six-state-machine]]
+- [[delete-bill-unpaid]]
+- [[bulk-delete-batch-mistake]]
+- [[audit-activitylog-trace]]
+- [[../meter/exception-readings-locked-after-bill]](类似 已落账修正)
+- [[../adhoc/cancel-amount-error-redo]](adhoc 同类对比)