diff --git a/changelogs/2026-04/2026-04-17_product-v2_quote-deposit-tierseq.md b/changelogs/2026-04/2026-04-17_product-v2_quote-deposit-tierseq.md new file mode 100644 index 0000000..c95df2b --- /dev/null +++ b/changelogs/2026-04/2026-04-17_product-v2_quote-deposit-tierseq.md @@ -0,0 +1,161 @@ +# 算价接口补充订金尾款 + 档位参数 + 数据校验 + +> **服务**: 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。