API Changelog Bot b1d0e6eb8b 小程序产品详情/列表接口新增支付模式字段 (PR #715 )

详情接口新增 paymentType/depositRatio/depositAmount，
列表接口新增 paymentType，支持前端展示全款/订金支付方式。

2026-04-17 09:58:15 +08:00

3.9 KiB

原始文件 Blame 文件历史

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

服务: 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`

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

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

全款产品示例：

{
  "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`=订金+尾款

响应示例：

{
  "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`	订金+尾款	先付订金，出发前补尾款

五、业务规则

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

3.9 KiB 原始文件 Blame 文件历史 Unescape Escape