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,43 +195,43 @@
       "obsidian-git:Open Git source control": false
     }
   },
-  "active": "849c5ff8936a2b67",
+  "active": "b06ed69835363258",
   "lastOpenFiles": [
-    "prop-acc/scenarios/meter/exception-readings-locked-after-bill.md",
+    "prop-acc/index.md",
-    "prop-acc/scenarios/meter/exception-high-consumption.md",
+    "prop-acc/scenarios/prepaid/deposit-first-time.md",
-    "prop-acc/scenarios/meter/generate-bill-min-max-cap.md",
+    "prop-acc/scenarios/billing/audit-activitylog-trace.md",
-    "prop-acc/scenarios/meter/generate-bill-with-multiplier.md",
+    "prop-acc/scenarios/billing/audit-monthly-billing-vs-collection.md",
-    "prop-acc/scenarios/meter/generate-bill-tiered-pricing.md",
+    "prop-acc/scenarios/billing/exception-overdue-bills.md",
-    "prop-acc/scenarios/meter/read-with-photo-proof.md",
+    "prop-acc/scenarios/billing/exception-partial-payment.md",
-    "prop-acc/scenarios/meter/read-via-iot-remote-source.md",
+    "prop-acc/scenarios/billing/bulk-delete-batch-mistake.md",
-    "prop-acc/scenarios/meter/read-batch-via-excel-import.md",
+    "prop-acc/scenarios/billing/void-paid-bill.md",
-    "prop-acc/scenarios/meter/read-single-meter-manual.md",
+    "prop-acc/scenarios/billing/delete-bill-unpaid.md",
-    "prop-acc/scenarios/meter/decommission-without-replacement.md",
+    "prop-acc/scenarios/billing/resume-bill.md",
-    "prop-acc/scenarios/meter/replace-broken-meter.md",
+    "prop-acc/scenarios/billing/suspend-bill.md",
-    "prop-acc/scenarios/meter/register-single-meter.md",
+    "prop-acc/scenarios/billing/split-bill.md",
-    "prop-acc/scenarios/meter/init-new-community-batch.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",
+    "prop-acc/concepts/billing/periodic-bill-generation.md",
+    "prop-acc/concepts/billing/bill-vs-collection-order.md",
+    "prop-acc/concepts/billing/bill-types-and-sources.md",
+    "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",
-    "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/replacement-chain.md",
-    "prop-acc/concepts/meter/meter-vs-meter-reading.md",
     "prop-acc/concepts/meter",
-    "prop-acc/scenarios/prepaid/audit-low-balance-and-overdue.md",
-    "prop-acc/scenarios/prepaid/exception-refund-on-frozen.md",
-    "prop-acc/scenarios/prepaid/exception-cross-community-consume.md",
-    "prop-acc/scenarios/prepaid/close-with-zero-balance-decision.md",
-    "prop-acc/scenarios/prepaid/close-resident-moveout.md",
-    "prop-acc/scenarios/prepaid/unfreeze-after-verification.md",
     "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",
-    "resident-portal/reference"
   ]
 }

prop-acc/concepts/billing/bill-six-state-machine.md

@@ -0,0 +1,222 @@
+---
+title: prop-acc · billing · 账单六状态机
+aliases:
+  - 账单六状态机
+  - Bill 状态机
+  - BillStatus
+  - 6 个账单状态
+tags:
+  - 概念
+  - prop-acc
+  - 账单
+  - 状态机
+  - 核心概念
+audience:
+  - 业务人员
+  - 财务
+  - 架构师
+status: 已发布
+sub_feature: billing
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 账单六状态机
+
+`Bill` 是 prop-acc 状态机**最复杂**的子模块,有 **6 个状态**:**Unpaid / Partial / Paid / Suspended / Processing / Void**。比 deposit / prepaid / meter 的 3-4 态都细,反映账单从生成到关闭的全生命周期 + 异常处置路径。
+
+## 6 状态速查
+
+| 状态 | 中文 | 何时进入 | 能做什么 |
+|---|---|---|---|
+| `Unpaid` | 未付 | 账单刚创建 | 收款 / 拆单 / 挂起 / 删 / 作废 |
+| `Partial` | 部分付 | 收到一部分钱(小于账单金额) | 继续收款 / 作废(已收的需退) |
+| `Paid` | 已付 | 收齐全部金额 | 作废(走退款) |
+| `Suspended` | 挂起 | 业务人员主动暂停(纠纷 / 失联) | 恢复 / 作废 |
+| `Processing` | 处理中 | 收款流程中(罕见,如银行扣款排队)| 等回调 |
+| `Void` | 作废 | 主动 void | 只读,审计可查 |
+
+## 状态机图
+
+```mermaid
+stateDiagram-v2
+  [*] --> Unpaid : 创建
+
+  Unpaid --> Partial : 部分收款
+  Unpaid --> Paid : 全额收款
+  Unpaid --> Suspended : suspend(纠纷)
+  Unpaid --> Void : void
+  Unpaid --> [*] : 物理删除(无付款关联)
+
+  Partial --> Partial : 继续收款(仍未付清)
+  Partial --> Paid : 收齐
+  Partial --> Suspended : suspend
+  Partial --> Void : void(已收部分需退)
+
+  Paid --> Void : void(已收全额需退)
+
+  Suspended --> Unpaid : resume(纠纷解决)
+  Suspended --> Partial : resume(回到部分付状态,若之前有付款)
+  Suspended --> Void : void
+
+  Processing --> Paid : 收款回调成功
+  Processing --> Unpaid : 收款回调失败
+
+  Void --> [*]
+```
+
+## 守护方法(模型层)
+
+`Bill` 模型上的辅助方法:
+
+| 方法 | 返回 true 的状态 | 用途 |
+|---|---|---|
+| `canBePaid()` | Unpaid / Partial | CollectPaymentAction 准入 |
+| `canBeIssued()` | (用于"发出账单"流程,看实现) | — |
+| `isVoid()` | Void | UI 灰化判断 |
+| `isPaid()` | Paid | 报表 / 收款率统计 |
+| `hasAnyPayment()` | 有任何 CollectionOrderBill / prepaid_transaction 关联 | 决定能否物理删 |
+| `canBeDeleted()` | Unpaid + 无任何付款关联 | DeleteAction 守护 |
+| `canBeVoided()` | 非 Paid 非 Void | VoidBillAction 守护 |
+
+> [!warning] `canBeVoided` 的微妙之处
+> Paid 状态**也可以走 void**(已付全额作废 → 退款),但 `canBeVoided()` 返回 false。原因:
+> - 已付账单的作废需要**走退款流程**,不是单纯改状态
+> - 简单的 `VoidBillAction` 只翻状态 + 留 meta,**不处理钱**
+> - 已付的作废应该走专门的"作废 + 退款"组合流程(类似 [[../meter/exception-readings-locked-after-bill|计量账单修正]])
+>
+> 即:`canBeVoided()` 检查的是"能否走简单作废",不是"能否所有方式作废"。
+
+## 状态转换详解
+
+### Unpaid → Partial(部分收款)
+
+业户付了 ¥300 给 ¥800 的账单:
+
+```
+- Bill.status: Unpaid → Partial
+- 建 CollectionOrderBill(allocated_amount=300)
+- 关联 CollectionOrder(actual_amount=+300)
+- Bill.paid_amount(若有此字段) = 300
+- 余 500 待付
+```
+
+### Partial → Paid(收齐)
+
+业户再付 ¥500:
+
+```
+- Bill.status: Partial → Paid
+- 建第 2 条 CollectionOrderBill(allocated_amount=500)
+- Bill.paid_amount = 800(=账单金额)
+- 收齐
+```
+
+### Unpaid → Suspended(挂起)
+
+业户与物业纠纷 / 业户失联:
+
+```
+- Bill.status: Unpaid → Suspended
+- 业务人员走 SuspendBillAction
+- 记 suspend_reason + suspended_at(meta)
+- 后续 CollectPaymentAction 守护拒绝(canBePaid=false)
+```
+
+### Suspended → Unpaid(恢复)
+
+纠纷解决:
+
+```
+- Bill.status: Suspended → Unpaid(或回到 Partial,若之前有付款)
+- 业务人员走 ResumeBillAction
+- 记 resume_reason + resumed_at
+- 后续 CollectPaymentAction 重新可用
+```
+
+### Unpaid → Void(作废)
+
+误开的账单,业户没付:
+
+```
+- Bill.status: Unpaid → Void
+- VoidBillAction 守护通过(canBeVoided=true)
+- 记 voided_reason + voided_at + voided_by
+- 业户无影响(没付钱)
+```
+
+### Paid → Void(已付作废)
+
+走专门的"作废 + 退款"流程(未来扩展):
+
+```
+- 当前 VoidBillAction **不允许**(canBeVoided=false for Paid)
+- 需要走类似 meter 的修正流程
+- 后续若实施 RefundBillAction:作废 + 退款一次性
+```
+
+### Unpaid → 物理删除(误建立刻删)
+
+```
+- 状态层面消失(从数据库删除)
+- 走 DeleteAction
+- 守护:canBeDeleted = Unpaid + 无任何付款关联
+- 留 activitylog
+```
+
+详见 [[delete-vs-void-dual-track]]。
+
+## 业务人员视角
+
+后台账户列表的状态列对应这 6 个值:
+
+- 🟢 **Unpaid**:绿色,可操作(收款 / 拆 / 挂起 / 删 / 作废)
+- 🟡 **Partial**:黄色,部分付,可继续收款
+- ✅ **Paid**:绿色对号,已完成,无操作
+- 🧊 **Suspended**:灰色雪花,挂起,只能恢复 / 作废
+- ⏳ **Processing**:旋转图标,处理中(等回调)
+- ❌ **Void**:红色叉,已作废,只读
+
+## 业户视角
+
+业户感受到的:
+
+| 状态 | 业户感知 |
+|---|---|
+| Unpaid | 收到"账单 ¥800 待付"通知 |
+| Partial | 看到"已付 ¥300,还差 ¥500"|
+| Paid | 收到"已付清"通知 + 收据 |
+| Suspended | (通常通知)"账单挂起,事由 XXX,请联系物业" |
+| Processing | 几乎不感知(过渡态)|
+| Void | 收到"账单已作废,理由 XXX" |
+
+## 与其他模块状态机的对比
+
+| 模块 | 状态数 | 主要状态 |
+|---|---|---|
+| deposit | 3 | Active / Frozen / Closed |
+| prepaid | 3 | Active / Frozen / Closed |
+| meter(`is_active`)| 2 | active / inactive |
+| **bill** | **6** | **Unpaid / Partial / Paid / Suspended / Processing / Void** |
+
+bill 的复杂度反映**收款全流程**:从应收到已收,中间有挂起、部分付、回调中等多种异常路径。
+
+## 历史:Policy 修复
+
+> [!info] issue.md Q6 第一轮发现的漏洞
+> 原 `BillPolicy` 几乎是空壳(只有 `getPermissionPrefix`),所有授权全靠 `AbstractPolicy` 默认(只查权限,**不查状态**)。
+>
+> 修复后补 7 个方法:`update` / `delete` / `deleteAny` / `void` / `collect` / `suspend` / `resume`。每个方法都加了**状态守护**(canBeDeleted / canBeVoided 等)。
+>
+> 详见 [[delete-vs-void-dual-track]] 和 [[smart-bulk-delete-design]]。
+
+## 相关文档
+
+- [[bill-types-and-sources]]
+- [[bill-vs-collection-order]]
+- [[delete-vs-void-dual-track]]
+- [[smart-bulk-delete-design]]
+- [[collect-payment-single]]
+- [[suspend-bill]]
+- [[void-paid-bill]]
+- [[../meter/decommission-and-locking]](类似的"状态机+守护"对比)

prop-acc/concepts/billing/bill-types-and-sources.md

@@ -0,0 +1,220 @@
+---
+title: prop-acc · billing · 账单类型与来源
+aliases:
+  - 账单类型
+  - 账单来源
+  - BillType
+  - sourceable polymorphism
+  - 周期账单 vs 计量账单
+tags:
+  - 概念
+  - prop-acc
+  - 账单
+  - 数据模型
+audience:
+  - 业务人员
+  - 财务
+  - 架构师
+status: 已发布
+sub_feature: billing
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 账单类型与来源
+
+`Bill` 可以由**多种业务源**产生:周期任务(月度物业费)、抄表事件(水电费)、手工建单(临时收费)。系统通过 **`sourceable` 多态关联**统一存储,通过 **`BillType` 枚举**区分类型。
+
+## 三种主要账单类型
+
+### 1. 周期账单(Periodic)
+
+**业务**:按固定周期(月 / 季 / 年)自动生成的账单。最典型:物业费、停车费、有线电视费。
+
+**生成方式**:`GeneratePeriodicBillsAction`(批量,详见 [[periodic-bill-generation]])。
+
+**源**:无直接 sourceable(由周期任务批量生成,不指向具体 reading / event)。
+
+**特点**:
+- 金额固定(由 RatePlan + 房屋面积 / 停车位等参数算)
+- 期次明确(`billing_period_start / end`)
+- 批量生成(一户一张,或合并)
+
+### 2. 计量账单(Meter-based)
+
+**业务**:抄表产生的账单。最典型:水费、电费、燃气费。
+
+**生成方式**:`GenerateBillsFromMeterReadingsAction`([[../meter/bill-generation-pipeline]])。
+
+**源**:`sourceable_type = MeterReading`,`sourceable_id = reading.id`。
+
+**特点**:
+- 金额浮动(按用量算)
+- 一抄表 → 一 Bill 行
+- 由 [[../meter/multiplier-and-tiered-pricing|阶梯+倍率+min/max]] 三层算法决定金额
+
+### 3. 临时账单(Manual / Ad-hoc)
+
+**业务**:不定期的临时收费,业务人员手工建单。例如:维修费分摊、特别活动费、单次罚款。
+
+**生成方式**:`CreateBill` Filament 页面手工建。
+
+**源**:无 sourceable(或自定义 sourceable_type)。
+
+**特点**:
+- 金额手填
+- 单次建单
+- 适合"系统不知道怎么算"的特殊场景
+
+## `BillType` 枚举
+
+> [!info] 实际 BillType 枚举值看代码
+> 当前 `packages/prop-acc/src/Enums/BillType.php` 的具体枚举值需查代码。常见可能:
+>
+> - `Periodic`(周期)
+> - `Meter`(计量)
+> - `OneTime`(一次性 / 临时)
+> - `Adjustment`(调整,罕见)
+>
+> 类型字段用于:报表分类、UI 过滤、业务逻辑分支(例如周期账单的合并策略只对 Periodic 类型生效)。
+
+## Sourceable Polymorphism
+
+Bill 表用 Laravel 多态关联存"源":
+
+```
+Bill
+├── sourceable_type: enum 'App\Models\MeterReading' / 'App\Jobs\GeneratePeriodicBills' / null
+├── sourceable_id: 关联记录的 ID
+└── (other fields)
+```
+
+### 类型对照
+
+| Bill.sourceable_type | Bill.sourceable_id | 业务来源 |
+|---|---|---|
+| `MeterReading` | reading.id | 计量账单 |
+| `PeriodicBillingTask`(假设) | task.id | 周期账单(若设计为指向任务记录)|
+| `null` | null | 手工建单 / 周期任务但不挂任务表 |
+| (其他业务可扩展) | (其他)| 未来新业务可加 |
+
+### 多态的好处
+
+| 好处 | 说明 |
+|---|---|
+| **可追溯** | Bill 上可以查到"这条 Bill 是哪条 reading 生成的" |
+| **可反查** | reading 上有 `bill_id`,Bill 上有 `sourceable_*`,双向 |
+| **统一接口** | 各业务源都用同样的 Bill 表,不用为每种源单独建表 |
+| **扩展友好** | 未来新业务(如"维修工单产生账单")只需:写新 Action + 设 `sourceable_type='WorkOrder'`,不改 Bill 表结构 |
+
+### 多态的代价
+
+- ORM 查询稍复杂(需 morphTo 关系)
+- 关联完整性靠应用层(数据库无强制外键到具体表)
+- 调试时要看 sourceable_type 才知道是哪种业务
+
+## 账单核心字段(简表)
+
+| 字段 | 含义 |
+|---|---|
+| `id` | 账单 ID |
+| `bill_no` | 账单编号(对外显示,如 `B-202605-501-001`)|
+| `community_id` | 所属物业项目 |
+| `asset_id` | 关联房屋 |
+| `resident_id` | 账单收方业户 |
+| `fee_type_id` | 费用类型(物业费 / 水费 / 电费 / ...)|
+| **`bill_type`** | **BillType 枚举(Periodic / Meter / ...)** |
+| `amount` | 账单金额 |
+| `paid_amount` | 已付金额(可能字段名不同)|
+| **`status`** | **BillStatus(6 种,见 [[bill-six-state-machine]])** |
+| `billing_period_start` / `billing_period_end` | 期次(周期账单用)|
+| `due_at` | 到期日 |
+| **`sourceable_type`** / **`sourceable_id`** | **多态源关联** |
+| `meta` | JSON 扩展(suspend_reason / voided_reason 等审计字段)|
+
+## 业务人员视角
+
+后台账单列表(`BillsTable`)列:
+
+| 列 | 内容 |
+|---|---|
+| 账单号 | bill_no |
+| 业户 | resident.name |
+| 房号 | asset.code |
+| 费用类型 | fee_type.name(物业费 / 水费 / ...)|
+| **类型(BillType)** | 周期 / 计量 / 临时 |
+| 期次 | period_start ~ period_end |
+| 金额 | amount |
+| 状态 | status(6 状态图标)|
+| 操作 | 收款 / 拆 / 挂起 / 作废 / 删 |
+
+可按 BillType 过滤:看本月所有"周期账单"或所有"计量账单"。
+
+## 业户视角
+
+业户**通常不关心账单类型**,只看到:
+
+```
+我的账单
+
+5月 物业费 ¥800 ✅ 已付
+5月 水费   ¥54  待付
+5月 电费   ¥168 待付
+5月 燃气   ¥30  待付
+```
+
+每条对应一个 Bill,业户不关心是周期还是计量,只关心"该付多少 / 付了没"。
+
+## 与 CollectionOrder 的关系
+
+Bill 是**应收应付**(应该收的钱),CollectionOrder 是**已收**(实际收到的钱)。两者多对多关联(CollectionOrderBill 中间表)。
+
+详见 [[bill-vs-collection-order]]。
+
+## 与其他子模块的协作
+
+| 业务模块 | 与 billing 的关系 |
+|---|---|
+| **meter** | 抄表 → 生成计量 Bill(sourceable=MeterReading)|
+| **prepaid** | 业户预存款抵 Bill(consume,Bill 状态 Unpaid → Paid)|
+| **deposit** | 通常不抵 Bill(押金是代管资金,不主动抵)|
+| **adhoc** | AdHocEvent 与 Bill 是兄弟概念(都产 CollectionOrder),但不互相关联 |
+
+billing 是 prop-acc 的**收款中枢** —— 各种"该收的钱"都先变成 Bill,然后通过 CollectionOrder 完成收款。
+
+## 常见问题
+
+> [!question] 周期账单和计量账单的 BillType 一定区分吗?
+> 业务上**应该区分**。理由:
+>
+> - 报表分类(物业费收入 vs 水电费收入)
+> - 业务逻辑(周期账单可合并,计量账单不合并)
+> - 业户感知(账单上区分类型,业户更明白)
+
+> [!question] sourceable 为 null 的 Bill 怎么追溯来源?
+> 看 `created_by`(操作员)+ `created_at`(时间)+ `meta`(备注)。手工建单可在 memo 写清缘由。
+
+> [!question] 同一抄表 reading 多次生成 Bill 会怎样?
+> 不会发生(理论上):
+> - Reading 上有 `bill_id` 字段,有值表示已关联 Bill
+> - `GenerateBillsFromMeterReadingsAction` 校验 `bill_id === null`(已有 Bill 跳过)
+>
+> 但若数据手工乱改 → 可能 Bill 重复 → reading 的 bill_id 会被新建的覆盖,留下"孤儿 Bill"。需运维清理。
+
+> [!question] 一个 Bill 关联多个 reading 可以吗?
+> 当前 `sourceable_*` 是 1:1(一个 Bill 对应一个 source)。如果业务上一户家有 2 张水表合并出账(罕见):需要扩展(新建中间表 BillReading,或者改 Bill schema 加 child reading 字段)。issue.md 未明确,可作为未来扩展点。
+
+> [!question] 临时账单的 sourceable_type 应该是什么?
+> `null` 或自定义类型。当前实现倾向 `null`(简单)。如果未来要"临时账单"也有追溯链(例如关联到具体维修工单),可以扩展为 `sourceable_type='WorkOrder'`。
+
+## 相关文档
+
+- [[bill-six-state-machine]]
+- [[bill-vs-collection-order]]
+- [[periodic-bill-generation]]
+- [[delete-vs-void-dual-track]]
+- [[create-periodic-property-fee]]
+- [[create-meter-bill-auto]]
+- [[create-single-bill-manual]]
+- [[../meter/bill-generation-pipeline]]
+- [[../prepaid/consume-via-bill-collection-type]]

prop-acc/concepts/billing/bill-vs-collection-order.md

@@ -0,0 +1,265 @@
+---
+title: prop-acc · billing · Bill 与 CollectionOrder 的关系
+aliases:
+  - Bill vs CollectionOrder
+  - CollectionOrderBill
+  - 应收 vs 已收
+  - 账单与收款单
+tags:
+  - 概念
+  - prop-acc
+  - 账单
+  - 核心概念
+audience:
+  - 业务人员
+  - 财务
+  - 架构师
+status: 已发布
+sub_feature: billing
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# Bill 与 CollectionOrder 的关系
+
+`Bill`(应收 / 应付)和 `CollectionOrder`(已收)是 prop-acc 的**两个核心对象**:
+
+- **Bill** = "这是业户该付的钱"(应收账款)
+- **CollectionOrder** = "业户实际付了多少 / 怎么付的"(已收记录)
+
+两者通过 **`CollectionOrderBill` 中间表多对多关联** —— 一张 Bill 可能由多笔 CollectionOrder 凑齐(部分付);一笔 CollectionOrder 可能付多张 Bill(批量收款)。
+
+## 一对多 vs 多对多
+
+### 错例:一对一
+
+```
+Bill ─── CollectionOrder
+```
+
+业务上**不够用**:
+- 业户付一半 → 怎么记?
+- 业户一次付 3 张账单 → 怎么记?
+- 一张大账单分两次付 → 怎么记?
+
+### 正例:多对多(本设计)
+
+```
+Bill ─── CollectionOrderBill ─── CollectionOrder
+   M  ─────────  N           ─────────  M  ─────────  N
+```
+
+- 1 个 Bill 可对应多个 CollectionOrderBill(一张账单分两次付)
+- 1 个 CollectionOrder 可对应多个 CollectionOrderBill(一次收款付多张账单)
+- `CollectionOrderBill` 中间表存**分配金额**(`allocated_amount`)
+
+## `CollectionOrderBill` 中间表
+
+| 字段 | 含义 |
+|---|---|
+| `id` | 主键 |
+| `collection_order_id` | 关联收款单 |
+| `bill_id` | 关联账单 |
+| **`allocated_amount`** | **本次分配给该账单的金额**(可以小于账单金额 = 部分付)|
+| `created_at` | 关联时间 |
+
+> [!info] allocated_amount 是关键
+> 这个字段决定"这笔收款付了这张账单多少",而不是"账单全付了"。例如:
+>
+> - 业户付 ¥1,000 想分摊到 3 张账单(¥300 + ¥400 + ¥300)
+> - 建 1 个 CollectionOrder(¥1,000)
+> - 建 3 个 CollectionOrderBill(分别 allocated_amount 300/400/300,关联各自的 Bill)
+> - 3 张 Bill 的 paid_amount 累加各自的 allocated_amount
+
+## 完整模型关系图
+
+```mermaid
+erDiagram
+  Bill ||--o{ CollectionOrderBill : "1:N"
+  CollectionOrderBill }o--|| CollectionOrder : "N:1"
+
+  Bill {
+    id PK
+    bill_no
+    amount
+    paid_amount
+    status
+  }
+
+  CollectionOrderBill {
+    id PK
+    bill_id FK
+    collection_order_id FK
+    allocated_amount
+  }
+
+  CollectionOrder {
+    id PK
+    collection_type
+    actual_amount
+    payment_channel_id
+    status
+  }
+```
+
+## 业务场景对照
+
+### 场景 1:简单单笔收款
+
+业户付 ¥800 物业费,一笔现金:
+
+```
+Bill #B-001 (amount=800, status=Unpaid)
+    │
+    └── CollectionOrderBill #1 (allocated_amount=800)
+            │
+            └── CollectionOrder #CO-001 (type=Bill, actual_amount=+800, payment=现金)
+                    │
+                    └── Receipt #R-001 ("物业费 ¥800")
+```
+
+Bill 状态翻 Paid,完成。
+
+### 场景 2:同业户批量收款(本月所有账单一起付)
+
+业户付 ¥1,082 = 物业费 800 + 水费 54 + 电费 168 + 燃气 60:
+
+```
+Bill #B-001 物业费 (amount=800)  ──┐
+Bill #B-002 水费   (amount=54)   ──┤
+Bill #B-003 电费   (amount=168)  ──┤
+Bill #B-004 燃气   (amount=60)   ──┤
+                                    │
+        4 个 CollectionOrderBill ──┘
+                    │
+                    └── 1 个 CollectionOrder (actual_amount=+1082, payment=微信)
+                            │
+                            └── 1 个 Receipt(可能列出 4 个明细)
+```
+
+走 `BatchCollectPaymentAction`,详见 [[collect-payment-batch]]。
+
+### 场景 3:部分付(Partial)
+
+业户付 ¥300 给 ¥800 物业费(欠 ¥500):
+
+```
+Bill #B-001 物业费 (amount=800, status=Partial)
+    │
+    └── CollectionOrderBill #1 (allocated_amount=300)
+            │
+            └── CollectionOrder #CO-001 (actual_amount=+300, payment=现金)
+```
+
+Bill 状态:**Partial**(详见 [[bill-six-state-machine]])。后续业户补付 ¥500:
+
+```
+Bill #B-001 (amount=800, status=Paid)  ← 收齐变 Paid
+    │
+    ├── CollectionOrderBill #1 (allocated_amount=300, 关联 CO-001)
+    └── CollectionOrderBill #2 (allocated_amount=500, 关联 CO-002)
+                                                          │
+                                                          └── CollectionOrder #CO-002 (+500)
+```
+
+### 场景 4:预存款抵扣
+
+业户预存款余额 ¥5,000,自动抵 ¥800 物业费:
+
+```
+Bill #B-001 (amount=800, status=Unpaid → Paid)
+    │
+    └── CollectionOrderBill #1 (allocated_amount=800)
+            │
+            └── CollectionOrder #CO-001 (type=Bill, actual_amount=+800,
+                                          meta.fund_source=prepaid)
+                    │
+                    └── PrepaidTransaction (type=consume, amount=800)
+```
+
+详见 [[../prepaid/consume-via-bill-collection-type]]。**关键**:CollectionOrder.type 仍是 `Bill`(账单视角),fund_source 标 prepaid。
+
+## CollectionOrderBill 是只读管理
+
+`CollectionAllocationsRelationManager`(Bill 详情页的子表)**完全只读**(无任何 Action,不可改 / 不可删 / 不可加)。理由:
+
+- 分配是收款 Action 内事务一次性写入,业务上不需要"事后调整"
+- 改了会导致 Bill.paid_amount 与 allocations 累加值不一致 → 数据脱节
+- 误删等于"业户付的钱凭空消失" → 灾难
+
+issue.md Q6 明确:**"`CollectionAllocationsRelationManager` 完美保持不动:作为只读管理器的最佳示范"**。
+
+## 业务人员视角
+
+后台 Bill 详情(`ViewBill`)的子表"收款分配":
+
+| 列 | 内容 |
+|---|---|
+| 收款单号 | CO-XXX |
+| 分配金额 | allocated_amount |
+| 付款方式 | CO 的 payment_channel |
+| 付款时间 | CO 的 created_at |
+
+业务人员看明白:"这张账单的 ¥800 是 5/15 微信付的"。
+
+## 业户视角
+
+业户**通常感受不到**这两个对象的复杂关系。看到的是:
+
+- 账单状态(Unpaid / Partial / Paid / ...)
+- 已付金额 / 未付金额
+- 收款明细(几次付、什么时候付、用什么方式付)
+
+整体感知:**"我付了 ¥800 物业费"**,而不是"我建了一个 CollectionOrder 关联到 Bill 通过 CollectionOrderBill"。
+
+## 与 adhoc 模块的对比
+
+[[../adhoc/collection-order-and-receipt|adhoc 的 CollectionOrder 与 Receipt]] 概念:
+
+| 维度 | adhoc(一次性收费)| **billing(账单)** |
+|---|---|---|
+| 主对象 | `AdHocEvent` | `Bill` |
+| 与 CollectionOrder 关系 | 1:1(一次买卖一个 CO)| **多对多(中间表)** |
+| 是否支持部分付 | ❌(一次性付清)| **✅ Partial 状态** |
+| 是否支持批量付 | ❌(每单独立)| **✅ BatchCollectPayment** |
+| 收款类型 | `CollectionType=AdHoc` | `CollectionType=Bill` |
+
+bill 的多对多设计让**批量收款 + 部分付**成为可能,这是周期账单业务的核心需求。
+
+## 常见问题
+
+> [!question] 为什么不直接在 Bill 上记 paid_amount,不要中间表?
+> 因为要记**每笔付款的细节**(什么时候付、什么方式、多少金额)。中间表才能存这些。
+>
+> 单纯 `paid_amount` 字段只能表达"总付了多少",无法回答"业户上次付的时候用的什么方式"。
+
+> [!question] 一个 CollectionOrder 关联到一个 Bill 但 allocated_amount < CO.actual_amount 怎么办?
+> 业务上不应该发生(每笔 CO 应该被完全分配)。如果发生,差额部分是"未分配收款" → 需要后续补建 CollectionOrderBill 关联其他 Bill(或留作业户预付,看业务设计)。
+
+> [!question] Bill.paid_amount 字段从哪算?
+> 系统应自动维护:`paid_amount = SUM(collectionOrderBills.allocated_amount)`。每次新建 CollectionOrderBill 时回填 Bill.paid_amount。
+>
+> 若数据库直接改 collectionOrderBills 没回填(理论上不应该,但若有 bug)→ Bill.paid_amount 与实际不符 → 需修复 + 审计。
+
+> [!question] 已付账单作废后,关联的 CollectionOrderBill 怎么办?
+> 看实现:
+> - **不动**(保留历史关联)+ 走"作废 + 退款"组合(建红字 CO 退给业户)
+> - **解除关联**(allocated_amount 退还,但这种做法破坏审计)
+>
+> 推荐**前者**(保留历史 + 走退款)。详见 [[void-paid-bill]]。
+
+> [!question] CollectionOrderBill 的允许的 allocated_amount 大于 Bill.amount 吗?
+> 业务上不应该(超额付了无意义)。如果业户付多了:
+> - 多余部分**应该退**(或转入预存款)
+> - 不应该让 CollectionOrderBill.allocated_amount > Bill.amount(等于"账单凭空多了钱")
+
+## 相关文档
+
+- [[bill-six-state-machine]]
+- [[bill-types-and-sources]]
+- [[collect-payment-single]]
+- [[collect-payment-batch]]
+- [[collect-via-prepaid-auto]]
+- [[exception-partial-payment]]
+- [[../adhoc/collection-order-and-receipt]]
+- [[../prepaid/consume-via-bill-collection-type]]

prop-acc/concepts/billing/delete-vs-void-dual-track.md

@@ -0,0 +1,320 @@
+---
+title: prop-acc · billing · 删除 vs 作废双轨制
+aliases:
+  - 删除 vs 作废
+  - 双轨制
+  - delete-vs-void-dual-track
+  - VoidBillAction
+  - canBeDeleted
+  - canBeVoided
+tags:
+  - 概念
+  - prop-acc
+  - 账单
+  - 数据治理
+audience:
+  - 业务人员
+  - 财务
+  - 架构师
+status: 已发布
+sub_feature: billing
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 删除 vs 作废双轨制
+
+billing 模块对"账单消失"提供**两条路径**:**物理删除**(Delete,Unpaid + 无付款关联)和 **作废**(Void,留状态 + 留审计)。这是 prop-acc 其他子模块**都没有**的设计:deposit/prepaid/meter 都只支持 Close / Decommission 类的"终态保留"。
+
+## 为什么要双轨制
+
+业务方提了"想要批量删除功能 + 单张删除功能"。深入讨论后形成双轨:
+
+| 场景 | 推荐路径 | 理由 |
+|---|---|---|
+| **误开账单立刻发现**(还没付款)| **物理删除** | 干净,没钱被卷入,删了不留痕(activitylog 仍有) |
+| **已生成 + 已收一部分钱**(Partial) | **作废** | 钱已经卷入,删了等于消灭凭证;作废留状态 + 退款 |
+| **已生成 + 已付清**(Paid)| **作废(需走退款)** | 同上 |
+| **业户失联 / 长期不付** | **挂起(Suspend)** | 暂停状态,不是终态;后续可恢复或作废 |
+
+## 删除路径
+
+### 守护
+
+`Bill::canBeDeleted()`:
+
+```php
+public function canBeDeleted(): bool
+{
+    return $this->status === BillStatus::Unpaid
+        && ! $this->hasAnyPayment();
+}
+```
+
+`Bill::hasAnyPayment()` 检查:
+
+- `CollectionOrderBill`(走收款的关联)
+- `PrepaidTransaction`(走预存款抵的关联)
+
+**Unpaid + 无任何付款关联** = 业户没付过任何钱 + 账单状态干净 → 安全删。
+
+### 触发入口
+
+| 入口 | UI |
+|---|---|
+| 单删 | `EditBill` 页面的 `DeleteAction`(`->visible(canBeDeleted)` + `->authorize('delete')`)|
+| 批删 | `BulkDeleteBillsAction`(智能 Modal,详见 [[smart-bulk-delete-design]])|
+
+### Policy 守护
+
+```php
+// BillPolicy
+public function delete(AuthUser $user, Model $record): bool
+{
+    return $user->can('delete bills') && $record->canBeDeleted();
+}
+
+public function deleteAny(AuthUser $user): bool
+{
+    return $user->can('bulkDelete bills');  // 独立高敏权限
+}
+```
+
+`deleteAny` 是**独立权限**(`bill.bulkDelete`),比单删更敏感(批删一次可能 100+ 张),需单独授权。
+
+### 删除后留什么
+
+| 留下 | 不留 |
+|---|---|
+| **activitylog** 记录(谁删了 / 什么时候 / 哪些 bill_no)| **Bill 数据库记录** |
+| 业户 / asset 等关联实体不动 | **关联的 CollectionOrderBill**(应该 0 个,因守护保证)|
+
+activitylog 详见 [[smart-bulk-delete-design]]"activitylog 审计"段。
+
+## 作废路径
+
+### 守护
+
+`Bill::canBeVoided()`:
+
+```php
+public function canBeVoided(): bool
+{
+    return $this->status !== BillStatus::Paid
+        && $this->status !== BillStatus::Void;
+}
+```
+
+**非 Paid 非 Void** = 可作废。包括 Unpaid / Partial / Suspended / Processing。
+
+> [!warning] Paid 的作废需走专门流程
+> `canBeVoided()` 对 Paid 返 false,因为单纯翻状态会让业户已付的钱"凭空消失"。Paid 账单作废需要**配套退款流程**(未来扩展,目前手工 / tinker 操作)。
+>
+> issue.md Q6 未具体规划"Paid 作废"业务流程,留作未来扩展。
+
+### 触发入口
+
+`VoidBillAction`(Filament UI)挂在 `EditBill` / `ViewBill` / Table 行。Modal 必填**作废原因**(`reason`):
+
+```
+请填写作废原因(必填,审计留痕):
+[多行输入框]
+
+[取消]  [确认作废]
+```
+
+### 业务 Action 实现
+
+`src/Actions/Bills/VoidBillAction.php`(业务层,与 Filament UI 分离):
+
+```php
+class VoidBillAction
+{
+    public function handle(Bill $bill, string $reason, User $user): void
+    {
+        if (! $bill->canBeVoided()) {
+            throw new RuntimeException("账单状态 {$bill->status->value} 不可作废");
+        }
+
+        $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' => BillStatus::Void->value,
+                'bill_no' => $bill->bill_no,
+                'amount' => $bill->amount,
+            ])
+            ->event('voided')
+            ->log('账单已作废');
+    }
+}
+```
+
+### Policy 守护
+
+```php
+public function void(AuthUser $user, Bill $bill): bool
+{
+    return $user->can('void bills') && $bill->canBeVoided();
+}
+```
+
+### 作废后留什么
+
+| 留下 | 改变 |
+|---|---|
+| **Bill 数据库记录**(只读)| `status = Void` |
+| **关联的 CollectionOrderBill**(若有)| 不动 |
+| **meta**:voided_reason / voided_at / voided_by | 新增 |
+| **activitylog**:event=voided | 新增 |
+| **Receipt 等下游凭证** | 不动(已经发出去的不撤销)|
+
+业户可以看到账单"已作废",物业有完整审计链。
+
+## 双轨决策树
+
+```mermaid
+flowchart TD
+  A[要让账单"消失"] --> B{账单状态?}
+
+  B -->|Unpaid| C{有付款关联吗?}
+  B -->|Partial / Suspended / Processing| D[走作废 Void]
+  B -->|Paid| E[当前 canBeVoided=false<br/>需走专门退款流程<br/>未来扩展]
+  B -->|Void| F[已经是 Void,无需重复]
+
+  C -->|无| G[物理删除 Delete]
+  C -->|有| D
+```
+
+## 业务人员视角
+
+### 决策时
+
+| 误开发现时间 | 推荐 |
+|---|---|
+| 几秒内(业户还在面前)| 物理删除(干净)|
+| 几小时(可能业户已付)| 先查是否已付:已付 → 作废 + 退;未付 → 删 |
+| 几天(已发账单)| 通常作废(留状态让业户知道) |
+| 几月(已查到)| 作废 + 走退款流程(若已付) |
+
+### Modal 操作
+
+**单删 Modal**(`EditBill` → DeleteAction):
+
+```
+确认删除账单 #B-202605-501-001?
+
+⚠️ 此账单状态为 Unpaid 且无付款关联,可物理删除。
+   删除后无法恢复(但 activitylog 会保留记录)。
+
+[取消]  [确认删除]
+```
+
+**作废 Modal**(`VoidBillAction`):
+
+```
+作废账单 #B-202605-501-001
+
+账单状态:Unpaid
+账单金额:¥800
+
+请填写作废原因(必填):
+[多行输入]
+
+[取消]  [确认作废]
+```
+
+## 业户视角
+
+| 操作 | 业户感知 |
+|---|---|
+| 物理删除 | **无感**(账单从未真正"存在过",未通知业户) |
+| 作废 | 收到通知"您的账单 #XXX 已作废,理由 YYY" + 账单状态显示 Void |
+| Paid 作废(未来) | 收到通知 + 退款到账 + 红字凭证 |
+
+## 与 prop-acc 其他模块的对比
+
+| 模块 | 删 / 作废 / 退役 / 关账 |
+|---|---|
+| **deposit** | 无 delete UI(Policy 严格)+ ForceClose(终态)|
+| **prepaid** | 无 delete UI + CloseAction(终态)|
+| **meter** | 无 delete UI(仅退役 + 严格条件下删空表)+ Decommission |
+| **bill(本模块)** | **delete + void 双轨** + Suspend / Resume |
+
+bill 的双轨是 prop-acc **最完整的"账单消失"设计**。其他模块"没有删,只有 终态"是因为它们的对象天然不该消失(账户、押金、表都是长期实体)。bill 的"账单"本质上是**可消失的事务记录**,所以双轨合理。
+
+## 历史:issue.md Q6 的修复
+
+> [!info] 修复前
+> `BillPolicy` 几乎是空壳(只有 `getPermissionPrefix`),`DeleteAction` 暴露在 EditBill 页 + `DeleteBulkAction` 暴露在 Table toolbar(`visible(false)` 假关闭),Unpaid + Paid + Void 全状态都能删 → 删 Paid Bill = 业户付的钱凭空消失 + 完全无审计痕迹。
+>
+> **风险等级**:严重(类似 deposit / prepaid 第二轮修复的"消灭法律证据"级别)。
+
+> [!info] 修复后(issue.md Q6 第一轮)
+>
+> 1. Bill 模型加 3 辅助方法(`hasAnyPayment` / `canBeDeleted` / `canBeVoided`)
+> 2. BillPolicy 补 7 方法(`update / delete / deleteAny / void / collect / suspend / resume`)
+> 3. 新增 `VoidBillAction` 业务 Action + Filament UI
+> 4. 新增 `BulkDeleteBillsAction` 智能批删(详见 [[smart-bulk-delete-design]])
+> 5. 删除 `DeleteBulkAction` 的 `visible(false)` 反模式 → 替换为真正的智能批删
+> 6. EditAction / DeleteAction 三处加 visible 守护
+> 7. CollectPaymentAction authorize 改为 `->authorize('collect')`(取代跨模型 authorize)
+> 8. Plugin.php 扩权限位:`bill.bulkDelete` 独立高敏权限
+>
+> 全栈守护(UI / Policy / Action / Model)+ activitylog 审计。
+
+## 常见问题
+
+> [!question] 为什么不全部走作废,简化设计?
+> **物理删的"干净"是有价值的**:
+>
+> - 误开的账单不留痕,业务人员不慌
+> - 业户看不到"已作废"的诡异状态(从未存在过最自然)
+> - 数据库无 Void 状态垃圾堆积
+>
+> 但**只对没动钱的账单适用**。一旦动了钱,必须作废留痕,不能"假装从未发生"。
+
+> [!question] 作废后能撤销吗?
+> 不能(Void 是终态,无 reactivate 路径)。如需"恢复":新建一张同信息的 Bill。
+
+> [!question] hasAnyPayment 检查的"付款关联"具体是?
+> 看 `Bill::hasAnyPayment()` 实现。通常:
+>
+> - `collectionOrderBills()->exists()`(有任何分配记录)
+> - `prepaidTransactions()->where('related_bill_id', this->id)->exists()`(被 prepaid consume 过)
+>
+> 任意一个为真 → 有付款关联 → 不可物理删。
+
+> [!question] 批量删的智能 Modal 怎么工作?
+> 详见专门概念 [[smart-bulk-delete-design]]。
+
+> [!question] activitylog 怎么查?
+>
+> ```sql
+> -- 某员工某月的全部批量删除
+> SELECT * FROM activity_log
+> WHERE causer_id = ?
+>   AND event IN ('voided', 'bulk_deleted')
+>   AND created_at BETWEEN '2026-05-01' AND '2026-05-31';
+> ```
+
+## 相关文档
+
+- [[bill-six-state-machine]]
+- [[smart-bulk-delete-design]]
+- [[delete-bill-unpaid]]
+- [[void-paid-bill]]
+- [[bulk-delete-batch-mistake]]
+- [[suspend-bill]]
+- [[../meter/decommission-and-locking]](类似"保留 vs 删除"对比)

prop-acc/concepts/billing/periodic-bill-generation.md

@@ -0,0 +1,254 @@
+---
+title: prop-acc · billing · 周期账单生成机制
+aliases:
+  - 周期账单生成
+  - 月度物业费生成
+  - GeneratePeriodicBillsAction
+  - BillingMergeStrategy
+  - 合单策略
+tags:
+  - 概念
+  - prop-acc
+  - 账单
+  - 业务流程
+audience:
+  - 业务人员
+  - 财务
+  - 架构师
+status: 已发布
+sub_feature: billing
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 周期账单生成机制
+
+物业费、停车费、电视费等**按周期(月 / 季 / 年)固定收**的账单,通过 **`GeneratePeriodicBillsAction`** 批量生成。配合 **`BillingMergeStrategy` 枚举**决定"同业户多个费用类型是否合并到一张账单"。
+
+## 业务场景
+
+每月 1 日,物业为本社区 **300 户业主**生成本月物业费账单(每户 ¥800 起步,按房屋面积浮动)。系统应:
+
+- 自动算每户的金额(按 RatePlan + 房屋面积)
+- 批量建 Bill(300 张)
+- 各张 Bill 期次清晰(billing_period 5/1 - 5/31)
+- 不重复生成(本月已生成的不再生成)
+- 业务人员收到结果报告
+
+## 批量生成流程
+
+```mermaid
+flowchart TD
+  A[业务人员触发 GeneratePeriodicBillsAction] --> B[Modal 输入参数]
+  B --> C[参数:期次 / 费用类型 / 社区范围 / 合并策略]
+  C --> D[扫描候选业户清单]
+
+  D --> E[每户:计算应付金额]
+  E --> F{已有本期 Bill?}
+
+  F -->|否| G[建新 Bill]
+  F -->|是,根据策略| H{合并策略}
+
+  H -->|MERGE 合单| I[追加到既有 Bill]
+  H -->|SKIP 跳过| J[不动]
+  H -->|REPLACE 替换| K[作废旧 Bill + 建新]
+
+  G --> L[报告完成]
+  I --> L
+  J --> L
+  K --> L
+```
+
+## `GeneratePeriodicBillsAction` 参数
+
+业务人员触发(`Bills` List 页 → 顶部 "批量生成周期账单" 按钮):
+
+| 参数 | 说明 |
+|---|---|
+| **期次(billing_period)** | 如 "2026 年 5 月",决定 start / end |
+| **费用类型(fee_type_id)** | 物业费 / 停车费 / 有线电视费 / ... |
+| **社区范围(community_id)** | 单社区 / 全平台 |
+| **业户范围** | 单个业户 / 全社区业户 / 自定义清单 |
+| **合并策略(merge_strategy)** | MERGE / SKIP / REPLACE |
+| 备注 | 选填 |
+
+提交后系统扫描候选业户清单,逐户计算 + 建账。
+
+## `BillingMergeStrategy` 枚举
+
+> [!info] 实际枚举值看 `packages/prop-acc/src/Enums/BillingMergeStrategy.php`
+> 可能值(推测):
+>
+> | 值 | 含义 |
+> |---|---|
+> | `SkipExisting` | 同业户同期次已有 Bill → 跳过(不重复生成)|
+> | `Merge` | 追加到既有 Bill(同业户同期次的不同费用类型合一张)|
+> | `Replace` | 作废旧 Bill + 建新(罕见,数据修复用)|
+>
+> 默认策略通常是 **`SkipExisting`**(最安全)。
+
+## 三种策略对照
+
+### 策略 1:SkipExisting(默认,推荐)
+
+业务人员 5 月 1 日点击"生成 5 月物业费"。系统:
+
+- 张阿姨已经有 5 月物业费 Bill → **跳过**(避免重复)
+- 陈先生没有 5 月物业费 Bill → 新建
+
+**适用**:正常月度操作,业务人员不确定是否之前已经生成过,跳过最安全。
+
+### 策略 2:Merge(合单)
+
+业务人员同时为业户生成"5 月物业费 + 5 月电视费"。系统:
+
+- 找到张阿姨已有 5 月物业费 Bill(¥800)
+- **追加电视费 ¥40 到同一张 Bill**(amount: 800 + 40 = 840)
+- 业户收到**一张账单 ¥840**(明细两项)
+
+**适用**:多种费用类型一起发(减少业户收到的账单数,体验好)。
+
+> [!warning] Merge 的局限
+> 合并后**单一 Bill 的金额 = 各费用类型总和**,但**关联的 sourceable** 怎么处理?Bill 表 sourceable 字段是 1:1。**当前实现可能**:
+> - 不挂 sourceable(`sourceable_type=null`)
+> - 或挂主费用类型的 source
+>
+> 具体看代码。Merge 策略实施细节复杂,生产环境**谨慎用**。
+
+### 策略 3:Replace(替换)
+
+业务人员发现 5 月物业费金额算错了(RatePlan 改过),要全部重算:
+
+- 找到张阿姨已有的 5 月物业费 Bill
+- **作废**(VoidBillAction,状态翻 Void)
+- **重新生成**新 Bill(按新 RatePlan)
+
+**适用**:数据修复场景(罕见,需高权限 + 必填原因)。
+
+> [!warning] Replace 的风险
+> 已付的 Bill 作废后,业户已经付的钱**怎么办**?
+>
+> - Bill 状态翻 Void
+> - 已付的 CollectionOrderBill 关联保留(审计需要)
+> - 但业户的钱 = 物业账面多收了
+> - **必须走退款**(建红字 CollectionOrder)
+>
+> Replace 策略**只对 Unpaid Bill 使用相对安全**;Paid Bill 慎用,需配套退款流程。
+
+## 金额计算
+
+周期账单金额怎么算?取决于 RatePlan 配置:
+
+| 算法 | 说明 |
+|---|---|
+| **固定金额** | 每户每月固定 ¥800(简单)|
+| **按面积** | 房屋面积 × 单价(例如物业费 ¥3 / m² / 月)|
+| **按车位** | 每个停车位固定金额(停车费)|
+| **按设备** | 每台空调 ¥X / 月(中央空调费)|
+| **阶梯** | 类似计量账单的阶梯(罕见)|
+
+具体看 `RatePlan` 的配置 + 业务计算逻辑。可能在 `PeriodicBillGenerationService`(若有)实现,或在 Action 内联。
+
+## 生成的 Bill 字段
+
+每张生成的 Bill:
+
+| 字段 | 值 |
+|---|---|
+| `bill_no` | 自动编号(`B-202605-501-001` 或类似)|
+| `community_id` | 所属社区 |
+| `asset_id` | 业户房屋 |
+| `resident_id` | 业户 |
+| `fee_type_id` | 费用类型 |
+| `bill_type` | `Periodic`(枚举) |
+| `amount` | 算出的金额 |
+| `paid_amount` | 0(刚生成,未付)|
+| `status` | `Unpaid` |
+| `billing_period_start` | 期次开始(2026-05-01)|
+| `billing_period_end` | 期次结束(2026-05-31)|
+| `due_at` | 到期日(通常本期末 + 宽限期,如 2026-06-15)|
+| `sourceable_*` | null(周期账单通常无 source)|
+
+## 业户视角
+
+业户每月初(或月底,看物业策略)收到推送:
+
+> 张阿姨您好,您的 2026 年 5 月物业费 ¥800 已生成。请于 6 月 15 日前付清。
+
+业户可选:
+
+- 现金 / 微信付 → 走 [[collect-payment-single]]
+- 预存款抵 → 走 [[collect-via-prepaid-auto]](自动)
+- 与其他账单一起付 → 走 [[collect-payment-batch]]
+- 暂时不付 → 到期日后变逾期,走 [[exception-overdue-bills]] 催收
+
+## 业务人员视角
+
+### 月初执行
+
+每月 1-3 日,业务人员王主管:
+
+1. 打开 BillsListPage → 顶部 "生成周期账单"
+2. 选费用类型(物业费 / 停车费 / 等)+ 期次 + 策略 + 备注
+3. 提交 → 系统扫描 + 生成 → 报告"已生成 N 张账单,跳过 M 张"
+4. 抽样核对几张 Bill 的金额 + 业户
+
+### 异常处置
+
+| 异常 | 处置 |
+|---|---|
+| 某户 RatePlan 配置缺失 | 跳过该户 + 在报告里标记 → 单独建 RatePlan + 单独生成 |
+| 某户已有同期 Bill(被跳过)| 看是否需要 Merge / Replace |
+| 全部失败(系统错)| 联系运维查日志 |
+
+## 自动化的可能
+
+issue.md Q6 未列入"待补",但业务上可能需要:
+
+- **Scheduled job 月初自动跑** — 不需要业务人员手动触发
+- **跟 prepaid 自动抵扣 job 串联** — 账单生成 → 立即触发 [[../prepaid/auto-deduction-design|预存款自动抵]] → 业户感受"无感扣账单"
+
+当前**仍是手动触发**。
+
+## 常见问题
+
+> [!question] 同业户同期次同费用类型能有两张 Bill 吗?
+> 业务上**不应该**(违反业务规则:一户一月一物业费)。系统层面看是否有 unique 约束:
+>
+> ```sql
+> UNIQUE INDEX (community_id, resident_id, fee_type_id, billing_period_start)
+> ```
+>
+> 若有 → 数据库层挡住重复;若无 → 全靠 Action 的 SkipExisting 策略判断,理论上可能因并发产生重复。
+
+> [!question] 业户搬走中途,本月物业费要不要全收?
+> 看物业策略 + 合同约定:
+>
+> - **全月收**(简单,业户合同到月底)
+> - **按天分摊**(按搬走前的天数算)
+> - **不收**(罕见)
+>
+> 系统**当前简版**通常是全月收。按天分摊需要业务层算法支持。
+
+> [!question] 周期账单生成后才发现 RatePlan 配错怎么办?
+> 走 Replace 策略**只对 Unpaid 安全**。如果已付:
+>
+> - 看错的金额方向:
+>   - 收多了 → 退差额(走 [[void-paid-bill]] 类似流程)
+>   - 收少了 → 补开账单(新建一张 ¥差额 的临时账单)
+
+> [!question] 批量生成多久?300 户 5 秒?
+> 单户 ~50-100ms(查 RatePlan + 查业户 + 建 Bill + 日志)。300 户**顺序执行** ~15-30 秒。可优化为并发(若业务量大)。
+
+> [!question] 周期账单和计量账单可以一起生成吗?
+> 不在同一个 Action(周期是 `GeneratePeriodicBillsAction`,计量是 [[../meter/bill-generation-pipeline|GenerateBillsFromMeterReadingsAction]])。**业务流程上**业务人员通常先做完抄表 + 计量账单生成 → 再触发周期账单生成。
+
+## 相关文档
+
+- [[bill-six-state-machine]]
+- [[bill-types-and-sources]]
+- [[bill-vs-collection-order]]
+- [[create-periodic-property-fee]]
+- [[create-meter-bill-auto]]
+- [[../meter/bill-generation-pipeline]](类似的 Calculator + Service + Action 模式)
+- [[../prepaid/auto-deduction-design]](账单生成后的下游消费)

prop-acc/concepts/billing/smart-bulk-delete-design.md

@@ -0,0 +1,359 @@
+---
+title: prop-acc · billing · 智能批量删除设计
+aliases:
+  - 智能批量删除
+  - BulkDeleteBillsAction
+  - 三档分类
+  - activitylog 审计
+  - smart-bulk-delete-design
+tags:
+  - 概念
+  - prop-acc
+  - 账单
+  - 数据治理
+  - 审计
+audience:
+  - 业务人员
+  - 财务
+  - 架构师
+status: 已发布
+sub_feature: billing
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 智能批量删除设计
+
+`BulkDeleteBillsAction` 是 prop-acc **最精巧的批量操作设计**:选中 N 张 Bill 后,系统**预检查 + 分类三档**(可删 / 可作废 / 跳过),Modal 显示统计 + 选模式 + 必填原因,最后**一条 activitylog** 记录全过程,`affected_ids` 串联具体哪些账单。
+
+## 为什么要"智能"
+
+业务人员选了 100 张账单点"批量删除",其中可能:
+
+- 92 张是 Unpaid + 无付款 → 可物理删
+- 5 张是 Partial / Paid → 不能删(动了钱),但可作废
+- 3 张是 Suspended / 已 Void → 跳过
+
+**简单批量删**(一刀切删全部)的灾难:
+
+- 5 张 Partial / Paid 的被删 → 业户付的钱凭空消失 + 审计断链
+- 业务人员可能根本不知道里面有 Partial / Paid(没逐张点开看)
+
+**智能批删**(本设计):
+
+1. **预检查** 每张 Bill 分类
+2. **Modal 显示**:`✅ 可删 92  ⚠️ 需作废 5  ❌ 跳过 3`
+3. **业务人员选模式**:`仅删可删的` 或 `删可删 + 作废需作废的`
+4. **必填原因**(审计要求)
+5. **执行 + 一条 activitylog**:`affected_ids` 串联每张账单的处理结果
+
+## 三档分类逻辑
+
+```php
+// 伪代码,来自 BulkDeleteBillsAction
+foreach ($selectedBills as $bill) {
+    if ($bill->canBeDeleted()) {
+        $deletable[] = $bill;
+    } elseif ($bill->canBeVoided()) {
+        $voidable[] = $bill;
+    } else {
+        $blocked[] = $bill;  // Paid / Void 已经 / 异常状态
+    }
+}
+```
+
+| 档 | 条件 | 处置 |
+|---|---|---|
+| **可删**(Deletable) | `canBeDeleted()` = Unpaid + 无付款 | 物理 delete |
+| **可作废**(Voidable) | `canBeVoided()` = 非 Paid 非 Void | 翻状态 Void + 留 meta |
+| **跳过**(Blocked) | Paid / Void / 其他异常 | 不动 |
+
+## Modal 设计
+
+业务人员在 `BillsTable` 选 N 张 → 点 "批量删除" → 弹出:
+
+```
+批量删除账单 (选中 100 张)
+
+预检查统计:
+  ✅ 可删:     92 张
+  ⚠️ 需作废:    5 张
+  ❌ 跳过:      3 张(已付清 / 已作废 / 其他)
+
+请选择处理模式:
+  ⚪ 仅删除可删的(92 张物理删,5 张需作废 / 3 张跳过)
+  ⚫ 删可删 + 作废需作废的(92 删 + 5 作废,3 跳过)
+
+批量操作原因(必填,审计留痕):
+[多行输入框]
+
+⚠️ 注意:
+  - 物理删除不可恢复(但 activitylog 保留 bill_no)
+  - 作废不可撤销
+  - 跳过的账单不动
+
+[取消]  [确认执行]
+```
+
+## 业务 Action 实现(`src/Actions/Bills/BulkDeleteBillsAction`)
+
+```php
+class BulkDeleteBillsAction
+{
+    public function handle(
+        iterable $bills,
+        BulkDeleteMode $mode,  // OnlyDeletable / DeleteAndVoid
+        string $reason,
+        User $user,
+    ): BulkDeleteResult {
+        $deletable = [];
+        $voidable = [];
+        $blocked = [];
+
+        // 第 1 步:分类
+        foreach ($bills as $bill) {
+            if ($bill->canBeDeleted()) {
+                $deletable[] = $bill;
+            } elseif ($bill->canBeVoided()) {
+                $voidable[] = $bill;
+            } else {
+                $blocked[] = $bill;
+            }
+        }
+
+        $deletedCount = 0;
+        $voidedCount = 0;
+        $affectedBillNos = [];
+
+        // 第 2 步:执行
+        DB::transaction(function () use (...) {
+            foreach ($deletable as $bill) {
+                $affectedBillNos[] = $bill->bill_no . ' [DELETED]';
+                $bill->delete();
+                $deletedCount++;
+            }
+
+            if ($mode === BulkDeleteMode::DeleteAndVoid) {
+                foreach ($voidable as $bill) {
+                    $affectedBillNos[] = $bill->bill_no . ' [VOIDED]';
+                    app(VoidBillAction::class)->handle($bill, $reason, $user);
+                    $voidedCount++;
+                }
+            }
+
+            foreach ($blocked as $bill) {
+                $affectedBillNos[] = $bill->bill_no . ' [SKIPPED]';
+            }
+
+            // 第 3 步:一条总体 activitylog
+            activity()
+                ->causedBy($user)
+                ->withProperties([
+                    'mode' => $mode->value,
+                    'reason' => $reason,
+                    'total_selected' => count($bills),
+                    'deleted_count' => $deletedCount,
+                    'voided_count' => $voidedCount,
+                    'blocked_count' => count($blocked),
+                    'affected_bill_nos' => $affectedBillNos,
+                ])
+                ->event('bulk_deleted')
+                ->log('批量删除账单');
+        });
+
+        return new BulkDeleteResult(
+            deletedCount: $deletedCount,
+            voidedCount: $voidedCount,
+            blockedCount: count($blocked),
+            affectedBillNos: $affectedBillNos,
+        );
+    }
+}
+```
+
+## activitylog 设计
+
+利用 `spatie/laravel-activitylog`(项目已装但本次首次启用)。
+
+### 单条作废日志
+
+`VoidBillAction` 触发,subject 是被作废的 Bill:
+
+| 字段 | 值 |
+|---|---|
+| `log_name` | `default` |
+| `subject_type` | `Bill` |
+| `subject_id` | 被作废 bill 的 ID |
+| `event` | `voided` |
+| `causer_id` | 操作员 ID |
+| `properties` | `{reason, from_status, to_status, bill_no, amount}` |
+
+### 批量删除日志(本场景)
+
+`BulkDeleteBillsAction` 触发,**无 subject**(批量操作不绑单个对象):
+
+| 字段 | 值 |
+|---|---|
+| `log_name` | `default` |
+| `subject_type` | null |
+| `subject_id` | null |
+| `event` | `bulk_deleted` |
+| `causer_id` | 操作员 ID |
+| `properties` | `{mode, reason, total_selected, deleted_count, voided_count, blocked_count, affected_bill_nos[]}` |
+
+`properties.affected_bill_nos` 是一个数组,每条形如 `"B-202605-501-001 [DELETED]"` / `"B-202605-502-003 [VOIDED]"`,审计可完整还原。
+
+## 审计追溯 SQL
+
+```sql
+-- 某员工某月的全部批量删除
+SELECT
+    id,
+    event,
+    causer_id,
+    properties->>'$.mode' AS mode,
+    properties->>'$.reason' AS reason,
+    properties->>'$.deleted_count' AS deleted,
+    properties->>'$.voided_count' AS voided,
+    properties->>'$.affected_bill_nos' AS affected,
+    created_at
+FROM activity_log
+WHERE causer_id = ?
+  AND event = 'bulk_deleted'
+  AND created_at BETWEEN '2026-05-01' AND '2026-05-31'
+ORDER BY created_at DESC;
+```
+
+返回示例:
+
+| created_at | mode | reason | deleted | voided | affected (部分) |
+|---|---|---|---|---|---|
+| 2026-05-15 14:32 | DeleteAndVoid | "5 月物业费 RatePlan 配错,清理重生成" | 92 | 5 | ["B-202605-501-001 [DELETED]", ...] |
+
+## 完整业务流程
+
+```mermaid
+sequenceDiagram
+    participant 业务[业务人员]
+    participant Filament
+    participant BulkDelete[BulkDeleteBillsAction Filament UI]
+    participant Action[BulkDeleteBillsAction 业务层]
+    participant Bill[Bill 模型]
+    participant Activity[activitylog]
+    participant DB
+
+    业务->>Filament: 选 100 张 → 点"批量删除"
+    Filament->>BulkDelete: 显示 Modal
+
+    BulkDelete->>BulkDelete: 预检查每张 Bill 分类
+    BulkDelete->>Filament: Modal 显示 ✅92 ⚠️5 ❌3
+
+    业务->>Filament: 选"删可删 + 作废需作废" + 填原因 + 提交
+    Filament->>Action: handle(100 bills, mode=DeleteAndVoid, reason, user)
+    Action->>Bill: 第 1 步:再次分类(防 UI 缓存过期)
+    Bill-->>Action: 92 deletable / 5 voidable / 3 blocked
+
+    Action->>DB: 开启事务
+
+    loop 92 deletable
+        Action->>Bill: delete()
+        Bill->>DB: 物理删
+    end
+
+    loop 5 voidable
+        Action->>Action: 调 VoidBillAction.handle(bill, reason, user)
+        Action->>Bill: 翻状态 Void + meta
+        Action->>Activity: log voided(单条)
+    end
+
+    Action->>Activity: log bulk_deleted(总体 + affected_bill_nos)
+    Action->>DB: 提交事务
+
+    Action-->>Filament: 结果(92 删 / 5 作废 / 3 跳过)
+    Filament-->>业务: 通知"批量操作完成"
+```
+
+## 业务人员视角
+
+完整流程:
+
+1. **筛选**:在 `BillsTable` 用过滤(按期次 / 状态 / 费用类型)选出要清理的批
+2. **选中**:Table 的勾选框
+3. **触发**:顶部 "批量删除" 按钮
+4. **看预检查**:Modal 显示 ✅ / ⚠️ / ❌ 三档统计
+5. **决策**:选"仅删可删的"或"删可删 + 作废需作废的"
+6. **填原因**(必填):"5 月物业费配错,清理重生成"
+7. **提交**:系统执行 + 通知
+8. **审计**:事后可查 activitylog 追溯
+
+## 业户视角
+
+业户感知:
+
+| 业户类型 | 感知 |
+|---|---|
+| 被物理删账单的业户(未付款)| **无感**(账单从未发出 / 未通知)|
+| 被作废账单的业户(已付款)| 收到通知 + 看到 Void 状态 + 可能涉及退款 |
+| 不在批量内的业户 | 无感 |
+
+## 权限设计
+
+| 权限 | 谁该有 |
+|---|---|
+| `bill.delete` | 普通业务人员(单删)|
+| `bill.bulkDelete` | 主管 / 财务总监(批删独立权限)|
+| `bill.void` | 普通业务人员(作废)|
+
+`bulkDelete` 是**独立高敏权限**,因为:
+
+- 一次可能影响 100+ 张账单
+- 影响面大 → 限定高权限人员
+- 责任明确 → 出问题能追溯到这个人
+
+## 常见问题
+
+> [!question] 为什么不直接走"全部作废"?
+> 物理删的"干净"价值见 [[delete-vs-void-dual-track]]。批量场景里,**绝大多数账单是 Unpaid 误建**,物理删一次清理干净;少数已动钱的走作废留痕,两全其美。
+
+> [!question] Modal 预检查后实际执行时状态变了怎么办?
+> Action **再次分类**(防 UI 缓存),实际执行用最新状态。例如:
+>
+> - Modal 显示 Bill #X 可删(Unpaid 无付款)
+> - 业务人员看 Modal 时,另一人付了款 → Bill #X 变 Partial
+> - 业务人员点提交 → Action 重新分类 → Bill #X 进 voidable 档
+> - 按当前模式处理(若选 "DeleteAndVoid",作废;若选 "OnlyDeletable",跳过)
+
+> [!question] activitylog 表会无限膨胀吗?
+> 是的(每条单作废 + 每次批量都加一条)。需要**归档策略**:
+>
+> - 超 X 年的 activitylog 归档到冷存储
+> - 或拆表(按月分区)
+>
+> 当前未配置归档,需运维介入(若数据量大)。
+
+> [!question] 业务人员误操作批删大量账单怎么办?
+> activitylog 留有 `affected_bill_nos`,可以**反向恢复**(理论上):
+>
+> - 物理删的 Bill:无法恢复(数据真的没了),只能重新生成(走 [[create-periodic-property-fee]] 或 [[create-single-bill-manual]])
+> - 作废的 Bill:状态翻回 Unpaid 是不允许的(Void 是终态)→ 重新创建一张同信息的 Bill
+>
+> **预防**:必填原因 + 高权限 + Modal 显示统计 + 强调"不可恢复"。
+
+> [!question] BulkDelete vs 直接逐条 Delete 100 次有什么区别?
+> | 维度 | BulkDelete | 逐条 100 次 |
+> |---|---|---|
+> | activitylog | 1 条(汇总)| 100 条(详细)|
+> | 业务人员效率 | 高(一次操作)| 低(100 次点击)|
+> | 模式灵活性 | 选 DeleteAndVoid 一次处理混合状态 | 逐条决策 |
+> | 审计可读性 | 中(看汇总 + affected)| 高(每条独立)|
+>
+> 当前设计**汇总一条 log + affected 数组** = 兼顾效率与可审计。
+
+## 相关文档
+
+- [[bill-six-state-machine]]
+- [[delete-vs-void-dual-track]]
+- [[delete-bill-unpaid]]
+- [[void-paid-bill]]
+- [[bulk-delete-batch-mistake]]
+- [[audit-activitylog-trace]]

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) | ✅ 23 篇 |
 | **收款订单**  | 一次收款的支付方式、银行账户记录 | _待补_                                          | 🚧     |
 | **收据**    | 成功收款后生成的凭证       | _待补_                                          | 🚧     |
 

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

@@ -0,0 +1,145 @@
+---
+title: prop-acc · billing · 知识地图
+aliases:
+  - billing 知识地图
+  - 账单知识地图
+tags:
+  - 规范
+  - prop-acc
+  - 知识地图
+  - 账单
+sub_feature: billing
+audience:
+  - 业务人员
+  - 财务
+  - 抄表员
+status: 已发布
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 账单(billing)知识地图
+
+> 本子模块 = Bill + CollectionOrderBill(中间表)。覆盖物业收款的**应收应付侧**:账单生成、状态管理、收款关联、删除 / 作废 / 挂起 / 拆单全套。
+>
+> billing 是 prop-acc **最复杂的子模块**,也是**收款流程的中枢**(各业务源 → Bill → CollectionOrder)。
+
+## 这是什么?
+
+物业管理软件最核心的对象之一 —— **应收账款的记录**。从抄表 / 周期任务 / 手工建单产生,经历状态变化(Unpaid → Partial → Paid),最终通过 [CollectionOrder](../concepts/adhoc/collection-order-and-receipt.md) 完成收款。
+
+## 与其他子模块的关系
+
+| 关系 | 说明 |
+|---|---|
+| **上游**:meter → bill | 抄表 → 生成计量账单 |
+| **上游**:周期任务 → bill | 月度物业费等批量生成 |
+| **上游**:手工 → bill | 临时收费 |
+| **下游**:bill → CollectionOrder | 收款时建 CO + Receipt |
+| **侧链**:bill ← prepaid | 业户预存款抵账单(走 Bill consume,见 [prepaid 模块](prepaid-knowledge-map.md))|
+
+## 与其他子模块的核心差异
+
+| 维度 | bill | 其他子模块 |
+|---|---|---|
+| 状态数 | **6**(最复杂)| deposit/prepaid 3,meter 2 |
+| 删 / 作废 | **双轨制** | 只有 Close / Decommission |
+| Policy 方法数 | **7** | deposit 12 / prepaid 9 / meter 5 |
+| 审计 | **activitylog + meta** | meta JSON only |
+| 批删 | **智能 Modal(3 档分类)** | 无 |
+| 与 CollectionOrder 关系 | **多对多**(中间表)| 1:1(adhoc / deposit / prepaid) |
+
+## 核心概念(6 篇)
+
+| 文档 | 一句话 |
+|---|---|
+| [账单六状态机](../concepts/billing/bill-six-state-machine.md) | 6 状态(Unpaid / Partial / Paid / Suspended / Processing / Void),prop-acc 最复杂 |
+| [账单类型与来源](../concepts/billing/bill-types-and-sources.md) | 周期 / 计量 / 临时 三类 + sourceable polymorphism |
+| [Bill 与 CollectionOrder 关系](../concepts/billing/bill-vs-collection-order.md) | 应收 vs 已收,CollectionOrderBill 多对多 |
+| [周期账单生成机制](../concepts/billing/periodic-bill-generation.md) | `GeneratePeriodicBillsAction` + `BillingMergeStrategy` 三种合并策略 |
+| [删除 vs 作废双轨制](../concepts/billing/delete-vs-void-dual-track.md) | 物理删(Unpaid 无付款)vs 作废(留状态留审计)的设计哲学 |
+| [智能批量删除设计](../concepts/billing/smart-bulk-delete-design.md) | 预检查三档分类 + 必填原因 + activitylog 完整审计 |
+
+## 场景手册(16 篇,**全部完成 ✅**)
+
+### 📝 账单创建(3 篇)
+
+- ✅ [月度物业费批量生成(`GeneratePeriodicBillsAction`)](../scenarios/billing/create-periodic-property-fee.md)
+- ✅ [抄表自动生成计量账单(走 meter pipeline)](../scenarios/billing/create-meter-bill-auto.md)
+- ✅ [手动建单(临时收费 / 调整账单)](../scenarios/billing/create-single-bill-manual.md)
+
+### 💰 收款(3 篇)
+
+- ✅ [单张账单收款(`CollectPaymentAction`)](../scenarios/billing/collect-payment-single.md)
+- ✅ [同业户多账单批量收款(`BatchCollectPaymentAction`)](../scenarios/billing/collect-payment-batch.md)
+- ✅ [预存款抵扣自动收款(关联 prepaid)](../scenarios/billing/collect-via-prepaid-auto.md)
+
+### ✂️ 账单调整(3 篇)
+
+- ✅ [拆账单(`SplitBillAction`,租户与房东分摊)](../scenarios/billing/split-bill.md)
+- ✅ [挂起账单(业户失联 / 纠纷)](../scenarios/billing/suspend-bill.md)
+- ✅ [恢复挂起的账单](../scenarios/billing/resume-bill.md)
+
+### 🗑️ 删除 / 作废(3 篇)
+
+- ✅ [物理删除未付账单(误建立刻删)](../scenarios/billing/delete-bill-unpaid.md)
+- ✅ [作废已付账单(走作废 + 退款)](../scenarios/billing/void-paid-bill.md)
+- ✅ [批量误建,智能 Modal 三档清理](../scenarios/billing/bulk-delete-batch-mistake.md)
+
+### 🛡️ 异常 / 审计(4 篇)
+
+- ✅ [部分付状态处理(Partial)](../scenarios/billing/exception-partial-payment.md)
+- ✅ [逾期账单清单 + 催收(`OverdueBillsListWidget`)](../scenarios/billing/exception-overdue-bills.md)
+- ✅ [月度账单生成 vs 收款对比(`MonthlyBillingVsCollectionChart`)](../scenarios/billing/audit-monthly-billing-vs-collection.md)
+- ✅ [activitylog 审计追溯](../scenarios/billing/audit-activitylog-trace.md)
+
+## 跨域引用
+
+本子模块引用以下跨域共享概念:
+
+- [业户](../../cross/concepts/resident.md) — 账单收方
+- [房屋单元](../../cross/concepts/housing-unit.md) — `asset_id`,账单关联房屋
+- [组织结构](../../cross/concepts/org-hierarchy.md) — `community_id`,物业项目归属
+
+## 跨子模块引用
+
+- [adhoc · CollectionOrder 与 Receipt](../concepts/adhoc/collection-order-and-receipt.md) — 收款侧的核心对象
+- [meter · 账单生成的三层分层](../concepts/meter/bill-generation-pipeline.md) — 计量账单的生成器
+- [prepaid · Consume 走 CollectionType=Bill](../concepts/prepaid/consume-via-bill-collection-type.md) — 预存款抵账单的资金流
+- [meter · 表退役与读数锁定](../concepts/meter/decommission-and-locking.md) — 类似的"状态机+守护"对比
+- [deposit · 账户与流水](../concepts/deposit/deposit-account-vs-transaction.md) — 双对象模式对比
+
+## 相关代码
+
+- 模型:[`Bill.php`](../../../packages/prop-acc/src/Models/Bill.php)、[`CollectionOrderBill.php`](../../../packages/prop-acc/src/Models/CollectionOrderBill.php)
+- 枚举:`BillStatus`(6 种)、`BillType`、`BillingMergeStrategy`、`FeeTypeBillType`
+- Policy:`BillPolicy`(7 个方法:update / delete / deleteAny / void / collect / suspend / resume)
+- 业务 Actions(src/Actions/Bills/):
+  - [`VoidBillAction`](../../../packages/prop-acc/src/Actions/Bills/VoidBillAction.php)
+  - [`SplitBillAction`](../../../packages/prop-acc/src/Actions/Bills/SplitBillAction.php)
+  - [`SuspendBillAction`](../../../packages/prop-acc/src/Actions/Bills/SuspendBillAction.php)
+  - [`ResumeBillAction`](../../../packages/prop-acc/src/Actions/Bills/ResumeBillAction.php)
+  - `BulkDeleteBillsAction`(智能批删)
+- Filament Resource:[`packages/prop-acc/src/Filament/Resources/Bills/`](../../../packages/prop-acc/src/Filament/Resources/Bills/)
+- Filament Actions(UI 入口):8 个(CollectPayment / BatchCollectPayment / GeneratePeriodicBills / Split / Suspend / Resume / Void / BulkDelete)
+- Widgets:`BillingStatsOverviewWidget`、`MonthlyBillingVsCollectionChart`、`FeeTypeRevenueDistributionChart`、`OverdueBillsListWidget`、`MonthlyRevenueTrendChart`
+- 业务设计决策:`packages/prop-acc/issue.md` 的 Q6 段(最详细的 issue 之一)
+
+## 相关文档
+
+- [prop-acc 域知识地图](knowledge-map.md)
+- [prop-acc 域首页](../index.md)
+- [adhoc 子模块知识地图](adhoc-knowledge-map.md)
+- [deposit 子模块知识地图](deposit-knowledge-map.md)
+- [prepaid 子模块知识地图](prepaid-knowledge-map.md)
+- [meter 子模块知识地图](meter-knowledge-map.md)
+- [跨域协作地图](../../cross/maps/cross-domain-map.md)
+
+---
+
+> [!success] billing 子模块:6 概念 + 16 场景 + 1 知识地图 = **23 篇完成**
+>
+> 写作日期: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 知识地图](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 同类对比)