---
title: prop-acc · deposit · 场景 - 余额清零自动关闭
aliases:
  - 押金账户自动关账
  - 余额 0 自动 Closed
  - close-after-zero-balance
  - 场景-押金账户自动关闭
tags:
  - 场景
  - prop-acc
  - 保证金
  - 结清
audience:
  - 业户
  - 业务人员
status: 已发布
sub_feature: deposit
last_review: 2026-05-25
code_version: 2026-05-22
---

# 场景:余额清零自动关闭

押金账户在**最后一笔操作**(退款 / 扣罚)使余额变 0 的瞬间,系统**自动**把账户状态翻为 `Closed`,无需手工再点"关账"。

## 典型情境

> [!example] 真实情境(三种触发)
>
> **情境 A**:张阿姨家装修无损坏,物业全额退 ¥5,000 → 余额 0 → 账户**自动 Closed**。
>
> **情境 B**:陈先生家装修部分损坏,先扣 ¥800,再退余下 ¥4,200 → 余额 0 → 账户**自动 Closed**。
>
> **情境 C**:刘先生违约严重,全部 ¥5,000 全扣无退 → 余额 0 → 账户**自动 Closed**。

## 业户视角

### 您会感受到什么

- 收到**最后一张红字收据**(可能是退款 / 也可能是扣罚)
- 同时收到通知:"您的押金账户已结清,余额 0"
- 小程序"我的押金账户"显示 "🔒 已结清"
- 流水台账仍可查(只读),整张账户的历史可追溯

### 您要做什么

- 妥善保管所有收据(缴款蓝字 + 历次退款 / 扣罚红字)
- **不要试图重启账户** —— 系统设计上不允许;新业务请联系物业开新账户
- 如有任何关于过往流水的疑问 → 联系物业核对(凭收据 + 流水台账)

## 业务人员视角

### 关键认知:不需要手工关账

> [!info] 自动机制
> 任何 `RefundAction` / `ForfeitureAction` 提交后,系统在事务尾部检查 `balance == 0`,**自动**把 `status` 从 `Active` 翻到 `Closed`。
>
> 你不需要(也不应该)在余额变 0 后还跑一次 `CloseAction` —— 那个按钮 UI 上会被守护 `canBeClosed()`(已是 Closed → false),即使强行调也会被 Policy 拦截。

### 触发链路

最常见的几条路径:

| 序号 | 场景 | 触发动作 | 关账方式 |
|---|---|---|---|
| 1 | 无损全退 | `RefundAction(全额)` | 自动 |
| 2 | 部分扣罚 + 退余 | `RefundAction(剩余)` | 自动(退完瞬间)|
| 3 | 全扣无退 | `ForfeitureAction(余额全)` | 自动(扣完瞬间)|
| 4 | 多次扣罚直到清零 | 最后一笔 `ForfeitureAction` | 自动 |
| 5 | 主动关账(罕见,见 [[close-manual-with-zero-balance]]) | `CloseAction` | 手工(账户余额本来就 0) |

### 实现细节(`canBeClosed` + 自动逻辑)

`DepositAccount` 模型上的相关方法:

```php
public function canBeClosed(): bool
{
    return $this->balance == 0 && $this->status !== DepositAccountStatus::Closed;
}
```

业务层(`RefundFromDepositAccountAction` / `ForfeitFromDepositAccountAction`)在事务最后会检查并自动调用 `close()`:

```php
// 伪代码
if ($account->canBeClosed()) {
    $account->update(['status' => DepositAccountStatus::Closed]);
}
```

### 通知

后台日志记录"账户已自动关账",业户侧通过最后一张 Receipt 同时收到关账信息(Receipt 内容 + 短信)。

## 系统流程

```mermaid
sequenceDiagram
    participant 财务
    participant Filament
    participant RefundFromDepositAccountAction
    participant 数据库

    Note over 财务: 余额 4200,退最后 4200

    财务->>Filament: RefundAction (4200)
    Filament->>RefundFromDepositAccountAction: handle(account, 4200, channel)
    RefundFromDepositAccountAction->>数据库: 开启事务
    RefundFromDepositAccountAction->>数据库: 建 CO(-4200) + Transaction(refund, 4200→0)
    RefundFromDepositAccountAction->>数据库: balance=0
    Note over RefundFromDepositAccountAction: 检查 canBeClosed() → balance==0 → true
    RefundFromDepositAccountAction->>数据库: 自动 status=Closed
    RefundFromDepositAccountAction->>数据库: 触发 CollectionOrderCompleted
    RefundFromDepositAccountAction->>数据库: 提交事务
```

## 常见问题

> [!question] 余额 0 但 status 还是 Active 怎么办?
> 这是 bug。可能原因:
> - 业务 Action 没调 `canBeClosed()` 检查
> - 事务回滚后状态不一致
>
> 修复:tinker 手工执行 `$account->update(['status' => DepositAccountStatus::Closed])`,然后修复 Action 代码。审计上可写一笔说明备注。

> [!question] 没有任何流水(从未缴款)的账户能关账吗?
> 技术上可以(`balance == 0`)。但**业务上不正常**(开了账户没缴款),应:
> - 查清原因(为什么开了不缴?录错?)
> - 走 `CloseAction` 手工关([[close-manual-with-zero-balance]] 场景)
> - 备注清楚"无缴款记录,关闭"

> [!question] Frozen 账户余额是 0,自动关账吗?
> **不会**。Frozen 状态下不会自动关账,因为冻结期间任何状态变更都需要审慎处理。Frozen 且余额 0 → 先 [[unfreeze-after-mediation|解冻]] → 自动变 Active → 再走 `CloseAction` 手工关(或重启业务再继续操作)。

> [!question] 已关账户能"重新开张"继续用吗?
> 不能。`canBeReopened()` 永远 false。**新业务开新账户**。详见 [[account-state-machine]] "为什么不允许 Reopen" 段。

> [!question] 关账时业户能查看流水吗?
> 能。Closed 账户**只读模式**保留全部历史 —— 流水台账、所有 Receipt、状态变更记录(`meta`)都可查询。这是账户的"历史档案",随时可调出对账。

## 与 ForceClose 的区别

| 维度 | 本场景(自动关账) | [[force-close-refund]] 等 |
|---|---|---|
| 触发条件 | balance==0 时的最后一笔 Refund / Forfeiture | 账户 Frozen + 有余额,但要终结此账户 |
| 状态前置 | Active(Frozen 不会自动) | Frozen + hasBalance |
| Action | 任何减余额到 0 的 Action | 专用 `ForceCloseAction` |
| 资金处置 | 已有的 Refund / Forfeiture 决定 | 由 disposition 选(refund / forfeit / retain) |
| 关账理由 | "余额清零正常关账" | 强制结清,有专门 audit 字段 |

## 异常分支

- 关账时业户提出反悔 → 不可逆;走线下沟通 / 司法
- 余额非 0 想强制关 → 走 [[force-close-refund]] / [[force-close-forfeit]] / [[force-close-retain]]
- 主动关账(无业务往来)→ [[close-manual-with-zero-balance]]

## 相关文档

- [[account-state-machine]]
- [[refund-full-no-damage]]
- [[refund-partial-after-forfeit]]
- [[forfeit-damage-public-area]]
- [[close-manual-with-zero-balance]]
- [[force-close-refund]]