From 42c135a5cf9140fca9b596848226a7985f8edb4a Mon Sep 17 00:00:00 2001 From: Willie Date: Tue, 26 May 2026 01:21:32 +0800 Subject: [PATCH] =?UTF-8?q?billing=20=E5=AD=90=E6=A8=A1=E5=9D=97=20=C2=B7?= =?UTF-8?q?=20=E8=BD=AE=202:16=20=E5=9C=BA=E6=99=AF=20+=20=E7=9F=A5?= =?UTF-8?q?=E8=AF=86=E5=9C=B0=E5=9B=BE=E6=94=B6=E5=B0=BE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 写 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) --- prop-acc/index.md | 2 +- prop-acc/maps/billing-knowledge-map.md | 45 +++++++++++++------------- prop-acc/maps/knowledge-map.md | 2 +- 3 files changed, 25 insertions(+), 24 deletions(-) diff --git a/prop-acc/index.md b/prop-acc/index.md index 483924a..bacb118 100644 --- a/prop-acc/index.md +++ b/prop-acc/index.md @@ -27,7 +27,7 @@ last_review: 2026-05-25 | **保证金** | 装修押金等代管资金,完工后退还 | [deposit 知识地图](maps/deposit-knowledge-map.md) | ✅ 25 篇 | | **预存款** | 业户预存,自动抵扣月度账单 | [prepaid 知识地图](maps/prepaid-knowledge-map.md) | ✅ 23 篇 | | **计量表** | 水表/电表/燃气表,抄表生成账单 | [meter 知识地图](maps/meter-knowledge-map.md) | ✅ 21 篇 | -| **账单** | 周期性账单 + 计量账单 | [billing 知识地图](maps/billing-knowledge-map.md) | 🟡 6 概念已完成,16 场景待补 | +| **账单** | 周期性账单 + 计量账单 | [billing 知识地图](maps/billing-knowledge-map.md) | ✅ 23 篇 | | **收款订单** | 一次收款的支付方式、银行账户记录 | _待补_ | 🚧 | | **收据** | 成功收款后生成的凭证 | _待补_ | 🚧 | diff --git a/prop-acc/maps/billing-knowledge-map.md b/prop-acc/maps/billing-knowledge-map.md index b32dbe1..6765cb7 100644 --- a/prop-acc/maps/billing-knowledge-map.md +++ b/prop-acc/maps/billing-knowledge-map.md @@ -60,40 +60,38 @@ code_version: 2026-05-22 | [删除 vs 作废双轨制](../concepts/billing/delete-vs-void-dual-track.md) | 物理删(Unpaid 无付款)vs 作废(留状态留审计)的设计哲学 | | [智能批量删除设计](../concepts/billing/smart-bulk-delete-design.md) | 预检查三档分类 + 必填原因 + activitylog 完整审计 | -## 场景手册(16 篇,**待补充 ✋**) - -> 🚧 概念骨架已就位,场景文档将在下一轮(轮 2)产出。预定结构如下。 +## 场景手册(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) +- ✅ [月度物业费批量生成(`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) +- ✅ [单张账单收款(`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) +- ✅ [拆账单(`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) +- ✅ [物理删除未付账单(误建立刻删)](../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) +- ✅ [部分付状态处理(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) ## 跨域引用 @@ -139,6 +137,9 @@ code_version: 2026-05-22 --- -> [!info] 概念已完成,场景待补 -> 本轮(轮 1)产出:6 个概念 + 本子模块地图 + 域总图更新。 -> 下一轮(轮 2)产出:16 个场景文档,基于本知识地图骨架填充。 +> [!success] billing 子模块:6 概念 + 16 场景 + 1 知识地图 = **23 篇完成** +> +> 写作日期:2026-05-26 +> 对应代码版本:2026-05-22(详见 `packages/prop-acc/issue.md` Q6 段,最详细 issue 之一) +> +> 如果发现遗漏的场景或需要补充的细节,告诉我,可以单独补充新文档。 diff --git a/prop-acc/maps/knowledge-map.md b/prop-acc/maps/knowledge-map.md index ba03d8a..4ff512e 100644 --- a/prop-acc/maps/knowledge-map.md +++ b/prop-acc/maps/knowledge-map.md @@ -23,7 +23,7 @@ last_review: 2026-05-25 | prepaid | 预存款 | 业户预存,自动抵扣月度账单 | [prepaid 知识地图](prepaid-knowledge-map.md) | ✅ 16 场景 + 6 概念 + 1 地图 = 23 篇 | | deposit | 保证金 | 装修押金等代管资金,完工后退还 | [deposit 知识地图](deposit-knowledge-map.md) | ✅ 18 场景 + 6 概念 + 1 地图 = 25 篇 | | meter | 计量表 | 水表/电表/燃气表,抄表生成账单 | [meter 知识地图](meter-knowledge-map.md) | ✅ 14 场景 + 6 概念 + 1 地图 = 21 篇 | -| billing | 账单 | 周期性账单 + 计量账单 | [billing 知识地图](billing-knowledge-map.md) | 🟡 6 概念已完成,16 场景待补 | +| billing | 账单 | 周期性账单 + 计量账单 | [billing 知识地图](billing-knowledge-map.md) | ✅ 16 场景 + 6 概念 + 1 地图 = 23 篇 | | payment-order | 收款订单 | 一次收款的支付方式、银行账户记录 | _待补_ | 🚧 | | receipt | 收据 | 成功收款后生成的凭证 | _待补_ | 🚧 |