hl-api-changelog/changelogs/2026-04/2026-04-13_product-v2_create-merge-and-pricing-guide.md

接口变更记录 — 2026-04-13

变更类型：接口合并 + 定价模型说明 在线文档：

• 局域网：http://192.168.100.236:8080/doc.html → 1. 管理端 - 产品管理
• 公网：https://api.test.1814.love:9443/doc.html（需认证）

---

一、创建产品和Step1基础信息合并为一个接口

旧接口（已删除）

接口	说明
POST /admin/product/item	独立创建接口，已删除
PUT /admin/product/item/{id}/basic	独立Step1保存，已删除

新接口

POST /admin/product/item/basic — 创建+更新合一

• productId 不传 = 创建新产品（草稿），返回新 productId
• productId 传了 = 更新已有产品，返回原 productId

创建时请求示例（productId不传）

{
  "productType": "CORE",
  "name": "额吉的故乡·亲子版",
  "tripDays": 6,
  "lineId": 100,
  "coverImageUrl": "https://...",
  "seasons": ["summer"],
  "tags": ["亲子"]
}

• productType 创建时必传（CORE/GROUP/CUSTOM）
• version 创建时不传
• 其他字段可选，创建时可以只传最少信息，也可以一次性填完全部

更新时请求示例（productId传已有ID）

{
  "productId": 2043246204711550977,
  "version": 0,
  "name": "额吉的故乡·亲子版（修改）",
  "tripDays": 6,
  "lineId": 100,
  "coverImageUrl": "https://...",
  "seasons": ["summer", "autumn"],
  "tags": ["亲子", "研学"],
  "tiers": [
    {"tierSeq": 1, "tierName": "舒适"},
    {"tierSeq": 2, "tierName": "豪华"}
  ]
}

• version 更新时必传（从详情接口获取，乐观锁校验）
• productType 更新时传了也会被忽略（创建后不可改）

响应

{
  "code": 200,
  "message": "成功",
  "data": 2043246204711550977
}

返回 Long 类型的产品ID（创建时是新ID，更新时是原ID）。

---

二、定价模型：哪种产品用哪个接口

核心规则

产品类型	定价模型	用户选什么	用哪组接口
CORE（核心产品）	价格日历	用户从日历选出发日期	price-calendar 系列
CUSTOM（私人定制）	价格日历	同上	price-calendar 系列
GROUP（小蒙马）	班期制	用户从班期列表选第N期	schedule 系列

前端判断逻辑

if (productType === 'CORE' || productType === 'CUSTOM') {
    // Step4 显示【价格日历】界面
    // 用 price-calendar 系列接口
} else if (productType === 'GROUP') {
    // Step4 显示【班期管理】界面
    // 用 schedule 系列接口
}

价格日历接口（CORE / CUSTOM 产品用）

场景	方法	路径	说明
查询价格日历	GET	/admin/product/item/{id}/price-calendar?month=2026-07&tierSeq=1	按月+档位查询
批量设置价格	POST	/admin/product/item/{id}/price-calendar/batch	按日期范围设价
删除价格区间	DELETE	/admin/product/item/{id}/price-calendar	按日期范围删除

批量设置请求示例：

{
  "productId": 123,
  "version": 3,
  "startDate": "2026-07-01",
  "endDate": "2026-07-31",
  "tierSeq": 1,
  "priceType": "PEAK",
  "adultSellPrice": 4980,
  "childSellPrice": 3980,
  "toddlerDiscount": -500,
  "infantPrice": 0,
  "dailyStock": 10
}

价格日历查询响应：

[
  {
    "id": 1,
    "productId": 123,
    "tierSeq": 1,
    "date": "2026-07-01",
    "priceType": "PEAK",
    "adultSellPrice": 4980,
    "childSellPrice": 3980,
    "toddlerDiscount": -500,
    "infantPrice": 0,
    "dailyStock": 10,
    "sold": 2
  }
]

班期接口（GROUP 小蒙马产品用）

场景	方法	路径	说明
班期列表	GET	/admin/product/item/{id}/schedule/list	返回全部班期
创建班期	POST	/admin/product/item/{id}/schedule	不传batchId
修改班期	PUT	/admin/product/item/{id}/schedule	传batchId
删除班期	DELETE	/admin/product/item/{id}/schedule/{scheduleId}	有订单不可删
取消班期	POST	/admin/product/item/{id}/schedule/{scheduleId}/cancel	触发退款
批量创建	POST	/admin/product/item/{id}/schedule/batch-create	按重复模式
班期团队查询	GET	/admin/product/item/{id}/schedule/team?batchId=xxx	团队成员
班期团队保存	PUT	/admin/product/item/{id}/schedule/team?batchId=xxx	全量替换

创建班期请求示例：

{
  "productId": 123,
  "batchName": "第1期",
  "departureDate": "2026-07-01",
  "enrollmentDeadline": "2026-06-30",
  "adultPrice": 4980,
  "childPrice": 3980,
  "toddlerDiscount": -500,
  "infantPrice": 0,
  "maxParticipants": 20,
  "maxRooms": 10,
  "productStockLimit": 20
}

班期列表响应：

[
  {
    "batchId": 456,
    "productId": 123,
    "batchNo": "B20260701001",
    "batchName": "第1期",
    "departureDate": "2026-07-01",
    "endDate": "2026-07-06",
    "enrollmentDeadline": "2026-06-30",
    "adultPrice": 4980,
    "childPrice": 3980,
    "toddlerDiscount": -500,
    "infantPrice": 0,
    "maxParticipants": 20,
    "enrolledCount": 8,
    "maxRooms": 10,
    "bookedRooms": 4,
    "productStockLimit": 20,
    "batchStatus": "ENROLLING",
    "version": 0
  }
]

批量创建班期请求示例：

{
  "productId": 123,
  "startDate": "2026-07-01",
  "endDate": "2026-09-30",
  "repeatMode": "WEEKLY",
  "dayOfWeek": 1,
  "adultPrice": 4980,
  "childPrice": 3980,
  "maxParticipants": 20,
  "maxRooms": 10
}

价格日历 vs 班期对比

维度	价格日历（CORE/CUSTOM）	班期（GROUP）
定价粒度	每天独立价格	每期一个固定价格
库存	按天（dailyStock=每天可接几单）	按期（maxParticipants=总人数+maxRooms=总房间数）
档位	支持多档（tierSeq区分）	单一档位
用户选择	C端日历选日期	C端列表选第N期
团队配置	无	每期可配领队/摄影师等
价格类型	平日/旺季/节假日/特价（颜色区分）	无（每期统一价）

班期状态说明

状态	中文	说明
ENROLLING	报名中	正常接受报名
NEARLY_FULL	即将满员	剩余房间≤阈值（默认2间）
FULL	已满	剩余房间=0
FINISHED	已结束	出发日期已过
CANCELLING	取消中	有订单，退款处理中
CANCELLED	已取消	取消完成