diff --git a/.swagger/hl-order-service.json b/.swagger/hl-order-service.json index 70bd13d..9c31159 100644 --- a/.swagger/hl-order-service.json +++ b/.swagger/hl-order-service.json @@ -5438,6 +5438,241 @@ "x-order": "2147483647" } }, + "/admin/order/{orderId}/surcharge": { + "post": { + "tags": [ + "管理端订单接口" + ], + "summary": "添加费用增加项", + "description": "为订单添加费用增加项(如升级房型补差价、加座费等)。\n添加后系统自动重算订单尾款金额。\n\n**权限**:仅该订单的定制师或超级管理员(SUPER_ADMIN)可操作", + "operationId": "addSurchargeUsingPOST", + "consumes": [ + "application/json" + ], + "produces": [ + "*/*" + ], + "parameters": [ + { + "name": "orderId", + "in": "path", + "description": "订单ID", + "required": false, + "type": "integer", + "format": "int64" + }, + { + "in": "body", + "name": "surchargeRequest", + "description": "费用增加项请求", + "required": false, + "schema": { + "$ref": "#/definitions/费用增加项请求", + "originalRef": "费用增加项请求" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/统一响应结果«OrderSurcharge»", + "originalRef": "统一响应结果«OrderSurcharge»" + } + }, + "201": { + "description": "Created" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "responsesObject": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/统一响应结果«OrderSurcharge»", + "originalRef": "统一响应结果«OrderSurcharge»" + } + }, + "201": { + "description": "Created" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "deprecated": false, + "x-order": "2147483647" + } + }, + "/admin/order/{orderId}/surcharge/{surchargeId}": { + "put": { + "tags": [ + "管理端订单接口" + ], + "summary": "修改费用增加项", + "description": "修改已添加的费用增加项名称或金额,修改后自动重算订单尾款金额。\n\n**权限**:仅该订单的定制师或超级管理员(SUPER_ADMIN)可操作", + "operationId": "updateSurchargeUsingPUT", + "consumes": [ + "application/json" + ], + "produces": [ + "*/*" + ], + "parameters": [ + { + "name": "orderId", + "in": "path", + "description": "订单ID", + "required": false, + "type": "integer", + "format": "int64" + }, + { + "name": "surchargeId", + "in": "path", + "description": "费用增加项ID", + "required": false, + "type": "integer", + "format": "int64" + }, + { + "in": "body", + "name": "surchargeRequest", + "description": "费用增加项请求", + "required": false, + "schema": { + "$ref": "#/definitions/费用增加项请求", + "originalRef": "费用增加项请求" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/统一响应结果«Void»", + "originalRef": "统一响应结果«Void»" + } + }, + "201": { + "description": "Created" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "responsesObject": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/统一响应结果«Void»", + "originalRef": "统一响应结果«Void»" + } + }, + "201": { + "description": "Created" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "deprecated": false, + "x-order": "2147483647" + }, + "delete": { + "tags": [ + "管理端订单接口" + ], + "summary": "删除费用增加项", + "description": "删除已添加的费用增加项,删除后自动重算订单尾款金额。\n\n**权限**:仅该订单的定制师或超级管理员(SUPER_ADMIN)可操作", + "operationId": "removeSurchargeUsingDELETE", + "produces": [ + "*/*" + ], + "parameters": [ + { + "name": "orderId", + "in": "path", + "description": "订单ID", + "required": false, + "type": "integer", + "format": "int64" + }, + { + "name": "surchargeId", + "in": "path", + "description": "费用增加项ID", + "required": false, + "type": "integer", + "format": "int64" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/统一响应结果«Void»", + "originalRef": "统一响应结果«Void»" + } + }, + "204": { + "description": "No Content" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + } + }, + "responsesObject": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/统一响应结果«Void»", + "originalRef": "统一响应结果«Void»" + } + }, + "204": { + "description": "No Content" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + } + }, + "deprecated": false, + "x-order": "2147483647" + } + }, "/admin/order/{orderId}/todos": { "get": { "tags": [ @@ -5638,6 +5873,67 @@ "x-order": "2147483647" } }, + "/admin/order/{orderId}/travelers": { + "get": { + "tags": [ + "管理端订单接口" + ], + "summary": "获取订单出行人列表", + "description": "返回指定订单的所有出行人信息,用于保险投保时自动填充被保人。\n\n**权限**:需管理员登录\n\n**关联字典**:\n- 返回字段 travelerType → 字典:traveler_type(出行人类型)\n- 返回字段 idCardType → 字典:id_card_type(证件类型)\n- 返回字段 gender → 字典:gender(性别)", + "operationId": "getOrderTravelersUsingGET", + "produces": [ + "*/*" + ], + "parameters": [ + { + "name": "orderId", + "in": "path", + "description": "订单ID", + "required": false, + "type": "integer", + "format": "int64" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/统一响应结果«List«OrderTraveler»»", + "originalRef": "统一响应结果«List«OrderTraveler»»" + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "responsesObject": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/统一响应结果«List«OrderTraveler»»", + "originalRef": "统一响应结果«List«OrderTraveler»»" + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "deprecated": false, + "x-order": "2147483647" + } + }, "/admin/order/{orderId}/vehicle-assignment": { "put": { "tags": [ @@ -8131,6 +8427,13 @@ "type": "object" } }, + "Map«string,object»_4": { + "type": "object", + "title": "Map«string,object»_4", + "additionalProperties": { + "type": "object" + } + }, "OrderDiscount": { "type": "object", "properties": { @@ -8308,6 +8611,45 @@ }, "title": "OrderItineraryEdit" }, + "OrderSurcharge": { + "type": "object", + "properties": { + "createTime": { + "type": "string", + "format": "date-time", + "description": "创建时间" + }, + "deletedAt": { + "type": "string", + "format": "date-time", + "description": "删除时间(软删除)" + }, + "orderId": { + "type": "integer", + "format": "int64", + "description": "订单ID" + }, + "surchargeAmount": { + "type": "number", + "description": "费用增加金额" + }, + "surchargeId": { + "type": "integer", + "format": "int64", + "description": "费用增加项ID" + }, + "surchargeName": { + "type": "string", + "description": "费用增加项名称" + }, + "updateTime": { + "type": "string", + "format": "date-time", + "description": "更新时间" + } + }, + "title": "OrderSurcharge" + }, "OrderTimeline": { "type": "object", "properties": { @@ -8315,6 +8657,10 @@ "type": "string", "description": "操作动作" }, + "actionLabel": { + "type": "string", + "description": "操作动作中文标签" + }, "content": { "type": "string", "description": "操作内容" @@ -8342,6 +8688,10 @@ "type": "string", "description": "操作人类型:USER=用户 ADMIN=管理员 SYSTEM=系统" }, + "operatorTypeLabel": { + "type": "string", + "description": "操作人类型中文标签" + }, "orderId": { "type": "integer", "format": "int64", @@ -8372,6 +8722,10 @@ "type": "string", "description": "指派角色Key" }, + "assigneeRoleLabel": { + "type": "string", + "description": "指派角色中文标签" + }, "completedAt": { "type": "string", "format": "date-time", @@ -8433,6 +8787,10 @@ "type": "string", "description": "待办类型" }, + "todoTypeLabel": { + "type": "string", + "description": "待办类型中文标签" + }, "updateTime": { "type": "string", "format": "date-time", @@ -8538,8 +8896,7 @@ "description": "紧急联系人电话(加密存储)" }, "gender": { - "type": "integer", - "format": "int32", + "type": "string", "description": "性别(字典:gender)" }, "idCardNo": { @@ -8550,6 +8907,18 @@ "type": "string", "description": "证件类型(字典:id_card_type)" }, + "idCardTypeLabel": { + "type": "string", + "description": "证件类型中文标签" + }, + "insurancePolicies": { + "type": "array", + "description": "该出行人的保险保单列表(按人合并,含保障期间和保单号)", + "items": { + "$ref": "#/definitions/Map«string,object»", + "originalRef": "Map«string,object»" + } + }, "name": { "type": "string", "description": "出行人姓名" @@ -8576,6 +8945,10 @@ "type": "string", "description": "出行人类型(字典:traveler_type)" }, + "travelerTypeLabel": { + "type": "string", + "description": "出行人类型中文标签" + }, "updateTime": { "type": "string", "format": "date-time", @@ -8882,8 +9255,7 @@ "description": "紧急联系电话" }, "gender": { - "type": "integer", - "format": "int32", + "type": "string", "example": 1, "description": "性别(字典:gender)" }, @@ -9043,6 +9415,51 @@ }, "title": "分页结果«管理员订单列表VO»" }, + "单天住宿分配": { + "type": "object", + "properties": { + "date": { + "type": "string", + "description": "日期(yyyy-MM-dd)" + }, + "hotelCoverUrl": { + "type": "string", + "description": "酒店封面图URL(从产品快照提取,可能为空)" + }, + "hotelId": { + "type": "integer", + "format": "int64", + "description": "酒店ID" + }, + "hotelName": { + "type": "string", + "description": "酒店名称" + }, + "remark": { + "type": "string", + "description": "备注" + }, + "roomCount": { + "type": "integer", + "format": "int32", + "description": "房间数量" + }, + "roomType": { + "type": "string", + "description": "房型名称" + }, + "roomTypeCoverUrl": { + "type": "string", + "description": "房型封面图URL(从产品快照提取,可能为空)" + }, + "roomTypeId": { + "type": "integer", + "format": "int64", + "description": "房型ID" + } + }, + "title": "单天住宿分配" + }, "单天升级差价明细": { "type": "object", "properties": { @@ -9637,6 +10054,12 @@ "example": 13800138000, "description": "联系人电话" }, + "customizerId": { + "type": "integer", + "format": "int64", + "example": 123456, + "description": "定制师ID(切换定制师)" + }, "departureDate": { "type": "string", "format": "date", @@ -9865,6 +10288,10 @@ "type": "number", "description": "尾款金额(DEPOSIT模式:总售价-定金-优惠)" }, + "checklistConfirmed": { + "type": "boolean", + "description": "是否已锁单(清单确认后锁定)" + }, "childCount": { "type": "integer", "format": "int32", @@ -9914,6 +10341,10 @@ "type": "string", "description": "商户号" }, + "mchName": { + "type": "string", + "description": "商户名称" + }, "orderId": { "type": "integer", "format": "int64", @@ -9964,6 +10395,10 @@ "type": "string", "description": "订单状态标签(字典:order_status 翻译)" }, + "surchargeAmount": { + "type": "number", + "description": "费用增加总额" + }, "totalPrice": { "type": "number", "description": "总售价" @@ -10185,6 +10620,31 @@ }, "title": "统一响应结果«List«OrderTransportSegment»»" }, + "统一响应结果«List«OrderTraveler»»": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "format": "int32", + "example": 200, + "description": "状态码" + }, + "data": { + "type": "array", + "description": "响应数据", + "items": { + "$ref": "#/definitions/OrderTraveler", + "originalRef": "OrderTraveler" + } + }, + "message": { + "type": "string", + "example": "成功", + "description": "响应消息" + } + }, + "title": "统一响应结果«List«OrderTraveler»»" + }, "统一响应结果«List«管理员基本信息»»": { "type": "object", "properties": { @@ -10300,6 +10760,28 @@ }, "title": "统一响应结果«OrderItineraryEdit»" }, + "统一响应结果«OrderSurcharge»": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "format": "int32", + "example": 200, + "description": "状态码" + }, + "data": { + "description": "响应数据", + "$ref": "#/definitions/OrderSurcharge", + "originalRef": "OrderSurcharge" + }, + "message": { + "type": "string", + "example": "成功", + "description": "响应消息" + } + }, + "title": "统一响应结果«OrderSurcharge»" + }, "统一响应结果«Void»": { "type": "object", "properties": { @@ -10806,9 +11288,17 @@ "format": "date-time", "description": "支付截止时间" }, + "hotelAssignmentDetails": { + "type": "array", + "description": "酒店分配详情(按家庭分组,含封面图)", + "items": { + "$ref": "#/definitions/酒店分配详情(按家庭分组)", + "originalRef": "酒店分配详情(按家庭分组)" + } + }, "hotelAssignments": { "type": "string", - "description": "酒店分配信息JSON" + "description": "酒店分配信息JSON(原始数据)" }, "insurances": { "type": "array", @@ -10822,6 +11312,10 @@ "type": "string", "description": "商户号" }, + "mchName": { + "type": "string", + "description": "商户名称" + }, "orderId": { "type": "integer", "format": "int64", @@ -10848,6 +11342,14 @@ "type": "string", "description": "支付模式(字典:payment_mode)" }, + "paymentModeLabel": { + "type": "string", + "description": "支付模式中文标签(DEPOSIT=定金+尾款, FULL=全款)" + }, + "pendingUpgradeAmount": { + "type": "number", + "description": "待确认差价总额(配房/配车升级未确认的差价)" + }, "processStatus": { "type": "string", "description": "内部流程状态(字典:order_process_status)" @@ -10877,6 +11379,10 @@ "type": "string", "description": "产品类型(字典:product_type)" }, + "productTypeLabel": { + "type": "string", + "description": "产品类型中文标签(CORE=核心产品, CUSTOM=私人定制, GROUP=小蒙马, ROUTE=路书产品)" + }, "readyAt": { "type": "string", "format": "date-time", @@ -10886,6 +11392,11 @@ "type": "number", "description": "退款金额(实退金额)" }, + "refundPolicy": { + "description": "退款政策(含政策名称和退款规则列表)", + "$ref": "#/definitions/退款政策VO", + "originalRef": "退款政策VO" + }, "remark": { "type": "string", "description": "备注" @@ -10915,6 +11426,18 @@ "type": "string", "description": "订单状态标签(字典:order_status 翻译)" }, + "surchargeAmount": { + "type": "number", + "description": "费用增加总额" + }, + "surcharges": { + "type": "array", + "description": "费用增加项列表", + "items": { + "$ref": "#/definitions/OrderSurcharge", + "originalRef": "OrderSurcharge" + } + }, "timeline": { "type": "array", "description": "时间线列表", @@ -11001,6 +11524,26 @@ }, "title": "记录尾款请求" }, + "费用增加项请求": { + "type": "object", + "required": [ + "surchargeAmount", + "surchargeName" + ], + "properties": { + "surchargeAmount": { + "type": "number", + "example": 200.0, + "description": "费用增加金额" + }, + "surchargeName": { + "type": "string", + "example": "升级房型补差价", + "description": "费用增加项名称" + } + }, + "title": "费用增加项请求" + }, "跳过行程节点请求": { "type": "object", "required": [ @@ -11089,7 +11632,6 @@ "车辆分配请求": { "type": "object", "required": [ - "vehicleBrand", "vehicleModel" ], "properties": { @@ -11107,7 +11649,7 @@ }, "vehicleBrand": { "type": "string", - "description": "品牌" + "description": "品牌(选填,不传则从车型名称中提取)" }, "vehicleModel": { "type": "string", @@ -11116,6 +11658,73 @@ }, "title": "车辆分配请求" }, + "退款政策VO": { + "type": "object", + "properties": { + "createTime": { + "type": "string", + "format": "date-time", + "description": "创建时间" + }, + "createdBy": { + "type": "integer", + "format": "int64", + "description": "创建人ID" + }, + "enabled": { + "type": "boolean", + "description": "是否启用" + }, + "policyId": { + "type": "integer", + "format": "int64", + "description": "政策ID" + }, + "policyName": { + "type": "string", + "description": "政策名称" + }, + "remark": { + "type": "string", + "description": "备注" + }, + "rules": { + "type": "array", + "description": "退款规则列表", + "items": { + "$ref": "#/definitions/退款规则VO", + "originalRef": "退款规则VO" + } + }, + "updateTime": { + "type": "string", + "format": "date-time", + "description": "更新时间" + } + }, + "title": "退款政策VO" + }, + "退款规则VO": { + "type": "object", + "properties": { + "minDays": { + "type": "integer", + "format": "int32", + "description": "距出发最少天数" + }, + "refundRatio": { + "type": "integer", + "format": "int32", + "description": "退款比例(百分比)" + }, + "ruleId": { + "type": "integer", + "format": "int64", + "description": "规则ID" + } + }, + "title": "退款规则VO" + }, "配房升级差价预览": { "type": "object", "properties": { @@ -11142,6 +11751,29 @@ }, "title": "配房升级差价预览" }, + "酒店分配详情(按家庭分组)": { + "type": "object", + "properties": { + "days": { + "type": "array", + "description": "每天的住宿分配列表", + "items": { + "$ref": "#/definitions/单天住宿分配", + "originalRef": "单天住宿分配" + } + }, + "familyIndex": { + "type": "integer", + "format": "int32", + "description": "家庭序号(从1开始)" + }, + "familyLabel": { + "type": "string", + "description": "家庭标签(如:家庭1、家庭2)" + } + }, + "title": "酒店分配详情(按家庭分组)" + }, "酒店分配请求": { "type": "object", "required": [ @@ -11447,60 +12079,6 @@ }, "title": "退款原因VO" }, - "退款政策VO": { - "type": "object", - "properties": { - "createTime": { - "type": "string", - "format": "date-time", - "description": "创建时间" - }, - "createdBy": { - "type": "integer", - "format": "int64", - "description": "创建人ID" - }, - "enabled": { - "type": "boolean", - "description": "是否启用" - }, - "isDefault": { - "type": "boolean", - "description": "是否为默认政策" - }, - "policyId": { - "type": "integer", - "format": "int64", - "description": "政策ID" - }, - "policyName": { - "type": "string", - "description": "政策名称" - }, - "refundType": { - "type": "string", - "description": "退款类型(字典:refund_type)DEPOSIT(定金)/BALANCE(尾款)/FULL(全款)" - }, - "remark": { - "type": "string", - "description": "备注" - }, - "rules": { - "type": "array", - "description": "退款规则列表", - "items": { - "$ref": "#/definitions/退款规则VO", - "originalRef": "退款规则VO" - } - }, - "updateTime": { - "type": "string", - "format": "date-time", - "description": "更新时间" - } - }, - "title": "退款政策VO" - }, "退款政策请求": { "type": "object", "required": [ @@ -11508,21 +12086,11 @@ "rules" ], "properties": { - "isDefault": { - "type": "boolean", - "example": false, - "description": "是否为默认政策(产品未绑定退款政策时使用默认政策)" - }, "policyName": { "type": "string", "example": "国内游退款政策", "description": "政策名称" }, - "refundType": { - "type": "string", - "example": "FULL", - "description": "退款类型(字典:refund_type)DEPOSIT(定金)/BALANCE(尾款)/FULL(全款)" - }, "remark": { "type": "string", "example": "适用于所有国内游产品", @@ -11700,27 +12268,6 @@ }, "title": "退款申请VO" }, - "退款规则VO": { - "type": "object", - "properties": { - "minDays": { - "type": "integer", - "format": "int32", - "description": "距出发最少天数" - }, - "refundRatio": { - "type": "integer", - "format": "int32", - "description": "退款比例(百分比)" - }, - "ruleId": { - "type": "integer", - "format": "int64", - "description": "规则ID" - } - }, - "title": "退款规则VO" - }, "退款规则项": { "type": "object", "required": [ diff --git a/changelogs/2026-03/24_1745_sync.md b/changelogs/2026-03/24_1745_sync.md new file mode 100644 index 0000000..ddaf0b4 --- /dev/null +++ b/changelogs/2026-03/24_1745_sync.md @@ -0,0 +1,60 @@ +# API 变更通知 + +**更新时间**: 2026-03-24 17:46 + +## ⚠️ Breaking Changes (6) + +> **前端必须处理的变更,不处理会导致功能异常** + +### 订单服务 + +**字段删除** + +| 数据对象 | 删除字段 | 原类型 | +| --- | --- | --- | +| `退款政策VO` | ~~`isDefault`~~ | `boolean` | +| `退款政策VO` | ~~`refundType`~~ | `string` | +| `退款政策请求` | ~~`isDefault`~~ | `boolean` | +| `退款政策请求` | ~~`refundType`~~ | `string` | + +**字段类型变化** + +| 数据对象 | 字段 | 原类型 | 新类型 | +| --- | --- | --- | --- | +| `OrderTraveler` | `gender` | `integer(int32)` | `string` | +| `出行人信息` | `gender` | `integer(int32)` | `string` | + +## ℹ️ 新增 (23) + +### 订单服务 + +**新增接口** + +- 🆕 `DELETE /admin/order/{orderId}/surcharge/{surchargeId}` +- 🆕 `GET /admin/order/{orderId}/travelers` +- 🆕 `POST /admin/order/{orderId}/surcharge` +- 🆕 `PUT /admin/order/{orderId}/surcharge/{surchargeId}` + +**新增字段** + +| 数据对象 | 新增字段 | 类型 | +| --- | --- | --- | +| `OrderTimeline` | `actionLabel` | `string` | +| `OrderTimeline` | `operatorTypeLabel` | `string` | +| `OrderTodo` | `assigneeRoleLabel` | `string` | +| `OrderTodo` | `todoTypeLabel` | `string` | +| `OrderTraveler` | `idCardTypeLabel` | `string` | +| `OrderTraveler` | `insurancePolicies` | `Map«string,object»[]` | +| `OrderTraveler` | `travelerTypeLabel` | `string` | +| `管理员修改订单请求` | `customizerId` | `integer(int64)` | +| `管理员订单列表VO` | `checklistConfirmed` | `boolean` | +| `管理员订单列表VO` | `mchName` | `string` | +| `管理员订单列表VO` | `surchargeAmount` | `number` | +| `订单详情VO` | `hotelAssignmentDetails` | `酒店分配详情(按家庭分组)[]` | +| `订单详情VO` | `mchName` | `string` | +| `订单详情VO` | `paymentModeLabel` | `string` | +| `订单详情VO` | `pendingUpgradeAmount` | `number` | +| `订单详情VO` | `productTypeLabel` | `string` | +| `订单详情VO` | `refundPolicy` | `退款政策VO` | +| `订单详情VO` | `surchargeAmount` | `number` | +| `订单详情VO` | `surcharges` | `OrderSurcharge[]` |