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/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/freeze-suspected-fraud.md",
-    "prop-acc/scenarios/prepaid/refund-partial-after-consume.md",
-    "prop-acc/scenarios/prepaid/refund-full-resident-moveout.md",
-    "prop-acc/scenarios/prepaid/consume-batch-auto-monthly.md",
-    "prop-acc/scenarios/prepaid/consume-meter-bill.md",
-    "prop-acc/scenarios/prepaid/consume-multiple-bills-priority.md",
-    "prop-acc/scenarios/prepaid/consume-monthly-property-bill.md",
-    "prop-acc/scenarios/prepaid/deposit-via-miniapp-pending.md",
-    "prop-acc/scenarios/prepaid/deposit-additional-topup.md",
-    "prop-acc/scenarios/prepaid/deposit-first-time.md",
-    "prop-acc/concepts/prepaid/account-state-machine.md",
-    "prop-acc/scenarios/prepaid",
     "prop-acc/index.md",
-    "prop-acc/scenarios/deposit/deposit-first-time-renovation.md",
+    "prop-acc/scenarios/prepaid/deposit-first-time.md",
-    "prop-acc/scenarios/deposit/deposit-additional-topup.md",
+    "prop-acc/scenarios/billing/audit-activitylog-trace.md",
-    "prop-acc/maps/prepaid-knowledge-map.md",
+    "prop-acc/scenarios/billing/audit-monthly-billing-vs-collection.md",
+    "prop-acc/scenarios/billing/exception-overdue-bills.md",
+    "prop-acc/scenarios/billing/exception-partial-payment.md",
+    "prop-acc/scenarios/billing/bulk-delete-batch-mistake.md",
+    "prop-acc/scenarios/billing/void-paid-bill.md",
+    "prop-acc/scenarios/billing/delete-bill-unpaid.md",
+    "prop-acc/scenarios/billing/resume-bill.md",
+    "prop-acc/scenarios/billing/suspend-bill.md",
+    "prop-acc/scenarios/billing/split-bill.md",
+    "prop-acc/scenarios/billing/collect-via-prepaid-auto.md",
+    "prop-acc/scenarios/billing/collect-payment-batch.md",
+    "prop-acc/scenarios/billing/collect-payment-single.md",
+    "prop-acc/scenarios/billing/create-single-bill-manual.md",
+    "prop-acc/scenarios/billing/create-meter-bill-auto.md",
+    "prop-acc/scenarios/billing/create-periodic-property-fee.md",
+    "prop-acc/scenarios/billing",
+    "prop-acc/maps/billing-knowledge-map.md",
+    "prop-acc/concepts/billing/smart-bulk-delete-design.md",
+    "prop-acc/concepts/billing/delete-vs-void-dual-track.md",
+    "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/concepts/meter",
+    "prop-acc/scenarios/prepaid",
     "prop-acc/concepts/prepaid",
     "prop-acc/scenarios/deposit",
     "prop-acc/concepts/deposit",
     "prop-acc/scenarios/adhoc",
-    "prop-acc/concepts/adhoc",
+    "prop-acc/concepts/adhoc"
-    "resident-portal/scenarios",
-    "resident-portal/reference",
-    "resident-portal/procedures"
   ]
 }

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

@@ -26,8 +26,8 @@ last_review: 2026-05-25
 | **一次性收费** | IC 卡、装修证、泳票等单次购买 | [adhoc 知识地图](maps/adhoc-knowledge-map.md)     | ✅ 28 篇 |
 | **保证金**   | 装修押金等代管资金,完工后退还  | [deposit 知识地图](maps/deposit-knowledge-map.md) | ✅ 25 篇 |
 | **预存款**   | 业户预存,自动抵扣月度账单    | [prepaid 知识地图](maps/prepaid-knowledge-map.md) | ✅ 23 篇 |
-| **计量表**   | 水表/电表/燃气表,抄表生成账单 | [meter 知识地图](maps/meter-knowledge-map.md)    | 🟡 6 概念已完成,14 场景待补 |
+| **计量表**   | 水表/电表/燃气表,抄表生成账单 | [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

@@ -22,8 +22,8 @@ last_review: 2026-05-25
 | adhoc | 一次性收费 | IC 卡、装修证、泳票等单次购买 | [adhoc 知识地图](adhoc-knowledge-map.md) | ✅ 25 场景 + 3 概念 |
 | 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) | 🟡 6 概念已完成,14 场景待补 |
+| 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/maps/meter-knowledge-map.md

@@ -60,35 +60,33 @@ code_version: 2026-05-22
 | [抄表来源与拍照存证](../concepts/meter/reading-source-and-photo-proof.md) | `manual` 手抄 vs `remote` 集抄 + `photo_url` 凭证,业户争议时的证据 |
 | [表退役与读数锁定](../concepts/meter/decommission-and-locking.md) | 5 种退役原因 + Reading 双锁机制(创建即不可改,有 Bill 更不可改) |
 
-## 场景手册(14 篇,**待补充 ✋**)
+## 场景手册(14 篇,**全部完成 ✅**)
-
-> 🚧 概念骨架已就位,场景文档将在下一轮(轮 2)产出。预定结构如下。
 
 ### 📦 表管理(4 篇)
 
-- 🚧 [新社区批量建表 + 初始读数 Excel 导入](../scenarios/meter/init-new-community-batch.md)
+- ✅ [新社区批量建表 + 初始读数 Excel 导入](../scenarios/meter/init-new-community-batch.md)
-- 🚧 [单独新增一张表(后台单录)](../scenarios/meter/register-single-meter.md)
+- ✅ [单独新增一张表(后台单录)](../scenarios/meter/register-single-meter.md)
-- 🚧 [换表:旧表故障/退役,新表带 -R1 后缀,初始读数继承](../scenarios/meter/replace-broken-meter.md)
+- ✅ [换表:旧表故障/退役,新表带 -R1 后缀,初始读数继承](../scenarios/meter/replace-broken-meter.md)
-- 🚧 [退役不换表(房屋拆除 / 业户永久弃用)](../scenarios/meter/decommission-without-replacement.md)
+- ✅ [退役不换表(房屋拆除 / 业户永久弃用)](../scenarios/meter/decommission-without-replacement.md)
 
 ### 📊 抄表(4 篇)
 
-- 🚧 [单张表后台手动录入](../scenarios/meter/read-single-meter-manual.md)
+- ✅ [单张表后台手动录入](../scenarios/meter/read-single-meter-manual.md)
-- 🚧 [一次导入整月所有读数(Excel 批量)](../scenarios/meter/read-batch-via-excel-import.md)
+- ✅ [一次导入整月所有读数(Excel 批量)](../scenarios/meter/read-batch-via-excel-import.md)
-- 🚧 [集抄系统自动推送(`source=remote`)](../scenarios/meter/read-via-iot-remote-source.md)
+- ✅ [集抄系统自动推送(`source=remote`)](../scenarios/meter/read-via-iot-remote-source.md)
-- 🚧 [抄表拍照存证(物理表头照片)](../scenarios/meter/read-with-photo-proof.md)
+- ✅ [抄表拍照存证(物理表头照片)](../scenarios/meter/read-with-photo-proof.md)
 
 ### 💰 账单生成(3 篇)
 
-- 🚧 [阶梯水电价生成账单(progressive 累进算例)](../scenarios/meter/generate-bill-tiered-pricing.md)
+- ✅ [阶梯水电价生成账单(progressive 累进算例)](../scenarios/meter/generate-bill-tiered-pricing.md)
-- 🚧 [工业表 10x 倍率生成账单](../scenarios/meter/generate-bill-with-multiplier.md)
+- ✅ [工业表 10x 倍率生成账单](../scenarios/meter/generate-bill-with-multiplier.md)
-- 🚧 [单笔账单上下限封顶(防异常用量爆账)](../scenarios/meter/generate-bill-min-max-cap.md)
+- ✅ [单笔账单上下限封顶(防异常用量爆账)](../scenarios/meter/generate-bill-min-max-cap.md)
 
 ### 🛡️ 异常 / 审计(3 篇)
 
-- 🚧 [高用量异常(漏水 / 电器故障),`HighConsumptionReadingsListWidget` 预警](../scenarios/meter/exception-high-consumption.md)
+- ✅ [高用量异常(漏水 / 电器故障),`HighConsumptionReadingsListWidget` 预警](../scenarios/meter/exception-high-consumption.md)
-- 🚧 [已生成 Bill 的 Reading 锁定,要修正需作废 Bill](../scenarios/meter/exception-readings-locked-after-bill.md)
+- ✅ [已生成 Bill 的 Reading 锁定,要修正需作废 Bill](../scenarios/meter/exception-readings-locked-after-bill.md)
-- 🚧 [待抄表清单 + 月度抄表完成率(`MetersNeedingReadingListWidget`)](../scenarios/meter/audit-meters-needing-reading.md)
+- ✅ [待抄表清单 + 月度抄表完成率(`MetersNeedingReadingListWidget`)](../scenarios/meter/audit-meters-needing-reading.md)
 
 ## 跨域引用
 
@@ -129,6 +127,9 @@ code_version: 2026-05-22
 
 ---
 
-> [!info] 概念已完成,场景待补
+> [!success] meter 子模块:6 概念 + 14 场景 + 1 知识地图 = **21 篇完成**
-> 本轮(轮 1)产出:6 个概念 + 本子模块地图 + 域总图更新。
+>
-> 下一轮(轮 2)产出:14 个场景文档,基于本知识地图骨架填充。
+> 写作日期:2026-05-26
+> 对应代码版本:2026-05-22(详见 `packages/prop-acc/issue.md` Q5 段)
+>
+> 如果发现遗漏的场景或需要补充的细节,告诉我,可以单独补充新文档。

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 同类对比)

prop-acc/scenarios/meter/audit-meters-needing-reading.md

@@ -0,0 +1,261 @@
+---
+title: prop-acc · meter · 场景 - 待抄表清单 + 月度抄表完成率
+aliases:
+  - 待抄表清单
+  - 抄表完成率
+  - audit-meters-needing-reading
+  - MetersNeedingReadingListWidget
+  - 场景-待抄表审计
+tags:
+  - 场景
+  - prop-acc
+  - 计量表
+  - 审计
+audience:
+  - 业务人员
+  - 财务
+  - 抄表员
+status: 已发布
+sub_feature: meter
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 场景:待抄表清单 + 月度抄表完成率
+
+物业**月底**核对:本月**应抄**多少张表(在役表数)vs **已抄**多少张(本月有 reading 的表)。差额 = **待抄表清单**(可能是抄表员漏抄 / 集抄掉线)。`MetersNeedingReadingListWidget` 在 `MeterDashboard` 实时显示。
+
+## 典型情境
+
+> [!example] 真实情境
+> 5 月 28 日王主管打开 `MeterDashboard`,看 `MetersNeedingReadingListWidget`:
+>
+> - 嘉禾花园在役表 1,200 张
+> - 本月已抄 1,150 张
+> - **待抄 50 张**
+>
+> 分析:
+> - 30 张:集抄掉线(`source=remote` 应自动推但没推)
+> - 15 张:抄表员遗漏(手抄区域漏了)
+> - 5 张:业户家无人无法入户读表
+>
+> 5/30 截止前必须补齐(否则当月账单缺漏)。
+
+## 业务人员视角
+
+### Widget 显示
+
+`MetersNeedingReadingListWidget`(MeterDashboard):
+
+| 列 | 内容 |
+|---|---|
+| 业户 / 资产 | 房号 + 业户姓名 |
+| 表编号 | meter code |
+| 费用类型 | 水/电/燃气 |
+| 上次抄表日期 | 上月 read_at |
+| 抄表来源 | manual / remote(看历史)|
+| 状态 | 未抄 / 部分缺漏 |
+| 操作 | 链接到该 meter 的录入入口 |
+
+排序:**按上次抄表日期升序**(最久没抄的优先,可能问题最大)。
+
+### 完成率计算
+
+```
+本月完成率 = 本月已抄表数 / 在役表总数
+        = 1150 / 1200
+        = 95.8%
+```
+
+业务上通常**目标 > 99%**(漏抄太多说明流程有问题)。
+
+### 分级处置
+
+| 待抄类型 | 数量 | 处置 |
+|---|---|---|
+| 集抄掉线 | 30 | 联系集抄运营商 + 抄表员现场补抄 |
+| 抄表员漏抄 | 15 | 抄表员立即补抄 |
+| 业户无人 | 5 | 多次上门 / 与业户约时间 / 估算用量(罕见) |
+
+### 处理流程
+
+```mermaid
+flowchart TD
+  A[Widget 显示 50 张待抄] --> B{分类}
+
+  B -->|集抄掉线 30 张| C[联系集抄运营商]
+  C --> D{原因}
+  D -->|网关故障| E[运营商修复 → 重推数据]
+  D -->|个别表故障| F[抄表员现场补抄 + 走 replace-broken-meter]
+
+  B -->|抄表员漏抄 15 张| G[立即补抄]
+
+  B -->|业户无人 5 张| H[多次上门 / 约时间]
+  H --> I{约不上}
+  I -->|是| J[估算用量 / 用 min_amount 兜底 / 延后处理]
+  I -->|否| G
+
+  E --> K[完成率回升]
+  F --> K
+  G --> K
+```
+
+### 月度执行清单
+
+每月最后一周(25-30 号),业务人员清单:
+
+- [ ] 25 号:看 Widget,记录待抄数 + 分类
+- [ ] 26-28 号:跟进集抄运营商 + 抄表员补抄
+- [ ] 29 号:再看 Widget,核对剩余待抄
+- [ ] 30 号:截止前完成 99%+,剩余的特殊处理
+- [ ] 月初(1 号):看完成率报告 + 触发账单生成
+
+## 抄表员视角(李师傅)
+
+### 自己的清单
+
+抄表员手机 App 上显示**本月分配的清单**(类似 widget 但只显示自己负责的区域)。
+
+每天进度:
+
+- 上午:看清单 + 规划路线
+- 现场抄表 + 拍照 + 录入
+- 下午回办公室:补录 / 同步
+
+完成度自我管理。月底向王主管报告:"本月我负责的 X 张表已完成 Y 张,剩 Z 张是 [原因] 需 [协助]"。
+
+## `MetersNeedingReadingListWidget` 实现
+
+> [!info] 当前实现的逻辑
+>
+> SQL 大概:
+>
+> ```sql
+> -- 在役表里,本月没有 reading 的
+> SELECT m.*, MAX(r.read_at) AS last_read_at
+> FROM acc_meters m
+> LEFT JOIN acc_meter_readings r ON r.meter_id = m.id
+> WHERE m.is_active = true
+>   AND m.community_id = ?
+>   -- 本月起没有 reading
+>   AND m.id NOT IN (
+>     SELECT meter_id FROM acc_meter_readings
+>     WHERE read_at BETWEEN '2026-05-01' AND '2026-05-31 23:59:59'
+>   )
+> GROUP BY m.id
+> ORDER BY last_read_at ASC;
+> ```
+>
+> 关键:
+> - 只看在役表(退役表 `is_active=false` 不算)
+> - "本月没 reading" = 待抄
+> - "上次抄表日期久远" = 优先级高
+
+## 报表 / 周报
+
+王主管月初出报告(给物业总经理 / 财务总监):
+
+```markdown
+# 2026 年 5 月 嘉禾花园抄表完成率报告
+
+## 总览
+- 在役表:1,200 张
+- 本月已抄:1,200 张(目标 99%,实际 100%)
+- 完成率:100% ✅
+
+## 抄表来源分布
+- 集抄(remote):1,160 张(96.7%)
+- 手抄(manual):40 张(3.3%)
+  - 集抄掉线补抄:30 张
+  - 业户无人后多次上门:10 张
+
+## 异常事件
+- 集抄掉线高峰:5/25 一天 30 张(网关故障 4 小时,运营商已修)
+- 单户长期无人:王先生(15-7-203),已联系成功 + 补抄
+
+## 趋势
+- 4 月完成率 99.8%(漏 2 张次月补)
+- 5 月完成率 100%(全部当月完成)
+- 集抄稳定性提升(运营商升级了网关)
+
+## 建议
+- 与集抄运营商签更严的 SLA(网关掉线 < 1 小时)
+- 给抄表员增加"无人户备份方案"(预约 + 业户授权代抄)
+```
+
+## 业户视角
+
+业户**通常不感知**这个审计动作。极少数情况:
+
+| 业户场景 | 业户感知 |
+|---|---|
+| 业户无人导致漏抄,下月补 | 收到的下月账单可能比往常高(两个月用量)|
+| 集抄掉线导致补抄 | 物业可能上门 / 微信问"麻烦看下您家水表读数发我下" |
+| 长期补不上 | 物业按"平均月用量"估算账单(业户可能不爽)|
+
+## 与其他审计的对比
+
+| 审计场景 | 关注什么 | 频率 |
+|---|---|---|
+| **本场景(待抄表)** | 月度抄表完成率 | 月度 |
+| [[exception-high-consumption|高用量预警]] | 异常用量预防 | 月度(抄表完成后)|
+| [[../deposit/audit-monthly-deposit-balance|押金月度对账]] | 账面 vs 银行平衡 | 月度 |
+| [[../prepaid/audit-low-balance-and-overdue|预存款低余额]] | 业户预存款健康度 | 每周 / 月度 |
+
+各模块审计**频率与关注点不同**,本场景是 meter 模块的**最重要月度审计**。
+
+## 常见问题
+
+> [!question] 完成率 < 95% 的常见原因?
+> - 集抄设备大面积故障
+> - 抄表员人手不足
+> - 业户长期无人 / 拒绝抄表
+> - 系统 bug(meter 状态错乱)
+>
+> 长期完成率低 → 升级集抄 / 改流程 / 加人手。
+
+> [!question] 漏抄的表下月一起算可以吗?
+> 可以,但**业户体验差**(账单突然翻倍)。推荐:
+> - 当月尽量补齐
+> - 实在补不齐 → 让业户**自报**读数(业务上接受,需核对)
+> - 估算用量(罕见,看物业政策)
+
+> [!question] 业户长期无人怎么办?
+> - 多次上门(2-3 次)
+> - 业户授权代抄(物业拿钥匙 / 业户邻居代抄)
+> - 估算用量(按往月平均算)
+> - 长期(> 6 个月)无人 → 标记为"特殊处理户",月度估算 / 等业户回来再补
+
+> [!question] 集抄运营商频繁掉线,物业如何制约?
+> 合同 SLA:
+> - 集抄运营商承诺 99% 在线率
+> - 违约罚款(掉线超 X 小时罚 Y 元)
+> - 严重违约 → 解约换供应商
+
+> [!question] 漏抄但已经生成账单(只是少了 N 户)能补充生成吗?
+> 可以。补抄 → 录 reading → 触发 [[bill-generation-pipeline|GenerateBills]] 对新 reading 生成 Bill。已有 Bill 不受影响。
+
+## 升级机会(待补)
+
+`MetersNeedingReadingListWidget` 当前简版,可升级为:
+
+- **更精准的"待抄"判定**(按抄表周期,不一定按月)
+- **完成率趋势图**(月度趋势线)
+- **抄表员效率排名**(谁抄得快 / 准)
+- **预警机制**(月底前 7 天若完成率 < 90% 自动告警)
+
+## 异常分支
+
+- 高用量预警(完成抄表后)→ [[exception-high-consumption]]
+- 已生成 Bill 的 reading 错(本场景兜底)→ [[exception-readings-locked-after-bill]]
+- 集抄系统 → [[read-via-iot-remote-source]]
+- 单录补抄 → [[read-single-meter-manual]]
+
+## 相关文档
+
+- [[bill-generation-pipeline]]
+- [[exception-high-consumption]]
+- [[exception-readings-locked-after-bill]]
+- [[read-via-iot-remote-source]]
+- [[read-single-meter-manual]]
+- [[../deposit/audit-monthly-deposit-balance]](类似月度对账模式)

prop-acc/scenarios/meter/decommission-without-replacement.md

@@ -0,0 +1,191 @@
+---
+title: prop-acc · meter · 场景 - 退役不换表(房屋拆除/业户永久弃用)
+aliases:
+  - 退役不换表
+  - 永久弃用
+  - decommission-without-replacement
+  - 场景-计量表退役不换
+tags:
+  - 场景
+  - prop-acc
+  - 计量表
+  - 表管理
+audience:
+  - 业务人员
+status: 已发布
+sub_feature: meter
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 场景:退役不换表(房屋拆除/业户永久弃用)
+
+物理表**不再需要**(房屋拆除 / 业户永久搬走 / 商铺撤店 / 法定使用年限到不续装),系统**只退役不建新表**。`decommission_reason` 选 `Removed` / `Expired` 等,不走 `ReplaceMeterAction`。
+
+## 典型情境
+
+> [!example] 真实情境(一):房屋拆除
+> 嘉禾花园三期某栋老楼要拆迁重建,3 单元 1-6 层 30 户业主已全部搬走,准备拆楼。该单元所有水电气表(共 90 张)需要**永久退役**(房子拆了表也没了)。
+
+> [!example] 真实情境(二):商铺撤店
+> 一楼商铺(原餐饮店)经营 5 年后结业,装修拆除,新承租人方向未定。原餐饮店专用商业电表 + 燃气表暂不需要,**退役归档**(等新承租人入驻再视情况建新表)。
+
+> [!example] 真实情境(三):法定使用年限到
+> 一批 2010 年装的电表到 2026 年达到法定 15 年使用年限。物业评估:
+> - 部分表性能仍好 + 业户无投诉 → 送校验,合格继续用([[replace-broken-meter|换表]] 的 `Calibration` reason)
+> - 部分表频繁出问题 + 业户投诉 → 退役换新表(`Replaced`)
+> - 个别表所在房屋已无人居住 → **退役不换表**(`Expired`)
+
+## 业务人员视角(王主管)
+
+### 第 1 步:确认场景与原因
+
+选择正确的 `decommission_reason`:
+
+| 场景 | 推荐 reason |
+|---|---|
+| 房屋拆除 | `Removed` |
+| 业户永久搬走且无新业户 | `Removed` |
+| 法定年限到不续装 | `Expired` |
+| 校验送检中暂停(后续可能恢复) | `Calibration`(暂停态,不算永久退役)|
+| 损坏不修(整体弃用)| `Damaged` |
+| (换新表替代) | `Replaced` — **走 [[replace-broken-meter]] 不是本场景** |
+
+### 第 2 步:打开表
+
+后台 → 计量表 → 按 asset 查找 → 进 `ViewMeter`(`is_active=true`)。
+
+### 第 3 步:`EditMeter` 改字段(或专用退役 Action,看 UI 设计)
+
+> [!info] UI 实现注意
+> 当前实现可能**没有专门的"退役不换表"按钮**,而是通过:
+> - `EditMeter` 页直接改 `is_active=false` + 填 `decommissioned_at` + `decommission_reason` + `final_reading`
+> - 或自定义"退役"Action(若实现了)
+>
+> 看具体 `MeterForm` 的字段开关。若没专用按钮,走 EditMeter。
+
+填字段:
+
+| 字段 | 填什么 |
+|---|---|
+| `is_active` | **false**(取消勾选)|
+| `decommissioned_at` | 2026-05-26 |
+| `decommission_reason` | `Removed`(本场景一) / `Expired` / `Damaged` |
+| `final_reading` | 退役那天的物理读数(若可读)/ 0(若表已被拆除无法读)|
+| 备注 | 关键说明,如 "三期 3-1-101 拆迁,房屋已拆,表无法回读" |
+
+### 第 4 步:提交
+
+系统:
+
+1. 校验旧表 `is_active=true`(`EditMeter` 守护 `->visible(is_active)`)
+2. update Meter:`is_active=false`, `decommissioned_at`, `decommission_reason`, `final_reading`
+3. **不建新表**(与 [[replace-broken-meter|换表]] 的关键区别)
+
+### 第 5 步:后续不抄表
+
+`MetersNeedingReadingListWidget` 自动**不再显示**此表(`is_active=false` 过滤)。
+
+历史 reading 保留,可查。
+
+## 批量退役
+
+如果是单元拆除(90 张表一起退役),逐张走太慢。可能的批量方案:
+
+| 方案 | 实现 |
+|---|---|
+| **List 页批量 Edit**(若有 BulkAction) | 选中多张 → 批量改 `is_active=false` |
+| **Excel 导入"退役清单"** | 类似 `MeterInitializationImporter`,但当前没此功能(可补)|
+| **tinker 脚本**(运维)| `Meter::whereIn('id', [...])->update([...])`,**留 audit log** |
+
+当前推荐:**业务量小的话逐张 EditMeter**;**业务量大的话联系运维**走 tinker(批量改字段 + 留事由记录)。
+
+## 系统流程
+
+```mermaid
+sequenceDiagram
+    participant 王主管
+    participant Filament
+    participant EditMeter
+    participant 数据库
+
+    王主管->>Filament: 找到要退役的表 → ViewMeter → 编辑
+    Filament->>EditMeter: 渲染 form
+    王主管->>EditMeter: is_active=false + 填 decommissioned_at + reason + final_reading + 备注
+    EditMeter->>EditMeter: 校验 is_active=true(原状态)+ Policy update 权限
+    EditMeter->>数据库: update Meter 字段
+    数据库-->>Filament: ok
+    Filament-->>王主管: 跳回 ViewMeter,状态显示"已退役 - Removed - 2026-05-26"
+```
+
+## 退役后的状态
+
+| 字段 | 退役后值 |
+|---|---|
+| `is_active` | false |
+| `decommissioned_at` | 2026-05-26 |
+| `decommission_reason` | `Removed` |
+| `final_reading` | 退役当天读数(或 0)|
+| `replaced_meter_id` | null(没有继任者)|
+| 后续是否能改字段 | **几乎不能**(`EditMeter` `visible(is_active)` 守护 + Policy 拦截)|
+| 后续是否能删 | 仅当**无任何 reading** 时(罕见)|
+
+详见 [[decommission-and-locking]]"退役后的行为"段。
+
+## 与"换表"的关键差异
+
+| 维度 | [[replace-broken-meter|换表(Replaced)]] | **退役不换表(本场景)** |
+|---|---|---|
+| `decommission_reason` | `Replaced` | `Removed` / `Expired` / `Damaged` |
+| 是否建新表 | ✅ 是,带 `-R1` 后缀 | ❌ 否 |
+| 业户后续是否要付水电费 | 是(用新表继续计费)| 否(无表无计费)|
+| 房屋状态 | 仍有人住 | 通常拆 / 撤 / 弃用 |
+| 触发 UI | `ReplaceMeterAction`(专用)| `EditMeter`(改字段)|
+
+## 业户视角
+
+业户**通常感知不到**这条系统操作,因为业户本人也搬走 / 房屋已拆。
+
+如果是商铺撤店 / 房屋暂时无人(后续可能有新业户),系统层面表已退役,**未来如有新业户入住要重新装表 → 建新表(走 [[register-single-meter]]),不是"复活"旧表**。
+
+## 常见问题
+
+> [!question] 退役表能"复活"吗(`is_active=false → true`)?
+> Policy 设计上**不允许**(`EditMeter` 在 `is_active=false` 时隐藏所有编辑)。如果真需要复活:
+>
+> - tinker 改字段(运维,留事由)
+> - 推荐做法:**建新表**替代,旧表保持退役状态(历史档案)
+
+> [!question] 退役表如何处理未付的历史 Bill?
+> 表退役**不影响**已生成的 Bill(Bill 关联 reading 关联表,数据完整)。业户该付的还是要付。
+>
+> 若业户也搬走联系不上:走逾期催收流程(不在本场景)。
+
+> [!question] 退役不换表后,房屋还在但暂无业户用电怎么办?
+> 房屋空置但有可能后续入驻 → **保留表 active 状态**,只是没有抄表数据(零用量)。每月账单可能仍生成(看 RatePlan 是否有 `min_amount`,详见 [[multiplier-and-tiered-pricing|min/max 封顶]])。
+>
+> 真的永久不需要 → 退役。
+
+> [!question] `decommission_reason` 选错了能改吗?
+> 退役后修改字段被 Policy 拦截。若改错只能 tinker 修(运维 + 留事由)。
+>
+> **预防**:退役前确认场景,选对 reason。
+
+> [!question] 退役了但表上物理装着没拆走怎么办?
+> 系统层面无区别(系统不管物理状态,只管"系统层面已退役")。物业人员需要**实际去现场拆表**(若房屋拆迁要拆楼)或**留存**(若只是商铺暂关)。系统不管理物理库存。
+
+> [!question] 表的物理库存追踪?
+> 当前系统**不涉及**。物业的"实物计量表"库存(回收、报废、复用)在 ERP / 资产管理系统里处理,不在本子模块。
+
+## 异常分支
+
+- 换表(有新表替代)→ [[replace-broken-meter]]
+- 误退役想撤销 → 困难,见上方"复活"问题
+- 退役后无历史读数想删表 → 见 [[decommission-and-locking]]"退役表的物理删除"段
+
+## 相关文档
+
+- [[decommission-and-locking]]
+- [[replace-broken-meter]]
+- [[meter-vs-meter-reading]]
+- [[multiplier-and-tiered-pricing]]

prop-acc/scenarios/meter/exception-high-consumption.md

@@ -0,0 +1,239 @@
+---
+title: prop-acc · meter · 场景 - 高用量异常(漏水/电器故障)
+aliases:
+  - 高用量预警
+  - 漏水告警
+  - exception-high-consumption
+  - HighConsumptionReadingsListWidget
+  - 场景-高用量异常
+tags:
+  - 场景
+  - prop-acc
+  - 计量表
+  - 异常
+audience:
+  - 业务人员
+  - 业户
+  - 抄表员
+status: 已发布
+sub_feature: meter
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 场景:高用量异常(漏水/电器故障)
+
+业户**用量异常**(漏水 / 电器故障 / 偷电),系统通过 `HighConsumptionReadingsListWidget` 在月度抄表数据出来后**主动预警**,业务人员介入排查,避免账单生成后业户暴击 / 投诉。
+
+## 典型情境
+
+> [!example] 真实情境
+> 5 月底集抄 / 批量抄表完成,王主管打开 `MeterDashboard`:
+>
+> - `HighConsumptionReadingsListWidget` 显示 **本月用量 top 20** 的 reading
+> - 其中前 3 名:
+>
+> | 业户 | 表 | 上月 | 本月 | 用量 | 异常? |
+> |---|---|---|---|---|---|
+> | 张阿姨(12-3-501) | 水表 | 12 吨 | **800 吨** | 800 | 🔴 极度异常(漏水) |
+> | 陈先生(12-3-502) | 电表 | 200 度 | **2,800 度** | 2,800 | 🔴 异常高(空调故障 / 偷电) |
+> | 商铺一楼餐厅 | 电表 | 1,500 度 | **3,200 度** | 3,200 | 🟡 警告(正常波动?旺季?)|
+>
+> 王主管立即处理。
+
+## 业务人员视角
+
+### Widget 显示
+
+`HighConsumptionReadingsListWidget`(后台 → MeterDashboard):
+
+| 列 | 内容 |
+|---|---|
+| 业户 / 资产 | 房号 + 业户姓名 |
+| 表编号 | meter code |
+| 上月用量 | previous reading 推出 |
+| 本月用量 | consumption |
+| 倍数 | 本月 / 上月 |
+| 抄表日期 | read_at |
+| 操作 | 链接到 reading 详情 / 查看 / 联系业户 |
+
+排序:**按 consumption 降序 top 20**(简版实现,详见下方"待补")。
+
+### 分级处置
+
+| 级别 | 触发 | 处置 |
+|---|---|---|
+| 🔴 **极度异常**(>10× 历史平均) | 漏水 / 大型故障 | 立即联系业户 + 派人现场检查 |
+| 🔴 **高异常**(>3× 历史平均) | 设备故障 / 习惯改变 | 联系业户确认 |
+| 🟡 **警告**(>1.5× 历史平均) | 正常波动 / 季节性 | 推送提醒 / 标记观察 |
+| 🟢 **正常** | < 1.5× | 不处理 |
+
+### 处理流程(漏水案例)
+
+```mermaid
+flowchart TD
+  A[Widget 显示张阿姨水 800 吨] --> B[王主管联系张阿姨]
+  B --> C{业户回应}
+
+  C -->|"我不知道,你来看看"| D[派维修队上门]
+  C -->|"啊?我不可能用这么多"| D
+  C -->|"我装修了用水多"| E[业户接受账单]
+
+  D --> F{查到原因?}
+  F -->|墙内暗水管漏水| G[维修 + 重算账单]
+  F -->|无可见漏水点| H[换表测试是否表故障]
+
+  H --> I{换表后情况}
+  I -->|新表用量正常| J[确认旧表故障 + 走修正流程]
+  I -->|新表用量仍异常| K[排查家电 / 业户习惯]
+
+  G --> L[与业户协商:走 max 封顶/部分减免/重算]
+  J --> L
+```
+
+### 修正账单(若证实表故障)
+
+如果证实是表故障 / 抄表错:
+
+1. 走 [[replace-broken-meter|换表]]([[decommission-and-locking|退役旧表]])
+2. 旧 reading 已生成 Bill → 走 [[exception-readings-locked-after-bill|作废 Bill]] 流程
+3. 重新算正确用量 → 重生成 Bill
+4. 业户付正确金额
+
+## `HighConsumptionReadingsListWidget` 实现现状
+
+> [!info] 当前实现简版,issue.md Q5 已标待升级
+> 当前:**按 consumption 降序 top 20**,不是统计学意义的异常检测。
+>
+> issue.md Q5"待补":
+>
+> - **3σ 异常**(对比历史 3 个月平均的标准差)
+> - **倒走告警**(current < previous)
+> - **0 读数告警**(可能表故障)
+>
+> 当前简版的缺陷:
+> - 排名靠前的可能是商铺 / 工业表(正常用量大),不是真异常
+> - 漏掉"中等用量但异常波动"的住户(从 12 吨涨到 50 吨,绝对数小但相对倍数高)
+> - 没区分"业户家用电习惯变了"vs"漏水 / 故障"
+
+业务人员**需自行判断**(看 Widget 内容 + 历史用量对照 + 联系业户)。
+
+## 业户视角
+
+### 您可能收到的联系
+
+物业打电话 / 微信 / 上门:
+
+> 张阿姨您好,您家本月水量异常高(800 吨,平时 12 吨)。请问您家最近是否有装修 / 漏水 / 大量用水活动?如有疑问,我们可派维修队上门检查。
+
+### 您要做的
+
+| 情况 | 您要做 |
+|---|---|
+| 确实在装修 / 大量用水 | 接受账单 + 看是否触发 [[generate-bill-min-max-cap|max 封顶]] 减免 |
+| 不知道原因 / 怀疑漏水 | 同意物业派人上门检查 |
+| 怀疑表 / 系统错 | 要求看 [[read-with-photo-proof|抄表照片]] + 派人现场再读一次 |
+
+### 检测到漏水后的减免
+
+物业**通常会减免**(看政策):
+
+- 部分减免(承担一半 / 30%)
+- 全免(罕见,看物业宽厚)
+- 按"平时月用量"算账(常见)
+- max 封顶后业户支付封顶值,差额物业承担
+
+具体看物业与业户的协商 + 物业的"漏水维修保险"理赔。
+
+## 系统流程
+
+```mermaid
+sequenceDiagram
+    participant 集抄/抄表员
+    participant 系统
+    participant Widget[HighConsumptionReadingsListWidget]
+    participant 王主管
+    participant 业户
+
+    集抄/抄表员->>系统: 推 / 录入本月 reading
+    系统->>系统: 建 MeterReading + 算 consumption
+
+    Note over 系统: 月度数据完成
+
+    王主管->>Widget: 打开 MeterDashboard
+    Widget->>系统: SELECT TOP 20 reading ORDER BY consumption DESC
+    系统-->>Widget: 显示 top 20 异常清单
+
+    王主管->>王主管: 看清单 → 分级处置
+
+    loop 每个 🔴 异常
+        王主管->>业户: 联系 + 排查
+        alt 漏水 / 故障
+            王主管->>系统: 走修正流程(换表 / 作废 Bill 重算)
+        else 业户认账
+            王主管->>系统: 接受 + 触发 max 封顶减免(若适用)
+        end
+    end
+```
+
+## 高用量的常见原因清单
+
+| 原因 | 业户感知 | 处置 |
+|---|---|---|
+| **水管漏水**(墙内 / 管井) | 业户不知道,直到账单异常 | 派维修队 + 修管子 + 减免 |
+| **马桶漏水**(节流阀坏) | 业户偶尔听到流水声 | 业户自修 / 物业协助 |
+| **空调 24h 不关** | 业户习惯 | 业户调整 / 接受账单 |
+| **旧冰箱故障**(压缩机一直跑) | 业户不知道 | 业户换冰箱 |
+| **电热水器**(储热式漏电 / 一直加热) | 业户不知道 | 业户检查 |
+| **业户偷电 / 绕表** | 物业 / 国家电网监管 | 法律责任 |
+| **抄表错** | (系统层面)| 走 [[exception-readings-locked-after-bill|修正]] |
+| **集抄数据错** | (系统层面)| 同上 |
+| **表故障**(乱跳)| 业户长期感觉 | [[replace-broken-meter|换表]] |
+| **大型装修 / 大量用水活动** | 业户自知 | 业户接受账单 |
+
+## 常见问题
+
+> [!question] Widget 显示的"top 20"是当月吗?
+> 看 Widget 实现。可能是:
+>
+> - 本月(`read_at` 在当月)
+> - 最近 30 天
+> - 所有未结账 reading
+>
+> 业务上推荐"本月",每月初看一遍 + 月底再看一遍。
+
+> [!question] 排查发现是抄表错 + 已经生成 Bill 了怎么办?
+> 走 [[exception-readings-locked-after-bill]] 流程:作废 Bill → 修正 reading → 重生成 Bill。复杂,需运维 / 高权限介入。
+
+> [!question] 业户漏水但拒不修怎么办?
+> 物业**强烈建议** + **法律手段**(漏水可能影响楼下邻居,涉及侵权)。系统层面无法干预。
+
+> [!question] 商铺 / 工业用户的"高用量"和住宅"高用量"判断标准应该一样吗?
+> **不一样**。商铺正常用量本来就大。Widget 当前简版**无区分**,需业务人员自己判断。
+>
+> 升级建议:Widget 按 `asset_type`(住宅 / 商铺 / 工业)分别统计 + 各自的"异常阈值"。
+
+> [!question] 排查后没找到原因(业户也说没漏水也没新增电器)?
+> 几个可能:
+> - 业户家有人偷接电(罕见)
+> - 表故障(漂移)→ 换表观察一个月
+> - 集抄 / 抄表系统 bug(同时多户异常?排查系统)
+
+> [!question] 高用量预警之外,有"用量异常低"(可能业户搬走 / 表故障 0 读数)预警吗?
+> 当前**无**(只有高用量 widget)。需求详见 issue.md Q5"待补"。
+
+## 异常分支
+
+- 排查确认是抄表错 → [[exception-readings-locked-after-bill]] 修正
+- 排查确认是表故障 → [[replace-broken-meter|换表]]
+- 业户接受账单 → 走 [[generate-bill-min-max-cap|max 封顶]](若适用)
+- 待抄表清单(对偶场景)→ [[audit-meters-needing-reading]]
+
+## 相关文档
+
+- [[multiplier-and-tiered-pricing]]
+- [[generate-bill-min-max-cap]]
+- [[exception-readings-locked-after-bill]]
+- [[replace-broken-meter]]
+- [[audit-meters-needing-reading]]
+- [[reading-source-and-photo-proof]]

prop-acc/scenarios/meter/exception-readings-locked-after-bill.md

@@ -0,0 +1,249 @@
+---
+title: prop-acc · meter · 场景 - 已生成 Bill 的 Reading 锁定,要修正需作废 Bill
+aliases:
+  - Reading 锁定
+  - 已落账 reading 修正
+  - exception-readings-locked-after-bill
+  - 作废 Bill 重算
+  - 场景-已落账读数修正
+tags:
+  - 场景
+  - prop-acc
+  - 计量表
+  - 异常
+  - 数据完整性
+audience:
+  - 业务人员
+  - 架构师
+status: 已发布
+sub_feature: meter
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 场景:已生成 Bill 的 Reading 锁定,要修正需作废 Bill
+
+`MeterReading` 一经创建**不可改**;**一旦生成 Bill 更不可改 / 不可删**(双锁,见 [[decommission-and-locking]])。如果发现已落账 reading 数据错(抄表录错 / 集抄错传 / 业户质疑成功),需走**复杂修正流程**:**先作废 Bill → 改 reading(实际是建新 reading + 标旧 reading 作废)→ 重生成 Bill**。
+
+## 典型情境
+
+> [!example] 真实情境
+> 5 月底抄表 + 自动生成账单。陈先生 5 月电费账单 ¥1,200(2,800 度,异常高,触发 [[exception-high-consumption|高用量预警]])。
+>
+> 物业派人排查,发现:
+> - **抄表员李师傅手抖**:把 1,500 录成 2,500
+> - 实际本月用量 ~1,500 度,账单应 ¥600 左右(不是 1,200)
+>
+> 陈先生质疑成功,物业要把账单从 1,200 改成 ~600。但:
+> - **Reading 不可改**(系统层面双锁)
+> - **Bill 已经生成 + 关联 reading**
+>
+> 需要走**作废 + 重算**的组合流程。
+
+## 当前实施状态
+
+> [!warning] **当前系统不支持自动化此流程**
+>
+> issue.md Q5 "待补"段明确记录:
+>
+> > **"作废已生成 Bill 的 MeterReading"组合流程**:当前 Reading 一旦生成 Bill 即锁定。要修正错误读数需要先**作废 Bill** 再改 Reading 再重新生成。这个组合流程类似 AdHocEvent 的 `VoidAction`(级联废 + 留 voided 审计),需要单独设计。等业务方明确"已收款的 Bill 应该怎么撤销"再做(可能涉及红字 Bill / 退款)。
+>
+> **当前替代**:运维 / 高权限人员通过 tinker 手工处理。本场景描述**业务流程层**和**未来的目标态**。
+
+## 业务人员视角(当前手工处理)
+
+### 第 1 步:确认要修正
+
+- 业户质疑账单 + 提供合理证据(自家拍照 / 历史数据对照)
+- 物业核对:抄表照片 / 集抄数据 / 物理表
+- 内部决定:确实要修正
+
+### 第 2 步:看账单是否已付
+
+| 账单状态 | 处理路径 |
+|---|---|
+| **未付**(Unpaid)| 简单:作废 Bill → 重算 |
+| **已付**(Paid,业户付现金/微信)| 复杂:作废 Bill → 业户**退款** → 重新出账单 → 业户**重付** |
+| **已付**(用 [[../prepaid/consume-monthly-property-bill|预存款抵扣]])| 复杂:作废 Bill → 预存款**反向充值** → 重新出账单 → 重新抵扣 |
+
+### 第 3 步:走"作废 Bill"流程
+
+当前**没专用 UI** —— 联系运维 / 高权限人员:
+
+```php
+// tinker 操作示意(运维)
+DB::transaction(function () use ($readingId) {
+    $reading = MeterReading::find($readingId);
+    $oldBill = Bill::find($reading->bill_id);
+
+    // 1. 作废 Bill
+    $oldBill->update([
+        'status' => BillStatus::Voided,
+        'voided_at' => now(),
+        'voided_reason' => '抄表录错,需重算',
+    ]);
+
+    // 2. 解锁 reading(把 bill_id 设 null,让它可被处理)
+    $reading->update(['bill_id' => null]);
+    // 或者:标 reading 作废,新建一条修正 reading
+    $reading->update(['voided_at' => now(), 'voided_reason' => '录错']);
+});
+```
+
+### 第 4 步:建修正 reading
+
+如果走"建新 reading"路径:
+
+```php
+$correctReading = MeterReading::create([
+    'meter_id' => $oldReading->meter_id,
+    'read_at' => $oldReading->read_at,  // 同抄表日期
+    'current_reading' => 1500,           // 改成正确值
+    'source' => MeterReadingSource::Manual,
+    'operated_by' => $currentAdmin->id,
+    'memo' => "修正:原 reading #{$oldReading->id} 数值录错(2500 → 1500)",
+]);
+```
+
+### 第 5 步:重生成 Bill
+
+走 [[bill-generation-pipeline]]:对新 reading 调 `GenerateBillsFromMeterReadingsAction`。
+
+### 第 6 步:处理已付款的差额
+
+如果旧账单已被业户付了:
+
+- **业户付现金**:物业现场退差额(¥1,200 - ¥600 = ¥600)
+- **微信付**:物业微信退款
+- **预存款抵扣**:走"反向 consume"(技术上是 `PrepaidAccount::deposit` 把钱充回 → 然后从新账单扣)
+
+### 第 7 步:通知业户
+
+完整说明:
+
+- 旧账单 ¥1,200 已作废(原因:抄表录错)
+- 新账单 ¥600
+- 差额已退还(或预存款已回填)
+
+## 未来目标态(待开发)
+
+类似 AdHocEvent 的 `VoidAction`(级联废 + 留 voided 审计):
+
+```mermaid
+sequenceDiagram
+    participant 业务
+    participant Filament
+    participant VoidBillAction[待开发]
+    participant 数据库
+
+    业务->>Filament: 找到要作废的 Bill → VoidBillAction
+    Filament->>VoidBillAction: handle(bill, reason)
+    VoidBillAction->>数据库: Bill.status=Voided + voided_reason + voided_at
+    VoidBillAction->>数据库: Reading.bill_id=null(解锁)
+    VoidBillAction->>数据库: 若已付:建红字 Receipt + 退款 / 预存款回填
+    Filament-->>业务: 完成
+
+    业务->>Filament: 建修正 MeterReading(同 read_at)
+    Filament->>数据库: 新建 reading
+    Filament->>VoidBillAction[GenerateBills]: handle(new reading)
+    数据库->>数据库: 建新 Bill(amount=正确值)
+```
+
+## 系统视角:双锁的设计意义
+
+为什么 Reading 创建后不可改(第 1 锁)+ 有 Bill 更不可改(第 2 锁)?
+
+| 反例(若允许改)| 后果 |
+|---|---|
+| 业务人员直接改 Reading 数据 | 历史 Bill 仍是旧金额,Reading 是新数据 → 不一致 |
+| 改 Reading 同时改 Bill | 已付的钱怎么办?业户付了 1200 你改成 600 → 600 凭空消失 |
+| 业户已付 + 物业改 Reading 改小金额 | 物业账面收入虚高(实际收 1200,账面记 600,差额 600 不知去向)|
+
+**双锁强制**业务人员走"作废 + 重生成"流程,**留下完整审计痕迹**(旧 Bill voided + 新 Bill 创建 + 退款 / 预存款回填记录)。
+
+## 业户视角
+
+业户**不直接接触系统层**,只感受:
+
+- 提出异议
+- 物业核实
+- 收到说明:"经核实,5 月账单 ¥1,200 是抄表录错,实际应付 ¥600。已作废原账单,新账单已发,差额 ¥600 已退到您微信"
+- 收到**红字凭证**(若已付,作废 + 退款)
+- 收到**新账单**
+
+整个流程业户感知:"物业认错 + 退钱 + 重发账单",是**正面体验**(物业承认错误并改正)。
+
+## 流水台账(完整修正过程)
+
+| 时间 | 动作 | Reading | Bill |
+|---|---|---|---|
+| 5/26 | 抄表录错 | #1(current=2500, bill_id=Bill#A) | Bill#A(amount=1200, Unpaid) |
+| 5/27 | 业户质疑 + 核实 | (不变) | (不变) |
+| 5/30 | 作废 Bill | #1.voided=true, bill_id=null | Bill#A.status=Voided, voided_reason="抄表录错" |
+| 5/30 | 建修正 reading | #2(current=1500, bill_id=null) | (无) |
+| 5/30 | 重生成 Bill | #2.bill_id=Bill#B | Bill#B(amount=600, Unpaid) |
+| 5/31 | 业户付款 | (不变) | Bill#B.status=Paid |
+
+整条修正记录可审计。
+
+## 常见问题
+
+> [!question] 如果原账单未付,作废就行,不用退款?
+> 是的。未付 → 作废 → 不开账单 → 业户没付任何钱。重生成新账单业户直接付新账单即可。
+
+> [!question] 业户已经付了,作废 Bill 之后如何退款?
+> 看付款方式:
+> - **现金 / 微信 / POS**:物业按渠道退
+> - **预存款抵扣**:`PrepaidAccount::deposit` 反向充值(技术上是建一笔 deposit 流水把钱"还"回预存款余额)→ 然后业户继续用预存款付新账单
+>
+> 当前**没自动化**,需运维 / 业务流程操作。
+
+> [!question] 已经走过红字流程的 deposit/prepaid 模块,meter 为什么没有?
+> meter 模块**直接产 Bill 不直接产 Receipt**,与 deposit/prepaid 直接产 Receipt 的模式不同。"红字 Bill" 的设计需要 Bill 模型支持(增加 `voided_at` / `voided_reason` 字段 + 业务流程),issue.md Q5 标记为"待补"。
+
+> [!question] 抄表员经常录错怎么办?
+> 系统层面:
+> - 强制拍照([[reading-source-and-photo-proof]] + [[read-with-photo-proof]])
+> - Form 上显示 previous 读数 + 异常告警(本月差与上月差比超过 X 倍 → 提示)
+>
+> 业务层面:
+> - 抄表员培训
+> - 关键抄表数据二次审核(双签)
+> - 升级集抄([[read-via-iot-remote-source]])减少人工录入
+
+> [!question] "修正 reading" 是建新 reading 还是改旧?
+> 看实现:
+> - **改旧**(直接 update)→ 简单但丢失历史(原数据没了)
+> - **建新 + 标旧 voided**(推荐)→ 复杂但完整保留审计
+>
+> 当前 issue.md 倾向"建新 + 标旧 voided"模式(类似 AdHocEvent VoidAction)。需要给 Reading 表加 `voided_at` / `voided_reason` 字段。
+
+> [!question] 长期不修复这个 gap 有什么风险?
+> - 业务人员**每次修正都要联系运维**(慢、不可扩展)
+> - 修正没有标准化流程 → 容易出错(漏退款 / 漏作废)
+> - 审计困难(运维 tinker 操作的痕迹靠日志,不像 UI 操作那么清晰)
+> - 业户体验差(响应慢)
+>
+> 业务方提需求时优先级会上来。
+
+## 相关 issue.md 待补
+
+```
+- "作废已生成 Bill 的 MeterReading"组合流程:
+  类似 AdHocEvent 的 VoidAction(级联废 + 留 voided 审计),需要单独设计。
+  等业务方明确"已收款的 Bill 应该怎么撤销"再做(可能涉及红字 Bill / 退款)
+```
+
+## 异常分支
+
+- 抄表员录错预防 → [[read-with-photo-proof|拍照存证]] + Form 守护
+- 高用量触发预警 → [[exception-high-consumption]]
+- 表故障导致错读 → [[replace-broken-meter|换表]] + 走本场景修正
+
+## 相关文档
+
+- [[decommission-and-locking]]
+- [[bill-generation-pipeline]]
+- [[exception-high-consumption]]
+- [[replace-broken-meter]]
+- [[../adhoc/cancel-amount-error-redo]](adhoc 模块的类似 void 流程参考)

prop-acc/scenarios/meter/generate-bill-min-max-cap.md

@@ -0,0 +1,273 @@
+---
+title: prop-acc · meter · 场景 - 单笔账单上下限封顶(防异常用量爆账)
+aliases:
+  - min max 封顶
+  - 账单封顶
+  - generate-bill-min-max-cap
+  - 场景-账单上下限封顶
+tags:
+  - 场景
+  - prop-acc
+  - 计量表
+  - 账单生成
+  - 异常防御
+audience:
+  - 业务人员
+  - 财务
+  - 业户
+status: 已发布
+sub_feature: meter
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 场景:单笔账单上下限封顶(防异常用量爆账)
+
+`RatePlan` 上的 `min_amount` / `max_amount` 字段为单笔账单设置**上下限**:
+
+- **`max_amount`** 防止极端用量(漏水 / 设备故障)导致离谱账单 → 业户友好,但物业承担差额
+- **`min_amount`** 防止零用量 / 极低用量逃避基础服务费 → 物业兜底,但业户可能不爽
+
+本场景演示三种触发情境。
+
+## 典型情境
+
+### 情境 1:漏水触发 max 封顶
+
+> [!example] 真实情境
+> 张阿姨家**水管漏水**(藏在墙里没发现),5 月用水 **800 吨**(平时 12 吨)。按阶梯计价:
+>
+> ```
+> 0-20 吨段:20 × 3.0 = 60
+> 21-30 吨段:10 × 4.5 = 45
+> 31-800 吨段:770 × 6.0 = 4,620
+> 算出金额:4,725 元
+> ```
+>
+> RatePlan 配置 `max_amount = 1,500`,触发封顶:
+>
+> ```
+> final_amount = min(4725, 1500) = 1500
+> ```
+>
+> 账单 ¥1,500,差额 ¥3,225 物业承担(走维修保险 / 业务减免)。
+
+### 情境 2:零用量触发 min 兜底
+
+> [!example] 真实情境
+> 王先生整月**出差不在家**,水表读数无变化(consumption=0)。按阶梯算 = 0 元。但物业配置 `min_amount = 20`,兜底:
+>
+> ```
+> final_amount = max(0, 20) = 20
+> ```
+>
+> 账单 ¥20,理由"基础服务费 / 管网维护费"。王先生抱怨"我没用水为什么收钱?",物业解释:小区水管 / 表的维护是公共成本,按户分摊。
+
+### 情境 3:正常范围,无封顶
+
+> [!example] 真实情境
+> 陈先生 5 月用水 35 吨,按阶梯算 135 元。RatePlan 配置 `min_amount=20`, `max_amount=1500`:
+>
+> ```
+> final_amount = max(20, min(135, 1500)) = 135
+> ```
+>
+> 账单 ¥135,封顶规则**不触发**(在合理范围内)。
+
+## min / max 算法
+
+```
+if (max_amount !== null && calculated > max_amount) calculated = max_amount;
+if (min_amount !== null && calculated < min_amount) calculated = min_amount;
+final_amount = calculated;
+```
+
+或等价:`final_amount = max(min_amount ?? 0, min(calculated, max_amount ?? INF))`。
+
+详见 [[multiplier-and-tiered-pricing|倍率与阶梯计价]]"第 3 层 min/max 封顶"段。
+
+## 系统流程
+
+```mermaid
+sequenceDiagram
+    participant Calc[MeterBillCalculator]
+    participant Service[MeterBillGenerationService]
+    participant DB
+
+    Calc->>Calc: 阶梯算法 → calculated_amount
+    Note over Calc: 假设漏水算出 4725
+
+    Calc->>Calc: max_amount 检查
+    alt calculated > max_amount(4725 > 1500)
+        Calc->>Calc: final = max_amount = 1500
+    else 在范围内
+        Calc->>Calc: 通过
+    end
+
+    Calc->>Calc: min_amount 检查
+    alt final < min_amount
+        Calc->>Calc: final = min_amount
+    else 在范围内
+        Calc->>Calc: 通过
+    end
+
+    Calc-->>Service: 1500
+    Service->>DB: 建 Bill(amount=1500, sourceable=reading)
+    Note over DB: 业务上是否记录"封顶减免"?目前 Bill 表无此字段,留作业务备注
+```
+
+## 业户视角
+
+### Max 封顶(漏水)
+
+业户收到的账单:
+
+```
+2026 年 5 月水费账单
+
+用水量:800 吨 ⚠️ 用量异常高
+按阶梯算应付:¥4,725.00
+封顶后实付:¥1,500.00
+差额减免:¥3,225.00(由物业 / 维修保险承担)
+
+应付:¥1,500.00
+```
+
+> [!info] 账单展示封顶信息
+> **强烈推荐**账单展示"按阶梯算 X,封顶 Y,差额 Z 由物业承担"。让业户明白封顶的存在 + 物业的友好。
+
+业户会**感激物业封顶**,但更会**自查漏水 / 设备故障**。
+
+### Min 兜底(零用量)
+
+业户收到的账单:
+
+```
+2026 年 5 月水费账单
+
+用水量:0 吨
+按阶梯算应付:¥0.00
+基础费(min):¥20.00
+
+应付:¥20.00
+```
+
+业户可能**不接受**:"我没用水为什么收钱?"。物业要解释:
+
+- 水管 / 公共部位维护成本
+- 物业服务费的"基础保障"性质(签合同时已告知)
+- 法律 / 政策依据(若有)
+
+## 业务人员视角
+
+### 配置 min / max
+
+后台 → 费率管理 → RatePlan → 编辑 → 填字段:
+
+| 字段 | 推荐值(参考)|
+|---|---|
+| `min_amount` | 10-30 元(看物业 + 费用类型)|
+| `max_amount` | 1000-5000 元(看业户类型,商铺可以更高)|
+
+> [!warning] 配置要谨慎
+>
+> **max 配低**:正常用量也被封顶 → 物业损失收入。例如 max=300,商铺正常月费 ¥500 → 物业每月被减免 ¥200。**严重 bug**。
+>
+> **max 配高**(或不配):无封顶 → 极端用量爆账户,业户投诉 + 法律风险。
+>
+> **min 配高**:业户不满 + 投诉。
+>
+> **配置后用极端值算例验证**(0 度 / 极少 / 正常 / 极高 各算一遍看是否合理)。
+
+### 触发封顶后的业务流程
+
+| 触发 | 业务人员动作 |
+|---|---|
+| max 触发(异常高用量)| 联系业户排查([[exception-high-consumption]]) → 减免数额可能要审批 |
+| min 触发(零 / 极低用量)| 通常无需介入,业户接受 min 即可 |
+| 频繁 max 触发 | 评估是否表 / 设备有问题(漏水 / 故障)|
+
+### 封顶减免的会计处理
+
+封顶差额(`max_amount` 触发时,实际应付 vs 物业承担)的会计处理:
+
+| 选项 | 实现 |
+|---|---|
+| **物业直接承担**(本系统当前简化)| Bill.amount 直接是封顶后金额。账面收入 ¥1,500(实际应是 ¥4,725)→ 物业少收 ¥3,225 |
+| **走维修保险**(高大上)| 物业向保险公司报销 ¥3,225,账面通过应收 / 已收 走完整流程 |
+| **业户与物业分摊**(罕见)| 部分协议:超过封顶部分 50% 业户 50% 物业 |
+
+当前**最简单实现**:物业直接承担。其他方案需要业务方提需求。
+
+## 财务视角
+
+### 月度报表统计封顶情况
+
+```sql
+-- 本月触发 max 封顶的 reading(假设 Bill 不存"封顶前 amount",我们用 reading 算)
+SELECT
+    r.id AS reading_id,
+    r.consumption,
+    -- 重算应付(简化,实际要走 Calculator 逻辑)
+    -- calculate(consumption, ratePlan) AS expected_amount
+    b.amount AS billed_amount,
+    -- (expected - billed) AS reduction
+    rp.max_amount
+FROM acc_meter_readings r
+JOIN acc_meters m ON r.meter_id = m.id
+JOIN fee_types ft ON m.fee_type_id = ft.id
+JOIN rate_plans rp ON ft.current_rate_plan_id = rp.id
+JOIN acc_bills b ON r.bill_id = b.id
+WHERE b.amount = rp.max_amount  -- 简化判断:Bill 金额刚好等于封顶值 = 大概率封顶触发了
+  AND b.created_at BETWEEN '2026-05-01' AND '2026-05-31';
+```
+
+业务用途:看月度物业因封顶减免多少收入。若太多 → 调整 max 或排查根因(频繁漏水 / 设备故障)。
+
+## 常见问题
+
+> [!question] min_amount 是 0 / null 时不兜底?
+> 是的。若 `min_amount=null`,系统不兜底,零用量账单 = 0 元(可能不开账单)。物业政策决定是否兜底。
+
+> [!question] max 触发后业户反悔说"我自查没漏水,你怎么算出我用 800 吨的?"
+> 业务人员排查:
+> - 看 reading 数据(读数对吗?抄表照片有吗?)
+> - 派人现场核对物理表
+> - 找漏水点(物业派维修人员)
+> - 若证实表故障 → 走 [[replace-broken-meter|换表]],并重算账单(走 [[exception-readings-locked-after-bill|修正流程]])
+>
+> 若所有证据都指向"确实用了 800 吨"(且业户家有漏水迹象)→ 业户认账,封顶后金额是优惠了。
+
+> [!question] min 触发后业户拒付怎么办?
+> 物业说服 + 法律协议层面要求(物业合同里通常有"基础服务费"条款)。坚决拒付 → 进入逾期催收。
+
+> [!question] 不同业户(住宅 vs 商铺)封顶不同可以吗?
+> 看 RatePlan 设计。当前可能"每个 FeeType 一份 RatePlan",所以同 FeeType 共用 min/max。如果要区分,可:
+>
+> - 给商铺单独建 FeeType + RatePlan
+> - 或扩展 RatePlan 支持多档 min/max(改 schema)
+
+> [!question] 跨月用量(忘了抄一个月,两个月用量算一笔)会触发 max 吗?
+> 可能会(双月用量翻倍)。**预防**:不要漏抄(走 [[audit-meters-needing-reading|审计]] 监控)。漏抄了发现:
+> - 把这笔大账单**人工拆**成两个月(系统不直接支持,业务流程做)
+> - 或当作正常账单收 + 与业户沟通
+
+> [!question] 封顶后差额怎么入账?
+> 当前最简单实现:Bill.amount 直接是封顶后金额,差额不入账(物业默默承担)。
+>
+> 严格会计:差额应记入"管理费用 / 维修保险报销 / 服务减免"科目。需扩展 schema 才能精确处理。
+
+## 异常分支
+
+- 阶梯计价(本场景叠加)→ [[generate-bill-tiered-pricing]]
+- 工业表倍率叠加 → [[generate-bill-with-multiplier]]
+- 异常高用量(可能触发 max)→ [[exception-high-consumption]]
+- 读数错误导致离谱算账 → [[exception-readings-locked-after-bill]] 修正
+
+## 相关文档
+
+- [[multiplier-and-tiered-pricing]]
+- [[bill-generation-pipeline]]
+- [[generate-bill-tiered-pricing]]
+- [[generate-bill-with-multiplier]]
+- [[exception-high-consumption]]

prop-acc/scenarios/meter/generate-bill-tiered-pricing.md

@@ -0,0 +1,246 @@
+---
+title: prop-acc · meter · 场景 - 阶梯水电价生成账单(progressive 累进)
+aliases:
+  - 阶梯计价账单
+  - tiered pricing 算例
+  - generate-bill-tiered-pricing
+  - 场景-阶梯计价生成账单
+tags:
+  - 场景
+  - prop-acc
+  - 计量表
+  - 账单生成
+audience:
+  - 业务人员
+  - 财务
+  - 业户
+status: 已发布
+sub_feature: meter
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 场景:阶梯水电价生成账单(progressive 累进)
+
+业户**用量超过低阶梯**进入更高阶梯时,系统按 **progressive 累进** 算账单(每段用量按各自单价,**不是**整月按最高阶梯)。本场景完整演示算例。
+
+## 典型情境
+
+> [!example] 真实情境
+> 张阿姨 5 月用水 35 吨(平时 12-15 吨,本月浇花 + 装修),嘉禾花园的水费阶梯如下:
+>
+> | 阶梯 | 月用水(吨)| 单价(元/吨)|
+> |---|---|---|
+> | 第一阶梯 | 0-20 | 3.0 |
+> | 第二阶梯 | 21-30 | 4.5 |
+> | 第三阶梯 | 30+ | 6.0 |
+>
+> 张阿姨 5 月用 35 吨,本月水费应是多少?
+
+**Progressive 累进算法**(本系统采用):
+
+```
+段 1(0-20 吨):20 × 3.0 = 60 元
+段 2(21-30 吨):10 × 4.5 = 45 元
+段 3(31-35 吨): 5 × 6.0 = 30 元
+合计:              135 元 ✅
+```
+
+**Full-tier 简陋实现**(错!本系统未采用):
+
+```
+35 吨 × 6.0(整月按最高阶梯) = 210 元 ❌
+```
+
+差额 ¥75。简陋实现对业户极不公平,**是市场上劣质系统的常见 bug**。本系统 `MeterBillCalculator::calculateTiered()` 实现的是 progressive,业户收到的账单准确。
+
+## 系统流程
+
+```mermaid
+sequenceDiagram
+    participant 抄表完成
+    participant Action[GenerateBillsFromMeterReadingsAction]
+    participant Service[MeterBillGenerationService]
+    participant Calc[MeterBillCalculator]
+    participant 数据库
+
+    抄表完成->>Action: handle([5月 reading,consumption=35])
+    Action->>Service: generateBillForReading(reading)
+    Service->>数据库: 查 meter.fee_type=水费 → 查 RatePlan + RateTier(3 个 tier)
+    Service->>Calc: calculate(consumption=35, ratePlan, min, max)
+    Calc->>Calc: calculateTiered(35, [tier1, tier2, tier3])
+    Note over Calc: 段 1:min(35,20)-0=20 → 20*3=60
+    Note over Calc: 段 2:min(35,30)-20=10 → 10*4.5=45
+    Note over Calc: 段 3:35-30=5 → 5*6=30
+    Note over Calc: 总和 135
+    Calc-->>Service: 135
+    Service->>Service: clamp(135, min, max) = 135
+    Service->>数据库: 建 Bill(amount=135, sourceable=reading)
+    Service->>数据库: 更新 reading.bill_id
+    Service-->>Action: ok
+```
+
+## `calculateTiered()` 算法(伪代码)
+
+```php
+function calculateTiered(float $consumption, Collection $tiers): float
+{
+    $amount = 0.0;
+    $remaining = $consumption;
+
+    foreach ($tiers as $tier) {
+        if ($remaining <= 0) break;
+
+        $tierRange = $tier->upper ? $tier->upper - $tier->lower : INF;
+        $consumedInTier = min($remaining, $tierRange);
+
+        $amount += $consumedInTier * $tier->unit_price;
+        $remaining -= $consumedInTier;
+    }
+
+    return $amount;
+}
+```
+
+详见 [[multiplier-and-tiered-pricing|倍率与阶梯计价]] 概念。
+
+## 业户视角
+
+### 您收到的账单(简化版)
+
+```
+5 月水费账单
+
+用水量:35 吨
+
+明细:
+  0-20 吨段:20 × 3.0 = 60 元
+  21-30 吨段:10 × 4.5 = 45 元
+  31+ 吨段: 5 × 6.0 = 30 元
+合计:135 元
+
+应付:¥135.00
+```
+
+> [!info] 账单明细的展示
+> 当前 Bill / Receipt 是否展示阶梯明细取决于模板设计。**强烈推荐展示**:
+>
+> - 业户能看清"为什么收 135 不是 105"
+> - 政策合规(国家阶梯水电价要求公开透明)
+> - 减少业户疑问
+
+### 用得越多越贵的教育意义
+
+阶梯计价**鼓励节约**:
+
+| 用量 | 总水费 | 平均单价 |
+|---|---|---|
+| 15 吨(低用)| 45 | 3.0 |
+| 35 吨(本场景)| 135 | 3.86 |
+| 60 吨(浪费)| 270 | 4.5 |
+
+业户**用越多平均单价越高**,符合"超额消费多付费"的政策导向。
+
+## 业务人员视角
+
+### 配置阶梯
+
+阶梯定义在 `RatePlan` + `RateTier`(不在 meter 子模块,通常运营 / 财务总监配):
+
+- 后台 → 费率管理 → 选水费 → 编辑 RatePlan
+- 加 RateTier:`tier=1, lower=0, upper=20, unit_price=3.0`
+- 加 RateTier:`tier=2, lower=20, upper=30, unit_price=4.5`
+- 加 RateTier:`tier=3, lower=30, upper=null, unit_price=6.0`(upper=null 表示无上限)
+
+> [!warning] 阶梯配置要严谨
+> 配置错的常见症状:
+> - 段不连续(`tier1 upper=20`, `tier2 lower=22`)→ 21 吨用量无法分配
+> - 段重叠(`tier1 upper=20`, `tier2 lower=18`)→ 18-20 吨段算两次
+> - 缺最高段(没有 `tier_max`)→ 超过最高阶梯的用量无单价
+>
+> 业务人员配置完后**用极端值算例**验证(0 / 1 / 20 / 21 / 30 / 31 / 100 / 1000 吨各算一遍看是否合理)。
+
+### 月度账单生成
+
+抄表完成 → 业务人员触发 `GenerateBillsFromMeterReadingsAction`(或自动)→ 系统调 `MeterBillCalculator` → 每张表算金额 → 建 Bill。
+
+### 异常处理
+
+阶梯计价的常见异常:
+
+| 异常 | 处置 |
+|---|---|
+| 业户用量极高(> 100 吨) | [[exception-high-consumption|高用量预警]] → 排查是否漏水 / 设备故障 |
+| 业户用量极低(0 吨)| `min_amount` 兜底,详见 [[generate-bill-min-max-cap]] |
+| 业户用量倒走(reading 错)| 走 [[exception-readings-locked-after-bill|修正流程]] |
+
+## 财务视角
+
+### 账面会计
+
+阶梯账单的**总金额**仍归"水费收入"科目。无需按阶梯拆分入账。
+
+阶梯只影响**业户感知**(单价不同)和**业户行为引导**(鼓励节约),不影响会计核算。
+
+### 报表统计
+
+业务可能想看"本月各阶梯段用量分布"(政策报告 / 节约成效),需要单独的报表 SQL:
+
+```sql
+-- 本月各阶梯段用量分布(简化版,真实算法更复杂)
+SELECT
+    SUM(LEAST(consumption, 20)) AS tier1_volume,
+    SUM(GREATEST(LEAST(consumption, 30) - 20, 0)) AS tier2_volume,
+    SUM(GREATEST(consumption - 30, 0)) AS tier3_volume
+FROM acc_meter_readings
+WHERE meter_id IN (SELECT id FROM acc_meters WHERE community_id=? AND fee_type_id=水费)
+  AND read_at BETWEEN '2026-05-01' AND '2026-05-31';
+```
+
+## 常见问题
+
+> [!question] 阶梯按月 / 按年?
+> 看物业政策:
+> - **按月**(常见):每月 reset,从段 1 开始算
+> - **按年**(部分地区):全年累计,跨段更慢
+>
+> 当前系统**按月**(单次抄表 = 单段计价)。按年的话需要不同算法(累加去年 12 月以来的用量,再分阶梯)。
+
+> [!question] 不同物业 / 不同社区可以有不同阶梯吗?
+> 可以。`RatePlan` 按 `community_id` + `fee_type_id` 隔离。每个社区独立配置。
+
+> [!question] 阶梯改了,历史 Bill 怎么办?
+> 历史 Bill 不变(`Bill.amount` 是当时算出的,不动态查 RatePlan)。新 Bill 按新阶梯算。
+>
+> 这是正确做法(已发账单不应因配置变化追溯改金额)。
+
+> [!question] 业户对算法有疑问怎么解释?
+> 给业户看明细(段 1 + 段 2 + 段 3)+ 阶梯单价表。绝大多数业户看懂后接受。
+
+> [!question] progressive 算法的边界用量(如 20 吨整)算哪段?
+> 看实现细节:
+> - `consumption=20`:段 1 全部(20 × 3 = 60),段 2 / 3 不进入
+> - `consumption=20.01`:段 1(20 × 3 = 60)+ 段 2(0.01 × 4.5 ≈ 0.045)
+> - 边界是 inclusive 还是 exclusive 看 RateTier 配置(`lower`/`upper` 字段语义)
+
+> [!question] 阶梯计价对工业表(multiplier > 1)的影响?
+> 倍率 + 阶梯叠加:`consumption = (current - previous) × multiplier`,然后这个 consumption 走阶梯。例如三相工业表 multiplier=10:
+>
+> - 物理表头读数差 28 度 → consumption = 280 度
+> - 280 度走阶梯计算
+>
+> 详见 [[generate-bill-with-multiplier]]。
+
+## 异常分支
+
+- 工业表倍率参与 → [[generate-bill-with-multiplier]]
+- 异常用量触发 min/max → [[generate-bill-min-max-cap]]
+- 用量异常高(漏水)→ [[exception-high-consumption]]
+
+## 相关文档
+
+- [[multiplier-and-tiered-pricing]]
+- [[bill-generation-pipeline]]
+- [[meter-vs-meter-reading]]
+- [[generate-bill-with-multiplier]]
+- [[generate-bill-min-max-cap]]

prop-acc/scenarios/meter/generate-bill-with-multiplier.md

@@ -0,0 +1,234 @@
+---
+title: prop-acc · meter · 场景 - 工业表 10x 倍率生成账单
+aliases:
+  - 工业表账单
+  - multiplier 计算
+  - generate-bill-with-multiplier
+  - 场景-倍率表生成账单
+tags:
+  - 场景
+  - prop-acc
+  - 计量表
+  - 账单生成
+  - 倍率
+audience:
+  - 业务人员
+  - 财务
+  - 抄表员
+status: 已发布
+sub_feature: meter
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 场景:工业表 10x 倍率生成账单
+
+商铺 / 集团表 / 三相工业表的物理表头**只显示用量的 1/10 或 1/100**,需要乘以倍率(multiplier)才是实际用量。系统在 `consumption = (current - previous) × multiplier` 公式中自动处理。
+
+## 典型情境
+
+> [!example] 真实情境
+> 嘉禾花园 1 楼商铺(中式餐厅)装的是**三相工业电表**(multiplier=10)。本月抄表:
+>
+> - 上月 reading.current_reading = 280
+> - 本月 reading.current_reading = 308
+> - 物理表头读数差 = 28
+>
+> **实际用电量** = 28 × **10** = **280 度**(不是 28 度!)
+>
+> 按电费阶梯(0-200 度 0.8 元,200+ 度 1.0 元)算:
+>
+> ```
+> 段 1:200 × 0.8 = 160 元
+> 段 2:80 × 1.0 = 80 元
+> 合计:        240 元
+> ```
+>
+> 商铺老板看到账单 ¥240 / 280 度。
+
+如果**没有 multiplier**:
+
+```
+consumption = (308 - 280) × 1 = 28 度
+amount = 28 × 0.8 = 22.4 元 ❌
+```
+
+少收 ¥217.6,商铺白用 252 度电。**物业必须用倍率算账,这是工业表的天然属性**。
+
+## 系统流程
+
+```mermaid
+sequenceDiagram
+    participant 抄表员
+    participant Filament
+    participant Calc[MeterBillCalculator]
+    participant 数据库
+
+    抄表员->>Filament: 录入 reading current=308(物理表头)
+    Filament->>Filament: 查 meter.multiplier=10
+    Filament->>Filament: 查 previous_reading=280(上月)
+    Filament->>Filament: consumption = (308 - 280) × 10 = 280 度
+    Filament->>数据库: 建 MeterReading(consumption=280)
+
+    Note over 数据库: 后续 GenerateBills
+
+    Filament->>Calc: calculate(consumption=280, ratePlan)
+    Calc->>Calc: 阶梯算法 200*0.8 + 80*1 = 240
+    Calc-->>Filament: 240
+    Filament->>数据库: 建 Bill(amount=240)
+```
+
+## 抄表员视角(李师傅)
+
+### 抄表录入
+
+抄表员看到物理表头是 **308**(不是 3080),录入时填 **308**。
+
+> [!warning] 抄表员不应自己乘倍率
+>
+> **错误做法**:抄表员看到 308 + 知道倍率 10 → 录入 3080
+>
+> **后果**:系统再乘一次 10 → consumption = (3080 - 2800) × 10 = 2800 度 → 收业户 2800 度电费 → 业户疯狂投诉
+>
+> **正确做法**:**严格录入物理表头数字**(308),倍率由系统自动处理。
+
+Form 上应显示 meter 的 multiplier 提醒抄表员:
+
+```
+表编号:E-COMMERCIAL-1
+倍率:10x(工业表)
+上次读数:280
+
+本次读数:[___] (请录入物理表头数字)
+```
+
+### 与家用表的对比
+
+| 维度 | 家用表(multiplier=1)| 工业表(multiplier=10/100/...)|
+|---|---|---|
+| 抄表员录入 | 表头数字 = 实际用量 | 表头数字 ≠ 实际用量 |
+| 是否需要换算 | 不需要 | 需要(系统自动)|
+| 抄表员错误风险 | 低 | **中**(可能录乘 / 不乘 10) |
+| 业务培训 | 简单 | **需培训**(说清楚"录原始数字")|
+
+## 业务人员视角
+
+### 配置倍率
+
+建表时 `MeterForm.multiplier` 字段填:
+
+| 表类型 | 推荐 multiplier |
+|---|---|
+| 家用单相电表 | 1 |
+| 家用水表 | 1 |
+| 三相工业电表 | 10(常见)|
+| 大型工业电表(高压侧) | 100 / 1000 |
+| 工业大流量水表 | 10 / 100 |
+
+具体看表的物理铭牌 + 设计图纸。
+
+### 倍率改了如何处理
+
+> [!warning] 倍率改动影响极大
+> `multiplier` 改了不会重算历史 reading 的 consumption(那些数据已经存了)。但**会影响后续抄表**。
+>
+> **何时可改 multiplier**:
+> - 表是 `is_active=true`(退役表不可改,见 [[decommission-and-locking]])
+> - 表**没有任何已生成 Bill 的 reading**(若有,改 multiplier 让历史 vs 现在的算法不一致,审计困难)
+>
+> **推荐做法**:倍率配错 → 退役旧表 → 建新表用正确 multiplier(不走更换链,因为不是物理换表)。详见 [[decommission-without-replacement]]。
+
+## 业户视角(商铺老板)
+
+### 您看到的账单
+
+```
+2026 年 5 月电费账单
+
+用电量:280 度
+   (本月表头读数 308,上月 280,差 28 × 倍率 10)
+
+明细:
+  0-200 度段:200 × 0.8 = 160 元
+  201+ 度段:  80 × 1.0 = 80 元
+合计:240 元
+```
+
+> [!info] 账单展示倍率信息
+> 强烈推荐账单 / Receipt 展示"原始读数 + 倍率 + 计算公式",让业户看明白:
+>
+> - 业户看到差 28 度,但收 240 元,会疑惑(单价怎么算?)
+> - 展示"28 × 倍率 10 = 280 度,按 280 算"业户秒懂
+
+### 商铺老板的特殊关注
+
+| 业户疑问 | 应答 |
+|---|---|
+| "为什么我家是工业表不是家用表?" | 商铺用电量大,法规要求工业表 |
+| "倍率是物业定的吗?" | 不是,是物理表的属性,出厂时定 |
+| "可以换成家用表吗?" | 不能,商铺合规上必须用工业表 |
+
+## 倍率与阶梯的叠加
+
+倍率**先算**,得到 consumption;然后 consumption 走阶梯。两者完全独立、按顺序应用。
+
+完整公式:
+
+```
+consumption = (current - previous) × multiplier      # 第 1 层
+amount = sum(段 i 用量 × 段 i 单价)                  # 第 2 层(阶梯)
+amount = clamp(amount, min, max)                     # 第 3 层(min/max 封顶)
+```
+
+详见 [[multiplier-and-tiered-pricing]] 完整说明。
+
+## 不同 multiplier 表的算例
+
+| 表类型 | multiplier | 表头读数差 | consumption | 单价 0.8 | 账单 |
+|---|---|---|---|---|---|
+| 家用 | 1 | 280 | 280 | 224 | 224 |
+| 三相工业 | 10 | 28 | 280 | 224 | 224 |
+| 大工业(高压侧) | 100 | 2.8 | 280 | 224 | 224 |
+
+**同样 280 度,账单相同**,只是物理表头数字大小不同。系统的 multiplier 字段把这层差异隐藏在算法里。
+
+## 常见问题
+
+> [!question] multiplier 必须是整数吗?
+> 不必须。decimal(10,4) 精度,支持 0.5 / 1.25 等小数。但 1.0 / 10.0 / 100.0 是市场常见的"整数倍率"。
+
+> [!question] 同一表的 multiplier 会随时间变吗?
+> 物理上**不会**。表的物理参数(变压比)是出厂时确定的,使用过程中不变。
+>
+> 系统层面**可改字段**(若 `is_active=true` 且无 Bill,Policy 允许),但**不推荐**改 —— 历史与现在的算法不一致,审计困难。
+
+> [!question] 抄表员录入时如何区分"录物理读数"vs"录乘倍率后读数"?
+> Form 上**明确显示倍率**+ 标注"请录入物理表头数字"。培训抄表员**严格遵守**。系统统一存物理表头数字。
+
+> [!question] 集抄系统推过来的数据是物理读数还是乘了倍率?
+> 看集抄运营商。**通常是物理读数**(IoT 设备读表头,不知道倍率)。本系统接收时按 `meter.multiplier` 算 consumption。
+>
+> 如果集抄推已乘倍率的数据 → 集抄端**降级处理**(本系统 multiplier 应该设为 1,避免重复乘)。需对接时讲清楚。
+
+> [!question] 配置错倍率(应该 10 配成 1)会怎样?
+> 系统按 multiplier=1 算 → consumption 缩小 10 倍 → 业户账单缩小 10 倍 → 物业损失收入(直到发现)。
+>
+> 发现后修复:
+> - 改 multiplier=10(若 Policy 允许)
+> - 修复历史已欠收(走"补开账单"业务流程,系统不直接支持)
+> - 通知业户 + 退还 / 补收差额
+
+## 异常分支
+
+- 阶梯计价(本场景叠加)→ [[generate-bill-tiered-pricing]]
+- min/max 封顶 → [[generate-bill-min-max-cap]]
+- 倍率配错想改 → 复杂,通常退役旧表新建([[decommission-and-locking]])
+- 抄表员录错乘倍率 → [[exception-readings-locked-after-bill]] 修正
+
+## 相关文档
+
+- [[multiplier-and-tiered-pricing]]
+- [[bill-generation-pipeline]]
+- [[meter-vs-meter-reading]]
+- [[generate-bill-tiered-pricing]]
+- [[generate-bill-min-max-cap]]

prop-acc/scenarios/meter/init-new-community-batch.md

@@ -0,0 +1,185 @@
+---
+title: prop-acc · meter · 场景 - 新社区批量建表 + 初始读数 Excel 导入
+aliases:
+  - 批量建表
+  - 新社区计量表初始化
+  - init-new-community-batch
+  - 场景-新社区批量建表
+tags:
+  - 场景
+  - prop-acc
+  - 计量表
+  - 表管理
+  - 批量导入
+audience:
+  - 业务人员
+  - 抄表员
+status: 已发布
+sub_feature: meter
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 场景:新社区批量建表 + 初始读数 Excel 导入
+
+物业**新接管社区**(或老社区从 0 接入本系统),需要**批量建表 + 录初始读数**。通过 `MeterInitializationImporter` + `ImportActionWithExcel` 一次性导入。
+
+## 典型情境
+
+> [!example] 真实情境
+> 平台新签了"嘉禾花园"社区,本月底接管。该社区有 300 户业主 + 公共部位 + 商铺,合计约 1,200 张表(每户水电气 3 张 + 公共部位 + 商铺各类)。
+>
+> 物业财务王主管不可能手工建 1,200 张表,**走批量导入**:
+>
+> 1. 抄表员李师傅 + 物业前任团队 出 Excel 表(包含每张表的房号、表号、初始读数)
+> 2. 王主管在系统下载"建表初始化模板"
+> 3. 把数据填入模板 → 上传 → 系统批量建表
+
+## 业务人员视角
+
+### 第 1 步:下载初始化模板
+
+后台 → 计量表 → 列表 → 顶部 **"下载初始化模板"** 按钮(`ExportMeterInitializationTemplateAction`)。
+
+下载到的 Excel 包含:
+
+| 列 | 说明 | 示例 |
+|---|---|---|
+| 房号 / 资产编号 | 关联 asset(必填,系统按房号查 asset_id) | 12-3-501 |
+| 费用类型 | 水费 / 电费 / 燃气费(必填) | 电费 |
+| 表编号 | 物理表牌号(必填) | E-501 |
+| 倍率 | multiplier(可选,默认 1)| 1 |
+| 初始读数 | initial_reading(必填,首次接管时表上的读数)| 0 / 8523 / etc. |
+| 安装日期 | installed_at(可选,默认导入日)| 2026-05-26 |
+| 备注 | (可选) | "新装" |
+
+模板列名清晰,业务人员 / 抄表员看得懂。
+
+> [!warning] 模板列含义"双义"问题(已知 issue)
+> 当前 `MeterInitializationImporter` 用**一个 Importer 处理两种 Excel layout**(住宅单元 vs 商铺/公共)。某些列 label 是"双义"形式,导入选项里选错 `asset_type` 不报错,只是数据写到错误字段(silent corruption)。issue.md Q5 已记录,待拆成两个独立 Importer。**当前预防**:务必仔细选 asset_type。
+
+### 第 2 步:填写数据
+
+物业 / 抄表员把 1,200 张表的信息填入模板。
+
+关键字段对齐:
+
+- 房号:对应系统里 asset 表已存在的编号(若不存在,先到 community 模块建 asset)
+- 费用类型:对应系统配置的 FeeType(水/电/燃气,各社区独立配置)
+- 表编号:物业自编(常见 `<费用类型简写>-<房号>` 模式)
+- 初始读数:**接管当天**的物理表读数(关键!首次接管之前的用量物业不管)
+
+### 第 3 步:上传 + 导入
+
+后台 → 计量表 → 列表 → 顶部 **"导入初始化"** 按钮(`ImportActionWithExcel` + `MeterInitializationImporter`)→ 选 asset_type(住宅 / 商铺)→ 上传 Excel → 提交。
+
+系统:
+
+1. **解析 Excel**(走 `BaseImporter` + `ImportActionWithExcel`,支持 .xlsx / .xls / .csv)
+2. **每行校验**(房号 asset 存在?费用类型存在?表编号是否在该社区重复?)
+3. **批量建 Meter**(每行一张 Meter 记录)
+4. **可选:同时建第一条 MeterReading**(若模板含"初始读数",建初始 reading 来锁定 `previous_reading` 起点)
+5. **报告**:成功 N 张,失败 M 张 + 每条失败的原因
+
+> [!info] BaseImporter + chunk rollback
+> 走 `App\Filament\Importers\BaseImporter`(host 基类,详见 saas-baseline 规范)+ `TransactionalImportCsv` job。一批 100 行任意一行失败 → 该批全回滚。
+>
+> 这避免"部分建好部分没建"的脏中间态。失败的批可下载"失败行" Excel,修复后再导入。
+
+### 第 4 步:核对
+
+导入后:
+
+- 后台 → 计量表 → 按社区过滤 → 看是否 1,200 张表都在
+- 抽样核对:打开几张表看初始读数对不对
+
+### 第 5 步:启动月度抄表
+
+接管下一个月 → 抄表员去现场抄读数(走 [[read-batch-via-excel-import]] 或 [[read-single-meter-manual]])→ 系统按 `current - initial × multiplier` 算用量 → 生成第一份账单(走 [[bill-generation-pipeline]])。
+
+## 系统流程
+
+```mermaid
+sequenceDiagram
+    participant 王主管
+    participant Filament
+    participant ImportActionWithExcel
+    participant MeterInitializationImporter
+    participant 数据库
+
+    Note over 王主管: 已填好 1200 行 Excel
+
+    王主管->>Filament: ListMeters → 导入初始化 → 选 asset_type + 上传
+    Filament->>ImportActionWithExcel: parse .xlsx
+    ImportActionWithExcel->>MeterInitializationImporter: 按 chunk 处理(100 行/批)
+
+    loop 每批
+      MeterInitializationImporter->>数据库: 开启事务
+      loop 每行
+        MeterInitializationImporter->>数据库: 校验 asset / fee_type / code 唯一
+        alt 校验通过
+          MeterInitializationImporter->>数据库: 建 Meter + 可选 initial MeterReading
+        else 校验失败
+          MeterInitializationImporter->>MeterInitializationImporter: 收集失败行
+        end
+      end
+      alt 全成功
+        MeterInitializationImporter->>数据库: 提交
+      else 任一失败
+        MeterInitializationImporter->>数据库: 回滚整批
+      end
+    end
+
+    MeterInitializationImporter-->>Filament: 报告 "成功 1198,失败 2"
+    Filament-->>王主管: 通知 + 下载失败行 Excel
+```
+
+## 业户视角
+
+业户**不感知**这一步。新接管社区会发个公告"本月起本物业系统升级,各位业户的水电气计量将从 X 月 X 日起按本系统记账"。具体业户看到的:
+
+- 接管前最后一份账单(由前任物业 / 自建系统出)
+- 接管后第一份账单(由本系统出,用量从接管那天起算)
+
+中间**绝不能有"重复账单"或"漏账"** —— 接管时的 `initial_reading` 必须准确反映物理表当时读数。
+
+## 常见问题
+
+> [!question] 为什么需要"初始读数"?
+> 系统计算用量公式是 `(current - previous) × multiplier`。新表的"上一次读数"在系统里没有,所以接管时存的 `initial_reading` 就是"`previous_reading` 的起点"。后续每月抄表 → 当前 - 上次 = 用量。
+>
+> 如果不填初始读数 → 第一次抄表算用量会爆炸(`current - 0 = 所有历史用量`),业户被收一笔巨账,投诉。
+
+> [!question] 导入失败的常见原因?
+> - **房号(asset)不存在**:在 community 模块的 asset 还没建好。先建 asset 再导入表
+> - **费用类型不存在**:RatePlan 没配置。先到 FeeType 配置
+> - **表编号在该社区重复**(社区内 code 应唯一,虽然 issue.md Q5 提到目前是 nullable + 非 unique 的"待治理"状态)
+> - **倍率格式错**(非数字 / 负数)
+> - **初始读数格式错**(非数字 / 负数)
+
+> [!question] 失败的行可以单独处理吗?
+> 可以。导入完成后系统提供"下载失败行"Excel(走 host 的 `TransactionalImportCsv` 机制),业务人员修复后单独导入失败行。已成功的不影响。
+
+> [!question] 同一社区多次导入会重复建表吗?
+> 视 Importer 实现。若有 unique 校验(asset_id + fee_type_id 不可重复)→ 重复行会失败,需手工合并。若无校验 → 重复建,**灾难**。
+
+> [!question] 老社区已经有一年的抄表历史,接管时怎么办?
+> 简化做法:**只导入接管那天的状态**(initial_reading = 接管那天的物理读数),历史数据**不进系统**(在 Excel 备查)。
+>
+> 复杂做法:**导入历史 reading 数据**,让本系统有完整历史。需要业务方决定(用户对账复杂度 vs 系统数据完整度的权衡)。
+
+> [!question] 商铺表 / 公共部位表怎么导入?
+> 同样走 `MeterInitializationImporter`,但**选不同 asset_type**(public / shop)。导入时系统按 asset_type 决定列含义。详见 issue.md Q5"双义列名"问题。
+
+## 异常分支
+
+- 单张新表(后续装机 / 个别加表)→ [[register-single-meter]]
+- 老表换新表 → [[replace-broken-meter]]
+- 抄表(初始化后日常)→ [[read-batch-via-excel-import]] / [[read-single-meter-manual]]
+
+## 相关文档
+
+- [[meter-vs-meter-reading]]
+- [[register-single-meter]]
+- [[read-batch-via-excel-import]]
+- [[bill-generation-pipeline]]

prop-acc/scenarios/meter/read-batch-via-excel-import.md

@@ -0,0 +1,228 @@
+---
+title: prop-acc · meter · 场景 - 一次导入整月所有读数(Excel 批量)
+aliases:
+  - 批量抄表
+  - Excel 导入抄表
+  - read-batch-via-excel-import
+  - MeterReadingsImporter
+  - 场景-Excel 批量抄表
+tags:
+  - 场景
+  - prop-acc
+  - 计量表
+  - 抄表
+  - 批量导入
+audience:
+  - 业务人员
+  - 抄表员
+status: 已发布
+sub_feature: meter
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 场景:一次导入整月所有读数(Excel 批量)
+
+中型物业(几百到上千张表)、未上集抄系统的,抄表员**月底一次性**把全社区抄表数据填入 Excel,业务人员**上传导入**。
+
+## 典型情境
+
+> [!example] 真实情境
+> 嘉禾花园 300 户 + 公共部位 + 商铺,合计 1,200 张表(水电气混)。未上集抄。抄表员李师傅 + 团队**每月最后一周**集中抄表 5-7 天,完成后:
+>
+> 1. 整理 Excel(1,200 行,每行一张表的本月读数)
+> 2. 王主管下载"抄表读数模板"
+> 3. 抄表数据填入模板对应列
+> 4. 上传导入
+
+## 业务人员视角
+
+### 第 1 步:下载抄表模板
+
+后台 → 计量表 → 列表 → 顶部 **"下载抄表模板"** 按钮(`ExportMeterReadingsAction`,**注意**:命名误导,实际是下载模板)。
+
+> [!info] 命名问题(issue.md Q5)
+> `ExportMeterReadingsAction` 的名字让人以为是"导出读数"(把数据从系统导出来),实际是**"下载抄表模板"**(给抄表员填的空模板,预填上次读数)。issue.md Q5 待补:重命名为 `DownloadMeterReadingsTemplateAction`。
+
+下载的 Excel 包含:
+
+| 列 | 说明 | 预填 |
+|---|---|---|
+| 房号 | asset 编号 | ✅ 系统填(对应每张已建表) |
+| 表编号 | meter code | ✅ 系统填 |
+| 费用类型 | 水/电/燃气 | ✅ 系统填 |
+| 上次读数 | 上月该表 reading | ✅ 系统填(供抄表员对比)|
+| **本次读数** | 本月该表 reading | **❌ 空,抄表员填**|
+| 抄表日期 | 本次 read_at | **❌ 空,抄表员填**(或默认月底)|
+| 备注 | 选填 | ❌ |
+
+预填上次读数让抄表员**对比时有参考**(本次 > 上次 才合理),也防止漏填行(看清楚每行该填什么)。
+
+### 第 2 步:抄表员填本月数据
+
+抄表员李师傅团队**整月**(或月末几天)做这事:
+
+- 现场抄表 + 拍照(用 App / 纸质本)
+- 数据填入模板
+- 完成后交回王主管
+
+### 第 3 步:上传导入
+
+后台 → 计量表 → 列表 → 顶部 **"导入抄表数据"** 按钮(`ImportActionWithExcel` + `MeterReadingsImporter`)→ 选 asset_type → 上传 → 提交。
+
+系统:
+
+1. 解析 Excel(走 `BaseImporter`)
+2. 每行校验(meter 存在?asset 匹配?读数合法?)
+3. 批量建 MeterReading(每行一条,`source=manual`,`operated_by=导入操作员`,无 photo_url —— 走批量没拍照)
+4. 算 consumption
+5. 报告:成功 N 条,失败 M 条
+
+> [!warning] 批量导入无 photo_url
+> Excel 模板没法批量上传照片。批量导入的 reading **photo_url 为空**。
+>
+> 业务上推荐:**抄表员独立留照片**(手机相册按月归档),业户事后争议时翻照片(虽然不在系统里)。或者:
+> - 高争议表(住宅)走 [[read-single-meter-manual|单录 + 拍照]]
+> - 低争议表(商铺 / 公共)走批量导入(节省时间)
+
+### 第 4 步:核对
+
+导入后:
+
+- `MetersNeedingReadingListWidget` 显示"本月未抄表"清单 → 此时应 0 条(或个别遗漏)
+- 抽样验证几张表的 reading 数据正确
+- `HighConsumptionReadingsListWidget` 看是否有异常用量
+
+### 第 5 步:触发账单生成
+
+导入完成后:
+
+- **自动触发**(`MeterReadingsImporter` 完成后默认调 `GenerateBillsFromMeterReadingsAction`)
+- 或**手动触发**(`ListMeters` 上的"生成账单"按钮,选刚导入的 readings)
+
+详见 [[bill-generation-pipeline]]。
+
+## 系统流程
+
+```mermaid
+sequenceDiagram
+    participant 李师傅
+    participant 王主管
+    participant Filament
+    participant MeterReadingsImporter
+    participant GenerateBills[GenerateBillsFromMeterReadingsAction]
+    participant 数据库
+
+    王主管->>Filament: 下载抄表模板(预填上次读数)
+    Filament-->>王主管: 模板.xlsx
+    王主管->>李师傅: 转发模板
+    李师傅->>李师傅: 现场抄表 + 填模板
+    李师傅->>王主管: 已填模板.xlsx
+
+    王主管->>Filament: 导入抄表数据 → 选 asset_type + 上传
+    Filament->>MeterReadingsImporter: parse + chunk 处理(100/批)
+
+    loop 每批
+      MeterReadingsImporter->>数据库: 开启事务
+      loop 每行
+        MeterReadingsImporter->>数据库: 校验 meter + asset
+        alt 通过
+          MeterReadingsImporter->>数据库: 建 MeterReading
+        else 失败
+          MeterReadingsImporter->>MeterReadingsImporter: 记失败行
+        end
+      end
+      alt 全成功
+        MeterReadingsImporter->>数据库: 提交
+      else 任一失败
+        MeterReadingsImporter->>数据库: 回滚整批
+      end
+    end
+
+    MeterReadingsImporter->>GenerateBills: handle(刚建的 readings)
+    GenerateBills->>数据库: 批量建 Bill + 回写 reading.bill_id
+
+    MeterReadingsImporter-->>Filament: 报告
+    Filament-->>王主管: 通知 + 失败行下载
+```
+
+## 抄表员视角(李师傅)
+
+整月抄表流程:
+
+1. **第 1-5 周(月初)**:正常工作 + 部分非紧急表抄(若有时间)
+2. **第 25-30 日(月末)**:集中抄表
+   - 按楼栋 + 单元顺序(避免漏)
+   - 每户:开门(若有人)/ 看公共表(若装在外)
+   - 读表 → 拍照 → 填模板
+3. **30 日 / 月底**:整理完整 Excel → 交回王主管
+
+工作量:1,200 张表 / 月 / 1 抄表员 → 约 40 张 / 天 / 5 天工作。比单录(后台一张张点)快 3-5 倍。
+
+## 业户视角
+
+业户**无感知** —— 抄表员上门时业户可能在家也可能不在(公共表 / 燃气表通常装在楼道,不用进户)。
+
+## `MeterReadingsImporter` 双义列名问题(issue.md Q5)
+
+> [!warning] 已知 silent corruption 风险
+> 当前 `MeterReadingsImporter` 用**一个 Importer 处理两种 Excel layout**(住宅单元 vs 商铺/公共),列 label 是"双义"形式(如 `'层编号/费用类型'`),靠 `$this->options['asset_type']` 决定列含义。
+>
+> **风险**:导入时用户选错 `asset_type`:
+> - 系统不报错(列存在,数据有值,看着像合法)
+> - 但数据写到**错误字段**(silent corruption)
+> - 业务人员事后核对才发现数据错位
+>
+> **修复**(issue.md Q5 待补):拆成 `MeterReadingsImporterForUnit` + `MeterReadingsImporterForShop`,每个列含义固定。
+>
+> **当前预防**:导入时**务必仔细确认** asset_type 选项 + 抽样核对前几行数据。
+
+## 常见问题
+
+> [!question] 导入失败的常见原因?
+> - meter 不存在(asset 或 code 找不到对应表)
+> - meter 已退役(`is_active=false`)
+> - 读数倒走(本次 < 上次)
+> - 读数格式错(非数字 / 含中文)
+> - asset_type 选错(silent corruption,不报错但数据错)
+
+> [!question] 已导入想撤销?
+> Reading 不可改 / 不可删(若已生成 Bill 更严)。撤销 = 走 [[exception-readings-locked-after-bill]] 流程,复杂。
+>
+> **预防**:导入前抽样核对 Excel + 选对 asset_type + 小批量先试。
+
+> [!question] 同一张表本月被重复导入(填了两次 Excel)?
+> 看 `MeterReadingsImporter` 是否有"同 meter + 同 read_at 不允许"的守护。如果没有 → 系统建两条 reading → 两条都算用量 → 业户被算两遍。**严重 bug**,需要业务人员核对避免重复导入。
+
+> [!question] 部分表本月没抄怎么办?
+> `MetersNeedingReadingListWidget` 会显示"本月未抄"清单。业务人员可:
+> - 让抄表员补抄(走 [[read-single-meter-manual|单录]])
+> - 让业户自报读数(部分物业接受,但需核对)
+> - 跳过本月(下月一起算,业户账单可能突然变高)
+
+> [!question] 商铺 / 公共表与住宅表能合并导入吗?
+> 看 Excel 模板设计。当前**asset_type 是必选项**,即一次导入只能处理一种类型。要分两次导入(住宅一次,商铺一次,公共一次)。
+
+> [!question] 导入完成后立即生成账单还是等月底?
+> 取决于业务流程:
+> - **导入即生成**:`MeterReadingsImporter` 完成后自动调 GenerateBills(默认推荐)
+> - **手动触发**:业务人员后续审核 reading 后再触发生成
+>
+> 当前实现应是"自动生成"模式(看 Importer 配置)。
+
+## 异常分支
+
+- 单张表录入 → [[read-single-meter-manual]]
+- 集抄自动 → [[read-via-iot-remote-source]]
+- 已导入发现错 → [[exception-readings-locked-after-bill]]
+- 高用量异常 → [[exception-high-consumption]]
+- 抄表完成率审计 → [[audit-meters-needing-reading]]
+
+## 相关文档
+
+- [[meter-vs-meter-reading]]
+- [[reading-source-and-photo-proof]]
+- [[bill-generation-pipeline]]
+- [[read-single-meter-manual]]
+- [[read-via-iot-remote-source]]
+- [[init-new-community-batch]]

prop-acc/scenarios/meter/read-single-meter-manual.md

@@ -0,0 +1,170 @@
+---
+title: prop-acc · meter · 场景 - 单张表后台手动录入
+aliases:
+  - 手动抄表单录
+  - 单张表录入
+  - read-single-meter-manual
+  - 场景-单张表手动抄表
+tags:
+  - 场景
+  - prop-acc
+  - 计量表
+  - 抄表
+audience:
+  - 业务人员
+  - 抄表员
+status: 已发布
+sub_feature: meter
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 场景:单张表后台手动录入
+
+抄表员**单张表**录入读数。最基础的抄表方式 —— 适合小规模物业 / 个别补抄 / 集抄掉线的兜底。
+
+## 典型情境
+
+> [!example] 真实情境
+> 嘉禾花园抄表员李师傅本月集抄系统**有 5 户掉线**(IoT 表故障 / 信号不好)。这 5 户他亲自上门读表,然后回办公室后台单条录入。
+>
+> 本场景:其中一户(张阿姨 12-3-501 的电表 E-501,本月读数 5,280)。
+
+## 抄表员视角
+
+### 第 1 步:现场读表
+
+到张阿姨家:
+
+1. 找到电表(通常装在玄关 / 门外配电箱)
+2. **看清表头数字**:5280
+3. **拍照存证**(`photo_url`,见 [[reading-source-and-photo-proof]] + [[read-with-photo-proof]])
+4. 记录(写在抄表本子上或手机备忘)
+
+### 第 2 步:回办公室录入
+
+打开手机 App / 浏览器后台 → 计量表 → 找 E-501 → 进 `ViewMeter` → 滚动到下方"抄表读数"(`MeterReadingsRelationManager`)→ 点 **"新增"** 按钮。
+
+> 替代路径:抄表员手机 App 直接现场录入,无需回办公室。当前若有此 App 走集成接口,无此 App 走后台。
+
+### 第 3 步:填表单
+
+| 字段 | 填什么 |
+|---|---|
+| **抄表日期(`read_at`)** | 2026-05-26(默认今天)|
+| **当前读数(`current_reading`)** | 5280(物理表头数字)|
+| **来源(`source`)** | `manual`(默认)|
+| **拍照(`photo_url`)** | 上传现场照片(若有要求)|
+| **操作员(`operated_by`)** | 自动填李师傅(当前登录用户)|
+| **备注(`memo`)** | 选填,如 "集抄掉线手动补抄" |
+
+> [!info] previous_reading 不用填
+> 系统自动从该 meter 最近一条 reading 取(或从 `Meter.initial_reading` 取)作为 previous,自动算 `consumption = (current - previous) × multiplier`。
+>
+> 例:上次抄表 5050 → previous=5050 → consumption = (5280 - 5050) × 1 = 230 度
+
+### 第 4 步:提交
+
+系统:
+
+1. 校验 `meter.is_active=true`(退役表不能抄,详见 [[decommission-and-locking]])
+2. 校验 `current_reading >= previous_reading`(若有此守护;否则即"读数倒走"异常,见 [[exception-high-consumption]] 相关)
+3. 算 consumption
+4. 建 MeterReading(`bill_id=null`,即未生成账单)
+5. (可选)若配置了"抄表即生成账单",自动调 `GenerateBillsFromMeterReadingsAction`(详见 [[bill-generation-pipeline]])
+
+提交后跳回 `ViewMeter`,新 reading 显示在列表第一条。
+
+## 业务人员视角
+
+业务人员**通常不直接抄表**,但会做:
+
+- **审核**抄表员录入的数据(看高用量异常,见 [[exception-high-consumption]])
+- **生成账单**(批量,月底统一,走 `GenerateBillsFromMeterReadingsAction`)
+- **核对**抄表完成率(`MetersNeedingReadingListWidget`)
+
+## 系统流程
+
+```mermaid
+sequenceDiagram
+    participant 李师傅[抄表员]
+    participant Filament
+    participant MeterReadingsRelationManager
+    participant 数据库
+
+    Note over 李师傅: 现场读表 5280
+
+    李师傅->>Filament: ViewMeter(E-501) → 新增 reading
+    Filament->>MeterReadingsRelationManager: 渲染 form
+    李师傅->>MeterReadingsRelationManager: 填 current=5280 + 上传照片 + 提交
+    MeterReadingsRelationManager->>数据库: 校验 meter.is_active=true
+    MeterReadingsRelationManager->>数据库: 查 previous_reading(上次 5050)
+    MeterReadingsRelationManager->>数据库: 算 consumption=(5280-5050)*1=230
+    MeterReadingsRelationManager->>数据库: 建 MeterReading(source=manual, operated_by=李师傅, photo_url, bill_id=null)
+    Filament-->>李师傅: 显示新 reading 230 度
+```
+
+## 业户视角
+
+业户**无感知** —— 张阿姨可能根本不知道李师傅上门读了表。
+
+下个月物业账单出来,显示"5 月电费:用电 230 度,¥XXX",业户看明白即可。如果有异议 → 物业拿出 `photo_url` 照片证明。
+
+## 何时用本场景
+
+| 场景 | 用本场景? |
+|---|---|
+| 集抄系统正常运行 | ❌ 走 [[read-via-iot-remote-source]] |
+| 集抄系统某户掉线 | ✅ 个别补抄 |
+| 小规模物业未上集抄(全靠人工)| ✅ 但建议升级到 [[read-batch-via-excel-import]](效率高)|
+| 抄表数据需要事后修正 | ❌ Reading 不可改,见 [[exception-readings-locked-after-bill]] |
+| 业户家暂时无人,无法抄 | 抄表员标"未抄",月底再补 |
+
+## 常见问题
+
+> [!question] 读数倒走(current < previous)怎么办?
+> 看 Form 是否有守护。若**允许提交**:系统建 reading,consumption 是负数 → 后续生成 Bill 时 Calculator 可能抛错 / 给 0 / 给 min_amount。
+>
+> **业务上**读数倒走通常意味着:
+> - 表故障(乱跳)→ 走 [[replace-broken-meter|换表]]
+> - 抄表录错(可能是本月录上月数 / 笔误)→ 立即改(若没生成 Bill 可改;若有 Bill 见 [[exception-readings-locked-after-bill]])
+> - 业户偷电 / 物理改表 → 严重事件,法务介入
+
+> [!question] 读完一户表才发现没拍照怎么办?
+> 看物业政策严格度:
+> - **必须拍照**:回去补拍 → 上传(理论上事后照片也是凭据,但不如当场)
+> - **建议拍照**:本次录入时备注"未拍照" → 业户事后无异议则 OK
+>
+> 长期不拍照 = 业户争议时无凭证 = 物业被动。
+
+> [!question] 抄表日期填错了能改吗?
+> Reading 不可改([[decommission-and-locking]] 第 2 锁)。若 `read_at` 填错且**没生成 Bill** → 见 Policy 是否允许删 + 重建。若**已生成 Bill** → 复杂,走作废 Bill 流程([[exception-readings-locked-after-bill]])。
+>
+> **预防**:Form 默认带入今天日期,改之前确认。
+
+> [!question] 一次录多张表(几十户)用单录效率太低?
+> 是的。**走 [[read-batch-via-excel-import]] 批量导入**或 [[read-via-iot-remote-source]] IoT 自动。本场景适合 1-10 张表的个别情况。
+
+> [!question] 录入后立即生成 Bill 吗?
+> 看配置:
+> - **抄表即生成 Bill**:Form 提交后自动调 `GenerateBillsFromMeterReadingsAction`(每条 reading 立即变 Bill)
+> - **月底批量生成 Bill**:Form 提交后只建 reading,月底业务人员统一触发批量生成
+>
+> 当前实现看具体 Filament 配置,两种都支持。
+
+## 异常分支
+
+- 批量录入 → [[read-batch-via-excel-import]]
+- 集抄自动 → [[read-via-iot-remote-source]]
+- 拍照存证 → [[read-with-photo-proof]]
+- 读完发现是错的 → 立即改(无 Bill)/ [[exception-readings-locked-after-bill]](有 Bill)
+- 异常用量 → [[exception-high-consumption]]
+
+## 相关文档
+
+- [[meter-vs-meter-reading]]
+- [[reading-source-and-photo-proof]]
+- [[bill-generation-pipeline]]
+- [[read-batch-via-excel-import]]
+- [[read-via-iot-remote-source]]
+- [[exception-high-consumption]]

prop-acc/scenarios/meter/read-via-iot-remote-source.md

@@ -0,0 +1,246 @@
+---
+title: prop-acc · meter · 场景 - 集抄系统自动推送(source=remote)
+aliases:
+  - 集抄系统
+  - IoT 抄表
+  - read-via-iot-remote-source
+  - 场景-集抄自动抄表
+tags:
+  - 场景
+  - prop-acc
+  - 计量表
+  - 抄表
+  - IoT
+audience:
+  - 业务人员
+  - 架构师
+  - 抄表员
+status: 已发布
+sub_feature: meter
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 场景:集抄系统自动推送(source=remote)
+
+集抄系统(IoT)通过 RS485 / NB-IoT / LoRa 等技术**远程读取**物理表读数,定时(每天 / 每小时 / 每月)推送给本系统。本系统收到后建 `MeterReading(source=remote)`,**完全自动,无人工介入**。是现代化物业的标配。
+
+## 典型情境
+
+> [!example] 真实情境
+> 嘉禾花园 2 年前升级了集抄系统,1,200 张水电气表全部接入 IoT 网关。集抄运营商每月 1 日凌晨**统一上传上月用量数据**到本系统。
+>
+> 物业财务王主管早上来上班,集抄数据已经全部到位 + 账单已经自动生成。她只需要:
+> - 看 dashboard 异常告警(高用量 / 集抄掉线表)
+> - 手工处理少数异常情况
+
+## 系统流程
+
+```mermaid
+sequenceDiagram
+    participant Meter[物理表]
+    participant Gateway[IoT 网关]
+    participant Vendor[集抄运营商平台]
+    participant API[本系统集抄 API]
+    participant 数据库
+    participant GenerateBills
+
+    Note over Meter: 物理表每月 1 日凌晨自报
+
+    Meter->>Gateway: 读数推送(RS485 / NB-IoT)
+    Gateway->>Vendor: 上传(GSM / 4G / 有线)
+    Vendor->>Vendor: 整合 + 校验 + 归档
+
+    Note over Vendor: 月度批量推送(可能是每天 / 每月)
+
+    Vendor->>API: HTTP POST(批量推 readings)
+    API->>API: 校验签名 + 防重放
+    API->>API: 校验 meter 是否存在 + 是否 active
+
+    loop 每条 reading
+      API->>数据库: 建 MeterReading(source=remote, operated_by=null, photo_url=null)
+    end
+
+    API->>GenerateBills: handle(刚建的 readings)
+    GenerateBills->>数据库: 批量建 Bill + 回写 reading.bill_id
+
+    API-->>Vendor: 响应(成功 N,失败 M)
+```
+
+## 业务人员视角
+
+### 日常(集抄正常运行)
+
+业务人员**几乎不操作**:
+
+- 看 `MeterDashboard`(自动跳出异常告警)
+- 月度对账(`audit-meters-needing-reading.md` 类似审计)
+- 不需要手动抄表 / 录入
+
+### 月初(集抄推数完成后)
+
+通常上午到岗时:
+
+- 所有 reading 已经在 `MeterReading` 表里
+- 所有 Bill 已经生成
+- Dashboard 显示:本月已抄 N 张 / 应抄 M 张
+- 看 `HighConsumptionReadingsListWidget` 异常告警 → 处理([[exception-high-consumption]])
+- 看 `MetersNeedingReadingListWidget` 显示掉线 / 漏抄表(本场景的兜底:走 [[read-single-meter-manual]] 个别补抄)
+
+### 异常(集抄掉线)
+
+| 掉线规模 | 处置 |
+|---|---|
+| 个别表(< 5%)| 抄表员补抄([[read-single-meter-manual]])|
+| 大面积(网关故障)| 联系集抄运营商修复 + 物业短期手抄兜底 |
+| 长期掉线(> 2 周)| 重新评估集抄设备的可靠性 |
+
+## 集抄 API 设计(待文档化 / 实现细节)
+
+> [!info] 当前实施状态
+> 集抄 API 的**具体实现细节**(endpoint、签名、数据格式、防重放)需要看代码或与集抄运营商对接文档,本场景描述**业务流程层**。
+
+### 接口要求
+
+| 要求 | 说明 |
+|---|---|
+| 接收端 | 本系统提供 HTTP POST endpoint |
+| 数据格式 | JSON 数组,每条 reading 字段:meter_code / read_at / current_reading / community_id / vendor_signature |
+| 签名校验 | 防伪造,通常 HMAC-SHA256 或非对称签名 |
+| 防重放 | 同 meter + 同 read_at 不重复建(unique index)|
+| 错误响应 | 详细告知哪条失败、原因 |
+| 失败重试 | 集抄运营商按响应决定重试逻辑 |
+
+### MeterReading 字段对照
+
+集抄推送的 reading,数据库存的 MeterReading:
+
+| 字段 | 集抄数据 | 系统存 |
+|---|---|---|
+| `meter_id` | 集抄推 meter_code → 系统查 | meter ID |
+| `read_at` | 集抄推时间(通常表自身上报) | datetime |
+| `current_reading` | 物理表读数 | decimal(12,2) |
+| `previous_reading` | (系统自动取上次)| decimal |
+| `consumption` | (系统自动算)| decimal |
+| **`source`** | (系统设)| **`remote`** |
+| `operated_by` | null(集抄无人)| null |
+| `photo_url` | null(集抄无照片)| null |
+| `bill_id` | null(初始)→ 后续 GenerateBills 回写 | 可空 |
+| `memo` | 选填(集抄可能写型号 / 网关 ID)| text |
+
+## 集抄 vs 手抄 数据差异
+
+| 维度 | manual(手抄) | **remote(集抄)** |
+|---|---|---|
+| 录入速度 | 慢(几天到几周)| **几小时全社区** |
+| 准确性 | 中(手抖 / 看错)| **高**(机器直读)|
+| 拍照存证 | 强烈推荐 | 无(IoT 设备自身就是凭证)|
+| operated_by | 抄表员 ID | null |
+| 业户感知 | 抄表员上门 | **无感**(无人上门)|
+| 异常处理 | 抄表员现场判断 | 系统后台告警 → 人工介入 |
+| 成本 | 抄表员工资 | IoT 设备 + 网关 + 月度服务费 |
+| 业户家在不在影响 | 影响(开门才能抄) | 无影响 |
+
+## 业户视角
+
+业户**完全无感** —— 集抄系统的存在业户可能都不知道(除非物业告知)。
+
+唯一感知:
+
+- 账单出来更准时(每月固定日期到账)
+- 没人上门抄表(隐私感更好)
+- 用量明细可能更详细(集抄能支持小时 / 天级别 granularity,虽然账单仍是月度)
+
+## 集抄设备与本系统的关系
+
+```mermaid
+flowchart TB
+  subgraph "物理层"
+    M1[家用水表]
+    M2[家用电表]
+    M3[工业表]
+  end
+
+  subgraph "网关层"
+    G1[楼栋网关<br/>RS485 → 4G]
+  end
+
+  subgraph "运营商层(第三方)"
+    V[集抄运营商平台<br/>设备管理 / 数据归档 / API 输出]
+  end
+
+  subgraph "本系统(prop-acc)"
+    API[集抄 API endpoint]
+    DB[(MeterReading)]
+    GenerateBills[GenerateBillsFromMeterReadingsAction]
+    Bill[(Bill)]
+  end
+
+  M1 --> G1
+  M2 --> G1
+  M3 --> G1
+  G1 --> V
+  V -->|每月推送| API
+  API --> DB
+  DB --> GenerateBills
+  GenerateBills --> Bill
+```
+
+**本系统只**管接收 + 存 + 生成账单。**不管**物理设备、网关、信号质量。这些都是集抄运营商的事。
+
+## 常见问题
+
+> [!question] 集抄数据准确吗?会不会比手抄更容易出错?
+> 集抄数据**理论上更准**(机器直读,没手抖)。但:
+>
+> - IoT 设备本身可能故障(读数漂移、传输错)
+> - 信号不好可能漏传(掉线)
+> - 集抄运营商平台可能 bug(数据传错)
+>
+> 准确性强烈依赖**集抄运营商的可靠性**。选大牌运营商 + 完善 SLA。
+
+> [!question] 集抄推过来的数据能改吗?
+> 不能(MeterReading 不可变,见 [[decommission-and-locking]])。如果集抄推错:
+>
+> - 在系统侧建错误 reading
+> - 走作废 Bill → 删 reading(若 Policy 允许)→ 集抄重推
+> - 或运维 tinker 介入
+
+> [!question] 集抄运营商收费贵不贵?
+> 看市场,通常:
+> - 设备 + 安装一次性几十到几百每点
+> - 月度服务费 几元 / 表 / 月
+>
+> 中型社区(1,000 表)月度成本可能几千到几万。物业自行评估"省抄表员工资 vs 集抄费用" ROI。
+
+> [!question] 集抄系统对接需要多久?
+> 看运营商:
+> - 大牌(华为 / 海康)平台标准 API → 1-2 周(主要是数据格式映射 + 测试)
+> - 小厂自研协议 → 1-3 个月(需自定义对接代码)
+
+> [!question] 集抄推数据时本系统有问题(数据库挂 / 网络断)?
+> 集抄运营商应有重试机制(看 SLA)。本系统应:
+> - API 幂等(同 meter + 同 read_at 不重复建)
+> - 失败响应详细(让运营商知道哪条没收到)
+> - 重要数据有补传机制(运营商手动重推)
+
+> [!question] 集抄数据与业户预存款自动扣的关系?
+> 集抄推数 → 生成 Bill → 触发 [[../prepaid/auto-deduction-design|预存款自动抵扣 job]](待实现)→ 业户预存款余额自动扣 + Bill 翻 Paid。
+>
+> 整条链**完全无人介入**,业户次日推送:"5 月电费 ¥168 已自动扣,余额 ¥X"。
+
+## 异常分支
+
+- 集抄掉线个别表 → [[read-single-meter-manual]] 兜底
+- 集抄数据异常用量 → [[exception-high-consumption]]
+- 集抄推错数据需修正 → [[exception-readings-locked-after-bill]]
+- 集抄 API 故障 → 运维 / 集抄运营商支持
+
+## 相关文档
+
+- [[meter-vs-meter-reading]]
+- [[reading-source-and-photo-proof]]
+- [[bill-generation-pipeline]]
+- [[read-single-meter-manual]]
+- [[read-batch-via-excel-import]]
+- [[exception-high-consumption]]

prop-acc/scenarios/meter/read-with-photo-proof.md

@@ -0,0 +1,229 @@
+---
+title: prop-acc · meter · 场景 - 抄表拍照存证(物理表头照片)
+aliases:
+  - 抄表拍照
+  - 照片存证
+  - read-with-photo-proof
+  - 场景-抄表拍照存证
+tags:
+  - 场景
+  - prop-acc
+  - 计量表
+  - 抄表
+  - 存证
+audience:
+  - 业户
+  - 业务人员
+  - 抄表员
+status: 已发布
+sub_feature: meter
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 场景:抄表拍照存证(物理表头照片)
+
+抄表员**录入读数同时上传现场拍的物理表头照片**(`photo_url`),作为**业户事后质疑账单时的关键凭证**。配合 [[read-single-meter-manual|单录]] 流程使用。
+
+## 典型情境
+
+> [!example] 真实情境
+> 张阿姨 6 月初收到 5 月电费账单 ¥168(280 度),她声称"我家平时就 100 多度,不可能这么多":
+>
+> - 王主管打开后台 → 找 E-501 的 5 月 reading → 看 `photo_url`
+> - 照片清晰显示:**表头数字 5,280**(日期戳 2026-05-26,环境信息可识别为张阿姨家配电箱)
+> - 拿照片给张阿姨看 → **业户无话可说**(确实读数是 5,280)
+> - 王主管协助分析:可能近期家里某电器异常耗电(空调 24 小时开?旧冰箱故障?)
+> - 业户回去自查 → 发现儿子用了电烤箱 + 空气炸锅一个月 → 接受账单
+>
+> 拍照存证**避免了一次纠纷**。
+
+## 抄表员视角(李师傅)
+
+### 拍照要点
+
+每张表抄表时,**拍 1-2 张照片**:
+
+| 角度 | 内容 |
+|---|---|
+| **正面特写** | 表头数字清晰可读(关键!)|
+| **环境照** | 表 + 周围环境(配电箱 / 房号牌),证明是哪家的表 |
+
+照片要素:
+
+- **清晰**(对焦,光线足够)
+- **包含表头读数全部位数**(不要遮挡)
+- **时间戳**(手机 EXIF 元数据自动带)
+- **GPS**(若手机 App 支持,更好)
+
+### 录入
+
+后台 / 抄表 App 上的 reading 录入 form 含 `photo_url` 字段:
+
+| 字段 | 填什么 |
+|---|---|
+| 当前读数 | 5280 |
+| 拍照 | 上传刚才的照片(或 App 直接拍照上传)|
+| 备注 | 选填,如"电表正常,环境无异常" |
+
+上传后照片存储到对象存储(S3 / OSS),`photo_url` 字段存对外可访问 URL。
+
+> [!info] 强制度看物业政策
+> - **严格物业**:Form 上 `photo` 字段 `->required()`,无照片不能提交
+> - **建议物业**:Form 可空,UI 上有"建议拍照"提示
+> - **宽松物业**:Form 可空,无提示
+>
+> 当前实现看 `MeterReadingsRelationManager` 的 form 配置。**生产环境强烈推荐严格模式**。
+
+## 业务人员视角
+
+### 查照片
+
+后台 → 计量表 → ViewMeter → Reading 列表(`MeterReadingsRelationManager`):
+
+- 每条 reading 显示"照片"图标(若 photo_url 不为空)
+- 点击图标 → 弹出照片预览
+- 可下载原图
+
+### 业户争议处理
+
+业户来电话 / 上门质疑账单:
+
+1. 王主管打开对应 reading
+2. 调出 photo_url 照片
+3. 与业户当面 / 视频核对
+4. 业户接受 → 案件了结
+5. 业户仍质疑 →
+   - 物业派人**现场再读一次**(若表还在)
+   - 若现场读数与照片一致 → 业户更难反驳
+   - 若现场读数与照片不一致 → 表可能故障 / 数据有问题,走 [[replace-broken-meter|换表]] / [[exception-readings-locked-after-bill|修正流程]]
+
+## 拍照流程图
+
+```mermaid
+sequenceDiagram
+    participant 李师傅
+    participant 物理表
+    participant 手机App
+    participant ObjectStorage[对象存储 S3/OSS]
+    participant 数据库
+
+    李师傅->>物理表: 现场观察读数
+    李师傅->>物理表: 拍照
+    李师傅->>手机App: 录入读数 + 选刚拍的照片
+    手机App->>ObjectStorage: 上传照片
+    ObjectStorage-->>手机App: 返回 URL
+    手机App->>数据库: 建 MeterReading + photo_url
+```
+
+## 业户视角
+
+### 您会感受到什么
+
+通常**不感知** —— 抄表员拍照是物业内部流程。
+
+唯一影响:
+
+- 抄表员上门时可能要求"打开配电箱看表"(配合)
+- 极端情况:业户怀疑抄表员拍假照(看清照片是否真的是自己家表 = 看背景环境)
+
+### 您的权利
+
+对账单有异议时**有权要求**:
+
+- 看抄表照片
+- 派人现场再读一次
+- 提交业户自己拍的反证照片(若业户当时也拍了)
+
+## 拍照的额外用途
+
+除业户争议外,照片还有其他价值:
+
+| 用途 | 怎么用 |
+|---|---|
+| **审计追溯**(年审 / 监管)| 抽查某月某些 reading 的 photo_url,验证抄表真实性 |
+| **抄表员考核** | 检查抄表员是否真去现场(对比 GPS / 时间 / 环境)|
+| **培训新人** | 给新抄表员看老抄表员的照片范例 |
+| **争议预防** | 业户知道有照片在,主动质疑减少 |
+
+## 拍照的成本
+
+| 成本 | 说明 |
+|---|---|
+| 抄表员时间 | 每张表 +5-10 秒 → 1,000 张表 +1-2 小时 |
+| 手机存储 | 每张照片 1-5 MB → 1,000 张 = 几 GB / 月 |
+| 对象存储 | 几 GB / 月 ≈ 几元 / 月(阿里云 OSS / S3) |
+| 长期累积 | 5 年 = TB 级,需归档策略 |
+| 培训 | 抄表员要学会拍合格照片(对焦、清晰、含表头全部数字)|
+
+整体**成本可控**,但需要持续投入。
+
+## 拍照的法律意义
+
+> [!info] 业户法律纠纷时
+>
+> 在物业 vs 业户法律纠纷中,拍照照片是**关键物证**:
+>
+> - 照片有**时间戳 + GPS + 环境元数据**(EXIF) → 可证明真实性
+> - 照片清晰显示读数 + 表号 → 可证明读数正确
+> - 法院通常**采信** 这类专业现场记录
+>
+> 物业**完全没有拍照** → 只有业户口供 vs 物业账面数据 → 物业举证困难。
+
+## 集抄(remote)与拍照的关系
+
+集抄 reading(`source=remote`)**通常无拍照**:
+
+- IoT 设备直接传数据,无相机
+- IoT 设备本身就是凭证(机器读数 → 通常比人工准)
+- 集抄掉线的兜底 [[read-single-meter-manual]] 仍要拍照
+
+详见 [[reading-source-and-photo-proof]]"拍照存证"段。
+
+## 常见问题
+
+> [!question] 业户拒绝抄表员进屋拍照怎么办?
+> 公共部位的表(楼道电表、燃气表)通常装在外面,不用进屋。
+>
+> 入户表(水表常在厨房 / 卫生间)若业户拒绝:
+> - 协商上门时间(业户在家时)
+> - 业户**自己拍照**发给物业(部分物业接受)
+> - 长期拒绝 → 物业政策决定(警告 / 法律手段 / 估算用量)
+
+> [!question] 照片上传失败怎么办?
+> 网络问题 / 对象存储故障:
+> - App 应有**本地缓存**机制(离线时存手机,联网时上传)
+> - 上传失败的 reading 应**仍能提交**(photo_url 为空但有备注"上传失败")
+> - 后续重传(若设计支持)
+
+> [!question] 照片存多久?
+> 法律 / 业务规定:
+> - 中国通常 3-5 年(看物业法规)
+> - 与账单同周期(账单存多久,照片存多久)
+> - 长期归档(冷存储,如阿里云 OSS Archive)成本极低
+
+> [!question] 一张照片能证明哪张表是谁家的?
+> 照片本身不能(看不出房号)。需配合:
+> - **环境识别**(房号牌、门口装饰、邻居环境)
+> - **抄表员手写标注**(若 App 支持)
+> - **GPS 坐标**(若 App 支持)
+> - **数据库 meter_id 关联**(reading 关联 meter,meter 关联 asset)
+
+> [!question] 业户对照片质疑"那不是我家的表"怎么办?
+> 调取**原始 EXIF 数据**(时间戳、GPS、设备型号)→ 证明照片真实性。物业可派人**现场对照**确认表号物理一致。
+
+## 异常分支
+
+- 单录(本场景前置)→ [[read-single-meter-manual]]
+- 批量导入(无拍照)→ [[read-batch-via-excel-import]]
+- 集抄(无拍照)→ [[read-via-iot-remote-source]]
+- 拍照后业户仍质疑高用量 → [[exception-high-consumption]]
+
+## 相关文档
+
+- [[reading-source-and-photo-proof]]
+- [[read-single-meter-manual]]
+- [[read-batch-via-excel-import]]
+- [[read-via-iot-remote-source]]
+- [[exception-high-consumption]]
+- [[decommission-and-locking]]

prop-acc/scenarios/meter/register-single-meter.md

@@ -0,0 +1,153 @@
+---
+title: prop-acc · meter · 场景 - 单独新增一张表
+aliases:
+  - 新增计量表
+  - 单录建表
+  - register-single-meter
+  - 场景-新增计量表
+tags:
+  - 场景
+  - prop-acc
+  - 计量表
+  - 表管理
+audience:
+  - 业务人员
+status: 已发布
+sub_feature: meter
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 场景:单独新增一张表
+
+社区**已经初始化完成**(走过 [[init-new-community-batch]] 或老社区已有数据),后续个别新装一张表(新业户入住装表 / 旧业户加装电表分户 / 商铺新进驻装表),走**后台单录**而非批量。
+
+## 典型情境
+
+> [!example] 真实情境
+> 嘉禾花园 12-3-501 业户陈先生最近**装修后想加装一个独立电表**(主表外的厨房专用电表,方便核算厨房电费)。物业财务王主管要在系统建这张新表。
+
+## 业务人员视角
+
+### 第 1 步:确认装表信息
+
+向陈先生 / 抄表员李师傅核实:
+
+- 房号 / 资产编号:12-3-501(对应 asset)
+- 费用类型:电费(对应 FeeType)
+- 物理表编号:E-501-K(物业自编,K 表示厨房)
+- 倍率:1(普通家用单相表)
+- 安装日期:今天(2026-05-26)
+- **初始读数**:抄表员现场看物理表读数,假设 0(全新表)
+
+### 第 2 步:打开后台
+
+后台 → 计量表 → 列表 → 右上角 **"新建"** 按钮 → 进 `CreateMeter` 页面。
+
+### 第 3 步:填表单(`MeterForm`)
+
+| 字段 | 填什么 |
+|---|---|
+| **社区(community_id)** | 嘉禾花园 |
+| **绑定房屋(asset_id)** | 12-3-501(下拉选)|
+| **费用类型(fee_type_id)** | 电费(下拉选)|
+| **表编号(code)** | `E-501-K` |
+| **倍率(multiplier)** | 1.0 |
+| **初始读数(initial_reading)** | 0.0 |
+| **安装日期(installed_at)** | 2026-05-26 |
+| **是否在役(is_active)** | ✅ 是(默认)|
+| **替换上一代(replaced_meter_id)** | 留空(全新表,不是换表)|
+| 备注 | "陈先生厨房分户表" |
+
+### 第 4 步:提交
+
+系统:
+
+1. 校验 asset / fee_type 存在
+2. 校验 code 在该社区不重复(若有 unique 约束)
+3. 建 Meter 记录(`is_active=true`, `replaced_meter_id=null`)
+4. **可选**:是否同时建一条 `initial_reading` 的 MeterReading?看 `CreateMeter` 实现 —— 若 form 有"初始读数"字段(目前应该有),`installed_at` 当天会建一条 `MeterReading(current_reading=0)` 作为起点,这样下次抄表算用量有 previous 可对照
+
+### 第 5 步:启用 + 抄表
+
+新表建好后,下次抄表周期就纳入正常流程(`MetersNeedingReadingListWidget` 会显示)。
+
+## 系统流程
+
+```mermaid
+sequenceDiagram
+    participant 王主管
+    participant Filament
+    participant CreateMeter
+    participant 数据库
+
+    王主管->>Filament: ListMeters → 新建按钮
+    Filament->>CreateMeter: 渲染 form
+    王主管->>CreateMeter: 填字段 + 提交
+    CreateMeter->>数据库: 校验 asset / fee_type / code
+    CreateMeter->>数据库: 建 Meter(is_active=true)
+    alt form 含 initial_reading
+      CreateMeter->>数据库: 建 MeterReading(current=initial, source=manual, operated_by=王主管)
+    end
+    CreateMeter-->>Filament: 跳转 ViewMeter
+    Filament-->>王主管: 显示新表详情
+```
+
+## 与批量导入的对比
+
+| 维度 | [[init-new-community-batch|批量导入]] | **单录(本场景)** |
+|---|---|---|
+| 触发场景 | 新社区接管 / 一次性大批量 | 个别新装 / 后续补建 |
+| 数量级 | 100+ | 1 |
+| UI | Excel 导入 | Filament `CreateMeter` 表单 |
+| 时长 | 几分钟 / 小时 | 1-2 分钟 |
+| 出错容忍 | 单行失败 / 部分行可独立处理 | 单条提交,错就改了再交 |
+| 业务人员熟练度 | 需熟悉 Excel 模板 | 任何人填表都行 |
+
+## 常见问题
+
+> [!question] 业主已经有主电表,加装分表合规吗?
+> **业务问题**,看物业政策 / 法律法规:
+>
+> - 国家电网通常**禁止**业主自己装"二次表"用于电费分摊
+> - 但**物业内部**核算可以(例如商铺租户共用一个主表,物业按业主装的分表算各自费用)
+>
+> 系统层面**只管记录**,不判断合规性。
+
+> [!question] 同一房屋有主表也有分表怎么办?
+> 系统允许同一 `asset_id` + 同一 `fee_type_id` 下有多张表(不像 prepaid 的"一户一账"约束)。每张表独立抄表 + 独立账单。
+>
+> 但**业务上要清楚谁付谁的钱**:
+> - 主表账单给业主
+> - 分表账单给租户 / 厨房承包人(看场景)
+>
+> 这要业务方明确**账单收方**,系统按 `community_asset_users` 关系找业户。
+
+> [!question] 单录时填错 code 怎么办?
+> 表创建后可走 `EditMeter`(`is_active=true` 时允许)修改。但若**已抄过表 / 生成 Bill**,改 code 会让"历史照片上的表号"与"系统 code"对不上 → 强烈不推荐改。详见 [[decommission-and-locking]]"为什么退役表不能改"段。
+
+> [!question] 单录后没抄表就发现错了能删吗?
+> 看 `MeterPolicy::delete()`:**仅允许"已退役 + 无任何读数"**的表被删。
+>
+> 处理流程:
+> 1. 先退役表(`is_active=false`, `decommission_reason=Removed`)
+> 2. 走删除(若 Policy 允许 + 没读数)
+> 3. 重新建正确的表
+>
+> 详见 [[decommission-and-locking]]。
+
+> [!question] 单录的表如何同步给抄表员?
+> `MetersNeedingReadingListWidget` 会自动显示新表(下个抄表周期)。无需手工通知。
+
+## 异常分支
+
+- 大批量 → [[init-new-community-batch]]
+- 换表(旧表退役 + 新表建)→ [[replace-broken-meter]]
+- 错了删表 → [[decommission-without-replacement]]
+
+## 相关文档
+
+- [[meter-vs-meter-reading]]
+- [[init-new-community-batch]]
+- [[replace-broken-meter]]
+- [[decommission-and-locking]]

prop-acc/scenarios/meter/replace-broken-meter.md

@@ -0,0 +1,234 @@
+---
+title: prop-acc · meter · 场景 - 换表:旧表故障/退役,新表带 -R1 后缀
+aliases:
+  - 换表
+  - 表更换
+  - replace-broken-meter
+  - ReplaceMeterAction
+  - 场景-换计量表
+tags:
+  - 场景
+  - prop-acc
+  - 计量表
+  - 表管理
+audience:
+  - 业务人员
+  - 抄表员
+status: 已发布
+sub_feature: meter
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 场景:换表,旧表故障/退役,新表带 -R1 后缀
+
+物理表**老化 / 损坏 / 校验未过**,需要换新表。系统通过 `ReplaceMeterAction` **一步完成**:旧表退役 + 新表建立 + `replaced_meter_id` 关联 + 初始读数继承。新表自动编号 `<旧编号>-R1`。
+
+## 典型情境
+
+> [!example] 真实情境
+> 张阿姨家电表(编号 E-501)用了 8 年,2026 年 5 月例行校验未通过(读数漂移),物业要换新表。
+>
+> 换表当天:
+> - 抄表员李师傅现场读旧表:**5000 度**
+> - 卸下旧表 + 装上新表
+> - 新表出厂读数:**0**(物理上)
+> - 系统操作:`ReplaceMeterAction`
+>
+> 系统结果:
+> - 旧表 E-501:`is_active=false`, `decommissioned_at=今天`, `decommission_reason=Replaced`, `final_reading=5000`
+> - 新表 **E-501-R1**:`is_active=true`, `installed_at=今天`, `replaced_meter_id=旧表 ID`, **`initial_reading=5000`(继承)**, multiplier 继承
+
+## 抄表员视角(李师傅)
+
+### 第 1 步:现场操作
+
+到张阿姨家:
+
+1. 检查旧表状态(确认换表必要性)
+2. **拍照存证**旧表当前读数(关键!后续争议时凭证)
+3. 物理换表(断电 → 换表 → 通电)
+4. 拍照新表初始状态(出厂 0)
+5. 把信息回传业务人员(微信 / App / 当面)
+
+> [!warning] 拍照不能省
+> 旧表读数没拍照 = 系统里填的"5000" 没物理证据 = 业户事后质疑"我家明明只用了 4500" 时物业百口莫辩。
+
+### 第 2 步:报回业务
+
+抄表员把信息汇总给王主管(业务人员):
+
+- 旧表编号:E-501
+- 旧表最后读数:5000
+- 换表日期:2026-05-26
+- 退役原因:校验未过(`Replaced`)
+- 新表型号:同型号(multiplier=1)
+
+## 业务人员视角
+
+### 第 1 步:打开旧表
+
+后台 → 计量表 → 找 E-501 → 进 `ViewMeter`。
+
+### 第 2 步:点 `ReplaceMeterAction`
+
+右上角"换表"按钮(标签可能是"更换")。
+
+> [!warning] 按钮可见性
+> 守护:`is_active=true` + Policy `->authorize('replace')`。已退役表此按钮灰化。
+
+Modal 表单:
+
+| 字段 | 填什么 |
+|---|---|
+| **旧表最后读数(`final_reading`)** | 5000(抄表员现场读)|
+| **退役原因(`decommission_reason`)** | `Replaced`(其他 4 种见 [[decommission-and-locking]]) |
+| **退役日期** | 2026-05-26(默认今天)|
+| **新表编号** | E-501-R1(系统自动生成,`nextReplacementCode()`,可改但不推荐)|
+| **新表 multiplier** | 1.0(默认继承旧表)|
+| **新表安装日期** | 2026-05-26(默认今天)|
+| 备注 | "校验未通过,换新表" |
+
+### 第 3 步:提交
+
+系统在**一个事务**内:
+
+1. 校验旧表 `is_active=true`(否则按钮就不该出现)
+2. 旧表 update:
+   - `is_active = false`
+   - `decommissioned_at = 2026-05-26`
+   - `decommission_reason = Replaced`
+   - `final_reading = 5000`
+3. 建新表:
+   - `code = E-501-R1`(`nextReplacementCode($oldCode)`)
+   - `is_active = true`
+   - `installed_at = 2026-05-26`
+   - `replaced_meter_id = 旧表 ID`
+   - **`initial_reading = 5000`**(继承自旧表 final_reading)
+   - `multiplier = 1.0`(继承)
+   - `community_id` / `asset_id` / `fee_type_id` 继承
+
+### 第 4 步:验证 + 通知
+
+后台 → 计量表 → 看新旧两张表 → 确认数据正确。
+
+业户可不通知(业户对系统层无感)。
+
+## 系统流程
+
+```mermaid
+sequenceDiagram
+    participant 抄表员
+    participant 王主管
+    participant Filament
+    participant ReplaceMeterAction
+    participant 数据库
+
+    抄表员->>抄表员: 现场拍照 + 换表(物理)
+    抄表员->>王主管: 旧表读数 5000,换表完成
+
+    王主管->>Filament: ViewMeter(旧表) → ReplaceMeterAction
+    Filament->>ReplaceMeterAction: handle(oldMeter, finalReading=5000, reason=Replaced)
+    ReplaceMeterAction->>数据库: 开启事务
+    ReplaceMeterAction->>数据库: 1. 旧表 update:is_active=false, decommissioned_at, decommission_reason=Replaced, final_reading=5000
+    ReplaceMeterAction->>数据库: 2. 建新表:code=E-501-R1, is_active=true, replaced_meter_id=旧表id, initial_reading=5000, multiplier=1
+    ReplaceMeterAction->>数据库: 提交事务
+    Filament-->>王主管: 跳转新表 ViewMeter
+```
+
+## 旧表 / 新表数据对照
+
+| 字段 | 旧表 E-501 | **新表 E-501-R1** |
+|---|---|---|
+| `code` | E-501 | **E-501-R1** |
+| `is_active` | **false** | true |
+| `installed_at` | 2018-XX-XX(原值) | 2026-05-26 |
+| `decommissioned_at` | **2026-05-26** | null |
+| `decommission_reason` | **Replaced** | null |
+| `final_reading` | **5000** | null |
+| `initial_reading` | (历史值不动)| **5000**(继承)|
+| `multiplier` | 1 | 1(继承) |
+| `replaced_meter_id` | null | **旧表 id** |
+| `community_id`, `asset_id`, `fee_type_id` | 不动 | 继承 |
+
+## 5 月份的抄表 + 账单
+
+换表那个月的账单:
+
+```
+本月用量 = current(新表第一次抄)+ initial(=5000) - previous(=5000)
+        = (50 + 5000) - 5000
+        = 50 度
+```
+
+新表 5 月底第一次抄读到 50(物理表头),系统存 `current_reading = 50 + 5000 = 5050`,`previous_reading = 5000`(继承),`consumption = 50`。账单按 50 度算,业户感觉不到换表。
+
+> [!info] 抄表员录入逻辑
+> 抄表员现场看到新表是 50,**系统应自动加上 5000 存为 5050**(避免抄表员手动算)。或者抄表员录 50,系统在保存时自动加 5000。具体实现看 `MeterReadingsRelationManager` 的 form。
+
+## 业户视角
+
+业户**几乎感受不到** —— 只看到下月账单仍是正常用量。
+
+唯一感知:换表当天可能短暂断电断水(物理操作)。物业应**提前通知**业户。
+
+## 整链追溯
+
+如果以后这张 E-501-R1 又出问题再换 → 新表 E-501-R2,`replaced_meter_id` 指 R1。如此累加:
+
+```
+E-501 (原生) → E-501-R1 (第 1 次换) → E-501-R2 (第 2 次换) → E-501-R3 ...
+```
+
+详见 [[replacement-chain]]"整条链的追溯"段。
+
+## 常见问题
+
+> [!question] 旧表 `final_reading` 填错了能改吗?
+> 旧表的 `final_reading` 严格上属于"已退役表的字段",`MeterPolicy::update()` 在 `is_active=false` 时拒绝改([[decommission-and-locking]] 守护)。
+>
+> 改错的话:
+> - 通过 tinker 修(运维操作,留备注)
+> - 或者把 `decommissioned_at = null` 让表"复活"(Policy 可能不允许),再走完整换表流程
+>
+> **预防**:换表 Modal 提交前与抄表员书面确认 final_reading。
+
+> [!question] 新表 multiplier 与旧表不同可以吗?
+> 可以(form 上可改),但**强烈不推荐**。理由见 [[replacement-chain]]"常见问题"段:不同 multiplier 让用量计算公式变,业户对账困难。
+
+> [!question] 新表编号 -R1 不喜欢能改成别的吗?
+> Modal 表单允许改 `code`,但**强烈不推荐**:
+> - `-R1` 是标准化命名,审计 / 报表 / 后续换表的 `-R2` 都基于这个 pattern
+> - 改成自定义 code(如 "E-501-NEW")会破坏 `nextReplacementCode()` 算法,下次换表生成 `E-501-NEW-R1` 看着别扭
+
+> [!question] 换表后业户对历史账单有异议怎么办?
+> 历史 reading 都关联到旧表(`meter_id=旧表 id`),不会因换表丢失。审计可:
+>
+> - 后台找旧表 → 看历次 reading(只读)
+> - 拿物理表照片(若有)
+> - 拿换表前的累计读数(旧表 final_reading)对照
+
+> [!question] 业户搬走永久弃用表,这种"换表"怎么处理?
+> 那不是换表,是 [[decommission-without-replacement|退役不换表]]。`decommission_reason=Removed` 或 `Expired`,不建新表。
+
+> [!question] 旧表是 active 但有未结账 reading,能换表吗?
+> 系统**不阻止**(Action 不查未结账 reading)。但业务上:
+>
+> - 应先生成未结账 reading 的 Bill(走 [[bill-generation-pipeline]])
+> - 否则换表后那些 reading 永远不会被处理(它们关联旧表)
+>
+> 推荐流程:**换表前先把旧表当月抄表录入 + 生成 Bill** → 然后再换表。
+
+## 异常分支
+
+- 不换表只退役 → [[decommission-without-replacement]]
+- 误换表想撤销 → 困难,见 [[replacement-chain]]"常见问题"段
+- 单纯换 multiplier 不换表 → 不推荐(应换表保留历史)
+
+## 相关文档
+
+- [[meter-vs-meter-reading]]
+- [[replacement-chain]]
+- [[decommission-and-locking]]
+- [[decommission-without-replacement]]
+- [[register-single-meter]]