meter 子模块 · 轮 1:6 概念 + 知识地图 + 导航更新
写 6 个核心概念到 prop-acc/concepts/meter/: - meter-vs-meter-reading:物理表配置 + 不可变读数流水双对象;与"账户+流水"模式 对比(主对象有 balance vs 物理硬件配置;直接产 Receipt vs 通过 Bill 中转) - replacement-chain:replaced_meter_id + 自动 -R1 后缀 + 初始读数继承; nextReplacementCode() 算法 + 整链追溯 + ReplaceMeterAction 流程 - multiplier-and-tiered-pricing:倍率(decimal(10,4),工业表 10x/100x)+ 阶梯计价(progressive 累进算法,非 full-tier 简陋实现)+ min/max 封顶 - bill-generation-pipeline:三层分层 Calculator(纯算)→ Service(查费率+找业主+建账) → Action(入口);多调用方共用业务层;prop-acc 后续模块的样板 - reading-source-and-photo-proof:MeterReadingSource 2 种(manual/remote)+ photo_url 拍照存证;业户对账单争议时的凭证依据 - decommission-and-locking:MeterDecommissionReason 5 种 + Reading 双锁机制 (创建即不可改;有 bill_id 更不可改/删);issue.md Q5 第二轮修复历史 新建子模块知识地图: - prop-acc/maps/meter-knowledge-map.md:6 概念入口 + 14 场景预占清单 + 跨子模块对比(meter 与 deposit/prepaid 的核心差异)+ 代码索引 更新导航: - prop-acc/maps/knowledge-map.md:域总图 meter 行链 meter 知识地图,状态 🟡 - prop-acc/index.md:同步 下一轮:14 个场景文档(meter/scenarios/),按本知识地图骨架填充。 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Willie
@@ -22,7 +22,7 @@ last_review: 2026-05-25
|
||||
| adhoc | 一次性收费 | IC 卡、装修证、泳票等单次购买 | [adhoc 知识地图](adhoc-knowledge-map.md) | ✅ 25 场景 + 3 概念 |
|
||||
| prepaid | 预存款 | 业户预存,自动抵扣月度账单 | [prepaid 知识地图](prepaid-knowledge-map.md) | ✅ 16 场景 + 6 概念 + 1 地图 = 23 篇 |
|
||||
| deposit | 保证金 | 装修押金等代管资金,完工后退还 | [deposit 知识地图](deposit-knowledge-map.md) | ✅ 18 场景 + 6 概念 + 1 地图 = 25 篇 |
|
||||
| meter | 计量表 | 水表/电表/燃气表,抄表生成账单 | _待补_ | 🚧 |
|
||||
| meter | 计量表 | 水表/电表/燃气表,抄表生成账单 | [meter 知识地图](meter-knowledge-map.md) | 🟡 6 概念已完成,14 场景待补 |
|
||||
| billing | 账单 | 周期性账单 + 计量账单 | _待补_ | 🚧 |
|
||||
| payment-order | 收款订单 | 一次收款的支付方式、银行账户记录 | _待补_ | 🚧 |
|
||||
| receipt | 收据 | 成功收款后生成的凭证 | _待补_ | 🚧 |
|
||||
|
||||
134
prop-acc/maps/meter-knowledge-map.md
Normal file
134
prop-acc/maps/meter-knowledge-map.md
Normal file
@@ -0,0 +1,134 @@
|
||||
---
|
||||
title: prop-acc · meter · 知识地图
|
||||
aliases:
|
||||
- meter 知识地图
|
||||
- 计量表知识地图
|
||||
tags:
|
||||
- 规范
|
||||
- prop-acc
|
||||
- 知识地图
|
||||
- 计量表
|
||||
sub_feature: meter
|
||||
audience:
|
||||
- 业务人员
|
||||
- 抄表员
|
||||
- 财务
|
||||
status: 已发布
|
||||
last_review: 2026-05-25
|
||||
code_version: 2026-05-22
|
||||
---
|
||||
|
||||
# 计量表(meter)知识地图
|
||||
|
||||
> 本子模块 = Meter(物理表配置)+ MeterReading(不可变抄表流水)。覆盖物业计量收费(水电气)的全生命周期 —— 建表、抄表、生成账单、表更换、表退役、异常处理。
|
||||
|
||||
## 这是什么?
|
||||
|
||||
物业管理水表 / 电表 / 燃气表的**计量计费基础设施**。从"业户家里有一张物理表"到"每月物业费账单里有一行水电费",中间走的就是本模块。
|
||||
|
||||
> [!info] meter 是 prop-acc 里**最成熟**的子模块
|
||||
> issue.md Q5 评估:数据模型对齐市场标准 ~90%,业务分层清楚(`Calculator → Service → Action`),完整的换表链、倍率支持、阶梯计价、min/max 封顶、抄表来源跟踪、拍照存证、初始化批量导入。**后续 deposit / prepaid / adhoc 模块的分层方法是从 meter 学的**。
|
||||
|
||||
## 与其他子模块的关系
|
||||
|
||||
| 关系 | 说明 |
|
||||
|---|---|
|
||||
| **下游产 Bill,不直接产 Receipt** | 抄表 → 生成 Bill → 业户付账单时走 [adhoc 的 CollectionOrder + Receipt 体系](../concepts/adhoc/collection-order-and-receipt.md) |
|
||||
| **业户付账单的资金可来自预存款** | 走 [prepaid 的 consume](../concepts/prepaid/consume-via-bill-collection-type.md) 模式 —— Bill.amount 自动从预存款余额扣 |
|
||||
| **本模块不涉及押金** | 计量表是日常计费工具,无押金概念 |
|
||||
|
||||
## 核心特性(与其他模块对比)
|
||||
|
||||
| 维度 | meter | deposit / prepaid |
|
||||
|---|---|---|
|
||||
| 主对象类型 | **物理硬件**(表)| 抽象账户 |
|
||||
| 主对象有 balance | ❌ | ✅ |
|
||||
| 流水方向 | 单向(只录读数,无 +/-) | 双向(deposit / refund / forfeit / consume) |
|
||||
| 直接产 Receipt | ❌(走 Bill 中转) | ✅ |
|
||||
| 表更换 / 退役机制 | ✅(`replaced_meter_id` 链 + 5 种退役原因) | N/A |
|
||||
| 来源标记(manual/remote) | ✅ | ❌ |
|
||||
| 拍照存证 | ✅ | ❌ |
|
||||
|
||||
## 核心概念(6 篇)
|
||||
|
||||
| 文档 | 一句话 |
|
||||
|---|---|
|
||||
| [计量表与抄表流水](../concepts/meter/meter-vs-meter-reading.md) | 双对象(物理表配置 + 不可变读数流水),与"账户+流水"模式的差异 |
|
||||
| [表更换链](../concepts/meter/replacement-chain.md) | `replaced_meter_id` + 自动 `-R1` 后缀 + 初始读数继承,保证用量计算连续 |
|
||||
| [倍率与阶梯计价](../concepts/meter/multiplier-and-tiered-pricing.md) | 倍率(工业表 10x/100x) + 阶梯计价(progressive 累进) + min/max 封顶 |
|
||||
| [账单生成的三层分层](../concepts/meter/bill-generation-pipeline.md) | Calculator(纯算)→ Service(查费率 + 找业主)→ Action(入口),prop-acc 的样板 |
|
||||
| [抄表来源与拍照存证](../concepts/meter/reading-source-and-photo-proof.md) | `manual` 手抄 vs `remote` 集抄 + `photo_url` 凭证,业户争议时的证据 |
|
||||
| [表退役与读数锁定](../concepts/meter/decommission-and-locking.md) | 5 种退役原因 + Reading 双锁机制(创建即不可改,有 Bill 更不可改) |
|
||||
|
||||
## 场景手册(14 篇,**待补充 ✋**)
|
||||
|
||||
> 🚧 概念骨架已就位,场景文档将在下一轮(轮 2)产出。预定结构如下。
|
||||
|
||||
### 📦 表管理(4 篇)
|
||||
|
||||
- 🚧 [新社区批量建表 + 初始读数 Excel 导入](../scenarios/meter/init-new-community-batch.md)
|
||||
- 🚧 [单独新增一张表(后台单录)](../scenarios/meter/register-single-meter.md)
|
||||
- 🚧 [换表:旧表故障/退役,新表带 -R1 后缀,初始读数继承](../scenarios/meter/replace-broken-meter.md)
|
||||
- 🚧 [退役不换表(房屋拆除 / 业户永久弃用)](../scenarios/meter/decommission-without-replacement.md)
|
||||
|
||||
### 📊 抄表(4 篇)
|
||||
|
||||
- 🚧 [单张表后台手动录入](../scenarios/meter/read-single-meter-manual.md)
|
||||
- 🚧 [一次导入整月所有读数(Excel 批量)](../scenarios/meter/read-batch-via-excel-import.md)
|
||||
- 🚧 [集抄系统自动推送(`source=remote`)](../scenarios/meter/read-via-iot-remote-source.md)
|
||||
- 🚧 [抄表拍照存证(物理表头照片)](../scenarios/meter/read-with-photo-proof.md)
|
||||
|
||||
### 💰 账单生成(3 篇)
|
||||
|
||||
- 🚧 [阶梯水电价生成账单(progressive 累进算例)](../scenarios/meter/generate-bill-tiered-pricing.md)
|
||||
- 🚧 [工业表 10x 倍率生成账单](../scenarios/meter/generate-bill-with-multiplier.md)
|
||||
- 🚧 [单笔账单上下限封顶(防异常用量爆账)](../scenarios/meter/generate-bill-min-max-cap.md)
|
||||
|
||||
### 🛡️ 异常 / 审计(3 篇)
|
||||
|
||||
- 🚧 [高用量异常(漏水 / 电器故障),`HighConsumptionReadingsListWidget` 预警](../scenarios/meter/exception-high-consumption.md)
|
||||
- 🚧 [已生成 Bill 的 Reading 锁定,要修正需作废 Bill](../scenarios/meter/exception-readings-locked-after-bill.md)
|
||||
- 🚧 [待抄表清单 + 月度抄表完成率(`MetersNeedingReadingListWidget`)](../scenarios/meter/audit-meters-needing-reading.md)
|
||||
|
||||
## 跨域引用
|
||||
|
||||
本子模块引用以下跨域共享概念:
|
||||
|
||||
- [业户](../../cross/concepts/resident.md) — 账单关联业户
|
||||
- [房屋单元](../../cross/concepts/housing-unit.md) — `asset_id`,表绑定房屋
|
||||
- [组织结构](../../cross/concepts/org-hierarchy.md) — `community_id`,物业项目归属
|
||||
|
||||
## 跨子模块引用
|
||||
|
||||
- [adhoc · CollectionOrder 与 Receipt](../concepts/adhoc/collection-order-and-receipt.md) — 计量账单付款时走的凭证体系
|
||||
- [prepaid · Consume 走 CollectionType=Bill 的设计](../concepts/prepaid/consume-via-bill-collection-type.md) — 计量账单可由预存款抵扣
|
||||
- [deposit · 账户与流水](../concepts/deposit/deposit-account-vs-transaction.md) — 账户+流水模式对比
|
||||
|
||||
## 相关代码
|
||||
|
||||
- 模型:[`Meter.php`](../../../packages/prop-acc/src/Models/Meter.php)、[`MeterReading.php`](../../../packages/prop-acc/src/Models/MeterReading.php)
|
||||
- 枚举:`MeterReadingSource`(2 种)、`MeterDecommissionReason`(5 种)
|
||||
- Policy:`MeterPolicy`(3 个方法)、`MeterReadingPolicy`(2 个方法)
|
||||
- 业务层:
|
||||
- [`MeterBillCalculator`](../../../packages/prop-acc/src/Services/MeterBillCalculator.php)(纯算)
|
||||
- [`MeterBillGenerationService`](../../../packages/prop-acc/src/Services/MeterBillGenerationService.php)(业务编排)
|
||||
- [`GenerateBillsFromMeterReadingsAction`](../../../packages/prop-acc/src/Actions/Meters/GenerateBillsFromMeterReadingsAction.php)(入口)
|
||||
- Filament Resource:[`packages/prop-acc/src/Filament/Resources/Meters/`](../../../packages/prop-acc/src/Filament/Resources/Meters/)
|
||||
- Importers:`MeterReadingsImporter`、`MeterInitializationImporter`(继承 `BaseImporter`)
|
||||
- Dashboard / Widgets:`MeterDashboard`、`MetersNeedingReadingListWidget`、`HighConsumptionReadingsListWidget`、`MonthlyConsumptionByFeeTypeChart`、`MeterStatsOverviewWidget`
|
||||
- 业务设计决策:`packages/prop-acc/issue.md` 的 Q5 段
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [prop-acc 域知识地图](knowledge-map.md)
|
||||
- [prop-acc 域首页](../index.md)
|
||||
- [adhoc 子模块知识地图](adhoc-knowledge-map.md)
|
||||
- [deposit 子模块知识地图](deposit-knowledge-map.md)
|
||||
- [prepaid 子模块知识地图](prepaid-knowledge-map.md)
|
||||
- [跨域协作地图](../../cross/maps/cross-domain-map.md)
|
||||
|
||||
---
|
||||
|
||||
> [!info] 概念已完成,场景待补
|
||||
> 本轮(轮 1)产出:6 个概念 + 本子模块地图 + 域总图更新。
|
||||
> 下一轮(轮 2)产出:14 个场景文档,基于本知识地图骨架填充。
|
||||
Reference in New Issue
Block a user