vault backup: 2026-05-25 22:57:50

prop-acc/concepts/prepaid/prepaid-account-vs-transaction.md

@@ -0,0 +1,148 @@
+---
+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]]