---
title: prop-acc · deposit · 知识地图
aliases:
  - deposit 知识地图
  - 保证金知识地图
  - 押金知识地图
tags:
  - 规范
  - prop-acc
  - 知识地图
  - 保证金
sub_feature: deposit
audience:
  - 业户
  - 业务人员
  - 财务
status: 已发布
last_review: 2026-05-25
code_version: 2026-05-22
---

# 保证金(deposit)知识地图

> 本子模块 = DepositAccount + DepositTransaction。覆盖物业代为保管的押金(装修保证金、入驻押金等)的开户、缴款、退款、扣罚、冻结、关账、强制关账等全套生命周期。

## 这是什么?

业户/装修方/供应商**先交一笔钱**给物业代为保管,等事情结束(装修完、租约满、合同执行完)再退还。中途如果发生损坏或违约,物业可扣除。这就是**保证金 / 押金**。

> [!warning] 押金不是收入!
> 业户交的 5,000 装修押金,**不算物业收入**,是物业代为保管的钱。会计科目记入"其他应付款"(负债),不进收入。
>
> 这条原则决定了所有设计:必须有独立账户 + 完整流水台账 + 红字凭证(退款扣罚),不能像一次性收费那样"一笔进账完事"。

## 核心概念(6 篇)

| 文档 | 一句话 |
|---|---|
| [押金账户与押金流水](../concepts/deposit/deposit-account-vs-transaction.md) | 双对象模式:账户记余额状态,流水记每笔历史 |
| [账户状态机](../concepts/deposit/account-state-machine.md) | Active / Frozen / Closed 三状态,Frozen 严格冻结 |
| [缴款人类型](../concepts/deposit/payer-types.md) | 6 种(业主/租户/装修承包商/装修公司/供应商/其他)及业户账户 vs 三方账户 |
| [流水类型](../concepts/deposit/transaction-types.md) | 3 种合法流水(deposit/refund/forfeiture),已弃用 adjustment 的设计取舍 |
| [红字凭证设计](../concepts/deposit/red-receipt-design.md) | 退款扣罚走红字 CollectionOrder + Receipt,而非新增枚举 |
| [押金 vs 一次性收费 vs 预存款](../concepts/deposit/deposit-vs-adhoc-vs-prepaid.md) | 三个子模块的会计本质区别(收入 vs 预收 vs 代管) |

## 场景手册(18 篇,**待补充 ✋**)

> 🚧 概念骨架已就位,场景文档将在下一轮产出。预定结构如下。

### 📥 缴纳(Deposit)— 3 篇

- 🚧 [装修业户首次缴 5,000 保证金](../scenarios/deposit/deposit-first-time-renovation.md)
- 🚧 [已有账户后续追加缴款](../scenarios/deposit/deposit-additional-topup.md)
- 🚧 [装修公司代业户缴纳](../scenarios/deposit/deposit-on-behalf-by-company.md)

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

- 🚧 [装修完无损全额退还](../scenarios/deposit/refund-full-no-damage.md)
- 🚧 [部分扣罚后退还差额](../scenarios/deposit/refund-partial-after-forfeit.md)
- 🚧 [退款渠道与缴款渠道不同](../scenarios/deposit/refund-with-payment-channel-switch.md)

### ⚠️ 扣罚(Forfeiture)— 2 篇

- 🚧 [损坏公共走道墙面扣 800](../scenarios/deposit/forfeit-damage-public-area.md)
- 🚧 [未申请直接动工违约扣罚](../scenarios/deposit/forfeit-violation-no-permit.md)

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

- 🚧 [业户纠纷期间冻结账户](../scenarios/deposit/freeze-during-dispute.md)
- 🚧 [调解结束后解冻](../scenarios/deposit/unfreeze-after-mediation.md)

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

- 🚧 [余额清零自动关闭](../scenarios/deposit/close-after-zero-balance.md)
- 🚧 [主动关账(已无业务往来)](../scenarios/deposit/close-manual-with-zero-balance.md)

### 🚨 强制关账(ForceClose)— 3 篇

> 解决 "Frozen + 有余额 + 想关账" 的设计困境。三种 disposition 对应不同业务出口。

- 🚧 [冻结状态强制全退并关账](../scenarios/deposit/force-close-refund.md)
- 🚧 [冻结状态强制全扣并关账](../scenarios/deposit/force-close-forfeit.md)
- 🚧 [法律保留期 / 业户失联,资金保留并关账](../scenarios/deposit/force-close-retain.md)

### 🛡️ 异常 / 审计 / 配置 — 3 篇

- 🚧 [冻结账户尝试缴款被守护拦截](../scenarios/deposit/exception-deposit-on-frozen.md)
- 🚧 [月度押金账户余额对账](../scenarios/deposit/audit-monthly-deposit-balance.md)
- 🚧 [长期未关账户排查](../scenarios/deposit/audit-long-pending-accounts.md)

## 跨域引用

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

- [业户](../../cross/concepts/resident.md) — Owner / Tenant 类型的缴款人主体
- [房屋单元](../../cross/concepts/housing-unit.md) — `asset_id`,装修押金通常与具体房屋关联
- [组织结构](../../cross/concepts/org-hierarchy.md) — `community_id`,物业项目归属
- [角色与权限](../../cross/concepts/role-permission.md) — `DepositAccountPolicy` 权限模型

## 跨子模块引用

- [adhoc · CollectionOrder 与 Receipt](../concepts/adhoc/collection-order-and-receipt.md) — 押金流水复用相同凭证模型,退款走红字
- [adhoc · AdHocEvent 状态机](../concepts/adhoc/event-state-machine.md) — 对比:adhoc 状态机 vs deposit 状态机

## 相关代码

- 模型:[`packages/prop-acc/src/Models/DepositAccount.php`](../../../packages/prop-acc/src/Models/DepositAccount.php)、[`DepositTransaction.php`](../../../packages/prop-acc/src/Models/DepositTransaction.php)
- 枚举:`DepositAccountStatus`、`DepositPayerType`、`DepositTransactionType`、`FundSource`
- Policy:`DepositAccountPolicy`、`DepositTransactionPolicy`
- Actions(业务层):`packages/prop-acc/src/Actions/Deposits/`(`DepositIntoAccountAction` / `RefundFromDepositAccountAction` / `ForfeitFromDepositAccountAction` / `ForceCloseDepositAccountAction`)
- Filament Resource:[`packages/prop-acc/src/Filament/Resources/DepositAccounts/`](../../../packages/prop-acc/src/Filament/Resources/DepositAccounts/)
- 业务设计决策:`packages/prop-acc/issue.md` 的 Q3 段

## 相关文档

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

---

> [!info] 概念已完成,场景待补
> 本轮(轮 1)产出:6 个概念 + 本子模块地图 + 域总图更新。
> 下一轮(轮 2)产出:18 个场景文档,基于本知识地图骨架填充。