# 订单详情补产品封面字段 productCoverImg

- **变更类型**：修改接口
- **端类型**：管理后台
- **日期**：2026-06-19
- **Issue**：[#4025](https://git.1814.love:8443/wx/HL/issues/4025)
- **PR**：[#4026](https://git.1814.love:8443/wx/HL/pulls/4026)
- **后端负责人**：腰苏图

---

## 1. 接口背景

订单详情接口（`GET /v3/admin/order/{id}`）的 `main` 块此前不返回产品封面图，导致管理后台详情页无法展示封面，只能在订单列表页看到封面。本次补齐 `productCoverImg` 字段，与订单列表接口同名同义，前端可复用相同的图片渲染逻辑，无需额外适配。

---

## 2. 变更清单

| 序号 | 接口 | 变更点 | 变更类型 |
|------|------|--------|----------|
| 1 | `GET /v3/admin/order/{id}` | `data.main` 新增出参字段 `productCoverImg`（产品封面图 URL） | ✨ 新增字段 |

**入参无变化，无 DDL 变更。**

---

## 3. 接口详情

| 项目 | 说明 |
|------|------|
| **方法** | GET |
| **路径** | `/v3/admin/order/{id}` |
| **接口名** | 订单详情（9 Tab 聚合） |
| **认证** | Bearer JWT（管理后台 Token） |
| **幂等性** | 查询接口，天然幂等 |
| **限流** | 无特殊限流 |
| **返回结构** | `Result<OrderDetailRespVO>`，本次仅变更 `data.main` 块 |

---

## 4. 接口入参

### 4.1 路径参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | Long（字符串形式） | 是 | 订单 ID（雪花 ID，前端需以字符串传递防精度丢失） |

### 4.2 请求体

无请求体（GET 接口）。

---

## 5. 出参字段

本次仅列出 `data.main` 块的变更字段。其余 Tab（traveler / itinerary / requirement / contract / insurance / payment / refund / complaint）无变化。

### data.main（OrderMainVO）新增字段

| 字段名 | 类型 | 可空 | 说明 |
|--------|------|------|------|
| `productCoverImg` | String | 是（可为 null） | 产品封面图 OSS URL。下单时从产品快照落库，历史订单（无封面快照）返回 null |

> **与订单列表一致**：`GET /v3/admin/order/list` 列表项 `productCoverImg` 字段同名同义，前端可复用相同渲染逻辑（img src 赋值、占位图降级处理）。

---

## 6. 枚举 / 数据字典

本次变更无枚举或字典变化。

---

## 7. 错误码

本次变更无新增错误码。接口原有错误码不变：

| 错误码 | 说明 |
|--------|------|
| `580101` | 订单不存在 |

---

## 8. 示例

### 8.1 典型成功（productCoverImg 有值）

**请求**

```http
GET /v3/admin/order/1923800000000001 HTTP/1.1
Authorization: Bearer <admin-token>
```

**响应（仅展示 data.main 核心字段，其余 Tab 略）**

```json
{
  "code": 200,
  "data": {
    "main": {
      "id": "1923800000000001",
      "orderNo": "HL2026060001",
      "productName": "长白山 5 日精品游",
      "productCoverImg": "https://oss.hulalv.com/p/changbai-cover.jpg",
      "orderStatus": "PENDING_PAYMENT",
      "flowStepName": "待支付"
    }
  }
}
```

### 8.2 边界情况（历史订单，productCoverImg 为 null）

历史订单在 `product_cover_img` 列无快照数据时，字段返回 `null`，前端需做占位图降级处理。

**响应片段**

```json
{
  "code": 200,
  "data": {
    "main": {
      "id": "1800000000000001",
      "orderNo": "HL2025120001",
      "productCoverImg": null
    }
  }
}
```

### 8.3 业务失败（订单不存在）

**请求**

```http
GET /v3/admin/order/9999999999999999 HTTP/1.1
Authorization: Bearer <admin-token>
```

**响应**

```json
{
  "code": 580101,
  "msg": "订单不存在"
}
```

---

## 9. 业务边界

| 场景 | 行为 |
|------|------|
| 正常下单（有产品封面） | `productCoverImg` 返回产品封面 OSS URL |
| 历史订单（无封面快照） | `productCoverImg` 返回 `null`，前端需做占位图降级 |
| URL 为完整路径 | 直接赋值给 img src，无需拼接域名前缀 |

---

## 10. 修改前后对比

### 字段级对比（data.main 块）

| 字段 | 修改前 | 修改后 |
|------|--------|--------|
| `productCoverImg` | **不存在**（详情不返回） | ✨ 新增，String，可为 null |

### 行为级对比

| 场景 | 修改前 | 修改后 |
|------|--------|--------|
| 管理后台详情页封面展示 | 无法在详情获取封面，只能在列表展示 | 详情 `main.productCoverImg` 直接可用 |

---

## 11. 影响评估 / 回滚

| 项目 | 说明 |
|------|------|
| **破坏兼容性** | 否。纯新增字段，旧前端代码忽略即可，不影响已有功能 |
| **前端同步上线** | 非必须同步。前端可按需接入此字段以展示封面 |
| **回滚方案** | 后端回滚 PR #4026 即可；前端无需回滚（该字段缺失时原逻辑不受影响） |

---

## 12. 注意事项

1. `productCoverImg` 可为 `null`，前端渲染时**必须**做判空处理（img 设置 fallback 占位图，避免空 src 报错）。
2. 与订单列表接口（`GET /v3/admin/order/list`）的 `productCoverImg` **完全同名同义**，前端可提取公共渲染组件复用。
3. OSS URL 已是完整路径，不需要拼接域名前缀。

---

## 13. 关联 / 联系人

| 项目 | 链接 |
|------|------|
| Issue | https://git.1814.love:8443/wx/HL/issues/4025 |
| PR | https://git.1814.love:8443/wx/HL/pulls/4026 |
| 后端负责人 | 腰苏图 |
