订单财务手动推送 - 日期筛选 前端对接指引

后端服务：xp-robotaxi-order-boot
Feature：push-date-filter
文档版本：2026-06-18

一、需求背景

订单管理页「手动推送」按钮原先点击后会立即对所有满足条件的订单（已支付/已完成/已退款，且财务事件未推送或推送失败）发起财务推送。

本次新增：点击「手动推送」按钮后弹出一个对话框，允许按**订单创建时间区间**进行筛选，确认后仅推送该时间段内的订单。其中**结束日期默认当天**。

二、接口变更

POST /api/v1/order/manualPush

变更点：由原先的「无参数」改为**必须**携带 JSON Body（application/json），用于按订单创建时间过滤。前端调用时必须传 Body（至少传空对象 {}），否则后端返回 400。

请求 Body（必填）：

• Body 本身必填（不可省略），但其中的 startTime/endTime 字段均可选。
• 时间按订单 createTime（创建时间）过滤。
• 字段都不传（传空 Body {}）时，行为为「下限不限 + 上限默认当天结束」，即推送当天及之前的所有待推送订单。

请求示例：

{
  "startTime": "2026-06-18 00:00:00",
  "endTime": "2026-06-18 23:59:59"
}

响应（结构不变）：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "batchNo": "FRDXFMANUAL...",
    "totalCount": 12,
    "successCount": 10,
    "failedCount": 2,
    "detailIds": [1001, 1002]
  }
}

并发控制：后端用 Redis 锁保证同一时间只有一个手动推送任务。若已有任务执行中，返回 R.fail("已有手动推送任务正在执行，请稍后再试")，前端按 code !== 200 提示即可。

三、推荐 UI 交互

入口

订单管理页 → 顶部操作区「手动推送」按钮。

点击后弹框

弹出对话框，包含一个日期范围选择器：

• 字段：订单日期（开始日期 ~ 结束日期）
• 结束日期默认当天（开始日期可不填，或按业务习惯默认当天 / 不限）
• 「确定」按钮触发推送；「取消」关闭弹框

调用示例（伪代码）

// services/order.ts
export const manualPush = (params?: { startTime?: string; endTime?: string }) =>
  request.post('/api/v1/order/manualPush', params ?? {})

// 组件
const [range, setRange] = useState<[Dayjs | null, Dayjs | null]>([null, dayjs()]) // 结束默认当天

const handleConfirm = async () => {
  const [start, end] = range
  const res = await manualPush({
    startTime: start ? start.format('YYYY-MM-DD 00:00:00') : undefined,
    endTime: (end ?? dayjs()).format('YYYY-MM-DD 23:59:59'),
  })
  if (res.code === 200) {
    message.success(`推送完成：成功 ${res.data.successCount} / 失败 ${res.data.failedCount}`)
    closeDialog()
  } else {
    message.error(res.msg)
  }
}

四、注意事项

1. 结束日期默认当天，前端建议固定将结束时间格式化为 23:59:59，开始时间格式化为 00:00:00，避免漏掉边界订单。
2. 即使前端不传 endTime，后端也会兜底为当天 23:59:59，二者行为一致。
3. 推送是同步执行，订单量大时接口耗时较长，前端确定按钮需加 loading 防重复点击（后端 Redis 锁也会拦截并发）。