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

---
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 篇,**全部完成 ✅**)

### 📦 表管理(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)

---

> [!success] meter 子模块:6 概念 + 14 场景 + 1 知识地图 = **21 篇完成**
>
> 写作日期:2026-05-26
> 对应代码版本:2026-05-22(详见 `packages/prop-acc/issue.md` Q5 段)
>
> 如果发现遗漏的场景或需要补充的细节,告诉我,可以单独补充新文档。