wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态
hl-api-changelog/hl-product-service.md
API Changelog Bot 8cdd5773fa docs: sync 13 services API documentation
2026-03-17 09:24:37 +08:00

5189 行
239 KiB
Markdown
原始文件 Blame 文件历史

此文件含有模棱两可的 Unicode 字符

此文件含有可能会与其他字符混淆的 Unicode 字符。 如果您是想特意这样的，可以安全地忽略该警告。 使用 Escape 按钮显示他们。

# 产品服务 API 文档
**服务**: `hl-product-service`
**接口总数**: 106
## 目录
- **产品文件夹管理** (4 个接口)
- **产品管理** (10 个接口)
- **产品线管理** (6 个接口)
- **定价与费用管理** (20 个接口)
- **定价公式管理** (19 个接口)
- **家庭分组管理** (4 个接口)
- **小程序-产品** (3 个接口)
- **报价计算** (2 个接口)
- **拼团批次管理** (12 个接口)
- **行政区划搜索** (1 个接口)
- **行程管理** (25 个接口)
---
## 产品文件夹管理
### `POST` /admin/product/folder
**创建文件夹**
创建产品文件夹，用于组织管理产品。支持多级目录结构。
文件夹归属于创建人，普通管理员只能看到自己的文件夹。
**请求体** `创建文件夹请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `name` | `string` | 是 | 文件夹名称 |
| `parentId` | `string` | | 父文件夹ID，为空则为根文件夹 |
| `sortOrder` | `int` | | 排序序号 |
**响应** `统一响应结果«产品文件夹VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `产品文件夹VO` | | 响应数据 |
|   `children` | `产品文件夹VO[]` | | 子文件夹列表 |
|     `children` | `产品文件夹VO[]` | | 子文件夹列表 |
|     `createTime` | `string` | | 创建时间 |
|     `folderId` | `string` | | 文件夹ID |
|     `name` | `string` | | 文件夹名称 |
|     `ownerId` | `string` | | 拥有者ID |
|     `ownerName` | `string` | | 拥有者姓名 |
|     `parentId` | `string` | | 父文件夹ID |
|     `productCount` | `int` | | 文件夹内产品数量 |
|     `sortOrder` | `int` | | 排序序号 |
|     `updateTime` | `string` | | 更新时间 |
|   `createTime` | `string` | | 创建时间 |
|   `folderId` | `string` | | 文件夹ID |
|   `name` | `string` | | 文件夹名称 |
|   `ownerId` | `string` | | 拥有者ID |
|   `ownerName` | `string` | | 拥有者姓名 |
|   `parentId` | `string` | | 父文件夹ID |
|   `productCount` | `int` | | 文件夹内产品数量 |
|   `sortOrder` | `int` | | 排序序号 |
|   `updateTime` | `string` | | 更新时间 |
| `message` | `string` | | 响应消息 |
---
### `GET` /admin/product/folder/tree
**获取文件夹树**
获取当前用户可见的文件夹树形结构。
普通管理员只能看到自己创建的文件夹，SUPER_ADMIN 可看到所有文件夹。
返回结构为嵌套的树形列表，包含每个文件夹的子文件夹。
**响应** `统一响应结果«List«产品文件夹VO»»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `产品文件夹VO[]` | | 响应数据 |
|   `children` | `产品文件夹VO[]` | | 子文件夹列表 |
|     `children` | `产品文件夹VO[]` | | 子文件夹列表 |
|     `createTime` | `string` | | 创建时间 |
|     `folderId` | `string` | | 文件夹ID |
|     `name` | `string` | | 文件夹名称 |
|     `ownerId` | `string` | | 拥有者ID |
|     `ownerName` | `string` | | 拥有者姓名 |
|     `parentId` | `string` | | 父文件夹ID |
|     `productCount` | `int` | | 文件夹内产品数量 |
|     `sortOrder` | `int` | | 排序序号 |
|     `updateTime` | `string` | | 更新时间 |
|   `createTime` | `string` | | 创建时间 |
|   `folderId` | `string` | | 文件夹ID |
|   `name` | `string` | | 文件夹名称 |
|   `ownerId` | `string` | | 拥有者ID |
|   `ownerName` | `string` | | 拥有者姓名 |
|   `parentId` | `string` | | 父文件夹ID |
|   `productCount` | `int` | | 文件夹内产品数量 |
|   `sortOrder` | `int` | | 排序序号 |
|   `updateTime` | `string` | | 更新时间 |
| `message` | `string` | | 响应消息 |
---
### `PUT` /admin/product/folder/{folderId}
**更新文件夹**
更新文件夹名称等信息。
**权限说明**：普通管理员只能更新自己创建的文件夹，SUPER_ADMIN 可更新任何文件夹。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `folderId` | `integer` | | 文件夹ID |
**请求体** `更新文件夹请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `name` | `string` | | 文件夹名称 |
| `sortOrder` | `int` | | 排序序号 |
**响应** `统一响应结果«产品文件夹VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `产品文件夹VO` | | 响应数据 |
|   `children` | `产品文件夹VO[]` | | 子文件夹列表 |
|     `children` | `产品文件夹VO[]` | | 子文件夹列表 |
|     `createTime` | `string` | | 创建时间 |
|     `folderId` | `string` | | 文件夹ID |
|     `name` | `string` | | 文件夹名称 |
|     `ownerId` | `string` | | 拥有者ID |
|     `ownerName` | `string` | | 拥有者姓名 |
|     `parentId` | `string` | | 父文件夹ID |
|     `productCount` | `int` | | 文件夹内产品数量 |
|     `sortOrder` | `int` | | 排序序号 |
|     `updateTime` | `string` | | 更新时间 |
|   `createTime` | `string` | | 创建时间 |
|   `folderId` | `string` | | 文件夹ID |
|   `name` | `string` | | 文件夹名称 |
|   `ownerId` | `string` | | 拥有者ID |
|   `ownerName` | `string` | | 拥有者姓名 |
|   `parentId` | `string` | | 父文件夹ID |
|   `productCount` | `int` | | 文件夹内产品数量 |
|   `sortOrder` | `int` | | 排序序号 |
|   `updateTime` | `string` | | 更新时间 |
| `message` | `string` | | 响应消息 |
---
### `DELETE` /admin/product/folder/{folderId}
**删除文件夹**
删除文件夹。如果文件夹下有产品，产品会自动移到根目录（folderId 置空）。
普通管理员只能删除自己的文件夹，SUPER_ADMIN 可删除任何文件夹。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `folderId` | `integer` | | 文件夹ID |
**响应** `统一响应结果«Void»`
---
## 产品管理
### `POST` /admin/product/item
**创建产品（草稿）**
创建一个新产品，初始状态为 DRAFT（草稿）。
**产品类型说明**：
- CORE：核心产品，标准旅游产品，支持上架/下架审批流程
- GROUP：小蒙马拼团，需配合团期批次管理，按人头计价
- CUSTOM：定制产品，由定制师为客户量身定制，按单计价
- ROUTE：线路产品，预设线路模板，按单计价
**注意事项**：
- 创建后需依次完善行程、定价、价格日历等信息
- CUSTOM/ROUTE 产品的价格日历存储的是整单总价，不按人头乘算
- GROUP 产品需额外创建团期批次才能报名
**关联字典**：
- product_type（产品类型）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品
- product_category（产品分类）：family=亲子游, honeymoon=蜜月游, photography=旅拍, experience=体验, driving=自驾
**请求体** `创建产品请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `adultCount` | `int` | | 成人人数 |
| `babyCount` | `int` | | 婴儿人数 |
| `bookingNotice` | `string` | | 预定须知 |
| `cancelPolicy` | `string` | | 退改政策 |
| `carouselImages` | `string[]` | | 轮播图列表 |
| `carouselVideoUrl` | `string` | | 轮播视频URL |
| `childCount` | `int` | | 儿童人数 |
| `creatorAvatarUrl` | `string` | | 定制师头像URL |
| `creatorIntro` | `string` | | 创作者寄语 |
| `customizerId` | `string` | | 定制师ID |
| `departureCity` | `string` | | 出发城市 |
| `destinationCity` | `string` | | 目的地城市 |
| `folderId` | `string` | | 所属文件夹ID |
| `groupChatQrUrl` | `string` | | 群聊二维码URL |
| `groupRoomId` | `string` | | 企微群聊ID(用于会话存档展示群消息) |
| `isBooking` | `boolean` | | 是否预约产品 |
| `lineId` | `string` | | 产品线ID |
| `maxAdultPerOrder` | `int` | | 每单最大成人数(不填则不限制) |
| `maxChildPerOrder` | `int` | | 每单最大儿童数(不填则不限制) |
| `mchId` | `string` | | 商户号：shanhe/wenlu |
| `minAdultPerOrder` | `int` | | 每单最少成人数(不填默认1) |
| `name` | `string` | 是 | 产品名称 |
| `productType` | `string` | 是 | 产品类型：CORE=核心产品 ROUTE=线路产品 CUSTOM=定制产品 GROUP=小蒙马拼团 |
| `seasons` | `string[]` | | 适用季节列表 |
| `showChatGroup` | `boolean` | | 是否显示群聊入口 |
| `showReview` | `boolean` | | 是否显示评价 |
| `showTripDistance` | `boolean` | | 是否显示行程距离 |
| `showTripTime` | `boolean` | | 是否显示行程时间 |
| `subtitle` | `string` | | 副标题 |
| `tags` | `string[]` | | 产品标签列表 |
| `tripDays` | `int` | | 行程天数 |
| `warmTips` | `string` | | 温馨提示 |
| `youngChildCount` | `int` | | 小童人数 |
**响应** `统一响应结果«产品详情VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `产品详情VO` | | 响应数据 |
|   `adultCount` | `int` | | 成人人数 |
|   `babyCount` | `int` | | 婴儿人数 |
|   `benefitsDescription` | `权益分组[]` | | 权益说明（静态，所有产品相同） |
|     `items` | `权益项[]` | | 权益项列表 |
|     `title` | `string` | | 分组标题，如：儿童权益 (1.2m以下) |
|   `bookingNotice` | `string` | | 预定须知 |
|   `cancelPolicy` | `string` | | 退改政策 |
|   `carouselImages` | `string[]` | | 轮播图列表 |
|   `carouselVideoUrl` | `string` | | 轮播视频URL |
|   `chatMessages` | `群聊消息VO[]` | | 群聊消息列表 |
|     `avatar` | `string` | | 用户头像URL（type=user时有效） |
|     `text` | `string` | | 消息内容 |
|     `type` | `string` | | 消息类型: user/creator |
|   `childCount` | `int` | | 儿童人数 |
|   `costItems` | `产品成本项VO[]` | | 成本项列表 |
|     `category` | `string` | | 成本项类别：HOTEL/SCENIC/VEHICLE/ACTIVITY/SERVICE/DINING/OTHER |
|     `description` | `string` | | 成本项描述 |
|     `id` | `string` | | 成本项ID |
|     `sortOrder` | `int` | | 排序序号 |
|     `title` | `string` | | 成本项标题 |
|     `type` | `string` | | 成本项类型：INCLUDED=费用包含 EXCLUDED=费用不含 SELF_PAY=自理费用 |
|   `coverImageUrl` | `string` | | 封面图URL |
|   `createBy` | `string` | | 创建人ID |
|   `createTime` | `string` | | 创建时间 |
|   `creatorAvatarUrl` | `string` | | 定制师头像URL |
|   `creatorIntro` | `string` | | 创作者寄语 |
|   `customFees` | `产品自定义费用项VO[]` | | 自定义费用项列表 |
|     `description` | `string` | | 费用说明 |
|     `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
|     `feeAmount` | `number` | | 费用金额 |
|     `feeName` | `string` | | 费用项名称 |
|     `feeUnit` | `string` | | 费用单位 |
|     `id` | `string` | | 费用项ID |
|     `sortOrder` | `int` | | 排序序号 |
|   `customizerId` | `string` | | 定制师ID |
|   `departureCity` | `string` | | 出发城市 |
|   `destinationCities` | `string[]` | | 途经城市列表（从行程节点资源去重提取） |
|   `destinationCity` | `string` | | 目的地城市 |
|   `families` | `家庭分组VO[]` | | 家庭分组列表（定制产品） |
|     `adultCount` | `int` | | 成人数 |
|     `babyCount` | `int` | | 幼童数 |
|     `childCount` | `int` | | 儿童数 |
|     `familyId` | `string` | | 家庭ID |
|     `familyName` | `string` | | 家庭名称 |
|     `sortOrder` | `int` | | 排序序号 |
|     `youngChildCount` | `int` | | 小童数 |
|   `folderId` | `string` | | 所属文件夹ID |
|   `groupChatQrUrl` | `string` | | 群聊二维码URL |
|   `groupRoomId` | `string` | | 企微群聊ID(用于会话存档展示群消息) |
|   `isBooking` | `boolean` | | 是否预约产品 |
|   `itineraryDays` | `行程天VO[]` | | 行程天列表 |
|     `dayId` | `string` | | 行程天ID |
|     `dayNumber` | `int` | | 天数编号 |
|     `dayTitle` | `string` | | 天标题 |
|     `hotels` | `每日酒店VO[]` | | 当日酒店列表 |
|     `nodes` | `行程节点VO[]` | | 行程节点列表 |
|     `restaurants` | `用餐选项VO[]` | | 当日用餐列表 |
|     `routeSummary` | `string` | | 路线概览 |
|   `lineId` | `string` | | 产品线ID |
|   `lineName` | `string` | | 产品线名称 |
|   `lineSubtitle` | `string` | | 产品线副标题 |
|   `maxAdultPerOrder` | `int` | | 每单最大成人数(null=不限) |
|   `maxChildPerOrder` | `int` | | 每单最大儿童数(null=不限) |
|   `mchId` | `string` | | 商户号 |
|   `minAdultPerOrder` | `int` | | 每单最少成人数(null=默认1) |
|   `name` | `string` | | 产品名称 |
|   `paymentMode` | `string` | | 支付模式：FULL=全款 DEPOSIT=定金+尾款 |
|   `pricing` | `产品定价配置VO` | | 定价配置 |
|     `adultExtraBed` | `number` | | 成人加床费 |
|     `babyPrice` | `number` | | 婴儿价 |
|     `balanceDueDays` | `int` | | 尾款支付截止天数（出发前N天） |
|     `childDiscountPercent` | `number` | | 儿童折扣百分比 |
|     `childNoBed` | `number` | | 儿童不占床价 |
|     `childWithBed` | `number` | | 儿童占床价 |
|     `companionPrice` | `number` | | 陪同人员价格 |
|     `customTotalPrice` | `number` | | 定制产品总价（CUSTOM模式下使用） |
|     `depositAmount` | `number` | | 定金金额 |
|     `depositRatio` | `int` | | 定金比例（百分比） |
|     `extraCostPerPerson` | `number` | | 每人额外成本 |
|     `insuranceFee` | `number` | | 保险费用 |
|     `markupPercent` | `number` | | 加价百分比（PERCENT模式下使用） |
|     `maxGroupSize` | `int` | | 最大成团人数 |
|     `mealBudget` | `number` | | 餐费预算 |
|     `minGroupSize` | `int` | | 最小成团人数 |
|     `paymentType` | `string` | | 支付方式：FULL=全款 DEPOSIT=定金+尾款 |
|     `pricingId` | `string` | | 定价配置ID |
|     `pricingMode` | `string` | | 定价模式：AUTO=自动计算 MANUAL=手动定价 CUSTOM=定制定价 |
|     `productId` | `string` | | 产品ID |
|     `profitAmount` | `number` | | 利润金额（FIXED模式下使用） |
|     `profitMode` | `string` | | 利润模式：FIXED=固定金额 PERCENT=百分比 |
|     `singleRoomDiff` | `number` | | 单房差 |
|     `vehicleModelIds` | `string[]` | | 车型ID列表 |
|     `vehicleWarning` | `string` | | 车辆绑定警告信息（为空表示绑定成功） |
|   `productId` | `string` | | 产品ID |
|   `productNo` | `string` | | 产品编号 |
|   `productType` | `string` | | 产品类型：CORE=核心产品 ROUTE=线路产品 CUSTOM=定制产品 GROUP=小蒙马拼团 |
|   `publishedAt` | `string` | | 发布时间 |
|   `routeMapUrl` | `string` | | 路径图URL（后端自动生成） |
|   `seasons` | `string[]` | | 适用季节列表 |
|   `showChatGroup` | `boolean` | | 是否显示群聊入口 |
|   `showReview` | `boolean` | | 是否显示评价 |
|   `showTripDistance` | `boolean` | | 是否显示行程距离 |
|   `showTripTime` | `boolean` | | 是否显示行程时间 |
|   `sortOrder` | `int` | | 排序序号 |
|   `staffConfigs` | `产品人员配置VO[]` | | 人员配置列表（定制产品） |
|     `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
|     `id` | `string` | | 记录ID |
|     `quantity` | `int` | | 数量 |
|     `sortOrder` | `int` | | 排序序号 |
|     `staffType` | `string` | | 人员类型：GUIDE/GUIDE_ASSISTANT/PHOTOGRAPHER/LEADER/OTHER |
|     `staffTypeName` | `string` | | 人员类型名称 |
|   `startPrice` | `number` | | 起步价：未来一年价格日历中最低成人售价 |
|   `status` | `string` | | 产品状态：DRAFT/PENDING_REVIEW/REVIEWED/REJECTED/PUBLISHED/UNPUBLISHED/COMPLETED |
|   `subtitle` | `string` | | 副标题 |
|   `suppliesList` | `产品物资VO[]` | | 物资列表 |
|     `billingType` | `string` | | 计费方式：BY_PERSON=按人头 BY_COUNT=按次/按件 |
|     `costPerPerson` | `number` | | 每人成本 |
|     `coverUrl` | `string` | | 封面图URL |
|     `dayNumber` | `int` | | 天数编号（scope=DAY时生效） |
|     `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
|     `id` | `string` | | 记录ID |
|     `quantity` | `int` | | 数量 |
|     `scope` | `string` | | 适用范围：ALL=整个行程 DAY=指定天 |
|     `sortOrder` | `int` | | 排序序号 |
|     `suppliesId` | `string` | | 物资ID |
|     `suppliesName` | `string` | | 物资名称 |
|   `tags` | `string[]` | | 产品标签列表 |
|   `teamExperienceYears` | `int` | | 团队经验年数 |
|   `tripDays` | `int` | | 行程天数 |
|   `tripNights` | `int` | | 行程晚数 |
|   `updateBy` | `string` | | 更新人ID |
|   `updateTime` | `string` | | 更新时间 |
|   `warmTips` | `string` | | 温馨提示 |
|   `youngChildCount` | `int` | | 小童人数 |
| `message` | `string` | | 响应消息 |
---
### `GET` /admin/product/item/list
**产品列表**
分页查询产品列表，支持多维度筛选和排序。
**权限说明**：
- 普通管理员只能看到自己创建的产品
- SUPER_ADMIN 可看到所有产品
**筛选条件**：关键词（名称/副标题模糊匹配）、产品类型、状态、文件夹、产品线、季节、行程天数。
支持多状态筛选（statuses 字段，逗号分隔）。
**关联字典**：
- product_type（产品类型，筛选条件）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品
- product_status（产品状态，筛选条件+返回字段）：DRAFT=草稿, PENDING_REVIEW=待审核, REVIEWED=已审核, REJECTED=已驳回, PUBLISHED=已上架, UNPUBLISHED=已下架, COMPLETED=已完成, ORDERED=已下单
**查询参数**
| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `folderId` | `string` | | 文件夹ID | 1893012345678901234 |
| `keyword` | `string` | | 搜索关键词 | 丽江 |
| `lineId` | `string` | | 产品线ID | 1893012345678901234 |
| `page` | `integer(int32)` | | 页码 | 1 |
| `pageSize` | `integer(int32)` | | 每页条数 | 20 |
| `productType` | `string` | | 产品类型：CORE=核心产品 ROUTE=线路产品 CUSTOM=定制产品 GROUP=小蒙马拼团 | CORE |
| `season` | `string` | | 季节筛选 | spring |
| `sortBy` | `string` | | 排序字段：name/tripDays/createTime/updateTime | createTime |
| `sortDir` | `string` | | 排序方向：asc/desc | desc |
| `status` | `string` | | 产品状态：DRAFT/PENDING_REVIEW/REVIEWED/REJECTED/PUBLISHED/UNPUBLISHED/COMPLETED | PUBLISHED |
| `statuses` | `string` | | 多状态筛选（逗号分隔） | PUBLISHED,COMPLETED |
| `tripDays` | `integer(int32)` | | 行程天数 | 5 |
**响应** `统一响应结果«分页结果«产品列表VO»»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `分页结果«产品列表VO»` | | 响应数据 |
|   `page` | `int` | | 当前页码 |
|   `pageSize` | `int` | | 每页条数 |
|   `records` | `产品列表VO[]` | | 数据列表 |
|     `adultCount` | `int` | | 成人数（私人定制/路书） |
|     `approvalNo` | `string` | | 审批编号 |
|     `babyCount` | `int` | | 幼童数（私人定制/路书） |
|     `childCount` | `int` | | 儿童数（私人定制/路书） |
|     `coverImageUrl` | `string` | | 封面图URL |
|     `createBy` | `string` | | 创建人ID |
|     `createTime` | `string` | | 创建时间 |
|     `departureCity` | `string` | | 出发城市 |
|     `destinationCity` | `string` | | 目的地城市 |
|     `folderId` | `string` | | 所属文件夹ID |
|     `groupRoomId` | `string` | | 企微群聊ID(用于会话存档展示群消息) |
|     `isBooking` | `boolean` | | 是否预约产品 |
|     `lineId` | `string` | | 产品线ID |
|     `lineName` | `string` | | 产品线名称 |
|     `maxAdultPerOrder` | `int` | | 每单最大成人数(null=不限) |
|     `maxChildPerOrder` | `int` | | 每单最大儿童数(null=不限) |
|     `mchId` | `string` | | 商户号 |
|     `minAdultPerOrder` | `int` | | 每单最少成人数(null=默认1) |
|     `name` | `string` | | 产品名称 |
|     `pendingStatus` | `string` | | 待审批目标状态 |
|     `productId` | `string` | | 产品ID |
|     `productNo` | `string` | | 产品编号 |
|     `productType` | `string` | | 产品类型：CORE=核心产品 ROUTE=线路产品 CUSTOM=定制产品 GROUP=小蒙马拼团 |
|     `seasons` | `string[]` | | 适用季节列表 |
|     `sortOrder` | `int` | | 排序序号 |
|     `status` | `string` | | 产品状态：DRAFT/PENDING_REVIEW/REVIEWED/REJECTED/PUBLISHED/UNPUBLISHED/COMPLETED |
|     `subtitle` | `string` | | 副标题 |
|     `tripDays` | `int` | | 行程天数 |
|     `tripNights` | `int` | | 行程晚数 |
|     `updateTime` | `string` | | 更新时间 |
|     `youngChildCount` | `int` | | 小童数（私人定制/路书） |
|   `total` | `int` | | 总记录数 |
| `message` | `string` | | 响应消息 |
---
### `GET` /admin/product/item/{productId}
**获取产品详情**
获取产品完整信息，包括基本信息、行程天列表、定价配置、费用项等。
返回数据包含关联的行程节点资源详情，适用于产品编辑页面。
不过滤产品状态，所有状态的产品都可查看。
**关联字典**：
- product_type（产品类型）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品
- product_status（产品状态）：DRAFT=草稿, PENDING_REVIEW=待审核, REVIEWED=已审核, REJECTED=已驳回, PUBLISHED=已上架, UNPUBLISHED=已下架, COMPLETED=已完成, ORDERED=已下单
- product_category（产品分类）：family=亲子游, honeymoon=蜜月游, photography=旅拍, experience=体验, driving=自驾
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `productId` | `integer` | | 产品ID |
**响应** `统一响应结果«产品详情VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `产品详情VO` | | 响应数据 |
|   `adultCount` | `int` | | 成人人数 |
|   `babyCount` | `int` | | 婴儿人数 |
|   `benefitsDescription` | `权益分组[]` | | 权益说明（静态，所有产品相同） |
|     `items` | `权益项[]` | | 权益项列表 |
|     `title` | `string` | | 分组标题，如：儿童权益 (1.2m以下) |
|   `bookingNotice` | `string` | | 预定须知 |
|   `cancelPolicy` | `string` | | 退改政策 |
|   `carouselImages` | `string[]` | | 轮播图列表 |
|   `carouselVideoUrl` | `string` | | 轮播视频URL |
|   `chatMessages` | `群聊消息VO[]` | | 群聊消息列表 |
|     `avatar` | `string` | | 用户头像URL（type=user时有效） |
|     `text` | `string` | | 消息内容 |
|     `type` | `string` | | 消息类型: user/creator |
|   `childCount` | `int` | | 儿童人数 |
|   `costItems` | `产品成本项VO[]` | | 成本项列表 |
|     `category` | `string` | | 成本项类别：HOTEL/SCENIC/VEHICLE/ACTIVITY/SERVICE/DINING/OTHER |
|     `description` | `string` | | 成本项描述 |
|     `id` | `string` | | 成本项ID |
|     `sortOrder` | `int` | | 排序序号 |
|     `title` | `string` | | 成本项标题 |
|     `type` | `string` | | 成本项类型：INCLUDED=费用包含 EXCLUDED=费用不含 SELF_PAY=自理费用 |
|   `coverImageUrl` | `string` | | 封面图URL |
|   `createBy` | `string` | | 创建人ID |
|   `createTime` | `string` | | 创建时间 |
|   `creatorAvatarUrl` | `string` | | 定制师头像URL |
|   `creatorIntro` | `string` | | 创作者寄语 |
|   `customFees` | `产品自定义费用项VO[]` | | 自定义费用项列表 |
|     `description` | `string` | | 费用说明 |
|     `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
|     `feeAmount` | `number` | | 费用金额 |
|     `feeName` | `string` | | 费用项名称 |
|     `feeUnit` | `string` | | 费用单位 |
|     `id` | `string` | | 费用项ID |
|     `sortOrder` | `int` | | 排序序号 |
|   `customizerId` | `string` | | 定制师ID |
|   `departureCity` | `string` | | 出发城市 |
|   `destinationCities` | `string[]` | | 途经城市列表（从行程节点资源去重提取） |
|   `destinationCity` | `string` | | 目的地城市 |
|   `families` | `家庭分组VO[]` | | 家庭分组列表（定制产品） |
|     `adultCount` | `int` | | 成人数 |
|     `babyCount` | `int` | | 幼童数 |
|     `childCount` | `int` | | 儿童数 |
|     `familyId` | `string` | | 家庭ID |
|     `familyName` | `string` | | 家庭名称 |
|     `sortOrder` | `int` | | 排序序号 |
|     `youngChildCount` | `int` | | 小童数 |
|   `folderId` | `string` | | 所属文件夹ID |
|   `groupChatQrUrl` | `string` | | 群聊二维码URL |
|   `groupRoomId` | `string` | | 企微群聊ID(用于会话存档展示群消息) |
|   `isBooking` | `boolean` | | 是否预约产品 |
|   `itineraryDays` | `行程天VO[]` | | 行程天列表 |
|     `dayId` | `string` | | 行程天ID |
|     `dayNumber` | `int` | | 天数编号 |
|     `dayTitle` | `string` | | 天标题 |
|     `hotels` | `每日酒店VO[]` | | 当日酒店列表 |
|     `nodes` | `行程节点VO[]` | | 行程节点列表 |
|     `restaurants` | `用餐选项VO[]` | | 当日用餐列表 |
|     `routeSummary` | `string` | | 路线概览 |
|   `lineId` | `string` | | 产品线ID |
|   `lineName` | `string` | | 产品线名称 |
|   `lineSubtitle` | `string` | | 产品线副标题 |
|   `maxAdultPerOrder` | `int` | | 每单最大成人数(null=不限) |
|   `maxChildPerOrder` | `int` | | 每单最大儿童数(null=不限) |
|   `mchId` | `string` | | 商户号 |
|   `minAdultPerOrder` | `int` | | 每单最少成人数(null=默认1) |
|   `name` | `string` | | 产品名称 |
|   `paymentMode` | `string` | | 支付模式：FULL=全款 DEPOSIT=定金+尾款 |
|   `pricing` | `产品定价配置VO` | | 定价配置 |
|     `adultExtraBed` | `number` | | 成人加床费 |
|     `babyPrice` | `number` | | 婴儿价 |
|     `balanceDueDays` | `int` | | 尾款支付截止天数（出发前N天） |
|     `childDiscountPercent` | `number` | | 儿童折扣百分比 |
|     `childNoBed` | `number` | | 儿童不占床价 |
|     `childWithBed` | `number` | | 儿童占床价 |
|     `companionPrice` | `number` | | 陪同人员价格 |
|     `customTotalPrice` | `number` | | 定制产品总价（CUSTOM模式下使用） |
|     `depositAmount` | `number` | | 定金金额 |
|     `depositRatio` | `int` | | 定金比例（百分比） |
|     `extraCostPerPerson` | `number` | | 每人额外成本 |
|     `insuranceFee` | `number` | | 保险费用 |
|     `markupPercent` | `number` | | 加价百分比（PERCENT模式下使用） |
|     `maxGroupSize` | `int` | | 最大成团人数 |
|     `mealBudget` | `number` | | 餐费预算 |
|     `minGroupSize` | `int` | | 最小成团人数 |
|     `paymentType` | `string` | | 支付方式：FULL=全款 DEPOSIT=定金+尾款 |
|     `pricingId` | `string` | | 定价配置ID |
|     `pricingMode` | `string` | | 定价模式：AUTO=自动计算 MANUAL=手动定价 CUSTOM=定制定价 |
|     `productId` | `string` | | 产品ID |
|     `profitAmount` | `number` | | 利润金额（FIXED模式下使用） |
|     `profitMode` | `string` | | 利润模式：FIXED=固定金额 PERCENT=百分比 |
|     `singleRoomDiff` | `number` | | 单房差 |
|     `vehicleModelIds` | `string[]` | | 车型ID列表 |
|     `vehicleWarning` | `string` | | 车辆绑定警告信息（为空表示绑定成功） |
|   `productId` | `string` | | 产品ID |
|   `productNo` | `string` | | 产品编号 |
|   `productType` | `string` | | 产品类型：CORE=核心产品 ROUTE=线路产品 CUSTOM=定制产品 GROUP=小蒙马拼团 |
|   `publishedAt` | `string` | | 发布时间 |
|   `routeMapUrl` | `string` | | 路径图URL（后端自动生成） |
|   `seasons` | `string[]` | | 适用季节列表 |
|   `showChatGroup` | `boolean` | | 是否显示群聊入口 |
|   `showReview` | `boolean` | | 是否显示评价 |
|   `showTripDistance` | `boolean` | | 是否显示行程距离 |
|   `showTripTime` | `boolean` | | 是否显示行程时间 |
|   `sortOrder` | `int` | | 排序序号 |
|   `staffConfigs` | `产品人员配置VO[]` | | 人员配置列表（定制产品） |
|     `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
|     `id` | `string` | | 记录ID |
|     `quantity` | `int` | | 数量 |
|     `sortOrder` | `int` | | 排序序号 |
|     `staffType` | `string` | | 人员类型：GUIDE/GUIDE_ASSISTANT/PHOTOGRAPHER/LEADER/OTHER |
|     `staffTypeName` | `string` | | 人员类型名称 |
|   `startPrice` | `number` | | 起步价：未来一年价格日历中最低成人售价 |
|   `status` | `string` | | 产品状态：DRAFT/PENDING_REVIEW/REVIEWED/REJECTED/PUBLISHED/UNPUBLISHED/COMPLETED |
|   `subtitle` | `string` | | 副标题 |
|   `suppliesList` | `产品物资VO[]` | | 物资列表 |
|     `billingType` | `string` | | 计费方式：BY_PERSON=按人头 BY_COUNT=按次/按件 |
|     `costPerPerson` | `number` | | 每人成本 |
|     `coverUrl` | `string` | | 封面图URL |
|     `dayNumber` | `int` | | 天数编号（scope=DAY时生效） |
|     `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
|     `id` | `string` | | 记录ID |
|     `quantity` | `int` | | 数量 |
|     `scope` | `string` | | 适用范围：ALL=整个行程 DAY=指定天 |
|     `sortOrder` | `int` | | 排序序号 |
|     `suppliesId` | `string` | | 物资ID |
|     `suppliesName` | `string` | | 物资名称 |
|   `tags` | `string[]` | | 产品标签列表 |
|   `teamExperienceYears` | `int` | | 团队经验年数 |
|   `tripDays` | `int` | | 行程天数 |
|   `tripNights` | `int` | | 行程晚数 |
|   `updateBy` | `string` | | 更新人ID |
|   `updateTime` | `string` | | 更新时间 |
|   `warmTips` | `string` | | 温馨提示 |
|   `youngChildCount` | `int` | | 小童人数 |
| `message` | `string` | | 响应消息 |
---
### `PUT` /admin/product/item/{productId}
**更新产品**
更新产品基本信息，仅传入需要修改的字段，未传字段不会被覆盖。
**权限说明**：
- 普通管理员只能编辑自己创建的产品
- SUPER_ADMIN 可编辑所有产品
**注意**：行程、定价、价格日历等通过各自独立的接口管理，不在此接口中处理。
**关联字典**：
- product_type（产品类型）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品
- product_category（产品分类）：family=亲子游, honeymoon=蜜月游, photography=旅拍, experience=体验, driving=自驾
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `productId` | `integer` | | 产品ID |
**请求体** `更新产品请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `adultCount` | `int` | | 成人人数 |
| `babyCount` | `int` | | 婴儿人数 |
| `bookingNotice` | `string` | | 预定须知 |
| `cancelPolicy` | `string` | | 退改政策 |
| `carouselImages` | `string[]` | | 轮播图列表 |
| `carouselVideoUrl` | `string` | | 轮播视频URL |
| `chatMessages` | `群聊消息VO[]` | | 群聊消息列表 |
|   `avatar` | `string` | | 用户头像URL（type=user时有效） |
|   `text` | `string` | | 消息内容 |
|   `type` | `string` | | 消息类型: user/creator |
| `childCount` | `int` | | 儿童人数 |
| `creatorAvatarUrl` | `string` | | 定制师头像URL |
| `creatorIntro` | `string` | | 创作者寄语 |
| `customizerId` | `string` | | 定制师ID |
| `departureCity` | `string` | | 出发城市 |
| `destinationCity` | `string` | | 目的地城市 |
| `folderId` | `string` | | 所属文件夹ID |
| `groupChatQrUrl` | `string` | | 群聊二维码URL |
| `groupRoomId` | `string` | | 企微群聊ID(用于会话存档展示群消息) |
| `isBooking` | `boolean` | | 是否预约产品 |
| `lineId` | `string` | | 产品线ID |
| `lineSubtitle` | `string` | | 产品线副标题 |
| `maxAdultPerOrder` | `int` | | 每单最大成人数(不填则不限制) |
| `maxChildPerOrder` | `int` | | 每单最大儿童数(不填则不限制) |
| `mchId` | `string` | | 商户号：shanhe/wenlu |
| `minAdultPerOrder` | `int` | | 每单最少成人数(不填默认1) |
| `name` | `string` | | 产品名称 |
| `seasons` | `string[]` | | 适用季节列表 |
| `showChatGroup` | `boolean` | | 是否显示群聊入口 |
| `showReview` | `boolean` | | 是否显示评价 |
| `showTripDistance` | `boolean` | | 是否显示行程距离 |
| `showTripTime` | `boolean` | | 是否显示行程时间 |
| `sortOrder` | `int` | | 排序序号 |
| `subtitle` | `string` | | 副标题 |
| `tags` | `string[]` | | 产品标签列表 |
| `teamExperienceYears` | `int` | | 团队经验年数 |
| `tripDays` | `int` | | 行程天数 |
| `warmTips` | `string` | | 温馨提示 |
| `youngChildCount` | `int` | | 小童人数 |
**响应** `统一响应结果«产品详情VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `产品详情VO` | | 响应数据 |
|   `adultCount` | `int` | | 成人人数 |
|   `babyCount` | `int` | | 婴儿人数 |
|   `benefitsDescription` | `权益分组[]` | | 权益说明（静态，所有产品相同） |
|     `items` | `权益项[]` | | 权益项列表 |
|     `title` | `string` | | 分组标题，如：儿童权益 (1.2m以下) |
|   `bookingNotice` | `string` | | 预定须知 |
|   `cancelPolicy` | `string` | | 退改政策 |
|   `carouselImages` | `string[]` | | 轮播图列表 |
|   `carouselVideoUrl` | `string` | | 轮播视频URL |
|   `chatMessages` | `群聊消息VO[]` | | 群聊消息列表 |
|     `avatar` | `string` | | 用户头像URL（type=user时有效） |
|     `text` | `string` | | 消息内容 |
|     `type` | `string` | | 消息类型: user/creator |
|   `childCount` | `int` | | 儿童人数 |
|   `costItems` | `产品成本项VO[]` | | 成本项列表 |
|     `category` | `string` | | 成本项类别：HOTEL/SCENIC/VEHICLE/ACTIVITY/SERVICE/DINING/OTHER |
|     `description` | `string` | | 成本项描述 |
|     `id` | `string` | | 成本项ID |
|     `sortOrder` | `int` | | 排序序号 |
|     `title` | `string` | | 成本项标题 |
|     `type` | `string` | | 成本项类型：INCLUDED=费用包含 EXCLUDED=费用不含 SELF_PAY=自理费用 |
|   `coverImageUrl` | `string` | | 封面图URL |
|   `createBy` | `string` | | 创建人ID |
|   `createTime` | `string` | | 创建时间 |
|   `creatorAvatarUrl` | `string` | | 定制师头像URL |
|   `creatorIntro` | `string` | | 创作者寄语 |
|   `customFees` | `产品自定义费用项VO[]` | | 自定义费用项列表 |
|     `description` | `string` | | 费用说明 |
|     `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
|     `feeAmount` | `number` | | 费用金额 |
|     `feeName` | `string` | | 费用项名称 |
|     `feeUnit` | `string` | | 费用单位 |
|     `id` | `string` | | 费用项ID |
|     `sortOrder` | `int` | | 排序序号 |
|   `customizerId` | `string` | | 定制师ID |
|   `departureCity` | `string` | | 出发城市 |
|   `destinationCities` | `string[]` | | 途经城市列表（从行程节点资源去重提取） |
|   `destinationCity` | `string` | | 目的地城市 |
|   `families` | `家庭分组VO[]` | | 家庭分组列表（定制产品） |
|     `adultCount` | `int` | | 成人数 |
|     `babyCount` | `int` | | 幼童数 |
|     `childCount` | `int` | | 儿童数 |
|     `familyId` | `string` | | 家庭ID |
|     `familyName` | `string` | | 家庭名称 |
|     `sortOrder` | `int` | | 排序序号 |
|     `youngChildCount` | `int` | | 小童数 |
|   `folderId` | `string` | | 所属文件夹ID |
|   `groupChatQrUrl` | `string` | | 群聊二维码URL |
|   `groupRoomId` | `string` | | 企微群聊ID(用于会话存档展示群消息) |
|   `isBooking` | `boolean` | | 是否预约产品 |
|   `itineraryDays` | `行程天VO[]` | | 行程天列表 |
|     `dayId` | `string` | | 行程天ID |
|     `dayNumber` | `int` | | 天数编号 |
|     `dayTitle` | `string` | | 天标题 |
|     `hotels` | `每日酒店VO[]` | | 当日酒店列表 |
|     `nodes` | `行程节点VO[]` | | 行程节点列表 |
|     `restaurants` | `用餐选项VO[]` | | 当日用餐列表 |
|     `routeSummary` | `string` | | 路线概览 |
|   `lineId` | `string` | | 产品线ID |
|   `lineName` | `string` | | 产品线名称 |
|   `lineSubtitle` | `string` | | 产品线副标题 |
|   `maxAdultPerOrder` | `int` | | 每单最大成人数(null=不限) |
|   `maxChildPerOrder` | `int` | | 每单最大儿童数(null=不限) |
|   `mchId` | `string` | | 商户号 |
|   `minAdultPerOrder` | `int` | | 每单最少成人数(null=默认1) |
|   `name` | `string` | | 产品名称 |
|   `paymentMode` | `string` | | 支付模式：FULL=全款 DEPOSIT=定金+尾款 |
|   `pricing` | `产品定价配置VO` | | 定价配置 |
|     `adultExtraBed` | `number` | | 成人加床费 |
|     `babyPrice` | `number` | | 婴儿价 |
|     `balanceDueDays` | `int` | | 尾款支付截止天数（出发前N天） |
|     `childDiscountPercent` | `number` | | 儿童折扣百分比 |
|     `childNoBed` | `number` | | 儿童不占床价 |
|     `childWithBed` | `number` | | 儿童占床价 |
|     `companionPrice` | `number` | | 陪同人员价格 |
|     `customTotalPrice` | `number` | | 定制产品总价（CUSTOM模式下使用） |
|     `depositAmount` | `number` | | 定金金额 |
|     `depositRatio` | `int` | | 定金比例（百分比） |
|     `extraCostPerPerson` | `number` | | 每人额外成本 |
|     `insuranceFee` | `number` | | 保险费用 |
|     `markupPercent` | `number` | | 加价百分比（PERCENT模式下使用） |
|     `maxGroupSize` | `int` | | 最大成团人数 |
|     `mealBudget` | `number` | | 餐费预算 |
|     `minGroupSize` | `int` | | 最小成团人数 |
|     `paymentType` | `string` | | 支付方式：FULL=全款 DEPOSIT=定金+尾款 |
|     `pricingId` | `string` | | 定价配置ID |
|     `pricingMode` | `string` | | 定价模式：AUTO=自动计算 MANUAL=手动定价 CUSTOM=定制定价 |
|     `productId` | `string` | | 产品ID |
|     `profitAmount` | `number` | | 利润金额（FIXED模式下使用） |
|     `profitMode` | `string` | | 利润模式：FIXED=固定金额 PERCENT=百分比 |
|     `singleRoomDiff` | `number` | | 单房差 |
|     `vehicleModelIds` | `string[]` | | 车型ID列表 |
|     `vehicleWarning` | `string` | | 车辆绑定警告信息（为空表示绑定成功） |
|   `productId` | `string` | | 产品ID |
|   `productNo` | `string` | | 产品编号 |
|   `productType` | `string` | | 产品类型：CORE=核心产品 ROUTE=线路产品 CUSTOM=定制产品 GROUP=小蒙马拼团 |
|   `publishedAt` | `string` | | 发布时间 |
|   `routeMapUrl` | `string` | | 路径图URL（后端自动生成） |
|   `seasons` | `string[]` | | 适用季节列表 |
|   `showChatGroup` | `boolean` | | 是否显示群聊入口 |
|   `showReview` | `boolean` | | 是否显示评价 |
|   `showTripDistance` | `boolean` | | 是否显示行程距离 |
|   `showTripTime` | `boolean` | | 是否显示行程时间 |
|   `sortOrder` | `int` | | 排序序号 |
|   `staffConfigs` | `产品人员配置VO[]` | | 人员配置列表（定制产品） |
|     `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
|     `id` | `string` | | 记录ID |
|     `quantity` | `int` | | 数量 |
|     `sortOrder` | `int` | | 排序序号 |
|     `staffType` | `string` | | 人员类型：GUIDE/GUIDE_ASSISTANT/PHOTOGRAPHER/LEADER/OTHER |
|     `staffTypeName` | `string` | | 人员类型名称 |
|   `startPrice` | `number` | | 起步价：未来一年价格日历中最低成人售价 |
|   `status` | `string` | | 产品状态：DRAFT/PENDING_REVIEW/REVIEWED/REJECTED/PUBLISHED/UNPUBLISHED/COMPLETED |
|   `subtitle` | `string` | | 副标题 |
|   `suppliesList` | `产品物资VO[]` | | 物资列表 |
|     `billingType` | `string` | | 计费方式：BY_PERSON=按人头 BY_COUNT=按次/按件 |
|     `costPerPerson` | `number` | | 每人成本 |
|     `coverUrl` | `string` | | 封面图URL |
|     `dayNumber` | `int` | | 天数编号（scope=DAY时生效） |
|     `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
|     `id` | `string` | | 记录ID |
|     `quantity` | `int` | | 数量 |
|     `scope` | `string` | | 适用范围：ALL=整个行程 DAY=指定天 |
|     `sortOrder` | `int` | | 排序序号 |
|     `suppliesId` | `string` | | 物资ID |
|     `suppliesName` | `string` | | 物资名称 |
|   `tags` | `string[]` | | 产品标签列表 |
|   `teamExperienceYears` | `int` | | 团队经验年数 |
|   `tripDays` | `int` | | 行程天数 |
|   `tripNights` | `int` | | 行程晚数 |
|   `updateBy` | `string` | | 更新人ID |
|   `updateTime` | `string` | | 更新时间 |
|   `warmTips` | `string` | | 温馨提示 |
|   `youngChildCount` | `int` | | 小童人数 |
| `message` | `string` | | 响应消息 |
---
### `DELETE` /admin/product/item/{productId}
**删除产品**
软删除产品（设置 deleted_at 字段）。
**权限说明**：普通管理员只能删除自己创建的产品，SUPER_ADMIN 可删除所有产品。
**限制**：已上架（PUBLISHED）的产品不能直接删除，需先下架。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `productId` | `integer` | | 产品ID |
**响应** `统一响应结果«Void»`
---
### `POST` /admin/product/item/{productId}/copy
**复制产品**
深度复制产品，包括行程天、行程节点、定价配置、住宿、餐饮、物资、人员配置等所有关联数据。
复制后的产品状态为 DRAFT，名称自动添加"(副本)"后缀。
适用场景：基于已有产品快速创建新产品。
**关联字典**：
- product_type（产品类型，返回字段）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品
- product_status（产品状态，复制后固定为 DRAFT）
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `productId` | `integer` | | 产品ID |
**响应** `统一响应结果«产品详情VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `产品详情VO` | | 响应数据 |
|   `adultCount` | `int` | | 成人人数 |
|   `babyCount` | `int` | | 婴儿人数 |
|   `benefitsDescription` | `权益分组[]` | | 权益说明（静态，所有产品相同） |
|     `items` | `权益项[]` | | 权益项列表 |
|     `title` | `string` | | 分组标题，如：儿童权益 (1.2m以下) |
|   `bookingNotice` | `string` | | 预定须知 |
|   `cancelPolicy` | `string` | | 退改政策 |
|   `carouselImages` | `string[]` | | 轮播图列表 |
|   `carouselVideoUrl` | `string` | | 轮播视频URL |
|   `chatMessages` | `群聊消息VO[]` | | 群聊消息列表 |
|     `avatar` | `string` | | 用户头像URL（type=user时有效） |
|     `text` | `string` | | 消息内容 |
|     `type` | `string` | | 消息类型: user/creator |
|   `childCount` | `int` | | 儿童人数 |
|   `costItems` | `产品成本项VO[]` | | 成本项列表 |
|     `category` | `string` | | 成本项类别：HOTEL/SCENIC/VEHICLE/ACTIVITY/SERVICE/DINING/OTHER |
|     `description` | `string` | | 成本项描述 |
|     `id` | `string` | | 成本项ID |
|     `sortOrder` | `int` | | 排序序号 |
|     `title` | `string` | | 成本项标题 |
|     `type` | `string` | | 成本项类型：INCLUDED=费用包含 EXCLUDED=费用不含 SELF_PAY=自理费用 |
|   `coverImageUrl` | `string` | | 封面图URL |
|   `createBy` | `string` | | 创建人ID |
|   `createTime` | `string` | | 创建时间 |
|   `creatorAvatarUrl` | `string` | | 定制师头像URL |
|   `creatorIntro` | `string` | | 创作者寄语 |
|   `customFees` | `产品自定义费用项VO[]` | | 自定义费用项列表 |
|     `description` | `string` | | 费用说明 |
|     `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
|     `feeAmount` | `number` | | 费用金额 |
|     `feeName` | `string` | | 费用项名称 |
|     `feeUnit` | `string` | | 费用单位 |
|     `id` | `string` | | 费用项ID |
|     `sortOrder` | `int` | | 排序序号 |
|   `customizerId` | `string` | | 定制师ID |
|   `departureCity` | `string` | | 出发城市 |
|   `destinationCities` | `string[]` | | 途经城市列表（从行程节点资源去重提取） |
|   `destinationCity` | `string` | | 目的地城市 |
|   `families` | `家庭分组VO[]` | | 家庭分组列表（定制产品） |
|     `adultCount` | `int` | | 成人数 |
|     `babyCount` | `int` | | 幼童数 |
|     `childCount` | `int` | | 儿童数 |
|     `familyId` | `string` | | 家庭ID |
|     `familyName` | `string` | | 家庭名称 |
|     `sortOrder` | `int` | | 排序序号 |
|     `youngChildCount` | `int` | | 小童数 |
|   `folderId` | `string` | | 所属文件夹ID |
|   `groupChatQrUrl` | `string` | | 群聊二维码URL |
|   `groupRoomId` | `string` | | 企微群聊ID(用于会话存档展示群消息) |
|   `isBooking` | `boolean` | | 是否预约产品 |
|   `itineraryDays` | `行程天VO[]` | | 行程天列表 |
|     `dayId` | `string` | | 行程天ID |
|     `dayNumber` | `int` | | 天数编号 |
|     `dayTitle` | `string` | | 天标题 |
|     `hotels` | `每日酒店VO[]` | | 当日酒店列表 |
|     `nodes` | `行程节点VO[]` | | 行程节点列表 |
|     `restaurants` | `用餐选项VO[]` | | 当日用餐列表 |
|     `routeSummary` | `string` | | 路线概览 |
|   `lineId` | `string` | | 产品线ID |
|   `lineName` | `string` | | 产品线名称 |
|   `lineSubtitle` | `string` | | 产品线副标题 |
|   `maxAdultPerOrder` | `int` | | 每单最大成人数(null=不限) |
|   `maxChildPerOrder` | `int` | | 每单最大儿童数(null=不限) |
|   `mchId` | `string` | | 商户号 |
|   `minAdultPerOrder` | `int` | | 每单最少成人数(null=默认1) |
|   `name` | `string` | | 产品名称 |
|   `paymentMode` | `string` | | 支付模式：FULL=全款 DEPOSIT=定金+尾款 |
|   `pricing` | `产品定价配置VO` | | 定价配置 |
|     `adultExtraBed` | `number` | | 成人加床费 |
|     `babyPrice` | `number` | | 婴儿价 |
|     `balanceDueDays` | `int` | | 尾款支付截止天数（出发前N天） |
|     `childDiscountPercent` | `number` | | 儿童折扣百分比 |
|     `childNoBed` | `number` | | 儿童不占床价 |
|     `childWithBed` | `number` | | 儿童占床价 |
|     `companionPrice` | `number` | | 陪同人员价格 |
|     `customTotalPrice` | `number` | | 定制产品总价（CUSTOM模式下使用） |
|     `depositAmount` | `number` | | 定金金额 |
|     `depositRatio` | `int` | | 定金比例（百分比） |
|     `extraCostPerPerson` | `number` | | 每人额外成本 |
|     `insuranceFee` | `number` | | 保险费用 |
|     `markupPercent` | `number` | | 加价百分比（PERCENT模式下使用） |
|     `maxGroupSize` | `int` | | 最大成团人数 |
|     `mealBudget` | `number` | | 餐费预算 |
|     `minGroupSize` | `int` | | 最小成团人数 |
|     `paymentType` | `string` | | 支付方式：FULL=全款 DEPOSIT=定金+尾款 |
|     `pricingId` | `string` | | 定价配置ID |
|     `pricingMode` | `string` | | 定价模式：AUTO=自动计算 MANUAL=手动定价 CUSTOM=定制定价 |
|     `productId` | `string` | | 产品ID |
|     `profitAmount` | `number` | | 利润金额（FIXED模式下使用） |
|     `profitMode` | `string` | | 利润模式：FIXED=固定金额 PERCENT=百分比 |
|     `singleRoomDiff` | `number` | | 单房差 |
|     `vehicleModelIds` | `string[]` | | 车型ID列表 |
|     `vehicleWarning` | `string` | | 车辆绑定警告信息（为空表示绑定成功） |
|   `productId` | `string` | | 产品ID |
|   `productNo` | `string` | | 产品编号 |
|   `productType` | `string` | | 产品类型：CORE=核心产品 ROUTE=线路产品 CUSTOM=定制产品 GROUP=小蒙马拼团 |
|   `publishedAt` | `string` | | 发布时间 |
|   `routeMapUrl` | `string` | | 路径图URL（后端自动生成） |
|   `seasons` | `string[]` | | 适用季节列表 |
|   `showChatGroup` | `boolean` | | 是否显示群聊入口 |
|   `showReview` | `boolean` | | 是否显示评价 |
|   `showTripDistance` | `boolean` | | 是否显示行程距离 |
|   `showTripTime` | `boolean` | | 是否显示行程时间 |
|   `sortOrder` | `int` | | 排序序号 |
|   `staffConfigs` | `产品人员配置VO[]` | | 人员配置列表（定制产品） |
|     `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
|     `id` | `string` | | 记录ID |
|     `quantity` | `int` | | 数量 |
|     `sortOrder` | `int` | | 排序序号 |
|     `staffType` | `string` | | 人员类型：GUIDE/GUIDE_ASSISTANT/PHOTOGRAPHER/LEADER/OTHER |
|     `staffTypeName` | `string` | | 人员类型名称 |
|   `startPrice` | `number` | | 起步价：未来一年价格日历中最低成人售价 |
|   `status` | `string` | | 产品状态：DRAFT/PENDING_REVIEW/REVIEWED/REJECTED/PUBLISHED/UNPUBLISHED/COMPLETED |
|   `subtitle` | `string` | | 副标题 |
|   `suppliesList` | `产品物资VO[]` | | 物资列表 |
|     `billingType` | `string` | | 计费方式：BY_PERSON=按人头 BY_COUNT=按次/按件 |
|     `costPerPerson` | `number` | | 每人成本 |
|     `coverUrl` | `string` | | 封面图URL |
|     `dayNumber` | `int` | | 天数编号（scope=DAY时生效） |
|     `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
|     `id` | `string` | | 记录ID |
|     `quantity` | `int` | | 数量 |
|     `scope` | `string` | | 适用范围：ALL=整个行程 DAY=指定天 |
|     `sortOrder` | `int` | | 排序序号 |
|     `suppliesId` | `string` | | 物资ID |
|     `suppliesName` | `string` | | 物资名称 |
|   `tags` | `string[]` | | 产品标签列表 |
|   `teamExperienceYears` | `int` | | 团队经验年数 |
|   `tripDays` | `int` | | 行程天数 |
|   `tripNights` | `int` | | 行程晚数 |
|   `updateBy` | `string` | | 更新人ID |
|   `updateTime` | `string` | | 更新时间 |
|   `warmTips` | `string` | | 温馨提示 |
|   `youngChildCount` | `int` | | 小童人数 |
| `message` | `string` | | 响应消息 |
---
### `POST` /admin/product/item/{productId}/generate-route-map
**手动生成路径图**
根据产品行程节点的经纬度信息，调用地图API生成行程路径图。
通常在行程编辑完成后手动触发，生成结果为 OSS 图片 URL。
如果行程节点没有经纬度信息，则无法生成路径图。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `productId` | `integer` | | 产品ID |
**响应** `统一响应结果«string»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `string` | | 响应数据 |
| `message` | `string` | | 响应消息 |
---
### `PUT` /admin/product/item/{productId}/move
**移动产品到文件夹**
将产品移动到指定文件夹，或移出文件夹（folderId 传空字符串或 null）。
文件夹用于组织管理产品，不影响产品的业务逻辑。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `productId` | `integer` | | 产品ID |
**请求体** `产品移动请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `folderId` | `string` | | 目标文件夹ID，为空则移动到根目录 |
**响应** `统一响应结果«Void»`
---
### `POST` /admin/product/item/{productId}/share-link
**生成定制产品分享链接**
为 CUSTOM（定制）产品生成小程序分享链接，用于定制师发送给客户查看方案。
**限制**：仅 CUSTOM 类型且状态为 COMPLETED 的产品可生成。
**权限**：普通管理员只能为自己创建的产品生成链接，SUPER_ADMIN 不受限制。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `productId` | `integer` | | 产品ID |
**响应** `统一响应结果«分享链接响应»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `分享链接响应` | | 响应数据 |
|   `expireTime` | `object` | | 链接过期时间(Unix时间戳) |
|   `productId` | `long` | | 产品ID |
|   `productName` | `string` | | 产品名称 |
|   `urlLink` | `string` | | 微信URL Link |
| `message` | `string` | | 响应消息 |
---
### `PUT` /admin/product/item/{productId}/status
**产品状态变更（上架/下架/完成）**
根据产品类型，状态流转规则不同：
**核心产品(CORE) / 小蒙马(GROUP)**：支持上架/下架，需企微审批
- DRAFT → PENDING_REVIEW → REVIEWED → PUBLISHED（上架）
- PUBLISHED → UNPUBLISHED（下架）
- UNPUBLISHED → PUBLISHED（重新上架）
- REJECTED → DRAFT（驳回后重新编辑）
**定制产品(CUSTOM)**：仅支持完成，无上架/下架概念
- DRAFT → COMPLETED（定制师完成设计）
- COMPLETED → ORDERED（客户下单，系统自动变更）
- ORDERED → COMPLETED（订单取消/退款后回退）
**关联字典**：
- product_type（产品类型，影响状态流转规则）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品
- product_status（产品状态，请求+返回字段）：DRAFT=草稿, PENDING_REVIEW=待审核, REVIEWED=已审核, REJECTED=已驳回, PUBLISHED=已上架, UNPUBLISHED=已下架, COMPLETED=已完成, ORDERED=已下单
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `productId` | `integer` | | 产品ID |
**请求体** `产品状态变更请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `reason` | `string` | | 状态变更原因（驳回时必填；上架/下架审批时可填） |
| `status` | `string` | 是 | 目标状态。核心/小蒙马：DRAFT/PENDING_REVIEW/REVIEWED/REJECTED/PUBLISHED/UNPUBLISHED；定制产品：COMPLETED |
**响应** `统一响应结果«Void»`
---
## 产品线管理
### `POST` /admin/product/line
**创建产品线**
创建产品线，用于对产品进行业务分类（如：亲子游、蜜月游、探险游等）。
产品线在小程序端可作为筛选条件，帮助用户快速找到感兴趣的产品类别。
**请求体** `创建产品线请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `coverImageUrl` | `string` | | 封面图URL |
| `description` | `string` | | 产品线描述 |
| `name` | `string` | 是 | 产品线名称 |
| `sortOrder` | `int` | | 排序序号 |
**响应** `统一响应结果«产品线VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `产品线VO` | | 响应数据 |
|   `coverImageUrl` | `string` | | 封面图URL |
|   `createBy` | `string` | | 创建人ID |
|   `createTime` | `string` | | 创建时间 |
|   `description` | `string` | | 产品线描述 |
|   `lineId` | `string` | | 产品线ID |
|   `name` | `string` | | 产品线名称 |
|   `productCount` | `int` | | 关联产品数量 |
|   `sortOrder` | `int` | | 排序序号 |
|   `status` | `string` | | 状态：ACTIVE=启用 INACTIVE=停用 |
|   `updateTime` | `string` | | 更新时间 |
| `message` | `string` | | 响应消息 |
---
### `GET` /admin/product/line/active
**所有启用的产品线**
获取所有启用状态的产品线，不分页。
适用于产品编辑时的产品线下拉选择，以及小程序端的筛选项。
**响应** `统一响应结果«List«产品线VO»»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `产品线VO[]` | | 响应数据 |
|   `coverImageUrl` | `string` | | 封面图URL |
|   `createBy` | `string` | | 创建人ID |
|   `createTime` | `string` | | 创建时间 |
|   `description` | `string` | | 产品线描述 |
|   `lineId` | `string` | | 产品线ID |
|   `name` | `string` | | 产品线名称 |
|   `productCount` | `int` | | 关联产品数量 |
|   `sortOrder` | `int` | | 排序序号 |
|   `status` | `string` | | 状态：ACTIVE=启用 INACTIVE=停用 |
|   `updateTime` | `string` | | 更新时间 |
| `message` | `string` | | 响应消息 |
---
### `GET` /admin/product/line/list
**产品线列表（分页）**
分页查询产品线列表，支持按名称关键词筛选。
**查询参数**
| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `keyword` | `string` | | 搜索关键词 | 丽江 |
| `page` | `integer(int32)` | | 页码 | 1 |
| `pageSize` | `integer(int32)` | | 每页条数 | 20 |
| `status` | `string` | | 产品线状态：ACTIVE=启用 INACTIVE=停用 | ACTIVE |
**响应** `统一响应结果«分页结果«产品线VO»»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `分页结果«产品线VO»` | | 响应数据 |
|   `page` | `int` | | 当前页码 |
|   `pageSize` | `int` | | 每页条数 |
|   `records` | `产品线VO[]` | | 数据列表 |
|     `coverImageUrl` | `string` | | 封面图URL |
|     `createBy` | `string` | | 创建人ID |
|     `createTime` | `string` | | 创建时间 |
|     `description` | `string` | | 产品线描述 |
|     `lineId` | `string` | | 产品线ID |
|     `name` | `string` | | 产品线名称 |
|     `productCount` | `int` | | 关联产品数量 |
|     `sortOrder` | `int` | | 排序序号 |
|     `status` | `string` | | 状态：ACTIVE=启用 INACTIVE=停用 |
|     `updateTime` | `string` | | 更新时间 |
|   `total` | `int` | | 总记录数 |
| `message` | `string` | | 响应消息 |
---
### `GET` /admin/product/line/{lineId}
**产品线详情**
获取指定产品线的完整信息。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `lineId` | `integer` | | 产品线ID |
**响应** `统一响应结果«产品线VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `产品线VO` | | 响应数据 |
|   `coverImageUrl` | `string` | | 封面图URL |
|   `createBy` | `string` | | 创建人ID |
|   `createTime` | `string` | | 创建时间 |
|   `description` | `string` | | 产品线描述 |
|   `lineId` | `string` | | 产品线ID |
|   `name` | `string` | | 产品线名称 |
|   `productCount` | `int` | | 关联产品数量 |
|   `sortOrder` | `int` | | 排序序号 |
|   `status` | `string` | | 状态：ACTIVE=启用 INACTIVE=停用 |
|   `updateTime` | `string` | | 更新时间 |
| `message` | `string` | | 响应消息 |
---
### `PUT` /admin/product/line/{lineId}
**更新产品线**
更新产品线名称、描述、状态等信息。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `lineId` | `integer` | | 产品线ID |
**请求体** `更新产品线请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `coverImageUrl` | `string` | | 封面图URL |
| `description` | `string` | | 产品线描述 |
| `name` | `string` | | 产品线名称 |
| `sortOrder` | `int` | | 排序序号 |
| `status` | `string` | | 产品线状态：ACTIVE=启用 INACTIVE=停用 |
**响应** `统一响应结果«产品线VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `产品线VO` | | 响应数据 |
|   `coverImageUrl` | `string` | | 封面图URL |
|   `createBy` | `string` | | 创建人ID |
|   `createTime` | `string` | | 创建时间 |
|   `description` | `string` | | 产品线描述 |
|   `lineId` | `string` | | 产品线ID |
|   `name` | `string` | | 产品线名称 |
|   `productCount` | `int` | | 关联产品数量 |
|   `sortOrder` | `int` | | 排序序号 |
|   `status` | `string` | | 状态：ACTIVE=启用 INACTIVE=停用 |
|   `updateTime` | `string` | | 更新时间 |
| `message` | `string` | | 响应消息 |
---
### `DELETE` /admin/product/line/{lineId}
**删除产品线**
删除产品线（软删除）。已关联产品的产品线仍可删除，但关联产品的产品线字段不会被清空。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `lineId` | `integer` | | 产品线ID |
**响应** `统一响应结果«Void»`
---
## 定价与费用管理
### `POST` /admin/product/item/{productId}/cost-item
**添加费用项**
添加产品的费用包含/不包含说明项。
用于在产品详情页展示"费用包含"和"费用不包含"信息。
仅用于前端展示，不参与报价计算。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `productId` | `integer` | | 产品ID |
**请求体** `成本项请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `category` | `string` | 是 | 成本项类别：HOTEL/SCENIC/VEHICLE/ACTIVITY/SERVICE/DINING/OTHER |
| `description` | `string` | | 成本项描述 |
| `sortOrder` | `int` | | 排序序号 |
| `title` | `string` | 是 | 成本项标题 |
| `type` | `string` | 是 | 成本项类型：INCLUDED=费用包含 EXCLUDED=费用不含 SELF_PAY=自理费用 |
**响应** `统一响应结果«产品成本项VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `产品成本项VO` | | 响应数据 |
|   `category` | `string` | | 成本项类别：HOTEL/SCENIC/VEHICLE/ACTIVITY/SERVICE/DINING/OTHER |
|   `description` | `string` | | 成本项描述 |
|   `id` | `string` | | 成本项ID |
|   `sortOrder` | `int` | | 排序序号 |
|   `title` | `string` | | 成本项标题 |
|   `type` | `string` | | 成本项类型：INCLUDED=费用包含 EXCLUDED=费用不含 SELF_PAY=自理费用 |
| `message` | `string` | | 响应消息 |
---
### `PUT` /admin/product/item/{productId}/cost-item/{itemId}
**更新费用项**
更新费用包含/不包含说明项的内容。仅用于前端展示，不参与报价计算。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `itemId` | `integer` | | 费用项ID |
| `productId` | `integer` | | 产品ID |
**请求体** `成本项请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `category` | `string` | 是 | 成本项类别：HOTEL/SCENIC/VEHICLE/ACTIVITY/SERVICE/DINING/OTHER |
| `description` | `string` | | 成本项描述 |
| `sortOrder` | `int` | | 排序序号 |
| `title` | `string` | 是 | 成本项标题 |
| `type` | `string` | 是 | 成本项类型：INCLUDED=费用包含 EXCLUDED=费用不含 SELF_PAY=自理费用 |
**响应** `统一响应结果«产品成本项VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `产品成本项VO` | | 响应数据 |
|   `category` | `string` | | 成本项类别：HOTEL/SCENIC/VEHICLE/ACTIVITY/SERVICE/DINING/OTHER |
|   `description` | `string` | | 成本项描述 |
|   `id` | `string` | | 成本项ID |
|   `sortOrder` | `int` | | 排序序号 |
|   `title` | `string` | | 成本项标题 |
|   `type` | `string` | | 成本项类型：INCLUDED=费用包含 EXCLUDED=费用不含 SELF_PAY=自理费用 |
| `message` | `string` | | 响应消息 |
---
### `DELETE` /admin/product/item/{productId}/cost-item/{itemId}
**删除费用项**
删除费用包含/不包含说明项。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `itemId` | `integer` | | 费用项ID |
| `productId` | `integer` | | 产品ID |
**响应** `统一响应结果«Void»`
---
### `GET` /admin/product/item/{productId}/cost-items
**获取费用项列表**
获取产品的所有费用包含/不包含说明项列表。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `productId` | `integer` | | 产品ID |
**响应** `统一响应结果«List«产品成本项VO»»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `产品成本项VO[]` | | 响应数据 |
|   `category` | `string` | | 成本项类别：HOTEL/SCENIC/VEHICLE/ACTIVITY/SERVICE/DINING/OTHER |
|   `description` | `string` | | 成本项描述 |
|   `id` | `string` | | 成本项ID |
|   `sortOrder` | `int` | | 排序序号 |
|   `title` | `string` | | 成本项标题 |
|   `type` | `string` | | 成本项类型：INCLUDED=费用包含 EXCLUDED=费用不含 SELF_PAY=自理费用 |
| `message` | `string` | | 响应消息 |
---
### `POST` /admin/product/item/{productId}/custom-fee
**添加自定义费用**
添加产品级别的自定义费用项，直接设置金额，参与成本自动计算。
与额外成本关联不同，自定义费用不关联资源服务的费用项，而是直接指定费用名称和金额。
适用于临时性或一次性的费用。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `productId` | `integer` | | 产品ID |
**请求体** `自定义费用项请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `description` | `string` | | 费用说明 |
| `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
| `feeAmount` | `number` | | 费用金额 |
| `feeName` | `string` | 是 | 费用项名称 |
| `feeUnit` | `string` | | 费用单位 |
| `sortOrder` | `int` | | 排序序号 |
**响应** `统一响应结果«产品自定义费用项VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `产品自定义费用项VO` | | 响应数据 |
|   `description` | `string` | | 费用说明 |
|   `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
|   `feeAmount` | `number` | | 费用金额 |
|   `feeName` | `string` | | 费用项名称 |
|   `feeUnit` | `string` | | 费用单位 |
|   `id` | `string` | | 费用项ID |
|   `sortOrder` | `int` | | 排序序号 |
| `message` | `string` | | 响应消息 |
---
### `PUT` /admin/product/item/{productId}/custom-fee/{feeId}
**更新自定义费用**
更新自定义费用项的名称、金额等信息。修改后会影响成本自动计算结果。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `feeId` | `integer` | | 自定义费用ID |
| `productId` | `integer` | | 产品ID |
**请求体** `自定义费用项请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `description` | `string` | | 费用说明 |
| `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
| `feeAmount` | `number` | | 费用金额 |
| `feeName` | `string` | 是 | 费用项名称 |
| `feeUnit` | `string` | | 费用单位 |
| `sortOrder` | `int` | | 排序序号 |
**响应** `统一响应结果«产品自定义费用项VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `产品自定义费用项VO` | | 响应数据 |
|   `description` | `string` | | 费用说明 |
|   `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
|   `feeAmount` | `number` | | 费用金额 |
|   `feeName` | `string` | | 费用项名称 |
|   `feeUnit` | `string` | | 费用单位 |
|   `id` | `string` | | 费用项ID |
|   `sortOrder` | `int` | | 排序序号 |
| `message` | `string` | | 响应消息 |
---
### `DELETE` /admin/product/item/{productId}/custom-fee/{feeId}
**删除自定义费用**
删除自定义费用项。删除后该费用不再计入成本自动计算。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `feeId` | `integer` | | 自定义费用ID |
| `productId` | `integer` | | 产品ID |
**响应** `统一响应结果«Void»`
---
### `GET` /admin/product/item/{productId}/custom-fees
**获取自定义费用列表**
获取产品的所有自定义费用项列表。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `productId` | `integer` | | 产品ID |
**响应** `统一响应结果«List«产品自定义费用项VO»»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `产品自定义费用项VO[]` | | 响应数据 |
|   `description` | `string` | | 费用说明 |
|   `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
|   `feeAmount` | `number` | | 费用金额 |
|   `feeName` | `string` | | 费用项名称 |
|   `feeUnit` | `string` | | 费用单位 |
|   `id` | `string` | | 费用项ID |
|   `sortOrder` | `int` | | 排序序号 |
| `message` | `string` | | 响应消息 |
---
### `POST` /admin/product/item/{productId}/extra-cost
**添加额外成本关联**
关联资源服务中的费用项（cost_item）到产品，参与成本自动计算。
额外成本是指不包含在行程节点中、但需要计入总成本的费用。
例如：导游服务费、保险费、通讯费等固定运营开支。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `productId` | `integer` | | 产品ID |
**请求体** `额外成本请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `costItemId` | `long` | 是 | 额外成本项ID（关联费用项资源） |
| `daily` | `boolean` | | 是否按天计算：true=按天计算(乘以天数) false=整个行程一次 |
| `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
| `quantity` | `int` | | 数量 |
| `sortOrder` | `int` | | 排序序号 |
**响应** `统一响应结果«产品额外成本VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `产品额外成本VO` | | 响应数据 |
|   `applyRole` | `string` | | 适用角色 |
|   `categoryCode` | `string` | | 费用类别编码 |
|   `costItemId` | `string` | | 费用项ID |
|   `costItemName` | `string` | | 费用项名称 |
|   `daily` | `boolean` | | 是否按天计算：true=按天计算(乘以天数) false=整个行程一次 |
|   `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
|   `id` | `string` | | 记录ID |
|   `quantity` | `int` | | 数量 |
|   `sortOrder` | `int` | | 排序序号 |
|   `unit` | `string` | | 单位 |
|   `unitPrice` | `number` | | 单价 |
| `message` | `string` | | 响应消息 |
---
### `PUT` /admin/product/item/{productId}/extra-cost/{ecId}
**更新额外成本关联**
更新额外成本关联的费用项、数量等信息。修改后会影响成本自动计算结果。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `ecId` | `integer` | | 额外成本ID |
| `productId` | `integer` | | 产品ID |
**请求体** `额外成本请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `costItemId` | `long` | 是 | 额外成本项ID（关联费用项资源） |
| `daily` | `boolean` | | 是否按天计算：true=按天计算(乘以天数) false=整个行程一次 |
| `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
| `quantity` | `int` | | 数量 |
| `sortOrder` | `int` | | 排序序号 |
**响应** `统一响应结果«产品额外成本VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `产品额外成本VO` | | 响应数据 |
|   `applyRole` | `string` | | 适用角色 |
|   `categoryCode` | `string` | | 费用类别编码 |
|   `costItemId` | `string` | | 费用项ID |
|   `costItemName` | `string` | | 费用项名称 |
|   `daily` | `boolean` | | 是否按天计算：true=按天计算(乘以天数) false=整个行程一次 |
|   `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
|   `id` | `string` | | 记录ID |
|   `quantity` | `int` | | 数量 |
|   `sortOrder` | `int` | | 排序序号 |
|   `unit` | `string` | | 单位 |
|   `unitPrice` | `number` | | 单价 |
| `message` | `string` | | 响应消息 |
---
### `DELETE` /admin/product/item/{productId}/extra-cost/{ecId}
**删除额外成本关联**
删除额外成本关联记录。删除后该费用项不再计入成本自动计算。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `ecId` | `integer` | | 额外成本ID |
| `productId` | `integer` | | 产品ID |
**响应** `统一响应结果«Void»`
---
### `GET` /admin/product/item/{productId}/extra-costs
**获取额外成本关联列表**
获取产品关联的所有额外成本项列表，包含费用项名称、金额等信息。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `productId` | `integer` | | 产品ID |
**响应** `统一响应结果«List«产品额外成本VO»»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `产品额外成本VO[]` | | 响应数据 |
|   `applyRole` | `string` | | 适用角色 |
|   `categoryCode` | `string` | | 费用类别编码 |
|   `costItemId` | `string` | | 费用项ID |
|   `costItemName` | `string` | | 费用项名称 |
|   `daily` | `boolean` | | 是否按天计算：true=按天计算(乘以天数) false=整个行程一次 |
|   `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
|   `id` | `string` | | 记录ID |
|   `quantity` | `int` | | 数量 |
|   `sortOrder` | `int` | | 排序序号 |
|   `unit` | `string` | | 单位 |
|   `unitPrice` | `number` | | 单价 |
| `message` | `string` | | 响应消息 |
---
### `GET` /admin/product/item/{productId}/price-calendar
**获取月度价格日历**
获取指定月份的价格日历数据列表。
每条数据包含：日期、成人售价/成本价、儿童售价/成本价、库存、状态（OPEN/CLOSED）等。
**CORE/GROUP 产品**：价格为单人价格，按人头 × 价格计算总价。
**CUSTOM/ROUTE 产品**：价格为整单总价，不乘以人头数。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `productId` | `integer` | | 产品ID |
**查询参数**
| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `month` | `integer(int32)` | | 月份 | |
| `year` | `integer(int32)` | | 年份 | |
**响应** `统一响应结果«List«产品价格日历VO»»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `产品价格日历VO[]` | | 响应数据 |
|   `adultCostPrice` | `number` | | 成人成本价 |
|   `adultProfit` | `number` | | 成人利润 |
|   `adultSellPrice` | `number` | | 成人售价 |
|   `childCostPrice` | `number` | | 儿童成本价 |
|   `childProfit` | `number` | | 儿童利润 |
|   `childSellPrice` | `number` | | 儿童售价 |
|   `costAutoCalc` | `boolean` | | 是否自动计算成本 |
|   `date` | `string` | | 日期 |
|   `id` | `string` | | 价格日历ID |
|   `profitRate` | `number` | | 利润率（百分比） |
|   `remark` | `string` | | 备注 |
|   `sold` | `int` | | 已售数量 |
|   `status` | `string` | | 状态：OPEN=开放 CLOSED=关闭 |
|   `stock` | `int` | | 库存数量 |
| `message` | `string` | | 响应消息 |
---
### `POST` /admin/product/item/{productId}/price-calendar
**设置单日价格**
设置或更新指定日期的价格和库存。如果该日期已有记录则更新，否则新建。
可设置成人售价/成本价、儿童售价/成本价、库存数量、状态（OPEN/CLOSED）。
状态为 CLOSED 的日期不会出现在小程序端的可选日期中。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `productId` | `integer` | | 产品ID |
**请求体** `价格日历请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `adultCostPrice` | `number` | | 成人成本价 |
| `adultCount` | `int` | | 成人人数（GROUP产品自动测算用） |
| `adultSellPrice` | `number` | | 成人售价 |
| `childCostPrice` | `number` | | 儿童成本价 |
| `childSellPrice` | `number` | | 儿童售价 |
| `costAutoCalc` | `boolean` | | 是否自动计算成本（true时重新测算会自动更新此日期的价格） |
| `date` | `string` | 是 | 日期 |
| `remark` | `string` | | 备注 |
| `status` | `string` | | 状态：OPEN=开放预订 CLOSED=关闭（不可预订） |
| `stock` | `int` | | 库存数量（CORE/GROUP按人头扣减，CUSTOM/ROUTE按单扣减） |
**响应** `统一响应结果«产品价格日历VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `产品价格日历VO` | | 响应数据 |
|   `adultCostPrice` | `number` | | 成人成本价 |
|   `adultProfit` | `number` | | 成人利润 |
|   `adultSellPrice` | `number` | | 成人售价 |
|   `childCostPrice` | `number` | | 儿童成本价 |
|   `childProfit` | `number` | | 儿童利润 |
|   `childSellPrice` | `number` | | 儿童售价 |
|   `costAutoCalc` | `boolean` | | 是否自动计算成本 |
|   `date` | `string` | | 日期 |
|   `id` | `string` | | 价格日历ID |
|   `profitRate` | `number` | | 利润率（百分比） |
|   `remark` | `string` | | 备注 |
|   `sold` | `int` | | 已售数量 |
|   `status` | `string` | | 状态：OPEN=开放 CLOSED=关闭 |
|   `stock` | `int` | | 库存数量 |
| `message` | `string` | | 响应消息 |
---
### `POST` /admin/product/item/{productId}/price-calendar/auto-calc
**自动计算成本并同步到价格日历**
根据出发日期和人数，自动计算成本并将结果写入价格日历。
与测算预览不同，此接口会实际更新价格日历数据。
计算逻辑：查询各资源的价格日历 → 汇总成本 → 应用公式和利润规则 → 写入结果。
**关联字典**：
- vehicle_type（车型）：车辆费用成本计算
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `productId` | `integer` | | 产品ID |
**请求体** `报价请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `adultCount` | `int` | 是 | 成人人数 |
| `babyCount` | `int` | | 婴儿人数（按固定 babyPrice 计算） |
| `childCount` | `int` | | 儿童人数（占床，按儿童价计算） |
| `childNeedBed` | `boolean` | | 儿童是否加床（true 时额外加收 childWithBed 费用） |
| `departureDate` | `string` | 是 | 出发日期 |
| `youngChildCount` | `int` | | 小童人数（不占床，按儿童价 × childDiscountPercent 折扣比例计算） |
**响应** `统一响应结果«报价结果VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `报价结果VO` | | 响应数据 |
|   `customFeeCost` | `number` | | 自定义费用合计（定制产品） |
|   `dayCosts` | `每日成本明细[]` | | 每日成本明细列表 |
|     `activityCost` | `number` | | 活动成本 |
|     `dayCostTotal` | `number` | | 当日成本合计 |
|     `dayNumber` | `int` | | 天数编号 |
|     `diningCost` | `number` | | 餐饮成本 |
|     `extraCost` | `number` | | 额外成本 |
|     `hotelCost` | `number` | | 酒店成本 |
|     `scenicCost` | `number` | | 景区成本 |
|     `serviceCost` | `number` | | 服务成本 |
|     `staffCost` | `number` | | 人员成本 |
|     `vehicleCost` | `number` | | 车辆成本 |
|   `extraCostItems` | `额外成本明细项[]` | | 额外成本明细列表 |
|     `costItemName` | `string` | | 成本项名称 |
|     `daily` | `boolean` | | 是否按天计算 |
|     `days` | `int` | | 天数（按天计算时） |
|     `quantity` | `int` | | 数量 |
|     `subtotal` | `number` | | 小计金额 |
|     `unitPrice` | `number` | | 单价 |
|   `extraCostPerPerson` | `number` | | 每人额外成本 |
|   `extraCostTotal` | `number` | | 额外成本合计 |
|   `familyCosts` | `家庭成本明细[]` | | 家庭分组成本明细（定制产品，有分组时返回） |
|     `activityCost` | `number` | | 活动成本 |
|     `adultCount` | `int` | | 成人数 |
|     `babyCost` | `number` | | 婴儿固定成本 |
|     `babyCount` | `int` | | 幼童数 |
|     `childCount` | `int` | | 儿童数 |
|     `costPerPerson` | `number` | | 人均成本（家庭成本/付费人头） |
|     `customFeeCost` | `number` | | 自定义费用成本 |
|     `extraCost` | `number` | | 额外成本 |
|     `familyId` | `string` | | 家庭ID |
|     `familyName` | `string` | | 家庭名称 |
|     `headcount` | `int` | | 人头数 |
|     `hotelCost` | `number` | | 酒店成本 |
|     `insuranceCost` | `number` | | 保险成本 |
|     `payingHeadcount` | `int` | | 付费人头数（不含幼童） |
|     `personCosts` | `每人成本明细[]` | | 每人分项成本列表 |
|     `scenicCost` | `number` | | 景区成本 |
|     `sellPricePerPerson` | `number` | | 人均售价（家庭售价/付费人头） |
|     `serviceCost` | `number` | | 服务成本 |
|     `staffCost` | `number` | | 人员成本 |
|     `suppliesCost` | `number` | | 物资成本 |
|     `totalCost` | `number` | | 家庭成本合计 |
|     `totalProfit` | `number` | | 家庭利润合计 |
|     `totalSellPrice` | `number` | | 家庭售价合计 |
|     `vehicleCost` | `number` | | 车辆成本 |
|     `youngChildCount` | `int` | | 小童数 |
|   `grandTotalCost` | `number` | | 总成本合计 |
|   `grandTotalProfit` | `number` | | 总利润合计 |
|   `grandTotalSellPrice` | `number` | | 总售价合计 |
|   `insuranceFee` | `number` | | 保险费用 |
|   `profitRate` | `number` | | 利润率（百分比） |
|   `staffCost` | `number` | | 人员成本 |
|   `suppliesCost` | `number` | | 物资成本 |
|   `totalAdultCost` | `number` | | 成人总成本 |
|   `totalAdultProfit` | `number` | | 成人总利润 |
|   `totalAdultSellPrice` | `number` | | 成人总售价 |
|   `totalBabyCost` | `number` | | 婴儿总成本 |
|   `totalBabySellPrice` | `number` | | 婴儿总售价 |
|   `totalChildCost` | `number` | | 儿童总成本 |
|   `totalChildSellPrice` | `number` | | 儿童总售价 |
|   `totalYoungChildCost` | `number` | | 小童总成本 |
|   `totalYoungChildSellPrice` | `number` | | 小童总售价 |
|   `warnings` | `string[]` | | 警告信息列表 |
| `message` | `string` | | 响应消息 |
---
### `POST` /admin/product/item/{productId}/price-calendar/batch
**批量设置价格**
批量设置日期范围内的价格和库存，支持按星期筛选。
指定 startDate 和 endDate 日期范围，可选 selectedWeekdays 过滤星期几。
示例：设置5月1日-5月31日的工作日（周一到周五=[1,2,3,4,5]）价格。
selectedWeekdays 为空时，范围内所有日期都会被设置。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `productId` | `integer` | | 产品ID |
**请求体** `批量设置价格日历请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `adultCostPrice` | `number` | | 成人成本价 |
| `adultSellPrice` | `number` | | 成人售价 |
| `childCostPrice` | `number` | | 儿童成本价 |
| `childSellPrice` | `number` | | 儿童售价 |
| `costAutoCalc` | `boolean` | | 是否自动计算成本 |
| `endDate` | `string` | 是 | 结束日期 |
| `remark` | `string` | | 备注 |
| `selectedWeekdays` | `int[]` | | 选中的星期(1=周一...7=周日)，为空或包含全部则不过滤 |
| `startDate` | `string` | 是 | 开始日期 |
| `status` | `string` | | 状态：OPEN=开放 CLOSED=关闭 |
| `stock` | `int` | | 库存数量 |
**响应** `统一响应结果«List«产品价格日历VO»»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `产品价格日历VO[]` | | 响应数据 |
|   `adultCostPrice` | `number` | | 成人成本价 |
|   `adultProfit` | `number` | | 成人利润 |
|   `adultSellPrice` | `number` | | 成人售价 |
|   `childCostPrice` | `number` | | 儿童成本价 |
|   `childProfit` | `number` | | 儿童利润 |
|   `childSellPrice` | `number` | | 儿童售价 |
|   `costAutoCalc` | `boolean` | | 是否自动计算成本 |
|   `date` | `string` | | 日期 |
|   `id` | `string` | | 价格日历ID |
|   `profitRate` | `number` | | 利润率（百分比） |
|   `remark` | `string` | | 备注 |
|   `sold` | `int` | | 已售数量 |
|   `status` | `string` | | 状态：OPEN=开放 CLOSED=关闭 |
|   `stock` | `int` | | 库存数量 |
| `message` | `string` | | 响应消息 |
---
### `POST` /admin/product/item/{productId}/price-calendar/calc-preview
**测算预览（不写入数据库）**
根据行程中的资源价格日历，自动计算指定日期的成本价和售价，仅预览不保存。
用于在设置价格日历前预览自动计算的结果。
计算逻辑：汇总当天所有行程节点关联资源的价格 → 应用公式引擎 → 加上利润。
GROUP 产品需要传 adultCount 参数（影响均摊计算）。
**关联字典**：
- vehicle_type（车型）：车辆费用成本测算
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `productId` | `integer` | | 产品ID |
**请求体** `成本预览请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `adultCount` | `int` | | 成人人数（GROUP产品用） |
| `date` | `string` | 是 | 日期 |
**响应** `统一响应结果«成本预览VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `成本预览VO` | | 响应数据 |
|   `adultCostPrice` | `number` | | 成人成本价 |
|   `adultSellPrice` | `number` | | 成人售价 |
|   `childCostPrice` | `number` | | 儿童成本价 |
|   `childSellPrice` | `number` | | 儿童售价 |
|   `warnings` | `string[]` | | 警告信息列表 |
| `message` | `string` | | 响应消息 |
---
### `POST` /admin/product/item/{productId}/price-calendar/recalculate
**重新测算所有自动测算日期的价格**
重新计算价格日历中所有 costAutoCalc=true 的日期的成本价和售价。
适用场景：资源价格调整后，批量刷新所有自动计算的价格日历。
返回更新的日期数量和详情。手动设置的价格（costAutoCalc=false）不受影响。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `productId` | `integer` | | 产品ID |
**响应** `统一响应结果«Map«string,object»»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `object` | | 响应数据 |
| `message` | `string` | | 响应消息 |
---
### `GET` /admin/product/item/{productId}/pricing
**获取定价规则**
获取产品的定价配置，包括定价模式、利润设置、儿童/婴儿价格、支付方式等。
如果产品尚未设置定价规则，返回 null。
**关联字典**：
- vehicle_type（车型）：费用配置中车辆相关成本显示
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `productId` | `integer` | | 产品ID |
**响应** `统一响应结果«产品定价配置VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `产品定价配置VO` | | 响应数据 |
|   `adultExtraBed` | `number` | | 成人加床费 |
|   `babyPrice` | `number` | | 婴儿价 |
|   `balanceDueDays` | `int` | | 尾款支付截止天数（出发前N天） |
|   `childDiscountPercent` | `number` | | 儿童折扣百分比 |
|   `childNoBed` | `number` | | 儿童不占床价 |
|   `childWithBed` | `number` | | 儿童占床价 |
|   `companionPrice` | `number` | | 陪同人员价格 |
|   `customTotalPrice` | `number` | | 定制产品总价（CUSTOM模式下使用） |
|   `depositAmount` | `number` | | 定金金额 |
|   `depositRatio` | `int` | | 定金比例（百分比） |
|   `extraCostPerPerson` | `number` | | 每人额外成本 |
|   `insuranceFee` | `number` | | 保险费用 |
|   `markupPercent` | `number` | | 加价百分比（PERCENT模式下使用） |
|   `maxGroupSize` | `int` | | 最大成团人数 |
|   `mealBudget` | `number` | | 餐费预算 |
|   `minGroupSize` | `int` | | 最小成团人数 |
|   `paymentType` | `string` | | 支付方式：FULL=全款 DEPOSIT=定金+尾款 |
|   `pricingId` | `string` | | 定价配置ID |
|   `pricingMode` | `string` | | 定价模式：AUTO=自动计算 MANUAL=手动定价 CUSTOM=定制定价 |
|   `productId` | `string` | | 产品ID |
|   `profitAmount` | `number` | | 利润金额（FIXED模式下使用） |
|   `profitMode` | `string` | | 利润模式：FIXED=固定金额 PERCENT=百分比 |
|   `singleRoomDiff` | `number` | | 单房差 |
|   `vehicleModelIds` | `string[]` | | 车型ID列表 |
|   `vehicleWarning` | `string` | | 车辆绑定警告信息（为空表示绑定成功） |
| `message` | `string` | | 响应消息 |
---
### `POST` /admin/product/item/{productId}/pricing
**保存定价规则**
保存或更新产品的定价配置（一个产品仅一条定价记录，重复调用为覆盖更新）。
**定价模式**：
- AUTO：自动计算，通过公式引擎根据行程资源价格自动测算成本和售价
- MANUAL：手动定价，直接在价格日历中手动设置每日价格
- CUSTOM：定制定价，设置整单总价（customTotalPrice），不按人头
**利润模式**（AUTO 模式下生效）：
- FIXED：固定金额加价，售价 = 成本 + profitAmount
- PERCENT：百分比加价，售价 = 成本 × (1 + markupPercent/100)
**支付方式**：FULL=全款支付，DEPOSIT=定金+尾款（需设置 depositRatio 或 depositAmount）
**关联字典**：
- vehicle_type（车型）：费用配置中车辆相关成本计算
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `productId` | `integer` | | 产品ID |
**请求体** `定价配置请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `adultExtraBed` | `number` | | 成人加床费 |
| `babyPrice` | `number` | | 婴儿固定价格（不随日期变化） |
| `balanceDueDays` | `int` | | 尾款支付截止天数（出发前N天必须支付尾款，超时可能取消订单） |
| `childDiscountPercent` | `number` | | 小童折扣百分比（小童价=儿童价×此百分比/100，如70表示打7折） |
| `childNoBed` | `number` | | 儿童不占床价（暂未使用，预留字段） |
| `childWithBed` | `number` | | 儿童加床费（childNeedBed=true时额外加收的费用） |
| `companionPrice` | `number` | | 陪同人员价格 |
| `customTotalPrice` | `number` | | 定制产品总价（CUSTOM定价模式下使用，代表整单总价） |
| `depositAmount` | `number` | | 定金金额（固定金额，与depositRatio二选一） |
| `depositRatio` | `int` | | 定金比例（百分比，如30代表30%。与depositAmount二选一，优先使用比例） |
| `extraCostPerPerson` | `number` | | 每人额外成本 |
| `insuranceFee` | `number` | | 保险费用 |
| `markupPercent` | `number` | | 加价百分比（PERCENT模式下使用） |
| `maxGroupSize` | `int` | | 最大成团人数（CORE/GROUP产品用） |
| `mealBudget` | `number` | | 餐费预算 |
| `minGroupSize` | `int` | | 最小成团人数（CORE/GROUP产品用，影响均摊成本计算） |
| `paymentType` | `string` | | 支付方式：FULL=全款支付 DEPOSIT=定金+尾款分期支付 |
| `pricingMode` | `string` | | 定价模式：AUTO=根据行程资源价格自动计算 MANUAL=手动在价格日历设置每日价格 CUSTOM=定制产品整单定价 |
| `profitAmount` | `number` | | 利润金额（FIXED模式下使用） |
| `profitMode` | `string` | | 利润模式（AUTO模式下生效）：FIXED=在成本基础上加固定金额 PERCENT=在成本基础上按百分比加价 |
| `singleRoomDiff` | `number` | | 单房差 |
| `vehicleModelIds` | `long[]` | | 车型ID列表 |
**响应** `统一响应结果«产品定价配置VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `产品定价配置VO` | | 响应数据 |
|   `adultExtraBed` | `number` | | 成人加床费 |
|   `babyPrice` | `number` | | 婴儿价 |
|   `balanceDueDays` | `int` | | 尾款支付截止天数（出发前N天） |
|   `childDiscountPercent` | `number` | | 儿童折扣百分比 |
|   `childNoBed` | `number` | | 儿童不占床价 |
|   `childWithBed` | `number` | | 儿童占床价 |
|   `companionPrice` | `number` | | 陪同人员价格 |
|   `customTotalPrice` | `number` | | 定制产品总价（CUSTOM模式下使用） |
|   `depositAmount` | `number` | | 定金金额 |
|   `depositRatio` | `int` | | 定金比例（百分比） |
|   `extraCostPerPerson` | `number` | | 每人额外成本 |
|   `insuranceFee` | `number` | | 保险费用 |
|   `markupPercent` | `number` | | 加价百分比（PERCENT模式下使用） |
|   `maxGroupSize` | `int` | | 最大成团人数 |
|   `mealBudget` | `number` | | 餐费预算 |
|   `minGroupSize` | `int` | | 最小成团人数 |
|   `paymentType` | `string` | | 支付方式：FULL=全款 DEPOSIT=定金+尾款 |
|   `pricingId` | `string` | | 定价配置ID |
|   `pricingMode` | `string` | | 定价模式：AUTO=自动计算 MANUAL=手动定价 CUSTOM=定制定价 |
|   `productId` | `string` | | 产品ID |
|   `profitAmount` | `number` | | 利润金额（FIXED模式下使用） |
|   `profitMode` | `string` | | 利润模式：FIXED=固定金额 PERCENT=百分比 |
|   `singleRoomDiff` | `number` | | 单房差 |
|   `vehicleModelIds` | `string[]` | | 车型ID列表 |
|   `vehicleWarning` | `string` | | 车辆绑定警告信息（为空表示绑定成功） |
| `message` | `string` | | 响应消息 |
---
## 定价公式管理
### `POST` /admin/product/formula/group
**创建公式组**
创建一个新的定价公式组。创建后默认为未激活状态。
公式组编码（groupCode）在同一产品类型下必须唯一。
建议命名规范：{产品类型}_PRICING_V{版本号}，如 CORE_PRICING_V2。
**关联字典**：
- product_type（产品类型，公式组所属类型）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品
**请求体** `公式组请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `description` | `string` | | 描述 |
| `groupCode` | `string` | 是 | 公式组编码 |
| `groupName` | `string` | 是 | 公式组名称 |
| `productType` | `string` | 是 | 适用产品类型：CORE/ROUTE/CUSTOM/GROUP |
**响应** `统一响应结果«公式组VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `公式组VO` | | 响应数据 |
|   `createTime` | `string` | | 创建时间 |
|   `description` | `string` | | 描述 |
|   `groupCode` | `string` | | 公式组编码 |
|   `groupId` | `string` | | 公式组ID |
|   `groupName` | `string` | | 公式组名称 |
|   `isActive` | `boolean` | | 是否激活 |
|   `productType` | `string` | | 适用产品类型 |
|   `stepCount` | `int` | | 步骤数量 |
|   `version` | `int` | | 版本号 |
| `message` | `string` | | 响应消息 |
---
### `GET` /admin/product/formula/group/list
**公式组列表**
获取定价公式组列表，可按产品类型筛选。
**公式引擎说明**：定价公式用于自动计算产品的成本价和售价。
每种产品类型可以有多个公式组，但同一时间只能有一个激活的公式组。
公式组包含多个步骤，按顺序执行，每步计算一个中间变量或最终结果。
**关联字典**：
- product_type（产品类型，筛选条件）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品
**查询参数**
| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `productType` | `string` | | productType | |
**响应** `统一响应结果«List«公式组VO»»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `公式组VO[]` | | 响应数据 |
|   `createTime` | `string` | | 创建时间 |
|   `description` | `string` | | 描述 |
|   `groupCode` | `string` | | 公式组编码 |
|   `groupId` | `string` | | 公式组ID |
|   `groupName` | `string` | | 公式组名称 |
|   `isActive` | `boolean` | | 是否激活 |
|   `productType` | `string` | | 适用产品类型 |
|   `stepCount` | `int` | | 步骤数量 |
|   `version` | `int` | | 版本号 |
| `message` | `string` | | 响应消息 |
---
### `GET` /admin/product/formula/group/{groupId}
**公式组详情**
获取公式组完整信息。
**关联字典**：
- product_type（产品类型）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `groupId` | `integer` | 是 | groupId |
**响应** `统一响应结果«公式组VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `公式组VO` | | 响应数据 |
|   `createTime` | `string` | | 创建时间 |
|   `description` | `string` | | 描述 |
|   `groupCode` | `string` | | 公式组编码 |
|   `groupId` | `string` | | 公式组ID |
|   `groupName` | `string` | | 公式组名称 |
|   `isActive` | `boolean` | | 是否激活 |
|   `productType` | `string` | | 适用产品类型 |
|   `stepCount` | `int` | | 步骤数量 |
|   `version` | `int` | | 版本号 |
| `message` | `string` | | 响应消息 |
---
### `PUT` /admin/product/formula/group/{groupId}
**更新公式组**
更新公式组信息。
**关联字典**：
- product_type（产品类型）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `groupId` | `integer` | 是 | groupId |
**请求体** `公式组请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `description` | `string` | | 描述 |
| `groupCode` | `string` | 是 | 公式组编码 |
| `groupName` | `string` | 是 | 公式组名称 |
| `productType` | `string` | 是 | 适用产品类型：CORE/ROUTE/CUSTOM/GROUP |
**响应** `统一响应结果«公式组VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `公式组VO` | | 响应数据 |
|   `createTime` | `string` | | 创建时间 |
|   `description` | `string` | | 描述 |
|   `groupCode` | `string` | | 公式组编码 |
|   `groupId` | `string` | | 公式组ID |
|   `groupName` | `string` | | 公式组名称 |
|   `isActive` | `boolean` | | 是否激活 |
|   `productType` | `string` | | 适用产品类型 |
|   `stepCount` | `int` | | 步骤数量 |
|   `version` | `int` | | 版本号 |
| `message` | `string` | | 响应消息 |
---
### `DELETE` /admin/product/formula/group/{groupId}
**删除公式组**
删除公式组及其下所有步骤。
**限制**：已激活的公式组不能删除，需先激活其他公式组。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `groupId` | `integer` | 是 | groupId |
**响应** `统一响应结果«Void»`
---
### `PUT` /admin/product/formula/group/{groupId}/activate
**激活公式组**
激活指定公式组，同时自动停用同产品类型下的其他公式组。
同一产品类型下只能有一个激活的公式组，激活操作具有排他性。
激活后，该产品类型的自动成本计算将使用此公式组。
**关联字典**：
- product_type（产品类型，同类型排他激活）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `groupId` | `integer` | 是 | groupId |
**响应** `统一响应结果«Void»`
---
### `GET` /admin/product/formula/group/{groupId}/steps
**公式步骤列表**
获取公式组下所有步骤，按执行顺序（executionOrder）升序排列。
步骤按顺序依次执行，前一步的输出变量可作为后续步骤的输入。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `groupId` | `integer` | 是 | groupId |
**响应** `统一响应结果«List«公式步骤VO»»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `公式步骤VO[]` | | 响应数据 |
|   `createTime` | `string` | | 创建时间 |
|   `description` | `string` | | 描述 |
|   `executionOrder` | `int` | | 执行顺序 |
|   `expression` | `string` | | 表达式 |
|   `formulaId` | `string` | | 公式ID |
|   `groupId` | `string` | | 公式组ID |
|   `inputVars` | `string` | | 输入变量(逗号分隔) |
|   `isEnabled` | `boolean` | | 是否启用 |
|   `outputVar` | `string` | | 输出变量名 |
|   `stepCode` | `string` | | 步骤编码 |
|   `stepName` | `string` | | 步骤名称 |
|   `updateTime` | `string` | | 更新时间 |
| `message` | `string` | | 响应消息 |
---
### `POST` /admin/product/formula/step
**创建公式步骤**
在公式组中创建一个计算步骤。
**表达式语法**：使用 Aviator 表达式引擎，支持数学运算、条件判断、内置函数等。
示例：`baseCost = adultCount * adultUnitCost + childCount * childUnitCost`
**输入变量**：可引用公式变量表中定义的变量，或前置步骤的输出变量。
**输出变量**：每个步骤必须指定一个输出变量名，供后续步骤引用。
**请求体** `公式步骤请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `changeNote` | `string` | | 变更说明 |
| `description` | `string` | | 描述 |
| `executionOrder` | `int` | | 执行顺序 |
| `expression` | `string` | 是 | Aviator表达式（支持数学运算、条件判断、内置函数；可引用前置步骤的输出变量和公式变量表中的变量） |
| `groupId` | `long` | 是 | 公式组ID |
| `inputVars` | `string` | | 输入变量(逗号分隔) |
| `outputVar` | `string` | 是 | 输出变量名 |
| `stepCode` | `string` | 是 | 步骤编码 |
| `stepName` | `string` | 是 | 步骤名称 |
**响应** `统一响应结果«公式步骤VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `公式步骤VO` | | 响应数据 |
|   `createTime` | `string` | | 创建时间 |
|   `description` | `string` | | 描述 |
|   `executionOrder` | `int` | | 执行顺序 |
|   `expression` | `string` | | 表达式 |
|   `formulaId` | `string` | | 公式ID |
|   `groupId` | `string` | | 公式组ID |
|   `inputVars` | `string` | | 输入变量(逗号分隔) |
|   `isEnabled` | `boolean` | | 是否启用 |
|   `outputVar` | `string` | | 输出变量名 |
|   `stepCode` | `string` | | 步骤编码 |
|   `stepName` | `string` | | 步骤名称 |
|   `updateTime` | `string` | | 更新时间 |
| `message` | `string` | | 响应消息 |
---
### `GET` /admin/product/formula/step/{formulaId}
**公式步骤详情**
获取单个公式步骤的完整信息，包含表达式、输入/输出变量、执行顺序等。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `formulaId` | `integer` | 是 | formulaId |
**响应** `统一响应结果«公式步骤VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `公式步骤VO` | | 响应数据 |
|   `createTime` | `string` | | 创建时间 |
|   `description` | `string` | | 描述 |
|   `executionOrder` | `int` | | 执行顺序 |
|   `expression` | `string` | | 表达式 |
|   `formulaId` | `string` | | 公式ID |
|   `groupId` | `string` | | 公式组ID |
|   `inputVars` | `string` | | 输入变量(逗号分隔) |
|   `isEnabled` | `boolean` | | 是否启用 |
|   `outputVar` | `string` | | 输出变量名 |
|   `stepCode` | `string` | | 步骤编码 |
|   `stepName` | `string` | | 步骤名称 |
|   `updateTime` | `string` | | 更新时间 |
| `message` | `string` | | 响应消息 |
---
### `PUT` /admin/product/formula/step/{formulaId}
**更新公式步骤**
更新公式步骤的表达式、输入/输出变量等。
每次更新会自动保存一个版本快照，可通过版本历史接口查看和回滚。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `formulaId` | `integer` | 是 | formulaId |
**请求体** `公式步骤请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `changeNote` | `string` | | 变更说明 |
| `description` | `string` | | 描述 |
| `executionOrder` | `int` | | 执行顺序 |
| `expression` | `string` | 是 | Aviator表达式（支持数学运算、条件判断、内置函数；可引用前置步骤的输出变量和公式变量表中的变量） |
| `groupId` | `long` | 是 | 公式组ID |
| `inputVars` | `string` | | 输入变量(逗号分隔) |
| `outputVar` | `string` | 是 | 输出变量名 |
| `stepCode` | `string` | 是 | 步骤编码 |
| `stepName` | `string` | 是 | 步骤名称 |
**响应** `统一响应结果«公式步骤VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `公式步骤VO` | | 响应数据 |
|   `createTime` | `string` | | 创建时间 |
|   `description` | `string` | | 描述 |
|   `executionOrder` | `int` | | 执行顺序 |
|   `expression` | `string` | | 表达式 |
|   `formulaId` | `string` | | 公式ID |
|   `groupId` | `string` | | 公式组ID |
|   `inputVars` | `string` | | 输入变量(逗号分隔) |
|   `isEnabled` | `boolean` | | 是否启用 |
|   `outputVar` | `string` | | 输出变量名 |
|   `stepCode` | `string` | | 步骤编码 |
|   `stepName` | `string` | | 步骤名称 |
|   `updateTime` | `string` | | 更新时间 |
| `message` | `string` | | 响应消息 |
---
### `DELETE` /admin/product/formula/step/{formulaId}
**删除公式步骤**
删除指定的公式步骤。删除后其他步骤的执行顺序不会自动调整。
**注意**：如果后续步骤引用了被删步骤的输出变量，执行时会报错。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `formulaId` | `integer` | 是 | formulaId |
**响应** `统一响应结果«Void»`
---
### `PUT` /admin/product/formula/step/{formulaId}/rollback/{versionNum}
**回滚公式步骤到指定版本**
将公式步骤回滚到历史版本。
回滚操作会用历史版本的表达式、变量等覆盖当前内容，并创建一个新的版本记录。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `formulaId` | `integer` | 是 | formulaId |
| `versionNum` | `integer` | 是 | versionNum |
**响应** `统一响应结果«公式步骤VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `公式步骤VO` | | 响应数据 |
|   `createTime` | `string` | | 创建时间 |
|   `description` | `string` | | 描述 |
|   `executionOrder` | `int` | | 执行顺序 |
|   `expression` | `string` | | 表达式 |
|   `formulaId` | `string` | | 公式ID |
|   `groupId` | `string` | | 公式组ID |
|   `inputVars` | `string` | | 输入变量(逗号分隔) |
|   `isEnabled` | `boolean` | | 是否启用 |
|   `outputVar` | `string` | | 输出变量名 |
|   `stepCode` | `string` | | 步骤编码 |
|   `stepName` | `string` | | 步骤名称 |
|   `updateTime` | `string` | | 更新时间 |
| `message` | `string` | | 响应消息 |
---
### `PUT` /admin/product/formula/step/{formulaId}/toggle
**启用/禁用公式步骤**
切换公式步骤的启用状态。
禁用的步骤在公式执行时会被跳过，不影响其他步骤的执行。
适用场景：临时跳过某个计算步骤进行调试或测试。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `formulaId` | `integer` | 是 | formulaId |
**响应** `统一响应结果«Void»`
---
### `GET` /admin/product/formula/step/{formulaId}/versions
**公式步骤版本历史**
获取公式步骤的所有历史版本列表，按版本号倒序。
每次更新步骤表达式会自动创建新版本，方便追溯和回滚。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `formulaId` | `integer` | 是 | formulaId |
**响应** `统一响应结果«List«公式版本历史VO»»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `公式版本历史VO[]` | | 响应数据 |
|   `changeNote` | `string` | | 变更说明 |
|   `changedBy` | `string` | | 变更人ID |
|   `createTime` | `string` | | 创建时间 |
|   `expression` | `string` | | 表达式 |
|   `formulaId` | `string` | | 公式ID |
|   `versionId` | `string` | | 版本ID |
|   `versionNum` | `int` | | 版本号 |
| `message` | `string` | | 响应消息 |
---
### `POST` /admin/product/formula/test
**测试公式执行**
使用自定义变量值测试公式组的执行结果，不影响任何业务数据。
传入公式组ID和测试变量（变量名→值的映射），返回每个步骤的执行结果。
适用于公式调试：验证表达式是否正确、计算结果是否符合预期。
如果某步骤执行出错，会在结果中标明错误信息。
**请求体** `公式测试请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `groupId` | `long` | 是 | 公式组ID |
| `variables` | `object` | 是 | 测试变量(变量名→值) |
**响应** `统一响应结果«公式测试结果VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `公式测试结果VO` | | 响应数据 |
|   `errorMessage` | `string` | | 错误信息 |
|   `finalVariables` | `object` | | 最终变量表 |
|   `stepResults` | `步骤执行结果[]` | | 各步骤执行结果 |
|     `errorMessage` | `string` | | 错误信息 |
|     `executionTimeMs` | `long` | | 执行耗时(毫秒) |
|     `expression` | `string` | | 表达式 |
|     `outputValue` | `object` | | 输出值 |
|     `outputVar` | `string` | | 输出变量名 |
|     `stepCode` | `string` | | 步骤编码 |
|     `stepName` | `string` | | 步骤名称 |
|     `success` | `boolean` | | 是否成功 |
|   `success` | `boolean` | | 是否成功 |
|   `totalTimeMs` | `long` | | 总耗时(毫秒) |
| `message` | `string` | | 响应消息 |
---
### `POST` /admin/product/formula/var
**创建公式变量**
创建公式变量定义。变量名（varName）全局唯一，建议使用驼峰命名。
可指定适用的产品类型列表（productTypes），为空则适用于所有类型。
**关联字典**：
- product_type（产品类型，变量适用范围）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品
**请求体** `公式变量请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `category` | `string` | 是 | 变量分类：INPUT/INTERMEDIATE/OUTPUT |
| `defaultValue` | `string` | | 默认值 |
| `description` | `string` | | 描述 |
| `productTypes` | `string[]` | | 适用产品类型列表 |
| `varName` | `string` | 是 | 变量名 |
| `varType` | `string` | 是 | 变量类型：DECIMAL/INTEGER/BOOLEAN/STRING |
**响应** `统一响应结果«公式变量VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `公式变量VO` | | 响应数据 |
|   `category` | `string` | | 变量分类：INPUT/INTERMEDIATE/OUTPUT |
|   `defaultValue` | `string` | | 默认值 |
|   `description` | `string` | | 描述 |
|   `productTypes` | `string[]` | | 适用产品类型列表 |
|   `varId` | `string` | | 变量ID |
|   `varName` | `string` | | 变量名 |
|   `varType` | `string` | | 变量类型：DECIMAL/INTEGER/BOOLEAN/STRING |
| `message` | `string` | | 响应消息 |
---
### `GET` /admin/product/formula/var/list
**公式变量列表**
获取公式变量列表，可按变量分类筛选。
**变量分类**：
- INPUT：输入变量，从业务数据获取（如成人人数、资源单价）
- INTERMEDIATE：中间变量，由公式步骤计算得出
- OUTPUT：输出变量，最终报价结果（如总成本、售价）
**查询参数**
| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `category` | `string` | | category | |
**响应** `统一响应结果«List«公式变量VO»»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `公式变量VO[]` | | 响应数据 |
|   `category` | `string` | | 变量分类：INPUT/INTERMEDIATE/OUTPUT |
|   `defaultValue` | `string` | | 默认值 |
|   `description` | `string` | | 描述 |
|   `productTypes` | `string[]` | | 适用产品类型列表 |
|   `varId` | `string` | | 变量ID |
|   `varName` | `string` | | 变量名 |
|   `varType` | `string` | | 变量类型：DECIMAL/INTEGER/BOOLEAN/STRING |
| `message` | `string` | | 响应消息 |
---
### `PUT` /admin/product/formula/var/{varId}
**更新公式变量**
更新公式变量定义。
**关联字典**：
- product_type（产品类型，变量适用范围）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `varId` | `integer` | 是 | varId |
**请求体** `公式变量请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `category` | `string` | 是 | 变量分类：INPUT/INTERMEDIATE/OUTPUT |
| `defaultValue` | `string` | | 默认值 |
| `description` | `string` | | 描述 |
| `productTypes` | `string[]` | | 适用产品类型列表 |
| `varName` | `string` | 是 | 变量名 |
| `varType` | `string` | 是 | 变量类型：DECIMAL/INTEGER/BOOLEAN/STRING |
**响应** `统一响应结果«公式变量VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `公式变量VO` | | 响应数据 |
|   `category` | `string` | | 变量分类：INPUT/INTERMEDIATE/OUTPUT |
|   `defaultValue` | `string` | | 默认值 |
|   `description` | `string` | | 描述 |
|   `productTypes` | `string[]` | | 适用产品类型列表 |
|   `varId` | `string` | | 变量ID |
|   `varName` | `string` | | 变量名 |
|   `varType` | `string` | | 变量类型：DECIMAL/INTEGER/BOOLEAN/STRING |
| `message` | `string` | | 响应消息 |
---
### `DELETE` /admin/product/formula/var/{varId}
**删除公式变量**
删除公式变量定义。
**注意**：如果有公式步骤引用了该变量，删除后步骤执行时会报错。建议先确认无引用再删除。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `varId` | `integer` | 是 | varId |
**响应** `统一响应结果«Void»`
---
## 家庭分组管理
### `GET` /admin/product/item/{productId}/families
**获取家庭分组列表**
获取产品的家庭分组列表，按排序序号升序。
**仅适用于 CUSTOM（定制）产品**。
家庭分组用于将定制产品的行程按家庭单位分配，每个家庭可以有不同的人数和行程安排。
行程节点通过 familyIds 字段关联到具体的家庭分组。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `productId` | `integer` | | 产品ID |
**响应** `统一响应结果«List«家庭分组VO»»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `家庭分组VO[]` | | 响应数据 |
|   `adultCount` | `int` | | 成人数 |
|   `babyCount` | `int` | | 幼童数 |
|   `childCount` | `int` | | 儿童数 |
|   `familyId` | `string` | | 家庭ID |
|   `familyName` | `string` | | 家庭名称 |
|   `sortOrder` | `int` | | 排序序号 |
|   `youngChildCount` | `int` | | 小童数 |
| `message` | `string` | | 响应消息 |
---
### `POST` /admin/product/item/{productId}/family
**添加家庭分组**
为 CUSTOM 定制产品添加一个家庭分组，指定家庭名称和各类型人数。
添加后可在行程节点中关联此家庭，实现按家庭分配行程。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `productId` | `integer` | | 产品ID |
**请求体** `家庭分组保存请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `adultCount` | `int` | | 成人数 |
| `babyCount` | `int` | | 幼童数 |
| `childCount` | `int` | | 儿童数 |
| `familyName` | `string` | 是 | 家庭名称 |
| `sortOrder` | `int` | | 排序序号 |
| `youngChildCount` | `int` | | 小童数 |
**响应** `统一响应结果«家庭分组VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `家庭分组VO` | | 响应数据 |
|   `adultCount` | `int` | | 成人数 |
|   `babyCount` | `int` | | 幼童数 |
|   `childCount` | `int` | | 儿童数 |
|   `familyId` | `string` | | 家庭ID |
|   `familyName` | `string` | | 家庭名称 |
|   `sortOrder` | `int` | | 排序序号 |
|   `youngChildCount` | `int` | | 小童数 |
| `message` | `string` | | 响应消息 |
---
### `PUT` /admin/product/item/{productId}/family/{familyId}
**更新家庭分组**
更新家庭分组的名称、各类型人数等信息。
**仅适用于 CUSTOM（定制）产品**。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `familyId` | `integer` | | 家庭ID |
| `productId` | `integer` | | 产品ID |
**请求体** `家庭分组保存请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `adultCount` | `int` | | 成人数 |
| `babyCount` | `int` | | 幼童数 |
| `childCount` | `int` | | 儿童数 |
| `familyName` | `string` | 是 | 家庭名称 |
| `sortOrder` | `int` | | 排序序号 |
| `youngChildCount` | `int` | | 小童数 |
**响应** `统一响应结果«家庭分组VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `家庭分组VO` | | 响应数据 |
|   `adultCount` | `int` | | 成人数 |
|   `babyCount` | `int` | | 幼童数 |
|   `childCount` | `int` | | 儿童数 |
|   `familyId` | `string` | | 家庭ID |
|   `familyName` | `string` | | 家庭名称 |
|   `sortOrder` | `int` | | 排序序号 |
|   `youngChildCount` | `int` | | 小童数 |
| `message` | `string` | | 响应消息 |
---
### `DELETE` /admin/product/item/{productId}/family/{familyId}
**删除家庭分组**
删除家庭分组。如果有行程节点通过 familyIds 关联了该分组，需要手动移除关联。
**仅适用于 CUSTOM（定制）产品**。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `familyId` | `integer` | | 家庭ID |
| `productId` | `integer` | | 产品ID |
**响应** `统一响应结果«Void»`
---
## 小程序-产品
### `GET` /mp/product/list
**产品列表（C端）**
小程序端产品列表接口，仅返回已上架（PUBLISHED）的产品。
支持按产品类型、季节、行程天数、目的地、产品线、支付模式、定制师等筛选。
默认按 sortOrder 排序，也可按价格或行程天数排序。
**关联字典**：
- product_type（产品类型，筛选条件）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品
**查询参数**
| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `designerId` | `integer(int64)` | | 定制师ID（创建者ID）筛选 | 1893012345678901234 |
| `destination` | `string` | | 目的地筛选 | 丽江 |
| `keyword` | `string` | | 搜索关键词（产品名称） | 丽江 |
| `lineId` | `string` | | 产品线ID筛选 | 1893012345678901234 |
| `page` | `integer(int32)` | | 页码 | 1 |
| `pageSize` | `integer(int32)` | | 每页条数 | 10 |
| `paymentMode` | `string` | | 支付模式筛选：FULL=全款 DEPOSIT=定金+尾款 null=全部 | DEPOSIT |
| `productType` | `string` | | 产品类型：CORE=核心产品 ROUTE=线路产品 CUSTOM=定制产品 GROUP=小蒙马拼团 | CORE |
| `season` | `string` | | 季节筛选 | spring |
| `sortBy` | `string` | | 排序字段：price/tripDays/default(默认按sortOrder) | price |
| `sortDir` | `string` | | 排序方向：asc/desc | asc |
| `tripDays` | `integer(int32)` | | 行程天数筛选 | 5 |
**响应** `统一响应结果«分页结果«C端产品列表VO»»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `分页结果«C端产品列表VO»` | | 响应数据 |
|   `page` | `int` | | 当前页码 |
|   `pageSize` | `int` | | 每页条数 |
|   `records` | `C端产品列表VO[]` | | 数据列表 |
|     `coverImageUrl` | `string` | | 封面图URL |
|     `creatorAvatarUrl` | `string` | | 定制师头像URL |
|     `departureCity` | `string` | | 出发城市 |
|     `destinationCity` | `string` | | 目的地城市 |
|     `lineName` | `string` | | 产品线名称 |
|     `name` | `string` | | 产品名称 |
|     `paymentMode` | `string` | | 支付模式：FULL=全款 DEPOSIT=定金+尾款 |
|     `productId` | `string` | | 产品ID |
|     `productType` | `string` | | 产品类型：CORE=核心产品 ROUTE=线路产品 CUSTOM=定制产品 GROUP=小蒙马拼团 |
|     `routeMapUrl` | `string` | | 路径图URL |
|     `seasons` | `string[]` | | 适用季节列表 |
|     `startPrice` | `number` | | 起步价（来自定价配置） |
|     `subtitle` | `string` | | 副标题 |
|     `tags` | `string[]` | | 产品标签列表 |
|     `tripDays` | `int` | | 行程天数 |
|     `tripNights` | `int` | | 行程晚数 |
|   `total` | `int` | | 总记录数 |
| `message` | `string` | | 响应消息 |
---
### `GET` /mp/product/{productId}
**产品详情（C端）**
小程序端产品详情接口，仅返回已上架（PUBLISHED）的产品。
包含完整的行程信息、定价配置、费用说明、创作者寄语等。
未上架的产品会返回 404 错误。
**关联字典**：
- product_type（产品类型）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品
- product_category（产品分类）：family=亲子游, honeymoon=蜜月游, photography=旅拍, experience=体验, driving=自驾
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `productId` | `integer` | | 产品ID |
**响应** `统一响应结果«产品详情VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `产品详情VO` | | 响应数据 |
|   `adultCount` | `int` | | 成人人数 |
|   `babyCount` | `int` | | 婴儿人数 |
|   `benefitsDescription` | `权益分组[]` | | 权益说明（静态，所有产品相同） |
|     `items` | `权益项[]` | | 权益项列表 |
|     `title` | `string` | | 分组标题，如：儿童权益 (1.2m以下) |
|   `bookingNotice` | `string` | | 预定须知 |
|   `cancelPolicy` | `string` | | 退改政策 |
|   `carouselImages` | `string[]` | | 轮播图列表 |
|   `carouselVideoUrl` | `string` | | 轮播视频URL |
|   `chatMessages` | `群聊消息VO[]` | | 群聊消息列表 |
|     `avatar` | `string` | | 用户头像URL（type=user时有效） |
|     `text` | `string` | | 消息内容 |
|     `type` | `string` | | 消息类型: user/creator |
|   `childCount` | `int` | | 儿童人数 |
|   `costItems` | `产品成本项VO[]` | | 成本项列表 |
|     `category` | `string` | | 成本项类别：HOTEL/SCENIC/VEHICLE/ACTIVITY/SERVICE/DINING/OTHER |
|     `description` | `string` | | 成本项描述 |
|     `id` | `string` | | 成本项ID |
|     `sortOrder` | `int` | | 排序序号 |
|     `title` | `string` | | 成本项标题 |
|     `type` | `string` | | 成本项类型：INCLUDED=费用包含 EXCLUDED=费用不含 SELF_PAY=自理费用 |
|   `coverImageUrl` | `string` | | 封面图URL |
|   `createBy` | `string` | | 创建人ID |
|   `createTime` | `string` | | 创建时间 |
|   `creatorAvatarUrl` | `string` | | 定制师头像URL |
|   `creatorIntro` | `string` | | 创作者寄语 |
|   `customFees` | `产品自定义费用项VO[]` | | 自定义费用项列表 |
|     `description` | `string` | | 费用说明 |
|     `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
|     `feeAmount` | `number` | | 费用金额 |
|     `feeName` | `string` | | 费用项名称 |
|     `feeUnit` | `string` | | 费用单位 |
|     `id` | `string` | | 费用项ID |
|     `sortOrder` | `int` | | 排序序号 |
|   `customizerId` | `string` | | 定制师ID |
|   `departureCity` | `string` | | 出发城市 |
|   `destinationCities` | `string[]` | | 途经城市列表（从行程节点资源去重提取） |
|   `destinationCity` | `string` | | 目的地城市 |
|   `families` | `家庭分组VO[]` | | 家庭分组列表（定制产品） |
|     `adultCount` | `int` | | 成人数 |
|     `babyCount` | `int` | | 幼童数 |
|     `childCount` | `int` | | 儿童数 |
|     `familyId` | `string` | | 家庭ID |
|     `familyName` | `string` | | 家庭名称 |
|     `sortOrder` | `int` | | 排序序号 |
|     `youngChildCount` | `int` | | 小童数 |
|   `folderId` | `string` | | 所属文件夹ID |
|   `groupChatQrUrl` | `string` | | 群聊二维码URL |
|   `groupRoomId` | `string` | | 企微群聊ID(用于会话存档展示群消息) |
|   `isBooking` | `boolean` | | 是否预约产品 |
|   `itineraryDays` | `行程天VO[]` | | 行程天列表 |
|     `dayId` | `string` | | 行程天ID |
|     `dayNumber` | `int` | | 天数编号 |
|     `dayTitle` | `string` | | 天标题 |
|     `hotels` | `每日酒店VO[]` | | 当日酒店列表 |
|     `nodes` | `行程节点VO[]` | | 行程节点列表 |
|     `restaurants` | `用餐选项VO[]` | | 当日用餐列表 |
|     `routeSummary` | `string` | | 路线概览 |
|   `lineId` | `string` | | 产品线ID |
|   `lineName` | `string` | | 产品线名称 |
|   `lineSubtitle` | `string` | | 产品线副标题 |
|   `maxAdultPerOrder` | `int` | | 每单最大成人数(null=不限) |
|   `maxChildPerOrder` | `int` | | 每单最大儿童数(null=不限) |
|   `mchId` | `string` | | 商户号 |
|   `minAdultPerOrder` | `int` | | 每单最少成人数(null=默认1) |
|   `name` | `string` | | 产品名称 |
|   `paymentMode` | `string` | | 支付模式：FULL=全款 DEPOSIT=定金+尾款 |
|   `pricing` | `产品定价配置VO` | | 定价配置 |
|     `adultExtraBed` | `number` | | 成人加床费 |
|     `babyPrice` | `number` | | 婴儿价 |
|     `balanceDueDays` | `int` | | 尾款支付截止天数（出发前N天） |
|     `childDiscountPercent` | `number` | | 儿童折扣百分比 |
|     `childNoBed` | `number` | | 儿童不占床价 |
|     `childWithBed` | `number` | | 儿童占床价 |
|     `companionPrice` | `number` | | 陪同人员价格 |
|     `customTotalPrice` | `number` | | 定制产品总价（CUSTOM模式下使用） |
|     `depositAmount` | `number` | | 定金金额 |
|     `depositRatio` | `int` | | 定金比例（百分比） |
|     `extraCostPerPerson` | `number` | | 每人额外成本 |
|     `insuranceFee` | `number` | | 保险费用 |
|     `markupPercent` | `number` | | 加价百分比（PERCENT模式下使用） |
|     `maxGroupSize` | `int` | | 最大成团人数 |
|     `mealBudget` | `number` | | 餐费预算 |
|     `minGroupSize` | `int` | | 最小成团人数 |
|     `paymentType` | `string` | | 支付方式：FULL=全款 DEPOSIT=定金+尾款 |
|     `pricingId` | `string` | | 定价配置ID |
|     `pricingMode` | `string` | | 定价模式：AUTO=自动计算 MANUAL=手动定价 CUSTOM=定制定价 |
|     `productId` | `string` | | 产品ID |
|     `profitAmount` | `number` | | 利润金额（FIXED模式下使用） |
|     `profitMode` | `string` | | 利润模式：FIXED=固定金额 PERCENT=百分比 |
|     `singleRoomDiff` | `number` | | 单房差 |
|     `vehicleModelIds` | `string[]` | | 车型ID列表 |
|     `vehicleWarning` | `string` | | 车辆绑定警告信息（为空表示绑定成功） |
|   `productId` | `string` | | 产品ID |
|   `productNo` | `string` | | 产品编号 |
|   `productType` | `string` | | 产品类型：CORE=核心产品 ROUTE=线路产品 CUSTOM=定制产品 GROUP=小蒙马拼团 |
|   `publishedAt` | `string` | | 发布时间 |
|   `routeMapUrl` | `string` | | 路径图URL（后端自动生成） |
|   `seasons` | `string[]` | | 适用季节列表 |
|   `showChatGroup` | `boolean` | | 是否显示群聊入口 |
|   `showReview` | `boolean` | | 是否显示评价 |
|   `showTripDistance` | `boolean` | | 是否显示行程距离 |
|   `showTripTime` | `boolean` | | 是否显示行程时间 |
|   `sortOrder` | `int` | | 排序序号 |
|   `staffConfigs` | `产品人员配置VO[]` | | 人员配置列表（定制产品） |
|     `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
|     `id` | `string` | | 记录ID |
|     `quantity` | `int` | | 数量 |
|     `sortOrder` | `int` | | 排序序号 |
|     `staffType` | `string` | | 人员类型：GUIDE/GUIDE_ASSISTANT/PHOTOGRAPHER/LEADER/OTHER |
|     `staffTypeName` | `string` | | 人员类型名称 |
|   `startPrice` | `number` | | 起步价：未来一年价格日历中最低成人售价 |
|   `status` | `string` | | 产品状态：DRAFT/PENDING_REVIEW/REVIEWED/REJECTED/PUBLISHED/UNPUBLISHED/COMPLETED |
|   `subtitle` | `string` | | 副标题 |
|   `suppliesList` | `产品物资VO[]` | | 物资列表 |
|     `billingType` | `string` | | 计费方式：BY_PERSON=按人头 BY_COUNT=按次/按件 |
|     `costPerPerson` | `number` | | 每人成本 |
|     `coverUrl` | `string` | | 封面图URL |
|     `dayNumber` | `int` | | 天数编号（scope=DAY时生效） |
|     `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
|     `id` | `string` | | 记录ID |
|     `quantity` | `int` | | 数量 |
|     `scope` | `string` | | 适用范围：ALL=整个行程 DAY=指定天 |
|     `sortOrder` | `int` | | 排序序号 |
|     `suppliesId` | `string` | | 物资ID |
|     `suppliesName` | `string` | | 物资名称 |
|   `tags` | `string[]` | | 产品标签列表 |
|   `teamExperienceYears` | `int` | | 团队经验年数 |
|   `tripDays` | `int` | | 行程天数 |
|   `tripNights` | `int` | | 行程晚数 |
|   `updateBy` | `string` | | 更新人ID |
|   `updateTime` | `string` | | 更新时间 |
|   `warmTips` | `string` | | 温馨提示 |
|   `youngChildCount` | `int` | | 小童人数 |
| `message` | `string` | | 响应消息 |
---
### `POST` /mp/product/{productId}/quote
**报价计算（C端）**
小程序端报价计算接口，根据用户选择的日期和人数计算总价。
内部会校验产品是否存在且已上架。
详细计算逻辑参见管理后台的报价计算接口说明。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `productId` | `integer` | | 产品ID |
**请求体** `报价请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `adultCount` | `int` | 是 | 成人人数 |
| `babyCount` | `int` | | 婴儿人数（按固定 babyPrice 计算） |
| `childCount` | `int` | | 儿童人数（占床，按儿童价计算） |
| `childNeedBed` | `boolean` | | 儿童是否加床（true 时额外加收 childWithBed 费用） |
| `departureDate` | `string` | 是 | 出发日期 |
| `youngChildCount` | `int` | | 小童人数（不占床，按儿童价 × childDiscountPercent 折扣比例计算） |
**响应** `统一响应结果«报价结果VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `报价结果VO` | | 响应数据 |
|   `customFeeCost` | `number` | | 自定义费用合计（定制产品） |
|   `dayCosts` | `每日成本明细[]` | | 每日成本明细列表 |
|     `activityCost` | `number` | | 活动成本 |
|     `dayCostTotal` | `number` | | 当日成本合计 |
|     `dayNumber` | `int` | | 天数编号 |
|     `diningCost` | `number` | | 餐饮成本 |
|     `extraCost` | `number` | | 额外成本 |
|     `hotelCost` | `number` | | 酒店成本 |
|     `scenicCost` | `number` | | 景区成本 |
|     `serviceCost` | `number` | | 服务成本 |
|     `staffCost` | `number` | | 人员成本 |
|     `vehicleCost` | `number` | | 车辆成本 |
|   `extraCostItems` | `额外成本明细项[]` | | 额外成本明细列表 |
|     `costItemName` | `string` | | 成本项名称 |
|     `daily` | `boolean` | | 是否按天计算 |
|     `days` | `int` | | 天数（按天计算时） |
|     `quantity` | `int` | | 数量 |
|     `subtotal` | `number` | | 小计金额 |
|     `unitPrice` | `number` | | 单价 |
|   `extraCostPerPerson` | `number` | | 每人额外成本 |
|   `extraCostTotal` | `number` | | 额外成本合计 |
|   `familyCosts` | `家庭成本明细[]` | | 家庭分组成本明细（定制产品，有分组时返回） |
|     `activityCost` | `number` | | 活动成本 |
|     `adultCount` | `int` | | 成人数 |
|     `babyCost` | `number` | | 婴儿固定成本 |
|     `babyCount` | `int` | | 幼童数 |
|     `childCount` | `int` | | 儿童数 |
|     `costPerPerson` | `number` | | 人均成本（家庭成本/付费人头） |
|     `customFeeCost` | `number` | | 自定义费用成本 |
|     `extraCost` | `number` | | 额外成本 |
|     `familyId` | `string` | | 家庭ID |
|     `familyName` | `string` | | 家庭名称 |
|     `headcount` | `int` | | 人头数 |
|     `hotelCost` | `number` | | 酒店成本 |
|     `insuranceCost` | `number` | | 保险成本 |
|     `payingHeadcount` | `int` | | 付费人头数（不含幼童） |
|     `personCosts` | `每人成本明细[]` | | 每人分项成本列表 |
|     `scenicCost` | `number` | | 景区成本 |
|     `sellPricePerPerson` | `number` | | 人均售价（家庭售价/付费人头） |
|     `serviceCost` | `number` | | 服务成本 |
|     `staffCost` | `number` | | 人员成本 |
|     `suppliesCost` | `number` | | 物资成本 |
|     `totalCost` | `number` | | 家庭成本合计 |
|     `totalProfit` | `number` | | 家庭利润合计 |
|     `totalSellPrice` | `number` | | 家庭售价合计 |
|     `vehicleCost` | `number` | | 车辆成本 |
|     `youngChildCount` | `int` | | 小童数 |
|   `grandTotalCost` | `number` | | 总成本合计 |
|   `grandTotalProfit` | `number` | | 总利润合计 |
|   `grandTotalSellPrice` | `number` | | 总售价合计 |
|   `insuranceFee` | `number` | | 保险费用 |
|   `profitRate` | `number` | | 利润率（百分比） |
|   `staffCost` | `number` | | 人员成本 |
|   `suppliesCost` | `number` | | 物资成本 |
|   `totalAdultCost` | `number` | | 成人总成本 |
|   `totalAdultProfit` | `number` | | 成人总利润 |
|   `totalAdultSellPrice` | `number` | | 成人总售价 |
|   `totalBabyCost` | `number` | | 婴儿总成本 |
|   `totalBabySellPrice` | `number` | | 婴儿总售价 |
|   `totalChildCost` | `number` | | 儿童总成本 |
|   `totalChildSellPrice` | `number` | | 儿童总售价 |
|   `totalYoungChildCost` | `number` | | 小童总成本 |
|   `totalYoungChildSellPrice` | `number` | | 小童总售价 |
|   `warnings` | `string[]` | | 警告信息列表 |
| `message` | `string` | | 响应消息 |
---
## 报价计算
### `GET` /admin/product/item/{productId}/group-quote
**GROUP产品报价（按套餐组合）**
为 GROUP（小蒙马拼团）产品按团期批次和套餐组合计算报价。
GROUP 产品的价格由批次下的套餐组合（combo）决定，不同组合有不同的成人/儿童人数搭配和价格。
传入 batchId 指定团期批次，adultCount 用于匹配合适的套餐组合。
**与普通报价的区别**：普通报价从价格日历取单价，GROUP 报价从套餐组合取打包价。
**关联字典**：
- product_type（产品类型，仅限GROUP）：GROUP=小蒙马拼团
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `productId` | `integer` | | 产品ID |
**查询参数**
| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `adultCount` | `integer(int32)` | | 成人人数 | |
| `batchId` | `integer(int64)` | | 团期ID | |
**响应** `统一响应结果«GROUP产品报价结果»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `GROUP产品报价结果` | | 响应数据 |
|   `adultCostPrice` | `number` | | 成人成本价(单房差+每人费用) |
|   `adultSellPrice` | `number` | | 成人售价 |
|   `childCostPrice` | `number` | | 儿童成本价(每人费用，不含酒店) |
|   `childSellPrice` | `number` | | 儿童售价 |
|   `code` | `int` | | 返回码: 0=成功, 1=非GROUP产品, 2=错误 |
|   `dayCosts` | `每日成本明细[]` | | 每日成本明细 |
|     `activityCost` | `number` | | 活动成本 |
|     `dayCostTotal` | `number` | | 当日成本合计 |
|     `dayNumber` | `int` | | 天数编号 |
|     `diningCost` | `number` | | 餐饮成本 |
|     `extraCost` | `number` | | 额外成本 |
|     `hotelCost` | `number` | | 酒店成本 |
|     `scenicCost` | `number` | | 景区成本 |
|     `serviceCost` | `number` | | 服务成本 |
|     `staffCost` | `number` | | 人员成本 |
|     `vehicleCost` | `number` | | 车辆成本 |
|   `extraCostItems` | `额外成本明细项[]` | | 额外成本明细列表 |
|     `costItemName` | `string` | | 成本项名称 |
|     `daily` | `boolean` | | 是否按天计算 |
|     `days` | `int` | | 天数（按天计算时） |
|     `quantity` | `int` | | 数量 |
|     `subtotal` | `number` | | 小计金额 |
|     `unitPrice` | `number` | | 单价 |
|   `extraCostPerPerson` | `number` | | 额外成本（人均） |
|   `extraCostTotal` | `number` | | 额外成本总额（团队） |
|   `hotelCostTotal` | `number` | | 酒店总成本 |
|   `message` | `string` | | 错误信息(code!=0时) |
|   `perPersonCost` | `number` | | 每人成本(不含酒店) |
|   `profitMode` | `string` | | 利润模式 |
|   `singleRoomSupplement` | `number` | | 单房差(酒店总成本/2) |
|   `warnings` | `string[]` | | 警告信息 |
| `message` | `string` | | 响应消息 |
---
### `POST` /admin/product/item/{productId}/quote
**计算报价**
根据出发日期和人数组合，计算产品的完整报价。
**计算流程**：
1. 从价格日历获取指定日期的单价
2. 按人数类型分别计算：成人 × 成人价、儿童 × 儿童价
3. 小童按儿童价 × 折扣比例（childDiscountPercent）计算
4. 婴儿使用固定价格（babyPrice）
5. 儿童加床（childNeedBed=true）额外加收 childWithBed 费用
**CUSTOM/ROUTE 产品**：价格日历存的是整单总价，不按人头乘算。
**GROUP 产品**：建议使用 group-quote 接口，支持套餐组合报价。
**关联字典**：
- product_type（产品类型，影响计算逻辑）：CORE=核心产品, GROUP=小蒙马拼团, CUSTOM=定制产品, ROUTE=线路产品
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `productId` | `integer` | | 产品ID |
**请求体** `报价请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `adultCount` | `int` | 是 | 成人人数 |
| `babyCount` | `int` | | 婴儿人数（按固定 babyPrice 计算） |
| `childCount` | `int` | | 儿童人数（占床，按儿童价计算） |
| `childNeedBed` | `boolean` | | 儿童是否加床（true 时额外加收 childWithBed 费用） |
| `departureDate` | `string` | 是 | 出发日期 |
| `youngChildCount` | `int` | | 小童人数（不占床，按儿童价 × childDiscountPercent 折扣比例计算） |
**响应** `统一响应结果«报价结果VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `报价结果VO` | | 响应数据 |
|   `customFeeCost` | `number` | | 自定义费用合计（定制产品） |
|   `dayCosts` | `每日成本明细[]` | | 每日成本明细列表 |
|     `activityCost` | `number` | | 活动成本 |
|     `dayCostTotal` | `number` | | 当日成本合计 |
|     `dayNumber` | `int` | | 天数编号 |
|     `diningCost` | `number` | | 餐饮成本 |
|     `extraCost` | `number` | | 额外成本 |
|     `hotelCost` | `number` | | 酒店成本 |
|     `scenicCost` | `number` | | 景区成本 |
|     `serviceCost` | `number` | | 服务成本 |
|     `staffCost` | `number` | | 人员成本 |
|     `vehicleCost` | `number` | | 车辆成本 |
|   `extraCostItems` | `额外成本明细项[]` | | 额外成本明细列表 |
|     `costItemName` | `string` | | 成本项名称 |
|     `daily` | `boolean` | | 是否按天计算 |
|     `days` | `int` | | 天数（按天计算时） |
|     `quantity` | `int` | | 数量 |
|     `subtotal` | `number` | | 小计金额 |
|     `unitPrice` | `number` | | 单价 |
|   `extraCostPerPerson` | `number` | | 每人额外成本 |
|   `extraCostTotal` | `number` | | 额外成本合计 |
|   `familyCosts` | `家庭成本明细[]` | | 家庭分组成本明细（定制产品，有分组时返回） |
|     `activityCost` | `number` | | 活动成本 |
|     `adultCount` | `int` | | 成人数 |
|     `babyCost` | `number` | | 婴儿固定成本 |
|     `babyCount` | `int` | | 幼童数 |
|     `childCount` | `int` | | 儿童数 |
|     `costPerPerson` | `number` | | 人均成本（家庭成本/付费人头） |
|     `customFeeCost` | `number` | | 自定义费用成本 |
|     `extraCost` | `number` | | 额外成本 |
|     `familyId` | `string` | | 家庭ID |
|     `familyName` | `string` | | 家庭名称 |
|     `headcount` | `int` | | 人头数 |
|     `hotelCost` | `number` | | 酒店成本 |
|     `insuranceCost` | `number` | | 保险成本 |
|     `payingHeadcount` | `int` | | 付费人头数（不含幼童） |
|     `personCosts` | `每人成本明细[]` | | 每人分项成本列表 |
|     `scenicCost` | `number` | | 景区成本 |
|     `sellPricePerPerson` | `number` | | 人均售价（家庭售价/付费人头） |
|     `serviceCost` | `number` | | 服务成本 |
|     `staffCost` | `number` | | 人员成本 |
|     `suppliesCost` | `number` | | 物资成本 |
|     `totalCost` | `number` | | 家庭成本合计 |
|     `totalProfit` | `number` | | 家庭利润合计 |
|     `totalSellPrice` | `number` | | 家庭售价合计 |
|     `vehicleCost` | `number` | | 车辆成本 |
|     `youngChildCount` | `int` | | 小童数 |
|   `grandTotalCost` | `number` | | 总成本合计 |
|   `grandTotalProfit` | `number` | | 总利润合计 |
|   `grandTotalSellPrice` | `number` | | 总售价合计 |
|   `insuranceFee` | `number` | | 保险费用 |
|   `profitRate` | `number` | | 利润率（百分比） |
|   `staffCost` | `number` | | 人员成本 |
|   `suppliesCost` | `number` | | 物资成本 |
|   `totalAdultCost` | `number` | | 成人总成本 |
|   `totalAdultProfit` | `number` | | 成人总利润 |
|   `totalAdultSellPrice` | `number` | | 成人总售价 |
|   `totalBabyCost` | `number` | | 婴儿总成本 |
|   `totalBabySellPrice` | `number` | | 婴儿总售价 |
|   `totalChildCost` | `number` | | 儿童总成本 |
|   `totalChildSellPrice` | `number` | | 儿童总售价 |
|   `totalYoungChildCost` | `number` | | 小童总成本 |
|   `totalYoungChildSellPrice` | `number` | | 小童总售价 |
|   `warnings` | `string[]` | | 警告信息列表 |
| `message` | `string` | | 响应消息 |
---
## 拼团批次管理
### `POST` /admin/product/item/{productId}/batch
**创建主批次**
为 GROUP（小蒙马拼团）产品创建一个团期主批次。
**仅适用于 GROUP 产品类型**。
每个批次有独立的出发日期、报名截止日期、人数上限。
创建后状态为 PENDING（待开放），需手动开启报名。
**批次状态流转**：PENDING → ENROLLING（报名中）→ CONFIRMED（已成团）→ CLOSED（已关闭）
任意报名状态均可被解散（DISBANDED）。
**关联字典**：
- product_type（产品类型，仅限GROUP）：GROUP=小蒙马拼团
- batch_status（批次状态）：PENDING=待开放, ENROLLING=报名中, CONFIRMED=已成团, FULL=已满员, CLOSED=已关闭, DISBANDED=已解散, IN_PROGRESS=进行中, FINISHED=已结束
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `productId` | `integer` | 是 | productId |
**请求体** `创建拼团批次请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `batchName` | `string` | 是 | 批次名称 |
| `departureDate` | `string` | 是 | 出发日期 |
| `enrollmentDeadline` | `string` | 是 | 报名截止日期，必须早于出发日期 |
| `maxParticipants` | `int` | 是 | 最大参团人数（报名人数达到上限后自动关闭报名） |
| `minParticipants` | `int` | | 最低成团人数（0=不限制，达到此人数自动变为CONFIRMED状态） |
| `remark` | `string` | | 备注说明 |
| `sortOrder` | `int` | | 排序序号（越小越靠前） |
**响应** `统一响应结果«团批次VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `团批次VO` | | 响应数据 |
|   `batchId` | `string` | | 批次ID |
|   `batchLabel` | `string` | | 批次标签(简称) |
|   `batchName` | `string` | | 批次名称 |
|   `batchNo` | `string` | | 批次编号 |
|   `batchStatus` | `string` | | 批次状态: PENDING/ENROLLING/CONFIRMED/FULL/CLOSED/IN_PROGRESS/FINISHED/DISBANDED |
|   `createBy` | `string` | | 创建人ID |
|   `createTime` | `string` | | 创建时间 |
|   `departureDate` | `string` | | 出发日期 |
|   `endDate` | `string` | | 结束日期 |
|   `enrolledCount` | `int` | | 已报名人数 |
|   `enrollmentDeadline` | `string` | | 报名截止日期 |
|   `maxParticipants` | `int` | | 最大人数 |
|   `minParticipants` | `int` | | 最少成团人数 |
|   `parentBatchId` | `string` | | 父批次ID(子批次时有值) |
|   `productId` | `string` | | 产品ID |
|   `remainingSlots` | `int` | | 剩余名额 |
|   `remark` | `string` | | 备注 |
|   `sortOrder` | `int` | | 排序 |
|   `subBatches` | `团批次VO[]` | | 子批次列表(树形) |
|     `batchId` | `string` | | 批次ID |
|     `batchLabel` | `string` | | 批次标签(简称) |
|     `batchName` | `string` | | 批次名称 |
|     `batchNo` | `string` | | 批次编号 |
|     `batchStatus` | `string` | | 批次状态: PENDING/ENROLLING/CONFIRMED/FULL/CLOSED/IN_PROGRESS/FINISHED/DISBANDED |
|     `createBy` | `string` | | 创建人ID |
|     `createTime` | `string` | | 创建时间 |
|     `departureDate` | `string` | | 出发日期 |
|     `endDate` | `string` | | 结束日期 |
|     `enrolledCount` | `int` | | 已报名人数 |
|     `enrollmentDeadline` | `string` | | 报名截止日期 |
|     `maxParticipants` | `int` | | 最大人数 |
|     `minParticipants` | `int` | | 最少成团人数 |
|     `parentBatchId` | `string` | | 父批次ID(子批次时有值) |
|     `productId` | `string` | | 产品ID |
|     `remainingSlots` | `int` | | 剩余名额 |
|     `remark` | `string` | | 备注 |
|     `sortOrder` | `int` | | 排序 |
|     `subBatches` | `团批次VO[]` | | 子批次列表(树形) |
|     `updateTime` | `string` | | 更新时间 |
|   `updateTime` | `string` | | 更新时间 |
| `message` | `string` | | 响应消息 |
---
### `GET` /admin/product/item/{productId}/batch/list
**批次列表(树形)**
获取产品所有批次，以树形结构返回（主批次包含子批次列表）。
按出发日期升序排列，包含每个批次的报名人数和剩余名额。
**关联字典**：
- batch_status（批次状态，返回字段）：PENDING=待开放, ENROLLING=报名中, CONFIRMED=已成团, FULL=已满员, CLOSED=已关闭, DISBANDED=已解散, IN_PROGRESS=进行中, FINISHED=已结束
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `productId` | `integer` | 是 | productId |
**响应** `统一响应结果«List«团批次VO»»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `团批次VO[]` | | 响应数据 |
|   `batchId` | `string` | | 批次ID |
|   `batchLabel` | `string` | | 批次标签(简称) |
|   `batchName` | `string` | | 批次名称 |
|   `batchNo` | `string` | | 批次编号 |
|   `batchStatus` | `string` | | 批次状态: PENDING/ENROLLING/CONFIRMED/FULL/CLOSED/IN_PROGRESS/FINISHED/DISBANDED |
|   `createBy` | `string` | | 创建人ID |
|   `createTime` | `string` | | 创建时间 |
|   `departureDate` | `string` | | 出发日期 |
|   `endDate` | `string` | | 结束日期 |
|   `enrolledCount` | `int` | | 已报名人数 |
|   `enrollmentDeadline` | `string` | | 报名截止日期 |
|   `maxParticipants` | `int` | | 最大人数 |
|   `minParticipants` | `int` | | 最少成团人数 |
|   `parentBatchId` | `string` | | 父批次ID(子批次时有值) |
|   `productId` | `string` | | 产品ID |
|   `remainingSlots` | `int` | | 剩余名额 |
|   `remark` | `string` | | 备注 |
|   `sortOrder` | `int` | | 排序 |
|   `subBatches` | `团批次VO[]` | | 子批次列表(树形) |
|     `batchId` | `string` | | 批次ID |
|     `batchLabel` | `string` | | 批次标签(简称) |
|     `batchName` | `string` | | 批次名称 |
|     `batchNo` | `string` | | 批次编号 |
|     `batchStatus` | `string` | | 批次状态: PENDING/ENROLLING/CONFIRMED/FULL/CLOSED/IN_PROGRESS/FINISHED/DISBANDED |
|     `createBy` | `string` | | 创建人ID |
|     `createTime` | `string` | | 创建时间 |
|     `departureDate` | `string` | | 出发日期 |
|     `endDate` | `string` | | 结束日期 |
|     `enrolledCount` | `int` | | 已报名人数 |
|     `enrollmentDeadline` | `string` | | 报名截止日期 |
|     `maxParticipants` | `int` | | 最大人数 |
|     `minParticipants` | `int` | | 最少成团人数 |
|     `parentBatchId` | `string` | | 父批次ID(子批次时有值) |
|     `productId` | `string` | | 产品ID |
|     `remainingSlots` | `int` | | 剩余名额 |
|     `remark` | `string` | | 备注 |
|     `sortOrder` | `int` | | 排序 |
|     `subBatches` | `团批次VO[]` | | 子批次列表(树形) |
|     `updateTime` | `string` | | 更新时间 |
|   `updateTime` | `string` | | 更新时间 |
| `message` | `string` | | 响应消息 |
---
### `GET` /admin/product/item/{productId}/batch/{batchId}
**批次详情**
获取单个批次的完整信息，包括批次基本信息、服务人员配置、套餐组合等。
**关联字典**：
- batch_status（批次状态）：PENDING=待开放, ENROLLING=报名中, CONFIRMED=已成团, FULL=已满员, CLOSED=已关闭, DISBANDED=已解散, IN_PROGRESS=进行中, FINISHED=已结束
- staff_type（人员类型，服务人员配置）：GUIDE=领队, DRIVER=司机, PHOTOGRAPHER=摄影师, ASSISTANT=助理, OTHER=其他
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `batchId` | `integer` | 是 | batchId |
| `productId` | `integer` | 是 | productId |
**响应** `统一响应结果«团批次详情VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `团批次详情VO` | | 响应数据 |
|   `batchId` | `string` | | 批次ID |
|   `batchLabel` | `string` | | 批次标签(简称) |
|   `batchName` | `string` | | 批次名称 |
|   `batchNo` | `string` | | 批次编号 |
|   `batchStatus` | `string` | | 批次状态: PENDING/ENROLLING/CONFIRMED/FULL/CLOSED/IN_PROGRESS/FINISHED/DISBANDED |
|   `createBy` | `string` | | 创建人ID |
|   `createTime` | `string` | | 创建时间 |
|   `departureDate` | `string` | | 出发日期 |
|   `endDate` | `string` | | 结束日期 |
|   `enrolledCount` | `int` | | 已报名人数 |
|   `enrollmentDeadline` | `string` | | 报名截止日期 |
|   `maxParticipants` | `int` | | 最大人数 |
|   `minParticipants` | `int` | | 最少成团人数 |
|   `parentBatchId` | `string` | | 父批次ID(子批次时有值) |
|   `productId` | `string` | | 产品ID |
|   `remainingSlots` | `int` | | 剩余名额 |
|   `remark` | `string` | | 备注 |
|   `sortOrder` | `int` | | 排序 |
|   `staff` | `团批次服务人员VO[]` | | 服务人员列表 |
|     `batchId` | `string` | | 批次ID |
|     `createTime` | `string` | | 创建时间 |
|     `id` | `string` | | 记录ID |
|     `productId` | `string` | | 产品ID |
|     `remark` | `string` | | 备注 |
|     `sortOrder` | `int` | | 排序 |
|     `staffId` | `string` | | 服务人员ID |
|     `staffName` | `string` | | 姓名 |
|     `staffPhone` | `string` | | 手机号 |
|     `staffRole` | `string` | | 角色: GUIDE/GUIDE_ASSISTANT/PHOTOGRAPHER/LEADER/OTHER |
|   `subBatches` | `团批次VO[]` | | 子批次列表(树形) |
|     `batchId` | `string` | | 批次ID |
|     `batchLabel` | `string` | | 批次标签(简称) |
|     `batchName` | `string` | | 批次名称 |
|     `batchNo` | `string` | | 批次编号 |
|     `batchStatus` | `string` | | 批次状态: PENDING/ENROLLING/CONFIRMED/FULL/CLOSED/IN_PROGRESS/FINISHED/DISBANDED |
|     `createBy` | `string` | | 创建人ID |
|     `createTime` | `string` | | 创建时间 |
|     `departureDate` | `string` | | 出发日期 |
|     `endDate` | `string` | | 结束日期 |
|     `enrolledCount` | `int` | | 已报名人数 |
|     `enrollmentDeadline` | `string` | | 报名截止日期 |
|     `maxParticipants` | `int` | | 最大人数 |
|     `minParticipants` | `int` | | 最少成团人数 |
|     `parentBatchId` | `string` | | 父批次ID(子批次时有值) |
|     `productId` | `string` | | 产品ID |
|     `remainingSlots` | `int` | | 剩余名额 |
|     `remark` | `string` | | 备注 |
|     `sortOrder` | `int` | | 排序 |
|     `subBatches` | `团批次VO[]` | | 子批次列表(树形) |
|     `updateTime` | `string` | | 更新时间 |
|   `updateTime` | `string` | | 更新时间 |
| `message` | `string` | | 响应消息 |
---
### `PUT` /admin/product/item/{productId}/batch/{batchId}
**更新批次**
更新批次基本信息。仅传入需要修改的字段。
已有报名人员的批次修改人数上限时，不能低于已报名人数。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `batchId` | `integer` | 是 | batchId |
| `productId` | `integer` | 是 | productId |
**请求体** `更新拼团批次请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `batchName` | `string` | | 批次名称 |
| `departureDate` | `string` | | 出发日期 |
| `enrollmentDeadline` | `string` | | 报名截止日期 |
| `maxParticipants` | `int` | | 最大参团人数（不能低于已报名人数） |
| `minParticipants` | `int` | | 最低成团人数（0=不限制） |
| `remark` | `string` | | 备注说明 |
| `sortOrder` | `int` | | 排序序号 |
**响应** `统一响应结果«团批次VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `团批次VO` | | 响应数据 |
|   `batchId` | `string` | | 批次ID |
|   `batchLabel` | `string` | | 批次标签(简称) |
|   `batchName` | `string` | | 批次名称 |
|   `batchNo` | `string` | | 批次编号 |
|   `batchStatus` | `string` | | 批次状态: PENDING/ENROLLING/CONFIRMED/FULL/CLOSED/IN_PROGRESS/FINISHED/DISBANDED |
|   `createBy` | `string` | | 创建人ID |
|   `createTime` | `string` | | 创建时间 |
|   `departureDate` | `string` | | 出发日期 |
|   `endDate` | `string` | | 结束日期 |
|   `enrolledCount` | `int` | | 已报名人数 |
|   `enrollmentDeadline` | `string` | | 报名截止日期 |
|   `maxParticipants` | `int` | | 最大人数 |
|   `minParticipants` | `int` | | 最少成团人数 |
|   `parentBatchId` | `string` | | 父批次ID(子批次时有值) |
|   `productId` | `string` | | 产品ID |
|   `remainingSlots` | `int` | | 剩余名额 |
|   `remark` | `string` | | 备注 |
|   `sortOrder` | `int` | | 排序 |
|   `subBatches` | `团批次VO[]` | | 子批次列表(树形) |
|     `batchId` | `string` | | 批次ID |
|     `batchLabel` | `string` | | 批次标签(简称) |
|     `batchName` | `string` | | 批次名称 |
|     `batchNo` | `string` | | 批次编号 |
|     `batchStatus` | `string` | | 批次状态: PENDING/ENROLLING/CONFIRMED/FULL/CLOSED/IN_PROGRESS/FINISHED/DISBANDED |
|     `createBy` | `string` | | 创建人ID |
|     `createTime` | `string` | | 创建时间 |
|     `departureDate` | `string` | | 出发日期 |
|     `endDate` | `string` | | 结束日期 |
|     `enrolledCount` | `int` | | 已报名人数 |
|     `enrollmentDeadline` | `string` | | 报名截止日期 |
|     `maxParticipants` | `int` | | 最大人数 |
|     `minParticipants` | `int` | | 最少成团人数 |
|     `parentBatchId` | `string` | | 父批次ID(子批次时有值) |
|     `productId` | `string` | | 产品ID |
|     `remainingSlots` | `int` | | 剩余名额 |
|     `remark` | `string` | | 备注 |
|     `sortOrder` | `int` | | 排序 |
|     `subBatches` | `团批次VO[]` | | 子批次列表(树形) |
|     `updateTime` | `string` | | 更新时间 |
|   `updateTime` | `string` | | 更新时间 |
| `message` | `string` | | 响应消息 |
---
### `DELETE` /admin/product/item/{productId}/batch/{batchId}
**删除批次**
删除批次（软删除）。
**限制**：已有报名人员的批次不能直接删除，需先解散批次。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `batchId` | `integer` | 是 | batchId |
| `productId` | `integer` | 是 | productId |
**响应** `统一响应结果«Void»`
---
### `PUT` /admin/product/item/{productId}/batch/{batchId}/close
**关闭报名(ENROLLING/CONFIRMED->CLOSED)**
关闭批次报名，不再接受新的报名。
已报名的订单不受影响，仅阻止新增报名。
适用于报名截止日期到达或手动提前关闭的场景。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `batchId` | `integer` | 是 | batchId |
| `productId` | `integer` | 是 | productId |
**响应** `统一响应结果«Void»`
---
### `POST` /admin/product/item/{productId}/batch/{batchId}/disband
**解散批次**
解散批次并处理已报名的订单。
**重要**：解散操作会触发以下流程：
1. 批次状态变更为 DISBANDED
2. 通过 MQ 消息通知订单服务，自动取消该批次下的所有未完成订单
3. 已支付订单会触发退款流程
必须填写解散原因（如：报名人数不足、行程调整等）。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `batchId` | `integer` | 是 | batchId |
| `productId` | `integer` | 是 | productId |
**请求体** `解散批次请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `reason` | `string` | 是 | 解散原因（如：报名人数不足、行程调整等） |
**响应** `统一响应结果«Void»`
---
### `PUT` /admin/product/item/{productId}/batch/{batchId}/open
**开启报名(PENDING->ENROLLING)**
将批次从 PENDING 状态变更为 ENROLLING（报名中）。
开启后用户可在小程序端看到该团期并报名。
前提条件：产品必须已上架（PUBLISHED）。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `batchId` | `integer` | 是 | batchId |
| `productId` | `integer` | 是 | productId |
**响应** `统一响应结果«Void»`
---
### `GET` /admin/product/item/{productId}/batch/{batchId}/staff
**服务人员列表**
**关联字典**：
- staff_type（人员类型）：GUIDE=领队, DRIVER=司机, PHOTOGRAPHER=摄影师, ASSISTANT=助理, OTHER=其他
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `batchId` | `integer` | 是 | batchId |
| `productId` | `integer` | 是 | productId |
**响应** `统一响应结果«List«团批次服务人员VO»»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `团批次服务人员VO[]` | | 响应数据 |
|   `batchId` | `string` | | 批次ID |
|   `createTime` | `string` | | 创建时间 |
|   `id` | `string` | | 记录ID |
|   `productId` | `string` | | 产品ID |
|   `remark` | `string` | | 备注 |
|   `sortOrder` | `int` | | 排序 |
|   `staffId` | `string` | | 服务人员ID |
|   `staffName` | `string` | | 姓名 |
|   `staffPhone` | `string` | | 手机号 |
|   `staffRole` | `string` | | 角色: GUIDE/GUIDE_ASSISTANT/PHOTOGRAPHER/LEADER/OTHER |
| `message` | `string` | | 响应消息 |
---
### `POST` /admin/product/item/{productId}/batch/{batchId}/staff
**保存服务人员(全量替换)**
保存批次的服务人员配置，采用全量替换模式（先删后增）。
每次提交完整的人员列表，替换掉该批次原有的所有人员配置。
人员来源于资源服务的人员库，通过 staffId 关联。
**角色类型**：LEADER(领队)/PHOTOGRAPHER(摄影师)/DRIVER(司机)/OTHER(其他)
**关联字典**：
- staff_type（人员类型）：GUIDE=领队, DRIVER=司机, PHOTOGRAPHER=摄影师, ASSISTANT=助理, OTHER=其他
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `batchId` | `integer` | 是 | batchId |
| `productId` | `integer` | 是 | productId |
**请求体** `批次服务人员分配请求[]`
**响应** `统一响应结果«List«团批次服务人员VO»»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `团批次服务人员VO[]` | | 响应数据 |
|   `batchId` | `string` | | 批次ID |
|   `createTime` | `string` | | 创建时间 |
|   `id` | `string` | | 记录ID |
|   `productId` | `string` | | 产品ID |
|   `remark` | `string` | | 备注 |
|   `sortOrder` | `int` | | 排序 |
|   `staffId` | `string` | | 服务人员ID |
|   `staffName` | `string` | | 姓名 |
|   `staffPhone` | `string` | | 手机号 |
|   `staffRole` | `string` | | 角色: GUIDE/GUIDE_ASSISTANT/PHOTOGRAPHER/LEADER/OTHER |
| `message` | `string` | | 响应消息 |
---
### `POST` /admin/product/item/{productId}/batch/{batchId}/staff/copy-from/{sourceId}
**从其他批次复制服务人员**
将源批次的服务人员配置复制到当前批次（全量替换当前批次已有人员）。
适用场景：多个团期使用相同的服务人员班底。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `batchId` | `integer` | 是 | batchId |
| `productId` | `integer` | 是 | productId |
| `sourceId` | `integer` | 是 | sourceId |
**响应** `统一响应结果«List«团批次服务人员VO»»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `团批次服务人员VO[]` | | 响应数据 |
|   `batchId` | `string` | | 批次ID |
|   `createTime` | `string` | | 创建时间 |
|   `id` | `string` | | 记录ID |
|   `productId` | `string` | | 产品ID |
|   `remark` | `string` | | 备注 |
|   `sortOrder` | `int` | | 排序 |
|   `staffId` | `string` | | 服务人员ID |
|   `staffName` | `string` | | 姓名 |
|   `staffPhone` | `string` | | 手机号 |
|   `staffRole` | `string` | | 角色: GUIDE/GUIDE_ASSISTANT/PHOTOGRAPHER/LEADER/OTHER |
| `message` | `string` | | 响应消息 |
---
### `POST` /admin/product/item/{productId}/batch/{batchId}/sub-batch
**创建子批次(溢出)**
当主批次人数满员时，创建子批次接收溢出报名。
子批次共享主批次的出发日期和行程，但有独立的人数上限和报名人数。
适用场景：某团期特别火爆，需要扩容但希望分开管理。
子批次在列表中显示为主批次的子级节点。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `batchId` | `integer` | 是 | batchId |
| `productId` | `integer` | 是 | productId |
**请求体** `创建拼团批次请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `batchName` | `string` | 是 | 批次名称 |
| `departureDate` | `string` | 是 | 出发日期 |
| `enrollmentDeadline` | `string` | 是 | 报名截止日期，必须早于出发日期 |
| `maxParticipants` | `int` | 是 | 最大参团人数（报名人数达到上限后自动关闭报名） |
| `minParticipants` | `int` | | 最低成团人数（0=不限制，达到此人数自动变为CONFIRMED状态） |
| `remark` | `string` | | 备注说明 |
| `sortOrder` | `int` | | 排序序号（越小越靠前） |
**响应** `统一响应结果«团批次VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `团批次VO` | | 响应数据 |
|   `batchId` | `string` | | 批次ID |
|   `batchLabel` | `string` | | 批次标签(简称) |
|   `batchName` | `string` | | 批次名称 |
|   `batchNo` | `string` | | 批次编号 |
|   `batchStatus` | `string` | | 批次状态: PENDING/ENROLLING/CONFIRMED/FULL/CLOSED/IN_PROGRESS/FINISHED/DISBANDED |
|   `createBy` | `string` | | 创建人ID |
|   `createTime` | `string` | | 创建时间 |
|   `departureDate` | `string` | | 出发日期 |
|   `endDate` | `string` | | 结束日期 |
|   `enrolledCount` | `int` | | 已报名人数 |
|   `enrollmentDeadline` | `string` | | 报名截止日期 |
|   `maxParticipants` | `int` | | 最大人数 |
|   `minParticipants` | `int` | | 最少成团人数 |
|   `parentBatchId` | `string` | | 父批次ID(子批次时有值) |
|   `productId` | `string` | | 产品ID |
|   `remainingSlots` | `int` | | 剩余名额 |
|   `remark` | `string` | | 备注 |
|   `sortOrder` | `int` | | 排序 |
|   `subBatches` | `团批次VO[]` | | 子批次列表(树形) |
|     `batchId` | `string` | | 批次ID |
|     `batchLabel` | `string` | | 批次标签(简称) |
|     `batchName` | `string` | | 批次名称 |
|     `batchNo` | `string` | | 批次编号 |
|     `batchStatus` | `string` | | 批次状态: PENDING/ENROLLING/CONFIRMED/FULL/CLOSED/IN_PROGRESS/FINISHED/DISBANDED |
|     `createBy` | `string` | | 创建人ID |
|     `createTime` | `string` | | 创建时间 |
|     `departureDate` | `string` | | 出发日期 |
|     `endDate` | `string` | | 结束日期 |
|     `enrolledCount` | `int` | | 已报名人数 |
|     `enrollmentDeadline` | `string` | | 报名截止日期 |
|     `maxParticipants` | `int` | | 最大人数 |
|     `minParticipants` | `int` | | 最少成团人数 |
|     `parentBatchId` | `string` | | 父批次ID(子批次时有值) |
|     `productId` | `string` | | 产品ID |
|     `remainingSlots` | `int` | | 剩余名额 |
|     `remark` | `string` | | 备注 |
|     `sortOrder` | `int` | | 排序 |
|     `subBatches` | `团批次VO[]` | | 子批次列表(树形) |
|     `updateTime` | `string` | | 更新时间 |
|   `updateTime` | `string` | | 更新时间 |
| `message` | `string` | | 响应消息 |
---
## 行政区划搜索
### `GET` /admin/product/district/search
**搜索行政区划（城市/区县）**
通过高德地图 API 搜索行政区划，用于产品的出发城市和目的地城市选择。
输入关键词（如"丽江"、"昆明"），返回匹配的城市/区县列表，包含行政区划编码。
**关联字典**：
- cities（城市）：搜索结果可用于产品行程中的城市预览
- city（城市筛选）：搜索结果可用于资源面板城市筛选
**查询参数**
| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `keywords` | `string` | | 搜索关键词 | |
**响应** `统一响应结果«List«行政区划搜索结果»»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `行政区划搜索结果[]` | | 响应数据 |
|   `adcode` | `string` | | 行政区编码 |
|   `level` | `string` | | 级别: city/district |
|   `levelName` | `string` | | 级别中文名 |
|   `name` | `string` | | 行政区名称 |
| `message` | `string` | | 响应消息 |
---
## 行程管理
### `PUT` /admin/product/dining/{id}
**更新餐饮推荐**
更新餐饮推荐的餐厅、用餐类型（早/午/晚）、描述等信息。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` | | 餐饮推荐ID |
**请求体** `用餐选项请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `coverUrl` | `string` | | 餐食封面图URL |
| `mealTypes` | `string` | | 餐次：早餐/午餐/晚餐 |
| `priceInfo` | `string` | | 价格信息 |
| `quantity` | `int` | | 数量 |
| `restaurantId` | `string` | | 餐厅ID（GROUP产品可不传） |
| `restaurantName` | `string` | | 餐厅/餐食名称 |
| `sortOrder` | `int` | | 排序序号 |
| `unitPrice` | `number` | | 餐食单价(元，GROUP产品用于成本计算) |
**响应** `统一响应结果«用餐选项VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `用餐选项VO` | | 响应数据 |
|   `coverUrl` | `string` | | 餐食封面图URL |
|   `dayNumber` | `int` | | 天数编号 |
|   `id` | `string` | | 记录ID |
|   `mealTypes` | `string` | | 餐次：早餐/午餐/晚餐 |
|   `priceInfo` | `string` | | 价格信息 |
|   `quantity` | `int` | | 数量 |
|   `restaurantId` | `string` | | 餐厅ID |
|   `restaurantName` | `string` | | 餐厅/餐食名称 |
|   `sortOrder` | `int` | | 排序序号 |
|   `unitPrice` | `number` | | 餐食单价(元) |
| `message` | `string` | | 响应消息 |
---
### `DELETE` /admin/product/dining/{id}
**删除餐饮推荐**
删除指定的餐饮推荐记录。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` | | 餐饮推荐ID |
**响应** `统一响应结果«Void»`
---
### `PUT` /admin/product/hotel/{id}
**更新每日住宿**
更新住宿记录的酒店、房型、数量等信息。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` | | 住宿记录ID |
**请求体** `每日酒店配置请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `coverUrl` | `string` | | 封面图URL |
| `familyIds` | `string[]` | | 所属家庭ID列表（定制产品，不传=所有家庭共享） |
| `familyRoomConfig` | `object` | | 家庭房间分配（定制产品）：{familyId: roomCount}，如 {"123": 2, "456": 1} |
| `hotelId` | `string` | 是 | 酒店ID |
| `hotelName` | `string` | | 酒店名称 |
| `isDefault` | `boolean` | | 是否默认酒店 |
| `roomCount` | `int` | | 房间数量 |
| `roomTypeId` | `string` | | 关联房型ID（定制产品必填，核心产品为空） |
| `roomTypeName` | `string` | | 房型名称 |
| `sortOrder` | `int` | | 排序序号 |
**响应** `统一响应结果«每日酒店VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `每日酒店VO` | | 响应数据 |
|   `coverUrl` | `string` | | 封面图URL |
|   `dayNumber` | `int` | | 天数编号 |
|   `familyIds` | `string[]` | | 所属家庭ID列表（NULL=所有家庭共享） |
|   `familyRoomConfig` | `object` | | 家庭房间分配：{familyId: roomCount} |
|   `hotelId` | `string` | | 酒店ID |
|   `hotelName` | `string` | | 酒店名称 |
|   `id` | `string` | | 记录ID |
|   `isDefault` | `boolean` | | 是否默认酒店 |
|   `roomCount` | `int` | | 房间数量 |
|   `roomTypeId` | `string` | | 房型ID |
|   `roomTypeName` | `string` | | 房型名称 |
|   `sortOrder` | `int` | | 排序序号 |
| `message` | `string` | | 响应消息 |
---
### `DELETE` /admin/product/hotel/{id}
**删除每日住宿**
删除指定住宿记录。删除后该天的住宿成本会从报价中移除。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` | | 住宿记录ID |
**响应** `统一响应结果«Void»`
---
### `PUT` /admin/product/item/{productId}/day/{dayNumber}
**更新行程天**
更新指定天的行程信息，如当天主题、概述等。
行程天在创建产品时根据 tripDays 自动生成，不支持单独增删，只能更新。
dayNumber 从 1 开始，对应第几天的行程。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `dayNumber` | `integer` | | 天数编号 |
| `productId` | `integer` | | 产品ID |
**请求体** `行程天请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `dayTitle` | `string` | | 天标题 |
| `routeSummary` | `string` | | 路线概览 |
**响应** `统一响应结果«行程天VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `行程天VO` | | 响应数据 |
|   `dayId` | `string` | | 行程天ID |
|   `dayNumber` | `int` | | 天数编号 |
|   `dayTitle` | `string` | | 天标题 |
|   `hotels` | `每日酒店VO[]` | | 当日酒店列表 |
|     `coverUrl` | `string` | | 封面图URL |
|     `dayNumber` | `int` | | 天数编号 |
|     `familyIds` | `string[]` | | 所属家庭ID列表（NULL=所有家庭共享） |
|     `familyRoomConfig` | `object` | | 家庭房间分配：{familyId: roomCount} |
|     `hotelId` | `string` | | 酒店ID |
|     `hotelName` | `string` | | 酒店名称 |
|     `id` | `string` | | 记录ID |
|     `isDefault` | `boolean` | | 是否默认酒店 |
|     `roomCount` | `int` | | 房间数量 |
|     `roomTypeId` | `string` | | 房型ID |
|     `roomTypeName` | `string` | | 房型名称 |
|     `sortOrder` | `int` | | 排序序号 |
|   `nodes` | `行程节点VO[]` | | 行程节点列表 |
|     `costPrice` | `number` | | 资源成本价（来自资源价格日历） |
|     `dayId` | `string` | | 所属行程天ID |
|     `description` | `string` | | 节点描述 |
|     `distanceKm` | `number` | | 距离（公里） |
|     `durationMinutes` | `int` | | 时长（分钟） |
|     `emojiIcon` | `string` | | 表情图标 |
|     `extraData` | `string` | | 扩展数据（JSON格式） |
|     `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
|     `images` | `string[]` | | 节点图片列表 |
|     `latitude` | `number` | | 纬度 |
|     `longitude` | `number` | | 经度 |
|     `nodeId` | `string` | | 节点ID |
|     `nodeName` | `string` | | 节点名称 |
|     `nodeType` | `string` | | 节点类型：SCENIC/HOTEL/RESTAURANT/ACTIVITY/VEHICLE/SERVICE/FREE/NOTE |
|     `quantity` | `int` | | 数量 |
|     `resourceDetail` | `资源详情` | | 绑定资源的详细信息（含图片、地址等） |
|     `resourceId` | `string` | | 关联资源ID |
|     `resourceName` | `string` | | 关联资源名称 |
|     `resourceType` | `string` | | 关联资源类型：SCENIC_SPOT/HOTEL/RESTAURANT/ACTIVITY/VEHICLE/SERVICE |
|     `sortOrder` | `int` | | 排序序号 |
|     `startTime` | `string` | | 开始时间 |
|   `restaurants` | `用餐选项VO[]` | | 当日用餐列表 |
|     `coverUrl` | `string` | | 餐食封面图URL |
|     `dayNumber` | `int` | | 天数编号 |
|     `id` | `string` | | 记录ID |
|     `mealTypes` | `string` | | 餐次：早餐/午餐/晚餐 |
|     `priceInfo` | `string` | | 价格信息 |
|     `quantity` | `int` | | 数量 |
|     `restaurantId` | `string` | | 餐厅ID |
|     `restaurantName` | `string` | | 餐厅/餐食名称 |
|     `sortOrder` | `int` | | 排序序号 |
|     `unitPrice` | `number` | | 餐食单价(元) |
|   `routeSummary` | `string` | | 路线概览 |
| `message` | `string` | | 响应消息 |
---
### `GET` /admin/product/item/{productId}/day/{dayNumber}/dining
**获取某天的餐厅推荐列表**
获取指定天的所有餐饮推荐，包含餐厅名称、用餐类型、描述等信息。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `dayNumber` | `integer` | | 天数编号 |
| `productId` | `integer` | | 产品ID |
**响应** `统一响应结果«List«用餐选项VO»»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `用餐选项VO[]` | | 响应数据 |
|   `coverUrl` | `string` | | 餐食封面图URL |
|   `dayNumber` | `int` | | 天数编号 |
|   `id` | `string` | | 记录ID |
|   `mealTypes` | `string` | | 餐次：早餐/午餐/晚餐 |
|   `priceInfo` | `string` | | 价格信息 |
|   `quantity` | `int` | | 数量 |
|   `restaurantId` | `string` | | 餐厅ID |
|   `restaurantName` | `string` | | 餐厅/餐食名称 |
|   `sortOrder` | `int` | | 排序序号 |
|   `unitPrice` | `number` | | 餐食单价(元) |
| `message` | `string` | | 响应消息 |
---
### `POST` /admin/product/item/{productId}/day/{dayNumber}/dining
**添加每日餐厅推荐**
为指定天添加餐饮推荐，关联资源服务中的餐厅。
用于展示当天的用餐安排，可按早/午/晚分类。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `dayNumber` | `integer` | | 天数编号 |
| `productId` | `integer` | | 产品ID |
**请求体** `用餐选项请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `coverUrl` | `string` | | 餐食封面图URL |
| `mealTypes` | `string` | | 餐次：早餐/午餐/晚餐 |
| `priceInfo` | `string` | | 价格信息 |
| `quantity` | `int` | | 数量 |
| `restaurantId` | `string` | | 餐厅ID（GROUP产品可不传） |
| `restaurantName` | `string` | | 餐厅/餐食名称 |
| `sortOrder` | `int` | | 排序序号 |
| `unitPrice` | `number` | | 餐食单价(元，GROUP产品用于成本计算) |
**响应** `统一响应结果«用餐选项VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `用餐选项VO` | | 响应数据 |
|   `coverUrl` | `string` | | 餐食封面图URL |
|   `dayNumber` | `int` | | 天数编号 |
|   `id` | `string` | | 记录ID |
|   `mealTypes` | `string` | | 餐次：早餐/午餐/晚餐 |
|   `priceInfo` | `string` | | 价格信息 |
|   `quantity` | `int` | | 数量 |
|   `restaurantId` | `string` | | 餐厅ID |
|   `restaurantName` | `string` | | 餐厅/餐食名称 |
|   `sortOrder` | `int` | | 排序序号 |
|   `unitPrice` | `number` | | 餐食单价(元) |
| `message` | `string` | | 响应消息 |
---
### `POST` /admin/product/item/{productId}/day/{dayNumber}/hotel
**添加每日住宿**
为指定天添加住宿安排，关联资源服务中的酒店和房型。
每天可以有多个住宿选项（如不同档次），参与成本自动计算。
住宿费用会体现在价格日历的成本计算中。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `dayNumber` | `integer` | | 天数编号 |
| `productId` | `integer` | | 产品ID |
**请求体** `每日酒店配置请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `coverUrl` | `string` | | 封面图URL |
| `familyIds` | `string[]` | | 所属家庭ID列表（定制产品，不传=所有家庭共享） |
| `familyRoomConfig` | `object` | | 家庭房间分配（定制产品）：{familyId: roomCount}，如 {"123": 2, "456": 1} |
| `hotelId` | `string` | 是 | 酒店ID |
| `hotelName` | `string` | | 酒店名称 |
| `isDefault` | `boolean` | | 是否默认酒店 |
| `roomCount` | `int` | | 房间数量 |
| `roomTypeId` | `string` | | 关联房型ID（定制产品必填，核心产品为空） |
| `roomTypeName` | `string` | | 房型名称 |
| `sortOrder` | `int` | | 排序序号 |
**响应** `统一响应结果«每日酒店VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `每日酒店VO` | | 响应数据 |
|   `coverUrl` | `string` | | 封面图URL |
|   `dayNumber` | `int` | | 天数编号 |
|   `familyIds` | `string[]` | | 所属家庭ID列表（NULL=所有家庭共享） |
|   `familyRoomConfig` | `object` | | 家庭房间分配：{familyId: roomCount} |
|   `hotelId` | `string` | | 酒店ID |
|   `hotelName` | `string` | | 酒店名称 |
|   `id` | `string` | | 记录ID |
|   `isDefault` | `boolean` | | 是否默认酒店 |
|   `roomCount` | `int` | | 房间数量 |
|   `roomTypeId` | `string` | | 房型ID |
|   `roomTypeName` | `string` | | 房型名称 |
|   `sortOrder` | `int` | | 排序序号 |
| `message` | `string` | | 响应消息 |
---
### `GET` /admin/product/item/{productId}/day/{dayNumber}/hotels
**获取某天的住宿列表**
获取指定天的所有住宿安排，包含酒店名称、房型、数量等信息。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `dayNumber` | `integer` | | 天数编号 |
| `productId` | `integer` | | 产品ID |
**响应** `统一响应结果«List«每日酒店VO»»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `每日酒店VO[]` | | 响应数据 |
|   `coverUrl` | `string` | | 封面图URL |
|   `dayNumber` | `int` | | 天数编号 |
|   `familyIds` | `string[]` | | 所属家庭ID列表（NULL=所有家庭共享） |
|   `familyRoomConfig` | `object` | | 家庭房间分配：{familyId: roomCount} |
|   `hotelId` | `string` | | 酒店ID |
|   `hotelName` | `string` | | 酒店名称 |
|   `id` | `string` | | 记录ID |
|   `isDefault` | `boolean` | | 是否默认酒店 |
|   `roomCount` | `int` | | 房间数量 |
|   `roomTypeId` | `string` | | 房型ID |
|   `roomTypeName` | `string` | | 房型名称 |
|   `sortOrder` | `int` | | 排序序号 |
| `message` | `string` | | 响应消息 |
---
### `POST` /admin/product/item/{productId}/day/{dayNumber}/node
**添加行程节点**
在指定天添加一个行程节点。节点是行程的最小单元，可关联资源服务中的景区、酒店、活动等。
**节点类型**：TRANSPORT(交通)/SCENIC(景区)/DINING(餐饮)/ACTIVITY(活动)/PHOTOGRAPHY(摄影)/HOTEL(酒店)/FREE(自由活动)/CUSTOM(自定义)
**CUSTOM 定制产品特有**：可通过 familyIds 指定节点所属的家庭分组，实现按家庭分配行程。
新建节点自动追加到当天最后位置，可通过排序接口调整顺序。
**关联字典**：
- city（城市，资源面板筛选用）：用于在添加节点时按城市筛选可选资源
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `dayNumber` | `integer` | | 天数编号 |
| `productId` | `integer` | | 产品ID |
**请求体** `创建行程节点请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `description` | `string` | | 节点描述 |
| `distanceKm` | `number` | | 距离（公里） |
| `durationMinutes` | `int` | | 时长（分钟） |
| `emojiIcon` | `string` | | 表情图标 |
| `extraData` | `string` | | 扩展数据（JSON格式） |
| `familyIds` | `string[]` | | 所属家庭ID列表（仅CUSTOM定制产品使用，实现按家庭分配行程节点） |
| `images` | `string[]` | | 节点图片列表 |
| `latitude` | `number` | | 纬度 |
| `longitude` | `number` | | 经度 |
| `nodeName` | `string` | 是 | 节点名称 |
| `nodeType` | `string` | 是 | 节点类型：TRANSPORT(交通)/SCENIC(景区)/DINING(餐饮)/ACTIVITY(活动)/PHOTOGRAPHY(摄影)/HOTEL(酒店)/FREE(自由活动)/CUSTOM(自定义) |
| `quantity` | `int` | | 数量 |
| `resourceId` | `string` | | 关联资源ID（来自资源服务，关联后节点名称和图片可自动同步） |
| `resourceType` | `string` | | 关联资源类型（关联后可从资源服务获取价格参与成本计算）：SCENIC/HOTEL/RESTAURANT/ACTIVITY/VEHICLE/SERVICE |
| `startTime` | `string` | | 开始时间 |
**响应** `统一响应结果«行程节点VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `行程节点VO` | | 响应数据 |
|   `costPrice` | `number` | | 资源成本价（来自资源价格日历） |
|   `dayId` | `string` | | 所属行程天ID |
|   `description` | `string` | | 节点描述 |
|   `distanceKm` | `number` | | 距离（公里） |
|   `durationMinutes` | `int` | | 时长（分钟） |
|   `emojiIcon` | `string` | | 表情图标 |
|   `extraData` | `string` | | 扩展数据（JSON格式） |
|   `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
|   `images` | `string[]` | | 节点图片列表 |
|   `latitude` | `number` | | 纬度 |
|   `longitude` | `number` | | 经度 |
|   `nodeId` | `string` | | 节点ID |
|   `nodeName` | `string` | | 节点名称 |
|   `nodeType` | `string` | | 节点类型：SCENIC/HOTEL/RESTAURANT/ACTIVITY/VEHICLE/SERVICE/FREE/NOTE |
|   `quantity` | `int` | | 数量 |
|   `resourceDetail` | `资源详情` | | 绑定资源的详细信息（含图片、地址等） |
|     `address` | `string` | | 地址 |
|     `city` | `string` | | 所在城市 |
|     `cover` | `string` | | 封面图URL |
|     `description` | `string` | | 简介/描述 |
|     `featureIntro` | `string` | | 图文详情（featureIntro JSON） |
|     `images` | `string[]` | | 图片URL列表（轮播图） |
|     `latitude` | `number` | | 纬度 |
|     `longitude` | `number` | | 经度 |
|     `name` | `string` | | 资源名称 |
|     `rating` | `number` | | 评分 |
|     `resourceId` | `string` | | 资源ID |
|     `resourceType` | `string` | | 资源类型: SCENIC_SPOT/HOTEL/RESTAURANT/ACTIVITY |
|     `subtitle` | `string` | | 副标题 |
|     `tags` | `string[]` | | 标签列表 |
|   `resourceId` | `string` | | 关联资源ID |
|   `resourceName` | `string` | | 关联资源名称 |
|   `resourceType` | `string` | | 关联资源类型：SCENIC_SPOT/HOTEL/RESTAURANT/ACTIVITY/VEHICLE/SERVICE |
|   `sortOrder` | `int` | | 排序序号 |
|   `startTime` | `string` | | 开始时间 |
| `message` | `string` | | 响应消息 |
---
### `GET` /admin/product/item/{productId}/day/{dayNumber}/nodes
**获取某天的节点列表**
获取指定天的所有行程节点，按排序顺序返回。
每个节点包含类型、名称、时间、关联资源信息、图片等完整数据。
**关联字典**：
- city（城市）：资源面板城市筛选
- cities（城市ID映射）：城市名称预览
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `dayNumber` | `integer` | | 天数编号 |
| `productId` | `integer` | | 产品ID |
**响应** `统一响应结果«List«行程节点VO»»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `行程节点VO[]` | | 响应数据 |
|   `costPrice` | `number` | | 资源成本价（来自资源价格日历） |
|   `dayId` | `string` | | 所属行程天ID |
|   `description` | `string` | | 节点描述 |
|   `distanceKm` | `number` | | 距离（公里） |
|   `durationMinutes` | `int` | | 时长（分钟） |
|   `emojiIcon` | `string` | | 表情图标 |
|   `extraData` | `string` | | 扩展数据（JSON格式） |
|   `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
|   `images` | `string[]` | | 节点图片列表 |
|   `latitude` | `number` | | 纬度 |
|   `longitude` | `number` | | 经度 |
|   `nodeId` | `string` | | 节点ID |
|   `nodeName` | `string` | | 节点名称 |
|   `nodeType` | `string` | | 节点类型：SCENIC/HOTEL/RESTAURANT/ACTIVITY/VEHICLE/SERVICE/FREE/NOTE |
|   `quantity` | `int` | | 数量 |
|   `resourceDetail` | `资源详情` | | 绑定资源的详细信息（含图片、地址等） |
|     `address` | `string` | | 地址 |
|     `city` | `string` | | 所在城市 |
|     `cover` | `string` | | 封面图URL |
|     `description` | `string` | | 简介/描述 |
|     `featureIntro` | `string` | | 图文详情（featureIntro JSON） |
|     `images` | `string[]` | | 图片URL列表（轮播图） |
|     `latitude` | `number` | | 纬度 |
|     `longitude` | `number` | | 经度 |
|     `name` | `string` | | 资源名称 |
|     `rating` | `number` | | 评分 |
|     `resourceId` | `string` | | 资源ID |
|     `resourceType` | `string` | | 资源类型: SCENIC_SPOT/HOTEL/RESTAURANT/ACTIVITY |
|     `subtitle` | `string` | | 副标题 |
|     `tags` | `string[]` | | 标签列表 |
|   `resourceId` | `string` | | 关联资源ID |
|   `resourceName` | `string` | | 关联资源名称 |
|   `resourceType` | `string` | | 关联资源类型：SCENIC_SPOT/HOTEL/RESTAURANT/ACTIVITY/VEHICLE/SERVICE |
|   `sortOrder` | `int` | | 排序序号 |
|   `startTime` | `string` | | 开始时间 |
| `message` | `string` | | 响应消息 |
---
### `PUT` /admin/product/item/{productId}/day/{dayNumber}/nodes/sort
**行程节点拖拽排序**
重新排列指定天的所有行程节点顺序。前端拖拽排序后，将新的节点ID顺序全量提交。
nodeIds 列表中的顺序即为新的排序顺序（从上到下）。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `dayNumber` | `integer` | | 天数编号 |
| `productId` | `integer` | | 产品ID |
**请求体** `节点排序请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `nodeIds` | `string[]` | 是 | 节点ID有序列表，按期望排序顺序排列 |
**响应** `统一响应结果«Void»`
---
### `GET` /admin/product/item/{productId}/days
**获取行程天列表**
获取产品所有行程天的信息，按 dayNumber 升序排列。
每一天包含当天主题、概述等信息，不包含节点详情（节点通过单独接口获取）。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `productId` | `integer` | | 产品ID |
**响应** `统一响应结果«List«行程天VO»»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `行程天VO[]` | | 响应数据 |
|   `dayId` | `string` | | 行程天ID |
|   `dayNumber` | `int` | | 天数编号 |
|   `dayTitle` | `string` | | 天标题 |
|   `hotels` | `每日酒店VO[]` | | 当日酒店列表 |
|     `coverUrl` | `string` | | 封面图URL |
|     `dayNumber` | `int` | | 天数编号 |
|     `familyIds` | `string[]` | | 所属家庭ID列表（NULL=所有家庭共享） |
|     `familyRoomConfig` | `object` | | 家庭房间分配：{familyId: roomCount} |
|     `hotelId` | `string` | | 酒店ID |
|     `hotelName` | `string` | | 酒店名称 |
|     `id` | `string` | | 记录ID |
|     `isDefault` | `boolean` | | 是否默认酒店 |
|     `roomCount` | `int` | | 房间数量 |
|     `roomTypeId` | `string` | | 房型ID |
|     `roomTypeName` | `string` | | 房型名称 |
|     `sortOrder` | `int` | | 排序序号 |
|   `nodes` | `行程节点VO[]` | | 行程节点列表 |
|     `costPrice` | `number` | | 资源成本价（来自资源价格日历） |
|     `dayId` | `string` | | 所属行程天ID |
|     `description` | `string` | | 节点描述 |
|     `distanceKm` | `number` | | 距离（公里） |
|     `durationMinutes` | `int` | | 时长（分钟） |
|     `emojiIcon` | `string` | | 表情图标 |
|     `extraData` | `string` | | 扩展数据（JSON格式） |
|     `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
|     `images` | `string[]` | | 节点图片列表 |
|     `latitude` | `number` | | 纬度 |
|     `longitude` | `number` | | 经度 |
|     `nodeId` | `string` | | 节点ID |
|     `nodeName` | `string` | | 节点名称 |
|     `nodeType` | `string` | | 节点类型：SCENIC/HOTEL/RESTAURANT/ACTIVITY/VEHICLE/SERVICE/FREE/NOTE |
|     `quantity` | `int` | | 数量 |
|     `resourceDetail` | `资源详情` | | 绑定资源的详细信息（含图片、地址等） |
|     `resourceId` | `string` | | 关联资源ID |
|     `resourceName` | `string` | | 关联资源名称 |
|     `resourceType` | `string` | | 关联资源类型：SCENIC_SPOT/HOTEL/RESTAURANT/ACTIVITY/VEHICLE/SERVICE |
|     `sortOrder` | `int` | | 排序序号 |
|     `startTime` | `string` | | 开始时间 |
|   `restaurants` | `用餐选项VO[]` | | 当日用餐列表 |
|     `coverUrl` | `string` | | 餐食封面图URL |
|     `dayNumber` | `int` | | 天数编号 |
|     `id` | `string` | | 记录ID |
|     `mealTypes` | `string` | | 餐次：早餐/午餐/晚餐 |
|     `priceInfo` | `string` | | 价格信息 |
|     `quantity` | `int` | | 数量 |
|     `restaurantId` | `string` | | 餐厅ID |
|     `restaurantName` | `string` | | 餐厅/餐食名称 |
|     `sortOrder` | `int` | | 排序序号 |
|     `unitPrice` | `number` | | 餐食单价(元) |
|   `routeSummary` | `string` | | 路线概览 |
| `message` | `string` | | 响应消息 |
---
### `POST` /admin/product/item/{productId}/staff-config
**添加人员配置**
为产品添加服务人员配置（如领队、摄影师、司机等），关联资源服务中的人员。
人员配置是产品级别的模板，GROUP 产品的实际人员在团期批次中单独分配。
人员费用参与成本自动计算。
**关联字典**：
- staff_type（人员类型）：GUIDE=领队, DRIVER=司机, PHOTOGRAPHER=摄影师, ASSISTANT=助理, OTHER=其他
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `productId` | `integer` | | 产品ID |
**请求体** `人员配置请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
| `quantity` | `int` | 是 | 数量 |
| `sortOrder` | `int` | | 排序序号 |
| `staffType` | `string` | 是 | 人员类型：GUIDE/GUIDE_ASSISTANT/PHOTOGRAPHER/LEADER/OTHER |
**响应** `统一响应结果«产品人员配置VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `产品人员配置VO` | | 响应数据 |
|   `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
|   `id` | `string` | | 记录ID |
|   `quantity` | `int` | | 数量 |
|   `sortOrder` | `int` | | 排序序号 |
|   `staffType` | `string` | | 人员类型：GUIDE/GUIDE_ASSISTANT/PHOTOGRAPHER/LEADER/OTHER |
|   `staffTypeName` | `string` | | 人员类型名称 |
| `message` | `string` | | 响应消息 |
---
### `GET` /admin/product/item/{productId}/staff-configs
**获取产品人员配置列表**
**关联字典**：
- staff_type（人员类型）：GUIDE=领队, DRIVER=司机, PHOTOGRAPHER=摄影师, ASSISTANT=助理, OTHER=其他
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `productId` | `integer` | | 产品ID |
**响应** `统一响应结果«List«产品人员配置VO»»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `产品人员配置VO[]` | | 响应数据 |
|   `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
|   `id` | `string` | | 记录ID |
|   `quantity` | `int` | | 数量 |
|   `sortOrder` | `int` | | 排序序号 |
|   `staffType` | `string` | | 人员类型：GUIDE/GUIDE_ASSISTANT/PHOTOGRAPHER/LEADER/OTHER |
|   `staffTypeName` | `string` | | 人员类型名称 |
| `message` | `string` | | 响应消息 |
---
### `GET` /admin/product/item/{productId}/supplies
**获取产品物资列表**
获取产品关联的所有物资配品，包含物资名称、数量、单价等信息。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `productId` | `integer` | | 产品ID |
**响应** `统一响应结果«List«产品物资VO»»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `产品物资VO[]` | | 响应数据 |
|   `billingType` | `string` | | 计费方式：BY_PERSON=按人头 BY_COUNT=按次/按件 |
|   `costPerPerson` | `number` | | 每人成本 |
|   `coverUrl` | `string` | | 封面图URL |
|   `dayNumber` | `int` | | 天数编号（scope=DAY时生效） |
|   `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
|   `id` | `string` | | 记录ID |
|   `quantity` | `int` | | 数量 |
|   `scope` | `string` | | 适用范围：ALL=整个行程 DAY=指定天 |
|   `sortOrder` | `int` | | 排序序号 |
|   `suppliesId` | `string` | | 物资ID |
|   `suppliesName` | `string` | | 物资名称 |
| `message` | `string` | | 响应消息 |
---
### `POST` /admin/product/item/{productId}/supplies
**添加物资配品**
为产品添加物资配品（如帐篷、睡袋、登山杖等），关联资源服务中的物资。
物资配品是产品级别的，不区分具体哪一天，参与成本计算。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `productId` | `integer` | | 产品ID |
**请求体** `物资配置请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `billingType` | `string` | | 计费方式：BY_PERSON=按人头 BY_COUNT=按次/按件 |
| `costPerPerson` | `number` | | 每人成本 |
| `coverUrl` | `string` | | 封面图URL |
| `dayNumber` | `int` | | 天数编号（scope=DAY时生效） |
| `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
| `quantity` | `int` | | 数量 |
| `scope` | `string` | | 适用范围：ALL=整个行程 DAY=指定天 |
| `sortOrder` | `int` | | 排序序号 |
| `suppliesId` | `string` | 是 | 物资ID |
| `suppliesName` | `string` | | 物资名称 |
**响应** `统一响应结果«产品物资VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `产品物资VO` | | 响应数据 |
|   `billingType` | `string` | | 计费方式：BY_PERSON=按人头 BY_COUNT=按次/按件 |
|   `costPerPerson` | `number` | | 每人成本 |
|   `coverUrl` | `string` | | 封面图URL |
|   `dayNumber` | `int` | | 天数编号（scope=DAY时生效） |
|   `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
|   `id` | `string` | | 记录ID |
|   `quantity` | `int` | | 数量 |
|   `scope` | `string` | | 适用范围：ALL=整个行程 DAY=指定天 |
|   `sortOrder` | `int` | | 排序序号 |
|   `suppliesId` | `string` | | 物资ID |
|   `suppliesName` | `string` | | 物资名称 |
| `message` | `string` | | 响应消息 |
---
### `PUT` /admin/product/node/{nodeId}
**更新行程节点**
更新行程节点信息，仅传入需要修改的字段。
可修改节点名称、时间、关联资源、图片、描述等。
**关联字典**：
- city（城市）：资源面板城市筛选
- cities（城市ID映射）：城市名称预览
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `nodeId` | `integer` | | 行程节点ID |
**请求体** `更新行程节点请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `description` | `string` | | 节点描述 |
| `distanceKm` | `number` | | 距离（公里） |
| `durationMinutes` | `int` | | 时长（分钟） |
| `emojiIcon` | `string` | | 表情图标 |
| `extraData` | `string` | | 扩展数据（JSON格式） |
| `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
| `images` | `string[]` | | 节点图片列表 |
| `latitude` | `number` | | 纬度 |
| `longitude` | `number` | | 经度 |
| `nodeName` | `string` | | 节点名称 |
| `nodeType` | `string` | | 节点类型：TRANSPORT(交通)/SCENIC(景区)/DINING(餐饮)/ACTIVITY(活动)/PHOTOGRAPHY(摄影)/HOTEL(酒店)/FREE(自由活动)/CUSTOM(自定义) |
| `quantity` | `int` | | 数量 |
| `resourceId` | `string` | | 关联资源ID |
| `resourceType` | `string` | | 关联资源类型：SCENIC_SPOT/HOTEL/RESTAURANT/ACTIVITY/VEHICLE/SERVICE |
| `startTime` | `string` | | 开始时间 |
**响应** `统一响应结果«行程节点VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `行程节点VO` | | 响应数据 |
|   `costPrice` | `number` | | 资源成本价（来自资源价格日历） |
|   `dayId` | `string` | | 所属行程天ID |
|   `description` | `string` | | 节点描述 |
|   `distanceKm` | `number` | | 距离（公里） |
|   `durationMinutes` | `int` | | 时长（分钟） |
|   `emojiIcon` | `string` | | 表情图标 |
|   `extraData` | `string` | | 扩展数据（JSON格式） |
|   `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
|   `images` | `string[]` | | 节点图片列表 |
|   `latitude` | `number` | | 纬度 |
|   `longitude` | `number` | | 经度 |
|   `nodeId` | `string` | | 节点ID |
|   `nodeName` | `string` | | 节点名称 |
|   `nodeType` | `string` | | 节点类型：SCENIC/HOTEL/RESTAURANT/ACTIVITY/VEHICLE/SERVICE/FREE/NOTE |
|   `quantity` | `int` | | 数量 |
|   `resourceDetail` | `资源详情` | | 绑定资源的详细信息（含图片、地址等） |
|     `address` | `string` | | 地址 |
|     `city` | `string` | | 所在城市 |
|     `cover` | `string` | | 封面图URL |
|     `description` | `string` | | 简介/描述 |
|     `featureIntro` | `string` | | 图文详情（featureIntro JSON） |
|     `images` | `string[]` | | 图片URL列表（轮播图） |
|     `latitude` | `number` | | 纬度 |
|     `longitude` | `number` | | 经度 |
|     `name` | `string` | | 资源名称 |
|     `rating` | `number` | | 评分 |
|     `resourceId` | `string` | | 资源ID |
|     `resourceType` | `string` | | 资源类型: SCENIC_SPOT/HOTEL/RESTAURANT/ACTIVITY |
|     `subtitle` | `string` | | 副标题 |
|     `tags` | `string[]` | | 标签列表 |
|   `resourceId` | `string` | | 关联资源ID |
|   `resourceName` | `string` | | 关联资源名称 |
|   `resourceType` | `string` | | 关联资源类型：SCENIC_SPOT/HOTEL/RESTAURANT/ACTIVITY/VEHICLE/SERVICE |
|   `sortOrder` | `int` | | 排序序号 |
|   `startTime` | `string` | | 开始时间 |
| `message` | `string` | | 响应消息 |
---
### `DELETE` /admin/product/node/{nodeId}
**删除行程节点**
删除指定行程节点，同天其他节点的排序自动调整。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `nodeId` | `integer` | | 行程节点ID |
**响应** `统一响应结果«Void»`
---
### `POST` /admin/product/node/{nodeId}/copy
**复制行程节点**
复制指定节点到同一天的末尾位置，包括节点的所有属性（名称、资源关联、图片等）。
适用场景：同一天有相似的行程安排时快速复制。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `nodeId` | `integer` | | 行程节点ID |
**响应** `统一响应结果«行程节点VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `行程节点VO` | | 响应数据 |
|   `costPrice` | `number` | | 资源成本价（来自资源价格日历） |
|   `dayId` | `string` | | 所属行程天ID |
|   `description` | `string` | | 节点描述 |
|   `distanceKm` | `number` | | 距离（公里） |
|   `durationMinutes` | `int` | | 时长（分钟） |
|   `emojiIcon` | `string` | | 表情图标 |
|   `extraData` | `string` | | 扩展数据（JSON格式） |
|   `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
|   `images` | `string[]` | | 节点图片列表 |
|   `latitude` | `number` | | 纬度 |
|   `longitude` | `number` | | 经度 |
|   `nodeId` | `string` | | 节点ID |
|   `nodeName` | `string` | | 节点名称 |
|   `nodeType` | `string` | | 节点类型：SCENIC/HOTEL/RESTAURANT/ACTIVITY/VEHICLE/SERVICE/FREE/NOTE |
|   `quantity` | `int` | | 数量 |
|   `resourceDetail` | `资源详情` | | 绑定资源的详细信息（含图片、地址等） |
|     `address` | `string` | | 地址 |
|     `city` | `string` | | 所在城市 |
|     `cover` | `string` | | 封面图URL |
|     `description` | `string` | | 简介/描述 |
|     `featureIntro` | `string` | | 图文详情（featureIntro JSON） |
|     `images` | `string[]` | | 图片URL列表（轮播图） |
|     `latitude` | `number` | | 纬度 |
|     `longitude` | `number` | | 经度 |
|     `name` | `string` | | 资源名称 |
|     `rating` | `number` | | 评分 |
|     `resourceId` | `string` | | 资源ID |
|     `resourceType` | `string` | | 资源类型: SCENIC_SPOT/HOTEL/RESTAURANT/ACTIVITY |
|     `subtitle` | `string` | | 副标题 |
|     `tags` | `string[]` | | 标签列表 |
|   `resourceId` | `string` | | 关联资源ID |
|   `resourceName` | `string` | | 关联资源名称 |
|   `resourceType` | `string` | | 关联资源类型：SCENIC_SPOT/HOTEL/RESTAURANT/ACTIVITY/VEHICLE/SERVICE |
|   `sortOrder` | `int` | | 排序序号 |
|   `startTime` | `string` | | 开始时间 |
| `message` | `string` | | 响应消息 |
---
### `PUT` /admin/product/node/{nodeId}/move
**移动行程节点到其他天**
将节点从当前天移动到目标天的末尾位置。
移动后原天和目标天的节点排序自动调整。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `nodeId` | `integer` | | 行程节点ID |
**请求体** `节点移动请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `targetDayNumber` | `int` | 是 | 目标天数编号 |
**响应** `统一响应结果«行程节点VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `行程节点VO` | | 响应数据 |
|   `costPrice` | `number` | | 资源成本价（来自资源价格日历） |
|   `dayId` | `string` | | 所属行程天ID |
|   `description` | `string` | | 节点描述 |
|   `distanceKm` | `number` | | 距离（公里） |
|   `durationMinutes` | `int` | | 时长（分钟） |
|   `emojiIcon` | `string` | | 表情图标 |
|   `extraData` | `string` | | 扩展数据（JSON格式） |
|   `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
|   `images` | `string[]` | | 节点图片列表 |
|   `latitude` | `number` | | 纬度 |
|   `longitude` | `number` | | 经度 |
|   `nodeId` | `string` | | 节点ID |
|   `nodeName` | `string` | | 节点名称 |
|   `nodeType` | `string` | | 节点类型：SCENIC/HOTEL/RESTAURANT/ACTIVITY/VEHICLE/SERVICE/FREE/NOTE |
|   `quantity` | `int` | | 数量 |
|   `resourceDetail` | `资源详情` | | 绑定资源的详细信息（含图片、地址等） |
|     `address` | `string` | | 地址 |
|     `city` | `string` | | 所在城市 |
|     `cover` | `string` | | 封面图URL |
|     `description` | `string` | | 简介/描述 |
|     `featureIntro` | `string` | | 图文详情（featureIntro JSON） |
|     `images` | `string[]` | | 图片URL列表（轮播图） |
|     `latitude` | `number` | | 纬度 |
|     `longitude` | `number` | | 经度 |
|     `name` | `string` | | 资源名称 |
|     `rating` | `number` | | 评分 |
|     `resourceId` | `string` | | 资源ID |
|     `resourceType` | `string` | | 资源类型: SCENIC_SPOT/HOTEL/RESTAURANT/ACTIVITY |
|     `subtitle` | `string` | | 副标题 |
|     `tags` | `string[]` | | 标签列表 |
|   `resourceId` | `string` | | 关联资源ID |
|   `resourceName` | `string` | | 关联资源名称 |
|   `resourceType` | `string` | | 关联资源类型：SCENIC_SPOT/HOTEL/RESTAURANT/ACTIVITY/VEHICLE/SERVICE |
|   `sortOrder` | `int` | | 排序序号 |
|   `startTime` | `string` | | 开始时间 |
| `message` | `string` | | 响应消息 |
---
### `PUT` /admin/product/staff-config/{id}
**更新人员配置**
**关联字典**：
- staff_type（人员类型）：GUIDE=领队, DRIVER=司机, PHOTOGRAPHER=摄影师, ASSISTANT=助理, OTHER=其他
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` | | 人员配置ID |
**请求体** `人员配置请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
| `quantity` | `int` | 是 | 数量 |
| `sortOrder` | `int` | | 排序序号 |
| `staffType` | `string` | 是 | 人员类型：GUIDE/GUIDE_ASSISTANT/PHOTOGRAPHER/LEADER/OTHER |
**响应** `统一响应结果«产品人员配置VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `产品人员配置VO` | | 响应数据 |
|   `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
|   `id` | `string` | | 记录ID |
|   `quantity` | `int` | | 数量 |
|   `sortOrder` | `int` | | 排序序号 |
|   `staffType` | `string` | | 人员类型：GUIDE/GUIDE_ASSISTANT/PHOTOGRAPHER/LEADER/OTHER |
|   `staffTypeName` | `string` | | 人员类型名称 |
| `message` | `string` | | 响应消息 |
---
### `DELETE` /admin/product/staff-config/{id}
**删除人员配置**
删除指定的人员配置记录。删除后该人员费用不再计入成本。
**关联字典**：
- staff_type（人员类型）：GUIDE=领队, DRIVER=司机, PHOTOGRAPHER=摄影师, ASSISTANT=助理, OTHER=其他
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` | | 人员配置ID |
**响应** `统一响应结果«Void»`
---
### `PUT` /admin/product/supplies/{id}
**更新物资配品**
更新物资配品的关联物资、数量等信息。修改后会影响成本自动计算结果。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` | | 物资配品ID |
**请求体** `物资配置请求`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `billingType` | `string` | | 计费方式：BY_PERSON=按人头 BY_COUNT=按次/按件 |
| `costPerPerson` | `number` | | 每人成本 |
| `coverUrl` | `string` | | 封面图URL |
| `dayNumber` | `int` | | 天数编号（scope=DAY时生效） |
| `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
| `quantity` | `int` | | 数量 |
| `scope` | `string` | | 适用范围：ALL=整个行程 DAY=指定天 |
| `sortOrder` | `int` | | 排序序号 |
| `suppliesId` | `string` | 是 | 物资ID |
| `suppliesName` | `string` | | 物资名称 |
**响应** `统一响应结果«产品物资VO»`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` | | 状态码 |
| `data` | `产品物资VO` | | 响应数据 |
|   `billingType` | `string` | | 计费方式：BY_PERSON=按人头 BY_COUNT=按次/按件 |
|   `costPerPerson` | `number` | | 每人成本 |
|   `coverUrl` | `string` | | 封面图URL |
|   `dayNumber` | `int` | | 天数编号（scope=DAY时生效） |
|   `familyIds` | `string[]` | | 所属家庭ID列表（定制产品按家庭分配） |
|   `id` | `string` | | 记录ID |
|   `quantity` | `int` | | 数量 |
|   `scope` | `string` | | 适用范围：ALL=整个行程 DAY=指定天 |
|   `sortOrder` | `int` | | 排序序号 |
|   `suppliesId` | `string` | | 物资ID |
|   `suppliesName` | `string` | | 物资名称 |
| `message` | `string` | | 响应消息 |
---
### `DELETE` /admin/product/supplies/{id}
**删除物资配品**
删除指定的物资配品记录。删除后该物资费用不再计入成本。
**路径参数**
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` | | 物资配品ID |
**响应** `统一响应结果«Void»`
---
在新工单中引用 查看 Git Blame 复制永久链接