fujian_water_biz_doc/docs/superpowers/plans/2026-06-08-arrearage-reminder-frontend.md

催缴登记 (Arrearage Reminder) 前端对接 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: 将两个前端页面（欠费催缴池 + 催缴记录）从 mock 数据切换到真实后端 API，包括 API 层补齐、催缴表单对接、汇总统计、导出功能。

Architecture: 后端 9 个接口均已就绪 (POST /create, GET /page, GET /pending-page, GET /get, GET /detail-list, POST /batch-create, GET /pending-summary, GET /pending-export, GET /pending-detail-export)。前端按 "API 层 → 催缴表单 → 欠费池页面 → 催缴记录页面" 的顺序逐层对接，每层完成后可独立验证。

Tech Stack: Vue 3, TypeScript, Element Plus, Axios (@/config/axios), pnpm

---

File Structure

API layer

• Modify: ../water-frontend/src/api/collectionManage/arrears/index.ts
  • 新增所有请求/响应 VO 类型 + 7 个缺失的 API 方法

Components

• Modify: ../water-frontend/src/views/collectionManage/arrears/components/RemindForm.vue
  • 对接 batchCreate API，接收父组件传入的选中行数据

Views

• Modify: ../water-frontend/src/views/collectionManage/arrears/index.vue
  • 汇总统计条对接 getPendingSummary、导出对接 getPendingExportList、催缴按钮传递选中数据给 RemindForm
• Modify: ../water-frontend/src/views/collectionManage/collectionRecord/index.vue
  • 列表对接 getPage、详情展开对接 getDetailList、导出对接后端（如有对应接口）
  • 查询表单字段对齐 ArrearageReminderPageReqVO

---

Task 1: 补齐 API 层 — 类型定义与全部接口方法

Files:

• Modify: ../water-frontend/src/api/collectionManage/arrears/index.ts

• Step 1: 添加所有 VO 类型定义和 API 方法

import request from '@/config/axios'
import download from '@/utils/download'

// ========== 请求 VO ==========

export interface ArrearagePendingPageReqVO {
  pageNo: number
  pageSize: number
  deptId?: number
  code?: string
  name?: string
  address?: string
  mobile?: string
  custStates?: number[]
  custType?: number
  billMonthStart?: number
  billMonthEnd?: number
  meterReaderId?: number
  bookCode?: string
  arrearsCountMin?: number
  arrearsCountMax?: number
  arrearsAmountMin?: number
  arrearsAmountMax?: number
  remindFilter?: string
}

export interface ArrearageReminderPageReqVO {
  pageNo: number
  pageSize: number
  custId?: number
  reminderUser?: string
  reminderType?: number
  reminderReason?: number
  reminderResult?: number
}

export interface ArrearageReminderCreateReqVO {
  custId: number
  chargeIds: number[]
  reminderType: number
  reminderReason: number
  reminderResult: number
  reminderUser: string
  reminderTemplate?: number
  remark?: string
}

export interface ArrearageReminderBatchCreateReqVO {
  customers: {
    custId: number
    chargeIds: number[]
  }[]
  reminderType: number
  reminderReason: number
  reminderResult: number
  reminderUser: string
  reminderTemplate?: number
  remark?: string
}

// ========== 响应 VO ==========

export interface ArrearagePendingPageRespVO {
  custId: number
  custCode: string
  custName: string
  custAddress: string
  meterCaliber: string
  waterNature: string
  arrearsCount: number
  waterVolume: number
  totalAmount: number
  penaltyAmount: number
  receivableAmount: number
  billAmount: number
  accountMonthRange: string
  custStatus: string
  prestoreAmount: number
  mobile: string
  isRemindedThisMonth: boolean
  agreementNo: string
  contractNo: string
  details: ArrearagePendingChargeDetailRespVO[]
}

export interface ArrearagePendingChargeDetailRespVO {
  chargeId: number
  billMonth: string
  lastReading: number
  currentReading: number
  waterVolume: number
  billAmount: number
  penaltyAmount: number
  readingDate: string
}

export interface ArrearagePendingSummaryRespVO {
  custCount: number
  arrearsCount: number
  waterVolume: number
  billAmount: number
  penaltyAmount: number
  totalAmount: number
  receivableAmount: number
}

export interface ArrearageReminderPageRespVO {
  id: number
  custId: number
  custCode: string
  custName: string
  reminderType: number
  reminderReason: number
  reminderUser: string
  remark: string
  reminderTemplate: number
  completeTime: string
  pushState: number
  pushResults: string
  reminderResult: number
  batchStamp: string
  totalBillWater: number
  totalExtendedAmount: number
  totalLateFee: number
  deposit: number
  mobile: string
  createTime: string
  updateTime: string
}

export interface ArrearageReminderRespVO extends ArrearageReminderPageRespVO {}

export interface ArrearageReminderDetailRespVO {
  id: number
  arrearageReminderId: number
  chargeId: number
  lateFee: number
  createTime: string
  updateTime: string
}

export interface ArrearageReminderCreateRespVO {
  id: number
  detailCount: number
}

export interface ArrearageReminderBatchCreateRespVO {
  successCount: number
  failCount: number
  successItems: { custId: number; reminderId: number; detailCount: number }[]
  failItems: { custId: number; reason: string }[]
}

// ========== API 方法 ==========

export const ArrearsApi = {
  // 待催欠费池
  getPendingPage: async (params: ArrearagePendingPageReqVO) => {
    return await request.get<{ list: ArrearagePendingPageRespVO[]; total: number }>({
      url: '/business/arrearage-reminder/pending-page',
      params
    })
  },

  getPendingSummary: async (params: ArrearagePendingPageReqVO) => {
    return await request.get<ArrearagePendingSummaryRespVO>({
      url: '/business/arrearage-reminder/pending-summary',
      params
    })
  },

  // 催缴登记 CRUD
  create: async (data: ArrearageReminderCreateReqVO) => {
    return await request.post<ArrearageReminderCreateRespVO>({
      url: '/business/arrearage-reminder/create',
      data
    })
  },

  batchCreate: async (data: ArrearageReminderBatchCreateReqVO) => {
    return await request.post<ArrearageReminderBatchCreateRespVO>({
      url: '/business/arrearage-reminder/batch-create',
      data
    })
  },

  getPage: async (params: ArrearageReminderPageReqVO) => {
    return await request.get<{ list: ArrearageReminderPageRespVO[]; total: number }>({
      url: '/business/arrearage-reminder/page',
      params
    })
  },

  get: async (id: number) => {
    return await request.get<ArrearageReminderRespVO>({
      url: '/business/arrearage-reminder/get',
      params: { id }
    })
  },

  getDetailList: async (reminderId: number) => {
    return await request.get<ArrearageReminderDetailRespVO[]>({
      url: '/business/arrearage-reminder/detail-list',
      params: { reminderId }
    })
  },

  // 导出
  exportPending: async (params: ArrearagePendingPageReqVO) => {
    const res = await request.download({
      url: '/business/arrearage-reminder/pending-export',
      params
    })
    download.response(res, '待催欠费客户.xlsx')
  },

  exportPendingDetail: async (params: ArrearagePendingPageReqVO) => {
    const res = await request.download({
      url: '/business/arrearage-reminder/pending-detail-export',
      params
    })
    download.response(res, '待催欠费明细.xlsx')
  }
}

• Step 2: 验证 API 层编译

Run: cd ../water-frontend && npx vue-tsc --noEmit src/api/collectionManage/arrears/index.ts 2>&1 | head -20 Expected: No type errors

---

Task 2: RemindForm 对接 batchCreate API

Files:

• Modify: ../water-frontend/src/views/collectionManage/arrears/components/RemindForm.vue

• Step 1: 重写 RemindForm 脚本，接收选中行 props 并调 batchCreate

将 <script setup lang="ts"> 段替换为：

import { ArrearsApi } from '@/api/collectionManage/arrears'

const message = useMessage()
const dialogVisible = ref(false)
const formRef = ref()

const props = defineProps<{
  selectedRows: any[]
}>()

// reminderType 映射: '催缴单'->1, '短信'->2, '电话'->3, '微信'->4, '其它'->5, '热线'->6
const methodMap: Record<string, number> = {
  '催缴单': 1, '短信': 2, '电话': 3, '微信': 4, '其它': 5, '热线': 6
}

const formData = ref({
  method: '催缴单',
  operator: '',
  reason: '',
  remark: ''
})

const rules = {
  method: [{ required: true, message: '请选择催缴方式', trigger: 'change' }],
  operator: [{ required: true, message: '请选择催缴人员', trigger: 'change' }],
  reason: [{ required: true, message: '请选择催缴原因', trigger: 'change' }]
}

const open = () => {
  dialogVisible.value = true
  formData.value = {
    method: '催缴单',
    operator: '',
    reason: '',
    remark: ''
  }
}

const submitForm = async () => {
  if (!formRef.value) return
  await formRef.value.validate(async (valid: boolean) => {
    if (!valid) return
    try {
      const customers = props.selectedRows.map((row: any) => ({
        custId: row.custId,
        chargeIds: row.details?.map((d: any) => d.chargeId) || []
      }))
      const res = await ArrearsApi.batchCreate({
        customers,
        reminderType: methodMap[formData.value.method] || 1,
        reminderReason: Number(formData.value.reason),
        reminderResult: 0,
        reminderUser: formData.value.operator,
        remark: formData.value.remark
      })
      if (res.failCount > 0) {
        const failMsgs = res.failItems.map((f: any) => `客户${f.custId}: ${f.reason}`).join('; ')
        message.warning(`成功 ${res.successCount} 条，失败 ${res.failCount} 条。${failMsgs}`)
      } else {
        message.success(`成功创建 ${res.successCount} 条催缴记录`)
      }
      dialogVisible.value = false
      emit('success')
    } catch (e: any) {
      message.error(e?.message || '催缴失败')
    }
  })
}

const emit = defineEmits(['success'])
defineExpose({ open })

• Step 2: 修改父组件传参 — 更新 arrears/index.vue 中 RemindForm 的使用

在 ../water-frontend/src/views/collectionManage/arrears/index.vue 底部模板中：

<!-- 修改前 -->
<RemindForm ref="remindFormRef" @success="handleSuccess" />

<!-- 修改后 -->
<RemindForm ref="remindFormRef" :selected-rows="selectedRows" @success="handleSuccess" />

• Step 3: 验证编译

Run: cd ../water-frontend && npx vue-tsc --noEmit 2>&1 | tail -20 Expected: No type errors (may have pre-existing errors in other files, check only arrearage-related)

---

Task 3: 欠费催缴池页面 — 汇总统计 + 导出 + 全选催缴

Files:

• Modify: ../water-frontend/src/views/collectionManage/arrears/index.vue

• Step 1: 添加汇总统计数据获取

在 getList 调用后追加 summary 请求。找到 script setup 中的 getList 函数（约 line 629），在其后添加：

const summary = ref<{
  custCount: number
  arrearsCount: number
  waterVolume: number
  billAmount: number
  penaltyAmount: number
  totalAmount: number
  receivableAmount: number
}>({
  custCount: 0, arrearsCount: 0, waterVolume: 0,
  billAmount: 0, penaltyAmount: 0, totalAmount: 0, receivableAmount: 0
})

const fetchSummary = async () => {
  try {
    summary.value = await ArrearsApi.getPendingSummary(buildPageParams())
  } catch {
    // summary stays at zero
  }
}

修改 handleQuery 和 onMounted 中的 getList() 调用为并行：

const handleQuery = () => {
  queryParams.pageNo = 1
  Promise.all([getList(), fetchSummary()])
}

并在 onMounted 中：

onMounted(async () => {
  await Promise.resolve(getSiteTree())
  await Promise.all([getList(), fetchSummary()])
})

• Step 2: 替换模板中的硬编码统计值为真实数据

找到 <el-descriptions> 区域（约 line 211-226），替换其中各 el-descriptions-item 的值为 summary 响应式数据：

<el-descriptions :column="5" class="mt-15px mb-8px" border label-width="120">
  <el-descriptions-item label="客户数">
    <span class="text-orange-500 font-bold">{{ summary.custCount }}</span>
  </el-descriptions-item>
  <el-descriptions-item label="欠费笔数">
    <span class="text-orange-500 font-bold">{{ summary.arrearsCount }}</span>
  </el-descriptions-item>
  <el-descriptions-item label="用水量">
    <span class="text-orange-500 font-bold">{{ summary.waterVolume }}</span>
  </el-descriptions-item>
  <el-descriptions-item label="合计金额">
    <span class="text-orange-500 font-bold">¥{{ summary.totalAmount }}</span>
  </el-descriptions-item>
  <el-descriptions-item label="账单金额">
    <span class="text-orange-500 font-bold">¥{{ summary.billAmount }}</span>
  </el-descriptions-item>
  <el-descriptions-item label="违约金">
    <span class="text-orange-500 font-bold">¥{{ summary.penaltyAmount }}</span>
  </el-descriptions-item>
  <el-descriptions-item label="应缴金额">
    <span class="text-orange-500 font-bold">¥{{ summary.receivableAmount }}</span>
  </el-descriptions-item>
</el-descriptions>

• Step 3: 导出对接真实 API

找到 handleExport 函数（约 line 663），替换为：

const handleExport = async () => {
  try {
    message.loading('正在导出...')
    await ArrearsApi.exportPending(buildPageParams())
    message.success('导出成功')
  } catch {
    message.error('导出失败')
  }
}

• Step 4: 全部催缴传参

找到 handleRemindAll（约 line 657），当前直接 remindFormRef.value.open()，需要传入当前列表中所有行的数据。修改为：

const handleRemindAll = () => {
  selectedRows.value = list.value
  remindFormRef.value.open()
}

• Step 5: 从 API 导入汇总相关方法

在 arrears/index.vue 的 import 中，ArrearsApi 的导入行保持不变（当前已导入），新增 summary ref 定义的位置放到 selectedRows 附近。

• Step 6: 验证编译

Run: cd ../water-frontend && npx vue-tsc --noEmit 2>&1 | tail -20 Expected: No new type errors from arrears files

---

Task 4: 催缴记录页面 — 列表与详情对接

Files:

• Modify: ../water-frontend/src/views/collectionManage/collectionRecord/index.vue

• Step 1: 添加 API 导入

在 script setup 顶部 import 中加入：

import { ArrearsApi } from '@/api/collectionManage/arrears'

• Step 2: 添加详情数据 ref 和获取方法

在 list ref 附近（约 line 294）追加：

const detailMap = ref<Record<number, any[]>>({})

const fetchDetailList = async (reminderId: number) => {
  if (detailMap.value[reminderId]) return
  try {
    const details = await ArrearsApi.getDetailList(reminderId)
    detailMap.value[reminderId] = details
  } catch {
    detailMap.value[reminderId] = []
  }
}

• Step 3: 替换 getList 为真实 API 调用

找到现有的 getList 函数（当前为 mock 数据），替换为：

const getList = async () => {
  loading.value = true
  try {
    const data = await ArrearsApi.getPage({
      pageNo: queryParams.pageNo,
      pageSize: queryParams.pageSize,
      custId: undefined, // 后续可扩展
      reminderUser: queryParams.remindUser || undefined,
      reminderType: undefined,
      reminderReason: queryParams.remindReason ? Number(queryParams.remindReason) : undefined,
      reminderResult: queryParams.remindResult ? Number(queryParams.remindResult) : undefined
    })
    list.value = (data?.list || []).map((item: any) => ({
      ...item,
      id: item.id,
      deptName: item.deptName || '-',
      custCode: item.custCode,
      custName: item.custName,
      custAddress: item.custAddress || '-',
      remindUser: item.reminderUser,
      remindMethod: item.reminderType,
      remindReason: item.reminderReason,
      mobile: item.mobile,
      arrearsCount: 0, // reminder records don't carry count — fetched via details
      arrearsWaterVolume: item.totalBillWater,
      arrearsAmount: item.totalExtendedAmount,
      penaltyAmount: item.totalLateFee,
      prestoreBalance: item.deposit,
      completeDate: item.completeTime,
      registerDate: item.createTime,
      remark: item.remark,
      expanded: false,
      pushStatus: item.pushState,
      details: []
    }))
    total.value = data?.total || 0
  } finally {
    loading.value = false
  }
}

• Step 4: 展开行对接详情

找到模板中的 expand slot（当前显示 mock 数据 detailsMock1），替换为绑定 detailMap：

<template #expand="scope">
  <div class="p-20px bg-gray-50">
    <el-table
      :data="detailMap[scope.row.id] || []"
      border
      style="width: 100%"
      v-loading="!detailMap[scope.row.id]"
    >
      <el-table-column prop="chargeId" label="账单ID" width="120" />
      <el-table-column prop="lateFee" label="违约金" width="120" />
      <el-table-column prop="createTime" label="创建时间" width="180" />
    </el-table>
  </div>
</template>

• Step 5: 展开事件触发详情加载

在 handleExpandChange 中调用 fetchDetailList：

const handleExpandChange = (row: any, expandedRows: any[]) => {
  row.expanded = expandedRows.includes(row)
  if (row.expanded) {
    fetchDetailList(row.id)
  }
}

• Step 6: 删除 mock 数据

删除文件中的 detailsMock1 等 mock 数据声明。

• Step 7: 验证编译

Run: cd ../water-frontend && npx vue-tsc --noEmit 2>&1 | tail -20 Expected: No new type errors

---

Verification Checklist

完成所有 4 个 Task 后，执行端到端 smoke：

• npx vue-tsc --noEmit 编译通过
• 欠费催缴池页面：汇总统计数字不再是硬编码
• 欠费催缴池页面：点击"导出"触发 GET /pending-export 下载 xlsx
• 欠费催缴池页面：勾选客户 → 点击"选中催缴" → 弹窗填写 → 提交 → 调 POST /batch-create
• 欠费催缴池页面：点击"全部催缴"将当前列表全部行传入 RemindForm
• 催缴记录页面：列表从 GET /page 加载，查询条件生效
• 催缴记录页面：展开行从 GET /detail-list 加载账单明细