API Changelog Bot f284e37955 算价接口补充订金尾款+档位参数+数据校验 (PR #716 )

MP算价新增paymentType/depositAmount/balanceAmount，
内部算价新增tierSeq参数，订单创建全链路透传tierSeq，
补充产品/档位/价格合法性校验。

2026-04-17 10:38:48 +08:00

4.5 KiB

原始文件 Blame 文件历史

算价接口补充订金尾款 + 档位参数 + 数据校验

服务: hl-product-service-v2 (端口 8083) + hl-order-service-v2 (端口 8084) PR: #716 日期: 2026-04-17 影响范围: 小程序端算价、内部算价、订单创建

一、变更说明

小程序算价接口新增订金/尾款金额返回，前端可直接展示"支付订金 ¥X / 尾款 ¥X"
内部算价接口新增 tierSeq 档位参数，支持多档位差异报价
订单创建全链路透传 tierSeq，创建订单时按用户选择的档位算价
数据校验：产品ID不存在、档位不存在、价格为0 均返回明确错误

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	C端报价	POST	`/mp/product/{id}/quote`	响应新增字段	新增 paymentType/depositAmount/balanceAmount
2	内部简单报价	GET	`/internal/product/{id}/simple-quote`	请求新增参数	新增 tierSeq 参数
3	C端创建订单	POST	`/internal/order/mp/create`	请求新增字段	新增 tierSeq
4	管理端创建订单	POST	`/admin/order/create`	请求新增字段	新增 tierSeq
5	管理端报价预览	POST	`/admin/order/quote`	请求新增字段	新增 tierSeq

三、接口详情

1. C端报价 `POST /mp/product/{id}/quote`

请求参数（无变化，tierSeq 已有）：

字段	类型	必填	说明
departureDate	String	是	出发日期，格式 yyyy-MM-dd
adultCount	Integer	是	成人数（≥1）
childCount	Integer	否	儿童数，默认0
tierSeq	Integer	否	档位序号，默认1

响应新增字段：

字段	类型	说明
`paymentType`	String	支付方式：`FULL`=全款, `DEPOSIT`=订金+尾款
`depositRatio`	Integer	订金比例(%)，仅 DEPOSIT 时有值
`depositAmount`	BigDecimal	订金金额，仅 DEPOSIT 时有值
`balanceAmount`	BigDecimal	尾款金额，仅 DEPOSIT 时有值

DEPOSIT产品响应示例：

{
  "code": 200,
  "data": {
    "adultUnitPrice": 4999.0,
    "childUnitPrice": 3499.0,
    "totalAdultPrice": 9998.0,
    "totalChildPrice": 3499.0,
    "grandTotal": 13497.0,
    "paymentType": "DEPOSIT",
    "depositRatio": 30,
    "depositAmount": 4049.10,
    "balanceAmount": 9447.90
  }
}

FULL产品响应示例：

{
  "code": 200,
  "data": {
    "grandTotal": 9998.0,
    "paymentType": "FULL",
    "depositRatio": null,
    "depositAmount": null,
    "balanceAmount": null
  }
}

2. C端/管理端创建订单 - 新增 tierSeq

请求新增字段（MpOrderSaveReqVO / AdminOrderSaveReqVO）：

字段	类型	必填	说明
`tierSeq`	Integer	否	档位序号，默认1。多档位产品需传入用户选择的档位

请求示例：

{
  "productId": 2042826067407925249,
  "departureDate": "2026-07-01",
  "adultCount": 2,
  "childCount": 1,
  "tierSeq": 2,
  "contactName": "张三",
  "contactPhone": "13800138000"
}

四、错误码新增

场景	code	message 示例
产品不存在(MP)	404	产品不存在或已下架
产品不存在(内部)	404	产品不存在: 999
档位不存在	404	日期 2026-07-01 档位99 未设置价格日历（产品ID=xxx）
日期无价格	404	日期 2030-01-01 档位1 未设置价格日历（产品ID=xxx）
成人售价为0	500	日期 2026-07-01 档位1 的成人售价未设置（产品ID=xxx）

五、前端实现建议

支付按钮区域

paymentType === "DEPOSIT" 时：
+---------------------------+
| 支付订金 ¥4,049            |  <-- depositAmount
| 尾款 ¥9,448 落地后由领队收取  |  <-- balanceAmount
+---------------------------+

paymentType === "FULL" 时：
+---------------------------+
| 立即支付 ¥13,497           |  <-- grandTotal
+---------------------------+

多档位选择

用户切换档位时，重新调用 /mp/product/{id}/quote，传入对应 tierSeq，刷新价格展示。

六、数据库变更

-- order_info 表新增档位字段
ALTER TABLE order_info ADD COLUMN tier_seq INT DEFAULT 1 COMMENT '档位序号(默认1)' AFTER room_count;

七、重启服务

需要重启：

hl-product-service-v2（端口 8083）
hl-order-service-v2（端口 8084）

测试环境需同步执行上述 DDL。

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