fujian_water_biz_doc/docs/superpowers/plans/2026-06-10-prestore-error-handling-and-frontend-display.md

预存余额错误处理修复 + 柜台收费开票/分账状态展示

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: 修复 3 类异常处理缺陷 + 柜台收费主表格增加开票状态和分账状态列。

Architecture: 后端 3 处异常处理修正已完成(未提交)，本次计划覆盖剩余 2 项：后端 VO 加字段 + 前端表格加列。BeanUtils.toBean 自动映射同名属性，后端改动最小。

Tech Stack: Spring Boot 3, MyBatis-Plus, Vue 3, Element Plus, TypeScript

---

已完成修改 (未提交)

文件	修改内容
ChargeServiceImpl.java:2276-2281	catch(Exception) 不再包装为 IllegalArgumentException，改为 exception(INTERNAL_SERVER_ERROR)
ChargeServiceImpl.java:2446-2448	开票状态校验从 != NOT_INVOICED 改为仅拦截 PARTIALLY_INVOICED 和 INVOICE_COMPLETED
PrestorageAdjustInternalApiImpl.java:194-200	catch 内 DB 更新加嵌套 try-catch，防止状态更新失败吞异常
BadDebt/PriceDiff/LateFeeReduce/Writtenoff AdjustInternalApiImpl	catch 内 .message(e.getMessage()) 加 null-safe

---

Task 1: 后端 — ChargeDetailsPageRespVO 加分账字段

Files:

• Modify: sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/charge/vo/ChargeDetailsPageRespVO.java (在 invoiceStateName 之后插入)

Purpose: 柜台收费主表格 API (/business/charge/page-details) 返回 splitAdjustId、splitStatus 字段，供前端展示分账状态。ChargeDO 已有这两个字段，只需在 VO 中声明即可自动映射。

• Step 1: 在 ChargeDetailsPageRespVO 添加字段

在 ChargeDetailsPageRespVO.java 的 invoiceStateName 字段后面添加：

    @Schema(description = "分账调整主表ID")
    private Long splitAdjustId;

    @Schema(description = "分账状态：NONE/PARENT_SPLIT/SPLIT_CHILD")
    @ExcelProperty("分账状态")
    private String splitStatus;

位置：invoiceStateName 字段声明之后、meterOthType 字段之前。BeanUtils.toBean 自动从 ChargeDO.splitAdjustId / ChargeDO.splitStatus 映射。

• Step 2: 编译验证

cd /Volumes/Dpan/github/water-workspace/water-backend/sw-business/sw-business-server && mvn compile -o

Expected: BUILD SUCCESS.

• Step 3: Commit

cd /Volumes/Dpan/github/water-workspace/water-backend
git add sw-business/sw-business-server/src/main/java/cn/com/emsoft/sw/business/controller/admin/charge/vo/ChargeDetailsPageRespVO.java
git commit -m "feat(charge): ChargeDetailsPageRespVO 加分账字段 splitAdjustId + splitStatus"

---

Task 2: 前端 — 柜台收费主表格加开票状态 + 分账状态列

Files:

• Modify: water-frontend/src/views/operatingCharges/counterCharging/index.vue:206-208 (在"状态"列之后插入两列)

Purpose: 待缴账单表格中，在"状态"列后面加"开票状态"（已有后端字段 invoiceStateName）和"分账状态"（新后端字段 splitStatus），让操作员预判操作是否会被拦截。

• Step 1: 在待缴账单表格加两列

当前代码（约 206-208 行）：

          <el-table-column label="状态" min-width="100">
            <template #default>未收</template>
          </el-table-column>

修改为：

          <el-table-column label="状态" min-width="100">
            <template #default>未收</template>
          </el-table-column>
          <el-table-column prop="invoiceStateName" label="开票状态" min-width="100">
            <template #default="{ row }">{{ row.invoiceStateName || '-' }}</template>
          </el-table-column>
          <el-table-column label="分账" min-width="90">
            <template #default="{ row }">
              <el-tag v-if="row.splitStatus === 'PARENT_SPLIT'" type="warning" size="small">已分账</el-tag>
              <el-tag v-else-if="row.splitStatus === 'SPLIT_CHILD'" type="info" size="small">子账单</el-tag>
              <span v-else>-</span>
            </template>
          </el-table-column>

• Step 2: 集收号模式下的子表格也同样加列

找到集收号子表格（约 75-89 行，getHubCustomerCharges 对应的 el-table），在"状态"列后同样插入上述两列。列定义相同。

• Step 3: TypeScript 类型检查

cd /Volumes/Dpan/github/water-workspace/water-frontend && npx vue-tsc --noEmit 2>&1 | grep "counterCharging" | head -10

Expected: 无新增错误（CounterChargingChargeVO 声明了 [key: string]: any，新字段不会报类型错误）。

• Step 4: Commit

cd /Volumes/Dpan/github/water-workspace/water-frontend
git add src/views/operatingCharges/counterCharging/index.vue
git commit -m "feat(counter): 柜台收费表格加开票状态 + 分账状态列"

---

Task 3: 提交全部后端异常处理修复

Files: (已在工作区修改，待提交)

• ChargeServiceImpl.java

• PrestorageAdjustInternalApiImpl.java

• BadDebtAdjustInternalApiImpl.java

• PriceDiffAdjustInternalApiImpl.java

• LateFeeReduceInternalApiImpl.java

• WrittenoffAdjustInternalApiImpl.java

• Step 1: 确认修改内容

cd /Volumes/Dpan/github/water-workspace/water-backend && git diff --stat

应显示 6 files changed.

• Step 2: 编译确认

cd /Volumes/Dpan/github/water-workspace/water-backend/sw-business/sw-business-server && mvn compile -o

Expected: BUILD SUCCESS (仅 WARNING，无 ERROR).

• Step 3: Commit

cd /Volumes/Dpan/github/water-workspace/water-backend
git add -A
git commit -m "fix: 异常处理修正 — handleUsageAdjust 不伪装 400 + invoiceState 放宽 + InternalApi catch 加固"

---