deposit 子模块 · 轮 1:6 概念 + 知识地图 + 导航更新
写 6 个核心概念到 prop-acc/concepts/deposit/: - deposit-account-vs-transaction:账户(余额状态)+ 流水(不可变历史)双对象模式 - account-state-machine:Active / Frozen / Closed 三状态机,canDeposit/canWithdraw 守护 - payer-types:6 种缴款人(Owner/Tenant/Contractor/Company/Supplier/Other),业户账户 vs 三方账户 - transaction-types:3 种合法流水(deposit/refund/forfeiture),已弃用 adjustment 的审计取舍 - red-receipt-design:退款扣罚走红字 CollectionOrder + Receipt(金额正负 vs 新枚举) - deposit-vs-adhoc-vs-prepaid:三个子模块会计本质区别(收入 / 预收 / 代管) 新建子模块知识地图: - prop-acc/maps/deposit-knowledge-map.md:6 概念入口 + 18 场景预占清单 + 跨域引用 + 代码索引 更新导航: - prop-acc/index.md:七大子模块表保证金行,链 deposit 知识地图,状态 🟡 - prop-acc/maps/knowledge-map.md:域总图同步 下一轮:18 个场景文档(deposit/scenarios/),按本知识地图骨架填充。 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Willie
150
prop-acc/concepts/deposit/deposit-vs-adhoc-vs-prepaid.md
Normal file
150
prop-acc/concepts/deposit/deposit-vs-adhoc-vs-prepaid.md
Normal file
@@ -0,0 +1,150 @@
|
||||
---
|
||||
title: prop-acc · deposit · 押金 vs 一次性收费 vs 预存款
|
||||
aliases:
|
||||
- 押金 vs 一次性收费 vs 预存款
|
||||
- 三种业户给钱的本质区别
|
||||
- deposit vs adhoc vs prepaid
|
||||
tags:
|
||||
- 概念
|
||||
- prop-acc
|
||||
- 保证金
|
||||
- 跨子模块对比
|
||||
audience:
|
||||
- 业户
|
||||
- 业务人员
|
||||
- 财务
|
||||
status: 已发布
|
||||
sub_feature: deposit
|
||||
last_review: 2026-05-25
|
||||
code_version: 2026-05-22
|
||||
---
|
||||
|
||||
# 押金 vs 一次性收费 vs 预存款
|
||||
|
||||
三个看似都是"业户给钱"的子模块,**会计本质完全不同**。本文说明何时用哪个,以及为什么不能合并。
|
||||
|
||||
## 一句话区别
|
||||
|
||||
| 子模块 | 业户给钱的性质 | 钱属于谁 | 何时该用 |
|
||||
|---|---|---|---|
|
||||
| **adhoc(一次性收费)** | 物业**收入** | 物业 | 业户买东西/服务,钱归物业 |
|
||||
| **prepaid(预存款)** | 物业**预收账款**(负债) | 业户(未使用前) | 业户先存,以后抵扣账单 |
|
||||
| **deposit(保证金)** | 物业**其他应付款**(负债) | 业户(代管中) | 业户交给物业代为保管,迟早要还(全退或扣损还差) |
|
||||
|
||||
## 核心差异图
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
subgraph "adhoc 一次性收费(收入)"
|
||||
A1[业户付 30 买 IC 卡] --> A2[钱进物业账户]
|
||||
A2 --> A3[计入收入科目]
|
||||
A3 --> A4[完成,业户拿货走人]
|
||||
end
|
||||
|
||||
subgraph "prepaid 预存款(预收)"
|
||||
B1[业户预存 5000] --> B2[钱进物业账户但**记为负债**]
|
||||
B2 --> B3[每月账单出来时,从预存款扣]
|
||||
B3 --> B4[扣的部分才进收入,余额仍是负债]
|
||||
end
|
||||
|
||||
subgraph "deposit 保证金(代管)"
|
||||
C1[业户交 5000 装修押金] --> C2[钱进物业账户但**记为负债**]
|
||||
C2 --> C3{装修结束}
|
||||
C3 -->|无损坏| C4[退回 5000,清账]
|
||||
C3 -->|有损坏 800| C5[扣 800 进收入,退 4200,清账]
|
||||
end
|
||||
```
|
||||
|
||||
## 字段层面的差异
|
||||
|
||||
| 维度 | adhoc | prepaid | deposit |
|
||||
|---|---|---|---|
|
||||
| **主表** | `acc_ad_hoc_events` | `acc_prepaid_accounts` | `acc_deposit_accounts` |
|
||||
| **流水表** | `acc_collection_orders` + `acc_receipts`(一次性) | `acc_prepaid_transactions` | `acc_deposit_transactions` |
|
||||
| **账户对象** | 无(每笔独立) | `PrepaidAccount`(余额状态) | `DepositAccount`(余额状态 + 三状态机) |
|
||||
| **是否可冻结** | N/A | N/A | ✅ Frozen 状态 |
|
||||
| **退款机制** | [[adhoc-void-after-payment]](作废原单) | 提现 / 转账(待补具体场景) | 红字 CollectionOrder([[red-receipt-design]]) |
|
||||
| **会计科目** | 收入 | 预收账款 | 其他应付款 |
|
||||
| **凭证(Receipt)** | 单笔正数 | 充值正数,扣减不出 Receipt(在账单上体现) | 缴款正数 / 退款扣罚负数(红字) |
|
||||
|
||||
## 业务判定:某场景该归哪个?
|
||||
|
||||
**判定三连问**:
|
||||
|
||||
1. **"这笔钱以后要不要还给业户?"**
|
||||
- 不还 → adhoc(收入)
|
||||
- 要还 → 看下一题
|
||||
2. **"业户是为'以后买什么'存的,还是为'万一坏了赔'存的?"**
|
||||
- 以后买东西 → prepaid(预收)
|
||||
- 担保不出事 → deposit(押金)
|
||||
3. **"如果业户不出事,钱原额回去吗?"**
|
||||
- 是(原额回) → deposit
|
||||
- 否(用完才退余) → prepaid
|
||||
|
||||
### 边界场景举例
|
||||
|
||||
> [!question] "充电桩电费充值"是哪种?
|
||||
>
|
||||
> **理论上是 prepaid**(预存抵扣)。但本系统提供了简化版本走 [[adhoc-flow-a-counter-ev-charging-topup]] —— 把它当一次性"购买充电码"卖,业户充值码自己输入。
|
||||
>
|
||||
> 严格说,长期需要"逐次扣减、随时查余额"的应该走 prepaid 模块(待补)。
|
||||
|
||||
> [!question] "泳票套票(夏季 10 次)"是哪种?
|
||||
>
|
||||
> **理论上是 prepaid**(预付 10 次)。但目前作为 adhoc 处理:业户一次买 10 张泳票,系统一次出 10 张。
|
||||
>
|
||||
> 等业务需要"实时显示剩余次数"时再迁到 prepaid。
|
||||
|
||||
> [!question] "装修押金"为什么不是 prepaid?
|
||||
>
|
||||
> 因为押金**不抵扣账单**,只用来"押到事情结束"。无损则原退,有损则扣差。这是担保性质,不是预付性质。
|
||||
|
||||
## 业户视角
|
||||
|
||||
> [!example] 业户王先生的某月账单
|
||||
>
|
||||
> 王先生这个月的财务往来:
|
||||
> - **3 月 1 日**:小区门禁卡丢了,前台补办 → ¥30(**adhoc 收入**)
|
||||
> - **3 月 15 日**:为方便每月免到柜台缴,预存 ¥5,000 到账户 → ¥5,000(**prepaid 预收**)
|
||||
> - **4 月 1 日**:物业费账单 ¥1,200 出账,自动从预存款扣 → 预存款余额变 ¥3,800
|
||||
> - **3 月 20 日**:开始装修,交 ¥5,000 装修保证金 → ¥5,000(**deposit 代管**)
|
||||
> - **5 月 30 日**:装修完无损,押金原额退 → ¥-5,000(**deposit 红字**)
|
||||
>
|
||||
> 三种钱**走不同账本、不同凭证、不同退款机制**。业户拿到的收据上能区分:
|
||||
> - adhoc 收据:`门禁卡 ¥30`
|
||||
> - prepaid 收据:`预存款充值 ¥5,000`
|
||||
> - deposit 收据(缴款):`装修保证金缴纳 ¥5,000`
|
||||
> - deposit 收据(退款):`装修保证金退还 ¥-5,000` ← 红字
|
||||
|
||||
## 业务人员视角
|
||||
|
||||
后台菜单也是三个独立入口:
|
||||
|
||||
```
|
||||
prop-acc/
|
||||
├── 一次性收费(AdHocEvent)
|
||||
├── 预存款(PrepaidAccount) ← 待补
|
||||
└── 保证金(DepositAccount)
|
||||
```
|
||||
|
||||
每个有自己的资源(Filament Resource)、自己的列表/详情/操作。**不要试图在一个地方处理三种业务** —— 字段、状态、凭证、操作权限都不一样。
|
||||
|
||||
## 财务视角
|
||||
|
||||
月底关账时:
|
||||
|
||||
| 科目 | 来源 | 余额方向 |
|
||||
|---|---|---|
|
||||
| 收入 | `SUM(adhoc completed CO actual_amount)` + `SUM(prepaid 已扣减部分)` + `SUM(deposit forfeiture 进收入部分)` | 贷方(正) |
|
||||
| 预收账款 | `SUM(prepaid 未抵扣余额)` | 贷方(负债) |
|
||||
| 其他应付款 | `SUM(deposit balance)` | 贷方(负债) |
|
||||
|
||||
押金账户和预存款账户的**总余额**就是物业**应还给业户的钱**,必须能与银行账户里"对应代管资金"对账平衡。详见 [[audit-monthly-deposit-balance]]。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [[deposit-account-vs-transaction]]
|
||||
- [[transaction-types]]
|
||||
- [[collection-order-and-receipt]]
|
||||
- [[adhoc-flow-a-vs-flow-b]]
|
||||
- [[audit-monthly-deposit-balance]]
|
||||
@@ -24,7 +24,7 @@ last_review: 2026-05-25
|
||||
| 子模块 | 一句话 | 深度地图 | 状态 |
|
||||
|---|---|---|---|
|
||||
| **一次性收费** | IC 卡、装修证、泳票等单次购买 | [adhoc 知识地图](maps/adhoc-knowledge-map.md) | ✅ 28 篇 |
|
||||
| **保证金** | 装修押金等代管资金,完工后退还 | _待补_ | 🚧 |
|
||||
| **保证金** | 装修押金等代管资金,完工后退还 | [deposit 知识地图](maps/deposit-knowledge-map.md) | 🟡 6 概念已完成,18 场景待补 |
|
||||
| **预存款** | 业户预存,自动抵扣月度账单 | _待补_ | 🚧 |
|
||||
| **计量表** | 水表/电表/燃气表,抄表生成账单 | _待补_ | 🚧 |
|
||||
| **账单** | 周期性账单 + 计量账单 | _待补_ | 🚧 |
|
||||
|
||||
125
prop-acc/maps/deposit-knowledge-map.md
Normal file
125
prop-acc/maps/deposit-knowledge-map.md
Normal file
@@ -0,0 +1,125 @@
|
||||
---
|
||||
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 个场景文档,基于本知识地图骨架填充。
|
||||
@@ -21,7 +21,7 @@ last_review: 2026-05-25
|
||||
|---|---|---|---|---|
|
||||
| adhoc | 一次性收费 | IC 卡、装修证、泳票等单次购买 | [adhoc 知识地图](adhoc-knowledge-map.md) | ✅ 25 场景 + 3 概念 |
|
||||
| prepaid | 预存款 | 业户预存,自动抵扣月度账单 | _待补_ | 🚧 |
|
||||
| deposit | 保证金 | 装修押金等代管资金,完工后退还 | _待补_ | 🚧 |
|
||||
| deposit | 保证金 | 装修押金等代管资金,完工后退还 | [deposit 知识地图](deposit-knowledge-map.md) | 🟡 6 概念已完成,18 场景待补 |
|
||||
| meter | 计量表 | 水表/电表/燃气表,抄表生成账单 | _待补_ | 🚧 |
|
||||
| billing | 账单 | 周期性账单 + 计量账单 | _待补_ | 🚧 |
|
||||
| payment-order | 收款订单 | 一次收款的支付方式、银行账户记录 | _待补_ | 🚧 |
|
||||
|
||||
Reference in New Issue
Block a user