Vault/uniprop-manual

Fork 0

Files

Willie f407569771 vault backup: 2026-05-25 23:22:55

2026-05-25 23:22:55 +08:00

5.3 KiB

Raw Blame History

title, aliases, tags, audience, status, sub_feature, last_review, code_version

title

aliases

场景:已有账户追加充值

业户已有 Active 预存款账户,余额不够 / 想多存,继续充值。比首次开户简单 —— 不建账户,只加流水。

典型情境

[!example] 真实情境张阿姨 3 个月前充了 ¥5,000 预存款,期间扣了 ¥2,400(物业费 800 × 3),余额 ¥2,600。下个月还要扣 ¥800 + ¥600 水电费,觉得余额勉强够,再充 ¥3,000 凑个整。

业户视角

第 1 步:到前台 / 小程序

跟物业管家说"我预存账户加 ¥3,000"。

第 2 步:付款

支付方式同首次充值。

第 3 步:拿收据

"预付款充值 ¥3,000"。

第 4 步:余额查看

后台 / 小程序看到:

上次余额 ¥2,600 + 本次 ¥3,000 = 当前余额 ¥5,600
后续账单自动从这扣

业务人员视角

[!info] 与首次充值的差异 不开新账户,在既有账户上 DepositAction 加流水。

第 1 步:找到既有账户

后台 → 预存款 → 账户列表 → 按业户姓名 / 房号搜索 → 找到 Active 账户。

第 2 步:进 `ViewPrepaidAccount`

详情页右上角点 DepositAction(标签"充值")。

[!warning] 按钮可见性 DepositAction 守护:canOperate()(Active only)+ Policy ->authorize('deposit')。Frozen / Closed 灰化。

第 3 步:Modal 表单

字段	填什么
充值金额	¥3,000
支付方式	现金 / 微信 / POS / 银行转账
收款银行账户	微信/POS/转账选对应银行
备注	选填

第 4 步:提交

系统调 PrepaidAccount::deposit($amount, ...),事务内:

模型层校验 canOperate()(Active only)
建 CollectionOrder(type=Prepaid,actual=+3000,Completed)
建 PrepaidTransaction(type=deposit,amount=3000,balance_before=2600,balance_after=5600,关联 CO)
更新 PrepaidAccount.balance=5600
触发 CollectionOrderCompleted → Listener 建 Receipt"预付款充值 ¥3,000"

第 5 步:给收据

打印 / 发微信。

系统流程

sequenceDiagram
    participant 业户
    participant 前台
    participant Filament
    participant PrepaidAccount
    participant 数据库

    业户->>前台: 给预存账户加 3000
    前台->>Filament: ViewPrepaidAccount → DepositAction(modal)
    Filament->>PrepaidAccount: deposit(3000, ...)
    PrepaidAccount->>PrepaidAccount: canOperate()? Active=true
    PrepaidAccount->>数据库: 开启事务
    PrepaidAccount->>数据库: 1. 建 CO (Prepaid, +3000, Completed)
    PrepaidAccount->>数据库: 2. 建 PrepaidTransaction (deposit, 2600→5600)
    PrepaidAccount->>数据库: 3. 更新 balance=5600
    PrepaidAccount->>监听器: 触发 CollectionOrderCompleted
    监听器->>数据库: 建 Receipt (预付款充值 ¥3,000)
    PrepaidAccount->>数据库: 提交
    Filament-->>前台: 成功
    前台->>业户: 收据

流水台账(本场景在累计流水中的位置)

流水	type	amount	balance_before	balance_after	备注
1	deposit	5000	0	5000	3 个月前首次充值
2	consume	800	5000	4200	第 1 月物业费
3	consume	800	4200	3400	第 2 月物业费
4	consume	800	3400	2600	第 3 月物业费
5	deposit	3000	2600	5600	本次追加

常见问题

[!question] Frozen 账户能追加充值吗? 不能。canOperate() 只允许 Active。详见 exception-refund-on-frozen(deposit / consume / refund 都一样)。

如果业户硬要充:

系统层无法绕过(模型层兜底)

业务层 需先 unfreeze-after-verification → 再充

不可"暂存钱等解冻后录入" —— 不合规

[!question] Closed 账户能追加充值吗? 不能(同上)。需要开新账户,但一户一账约束阻塞(详见 one-account-per-resident "已知设计 gap")。

[!question] 同时多笔追加(一天充两次)可以吗? 可以。每次独立 Action,各自一笔 Transaction + CO + Receipt。账户 balance 累加。

[!question] 充值过多担心退不出来? 任何时候可走 refund-partial-after-consume 或 refund-full-resident-moveout 退余。预存款不像押金有"装修结束才能退"的业务节点,随时可退。

[!question] 业户问"我能用别人的微信付吗?" 系统不限制实际支付来源(微信扫码用谁付都行)。业务上:

账面缴款人是业户本人(PrepaidAccount.community_user_profile_id 不变)

实际付钱的是谁是业户自己的事

退款时只退给账面缴款人(业户本人),不是实际付钱的微信号

异常分支

业户从未充过 → 走 deposit-first-time 开户
充错金额 → refund-partial-after-consume
账户冻结 → 先 unfreeze-after-verification 解冻

5.3 KiB Raw Blame History Unescape Escape