From 4ff1480683ceb7120375617aa2b3345adbea75fc Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Fri, 4 Sep 2026 15:49:24 +0800 Subject: [PATCH] =?UTF-8?q?=E8=A1=A5=E5=85=A8=207070=20=E6=88=BF=E5=8A=A1?= =?UTF-8?q?=20productType=20=E6=A0=87=E7=AD=BE=E6=8E=A5=E5=8F=A3=E6=96=87?= =?UTF-8?q?=E6=A1=A3=EF=BC=88=E5=AE=8C=E6=95=B4=E6=A8=A1=E6=9D=BF+?= =?UTF-8?q?=E7=BD=91=E5=85=B3=E5=AE=9E=E6=B5=8B=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...补产品类型标签-productType-修改接口-管理后台.md | 563 ++++++++++++++++-- 1 file changed, 525 insertions(+), 38 deletions(-) diff --git a/changelogs-v2/2026-09/04_7070_房务列表-详情补产品类型标签-productType-修改接口-管理后台.md b/changelogs-v2/2026-09/04_7070_房务列表-详情补产品类型标签-productType-修改接口-管理后台.md index 74cdc22f..c96b6b6e 100644 --- a/changelogs-v2/2026-09/04_7070_房务列表-详情补产品类型标签-productType-修改接口-管理后台.md +++ b/changelogs-v2/2026-09/04_7070_房务列表-详情补产品类型标签-productType-修改接口-管理后台.md @@ -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 个已有字段仅数据源切换、语义不变，无破坏性变更；请求侧无变更。 -- 兼容性结论：**向后兼容**（纯响应字段新增 + 已有字段取值口径不变）。 -- 网关验证：待测试环境部署后补充。