diff --git a/prop-acc/concepts/meter/decommission-and-locking.md b/prop-acc/concepts/meter/decommission-and-locking.md new file mode 100644 index 0000000..ce8b142 --- /dev/null +++ b/prop-acc/concepts/meter/decommission-and-locking.md @@ -0,0 +1,252 @@ +--- +title: prop-acc · meter · 表退役与读数锁定 +aliases: + - 表退役 + - decommission + - 读数锁定 + - reading lock + - MeterDecommissionReason +tags: + - 概念 + - prop-acc + - 计量表 + - 数据完整性 +audience: + - 业务人员 + - 架构师 +status: 已发布 +sub_feature: meter +last_review: 2026-05-25 +code_version: 2026-05-22 +--- + +# 表退役与读数锁定 + +Meter / MeterReading 模块有**两套不可变保护机制**保证数据完整性: + +1. **表退役 (Decommission)** — 表停用后只读,不能改 / 不能删 / 不能继续抄 +2. **读数锁定 (Reading lock)** — Reading 一经创建不可改;**一旦生成 Bill 更不可改 / 不可删** + +两套机制保证**审计可追溯**,防止"事后改数据"导致账单与历史不符。 + +## 第 1 套:表退役机制 + +### 5 种退役原因 + +`MeterDecommissionReason` 枚举: + +| 枚举 | 中文 | 业务场景 | +|---|---|---| +| `Damaged` | 损坏 | 表内电路烧 / 表头读不出 / 物理损坏 | +| `Replaced` | 更换 | 校验未通过 / 老化主动换,新表带 `-R1` 后缀(详见 [[replacement-chain]]) | +| `Removed` | 拆除 | 房屋拆迁 / 业主搬走永久弃用 / 重装时拆掉 | +| `Expired` | 到期 | 表的法定使用年限到(法律规定,需校验后定换或保留)| +| `Calibration` | 校验 | 送检校验中暂停使用(校验后可重启 / 退役)| + +### 退役后的行为 + +```mermaid +stateDiagram-v2 + [*] --> InUse : 装机 + InUse --> InUse : 抄表 / 编辑配置 + InUse --> Decommissioned : decommission() + Decommissioned --> [*] + Decommissioned --> Decommissioned : 只读,不可改 / 不可删 / 不能抄 +``` + +退役表(`is_active=false` + `decommissioned_at` 已填)的能力对照: + +| 操作 | InUse(`is_active=true`)| **Decommissioned(`is_active=false`)** | +|---|---|---| +| `EditAction`(改 code / multiplier / fee_type) | ✅ | **❌**(UI 灰化 + Policy 拦截)| +| `ReplaceMeterAction`(换表)| ✅ | **❌**(已退役无可换)| +| 录新 reading | ✅ | **❌**(业务上无表可读)| +| 看历史 reading | ✅ | ✅(只读)| +| 看历史 Bill | ✅ | ✅(只读)| +| `DeleteAction`(物理删除)| **❌**(UI 移除 + Policy 拦截)| **仅允许"已退役 + 无任何读数"**(罕见)| + +> [!warning] 为什么退役表不能改 code / multiplier +> 退役表是**历史档案**。改 code / fee_type / multiplier 不会回填到历史 reading / Bill,会让"历史档案"和"当时实际计费配置"对不上号: +> +> | 反例 | 后果 | +> |---|---| +> | 已退役表把 multiplier 从 1 改成 10 | 业户翻历史账单,看到 reading consumption 显示翻 10 倍,但当时账单金额没翻 → 业户困惑、质疑系统数据准确性 | +> | 已退役表把 code 改个名 | 历史抄表照片上的物理表号对不上系统 code → 审计追溯断链 | +> +> `EditAction` 在 `is_active=false` 时**三处**(Table 行 / ViewMeter / EditMeter)隐藏,`MeterPolicy::update()` 服务端兜底。 + +### 退役表的物理删除 + +`MeterPolicy::delete()` 默认拦截 —— 退役表是**历史档案**,正常情况下不该删。**唯一允许**: + +```php +// MeterPolicy::delete() +public function delete(AuthUser $user, Meter $meter): bool +{ + return $user->can('delete meters') + && ! $meter->is_active // 必须先退役 + && ! $meter->hasReadings(); // 且无任何读数(罕见,只在"误建表后未抄过"清理) +} +``` + +**业务场景**:某物业误建了张表(填错 asset),还没抄表就发现错了 → 退役 + 删除。 +**反例**:已抄过表的表**绝不能删**,删了会级联抹掉历史 reading + Bill 关联,等于消灭审计证据。 + +> [!info] 历史:issue.md Q5 第二轮的修复 +> 原本 `MeterPolicy` 是**空壳**(从父类继承默认 allow),Table 上的 `DeleteAction` / `DeleteBulkAction` / `EditMeter` 上的 `DeleteAction` 全暴露 → 业务人员一键级联删历史。第二轮修复: +> +> - 删 Table 行 `DeleteAction` +> - 删 Table toolbar `DeleteBulkAction` +> - 删 EditMeter 页 `DeleteAction` +> - `MeterPolicy::delete()` 服务端兜底 +> +> 三处 UI 入口移除 + 一层 Policy 防御 = 双保险。 + +## 第 2 套:Reading 锁定机制 + +### Reading 创建后不可改 + +`MeterReading` 一经创建**只读**(模型设计,无 Update 入口): + +| 字段 | 创建后可改吗 | +|---|---| +| `current_reading` | ❌ | +| `consumption` | ❌(算出来的)| +| `read_at` | ❌ | +| `source` | ❌ | +| `operated_by` | ❌ | +| `photo_url` | ❌ | +| `memo` | ❌(严格)| +| `bill_id` | ❌(由系统填写,业务人员不动)| + +**业务上"修正错误读数"** 走专门流程([[exception-readings-locked-after-bill]]): + +1. **如果还没生成 Bill**:理论上可以删 reading + 重建(看 Policy 允许) +2. **如果已生成 Bill**:必须先**作废 Bill** → 改 reading(实际是建新 reading + 标旧 reading 作废)→ 重生成 Bill + +### 已生成 Bill 的 Reading 更严 + +如果 `MeterReading.bill_id != null`,有**双锁**: + +```mermaid +flowchart TD + A[Reading 创建] --> B[Reading 只读
第 1 锁] + B --> C{有 bill_id 吗?} + C -->|有| D[更不可改
更不可删
第 2 锁] + C -->|无| E[暂时可删
看 Policy] +``` + +`MeterReadingPolicy`: + +```php +// MeterReadingPolicy.php(伪代码) +public function update(AuthUser $user, MeterReading $reading): bool +{ + // 几乎永远 false(Reading 不可改) + return false; +} + +public function delete(AuthUser $user, MeterReading $reading): bool +{ + return $user->can('delete meter readings') + && $reading->bill_id === null; // 已生成 Bill 不可删 +} +``` + +UI 同步: + +- `MeterReadingsRelationManager` 上 `EditAction->visible(fn ($r) => $r->bill_id === null)` +- 已生成 Bill 的 reading 在 UI 上 Edit / Delete 按钮**自动灰化** + +> [!info] 历史:issue.md Q5 第二轮的修复 +> 原本 `MeterReadingsRelationManager` 行级 `DeleteAction` 完全暴露 → 已落账的 reading 可被删除 → Bill 数据脱节、审计断链。第二轮修复: +> +> - 删 `MeterReading.DeleteAction` +> - `EditAction` 加 `->visible(bill === null)` +> - `MeterReadingPolicy::update()` / `delete()` 服务端兜底要求 `bill === null` + +## 两套机制的协同 + +```mermaid +flowchart LR + A[业务人员发现某 reading 数据错] --> B{Reading 有 bill 吗?} + + B -->|没有| C[尝试删 reading
看 Policy 是否允许] + C --> D[重建 reading] + D --> E[重生成 Bill] + + B -->|有| F[先作废 Bill
本身是复杂流程] + F --> G[Reading 上 bill_id 解除
视设计] + G --> H[新建一条修正 reading
+ 标旧 reading 作废] + H --> I[重生成 Bill] +``` + +第二种情况(已生成 Bill)是 issue.md Q5 "待补 / 已知问题"段中提到的: + +> **"作废已生成 Bill 的 MeterReading"组合流程**:当前 Reading 一旦生成 Bill 即锁定。要修正错误读数需要先**作废 Bill** 再改 Reading 再重新生成。这个组合流程类似 AdHocEvent 的 `VoidAction`(级联废 + 留 voided 审计),需要单独设计。 + +**当前实施**:不支持自动化,运维 / 高权限人员手工通过 tinker 处理。常见场景见 [[exception-readings-locked-after-bill]]。 + +## 业务人员视角 + +### 退役表 + +通常场景: + +- 检定到期 → `Calibration` → 送校验 → 校验后视情况 +- 校验未过 → `Replaced` → 走 [[replacement-chain|换表]] +- 物理损坏 → `Damaged` → 走 [[replacement-chain|换表]] 或 `Removed` 不换 +- 业户搬走永久弃用 → `Removed` +- 法定使用年限到 → `Expired` → 视情况换 / 退役 + +### 已锁定的 Reading + +业务上常见的"修正错误读数"诉求: + +- 抄表员手抖录错(2800 录成 2080)→ 已生成 Bill → 走作废 Bill 流程 +- 集抄数据错 → 同上 +- 业户拍照说"实际不是这个数字"→ 拿物理表当前读数对照 → 决定修正与否 + +修正不是常规操作,**预防胜于补救** —— 录入时多审核 + 拍照存证([[reading-source-and-photo-proof]])。 + +## 架构师视角 + +退役 + 锁定两套机制是**严肃的数据治理**: + +- 保证账单与抄表历史**一致性**(不能修改产生过账单的数据) +- 保证物业有**审计抗辩能力**(被业户质疑时拿出原始记录) +- 保证**长期数据可信**(5 年、10 年后的查询仍准确) + +替代方案(允许改)的代价: + +- 业户质疑账单 → 物业拿不出真实凭证 +- 内审查不出账面历史 vs 当时实际配置不一致 +- 法律纠纷物业举证不利 + +## 常见问题 + +> [!question] 已退役表的 Reading 还能新建吗? +> 不能。物理表不存在了,业务上无可读。系统层面 `MeterReadingsRelationManager` 在 `is_active=false` 时隐藏 Create 按钮(应该实现,若没有需补)。 + +> [!question] 错误退役(其实表还好)能撤销吗? +> Policy 设计上**不允许**(`is_active` 从 false 改 true 没 UI 入口)。如果真需要撤销: +> +> - tinker 直接改字段(运维操作,留备注) +> - 或退役表保留 + 建一张新表(`is_active=true`,但失去更换链关联) +> +> **预防胜于补救**:退役前确认。 + +> [!question] Reading 和 Bill 哪个先? +> 时间上:Reading 先(抄表),Bill 后(生成账单)。数据上:Reading 创建即写入,Bill 是 reading 的派生。一旦 Bill 创建,会回写 `Reading.bill_id`。 + +> [!question] 删 Bill 会自动解锁 Reading 吗? +> 当前**不会自动**(Reading.bill_id 不会因为 Bill 删除而自动 nullify,看具体 cascade 配置)。Bill 作废后,需要业务流程明确"是否要重新生成"——如果重新生成,新 Bill 创建时回写 `Reading.bill_id`(覆盖旧的)。 + +## 相关文档 + +- [[meter-vs-meter-reading]] +- [[replacement-chain]] +- [[bill-generation-pipeline]] +- [[exception-readings-locked-after-bill]] +- [[decommission-without-replacement]] +- [[replace-broken-meter]] diff --git a/prop-acc/index.md b/prop-acc/index.md index bc06532..4e521c7 100644 --- a/prop-acc/index.md +++ b/prop-acc/index.md @@ -26,7 +26,7 @@ last_review: 2026-05-25 | **一次性收费** | IC 卡、装修证、泳票等单次购买 | [adhoc 知识地图](maps/adhoc-knowledge-map.md) | ✅ 28 篇 | | **保证金** | 装修押金等代管资金,完工后退还 | [deposit 知识地图](maps/deposit-knowledge-map.md) | ✅ 25 篇 | | **预存款** | 业户预存,自动抵扣月度账单 | [prepaid 知识地图](maps/prepaid-knowledge-map.md) | ✅ 23 篇 | -| **计量表** | 水表/电表/燃气表,抄表生成账单 | _待补_ | 🚧 | +| **计量表** | 水表/电表/燃气表,抄表生成账单 | [meter 知识地图](maps/meter-knowledge-map.md) | 🟡 6 概念已完成,14 场景待补 | | **账单** | 周期性账单 + 计量账单 | _待补_ | 🚧 | | **收款订单** | 一次收款的支付方式、银行账户记录 | _待补_ | 🚧 | | **收据** | 成功收款后生成的凭证 | _待补_ | 🚧 | diff --git a/prop-acc/maps/knowledge-map.md b/prop-acc/maps/knowledge-map.md index 6ca7424..dac166c 100644 --- a/prop-acc/maps/knowledge-map.md +++ b/prop-acc/maps/knowledge-map.md @@ -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 | 收据 | 成功收款后生成的凭证 | _待补_ | 🚧 | diff --git a/prop-acc/maps/meter-knowledge-map.md b/prop-acc/maps/meter-knowledge-map.md new file mode 100644 index 0000000..fe78fe2 --- /dev/null +++ b/prop-acc/maps/meter-knowledge-map.md @@ -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 个场景文档,基于本知识地图骨架填充。