vault backup: 2026-05-25 23:53:01
This commit is contained in:
Willie
294
prop-acc/concepts/meter/bill-generation-pipeline.md
Normal file
294
prop-acc/concepts/meter/bill-generation-pipeline.md
Normal file
@@ -0,0 +1,294 @@
|
||||
---
|
||||
title: prop-acc · meter · 账单生成的三层分层
|
||||
aliases:
|
||||
- 账单生成 pipeline
|
||||
- Calculator Service Action 三层
|
||||
- MeterBillCalculator
|
||||
- MeterBillGenerationService
|
||||
- GenerateBillsFromMeterReadingsAction
|
||||
tags:
|
||||
- 概念
|
||||
- prop-acc
|
||||
- 计量表
|
||||
- 架构
|
||||
- 计费
|
||||
audience:
|
||||
- 架构师
|
||||
- 业务人员
|
||||
status: 已发布
|
||||
sub_feature: meter
|
||||
last_review: 2026-05-25
|
||||
code_version: 2026-05-22
|
||||
---
|
||||
|
||||
# 账单生成的三层分层
|
||||
|
||||
从"一条 MeterReading"到"一张 Bill",中间经过三层代码,每层职责清晰、可独立测试:
|
||||
|
||||
1. **`MeterBillCalculator`** — 纯算函数(无 DB IO),拿用量 + RatePlan,算出金额
|
||||
2. **`MeterBillGenerationService`** — 查费率 + 找业主 + 建 Bill 数据库记录
|
||||
3. **`GenerateBillsFromMeterReadingsAction`** — 业务入口,接收一组 reading,触发整个流程
|
||||
|
||||
> [!info] 为什么这种分层是 prop-acc 的"样板"
|
||||
> issue.md Q5 提到 meter 是 prop-acc 里**最成熟**的模块,后续 deposit / prepaid / adhoc 学习了它的"业务分层方法"。这条 Calculator → Service → Action 的链路设计,**值得作为新模块的参考蓝本**。
|
||||
|
||||
## 三层职责清单
|
||||
|
||||
| 层 | 类名 | 职责 | 依赖 |
|
||||
|---|---|---|---|
|
||||
| **Calculator** | `MeterBillCalculator` | 纯算:用量 → 金额(阶梯 + 倍率 + min/max)| 无(纯函数)|
|
||||
| **Service** | `MeterBillGenerationService` | 业务编排:从 Reading 查 fee_type → 查 RatePlan → 找 asset 业主 → 调 Calculator → 建 Bill | DB |
|
||||
| **Action** | `GenerateBillsFromMeterReadingsAction` | 业务入口:接收一组 Reading → 校验 → 逐条调 Service | DB + 事件 |
|
||||
|
||||
## 调用栈
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant 业务[业务人员/定时任务]
|
||||
participant Filament
|
||||
participant Action[GenerateBillsFromMeterReadingsAction]
|
||||
participant Service[MeterBillGenerationService]
|
||||
participant Calc[MeterBillCalculator]
|
||||
participant DB
|
||||
|
||||
业务->>Filament: 触发"生成本月账单"按钮
|
||||
Filament->>Action: handle([reading1, reading2, ..., readingN])
|
||||
|
||||
loop 每个 reading
|
||||
Action->>Action: 校验:reading.bill_id == null
|
||||
Action->>Service: generateBillForReading(reading)
|
||||
Service->>DB: 查 Meter.fee_type → 查 RatePlan + RateTier
|
||||
Service->>DB: 查 asset_id 关联的业户(community_asset_users)
|
||||
Service->>Calc: calculate(consumption, ratePlan, min, max)
|
||||
Calc-->>Service: amount = 148
|
||||
Service->>DB: 建 Bill(amount, asset, resident, sourceable=reading)
|
||||
Service->>DB: 更新 reading.bill_id = bill.id
|
||||
Service-->>Action: ok
|
||||
end
|
||||
|
||||
Action-->>Filament: 完成 + 报告(已生成 N 张 Bill)
|
||||
```
|
||||
|
||||
## 每层细节
|
||||
|
||||
### Layer 1:`MeterBillCalculator`(纯算)
|
||||
|
||||
```php
|
||||
// 伪代码示意
|
||||
class MeterBillCalculator
|
||||
{
|
||||
public function calculate(
|
||||
float $consumption,
|
||||
RatePlan $ratePlan,
|
||||
?float $minAmount,
|
||||
?float $maxAmount,
|
||||
): float {
|
||||
$amount = $this->calculateTiered($consumption, $ratePlan->tiers);
|
||||
if ($maxAmount !== null && $amount > $maxAmount) {
|
||||
$amount = $maxAmount;
|
||||
}
|
||||
if ($minAmount !== null && $amount < $minAmount) {
|
||||
$amount = $minAmount;
|
||||
}
|
||||
return $amount;
|
||||
}
|
||||
|
||||
public function calculateTiered(float $consumption, Collection $tiers): float
|
||||
{
|
||||
// progressive 累进算法,见 multiplier-and-tiered-pricing
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**特点**:
|
||||
|
||||
- 无 DB 查询
|
||||
- 无业务对象关联(只接受参数)
|
||||
- 完全可测试(给定输入 → 期望输出)
|
||||
- 单元测试覆盖率 100% 容易达到
|
||||
|
||||
### Layer 2:`MeterBillGenerationService`(业务编排)
|
||||
|
||||
```php
|
||||
// 伪代码示意
|
||||
class MeterBillGenerationService
|
||||
{
|
||||
public function __construct(
|
||||
private MeterBillCalculator $calculator,
|
||||
) {}
|
||||
|
||||
public function generateBillForReading(MeterReading $reading): Bill
|
||||
{
|
||||
$meter = $reading->meter;
|
||||
$feeType = $meter->feeType;
|
||||
$ratePlan = $feeType->currentRatePlan;
|
||||
$asset = $meter->asset;
|
||||
$resident = $this->findCurrentResident($asset); // 关键业务逻辑
|
||||
|
||||
$amount = $this->calculator->calculate(
|
||||
$reading->consumption,
|
||||
$ratePlan,
|
||||
$ratePlan->min_amount,
|
||||
$ratePlan->max_amount,
|
||||
);
|
||||
|
||||
return DB::transaction(function () use ($reading, $amount, /* ... */) {
|
||||
$bill = Bill::create([
|
||||
'community_id' => $meter->community_id,
|
||||
'asset_id' => $meter->asset_id,
|
||||
'resident_id' => $resident?->id,
|
||||
'fee_type_id' => $meter->fee_type_id,
|
||||
'amount' => $amount,
|
||||
'sourceable_type' => MeterReading::class,
|
||||
'sourceable_id' => $reading->id,
|
||||
'status' => BillStatus::Unpaid,
|
||||
'due_at' => /* 计算到期日 */,
|
||||
]);
|
||||
|
||||
$reading->update(['bill_id' => $bill->id]);
|
||||
|
||||
return $bill;
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**特点**:
|
||||
|
||||
- 查 DB(RatePlan / asset / resident)
|
||||
- 业务规则(找当前业主、计算到期日)
|
||||
- 事务边界(确保 Bill 建 + Reading 回写同时成功)
|
||||
- 不直接处理 UI / 用户输入
|
||||
|
||||
### Layer 3:`GenerateBillsFromMeterReadingsAction`(入口)
|
||||
|
||||
```php
|
||||
// 伪代码示意
|
||||
class GenerateBillsFromMeterReadingsAction
|
||||
{
|
||||
public function __construct(
|
||||
private MeterBillGenerationService $service,
|
||||
) {}
|
||||
|
||||
public function handle(Collection $readings): array
|
||||
{
|
||||
$generated = [];
|
||||
$skipped = [];
|
||||
|
||||
foreach ($readings as $reading) {
|
||||
if ($reading->bill_id !== null) {
|
||||
$skipped[] = ['reading' => $reading, 'reason' => 'already_billed'];
|
||||
continue;
|
||||
}
|
||||
|
||||
try {
|
||||
$bill = $this->service->generateBillForReading($reading);
|
||||
$generated[] = $bill;
|
||||
} catch (\Exception $e) {
|
||||
$skipped[] = ['reading' => $reading, 'reason' => $e->getMessage()];
|
||||
}
|
||||
}
|
||||
|
||||
return [
|
||||
'generated' => $generated,
|
||||
'skipped' => $skipped,
|
||||
];
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**特点**:
|
||||
|
||||
- 业务入口(给 Filament / Console / 定时任务调用)
|
||||
- 处理批量
|
||||
- 容错(单条失败不影响其他)
|
||||
- 返回结构化结果供调用方报告 / 推送
|
||||
|
||||
## 调用方
|
||||
|
||||
`GenerateBillsFromMeterReadingsAction` 的调用方:
|
||||
|
||||
| 调用方 | 场景 |
|
||||
|---|---|
|
||||
| **Filament Action**(`ViewMeter` 上的"生成账单"按钮)| 业务人员手动触发(单表 / 多表)|
|
||||
| **`MeterReadingsImporter`**(批量导入完成后)| 导入抄表数据后自动触发账单生成 |
|
||||
| **`MeterReadingsRelationManager`** 单录后(可选)| 抄表后即生成账单(配置项)|
|
||||
| **定时任务**(月初自动)| 待补(类似 prepaid 的 [[../prepaid/auto-deduction-design]]) |
|
||||
|
||||
**关键**:所有调用方**共用同一份 Action**,业务逻辑只写一遍。
|
||||
|
||||
## 为什么分层
|
||||
|
||||
| 不分层(全部塞 Filament Action)| **三层分层(本设计)** |
|
||||
|---|---|
|
||||
| 一个 Filament Action 500+ 行 | Calculator 100 行 + Service 200 行 + Action 100 行 |
|
||||
| 测试要 mock UI 才能跑 | Calculator 直接单元测试 |
|
||||
| 复用困难(其他调用方要复制粘贴)| 多调用方共用 Action / Service |
|
||||
| 业务逻辑藏在 UI 层(违反层次原则)| 业务逻辑在 Action 层,UI 只是入口 |
|
||||
| 重构成本极高 | 各层独立演化 |
|
||||
|
||||
issue.md 多处提到"清理内联业务逻辑"的迁移(deposit / prepaid / adhoc 都做过),meter 模块**一开始就是这样设计的**,所以没经历这种痛。
|
||||
|
||||
## 测试金字塔
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[Action 层<br/>少数 Feature 测试] --> B[Service 层<br/>中等数 Feature 测试]
|
||||
B --> C[Calculator 层<br/>大量 Unit 测试]
|
||||
```
|
||||
|
||||
- Calculator:大量边界情况单元测试(0 用量、负用量、阶梯边界、min max 触发等)
|
||||
- Service:Feature 测试覆盖业务规则(找业户失败、RatePlan 不存在等)
|
||||
- Action:Feature 测试覆盖批量逻辑(部分失败、空集合、重复 reading 等)
|
||||
|
||||
## 性能与并发
|
||||
|
||||
- 单 reading 生成 Bill: ~50ms(查 RatePlan + 业户 + 建 Bill + 更新 reading)
|
||||
- 批量 100 reading: ~5 秒(顺序执行)
|
||||
- 大规模批量(>1000):分 chunk 处理(Action 内置 / 调用方分批)
|
||||
- 并发安全:每次 `generateBillForReading` 在事务内,reading.bill_id 是数据库约束(unique 也好,not null check 也好),不会重复建 Bill
|
||||
|
||||
## 异常处理
|
||||
|
||||
| 异常 | Service 行为 | Action 报告 |
|
||||
|---|---|---|
|
||||
| RatePlan 不存在 | 抛 `RatePlanNotFoundException` | skipped[reason=rate_plan_not_found] |
|
||||
| asset 没绑业户 | 视设计 — 抛 / 建匿名 Bill / 不建 | skipped[reason=no_resident] |
|
||||
| Bill 建表 DB 错误 | 抛(回滚事务)| skipped[reason=db_error] |
|
||||
| reading 已有 bill_id | Service 不接 / Action 跳过 | skipped[reason=already_billed] |
|
||||
| consumption 是负数(读数倒走)| 视设计 — 抛 / 容错 | skipped[reason=negative_consumption] |
|
||||
|
||||
## 业务人员视角
|
||||
|
||||
在 Filament 后台**几乎感受不到**这三层:
|
||||
|
||||
- 看到的就是 `ViewMeter` 或 `ListMeters` 上的"生成账单"按钮
|
||||
- 点击 → 弹出选择 reading 的 Modal → 提交
|
||||
- 系统报告"X 张账单已生成"
|
||||
- 失败的 reading 列出原因
|
||||
|
||||
底层的 Calculator / Service / Action 对业务人员透明。
|
||||
|
||||
## 架构师视角
|
||||
|
||||
这套分层是**评审新功能**的参考:
|
||||
|
||||
| 新需求 | 该改哪一层 |
|
||||
|---|---|
|
||||
| 加新计价算法(累退 / 二次方等)| Calculator 层(纯算)|
|
||||
| 加业户关联规则(房屋多业主时按比例分摊)| Service 层(业务编排)|
|
||||
| 加新触发场景(微信小程序业户主动结账)| Action 层(入口)+ 新 controller |
|
||||
| 改账单字段(加新字段、改 due_at 计算)| Service 层 |
|
||||
| 加批量优化(并行 / 队列)| Action 层 |
|
||||
|
||||
每层都是**单一职责**,改动局部、不会污染其他层。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [[meter-vs-meter-reading]]
|
||||
- [[multiplier-and-tiered-pricing]]
|
||||
- [[decommission-and-locking]]
|
||||
- [[generate-bill-tiered-pricing]]
|
||||
- [[generate-bill-with-multiplier]]
|
||||
- [[generate-bill-min-max-cap]]
|
||||
- [[../prepaid/auto-deduction-design]](类似的"Service + Action"分层借鉴)
|
||||
244
prop-acc/concepts/meter/multiplier-and-tiered-pricing.md
Normal file
244
prop-acc/concepts/meter/multiplier-and-tiered-pricing.md
Normal file
@@ -0,0 +1,244 @@
|
||||
---
|
||||
title: prop-acc · meter · 倍率与阶梯计价
|
||||
aliases:
|
||||
- 倍率
|
||||
- 阶梯计价
|
||||
- multiplier
|
||||
- tiered pricing
|
||||
- min max 封顶
|
||||
tags:
|
||||
- 概念
|
||||
- prop-acc
|
||||
- 计量表
|
||||
- 计费
|
||||
audience:
|
||||
- 业务人员
|
||||
- 财务
|
||||
- 架构师
|
||||
status: 已发布
|
||||
sub_feature: meter
|
||||
last_review: 2026-05-25
|
||||
code_version: 2026-05-22
|
||||
---
|
||||
|
||||
# 倍率与阶梯计价
|
||||
|
||||
抄表生成账单的金额由三层叠加算出:**倍率(multiplier)** × **阶梯计价(tiered)** + **min/max 封顶**。这三层都在 `MeterBillCalculator` 内实现(纯算,无 DB IO),是 prop-acc 模块中**最严谨的算法之一**。
|
||||
|
||||
## 一句话总览
|
||||
|
||||
```
|
||||
本月用量 = (current_reading - previous_reading) × multiplier
|
||||
本月金额 = 阶梯计价(本月用量, RatePlan)
|
||||
最终金额 = clamp(本月金额, min, max)
|
||||
```
|
||||
|
||||
详见下文每层展开。
|
||||
|
||||
## 第 1 层:倍率(multiplier)
|
||||
|
||||
### 用途
|
||||
|
||||
工业 / 集团表的**实际计量值远大于表头数字**:
|
||||
|
||||
| 表型 | 表头读数 | multiplier | 实际用量 |
|
||||
|---|---|---|---|
|
||||
| 家用单相表 | 280 度 | 1 | 280 度 |
|
||||
| 三相工业表 | 28 度 | **10** | 280 度 |
|
||||
| 大型集团表(高压侧)| 28 度 | **100** | 2,800 度 |
|
||||
|
||||
物理原理:工业表为了在小表头显示大用量,内部有变压 / 分流比。multiplier 就是这个比值。
|
||||
|
||||
### 字段精度
|
||||
|
||||
```php
|
||||
// migration
|
||||
$table->decimal('multiplier', 10, 4);
|
||||
// model casts
|
||||
'multiplier' => 'decimal:4',
|
||||
```
|
||||
|
||||
decimal(10,4) 精度足够工业场景(常见 1.0 / 10.0 / 100.0 / 1000.0,极少数 0.5 / 1.25 等特殊变比)。
|
||||
|
||||
### 用量计算
|
||||
|
||||
```
|
||||
consumption = (current_reading - previous_reading) × multiplier
|
||||
```
|
||||
|
||||
例:三相表上月 280,本月 308,multiplier=10:
|
||||
|
||||
```
|
||||
consumption = (308 - 280) × 10 = 280 度
|
||||
```
|
||||
|
||||
业户账单按"280 度"算,不是"28 度"。
|
||||
|
||||
## 第 2 层:阶梯计价(Tiered Pricing)
|
||||
|
||||
### 用途
|
||||
|
||||
水电气**阶梯递增**:用得越多,单价越高。鼓励节约,符合国家政策。
|
||||
|
||||
例:某市水阶梯计价:
|
||||
|
||||
| 阶梯 | 月用水(吨)| 单价 |
|
||||
|---|---|---|
|
||||
| 第一阶梯 | 0-20 | 3.0 元/吨 |
|
||||
| 第二阶梯 | 21-30 | 4.5 元/吨 |
|
||||
| 第三阶梯 | 30 以上 | 6.0 元/吨 |
|
||||
|
||||
业户本月用 35 吨:
|
||||
|
||||
| 段 | 用量 | 单价 | 段金额 |
|
||||
|---|---|---|---|
|
||||
| 0-20 吨(第一阶梯) | 20 | 3.0 | 60 |
|
||||
| 21-30 吨(第二阶梯) | 10 | 4.5 | 45 |
|
||||
| 31-35 吨(第三阶梯) | 5 | 6.0 | 30 |
|
||||
| **合计** | **35** | | **135** |
|
||||
|
||||
### Progressive 累进 vs Full-tier 简陋实现
|
||||
|
||||
> [!info] 本系统采用 **progressive 累进**(正确算法),不是 full-tier 简陋实现。
|
||||
|
||||
| 算法 | 35 吨水 |
|
||||
|---|---|
|
||||
| **Progressive 累进**(本系统)| 20 × 3 + 10 × 4.5 + 5 × 6 = 135 元 ✅ |
|
||||
| Full-tier 简陋(错)| 35 × 6 = 210 元 ❌(整月用量按最高阶梯计)|
|
||||
| Mixed(更错)| 35 × 4.5 = 157.5 元 ❌ |
|
||||
|
||||
progressive 是国家政策标准做法,简陋实现是市场上劣质系统的常见 bug。`MeterBillCalculator::calculateTiered()` 实现得对,所以我们的账单准确。
|
||||
|
||||
### RatePlan + RateTier 模型
|
||||
|
||||
阶梯定义在 `RatePlan` + `RateTier` 模型里(不属于本子模块,在更通用的费率模块):
|
||||
|
||||
```
|
||||
RatePlan ─── RateTier (1..n)
|
||||
├── tier=1, lower=0, upper=20, unit_price=3.0
|
||||
├── tier=2, lower=20, upper=30, unit_price=4.5
|
||||
└── tier=3, lower=30, upper=null, unit_price=6.0
|
||||
```
|
||||
|
||||
`fee_type_id`(在 Meter 上)指向 RatePlan,Calculator 拿到 RatePlan → 按 tier 累加段金额。
|
||||
|
||||
## 第 3 层:min / max 封顶
|
||||
|
||||
### 用途
|
||||
|
||||
防止**极端用量**导致离谱账单:
|
||||
|
||||
| 场景 | 问题 | 封顶方案 |
|
||||
|---|---|---|
|
||||
| 业户家漏水,1 月用 1000 吨 | 按阶梯算 ~ 6000+ 元 | `max=2000` 封顶,差额走维修保险 |
|
||||
| 表故障读 0 度 | 业户不付钱了 | `min=20` 兜底(至少收基础费)|
|
||||
| 业户家整月没人(零用量)| 看物业政策 | `min=20` 仍要收(物业服务费性质)|
|
||||
|
||||
### 实现
|
||||
|
||||
`RatePlan` 上有 `min_amount` / `max_amount` 字段:
|
||||
|
||||
```
|
||||
final_amount = max(min_amount, min(calculated_amount, max_amount))
|
||||
```
|
||||
|
||||
例:计算出 ¥6,000 但 `max_amount=2000` → 实际收 ¥2,000,差额 ¥4,000 由物业 / 维修保险承担(账面体现为"封顶减免")。
|
||||
|
||||
### 业务上的取舍
|
||||
|
||||
> [!warning] 封顶不是万能的
|
||||
> max 封顶让业户感激,但物业要承担差额。建议:
|
||||
>
|
||||
> - 设合理的 max(覆盖正常波动范围)
|
||||
> - 异常用量先排查([[exception-high-consumption]])再决定是否减免
|
||||
> - 封顶降低收入,需评估对物业财务可持续性影响
|
||||
|
||||
min 类似:
|
||||
|
||||
> [!info] min 的政策意义
|
||||
> min 通常对应"管网维护费 / 基础服务费",即使零用量也要分摊管网成本。但在国家政策严格的地区,要明确告知业户"min 是什么"。
|
||||
|
||||
## 完整算法流程
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[抄表 current_reading] --> B[查询上次 reading]
|
||||
B --> C[计算 consumption =<br/>(current - previous) × multiplier]
|
||||
C --> D[加载 RatePlan + RateTier]
|
||||
D --> E[Calculator.calculateTiered<br/>按阶梯累加段金额]
|
||||
E --> F{有 min/max?}
|
||||
F -->|有 max & 金额超| G[封顶到 max]
|
||||
F -->|有 min & 金额低| H[补到 min]
|
||||
F -->|正常范围| I[原值]
|
||||
G --> J[最终账单金额]
|
||||
H --> J
|
||||
I --> J
|
||||
```
|
||||
|
||||
## 完整算例
|
||||
|
||||
电费阶梯(假设):
|
||||
|
||||
| 阶梯 | 用电度数 | 单价 |
|
||||
|---|---|---|
|
||||
| 1 | 0-200 | 0.5 |
|
||||
| 2 | 200-400 | 0.6 |
|
||||
| 3 | 400+ | 0.8 |
|
||||
|
||||
`min_amount=10`,`max_amount=500`。
|
||||
|
||||
工业表(三相,multiplier=10),5 月抄表 308,上月 280:
|
||||
|
||||
```
|
||||
1. consumption = (308 - 280) × 10 = 280 度
|
||||
2. 阶梯:200 × 0.5 + 80 × 0.6 = 100 + 48 = 148 元
|
||||
3. 封顶:10 ≤ 148 ≤ 500 → 不动
|
||||
4. 最终账单:148 元
|
||||
```
|
||||
|
||||
家用表(multiplier=1),5 月抄表 1100,上月 800:
|
||||
|
||||
```
|
||||
1. consumption = (1100 - 800) × 1 = 300 度
|
||||
2. 阶梯:200 × 0.5 + 100 × 0.6 = 100 + 60 = 160 元
|
||||
3. 封顶:10 ≤ 160 ≤ 500 → 不动
|
||||
4. 最终账单:160 元
|
||||
```
|
||||
|
||||
漏水 case(家用表,水阶梯,multiplier=1),本月用 1000 吨:
|
||||
|
||||
```
|
||||
1. consumption = 1000 吨
|
||||
2. 阶梯:20 × 3 + 10 × 4.5 + 970 × 6 = 60 + 45 + 5820 = 5925 元
|
||||
3. 封顶:5925 > max_amount(假设 2000)→ 封到 2000
|
||||
4. 最终账单:2000 元(差额 3925 由物业 / 维修保险承担)
|
||||
```
|
||||
|
||||
## 业务人员视角
|
||||
|
||||
- **配置阶梯**:在 RatePlan + RateTier 模型里设置(不在 meter 子模块,通常运营 / 财务总监来设)
|
||||
- **配置倍率**:建表时 / 后续编辑表时填(`MeterForm`,默认 1)
|
||||
- **核对账单**:看到异常金额时,顺着 Calculator 算法手工验算
|
||||
|
||||
## 财务视角
|
||||
|
||||
- 阶梯计价 = 政策合规
|
||||
- 倍率确保工业表账单正确
|
||||
- min/max 封顶 = 风险控制 + 业户友好(max)
|
||||
|
||||
## 业户视角
|
||||
|
||||
业户**不需要懂这套算法**,看到的是账单金额。但**对账时**要能理解:
|
||||
|
||||
- 上月读数 → 本月读数 → 用量(度 / 吨 / 立方米)
|
||||
- 用量 → 阶梯单价 → 金额
|
||||
- 如有封顶 → 凭证显示
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [[meter-vs-meter-reading]]
|
||||
- [[bill-generation-pipeline]]
|
||||
- [[generate-bill-tiered-pricing]]
|
||||
- [[generate-bill-with-multiplier]]
|
||||
- [[generate-bill-min-max-cap]]
|
||||
- [[exception-high-consumption]]
|
||||
206
prop-acc/concepts/meter/reading-source-and-photo-proof.md
Normal file
206
prop-acc/concepts/meter/reading-source-and-photo-proof.md
Normal file
@@ -0,0 +1,206 @@
|
||||
---
|
||||
title: prop-acc · meter · 抄表来源与拍照存证
|
||||
aliases:
|
||||
- 抄表来源
|
||||
- 抄表拍照存证
|
||||
- manual vs remote
|
||||
- MeterReadingSource
|
||||
tags:
|
||||
- 概念
|
||||
- prop-acc
|
||||
- 计量表
|
||||
- 数据字典
|
||||
audience:
|
||||
- 业务人员
|
||||
- 抄表员
|
||||
- 财务
|
||||
status: 已发布
|
||||
sub_feature: meter
|
||||
last_review: 2026-05-25
|
||||
code_version: 2026-05-22
|
||||
---
|
||||
|
||||
# 抄表来源与拍照存证
|
||||
|
||||
每条 `MeterReading` 有 **`source` 字段**标记**抄表数据来源**(`manual` 手抄 vs `remote` 集抄),配合 **`photo_url`** 拍照存证,保证抄表数据**可追溯、可核对、有凭据**。
|
||||
|
||||
## `MeterReadingSource` 枚举
|
||||
|
||||
```php
|
||||
enum MeterReadingSource: string
|
||||
{
|
||||
case Manual = 'manual'; // 抄表员手动录入
|
||||
case Remote = 'remote'; // 集抄系统(IoT)自动上报
|
||||
}
|
||||
```
|
||||
|
||||
只有两种,简洁明了。
|
||||
|
||||
## 两种来源对照
|
||||
|
||||
| 维度 | `manual`(手抄)| `remote`(集抄 / IoT)|
|
||||
|---|---|---|
|
||||
| 触发 | 抄表员到现场读表 + 录入 | 物联网集抄系统定时推送 |
|
||||
| 数据流 | 抄表员手机 / 抄表机 → App / 后台 | IoT 网关 → 后端 API → 系统 |
|
||||
| 速度 | 慢(几天到几周完成全社区)| 快(几小时全社区)|
|
||||
| 准确性 | 中(可能手抖 / 看错)| 高(设备直接传)|
|
||||
| 拍照存证 | **推荐**(`photo_url` 必填或强烈推荐)| 自动 |
|
||||
| 操作员(`operated_by`)| 必填(抄表员 ID)| null 或系统账号 |
|
||||
| 业务上常见 | 中小社区 / 老旧设备 | 新建社区 / 升级改造后 |
|
||||
| 故障率 | 抄表员漏抄、误抄、不录入 | IoT 设备掉线、数据丢失 |
|
||||
|
||||
## 拍照存证(`photo_url`)
|
||||
|
||||
### 为什么要拍照
|
||||
|
||||
抄表是物业**收业户钱**的依据。万一业户质疑账单金额,物业要拿出证据"5 月 X 日,您家表头读数确实是 280 度,这是抄表当天的照片"。
|
||||
|
||||
> [!info] 真实情境
|
||||
> 张阿姨 5 月电费账单 ¥168(280 度),她声称"我家不可能用这么多",要看证据。
|
||||
>
|
||||
> 物业打开后台 → 找 5 月那条 reading → 看 `photo_url` → 给业户看现场拍的表头照片("280" 清晰可见,旁边日期戳)→ **业户无话可说**。
|
||||
|
||||
### 实施细节
|
||||
|
||||
| 字段 | 实施 |
|
||||
|---|---|
|
||||
| `photo_url` | 存储到对象存储(S3 / 阿里云 OSS / 本地)的 URL |
|
||||
| 上传时机 | 抄表 App 录入读数同时上传(强制)|
|
||||
| 上传时机(批量导入)| Excel 批量导入时**没有拍照** → 业务上要求抄表员当场拍 + 单独留存,导入时只录数字 |
|
||||
| 上传时机(remote)| 集抄无拍照(IoT 设备本身就是凭证)|
|
||||
| 数据保留 | 法律 / 业务规定保留期(通常 3-5 年),与账单同周期 |
|
||||
|
||||
### 业务流程上的强制度
|
||||
|
||||
| 物业政策 | 实施 |
|
||||
|---|---|
|
||||
| **必须拍照**(严)| `MeterReadingsRelationManager` Form 上 `photo` 字段标 `->required()`,无照片不能提交 |
|
||||
| **建议拍照**(中)| Form 上 `photo` 可空,UI 上有"建议拍照"提示 |
|
||||
| **不强制**(松)| Form 上 `photo` 可空,无任何提示 |
|
||||
|
||||
当前实现**看具体配置**(应该是建议拍照,可空)。生产环境**强烈推荐"必须拍照"**,避免后续举证困难。
|
||||
|
||||
## 集抄(remote)的对接
|
||||
|
||||
### 数据流
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Meter[物理表]
|
||||
participant Gateway[IoT 网关]
|
||||
participant Backend[第三方集抄平台]
|
||||
participant API[本系统 API]
|
||||
participant DB
|
||||
|
||||
Note over Meter: 物理表通过 RS485 / NB-IoT 等连网关
|
||||
|
||||
loop 定时(每天/每月)
|
||||
Meter->>Gateway: 读数推送
|
||||
Gateway->>Backend: 上传(GSM/4G/有线)
|
||||
Backend->>API: HTTP POST(批量推 reading)
|
||||
API->>DB: 建 MeterReading(source=remote)
|
||||
end
|
||||
```
|
||||
|
||||
### 触发账单生成
|
||||
|
||||
集抄推数后**通常立即触发账单生成**(详见 [[bill-generation-pipeline]]):
|
||||
|
||||
- 集抄 API 接收 → 写 MeterReading → 同事务内或立即触发 `GenerateBillsFromMeterReadingsAction`
|
||||
- 或者每月固定时间批量(避免账单生成时机不一致)
|
||||
|
||||
### 集抄掉线的兜底
|
||||
|
||||
| 集抄掉线 | 处置 |
|
||||
|---|---|
|
||||
| 个别表掉线(少数)| 抄表员补抄(`source=manual` + 备注"集抄掉线")|
|
||||
| 大面积掉线(网关故障)| 集抄运维介入 + 物业短期手抄兜底 + 排查恢复 |
|
||||
| 长期掉线(>2 周)| 重新评估集抄设备的可靠性 |
|
||||
|
||||
## 手动抄表的实施
|
||||
|
||||
### 工具
|
||||
|
||||
- 抄表员手机 App(物业自研 / 第三方)
|
||||
- 老式:纸质本子 + 后台输入(误差大,逐步淘汰)
|
||||
|
||||
### 流程
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[抄表员到现场] --> B[读表头]
|
||||
B --> C[拍照]
|
||||
C --> D[App 上录入<br/>读数 + 上传照片]
|
||||
D --> E[同步到后台]
|
||||
E --> F[业务人员审核 / 直接生成账单]
|
||||
```
|
||||
|
||||
### 操作员追踪
|
||||
|
||||
每条 `MeterReading` 有 `operated_by` 字段(抄表员 ID):
|
||||
|
||||
- 业户对账单有疑问 → 后台查 → 看是谁抄的
|
||||
- 抄表员考核:本月抄了多少表、有无遗漏
|
||||
- 异常追责:某抄表员的读数频繁错 → 培训 / 换人
|
||||
|
||||
## 业务人员视角
|
||||
|
||||
后台 `ViewMeter` → 看 Reading 列表(`MeterReadingsRelationManager`),每条 reading 显示:
|
||||
|
||||
| 列 | 内容 |
|
||||
|---|---|
|
||||
| 抄表日期 | `read_at` |
|
||||
| 读数 | `current_reading` |
|
||||
| 用量 | `consumption` |
|
||||
| 来源 | `manual` / `remote`(图标区分)|
|
||||
| 抄表员 | `operated_by`(`manual` 时显示)|
|
||||
| 拍照 | `photo_url`(有图标,点开看照片)|
|
||||
| 备注 | `memo` |
|
||||
|
||||
## 抄表员视角
|
||||
|
||||
抄表员李师傅每月 25-30 号集中抄表:
|
||||
|
||||
- 拿手机 App 出门
|
||||
- 按片区(楼栋)走,App 自动按楼层 / 房号给清单
|
||||
- 每家:开门(若有人)→ 找表 → 读数 → 拍照 → 录入
|
||||
- 数据**实时上传**(网络可用时)或**离线缓存**(无网时回去再传)
|
||||
- 当月所有表抄完 → App 显示"完成度 100%" → 提交
|
||||
|
||||
每天 KPI:60-100 户(看小区密度)。
|
||||
|
||||
## 业户视角
|
||||
|
||||
业户**通常感知不到抄表细节**,只看月底账单。对账单有异议时:
|
||||
|
||||
- 联系物业询问
|
||||
- 物业出示 `photo_url` 证据
|
||||
- 如果证据充分 → 业户认可
|
||||
- 如果证据不足(无照片 + 抄表员说不清)→ 物业可能减免 / 让业户支付平均月用量
|
||||
|
||||
## 系统视角:不可变 + 双锁
|
||||
|
||||
详见 [[meter-vs-meter-reading]] "两者的契约" + [[decommission-and-locking]] "已生成 Bill 的 Reading 锁定" 段。
|
||||
|
||||
- MeterReading 一经创建**不可改**
|
||||
- 一旦生成 Bill 后**更不可改**(Policy 双锁)
|
||||
- 任何错误走"作废 Bill → 改 Reading → 重生成 Bill"的组合流程(详见 [[exception-readings-locked-after-bill]])
|
||||
|
||||
## 待补 / 已知问题
|
||||
|
||||
| 项 | 状态 |
|
||||
|---|---|
|
||||
| 集抄回调签名校验 / 防重放 | 未文档化(可能已实现,看具体集成 |
|
||||
| 抄表照片的对象存储清理(留存期满)| 未实现,需求看物业法务定 |
|
||||
| 抄表员位置 / 时间戳防作弊(GPS + 时间)| 未实现,部分物业有此需求 |
|
||||
| 拍照强制 + AI 识别照片内读数比对录入 | 未实现,高大上但实施成本高 |
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [[meter-vs-meter-reading]]
|
||||
- [[bill-generation-pipeline]]
|
||||
- [[decommission-and-locking]]
|
||||
- [[read-single-meter-manual]]
|
||||
- [[read-batch-via-excel-import]]
|
||||
- [[read-via-iot-remote-source]]
|
||||
- [[read-with-photo-proof]]
|
||||
205
prop-acc/concepts/meter/replacement-chain.md
Normal file
205
prop-acc/concepts/meter/replacement-chain.md
Normal file
@@ -0,0 +1,205 @@
|
||||
---
|
||||
title: prop-acc · meter · 表更换链
|
||||
aliases:
|
||||
- 表更换链
|
||||
- Meter Replacement Chain
|
||||
- replaced_meter_id
|
||||
- R1 R2 后缀
|
||||
tags:
|
||||
- 概念
|
||||
- prop-acc
|
||||
- 计量表
|
||||
- 数据模型
|
||||
audience:
|
||||
- 业务人员
|
||||
- 抄表员
|
||||
- 架构师
|
||||
status: 已发布
|
||||
sub_feature: meter
|
||||
last_review: 2026-05-25
|
||||
code_version: 2026-05-22
|
||||
---
|
||||
|
||||
# 表更换链
|
||||
|
||||
物理表会**老化、损坏、定期校验**。旧表换新表后,系统通过 **`replaced_meter_id`** 字段把新表指回旧表,**初始读数继承**(避免业户被白嫖一段用量)。新表编号自动加 **`-R1` / `-R2` / ...** 后缀,**整条更换链**(代代相承)在数据库里可追溯。
|
||||
|
||||
## 为什么要更换链
|
||||
|
||||
> [!info] 真实情境
|
||||
> 张阿姨家电表(编号 E-501)用了 8 年,2026 年 5 月 物业例行校验发现读数跳变(怀疑表内电路老化),要换新表。
|
||||
>
|
||||
> 换表那天:
|
||||
> - 旧表 E-501 最后读数 = 5,000 度
|
||||
> - 新表 E-501-R1 出厂 = 0 度,但**初始读数继承 5,000 度**
|
||||
> - 否则:新表从 0 起 → 业户下个月看着账单(假设用了 50 度)→ 但系统算的 "5050 - 0 = 5050 度"全要业户付 → 灾难
|
||||
|
||||
更换链保证**用量计算连续**,业户感知无差异。
|
||||
|
||||
## 数据模型
|
||||
|
||||
### 字段关系
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A[Meter 旧表<br/>E-501<br/>final_reading=5000<br/>is_active=false<br/>decommissioned_at=2026-05-15<br/>decommission_reason=Replaced] -->|被 replaced_meter_id 指回| B[Meter 新表<br/>E-501-R1<br/>initial_reading=5000<br/>is_active=true<br/>installed_at=2026-05-15<br/>replaced_meter_id=旧表 ID]
|
||||
```
|
||||
|
||||
### 字段语义
|
||||
|
||||
| Meter 字段 | 旧表(被换)| 新表(替代)|
|
||||
|---|---|---|
|
||||
| `code` | E-501 | **E-501-R1**(`nextReplacementCode()` 自动算)|
|
||||
| `is_active` | **false** | true |
|
||||
| `installed_at` | 8 年前 | 2026-05-15(换表当天)|
|
||||
| `decommissioned_at` | **2026-05-15** | null |
|
||||
| `decommission_reason` | `Replaced`(枚举,见 [[decommission-and-locking]])| null |
|
||||
| `final_reading` | **5000**(换表前最后读数)| null |
|
||||
| `initial_reading` | (历史值,不动)| **5000**(继承自旧表)|
|
||||
| `replaced_meter_id` | null(无上一代)| **旧表 ID** |
|
||||
|
||||
## 换表后的抄表数据
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[E-501 最后 reading<br/>2026-04-30 → 5000 度] --> B[换表 2026-05-15]
|
||||
B --> C[E-501-R1 第一次抄表<br/>2026-05-31 → ?]
|
||||
|
||||
C --> D[计算 5月用量]
|
||||
D --> E{用量公式}
|
||||
E -->|新表上累计读数| F[假设新表读到 50 度<br/>但 initial_reading=5000<br/>所以 current = 5050]
|
||||
F --> G[consumption = (5050 - 5000) * multiplier = 50 度]
|
||||
```
|
||||
|
||||
**关键**:新表 `initial_reading=5000` **不是**抄表的起点,而是用于计算用量的**基准**。下次抄表时:
|
||||
|
||||
```
|
||||
current_reading（新表表头读数 + initial_reading）= 50 + 5000 = 5050
|
||||
previous_reading = 5000（继承自旧表最后读数）
|
||||
consumption = (current - previous) × multiplier = (5050 - 5000) × 1 = 50
|
||||
```
|
||||
|
||||
业户付的就是 5 月实际用的 50 度,不是 5050。
|
||||
|
||||
> [!warning] 抄表员要注意
|
||||
> 抄表系统**显示给抄表员的数字是物理表头的数字**(50),系统**内部存的是叠加值**(5050)。如果系统设计不一致(让抄表员录 5050),会让人困惑。当前实现需查 `MeterReadingsRelationManager` / `MeterReadingsImporter` 看具体如何处理。
|
||||
|
||||
## 整条链的追溯
|
||||
|
||||
一张表可能多次换:
|
||||
|
||||
```
|
||||
E-501 (原生) → E-501-R1 (第一次换) → E-501-R2 (第二次换) → E-501-R3 (第三次换)
|
||||
```
|
||||
|
||||
每张表 `replaced_meter_id` 指上一代。后台 / API 可以:
|
||||
|
||||
```php
|
||||
// 找当前在役表
|
||||
$current = Meter::where('asset_id', $assetId)
|
||||
->where('fee_type_id', $feeType)
|
||||
->where('is_active', true)
|
||||
->first();
|
||||
|
||||
// 顺着链向上追溯
|
||||
$predecessors = [];
|
||||
$cursor = $current;
|
||||
while ($cursor->replaced_meter_id) {
|
||||
$cursor = Meter::find($cursor->replaced_meter_id);
|
||||
$predecessors[] = $cursor;
|
||||
}
|
||||
// $predecessors 现在是 [R2, R1, 原生] 的逆序数组
|
||||
```
|
||||
|
||||
业务上可用于:
|
||||
|
||||
- 业户对历史用量有异议:看哪张表抄出来的
|
||||
- 表更换历史报表
|
||||
- 长期累计用量
|
||||
|
||||
## `nextReplacementCode()` 实现
|
||||
|
||||
代码 `Meter::nextReplacementCode($oldMeterCode)` 算法:
|
||||
|
||||
```php
|
||||
// 伪代码
|
||||
function nextReplacementCode(string $oldCode): string
|
||||
{
|
||||
// E-501 → E-501-R1
|
||||
// E-501-R1 → E-501-R2
|
||||
// E-501-R2 → E-501-R3
|
||||
if (preg_match('/^(.*)-R(\d+)$/', $oldCode, $matches)) {
|
||||
return $matches[1] . '-R' . ($matches[2] + 1);
|
||||
}
|
||||
return $oldCode . '-R1';
|
||||
}
|
||||
```
|
||||
|
||||
业务人员**不需要手动想**新表编号,系统自动算。
|
||||
|
||||
## 操作:`ReplaceMeterAction`
|
||||
|
||||
后台 → 计量表 → 找旧表 → 进 `ViewMeter` → 点 `ReplaceMeterAction`。
|
||||
|
||||
Modal 表单:
|
||||
|
||||
| 字段 | 填什么 |
|
||||
|---|---|
|
||||
| **旧表最后读数(`final_reading`)** | 现场拍照确认,如 `5000` |
|
||||
| **退役原因(`decommission_reason`)** | 选 `Replaced`(其他选项见 [[decommission-and-locking]])|
|
||||
| **退役日期** | 默认今天 |
|
||||
| **新表编号** | 自动 `E-501-R1`(可改但不推荐)|
|
||||
| **新表 multiplier** | 默认继承旧表(可改)|
|
||||
| **新表安装日期** | 默认今天 |
|
||||
| 备注 | "校验未通过,换新表" |
|
||||
|
||||
提交后系统在一个事务内:
|
||||
|
||||
1. 旧表 `is_active=false`, `decommissioned_at=今天`, `decommission_reason=Replaced`, `final_reading=5000`
|
||||
2. 建新表 `is_active=true`, `installed_at=今天`, `replaced_meter_id=旧表.id`, `initial_reading=5000`, `multiplier=继承`
|
||||
|
||||
## 常见问题
|
||||
|
||||
> [!question] 旧表读数比新表初始低,会发生吗?
|
||||
> 不会。新表的 `initial_reading` 就是旧表的 `final_reading`,逻辑上必然相等。
|
||||
|
||||
> [!question] 换表时业户家正在用电怎么处理?
|
||||
> 实际换表过程要断电断水短暂时间,业户可感知。系统层面:
|
||||
>
|
||||
> - 旧表 `decommissioned_at` 和新表 `installed_at` 都填换表那天
|
||||
> - 中间用电量(几分钟到几小时)的微小差异通常忽略
|
||||
> - 严格的物业可在换表说明里告知业户"换表过程几分钟用电不计费"
|
||||
|
||||
> [!question] 换表后旧表的历史 MeterReading 还能查吗?
|
||||
> 能。每条 reading 都关联 `meter_id`(旧表 ID),不会因换表丢失。审计可完整追溯。
|
||||
|
||||
> [!question] 误换表(其实不该换)能撤销吗?
|
||||
> 不能直接撤销(MeterReading 不可变,Meter 状态也不轻易回滚)。要修复:
|
||||
>
|
||||
> - 物理上把新表退役(`is_active=false`, `decommission_reason=Removed`)
|
||||
> - 把旧表重启(`is_active=true`, `decommissioned_at=null`)→ 但这种"复活"操作在 Policy 层可能被守护拒绝([[decommission-and-locking]])
|
||||
>
|
||||
> **预防胜于补救**:换表前确认。
|
||||
|
||||
> [!question] 同一张表换好多次,链很长怎么办?
|
||||
> 链长本身不是问题,系统正常处理。如果链过长(>10 代),通常说明该表频繁出问题,业务上应:
|
||||
>
|
||||
> - 排查表的型号 / 安装环境
|
||||
> - 考虑改型号 / 换品牌
|
||||
> - 长链不影响数据查询性能(关联查询逐级递归,但物业表数量通常不大)
|
||||
|
||||
> [!question] 新表 `multiplier` 与旧表不同可以吗?
|
||||
> 可以,但**强烈不推荐**。如果新换的表倍率不同(例如旧 1x → 新 10x),用量计算公式就变,容易让业户困惑。除非业务上有明确升级原因(从普通家用表换成工业表),否则**继承旧表 multiplier**。
|
||||
|
||||
## 异常分支
|
||||
|
||||
- 表损坏(非校验)→ 走 [[replace-broken-meter]] 场景(meter_decommission_reason=Damaged)
|
||||
- 不换表只退役 → [[decommission-without-replacement]]
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [[meter-vs-meter-reading]]
|
||||
- [[decommission-and-locking]]
|
||||
- [[multiplier-and-tiered-pricing]]
|
||||
- [[replace-broken-meter]]
|
||||
- [[decommission-without-replacement]]
|
||||
Reference in New Issue
Block a user