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

---
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 之一)
>
> 如果发现遗漏的场景或需要补充的细节,告诉我,可以单独补充新文档。