# 小程序产品详情/列表接口新增支付模式字段

> **服务**: hl-product-service-v2 (端口 8083)
> **PR**: #715
> **日期**: 2026-04-17
> **影响范围**: 小程序端产品详情 + 产品列表

---

## 一、变更说明

小程序端产品详情接口和产品列表接口新增支付模式相关字段，前端可据此展示"全款支付"或"订金+尾款"的支付方式提示。

---

## 二、变更接口清单

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|------|---------|------|
| 1 | 产品详情(C端) | GET | `/mp/product/{id}` | 响应新增字段 | 新增 paymentType/depositRatio/depositAmount |
| 2 | 产品线下产品列表 | GET | `/mp/product/list-by-line` | 响应新增字段 | 新增 paymentType |

---

## 三、接口详情

### 1. 产品详情 `GET /mp/product/{id}`

**响应新增字段**（在原有响应基础上新增，其他字段不变）：

| 字段 | 类型 | 说明 |
|------|------|------|
| `paymentType` | String | 支付方式：`FULL`=全款, `DEPOSIT`=订金+尾款 |
| `depositRatio` | Integer | 订金比例(%)，仅 DEPOSIT 时有值，如 `30` 表示30% |
| `depositAmount` | BigDecimal | 订金固定额，仅 DEPOSIT 时有值，如 `2000.00` |

**响应示例（仅展示新增部分）**：

```json
{
  "code": 0,
  "data": {
    "productId": 1001,
    "name": "呼伦贝尔亲子5日游",
    "paymentType": "DEPOSIT",
    "depositRatio": 30,
    "depositAmount": null,
    "startPrice": 3980.00
  }
}
```

**全款产品示例**：

```json
{
  "code": 0,
  "data": {
    "productId": 1002,
    "name": "三亚蜜月7日游",
    "paymentType": "FULL",
    "depositRatio": null,
    "depositAmount": null,
    "startPrice": 5980.00
  }
}
```

### 2. 产品列表 `GET /mp/product/list-by-line`

**响应新增字段**（列表每项新增）：

| 字段 | 类型 | 说明 |
|------|------|------|
| `paymentType` | String | 支付方式：`FULL`=全款, `DEPOSIT`=订金+尾款 |

**响应示例**：

```json
{
  "code": 0,
  "data": [
    {
      "productId": 1001,
      "name": "呼伦贝尔亲子5日游",
      "paymentType": "DEPOSIT",
      "startPrice": 3980.00,
      "tierCount": 2
    },
    {
      "productId": 1002,
      "name": "三亚蜜月7日游",
      "paymentType": "FULL",
      "startPrice": 5980.00,
      "tierCount": 1
    }
  ]
}
```

---

## 四、枚举/字典值

### paymentType 支付方式

| 值 | 中文 | 说明 |
|----|------|------|
| `FULL` | 全款 | 一次性支付全部金额（默认值） |
| `DEPOSIT` | 订金+尾款 | 先付订金，出发前补尾款 |

---

## 五、业务规则

1. **默认值**：未设置支付方式的产品默认返回 `"FULL"`
2. **订金模式**：`paymentType=DEPOSIT` 时，`depositRatio`（百分比）和 `depositAmount`（固定金额）二选一有值
   - `depositRatio=30` 表示订金为总价的30%
   - `depositAmount=2000.00` 表示订金固定2000元
   - 两者都有时以 `depositAmount`（固定额）优先
3. **全款模式**：`paymentType=FULL` 时，`depositRatio` 和 `depositAmount` 均为 `null`

---

## 六、前端实现建议

### 产品详情页 - 支付方式提示

```
+---------------------------+
| 价格区域                    |
| 起步价: 3980/人             |
| 支付方式: 订金30% + 尾款     |  <-- paymentType=DEPOSIT 时显示
+---------------------------+
```

**展示逻辑**：
- `paymentType === "FULL"` → 不显示或显示"全款支付"
- `paymentType === "DEPOSIT"` → 显示"订金X% + 尾款"或"订金¥X + 尾款"
  - 优先用 `depositAmount`：`"订金¥2000 + 尾款"`
  - 无固定额用 `depositRatio`：`"订金30% + 尾款"`

### 产品列表卡片 - 支付标签

```
+---------------------------+
| [封面图]                    |
| 呼伦贝尔亲子5日游            |
| ¥3980起  [订金预订]         |  <-- paymentType=DEPOSIT 时显示标签
+---------------------------+
```

---

## 七、重启服务

需要重启 **hl-product-service-v2**（端口 8083）