From 461de616f1bdc0e02478433a37b89a7f6eabbd26 Mon Sep 17 00:00:00 2001 From: Willie Date: Mon, 25 May 2026 22:09:51 +0800 Subject: [PATCH] =?UTF-8?q?deposit=20=E5=AD=90=E6=A8=A1=E5=9D=97=20=C2=B7?= =?UTF-8?q?=20=E8=BD=AE=201:6=20=E6=A6=82=E5=BF=B5=20+=20=E7=9F=A5?= =?UTF-8?q?=E8=AF=86=E5=9C=B0=E5=9B=BE=20+=20=E5=AF=BC=E8=88=AA=E6=9B=B4?= =?UTF-8?q?=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 写 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) --- .../deposit/deposit-vs-adhoc-vs-prepaid.md | 150 ++++++++++++++++++ prop-acc/index.md | 2 +- prop-acc/maps/deposit-knowledge-map.md | 125 +++++++++++++++ prop-acc/maps/knowledge-map.md | 2 +- 4 files changed, 277 insertions(+), 2 deletions(-) create mode 100644 prop-acc/concepts/deposit/deposit-vs-adhoc-vs-prepaid.md create mode 100644 prop-acc/maps/deposit-knowledge-map.md diff --git a/prop-acc/concepts/deposit/deposit-vs-adhoc-vs-prepaid.md b/prop-acc/concepts/deposit/deposit-vs-adhoc-vs-prepaid.md new file mode 100644 index 0000000..83ab639 --- /dev/null +++ b/prop-acc/concepts/deposit/deposit-vs-adhoc-vs-prepaid.md @@ -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]] diff --git a/prop-acc/index.md b/prop-acc/index.md index 2d3e27f..a3e09e6 100644 --- a/prop-acc/index.md +++ b/prop-acc/index.md @@ -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 场景待补 | | **预存款** | 业户预存,自动抵扣月度账单 | _待补_ | 🚧 | | **计量表** | 水表/电表/燃气表,抄表生成账单 | _待补_ | 🚧 | | **账单** | 周期性账单 + 计量账单 | _待补_ | 🚧 | diff --git a/prop-acc/maps/deposit-knowledge-map.md b/prop-acc/maps/deposit-knowledge-map.md new file mode 100644 index 0000000..e9ec073 --- /dev/null +++ b/prop-acc/maps/deposit-knowledge-map.md @@ -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 个场景文档,基于本知识地图骨架填充。 diff --git a/prop-acc/maps/knowledge-map.md b/prop-acc/maps/knowledge-map.md index e91a6d4..81f3b26 100644 --- a/prop-acc/maps/knowledge-map.md +++ b/prop-acc/maps/knowledge-map.md @@ -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 | 收款订单 | 一次收款的支付方式、银行账户记录 | _待补_ | 🚧 |