f284e37955
MP算价新增paymentType/depositAmount/balanceAmount， 内部算价新增tierSeq参数，订单创建全链路透传tierSeq， 补充产品/档位/价格合法性校验。
162 行
4.5 KiB
Markdown
162 行
4.5 KiB
Markdown
# 算价接口补充订金尾款 + 档位参数 + 数据校验
|
||
|
||
> **服务**: hl-product-service-v2 (端口 8083) + hl-order-service-v2 (端口 8084)
|
||
> **PR**: #716
|
||
> **日期**: 2026-04-17
|
||
> **影响范围**: 小程序端算价、内部算价、订单创建
|
||
|
||
---
|
||
|
||
## 一、变更说明
|
||
|
||
1. **小程序算价接口**新增订金/尾款金额返回，前端可直接展示"支付订金 ¥X / 尾款 ¥X"
|
||
2. **内部算价接口**新增 `tierSeq` 档位参数，支持多档位差异报价
|
||
3. **订单创建**全链路透传 `tierSeq`，创建订单时按用户选择的档位算价
|
||
4. **数据校验**：产品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产品响应示例**：
|
||
|
||
```json
|
||
{
|
||
"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产品响应示例**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"grandTotal": 9998.0,
|
||
"paymentType": "FULL",
|
||
"depositRatio": null,
|
||
"depositAmount": null,
|
||
"balanceAmount": null
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. C端/管理端创建订单 - 新增 tierSeq
|
||
|
||
**请求新增字段**（MpOrderSaveReqVO / AdminOrderSaveReqVO）：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `tierSeq` | Integer | 否 | 档位序号，默认1。多档位产品需传入用户选择的档位 |
|
||
|
||
**请求示例**：
|
||
|
||
```json
|
||
{
|
||
"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`，刷新价格展示。
|
||
|
||
---
|
||
|
||
## 六、数据库变更
|
||
|
||
```sql
|
||
-- 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。
|