fujian_water_biz_doc/docs/superpowers/plans/2026-06-14-account-log-frontend-params.md

# 账务日志前端参数映射修正 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:** 修正账务日志页 `buildQueryParams()` 发送给后端的参数名与 `AccountingAdjustLogPageReqVO` 不匹配的问题，使表单筛选真正生效；同步更新前端 `AccountLogPageReqVO` 类型定义。

**Architecture:** 前端 `buildQueryParams()` 当前将表单字段映射为 `approvalStatus`/`objectType`/`resultStatus` 等前端旧命名，后端 `AccountingAdjustLogPageReqVO` 期望 `status`/`accountType`/`processMethod` 等字段名，且缺少 `deptId`/`custCode`/`createTime` 等关键字段。修正后筛选条件可正常下发，统计面板因后端已修复可直接显示。

**Tech Stack:** Vue 3 + TypeScript, Element Plus, Axios

---

## 文件结构

| 文件 | 职责 |
|---|---|
| `src/api/accountProcess/accountLog/index.ts` | API 类型定义，修正 `AccountLogPageReqVO` |
| `src/views/accountProcess/accountLog/index.vue` | 页面组件，修正 `buildQueryParams()` 映射 |

---

## 参数映射对照表

表单 `queryParams` → 后端期望字段 → 当前错误映射：

| 表单字段 | queryParams key | 后端字段 | 当前前端发送 | 问题 |
|---|---|---|---|---|
| 营业站点 | `deptId` | `deptId` | ❌ 未发送 | 缺失 |
| 客户编号 | `custCode` | `custCode` | ❌ 未发送 | 缺失 |
| 状态 | `status` | `status` | `approvalStatus` | 名称错误 |
| 账务年月 | `accountMonth` | `accountMonth` (List) | `accountMonthStart`/`End` | 缺少 `accountMonth` |
| 账务类型 | `accountType` | `accountType` | `objectType` | 名称错误 |
| 处理方式 | `processMethod` | `processMethod` | `resultStatus` + `writeBackStatus` | 名称错误+重复 |
| 创建时间 | `createTime` | `createTime` | ❌ 未发送 | 缺失 |
| 处理人 | `handler` | `handler` | ❌ 未发送 | 缺失 |
| 处理时间 | `handleTime` | `handleTime` | `operationTime` | 名称错误 |
| 目标户号 | `targetCustCode` | `targetCustCode` | ❌ 未发送 | 缺失 |
| 缴费日期 | `paymentDate` | `paymentDate` | ❌ 未发送 | 缺失 |
| 册本编号 | `bookCode` | `bookCode` | ❌ 未发送 | 缺失 |

---

### Task 1: 修正 AccountLogPageReqVO 类型定义

**Files:**
- Modify: `src/api/accountProcess/accountLog/index.ts`

- [ ] **Step 1: 替换类型定义**

将 `AccountLogPageReqVO` 接口替换为与后端 `AccountingAdjustLogPageReqVO` 对齐的版本：

```typescript
export interface AccountLogPageReqVO {
  /**
   * 调整单号
   */
  adjustmentNo?: string
  /**
   * 营业站点 ID
   */
  deptId?: number
  /**
   * 客户编号
   */
  custCode?: string
  /**
   * 页面状态（兼容前端：1-正常，2-已撤销）
   */
  status?: string
  /**
   * 账务年月范围（兼容前端 monthrange）
   */
  accountMonth?: string[]
  /**
   * 账务年月开始，格式 YYYYMM
   */
  accountMonthStart?: number
  /**
   * 账务年月结束，格式 YYYYMM
   */
  accountMonthEnd?: number
  /**
   * 账务类型
   */
  accountType?: string
  /**
   * 处理方式
   */
  processMethod?: string
  /**
   * 创建时间范围（兼容前端 daterange）
   */
  createTime?: string[]
  /**
   * 创建时间开始
   */
  createTimeStart?: string
  /**
   * 创建时间结束
   */
  createTimeEnd?: string
  /**
   * 处理人
   */
  handler?: string
  /**
   * 处理时间范围（兼容前端 daterange）
   */
  handleTime?: string[]
  /**
   * 处理时间开始
   */
  handleTimeStart?: string
  /**
   * 处理时间结束
   */
  handleTimeEnd?: string
  /**
   * 目标户号
   */
  targetCustCode?: string
  /**
   * 缴费日期范围（兼容前端 daterange）
   */
  paymentDate?: string[]
  /**
   * 缴费日期开始
   */
  paymentDateStart?: string
  /**
   * 缴费日期结束
   */
  paymentDateEnd?: string
  /**
   * 册本编号
   */
  bookCode?: string
  /**
   * 页码，从 1 开始
   */
  pageNo: number
  /**
   * 每页条数，最大值为 100
   */
  pageSize: number
  [property: string]: any
}
```

**设计要点：同时保留 `accountMonth`（数组）和 `accountMonthStart/accountMonthEnd`（数值），后端 `AccountingAdjustLogPageReqVO` 的 getter 方法会优先使用后者，但发送数组可保证 Spring 的日期格式兼容。**

---

### Task 2: 重写 buildQueryParams() 参数映射

**Files:**
- Modify: `src/views/accountProcess/accountLog/index.vue` (仅 `buildQueryParams` 函数)

- [ ] **Step 1: 替换 buildQueryParams 函数**

将当前的 `buildQueryParams`（约 15 行）替换为：

```typescript
const buildQueryParams = (): AccountLogPageReqVO => {
  const [accountMonthStartRaw, accountMonthEndRaw] = queryParams.accountMonth || []
  const [createTimeStartRaw, createTimeEndRaw] = queryParams.createTime || []
  const [handleTimeStartRaw, handleTimeEndRaw] = queryParams.handleTime || []
  const [paymentDateStartRaw, paymentDateEndRaw] = queryParams.paymentDate || []

  return {
    pageNo: queryParams.pageNo,
    pageSize: queryParams.pageSize,
    // 基础字段
    deptId: queryParams.deptId ?? undefined,
    custCode: queryParams.custCode || undefined,
    // 状态：前端 select 值为 "1"/"2"，直接透传给后端 status
    status: queryParams.status || undefined,
    // 账务年月：同时发数组（后端 getAccountMonth() 会解析）+ 数值（后端优先取用）
    accountMonth: queryParams.accountMonth?.length ? queryParams.accountMonth : undefined,
    accountMonthStart: toMonthNumber(accountMonthStartRaw),
    accountMonthEnd: toMonthNumber(accountMonthEndRaw),
    // 账务类型
    accountType: queryParams.accountType || undefined,
    // 处理方式
    processMethod: queryParams.processMethod || undefined,
    // 创建时间
    createTime: queryParams.createTime?.length ? queryParams.createTime : undefined,
    createTimeStart: createTimeStartRaw || undefined,
    createTimeEnd: createTimeEndRaw || undefined,
    // 处理人
    handler: queryParams.handler || undefined,
    // 处理时间
    handleTime: queryParams.handleTime?.length ? queryParams.handleTime : undefined,
    handleTimeStart: handleTimeStartRaw || undefined,
    handleTimeEnd: handleTimeEndRaw || undefined,
    // 目标户号
    targetCustCode: queryParams.targetCustCode || undefined,
    // 缴费日期
    paymentDate: queryParams.paymentDate?.length ? queryParams.paymentDate : undefined,
    paymentDateStart: paymentDateStartRaw || undefined,
    paymentDateEnd: paymentDateEndRaw || undefined,
    // 册本编号
    bookCode: queryParams.bookCode || undefined
  }
}
```

**关键修正点：**
- `approvalStatus` → `status`
- `objectType` → `accountType`
- `resultStatus` / `writeBackStatus`（重复） → `processMethod`
- `operationTime` → `handleTime`
- 新增：`deptId`、`custCode`、`createTime`、`handler`、`targetCustCode`、`paymentDate`、`bookCode`
- 时间字段同时发送数组形式（`createTime: ['2025-01-01','2026-01-29']`）和拆解形式（`createTimeStart`/`createTimeEnd`），后端 `normalizeQuery` 和 getter 均能处理

- [ ] **Step 2: 验证 TypeScript 编译**

```bash
cd /Volumes/Dpan/github/water-workspace/water-frontend
npx vue-tsc --noEmit src/views/accountProcess/accountLog/index.vue 2>&1 | head -20
```

预期：无类型错误。

---

### Task 3: 端到端验证

- [ ] **Step 1: 启动前端 dev server 验证页面**

```bash
cd /Volumes/Dpan/github/water-workspace/water-frontend
npx vite --port 5173 &
sleep 3
echo "Dev server running at http://localhost:5173"
```

- [ ] **Step 2: 验证统计面板**

打开账务日志页面，确认统计值不再是全 0：
- 金额汇总显示格式化货币值（如 `¥12,345.00`）
- 各笔数按颜色区分（成功=绿、失败=红、待审批=橙、通过=蓝）

- [ ] **Step 3: 验证筛选功能**

分别测试以下筛选条件确认数据变化：
- 切换"营业站点"下拉
- 输入"客户编号"查询
- 选择"状态"为"已撤销"

- [ ] **Step 4: 提交**

```bash
cd /Volumes/Dpan/github/water-workspace/water-frontend
git add src/api/accountProcess/accountLog/index.ts src/views/accountProcess/accountLog/index.vue
git commit -m "fix: align account log query params with backend AccountingAdjustLogPageReqVO

- Rewrite AccountLogPageReqVO interface to match backend field names
  (status, accountType, processMethod, handleTime, etc.)
- Add missing fields: deptId, custCode, createTime, handler,
  targetCustCode, paymentDate, bookCode
- Fix buildQueryParams() to send correct parameter names
- Send both array and decomposed date formats for backend compatibility"
```

---

## Self-Review

**1. Spec coverage:** 所有 12 个表单字段的映射错误均已覆盖，TypeScript 类型定义同步更新。

**2. Placeholder scan:** 无 TBD/TODO，所有步骤含具体代码和命令。

**3. Type consistency:**
- `buildQueryParams` 返回 `AccountLogPageReqVO`，所有字段名与 Task 1 中定义一致
- 时间字段同时发送数组形式（`createTime: string[]`）和拆解形式（`createTimeStart: string`），匹配后端 VO 的 getter 逻辑
- `deptId` 使用 `?? undefined` 处理 0 值（根站点），避免被 `||` 误判为 falsy
- 其他字符串字段使用 `|| undefined` 将空字符串转为 undefined