270 lines
8.9 KiB
Markdown
270 lines
8.9 KiB
Markdown
|
---
|
||
|
|
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 同类对比)
|