From 09109dba9e409605956437ce2f7fff34562fdb4f Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Fri, 20 Mar 2026 11:27:32 +0800 Subject: [PATCH] changelog: 2026-03/20_1127 (3 changes, 1 breaking) --- .swagger/hl-order-service.json | 245 ++++++++++++++++++++++++++--- changelogs/2026-03/20_1127_sync.md | 27 ++++ 2 files changed, 252 insertions(+), 20 deletions(-) create mode 100644 changelogs/2026-03/20_1127_sync.md diff --git a/.swagger/hl-order-service.json b/.swagger/hl-order-service.json index 33032a3..70bd13d 100644 --- a/.swagger/hl-order-service.json +++ b/.swagger/hl-order-service.json @@ -2687,12 +2687,21 @@ "管理端订单接口" ], "summary": "配房可选酒店列表", - "description": "返回所有启用酒店列表，标注该订单产品快照中包含的酒店（inSnapshot=true），并将快照酒店排在最前面。\n用于管理员配房时选择酒店，快照中的酒店是产品行程已安排的住宿，应优先选择。\n\n返回字段说明：\n- hotelId：酒店ID\n- hotelName：酒店名称\n- inSnapshot：是否在产品快照中（true=行程已安排的酒店）", + "description": "返回所有启用酒店列表，标注该订单产品快照中指定行程天包含的酒店（inSnapshot=true），并将快照酒店排在最前面。\n用于管理员配房时选择酒店，快照中的酒店是产品行程已安排的住宿，应优先选择。\n\n**必须传 dayIndex 参数**（行程第几天，从1开始），因为每天的酒店可能不同。\n\n返回字段说明：\n- hotelId：酒店ID\n- hotelName：酒店名称\n- inSnapshot：是否在该天产品快照中（true=该天行程已安排的酒店）", "operationId": "getAvailableHotelsUsingGET", "produces": [ "*/*" ], "parameters": [ + { + "name": "dayIndex", + "in": "query", + "description": "行程第几天（从1开始）", + "required": true, + "type": "integer", + "format": "int32", + "allowEmptyValue": false + }, { "name": "orderId", "in": "path", @@ -3371,7 +3380,7 @@ "管理端订单接口" ], "summary": "分配酒店信息", - "description": "按家庭为订单分配具体的酒店房间（酒店名称、房型、入住/退房日期）。\n每个家庭对应一条分配记录，分配后信息将展示在订单详情和C端行程中", + "description": "按天按家庭为订单分配具体的酒店房间。\n每天每个家庭一条记录，包含酒店ID、房型ID、日期和备注。\n\n**房型升级自动处理**：如果分配的房型与产品默认房型不同，系统自动计算差价并创建升级记录。\n- 定制师操作：自动确认，差价直接计入总售价\n- 其他角色操作：创建待确认记录（临时计入尾款），通知定制师确认\n- 可通过 upgradePrice 字段手动覆盖系统计算的差价", "operationId": "assignHotelUsingPUT", "consumes": [ "application/json" @@ -3445,6 +3454,86 @@ "x-order": "2147483647" } }, + "/admin/order/{orderId}/hotel-assignment/preview": { + "post": { + "tags": [ + "管理端订单接口" + ], + "summary": "配房升级差价预览", + "description": "预览配房时的房型升级差价（不创建记录）。\n逐天比较分配房型与产品默认房型（CORE产品默认标间），返回每天差价明细和汇总。\n前端可据此展示差价信息，用户确认后再调用分配接口。", + "operationId": "previewHotelAssignmentUsingPOST", + "consumes": [ + "application/json" + ], + "produces": [ + "*/*" + ], + "parameters": [ + { + "name": "orderId", + "in": "path", + "description": "订单ID", + "required": false, + "type": "integer", + "format": "int64" + }, + { + "in": "body", + "name": "request", + "description": "request", + "required": true, + "schema": { + "$ref": "#/definitions/酒店分配请求", + "originalRef": "酒店分配请求" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/统一响应结果«配房升级差价预览»", + "originalRef": "统一响应结果«配房升级差价预览»" + } + }, + "201": { + "description": "Created" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "responsesObject": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/统一响应结果«配房升级差价预览»", + "originalRef": "统一响应结果«配房升级差价预览»" + } + }, + "201": { + "description": "Created" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "deprecated": false, + "x-order": "2147483647" + } + }, "/admin/order/{orderId}/itinerary/add": { "post": { "tags": [ @@ -8954,39 +9043,107 @@ }, "title": "分页结果«管理员订单列表VO»" }, - "单项酒店分配": { + "单天升级差价明细": { "type": "object", - "required": [ - "checkInDate", - "checkOutDate", - "familyIndex", - "hotelName", - "roomType" - ], "properties": { - "checkInDate": { - "type": "string", - "description": "入住日期(yyyy-MM-dd)" + "assignedPrice": { + "type": "number", + "description": "实际房型当天单价" }, - "checkOutDate": { + "assignedRoomTypeId": { + "type": "integer", + "format": "int64", + "description": "实际分配房型ID" + }, + "assignedRoomTypeName": { "type": "string", - "description": "退房日期(yyyy-MM-dd)" + "description": "实际分配房型名称" + }, + "date": { + "type": "string", + "description": "日期" + }, + "dayDiff": { + "type": "number", + "description": "当天差价" + }, + "defaultPrice": { + "type": "number", + "description": "默认房型当天单价" + }, + "defaultRoomTypeId": { + "type": "integer", + "format": "int64", + "description": "产品默认房型ID" + }, + "defaultRoomTypeName": { + "type": "string", + "description": "产品默认房型名称" + }, + "direction": { + "type": "string", + "description": "差价方向" }, "familyIndex": { "type": "integer", "format": "int32", "description": "家庭序号" }, + "remark": { + "type": "string", + "description": "备注" + } + }, + "title": "单天升级差价明细" + }, + "单天单家庭酒店分配": { + "type": "object", + "required": [ + "date", + "familyIndex", + "hotelId", + "hotelName", + "roomType", + "roomTypeId" + ], + "properties": { + "date": { + "type": "string", + "description": "日期(yyyy-MM-dd)，单天" + }, + "familyIndex": { + "type": "integer", + "format": "int32", + "description": "家庭序号" + }, + "hotelId": { + "type": "integer", + "format": "int64", + "description": "酒店ID" + }, "hotelName": { "type": "string", "description": "酒店名称" }, + "remark": { + "type": "string", + "description": "当天备注" + }, "roomType": { "type": "string", - "description": "房型" + "description": "房型名称" + }, + "roomTypeId": { + "type": "integer", + "format": "int64", + "description": "房型ID" + }, + "upgradePrice": { + "type": "number", + "description": "手动覆盖升级差价（null=使用系统计算值，仅当房型与产品默认不同时有效）" } }, - "title": "单项酒店分配" + "title": "单天单家庭酒店分配" }, "工单操作日志VO": { "type": "object", @@ -10401,6 +10558,28 @@ }, "title": "统一响应结果«订单详情VO»" }, + "统一响应结果«配房升级差价预览»": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "format": "int32", + "example": 200, + "description": "状态码" + }, + "data": { + "description": "响应数据", + "$ref": "#/definitions/配房升级差价预览", + "originalRef": "配房升级差价预览" + }, + "message": { + "type": "string", + "example": "成功", + "description": "响应消息" + } + }, + "title": "统一响应结果«配房升级差价预览»" + }, "订单待办VO": { "type": "object", "properties": { @@ -10937,6 +11116,32 @@ }, "title": "车辆分配请求" }, + "配房升级差价预览": { + "type": "object", + "properties": { + "description": { + "type": "string", + "description": "描述" + }, + "details": { + "type": "array", + "description": "各天差价明细", + "items": { + "$ref": "#/definitions/单天升级差价明细", + "originalRef": "单天升级差价明细" + } + }, + "direction": { + "type": "string", + "description": "差价方向：UPGRADE=升级加价, DOWNGRADE=降级减价, SAME=价格不变, MIXED=部分升级部分降级" + }, + "totalDiff": { + "type": "number", + "description": "差价合计（正数=需补款，负数=可退款）" + } + }, + "title": "配房升级差价预览" + }, "酒店分配请求": { "type": "object", "required": [ @@ -10945,10 +11150,10 @@ "properties": { "assignments": { "type": "array", - "description": "酒店分配列表", + "description": "酒店分配列表（按天粒度，每天每个家庭一条记录）", "items": { - "$ref": "#/definitions/单项酒店分配", - "originalRef": "单项酒店分配" + "$ref": "#/definitions/单天单家庭酒店分配", + "originalRef": "单天单家庭酒店分配" } } }, diff --git a/changelogs/2026-03/20_1127_sync.md b/changelogs/2026-03/20_1127_sync.md new file mode 100644 index 0000000..7bb9481 --- /dev/null +++ b/changelogs/2026-03/20_1127_sync.md @@ -0,0 +1,27 @@ +# API 变更通知 + +**更新时间**: 2026-03-20 11:28 + +## ⚠️ Breaking Changes (1) + +> **前端必须处理的变更，不处理会导致功能异常** + +### 订单服务 + +**字段类型变化** + +| 数据对象 | 字段 | 原类型 | 新类型 | +| --- | --- | --- | --- | +| `酒店分配请求` | `assignments` | `单项酒店分配[]` | `单天单家庭酒店分配[]` | + +## ℹ️ 新增 (2) + +### 订单服务 + +**新增接口** + +- 🆕 `POST /admin/order/{orderId}/hotel-assignment/preview` + +**新增参数** + +- `GET /admin/order/{orderId}/available-hotels` 新增参数 `dayIndex`