131 lines
6.4 KiB
Markdown
131 lines
6.4 KiB
Markdown
|
---
|
||
|
|
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 篇,**待补充 ✋**)
|
||
|
|
|
||
|
|
> 🚧 概念骨架已就位,场景文档将在下一轮(轮 2)产出。预定结构如下。
|
||
|
|
|
||
|
|
### 📥 充值(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)
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
> [!info] 概念已完成,场景待补
|
||
|
|
> 本轮(轮 1)产出:6 个概念 + 本子模块地图 + 域总图更新。
|
||
|
|
> 下一轮(轮 2)产出:16 个场景文档,基于本知识地图骨架填充。
|