Files

Willie 42c135a5cf billing 子模块 · 轮 2:16 场景 + 知识地图收尾

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

2026-05-26 01:21:32 +08:00

7.4 KiB

Raw Blame History

title, aliases, tags, sub_feature, audience, status, last_review, code_version

title

aliases

账单(billing)知识地图

本子模块 = Bill + CollectionOrderBill(中间表)。覆盖物业收款的应收应付侧:账单生成、状态管理、收款关联、删除 / 作废 / 挂起 / 拆单全套。

billing 是 prop-acc 最复杂的子模块,也是收款流程的中枢(各业务源 → Bill → CollectionOrder)。

这是什么?

物业管理软件最核心的对象之一 —— 应收账款的记录。从抄表 / 周期任务 / 手工建单产生,经历状态变化(Unpaid → Partial → Paid),最终通过 CollectionOrder 完成收款。

与其他子模块的关系

关系	说明
上游:meter → bill	抄表 → 生成计量账单
上游:周期任务 → bill	月度物业费等批量生成
上游:手工 → bill	临时收费
下游:bill → CollectionOrder	收款时建 CO + Receipt
侧链:bill ← prepaid	业户预存款抵账单(走 Bill consume,见 prepaid 模块)

与其他子模块的核心差异

维度	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 篇)

文档	一句话
账单六状态机	6 状态(Unpaid / Partial / Paid / Suspended / Processing / Void),prop-acc 最复杂
账单类型与来源	周期 / 计量 / 临时三类 + sourceable polymorphism
Bill 与 CollectionOrder 关系	应收 vs 已收,CollectionOrderBill 多对多
周期账单生成机制	`GeneratePeriodicBillsAction` + `BillingMergeStrategy` 三种合并策略
删除 vs 作废双轨制	物理删(Unpaid 无付款)vs 作废(留状态留审计)的设计哲学
智能批量删除设计	预检查三档分类 + 必填原因 + activitylog 完整审计

场景手册(16 篇,全部完成 ✅)

📝 账单创建(3 篇)

💰 收款(3 篇)

✂️ 账单调整(3 篇)

🗑️ 删除 / 作废(3 篇)

🛡️ 异常 / 审计(4 篇)

跨域引用

本子模块引用以下跨域共享概念:

业户 — 账单收方
房屋单元 — asset_id,账单关联房屋
组织结构 — community_id,物业项目归属

跨子模块引用

adhoc · CollectionOrder 与 Receipt — 收款侧的核心对象
meter · 账单生成的三层分层 — 计量账单的生成器
prepaid · Consume 走 CollectionType=Bill — 预存款抵账单的资金流
meter · 表退役与读数锁定 — 类似的"状态机+守护"对比
deposit · 账户与流水 — 双对象模式对比

7.4 KiB Raw Blame History