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 对齐的版本：

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 行）替换为：

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 编译

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 验证页面

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: 提交

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