83 行
4.6 KiB
Markdown
83 行
4.6 KiB
Markdown
# 房务 / 候选 GET 查询「日期参数」绑定修复（stayDate 等 500）— 管理后台
|
||
|
||
> 变更类型：🐛 Bug 修复（GET 查询日期参数无法绑定，报 500）
|
||
> 端类型：管理后台（房务管家 · 候选酒店/抢单池/我的接单/待办/询房历史/核房历史/操作日志）
|
||
> 日期：2026-06-20
|
||
> 服务：hl-order-service-v3
|
||
> PR：https://git.1814.love:8443/wx/HL/pulls/4109
|
||
|
||
---
|
||
|
||
## ⚠️ 关键说明（给前端）
|
||
|
||
前端联调「选择酒店」弹窗时，`GET /v3/admin/hotel-candidates?orderId=...&stayDate=2026-06-20` 报：
|
||
|
||
```
|
||
Failed to convert property value of type 'java.lang.String' to required type
|
||
'java.time.LocalDate' for property 'stayDate' ... Parse attempt failed for value [2026-06-20]
|
||
```
|
||
|
||
**原因**：这是后端 bug —— GET 查询参数的日期字段缺少格式声明，已修复并部署测试服。前端**无需改 URL 写法**，只要按下面的**格式约定**传值即可正常工作。
|
||
|
||
## 日期参数格式约定（重要）
|
||
|
||
房务/候选这批 GET 接口的日期筛选参数，分两类，**格式不同**：
|
||
|
||
| 类型 | 接受格式 | 示例 | 涉及参数 |
|
||
|---|---|---|---|
|
||
| **日期** LocalDate | `yyyy-MM-dd` | `2026-06-20` | stayDate、departDateFrom/To、lastCheckedBefore、核房历史 startDate/endDate |
|
||
| **日期时间** LocalDateTime | `yyyy-MM-dd'T'HH:mm:ss`（**必须带 `T` 和时分秒**） | `2026-06-20T00:00:00` | claimedAtFrom/To、待办 createTimeFrom/To、询房 createTimeFrom/To·repliedAtFrom/To、操作日志 startDate/endDate |
|
||
|
||
> ⚠️ **日期时间类参数不能只传 `2026-06-20`**，要补全成 `2026-06-20T00:00:00`（起始）/ `2026-06-20T23:59:59`（结束）。日期选择器若只取到日，请前端拼上 `T00:00:00` / `T23:59:59` 再传。
|
||
|
||
## 受影响接口（已全部修复，9443 实测 200）
|
||
|
||
- `GET /v3/admin/hotel-candidates`（候选酒店 · stayDate）
|
||
- `GET /v3/admin/order/grab-pool/hotel-requirements`（抢单池 · departDateFrom/To）
|
||
- `GET /v3/admin/order/grab-pool/my-claims/hotel`（我的接单 · departDateFrom/To、claimedAtFrom/To）
|
||
- `GET /v3/admin/house/hotels`（房务酒店列表 · lastCheckedBefore）
|
||
- `GET /v3/admin/order/todos`（待办 · createTimeFrom/To）
|
||
- `GET /v3/admin/order/inquiry`（询房历史 · createTimeFrom/To、repliedAtFrom/To）
|
||
- `GET /v3/admin/house/hotels/{hotelId}/check-log`（核房历史 · startDate/endDate）
|
||
- `GET /v3/admin/house/hotels/{hotelId}/operation-log` 与 `GET /admin/house/orders/{orderId}/operation-log`（操作日志 · startDate/endDate）
|
||
|
||
> 注：POST 请求体（`@RequestBody`，如发起询房 `inquiry/send`、新增核房 `check-log`）走 JSON 解析，日期照常传 `2026-06-20` 即可，本次不受影响、未改动。
|
||
|
||
## 测试（测试服 9443 实测）
|
||
|
||
```bash
|
||
# 前端原报错的请求，现返回 200（不再 500）
|
||
curl -k "https://api.test.1814.love:9443/v3/admin/hotel-candidates?orderId=2067532338723504130&stayDate=2026-06-20" \
|
||
-H "Authorization: Bearer <token>"
|
||
```
|
||
|
||
- 候选酒店 + stayDate=2026-06-20：**200**（修复前 500 转换异常）。
|
||
- 上述 8 类日期/日期时间筛选端点逐一实测：全部 **200**，无转换异常、无 500。
|
||
- `mvn -pl hl-order-service-v3 compile` BUILD SUCCESS；测试服 order-v3 双实例部署 success。
|
||
|
||
## 同类隐患连带修复（PR #4112）
|
||
|
||
对三域对接总览 50+ 端点逐个真 token 实测（49 端点全绿、零框架级报错）后，又静态排查 order-v3 全部 GET 查询日期 VO，发现房务模块外另有 2 处同病，一并补 `@DateTimeFormat`：
|
||
|
||
| 端点 | 参数 |
|
||
|---|---|
|
||
| `GET /v3/admin/complaint/page`（投诉列表） | dateFrom / dateTo |
|
||
| `GET /v3/admin/order/vehicle-requirement/{id}/candidates`（配车候选） | availableFrom / availableTo |
|
||
|
||
均已部署 + 9443 实测按日期筛选返 200，不再 500。
|
||
|
||
## 参数格式错误消息已转干净中文（PR #4115）
|
||
|
||
合法日期已能正常解析（上文）；针对**非法/格式不对的日期**（如日期范围控件给 LocalDateTime 字段发了纯日期 `2026-06-20`，或脏值 `2026-13-45`），后端**不再向前端吐 Spring 原始的 `Failed to convert ... ConversionFailedException` 长串**，改为干净中文：
|
||
|
||
```
|
||
参数【stayDate】格式不正确（日期请用 yyyy-MM-dd，日期时间请用 yyyy-MM-dd'T'HH:mm:ss）
|
||
```
|
||
|
||
`code` 仍为 400。前端可直接展示该 `message`。（仅 order-v3 生效；合法值不受影响、行为不变。）
|
||
|
||
## 备注
|
||
|
||
- 配套《房务+定制师提房需求+站内信聊天 前端对接总览》（同日发布）的日期参数，按本文格式约定传值。
|
||
- 网关无需改。
|