vault backup: 2026-05-26 01:03:15

2026-05-26 01:03:15 +08:00
parent 82de3396bb
commit d3a786ba76
5 changed files with 1000 additions and 4 deletions
--- a/prop-acc/scenarios/billing/create-single-bill-manual.md
+++ b/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]]