uniprop-manual/prop-acc/maps/prepaid-knowledge-map.md

title, aliases, tags, sub_feature, audience, status, last_review, code_version

title	aliases	tags	sub_feature	audience	status	last_review	code_version
prop-acc · prepaid · 知识地图	prepaid 知识地图 预存款知识地图	规范 prop-acc 知识地图 预存款	prepaid	业户 业务人员 财务	已发布	2026-05-25	2026-05-22

预存款(prepaid)知识地图

本子模块 = PrepaidAccount + PrepaidTransaction。覆盖业户预存金额抵扣账单的全生命周期 —— 充值、消费(月度账单自动抵)、退款、冻结、关账。

这是什么?

业户提前充值一笔钱到自己的预存款账户,后续物业费 / 水电费等账单自动从这里扣,免得月月手动缴。是物业财务系统的"业户钱包"。

[!warning] 预存款不是收入,也不是押金 — 是预收账款 业户充进来的钱在抵扣账单之前,会计科目记预收账款(负债),不进收入。每次抵扣账单时,对应部分才转入收入。

三种模块的会计性质对比详见 adhoc 的 deposit-vs-adhoc-vs-prepaid 概念。

核心特性(与 deposit 的关键差异)

维度	prepaid 预存款	deposit 保证金
每业户账户数	1 个(一户一账)	多个
核心高频操作	consume(自动抵账单)	refund / forfeiture
Bill 关联	✅(consume 关联具体账单)	❌
零余额行为	保持 Active(可继续充值)	自动 Closed
ForceClose	❌(纠纷罕见)	✅
缴款人	只能是业户本人	多种(业主/租户/装修公司/...)

核心概念(6 篇)

文档	一句话
预存款账户与流水	双对象模式,与 deposit 同构但多两条独有约束
账户状态机	Active / Frozen / Closed,canOperate 统一守护,零余额不自动关账
一户一账约束	unique(community_id, profile_id) + 跨社区防御
流水类型	4 种(deposit / consume / refund / adjustment),consume 是高频
Consume 走 CollectionType=Bill 的设计	独特设计:抵账单用 Bill 视角,资金来源标 meta.fund_source=prepaid
月初批量自动抵扣设计	待补 scheduled job,产品核心卖点

场景手册(16 篇,全部完成 ✅)

📥 充值(Deposit)— 3 篇

• ✅ 首次开户充值 5000
• ✅ 已有账户追加充值
• ✅ 小程序在线充值(待补设计意图)

🧹 消费 Consume — 4 篇(最核心)

• ✅ 手动抵扣月度物业费
• ✅ 多个未付账单按 due_at 优先级抵扣
• ✅ 抵扣计量账单(水电费)
• ✅ 月初批量自动抵扣 job(设计意图 + 业务流程)

💰 退款(Refund)— 2 篇

• ✅ 业户搬走全额退余
• ✅ 部分消费后退余(不自动关账)

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

• ✅ 疑似欺诈 / 风控冻结
• ✅ 核实后解冻

🔒 结清(Close)— 2 篇

• ✅ 业户搬走主动关账
• ✅ 余额清零后不自动关,业户决定

🛡️ 异常 / 审计(3 篇)

• ✅ 跨社区消费防御
• ✅ 冻结状态退款被三层守护拦截
• ✅ 低余额业户预警 + 逾期账单排查

跨域引用

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

• 业户 — 缴款人(只能是业户本人)
• 组织结构 — community_id 归属

跨子模块引用

• adhoc · CollectionOrder 与 Receipt — prepaid 同样产出 CO + Receipt,但 consume 的 CO 用 type=Bill(详见本子模块独特设计)
• deposit · 账户与流水 — 双对象模式同构,可对比理解
• deposit · 状态机 — 三状态相同,关账行为不同
• deposit · 押金 vs 一次性收费 vs 预存款 — 三模块对比

相关代码

• 模型:PrepaidAccount.php、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/
• Dashboard / Widgets:DepositPrepaidDashboard、MonthlyPrepaidFlowChart、LowBalancePrepaidListWidget
• 业务设计决策:packages/prop-acc/issue.md 的 Q4 段

相关文档

• prop-acc 域知识地图
• prop-acc 域首页
• adhoc 子模块知识地图
• deposit 子模块知识地图
• 跨域协作地图

---

[!success] prepaid 子模块:6 概念 + 16 场景 + 1 知识地图 = 23 篇完成

写作日期:2026-05-25 对应代码版本:2026-05-22(详见 packages/prop-acc/issue.md Q4 段)

如果发现遗漏的场景或需要补充的细节,告诉我,可以单独补充新文档。