fujian_water_biz_doc/docs/superpowers/specs/2026-06-08-revenue-bugfix-clear-scope-design.md

营收明确缺陷第一批修复设计

日期：2026-06-08

背景

本设计用于收敛当前营收缺陷中代码证据最明确、可闭环验收的一批问题。前期排查表明，部分缺陷并非单纯后端写库失败，而是前后端接口契约、页面状态文案、查询语义和锁恢复流程不一致导致用户认为“成功但未生效”或“查不到记录”。

本轮不改变账务调整审批规则，不把待审批动作改成即时落账；目标是让系统行为与用户提示一致，并补齐明确漏查和重试闭环。

修复范围

本轮纳入以下缺陷：

• #78 水价调整：执行报错后，用户不应只能关闭菜单从头开始。
• #39 柜台结账：柜台预存缴费记录应能进入待结清并完成结账。
• #50 柜台结账：收费员筛选不应被后端无条件覆盖为当前登录用户。
• #53 柜台收费：预存抵扣金额需要前后端契约保护和回归验证。
• #58/#59 红冲记录：柜台红冲后应能在红冲记录页按红冲时间查到。
• #69/#76 未销分账、呆坏账：前端应准确表达“申请已提交，待审批/待回写”，不得提示为已生效。

以下缺陷不进入本轮实现，仅保留后续复现或产品确认：

• #70 未销调整提示成功但账单未变：现有后端金额/水量调整路径会写回，需要先抓请求体确认字段和值。
• #9 抄表状态修改无影响：需要产品确认状态配置影响已生成任务还是仅影响后续任务。

设计原则

1. 保持最小闭环，不重构完整账务调整体系。
2. 保留现有审批流语义，修正文案和状态展示，不把待审批改为立即落账。
3. 查询接口按业务语义返回数据，页面筛选字段与后端字段一致。
4. 后端对关键金额和状态做兜底校验，前端负责交互提示和用户确认。
5. 所有修改需要有最小单测、前端合约测试或页面 smoke 覆盖。

后端设计

水价调整锁恢复

PriceTemplateServiceImpl.updatePriceTemplate() 继续保持执行完成后释放调价锁的总体策略，但失败路径需要让前端能够明确恢复：

• 后端异常响应保持业务错误信息可读。
• 前端失败后重新进入 startAdjustment() 流程获取新锁。
• PriceTemplateAdjustmentLockRedisDAO.refreshLock() 不再采用 forceUnlock() 后重新 tryLock() 的刷新模式，改为安全续期，避免刷新瞬间锁被其他用户抢占。

柜台预存缴费进入结账

PaymentRecordMapper.selectCounterUnsettledRecords() 从仅查询 CHARGE_PAYMENT 扩展为同时包含 DEPOSIT_TOPUP：

• CHARGE_PAYMENT 表示账单收费记录。
• DEPOSIT_TOPUP 表示柜台预存充值记录。

CounterSettleApplicationServiceImpl.confirm() 需要支持预存充值记录无营业账 ID：

• 结账总金额仍以 PaymentRecord.paymentAmount 汇总。
• 写入结账明细时，chargeId、billMonth 可为空。
• chargeMapper.markCounterSettled() 只处理真实账单收费记录对应的 chargeIds。

收费员筛选

柜台结账查询的收费员解析规则改为：

• 请求 cashierId 为空时，默认使用当前登录用户。
• 请求 cashierId 非空时，使用请求值查询。
• 如后续接入完整数据权限，可在此基础上限制普通用户只能查自己、管理员可查指定收费员。本轮先不让后端无条件覆盖前端筛选值。

预存抵扣校验

柜台收费继续由前端传入 prepayDeductAmount：

• 后端校验抵扣金额不得小于 0。
• 抵扣金额不得超过账单应收金额。
• 抵扣金额不得超过账户预存余额。
• 抵扣金额大于 0 时扣减账户余额，并在支付记录 extJson 中保留 prepayDeductAmount。

本轮不启用后端自动计算抵扣金额，避免改变用户输入语义。

柜台红冲记录查询

红冲记录页应基于柜台结账红冲链路展示，而不是复用账务调整日志：

• 查询来源为 settle_record、settle_record_detail、payment_record 的柜台红冲结果。
• 默认包含部分红冲和全部红冲状态。
• 日期筛选使用红冲时间 reversedTime，而不是账务日志的创建时间或处理时间。
• 返回字段至少包含结账单号、收费员、客户、红冲金额、红冲时间、红冲原因。

前端设计

水价调整失败恢复

水价调整提交失败后，前端不再只把页面退出调整态。推荐交互：

1. 显示调价失败原因。
2. 自动调用 startAdjustment() 尝试重新获取锁。
3. 重新获取成功时保留当前页面数据，提示用户可继续修正后提交。
4. 重新获取失败时提示锁被占用或已过期，并引导用户重新开始调价。

待审批动作状态文案

未销分账、呆坏账、价差调整、违约金减免等提交后，根据响应状态显示文案：

• approvalRequired=true 或 resultStatus=PENDING_APPROVAL：显示“申请已提交，待审批”。
• writeBackStatus=PENDING：显示“待回写”或“待执行”，不刷新为已生效。
• resultStatus=SUCCESS 且 writeBackStatus=UPDATED：显示“处理完成”。

页面不得仅用“提交成功”表达所有结果。

柜台结账页面

未结账列表需要正常展示预存充值记录：

• 无 chargeId、billMonth 时显示 --。
• 客户、收费员、金额、缴费时间正常展示。
• 结账确认汇总包含预存充值金额。

收费员筛选继续保留，前端传入的 cashierId 应与后端查询语义一致。

红冲记录页面

红冲记录页面改为柜台红冲记录视图：

• 查询接口改为柜台红冲记录接口。
• 日期筛选标签改为“红冲时间”。
• 参数使用 beginReversedTime、endReversedTime。
• 列表展示柜台红冲相关字段，不再按账务调整日志字段组织。

预存抵扣交互

柜台收费页面保留当前按选中账单分摊 prepayDeductAmount 的逻辑，并补充交互保护：

• 抵扣金额不得超过预存余额。
• 抵扣金额不得超过选中账单应收合计。
• 用户开启预存抵扣但计算抵扣为 0 时，提交前给出明确提示或确认。

测试设计

后端测试

• 水价调整：覆盖失败后前端可重新开始调价；覆盖刷新锁不释放抢占。
• 柜台结账：覆盖 CHARGE_PAYMENT 和 DEPOSIT_TOPUP 都进入未结账；覆盖预存记录结账时不要求 chargeId。
• 收费员筛选：覆盖请求 cashierId 非空时后端按请求值查询。
• 预存抵扣：覆盖正常抵扣、余额不足、非法金额。
• 红冲记录：覆盖红冲状态默认可查，按 reversedTime 范围筛选。

前端测试

• 水价调整提交失败后重新获取锁或展示重获锁失败提示。
• 分账和呆坏账返回待审批时提示“申请已提交，待审批”。
• 柜台结账未结账列表能展示预存充值记录。
• 红冲记录页调用柜台红冲记录接口，并按红冲时间传参。
• 预存抵扣开启但抵扣金额为 0 时出现确认或提示。

验收标准

1. 用户在水价调整报错后无需关闭菜单即可继续修正并重新提交。
2. 柜台预存缴费能在柜台结账待结清列表中查询并完成结账。
3. 柜台结账收费员筛选不再无条件固定为当前登录用户。
4. 柜台红冲成功后，红冲记录页可按红冲时间查询到记录。
5. 分账、呆坏账等待审批动作不再被前端表达为已生效。
6. 预存抵扣金额写入支付记录并扣减账户余额，非法金额有明确错误。

实施边界

本设计不包含以下内容：

• 不重构完整 REV004 账务调整状态机。
• 不新增完整 BPM 审批能力。
• 不修改呆坏账、分账从待审批到已执行的业务规则。
• 不处理未复现的 #70 和产品规则未确认的 #9。