# 微信小程序 · 订单行李推荐接口

**日期**:2026-04-21
**影响**:**微信小程序** 订单详情行李推荐弹窗(原型 `zgNiD`)
**PR**:#1042(Closes #1041)

---

## 概述

订单详情页"行李推荐"弹窗独立查询接口。从产品快照中解析备品清单,按分类分组返回,附装备建议富文本。

> C 端展示已去除成本字段(`hasCost` / `unitPrice`),后端已过滤掉成本项(`hasCost=true`),仅返回给用户看的推荐行李。

---

## 接口

```
GET /mp/order/{orderId}/supplies-checklist
```

**鉴权**:Bearer token。
**缓存**:5 分钟。

### 入参

| 参数 | 位置 | 类型 | 必填 |
|---|---|---|---|
| orderId | Path | Long | ✅ |

### 出参 `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 | 排序(升序) |

### 响应示例

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "orderId": 20439,
    "categories": [
      {
        "category": "衣物",
        "items": [
          {"suppliesName":"冲锋衣","category":"衣物","quantity":1,"billingType":"PER_PERSON","sortOrder":1},
          {"suppliesName":"保暖内衣","category":"衣物","quantity":1,"billingType":"PER_PERSON","sortOrder":2}
        ]
      },
      {
        "category": "配件",
        "items": [
          {"suppliesName":"防晒霜","category":"配件","quantity":1,"billingType":"PER_QUANTITY","sortOrder":1},
          {"suppliesName":"墨镜","category":"配件","quantity":1,"billingType":"PER_PERSON","sortOrder":2}
        ]
      }
    ],
    "equipmentAdvice": "<p>呼伦贝尔 7 月早晚温差大,建议携带薄款冲锋衣。防晒需求高,墨镜 + 防晒霜必备。</p>"
  },
  "success": true
}
```

### 边界行为

- 订单不存在或无权限:500,`message` 含 `orderId`
- 产品快照无备品配置:`categories=[]`,`equipmentAdvice=null`
- 所有备品都是成本项:`categories=[]`(已过滤)

---

## 数据来源

字段从订单绑定产品的**产品快照**中解析得到,下单时刻的备品清单锁定,后续产品端备品变动不影响已下单订单。

---

## 关联字段(其他接口)

订单详情 `GET /mp/order/{orderId}` 的返回 VO(`MpOrderDetailVO`)本身也带 `supplies` 和 `equipmentAdvice` 字段,用于整单数据一次读取场景。本独立接口专用于弹窗按需拉取。

| 接口 | 字段 | 说明 |
|---|---|---|
| `GET /mp/order/{orderId}` | `supplies: List<OrderSuppliesVO>` | 订单备品(扁平列表,不分组) |
| `GET /mp/order/{orderId}` | `equipmentAdvice: String` | 装备建议富文本 |
| `GET /mp/order/{orderId}/supplies-checklist` | 见上文 | 按分类分组 + 装备建议,弹窗专用 |