diff --git a/prop-acc/index.md b/prop-acc/index.md index ba78a63..8b5718f 100644 --- a/prop-acc/index.md +++ b/prop-acc/index.md @@ -25,7 +25,7 @@ last_review: 2026-05-25 | --------- | ---------------- | --------------------------------------------- | ------ | | **一次性收费** | IC 卡、装修证、泳票等单次购买 | [adhoc 知识地图](maps/adhoc-knowledge-map.md) | ✅ 28 篇 | | **保证金** | 装修押金等代管资金,完工后退还 | [deposit 知识地图](maps/deposit-knowledge-map.md) | ✅ 25 篇 | -| **预存款** | 业户预存,自动抵扣月度账单 | _待补_ | 🚧 | +| **预存款** | 业户预存,自动抵扣月度账单 | [prepaid 知识地图](maps/prepaid-knowledge-map.md) | 🟡 6 概念已完成,16 场景待补 | | **计量表** | 水表/电表/燃气表,抄表生成账单 | _待补_ | 🚧 | | **账单** | 周期性账单 + 计量账单 | _待补_ | 🚧 | | **收款订单** | 一次收款的支付方式、银行账户记录 | _待补_ | 🚧 | diff --git a/prop-acc/maps/knowledge-map.md b/prop-acc/maps/knowledge-map.md index d0cd672..336d9a7 100644 --- a/prop-acc/maps/knowledge-map.md +++ b/prop-acc/maps/knowledge-map.md @@ -20,7 +20,7 @@ last_review: 2026-05-25 | 子模块 | 中文 | 一句话 | 深度地图 | 状态 | |---|---|---|---|---| | adhoc | 一次性收费 | IC 卡、装修证、泳票等单次购买 | [adhoc 知识地图](adhoc-knowledge-map.md) | ✅ 25 场景 + 3 概念 | -| prepaid | 预存款 | 业户预存,自动抵扣月度账单 | _待补_ | 🚧 | +| prepaid | 预存款 | 业户预存,自动抵扣月度账单 | [prepaid 知识地图](prepaid-knowledge-map.md) | 🟡 6 概念已完成,16 场景待补 | | deposit | 保证金 | 装修押金等代管资金,完工后退还 | [deposit 知识地图](deposit-knowledge-map.md) | ✅ 18 场景 + 6 概念 + 1 地图 = 25 篇 | | meter | 计量表 | 水表/电表/燃气表,抄表生成账单 | _待补_ | 🚧 | | billing | 账单 | 周期性账单 + 计量账单 | _待补_ | 🚧 | diff --git a/prop-acc/maps/prepaid-knowledge-map.md b/prop-acc/maps/prepaid-knowledge-map.md new file mode 100644 index 0000000..b155a69 --- /dev/null +++ b/prop-acc/maps/prepaid-knowledge-map.md @@ -0,0 +1,130 @@ +--- +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 个场景文档,基于本知识地图骨架填充。