From 3ed8cc3f14a4e7aa199324fa42d4dc327444bd6e Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Mon, 13 Apr 2026 09:52:12 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E9=80=9A=E7=9F=A5=E5=89=8D=E7=AB=AF?= =?UTF-8?q?=E5=88=9B=E5=BB=BA=E6=8E=A5=E5=8F=A3=E5=90=88=E5=B9=B6=20+=20?= =?UTF-8?q?=E5=AE=9A=E4=BB=B7=E6=A8=A1=E5=9E=8B=E6=8C=89=E4=BA=A7=E5=93=81?= =?UTF-8?q?=E7=B1=BB=E5=9E=8B=E5=8C=BA=E5=88=86=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.6 (1M context) --- ...oduct-v2_create-merge-and-pricing-guide.md | 242 ++++++++++++++++++ 1 file changed, 242 insertions(+) create mode 100644 changelogs/2026-04/2026-04-13_product-v2_create-merge-and-pricing-guide.md diff --git a/changelogs/2026-04/2026-04-13_product-v2_create-merge-and-pricing-guide.md b/changelogs/2026-04/2026-04-13_product-v2_create-merge-and-pricing-guide.md new file mode 100644 index 0000000..e594b38 --- /dev/null +++ b/changelogs/2026-04/2026-04-13_product-v2_create-merge-and-pricing-guide.md @@ -0,0 +1,242 @@ +# 接口变更记录 — 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不传） + +```json +{ + "productType": "CORE", + "name": "额吉的故乡·亲子版", + "tripDays": 6, + "lineId": 100, + "coverImageUrl": "https://...", + "seasons": ["summer"], + "tags": ["亲子"] +} +``` + +- `productType` **创建时必传**（CORE/GROUP/CUSTOM） +- `version` **创建时不传** +- 其他字段可选，创建时可以只传最少信息，也可以一次性填完全部 + +### 更新时请求示例（productId传已有ID） + +```json +{ + "productId": 2043246204711550977, + "version": 0, + "name": "额吉的故乡·亲子版（修改）", + "tripDays": 6, + "lineId": 100, + "coverImageUrl": "https://...", + "seasons": ["summer", "autumn"], + "tags": ["亲子", "研学"], + "tiers": [ + {"tierSeq": 1, "tierName": "舒适"}, + {"tierSeq": 2, "tierName": "豪华"} + ] +} +``` + +- `version` **更新时必传**（从详情接口获取，乐观锁校验） +- `productType` 更新时传了也会被忽略（创建后不可改） + +### 响应 + +```json +{ + "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` | 按日期范围删除 | + +**批量设置请求示例**： + +```json +{ + "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 +} +``` + +**价格日历查询响应**： + +```json +[ + { + "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` | 全量替换 | + +**创建班期请求示例**： + +```json +{ + "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 +} +``` + +**班期列表响应**： + +```json +[ + { + "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 + } +] +``` + +**批量创建班期请求示例**： + +```json +{ + "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 | 已取消 | 取消完成 |