5.7 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 |
场景:已有账户后续追加缴款
业户已经有一个 Active 状态的押金账户,现在要追加缴款(扩大装修范围 / 押金标准提升 / 分期补齐)。比首次开户简单 —— 不重建账户,只加流水。
典型情境
[!example] 真实情境 张阿姨家原来交了 ¥3,000 装修保证金。装修过程中她决定多动一面承重墙,物业要求她补 ¥2,000 押金(高风险装修加押)。第二天她到前台补缴。
业户视角
第 1 步:到前台 / 小程序
带身份证(部分物业要求)到前台,告诉职员:
"我要给装修押金账户补 ¥2,000。"
第 2 步:付款
同 deposit-first-time-renovation:现金 / 微信 / POS / 银行转账。
第 3 步:拿收据
新收据"装修保证金缴纳 ¥2,000"。
[!info] 您账户里现在有多少? 旧 ¥3,000 + 新 ¥2,000 = ¥5,000。下次退押时按这个总数算。
业务人员视角
[!info] 与首次缴款的关键差异 不开新账户,在既有账户上加缴款流水。如果误开新账户,会出现两个并行账户,退款时一笔退不清,业户会困惑。
第 1 步:找到既有账户
后台 → 保证金 → 账户列表 → 按业户姓名 / 房号 / 缴款人姓名搜索 → 找到 Active 账户。
第 2 步:进入账户详情(ViewDepositAccount)
详情页右上角的状态管理组里点 DepositAction 按钮(标签"追加缴款")。
[!warning] 按钮可能灰化 仅当账户
status=Active时可点。Frozen / Closed 状态下灰化。详见 account-state-machine 的canDeposit()守护。
第 3 步:Modal 表单
| 字段 | 填什么 |
|---|---|
| 缴款金额 | ¥2,000 |
| 支付方式 | 现金 / 微信 / POS / 银行转账 |
| 收款银行账户 | 微信/POS/转账选对应银行 |
| 备注 | 选填,如 "动承重墙加押" |
第 4 步:提交
系统调用业务层 DepositIntoAccountAction,在事务内:
- 校验账户
canDeposit()(Active only) - 建
CollectionOrder(actual_amount=+2000,status=Completed) - 在既有账户上加
DepositTransaction(type=deposit,amount=2000,balance_before=3000,balance_after=5000,关联 CO) - 更新
DepositAccount.balance= 5000 - 触发
CollectionOrderCompleted→ Listener 自动建 Receipt
第 5 步:给收据
后台找到新生成的 Receipt(只对应这一笔追加),交给业户。
系统流程
sequenceDiagram
participant 业户
participant 前台
participant Filament
participant DepositIntoAccountAction
participant 数据库
participant 监听器
业户->>前台: 给押金账户加 2000
前台->>Filament: ViewDepositAccount → DepositAction(modal)
Filament->>DepositIntoAccountAction: handle(account, 2000, paymentChannel)
DepositIntoAccountAction->>DepositIntoAccountAction: canDeposit() ? (Active=true)
DepositIntoAccountAction->>数据库: 开启事务
DepositIntoAccountAction->>数据库: 1. 建 CollectionOrder (+2000, Completed)
DepositIntoAccountAction->>数据库: 2. 建 DepositTransaction (deposit, 3000→5000)
DepositIntoAccountAction->>数据库: 3. 更新 DepositAccount.balance=5000
DepositIntoAccountAction->>监听器: 4. 触发 CollectionOrderCompleted
监听器->>数据库: 5. 建 Receipt (装修保证金缴纳 ¥2,000)
DepositIntoAccountAction->>数据库: 提交事务
Filament-->>前台: 成功通知 + 刷新余额显示
前台->>业户: 给新收据
[!info] 一处代码,两处入口
DepositIntoAccountAction是两处调用方共用的业务 Action:
- 本场景(追加缴款):从
ViewDepositAccount→DepositAction触发- deposit-first-time-renovation:从
CreateDepositAccount表单触发未来若小程序在线缴款,也复用同一份。逻辑只写一遍。
常见问题
[!question] Frozen 账户能追加缴款吗? 不能。
canDeposit()只允许Active。Frozen 状态下按钮灰化,直接调 Action 会抛RuntimeException。这条规则比直觉更严:看上去"多存钱不亏",但实际风险是纠纷期间装修公司继续往受冻结账户灌钱,资金被困、责任更复杂。详见 account-state-machine "关键守护" 段。
[!question] Closed 账户呢? 同样不能。Closed 是永久终态,新业务请deposit-first-time-renovation。
[!question] 多次追加缴款,余额怎么算? 每笔
DepositTransaction都有balance_before和balance_after,账户balance字段也实时更新。任何时刻业户问"我现在有多少押金",看DepositAccount.balance即可。审计可重算SUM(deposit) - SUM(refund) - SUM(forfeiture)校验自洽。
[!question] 追加缴款的收据是单独一张还是合并到原收据? 单独一张。每笔
DepositTransaction对应一张独立的Receipt。这与"原单上挂退款标记"的反模式相反,详见 red-receipt-design "为什么不在原 CollectionOrder 上挂退款标记" 段。
[!question] 业户能在小程序自助追加缴款吗? 待补。当前 Action 假设手工操作(前台触发)。未来加小程序在线支付时,前端调同一个
DepositIntoAccountAction,只需多加一个支付回调入口。