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

> **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` 字段后面添加：

```java
    @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: 编译验证**

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

Expected: BUILD SUCCESS.

- [ ] **Step 3: Commit**

```bash
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 行）：
```html
          <el-table-column label="状态" min-width="100">
            <template #default>未收</template>
          </el-table-column>
```

修改为：
```html
          <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 类型检查**

```bash
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**

```bash
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: 确认修改内容**

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

应显示 6 files changed.

- [ ] **Step 2: 编译确认**

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

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

- [ ] **Step 3: Commit**

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

---