2026-05-25 21:46:28 +08:00
|
|
|
---
|
|
|
|
|
title: prop-acc · 知识地图
|
|
|
|
|
aliases:
|
|
|
|
|
- prop-acc 知识地图
|
|
|
|
|
- 物业财务知识地图
|
|
|
|
|
tags:
|
|
|
|
|
- 规范
|
|
|
|
|
- prop-acc
|
|
|
|
|
- 知识地图
|
|
|
|
|
status: 已发布
|
|
|
|
|
last_review: 2026-05-25
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
# prop-acc · 域知识地图
|
|
|
|
|
|
|
|
|
|
物业财务域的全部子模块入口。每个子模块对应一张深度地图。
|
|
|
|
|
|
|
|
|
|
## 7 子模块
|
|
|
|
|
|
|
|
|
|
| 子模块 | 中文 | 一句话 | 深度地图 | 状态 |
|
|
|
|
|
|---|---|---|---|---|
|
|
|
|
|
| adhoc | 一次性收费 | IC 卡、装修证、泳票等单次购买 | [adhoc 知识地图](adhoc-knowledge-map.md) | ✅ 25 场景 + 3 概念 |
|
prepaid 子模块 · 轮 2:16 场景 + 知识地图收尾
写 16 个场景到 prop-acc/scenarios/prepaid/,覆盖 6 类业务:
📥 充值(3):
- deposit-first-time(张阿姨首次充 5000)
- deposit-additional-topup(已有账户追加充值)
- deposit-via-miniapp-pending(小程序在线充值设计意图,待补)
🧹 消费 Consume(4,最核心):
- consume-monthly-property-bill(手动抵扣月物业费)
- consume-multiple-bills-priority(多账单按 due_at 优先级抵扣)
- consume-meter-bill(抵扣计量账单 - 水电费)
- consume-batch-auto-monthly(月初批量自动抵扣 job 设计 + 业务流程,待补)
💰 退款(2):
- refund-full-resident-moveout(业户搬走全额退余,**不自动关账**)
- refund-partial-after-consume(部分退余,余额非零保持 Active)
🧊 冻结/解冻(2):
- freeze-suspected-fraud(疑似欺诈 / 风控冻结)
- unfreeze-after-verification(核实后解冻 = ReactivateAccountAction)
🔒 结清(2):
- close-resident-moveout(业户搬走主动关账,**需手动**与 deposit 不同)
- close-with-zero-balance-decision(余额清零不自动关,业户决定)
🛡️ 异常/审计(3):
- exception-cross-community-consume(跨社区消费三层防御,模型层抛 InvalidArgumentException)
- exception-refund-on-frozen(冻结状态退款三层守护,模型层最严 canOperate)
- audit-low-balance-and-overdue(低余额业户预警 + 逾期账单排查,
关联 LowBalancePrepaidListWidget + DepositPrepaidDashboard)
每篇结构:典型情境 → 业户视角 → 业务人员视角 → 系统流程(mermaid)→
常见问题 → 异常分支 → 相关文档(WikiLinks)。
prepaid 与 deposit 的核心差异在场景中持续强调:
- 一户一账约束(deposit 不允许跨账户操作的设计)
- 零余额不自动关账(consume / refund 后状态保持 Active)
- 消费走 CollectionType=Bill(账单视角,fund_source=prepaid)
- 没有 ForceClose(纠纷罕见,简化设计)
- 缴款人只能是业户本人(deposit 支持装修公司代缴)
收尾:
- prop-acc/maps/prepaid-knowledge-map.md:16 场景全部 ✅,加完成 callout
- prop-acc/maps/knowledge-map.md:prepaid 行状态改 "✅ 23 篇"
- prop-acc/index.md:同步
prepaid 子模块完整覆盖:6 概念 + 16 场景 + 1 知识地图 = 23 篇。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-25 23:39:05 +08:00
|
|
|
| prepaid | 预存款 | 业户预存,自动抵扣月度账单 | [prepaid 知识地图](prepaid-knowledge-map.md) | ✅ 16 场景 + 6 概念 + 1 地图 = 23 篇 |
|
2026-05-25 22:40:19 +08:00
|
|
|
| deposit | 保证金 | 装修押金等代管资金,完工后退还 | [deposit 知识地图](deposit-knowledge-map.md) | ✅ 18 场景 + 6 概念 + 1 地图 = 25 篇 |
|
meter 子模块 · 轮 2:14 场景 + 知识地图收尾
写 14 个场景到 prop-acc/scenarios/meter/,覆盖 4 类业务:
📦 表管理(4):
- init-new-community-batch(新社区批量建表 + 初始读数 Excel 导入,
走 MeterInitializationImporter + BaseImporter chunk rollback)
- register-single-meter(单独新增一张表,陈先生厨房分户表)
- replace-broken-meter(换表场景,旧表 5000 → 新表 -R1 后缀 + initial 5000 继承,
ReplaceMeterAction 完整流程)
- decommission-without-replacement(退役不换表,3 种典型情境:
房屋拆除 / 商铺撤店 / 法定年限到)
📊 抄表(4):
- read-single-meter-manual(后台单录,李师傅集抄掉线补抄)
- read-batch-via-excel-import(MeterReadingsImporter + 模板下载流程 +
双义列名 silent corruption 已知风险)
- read-via-iot-remote-source(集抄系统对接,API + 防重放 + 与 deposit/prepaid 集成)
- read-with-photo-proof(物理表头照片,业户争议时关键凭证)
💰 账单生成(3):
- generate-bill-tiered-pricing(progressive 累进算法完整算例 35 吨水的三段计算,
对比 full-tier 简陋实现)
- generate-bill-with-multiplier(工业表 multiplier=10 算例 + 抄表员录入注意事项)
- generate-bill-min-max-cap(漏水 max 封顶 + 零用量 min 兜底 + 正常范围三情境)
🛡️ 异常/审计(3):
- exception-high-consumption(HighConsumptionReadingsListWidget 预警 +
分级处置 + 完整排查流程)
- exception-readings-locked-after-bill(双锁机制下的修正流程,当前手工 +
未来 VoidBillAction 设计目标态,issue.md Q5 待补)
- audit-meters-needing-reading(MetersNeedingReadingListWidget +
月度完成率 99% 目标 + 月度报告模板)
每篇结构:典型情境 → 业户/抄表员/业务人员视角 → 系统流程(mermaid)→
对比表 / 算例 → 常见问题 → 异常分支 → 相关文档(WikiLinks)。
meter 模块特性在场景中持续强调:
- 物理硬件维度(非抽象账户)
- 不直接产 Receipt(走 Bill 中转)
- 三层业务分层(Calculator + Service + Action)
- 双锁机制(创建即不可改 + 有 Bill 更严)
- 抄表来源 + 拍照存证 + 集抄对接
- progressive 累进 vs full-tier 简陋实现的设计正确性
- 倍率 + 阶梯 + min/max 三层叠加算法
收尾:
- prop-acc/maps/meter-knowledge-map.md:14 场景全部 ✅,加完成 callout
- prop-acc/maps/knowledge-map.md:meter 行状态改 "✅ 21 篇"
- prop-acc/index.md:同步
meter 子模块完整覆盖:6 概念 + 14 场景 + 1 知识地图 = 21 篇。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-26 00:31:08 +08:00
|
|
|
| meter | 计量表 | 水表/电表/燃气表,抄表生成账单 | [meter 知识地图](meter-knowledge-map.md) | ✅ 14 场景 + 6 概念 + 1 地图 = 21 篇 |
|
billing 子模块 · 轮 2:16 场景 + 知识地图收尾
写 16 个场景到 prop-acc/scenarios/billing/,覆盖 5 类业务:
📝 账单创建(3):
- create-periodic-property-fee(月度物业费 300 户批量,SkipExisting 默认策略)
- create-meter-bill-auto(抄表自动生成计量账单,与 meter pipeline 衔接)
- create-single-bill-manual(电梯维修分摊 / 罚款 / 跨期补开 三典型情境)
💰 收款(3):
- collect-payment-single(单张收款,Modal + 数据示例 + 部分付场景)
- collect-payment-batch(同业户多账单一次收款,1 个 CO + N 个 COBill)
- collect-via-prepaid-auto(billing × prepaid 跨模块联动,fund_source=prepaid)
✂️ 账单调整(3):
- split-bill(房东/租户分摊场景,SplitBillAction 全转/部分拆模式)
- suspend-bill(纠纷/失联 SuspendBillAction,与 Unpaid/Partial 状态守护)
- resume-bill(智能恢复 Unpaid / Partial,suspend_history 数组设计)
🗑️ 删除 / 作废(3):
- delete-bill-unpaid(物理删 canBeDeleted=Unpaid+无付款,activitylog 留 bill_no)
- void-paid-bill(Partial 作废可用 + Paid 作废需手工/tinker 流程的局限)
- bulk-delete-batch-mistake(智能批删 Modal 三档分类 + 完整 activitylog 实战)
🛡️ 异常 / 审计(4):
- exception-partial-payment(Partial 状态完整生命周期 + 多次补付流水)
- exception-overdue-bills(OverdueBillsListWidget + 分级催收 +
滞纳金合规 + 服务限制合规边界)
- audit-monthly-billing-vs-collection(收款率核心指标 + SQL 报表 +
与会计科目映射)
- audit-activitylog-trace(spatie activitylog 实战查询 +
与 meta JSON 对比 + 跨模块审计 + 法务用途)
每篇结构:典型情境 → 业户/业务/财务/审计视角 → 系统流程(mermaid) →
SQL 报表 / 数据示例 → 常见问题 → 异常分支 → 相关文档(WikiLinks)。
billing 独特设计在场景中持续强调:
- 6 状态机的状态流转(Unpaid → Partial → Paid;Suspended ↔ Unpaid;Void 终态)
- 多对多关联(CollectionOrderBill 中间表 + allocated_amount 语义)
- 删 vs 作废双轨制(双层守护 + 业务场景区分)
- 智能批删 Modal(预检查三档分类 + 必填原因 + 单条 activitylog 含 affected_bill_nos)
- spatie activitylog 审计(properties JSON 跨模块查询)
- 跨子模块联动(meter → billing,prepaid → billing,billing → CollectionOrder)
收尾:
- prop-acc/maps/billing-knowledge-map.md:16 场景全部 ✅
- prop-acc/maps/knowledge-map.md:billing 行状态改 "✅ 23 篇"
- prop-acc/index.md:同步
billing 子模块完整覆盖:6 概念 + 16 场景 + 1 知识地图 = 23 篇。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-26 01:21:32 +08:00
|
|
|
| billing | 账单 | 周期性账单 + 计量账单 | [billing 知识地图](billing-knowledge-map.md) | ✅ 16 场景 + 6 概念 + 1 地图 = 23 篇 |
|
2026-05-25 21:46:28 +08:00
|
|
|
| payment-order | 收款订单 | 一次收款的支付方式、银行账户记录 | _待补_ | 🚧 |
|
|
|
|
|
| receipt | 收据 | 成功收款后生成的凭证 | _待补_ | 🚧 |
|
|
|
|
|
|
|
|
|
|
## 跨子模块概念
|
|
|
|
|
|
|
|
|
|
(本域内多个子模块共享的概念,落在 `concepts/` 顶层,不在任何子模块文件夹里)
|
|
|
|
|
|
|
|
|
|
(待添加)
|
|
|
|
|
|
|
|
|
|
## 跨域引用
|
|
|
|
|
|
|
|
|
|
本域引用以下共享概念:
|
|
|
|
|
|
|
|
|
|
- [业户](../../cross/concepts/resident.md)
|
|
|
|
|
- [门卡 / IC 卡](../../cross/concepts/access-card.md)
|
|
|
|
|
- [房屋单元](../../cross/concepts/housing-unit.md)
|
|
|
|
|
|
|
|
|
|
## 相关文档
|
|
|
|
|
|
|
|
|
|
- [prop-acc 域首页](../index.md)
|
|
|
|
|
- [跨域协作地图](../../cross/maps/cross-domain-map.md)
|
|
|
|
|
- [顶层域索引](../../maps/domain-map.md)
|