From d2f6180a3441df3fe9a34ce0dfba2c1bda8a80b7 Mon Sep 17 00:00:00 2001
From: tangweijie <877588133@qq.com>
Date: Tue, 14 Jul 2026 15:34:28 +0800
Subject: [PATCH] docs: design charge then topup continuation

---
 ...r-charge-then-topup-continuation-design.md | 60 +++++++++++++++++++
 1 file changed, 60 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-07-14-counter-charge-then-topup-continuation-design.md

diff --git a/docs/superpowers/specs/2026-07-14-counter-charge-then-topup-continuation-design.md b/docs/superpowers/specs/2026-07-14-counter-charge-then-topup-continuation-design.md
new file mode 100644
index 0000000..686181b
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-14-counter-charge-then-topup-continuation-design.md
@@ -0,0 +1,60 @@
+# 柜台收费缴费后连续预存设计
+
+## 背景与问题
+
+单客户柜台收费完成后，页面会保留刚缴纳的账单作为“收讫”展示行。当前实现同时将这些账单标记为 `displayChargeState: 'settled'` 并继续保留在 `selectedChargeRows` 中。
+
+无欠费预存模式要求页面不存在 `settled` 展示行，因此缴费完成后收费按钮被禁用，用户无法在同一客户、同一页面中继续办理预存。
+
+## 目标
+
+- 单客户普通账单缴费成功后，可以立即继续办理预存。
+- 已缴账单继续显示“收讫”，用于核对和查看账单详情。
+- 已缴账单不得再次进入收费提交数据。
+- 缴费完成后清空上一次实收金额，避免误将账单金额作为预存金额再次提交。
+- 集收号收费逻辑保持不变。
+
+## 方案
+
+### 已缴账单展示状态
+
+单客户普通账单收费成功后：
+
+1. 保留账单展示行；
+2. `payState` 和 `payStateName` 继续表示“收讫”；
+3. 将 `displayChargeState` 设为 `history`，表示该行仅供回看，不再阻塞后续操作；
+4. `displayChargeType` 保持 `bill`，详情继续使用普通账单详情链路。
+
+### 选中状态与金额
+
+- 收费成功后将 `selectedChargeRows` 清空。
+- 调用现有金额同步逻辑后，`actualAmount` 清空。
+- 已缴展示行因 `payState === 1` 继续保持不可勾选，不能再次加入收费数据。
+
+### 预存模式
+
+后台刷新后不存在待缴账单，且历史展示行不计入 `hasSettledChargeDisplay`，因此 `noArrearsTopupMode` 自动成立。收费按钮重新可用，用户输入新的实收金额后，提交路径调用预存接口而不是账单收费接口。
+
+### 集收号边界
+
+集收号收费完成后的展示和按钮限制不调整。集收号模式仍不支持缴费后直接多缴或预存，避免改变现有批量收费约束。
+
+## 异常与安全约束
+
+- 如果收费成功后的账单刷新失败，沿用现有异常提示，不把失败状态误切换成预存模式。
+- 历史收讫行必须不可选择、不可删除，但可以查看详情和打印。
+- 连续预存提交时，支付载荷中不得包含刚缴纳账单的 ID。
+- 页面切换客户或关闭客户时，继续沿用现有状态清理逻辑。
+
+## 测试与验收
+
+新增前端 `node:test` 契约测试，先验证失败再实施：
+
+1. 单客户普通账单收费成功后，收讫展示行使用 `history` 状态；
+2. 收费成功后 `selectedChargeRows` 被清空；
+3. 历史收讫行仍保持 `payState: 1`、`payStateName: '收讫'` 和 `displayChargeType: 'bill'`；
+4. 历史收讫行不阻塞 `noArrearsTopupMode`；
+5. 连续操作时进入 `submitCounterTopup` 路径，不重复调用 `submitCashCharge`；
+6. 集收号收费成功后的现有处理保持不变。
+
+验证运行相关 `node:test`、柜台收费现有测试和前端构建；按用户要求不运行 `vue-tsc`。