6.8 KiB
title, aliases, tags, audience, status, sub_feature, last_review, code_version
| title | aliases | tags | audience | status | sub_feature | last_review | code_version | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| prop-acc · deposit · 场景 - 装修完无损全额退还 |
|
|
|
已发布 | deposit | 2026-05-25 | 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,事务内:
- 校验账户
canWithdraw()(Active only) - 校验金额 ≤ 当前余额
- 建
CollectionOrder(actual_amount=-5000红字,status=Completed) - 加
DepositTransaction(type=refund,amount=5000,balance_before=5000,balance_after=0,关联红字 CO) - 更新
DepositAccount.balance=0 - 余额清零自动关账 → 账户
status=Closed - 触发
CollectionOrderCompleted→ Listener 建红字 Receipt"装修保证金退还 ¥-5,000"
第 5 步:走线下退款流程
- 微信 / POS 退款:在对应支付网关后台操作
- 银行转账:导出回款指令交银行
- 现金退款(罕见):张阿姨到前台领现金
第 6 步:把红字收据交给张阿姨
后台找到红字 Receipt → 打印 / 发微信。
系统流程
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 强制关并退