# C端「行李推荐弹窗」独立接口 — 2026-04-20

> **服务** hl-order-service-v2（端口 8094） + hl-mp-service（端口 8085）· **类型** feat · **关联** PR #1041 / #1042
> **前端调用路径**: 网关(8080) → hl-mp-service(8085) → hl-order-service-v2(8094)

---

## 一、新增接口（1 个）

### 🆕 `GET /mp/order/{orderId}/supplies-checklist` — 订单备品清单（行李推荐弹窗）

**功能**：对应小程序订单详情原型 `zgNiD` 行李推荐弹窗。从 `order_info.product_snapshot` 解析 `supplies`（按 `category` 分组，排除 `hasCost=true` 的成本项）+ `supplement.equipmentAdvice`（装备建议富文本）。

**请求参数**：

| 参数 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `orderId` | Path | `Long` | ✅ | 订单ID |

> `userId` 由 mp-service 从 token 中获取后透传给 order-service，前端不传。

**返回值** `Result<MpSuppliesChecklistRespVO>`：

| 字段 | 类型 | 必有 | 说明 |
| --- | --- | --- | --- |
| `orderId` | `Long` | ✅ | 订单 ID |
| `categories` | `List<MpSuppliesCategoryVO>` | ✅ | 备品清单按分类分组（无推荐时为空列表） |
| `equipmentAdvice` | `String` | 否 | 装备建议富文本（HTML，快照无值时为 null） |

**`MpSuppliesCategoryVO`**：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `category` | `String` | 分类名（如"衣物"、"配件"） |
| `items` | `List<MpSuppliesItemVO>` | 该分类下的备品列表 |

**`MpSuppliesItemVO`**：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `suppliesName` | `String` | 备品名称（如"防晒霜"） |
| `category` | `String` | 分类（与父级同） |
| `quantity` | `Integer` | 数量 |
| `billingType` | `String` | 计费方式（`PER_PERSON`=按人 / `PER_QUANTITY`=按件） |
| `sortOrder` | `Integer` | 排序 |

> ⚠️ 相比管理端 `OrderSuppliesVO`，C 端 VO 已去除 `hasCost`、`unitPrice` 等成本字段。

**请求示例**：

```
GET /mp/order/2043935542092980226/supplies-checklist
```

**响应示例**：

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "orderId": 2043935542092980226,
    "categories": [
      {
        "category": "衣物",
        "items": [
          { "suppliesName": "冲锋衣", "category": "衣物", "quantity": 1, "billingType": "PER_PERSON", "sortOrder": 1 },
          { "suppliesName": "速干裤", "category": "衣物", "quantity": 2, "billingType": "PER_PERSON", "sortOrder": 2 }
        ]
      },
      {
        "category": "配件",
        "items": [
          { "suppliesName": "防晒霜", "category": "配件", "quantity": 1, "billingType": "PER_QUANTITY", "sortOrder": 1 }
        ]
      }
    ],
    "equipmentAdvice": "<p>呼伦贝尔 7 月早晚温差大，建议携带薄款冲锋衣。</p>"
  }
}
```

**空推荐响应示例**（快照无 supplies 与 equipmentAdvice）：

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "orderId": 2043935542092980226,
    "categories": [],
    "equipmentAdvice": null
  }
}
```

---

## 二、mp-service BFF 转发

| 前端调用 | mp-service 转发到 |
| --- | --- |
| `GET /mp/order/{orderId}/supplies-checklist` | `GET /internal/mp/order/{orderId}/supplies-checklist` |

---

## 三、数据库变更

**无**。数据来自下单时固化的 `order_info.product_snapshot`。

---

## 四、错误码

HTTP 始终返回 200，错误码在 `Result.code` 中。

| code | 触发 | 说明 |
| --- | --- | --- |
| 200 | 正常 | 成功（快照缺失时 categories 为空列表，equipmentAdvice 为 null） |
| 400 | 订单不存在 | `BusinessException` |

---

## 五、关联

- PR: [wx/HL#1042](https://git.1814.love:8443/wx/HL/pulls/1042)
- 原型节点: `zgNiD` — 行李推荐弹窗
- 相关字段: `OrderDetailVO` 已同步新增 `supplies` / `equipmentAdvice` 字段，见 `2026-04-20_order-v2_order-detail-supplies-fields.md`