---
title: prop-acc · prepaid · 预存款账户与流水
aliases:
  - 预存款账户与流水
  - PrepaidAccount 与 PrepaidTransaction
  - 预存款的双对象模式
tags:
  - 概念
  - prop-acc
  - 预存款
  - 核心概念
audience:
  - 业户
  - 业务人员
status: 已发布
sub_feature: prepaid
last_review: 2026-05-25
code_version: 2026-05-22
---

# 预存款账户与流水

预存款模块底层是**账户**(`PrepaidAccount`)+ **流水**(`PrepaidTransaction`)的双对象模式 —— 与 [[deposit-account-vs-transaction|押金的账户+流水]]同构。但预存款多了两条**独有的约束**:

1. **一户一账**(每社区每业户**最多一个**预存款账户)
2. **零余额不自动关账**(账户随时可继续充值,不像押金清零就 Closed)

详细差异见 [[deposit-vs-adhoc-vs-prepaid]]。

## 为什么也用双对象

> [!info] 类比:超市充值卡
> - **账户** = 卡面上的"当前余额 ¥1,500"
> - **流水** = 每次充值 + 每次消费的明细列表

业户充一笔(deposit)、消费抵账单(consume)、退余额(refund)—— 每一笔都需要可追溯。账户只记**当前余额**和**状态**,流水记**每一笔变动**。

## 字段速查

### PrepaidAccount(账户)

| 字段 | 含义 |
|---|---|
| `id` | 账户 ID |
| `community_id` | 所属物业项目 |
| `community_user_profile_id` | **业户档案 ID(必填,与 community_id 组合唯一)** |
| **`balance`** | **当前余额** |
| `status` | 账户状态(详见 [[account-state-machine]]) |
| `opened_at` | 开户时间 |
| `meta` | JSON 扩展字段 |

> [!warning] 一户一账约束
> `(community_id, community_user_profile_id)` **数据库唯一约束**,保证同业户在同社区不会有两个预存款账户。开户时违反这条会抛 unique violation。详见 [[one-account-per-resident]]。

### PrepaidTransaction(流水)

| 字段 | 含义 |
|---|---|
| `id` | 流水 ID |
| `prepaid_account_id` | 归属账户 |
| `type` | 流水类型(详见 [[transaction-types]]) |
| `amount` | 本笔金额(正数;refund 也是正数,方向由 type 表达) |
| `balance_before` | 本笔之前余额 |
| `balance_after` | 本笔之后余额 |
| `related_collection_order_id` | 关联收款单(deposit / consume / refund 都关联) |
| **`related_bill_id`** | **(consume 独有)关联被抵扣的账单** |
| `memo` | 备注 |
| `operated_by` | 操作员 ID |
| 创建后**不可变** | 一旦生成只读 |

## 与 deposit 的关键差异

| 维度 | DepositAccount | PrepaidAccount |
|---|---|---|
| 缴款人 | 多种(`payer_type`:业主/租户/装修公司/...) | **只能是业户本人** |
| 每业户账户数 | 多个(按 fee_type、按 asset) | **1 个**(每社区每业户) |
| 关联对象 | `fee_type_id`、`asset_id` 可选 | 只关联 `community_user_profile_id` |
| 核心写入操作 | deposit / refund / forfeiture(3 种) | **deposit / consume / refund / adjustment(4 种,consume 是高频)** |
| Bill 关联 | ❌ | ✅(consume 时通过 `related_bill_id`) |
| 零余额行为 | 自动关账(`canBeClosed()` 触发) | **不关**,可继续充值 |
| ForceClose | ✅(Frozen + 有余额 → 关账) | ❌(一户一账纠纷罕见,不需要) |

## 两者的契约

与 deposit 完全一致:**账户.balance 必须等于流水按时间累加的净值**。

```php
$account->verifyBalance();              // bool
$account->getBalanceDifference();        // float
$account->calculateBalanceFromTransactions();
```

`canOperate()` 守护所有写入(deposit / consume / refund 都调):

```php
public function canOperate(): bool
{
    return $this->status === PrepaidAccountStatus::Active;
}
```

Frozen / Closed 都不允许操作。这条由模型层兜底,即使 Action 类、Filament UI 全部绕过,模型方法 `deposit()` / `consume()` / `refund()` 内置 `canOperate()` 检查,任何调用方都跑不掉(详见 [[exception-refund-on-frozen]])。

## 资金流概览

```mermaid
flowchart LR
  A[业户充值 5000] -->|deposit| B[PrepaidAccount<br/>balance=5000]
  B -->|consume 抵账单 800| C[balance=4200<br/>Bill 状态翻 Paid]
  C -->|consume 抵账单 1200| D[balance=3000]
  D -->|refund 退余 3000| E[balance=0<br/>Active 仍可继续充值]
```

注意最后一步:**余额清零账户保持 Active**,不像 deposit 那样自动 Closed。理由见 [[account-state-machine]] "零余额不自动关账" 段。

## 业户视角

业户在小程序"我的预存款"看到:

```
账户余额:¥3,000.00     [+ 充值]

最近流水:
2026-05-15  -800.00    抵扣 物业费(5月)
2026-05-15  -1200.00   抵扣 水电费(5月)
2026-05-01  +5000.00   预存款充值
```

充值随时可做,余额可看,消费明细可追。

## 业务人员视角

后台 → 预存款 → 账户列表 → 找到业户的账户 → `ViewPrepaidAccount`。右侧"流水"标签是 `PrepaidTransaction` 列表(只读、按时间倒序)。

所有写入 Action(`DepositAction` / `ConsumeAction` / `RefundAction`):

- 同时写账户余额 + 流水 + CollectionOrder + Receipt(事务内)
- 任何只写一边的代码都是 bug
- 状态守护(`canOperate()`)在 Filament Action、Policy、模型方法三层都有

## 相关文档

- [[account-state-machine]]
- [[one-account-per-resident]]
- [[transaction-types]]
- [[consume-via-bill-collection-type]]
- [[deposit-vs-adhoc-vs-prepaid]]
- [[deposit-account-vs-transaction]]