diff --git a/docs/superpowers/plans/2026-07-14-counter-charge-then-topup-continuation.md b/docs/superpowers/plans/2026-07-14-counter-charge-then-topup-continuation.md new file mode 100644 index 0000000..af752e8 --- /dev/null +++ b/docs/superpowers/plans/2026-07-14-counter-charge-then-topup-continuation.md @@ -0,0 +1,197 @@ +# Counter Charge Then Topup Continuation Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** 让单客户普通账单缴费成功后保留收讫记录,同时立即进入可继续预存的状态。 + +**Architecture:** 将单客户刚缴纳的账单保存为只读 `history` 展示行,并清空 `selectedChargeRows`。现有 `noArrearsTopupMode` 会忽略历史展示行并自动切换到预存提交路径;集收号路径不调整。 + +**Tech Stack:** Vue 3、TypeScript、Node.js `node:test`、现有柜台收费状态模型 + +--- + +## File Structure + +- Modify: `water-frontend/tests/operatingCharges/counterChargingPersistentTopup.test.mjs` + - 增加缴费后连续预存的状态契约测试。 +- Modify: `water-frontend/src/views/operatingCharges/counterCharging/index.vue` + - 允许收讫账单使用历史展示状态,并在单客户缴费成功后清空选中行。 +- Create: `water-docs/docs/evidence/bugfix/2026-07-14-counter-charge-then-topup-continuation.md` + - 记录根因、TDD 和回归验证结果。 + +### Task 1: Reproduce the blocked continuation state + +**Files:** +- Modify: `water-frontend/tests/operatingCharges/counterChargingPersistentTopup.test.mjs` + +- [ ] **Step 1: Add a failing test for single-customer post-payment state** + +```js +test('single-customer payment keeps paid bills as history and clears the payable selection', () => { + const submitStart = pageSource.indexOf('const confirmCharge = async') + const submitEnd = pageSource.indexOf('const editCustomer =') + const submitSection = pageSource.slice(submitStart, submitEnd) + + assert.match( + submitSection, + /setSettledChargeDisplayRows\(settledChargeRowsSnapshot,\s*'history'\)[\s\S]*selectedChargeRows\.value\s*=\s*\[\]/ + ) +}) +``` + +- [ ] **Step 2: Add a failing test for history-row semantics and unchanged hub behavior** + +```js +test('paid bill history remains read-only while hub charging keeps its existing settled flow', () => { + assert.match( + pageSource, + /const setSettledChargeDisplayRows = \([\s\S]*displayChargeState:\s*ChargeDisplayRowVO\['displayChargeState'\] = 'settled'[\s\S]*displayChargeState,[\s\S]*displayChargeType:\s*displayType/ + ) + assert.match(pageSource, /payState:\s*1,[\s\S]*payStateName:\s*'收讫'/) + + const submitStart = pageSource.indexOf('const confirmCharge = async') + const submitEnd = pageSource.indexOf('const editCustomer =') + const submitSection = pageSource.slice(submitStart, submitEnd) + assert.match( + submitSection, + /if \(isHubChargeMode\.value\) \{[\s\S]*setSettledHubChargeDisplayRows\(settledChargeRowsSnapshot\)[\s\S]*selectedChargeRows\.value = \[\.\.\.settledChargeRowsSnapshot\]/ + ) +}) +``` + +- [ ] **Step 3: Run the focused test and verify RED** + +Run: + +```bash +node --test tests/operatingCharges/counterChargingPersistentTopup.test.mjs +``` + +Expected: 9 个测试中原有 7 个通过,新增 2 个因缺少历史状态参数和选中行清理而失败。 + +- [ ] **Step 4: Commit the RED test** + +```bash +git add tests/operatingCharges/counterChargingPersistentTopup.test.mjs +git commit -m "test: reproduce blocked charge then topup flow" +``` + +### Task 2: Convert paid bills to non-blocking history rows + +**Files:** +- Modify: `water-frontend/src/views/operatingCharges/counterCharging/index.vue` + +- [ ] **Step 1: Parameterize the paid-bill display state** + +将 `setSettledChargeDisplayRows` 改为: + +```ts +const setSettledChargeDisplayRows = ( + rows: CounterChargingChargeVO[], + displayChargeState: ChargeDisplayRowVO['displayChargeState'] = 'settled', + displayType: ChargeDisplayRowVO['displayChargeType'] = 'bill' +) => { + settledChargeDisplayRows.value = rows.map((row) => ({ + ...row, + payState: 1, + payStateName: '收讫', + displayChargeState, + displayChargeType: displayType + })) +} +``` + +- [ ] **Step 2: Change only the single-customer successful payment branch** + +将普通账单收费成功分支改为: + +```ts +} else { + setSettledChargeDisplayRows(settledChargeRowsSnapshot, 'history') + selectedChargeRows.value = [] +} +syncActualAmountFromSelection() +``` + +集收号分支继续保留: + +```ts +setSettledHubChargeDisplayRows(settledChargeRowsSnapshot) +selectedChargeRows.value = [...settledChargeRowsSnapshot] +``` + +- [ ] **Step 3: Run the focused test and verify GREEN** + +Run: + +```bash +node --test tests/operatingCharges/counterChargingPersistentTopup.test.mjs +``` + +Expected: 9/9 通过。 + +- [ ] **Step 4: Run the existing counter-charging regression test** + +Run: + +```bash +pnpm test:counter-charging +``` + +Expected: 4/4 通过。 + +- [ ] **Step 5: Commit the implementation** + +```bash +git add src/views/operatingCharges/counterCharging/index.vue +git commit -m "fix: allow topup after counter payment" +``` + +### Task 3: Verify and record evidence + +**Files:** +- Create: `water-docs/docs/evidence/bugfix/2026-07-14-counter-charge-then-topup-continuation.md` + +- [ ] **Step 1: Run the combined focused tests** + +Run: + +```bash +node --test tests/operatingCharges/counterChargingPersistentTopup.test.mjs tests/operatingCharges/counterChargingInventory.test.mjs +``` + +Expected: 13/13 通过。 + +- [ ] **Step 2: Run the frontend build** + +Run: + +```bash +NODE_OPTIONS=--max-old-space-size=8192 pnpm build:dev +``` + +Expected: 退出码 `0`,输出 `Build successful. Please see dist directory`。 + +不得运行 `vue-tsc`、`pnpm ts:check` 或任何会调用 `vue-tsc` 的命令。 + +- [ ] **Step 3: Check the final diff** + +Run: + +```bash +git diff --check develop...HEAD +git status --short +``` + +Expected: 无空白错误,前端 worktree 干净。 + +- [ ] **Step 4: Record exact evidence** + +证据文档记录:阻塞根因、RED 结果 7 通过/2 失败、GREEN 结果 9/9、组合测试 13/13、构建成功、集收号路径未调整,以及未运行 `vue-tsc`。 + +- [ ] **Step 5: Commit evidence** + +```bash +git add docs/evidence/bugfix/2026-07-14-counter-charge-then-topup-continuation.md +git commit -m "docs: record charge then topup verification" +```