uniprop-manual/prop-acc/maps/prepaid-knowledge-map.md

---
title: prop-acc · prepaid · 知识地图
aliases:
  - prepaid 知识地图
  - 预存款知识地图
tags:
  - 规范
  - prop-acc
  - 知识地图
  - 预存款
sub_feature: prepaid
audience:
  - 业户
  - 业务人员
  - 财务
status: 已发布
last_review: 2026-05-25
code_version: 2026-05-22
---

# 预存款(prepaid)知识地图

> 本子模块 = PrepaidAccount + PrepaidTransaction。覆盖业户**预存金额抵扣账单**的全生命周期 —— 充值、消费(月度账单自动抵)、退款、冻结、关账。

## 这是什么?

业户**提前充值**一笔钱到自己的预存款账户,后续物业费 / 水电费等账单**自动从这里扣**,免得月月手动缴。是物业财务系统的"业户钱包"。

> [!warning] 预存款不是收入,也不是押金 — 是预收账款
> 业户充进来的钱在抵扣账单**之前**,会计科目记**预收账款(负债)**,不进收入。每次抵扣账单时,**对应部分**才转入收入。
>
> 三种模块的会计性质对比详见 [adhoc 的 deposit-vs-adhoc-vs-prepaid 概念](../concepts/deposit/deposit-vs-adhoc-vs-prepaid.md)。

## 核心特性(与 deposit 的关键差异)

| 维度 | prepaid 预存款 | deposit 保证金 |
|---|---|---|
| 每业户账户数 | **1 个**(一户一账) | 多个 |
| 核心高频操作 | **consume**(自动抵账单) | refund / forfeiture |
| Bill 关联 | ✅(consume 关联具体账单) | ❌ |
| 零余额行为 | **保持 Active**(可继续充值) | 自动 Closed |
| ForceClose | ❌(纠纷罕见) | ✅ |
| 缴款人 | 只能是业户本人 | 多种(业主/租户/装修公司/...) |

## 核心概念(6 篇)

| 文档 | 一句话 |
|---|---|
| [预存款账户与流水](../concepts/prepaid/prepaid-account-vs-transaction.md) | 双对象模式,与 deposit 同构但多两条独有约束 |
| [账户状态机](../concepts/prepaid/account-state-machine.md) | Active / Frozen / Closed,canOperate 统一守护,零余额不自动关账 |
| [一户一账约束](../concepts/prepaid/one-account-per-resident.md) | unique(community_id, profile_id) + 跨社区防御 |
| [流水类型](../concepts/prepaid/transaction-types.md) | 4 种(deposit / consume / refund / adjustment),consume 是高频 |
| [Consume 走 CollectionType=Bill 的设计](../concepts/prepaid/consume-via-bill-collection-type.md) | 独特设计:抵账单用 Bill 视角,资金来源标 meta.fund_source=prepaid |
| [月初批量自动抵扣设计](../concepts/prepaid/auto-deduction-design.md) | 待补 scheduled job,产品核心卖点 |

## 场景手册(16 篇,**全部完成 ✅**)

### 📥 充值(Deposit)— 3 篇

- ✅ [首次开户充值 5000](../scenarios/prepaid/deposit-first-time.md)
- ✅ [已有账户追加充值](../scenarios/prepaid/deposit-additional-topup.md)
- ✅ [小程序在线充值(待补设计意图)](../scenarios/prepaid/deposit-via-miniapp-pending.md)

### 🧹 消费 Consume — 4 篇(最核心)

- ✅ [手动抵扣月度物业费](../scenarios/prepaid/consume-monthly-property-bill.md)
- ✅ [多个未付账单按 due_at 优先级抵扣](../scenarios/prepaid/consume-multiple-bills-priority.md)
- ✅ [抵扣计量账单(水电费)](../scenarios/prepaid/consume-meter-bill.md)
- ✅ [月初批量自动抵扣 job(设计意图 + 业务流程)](../scenarios/prepaid/consume-batch-auto-monthly.md)

### 💰 退款(Refund)— 2 篇

- ✅ [业户搬走全额退余](../scenarios/prepaid/refund-full-resident-moveout.md)
- ✅ [部分消费后退余(不自动关账)](../scenarios/prepaid/refund-partial-after-consume.md)

### 🧊 冻结 / 解冻(Freeze / Unfreeze)— 2 篇

- ✅ [疑似欺诈 / 风控冻结](../scenarios/prepaid/freeze-suspected-fraud.md)
- ✅ [核实后解冻](../scenarios/prepaid/unfreeze-after-verification.md)

### 🔒 结清(Close)— 2 篇

- ✅ [业户搬走主动关账](../scenarios/prepaid/close-resident-moveout.md)
- ✅ [余额清零后不自动关,业户决定](../scenarios/prepaid/close-with-zero-balance-decision.md)

### 🛡️ 异常 / 审计(3 篇)

- ✅ [跨社区消费防御](../scenarios/prepaid/exception-cross-community-consume.md)
- ✅ [冻结状态退款被三层守护拦截](../scenarios/prepaid/exception-refund-on-frozen.md)
- ✅ [低余额业户预警 + 逾期账单排查](../scenarios/prepaid/audit-low-balance-and-overdue.md)

## 跨域引用

本子模块引用以下跨域共享概念:

- [业户](../../cross/concepts/resident.md) — 缴款人(只能是业户本人)
- [组织结构](../../cross/concepts/org-hierarchy.md) — community_id 归属

## 跨子模块引用

- [adhoc · CollectionOrder 与 Receipt](../concepts/adhoc/collection-order-and-receipt.md) — prepaid 同样产出 CO + Receipt,但 consume 的 CO 用 type=Bill(详见本子模块独特设计)
- [deposit · 账户与流水](../concepts/deposit/deposit-account-vs-transaction.md) — 双对象模式同构,可对比理解
- [deposit · 状态机](../concepts/deposit/account-state-machine.md) — 三状态相同,关账行为不同
- [deposit · 押金 vs 一次性收费 vs 预存款](../concepts/deposit/deposit-vs-adhoc-vs-prepaid.md) — 三模块对比

## 相关代码

- 模型:[`PrepaidAccount.php`](../../../packages/prop-acc/src/Models/PrepaidAccount.php)、[`PrepaidTransaction.php`](../../../packages/prop-acc/src/Models/PrepaidTransaction.php)
- 枚举:`PrepaidAccountStatus`、`PrepaidTransactionType`、`FundSource`、`CollectionType`
- Policy:`PrepaidAccountPolicy`(9 个方法)、`PrepaidTransactionPolicy`
- Actions(业务层):`packages/prop-acc/src/Actions/Prepaids/`(`ConsumeFromPrepaidAccountAction` / `RefundFromPrepaidAccountAction`,**自动抵扣 job 待补**)
- Filament Resource:[`packages/prop-acc/src/Filament/Resources/PrepaidAccounts/`](../../../packages/prop-acc/src/Filament/Resources/PrepaidAccounts/)
- Dashboard / Widgets:`DepositPrepaidDashboard`、`MonthlyPrepaidFlowChart`、`LowBalancePrepaidListWidget`
- 业务设计决策:`packages/prop-acc/issue.md` 的 Q4 段

## 相关文档

- [prop-acc 域知识地图](knowledge-map.md)
- [prop-acc 域首页](../index.md)
- [adhoc 子模块知识地图](adhoc-knowledge-map.md)
- [deposit 子模块知识地图](deposit-knowledge-map.md)
- [跨域协作地图](../../cross/maps/cross-domain-map.md)

---

> [!success] prepaid 子模块:6 概念 + 16 场景 + 1 知识地图 = **23 篇完成**
>
> 写作日期:2026-05-25
> 对应代码版本:2026-05-22(详见 `packages/prop-acc/issue.md` Q4 段)
>
> 如果发现遗漏的场景或需要补充的细节,告诉我,可以单独补充新文档。