API Changelog Bot 4e02058aff docs: 算价/档位/定金系列变更通知 (PR #718/#720/#722/#724)

2026-04-17 11:32:26 +08:00

6.6 KiB

原始文件 Blame 文件历史

算价/档位/定金系列变更

服务: hl-product-service-v2 (端口 8083) PR: #718, #720, #722, #724 日期: 2026-04-17 影响范围: 小程序算价、管理端算价、管理端下单产品选择、小程序档位对比

一、变更总览

#	主题	PR
1	固定定金算价按总人头 × 单价	#718
2	管理端下单产品选择列表补档位 + 新增档位下拉接口	#720
3	算价接口补全4类人员单价/小计（成人/儿童/小童/幼童）	#722
4	小程序档位对比响应补充档位名称 tierName	#724

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	小程序算价	POST	`/mp/product/quote`	响应字段语义 + 新增字段	固定定金按总人头×单价；新增4类人员单价/小计
2	管理端算价	POST	`/admin/product/item/quote`	响应新增字段	新增4类人员单价/小计
3	商品选择列表	GET	`/admin/product/item/simple-list`	响应新增字段	新增 `tiers` 档位数组
4	产品档位下拉	GET	`/admin/product/item/{productId}/tiers`	新增接口	下单选档位用
5	小程序档位对比	GET	`/mp/product/{id}/tier-compare`	响应新增字段	每组新增 `tierName`

三、接口详情

1. 小程序算价 `POST /mp/product/quote`

响应完整字段（新增 4 类人员细分）：

字段	类型	说明
`adultUnitPrice`	BigDecimal	成人单价
`childUnitPrice`	BigDecimal	儿童单价
`toddlerUnitPrice`	BigDecimal	🆕 小童单价 = max(儿童价 + 小童优惠额, 0)
`infantUnitPrice`	BigDecimal	🆕 幼童单价（0=免费）
`totalAdultPrice`	BigDecimal	成人小计
`totalChildPrice`	BigDecimal	儿童小计
`totalToddlerPrice`	BigDecimal	🆕 小童小计
`totalInfantPrice`	BigDecimal	🆕 幼童小计
`grandTotal`	BigDecimal	总价（4类小计之和，旧版只含成人+儿童）
`paymentType`	String	`FULL` / `DEPOSIT`
`depositRatio`	Integer	订金比例(%)，仅比例定金
`depositAmount`	BigDecimal	订金金额（⚠️ 固定定金语义变更见下方）
`balanceAmount`	BigDecimal	尾款金额

⚠️ 固定定金算法变更（#718）：

产品设置"订金固定额"时，之前返回的 depositAmount 是单人额度（不随人数变），导致前端显示与实际收款不符。

旧：depositAmount = product.depositAmount
新：depositAmount = product.depositAmount × (adultCount + childCount + toddlerCount + infantCount)
若乘出金额 > grandTotal，取 grandTotal 兜底（防止 balance 为负）
比例定金逻辑不变（仍按 grandTotal × ratio%）

示例（固定定金 500/人，2成人+1儿童+1幼童，grandTotal=13498）：

{
  "code": 200,
  "data": {
    "adultUnitPrice": 4999.00,
    "childUnitPrice": 3500.00,
    "toddlerUnitPrice": 0,
    "infantUnitPrice": 0,
    "totalAdultPrice": 9998.00,
    "totalChildPrice": 3500.00,
    "totalToddlerPrice": 0,
    "totalInfantPrice": 0,
    "grandTotal": 13498.00,
    "paymentType": "DEPOSIT",
    "depositAmount": 2000.00,   // 500 × 4人
    "balanceAmount": 11498.00
  }
}

2. 管理端算价 `POST /admin/product/item/quote`

响应新增字段与小程序端一致（toddlerUnitPrice / infantUnitPrice / totalToddlerPrice / totalInfantPrice），grandTotal 同步包含 4 类。

3. 商品选择列表 `GET /admin/product/item/simple-list`

请求参数（无变化）：

字段	类型	必填	说明
productType	String	否	CORE / GROUP / CUSTOM
keyword	String	否	名称/编号模糊
pageNo / pageSize	Integer	是	分页

响应新增字段：

字段	类型	说明
`tiers`	Array	🆕 档位列表（tierSeq / tierName / tierDescription）

响应示例：

{
  "code": 200,
  "data": {
    "records": [
      {
        "productId": 2043246204711550977,
        "productNo": "C260409001",
        "name": "额吉的故乡·亲子版",
        "tripDays": 6,
        "lineName": "草原环线",
        "tiers": [
          {"tierSeq": 1, "tierName": "标准档", "tierDescription": "三星酒店"},
          {"tierSeq": 2, "tierName": "豪华档", "tierDescription": "四星酒店升级"}
        ]
      }
    ],
    "total": 10,
    "page": 1,
    "pageSize": 50
  }
}

使用场景：下单搜索产品时，前端直接展示"有几档/具体档位"，避免再次请求。

4. 产品档位下拉 `GET /admin/product/item/{productId}/tiers` 🆕

场景：下单弹窗内选档位用。算价接口需要 tierSeq 参数，前端必须先让用户选档位。

请求：路径参数 productId

响应：

{
  "code": 200,
  "data": [
    {"tierSeq": 1, "tierName": "标准档", "tierDescription": "三星酒店"},
    {"tierSeq": 2, "tierName": "豪华档", "tierDescription": "四星酒店升级"}
  ]
}

异常：产品不存在 → code=404，message="产品不存在: xxx"

5. 小程序档位对比 `GET /mp/product/{id}/tier-compare`

响应变化：tiers[].tierName 🆕 新增字段。

{
  "code": 200,
  "data": {
    "tiers": [
      {
        "tierSeq": 1,
        "tierName": "标准档",    // 🆕
        "hotels": [...]
      },
      {
        "tierSeq": 2,
        "tierName": "豪华档",    // 🆕
        "hotels": [...]
      }
    ]
  }
}

四、前端适配指南

小程序端

算价展示：渲染 4 类人员的单价和小计；固定定金产品场景下 depositAmount 现在会随人数变化
档位对比页：用 tiers[].tierName 作为卡片标题（此前只能显示"档位1"之类）

管理端

下单产品选择弹窗：simple-list 响应里直接拿 tiers 展示档位数；选中产品后用 GET /{productId}/tiers 渲染档位下拉
算价展示：渲染 4 类人员单价/小计

五、重启提示

需要重启的服务：hl-product-service-v2（端口 8083）

不涉及 DB DDL，仅代码变更；字段注释有更新（deposit_amount COMMENT），但不影响运行时。

六、关联 Issue/PR

Issue	PR	主题
#717	#718	固定定金按人数计算
#719	#720	simple-list 补档位 + 档位下拉接口
#721	#722	算价补全 4 类人员单价
#723	#724	档位对比补 tierName

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