---
title: prop-acc · deposit · 场景 - 装修完无损全额退还
aliases:
  - 全额退还押金
  - 无损装修退押
  - refund-full-no-damage
  - 场景-押金全额退还
tags:
  - 场景
  - prop-acc
  - 保证金
  - 退款
audience:
  - 业户
  - 业务人员
status: 已发布
sub_feature: deposit
last_review: 2026-05-25
code_version: 2026-05-22
---

# 场景:装修完无损全额退还

最常见、最理想的退押场景。业户装修完物业验收**无损坏无违约**,押金原额退还,账户自动关闭。

## 典型情境

> [!example] 真实情境
> 张阿姨家装修完了(花了 6 周),物业例行验收公共走道、电梯、楼栋出入口,**没有任何损坏**。张阿姨当初交了 ¥5,000 装修保证金,现在物业要全额退给她。

## 业户视角

### 第 1 步:装修完通知物业验收

- 微信通知物业管家 / 直接到前台说"我家装修完了,来验收一下退押金"
- 通常物业 2-3 个工作日内派人到现场

### 第 2 步:验收无损,等退款

- 验收员检查公共区域、电梯、楼道、出入口
- 无损 → 出验收报告"无损,准予退押"
- 物业财务凭报告办理退款

### 第 3 步:收到退款

退款方式取决于您当初**怎么交的押金**:

| 当初缴款方式 | 退款方式 |
|---|---|
| 微信扫码 | 退微信 / 银行卡 |
| 现金 | 通常退到您银行卡(物业转账)|
| 银行转账 | 原账户回款 |
| POS 刷卡 | 原卡原路退 |

> [!info] 一两个工作日内到账
> 退款不是即时,物业财务批量处理(通常隔日)。

### 第 4 步:收到红字收据

您会收到一张**红字收据**:
> "装修保证金退还 ¥-5,000"

- 金额前的负号表示"退款"
- 这是中国会计的"红字凭证"标准写法
- 妥善保管,可作税务凭证

> [!success] 完成
> 账户自动关闭,不会再有变动。短信/微信通知:"您的押金账户已结清,余额 0"。

## 业务人员视角(物业财务)

### 第 1 步:核对验收报告

确认装修完验收通过、无损坏、无未结违约。

### 第 2 步:打开账户

后台 → 保证金 → 账户列表 → 找到张阿姨的账户(Active,balance=5000)→ 点击进入 `ViewDepositAccount`。

### 第 3 步:点击 `RefundAction`(标签"退款")

右上角状态管理组里。Modal 表单:

| 字段 | 填什么 |
|---|---|
| **退款金额** | ¥5,000(默认带入当前余额,可改) |
| **退款渠道(PaymentChannel)** | 选张阿姨指定的回款方式(微信 / 银行转账 / POS) |
| **退款备注** | 选填,如 "装修验收无损,全额退还" |

> [!warning] 按钮可见性
> `RefundAction` 加了 `->authorize('refund')` Policy 守护:`update` 权限 + `canWithdraw()` 状态(Active only)。Frozen / Closed 账户该按钮灰化。

### 第 4 步:提交

系统调 `RefundFromDepositAccountAction`,事务内:

1. 校验账户 `canWithdraw()`(Active only)
2. 校验金额 ≤ 当前余额
3. 建 `CollectionOrder`(`actual_amount=-5000` 红字,`status=Completed`)
4. 加 `DepositTransaction`(`type=refund`,`amount=5000`,`balance_before=5000`,`balance_after=0`,关联红字 CO)
5. 更新 `DepositAccount.balance=0`
6. **余额清零自动关账** → 账户 `status=Closed`
7. 触发 `CollectionOrderCompleted` → Listener 建红字 Receipt"装修保证金退还 ¥-5,000"

### 第 5 步:走线下退款流程

- 微信 / POS 退款:在对应支付网关后台操作
- 银行转账:导出回款指令交银行
- 现金退款(罕见):张阿姨到前台领现金

### 第 6 步:把红字收据交给张阿姨

后台找到红字 Receipt → 打印 / 发微信。

## 系统流程

```mermaid
sequenceDiagram
    participant 业户
    participant 财务
    participant Filament
    participant RefundFromDepositAccountAction
    participant 数据库
    participant 监听器

    业户->>财务: 装修完了,验收无损,退押金
    财务->>Filament: ViewDepositAccount → RefundAction(modal)
    Filament->>RefundFromDepositAccountAction: handle(account, 5000, channel)
    RefundFromDepositAccountAction->>RefundFromDepositAccountAction: canWithdraw()? (Active=true)
    RefundFromDepositAccountAction->>RefundFromDepositAccountAction: amount ≤ balance? (5000≤5000)
    RefundFromDepositAccountAction->>数据库: 开启事务
    RefundFromDepositAccountAction->>数据库: 1. 建 CollectionOrder (-5000 红字, Completed)
    RefundFromDepositAccountAction->>数据库: 2. 建 DepositTransaction (refund, 5000→0)
    RefundFromDepositAccountAction->>数据库: 3. balance=0,自动 status=Closed
    RefundFromDepositAccountAction->>监听器: 4. 触发 CollectionOrderCompleted
    监听器->>数据库: 5. 建 Receipt (装修保证金退还 ¥-5,000 红字)
    RefundFromDepositAccountAction->>数据库: 提交事务
    Filament-->>财务: 成功通知
    财务-->>业户: 银行/微信退款 + 红字收据
```

> [!info] 自动关账
> 余额清零时,系统自动把账户翻成 `Closed`,不需要再单独走一次 [[close-after-zero-balance|关账]] 操作。

## 常见问题

> [!question] 业户当初付现金,退款必须退现金吗?
> 不强制。退款时选 `PaymentChannel` 可以与缴款时不同。常见做法是退到业户银行卡,详见 [[refund-with-payment-channel-switch]]。

> [!question] 退一半就行可以吗?
> 可以,Modal 表单的"退款金额"字段可以改成任意 ≤ 余额的数字。剩余款还在账户里,账户保持 Active。后续可继续退或扣或关。

> [!question] 退款后红字收据上的"-"是什么意思?
> 中国会计的"红字凭证"。负数表示资金方向是"从物业流出 / 回到业户",与缴款时的"+"对称。详见 [[red-receipt-design]]。

> [!question] 业户拿到红字收据后觉得"扣了我的钱"?
> 给业户解释:
> - "-5,000" 不是"扣 5,000",是"退还 5,000"
> - 黑字(无负号)是物业收到的钱,红字(有负号)是物业退给您的钱
> - 这是会计标准做法

> [!question] 退款失败(银行退回 / 微信渠道异常)怎么办?
> 当前系统**不处理这种回调**。物业财务需要在线下沟通业户,重新指定退款渠道,然后:
> - 如果账户已关:开新账户(不推荐)或 tinker 改流水(运维介入)
> - 推荐:**业务流程上避免** —— 退款前与业户确认渠道有效

> [!question] 已关账户能反悔吗?
> 不能。`canBeReopened()` 永远 false。详见 [[account-state-machine]] "为什么不允许 Reopen" 段。如果业户反悔继续装修要再交押金,**开新账户**。

## 异常分支

- 有损坏 → 先扣 [[forfeit-damage-public-area]],再走 [[refund-partial-after-forfeit]]
- 退款渠道与缴款不同 → [[refund-with-payment-channel-switch]]
- 退款时账户 Frozen → 走 [[force-close-refund]] 强制关并退

## 相关文档

- [[deposit-account-vs-transaction]]
- [[account-state-machine]]
- [[red-receipt-design]]
- [[refund-partial-after-forfeit]]
- [[close-after-zero-balance]]