vault backup: 2026-05-26 00:23:07

prop-acc/scenarios/meter/generate-bill-with-multiplier.md

@@ -0,0 +1,234 @@
+---
+title: prop-acc · meter · 场景 - 工业表 10x 倍率生成账单
+aliases:
+  - 工业表账单
+  - multiplier 计算
+  - generate-bill-with-multiplier
+  - 场景-倍率表生成账单
+tags:
+  - 场景
+  - prop-acc
+  - 计量表
+  - 账单生成
+  - 倍率
+audience:
+  - 业务人员
+  - 财务
+  - 抄表员
+status: 已发布
+sub_feature: meter
+last_review: 2026-05-26
+code_version: 2026-05-22
+---
+
+# 场景:工业表 10x 倍率生成账单
+
+商铺 / 集团表 / 三相工业表的物理表头**只显示用量的 1/10 或 1/100**,需要乘以倍率(multiplier)才是实际用量。系统在 `consumption = (current - previous) × multiplier` 公式中自动处理。
+
+## 典型情境
+
+> [!example] 真实情境
+> 嘉禾花园 1 楼商铺(中式餐厅)装的是**三相工业电表**(multiplier=10)。本月抄表:
+>
+> - 上月 reading.current_reading = 280
+> - 本月 reading.current_reading = 308
+> - 物理表头读数差 = 28
+>
+> **实际用电量** = 28 × **10** = **280 度**(不是 28 度!)
+>
+> 按电费阶梯(0-200 度 0.8 元,200+ 度 1.0 元)算:
+>
+> ```
+> 段 1:200 × 0.8 = 160 元
+> 段 2:80 × 1.0 = 80 元
+> 合计:        240 元
+> ```
+>
+> 商铺老板看到账单 ¥240 / 280 度。
+
+如果**没有 multiplier**:
+
+```
+consumption = (308 - 280) × 1 = 28 度
+amount = 28 × 0.8 = 22.4 元 ❌
+```
+
+少收 ¥217.6,商铺白用 252 度电。**物业必须用倍率算账,这是工业表的天然属性**。
+
+## 系统流程
+
+```mermaid
+sequenceDiagram
+    participant 抄表员
+    participant Filament
+    participant Calc[MeterBillCalculator]
+    participant 数据库
+
+    抄表员->>Filament: 录入 reading current=308(物理表头)
+    Filament->>Filament: 查 meter.multiplier=10
+    Filament->>Filament: 查 previous_reading=280(上月)
+    Filament->>Filament: consumption = (308 - 280) × 10 = 280 度
+    Filament->>数据库: 建 MeterReading(consumption=280)
+
+    Note over 数据库: 后续 GenerateBills
+
+    Filament->>Calc: calculate(consumption=280, ratePlan)
+    Calc->>Calc: 阶梯算法 200*0.8 + 80*1 = 240
+    Calc-->>Filament: 240
+    Filament->>数据库: 建 Bill(amount=240)
+```
+
+## 抄表员视角(李师傅)
+
+### 抄表录入
+
+抄表员看到物理表头是 **308**(不是 3080),录入时填 **308**。
+
+> [!warning] 抄表员不应自己乘倍率
+>
+> **错误做法**:抄表员看到 308 + 知道倍率 10 → 录入 3080
+>
+> **后果**:系统再乘一次 10 → consumption = (3080 - 2800) × 10 = 2800 度 → 收业户 2800 度电费 → 业户疯狂投诉
+>
+> **正确做法**:**严格录入物理表头数字**(308),倍率由系统自动处理。
+
+Form 上应显示 meter 的 multiplier 提醒抄表员:
+
+```
+表编号:E-COMMERCIAL-1
+倍率:10x(工业表)
+上次读数:280
+
+本次读数:[___] (请录入物理表头数字)
+```
+
+### 与家用表的对比
+
+| 维度 | 家用表(multiplier=1)| 工业表(multiplier=10/100/...)|
+|---|---|---|
+| 抄表员录入 | 表头数字 = 实际用量 | 表头数字 ≠ 实际用量 |
+| 是否需要换算 | 不需要 | 需要(系统自动)|
+| 抄表员错误风险 | 低 | **中**(可能录乘 / 不乘 10) |
+| 业务培训 | 简单 | **需培训**(说清楚"录原始数字")|
+
+## 业务人员视角
+
+### 配置倍率
+
+建表时 `MeterForm.multiplier` 字段填:
+
+| 表类型 | 推荐 multiplier |
+|---|---|
+| 家用单相电表 | 1 |
+| 家用水表 | 1 |
+| 三相工业电表 | 10(常见)|
+| 大型工业电表(高压侧) | 100 / 1000 |
+| 工业大流量水表 | 10 / 100 |
+
+具体看表的物理铭牌 + 设计图纸。
+
+### 倍率改了如何处理
+
+> [!warning] 倍率改动影响极大
+> `multiplier` 改了不会重算历史 reading 的 consumption(那些数据已经存了)。但**会影响后续抄表**。
+>
+> **何时可改 multiplier**:
+> - 表是 `is_active=true`(退役表不可改,见 [[decommission-and-locking]])
+> - 表**没有任何已生成 Bill 的 reading**(若有,改 multiplier 让历史 vs 现在的算法不一致,审计困难)
+>
+> **推荐做法**:倍率配错 → 退役旧表 → 建新表用正确 multiplier(不走更换链,因为不是物理换表)。详见 [[decommission-without-replacement]]。
+
+## 业户视角(商铺老板)
+
+### 您看到的账单
+
+```
+2026 年 5 月电费账单
+
+用电量:280 度
+   (本月表头读数 308,上月 280,差 28 × 倍率 10)
+
+明细:
+  0-200 度段:200 × 0.8 = 160 元
+  201+ 度段:  80 × 1.0 = 80 元
+合计:240 元
+```
+
+> [!info] 账单展示倍率信息
+> 强烈推荐账单 / Receipt 展示"原始读数 + 倍率 + 计算公式",让业户看明白:
+>
+> - 业户看到差 28 度,但收 240 元,会疑惑(单价怎么算?)
+> - 展示"28 × 倍率 10 = 280 度,按 280 算"业户秒懂
+
+### 商铺老板的特殊关注
+
+| 业户疑问 | 应答 |
+|---|---|
+| "为什么我家是工业表不是家用表?" | 商铺用电量大,法规要求工业表 |
+| "倍率是物业定的吗?" | 不是,是物理表的属性,出厂时定 |
+| "可以换成家用表吗?" | 不能,商铺合规上必须用工业表 |
+
+## 倍率与阶梯的叠加
+
+倍率**先算**,得到 consumption;然后 consumption 走阶梯。两者完全独立、按顺序应用。
+
+完整公式:
+
+```
+consumption = (current - previous) × multiplier      # 第 1 层
+amount = sum(段 i 用量 × 段 i 单价)                  # 第 2 层(阶梯)
+amount = clamp(amount, min, max)                     # 第 3 层(min/max 封顶)
+```
+
+详见 [[multiplier-and-tiered-pricing]] 完整说明。
+
+## 不同 multiplier 表的算例
+
+| 表类型 | multiplier | 表头读数差 | consumption | 单价 0.8 | 账单 |
+|---|---|---|---|---|---|
+| 家用 | 1 | 280 | 280 | 224 | 224 |
+| 三相工业 | 10 | 28 | 280 | 224 | 224 |
+| 大工业(高压侧) | 100 | 2.8 | 280 | 224 | 224 |
+
+**同样 280 度,账单相同**,只是物理表头数字大小不同。系统的 multiplier 字段把这层差异隐藏在算法里。
+
+## 常见问题
+
+> [!question] multiplier 必须是整数吗?
+> 不必须。decimal(10,4) 精度,支持 0.5 / 1.25 等小数。但 1.0 / 10.0 / 100.0 是市场常见的"整数倍率"。
+
+> [!question] 同一表的 multiplier 会随时间变吗?
+> 物理上**不会**。表的物理参数(变压比)是出厂时确定的,使用过程中不变。
+>
+> 系统层面**可改字段**(若 `is_active=true` 且无 Bill,Policy 允许),但**不推荐**改 —— 历史与现在的算法不一致,审计困难。
+
+> [!question] 抄表员录入时如何区分"录物理读数"vs"录乘倍率后读数"?
+> Form 上**明确显示倍率**+ 标注"请录入物理表头数字"。培训抄表员**严格遵守**。系统统一存物理表头数字。
+
+> [!question] 集抄系统推过来的数据是物理读数还是乘了倍率?
+> 看集抄运营商。**通常是物理读数**(IoT 设备读表头,不知道倍率)。本系统接收时按 `meter.multiplier` 算 consumption。
+>
+> 如果集抄推已乘倍率的数据 → 集抄端**降级处理**(本系统 multiplier 应该设为 1,避免重复乘)。需对接时讲清楚。
+
+> [!question] 配置错倍率(应该 10 配成 1)会怎样?
+> 系统按 multiplier=1 算 → consumption 缩小 10 倍 → 业户账单缩小 10 倍 → 物业损失收入(直到发现)。
+>
+> 发现后修复:
+> - 改 multiplier=10(若 Policy 允许)
+> - 修复历史已欠收(走"补开账单"业务流程,系统不直接支持)
+> - 通知业户 + 退还 / 补收差额
+
+## 异常分支
+
+- 阶梯计价(本场景叠加)→ [[generate-bill-tiered-pricing]]
+- min/max 封顶 → [[generate-bill-min-max-cap]]
+- 倍率配错想改 → 复杂,通常退役旧表新建([[decommission-and-locking]])
+- 抄表员录错乘倍率 → [[exception-readings-locked-after-bill]] 修正
+
+## 相关文档
+
+- [[multiplier-and-tiered-pricing]]
+- [[bill-generation-pipeline]]
+- [[meter-vs-meter-reading]]
+- [[generate-bill-tiered-pricing]]
+- [[generate-bill-min-max-cap]]