wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 工作流 软件包 项目 发布 百科 活动

补全 7070 房务 productType 标签接口文档（完整模板+网关实测）
changelog-filename-gate / validate (push) Successful in 2s
详情

浏览代码
这个提交包含在：
API Changelog Bot
2026-09-04 15:50:54 +08:00
父节点 8c38fc6b89
当前提交 4ff1480683
共修改 1 个文件，包含 525 行新增和 38 行删除
下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件
changelogs-v2/2026-09/04_7070_房务列表-详情补产品类型标签-productType-修改接口-管理后台.md
+525 -38
查看文件
@@ -5,61 +5,548 @@ title: "房务列表/详情补产品类型标签 productType"
consumer: "admin"
author: "wx(GIT)"
change_type: "修改接口"
backend_status: "tested"
gateway_status: "pending"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "pending"
frontend_owner: ""
frontend_ref: ""
target_release: ""
verified_at: ""
status_note: ""
status_note: "2026-09-04 测试服部署 dev-v3@19ca3d702；详情/待办/抢单池 productType 网关实测与订单一致"
updated_at: "2026-09-04"
base: "dev-v3"
generated: "2026-09-04T14:30:35+08:00"
---
# 房务列表/详情补产品类型标签 productType
# 房务: 各订单列表与详情补产品类型标签 productType
> 房务各订单维度列表与详情新增/接通 `productType` 字段，供前端渲染「核心订单 / 线路订单 / 定制订单 / 团期订单」标签。
> **服务**: hl-order-service-v3
> **PR**: [#7077](https://git.1814.love:8443/wx/HL/pulls/7077) / [#7084](https://git.1814.love:8443/wx/HL/pulls/7084)
> **Issue**: [#7070](https://git.1814.love:8443/wx/HL/issues/7070)
> **日期**: 2026-09-04
> **影响范围**: 管理后台房务——抢单池、我的接单、订单详情、待办列表、日历下钻、月度对账订单明细、需求历史
---
## ⚠️ 关键变化
🔧 房务各订单维度列表行/详情新增或接通 `productType` 字段，前端据此渲染「核心订单 / 线路订单 / 定制订单 / 团期订单」标签。取值口径统一、稳定性提升（此前部分场景在产品服务不可用时返回空，现已消除该空值）。`productType` 为 null 的订单前端不渲染标签。
---
## 一、背景（选填）
房务在抢单、配房、对账时需要直观区分订单产品类型。此前抢单池/我的接单/详情虽能取到产品类型，但在产品服务不可用时可能返回空；待办/日历/对账/需求历史则完全没有该字段。本次统一为订单主数据直读并补齐缺失场景。
---
## 二、变更接口清单
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|------|----------|------|
| 1 | 抢单池列表 | GET | `/v3/admin/order/grab-pool/hotel-requirements` | 修改接口 | `productType` 取值口径统一，稳定性提升 |
| 2 | 我的接单列表 | GET | `/v3/admin/order/grab-pool/my-claims/hotel` | 修改接口 | `productType` 取值口径统一 |
| 3 | 房务订单详情 | GET | `/admin/house/orders/{orderId}` | 修改接口 | `order.productType` 取值口径统一 |
| 4 | 房务待办列表 | GET | `/v3/admin/order/todos` | 修改接口 | 行项新增出参 `productType` |
| 5 | 日历某天下钻 | GET | `/admin/house/calendar/day` | 修改接口 | 单团项新增出参 `productType` |
| 6 | 月度对账订单明细 | GET | `/v3/admin/house/reconciliation/monthly/hotel-orders` | 修改接口 | 订单明细行新增出参 `productType` |
| 7 | 需求历史列表 | GET | `/admin/house/orders/{orderId}/requirement-history` | 修改接口 | 历史版本项新增出参 `productType` |
---
## 三、接口详情
### 1. 抢单池列表 `GET /v3/admin/order/grab-pool/hotel-requirements`
**VO**: `HouseGrabPageItemRespVO`
#### 使用场景
房务打开抢单池页，浏览待抢的用房需求卡片。本变更让每张卡片可稳定显示产品类型标签。
#### 入参
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| page | Query | Integer | 否 | 默认 1 | 页码 |
| pageSize | Query | Integer | 否 | 默认 20 | 每页条数 |
| keyword | Query | String | 否 | ≤32 字 | 订单号/团号/客人/产品名模糊 |
| productType | Query | String | 否 | CORE/ROUTE/CUSTOM/GROUP | 产品类型筛选（既有入参，语义不变） |
| productName | Query | String | 否 | - | 产品名精准 |
| consultantId | Query | Long | 否 | - | 定制师筛选 |
| guestName | Query | String | 否 | - | 客人模糊 |
| departDateFrom | Query | Date | 否 | yyyy-MM-dd | 出发日起 |
| departDateTo | Query | Date | 否 | yyyy-MM-dd | 出发日止 |
| sortBy | Query | String | 否 | - | 排序 |
#### 出参
| 字段 | 类型 | 说明 |
|------|------|------|
| records[].productType | String | 产品类型枚举值 CORE/ROUTE/CUSTOM/GROUP；取值稳定（不再受产品服务可用性影响）；历史数据为 null 时前端不渲染 |
| records[].productNo | String | 产品编号（不受本变更影响） |
#### 请求示例
```http
GET /v3/admin/order/grab-pool/hotel-requirements?page=1&pageSize=10 HTTP/1.1
Host: api.test.1814.love:9443
Authorization: Bearer <管理员token>
```
（GET 无请求体）
#### 响应示例
```json
{
"code": 200,
"message": "成功",
"success": true,
"data": {
"total": 10,
"records": [
{ "orderId": "30456", "orderNo": "HL20260901101825666", "productType": "CORE", "productNo": "C-2026-001" }
]
}
}
```
#### 空数据 / 降级响应
`productType` 为 null（历史数据）时该字段返回 null，前端不渲染标签；列表其它字段不受影响。
#### 错误响应
```json
{
"code": 401,
"message": "未登录或登录已过期",
"success": false,
"data": null
}
```
#### 业务边界
- `productType` 与订单一致，只读。
- `productType` 筛选入参语义不变（当前页匹配过滤）。
### 2. 我的接单列表 `GET /v3/admin/order/grab-pool/my-claims/hotel`
**VO**: `HouseMyOrderItemRespVO`
#### 使用场景
房务查看「我的接单」列表。本变更让每行可稳定显示产品类型标签。
#### 入参
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| page | Query | Integer | 否 | 默认 1 | 页码 |
| pageSize | Query | Integer | 否 | 默认 20 | 每页条数 |
| keyword | Query | String | 否 | - | 模糊关键词 |
| productType | Query | String | 否 | CORE/ROUTE/CUSTOM/GROUP | 产品类型筛选（既有入参，语义不变） |
| status | Query | String | 否 | - | 状态筛选 |
| productName | Query | String | 否 | - | 产品名筛选 |
| consultantId | Query | Long | 否 | - | 定制师筛选 |
| guestName | Query | String | 否 | - | 客人筛选 |
| departDateFrom | Query | Date | 否 | yyyy-MM-dd | 出发日起 |
| departDateTo | Query | Date | 否 | yyyy-MM-dd | 出发日止 |
#### 出参
| 字段 | 类型 | 说明 |
|------|------|------|
| list[].productType | String | 产品类型枚举值；取值稳定，与订单一致；null 时前端不渲染 |
#### 请求示例
```http
GET /v3/admin/order/grab-pool/my-claims/hotel?page=1&pageSize=10 HTTP/1.1
Host: api.test.1814.love:9443
Authorization: Bearer <管理员token>
```
（GET 无请求体）
#### 响应示例
```json
{
"code": 200,
"message": "成功",
"success": true,
"data": {
"total": 3,
"list": [
{ "orderId": "30456", "orderNo": "HL2026...", "productType": "GROUP" }
]
}
}
```
#### 空数据 / 降级响应
订单信息取不到时 `productType` 落 null，列表照常返回，不阻断。
#### 错误响应
```json
{
"code": 401,
"message": "未登录或登录已过期",
"success": false,
"data": null
}
```
#### 业务边界
- 取值与订单一致，只读不改写。
### 3. 房务订单详情 `GET /admin/house/orders/{orderId}`
**VO**: `HouseOrderDetailRespVO`
#### 使用场景
房务打开订单详情弹窗。本变更让详情头部订单块稳定显示产品类型标签。
#### 入参
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| orderId | Path | Long | 是 | - | 订单 ID |
| requirementId | Query | Long | 否 | - | 指定需求版本（查看历史作废版本） |
#### 出参
| 字段 | 类型 | 说明 |
|------|------|------|
| order.productType | String | 产品类型枚举值；取值稳定，与订单一致；null 时前端不渲染 |
#### 请求示例
```http
GET /admin/house/orders/30456 HTTP/1.1
Host: api.test.1814.love:9443
Authorization: Bearer <管理员token>
```
（GET 无请求体）
#### 响应示例
```json
{
"code": 200,
"message": "成功",
"success": true,
"data": {
"order": { "orderId": "30456", "orderNo": "HL2026...", "productType": "CUSTOM" }
}
}
```
#### 空数据 / 降级响应
订单不存在时订单块仅含 orderId，`productType` 为 null，不返回 500。
#### 错误响应
```json
{
"code": 401,
"message": "未登录或登录已过期",
"success": false,
"data": null
}
```
#### 业务边界
- 取值与订单一致，只读。
### 4. 房务待办列表 `GET /v3/admin/order/todos`
**VO**: `HouseTodoItemVO`
#### 使用场景
房务待办列表（订单聚合行）。本变更**新增** `productType` 出参，每行可显示产品类型标签。
#### 入参
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| page | Query | Integer | 否 | 默认 1 | 页码 |
| pageSize | Query | Integer | 否 | 默认 20 | 每页条数 |
| scope | Query | String | 否 | mine/others/all | 范围，默认 all |
| todoType | Query | String | 否 | 多选逗号分隔 | 待办类型筛选 |
| status | Query | String | 否 | OPEN/RESOLVED | 状态筛选 |
| urgency | Query | String | 否 | danger/warn/normal | 紧急度筛选 |
| keyword | Query | String | 否 | ≤32 字 | 关键词 |
| orderId | Query | Long | 否 | - | 订单筛选 |
| ownerUserId | Query | Long | 否 | - | 归属房务筛选 |
| hotelId | Query | Long | 否 | - | 酒店筛选 |
#### 出参
| 字段 | 类型 | 说明 |
|------|------|------|
| list[].productType | String | **新增**：产品类型枚举值；无关联订单（酒店维度待办）或取不到订单时为 null，前端不渲染 |
#### 请求示例
```http
GET /v3/admin/order/todos?page=1&pageSize=10 HTTP/1.1
Host: api.test.1814.love:9443
Authorization: Bearer <管理员token>
```
（GET 无请求体）
#### 响应示例
```json
{
"code": 200,
"message": "成功",
"success": true,
"data": {
"total": 10,
"list": [
{ "id": "70500", "orderNo": "HL2026...", "productType": "CORE" }
]
}
}
```
#### 空数据 / 降级响应
订单信息取不到时 `productType` 落 null，列表照常返回。
#### 错误响应
```json
{
"code": 401,
"message": "未登录或登录已过期",
"success": false,
"data": null
}
```
#### 业务边界
- 订单维度待办行与订单一致；酒店维度待办（无订单）productType 为 null。
### 5. 日历某天下钻 `GET /admin/house/calendar/day`
**VO**: `DayTourItemVO`
#### 使用场景
房务日历点击某天下钻查看当天各「团」明细。本变更**新增** `productType` 出参。
#### 入参
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| date | Query | Date | 是 | yyyy-MM-dd | 下钻日期 |
| scope | Query | String | 否 | mine/all | 范围，默认 mine |
| status | Query | String | 否 | 多选 | 状态筛选 |
#### 出参
| 字段 | 类型 | 说明 |
|------|------|------|
| [].productType | String | **新增**：产品类型枚举值；团期折叠时取代表子订单；null 时前端不渲染 |
#### 请求示例
```http
GET /admin/house/calendar/day?date=2026-05-22&scope=all HTTP/1.1
Host: api.test.1814.love:9443
Authorization: Bearer <管理员token>
```
（GET 无请求体）
#### 响应示例
```json
{
"code": 200,
"message": "成功",
"success": true,
"data": [
{ "teamKey": "B:900", "isGroup": true, "orderNo": "HL100", "productType": "GROUP" }
]
}
```
#### 空数据 / 降级响应
当天无团返空列表；展示信息缺失时 `productType` 为 null。
#### 错误响应
```json
{
"code": 400,
"message": "scope 非法",
"success": false,
"data": null
}
```
#### 业务边界
- 团期折叠场景取代表子订单（订单号最小）的产品类型，与同团其它子订单一致。
### 6. 月度对账订单明细 `GET /v3/admin/house/reconciliation/monthly/hotel-orders`
**VO**: `HotelReconciliationOrderVO`
#### 使用场景
房务月度对账，查看某酒店下各订单明细行。本变更**新增** `productType` 出参。
#### 入参
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| month | Query | String | 是 | yyyy-MM | 对账月份 |
| hotelId | Query | Long | 否 | - | 酒店筛选 |
| hotelName | Query | String | 否 | - | 酒店名筛选 |
#### 出参
| 字段 | 类型 | 说明 |
|------|------|------|
| [].productType | String | **新增**：产品类型枚举值；订单缺失时为 null，前端不渲染 |
#### 请求示例
```http
GET /v3/admin/house/reconciliation/monthly/hotel-orders?month=2026-08&hotelId=1001 HTTP/1.1
Host: api.test.1814.love:9443
Authorization: Bearer <管理员token>
```
（GET 无请求体）
#### 响应示例
```json
{
"code": 200,
"message": "成功",
"success": true,
"data": [
{ "orderId": "30456", "orderNo": "HL2026...", "productName": "额吉的故乡", "productType": "CUSTOM" }
]
}
```
#### 空数据 / 降级响应
无配房订单返空列表；订单信息缺失时 `productType` 为 null。
#### 错误响应
```json
{
"code": 400,
"message": "month 格式非法",
"success": false,
"data": null
}
```
#### 业务边界
- 仅订单维度明细行新增；酒店汇总行无订单粒度，不含此字段。
### 7. 需求历史列表 `GET /admin/house/orders/{orderId}/requirement-history`
**VO**: `RequirementHistoryItem`
#### 使用场景
房务查看订单的用房需求历史版本。本变更**新增** `productType` 出参。
#### 入参
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| orderId | Path | Long | 是 | - | 订单 ID |
| includeDiff | Query | Boolean | 否 | - | 是否含字段级 diff |
| onlyReturned | Query | Boolean | 否 | - | 仅看退回版本 |
#### 出参
| 字段 | 类型 | 说明 |
|------|------|------|
| list[].productType | String | **新增**：产品类型枚举值；订单缺失时为 null，前端不渲染 |
#### 请求示例
```http
GET /admin/house/orders/30456/requirement-history HTTP/1.1
Host: api.test.1814.love:9443
Authorization: Bearer <管理员token>
```
（GET 无请求体）
#### 响应示例
```json
{
"code": 200,
"message": "成功",
"success": true,
"data": {
"list": [
{ "requirementId": "70123", "version": 2, "productType": "CORE" }
]
}
}
```
#### 空数据 / 降级响应
无历史返空列表；订单缺失时 `productType` 为 null。
#### 错误响应
```json
{
"code": 401,
"message": "未登录或登录已过期",
"success": false,
"data": null
}
```
#### 业务边界
- 各历史版本项产品类型同源同值（同订单）。
---
## 四、契约约束与正确调用方式
- `productType` 为**只读出参**，无需也不应在请求体中提交；抢单池/我的接单原有的 `productType` **筛选入参**语义不变。
- 前端按枚举值渲染标签，`null` 时不渲染。
---
## 六、边界行为
- 未登录 → 401（网关拦截）。
- 非法参数 → 400。
- 订单/需求信息缺失 → `productType` 落 null，不 500 不阻断列表/详情。
- 历史数据（无产品类型）→ 字段为 null，前端不渲染标签。
---
## 六.6、修改前后对比（修改/删除类接口必写，新增跳过）
### 字段级对比
| 字段 | 改前 | 改后 |
|------|------|------|
| 抢单池/我的接单/详情 productType | 产品服务不可用时可能返回空 | 取值稳定，不受产品服务可用性影响 |
| 待办/日历/对账/需求历史 productType | 无此字段 | 新增返回 |
### 行为级对比
| 行为 | 改前 | 改后 |
|------|------|------|
| 产品类型取值稳定性 | 依赖产品服务实时可用 | 订单主数据直读，稳定 |
| 列表/详情标签覆盖 | 仅抢单池/我的接单/详情 | 待办/日历/对账/需求历史全覆盖 |
## 六.7、影响评估（修改/删除类必写）
- **是否破坏向后兼容**: 否（纯出参字段新增 + 已有字段取值口径不变）
- **前端是否必须同步上线**: 否（不渲染则忽略新字段；旧前端不受影响）
- **前端 workaround 清理点**: 无
## 七、不影响范围（显式声明）
- **仅影响**: 管理后台房务上述 7 个接口的出参。
- **零影响**: C 端接口、订单创建/调整、车务、结算、`productType` 筛选入参语义、酒店维度视图（无订单行）。
---
## 八、测试环境已验证
真实网关接口输出（api.test.1814.love），带 ✓ 标记:
```
GET /admin/house/orders/... (3 个订单) → 200 + order.productType=CORE 与订单一致 ✓
GET /v3/admin/order/todos → 200 + 10 行均含 productType(订单行=CORE) ✓
GET /v3/admin/order/grab-pool/hotel-requirements → 200 + 10 行 productType=CORE ✓
```
验证账号: 房务管理员（测试环境）。
---
## 十、相关文档
- 关联 Issue: [wx/HL#7070](https://git.1814.love:8443/wx/HL/issues/7070)
- 关联 PR: [wx/HL#7077](https://git.1814.love:8443/wx/HL/pulls/7077) / [wx/HL#7084](https://git.1814.love:8443/wx/HL/pulls/7084)
## 关联 / 联系人
### 链接
- **Issue**: [#7070](https://git.1814.love:8443/wx/HL/issues/7070)
- **PR**: [#7077](https://git.1814.love:8443/wx/HL/pulls/7077)
- **Merge commit**: [cb8df55ee](https://git.1814.love:8443/wx/HL/commit/cb8df55ee)
- **PR**: [#7077](https://git.1814.love:8443/wx/HL/pulls/7077) / [#7084](https://git.1814.love:8443/wx/HL/pulls/7084)
- **Merge commit**: [19ca3d702](https://git.1814.love:8443/wx/HL/commit/19ca3d702)
### 联系人
- **后端负责人**: @wx
## 变更接口
| 方法 | 路径 | 变更 |
|---|---|---|
| GET | `/v3/admin/order/grab-pool/hotel-requirements` | 抢单池列表项 `productType` 数据源由 Product Feign 改直读 `order_main.product_type`（字段/类型/取值口径不变，消除 Feign 降级 null） |
| GET | `/v3/admin/order/grab-pool/my-claims/hotel` | 我的接单列表项 `productType` 同上改直读（语义不变） |
| GET | `/admin/house/orders/{orderId}` | 订单详情订单块 `productType` 同上改直读（语义不变） |
| GET | `/v3/admin/order/todos` | 待办订单聚合行**新增** `productType` 字段 |
| GET | `/admin/house/calendar/day` | 日历某天下钻单团项**新增** `productType` 字段（团期折叠取代表子订单） |
| GET | `/v3/admin/house/reconciliation/monthly/hotel-orders` | 月度对账订单明细行**新增** `productType` 字段 |
| GET | `/admin/house/orders/{orderId}/requirement-history` | 需求历史版本项**新增** `productType` 字段 |
## 契约影响文件
- `HouseGrabPageItemRespVO` / `HouseMyOrderItemRespVO` / `HouseOrderDetailRespVO`（`productType` 已有字段，数据源切换，取值口径不变）
- `HouseTodoItemVO` / `DayTourItemVO` / `HotelReconciliationOrderVO` / `RequirementHistoryItem`（**新增** `productType` 可选响应字段，EXTEND 无破坏）
## 前端/调用方动作
- 上述列表行/详情按 `productType` 枚举渲染产品类型标签，映射：`CORE`=核心订单、`ROUTE`=线路订单、`CUSTOM`=定制订单、`GROUP`=团期订单。
- `productType` 为 `null`（历史脏数据）时前端不渲染标签（空态不展示，勿显示默认文案）。
- 标签颜色/样式由前端自定，本变更仅交付枚举值。
## 验证证据
- 定向测试：`HouseGrabServiceImplTest`(77) / `HouseDetailAggregatorTest`(86) / `HouseCalendarServiceTest`(21) / `HouseTodoServiceTest`(119) / `MonthlyReconciliationServiceTest`(12) 共 **315 通过，0 失败**。
- 契约审查：frontend_api surface；Swagger2→OAS3/oasdiff 未配置（not_configured），已做源码级响应字段对比 fallback——4 个 VO 新增可选字段 EXTEND，3 个已有字段仅数据源切换、语义不变，无破坏性变更；请求侧无变更。
- 兼容性结论：**向后兼容**（纯响应字段新增 + 已有字段取值口径不变）。
- 网关验证：待测试环境部署后补充。