hl-api-changelog/hl-mp-service.md

# 小程序聚合服务 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` |  | 响应消息 |

---