# 小程序聚合服务 API 文档 **服务**: `hl-mp-service` **接口总数**: 132 ## 目录 - **C端 - 产品接口** (8 个接口) - **C端 - 公共接口** (6 个接口) - **C端 - 出行人接口** (6 个接口) - **C端 - 前端配置接口** (2 个接口) - **C端 - 发票接口** (4 个接口) - **C端 - 合同接口** (5 个接口) - **C端 - 天气接口** (3 个接口) - **C端 - 字典接口** (1 个接口) - **C端 - 定制师接口** (5 个接口) - **C端 - 徽章接口** (1 个接口) - **C端 - 心愿单接口** (2 个接口) - **C端 - 探索接口** (5 个接口) - **C端 - 搜索接口** (1 个接口) - **C端 - 支付接口** (3 个接口) - **C端 - 收藏接口** (6 个接口) - **C端 - 攻略接口** (4 个接口) - **C端 - 景区接口** (3 个接口) - **C端 - 活动接口** (2 个接口) - **C端 - 消息接口** (5 个接口) - **C端 - 用户接口** (8 个接口) - **C端 - 相册接口** (4 个接口) - **C端 - 行程接口** (4 个接口) - **C端 - 订单接口** (11 个接口) - **C端 - 评价接口** (13 个接口) - **C端 - 足迹接口** (4 个接口) - **C端 - 轮播图接口** (1 个接口) - **C端 - 退款接口** (7 个接口) - **C端 - 通用点赞** (3 个接口) - **C端 - 酒店接口** (2 个接口) - **C端 - 餐厅接口** (2 个接口) - **C端 - 首页接口** (1 个接口) --- ## C端 - 产品接口 ### `GET` /mp/product/batch/{batchId}/combos **GROUP批次套餐列表** 返回指定批次的所有套餐（名称、人数组合、价格、库存） **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `batchId` | `integer` | | 批次ID | **响应** `统一响应结果«List«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `Map«string,object»[]` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/product/lines **产品线列表** 返回所有已启用的产品线，用于小程序首页或筛选栏展示 **响应** `统一响应结果«List«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `Map«string,object»[]` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/product/list **产品列表** 分页查询已上架产品，支持按关键词、产品类型(CORE/ROUTE/CUSTOM/GROUP)、季节、天数、目的地、产品线筛选和排序 **关联字典（BFF透传）**： - product_type：产品类型（列表筛选+显示） - product_status：产品状态（透传自product-service） **查询参数** | 参数 | 类型 | 必填 | 说明 | 示例 | | --- | --- | --- | --- | --- | | `destination` | `string` | | 目的地 | | | `keyword` | `string` | | 搜索关键词 | | | `lineId` | `string` | | 产品线ID | | | `page` | `integer(int32)` | | 页码 | | | `pageSize` | `integer(int32)` | | 每页条数 | | | `productType` | `string` | | 产品类型：CORE/ROUTE/CUSTOM/GROUP | | | `season` | `string` | | 季节 | | | `sortBy` | `string` | | 排序字段 | | | `sortDir` | `string` | | 排序方向 | | | `tripDays` | `integer(int32)` | | 天数 | | **响应** `统一响应结果«分页结果«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `分页结果«Map«string,object»»` | | 响应数据 | |   `page` | `int` | | 当前页码 | |   `pageSize` | `int` | | 每页条数 | |   `records` | `Map«string,object»[]` | | 数据列表 | |   `total` | `int` | | 总记录数 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/product/{productId} **产品详情（聚合收藏状态）** 聚合流程：获取产品详情 → 并行查询收藏状态 → 异步记录足迹 → 返回聚合数据。支持未登录访问（不返回收藏状态） **关联字典（BFF透传）**： - product_type：产品类型（显示） - product_status：产品状态（透传自product-service） **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `productId` | `integer` | | 产品ID | **响应** `统一响应结果«C端产品详情»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `C端产品详情` | | 响应数据 | |   `chatMessages` | `Map«string,object»[]` | | 群聊最近消息（来自会话存档） | |   `earliestBookingDate` | `string` | | 最早可订日期(如 2026-07-15) | |   `earlyBirdDiscount` | `number` | | 早鸟优惠金额(元/人) | |   `earlyBirdPlanName` | `string` | | 早鸟计划名称 | |   `isFavorited` | `boolean` | | 是否已收藏（null表示未登录） | |   `participantFamilyCount` | `int` | | 参与家庭数 | |   `product` | `object` | | 产品详情（来自product-service） | |   `reviewStats` | `object` | | 评价统计数据 | |   `topLikedReview` | `object` | | 最高点赞评价 | |   `topRatedReview` | `object` | | 最高评分评价 | |   `totalSold` | `int` | | 已购人数 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/product/{productId}/batch-calendar **GROUP批次日历** 返回可报名批次列表（出发日期、剩余名额等），仅ENROLLING和CONFIRMED状态 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `productId` | `integer` | | 产品ID | **响应** `统一响应结果«List«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `Map«string,object»[]` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/product/{productId}/group-quote **GROUP报价** 返回指定批次的各套餐报价（totalSellPrice） **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `productId` | `integer` | | 产品ID | **查询参数** | 参数 | 类型 | 必填 | 说明 | 示例 | | --- | --- | --- | --- | --- | | `batchId` | `integer(int64)` | | 批次ID | | **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/product/{productId}/price-calendar **价格日历** 返回产品指定日期范围内的每日价格，用于日历组件展示。不传日期时默认返回未来一个月 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `productId` | `integer` | | 产品ID | **查询参数** | 参数 | 类型 | 必填 | 说明 | 示例 | | --- | --- | --- | --- | --- | | `endDate` | `string` | | 结束日期 | | | `startDate` | `string` | | 开始日期 | | **响应** `统一响应结果«List«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `Map«string,object»[]` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `POST` /mp/product/{productId}/quote **报价计算（含早鸟优惠）** 报价流程：传入出发日期+人数 → 价格日历计算基础报价（与下单一致） → 匹配早鸟优惠方案 → 返回明细报价+优惠信息。 支付方式说明： - FULL: 全额支付，需一次性付清全部金额 - DEPOSIT: 定金+尾款，先付定金（比例由产品配置），出行前补齐尾款 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `productId` | `integer` | | 产品ID | **请求体** `产品报价请求` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `adultCount` | `int` | 是 | 成人数量 | | `babyCount` | `int` | | 婴儿数量 | | `childCount` | `int` | | 儿童数量 | | `childNeedBed` | `boolean` | | 儿童是否需要床位 | | `departureDate` | `string` | 是 | 出发日期 | | `youngChildCount` | `int` | | 幼儿数量 | **响应** `统一响应结果«产品报价结果»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `产品报价结果` | | 响应数据 | |   `adultSellPrice` | `number` | | 成人单价 | |   `babySellPrice` | `number` | | 幼童单价（固定价） | |   `childSellPrice` | `number` | | 儿童单价 | |   `childWithBedFee` | `number` | | 儿童加床费 | |   `depositPayment` | `定金支付选项` | | 定金支付信息（仅paymentMode=DEPOSIT时有值） | |     `balanceAmount` | `number` | | 尾款金额（出行前需付） | |     `depositAmount` | `number` | | 定金金额（首次需付） | |     `depositRatio` | `int` | | 定金比例(%) | |     `description` | `string` | | 说明 | |   `earlyBirdDiscount` | `早鸟优惠信息` | | 早鸟优惠信息，无优惠时为null | |     `discountAmount` | `number` | | 优惠金额 | |     `minPeople` | `int` | | 最低人数要求 | |     `planId` | `long` | | 优惠方案ID | |     `planName` | `string` | | 优惠方案名称 | |   `finalPrice` | `number` | | 最终价（早鸟优惠后） | |   `fullPayment` | `全额支付选项` | | 全额支付信息 | |     `amount` | `number` | | 应付金额 | |     `description` | `string` | | 说明 | |   `grandTotalSellPrice` | `number` | | 总售价（优惠前） | |   `paymentMode` | `string` | | 支付方式: FULL(全额支付) / DEPOSIT(定金+尾款) | |   `totalAdultSellPrice` | `number` | | 成人小计 | |   `totalBabySellPrice` | `number` | | 幼童小计 | |   `totalChildSellPrice` | `number` | | 儿童小计 | |   `totalYoungChildSellPrice` | `number` | | 小童小计 | |   `youngChildSellPrice` | `number` | | 小童单价（儿童价×折扣比例） | | `message` | `string` | | 响应消息 | --- ## C端 - 公共接口 ### `GET` /mp/common/agreement/list **协议列表** 获取所有已上线的协议列表（不含内容，仅含类型、标题、版本） **响应** `统一响应结果«List«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `Map«string,object»[]` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/common/agreement/{type} **获取协议文本** 获取指定类型的协议文本（如隐私政策、用户协议），返回富文本内容 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `type` | `string` | 是 | 协议类型: privacy(隐私政策) / user(用户协议) | **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/common/config **应用配置** 获取应用全局配置信息 **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/common/contact **联系方式列表** 获取有效的联系方式列表（电话/微信/邮箱等） **响应** `统一响应结果«List«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `Map«string,object»[]` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/common/faq **FAQ列表** 获取常见问题列表（按分类分组） **响应** `统一响应结果«List«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `Map«string,object»[]` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `POST` /mp/common/feedback **提交反馈** 提交用户反馈，支持文字内容和图片附件 **请求体** `提交反馈请求` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `contact` | `string` | | 联系方式 | | `content` | `string` | 是 | 反馈内容 | | `images` | `string[]` | | 图片URL列表 | **响应** `统一响应结果«Void»` --- ## C端 - 出行人接口 ### `GET` /mp/user/traveler **出行人列表** 返回当前用户的所有出行人列表。如果用户已完善实名信息，列表中会自动包含一条「本人」虚拟记录(travelerId=0) **响应** `统一响应结果«List«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `Map«string,object»[]` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `POST` /mp/user/traveler **添加出行人** 添加常用出行人信息（姓名/证件/联系方式等），下单时可快速选择。单个用户最多50个出行人 **请求体** `修改)` **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/user/traveler/{id} **出行人详情** 获取单个出行人的完整信息（姓名、证件信息、联系方式等）。 **权限**：需登录，仅能查看自己的出行人。 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `id` | `integer` | | 出行人ID | **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `PUT` /mp/user/traveler/{id} **更新出行人** 修改出行人信息，支持部分更新（只传需要修改的字段）。已关联订单的出行人修改不影响历史订单记录。 **权限**：需登录。 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `id` | `integer` | | 出行人ID | **请求体** `修改)` **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `DELETE` /mp/user/traveler/{id} **删除出行人** 删除常用出行人记录。默认出行人不可删除，需先取消默认后再删除。 **权限**：需登录。 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `id` | `integer` | | 出行人ID | **响应** `统一响应结果«Void»` --- ### `PUT` /mp/user/traveler/{id}/default **设为默认出行人** 设为默认出行人后，下单时自动作为第一个出行人。每个用户只能有一个默认出行人 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `id` | `integer` | | 出行人ID | **响应** `统一响应结果«Void»` --- ## C端 - 前端配置接口 ### `GET` /mp/config **获取所有非敏感前端配置** 返回所有非SECRET类型的前端配置项（如主题色、客服电话、版本号等）。不含敏感配置，可安全传输给小程序端。 **响应** `统一响应结果«List«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `Map«string,object»[]` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/config/group/{group} **按分组获取非敏感前端配置** 按配置分组获取前端配置项，如UI分组、功能开关分组等。用于小程序按需加载特定分组的配置。 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `group` | `string` | | 配置分组 | **响应** `统一响应结果«List«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `Map«string,object»[]` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ## C端 - 发票接口 ### `POST` /mp/invoice/apply **申请开票** 开票流程：订单完成后 → 填写发票信息(抬头/税号/类型) → 提交开票申请 → 管理员处理 → 发送电子发票 **请求体** `发票申请请求` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `email` | `string` | | 接收邮箱 | | `invoiceTitle` | `string` | 是 | 发票抬头 | | `invoiceType` | `string` | 是 | 发票类型: PERSONAL(个人)/COMPANY(企业) | | `orderId` | `string` | 是 | 订单ID | | `taxpayerId` | `string` | | 纳税人识别号（企业发票必填） | **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/invoice/order/{orderId} **通过订单ID查询发票** 查询指定订单的发票信息，如果订单未开票则返回null **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `orderId` | `integer` | | 订单ID | **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/invoice/{id} **发票详情** 获取发票的完整信息，包含开票状态、发票抬头、税号、金额、电子发票文件链接等 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `id` | `integer` | | 发票ID | **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `POST` /mp/invoice/{invoiceId}/reissue **发票换开** 对已开发票申请换开（修改抬头/税号等），原发票作废后重新开具新发票 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `invoiceId` | `integer` | | 发票ID | **请求体** `发票换开请求` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `email` | `string` | | 接收邮箱 | | `invoiceTitle` | `string` | 是 | 发票抬头 | | `taxNumber` | `string` | | 纳税人识别号（企业发票必填） | | `titleType` | `string` | 是 | 抬头类型: PERSONAL(个人)/COMPANY(企业) | **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ## C端 - 合同接口 ### `GET` /mp/contract/by-order/{orderId} **按订单查合同** 返回订单关联的最新有效合同（非作废） **关联字典（BFF透传）**： - contract_status：合同状态（显示） **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `orderId` | `integer` | | 订单ID | **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/contract/by-order/{orderId}/all **按订单查所有合同** 返回订单关联的所有有效合同（TOUR+INSURANCE各一条） **关联字典（BFF透传）**： - contract_status：合同状态（显示） **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `orderId` | `integer` | | 订单ID | **响应** `统一响应结果«List«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `Map«string,object»[]` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/contract/list **合同列表** **关联字典（BFF透传）**： - contract_status：合同状态（列表筛选+显示） **查询参数** | 参数 | 类型 | 必填 | 说明 | 示例 | | --- | --- | --- | --- | --- | | `page` | `integer(int32)` | | 页码 | | | `pageSize` | `integer(int32)` | | 每页条数 | | | `status` | `string` | | 状态 | | **响应** `统一响应结果«分页结果«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `分页结果«Map«string,object»»` | | 响应数据 | |   `page` | `int` | | 当前页码 | |   `pageSize` | `int` | | 每页条数 | |   `records` | `Map«string,object»[]` | | 数据列表 | |   `total` | `int` | | 总记录数 | | `message` | `string` | | 响应消息 | --- ### `POST` /mp/contract/{contractId}/resend-sms **重新发送合同签署短信** 重新向出行人发送合同签署短信通知，适用于出行人未收到短信或短信过期的场景。 **权限**：需登录。 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `contractId` | `integer` | | 合同ID | **响应** `统一响应结果«boolean»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `boolean` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/contract/{id} **合同详情** 返回合同基本信息、签署状态、出行人签署详情及合同文件下载链接 **关联字典（BFF透传）**： - contract_status：合同状态（显示） **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `id` | `integer` | | 合同ID | **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ## C端 - 天气接口 ### `GET` /mp/weather/forecast **获取指定城市天气预报** 通过高德天气API查询指定城市未来3天的天气预报信息 **查询参数** | 参数 | 类型 | 必填 | 说明 | 示例 | | --- | --- | --- | --- | --- | | `city` | `string` | | 城市名称 | | **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/weather/itinerary/{orderId} **获取订单行程天气** 根据订单行程中的目的地城市，批量查询每日天气信息，用于行程详情页展示 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `orderId` | `integer` | | 订单ID | **响应** `统一响应结果«List«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `Map«string,object»[]` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/weather/live **获取指定城市实况天气** 通过高德天气API查询指定城市的实时天气（温度、湿度、风向等） **查询参数** | 参数 | 类型 | 必填 | 说明 | 示例 | | --- | --- | --- | --- | --- | | `city` | `string` | | 城市名称 | | **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ## C端 - 字典接口 ### `GET` /dict/all **获取所有字典数据** 获取系统全部字典数据（按字典类型分组），用于小程序端的下拉选项、枚举映射等。建议前端缓存此数据 **响应** `统一响应结果«List«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `Map«string,object»[]` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ## C端 - 定制师接口 ### `GET` /mp/designer **定制师列表(含真实产品数和评分，综合排序)** 获取定制师列表，聚合层会补充每个定制师的真实产品数量和评价评分。按综合排序（评分>路线数>咨询人数），用于小程序定制师推荐页。 **查询参数** | 参数 | 类型 | 必填 | 说明 | 示例 | | --- | --- | --- | --- | --- | | `limit` | `integer(int32)` | | 每页条数 | | | `page` | `integer(int32)` | | 页码 | | **响应** `统一响应结果«List«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `Map«string,object»[]` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/designer/featured **推荐定制师(综合排序第一名)** 获取综合排序排名第一的定制师信息（含产品数和评分），用于首页推荐定制师卡片展示。 **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/designer/{id} **定制师详情(含产品数量和评分)** 获取定制师完整个人信息，聚合层会补充该定制师的已发布产品数量和综合评分，用于定制师个人主页展示。 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `id` | `integer` | | 定制师ID | **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/designer/{id}/products **定制师已发布产品列表** **关联字典（BFF透传）**： - product_type：产品类型（显示） **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `id` | `integer` | | 定制师ID | **查询参数** | 参数 | 类型 | 必填 | 说明 | 示例 | | --- | --- | --- | --- | --- | | `page` | `integer(int32)` | | 页码 | | | `pageSize` | `integer(int32)` | | 每页条数 | | **响应** `统一响应结果«分页结果«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `分页结果«Map«string,object»»` | | 响应数据 | |   `page` | `int` | | 当前页码 | |   `pageSize` | `int` | | 每页条数 | |   `records` | `Map«string,object»[]` | | 数据列表 | |   `total` | `int` | | 总记录数 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/designer/{id}/reviews **定制师产品评价列表** **关联字典（BFF透传）**： - rating_level：评价等级（显示） **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `id` | `integer` | | 定制师ID | **查询参数** | 参数 | 类型 | 必填 | 说明 | 示例 | | --- | --- | --- | --- | --- | | `page` | `integer(int32)` | | 页码 | | | `pageSize` | `integer(int32)` | | 每页条数 | | **响应** `统一响应结果«分页结果«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `分页结果«Map«string,object»»` | | 响应数据 | |   `page` | `int` | | 当前页码 | |   `pageSize` | `int` | | 每页条数 | |   `records` | `Map«string,object»[]` | | 数据列表 | |   `total` | `int` | | 总记录数 | | `message` | `string` | | 响应消息 | --- ## C端 - 徽章接口 ### `GET` /mp/badge **获取徽章数据** 返回用户的徽章统计（未读消息数、待办事项数等），用于「我的」页面角标展示 **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ## C端 - 心愿单接口 ### `GET` /mp/wish **心愿单列表** 返回当前用户的心愿单列表，按创建时间倒序排列 **响应** `统一响应结果«List«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `Map«string,object»[]` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `POST` /mp/wish **创建心愿** 创建旅行心愿，描述想去的地方和时间偏好，定制师可据此推荐产品 **请求体** `创建心愿单请求` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `notes` | `string` | | 备注 | | `productId` | `string` | 是 | 产品ID | **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ## C端 - 探索接口 ### `GET` /mp/explore/list **探索列表** 获取已启用的探索分类列表（图文攻略内容），支持综合/最新/最热排序，分页返回。用于小程序探索频道首页瀑布流展示。 **查询参数** | 参数 | 类型 | 必填 | 说明 | 示例 | | --- | --- | --- | --- | --- | | `page` | `integer(int32)` | | 页码 | | | `pageSize` | `integer(int32)` | | 每页条数 | | | `sortType` | `string` | | 排序方式：comprehensive/newest/hottest | | **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/explore/{id} **探索详情** 自动增加浏览量，已登录时返回点赞/收藏状态 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `id` | `integer` | | 探索分类ID | **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `POST` /mp/explore/{id}/favorite **切换收藏** 对探索内容收藏/取消收藏，返回当前收藏状态（true=已收藏）。收藏后可在'我的收藏'中查看。 **权限**：需登录。 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `id` | `integer` | | 探索分类ID | **响应** `统一响应结果«boolean»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `boolean` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `POST` /mp/explore/{id}/like **切换点赞** 对探索内容点赞/取消点赞，返回当前点赞状态（true=已点赞）。 **权限**：需登录。 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `id` | `integer` | | 探索分类ID | **响应** `统一响应结果«boolean»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `boolean` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `POST` /mp/explore/{id}/view **浏览+1** 增加探索内容的浏览计数。前端进入探索详情页时调用，无需登录。 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `id` | `integer` | | 探索分类ID | **响应** `统一响应结果«Void»` --- ## C端 - 搜索接口 ### `GET` /mp/search **搜索产品** 按关键词搜索已上架产品（匹配产品名称和描述），支持按产品类型进一步筛选 **关联字典（BFF透传）**： - product_type：产品类型（筛选+显示） **查询参数** | 参数 | 类型 | 必填 | 说明 | 示例 | | --- | --- | --- | --- | --- | | `keyword` | `string` | | 搜索关键词 | | | `page` | `integer(int32)` | | 页码 | | | `pageSize` | `integer(int32)` | | 每页条数 | | | `productType` | `string` | | 产品类型：CORE/ROUTE/CUSTOM/GROUP | | **响应** `统一响应结果«分页结果«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `分页结果«Map«string,object»»` | | 响应数据 | |   `page` | `int` | | 当前页码 | |   `pageSize` | `int` | | 每页条数 | |   `records` | `Map«string,object»[]` | | 数据列表 | |   `total` | `int` | | 总记录数 | | `message` | `string` | | 响应消息 | --- ## C端 - 支付接口 ### `POST` /mp/payment/prepay **发起支付** 支付流程：选择支付方式(JSAPI/H5) → 调用微信支付API → 返回支付参数 → 前端调起微信支付 **关联字典（BFF透传）**： - payment_status：支付状态（返回字段） **请求体** `支付预下单请求` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `clientIp` | `string` | | 客户端IP（H5支付必填） | | `orderId` | `string` | 是 | 订单ID | | `tradeType` | `string` | 是 | 支付方式: JSAPI(小程序支付)/H5(H5支付) | **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/payment/status/{orderId} **查询支付状态** **关联字典（BFF透传）**： - payment_status：支付状态（显示） **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `orderId` | `integer` | | 订单ID | **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/payment/transactions/{orderId} **订单交易记录列表** **关联字典（BFF透传）**： - payment_status：支付状态（显示） **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `orderId` | `integer` | | 订单ID | **响应** `统一响应结果«List«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `Map«string,object»[]` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ## C端 - 收藏接口 ### `GET` /mp/user/favorite **收藏列表（含资源摘要）** 分页查询收藏列表，聚合层会补充每个收藏项对应资源的摘要信息（名称、封面图、价格等）。支持按目标类型筛选。 **权限**：需登录。 **关联字典**： - favorite_resource_type：收藏资源类型（PRODUCT/SCENIC/RESTAURANT/ACTIVITY） **查询参数** | 参数 | 类型 | 必填 | 说明 | 示例 | | --- | --- | --- | --- | --- | | `page` | `integer(int32)` | | 页码 | | | `pageSize` | `integer(int32)` | | 每页条数 | | | `targetType` | `string` | | 目标类型筛选（字典：favorite_resource_type）：PRODUCT/SCENIC/RESTAURANT/ACTIVITY | | **响应** `统一响应结果«分页结果«收藏列表项（含资源摘要）»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `分页结果«收藏列表项（含资源摘要）»` | | 响应数据 | |   `page` | `int` | | 当前页码 | |   `pageSize` | `int` | | 每页条数 | |   `records` | `收藏列表项（含资源摘要）[]` | | 数据列表 | |     `coverUrl` | `string` | | 封面图URL | |     `createdAt` | `string` | | 收藏时间 | |     `favoriteId` | `string` | | 收藏记录ID | |     `name` | `string` | | 资源名称 | |     `tags` | `string[]` | | 标签列表 | |     `targetId` | `string` | | 目标资源ID | |     `targetType` | `string` | | 目标类型（字典：favorite_resource_type） | |   `total` | `int` | | 总记录数 | | `message` | `string` | | 响应消息 | --- ### `POST` /mp/user/favorite **添加收藏** 将产品/景区/餐厅/活动加入收藏。同一目标重复收藏会返回已有收藏记录 **请求体** `收藏请求` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `targetId` | `string` | 是 | 目标资源ID | | `targetType` | `string` | 是 | 目标类型（字典：favorite_resource_type） | **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `DELETE` /mp/user/favorite/batch **批量删除收藏** 批量删除多条收藏记录，传入收藏记录ID列表。用于收藏管理页面的批量操作。 **权限**：需登录，仅能删除自己的收藏。 **请求体** `long[]` **响应** `统一响应结果«Void»` --- ### `DELETE` /mp/user/favorite/by-target **按目标取消收藏** 通过目标类型+目标ID取消收藏，适用于详情页点击取消收藏的场景（不需要知道收藏记录ID）。 **权限**：需登录。 **查询参数** | 参数 | 类型 | 必填 | 说明 | 示例 | | --- | --- | --- | --- | --- | | `targetId` | `integer(int64)` | | 目标资源ID | | | `targetType` | `string` | | 目标类型 | | **响应** `统一响应结果«Void»` --- ### `GET` /mp/user/favorite/check **检查是否已收藏** 检查当前用户是否已收藏指定资源，用于详情页收藏按钮状态显示。 **权限**：需登录。 **查询参数** | 参数 | 类型 | 必填 | 说明 | 示例 | | --- | --- | --- | --- | --- | | `targetId` | `integer(int64)` | | 目标资源ID | | | `targetType` | `string` | | 目标类型（字典：favorite_resource_type） | | **响应** `统一响应结果«boolean»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `boolean` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `DELETE` /mp/user/favorite/{id} **取消收藏** 通过收藏记录ID取消收藏，适用于收藏列表页的删除操作。 **权限**：需登录，仅能删除自己的收藏。 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `id` | `integer` | | 收藏记录ID | **响应** `统一响应结果«Void»` --- ## C端 - 攻略接口 ### `GET` /mp/wiki/article/{articleId} **文章详情** **关联字典（BFF透传）**： - wiki_status：文章状态（返回字段） **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `articleId` | `integer` | | 文章ID | **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/wiki/categories **攻略分类列表** 获取所有已启用的攻略分类，按排序值排列。用于小程序攻略频道的分类导航展示。 **响应** `统一响应结果«List«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `Map«string,object»[]` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/wiki/category/{categoryId}/articles **分类文章列表** 分页查询指定攻略分类下已发布的文章列表，按发布时间倒序排列。用于攻略分类详情页。 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `categoryId` | `integer` | | 攻略分类ID | **查询参数** | 参数 | 类型 | 必填 | 说明 | 示例 | | --- | --- | --- | --- | --- | | `page` | `integer(int32)` | | 页码 | | | `pageSize` | `integer(int32)` | | 每页条数 | | **响应** `统一响应结果«分页结果«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `分页结果«Map«string,object»»` | | 响应数据 | |   `page` | `int` | | 当前页码 | |   `pageSize` | `int` | | 每页条数 | |   `records` | `Map«string,object»[]` | | 数据列表 | |   `total` | `int` | | 总记录数 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/wiki/recommend-articles **推荐文章列表** 获取编辑推荐的攻略文章列表（按推荐权重排序），用于首页或攻略频道的推荐位展示。 **查询参数** | 参数 | 类型 | 必填 | 说明 | 示例 | | --- | --- | --- | --- | --- | | `limit` | `integer(int32)` | | 返回条数 | | **响应** `统一响应结果«List«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `Map«string,object»[]` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ## C端 - 景区接口 ### `GET` /mp/scenic/list **景区列表** 分页查询已上架的景区列表，支持按关键词和城市筛选。聚合层透传resource-service的景区数据。 **查询参数** | 参数 | 类型 | 必填 | 说明 | 示例 | | --- | --- | --- | --- | --- | | `city` | `string` | | 城市 | | | `keyword` | `string` | | 关键词 | | | `page` | `integer(int32)` | | 页码 | | | `pageSize` | `integer(int32)` | | 每页条数 | | **响应** `统一响应结果«分页结果«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `分页结果«Map«string,object»»` | | 响应数据 | |   `page` | `int` | | 当前页码 | |   `pageSize` | `int` | | 每页条数 | |   `records` | `Map«string,object»[]` | | 数据列表 | |   `total` | `int` | | 总记录数 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/scenic/{scenicId} **景区详情** 获取景区完整信息（含季节素材、图文详情、价格等），自动注入静态地图图片URL用于详情页地图展示。 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `scenicId` | `integer` | | 景区ID | **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/scenic/{scenicId}/nearby **附近景区（地理+探索分类聚合）** 聚合两个数据源：1.基于经纬度的地理位置附近景区（resource-service）；2.探索分类关联的景区（user-service）。去重合并后返回，用于景区详情页底部'附近推荐'展示。 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `scenicId` | `integer` | | 景区ID | **查询参数** | 参数 | 类型 | 必填 | 说明 | 示例 | | --- | --- | --- | --- | --- | | `limit` | `integer(int32)` | | 返回条数 | | | `radius` | `number(double)` | | 搜索半径(km) | | **响应** `统一响应结果«List«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `Map«string,object»[]` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ## C端 - 活动接口 ### `GET` /mp/activity/list **活动列表** 分页查询已上架的活动列表，支持关键词和分类筛选。聚合层透传resource-service的活动数据给小程序前端。 **查询参数** | 参数 | 类型 | 必填 | 说明 | 示例 | | --- | --- | --- | --- | --- | | `categoryCode` | `string` | | 分类 | | | `keyword` | `string` | | 关键词 | | | `page` | `integer(int32)` | | 页码 | | | `pageSize` | `integer(int32)` | | 每页条数 | | **响应** `统一响应结果«分页结果«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `分页结果«Map«string,object»»` | | 响应数据 | |   `page` | `int` | | 当前页码 | |   `pageSize` | `int` | | 每页条数 | |   `records` | `Map«string,object»[]` | | 数据列表 | |   `total` | `int` | | 总记录数 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/activity/{activityId} **活动详情** 获取活动完整信息（含图文详情、价格等），自动注入静态地图图片URL用于详情页地图展示。 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `activityId` | `integer` | | 活动ID | **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ## C端 - 消息接口 ### `GET` /mp/message/list **消息列表** 消息列表，支持按分类筛选，按时间倒序分页返回 **查询参数** | 参数 | 类型 | 必填 | 说明 | 示例 | | --- | --- | --- | --- | --- | | `category` | `string` | | 消息分类筛选，不传返回全部 | | | `page` | `integer(int32)` | | 页码，默认1 | | | `pageSize` | `integer(int32)` | | 每页条数，默认20 | | **响应** `统一响应结果«分页结果«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `分页结果«Map«string,object»»` | | 响应数据 | |   `page` | `int` | | 当前页码 | |   `pageSize` | `int` | | 每页条数 | |   `records` | `Map«string,object»[]` | | 数据列表 | |   `total` | `int` | | 总记录数 | | `message` | `string` | | 响应消息 | --- ### `PUT` /mp/message/read-all **全部标记已读** 将指定分类或全部消息标记为已读，不传category则全部已读 **查询参数** | 参数 | 类型 | 必填 | 说明 | 示例 | | --- | --- | --- | --- | --- | | `category` | `string` | | 消息分类，不传则将所有分类标记为已读 | | **响应** `统一响应结果«Void»` --- ### `GET` /mp/message/summary **消息摘要** 获取各分类的未读数量和最新一条消息，用于消息中心首页展示 **响应** `统一响应结果«List«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `Map«string,object»[]` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `DELETE` /mp/message/{id} **删除消息** 删除单条消息 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `id` | `integer` | 是 | 消息ID | **响应** `统一响应结果«Void»` --- ### `PUT` /mp/message/{id}/read **标记已读** 标记单条消息为已读 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `id` | `integer` | 是 | 消息ID | **响应** `统一响应结果«Void»` --- ## C端 - 用户接口 ### `DELETE` /mp/user/account **注销账号** 注销后用户数据将被软删除，30天内可联系客服恢复 **响应** `统一响应结果«Void»` --- ### `POST` /mp/user/login **微信登录** 登录流程：小程序wx.login获取code → 后端换取openid → 查找/创建用户 → 返回JWT令牌+needProfile标记 **请求体** `微信登录请求` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `string` | 是 | 微信授权code | **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `POST` /mp/user/login/sms **短信登录** 登录流程：获取验证码 → 验证手机号+验证码 → 查找/创建用户 → 返回JWT令牌 **请求体** `短信验证码登录请求` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `string` | 是 | 验证码 | | `phone` | `string` | 是 | 手机号 | **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `POST` /mp/user/logout **用户登出** 清除用户登录状态和服务端缓存的令牌信息。登出后需重新登录获取新令牌。 **权限**：需登录。 **响应** `统一响应结果«Void»` --- ### `POST` /mp/user/ocr/idcard **身份证OCR识别** 将身份证图片上传到OSS后，传入ossUrl进行OCR识别。返回姓名、身份证号、性别、民族等结构化数据，可用于自动填充出行人信息 **请求体** `身份证OCR识别请求` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `imgUrl` | `string` | 是 | 身份证图片的OSS地址 | **响应** `统一响应结果«Map«string,string»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/user/profile **获取用户信息** 获取当前登录用户的个人资料，包含头像、昵称、手机号、实名信息等 **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `PUT` /mp/user/profile **更新用户信息** 更新当前用户的个人资料，支持部分更新（只传需要修改的字段）。首次完善资料时realName为必填 **请求体** `更新个人资料请求` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `avatar` | `string` | | 头像URL | | `birthday` | `string` | | 生日 | | `email` | `string` | | 邮箱 | | `gender` | `int` | | 性别: 1=男, 2=女 | | `nationality` | `string` | | 国籍 | | `nickname` | `string` | | 昵称 | | `phone` | `string` | | 手机号 | | `realName` | `string` | | 真实姓名 | **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `POST` /mp/user/sms/send **发送短信验证码** 向指定手机号发送登录验证码，有效期5分钟，60秒内不可重复发送 **请求体** `发送短信验证码请求` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `phone` | `string` | 是 | 手机号 | **响应** `统一响应结果«Void»` --- ## C端 - 相册接口 ### `GET` /mp/album/file/{albumFileId}/download-url **获取文件下载链接** 获取文件的预签名下载URL，有效期有限 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `albumFileId` | `integer` | 是 | 相册文件ID | **响应** `统一响应结果«string»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `string` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/album/folder/{folderId}/files **文件夹下的文件列表** 获取文件夹下的文件列表（分页），含图片和视频 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `folderId` | `integer` | 是 | 文件夹ID | **查询参数** | 参数 | 类型 | 必填 | 说明 | 示例 | | --- | --- | --- | --- | --- | | `page` | `integer(int32)` | | 页码，默认1 | | | `size` | `integer(int32)` | | 每页数量，默认20 | | **响应** `统一响应结果«分页结果«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `分页结果«Map«string,object»»` | | 响应数据 | |   `page` | `int` | | 当前页码 | |   `pageSize` | `int` | | 每页条数 | |   `records` | `Map«string,object»[]` | | 数据列表 | |   `total` | `int` | | 总记录数 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/album/order/{orderId}/folders **订单的文件夹列表** 获取订单下的相册文件夹列表 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `orderId` | `integer` | 是 | 订单ID | **响应** `统一响应结果«List«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `Map«string,object»[]` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/album/orders **有相册的订单列表** 获取当前登录用户有相册的订单列表 **响应** `统一响应结果«List«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `Map«string,object»[]` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ## C端 - 行程接口 ### `GET` /mp/trip/list **行程列表** 获取当前登录用户的行程列表（已确认及进行中的订单对应的行程） **关联字典（BFF透传）**： - order_status：订单/行程状态（显示） **响应** `统一响应结果«List«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `Map«string,object»[]` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/trip/today **今日行程** 获取今日行程（如果有正在进行中的行程），无行程时data为null **关联字典（BFF透传）**： - order_status：订单/行程状态（显示） **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/trip/weather **天气查询** 高德天气API代理，传入城市名称返回实时天气信息 **查询参数** | 参数 | 类型 | 必填 | 说明 | 示例 | | --- | --- | --- | --- | --- | | `city` | `string` | 是 | 城市名称，如「成都」「拉萨」 | | **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/trip/{orderId} **行程详情** 获取订单对应的行程详情，含每日行程节点信息（景点/酒店/餐厅等） **关联字典（BFF透传）**： - order_status：订单/行程状态（显示） **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `orderId` | `integer` | 是 | 订单ID | **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ## C端 - 订单接口 ### `POST` /mp/order/bind-by-contact **绑定未绑定的订单** 绑定流程：用户登录 → 完善个人资料 → 自动通过联系人手机号+姓名匹配 → 将userId=NULL的订单绑定到当前用户 **请求体** `通过联系人信息绑定订单请求` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `contactName` | `string` | 是 | 联系人姓名 | | `contactPhone` | `string` | 是 | 联系人手机号 | **响应** `统一响应结果«int»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `int` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/order/count **各状态订单数量** 统计当前用户各状态的订单数量，用于「我的」页面的订单状态角标展示 **关联字典（BFF透传）**： - order_status：订单状态（状态分类统计） **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `POST` /mp/order/create **创建订单** 下单流程：选择产品 → 填写联系人/出行人信息 → 报价计算 → 创建订单 → 返回订单ID **请求体** `C端创建订单请求` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `adultCount` | `int` | | 成人数 | | `babyCount` | `int` | | 幼童数 | | `childCount` | `int` | | 儿童数 | | `childNeedBed` | `boolean` | | 儿童是否需要床位 | | `contactName` | `string` | 是 | 联系人姓名 | | `contactPhone` | `string` | 是 | 联系人电话 | | `customizerId` | `string` | | 定制师ID(通过分享链接下单时传入) | | `departureDate` | `string` | | 出发日期(GROUP产品从团期获取，可不传) | | `groupBatchId` | `string` | | 团期ID(GROUP产品必填) | | `productId` | `string` | 是 | 产品ID | | `remark` | `string` | | 备注 | | `roomCount` | `int` | | 房间数(GROUP产品，默认1) | | `sharerOpenid` | `string` | | 分享人微信openid（通过分享进入下单时传入，用于记录分享关系） | | `travelers` | `出行人信息[]` | | 出行人列表 | |   `birthday` | `string` | | 出生日期 | |   `email` | `string` | | 电子邮箱 | |   `emergencyContact` | `string` | | 紧急联系人 | |   `emergencyPhone` | `string` | | 紧急联系电话 | |   `gender` | `int` | | 性别（1=男, 2=女） | |   `idCardNo` | `string` | | 证件号码 | |   `idCardType` | `string` | | 证件类型 | |   `name` | `string` | 是 | 出行人姓名 | |   `nationality` | `string` | | 国籍 | |   `phone` | `string` | | 手机号 | |   `travelerType` | `string` | | 出行人类型（ADULT/CHILD/YOUNG_CHILD/BABY） | | `youngChildCount` | `int` | | 小童数 | **响应** `统一响应结果«订单详情»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `订单详情` | | 响应数据 | |   `adultCount` | `int` | | 成人数 | |   `babyCount` | `int` | | 幼童数 | |   `balanceAmount` | `number` | | 尾款金额 | |   `balancePayMethod` | `string` | | 尾款支付方式: ONLINE=线上 OFFLINE=线下 | |   `balanceProofUrl` | `string` | | 尾款凭证URL | |   `cancelReason` | `string` | | 取消原因 | |   `cancelledAt` | `string` | | 取消时间 | |   `checklistConfirmed` | `boolean` | | 清单确认状态 | |   `childCount` | `int` | | 儿童数 | |   `completedAt` | `string` | | 完成时间 | |   `confirmedAt` | `string` | | 确认时间 | |   `contactName` | `string` | | 联系人姓名 | |   `contactPhone` | `string` | | 联系人电话 | |   `contracts` | `Map«string,object»[]` | | 合同列表（含signUrl/fileUrl/status等） | |   `createTime` | `string` | | 创建时间 | |   `creatorAdminId` | `long` | | 创建人管理员ID | |   `creatorName` | `string` | | 创建人姓名 | |   `customizerId` | `long` | | 定制师ID | |   `customizerName` | `string` | | 定制师姓名 | |   `departureDate` | `string` | | 出发日期 | |   `depositAmount` | `number` | | 定金金额 | |   `depositRatio` | `int` | | 定金比例 | |   `discountAmount` | `number` | | 优惠金额 | |   `discountReason` | `string` | | 优惠原因 | |   `discounts` | `Map«string,object»[]` | | 优惠列表 | |   `expiryMinutes` | `int` | | 支付时限（分钟） | |   `expiryTime` | `string` | | 支付截止时间 | |   `hotelAssignments` | `string` | | 酒店分配信息JSON | |   `insurances` | `Map«string,object»[]` | | 保险订单列表（含productName/extPolicyNo/status/startDate/endDate等） | |   `mchId` | `string` | | 商户号 | |   `orderId` | `long` | | 订单ID | |   `orderNo` | `string` | | 订单编号 | |   `paidAmount` | `number` | | 已付金额 | |   `paidAt` | `string` | | 支付时间 | |   `payMethodLabel` | `string` | | 支付方式标签（如：微信支付、定金微信+尾款线下） | |   `paymentMode` | `string` | | 支付模式（FULL/DEPOSIT） | |   `processStatus` | `string` | | 内部流程状态 | |   `processStatusLabel` | `string` | | 内部流程状态标签 | |   `productCoverUrl` | `string` | | 产品封面图URL | |   `productId` | `long` | | 产品ID | |   `productName` | `string` | | 产品名称 | |   `productSnapshot` | `string` | | 产品快照JSON | |   `productType` | `string` | | 产品类型（CORE/ROUTE/CUSTOM/GROUP） | |   `readyAt` | `string` | | 就绪时间 | |   `refundAmount` | `number` | | 退款金额 | |   `remark` | `string` | | 备注 | |   `returnDate` | `string` | | 返程日期（出发日期 + 行程天数 - 1） | |   `reviewed` | `boolean` | | 是否已评价 | |   `roomInfo` | `string` | | 房间信息 | |   `status` | `string` | | 订单状态（PENDING_PAY/DEPOSIT_PAID/PAID/CONFIRMED/IN_PROGRESS/COMPLETED/CANCELLED） | |   `statusLabel` | `string` | | 订单状态标签 | |   `timeline` | `Map«string,object»[]` | | 时间线列表 | |   `todos` | `Map«string,object»[]` | | 待办列表 | |   `totalPrice` | `number` | | 总售价 | |   `travelers` | `Map«string,object»[]` | | 出行人列表 | |   `tripDays` | `int` | | 行程天数 | |   `tripNights` | `int` | | 行程晚数 | |   `unlockRequestedAt` | `string` | | 解锁请求时间 | |   `userId` | `long` | | 用户ID | |   `vehicleInfo` | `string` | | 车辆信息 | |   `youngChildCount` | `int` | | 小童数 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/order/list **订单列表** 分页查询当前用户的订单列表，支持按状态筛选。返回订单摘要信息（不含详细出行人信息） **关联字典（BFF透传）**： - order_status：订单状态（列表筛选+显示） - product_type：产品类型（订单卡片显示） **查询参数** | 参数 | 类型 | 必填 | 说明 | 示例 | | --- | --- | --- | --- | --- | | `page` | `integer(int32)` | | 页码 | | | `pageSize` | `integer(int32)` | | 每页条数 | | | `status` | `string` | | 状态 | | **响应** `统一响应结果«分页结果«订单列表项»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `分页结果«订单列表项»` | | 响应数据 | |   `page` | `int` | | 当前页码 | |   `pageSize` | `int` | | 每页条数 | |   `records` | `订单列表项[]` | | 数据列表 | |     `adultCount` | `int` | | 成人数 | |     `babyCount` | `int` | | 幼童数 | |     `balanceAmount` | `number` | | 尾款金额 | |     `childCount` | `int` | | 儿童数 | |     `contracts` | `Map«string,object»[]` | | 合同列表（含signUrl/fileUrl/status等） | |     `createTime` | `string` | | 创建时间 | |     `daysUntilDeparture` | `int` | | 距出发天数（负数表示已出发） | |     `departureDate` | `string` | | 出发日期 | |     `depositAmount` | `number` | | 定金金额 | |     `displayName` | `string` | | 显示名称（未支付=手机号+姓名，已支付=订单号） | |     `displayStatus` | `string` | | C端简化状态（PENDING_PAY/PENDING_DEPARTURE/PENDING_REVIEW/REFUND/CANCELLED） | |     `displayStatusLabel` | `string` | | C端简化状态标签 | |     `expiryTime` | `string` | | 支付截止时间（PENDING_PAY状态有效） | |     `insurances` | `Map«string,object»[]` | | 保险订单列表（含productName/extPolicyNo/status等） | |     `nextAction` | `string` | | 下一步操作提示 | |     `orderId` | `long` | | 订单ID | |     `orderNo` | `string` | | 订单编号 | |     `paidAmount` | `number` | | 已付金额 | |     `paymentMode` | `string` | | 支付模式（FULL/DEPOSIT） | |     `processStatus` | `string` | | 内部流程状态（字典：order_process_status） | |     `processStatusLabel` | `string` | | 内部流程状态标签（字典：order_process_status 翻译） | |     `productCoverUrl` | `string` | | 产品封面图URL | |     `productId` | `long` | | 产品ID | |     `productName` | `string` | | 产品名称 | |     `productType` | `string` | | 产品类型（CORE/ROUTE/CUSTOM/GROUP） | |     `status` | `string` | | 订单状态（PENDING_PAY/DEPOSIT_PAID/PAID/CONFIRMED/IN_PROGRESS/COMPLETED/CANCELLED） | |     `statusLabel` | `string` | | 订单状态标签 | |     `totalPrice` | `number` | | 总售价 | |     `tripDays` | `int` | | 行程天数 | |     `tripNights` | `int` | | 行程晚数 | |     `youngChildCount` | `int` | | 小童数 | |   `total` | `int` | | 总记录数 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/order/lookup **通过联系人手机号+姓名查找订单（无需登录）** 无需登录即可查询。用于管理员代下单场景：管理员创建订单后，用户通过联系人手机号+姓名查找订单并绑定到自己账号。仅返回尚未绑定用户(userId=NULL)的订单。 **查询参数** | 参数 | 类型 | 必填 | 说明 | 示例 | | --- | --- | --- | --- | --- | | `contactName` | `string` | | 联系人姓名 | | | `contactPhone` | `string` | | 联系人手机号 | | **响应** `统一响应结果«List«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `Map«string,object»[]` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/order/upcoming **即将出发的订单** 查询3天内即将出发的订单（状态为已确认/待出发/出行中），含合同和保险信息，按出发日期升序 **响应** `统一响应结果«List«订单列表项»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `订单列表项[]` | | 响应数据 | |   `adultCount` | `int` | | 成人数 | |   `babyCount` | `int` | | 幼童数 | |   `balanceAmount` | `number` | | 尾款金额 | |   `childCount` | `int` | | 儿童数 | |   `contracts` | `Map«string,object»[]` | | 合同列表（含signUrl/fileUrl/status等） | |   `createTime` | `string` | | 创建时间 | |   `daysUntilDeparture` | `int` | | 距出发天数（负数表示已出发） | |   `departureDate` | `string` | | 出发日期 | |   `depositAmount` | `number` | | 定金金额 | |   `displayName` | `string` | | 显示名称（未支付=手机号+姓名，已支付=订单号） | |   `displayStatus` | `string` | | C端简化状态（PENDING_PAY/PENDING_DEPARTURE/PENDING_REVIEW/REFUND/CANCELLED） | |   `displayStatusLabel` | `string` | | C端简化状态标签 | |   `expiryTime` | `string` | | 支付截止时间（PENDING_PAY状态有效） | |   `insurances` | `Map«string,object»[]` | | 保险订单列表（含productName/extPolicyNo/status等） | |   `nextAction` | `string` | | 下一步操作提示 | |   `orderId` | `long` | | 订单ID | |   `orderNo` | `string` | | 订单编号 | |   `paidAmount` | `number` | | 已付金额 | |   `paymentMode` | `string` | | 支付模式（FULL/DEPOSIT） | |   `processStatus` | `string` | | 内部流程状态（字典：order_process_status） | |   `processStatusLabel` | `string` | | 内部流程状态标签（字典：order_process_status 翻译） | |   `productCoverUrl` | `string` | | 产品封面图URL | |   `productId` | `long` | | 产品ID | |   `productName` | `string` | | 产品名称 | |   `productType` | `string` | | 产品类型（CORE/ROUTE/CUSTOM/GROUP） | |   `status` | `string` | | 订单状态（PENDING_PAY/DEPOSIT_PAID/PAID/CONFIRMED/IN_PROGRESS/COMPLETED/CANCELLED） | |   `statusLabel` | `string` | | 订单状态标签 | |   `totalPrice` | `number` | | 总售价 | |   `tripDays` | `int` | | 行程天数 | |   `tripNights` | `int` | | 行程晚数 | |   `youngChildCount` | `int` | | 小童数 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/order/{orderId} **订单详情** 获取订单完整信息，包含产品快照、出行人列表、支付信息、合同状态等 **关联字典（BFF透传）**： - order_status：订单状态（显示） - product_type：产品类型（显示） - contract_status：合同状态（显示） **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `orderId` | `integer` | | 订单ID | **响应** `统一响应结果«订单详情»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `订单详情` | | 响应数据 | |   `adultCount` | `int` | | 成人数 | |   `babyCount` | `int` | | 幼童数 | |   `balanceAmount` | `number` | | 尾款金额 | |   `balancePayMethod` | `string` | | 尾款支付方式: ONLINE=线上 OFFLINE=线下 | |   `balanceProofUrl` | `string` | | 尾款凭证URL | |   `cancelReason` | `string` | | 取消原因 | |   `cancelledAt` | `string` | | 取消时间 | |   `checklistConfirmed` | `boolean` | | 清单确认状态 | |   `childCount` | `int` | | 儿童数 | |   `completedAt` | `string` | | 完成时间 | |   `confirmedAt` | `string` | | 确认时间 | |   `contactName` | `string` | | 联系人姓名 | |   `contactPhone` | `string` | | 联系人电话 | |   `contracts` | `Map«string,object»[]` | | 合同列表（含signUrl/fileUrl/status等） | |   `createTime` | `string` | | 创建时间 | |   `creatorAdminId` | `long` | | 创建人管理员ID | |   `creatorName` | `string` | | 创建人姓名 | |   `customizerId` | `long` | | 定制师ID | |   `customizerName` | `string` | | 定制师姓名 | |   `departureDate` | `string` | | 出发日期 | |   `depositAmount` | `number` | | 定金金额 | |   `depositRatio` | `int` | | 定金比例 | |   `discountAmount` | `number` | | 优惠金额 | |   `discountReason` | `string` | | 优惠原因 | |   `discounts` | `Map«string,object»[]` | | 优惠列表 | |   `expiryMinutes` | `int` | | 支付时限（分钟） | |   `expiryTime` | `string` | | 支付截止时间 | |   `hotelAssignments` | `string` | | 酒店分配信息JSON | |   `insurances` | `Map«string,object»[]` | | 保险订单列表（含productName/extPolicyNo/status/startDate/endDate等） | |   `mchId` | `string` | | 商户号 | |   `orderId` | `long` | | 订单ID | |   `orderNo` | `string` | | 订单编号 | |   `paidAmount` | `number` | | 已付金额 | |   `paidAt` | `string` | | 支付时间 | |   `payMethodLabel` | `string` | | 支付方式标签（如：微信支付、定金微信+尾款线下） | |   `paymentMode` | `string` | | 支付模式（FULL/DEPOSIT） | |   `processStatus` | `string` | | 内部流程状态 | |   `processStatusLabel` | `string` | | 内部流程状态标签 | |   `productCoverUrl` | `string` | | 产品封面图URL | |   `productId` | `long` | | 产品ID | |   `productName` | `string` | | 产品名称 | |   `productSnapshot` | `string` | | 产品快照JSON | |   `productType` | `string` | | 产品类型（CORE/ROUTE/CUSTOM/GROUP） | |   `readyAt` | `string` | | 就绪时间 | |   `refundAmount` | `number` | | 退款金额 | |   `remark` | `string` | | 备注 | |   `returnDate` | `string` | | 返程日期（出发日期 + 行程天数 - 1） | |   `reviewed` | `boolean` | | 是否已评价 | |   `roomInfo` | `string` | | 房间信息 | |   `status` | `string` | | 订单状态（PENDING_PAY/DEPOSIT_PAID/PAID/CONFIRMED/IN_PROGRESS/COMPLETED/CANCELLED） | |   `statusLabel` | `string` | | 订单状态标签 | |   `timeline` | `Map«string,object»[]` | | 时间线列表 | |   `todos` | `Map«string,object»[]` | | 待办列表 | |   `totalPrice` | `number` | | 总售价 | |   `travelers` | `Map«string,object»[]` | | 出行人列表 | |   `tripDays` | `int` | | 行程天数 | |   `tripNights` | `int` | | 行程晚数 | |   `unlockRequestedAt` | `string` | | 解锁请求时间 | |   `userId` | `long` | | 用户ID | |   `vehicleInfo` | `string` | | 车辆信息 | |   `youngChildCount` | `int` | | 小童数 | | `message` | `string` | | 响应消息 | --- ### `POST` /mp/order/{orderId}/approve-unlock **同意解锁订单** 用户同意管理员的修改请求，解除订单锁定状态，允许管理员继续修改订单 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `orderId` | `integer` | | 订单ID | **响应** `统一响应结果«Void»` --- ### `POST` /mp/order/{orderId}/cancel **取消订单** 取消规则：仅PENDING_PAY/DEPOSIT_PAID状态可用户取消，取消后不可恢复 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `orderId` | `integer` | | 订单ID | **请求体** `用户取消订单请求` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `reason` | `string` | | 取消原因 | **响应** `统一响应结果«Void»` --- ### `PUT` /mp/order/{orderId}/edit **修改订单** 用户可修改出发日期和出行人。仅待支付/已付定金/已支付/已确认/待付尾款/待出发状态可修改，清单已确认的订单不允许修改。修改后重走内部流程 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `orderId` | `integer` | | 订单ID | **请求体** `修改订单请求` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `departureDate` | `string` | | 出发日期 | | `travelers` | `出行人信息_1[]` | | 出行人列表（提供则替换全部出行人） | |   `birthday` | `string` | | 出生日期 | |   `email` | `string` | | 电子邮箱 | |   `emergencyContact` | `string` | | 紧急联系人 | |   `emergencyPhone` | `string` | | 紧急联系电话 | |   `gender` | `int` | | 性别 | |   `idCardNo` | `string` | | 证件号码 | |   `idCardType` | `string` | | 证件类型 | |   `name` | `string` | 是 | 出行人姓名 | |   `nationality` | `string` | | 国籍 | |   `phone` | `string` | | 手机号 | |   `travelerType` | `string` | | 出行人类型 | **响应** `统一响应结果«订单详情»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `订单详情` | | 响应数据 | |   `adultCount` | `int` | | 成人数 | |   `babyCount` | `int` | | 幼童数 | |   `balanceAmount` | `number` | | 尾款金额 | |   `balancePayMethod` | `string` | | 尾款支付方式: ONLINE=线上 OFFLINE=线下 | |   `balanceProofUrl` | `string` | | 尾款凭证URL | |   `cancelReason` | `string` | | 取消原因 | |   `cancelledAt` | `string` | | 取消时间 | |   `checklistConfirmed` | `boolean` | | 清单确认状态 | |   `childCount` | `int` | | 儿童数 | |   `completedAt` | `string` | | 完成时间 | |   `confirmedAt` | `string` | | 确认时间 | |   `contactName` | `string` | | 联系人姓名 | |   `contactPhone` | `string` | | 联系人电话 | |   `contracts` | `Map«string,object»[]` | | 合同列表（含signUrl/fileUrl/status等） | |   `createTime` | `string` | | 创建时间 | |   `creatorAdminId` | `long` | | 创建人管理员ID | |   `creatorName` | `string` | | 创建人姓名 | |   `customizerId` | `long` | | 定制师ID | |   `customizerName` | `string` | | 定制师姓名 | |   `departureDate` | `string` | | 出发日期 | |   `depositAmount` | `number` | | 定金金额 | |   `depositRatio` | `int` | | 定金比例 | |   `discountAmount` | `number` | | 优惠金额 | |   `discountReason` | `string` | | 优惠原因 | |   `discounts` | `Map«string,object»[]` | | 优惠列表 | |   `expiryMinutes` | `int` | | 支付时限（分钟） | |   `expiryTime` | `string` | | 支付截止时间 | |   `hotelAssignments` | `string` | | 酒店分配信息JSON | |   `insurances` | `Map«string,object»[]` | | 保险订单列表（含productName/extPolicyNo/status/startDate/endDate等） | |   `mchId` | `string` | | 商户号 | |   `orderId` | `long` | | 订单ID | |   `orderNo` | `string` | | 订单编号 | |   `paidAmount` | `number` | | 已付金额 | |   `paidAt` | `string` | | 支付时间 | |   `payMethodLabel` | `string` | | 支付方式标签（如：微信支付、定金微信+尾款线下） | |   `paymentMode` | `string` | | 支付模式（FULL/DEPOSIT） | |   `processStatus` | `string` | | 内部流程状态 | |   `processStatusLabel` | `string` | | 内部流程状态标签 | |   `productCoverUrl` | `string` | | 产品封面图URL | |   `productId` | `long` | | 产品ID | |   `productName` | `string` | | 产品名称 | |   `productSnapshot` | `string` | | 产品快照JSON | |   `productType` | `string` | | 产品类型（CORE/ROUTE/CUSTOM/GROUP） | |   `readyAt` | `string` | | 就绪时间 | |   `refundAmount` | `number` | | 退款金额 | |   `remark` | `string` | | 备注 | |   `returnDate` | `string` | | 返程日期（出发日期 + 行程天数 - 1） | |   `reviewed` | `boolean` | | 是否已评价 | |   `roomInfo` | `string` | | 房间信息 | |   `status` | `string` | | 订单状态（PENDING_PAY/DEPOSIT_PAID/PAID/CONFIRMED/IN_PROGRESS/COMPLETED/CANCELLED） | |   `statusLabel` | `string` | | 订单状态标签 | |   `timeline` | `Map«string,object»[]` | | 时间线列表 | |   `todos` | `Map«string,object»[]` | | 待办列表 | |   `totalPrice` | `number` | | 总售价 | |   `travelers` | `Map«string,object»[]` | | 出行人列表 | |   `tripDays` | `int` | | 行程天数 | |   `tripNights` | `int` | | 行程晚数 | |   `unlockRequestedAt` | `string` | | 解锁请求时间 | |   `userId` | `long` | | 用户ID | |   `vehicleInfo` | `string` | | 车辆信息 | |   `youngChildCount` | `int` | | 小童数 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/order/{orderId}/resources **订单资源详情（按分类）** 解析产品快照，提取资源详情按分类返回 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `orderId` | `integer` | | 订单ID | **响应** `统一响应结果«Map«string,List«Map«string,object»»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ## C端 - 评价接口 ### `POST` /mp/review/create **创建评价** 评价流程：订单完成后 → 查询可评价目标列表 → 对每个目标(酒店/景区/活动等)提交评价 → 自动内容审核 → 审核通过后公开展示 **关联字典（BFF透传）**： - review_status：评价审核状态（返回字段） - rating_level：评价等级（返回字段） **请求体** `创建评价请求` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `content` | `string` | 是 | 评价内容(10-500字) | | `images` | `评价图片项[]` | | 评价图片列表（最多9张） | |   `fileId` | `long` | | 文件ID | |   `imageUrl` | `string` | 是 | 图片URL | | `orderId` | `long` | 是 | 订单ID | | `ratings` | `object` | 是 | 评分数据（key为评分类别字典的dictValue，value为1-5整数）。先调用 GET /mp/review/rating-categories 获取评分维度，required=true的必填。示例: {"ratingItinerary":5,"ratingAccommodation":4,"ratingDriver":5,"ratingDining":4,"ratingOverall":5} | | `videos` | `评价视频项[]` | | 评价视频列表（最多3个） | |   `coverUrl` | `string` | | 视频封面URL | |   `duration` | `int` | | 视频时长(秒) | |   `fileId` | `long` | | 文件ID | |   `videoUrl` | `string` | 是 | 视频URL | **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/review/featured **精选评价列表(公开)** 无需登录，返回精选评价数组，用于评价浏览页 **关联字典（BFF透传）**： - rating_level：评价等级（显示） **查询参数** | 参数 | 类型 | 必填 | 说明 | 示例 | | --- | --- | --- | --- | --- | | `limit` | `integer(int32)` | | 数量限制 | | **响应** `统一响应结果«List«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `Map«string,object»[]` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/review/my **我的评价列表** **关联字典（BFF透传）**： - review_status：评价审核状态（显示） - rating_level：评价等级（显示） **查询参数** | 参数 | 类型 | 必填 | 说明 | 示例 | | --- | --- | --- | --- | --- | | `page` | `integer(int32)` | | 页码 | | | `pageSize` | `integer(int32)` | | 每页条数 | | **响应** `统一响应结果«分页结果«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `分页结果«Map«string,object»»` | | 响应数据 | |   `page` | `int` | | 当前页码 | |   `pageSize` | `int` | | 每页条数 | |   `records` | `Map«string,object»[]` | | 数据列表 | |   `total` | `int` | | 总记录数 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/review/order/{orderId}/reviewable-targets **订单可评价目标列表** 返回订单中可评价的资源目标列表（景区/酒店/活动等），用于评价页面展示可评价项。已评价的目标不会重复出现。 **权限**：需登录。 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `orderId` | `integer` | | 订单ID | **响应** `统一响应结果«List«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `Map«string,object»[]` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/review/order/{orderId}/reviewed **检查订单是否已评价** 检查指定订单是否已提交评价，用于订单详情页决定是否显示'去评价'按钮。 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `orderId` | `integer` | | 订单ID | **响应** `统一响应结果«boolean»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `boolean` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/review/product/{productId} **按产品ID查看评价列表** 返回评价列表+统计数据，支持好中差评/有图/有视频筛选 **关联字典（BFF透传）**： - rating_level：评价等级（筛选+显示） **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `productId` | `integer` | | 产品ID | **查询参数** | 参数 | 类型 | 必填 | 说明 | 示例 | | --- | --- | --- | --- | --- | | `hasImage` | `boolean` | | 是否有图片 | | | `hasVideo` | `boolean` | | 是否有视频 | | | `page` | `integer(int32)` | | 页码 | | | `pageSize` | `integer(int32)` | | 每页条数 | | | `ratingLevel` | `string` | | 评价等级: GOOD/MEDIUM/BAD | | **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/review/product/{productId}/highlights **产品精选评价(最高评分+最高点赞+统计)** 用于产品详情页评价区域展示 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `productId` | `integer` | | 产品ID | **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/review/rating-categories **评分类别列表** 从字典读取评价时需要填写的评分维度，前端据此渲染评分组件。字典类型: review_rating_category，remark字段包含扩展JSON(required/min/max) **响应** `统一响应结果«List«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `Map«string,object»[]` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/review/search **关键词搜索评价(公开)** 按关键词搜索已通过的评价内容，支持按目标类型和目标ID筛选 **关联字典（BFF透传）**： - rating_level：评价等级（显示） **查询参数** | 参数 | 类型 | 必填 | 说明 | 示例 | | --- | --- | --- | --- | --- | | `keyword` | `string` | 是 | 搜索关键词 | | | `page` | `integer(int32)` | | 页码 | | | `pageSize` | `integer(int32)` | | 每页条数 | | | `targetId` | `integer(int64)` | | 目标ID(可选) | | | `targetType` | `string` | | 目标类型(可选): PRODUCT/SCENIC_SPOT/ACTIVITY/HOTEL等 | | **响应** `统一响应结果«分页结果«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `分页结果«Map«string,object»»` | | 响应数据 | |   `page` | `int` | | 当前页码 | |   `pageSize` | `int` | | 每页条数 | |   `records` | `Map«string,object»[]` | | 数据列表 | |   `total` | `int` | | 总记录数 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/review/stats **评价统计(平均分、数量)** 获取指定目标的评价统计数据（平均评分、总评价数等），用于详情页评价区域展示。产品showReview关闭时返回空统计。 **查询参数** | 参数 | 类型 | 必填 | 说明 | 示例 | | --- | --- | --- | --- | --- | | `targetId` | `integer(int64)` | | 目标ID | | | `targetType` | `string` | | 目标类型 | | **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/review/target **某目标的已通过评价(公开)** **关联字典（BFF透传）**： - rating_level：评价等级（筛选+显示） **查询参数** | 参数 | 类型 | 必填 | 说明 | 示例 | | --- | --- | --- | --- | --- | | `hasImage` | `boolean` | | 是否有图片 | | | `hasVideo` | `boolean` | | 是否有视频 | | | `page` | `integer(int32)` | | 页码 | | | `pageSize` | `integer(int32)` | | 每页条数 | | | `ratingLevel` | `string` | | 评价等级: GOOD/MEDIUM/BAD | | | `targetId` | `integer(int64)` | | 目标ID | | | `targetType` | `string` | | 目标类型 | | **响应** `统一响应结果«分页结果«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `分页结果«Map«string,object»»` | | 响应数据 | |   `page` | `int` | | 当前页码 | |   `pageSize` | `int` | | 每页条数 | |   `records` | `Map«string,object»[]` | | 数据列表 | |   `total` | `int` | | 总记录数 | | `message` | `string` | | 响应消息 | --- ### `POST` /mp/review/{reviewId}/like **点赞/取消点赞评价** 对评价进行点赞或取消点赞操作，返回当前点赞状态和点赞总数。 **权限**：需登录。 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `reviewId` | `integer` | | 评价ID | **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/review/{reviewId}/like/check **检查是否已点赞** 检查当前用户是否已点赞指定评价，用于评价列表/详情的点赞按钮状态展示。 **权限**：需登录。 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `reviewId` | `integer` | | 评价ID | **响应** `统一响应结果«boolean»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `boolean` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ## C端 - 足迹接口 ### `GET` /mp/user/footprint **足迹列表（含资源摘要）** 分页查询浏览足迹列表，聚合层会补充每条足迹对应资源的摘要信息（名称、封面图等）。支持按资源类型筛选，按浏览时间倒序。 **权限**：需登录。 **查询参数** | 参数 | 类型 | 必填 | 说明 | 示例 | | --- | --- | --- | --- | --- | | `page` | `integer(int32)` | | 页码 | | | `pageSize` | `integer(int32)` | | 每页条数 | | | `resourceType` | `string` | | 资源类型筛选：PRODUCT/SCENIC/RESTAURANT/ACTIVITY | | **响应** `统一响应结果«分页结果«足迹列表项（含资源摘要）»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `分页结果«足迹列表项（含资源摘要）»` | | 响应数据 | |   `page` | `int` | | 当前页码 | |   `pageSize` | `int` | | 每页条数 | |   `records` | `足迹列表项（含资源摘要）[]` | | 数据列表 | |     `coverUrl` | `string` | | 封面图URL | |     `footprintId` | `string` | | 足迹记录ID | |     `name` | `string` | | 资源名称 | |     `resourceId` | `string` | | 资源ID | |     `resourceType` | `string` | | 资源类型：PRODUCT/SCENIC/RESTAURANT/ACTIVITY | |     `tags` | `string[]` | | 标签列表 | |     `visitTime` | `string` | | 浏览时间 | |   `total` | `int` | | 总记录数 | | `message` | `string` | | 响应消息 | --- ### `POST` /mp/user/footprint **记录足迹** 记录用户浏览资源的足迹，同一资源重复浏览会更新浏览时间而非新增记录 **请求体** `添加足迹请求` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `resourceId` | `string` | 是 | 资源ID | | `resourceType` | `string` | 是 | 资源类型: PRODUCT/SCENIC/RESTAURANT/ACTIVITY | **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `DELETE` /mp/user/footprint/batch **批量删除足迹** 批量删除多条浏览足迹记录，传入足迹ID列表。用于足迹管理页面的批量清理。 **权限**：需登录，仅能删除自己的足迹。 **请求体** `long[]` **响应** `统一响应结果«Void»` --- ### `DELETE` /mp/user/footprint/{id} **删除足迹** 删除单条浏览足迹记录。 **权限**：需登录，仅能删除自己的足迹。 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `id` | `integer` | | 足迹ID | **响应** `统一响应结果«Void»` --- ## C端 - 轮播图接口 ### `GET` /mp/banner/active **获取当前生效的轮播图列表** 返回当前处于有效期内的轮播图，按排序值排列。用于小程序首页顶部轮播展示，透传自user-service。 **响应** `统一响应结果«List«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `Map«string,object»[]` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ## C端 - 退款接口 ### `GET` /mp/order/refund-reasons **退款原因列表** 返回系统预设的退款原因选项，用于退款申请页面的原因选择 **响应** `统一响应结果«List«退款原因»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `退款原因[]` | | 响应数据 | |   `category` | `string` | | 分类: GENERAL(通用)/PRODUCT(产品问题)/SERVICE(服务问题) | |   `enabled` | `boolean` | | 是否启用 | |   `reasonId` | `long` | | 原因ID | |   `reasonText` | `string` | | 原因描述 | |   `sortOrder` | `int` | | 排序序号 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/order/refund/{applicationId} **退款申请详情** 获取退款申请的完整信息，包含审核状态、退款金额、退款进度和操作记录 **关联字典（BFF透传）**： - order_status：订单状态（显示） - payment_status：支付/退款状态（显示） **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `applicationId` | `integer` | | 退款申请ID | **响应** `统一响应结果«退款申请详情»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `退款申请详情` | | 响应数据 | |   `actualAmount` | `number` | | 实际退款金额（审核后确定） | |   `appealAmount` | `number` | | 申诉退款金额 | |   `appealReason` | `string` | | 申诉原因 | |   `appealStatus` | `int` | | 申诉状态: 1-处理中, 2-通过, 3-驳回 | |   `appealStatusLabel` | `string` | | 申诉状态中文标签 | |   `appealedAt` | `string` | | 申诉时间 | |   `applicantId` | `long` | | 申请人ID | |   `applicantName` | `string` | | 申请人姓名 | |   `applicantType` | `string` | | 申请人类型: USER(用户)/ADMIN(管理员) | |   `applicationId` | `long` | | 退款申请ID | |   `approvalNo` | `string` | | 审批编号（企微OA审批编号） | |   `autoRefundDeadline` | `string` | | 自动退款截止时间 | |   `calculatedAmount` | `number` | | 计算退款金额 | |   `createTime` | `string` | | 创建时间 | |   `daysBeforeDept` | `int` | | 距出发天数 | |   `departureDate` | `string` | | 出发日期 | |   `orderId` | `long` | | 订单ID | |   `orderNo` | `string` | | 订单号 | |   `paidAmount` | `number` | | 已付金额 | |   `policyId` | `long` | | 退款政策ID | |   `policyName` | `string` | | 退款政策名称 | |   `productName` | `string` | | 产品名称 | |   `reasonDetail` | `string` | | 补充说明 | |   `reasonId` | `long` | | 退款原因ID | |   `reasonText` | `string` | | 退款原因 | |   `refundRatio` | `int` | | 退款比例（百分比） | |   `refundType` | `string` | | 退款类型: DEPOSIT(定金)/BALANCE(尾款)/FULL(全款) | |   `refundTypeLabel` | `string` | | 退款类型中文标签 | |   `refundedAt` | `string` | | 退款完成时间 | |   `reviewAdminId` | `long` | | 审批管理员ID | |   `reviewAdminName` | `string` | | 审批管理员姓名 | |   `reviewRemark` | `string` | | 审批备注 | |   `reviewedAt` | `string` | | 审批时间 | |   `status` | `string` | | 退款状态: PENDING(待审核)/APPROVED(已通过)/REJECTED(已拒绝)/REFUNDING(退款中)/REFUNDED(已退款)/CANCELLED(已撤回)/APPEALING(申诉中)/APPEAL_APPROVED(申诉通过)/APPEAL_REJECTED(申诉驳回) | |   `statusLabel` | `string` | | 退款状态中文标签 | |   `updateTime` | `string` | | 更新时间 | | `message` | `string` | | 响应消息 | --- ### `POST` /mp/order/refund/{applicationId}/appeal **发起申诉** 退款被拒绝后，用户可在3天内发起一次申诉，由上级管理员重新审核 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `applicationId` | `integer` | | 退款申请ID | **请求体** `退款申诉请求` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `appealReason` | `string` | 是 | 申诉原因 | | `evidence` | `string[]` | | 申诉凭证图片URL列表 | **响应** `统一响应结果«退款申请详情»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `退款申请详情` | | 响应数据 | |   `actualAmount` | `number` | | 实际退款金额（审核后确定） | |   `appealAmount` | `number` | | 申诉退款金额 | |   `appealReason` | `string` | | 申诉原因 | |   `appealStatus` | `int` | | 申诉状态: 1-处理中, 2-通过, 3-驳回 | |   `appealStatusLabel` | `string` | | 申诉状态中文标签 | |   `appealedAt` | `string` | | 申诉时间 | |   `applicantId` | `long` | | 申请人ID | |   `applicantName` | `string` | | 申请人姓名 | |   `applicantType` | `string` | | 申请人类型: USER(用户)/ADMIN(管理员) | |   `applicationId` | `long` | | 退款申请ID | |   `approvalNo` | `string` | | 审批编号（企微OA审批编号） | |   `autoRefundDeadline` | `string` | | 自动退款截止时间 | |   `calculatedAmount` | `number` | | 计算退款金额 | |   `createTime` | `string` | | 创建时间 | |   `daysBeforeDept` | `int` | | 距出发天数 | |   `departureDate` | `string` | | 出发日期 | |   `orderId` | `long` | | 订单ID | |   `orderNo` | `string` | | 订单号 | |   `paidAmount` | `number` | | 已付金额 | |   `policyId` | `long` | | 退款政策ID | |   `policyName` | `string` | | 退款政策名称 | |   `productName` | `string` | | 产品名称 | |   `reasonDetail` | `string` | | 补充说明 | |   `reasonId` | `long` | | 退款原因ID | |   `reasonText` | `string` | | 退款原因 | |   `refundRatio` | `int` | | 退款比例（百分比） | |   `refundType` | `string` | | 退款类型: DEPOSIT(定金)/BALANCE(尾款)/FULL(全款) | |   `refundTypeLabel` | `string` | | 退款类型中文标签 | |   `refundedAt` | `string` | | 退款完成时间 | |   `reviewAdminId` | `long` | | 审批管理员ID | |   `reviewAdminName` | `string` | | 审批管理员姓名 | |   `reviewRemark` | `string` | | 审批备注 | |   `reviewedAt` | `string` | | 审批时间 | |   `status` | `string` | | 退款状态: PENDING(待审核)/APPROVED(已通过)/REJECTED(已拒绝)/REFUNDING(退款中)/REFUNDED(已退款)/CANCELLED(已撤回)/APPEALING(申诉中)/APPEAL_APPROVED(申诉通过)/APPEAL_REJECTED(申诉驳回) | |   `statusLabel` | `string` | | 退款状态中文标签 | |   `updateTime` | `string` | | 更新时间 | | `message` | `string` | | 响应消息 | --- ### `POST` /mp/order/refund/{applicationId}/cancel **撤回退款申请** 仅PENDING状态的退款申请可撤回，撤回后订单恢复到原状态 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `applicationId` | `integer` | | 退款申请ID | **响应** `统一响应结果«Void»` --- ### `POST` /mp/order/{orderId}/refund **提交退款申请** 退款流程：获取退款预览 → 选择退款原因 → 提交退款申请 → 管理员审核 → 审核通过后自动退款到原支付方式 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `orderId` | `integer` | | 订单ID | **请求体** `退款申请请求` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `images` | `string[]` | | 退款凭证图片URL列表 | | `reasonDetail` | `string` | | 退款补充说明 | | `reasonId` | `string` | | 退款原因ID（已废弃，改用字典） | | `reasonText` | `string` | 是 | 退款原因文本 | | `reasonValue` | `string` | | 退款原因字典值 | | `refundType` | `string` | 是 | 退款类型（FULL/DEPOSIT/BALANCE） | **响应** `统一响应结果«退款申请详情»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `退款申请详情` | | 响应数据 | |   `actualAmount` | `number` | | 实际退款金额（审核后确定） | |   `appealAmount` | `number` | | 申诉退款金额 | |   `appealReason` | `string` | | 申诉原因 | |   `appealStatus` | `int` | | 申诉状态: 1-处理中, 2-通过, 3-驳回 | |   `appealStatusLabel` | `string` | | 申诉状态中文标签 | |   `appealedAt` | `string` | | 申诉时间 | |   `applicantId` | `long` | | 申请人ID | |   `applicantName` | `string` | | 申请人姓名 | |   `applicantType` | `string` | | 申请人类型: USER(用户)/ADMIN(管理员) | |   `applicationId` | `long` | | 退款申请ID | |   `approvalNo` | `string` | | 审批编号（企微OA审批编号） | |   `autoRefundDeadline` | `string` | | 自动退款截止时间 | |   `calculatedAmount` | `number` | | 计算退款金额 | |   `createTime` | `string` | | 创建时间 | |   `daysBeforeDept` | `int` | | 距出发天数 | |   `departureDate` | `string` | | 出发日期 | |   `orderId` | `long` | | 订单ID | |   `orderNo` | `string` | | 订单号 | |   `paidAmount` | `number` | | 已付金额 | |   `policyId` | `long` | | 退款政策ID | |   `policyName` | `string` | | 退款政策名称 | |   `productName` | `string` | | 产品名称 | |   `reasonDetail` | `string` | | 补充说明 | |   `reasonId` | `long` | | 退款原因ID | |   `reasonText` | `string` | | 退款原因 | |   `refundRatio` | `int` | | 退款比例（百分比） | |   `refundType` | `string` | | 退款类型: DEPOSIT(定金)/BALANCE(尾款)/FULL(全款) | |   `refundTypeLabel` | `string` | | 退款类型中文标签 | |   `refundedAt` | `string` | | 退款完成时间 | |   `reviewAdminId` | `long` | | 审批管理员ID | |   `reviewAdminName` | `string` | | 审批管理员姓名 | |   `reviewRemark` | `string` | | 审批备注 | |   `reviewedAt` | `string` | | 审批时间 | |   `status` | `string` | | 退款状态: PENDING(待审核)/APPROVED(已通过)/REJECTED(已拒绝)/REFUNDING(退款中)/REFUNDED(已退款)/CANCELLED(已撤回)/APPEALING(申诉中)/APPEAL_APPROVED(申诉通过)/APPEAL_REJECTED(申诉驳回) | |   `statusLabel` | `string` | | 退款状态中文标签 | |   `updateTime` | `string` | | 更新时间 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/order/{orderId}/refund-detail **根据订单ID获取最新退款详情** 查询订单关联的最新一条退款申请详情，无退款记录时返回null **关联字典（BFF透传）**： - order_status：订单状态（显示） - payment_status：支付/退款状态（显示） **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `orderId` | `string` | | 订单ID | **响应** `统一响应结果«退款申请详情»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `退款申请详情` | | 响应数据 | |   `actualAmount` | `number` | | 实际退款金额（审核后确定） | |   `appealAmount` | `number` | | 申诉退款金额 | |   `appealReason` | `string` | | 申诉原因 | |   `appealStatus` | `int` | | 申诉状态: 1-处理中, 2-通过, 3-驳回 | |   `appealStatusLabel` | `string` | | 申诉状态中文标签 | |   `appealedAt` | `string` | | 申诉时间 | |   `applicantId` | `long` | | 申请人ID | |   `applicantName` | `string` | | 申请人姓名 | |   `applicantType` | `string` | | 申请人类型: USER(用户)/ADMIN(管理员) | |   `applicationId` | `long` | | 退款申请ID | |   `approvalNo` | `string` | | 审批编号（企微OA审批编号） | |   `autoRefundDeadline` | `string` | | 自动退款截止时间 | |   `calculatedAmount` | `number` | | 计算退款金额 | |   `createTime` | `string` | | 创建时间 | |   `daysBeforeDept` | `int` | | 距出发天数 | |   `departureDate` | `string` | | 出发日期 | |   `orderId` | `long` | | 订单ID | |   `orderNo` | `string` | | 订单号 | |   `paidAmount` | `number` | | 已付金额 | |   `policyId` | `long` | | 退款政策ID | |   `policyName` | `string` | | 退款政策名称 | |   `productName` | `string` | | 产品名称 | |   `reasonDetail` | `string` | | 补充说明 | |   `reasonId` | `long` | | 退款原因ID | |   `reasonText` | `string` | | 退款原因 | |   `refundRatio` | `int` | | 退款比例（百分比） | |   `refundType` | `string` | | 退款类型: DEPOSIT(定金)/BALANCE(尾款)/FULL(全款) | |   `refundTypeLabel` | `string` | | 退款类型中文标签 | |   `refundedAt` | `string` | | 退款完成时间 | |   `reviewAdminId` | `long` | | 审批管理员ID | |   `reviewAdminName` | `string` | | 审批管理员姓名 | |   `reviewRemark` | `string` | | 审批备注 | |   `reviewedAt` | `string` | | 审批时间 | |   `status` | `string` | | 退款状态: PENDING(待审核)/APPROVED(已通过)/REJECTED(已拒绝)/REFUNDING(退款中)/REFUNDED(已退款)/CANCELLED(已撤回)/APPEALING(申诉中)/APPEAL_APPROVED(申诉通过)/APPEAL_REJECTED(申诉驳回) | |   `statusLabel` | `string` | | 退款状态中文标签 | |   `updateTime` | `string` | | 更新时间 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/order/{orderId}/refund-preview **退款金额预览** 根据退款政策和订单出发日期计算可退金额，展示退款比例和扣除金额明细 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `orderId` | `integer` | | 订单ID | **响应** `统一响应结果«退款预览»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `退款预览` | | 响应数据 | |   `calculatedAmount` | `number` | | 计算退款金额 | |   `daysBeforeDept` | `int` | | 距出发天数 | |   `departureDate` | `string` | | 出发日期 | |   `message` | `string` | | 提示信息 | |   `orderId` | `long` | | 订单ID | |   `orderNo` | `string` | | 订单号 | |   `paidAmount` | `number` | | 已付金额 | |   `policyId` | `long` | | 匹配的退款政策ID | |   `policyName` | `string` | | 匹配的退款政策名称 | |   `refundRatio` | `int` | | 退款比例（百分比） | |   `refundType` | `string` | | 退款类型: DEPOSIT/BALANCE/FULL | |   `refundable` | `boolean` | | 是否可退款 | |   `rules` | `退款规则项[]` | | 退款规则列表（按天数降序） | |     `matched` | `boolean` | | 是否当前命中此规则 | |     `minDays` | `int` | | 最低天数 | |     `refundRatio` | `int` | | 退款比例（百分比） | | `message` | `string` | | 响应消息 | --- ## C端 - 通用点赞 ### `POST` /mp/like/{targetType}/batch-check **批量检查点赞状态** 批量检查当前用户是否已对多个目标点赞，返回已点赞的目标ID列表。用于列表页批量展示点赞状态。 **权限**：需登录。 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `targetType` | `string` | | 目标类型 | **请求体** `string[]` **响应** `统一响应结果«List«string»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `string[]` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `POST` /mp/like/{targetType}/{targetId} **切换点赞** 点赞/取消点赞，返回 {liked: true/false, likeCount: 点赞数} **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `targetId` | `integer` | | 目标ID | | `targetType` | `string` | | 目标类型: REVIEW/EXPLORE/GUIDE等 | **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/like/{targetType}/{targetId}/check **检查是否已点赞** 检查当前用户是否已对指定目标点赞，用于前端点赞按钮状态展示。 **权限**：需登录。 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `targetId` | `integer` | | 目标ID | | `targetType` | `string` | | 目标类型 | **响应** `统一响应结果«boolean»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `boolean` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ## C端 - 酒店接口 ### `GET` /mp/hotel/list **酒店列表** 分页查询已上架的酒店列表，支持按关键词、城市、星级筛选。聚合层透传resource-service的酒店数据。 **查询参数** | 参数 | 类型 | 必填 | 说明 | 示例 | | --- | --- | --- | --- | --- | | `city` | `string` | | 城市 | | | `keyword` | `string` | | 关键词 | | | `page` | `integer(int32)` | | 页码 | | | `pageSize` | `integer(int32)` | | 每页条数 | | | `starLevel` | `integer(int32)` | | 星级 | | **响应** `统一响应结果«分页结果«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `分页结果«Map«string,object»»` | | 响应数据 | |   `page` | `int` | | 当前页码 | |   `pageSize` | `int` | | 每页条数 | |   `records` | `Map«string,object»[]` | | 数据列表 | |   `total` | `int` | | 总记录数 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/hotel/{hotelId} **酒店详情** 获取酒店完整信息（含房型列表、图文详情、价格等），自动注入静态地图图片URL用于详情页地图展示。 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `hotelId` | `integer` | | 酒店ID | **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ## C端 - 餐厅接口 ### `GET` /mp/restaurant/list **餐厅列表** 分页查询已上架的餐厅列表，支持按关键词和城市筛选。聚合层透传resource-service的餐厅数据。 **查询参数** | 参数 | 类型 | 必填 | 说明 | 示例 | | --- | --- | --- | --- | --- | | `city` | `string` | | 城市 | | | `keyword` | `string` | | 关键词 | | | `page` | `integer(int32)` | | 页码 | | | `pageSize` | `integer(int32)` | | 每页条数 | | **响应** `统一响应结果«分页结果«Map«string,object»»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `分页结果«Map«string,object»»` | | 响应数据 | |   `page` | `int` | | 当前页码 | |   `pageSize` | `int` | | 每页条数 | |   `records` | `Map«string,object»[]` | | 数据列表 | |   `total` | `int` | | 总记录数 | | `message` | `string` | | 响应消息 | --- ### `GET` /mp/restaurant/{restaurantId} **餐厅详情** 获取餐厅完整信息（含菜品、图文详情等），自动注入静态地图图片URL用于详情页地图展示。 **路径参数** | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `restaurantId` | `integer` | | 餐厅ID | **响应** `统一响应结果«Map«string,object»»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `object` | | 响应数据 | | `message` | `string` | | 响应消息 | --- ## C端 - 首页接口 ### `GET` /mp/home **首页数据** 聚合流程：并行获取推荐产品列表+产品线列表+轮播图 → Redis缓存5分钟 → 返回聚合数据 **关联字典（BFF透传）**： - product_type：产品类型（产品卡片显示） - product_status：产品状态（透传自product-service） **响应** `统一响应结果«首页聚合数据»` | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `code` | `int` | | 状态码 | | `data` | `首页聚合数据` | | 响应数据 | |   `banners` | `Map«string,object»[]` | | 轮播图Banner列表 | |   `contactInfo` | `Map«string,object»[]` | | 联系我们列表 | |   `exploreTopics` | `Map«string,object»[]` | | 探索专题列表 | |   `featuredDesigner` | `object` | | 推荐定制师 | |   `featuredReviews` | `Map«string,object»[]` | | 首页精选评价列表 | |   `productLines` | `Map«string,object»[]` | | 产品线分类列表 | |   `recommendProducts` | `Map«string,object»[]` | | 推荐产品列表 | | `message` | `string` | | 响应消息 | ---