changelog: 2026-03/20_1127 (3 changes, 1 breaking)

.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": "单天单家庭酒店分配"
           }
         }
       },

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`