156 lines
5.3 KiB
Markdown
156 lines
5.3 KiB
Markdown
|
---
|
||
|
|
title: prop-acc · prepaid · 预存款账户状态机
|
||
|
|
aliases:
|
||
|
|
- 预存款账户状态机
|
||
|
|
- PrepaidAccount 状态机
|
||
|
|
- canOperate
|
||
|
|
tags:
|
||
|
|
- 概念
|
||
|
|
- prop-acc
|
||
|
|
- 预存款
|
||
|
|
- 状态机
|
||
|
|
audience:
|
||
|
|
- 业户
|
||
|
|
- 业务人员
|
||
|
|
status: 已发布
|
||
|
|
sub_feature: prepaid
|
||
|
|
last_review: 2026-05-25
|
||
|
|
code_version: 2026-05-22
|
||
|
|
---
|
||
|
|
|
||
|
|
# 预存款账户状态机
|
||
|
|
|
||
|
|
预存款账户三种状态:**Active(可用)** / **Frozen(冻结)** / **Closed(已关闭)**。状态机骨架与 [[../deposit/account-state-machine|押金账户]]相同,但有两条**重要差异**:
|
||
|
|
|
||
|
|
1. **零余额不自动关账** —— 业户可以继续充值复用账户
|
||
|
|
2. **没有 ForceClose** —— 一户一账 + 预存款纠纷罕见,不需要 deposit 那种 Frozen + 有余额的解困出口
|
||
|
|
|
||
|
|
## 三状态速查
|
||
|
|
|
||
|
|
| 状态 | 中文 | 何时进入 | 能做什么 |
|
||
|
|
|---|---|---|---|
|
||
|
|
| `Active` | 可用 | 新账户首次充值后 | 充值 / 消费 / 退款 / 冻结 / 关账(主动)|
|
||
|
|
| `Frozen` | 冻结 | 风控、欺诈嫌疑、内审等 | 看流水(只读)/ 解冻 |
|
||
|
|
| `Closed` | 已关闭 | 业户搬走 / 主动关账 / 长期失联归档 | 看流水(只读)|
|
||
|
|
|
||
|
|
## 状态机图
|
||
|
|
|
||
|
|
```mermaid
|
||
|
|
stateDiagram-v2
|
||
|
|
[*] --> Active : 开户 + 首次充值
|
||
|
|
Active --> Active : 充值 / 消费 / 退款(任意次数,余额可清零回升)
|
||
|
|
Active --> Frozen : freeze() 风控
|
||
|
|
Frozen --> Active : reactivate() 等同解冻
|
||
|
|
Active --> Closed : close() 业户搬走等
|
||
|
|
Closed --> [*]
|
||
|
|
|
||
|
|
note right of Active
|
||
|
|
余额 0 时不自动关账
|
||
|
|
业户可继续充值复用
|
||
|
|
end note
|
||
|
|
|
||
|
|
note right of Frozen
|
||
|
|
冻结期间禁止任何资金动作
|
||
|
|
canOperate = false
|
||
|
|
end note
|
||
|
|
|
||
|
|
note left of Closed
|
||
|
|
永久终态
|
||
|
|
新业务请开新账户
|
||
|
|
(开新账户会撞一户一账约束 —— 业务上需要重新审视)
|
||
|
|
end note
|
||
|
|
```
|
||
|
|
|
||
|
|
## 守护方法
|
||
|
|
|
||
|
|
| 方法 | 返回 true 的状态 | 用途 |
|
||
|
|
|---|---|---|
|
||
|
|
| `canOperate()` | Active **only** | 统一守护:deposit / consume / refund 都调 |
|
||
|
|
| `hasBalance()` | balance > 0 | 配合判断"账户有钱"语义 |
|
||
|
|
| `isClosed()` | status == Closed | 给 UI / Policy 判断用 |
|
||
|
|
|
||
|
|
> [!info] canOperate 是模型层的最严防御
|
||
|
|
> 与 deposit 的 `canDeposit` / `canWithdraw` 二分不同,prepaid 用**统一** `canOperate()` —— 因为预存款的所有资金动作(充值 / 消费 / 退款)在 Frozen 状态下都要拒绝,没有"只能加不能减"的中间逻辑。
|
||
|
|
>
|
||
|
|
> 这条规则的实施有**三层兜底**(同 deposit):
|
||
|
|
> - UI 层:Filament Action 的 `visible` 用 `canOperate()`
|
||
|
|
> - Policy 层:`PrepaidAccountPolicy::deposit / consume / refund` 各自检查状态
|
||
|
|
> - **模型层(最严)**:`PrepaidAccount::deposit() / consume() / refund()` 内置 `canOperate()` 检查
|
||
|
|
>
|
||
|
|
> 即使 Filament / Policy 全部绕过(tinker、artisan、第三方调用),模型方法仍会抛错。详见 [[exception-refund-on-frozen]] "三层守护" 段。
|
||
|
|
|
||
|
|
## 与 deposit 状态机的关键差异
|
||
|
|
|
||
|
|
### 差异 1:零余额不自动关账
|
||
|
|
|
||
|
|
deposit:
|
||
|
|
|
||
|
|
```
|
||
|
|
balance > 0 ─ refund/forfeit ──→ balance == 0 ──自动──→ Closed
|
||
|
|
```
|
||
|
|
|
||
|
|
prepaid:
|
||
|
|
|
||
|
|
```
|
||
|
|
balance > 0 ─ consume/refund ──→ balance == 0 ──不自动关──→ Active(可继续充值)
|
||
|
|
```
|
||
|
|
|
||
|
|
为什么 prepaid 不自动关?
|
||
|
|
|
||
|
|
| 理由 | 解释 |
|
||
|
|
|---|---|
|
||
|
|
| 一户一账 | 关了再开会撞 unique 约束;关掉是浪费 |
|
||
|
|
| 业户长期使用 | 预存款是"我以后用"的账户,余额清零只意味着这一轮用完,可以继续充 |
|
||
|
|
| 业务高频 | 业户可能下周又充值,频繁开关账户毫无意义 |
|
||
|
|
| Bill 关联 | 关账后再有未付账单,业户充值无处去 |
|
||
|
|
|
||
|
|
deposit 自动关是因为:
|
||
|
|
|
||
|
|
| 理由 | 解释 |
|
||
|
|
|---|---|
|
||
|
|
| 业务完结 | 押金交完 → 装修完 → 退或扣 → 业务结束 |
|
||
|
|
| 多账户合理 | 业户可以同时有装修押金、入驻押金、设备押金多个账户 |
|
||
|
|
|
||
|
|
### 差异 2:没有 ForceClose
|
||
|
|
|
||
|
|
[[../deposit/account-state-machine|押金账户]]有 ForceClose 解决"Frozen + 有余额 + 想关账"的困境。预存款**没有**这个机制,因为:
|
||
|
|
|
||
|
|
- 一户一账,纠纷场景罕见(业户与自己的钱一般不打架)
|
||
|
|
- 真要关 Frozen 账户:先 [[unfreeze-after-verification|解冻]] → [[refund-full-resident-moveout|退余]] → 关账
|
||
|
|
- 业务方实际遇到再实现(issue.md Q4 "待补"段已记录)
|
||
|
|
|
||
|
|
## ReactivateAccountAction = 解冻
|
||
|
|
|
||
|
|
历史代码里有个 `ReactivateAccountAction`,字面意思"重新激活"。**实际行为只允许 Frozen → Active**(等同解冻),不允许 Closed → Active(那条永久禁止,同 deposit)。
|
||
|
|
|
||
|
|
UI 文案已统一为"解冻"(图标 `lock-open`),与 deposit 模块对齐。
|
||
|
|
|
||
|
|
> [!warning] 不要被名字误导
|
||
|
|
> "Reactivate" 字面给人"撤销关账"的暗示,实际**做不到**。Policy 守护 + UI visible 都只在 `status === Frozen` 时显示。
|
||
|
|
|
||
|
|
## 业务人员视角
|
||
|
|
|
||
|
|
后台账户列表的"状态"列对应三个值:
|
||
|
|
|
||
|
|
- 看到 `Active`:绿色,所有操作可用
|
||
|
|
- 看到 `Frozen`:橙色,所有写入按钮变灰,只剩 `ReactivateAccountAction`
|
||
|
|
- 看到 `Closed`:灰色,完全只读
|
||
|
|
|
||
|
|
## 业户视角
|
||
|
|
|
||
|
|
业户感受不到状态机内部,只感受到:
|
||
|
|
|
||
|
|
- 余额能正常用 → Active
|
||
|
|
- 充值 / 抵扣失败,提示"账户冻结中" → Frozen
|
||
|
|
- 账户已关 → 无法再充值 / 抵扣,看流水可
|
||
|
|
|
||
|
|
## 相关文档
|
||
|
|
|
||
|
|
- [[prepaid-account-vs-transaction]]
|
||
|
|
- [[transaction-types]]
|
||
|
|
- [[freeze-suspected-fraud]]
|
||
|
|
- [[unfreeze-after-verification]]
|
||
|
|
- [[close-with-zero-balance-decision]]
|
||
|
|
- [[exception-refund-on-frozen]]
|
||
|
|
- [[../deposit/account-state-machine]]
|