docs: design counter topup detail display

docs/superpowers/specs/2026-07-14-counter-topup-detail-design.md

@@ -0,0 +1,77 @@
+# 柜台收费预存款详情展示修复设计
+
+## 背景与问题
+
+柜台收费在客户无欠费时支持办理预存。预存成功后，页面会把支付记录作为一条只读的“预存款”记录展示。
+
+当前预存款行的 `id` 是支付记录 ID，但点击“详情”时统一调用 `/business/charge/get`，该接口要求账单 ID。由于对象类型和 ID 语义不一致，账单详情弹窗无法取得数据，所有字段显示为 `--`。
+
+## 目标
+
+- 预存款记录点击“详情”时展示符合预存业务语义的信息。
+- 预存款详情不得调用账单详情接口。
+- 普通账单详情链路保持不变。
+- 历史恢复的最新预存记录与刚办理成功的预存记录使用同一套详情展示。
+
+## 非目标
+
+- 不新增后端支付记录详情接口。
+- 不改造普通账单详情接口。
+- 不扩展为完整的历史预存记录列表。
+- 不调整预存、收费或余额入账逻辑。
+
+## 方案
+
+### 详情分流
+
+点击详情时根据行的 `displayChargeType` 判断记录类型：
+
+- `topup`：打开预存款专用详情，不调用 `/business/charge/get`。
+- `bill` 或未标记：继续使用现有账单详情链路。
+
+### 预存详情数据
+
+预存款显示行补充并保留以下支付快照字段：
+
+- 支付记录 ID
+- 预存金额
+- 收费时间
+- 收费方式
+- 期初余额
+- 期末余额
+- 收费状态
+
+客户编号、客户名称、客户地址优先取当前客户信息；支付字段取预存记录行。历史恢复时使用 `/business/charge/payment-record/page-new` 已返回的 `lastDeposit`、`deposit`、`actualMoney`、`chargeWay` 和支付时间。
+
+刚办理成功的预存记录在刷新最新预存记录后展示，以确保详情字段与持久化支付记录一致；若刷新失败，则保留成功响应和当前客户信息作为降级展示，不影响预存成功结果。
+
+### 页面展示
+
+预存款专用详情使用独立弹窗，展示：
+
+1. 客户编号、客户名称、客户地址；
+2. 业务类型（固定为“预存款”）、支付记录 ID；
+3. 预存金额、期初余额、期末余额；
+4. 收费时间、收费方式、收费状态（“收讫”）。
+
+不展示账务年月、抄码、水量、账单金额、违约金、开票状态等账单专属字段。
+
+## 异常处理
+
+- 预存行缺少支付记录 ID 时，不发起账单详情请求，提示“预存记录信息不完整”。
+- 金额或余额为 `0` 时必须显示 `0.00`，不得因假值判断显示 `--`。
+- 期初或期末余额确实缺失时显示 `--`。
+- 普通账单详情请求失败时沿用现有错误提示和关闭弹窗行为。
+
+## 测试与验收
+
+新增前端 `node:test` 契约测试，先验证失败再实施修复，覆盖：
+
+1. 预存款详情按 `displayChargeType === 'topup'` 分流；
+2. 预存款详情不调用 `getChargeById`；
+3. 专用弹窗包含客户、支付、余额和状态字段；
+4. 历史预存记录映射 `lastDeposit` 与 `deposit`；
+5. 普通账单仍调用原账单详情接口；
+6. `0` 金额与余额正确显示。
+
+验证仅运行相关 `node:test`、柜台收费现有测试和前端构建；按用户要求不运行 `vue-tsc`。