---
date: 2026-05-07
type: backend-fix
module: hl-order-service-v2/order+refund
priority: high
notify: ["@mmg"]
status: deployed-pending
restart_service: hl-order-service-v2
gitea_pr: 1804
gitea_issue: 1791
related_cases: [DD-004, DD-005, TK-004]
---

# 订单/退款列表日期范围筛选无效 — 三层补字段

## 现象（DD-004 / DD-005 / TK-004）

测试报告：
- 订单列表选起止日期 → 无法筛选
- 订单列表多条件组合 → "日期还是有问题"
- 退款列表多条件组合 → "无"

`/@bug` round-trip 极端测试 1900 vs 2099 vs 默认三组 total 都 29 一致 → 日期参数被静默丢弃。

## 修复

PR #1804 已合并 dev。三层补字段：

| 层 | 文件 | 改动 |
|----|------|------|
| VO | OrderPageReqVO + RefundApplicationPageReqVO | 加 `createTimeStart` / `createTimeEnd` (LocalDateTime + @DateTimeFormat) |
| Service | OrderListQueryService.listAdminOrders | 透传两个新参数到 mapper |
| Mapper | OrderInfoMapper.selectAdminPage / RefundApplicationMapper.selectPage | wrapper 加 `betweenIfPresent(OrderInfo::getCreateTime, start, end)` |

`betweenIfPresent` 智能退化：双边都给 = BETWEEN，只给 start = >= start，只给 end = <= end，都空跳过。

## 前端调用（@mmg）

### 订单列表

```js
// 接口：GET /admin/order/page
GET /admin/order/page?createTimeStart=2026-04-01T00:00:00&createTimeEnd=2026-04-30T23:59:59&page=1&pageSize=10
```

注意：
- 字段名：`createTimeStart` / `createTimeEnd`（驼峰，跟之前 status 字段一致）
- 格式：ISO 8601 DateTime（`2026-04-01T00:00:00`）
- 时区：服务端 `+08:00`，前端传字符串不带时区由后端 LocalDateTime 解析

### 退款列表

```js
// 接口：GET /admin/refund/application/page
GET /admin/refund/application/page?createTimeStart=...&createTimeEnd=...&page=1&pageSize=10
```

### 不传日期时

向后兼容，不传 `createTimeStart` / `createTimeEnd` 行为完全不变（既有调用零影响）。

## 重启服务

`hl-order-service-v2` 部署测试服后即可。

## 验收

- [ ] 订单列表传日期 → 数据按范围筛选
- [ ] 退款列表传日期 → 同样工作
- [ ] 不传日期 → 全量返回（向后兼容）
- [ ] 跨年 / 单边 / 边界 各 case 正常

## 关联工单
Gitea #1791 已 Closes 关闭。
