payment-platform/docs/superpowers/specs/2026-08-11-transfer-export-design.md

转账记录导出 Excel + 时间筛选 + 导出修复 — 设计文档

日期：2026-08-11 状态：已批准（用户逐项确认）

背景与目标

转账管理页面（module_payment/account/index.vue 的"转账记录" tab）增加导出 Excel 能力，导出的数据跟随表单筛选条件。同时修复两个既有问题：导出时间格式/时区、收款方类型翻译缺失。

现状

• 后端已有 GET /transfer/export（AccountController.java:238，权限 module_payment:account:transfer:list），但参数为 start_time/end_time（必填）+ enterprise_id，与页面筛选（out_biz_no/status/tenant_id/enterprise_id，无时间条件）不匹配
• 前端"下载报表"按钮被注释（index.vue:288-295），exportTransferReport API 已定义（account.ts:230，responseType: "blob"）但未接线——dead code
• transferExport 无其他调用方，参数改动无副作用
• 导出"创建时间"用 getCreatedTime().toString()（AccountService.java:332），输出 ISO 格式含 T/偏移；pay_transfer.created_time 为 timestamp without time zone，JDBC 读出的偏移标记取决于 JVM 时区（可能为 Z），导致时间看起来不是东8
• 导出"收款方类型" map（AccountService.java:316）只有 ALIPAY_ACCOUNT/BANK_CARD，而实际存储的 identity_type 是前端提交的 ALIPAY_USER_ID/ALIPAY_LOGON_ID/BANKCARD_ACCOUNT（转账表单下拉、批量转账 index.vue:1446），map 不命中输出英文

设计决策（用户已确认）

1. 实现方式：改造现有后端 transferExport 接口，前端恢复"下载报表"按钮
2. 导出列：现 9 列 + 备注 + 失败原因（共 11 列）
3. 页面"转账记录"筛选表单新增时间范围筛选，列表查询与导出同步适配
4. 筛选表单控件加宽，解决条件看不清问题
5. 导出时间格式化为东8 yyyy-MM-dd HH:mm:ss；页面"创建时间"列加 formatter 同样式
6. 收款方类型 map 补齐实际存储值
7. 时间解析沿用 parseDateTime 既有语义（结束日期解析为当天 00:00:00，与消费记录一致）
8. 空数据导出空 sheet，不特判提示

后端改动

AccountController.java

• transferList（:77）：新增 start_time/end_time 选填参数，透传 service
• transferExport（:238）：参数改为 6 个全可选——out_biz_no/status/tenant_id/enterprise_id/start_time/end_time；权限不变

AccountService.java

• transferList（:190）：时间条件 w.ge/le(TransferEntity::getCreatedTime, parseDateTime(...))，条件语义与既有四条件一致（eq 精确匹配）
• transferExport（:295）：
  • 查询条件与 transferList 逐条一致（6 条件，全部可选）
  • 导出列 11 列：序号、订单号、商户订单号、金额(元)、收款方姓名、收款方类型、状态、转账标题、创建时间、备注、失败原因
  • 失败原因取 errorMsg（非空输出，空则空串）
  • "创建时间"格式化为东8：createdTime.atZoneSameInstant(ZoneId.of("Asia/Shanghai")).format(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"))
  • "收款方类型" map 补齐：ALIPAY_USER_ID/ALIPAY_LOGON_ID/ALIPAY_ACCOUNT → 支付宝账户；BANKCARD_ACCOUNT/BANK_CARD → 银行卡

前端改动

account.ts

• exportTransferReport（:230）参数类型更新：out_biz_no?/status?/tenant_id?/enterprise_id?/start_time?/end_time?，去掉必填的 start_time/end_time

index.vue（转账记录区域）

• transferSearchForm 增加 dateRange/start_time/end_time（模式复用消费记录 consumeSearchForm :1806-1824）
• 筛选表单加 el-date-picker type="daterange"（value-format="YYYY-MM-DD"，消费记录同款 :415-425）
• 筛选控件加宽：订单号 input 220px、状态/租户/企业 select 180px、时间范围 280px
• handleTransferSearchReset 清空时间条件
• fetchTransferList 传 start_time/end_time
• 恢复"下载报表"按钮（原注释位 :288-295）：v-hasPerm="['module_payment:account:transfer:list']"、导出中 loading、失败 ElMessage.error、成功 blob → a.download 下载 转账记录.xlsx
• "创建时间"表格列加 formatter：显示 YYYY-MM-DD HH:mm:ss（东8墙钟，与导出一致）

验证计划

• 后端：mvn compile；curl 按筛选条件（含时间）调用 /transfer/export，核对导出列、筛选结果、时间格式（东8 yyyy-MM-dd HH:mm:ss）、类型翻译（支付宝账户/银行卡）
• 前端：ts:check 确认无新增错误（项目存在既有错误基线）；Playwright 验证筛选时间条件查询、导出按钮下载文件