From b1d0e6eb8b4c644a2c3e9cee74c445c8a52d16fd Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Fri, 17 Apr 2026 09:58:15 +0800
Subject: [PATCH] =?UTF-8?q?=E5=B0=8F=E7=A8=8B=E5=BA=8F=E4=BA=A7=E5=93=81?=
 =?UTF-8?q?=E8=AF=A6=E6=83=85/=E5=88=97=E8=A1=A8=E6=8E=A5=E5=8F=A3?=
 =?UTF-8?q?=E6=96=B0=E5=A2=9E=E6=94=AF=E4=BB=98=E6=A8=A1=E5=BC=8F=E5=AD=97?=
 =?UTF-8?q?=E6=AE=B5=20(PR=20#715)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

详情接口新增 paymentType/depositRatio/depositAmount，
列表接口新增 paymentType，支持前端展示全款/订金支付方式。
---
 .../2026-04-17_product-v2_mp-payment-mode.md  | 157 ++++++++++++++++++
 1 file changed, 157 insertions(+)
 create mode 100644 changelogs/2026-04/2026-04-17_product-v2_mp-payment-mode.md

diff --git a/changelogs/2026-04/2026-04-17_product-v2_mp-payment-mode.md b/changelogs/2026-04/2026-04-17_product-v2_mp-payment-mode.md
new file mode 100644
index 0000000..24ea2e7
--- /dev/null
+++ b/changelogs/2026-04/2026-04-17_product-v2_mp-payment-mode.md
@@ -0,0 +1,157 @@
+# 小程序产品详情/列表接口新增支付模式字段
+
+> **服务**: 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）