fix(v2): 房务 GET 查询日期参数绑定修复 changelog + 总览补日期格式约定

2026-06-20 11:33:25 +08:00
@@ -0,0 +1,61 @@
+# 房务 / 候选 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。
+
+## 备注
+
+- 配套《房务+定制师提房需求+站内信聊天 前端对接总览》（同日发布）的日期参数，按本文格式约定传值。
+- 网关无需改。