diff --git a/2026-03/17_0951/hl-order-service.md b/2026-03/17_0951/hl-order-service.md new file mode 100644 index 0000000..ed3738c --- /dev/null +++ b/2026-03/17_0951/hl-order-service.md @@ -0,0 +1,3594 @@ +# 订单服务 API 文档 + +**服务**: `hl-order-service` +**接口总数**: 90 + +## 目录 + +- **工单管理** (8 个接口) +- **早鸟优惠计划管理** (6 个接口) +- **管理端相册接口** (10 个接口) +- **管理端订单接口** (24 个接口) +- **管理端订单行程编辑** (18 个接口) +- **订单待办接口** (7 个接口) +- **订单配置接口** (2 个接口) +- **退款政策管理** (6 个接口) +- **退款管理** (9 个接口) + +--- + +## 工单管理 + +### `POST` /admin/order/work-order + +**创建工单** + +创建旅途中的变更工单，需关联订单ID。 +可指定处理人，未指定则进入待分配状态。可附带差价信息和资源详情JSON + +【关联字典】 +- 请求参数 type → 字典：work_order_type（工单类型） +- 请求参数 priority → 字典：work_order_priority（工单优先级） +- 返回字段 status → 字典：work_order_status（工单状态） +- 返回字段 type → 字典：work_order_type（工单类型） +- 返回字段 priority → 字典：work_order_priority（工单优先级） + +**请求体** `CreateWorkOrderRequest` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `assigneeAdminId` | `long` | | 指定处理人ID | +| `assigneeName` | `string` | | 指定处理人姓名 | +| `attachmentUrls` | `string` | | 附件URL(JSON数组) | +| `costDifference` | `number` | | 差价(正数=客户需补差价, 负数=需退费给客户) | +| `description` | `string` | 是 | 问题描述 | +| `orderId` | `long` | 是 | 关联订单ID | +| `priority` | `string` | 是 | 优先级: URGENT(紧急，如当天出发需处理)/NORMAL(普通) | +| `resourceDetail` | `string` | | 资源详情JSON(酒店/车辆/景点信息) | +| `type` | `string` | 是 | 工单类型: ROOM_CHANGE(换房)/ROOM_ADD(加房)/CHECKOUT_CHANGE(改退房日期)/HOTEL_ISSUE(酒店问题)/VEHICLE_CHANGE(换车)/SCENIC_ADD(加景点)/SCENIC_REMOVE(减景点)/OTHER(其他) | + +**响应** `统一响应结果«WorkOrderVO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `WorkOrderVO` | | 响应数据 | +|   `assigneeAdminId` | `string` | | 处理人ID | +|   `assigneeName` | `string` | | 处理人姓名 | +|   `attachmentUrls` | `string` | | 附件URL(JSON数组) | +|   `costDifference` | `number` | | 差价 | +|   `createTime` | `string` | | 创建时间 | +|   `creatorAdminId` | `string` | | 发起人ID | +|   `creatorName` | `string` | | 发起人姓名 | +|   `description` | `string` | | 问题描述 | +|   `logs` | `工单操作日志VO[]` | | 操作日志列表 | +|     `action` | `string` | | 操作动作 | +|     `actionLabel` | `string` | | 操作动作标签 | +|     `content` | `string` | | 操作内容 | +|     `createdAt` | `string` | | 操作时间 | +|     `logId` | `string` | | 日志ID | +|     `operatorName` | `string` | | 操作人姓名 | +|   `orderId` | `string` | | 关联订单ID | +|   `orderNo` | `string` | | 关联订单编号 | +|   `priority` | `string` | | 优先级 | +|   `priorityLabel` | `string` | | 优先级标签 | +|   `rejectReason` | `string` | | 驳回原因 | +|   `resolution` | `string` | | 处理结果 | +|   `resolvedAt` | `string` | | 处理完成时间 | +|   `resourceDetail` | `string` | | 资源详情JSON | +|   `status` | `string` | | 状态 | +|   `statusLabel` | `string` | | 状态标签 | +|   `type` | `string` | | 工单类型 | +|   `typeLabel` | `string` | | 工单类型标签 | +|   `updateTime` | `string` | | 更新时间 | +|   `workOrderId` | `string` | | 工单ID | +|   `workOrderNo` | `string` | | 工单编号 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/order/work-order/count-by-order/{orderId} + +**按订单查工单数量** + +返回指定订单关联的工单总数，用于订单详情页展示工单角标 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `orderId` | `integer` | | 订单ID | + +**响应** `统一响应结果«int»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `int` | | 响应数据 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/order/work-order/list + +**工单列表** + +分页查询工单，支持按状态/类型/优先级/订单编号/处理人筛选。 +工单用于处理旅行中的突发变更需求（如换房、换车、加景点等） + +【关联字典】 +- 筛选参数 status → 字典：work_order_status（工单状态） +- 筛选参数 type → 字典：work_order_type（工单类型） +- 筛选参数 priority → 字典：work_order_priority（工单优先级） +- 返回字段 status → 字典：work_order_status（工单状态） +- 返回字段 type → 字典：work_order_type（工单类型） +- 返回字段 priority → 字典：work_order_priority（工单优先级） + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `assigneeAdminId` | `integer(int64)` | | 处理人ID | | +| `orderNo` | `string` | | 订单编号(模糊) | | +| `page` | `integer(int32)` | | 页码 | | +| `pageSize` | `integer(int32)` | | 每页条数 | | +| `priority` | `string` | | 优先级: URGENT/NORMAL | | +| `status` | `string` | | 状态: PENDING/PROCESSING/RESOLVED/REJECTED | | +| `type` | `string` | | 类型: ROOM_CHANGE/ROOM_ADD/CHECKOUT_CHANGE/HOTEL_ISSUE/VEHICLE_CHANGE/SCENIC_ADD/SCENIC_REMOVE/OTHER | | + +**响应** `统一响应结果«分页结果«WorkOrderVO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«WorkOrderVO»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `WorkOrderVO[]` | | 数据列表 | +|     `assigneeAdminId` | `string` | | 处理人ID | +|     `assigneeName` | `string` | | 处理人姓名 | +|     `attachmentUrls` | `string` | | 附件URL(JSON数组) | +|     `costDifference` | `number` | | 差价 | +|     `createTime` | `string` | | 创建时间 | +|     `creatorAdminId` | `string` | | 发起人ID | +|     `creatorName` | `string` | | 发起人姓名 | +|     `description` | `string` | | 问题描述 | +|     `logs` | `工单操作日志VO[]` | | 操作日志列表 | +|     `orderId` | `string` | | 关联订单ID | +|     `orderNo` | `string` | | 关联订单编号 | +|     `priority` | `string` | | 优先级 | +|     `priorityLabel` | `string` | | 优先级标签 | +|     `rejectReason` | `string` | | 驳回原因 | +|     `resolution` | `string` | | 处理结果 | +|     `resolvedAt` | `string` | | 处理完成时间 | +|     `resourceDetail` | `string` | | 资源详情JSON | +|     `status` | `string` | | 状态 | +|     `statusLabel` | `string` | | 状态标签 | +|     `type` | `string` | | 工单类型 | +|     `typeLabel` | `string` | | 工单类型标签 | +|     `updateTime` | `string` | | 更新时间 | +|     `workOrderId` | `string` | | 工单ID | +|     `workOrderNo` | `string` | | 工单编号 | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/order/work-order/stats + +**工单统计** + +返回各状态的工单数量和紧急工单数，用于工单管理页面顶部统计卡片 + +【关联字典】 +- 返回字段中的状态key → 字典：work_order_status（工单状态） + +**响应** `统一响应结果«Map«string,object»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `object` | | 响应数据 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/order/work-order/{workOrderId} + +**工单详情** + +返回工单完整信息，包括关联订单、资源详情、处理记录和备注列表 + +【关联字典】 +- 返回字段 status → 字典：work_order_status（工单状态） +- 返回字段 type → 字典：work_order_type（工单类型） +- 返回字段 priority → 字典：work_order_priority（工单优先级） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `workOrderId` | `integer` | | 工单ID | + +**响应** `统一响应结果«WorkOrderVO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `WorkOrderVO` | | 响应数据 | +|   `assigneeAdminId` | `string` | | 处理人ID | +|   `assigneeName` | `string` | | 处理人姓名 | +|   `attachmentUrls` | `string` | | 附件URL(JSON数组) | +|   `costDifference` | `number` | | 差价 | +|   `createTime` | `string` | | 创建时间 | +|   `creatorAdminId` | `string` | | 发起人ID | +|   `creatorName` | `string` | | 发起人姓名 | +|   `description` | `string` | | 问题描述 | +|   `logs` | `工单操作日志VO[]` | | 操作日志列表 | +|     `action` | `string` | | 操作动作 | +|     `actionLabel` | `string` | | 操作动作标签 | +|     `content` | `string` | | 操作内容 | +|     `createdAt` | `string` | | 操作时间 | +|     `logId` | `string` | | 日志ID | +|     `operatorName` | `string` | | 操作人姓名 | +|   `orderId` | `string` | | 关联订单ID | +|   `orderNo` | `string` | | 关联订单编号 | +|   `priority` | `string` | | 优先级 | +|   `priorityLabel` | `string` | | 优先级标签 | +|   `rejectReason` | `string` | | 驳回原因 | +|   `resolution` | `string` | | 处理结果 | +|   `resolvedAt` | `string` | | 处理完成时间 | +|   `resourceDetail` | `string` | | 资源详情JSON | +|   `status` | `string` | | 状态 | +|   `statusLabel` | `string` | | 状态标签 | +|   `type` | `string` | | 工单类型 | +|   `typeLabel` | `string` | | 工单类型标签 | +|   `updateTime` | `string` | | 更新时间 | +|   `workOrderId` | `string` | | 工单ID | +|   `workOrderNo` | `string` | | 工单编号 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/order/work-order/{workOrderId}/assign + +**指派工单** + +将工单分配给指定管理员处理。被指派人将在待办列表中看到该工单 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `workOrderId` | `integer` | | 工单ID | + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `assigneeId` | `integer(int64)` | | 处理人ID | | +| `assigneeName` | `string` | | 处理人姓名 | | + +**响应** `统一响应结果«WorkOrderVO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `WorkOrderVO` | | 响应数据 | +|   `assigneeAdminId` | `string` | | 处理人ID | +|   `assigneeName` | `string` | | 处理人姓名 | +|   `attachmentUrls` | `string` | | 附件URL(JSON数组) | +|   `costDifference` | `number` | | 差价 | +|   `createTime` | `string` | | 创建时间 | +|   `creatorAdminId` | `string` | | 发起人ID | +|   `creatorName` | `string` | | 发起人姓名 | +|   `description` | `string` | | 问题描述 | +|   `logs` | `工单操作日志VO[]` | | 操作日志列表 | +|     `action` | `string` | | 操作动作 | +|     `actionLabel` | `string` | | 操作动作标签 | +|     `content` | `string` | | 操作内容 | +|     `createdAt` | `string` | | 操作时间 | +|     `logId` | `string` | | 日志ID | +|     `operatorName` | `string` | | 操作人姓名 | +|   `orderId` | `string` | | 关联订单ID | +|   `orderNo` | `string` | | 关联订单编号 | +|   `priority` | `string` | | 优先级 | +|   `priorityLabel` | `string` | | 优先级标签 | +|   `rejectReason` | `string` | | 驳回原因 | +|   `resolution` | `string` | | 处理结果 | +|   `resolvedAt` | `string` | | 处理完成时间 | +|   `resourceDetail` | `string` | | 资源详情JSON | +|   `status` | `string` | | 状态 | +|   `statusLabel` | `string` | | 状态标签 | +|   `type` | `string` | | 工单类型 | +|   `typeLabel` | `string` | | 工单类型标签 | +|   `updateTime` | `string` | | 更新时间 | +|   `workOrderId` | `string` | | 工单ID | +|   `workOrderNo` | `string` | | 工单编号 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/order/work-order/{workOrderId}/comment + +**添加工单备注** + +在工单中追加备注信息，用于内部沟通和处理过程记录 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `workOrderId` | `integer` | | 工单ID | + +**请求体** `object` + +**响应** `统一响应结果«WorkOrderVO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `WorkOrderVO` | | 响应数据 | +|   `assigneeAdminId` | `string` | | 处理人ID | +|   `assigneeName` | `string` | | 处理人姓名 | +|   `attachmentUrls` | `string` | | 附件URL(JSON数组) | +|   `costDifference` | `number` | | 差价 | +|   `createTime` | `string` | | 创建时间 | +|   `creatorAdminId` | `string` | | 发起人ID | +|   `creatorName` | `string` | | 发起人姓名 | +|   `description` | `string` | | 问题描述 | +|   `logs` | `工单操作日志VO[]` | | 操作日志列表 | +|     `action` | `string` | | 操作动作 | +|     `actionLabel` | `string` | | 操作动作标签 | +|     `content` | `string` | | 操作内容 | +|     `createdAt` | `string` | | 操作时间 | +|     `logId` | `string` | | 日志ID | +|     `operatorName` | `string` | | 操作人姓名 | +|   `orderId` | `string` | | 关联订单ID | +|   `orderNo` | `string` | | 关联订单编号 | +|   `priority` | `string` | | 优先级 | +|   `priorityLabel` | `string` | | 优先级标签 | +|   `rejectReason` | `string` | | 驳回原因 | +|   `resolution` | `string` | | 处理结果 | +|   `resolvedAt` | `string` | | 处理完成时间 | +|   `resourceDetail` | `string` | | 资源详情JSON | +|   `status` | `string` | | 状态 | +|   `statusLabel` | `string` | | 状态标签 | +|   `type` | `string` | | 工单类型 | +|   `typeLabel` | `string` | | 工单类型标签 | +|   `updateTime` | `string` | | 更新时间 | +|   `workOrderId` | `string` | | 工单ID | +|   `workOrderNo` | `string` | | 工单编号 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/order/work-order/{workOrderId}/process + +**处理工单（解决/驳回）** + +解决时需填写处理结果(resolution)，驳回时需填写驳回原因(rejectReason)。 +可调整差价(costDifference)，正数表示加价，负数表示退费 + +【关联字典】 +- 返回字段 status → 字典：work_order_status（工单状态） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `workOrderId` | `integer` | | 工单ID | + +**请求体** `ProcessWorkOrderRequest` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `action` | `string` | 是 | 操作: RESOLVE(解决) / REJECT(驳回) | +| `costDifference` | `number` | | 调整后差价 | +| `rejectReason` | `string` | | 驳回原因(驳回时填写) | +| `resolution` | `string` | | 处理结果(解决时填写) | + +**响应** `统一响应结果«WorkOrderVO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `WorkOrderVO` | | 响应数据 | +|   `assigneeAdminId` | `string` | | 处理人ID | +|   `assigneeName` | `string` | | 处理人姓名 | +|   `attachmentUrls` | `string` | | 附件URL(JSON数组) | +|   `costDifference` | `number` | | 差价 | +|   `createTime` | `string` | | 创建时间 | +|   `creatorAdminId` | `string` | | 发起人ID | +|   `creatorName` | `string` | | 发起人姓名 | +|   `description` | `string` | | 问题描述 | +|   `logs` | `工单操作日志VO[]` | | 操作日志列表 | +|     `action` | `string` | | 操作动作 | +|     `actionLabel` | `string` | | 操作动作标签 | +|     `content` | `string` | | 操作内容 | +|     `createdAt` | `string` | | 操作时间 | +|     `logId` | `string` | | 日志ID | +|     `operatorName` | `string` | | 操作人姓名 | +|   `orderId` | `string` | | 关联订单ID | +|   `orderNo` | `string` | | 关联订单编号 | +|   `priority` | `string` | | 优先级 | +|   `priorityLabel` | `string` | | 优先级标签 | +|   `rejectReason` | `string` | | 驳回原因 | +|   `resolution` | `string` | | 处理结果 | +|   `resolvedAt` | `string` | | 处理完成时间 | +|   `resourceDetail` | `string` | | 资源详情JSON | +|   `status` | `string` | | 状态 | +|   `statusLabel` | `string` | | 状态标签 | +|   `type` | `string` | | 工单类型 | +|   `typeLabel` | `string` | | 工单类型标签 | +|   `updateTime` | `string` | | 更新时间 | +|   `workOrderId` | `string` | | 工单ID | +|   `workOrderNo` | `string` | | 工单编号 | +| `message` | `string` | | 响应消息 | + +--- + +## 早鸟优惠计划管理 + +### `POST` /admin/order/early-bird + +**创建早鸟优惠计划** + +创建一个早鸟优惠计划，在指定日期范围内下单且满足最低人数条件的订单可享受优惠。 +下单时系统自动匹配最优的早鸟计划。权限：仅超级管理员(SUPER_ADMIN) + +**请求体** `早鸟优惠计划请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `discountAmount` | `number` | 是 | 优惠金额（从订单总价中扣减的固定金额） | +| `endDate` | `string` | 是 | 生效结束日期 | +| `minPeople` | `int` | 是 | 最低出行人数（含成人+儿童），订单人数>=此值才能享受优惠 | +| `planName` | `string` | 是 | 计划名称 | +| `remark` | `string` | | 备注 | +| `startDate` | `string` | 是 | 生效开始日期 | + +**响应** `统一响应结果«早鸟优惠计划VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `早鸟优惠计划VO` | | 响应数据 | +|   `createTime` | `string` | | 创建时间 | +|   `createdBy` | `long` | | 创建人ID | +|   `discountAmount` | `number` | | 优惠金额 | +|   `enabled` | `boolean` | | 是否启用 | +|   `endDate` | `string` | | 生效结束日期 | +|   `minPeople` | `int` | | 最低人数 | +|   `planId` | `long` | | 计划ID | +|   `planName` | `string` | | 计划名称 | +|   `remark` | `string` | | 备注 | +|   `startDate` | `string` | | 生效开始日期 | +|   `updateTime` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/order/early-bird/list + +**早鸟优惠计划列表** + +分页查询所有早鸟优惠计划。权限：仅超级管理员(SUPER_ADMIN) + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `page` | `integer(int32)` | | 页码 | | +| `pageSize` | `integer(int32)` | | 每页条数 | | + +**响应** `统一响应结果«分页结果«早鸟优惠计划VO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«早鸟优惠计划VO»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `早鸟优惠计划VO[]` | | 数据列表 | +|     `createTime` | `string` | | 创建时间 | +|     `createdBy` | `long` | | 创建人ID | +|     `discountAmount` | `number` | | 优惠金额 | +|     `enabled` | `boolean` | | 是否启用 | +|     `endDate` | `string` | | 生效结束日期 | +|     `minPeople` | `int` | | 最低人数 | +|     `planId` | `long` | | 计划ID | +|     `planName` | `string` | | 计划名称 | +|     `remark` | `string` | | 备注 | +|     `startDate` | `string` | | 生效开始日期 | +|     `updateTime` | `string` | | 更新时间 | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/order/early-bird/{planId} + +**早鸟优惠计划详情** + +权限：仅超级管理员(SUPER_ADMIN) + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `planId` | `integer` | | 早鸟计划ID | + +**响应** `统一响应结果«早鸟优惠计划VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `早鸟优惠计划VO` | | 响应数据 | +|   `createTime` | `string` | | 创建时间 | +|   `createdBy` | `long` | | 创建人ID | +|   `discountAmount` | `number` | | 优惠金额 | +|   `enabled` | `boolean` | | 是否启用 | +|   `endDate` | `string` | | 生效结束日期 | +|   `minPeople` | `int` | | 最低人数 | +|   `planId` | `long` | | 计划ID | +|   `planName` | `string` | | 计划名称 | +|   `remark` | `string` | | 备注 | +|   `startDate` | `string` | | 生效开始日期 | +|   `updateTime` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/order/early-bird/{planId} + +**修改早鸟优惠计划** + +权限：仅超级管理员(SUPER_ADMIN)。修改不影响已下单的订单优惠 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `planId` | `integer` | | 早鸟计划ID | + +**请求体** `早鸟优惠计划请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `discountAmount` | `number` | 是 | 优惠金额（从订单总价中扣减的固定金额） | +| `endDate` | `string` | 是 | 生效结束日期 | +| `minPeople` | `int` | 是 | 最低出行人数（含成人+儿童），订单人数>=此值才能享受优惠 | +| `planName` | `string` | 是 | 计划名称 | +| `remark` | `string` | | 备注 | +| `startDate` | `string` | 是 | 生效开始日期 | + +**响应** `统一响应结果«Void»` + +--- + +### `DELETE` /admin/order/early-bird/{planId} + +**删除早鸟优惠计划** + +权限：仅超级管理员(SUPER_ADMIN)。删除不影响已下单的订单优惠 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `planId` | `integer` | | 早鸟计划ID | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/order/early-bird/{planId}/toggle + +**启用/禁用早鸟优惠计划** + +禁用后该计划不再参与自动匹配。权限：仅超级管理员(SUPER_ADMIN) + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `planId` | `integer` | | 早鸟计划ID | + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `enabled` | `boolean` | | 是否启用 | | + +**响应** `统一响应结果«Void»` + +--- + +## 管理端相册接口 + +### `PUT` /admin/order/album/file/{albumFileId} + +**编辑文件信息** + +**关联字典**： +- album_file_type（文件类型，返回字段fileType）：IMAGE=图片, VIDEO=视频 +- album_location_type（地点类型，返回字段locationType）：RESOURCE=关联资源, CUSTOM=自定义地点 +- resource_type（资源类型，返回字段resourceType）：SCENIC_SPOT=景区, ACTIVITY=活动, RESTAURANT=餐厅, HOTEL=酒店, VEHICLE=车辆 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `albumFileId` | `integer` | | 相册文件ID | + +**请求体** `AlbumFileUpdateRequest` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `customLocation` | `string` | | 自定义地点文本 | +| `description` | `string` | | 文件描述 | +| `locationType` | `string` | | 地点类型: RESOURCE/CUSTOM | +| `resourceId` | `long` | | 资源ID | +| `resourceName` | `string` | | 资源名称 | +| `resourceType` | `string` | | 资源类型 | +| `sortOrder` | `int` | | 排序号 | + +**响应** `统一响应结果«AlbumFileVO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `AlbumFileVO` | | 响应数据 | +|   `albumFileId` | `long` | | 相册文件ID | +|   `createTime` | `string` | | 创建时间 | +|   `createdBy` | `long` | | 上传人ID | +|   `customLocation` | `string` | | 自定义地点文本 | +|   `description` | `string` | | 文件描述 | +|   `fileId` | `long` | | 文件ID | +|   `fileType` | `string` | | 文件类型: IMAGE/VIDEO | +|   `folderId` | `long` | | 所属文件夹ID | +|   `locationText` | `string` | | 地点显示文本 | +|   `locationType` | `string` | | 地点类型: RESOURCE/CUSTOM | +|   `ossUrl` | `string` | | 文件访问URL | +|   `resourceId` | `long` | | 资源ID | +|   `resourceName` | `string` | | 资源名称 | +|   `resourceType` | `string` | | 资源类型 | +|   `sortOrder` | `int` | | 排序号 | +|   `thumbnailUrl` | `string` | | 缩略图URL | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/order/album/file/{albumFileId} + +**删除文件** + +删除相册中的单个文件（照片/视频）。仅上传者或超级管理员可操作，删除后C端用户不再可见。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `albumFileId` | `integer` | | 相册文件ID | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/order/album/folder/{folderId} + +**编辑相册文件夹** + +修改文件夹名称或描述。仅创建者或超级管理员可操作 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `folderId` | `integer` | | 文件夹ID | + +**请求体** `AlbumFolderRequest` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `folderName` | `string` | | 文件夹名称 | +| `sortOrder` | `int` | | 排序号 | + +**响应** `统一响应结果«AlbumFolderVO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `AlbumFolderVO` | | 响应数据 | +|   `coverThumbnailUrl` | `string` | | 封面缩略图URL | +|   `coverUrl` | `string` | | 封面文件URL | +|   `createTime` | `string` | | 创建时间 | +|   `createdBy` | `long` | | 创建人ID | +|   `fileCount` | `int` | | 文件数量 | +|   `folderId` | `long` | | 文件夹ID | +|   `folderName` | `string` | | 文件夹名称 | +|   `orderId` | `long` | | 关联订单ID | +|   `sortOrder` | `int` | | 排序号 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/order/album/folder/{folderId} + +**删除相册文件夹** + +删除文件夹及其下所有文件。仅创建者或超级管理员可操作。删除后C端用户不再可见 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `folderId` | `integer` | | 文件夹ID | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/order/album/folder/{folderId}/cover + +**设置文件夹封面** + +将文件夹中的指定文件设为封面图，封面图会在文件夹列表中展示。仅上传者或超级管理员可操作。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `folderId` | `integer` | | 文件夹ID | + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `albumFileId` | `integer(int64)` | | 相册文件ID | | + +**响应** `统一响应结果«Void»` + +--- + +### `GET` /admin/order/album/folder/{folderId}/files + +**查询文件夹下的文件列表** + +**关联字典**： +- album_file_type（文件类型，返回字段fileType）：IMAGE=图片, VIDEO=视频 +- album_location_type（地点类型，返回字段locationType）：RESOURCE=关联资源, CUSTOM=自定义地点 +- resource_type（资源类型，返回字段resourceType）：SCENIC_SPOT=景区, ACTIVITY=活动, RESTAURANT=餐厅, HOTEL=酒店, VEHICLE=车辆 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `folderId` | `integer` | | 文件夹ID | + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `page` | `integer(int32)` | | 页码 | | +| `size` | `integer(int32)` | | 每页数量 | | + +**响应** `统一响应结果«分页结果«AlbumFileVO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«AlbumFileVO»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `AlbumFileVO[]` | | 数据列表 | +|     `albumFileId` | `long` | | 相册文件ID | +|     `createTime` | `string` | | 创建时间 | +|     `createdBy` | `long` | | 上传人ID | +|     `customLocation` | `string` | | 自定义地点文本 | +|     `description` | `string` | | 文件描述 | +|     `fileId` | `long` | | 文件ID | +|     `fileType` | `string` | | 文件类型: IMAGE/VIDEO | +|     `folderId` | `long` | | 所属文件夹ID | +|     `locationText` | `string` | | 地点显示文本 | +|     `locationType` | `string` | | 地点类型: RESOURCE/CUSTOM | +|     `ossUrl` | `string` | | 文件访问URL | +|     `resourceId` | `long` | | 资源ID | +|     `resourceName` | `string` | | 资源名称 | +|     `resourceType` | `string` | | 资源类型 | +|     `sortOrder` | `int` | | 排序号 | +|     `thumbnailUrl` | `string` | | 缩略图URL | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/order/album/folder/{folderId}/files + +**批量添加文件到文件夹** + +一次添加多个照片/视频到指定文件夹。文件需先通过文件服务上传获取OSS URL + +**关联字典**： +- album_file_type（文件类型，返回字段fileType）：IMAGE=图片, VIDEO=视频 +- album_location_type（地点类型，返回字段locationType）：RESOURCE=关联资源, CUSTOM=自定义地点 +- resource_type（资源类型，返回字段resourceType）：SCENIC_SPOT=景区, ACTIVITY=活动, RESTAURANT=餐厅, HOTEL=酒店, VEHICLE=车辆 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `folderId` | `integer` | | 文件夹ID | + +**请求体** `AlbumFileBatchAddRequest` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `files` | `AlbumFileAddRequest[]` | | 文件列表 | +|   `customLocation` | `string` | | 自定义地点文本（地点类型为CUSTOM时） | +|   `description` | `string` | | 文件描述 | +|   `fileId` | `long` | | 文件ID（来自file_info） | +|   `fileType` | `string` | | 文件类型: IMAGE/VIDEO | +|   `locationType` | `string` | | 地点类型: RESOURCE/CUSTOM | +|   `ossUrl` | `string` | | 文件访问URL | +|   `resourceId` | `long` | | 资源ID（地点类型为RESOURCE时） | +|   `resourceName` | `string` | | 资源名称（地点类型为RESOURCE时） | +|   `resourceType` | `string` | | 资源类型（地点类型为RESOURCE时） | +|   `sortOrder` | `int` | | 排序号 | +|   `thumbnailUrl` | `string` | | 缩略图URL | + +**响应** `统一响应结果«List«AlbumFileVO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `AlbumFileVO[]` | | 响应数据 | +|   `albumFileId` | `long` | | 相册文件ID | +|   `createTime` | `string` | | 创建时间 | +|   `createdBy` | `long` | | 上传人ID | +|   `customLocation` | `string` | | 自定义地点文本 | +|   `description` | `string` | | 文件描述 | +|   `fileId` | `long` | | 文件ID | +|   `fileType` | `string` | | 文件类型: IMAGE/VIDEO | +|   `folderId` | `long` | | 所属文件夹ID | +|   `locationText` | `string` | | 地点显示文本 | +|   `locationType` | `string` | | 地点类型: RESOURCE/CUSTOM | +|   `ossUrl` | `string` | | 文件访问URL | +|   `resourceId` | `long` | | 资源ID | +|   `resourceName` | `string` | | 资源名称 | +|   `resourceType` | `string` | | 资源类型 | +|   `sortOrder` | `int` | | 排序号 | +|   `thumbnailUrl` | `string` | | 缩略图URL | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/order/album/my-uploads + +**我的上传** + +查询当前管理员上传的所有相册文件（跨订单），方便管理自己上传的内容 + +**关联字典**： +- album_file_type（文件类型，返回字段fileType）：IMAGE=图片, VIDEO=视频 +- album_location_type（地点类型，返回字段locationType）：RESOURCE=关联资源, CUSTOM=自定义地点 +- resource_type（资源类型，返回字段resourceType）：SCENIC_SPOT=景区, ACTIVITY=活动, RESTAURANT=餐厅, HOTEL=酒店, VEHICLE=车辆 + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `page` | `integer(int32)` | | 页码 | | +| `size` | `integer(int32)` | | 每页数量 | | + +**响应** `统一响应结果«分页结果«AlbumFileVO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«AlbumFileVO»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `AlbumFileVO[]` | | 数据列表 | +|     `albumFileId` | `long` | | 相册文件ID | +|     `createTime` | `string` | | 创建时间 | +|     `createdBy` | `long` | | 上传人ID | +|     `customLocation` | `string` | | 自定义地点文本 | +|     `description` | `string` | | 文件描述 | +|     `fileId` | `long` | | 文件ID | +|     `fileType` | `string` | | 文件类型: IMAGE/VIDEO | +|     `folderId` | `long` | | 所属文件夹ID | +|     `locationText` | `string` | | 地点显示文本 | +|     `locationType` | `string` | | 地点类型: RESOURCE/CUSTOM | +|     `ossUrl` | `string` | | 文件访问URL | +|     `resourceId` | `long` | | 资源ID | +|     `resourceName` | `string` | | 资源名称 | +|     `resourceType` | `string` | | 资源类型 | +|     `sortOrder` | `int` | | 排序号 | +|     `thumbnailUrl` | `string` | | 缩略图URL | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/order/{orderId}/album/folder + +**创建相册文件夹** + +为订单创建旅行相册文件夹（如'第一天风景'、'合影'等），用于组织旅途照片/视频 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `orderId` | `integer` | | 订单ID | + +**请求体** `AlbumFolderRequest` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `folderName` | `string` | | 文件夹名称 | +| `sortOrder` | `int` | | 排序号 | + +**响应** `统一响应结果«AlbumFolderVO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `AlbumFolderVO` | | 响应数据 | +|   `coverThumbnailUrl` | `string` | | 封面缩略图URL | +|   `coverUrl` | `string` | | 封面文件URL | +|   `createTime` | `string` | | 创建时间 | +|   `createdBy` | `long` | | 创建人ID | +|   `fileCount` | `int` | | 文件数量 | +|   `folderId` | `long` | | 文件夹ID | +|   `folderName` | `string` | | 文件夹名称 | +|   `orderId` | `long` | | 关联订单ID | +|   `sortOrder` | `int` | | 排序号 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/order/{orderId}/album/folders + +**查询订单的文件夹列表** + +获取指定订单的所有相册文件夹，含文件夹名称、描述、封面图、文件数量等信息。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `orderId` | `integer` | | 订单ID | + +**响应** `统一响应结果«List«AlbumFolderVO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `AlbumFolderVO[]` | | 响应数据 | +|   `coverThumbnailUrl` | `string` | | 封面缩略图URL | +|   `coverUrl` | `string` | | 封面文件URL | +|   `createTime` | `string` | | 创建时间 | +|   `createdBy` | `long` | | 创建人ID | +|   `fileCount` | `int` | | 文件数量 | +|   `folderId` | `long` | | 文件夹ID | +|   `folderName` | `string` | | 文件夹名称 | +|   `orderId` | `long` | | 关联订单ID | +|   `sortOrder` | `int` | | 排序号 | +| `message` | `string` | | 响应消息 | + +--- + +## 管理端订单接口 + +### `POST` /admin/order/create + +**创建订单（定制师代下单）** + +创建订单流程：选择产品 → 填写联系人和出行人 → 系统计算报价 → 生成订单(PENDING_PAY状态) + +权限：CUSTOM产品仅创建者可下单，CORE/ROUTE产品所有管理员可下单 + +【关联字典】 +- 请求参数 productType → 字典：product_type（产品类型） +- 请求参数 travelers[].travelerType → 字典：traveler_type（出行人类型） +- 请求参数 travelers[].idCardType → 字典：id_card_type（证件类型） +- 请求参数 travelers[].gender → 字典：gender（性别） +- 返回字段 status → 字典：order_status（订单状态） +- 返回字段 processStatus → 字典：order_process_status（订单内部流程状态） +- 返回字段 productType → 字典：product_type（产品类型） +- 返回字段 travelers[].travelerType → 字典：traveler_type（出行人类型） +- 返回字段 travelers[].idCardType → 字典：id_card_type（证件类型） +- 返回字段 travelers[].gender → 字典：gender（性别） + +**请求体** `管理员创建订单请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `adultCount` | `int` | | 成人数 | +| `babyCount` | `int` | | 幼童数 | +| `childCount` | `int` | | 儿童数 | +| `childNeedBed` | `boolean` | | 儿童是否需要床位（影响房间分配和报价计算） | +| `contactName` | `string` | 是 | 联系人姓名 | +| `contactPhone` | `string` | 是 | 联系人电话 | +| `customizerId` | `long` | | 定制师ID（可选，默认为创建人） | +| `departureDate` | `string` | | 出发日期(GROUP产品可不传，从团期获取) | +| `expiryMinutes` | `int` | | 支付时限（分钟），不传则使用全局默认值。超时未支付订单自动取消 | +| `groupBatchId` | `long` | | 团期ID(GROUP产品必填) | +| `productId` | `long` | 是 | 产品ID | +| `remark` | `string` | | 备注 | +| `roomCount` | `int` | | 房间数(GROUP产品，默认1) | +| `travelers` | `出行人信息[]` | | 出行人列表 | +|   `birthday` | `string` | 是 | 出生日期（必填，后端根据此字段自动判断人员类型） | +|   `email` | `string` | | 电子邮箱 | +|   `emergencyContact` | `string` | | 紧急联系人 | +|   `emergencyPhone` | `string` | | 紧急联系电话 | +|   `gender` | `int` | | 性别（字典：gender） | +|   `idCardNo` | `string` | | 证件号码 | +|   `idCardType` | `string` | | 证件类型（字典：id_card_type） | +|   `name` | `string` | 是 | 出行人姓名 | +|   `nationality` | `string` | | 国籍 | +|   `phone` | `string` | | 手机号 | +| `userPhone` | `string` | | 用户手机号（可选，用于关联C端用户）。如匹配到已注册用户则自动绑定订单 | +| `youngChildCount` | `int` | | 小童数 | + +**响应** `统一响应结果«订单详情VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `订单详情VO` | | 响应数据 | +|   `adultCount` | `int` | | 成人数 | +|   `babyCount` | `int` | | 幼童数 | +|   `balanceAmount` | `number` | | 尾款金额（总售价-定金） | +|   `balancePayMethod` | `string` | | 尾款支付方式: ONLINE=线上微信支付 OFFLINE=线下转账 | +|   `balanceProofUrl` | `string` | | 尾款凭证URL | +|   `cancelReason` | `string` | | 取消原因 | +|   `cancelledAt` | `string` | | 取消时间 | +|   `checklistConfirmed` | `boolean` | | 清单确认状态 | +|   `childCount` | `int` | | 儿童数 | +|   `completedAt` | `string` | | 完成时间 | +|   `confirmedAt` | `string` | | 确认时间 | +|   `contactName` | `string` | | 联系人姓名 | +|   `contactPhone` | `string` | | 联系人电话 | +|   `contracts` | `Map«string,object»[]` | | 合同列表（含signUrl/fileUrl/status等） | +|   `createTime` | `string` | | 创建时间 | +|   `creatorAdminId` | `long` | | 创建人管理员ID | +|   `creatorName` | `string` | | 创建人姓名 | +|   `customizerId` | `long` | | 定制师ID | +|   `customizerName` | `string` | | 定制师姓名 | +|   `departureDate` | `string` | | 出发日期 | +|   `depositAmount` | `number` | | 定金金额 | +|   `depositRatio` | `int` | | 定金比例 | +|   `discountAmount` | `number` | | 优惠金额 | +|   `discountReason` | `string` | | 优惠原因 | +|   `discounts` | `OrderDiscount[]` | | 优惠列表 | +|     `createTime` | `string` | | 创建时间 | +|     `deletedAt` | `string` | | 删除时间（软删除） | +|     `discountAmount` | `number` | | 优惠金额 | +|     `discountId` | `long` | | 优惠ID | +|     `discountName` | `string` | | 优惠名称 | +|     `orderId` | `long` | | 订单ID | +|     `updateTime` | `string` | | 更新时间 | +|   `displayStatus` | `string` | | 前端显示状态（字典：order_display_status） | +|   `displayStatusLabel` | `string` | | 前端显示状态标签（字典：order_display_status 翻译） | +|   `expiryMinutes` | `int` | | 支付时限（分钟） | +|   `expiryTime` | `string` | | 支付截止时间 | +|   `hotelAssignments` | `string` | | 酒店分配信息JSON | +|   `insurances` | `Map«string,object»[]` | | 保险订单列表（含productName/extPolicyNo/status/startDate/endDate等） | +|   `mchId` | `string` | | 商户号 | +|   `orderId` | `long` | | 订单ID | +|   `orderNo` | `string` | | 订单号 | +|   `paidAmount` | `number` | | 已付金额 | +|   `paidAt` | `string` | | 支付时间 | +|   `payMethodLabel` | `string` | | 支付方式标签（如：微信支付、定金微信+尾款线下） | +|   `paymentMode` | `string` | | 支付模式（字典：payment_mode） | +|   `processStatus` | `string` | | 内部流程状态（字典：order_process_status） | +|   `processStatusLabel` | `string` | | 内部流程状态标签（字典：order_process_status 翻译） | +|   `productCoverUrl` | `string` | | 产品封面图URL | +|   `productId` | `long` | | 产品ID | +|   `productName` | `string` | | 产品名称 | +|   `productSnapshot` | `string` | | 产品快照JSON | +|   `productType` | `string` | | 产品类型（字典：product_type） | +|   `readyAt` | `string` | | 就绪时间 | +|   `refundAmount` | `number` | | 退款金额（实退金额） | +|   `remark` | `string` | | 备注 | +|   `returnDate` | `string` | | 返程日期（出发日期 + 行程天数 - 1） | +|   `reviewed` | `boolean` | | 是否已评价 | +|   `roomInfo` | `string` | | 房间信息 | +|   `sharerOpenid` | `string` | | 分享人微信openid | +|   `status` | `string` | | 订单状态（字典：order_status） | +|   `statusLabel` | `string` | | 订单状态标签（字典：order_status 翻译） | +|   `timeline` | `OrderTimeline[]` | | 时间线列表 | +|     `action` | `string` | | 操作动作 | +|     `content` | `string` | | 操作内容 | +|     `createTime` | `string` | | 创建时间 | +|     `deletedAt` | `string` | | 删除时间（软删除） | +|     `operatorId` | `long` | | 操作人ID | +|     `operatorName` | `string` | | 操作人姓名 | +|     `operatorType` | `string` | | 操作人类型：USER=用户 ADMIN=管理员 SYSTEM=系统 | +|     `orderId` | `long` | | 订单ID | +|     `timelineId` | `long` | | 时间线ID | +|     `updateTime` | `string` | | 更新时间 | +|   `todos` | `OrderTodo[]` | | 待办列表 | +|     `assigneeAdminId` | `long` | | 指派管理员ID | +|     `assigneeRoleKey` | `string` | | 指派角色Key | +|     `completedAt` | `string` | | 完成时间 | +|     `completedBy` | `long` | | 完成人ID | +|     `createTime` | `string` | | 创建时间 | +|     `deletedAt` | `string` | | 删除时间（软删除） | +|     `lastNotifiedAt` | `string` | | 最后通知时间 | +|     `notificationCount` | `int` | | 通知次数 | +|     `orderId` | `long` | | 订单ID | +|     `orderNo` | `string` | | 订单编号 | +|     `sequence` | `int` | | 排序序号 | +|     `status` | `string` | | 待办状态 | +|     `todoId` | `long` | | 待办ID | +|     `todoLabel` | `string` | | 待办标签 | +|     `todoType` | `string` | | 待办类型 | +|     `updateTime` | `string` | | 更新时间 | +|   `totalCost` | `number` | | 总成本（仅管理员可见） | +|   `totalPrice` | `number` | | 总售价 | +|   `travelers` | `OrderTraveler[]` | | 出行人列表 | +|     `birthday` | `string` | | 出生日期 | +|     `createTime` | `string` | | 创建时间 | +|     `deletedAt` | `string` | | 删除时间（软删除） | +|     `email` | `string` | | 邮箱地址 | +|     `emergencyContact` | `string` | | 紧急联系人姓名 | +|     `emergencyPhone` | `string` | | 紧急联系人电话（加密存储） | +|     `gender` | `int` | | 性别（字典：gender） | +|     `idCardNo` | `string` | | 证件号码（加密存储） | +|     `idCardType` | `string` | | 证件类型（字典：id_card_type） | +|     `name` | `string` | | 出行人姓名 | +|     `nationality` | `string` | | 国籍 | +|     `orderId` | `long` | | 订单ID | +|     `orderTravelerId` | `long` | | 出行人记录ID | +|     `phone` | `string` | | 手机号码（加密存储） | +|     `travelerType` | `string` | | 出行人类型（字典：traveler_type） | +|     `updateTime` | `string` | | 更新时间 | +|   `tripDays` | `int` | | 行程天数 | +|   `tripNights` | `int` | | 行程晚数 | +|   `unlockRequestedAt` | `string` | | 解锁请求时间 | +|   `userId` | `long` | | 用户ID | +|   `vehicleInfo` | `string` | | 车辆信息 | +|   `youngChildCount` | `int` | | 小童数 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/order/list + +**订单列表** + +支持按关键词（订单号/联系人/产品名）、状态、内部流程状态、产品类型筛选。 +支持按创建时间/出发日期/总价排序。 + +返回分页结果，包含订单基本信息、状态、支付信息和产品封面 + +【关联字典】 +- 筛选参数 status → 字典：order_status（订单状态） +- 筛选参数 processStatus → 字典：order_process_status（订单内部流程状态） +- 筛选参数 productType → 字典：product_type（产品类型） +- 返回字段 status → 字典：order_status（订单状态） +- 返回字段 processStatus → 字典：order_process_status（订单内部流程状态） +- 返回字段 productType → 字典：product_type（产品类型） + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `keyword` | `string` | | 搜索关键词（订单号/联系人姓名/产品名称） | HL2026 | +| `page` | `integer(int32)` | | 页码 | 1 | +| `pageSize` | `integer(int32)` | | 每页条数 | 20 | +| `processStatus` | `string` | | 内部流程状态（字典：order_process_status） | PENDING_ROOM | +| `productType` | `string` | | 产品类型（字典：product_type） | CORE | +| `sortBy` | `string` | | 排序字段（createTime/departureDate/totalPrice） | createTime | +| `sortDir` | `string` | | 排序方向（desc/asc） | desc | +| `status` | `string` | | 订单状态（字典：order_status，支持逗号分隔多状态） | PAID | + +**响应** `统一响应结果«分页结果«管理员订单列表VO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«管理员订单列表VO»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `管理员订单列表VO[]` | | 数据列表 | +|     `adultCount` | `int` | | 成人数 | +|     `babyCount` | `int` | | 幼童数 | +|     `balanceAmount` | `number` | | 尾款金额（DEPOSIT模式：总售价-定金-优惠） | +|     `childCount` | `int` | | 儿童数 | +|     `contactName` | `string` | | 联系人姓名 | +|     `contactPhone` | `string` | | 联系人电话 | +|     `createTime` | `string` | | 创建时间 | +|     `creatorAdminId` | `long` | | 创建人管理员ID | +|     `customizerName` | `string` | | 定制师名称 | +|     `daysUntilDeparture` | `int` | | 距出发天数（负数表示已出发） | +|     `departureDate` | `string` | | 出发日期 | +|     `depositAmount` | `number` | | 定金金额 | +|     `discountAmount` | `number` | | 优惠金额 | +|     `mchId` | `string` | | 商户号 | +|     `orderId` | `long` | | 订单ID | +|     `orderNo` | `string` | | 订单号 | +|     `paidAmount` | `number` | | 已付金额 | +|     `paymentMode` | `string` | | 支付模式（字典：payment_mode） | +|     `processStatus` | `string` | | 内部流程状态（字典：order_process_status） | +|     `processStatusLabel` | `string` | | 内部流程状态标签（字典：order_process_status 翻译） | +|     `productCoverUrl` | `string` | | 产品封面图URL | +|     `productId` | `long` | | 产品ID | +|     `productName` | `string` | | 产品名称 | +|     `productType` | `string` | | 产品类型（字典：product_type） | +|     `status` | `string` | | 订单状态（字典：order_status） | +|     `statusLabel` | `string` | | 订单状态标签（字典：order_status 翻译） | +|     `totalPrice` | `number` | | 总售价 | +|     `tripDays` | `int` | | 行程天数 | +|     `tripNights` | `int` | | 行程晚数 | +|     `userId` | `long` | | 用户ID | +|     `youngChildCount` | `int` | | 小童数 | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/order/quote + +**报价预览** + +根据产品、出发日期、人数组合实时计算报价。 +返回各资源明细价格和合计金额，前端据此展示报价清单。 + +注意：报价仅供参考，最终价格以创建订单时为准（价格日历可能变动） + +**请求体** `报价预览请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `adultCount` | `int` | | 成人数 | +| `babyCount` | `int` | | 幼童数 | +| `childCount` | `int` | | 儿童数 | +| `childNeedBed` | `boolean` | | 儿童是否需要床位 | +| `departureDate` | `string` | 是 | 出发日期 | +| `productId` | `long` | 是 | 产品ID | +| `youngChildCount` | `int` | | 小童数 | + +**响应** `统一响应结果«Map«string,object»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `object` | | 响应数据 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/order/{orderId} + +**订单详情** + +返回订单完整信息，包括：基本信息、产品快照、联系人、出行人列表、支付记录、优惠明细、时间线、内部流程状态等 + +【关联字典】 +- 返回字段 status → 字典：order_status（订单状态） +- 返回字段 processStatus → 字典：order_process_status（订单内部流程状态） +- 返回字段 productType → 字典：product_type（产品类型） +- 返回字段 travelers[].travelerType → 字典：traveler_type（出行人类型） +- 返回字段 travelers[].idCardType → 字典：id_card_type（证件类型） +- 返回字段 travelers[].gender → 字典：gender（性别） +- 返回字段 timeline[].action → 字典：order_timeline_action（订单操作类型） +- 返回字段 todos[].todoType → 字典：order_todo_type（订单待办类型） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `orderId` | `integer` | | 订单ID | + +**响应** `统一响应结果«订单详情VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `订单详情VO` | | 响应数据 | +|   `adultCount` | `int` | | 成人数 | +|   `babyCount` | `int` | | 幼童数 | +|   `balanceAmount` | `number` | | 尾款金额（总售价-定金） | +|   `balancePayMethod` | `string` | | 尾款支付方式: ONLINE=线上微信支付 OFFLINE=线下转账 | +|   `balanceProofUrl` | `string` | | 尾款凭证URL | +|   `cancelReason` | `string` | | 取消原因 | +|   `cancelledAt` | `string` | | 取消时间 | +|   `checklistConfirmed` | `boolean` | | 清单确认状态 | +|   `childCount` | `int` | | 儿童数 | +|   `completedAt` | `string` | | 完成时间 | +|   `confirmedAt` | `string` | | 确认时间 | +|   `contactName` | `string` | | 联系人姓名 | +|   `contactPhone` | `string` | | 联系人电话 | +|   `contracts` | `Map«string,object»[]` | | 合同列表（含signUrl/fileUrl/status等） | +|   `createTime` | `string` | | 创建时间 | +|   `creatorAdminId` | `long` | | 创建人管理员ID | +|   `creatorName` | `string` | | 创建人姓名 | +|   `customizerId` | `long` | | 定制师ID | +|   `customizerName` | `string` | | 定制师姓名 | +|   `departureDate` | `string` | | 出发日期 | +|   `depositAmount` | `number` | | 定金金额 | +|   `depositRatio` | `int` | | 定金比例 | +|   `discountAmount` | `number` | | 优惠金额 | +|   `discountReason` | `string` | | 优惠原因 | +|   `discounts` | `OrderDiscount[]` | | 优惠列表 | +|     `createTime` | `string` | | 创建时间 | +|     `deletedAt` | `string` | | 删除时间（软删除） | +|     `discountAmount` | `number` | | 优惠金额 | +|     `discountId` | `long` | | 优惠ID | +|     `discountName` | `string` | | 优惠名称 | +|     `orderId` | `long` | | 订单ID | +|     `updateTime` | `string` | | 更新时间 | +|   `displayStatus` | `string` | | 前端显示状态（字典：order_display_status） | +|   `displayStatusLabel` | `string` | | 前端显示状态标签（字典：order_display_status 翻译） | +|   `expiryMinutes` | `int` | | 支付时限（分钟） | +|   `expiryTime` | `string` | | 支付截止时间 | +|   `hotelAssignments` | `string` | | 酒店分配信息JSON | +|   `insurances` | `Map«string,object»[]` | | 保险订单列表（含productName/extPolicyNo/status/startDate/endDate等） | +|   `mchId` | `string` | | 商户号 | +|   `orderId` | `long` | | 订单ID | +|   `orderNo` | `string` | | 订单号 | +|   `paidAmount` | `number` | | 已付金额 | +|   `paidAt` | `string` | | 支付时间 | +|   `payMethodLabel` | `string` | | 支付方式标签（如：微信支付、定金微信+尾款线下） | +|   `paymentMode` | `string` | | 支付模式（字典：payment_mode） | +|   `processStatus` | `string` | | 内部流程状态（字典：order_process_status） | +|   `processStatusLabel` | `string` | | 内部流程状态标签（字典：order_process_status 翻译） | +|   `productCoverUrl` | `string` | | 产品封面图URL | +|   `productId` | `long` | | 产品ID | +|   `productName` | `string` | | 产品名称 | +|   `productSnapshot` | `string` | | 产品快照JSON | +|   `productType` | `string` | | 产品类型（字典：product_type） | +|   `readyAt` | `string` | | 就绪时间 | +|   `refundAmount` | `number` | | 退款金额（实退金额） | +|   `remark` | `string` | | 备注 | +|   `returnDate` | `string` | | 返程日期（出发日期 + 行程天数 - 1） | +|   `reviewed` | `boolean` | | 是否已评价 | +|   `roomInfo` | `string` | | 房间信息 | +|   `sharerOpenid` | `string` | | 分享人微信openid | +|   `status` | `string` | | 订单状态（字典：order_status） | +|   `statusLabel` | `string` | | 订单状态标签（字典：order_status 翻译） | +|   `timeline` | `OrderTimeline[]` | | 时间线列表 | +|     `action` | `string` | | 操作动作 | +|     `content` | `string` | | 操作内容 | +|     `createTime` | `string` | | 创建时间 | +|     `deletedAt` | `string` | | 删除时间（软删除） | +|     `operatorId` | `long` | | 操作人ID | +|     `operatorName` | `string` | | 操作人姓名 | +|     `operatorType` | `string` | | 操作人类型：USER=用户 ADMIN=管理员 SYSTEM=系统 | +|     `orderId` | `long` | | 订单ID | +|     `timelineId` | `long` | | 时间线ID | +|     `updateTime` | `string` | | 更新时间 | +|   `todos` | `OrderTodo[]` | | 待办列表 | +|     `assigneeAdminId` | `long` | | 指派管理员ID | +|     `assigneeRoleKey` | `string` | | 指派角色Key | +|     `completedAt` | `string` | | 完成时间 | +|     `completedBy` | `long` | | 完成人ID | +|     `createTime` | `string` | | 创建时间 | +|     `deletedAt` | `string` | | 删除时间（软删除） | +|     `lastNotifiedAt` | `string` | | 最后通知时间 | +|     `notificationCount` | `int` | | 通知次数 | +|     `orderId` | `long` | | 订单ID | +|     `orderNo` | `string` | | 订单编号 | +|     `sequence` | `int` | | 排序序号 | +|     `status` | `string` | | 待办状态 | +|     `todoId` | `long` | | 待办ID | +|     `todoLabel` | `string` | | 待办标签 | +|     `todoType` | `string` | | 待办类型 | +|     `updateTime` | `string` | | 更新时间 | +|   `totalCost` | `number` | | 总成本（仅管理员可见） | +|   `totalPrice` | `number` | | 总售价 | +|   `travelers` | `OrderTraveler[]` | | 出行人列表 | +|     `birthday` | `string` | | 出生日期 | +|     `createTime` | `string` | | 创建时间 | +|     `deletedAt` | `string` | | 删除时间（软删除） | +|     `email` | `string` | | 邮箱地址 | +|     `emergencyContact` | `string` | | 紧急联系人姓名 | +|     `emergencyPhone` | `string` | | 紧急联系人电话（加密存储） | +|     `gender` | `int` | | 性别（字典：gender） | +|     `idCardNo` | `string` | | 证件号码（加密存储） | +|     `idCardType` | `string` | | 证件类型（字典：id_card_type） | +|     `name` | `string` | | 出行人姓名 | +|     `nationality` | `string` | | 国籍 | +|     `orderId` | `long` | | 订单ID | +|     `orderTravelerId` | `long` | | 出行人记录ID | +|     `phone` | `string` | | 手机号码（加密存储） | +|     `travelerType` | `string` | | 出行人类型（字典：traveler_type） | +|     `updateTime` | `string` | | 更新时间 | +|   `tripDays` | `int` | | 行程天数 | +|   `tripNights` | `int` | | 行程晚数 | +|   `unlockRequestedAt` | `string` | | 解锁请求时间 | +|   `userId` | `long` | | 用户ID | +|   `vehicleInfo` | `string` | | 车辆信息 | +|   `youngChildCount` | `int` | | 小童数 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/order/{orderId} + +**编辑订单** + +修改订单的联系人、人数、出发日期、售价、成本、备注等信息。 +仅传入需要修改的字段，未传入的字段不会被修改。 + +如果提供了出行人列表(travelers)，将替换订单的全部出行人。 +已锁定的订单需先调用'申请修改'接口解锁后才能编辑 + +【关联字典】 +- 请求参数 travelers[].travelerType → 字典：traveler_type（出行人类型） +- 请求参数 travelers[].idCardType → 字典：id_card_type（证件类型） +- 请求参数 travelers[].gender → 字典：gender（性别） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `orderId` | `integer` | | 订单ID | + +**请求体** `管理员修改订单请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `adultCount` | `int` | | 成人数 | +| `babyCount` | `int` | | 幼童数 | +| `childCount` | `int` | | 儿童数 | +| `contactName` | `string` | | 联系人姓名 | +| `contactPhone` | `string` | | 联系人电话 | +| `departureDate` | `string` | | 出发日期 | +| `depositAmount` | `number` | | 定金金额 | +| `mchId` | `string` | | 商户号（微信支付商户号，多商户场景使用） | +| `remark` | `string` | | 备注 | +| `totalCost` | `number` | | 总成本 | +| `totalPrice` | `number` | | 总售价 | +| `travelers` | `出行人信息[]` | | 出行人列表（如提供则替换全部出行人，不传则不修改出行人） | +|   `birthday` | `string` | 是 | 出生日期（必填，后端根据此字段自动判断人员类型） | +|   `email` | `string` | | 电子邮箱 | +|   `emergencyContact` | `string` | | 紧急联系人 | +|   `emergencyPhone` | `string` | | 紧急联系电话 | +|   `gender` | `int` | | 性别（字典：gender） | +|   `idCardNo` | `string` | | 证件号码 | +|   `idCardType` | `string` | | 证件类型（字典：id_card_type） | +|   `name` | `string` | 是 | 出行人姓名 | +|   `nationality` | `string` | | 国籍 | +|   `phone` | `string` | | 手机号 | +| `youngChildCount` | `int` | | 小童数 | + +**响应** `统一响应结果«Void»` + +--- + +### `DELETE` /admin/order/{orderId} + +**删除订单** + +仅待支付(PENDING_PAY)状态的订单可删除，其他状态不可删除 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `orderId` | `integer` | | 订单ID | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/order/{orderId}/balance-pay-method + +**设置尾款支付方式** + +设置订单尾款的支付方式。ONLINE=线上微信支付，OFFLINE=线下转账（需管理员手动记录尾款到账） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `orderId` | `integer` | | 订单ID | + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `balancePayMethod` | `string` | 是 | 支付方式：ONLINE-线上支付, OFFLINE-线下支付 | | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/order/{orderId}/cancel + +**取消订单** + +管理员可取消的状态：待支付、已付定金、已全额支付、已确认、待付尾款 + +已付款订单取消后需走退款流程 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `orderId` | `integer` | | 订单ID | + +**请求体** `管理员取消订单请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `reason` | `string` | 是 | 取消原因 | +| `refundAmount` | `number` | | 退款金额（可选，不传则按退款政策自动计算；传0表示不退款） | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/order/{orderId}/confirm + +**确认订单** + +确认订单后进入内部流程：待配房 → 待配车 → 待核算 → 就绪 + +前置条件：订单状态为已全额支付(PAID)或已付定金(DEPOSIT_PAID) + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `orderId` | `integer` | | 订单ID | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/order/{orderId}/deposit + +**修改定金金额** + +修改订单的定金金额。仅待支付(PENDING_PAY)状态可修改。 + +定金金额不能超过订单总价，修改后影响用户支付页面显示的应付金额 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `orderId` | `integer` | | 订单ID | + +**请求体** `修改定金金额请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `amount` | `number` | 是 | 定金金额 | + +**响应** `统一响应结果«Void»` + +--- + +### `POST` /admin/order/{orderId}/discount + +**添加优惠项** + +为订单添加手动优惠（如会员折扣、老客优惠等）。 +添加后系统自动重算订单应付金额。一个订单可添加多个优惠项 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `orderId` | `integer` | | 订单ID | + +**请求体** `优惠项请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `discountAmount` | `number` | 是 | 优惠金额 | +| `discountName` | `string` | 是 | 优惠项目名称 | + +**响应** `统一响应结果«OrderDiscount»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `OrderDiscount` | | 响应数据 | +|   `createTime` | `string` | | 创建时间 | +|   `deletedAt` | `string` | | 删除时间（软删除） | +|   `discountAmount` | `number` | | 优惠金额 | +|   `discountId` | `long` | | 优惠ID | +|   `discountName` | `string` | | 优惠名称 | +|   `orderId` | `long` | | 订单ID | +|   `updateTime` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/order/{orderId}/discount/{discountId} + +**修改优惠项** + +修改已添加的优惠项名称或金额，修改后自动重算订单应付金额 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `discountId` | `integer` | | 优惠项ID | +| `orderId` | `integer` | | 订单ID | + +**请求体** `优惠项请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `discountAmount` | `number` | 是 | 优惠金额 | +| `discountName` | `string` | 是 | 优惠项目名称 | + +**响应** `统一响应结果«Void»` + +--- + +### `DELETE` /admin/order/{orderId}/discount/{discountId} + +**删除优惠项** + +删除已添加的优惠项，删除后自动重算订单应付金额 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `discountId` | `integer` | | 优惠项ID | +| `orderId` | `integer` | | 订单ID | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/order/{orderId}/hotel-assignment + +**分配酒店信息** + +按家庭为订单分配具体的酒店房间（酒店名称、房型、入住/退房日期）。 +每个家庭对应一条分配记录，分配后信息将展示在订单详情和C端行程中 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `orderId` | `integer` | | 订单ID | + +**请求体** `酒店分配请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `assignments` | `单项酒店分配[]` | 是 | 酒店分配列表 | +|   `checkInDate` | `string` | 是 | 入住日期(yyyy-MM-dd) | +|   `checkOutDate` | `string` | 是 | 退房日期(yyyy-MM-dd) | +|   `familyIndex` | `int` | 是 | 家庭序号 | +|   `hotelName` | `string` | 是 | 酒店名称 | +|   `roomType` | `string` | 是 | 房型 | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/order/{orderId}/process-status + +**推进内部流程** + +内部流程推进顺序：待配房(PENDING_ROOM) → 待配车(PENDING_VEHICLE) → 待核算(PENDING_FINANCE) → 就绪(READY) + +仅在订单状态为已确认(CONFIRMED)时有效，每次调用自动推进到下一步 + +【关联字典】 +- 涉及字段 processStatus → 字典：order_process_status（订单内部流程状态） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `orderId` | `integer` | | 订单ID | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/order/{orderId}/record-balance + +**记录尾款（线下收取）** + +管理员确认收到尾款 → 上传凭证。已确认(流程就绪)或待出行状态可操作 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `orderId` | `integer` | | 订单ID | + +**请求体** `记录尾款请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `proofUrl` | `string` | | 支付凭证URL | +| `remark` | `string` | | 备注 | + +**响应** `统一响应结果«Void»` + +--- + +### `POST` /admin/order/{orderId}/remark + +**添加备注** + +向订单时间线添加一条管理员备注。备注会记录操作人和时间，可用于内部沟通和订单跟踪 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `orderId` | `integer` | | 订单ID | + +**请求体** `管理员备注请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `content` | `string` | 是 | 备注内容 | + +**响应** `统一响应结果«Void»` + +--- + +### `POST` /admin/order/{orderId}/request-unlock + +**申请修改（解锁已锁定订单）** + +清单确认后订单进入锁定状态，如需修改需先申请解锁 + +解锁后可重新编辑订单信息并再次确认清单 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `orderId` | `integer` | | 订单ID | + +**请求体** `申请解锁订单请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `reason` | `string` | | 解锁原因 | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/order/{orderId}/room-info + +**更新房间信息（仅房务管理员/超级管理员）** + +更新订单的房间分配信息（房型、房间号、入住安排等）。 + +**权限**：仅ROOM_MANAGER（房务管理员）或SUPER_ADMIN（超级管理员）可操作。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `orderId` | `integer` | | 订单ID | + +**请求体** `房间信息请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `roomInfo` | `string` | 是 | 房间信息 | + +**响应** `统一响应结果«Void»` + +--- + +### `POST` /admin/order/{orderId}/room-info/check-diff + +**检测房型一致性** + +检测当前房间配置是否与产品快照一致。返回 null 表示一致，否则返回不一致描述 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `orderId` | `integer` | | 订单ID | + +**请求体** `string` + +**响应** `统一响应结果«string»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `string` | | 响应数据 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/order/{orderId}/status + +**更新订单状态** + +合法状态流转： +- 待支付 → 已付定金/已全额支付/已取消 +- 已付定金 → 已确认/已取消/售后中 +- 已全额支付 → 已确认/已取消/售后中 +- 已确认 → 待付尾款/待出行/已取消/售后中 +- 待付尾款 → 待出行/已取消/售后中 +- 待出行 → 旅行中/售后中 +- 旅行中 → 已完成 +- 已完成 → 售后中 +- 售后中 → 退款中 +- 退款中 → 已退款 + +【关联字典】 +- 请求参数 status → 字典：order_status（订单状态） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `orderId` | `integer` | | 订单ID | + +**请求体** `更新订单状态请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `status` | `string` | 是 | 目标状态。可选值：PENDING_PAY(待支付)/DEPOSIT_PAID(已付定金)/PAID(已全额支付)/CONFIRMED(已确认)/PENDING_BALANCE(待付尾款)/PENDING_DEPARTURE(待出行)/TRAVELLING(旅行中)/COMPLETED(已完成)/AFTER_SALE(售后中)/REFUNDING(退款中)/REFUNDED(已退款)/CANCELLED(已取消) | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/order/{orderId}/vehicle-assignment + +**分配车辆信息** + +为订单分配具体的车辆和司机信息（车型、品牌、车牌号、司机姓名和电话）。 +分配后信息将展示在订单详情和C端行程中 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `orderId` | `integer` | | 订单ID | + +**请求体** `车辆分配请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `driverName` | `string` | | 司机姓名 | +| `driverPhone` | `string` | | 司机电话 | +| `plateNumber` | `string` | | 车牌号 | +| `vehicleBrand` | `string` | 是 | 品牌 | +| `vehicleModel` | `string` | 是 | 车型 | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/order/{orderId}/vehicle-info + +**更新车辆信息（仅车务管理员/超级管理员）** + +更新订单的车辆分配信息（车型、车牌号、司机等）。 + +**权限**：仅VEHICLE_MANAGER（车务管理员）或SUPER_ADMIN（超级管理员）可操作。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `orderId` | `integer` | | 订单ID | + +**请求体** `车辆信息请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `vehicleInfo` | `string` | 是 | 车辆信息 | + +**响应** `统一响应结果«Void»` + +--- + +### `POST` /admin/order/{orderId}/vehicle-info/check-diff + +**检测车型一致性** + +检测当前车辆配置是否与产品快照一致。返回 null 表示一致，否则返回不一致描述 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `orderId` | `integer` | | 订单ID | + +**请求体** `string` + +**响应** `统一响应结果«string»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `string` | | 响应数据 | +| `message` | `string` | | 响应消息 | + +--- + +## 管理端订单行程编辑 + +### `POST` /admin/order/{orderId}/itinerary/add + +**新增节点** + +在某一天的行程中新增一个节点 + +**关联字典**： +- itinerary_edit_action（操作类型，返回字段action）：SKIP=跳过, ADD=新增节点, ADD_DAY=新增整天, ROOM_CHANGE=房型切换, VEHICLE_CHANGE=车型切换 +- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认 +- resource_type（资源类型，返回字段resourceType）：SCENIC_SPOT=景区, ACTIVITY=活动, RESTAURANT=餐厅, HOTEL=酒店, VEHICLE=车辆 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `orderId` | `integer` | | 订单ID | + +**请求体** `新增行程节点请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `balanceAdjustment` | `number` | | 尾款调整金额（正数=增加尾款，负数=减少尾款） | +| `dayNumber` | `int` | | 行程天数编号（独立调用时必填，addDay子节点时自动继承） | +| `description` | `string` | | 节点描述 | +| `nodeName` | `string` | 是 | 节点名称 | +| `nodeType` | `string` | 是 | 节点类型：SCENIC/HOTEL/RESTAURANT/ACTIVITY/VEHICLE/SERVICE/FREE/NOTE | +| `reason` | `string` | | 修改原因（独立调用时必填，addDay子节点时自动继承） | +| `resourceId` | `long` | | 关联资源ID | +| `resourceType` | `string` | | 关联资源类型：SCENIC_SPOT/ACTIVITY/RESTAURANT/HOTEL/VEHICLE | +| `sortOrder` | `int` | | 排序序号（插入位置，默认追加到末尾） | +| `startTime` | `string` | | 开始时间 | + +**响应** `统一响应结果«OrderItineraryEdit»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `OrderItineraryEdit` | | 响应数据 | +|   `action` | `string` | | 操作类型：SKIP/ADD | +|   `balanceAdjustment` | `number` | | 尾款调整金额（正数=增加尾款，负数=减少尾款） | +|   `changeDays` | `int` | | 变更天数 | +|   `changeReasonCode` | `string` | | 变更原因代码（字典项） | +|   `changeReasonLabel` | `string` | | 变更原因标签 | +|   `confirmStatus` | `string` | | 确认状态：PENDING_CONFIRM/CONFIRMED | +|   `confirmedAt` | `string` | | 确认时间 | +|   `confirmedBy` | `long` | | 确认人ID | +|   `createTime` | `string` | | 创建时间 | +|   `dayNumber` | `int` | | 行程天数编号 | +|   `deletedAt` | `string` | | 删除时间（软删除） | +|   `description` | `string` | | 节点描述（ADD时） | +|   `editId` | `long` | | 编辑ID | +|   `newResourceName` | `string` | | 新资源名称（房型/车型） | +|   `newUnitPrice` | `number` | | 新单价（日均） | +|   `nodeId` | `string` | | 原节点ID（SKIP时必填） | +|   `nodeName` | `string` | | 节点名称（ADD时） | +|   `nodeType` | `string` | | 节点类型（ADD时） | +|   `operatorId` | `long` | | 操作人ID | +|   `operatorName` | `string` | | 操作人姓名 | +|   `orderId` | `long` | | 订单ID | +|   `originalResourceName` | `string` | | 原资源名称（房型/车型） | +|   `originalUnitPrice` | `number` | | 原单价（日均） | +|   `reason` | `string` | | 修改原因 | +|   `resourceId` | `long` | | 关联资源ID | +|   `resourceType` | `string` | | 关联资源类型：SCENIC_SPOT/ACTIVITY/RESTAURANT/HOTEL/VEHICLE | +|   `sortOrder` | `int` | | 排序序号（ADD时） | +|   `startTime` | `string` | | 开始时间（ADD时） | +|   `suggestedAdjustment` | `number` | | 系统建议差价 | +|   `updateTime` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/order/{orderId}/itinerary/add-day + +**新增整天行程** + +在订单行程中新增一整天（含多个节点） + +**关联字典**： +- itinerary_edit_action（操作类型，返回字段action）：ADD_DAY=新增整天 +- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认 +- resource_type（资源类型，返回字段resourceType）：SCENIC_SPOT=景区, ACTIVITY=活动, RESTAURANT=餐厅, HOTEL=酒店, VEHICLE=车辆 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `orderId` | `integer` | | 订单ID | + +**请求体** `新增行程天请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `dayNumber` | `int` | 是 | 行程天数编号（插入位置，后续天数自动顺延） | +| `dayTitle` | `string` | 是 | 天标题 | +| `nodes` | `新增行程节点请求[]` | | 该天的行程节点列表 | +|   `balanceAdjustment` | `number` | | 尾款调整金额（正数=增加尾款，负数=减少尾款） | +|   `dayNumber` | `int` | | 行程天数编号（独立调用时必填，addDay子节点时自动继承） | +|   `description` | `string` | | 节点描述 | +|   `nodeName` | `string` | 是 | 节点名称 | +|   `nodeType` | `string` | 是 | 节点类型：SCENIC/HOTEL/RESTAURANT/ACTIVITY/VEHICLE/SERVICE/FREE/NOTE | +|   `reason` | `string` | | 修改原因（独立调用时必填，addDay子节点时自动继承） | +|   `resourceId` | `long` | | 关联资源ID | +|   `resourceType` | `string` | | 关联资源类型：SCENIC_SPOT/ACTIVITY/RESTAURANT/HOTEL/VEHICLE | +|   `sortOrder` | `int` | | 排序序号（插入位置，默认追加到末尾） | +|   `startTime` | `string` | | 开始时间 | +| `prevDayHotel` | `PrevDayHotel` | | 前一天住宿配置（原最后一天无住宿，新增天数后需配置） | +|   `hotelId` | `long` | | 酒店ID | +|   `hotelName` | `string` | | 酒店名称 | +|   `roomTypeId` | `long` | | 房型ID | +|   `roomTypeName` | `string` | | 房型名称 | +| `reason` | `string` | 是 | 变更原因 | + +**响应** `统一响应结果«List«OrderItineraryEdit»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `OrderItineraryEdit[]` | | 响应数据 | +|   `action` | `string` | | 操作类型：SKIP/ADD | +|   `balanceAdjustment` | `number` | | 尾款调整金额（正数=增加尾款，负数=减少尾款） | +|   `changeDays` | `int` | | 变更天数 | +|   `changeReasonCode` | `string` | | 变更原因代码（字典项） | +|   `changeReasonLabel` | `string` | | 变更原因标签 | +|   `confirmStatus` | `string` | | 确认状态：PENDING_CONFIRM/CONFIRMED | +|   `confirmedAt` | `string` | | 确认时间 | +|   `confirmedBy` | `long` | | 确认人ID | +|   `createTime` | `string` | | 创建时间 | +|   `dayNumber` | `int` | | 行程天数编号 | +|   `deletedAt` | `string` | | 删除时间（软删除） | +|   `description` | `string` | | 节点描述（ADD时） | +|   `editId` | `long` | | 编辑ID | +|   `newResourceName` | `string` | | 新资源名称（房型/车型） | +|   `newUnitPrice` | `number` | | 新单价（日均） | +|   `nodeId` | `string` | | 原节点ID（SKIP时必填） | +|   `nodeName` | `string` | | 节点名称（ADD时） | +|   `nodeType` | `string` | | 节点类型（ADD时） | +|   `operatorId` | `long` | | 操作人ID | +|   `operatorName` | `string` | | 操作人姓名 | +|   `orderId` | `long` | | 订单ID | +|   `originalResourceName` | `string` | | 原资源名称（房型/车型） | +|   `originalUnitPrice` | `number` | | 原单价（日均） | +|   `reason` | `string` | | 修改原因 | +|   `resourceId` | `long` | | 关联资源ID | +|   `resourceType` | `string` | | 关联资源类型：SCENIC_SPOT/ACTIVITY/RESTAURANT/HOTEL/VEHICLE | +|   `sortOrder` | `int` | | 排序序号（ADD时） | +|   `startTime` | `string` | | 开始时间（ADD时） | +|   `suggestedAdjustment` | `number` | | 系统建议差价 | +|   `updateTime` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/order/{orderId}/itinerary/add/{editId} + +**删除新增的节点** + +删除通过编辑新增的节点 + +**关联字典**： +- itinerary_edit_action（操作类型，返回字段action）：SKIP=跳过, ADD=新增节点, ADD_DAY=新增整天, ROOM_CHANGE=房型切换, VEHICLE_CHANGE=车型切换 +- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `editId` | `integer` | | 编辑记录ID | +| `orderId` | `integer` | | 订单ID | + +**请求体** `撤销行程编辑请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `reason` | `string` | 是 | 撤销原因 | + +**响应** `统一响应结果«Void»` + +--- + +### `GET` /admin/order/{orderId}/itinerary/balance-summary + +**获取尾款调整汇总** + +返回行程编辑产生的尾款调整明细和总额 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `orderId` | `integer` | | 订单ID | + +**响应** `统一响应结果«Map«string,object»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `object` | | 响应数据 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/order/{orderId}/itinerary/confirm-all + +**批量确认所有待确认修改** + +确认该订单所有待确认的行程编辑 + +**关联字典**： +- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `orderId` | `integer` | | 订单ID | + +**响应** `统一响应结果«int»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `int` | | 响应数据 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/order/{orderId}/itinerary/confirm/{editId} + +**确认单条修改** + +确认一条待确认的行程编辑 + +**关联字典**： +- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `editId` | `integer` | | 编辑记录ID | +| `orderId` | `integer` | | 订单ID | + +**响应** `统一响应结果«Void»` + +--- + +### `DELETE` /admin/order/{orderId}/itinerary/day/{editId} + +**删除新增的整天行程** + +删除通过新增操作添加的整天行程及其所有子节点，已确认的天不允许删除 + +**关联字典**： +- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `editId` | `integer` | | ADD_DAY编辑记录ID | +| `orderId` | `integer` | | 订单ID | + +**请求体** `撤销行程编辑请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `reason` | `string` | 是 | 撤销原因 | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/order/{orderId}/itinerary/edit/{editId} + +**修改编辑记录** + +修改待确认状态的编辑记录（如调整价格、名称等） + +**关联字典**： +- itinerary_edit_action（操作类型，返回字段action）：SKIP=跳过, ADD=新增节点, ADD_DAY=新增整天, ROOM_CHANGE=房型切换, VEHICLE_CHANGE=车型切换 +- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认 +- resource_type（资源类型，返回字段resourceType）：SCENIC_SPOT=景区, ACTIVITY=活动, RESTAURANT=餐厅, HOTEL=酒店, VEHICLE=车辆 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `editId` | `integer` | | 编辑记录ID | +| `orderId` | `integer` | | 订单ID | + +**请求体** `object` + +**响应** `统一响应结果«OrderItineraryEdit»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `OrderItineraryEdit` | | 响应数据 | +|   `action` | `string` | | 操作类型：SKIP/ADD | +|   `balanceAdjustment` | `number` | | 尾款调整金额（正数=增加尾款，负数=减少尾款） | +|   `changeDays` | `int` | | 变更天数 | +|   `changeReasonCode` | `string` | | 变更原因代码（字典项） | +|   `changeReasonLabel` | `string` | | 变更原因标签 | +|   `confirmStatus` | `string` | | 确认状态：PENDING_CONFIRM/CONFIRMED | +|   `confirmedAt` | `string` | | 确认时间 | +|   `confirmedBy` | `long` | | 确认人ID | +|   `createTime` | `string` | | 创建时间 | +|   `dayNumber` | `int` | | 行程天数编号 | +|   `deletedAt` | `string` | | 删除时间（软删除） | +|   `description` | `string` | | 节点描述（ADD时） | +|   `editId` | `long` | | 编辑ID | +|   `newResourceName` | `string` | | 新资源名称（房型/车型） | +|   `newUnitPrice` | `number` | | 新单价（日均） | +|   `nodeId` | `string` | | 原节点ID（SKIP时必填） | +|   `nodeName` | `string` | | 节点名称（ADD时） | +|   `nodeType` | `string` | | 节点类型（ADD时） | +|   `operatorId` | `long` | | 操作人ID | +|   `operatorName` | `string` | | 操作人姓名 | +|   `orderId` | `long` | | 订单ID | +|   `originalResourceName` | `string` | | 原资源名称（房型/车型） | +|   `originalUnitPrice` | `number` | | 原单价（日均） | +|   `reason` | `string` | | 修改原因 | +|   `resourceId` | `long` | | 关联资源ID | +|   `resourceType` | `string` | | 关联资源类型：SCENIC_SPOT/ACTIVITY/RESTAURANT/HOTEL/VEHICLE | +|   `sortOrder` | `int` | | 排序序号（ADD时） | +|   `startTime` | `string` | | 开始时间（ADD时） | +|   `suggestedAdjustment` | `number` | | 系统建议差价 | +|   `updateTime` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/order/{orderId}/itinerary/edits + +**获取行程编辑记录列表** + +**关联字典**： +- itinerary_edit_action（操作类型，返回字段action）：SKIP=跳过, ADD=新增节点, ADD_DAY=新增整天, ROOM_CHANGE=房型切换, VEHICLE_CHANGE=车型切换 +- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认 +- resource_type（资源类型，返回字段resourceType）：SCENIC_SPOT=景区, ACTIVITY=活动, RESTAURANT=餐厅, HOTEL=酒店, VEHICLE=车辆 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `orderId` | `integer` | | 订单ID | + +**响应** `统一响应结果«List«OrderItineraryEdit»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `OrderItineraryEdit[]` | | 响应数据 | +|   `action` | `string` | | 操作类型：SKIP/ADD | +|   `balanceAdjustment` | `number` | | 尾款调整金额（正数=增加尾款，负数=减少尾款） | +|   `changeDays` | `int` | | 变更天数 | +|   `changeReasonCode` | `string` | | 变更原因代码（字典项） | +|   `changeReasonLabel` | `string` | | 变更原因标签 | +|   `confirmStatus` | `string` | | 确认状态：PENDING_CONFIRM/CONFIRMED | +|   `confirmedAt` | `string` | | 确认时间 | +|   `confirmedBy` | `long` | | 确认人ID | +|   `createTime` | `string` | | 创建时间 | +|   `dayNumber` | `int` | | 行程天数编号 | +|   `deletedAt` | `string` | | 删除时间（软删除） | +|   `description` | `string` | | 节点描述（ADD时） | +|   `editId` | `long` | | 编辑ID | +|   `newResourceName` | `string` | | 新资源名称（房型/车型） | +|   `newUnitPrice` | `number` | | 新单价（日均） | +|   `nodeId` | `string` | | 原节点ID（SKIP时必填） | +|   `nodeName` | `string` | | 节点名称（ADD时） | +|   `nodeType` | `string` | | 节点类型（ADD时） | +|   `operatorId` | `long` | | 操作人ID | +|   `operatorName` | `string` | | 操作人姓名 | +|   `orderId` | `long` | | 订单ID | +|   `originalResourceName` | `string` | | 原资源名称（房型/车型） | +|   `originalUnitPrice` | `number` | | 原单价（日均） | +|   `reason` | `string` | | 修改原因 | +|   `resourceId` | `long` | | 关联资源ID | +|   `resourceType` | `string` | | 关联资源类型：SCENIC_SPOT/ACTIVITY/RESTAURANT/HOTEL/VEHICLE | +|   `sortOrder` | `int` | | 排序序号（ADD时） | +|   `startTime` | `string` | | 开始时间（ADD时） | +|   `suggestedAdjustment` | `number` | | 系统建议差价 | +|   `updateTime` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/order/{orderId}/itinerary/merged + +**获取合并后的行程（原始+编辑）** + +**关联字典**： +- itinerary_edit_action（操作类型，返回字段action）：SKIP=跳过, ADD=新增节点, ADD_DAY=新增整天, ROOM_CHANGE=房型切换, VEHICLE_CHANGE=车型切换 +- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认 +- resource_type（资源类型，返回字段resourceType）：SCENIC_SPOT=景区, ACTIVITY=活动, RESTAURANT=餐厅, HOTEL=酒店, VEHICLE=车辆 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `orderId` | `integer` | | 订单ID | + +**响应** `统一响应结果«List«Map«string,object»»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `Map«string,object»[]` | | 响应数据 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/order/{orderId}/itinerary/pending-count + +**获取待确认数量** + +返回该订单待确认的编辑数量 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `orderId` | `integer` | | 订单ID | + +**响应** `统一响应结果«long»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `long` | | 响应数据 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/order/{orderId}/itinerary/pending/{editId} + +**撤回待确认的修改** + +软删除一条待确认的编辑记录 + +**关联字典**： +- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `editId` | `integer` | | 编辑记录ID | +| `orderId` | `integer` | | 订单ID | + +**请求体** `撤销行程编辑请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `reason` | `string` | 是 | 撤销原因 | + +**响应** `统一响应结果«Void»` + +--- + +### `POST` /admin/order/{orderId}/itinerary/room-type-change + +**房型切换** + +执行房型切换，自动计算差价，创建待确认记录 + +**关联字典**： +- itinerary_edit_action（操作类型，返回字段action）：ROOM_CHANGE=房型切换 +- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认 +- resource_type（资源类型，返回字段resourceType）：HOTEL=酒店 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `orderId` | `integer` | | 订单ID | + +**请求体** `房型变更请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `balanceAdjustment` | `number` | | 尾款调整金额（可选，覆盖系统建议差价；正数=增加尾款，负数=减少尾款） | +| `changeReasonCode` | `string` | | 变更原因代码（字典项 order_change_reason） | +| `dayNumber` | `int` | 是 | 行程天数编号 | +| `newRoomTypeId` | `long` | 是 | 新房型ID | +| `originalRoomTypeId` | `long` | 是 | 原房型ID | +| `reason` | `string` | 是 | 变更原因 | +| `roomCount` | `int` | | 房间数量 | + +**响应** `统一响应结果«OrderItineraryEdit»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `OrderItineraryEdit` | | 响应数据 | +|   `action` | `string` | | 操作类型：SKIP/ADD | +|   `balanceAdjustment` | `number` | | 尾款调整金额（正数=增加尾款，负数=减少尾款） | +|   `changeDays` | `int` | | 变更天数 | +|   `changeReasonCode` | `string` | | 变更原因代码（字典项） | +|   `changeReasonLabel` | `string` | | 变更原因标签 | +|   `confirmStatus` | `string` | | 确认状态：PENDING_CONFIRM/CONFIRMED | +|   `confirmedAt` | `string` | | 确认时间 | +|   `confirmedBy` | `long` | | 确认人ID | +|   `createTime` | `string` | | 创建时间 | +|   `dayNumber` | `int` | | 行程天数编号 | +|   `deletedAt` | `string` | | 删除时间（软删除） | +|   `description` | `string` | | 节点描述（ADD时） | +|   `editId` | `long` | | 编辑ID | +|   `newResourceName` | `string` | | 新资源名称（房型/车型） | +|   `newUnitPrice` | `number` | | 新单价（日均） | +|   `nodeId` | `string` | | 原节点ID（SKIP时必填） | +|   `nodeName` | `string` | | 节点名称（ADD时） | +|   `nodeType` | `string` | | 节点类型（ADD时） | +|   `operatorId` | `long` | | 操作人ID | +|   `operatorName` | `string` | | 操作人姓名 | +|   `orderId` | `long` | | 订单ID | +|   `originalResourceName` | `string` | | 原资源名称（房型/车型） | +|   `originalUnitPrice` | `number` | | 原单价（日均） | +|   `reason` | `string` | | 修改原因 | +|   `resourceId` | `long` | | 关联资源ID | +|   `resourceType` | `string` | | 关联资源类型：SCENIC_SPOT/ACTIVITY/RESTAURANT/HOTEL/VEHICLE | +|   `sortOrder` | `int` | | 排序序号（ADD时） | +|   `startTime` | `string` | | 开始时间（ADD时） | +|   `suggestedAdjustment` | `number` | | 系统建议差价 | +|   `updateTime` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/order/{orderId}/itinerary/room-type-change/preview + +**房型切换差价预览** + +预览房型切换的差价，不创建记录 + +**关联字典**： +- resource_type（资源类型，返回字段resourceType）：HOTEL=酒店 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `orderId` | `integer` | | 订单ID | + +**请求体** `房型变更请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `balanceAdjustment` | `number` | | 尾款调整金额（可选，覆盖系统建议差价；正数=增加尾款，负数=减少尾款） | +| `changeReasonCode` | `string` | | 变更原因代码（字典项 order_change_reason） | +| `dayNumber` | `int` | 是 | 行程天数编号 | +| `newRoomTypeId` | `long` | 是 | 新房型ID | +| `originalRoomTypeId` | `long` | 是 | 原房型ID | +| `reason` | `string` | 是 | 变更原因 | +| `roomCount` | `int` | | 房间数量 | + +**响应** `统一响应结果«差价计算结果»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `差价计算结果` | | 响应数据 | +|   `changeDays` | `int` | | 变更天数 | +|   `description` | `string` | | 差价描述（中文说明） | +|   `direction` | `string` | | 差价方向：UPGRADE=升级加价, DOWNGRADE=降级减价, SAME=价格不变 | +|   `newName` | `string` | | 新资源名称 | +|   `newUnitPrice` | `number` | | 新单价（日均） | +|   `originalName` | `string` | | 原资源名称 | +|   `originalUnitPrice` | `number` | | 原单价（日均） | +|   `priceDiff` | `number` | | 差价金额（正数=需补款，负数=可退款） | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/order/{orderId}/itinerary/skip + +**跳过节点** + +将行程中的某个节点标记为跳过（客户不去） + +**关联字典**： +- itinerary_edit_action（操作类型，返回字段action）：SKIP=跳过, ADD=新增节点, ADD_DAY=新增整天, ROOM_CHANGE=房型切换, VEHICLE_CHANGE=车型切换 +- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认 +- resource_type（资源类型，返回字段resourceType）：SCENIC_SPOT=景区, ACTIVITY=活动, RESTAURANT=餐厅, HOTEL=酒店, VEHICLE=车辆 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `orderId` | `integer` | | 订单ID | + +**请求体** `跳过行程节点请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `balanceAdjustment` | `number` | | 尾款调整金额（正数=增加尾款，负数=减少尾款） | +| `dayNumber` | `int` | 是 | 行程天数编号 | +| `nodeId` | `string` | 是 | 节点ID | +| `nodeName` | `string` | | 节点名称 | +| `reason` | `string` | 是 | 修改原因 | + +**响应** `统一响应结果«OrderItineraryEdit»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `OrderItineraryEdit` | | 响应数据 | +|   `action` | `string` | | 操作类型：SKIP/ADD | +|   `balanceAdjustment` | `number` | | 尾款调整金额（正数=增加尾款，负数=减少尾款） | +|   `changeDays` | `int` | | 变更天数 | +|   `changeReasonCode` | `string` | | 变更原因代码（字典项） | +|   `changeReasonLabel` | `string` | | 变更原因标签 | +|   `confirmStatus` | `string` | | 确认状态：PENDING_CONFIRM/CONFIRMED | +|   `confirmedAt` | `string` | | 确认时间 | +|   `confirmedBy` | `long` | | 确认人ID | +|   `createTime` | `string` | | 创建时间 | +|   `dayNumber` | `int` | | 行程天数编号 | +|   `deletedAt` | `string` | | 删除时间（软删除） | +|   `description` | `string` | | 节点描述（ADD时） | +|   `editId` | `long` | | 编辑ID | +|   `newResourceName` | `string` | | 新资源名称（房型/车型） | +|   `newUnitPrice` | `number` | | 新单价（日均） | +|   `nodeId` | `string` | | 原节点ID（SKIP时必填） | +|   `nodeName` | `string` | | 节点名称（ADD时） | +|   `nodeType` | `string` | | 节点类型（ADD时） | +|   `operatorId` | `long` | | 操作人ID | +|   `operatorName` | `string` | | 操作人姓名 | +|   `orderId` | `long` | | 订单ID | +|   `originalResourceName` | `string` | | 原资源名称（房型/车型） | +|   `originalUnitPrice` | `number` | | 原单价（日均） | +|   `reason` | `string` | | 修改原因 | +|   `resourceId` | `long` | | 关联资源ID | +|   `resourceType` | `string` | | 关联资源类型：SCENIC_SPOT/ACTIVITY/RESTAURANT/HOTEL/VEHICLE | +|   `sortOrder` | `int` | | 排序序号（ADD时） | +|   `startTime` | `string` | | 开始时间（ADD时） | +|   `suggestedAdjustment` | `number` | | 系统建议差价 | +|   `updateTime` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/order/{orderId}/itinerary/skip/{editId} + +**恢复跳过的节点** + +取消跳过，恢复为正常状态 + +**关联字典**： +- itinerary_edit_action（操作类型，返回字段action）：SKIP=跳过, ADD=新增节点, ADD_DAY=新增整天, ROOM_CHANGE=房型切换, VEHICLE_CHANGE=车型切换 +- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `editId` | `integer` | | 编辑记录ID | +| `orderId` | `integer` | | 订单ID | + +**请求体** `撤销行程编辑请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `reason` | `string` | 是 | 撤销原因 | + +**响应** `统一响应结果«Void»` + +--- + +### `POST` /admin/order/{orderId}/itinerary/vehicle-type-change + +**车型切换** + +执行车型切换，自动计算差价，创建待确认记录 + +**关联字典**： +- itinerary_edit_action（操作类型，返回字段action）：VEHICLE_CHANGE=车型切换 +- itinerary_confirm_status（确认状态，返回字段confirmStatus）：PENDING_CONFIRM=待确认, CONFIRMED=已确认 +- resource_type（资源类型，返回字段resourceType）：VEHICLE=车辆 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `orderId` | `integer` | | 订单ID | + +**请求体** `车型变更请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `balanceAdjustment` | `number` | | 尾款调整金额（可选，覆盖系统建议差价；正数=增加尾款，负数=减少尾款） | +| `changeReasonCode` | `string` | | 变更原因代码（字典项 order_change_reason） | +| `newVehicleId` | `long` | 是 | 新车辆ID | +| `originalVehicleId` | `long` | 是 | 原车辆ID | +| `reason` | `string` | 是 | 变更原因 | + +**响应** `统一响应结果«OrderItineraryEdit»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `OrderItineraryEdit` | | 响应数据 | +|   `action` | `string` | | 操作类型：SKIP/ADD | +|   `balanceAdjustment` | `number` | | 尾款调整金额（正数=增加尾款，负数=减少尾款） | +|   `changeDays` | `int` | | 变更天数 | +|   `changeReasonCode` | `string` | | 变更原因代码（字典项） | +|   `changeReasonLabel` | `string` | | 变更原因标签 | +|   `confirmStatus` | `string` | | 确认状态：PENDING_CONFIRM/CONFIRMED | +|   `confirmedAt` | `string` | | 确认时间 | +|   `confirmedBy` | `long` | | 确认人ID | +|   `createTime` | `string` | | 创建时间 | +|   `dayNumber` | `int` | | 行程天数编号 | +|   `deletedAt` | `string` | | 删除时间（软删除） | +|   `description` | `string` | | 节点描述（ADD时） | +|   `editId` | `long` | | 编辑ID | +|   `newResourceName` | `string` | | 新资源名称（房型/车型） | +|   `newUnitPrice` | `number` | | 新单价（日均） | +|   `nodeId` | `string` | | 原节点ID（SKIP时必填） | +|   `nodeName` | `string` | | 节点名称（ADD时） | +|   `nodeType` | `string` | | 节点类型（ADD时） | +|   `operatorId` | `long` | | 操作人ID | +|   `operatorName` | `string` | | 操作人姓名 | +|   `orderId` | `long` | | 订单ID | +|   `originalResourceName` | `string` | | 原资源名称（房型/车型） | +|   `originalUnitPrice` | `number` | | 原单价（日均） | +|   `reason` | `string` | | 修改原因 | +|   `resourceId` | `long` | | 关联资源ID | +|   `resourceType` | `string` | | 关联资源类型：SCENIC_SPOT/ACTIVITY/RESTAURANT/HOTEL/VEHICLE | +|   `sortOrder` | `int` | | 排序序号（ADD时） | +|   `startTime` | `string` | | 开始时间（ADD时） | +|   `suggestedAdjustment` | `number` | | 系统建议差价 | +|   `updateTime` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/order/{orderId}/itinerary/vehicle-type-change/preview + +**车型切换差价预览** + +预览车型切换的差价，不创建记录 + +**关联字典**： +- resource_type（资源类型，返回字段resourceType）：VEHICLE=车辆 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `orderId` | `integer` | | 订单ID | + +**请求体** `车型变更请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `balanceAdjustment` | `number` | | 尾款调整金额（可选，覆盖系统建议差价；正数=增加尾款，负数=减少尾款） | +| `changeReasonCode` | `string` | | 变更原因代码（字典项 order_change_reason） | +| `newVehicleId` | `long` | 是 | 新车辆ID | +| `originalVehicleId` | `long` | 是 | 原车辆ID | +| `reason` | `string` | 是 | 变更原因 | + +**响应** `统一响应结果«差价计算结果»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `差价计算结果` | | 响应数据 | +|   `changeDays` | `int` | | 变更天数 | +|   `description` | `string` | | 差价描述（中文说明） | +|   `direction` | `string` | | 差价方向：UPGRADE=升级加价, DOWNGRADE=降级减价, SAME=价格不变 | +|   `newName` | `string` | | 新资源名称 | +|   `newUnitPrice` | `number` | | 新单价（日均） | +|   `originalName` | `string` | | 原资源名称 | +|   `originalUnitPrice` | `number` | | 原单价（日均） | +|   `priceDiff` | `number` | | 差价金额（正数=需补款，负数=可退款） | +| `message` | `string` | | 响应消息 | + +--- + +## 订单待办接口 + +### `GET` /admin/order/todo/contract-eligible + +**可签合同订单列表（保险已完成）** + +查询保险待办已完成、可以进入签合同环节的订单列表。 +用于合同管理页面展示待签合同的订单 + +【关联字典】 +- 返回字段 todoType → 字典：order_todo_type（订单待办类型） +- 返回字段 orderStatus → 字典：order_status（订单状态） + +**响应** `统一响应结果«List«订单待办VO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `订单待办VO[]` | | 响应数据 | +|   `assigneeAdminId` | `long` | | 负责管理员ID | +|   `assigneeRoleKey` | `string` | | 负责角色标识 | +|   `blocked` | `boolean` | | 是否阻塞 | +|   `blockedReason` | `string` | | 阻塞原因 | +|   `completedAt` | `string` | | 完成时间 | +|   `completedBy` | `long` | | 完成人ID | +|   `contactName` | `string` | | 联系人姓名（关联查询） | +|   `createTime` | `string` | | 创建时间 | +|   `departureDate` | `string` | | 出发日期（关联查询） | +|   `orderId` | `long` | | 订单ID | +|   `orderNo` | `string` | | 订单号 | +|   `orderStatus` | `string` | | 订单状态（关联查询） | +|   `productName` | `string` | | 产品名称（关联查询） | +|   `sequence` | `int` | | 排序序号 | +|   `status` | `string` | | 待办状态 | +|   `todoId` | `long` | | 待办ID | +|   `todoLabel` | `string` | | 待办名称 | +|   `todoType` | `string` | | 待办类型 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/order/todo/customizer-list + +**定制师列表** + +获取所有定制师(CUSTOMIZER角色)的列表，用于更换定制师时选择目标定制师 + +**响应** `统一响应结果«List«管理员基本信息»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `管理员基本信息[]` | | 响应数据 | +|   `adminId` | `long` | | 管理员ID | +|   `avatarUrl` | `string` | | 头像URL | +|   `username` | `string` | | 用户名 | +|   `wechatName` | `string` | | 企微用户名称 | +|   `wechatUserid` | `string` | | 企微用户ID | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/order/todo/my-count + +**我的待办数量** + +返回当前管理员未完成的待办总数，用于首页角标/红点提醒 + +**响应** `统一响应结果«int»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `int` | | 响应数据 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/order/todo/my-list + +**我的待办列表** + +根据当前管理员ID和角色，查询分配给自己的未完成待办。 +超级管理员可看到所有待办，其他角色只能看到对应类型的待办 + +【关联字典】 +- 返回字段 todoType → 字典：order_todo_type（订单待办类型） +- 返回字段 orderStatus → 字典：order_status（订单状态） + +**响应** `统一响应结果«List«订单待办VO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `订单待办VO[]` | | 响应数据 | +|   `assigneeAdminId` | `long` | | 负责管理员ID | +|   `assigneeRoleKey` | `string` | | 负责角色标识 | +|   `blocked` | `boolean` | | 是否阻塞 | +|   `blockedReason` | `string` | | 阻塞原因 | +|   `completedAt` | `string` | | 完成时间 | +|   `completedBy` | `long` | | 完成人ID | +|   `contactName` | `string` | | 联系人姓名（关联查询） | +|   `createTime` | `string` | | 创建时间 | +|   `departureDate` | `string` | | 出发日期（关联查询） | +|   `orderId` | `long` | | 订单ID | +|   `orderNo` | `string` | | 订单号 | +|   `orderStatus` | `string` | | 订单状态（关联查询） | +|   `productName` | `string` | | 产品名称（关联查询） | +|   `sequence` | `int` | | 排序序号 | +|   `status` | `string` | | 待办状态 | +|   `todoId` | `long` | | 待办ID | +|   `todoLabel` | `string` | | 待办名称 | +|   `todoType` | `string` | | 待办类型 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/order/todo/{todoId}/complete + +**完成待办** + +将指定待办标记为已完成。 +需要对应角色权限：如配房待办需ROOM_MANAGER角色，配车待办需VEHICLE_MANAGER角色。 + +完成后系统自动检查是否所有必要待办已完成，若是则推进内部流程 + +【关联字典】 +- 涉及字段 todoType → 字典：order_todo_type（订单待办类型） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `todoId` | `integer` | | 待办ID | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/order/{orderId}/customizer + +**更换定制师** + +将订单转派给另一位定制师。更换后原定制师的待办自动转移，订单时间线会记录此操作 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `orderId` | `integer` | | 订单ID | + +**请求体** `更换定制师请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `customizerId` | `long` | 是 | 定制师ID | + +**响应** `统一响应结果«Void»` + +--- + +### `GET` /admin/order/{orderId}/todos + +**获取订单待办列表** + +返回指定订单的所有待办项（含已完成和未完成）。 +待办类型包括：配房、配车、签合同、购保险、核算等，随内部流程自动生成 + +【关联字典】 +- 返回字段 todoType → 字典：order_todo_type（订单待办类型） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `orderId` | `integer` | | 订单ID | + +**响应** `统一响应结果«List«OrderTodo»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `OrderTodo[]` | | 响应数据 | +|   `assigneeAdminId` | `long` | | 指派管理员ID | +|   `assigneeRoleKey` | `string` | | 指派角色Key | +|   `completedAt` | `string` | | 完成时间 | +|   `completedBy` | `long` | | 完成人ID | +|   `createTime` | `string` | | 创建时间 | +|   `deletedAt` | `string` | | 删除时间（软删除） | +|   `lastNotifiedAt` | `string` | | 最后通知时间 | +|   `notificationCount` | `int` | | 通知次数 | +|   `orderId` | `long` | | 订单ID | +|   `orderNo` | `string` | | 订单编号 | +|   `sequence` | `int` | | 排序序号 | +|   `status` | `string` | | 待办状态 | +|   `todoId` | `long` | | 待办ID | +|   `todoLabel` | `string` | | 待办标签 | +|   `todoType` | `string` | | 待办类型 | +|   `updateTime` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +## 订单配置接口 + +### `GET` /admin/order/config/expiry-minutes + +**获取订单过期配置** + +获取当前的订单未支付自动过期时间（分钟）。 +返回当前值、默认值和配置来源（redis=已自定义, default=使用默认值） + +**响应** `统一响应结果«Map«string,object»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `object` | | 响应数据 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/order/config/expiry-minutes + +**设置订单过期时间（分钟）** + +修改订单未支付自动取消的等待时间。存储在Redis中，即时生效。 +仅影响新创建的订单，已有订单的过期时间不变 + +**请求体** `修改订单过期时间请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `minutes` | `int` | 是 | 过期时间（分钟） | + +**响应** `统一响应结果«Void»` + +--- + +## 退款政策管理 + +### `POST` /admin/order/refund-policy + +**创建退款政策** + +退款政策定义按产品类型和距出发天数的退款比例阶梯 + +例如：出发前30天退90%，前15天退70%，前7天退50%，7天内不可退 + +每种产品类型可配置独立的退款政策，用户申请退款时系统自动匹配 + +【关联字典】 +- 请求参数 refundType → 字典：refund_type（退款类型） +- 请求参数 productType → 字典：product_type（产品类型） + +**请求体** `退款政策请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `endDate` | `string` | | 生效结束日期 | +| `isDefault` | `boolean` | | 是否为默认政策 | +| `policyName` | `string` | 是 | 政策名称 | +| `refundType` | `string` | 是 | 退款类型 | +| `remark` | `string` | | 备注 | +| `rules` | `退款规则项[]` | 是 | 退款规则列表 | +|   `minDays` | `int` | 是 | 距出发最少天数（含当天）。例如：minDays=7表示出发前7天及以上适用此规则 | +|   `refundRatio` | `int` | 是 | 退款比例（百分比，0-100）。例如：80表示退已付金额的80% | +| `startDate` | `string` | | 生效开始日期 | + +**响应** `统一响应结果«退款政策VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `退款政策VO` | | 响应数据 | +|   `createTime` | `string` | | 创建时间 | +|   `createdBy` | `long` | | 创建人ID | +|   `enabled` | `boolean` | | 是否启用 | +|   `endDate` | `string` | | 生效结束日期 | +|   `isDefault` | `boolean` | | 是否为默认政策 | +|   `policyId` | `long` | | 政策ID | +|   `policyName` | `string` | | 政策名称 | +|   `refundType` | `string` | | 退款类型 | +|   `remark` | `string` | | 备注 | +|   `rules` | `退款规则VO[]` | | 退款规则列表 | +|     `minDays` | `int` | | 距出发最少天数 | +|     `refundRatio` | `int` | | 退款比例（百分比） | +|     `ruleId` | `long` | | 规则ID | +|   `startDate` | `string` | | 生效开始日期 | +|   `updateTime` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/order/refund-policy/list + +**退款政策列表** + +【关联字典】 +- 返回字段 refundType → 字典：refund_type（退款类型） +- 返回字段 productType → 字典：product_type（产品类型） + +**响应** `统一响应结果«List«退款政策VO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `退款政策VO[]` | | 响应数据 | +|   `createTime` | `string` | | 创建时间 | +|   `createdBy` | `long` | | 创建人ID | +|   `enabled` | `boolean` | | 是否启用 | +|   `endDate` | `string` | | 生效结束日期 | +|   `isDefault` | `boolean` | | 是否为默认政策 | +|   `policyId` | `long` | | 政策ID | +|   `policyName` | `string` | | 政策名称 | +|   `refundType` | `string` | | 退款类型 | +|   `remark` | `string` | | 备注 | +|   `rules` | `退款规则VO[]` | | 退款规则列表 | +|     `minDays` | `int` | | 距出发最少天数 | +|     `refundRatio` | `int` | | 退款比例（百分比） | +|     `ruleId` | `long` | | 规则ID | +|   `startDate` | `string` | | 生效开始日期 | +|   `updateTime` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/order/refund-policy/{policyId} + +**退款政策详情** + +【关联字典】 +- 返回字段 refundType → 字典：refund_type（退款类型） +- 返回字段 productType → 字典：product_type（产品类型） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `policyId` | `integer` | | 退款政策ID | + +**响应** `统一响应结果«退款政策VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `退款政策VO` | | 响应数据 | +|   `createTime` | `string` | | 创建时间 | +|   `createdBy` | `long` | | 创建人ID | +|   `enabled` | `boolean` | | 是否启用 | +|   `endDate` | `string` | | 生效结束日期 | +|   `isDefault` | `boolean` | | 是否为默认政策 | +|   `policyId` | `long` | | 政策ID | +|   `policyName` | `string` | | 政策名称 | +|   `refundType` | `string` | | 退款类型 | +|   `remark` | `string` | | 备注 | +|   `rules` | `退款规则VO[]` | | 退款规则列表 | +|     `minDays` | `int` | | 距出发最少天数 | +|     `refundRatio` | `int` | | 退款比例（百分比） | +|     `ruleId` | `long` | | 规则ID | +|   `startDate` | `string` | | 生效开始日期 | +|   `updateTime` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/order/refund-policy/{policyId} + +**修改退款政策** + +【关联字典】 +- 请求参数 refundType → 字典：refund_type（退款类型） +- 请求参数 productType → 字典：product_type（产品类型） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `policyId` | `integer` | | 退款政策ID | + +**请求体** `退款政策请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `endDate` | `string` | | 生效结束日期 | +| `isDefault` | `boolean` | | 是否为默认政策 | +| `policyName` | `string` | 是 | 政策名称 | +| `refundType` | `string` | 是 | 退款类型 | +| `remark` | `string` | | 备注 | +| `rules` | `退款规则项[]` | 是 | 退款规则列表 | +|   `minDays` | `int` | 是 | 距出发最少天数（含当天）。例如：minDays=7表示出发前7天及以上适用此规则 | +|   `refundRatio` | `int` | 是 | 退款比例（百分比，0-100）。例如：80表示退已付金额的80% | +| `startDate` | `string` | | 生效开始日期 | + +**响应** `统一响应结果«退款政策VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `退款政策VO` | | 响应数据 | +|   `createTime` | `string` | | 创建时间 | +|   `createdBy` | `long` | | 创建人ID | +|   `enabled` | `boolean` | | 是否启用 | +|   `endDate` | `string` | | 生效结束日期 | +|   `isDefault` | `boolean` | | 是否为默认政策 | +|   `policyId` | `long` | | 政策ID | +|   `policyName` | `string` | | 政策名称 | +|   `refundType` | `string` | | 退款类型 | +|   `remark` | `string` | | 备注 | +|   `rules` | `退款规则VO[]` | | 退款规则列表 | +|     `minDays` | `int` | | 距出发最少天数 | +|     `refundRatio` | `int` | | 退款比例（百分比） | +|     `ruleId` | `long` | | 规则ID | +|   `startDate` | `string` | | 生效开始日期 | +|   `updateTime` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/order/refund-policy/{policyId} + +**删除退款政策** + +软删除退款政策。删除后该产品类型将使用默认退款规则。不影响已使用该政策处理的历史退款申请。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `policyId` | `integer` | | 退款政策ID | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/order/refund-policy/{policyId}/toggle + +**启用/禁用退款政策** + +禁用后该政策不再参与退款金额计算，对应产品类型将使用默认退款规则 + +同一产品类型仅允许一个启用中的政策 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `policyId` | `integer` | | 退款政策ID | + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `enabled` | `boolean` | | 是否启用 | | + +**响应** `统一响应结果«Void»` + +--- + +## 退款管理 + +### `GET` /admin/order/refund/list + +**退款申请列表** + +分页查询退款申请，支持按状态筛选。 +状态包括：PENDING(待审批)、APPROVED(已通过)、REJECTED(已拒绝)、REFUNDING(退款中)、REFUNDED(已退款)、CANCELLED(已撤回)、APPEAL(申诉中) + +【关联字典】 +- 筛选参数 status → 字典：refund_status（退款状态） +- 返回字段 status → 字典：refund_status（退款状态） + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `page` | `integer(int32)` | | 页码 | | +| `pageSize` | `integer(int32)` | | 每页条数 | | +| `status` | `string` | | 状态 | | + +**响应** `统一响应结果«分页结果«退款申请VO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«退款申请VO»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `退款申请VO[]` | | 数据列表 | +|     `actualAmount` | `number` | | 实际退款金额 | +|     `appealAmount` | `number` | | 申诉退款金额 | +|     `appealReason` | `string` | | 申诉原因 | +|     `appealStatus` | `int` | | 申诉状态: 1-处理中 2-通过 3-驳回 | +|     `appealStatusLabel` | `string` | | 申诉状态标签 | +|     `appealedAt` | `string` | | 申诉时间 | +|     `applicantId` | `long` | | 申请人ID | +|     `applicantName` | `string` | | 申请人姓名 | +|     `applicantType` | `string` | | 申请人类型（USER/ADMIN） | +|     `applicationId` | `long` | | 申请ID | +|     `approvalNo` | `string` | | 审批编号 | +|     `calculatedAmount` | `number` | | 计算退款金额 | +|     `createTime` | `string` | | 创建时间 | +|     `daysBeforeDept` | `int` | | 距出发天数 | +|     `departureDate` | `string` | | 出发日期 | +|     `orderId` | `long` | | 订单ID | +|     `orderNo` | `string` | | 订单号 | +|     `paidAmount` | `number` | | 已付金额 | +|     `policyId` | `long` | | 退款政策ID | +|     `policyName` | `string` | | 退款政策名称 | +|     `productName` | `string` | | 产品名称 | +|     `reasonDetail` | `string` | | 补充说明 | +|     `reasonId` | `long` | | 退款原因ID | +|     `reasonText` | `string` | | 退款原因 | +|     `refundRatio` | `int` | | 退款比例（百分比） | +|     `refundType` | `string` | | 退款类型（字典：refund_type） | +|     `refundTypeLabel` | `string` | | 退款类型标签（字典：refund_type 翻译） | +|     `refundedAt` | `string` | | 退款完成时间 | +|     `reviewAdminId` | `long` | | 审批管理员ID | +|     `reviewAdminName` | `string` | | 审批管理员姓名 | +|     `reviewRemark` | `string` | | 审批备注 | +|     `reviewedAt` | `string` | | 审批时间 | +|     `status` | `string` | | 退款状态（字典：refund_status） | +|     `statusLabel` | `string` | | 退款状态标签（字典：refund_status 翻译） | +|     `updateTime` | `string` | | 更新时间 | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/order/refund/reason + +**创建退款原因** + +新增退款原因选项，C端用户申请退款时可选择。按sortOrder排序展示 + +【关联字典】 +- 请求参数 category → 字典：refund_reason_category（退款原因分类） + +**请求体** `创建退款原因请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `category` | `string` | | 分类 | +| `reasonText` | `string` | 是 | 退款原因文本 | +| `sortOrder` | `int` | | 排序号 | + +**响应** `统一响应结果«退款原因VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `退款原因VO` | | 响应数据 | +|   `category` | `string` | | 原因分类 | +|   `enabled` | `boolean` | | 是否启用 | +|   `reasonId` | `long` | | 原因ID | +|   `reasonText` | `string` | | 原因描述 | +|   `sortOrder` | `int` | | 排序序号 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/order/refund/reason/list + +**退款原因列表** + +获取所有退款原因选项（含禁用的），用于退款原因管理页面 + +【关联字典】 +- 返回字段 category → 字典：refund_reason_category（退款原因分类） + +**响应** `统一响应结果«List«退款原因VO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `退款原因VO[]` | | 响应数据 | +|   `category` | `string` | | 原因分类 | +|   `enabled` | `boolean` | | 是否启用 | +|   `reasonId` | `long` | | 原因ID | +|   `reasonText` | `string` | | 原因描述 | +|   `sortOrder` | `int` | | 排序序号 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/order/refund/reason/{reasonId} + +**修改退款原因** + +修改退款原因的文本、分类或排序，不影响已使用该原因的历史退款申请 + +【关联字典】 +- 请求参数 category → 字典：refund_reason_category（退款原因分类） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `reasonId` | `integer` | | 退款原因ID | + +**请求体** `修改退款原因请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `category` | `string` | | 分类 | +| `reasonText` | `string` | | 退款原因文本 | +| `sortOrder` | `int` | | 排序号 | + +**响应** `统一响应结果«退款原因VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `退款原因VO` | | 响应数据 | +|   `category` | `string` | | 原因分类 | +|   `enabled` | `boolean` | | 是否启用 | +|   `reasonId` | `long` | | 原因ID | +|   `reasonText` | `string` | | 原因描述 | +|   `sortOrder` | `int` | | 排序序号 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/order/refund/reason/{reasonId} + +**删除退款原因** + +软删除退款原因，删除后C端不再展示。不影响已使用该原因的历史退款申请 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `reasonId` | `integer` | | 退款原因ID | + +**响应** `统一响应结果«Void»` + +--- + +### `GET` /admin/order/refund/{applicationId} + +**退款申请详情** + +返回退款申请的完整信息，包括退款原因、申请金额、实退金额、审批记录、申诉信息等 + +【关联字典】 +- 返回字段 status → 字典：refund_status（退款状态） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `applicationId` | `integer` | | 退款申请ID | + +**响应** `统一响应结果«退款申请VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `退款申请VO` | | 响应数据 | +|   `actualAmount` | `number` | | 实际退款金额 | +|   `appealAmount` | `number` | | 申诉退款金额 | +|   `appealReason` | `string` | | 申诉原因 | +|   `appealStatus` | `int` | | 申诉状态: 1-处理中 2-通过 3-驳回 | +|   `appealStatusLabel` | `string` | | 申诉状态标签 | +|   `appealedAt` | `string` | | 申诉时间 | +|   `applicantId` | `long` | | 申请人ID | +|   `applicantName` | `string` | | 申请人姓名 | +|   `applicantType` | `string` | | 申请人类型（USER/ADMIN） | +|   `applicationId` | `long` | | 申请ID | +|   `approvalNo` | `string` | | 审批编号 | +|   `calculatedAmount` | `number` | | 计算退款金额 | +|   `createTime` | `string` | | 创建时间 | +|   `daysBeforeDept` | `int` | | 距出发天数 | +|   `departureDate` | `string` | | 出发日期 | +|   `orderId` | `long` | | 订单ID | +|   `orderNo` | `string` | | 订单号 | +|   `paidAmount` | `number` | | 已付金额 | +|   `policyId` | `long` | | 退款政策ID | +|   `policyName` | `string` | | 退款政策名称 | +|   `productName` | `string` | | 产品名称 | +|   `reasonDetail` | `string` | | 补充说明 | +|   `reasonId` | `long` | | 退款原因ID | +|   `reasonText` | `string` | | 退款原因 | +|   `refundRatio` | `int` | | 退款比例（百分比） | +|   `refundType` | `string` | | 退款类型（字典：refund_type） | +|   `refundTypeLabel` | `string` | | 退款类型标签（字典：refund_type 翻译） | +|   `refundedAt` | `string` | | 退款完成时间 | +|   `reviewAdminId` | `long` | | 审批管理员ID | +|   `reviewAdminName` | `string` | | 审批管理员姓名 | +|   `reviewRemark` | `string` | | 审批备注 | +|   `reviewedAt` | `string` | | 审批时间 | +|   `status` | `string` | | 退款状态（字典：refund_status） | +|   `statusLabel` | `string` | | 退款状态标签（字典：refund_status 翻译） | +|   `updateTime` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/order/refund/{applicationId}/complete + +**手动完成退款** + +用于测试订单或线下退款场景。将处于'退款中'状态的退款申请直接标记为'已退款' + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `applicationId` | `integer` | | 退款申请ID | + +**响应** `统一响应结果«退款申请VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `退款申请VO` | | 响应数据 | +|   `actualAmount` | `number` | | 实际退款金额 | +|   `appealAmount` | `number` | | 申诉退款金额 | +|   `appealReason` | `string` | | 申诉原因 | +|   `appealStatus` | `int` | | 申诉状态: 1-处理中 2-通过 3-驳回 | +|   `appealStatusLabel` | `string` | | 申诉状态标签 | +|   `appealedAt` | `string` | | 申诉时间 | +|   `applicantId` | `long` | | 申请人ID | +|   `applicantName` | `string` | | 申请人姓名 | +|   `applicantType` | `string` | | 申请人类型（USER/ADMIN） | +|   `applicationId` | `long` | | 申请ID | +|   `approvalNo` | `string` | | 审批编号 | +|   `calculatedAmount` | `number` | | 计算退款金额 | +|   `createTime` | `string` | | 创建时间 | +|   `daysBeforeDept` | `int` | | 距出发天数 | +|   `departureDate` | `string` | | 出发日期 | +|   `orderId` | `long` | | 订单ID | +|   `orderNo` | `string` | | 订单号 | +|   `paidAmount` | `number` | | 已付金额 | +|   `policyId` | `long` | | 退款政策ID | +|   `policyName` | `string` | | 退款政策名称 | +|   `productName` | `string` | | 产品名称 | +|   `reasonDetail` | `string` | | 补充说明 | +|   `reasonId` | `long` | | 退款原因ID | +|   `reasonText` | `string` | | 退款原因 | +|   `refundRatio` | `int` | | 退款比例（百分比） | +|   `refundType` | `string` | | 退款类型（字典：refund_type） | +|   `refundTypeLabel` | `string` | | 退款类型标签（字典：refund_type 翻译） | +|   `refundedAt` | `string` | | 退款完成时间 | +|   `reviewAdminId` | `long` | | 审批管理员ID | +|   `reviewAdminName` | `string` | | 审批管理员姓名 | +|   `reviewRemark` | `string` | | 审批备注 | +|   `reviewedAt` | `string` | | 审批时间 | +|   `status` | `string` | | 退款状态（字典：refund_status） | +|   `statusLabel` | `string` | | 退款状态标签（字典：refund_status 翻译） | +|   `updateTime` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/order/refund/{applicationId}/execute-appeal + +**申诉通过后执行退款** + +申诉退款流程：用户发起申诉 → 企微OA审批 → 审批通过后管理员确认实退金额 → 调起微信退款 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `applicationId` | `integer` | | 退款申请ID | + +**请求体** `申诉退款执行请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `actualAmount` | `number` | 是 | 实际退款金额 | +| `remark` | `string` | | 备注 | + +**响应** `统一响应结果«退款申请VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `退款申请VO` | | 响应数据 | +|   `actualAmount` | `number` | | 实际退款金额 | +|   `appealAmount` | `number` | | 申诉退款金额 | +|   `appealReason` | `string` | | 申诉原因 | +|   `appealStatus` | `int` | | 申诉状态: 1-处理中 2-通过 3-驳回 | +|   `appealStatusLabel` | `string` | | 申诉状态标签 | +|   `appealedAt` | `string` | | 申诉时间 | +|   `applicantId` | `long` | | 申请人ID | +|   `applicantName` | `string` | | 申请人姓名 | +|   `applicantType` | `string` | | 申请人类型（USER/ADMIN） | +|   `applicationId` | `long` | | 申请ID | +|   `approvalNo` | `string` | | 审批编号 | +|   `calculatedAmount` | `number` | | 计算退款金额 | +|   `createTime` | `string` | | 创建时间 | +|   `daysBeforeDept` | `int` | | 距出发天数 | +|   `departureDate` | `string` | | 出发日期 | +|   `orderId` | `long` | | 订单ID | +|   `orderNo` | `string` | | 订单号 | +|   `paidAmount` | `number` | | 已付金额 | +|   `policyId` | `long` | | 退款政策ID | +|   `policyName` | `string` | | 退款政策名称 | +|   `productName` | `string` | | 产品名称 | +|   `reasonDetail` | `string` | | 补充说明 | +|   `reasonId` | `long` | | 退款原因ID | +|   `reasonText` | `string` | | 退款原因 | +|   `refundRatio` | `int` | | 退款比例（百分比） | +|   `refundType` | `string` | | 退款类型（字典：refund_type） | +|   `refundTypeLabel` | `string` | | 退款类型标签（字典：refund_type 翻译） | +|   `refundedAt` | `string` | | 退款完成时间 | +|   `reviewAdminId` | `long` | | 审批管理员ID | +|   `reviewAdminName` | `string` | | 审批管理员姓名 | +|   `reviewRemark` | `string` | | 审批备注 | +|   `reviewedAt` | `string` | | 审批时间 | +|   `status` | `string` | | 退款状态（字典：refund_status） | +|   `statusLabel` | `string` | | 退款状态标签（字典：refund_status 翻译） | +|   `updateTime` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/order/refund/{applicationId}/review + +**审批退款申请** + +退款审批流程：查看退款申请 → 决定通过/拒绝 → 通过时填写实退金额 → 系统自动调起微信退款 + +拒绝后用户可发起申诉 + +【关联字典】 +- 返回字段 status → 字典：refund_status（退款状态） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `applicationId` | `integer` | | 退款申请ID | + +**请求体** `管理员退款审批请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `action` | `string` | 是 | 审批结果：APPROVE=通过（自动调起微信退款）、REJECT=拒绝（用户可发起申诉） | +| `actualAmount` | `number` | | 实际退款金额（审批通过时可调整，不传则使用申请金额）。不能超过订单已付金额 | +| `remark` | `string` | | 审批备注 | + +**响应** `统一响应结果«退款申请VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `退款申请VO` | | 响应数据 | +|   `actualAmount` | `number` | | 实际退款金额 | +|   `appealAmount` | `number` | | 申诉退款金额 | +|   `appealReason` | `string` | | 申诉原因 | +|   `appealStatus` | `int` | | 申诉状态: 1-处理中 2-通过 3-驳回 | +|   `appealStatusLabel` | `string` | | 申诉状态标签 | +|   `appealedAt` | `string` | | 申诉时间 | +|   `applicantId` | `long` | | 申请人ID | +|   `applicantName` | `string` | | 申请人姓名 | +|   `applicantType` | `string` | | 申请人类型（USER/ADMIN） | +|   `applicationId` | `long` | | 申请ID | +|   `approvalNo` | `string` | | 审批编号 | +|   `calculatedAmount` | `number` | | 计算退款金额 | +|   `createTime` | `string` | | 创建时间 | +|   `daysBeforeDept` | `int` | | 距出发天数 | +|   `departureDate` | `string` | | 出发日期 | +|   `orderId` | `long` | | 订单ID | +|   `orderNo` | `string` | | 订单号 | +|   `paidAmount` | `number` | | 已付金额 | +|   `policyId` | `long` | | 退款政策ID | +|   `policyName` | `string` | | 退款政策名称 | +|   `productName` | `string` | | 产品名称 | +|   `reasonDetail` | `string` | | 补充说明 | +|   `reasonId` | `long` | | 退款原因ID | +|   `reasonText` | `string` | | 退款原因 | +|   `refundRatio` | `int` | | 退款比例（百分比） | +|   `refundType` | `string` | | 退款类型（字典：refund_type） | +|   `refundTypeLabel` | `string` | | 退款类型标签（字典：refund_type 翻译） | +|   `refundedAt` | `string` | | 退款完成时间 | +|   `reviewAdminId` | `long` | | 审批管理员ID | +|   `reviewAdminName` | `string` | | 审批管理员姓名 | +|   `reviewRemark` | `string` | | 审批备注 | +|   `reviewedAt` | `string` | | 审批时间 | +|   `status` | `string` | | 退款状态（字典：refund_status） | +|   `statusLabel` | `string` | | 退款状态标签（字典：refund_status 翻译） | +|   `updateTime` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- diff --git a/2026-03/17_0951/hl-product-service.md b/2026-03/17_0951/hl-product-service.md new file mode 100644 index 0000000..06de89c --- /dev/null +++ b/2026-03/17_0951/hl-product-service.md @@ -0,0 +1,5188 @@ +# 产品服务 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»` + +--- diff --git a/2026-03/17_0951/hl-resource-service.md b/2026-03/17_0951/hl-resource-service.md new file mode 100644 index 0000000..4bea593 --- /dev/null +++ b/2026-03/17_0951/hl-resource-service.md @@ -0,0 +1,6998 @@ +# 资源服务 API 文档 + +**服务**: `hl-resource-service` +**接口总数**: 183 + +## 目录 + +- **住宿标签管理** (8 个接口) +- **住宿管理** (10 个接口) +- **增值服务管理** (9 个接口) +- **备品标签管理** (8 个接口) +- **备品管理** (9 个接口) +- **房型价格日历** (4 个接口) +- **房型管理** (7 个接口) +- **景区价格日历** (4 个接口) +- **景区季节内容** (3 个接口) +- **景区标签管理** (8 个接口) +- **景区管理** (9 个接口) +- **服务人员价格日历** (4 个接口) +- **服务人员标签管理** (8 个接口) +- **服务人员管理** (9 个接口) +- **服务价格日历** (4 个接口) +- **服务标签管理** (8 个接口) +- **游玩项目价格日历** (4 个接口) +- **游玩项目标签管理** (8 个接口) +- **游玩项目管理** (9 个接口) +- **费用项价格日历** (3 个接口) +- **费用项管理** (8 个接口) +- **车型价格日历** (4 个接口) +- **车型标签管理** (8 个接口) +- **车型管理** (10 个接口) +- **餐厅标签管理** (8 个接口) +- **餐厅管理** (9 个接口) + +--- + +## 住宿标签管理 + +### `PUT` /admin/hotel/item/{hotelId}/tags + +**设置住宿标签** + +全量替换指定住宿的标签列表。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `hotelId` | `integer` | | 住宿ID | + +**请求体** `酒店标签更新请求_1` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagIds` | `string[]` | | 标签ID列表（全量替换） | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/hotel/items/batch/tags + +**批量添加/移除标签** + +对多个住宿批量添加/移除标签。增量操作，不影响未指定的标签。 + +**请求体** `酒店批量标签操作请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `addTagIds` | `string[]` | | 要添加的标签ID列表 | +| `hotelIds` | `string[]` | 是 | 酒店ID列表 | +| `removeTagIds` | `string[]` | | 要移除的标签ID列表 | + +**响应** `统一响应结果«Void»` + +--- + +### `POST` /admin/hotel/tag + +**创建标签** + +创建预设标签，标签名不可重复。 + +**请求体** `酒店标签创建请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagColor` | `string` | | 标签颜色（十六进制） | +| `tagName` | `string` | 是 | 标签名称 | + +**响应** `统一响应结果«酒店标签VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `酒店标签VO` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `tagColor` | `string` | | 标签颜色（十六进制） | +|   `tagId` | `string` | | 标签ID | +|   `tagName` | `string` | | 标签名称 | +|   `tagType` | `int` | | 标签类型：0=自定义 1=系统 | +|   `useCount` | `int` | | 使用次数 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/hotel/tag/adhoc + +**查找或创建自定义标签** + +按名称查找标签，不存在则自动创建。用于住宿编辑时快速输入新标签。 + +**请求体** `酒店标签创建请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagColor` | `string` | | 标签颜色（十六进制） | +| `tagName` | `string` | 是 | 标签名称 | + +**响应** `统一响应结果«酒店标签VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `酒店标签VO` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `tagColor` | `string` | | 标签颜色（十六进制） | +|   `tagId` | `string` | | 标签ID | +|   `tagName` | `string` | | 标签名称 | +|   `tagType` | `int` | | 标签类型：0=自定义 1=系统 | +|   `useCount` | `int` | | 使用次数 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/hotel/tag/{tagId} + +**更新标签** + +修改标签名称或颜色，所有关联住宿自动生效。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagId` | `integer` | | 标签ID | + +**请求体** `酒店标签更新请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagColor` | `string` | | 标签颜色（十六进制） | +| `tagName` | `string` | | 标签名称 | + +**响应** `统一响应结果«酒店标签VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `酒店标签VO` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `tagColor` | `string` | | 标签颜色（十六进制） | +|   `tagId` | `string` | | 标签ID | +|   `tagName` | `string` | | 标签名称 | +|   `tagType` | `int` | | 标签类型：0=自定义 1=系统 | +|   `useCount` | `int` | | 使用次数 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/hotel/tag/{tagId} + +**删除标签** + +删除标签并解除所有住宿与该标签的关联。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagId` | `integer` | | 标签ID | + +**响应** `统一响应结果«Void»` + +--- + +### `GET` /admin/hotel/tags + +**预设标签列表（分页）** + +分页查询住宿标签库，支持按关键词搜索。 + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `keyword` | `string` | | 关键词 | | +| `page` | `integer(int32)` | | 页码 | | +| `pageSize` | `integer(int32)` | | 每页条数 | | + +**响应** `统一响应结果«分页结果«酒店标签VO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«酒店标签VO»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `酒店标签VO[]` | | 数据列表 | +|     `createdAt` | `string` | | 创建时间 | +|     `tagColor` | `string` | | 标签颜色（十六进制） | +|     `tagId` | `string` | | 标签ID | +|     `tagName` | `string` | | 标签名称 | +|     `tagType` | `int` | | 标签类型：0=自定义 1=系统 | +|     `useCount` | `int` | | 使用次数 | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/hotel/tags/all + +**所有标签列表** + +不分页返回所有标签，用于住宿编辑时的标签选择。 + +**响应** `统一响应结果«List«酒店标签VO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `酒店标签VO[]` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `tagColor` | `string` | | 标签颜色（十六进制） | +|   `tagId` | `string` | | 标签ID | +|   `tagName` | `string` | | 标签名称 | +|   `tagType` | `int` | | 标签类型：0=自定义 1=系统 | +|   `useCount` | `int` | | 使用次数 | +| `message` | `string` | | 响应消息 | + +--- + +## 住宿管理 + +### `POST` /admin/hotel/item + +**创建住宿** + +新建住宿资源（酒店/民宿/营地等），初始状态为草稿(status=0)。创建后需通过「提交启用/禁用审批」走企微OA审批流程才能上架。住宿下可继续创建房型（RoomType），房型有独立的价格日历。 + +**关联字典**： +- hotel_type：住宿类型（表单选择） +- hotel_star_level：酒店星级（表单选择） +- hotel_facility：酒店设施（表单多选） + +**请求体** `酒店创建请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `address` | `string` | 是 | 详细地址 | +| `bannerMaterialIds` | `string[]` | | 横幅素材ID列表 | +| `checkInNotes` | `string` | | 入住须知 | +| `checkInTime` | `string` | | 入住时间 | +| `checkOutTime` | `string` | | 退房时间 | +| `city` | `string` | | 城市 | +| `contactPerson` | `string` | | 联系人姓名 | +| `contactPhone` | `string` | | 联系电话 | +| `coverMaterialId` | `string` | | 封面素材ID | +| `description` | `string` | | 酒店描述 | +| `diamondLevel` | `int` | | 钻级：0-5 | +| `district` | `string` | | 区县 | +| `facilities` | `string` | | 设施配置（JSON） | +| `highlights` | `string` | | 酒店亮点（JSON） | +| `hotelType` | `string` | 是 | 住宿类型 | +| `latitude` | `number` | 是 | 纬度 | +| `longitude` | `number` | 是 | 经度 | +| `luggageInfo` | `string` | | 行李服务说明 | +| `name` | `string` | 是 | 酒店名称 | +| `parkingInfo` | `string` | | 停车信息 | +| `province` | `string` | | 省份 | +| `shuttleInfo` | `string` | | 接驳服务说明 | +| `sortOrder` | `int` | | 排序权重，值越大越靠前 | +| `starLevel` | `int` | | 星级：1-5 | +| `subtitle` | `string` | | 副标题 | +| `usageNotes` | `string` | | 使用须知 | +| `videoMaterialIds` | `string[]` | | 视频素材ID列表 | + +**响应** `统一响应结果«酒店详情VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `酒店详情VO` | | 响应数据 | +|   `address` | `string` | | 详细地址 | +|   `bannerMaterialIds` | `string[]` | | 横幅素材ID列表 | +|   `bannerUrls` | `string[]` | | 横幅图URL列表 | +|   `checkInNotes` | `string` | | 入住须知 | +|   `checkInTime` | `string` | | 入住时间 | +|   `checkOutTime` | `string` | | 退房时间 | +|   `city` | `string` | | 城市 | +|   `contactPerson` | `string` | | 联系人姓名 | +|   `contactPhone` | `string` | | 联系电话 | +|   `coverMaterialId` | `string` | | 封面素材ID | +|   `coverUrl` | `string` | | 封面图URL | +|   `createdAt` | `string` | | 创建时间 | +|   `createdBy` | `string` | | 创建者ID | +|   `description` | `string` | | 酒店描述 | +|   `diamondLevel` | `int` | | 钻级：0-5 | +|   `district` | `string` | | 区县 | +|   `facilities` | `string` | | 设施配置（JSON） | +|   `highlights` | `string` | | 酒店亮点（JSON） | +|   `hotelId` | `string` | | 酒店ID | +|   `hotelType` | `string` | | 住宿类型 | +|   `latitude` | `number` | | 纬度 | +|   `longitude` | `number` | | 经度 | +|   `luggageInfo` | `string` | | 行李服务说明 | +|   `name` | `string` | | 酒店名称 | +|   `parkingInfo` | `string` | | 停车信息 | +|   `province` | `string` | | 省份 | +|   `roomTypeCount` | `int` | | 房型数量 | +|   `shuttleInfo` | `string` | | 接驳服务说明 | +|   `sortOrder` | `int` | | 排序权重 | +|   `starLevel` | `int` | | 星级：1-5 | +|   `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +|   `subtitle` | `string` | | 副标题 | +|   `tags` | `酒店标签VO[]` | | 标签列表 | +|     `createdAt` | `string` | | 创建时间 | +|     `tagColor` | `string` | | 标签颜色（十六进制） | +|     `tagId` | `string` | | 标签ID | +|     `tagName` | `string` | | 标签名称 | +|     `tagType` | `int` | | 标签类型：0=自定义 1=系统 | +|     `useCount` | `int` | | 使用次数 | +|   `updatedAt` | `string` | | 更新时间 | +|   `usageNotes` | `string` | | 使用须知 | +|   `videoMaterialIds` | `string[]` | | 视频素材ID列表 | +|   `videoUrls` | `string[]` | | 视频URL列表 | +|   `viewCount` | `int` | | 浏览量 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/hotel/item/{hotelId} + +**住宿详情** + +获取住宿完整信息，包含素材URL、标签列表、房型列表等。素材ID会自动解析为OSS访问地址。 + +**关联字典**： +- hotel_type：住宿类型（详情显示） +- hotel_star_level：酒店星级（详情显示） +- hotel_facility：酒店设施（详情显示） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `hotelId` | `integer` | | 住宿ID | + +**响应** `统一响应结果«酒店详情VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `酒店详情VO` | | 响应数据 | +|   `address` | `string` | | 详细地址 | +|   `bannerMaterialIds` | `string[]` | | 横幅素材ID列表 | +|   `bannerUrls` | `string[]` | | 横幅图URL列表 | +|   `checkInNotes` | `string` | | 入住须知 | +|   `checkInTime` | `string` | | 入住时间 | +|   `checkOutTime` | `string` | | 退房时间 | +|   `city` | `string` | | 城市 | +|   `contactPerson` | `string` | | 联系人姓名 | +|   `contactPhone` | `string` | | 联系电话 | +|   `coverMaterialId` | `string` | | 封面素材ID | +|   `coverUrl` | `string` | | 封面图URL | +|   `createdAt` | `string` | | 创建时间 | +|   `createdBy` | `string` | | 创建者ID | +|   `description` | `string` | | 酒店描述 | +|   `diamondLevel` | `int` | | 钻级：0-5 | +|   `district` | `string` | | 区县 | +|   `facilities` | `string` | | 设施配置（JSON） | +|   `highlights` | `string` | | 酒店亮点（JSON） | +|   `hotelId` | `string` | | 酒店ID | +|   `hotelType` | `string` | | 住宿类型 | +|   `latitude` | `number` | | 纬度 | +|   `longitude` | `number` | | 经度 | +|   `luggageInfo` | `string` | | 行李服务说明 | +|   `name` | `string` | | 酒店名称 | +|   `parkingInfo` | `string` | | 停车信息 | +|   `province` | `string` | | 省份 | +|   `roomTypeCount` | `int` | | 房型数量 | +|   `shuttleInfo` | `string` | | 接驳服务说明 | +|   `sortOrder` | `int` | | 排序权重 | +|   `starLevel` | `int` | | 星级：1-5 | +|   `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +|   `subtitle` | `string` | | 副标题 | +|   `tags` | `酒店标签VO[]` | | 标签列表 | +|     `createdAt` | `string` | | 创建时间 | +|     `tagColor` | `string` | | 标签颜色（十六进制） | +|     `tagId` | `string` | | 标签ID | +|     `tagName` | `string` | | 标签名称 | +|     `tagType` | `int` | | 标签类型：0=自定义 1=系统 | +|     `useCount` | `int` | | 使用次数 | +|   `updatedAt` | `string` | | 更新时间 | +|   `usageNotes` | `string` | | 使用须知 | +|   `videoMaterialIds` | `string[]` | | 视频素材ID列表 | +|   `videoUrls` | `string[]` | | 视频URL列表 | +|   `viewCount` | `int` | | 浏览量 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/hotel/item/{hotelId} + +**更新住宿** + +更新住宿基本信息。更新不会改变当前状态，已上架的住宿修改后仍保持上架状态。 + +**关联字典**： +- hotel_type：住宿类型（表单选择） +- hotel_star_level：酒店星级（表单选择） +- hotel_facility：酒店设施（表单多选） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `hotelId` | `integer` | | 住宿ID | + +**请求体** `酒店更新请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `address` | `string` | | 详细地址 | +| `bannerMaterialIds` | `string[]` | | 横幅素材ID列表 | +| `checkInNotes` | `string` | | 入住须知 | +| `checkInTime` | `string` | | 入住时间 | +| `checkOutTime` | `string` | | 退房时间 | +| `city` | `string` | | 城市 | +| `contactPerson` | `string` | | 联系人姓名 | +| `contactPhone` | `string` | | 联系电话 | +| `coverMaterialId` | `string` | | 封面素材ID | +| `description` | `string` | | 酒店描述 | +| `diamondLevel` | `int` | | 钻级：0-5 | +| `district` | `string` | | 区县 | +| `facilities` | `string` | | 设施配置（JSON） | +| `highlights` | `string` | | 酒店亮点（JSON） | +| `hotelType` | `string` | | 住宿类型 | +| `latitude` | `number` | | 纬度 | +| `longitude` | `number` | | 经度 | +| `luggageInfo` | `string` | | 行李服务说明 | +| `name` | `string` | | 酒店名称 | +| `parkingInfo` | `string` | | 停车信息 | +| `province` | `string` | | 省份 | +| `shuttleInfo` | `string` | | 接驳服务说明 | +| `sortOrder` | `int` | | 排序权重，值越大越靠前 | +| `starLevel` | `int` | | 星级：1-5 | +| `subtitle` | `string` | | 副标题 | +| `usageNotes` | `string` | | 使用须知 | +| `videoMaterialIds` | `string[]` | | 视频素材ID列表 | + +**响应** `统一响应结果«酒店详情VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `酒店详情VO` | | 响应数据 | +|   `address` | `string` | | 详细地址 | +|   `bannerMaterialIds` | `string[]` | | 横幅素材ID列表 | +|   `bannerUrls` | `string[]` | | 横幅图URL列表 | +|   `checkInNotes` | `string` | | 入住须知 | +|   `checkInTime` | `string` | | 入住时间 | +|   `checkOutTime` | `string` | | 退房时间 | +|   `city` | `string` | | 城市 | +|   `contactPerson` | `string` | | 联系人姓名 | +|   `contactPhone` | `string` | | 联系电话 | +|   `coverMaterialId` | `string` | | 封面素材ID | +|   `coverUrl` | `string` | | 封面图URL | +|   `createdAt` | `string` | | 创建时间 | +|   `createdBy` | `string` | | 创建者ID | +|   `description` | `string` | | 酒店描述 | +|   `diamondLevel` | `int` | | 钻级：0-5 | +|   `district` | `string` | | 区县 | +|   `facilities` | `string` | | 设施配置（JSON） | +|   `highlights` | `string` | | 酒店亮点（JSON） | +|   `hotelId` | `string` | | 酒店ID | +|   `hotelType` | `string` | | 住宿类型 | +|   `latitude` | `number` | | 纬度 | +|   `longitude` | `number` | | 经度 | +|   `luggageInfo` | `string` | | 行李服务说明 | +|   `name` | `string` | | 酒店名称 | +|   `parkingInfo` | `string` | | 停车信息 | +|   `province` | `string` | | 省份 | +|   `roomTypeCount` | `int` | | 房型数量 | +|   `shuttleInfo` | `string` | | 接驳服务说明 | +|   `sortOrder` | `int` | | 排序权重 | +|   `starLevel` | `int` | | 星级：1-5 | +|   `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +|   `subtitle` | `string` | | 副标题 | +|   `tags` | `酒店标签VO[]` | | 标签列表 | +|     `createdAt` | `string` | | 创建时间 | +|     `tagColor` | `string` | | 标签颜色（十六进制） | +|     `tagId` | `string` | | 标签ID | +|     `tagName` | `string` | | 标签名称 | +|     `tagType` | `int` | | 标签类型：0=自定义 1=系统 | +|     `useCount` | `int` | | 使用次数 | +|   `updatedAt` | `string` | | 更新时间 | +|   `usageNotes` | `string` | | 使用须知 | +|   `videoMaterialIds` | `string[]` | | 视频素材ID列表 | +|   `videoUrls` | `string[]` | | 视频URL列表 | +|   `viewCount` | `int` | | 浏览量 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/hotel/item/{hotelId} + +**删除住宿** + +软删除住宿。仅SUPER_ADMIN或创建者可操作。删除住宿会同时删除其下所有房型和价格日历数据。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `hotelId` | `integer` | | 住宿ID | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/hotel/item/{hotelId}/status + +**启用/禁用切换** + +直接修改住宿状态（跳过审批），仅限SUPER_ADMIN使用。状态值：0=草稿，1=上架，2=下架。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `hotelId` | `integer` | | 住宿ID | + +**请求体** `酒店状态变更请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `hotelIds` | `string[]` | | 酒店ID列表（批量操作时使用） | +| `status` | `int` | 是 | 目标状态：0=草稿 1=上架 2=下架 | + +**响应** `统一响应结果«Void»` + +--- + +### `POST` /admin/hotel/item/{hotelId}/submit-approval + +**提交启用/禁用审批** + +向企微OA提交住宿启用/禁用审批。targetStatus=1申请上架，targetStatus=2申请下架。审批通过后自动更新状态。返回企微审批单号spNo。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `hotelId` | `integer` | | 住宿ID | + +**请求体** `酒店审批提交请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `reason` | `string` | 是 | 审批理由 | +| `targetStatus` | `int` | 是 | 目标状态：1=上架 2=下架 | + +**响应** `统一响应结果«Map«string,string»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `object` | | 响应数据 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/hotel/items + +**住宿列表** + +分页查询住宿列表，支持按名称关键词、状态、住宿类型等条件筛选。返回列表摘要信息，按sortOrder倒序+创建时间倒序排列。 + +**关联字典**： +- hotel_type：住宿类型（筛选+列表显示） +- hotel_star_level：酒店星级（筛选+列表显示） +- hotel_facility：酒店设施（列表显示） + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `city` | `string` | | 城市筛选 | 丽江市 | +| `cityKeyword` | `string` | | 城市/区域关键词模糊搜索（匹配城市名、省份、地址） | 海拉尔 | +| `hotelType` | `string` | | 住宿类型筛选 | HOTEL | +| `keyword` | `string` | | 搜索关键词（名称/地址模糊匹配） | 丽江 | +| `page` | `integer(int32)` | | 页码 | 1 | +| `pageSize` | `integer(int32)` | | 每页条数 | 20 | +| `sortBy` | `string` | | 排序字段 | createdAt | +| `sortDir` | `string` | | 排序方向：asc/desc | desc | +| `starLevel` | `integer(int32)` | | 星级筛选 | 5 | +| `status` | `integer(int32)` | | 状态筛选：0=草稿 1=上架 2=下架 | 1 | +| `tagId` | `integer(int64)` | | 标签ID（单个） | | +| `tagIds` | `string` | | 标签ID列表（逗号分隔） | 1,2,3 | + +**响应** `统一响应结果«分页结果«酒店列表VO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«酒店列表VO»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `酒店列表VO[]` | | 数据列表 | +|     `approvalNo` | `string` | | 审批单号 | +|     `city` | `string` | | 城市 | +|     `coverUrl` | `string` | | 封面图URL | +|     `createdAt` | `string` | | 创建时间 | +|     `diamondLevel` | `int` | | 钻级：0-5 | +|     `hotelId` | `string` | | 酒店ID | +|     `hotelType` | `string` | | 住宿类型 | +|     `name` | `string` | | 酒店名称 | +|     `pendingStatus` | `int` | | 待审批目标状态 | +|     `roomTypeCount` | `int` | | 房型数量 | +|     `sortOrder` | `int` | | 排序权重 | +|     `starLevel` | `int` | | 星级：1-5 | +|     `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +|     `subtitle` | `string` | | 副标题 | +|     `tags` | `酒店标签VO[]` | | 标签列表 | +|     `viewCount` | `int` | | 浏览量 | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/hotel/items/all-simple + +**所有启用的住宿（不分页，仅ID和名称）** + +返回所有已上架(status=1)的住宿简要信息，用于下拉选择框。每项只含hotelId和name字段。适用于房型管理时选择所属住宿、产品编排时绑定住宿资源等场景。 + +**响应** `统一响应结果«List«Map«string,object»»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `Map«string,object»[]` | | 响应数据 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/hotel/items/batch + +**批量删除** + +批量软删除多个住宿及其关联的房型和价格日历。仅SUPER_ADMIN或创建者可操作。 + +**请求体** `酒店批量删除请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `hotelIds` | `string[]` | 是 | 酒店ID列表 | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/hotel/items/batch/status + +**批量启用/禁用** + +批量修改多个住宿的状态，跳过审批流程。hotelIds为住宿ID列表（字符串格式）。 + +**请求体** `酒店状态变更请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `hotelIds` | `string[]` | | 酒店ID列表（批量操作时使用） | +| `status` | `int` | 是 | 目标状态：0=草稿 1=上架 2=下架 | + +**响应** `统一响应结果«Void»` + +--- + +## 增值服务管理 + +### `POST` /admin/service/item + +**创建增值服务** + +新建增值服务项目（如保险、签证代办、接送机等），初始状态为草稿(status=0)。支持免费(isPaid=false)和付费两种模式，付费服务有独立的价格日历。需走企微审批上架。 + +**关联字典**： +- service_category：服务分类（表单选择） +- billing_type_service：服务计费方式（表单选择） +- service_unit：服务计量单位（表单选择） + +**请求体** `服务项创建请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `address` | `string` | | 详细地址 | +| `advanceBookingHours` | `int` | | 提前预订时间（小时） | +| `bannerMaterialIds` | `string[]` | | 横幅素材ID列表 | +| `basePrice` | `number` | | 基础价格（元） | +| `billingType` | `string` | | 计费方式 | +| `cancellationPolicy` | `string` | | 取消政策说明 | +| `capacityMax` | `int` | | 最多服务人数 | +| `capacityMin` | `int` | | 最少服务人数 | +| `categoryCode` | `string` | 是 | 分类编码 | +| `city` | `string` | | 城市 | +| `contactPhone` | `string` | | 联系电话 | +| `coverMaterialId` | `string` | | 封面素材ID | +| `description` | `string` | | 服务描述 | +| `durationHours` | `number` | | 服务时长（小时） | +| `equipmentList` | `string` | | 设备清单（JSON） | +| `freeCancelHours` | `int` | | 免费取消期限（小时） | +| `highlights` | `string` | | 服务亮点 | +| `includedItems` | `string` | | 包含项目说明 | +| `instantConfirm` | `int` | | 是否即时确认：0=否 1=是 | +| `isPaid` | `int` | 是 | 是否收费：0=免费 1=收费 | +| `languageSupport` | `string` | | 语言支持 | +| `latitude` | `number` | | 纬度 | +| `longitude` | `number` | | 经度 | +| `name` | `string` | 是 | 服务名称 | +| `priceExcludes` | `string` | | 价格不包含内容 | +| `priceIncludes` | `string` | | 价格包含内容 | +| `province` | `string` | | 省份 | +| `serviceHours` | `string` | | 服务时段 | +| `serviceProcess` | `string` | | 服务流程说明 | +| `sortOrder` | `int` | | 排序权重，值越大越靠前 | +| `staffCount` | `int` | | 服务人员数量 | +| `subtitle` | `string` | | 副标题 | +| `unit` | `string` | | 计价单位 | +| `usageNotes` | `string` | | 使用须知 | +| `vehicleType` | `string` | | 配套车型 | +| `videoMaterialIds` | `string[]` | | 视频素材ID列表 | + +**响应** `统一响应结果«服务项详情VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `服务项详情VO` | | 响应数据 | +|   `address` | `string` | | 详细地址 | +|   `advanceBookingHours` | `int` | | 提前预订时间（小时） | +|   `bannerMaterialIds` | `string[]` | | 横幅素材ID列表 | +|   `bannerUrls` | `string[]` | | 横幅图URL列表 | +|   `basePrice` | `number` | | 基础价格（元） | +|   `billingType` | `string` | | 计费方式 | +|   `cancellationPolicy` | `string` | | 取消政策说明 | +|   `capacityMax` | `int` | | 最多服务人数 | +|   `capacityMin` | `int` | | 最少服务人数 | +|   `categoryCode` | `string` | | 分类编码 | +|   `city` | `string` | | 城市 | +|   `contactPhone` | `string` | | 联系电话 | +|   `coverMaterialId` | `string` | | 封面素材ID | +|   `coverUrl` | `string` | | 封面图URL | +|   `createdAt` | `string` | | 创建时间 | +|   `createdBy` | `string` | | 创建者ID | +|   `description` | `string` | | 服务描述 | +|   `durationHours` | `number` | | 服务时长（小时） | +|   `equipmentList` | `string` | | 设备清单（JSON） | +|   `freeCancelHours` | `int` | | 免费取消期限（小时） | +|   `highlights` | `string` | | 服务亮点 | +|   `includedItems` | `string` | | 包含项目说明 | +|   `instantConfirm` | `int` | | 是否即时确认：0=否 1=是 | +|   `isPaid` | `int` | | 是否收费：0=免费 1=收费 | +|   `languageSupport` | `string` | | 语言支持 | +|   `latitude` | `number` | | 纬度 | +|   `longitude` | `number` | | 经度 | +|   `name` | `string` | | 服务名称 | +|   `priceExcludes` | `string` | | 价格不包含内容 | +|   `priceIncludes` | `string` | | 价格包含内容 | +|   `province` | `string` | | 省份 | +|   `serviceHours` | `string` | | 服务时段 | +|   `serviceId` | `string` | | 服务项ID | +|   `serviceProcess` | `string` | | 服务流程说明 | +|   `sortOrder` | `int` | | 排序权重 | +|   `staffCount` | `int` | | 服务人员数量 | +|   `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +|   `subtitle` | `string` | | 副标题 | +|   `tags` | `服务标签VO[]` | | 标签列表 | +|     `createdAt` | `string` | | 创建时间 | +|     `tagColor` | `string` | | 标签颜色（十六进制） | +|     `tagId` | `string` | | 标签ID | +|     `tagName` | `string` | | 标签名称 | +|     `tagType` | `int` | | 标签类型：0=自定义 1=系统 | +|     `useCount` | `int` | | 使用次数 | +|   `unit` | `string` | | 计价单位 | +|   `updatedAt` | `string` | | 更新时间 | +|   `usageNotes` | `string` | | 使用须知 | +|   `vehicleType` | `string` | | 配套车型 | +|   `videoMaterialIds` | `string[]` | | 视频素材ID列表 | +|   `videoUrls` | `string[]` | | 视频URL列表 | +|   `viewCount` | `int` | | 浏览量 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/service/item/{serviceId} + +**增值服务详情** + +获取增值服务完整信息，包含素材URL、标签、计费方式等。 + +**关联字典**： +- service_category：服务分类（详情显示） +- billing_type_service：服务计费方式（详情显示） +- service_unit：服务计量单位（详情显示） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `serviceId` | `integer` | | 服务ID | + +**响应** `统一响应结果«服务项详情VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `服务项详情VO` | | 响应数据 | +|   `address` | `string` | | 详细地址 | +|   `advanceBookingHours` | `int` | | 提前预订时间（小时） | +|   `bannerMaterialIds` | `string[]` | | 横幅素材ID列表 | +|   `bannerUrls` | `string[]` | | 横幅图URL列表 | +|   `basePrice` | `number` | | 基础价格（元） | +|   `billingType` | `string` | | 计费方式 | +|   `cancellationPolicy` | `string` | | 取消政策说明 | +|   `capacityMax` | `int` | | 最多服务人数 | +|   `capacityMin` | `int` | | 最少服务人数 | +|   `categoryCode` | `string` | | 分类编码 | +|   `city` | `string` | | 城市 | +|   `contactPhone` | `string` | | 联系电话 | +|   `coverMaterialId` | `string` | | 封面素材ID | +|   `coverUrl` | `string` | | 封面图URL | +|   `createdAt` | `string` | | 创建时间 | +|   `createdBy` | `string` | | 创建者ID | +|   `description` | `string` | | 服务描述 | +|   `durationHours` | `number` | | 服务时长（小时） | +|   `equipmentList` | `string` | | 设备清单（JSON） | +|   `freeCancelHours` | `int` | | 免费取消期限（小时） | +|   `highlights` | `string` | | 服务亮点 | +|   `includedItems` | `string` | | 包含项目说明 | +|   `instantConfirm` | `int` | | 是否即时确认：0=否 1=是 | +|   `isPaid` | `int` | | 是否收费：0=免费 1=收费 | +|   `languageSupport` | `string` | | 语言支持 | +|   `latitude` | `number` | | 纬度 | +|   `longitude` | `number` | | 经度 | +|   `name` | `string` | | 服务名称 | +|   `priceExcludes` | `string` | | 价格不包含内容 | +|   `priceIncludes` | `string` | | 价格包含内容 | +|   `province` | `string` | | 省份 | +|   `serviceHours` | `string` | | 服务时段 | +|   `serviceId` | `string` | | 服务项ID | +|   `serviceProcess` | `string` | | 服务流程说明 | +|   `sortOrder` | `int` | | 排序权重 | +|   `staffCount` | `int` | | 服务人员数量 | +|   `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +|   `subtitle` | `string` | | 副标题 | +|   `tags` | `服务标签VO[]` | | 标签列表 | +|     `createdAt` | `string` | | 创建时间 | +|     `tagColor` | `string` | | 标签颜色（十六进制） | +|     `tagId` | `string` | | 标签ID | +|     `tagName` | `string` | | 标签名称 | +|     `tagType` | `int` | | 标签类型：0=自定义 1=系统 | +|     `useCount` | `int` | | 使用次数 | +|   `unit` | `string` | | 计价单位 | +|   `updatedAt` | `string` | | 更新时间 | +|   `usageNotes` | `string` | | 使用须知 | +|   `vehicleType` | `string` | | 配套车型 | +|   `videoMaterialIds` | `string[]` | | 视频素材ID列表 | +|   `videoUrls` | `string[]` | | 视频URL列表 | +|   `viewCount` | `int` | | 浏览量 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/service/item/{serviceId} + +**更新增值服务** + +更新增值服务基本信息，不改变当前状态。 + +**关联字典**： +- service_category：服务分类（表单选择） +- billing_type_service：服务计费方式（表单选择） +- service_unit：服务计量单位（表单选择） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `serviceId` | `integer` | | 服务ID | + +**请求体** `服务项更新请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `address` | `string` | | 详细地址 | +| `advanceBookingHours` | `int` | | 提前预订时间（小时） | +| `bannerMaterialIds` | `string[]` | | 横幅素材ID列表 | +| `basePrice` | `number` | | 基础价格（元） | +| `billingType` | `string` | | 计费方式 | +| `cancellationPolicy` | `string` | | 取消政策说明 | +| `capacityMax` | `int` | | 最多服务人数 | +| `capacityMin` | `int` | | 最少服务人数 | +| `categoryCode` | `string` | | 分类编码 | +| `city` | `string` | | 城市 | +| `contactPhone` | `string` | | 联系电话 | +| `coverMaterialId` | `string` | | 封面素材ID | +| `description` | `string` | | 服务描述 | +| `durationHours` | `number` | | 服务时长（小时） | +| `equipmentList` | `string` | | 设备清单（JSON） | +| `freeCancelHours` | `int` | | 免费取消期限（小时） | +| `highlights` | `string` | | 服务亮点 | +| `includedItems` | `string` | | 包含项目说明 | +| `instantConfirm` | `int` | | 是否即时确认：0=否 1=是 | +| `isPaid` | `int` | | 是否收费：0=免费 1=收费 | +| `languageSupport` | `string` | | 语言支持 | +| `latitude` | `number` | | 纬度 | +| `longitude` | `number` | | 经度 | +| `name` | `string` | | 服务名称 | +| `priceExcludes` | `string` | | 价格不包含内容 | +| `priceIncludes` | `string` | | 价格包含内容 | +| `province` | `string` | | 省份 | +| `serviceHours` | `string` | | 服务时段 | +| `serviceProcess` | `string` | | 服务流程说明 | +| `sortOrder` | `int` | | 排序权重，值越大越靠前 | +| `staffCount` | `int` | | 服务人员数量 | +| `subtitle` | `string` | | 副标题 | +| `unit` | `string` | | 计价单位 | +| `usageNotes` | `string` | | 使用须知 | +| `vehicleType` | `string` | | 配套车型 | +| `videoMaterialIds` | `string[]` | | 视频素材ID列表 | + +**响应** `统一响应结果«服务项详情VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `服务项详情VO` | | 响应数据 | +|   `address` | `string` | | 详细地址 | +|   `advanceBookingHours` | `int` | | 提前预订时间（小时） | +|   `bannerMaterialIds` | `string[]` | | 横幅素材ID列表 | +|   `bannerUrls` | `string[]` | | 横幅图URL列表 | +|   `basePrice` | `number` | | 基础价格（元） | +|   `billingType` | `string` | | 计费方式 | +|   `cancellationPolicy` | `string` | | 取消政策说明 | +|   `capacityMax` | `int` | | 最多服务人数 | +|   `capacityMin` | `int` | | 最少服务人数 | +|   `categoryCode` | `string` | | 分类编码 | +|   `city` | `string` | | 城市 | +|   `contactPhone` | `string` | | 联系电话 | +|   `coverMaterialId` | `string` | | 封面素材ID | +|   `coverUrl` | `string` | | 封面图URL | +|   `createdAt` | `string` | | 创建时间 | +|   `createdBy` | `string` | | 创建者ID | +|   `description` | `string` | | 服务描述 | +|   `durationHours` | `number` | | 服务时长（小时） | +|   `equipmentList` | `string` | | 设备清单（JSON） | +|   `freeCancelHours` | `int` | | 免费取消期限（小时） | +|   `highlights` | `string` | | 服务亮点 | +|   `includedItems` | `string` | | 包含项目说明 | +|   `instantConfirm` | `int` | | 是否即时确认：0=否 1=是 | +|   `isPaid` | `int` | | 是否收费：0=免费 1=收费 | +|   `languageSupport` | `string` | | 语言支持 | +|   `latitude` | `number` | | 纬度 | +|   `longitude` | `number` | | 经度 | +|   `name` | `string` | | 服务名称 | +|   `priceExcludes` | `string` | | 价格不包含内容 | +|   `priceIncludes` | `string` | | 价格包含内容 | +|   `province` | `string` | | 省份 | +|   `serviceHours` | `string` | | 服务时段 | +|   `serviceId` | `string` | | 服务项ID | +|   `serviceProcess` | `string` | | 服务流程说明 | +|   `sortOrder` | `int` | | 排序权重 | +|   `staffCount` | `int` | | 服务人员数量 | +|   `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +|   `subtitle` | `string` | | 副标题 | +|   `tags` | `服务标签VO[]` | | 标签列表 | +|     `createdAt` | `string` | | 创建时间 | +|     `tagColor` | `string` | | 标签颜色（十六进制） | +|     `tagId` | `string` | | 标签ID | +|     `tagName` | `string` | | 标签名称 | +|     `tagType` | `int` | | 标签类型：0=自定义 1=系统 | +|     `useCount` | `int` | | 使用次数 | +|   `unit` | `string` | | 计价单位 | +|   `updatedAt` | `string` | | 更新时间 | +|   `usageNotes` | `string` | | 使用须知 | +|   `vehicleType` | `string` | | 配套车型 | +|   `videoMaterialIds` | `string[]` | | 视频素材ID列表 | +|   `videoUrls` | `string[]` | | 视频URL列表 | +|   `viewCount` | `int` | | 浏览量 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/service/item/{serviceId} + +**删除增值服务** + +软删除增值服务。仅SUPER_ADMIN或创建者可操作。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `serviceId` | `integer` | | 服务ID | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/service/item/{serviceId}/status + +**启用/禁用切换** + +直接修改状态（跳过审批），仅限SUPER_ADMIN。状态值：0=草稿，1=上架，2=下架。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `serviceId` | `integer` | | 服务ID | + +**请求体** `服务项状态变更请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `serviceIds` | `string[]` | | 服务ID列表（批量操作时使用） | +| `status` | `int` | 是 | 目标状态：0=草稿 1=上架 2=下架 | + +**响应** `统一响应结果«Void»` + +--- + +### `POST` /admin/service/item/{serviceId}/submit-approval + +**提交启用/禁用审批** + +向企微OA提交审批。targetStatus=1申请上架，targetStatus=2申请下架。返回审批单号spNo。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `serviceId` | `integer` | | 服务ID | + +**请求体** `服务项审批提交请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `reason` | `string` | 是 | 审批理由 | +| `targetStatus` | `int` | 是 | 目标状态：1=上架 2=下架 | + +**响应** `统一响应结果«Map«string,string»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `object` | | 响应数据 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/service/items + +**增值服务列表** + +分页查询增值服务列表，支持按名称、状态、分类等条件筛选。 + +**关联字典**： +- service_category：服务分类（筛选+列表显示） +- billing_type_service：服务计费方式（列表显示） +- service_unit：服务计量单位（列表显示） + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `billingType` | `string` | | 计费方式筛选 | PER_DAY | +| `categoryCode` | `string` | | 分类编码筛选 | GUIDE | +| `city` | `string` | | 城市筛选 | 丽江市 | +| `cityKeyword` | `string` | | 城市/区域关键词模糊搜索（匹配城市名、省份、地址） | 海拉尔 | +| `instantConfirm` | `integer(int32)` | | 是否即时确认筛选：0=否 1=是 | 1 | +| `isPaid` | `integer(int32)` | | 是否收费筛选：0=免费 1=收费 | 1 | +| `keyword` | `string` | | 搜索关键词（名称模糊匹配） | 导游 | +| `maxPrice` | `number` | | 最高价格筛选 | 1000.0 | +| `minPrice` | `number` | | 最低价格筛选 | 100.0 | +| `page` | `integer(int32)` | | 页码 | 1 | +| `pageSize` | `integer(int32)` | | 每页条数 | 20 | +| `sortBy` | `string` | | 排序字段 | createdAt | +| `sortDir` | `string` | | 排序方向：asc/desc | desc | +| `status` | `integer(int32)` | | 状态筛选：0=草稿 1=上架 2=下架 | 1 | +| `tagId` | `integer(int64)` | | 标签ID（单个） | | +| `tagIds` | `string` | | 标签ID列表（逗号分隔） | 1,2,3 | +| `vehicleType` | `string` | | 配套车型筛选 | 商务车 | + +**响应** `统一响应结果«分页结果«服务项列表VO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«服务项列表VO»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `服务项列表VO[]` | | 数据列表 | +|     `approvalNo` | `string` | | 审批单号 | +|     `basePrice` | `number` | | 基础价格（元） | +|     `billingType` | `string` | | 计费方式 | +|     `categoryCode` | `string` | | 分类编码 | +|     `city` | `string` | | 城市 | +|     `coverUrl` | `string` | | 封面图URL | +|     `createdAt` | `string` | | 创建时间 | +|     `durationHours` | `number` | | 服务时长（小时） | +|     `highlights` | `string` | | 服务亮点 | +|     `instantConfirm` | `int` | | 是否即时确认：0=否 1=是 | +|     `isPaid` | `int` | | 是否收费：0=免费 1=收费 | +|     `latitude` | `number` | | 纬度 | +|     `longitude` | `number` | | 经度 | +|     `name` | `string` | | 服务名称 | +|     `pendingStatus` | `int` | | 待审批目标状态 | +|     `serviceId` | `string` | | 服务项ID | +|     `sortOrder` | `int` | | 排序权重 | +|     `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +|     `subtitle` | `string` | | 副标题 | +|     `tags` | `服务标签VO[]` | | 标签列表 | +|     `unit` | `string` | | 计价单位 | +|     `vehicleType` | `string` | | 配套车型 | +|     `viewCount` | `int` | | 浏览量 | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/service/items/batch + +**批量删除** + +批量软删除多个增值服务。仅SUPER_ADMIN或创建者可操作。 + +**请求体** `服务项批量删除请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `serviceIds` | `string[]` | 是 | 服务ID列表 | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/service/items/batch/status + +**批量启用/禁用** + +批量修改多个增值服务的状态，跳过审批流程。 + +**请求体** `服务项状态变更请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `serviceIds` | `string[]` | | 服务ID列表（批量操作时使用） | +| `status` | `int` | 是 | 目标状态：0=草稿 1=上架 2=下架 | + +**响应** `统一响应结果«Void»` + +--- + +## 备品标签管理 + +### `PUT` /admin/supplies/item/{suppliesId}/tags + +**更新备品标签** + +全量替换指定备品的标签列表。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `suppliesId` | `integer` | | 备品ID | + +**请求体** `备品标签更新请求_1` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagIds` | `string[]` | | 标签ID列表 | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/supplies/items/batch/tags + +**批量打标签** + +对多个备品批量添加/移除标签。增量操作。 + +**请求体** `备品批量标签操作请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `addTagIds` | `string[]` | | 要添加的标签ID列表 | +| `removeTagIds` | `string[]` | | 要移除的标签ID列表 | +| `suppliesIds` | `string[]` | 是 | 备品ID列表 | + +**响应** `统一响应结果«Void»` + +--- + +### `POST` /admin/supplies/tag + +**创建管理标签** + +创建预设标签，标签名不可重复。 + +**请求体** `备品标签创建请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagColor` | `string` | | 标签颜色（十六进制） | +| `tagName` | `string` | 是 | 标签名称 | + +**响应** `统一响应结果«备品标签视图»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `备品标签视图` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `tagColor` | `string` | | 标签颜色 | +|   `tagId` | `string` | | 标签ID | +|   `tagName` | `string` | | 标签名称 | +|   `tagType` | `int` | | 标签类型：1=系统标签 2=自定义标签 | +|   `useCount` | `int` | | 使用次数 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/supplies/tag/adhoc + +**解析自定义标签** + +按名称查找或自动创建标签。 + +**请求体** `备品标签创建请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagColor` | `string` | | 标签颜色（十六进制） | +| `tagName` | `string` | 是 | 标签名称 | + +**响应** `统一响应结果«备品标签视图»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `备品标签视图` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `tagColor` | `string` | | 标签颜色 | +|   `tagId` | `string` | | 标签ID | +|   `tagName` | `string` | | 标签名称 | +|   `tagType` | `int` | | 标签类型：1=系统标签 2=自定义标签 | +|   `useCount` | `int` | | 使用次数 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/supplies/tag/{tagId} + +**编辑标签** + +修改标签名称或颜色，所有关联备品自动生效。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagId` | `integer` | | 标签ID | + +**请求体** `备品标签更新请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagColor` | `string` | | 标签颜色（十六进制） | +| `tagName` | `string` | | 标签名称 | + +**响应** `统一响应结果«备品标签视图»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `备品标签视图` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `tagColor` | `string` | | 标签颜色 | +|   `tagId` | `string` | | 标签ID | +|   `tagName` | `string` | | 标签名称 | +|   `tagType` | `int` | | 标签类型：1=系统标签 2=自定义标签 | +|   `useCount` | `int` | | 使用次数 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/supplies/tag/{tagId} + +**删除标签** + +删除标签并解除所有备品与该标签的关联。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagId` | `integer` | | 标签ID | + +**响应** `统一响应结果«Void»` + +--- + +### `GET` /admin/supplies/tags + +**获取管理标签列表（分页）** + +分页查询备品标签库，支持按关键词搜索。 + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `keyword` | `string` | | 关键词 | | +| `page` | `integer(int32)` | | 页码 | | +| `pageSize` | `integer(int32)` | | 每页条数 | | + +**响应** `统一响应结果«分页结果«备品标签视图»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«备品标签视图»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `备品标签视图[]` | | 数据列表 | +|     `createdAt` | `string` | | 创建时间 | +|     `tagColor` | `string` | | 标签颜色 | +|     `tagId` | `string` | | 标签ID | +|     `tagName` | `string` | | 标签名称 | +|     `tagType` | `int` | | 标签类型：1=系统标签 2=自定义标签 | +|     `useCount` | `int` | | 使用次数 | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/supplies/tags/all + +**获取全部标签** + +不分页返回所有标签，用于备品编辑时的标签选择下拉。 + +**响应** `统一响应结果«List«备品标签视图»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `备品标签视图[]` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `tagColor` | `string` | | 标签颜色 | +|   `tagId` | `string` | | 标签ID | +|   `tagName` | `string` | | 标签名称 | +|   `tagType` | `int` | | 标签类型：1=系统标签 2=自定义标签 | +|   `useCount` | `int` | | 使用次数 | +| `message` | `string` | | 响应消息 | + +--- + +## 备品管理 + +### `POST` /admin/supplies/item + +**创建备品** + +新建备品资源（帐篷、睡袋、炊具等物资），初始状态为草稿(status=0)。需走企微审批上架。支持按件(PER_ITEM)和按人(PER_PERSON)计费。 + +**关联字典**： +- supplies_category：备品分类（表单选择） +- billing_type：计费方式（表单选择） + +**请求体** `备品创建请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `bannerMaterialIds` | `string[]` | | 轮播图素材ID列表 | +| `basePrice` | `number` | 是 | 基础单价（元） | +| `billingType` | `string` | 是 | 计费方式：PER_ITEM=按件 PER_DAY=按天 | +| `brand` | `string` | | 品牌 | +| `categoryCode` | `string` | 是 | 分类编码 | +| `coverMaterialId` | `string` | | 封面素材ID | +| `description` | `string` | | 备品描述 | +| `featureIntro` | `string` | | 图文详情（JSON格式） | +| `highlights` | `string` | | 亮点摘要 | +| `includes` | `string[]` | | 包含物品清单 | +| `model` | `string` | | 型号 | +| `name` | `string` | 是 | 备品名称 | +| `recommended` | `int` | | 是否推荐：0=否 1=是 | +| `sizeOptions` | `string[]` | | 可选尺码列表 | +| `sortOrder` | `int` | | 排序权重（数字越大越靠前） | +| `specifications` | `string` | | 规格参数（JSON格式） | +| `subtitle` | `string` | | 副标题 | +| `unit` | `string` | | 计量单位 | +| `usageNotes` | `string` | | 使用注意事项 | +| `videoMaterialIds` | `string[]` | | 视频素材ID列表 | +| `weight` | `number` | | 重量（kg） | + +**响应** `统一响应结果«备品详情视图»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `备品详情视图` | | 响应数据 | +|   `bannerMaterialIds` | `string[]` | | 轮播图素材ID列表 | +|   `bannerUrls` | `string[]` | | 轮播图URL列表 | +|   `basePrice` | `number` | | 基础单价（元） | +|   `billingType` | `string` | | 计费方式编码 | +|   `billingTypeName` | `string` | | 计费方式名称 | +|   `brand` | `string` | | 品牌 | +|   `categoryCode` | `string` | | 分类编码 | +|   `categoryName` | `string` | | 分类名称 | +|   `coverMaterialId` | `string` | | 封面素材ID | +|   `coverUrl` | `string` | | 封面图URL | +|   `createdAt` | `string` | | 创建时间 | +|   `createdBy` | `string` | | 创建人ID | +|   `createdByName` | `string` | | 创建人姓名 | +|   `description` | `string` | | 备品描述 | +|   `featureIntro` | `string` | | 图文详情（JSON格式） | +|   `highlights` | `string` | | 亮点摘要 | +|   `includes` | `string[]` | | 包含物品清单 | +|   `model` | `string` | | 型号 | +|   `name` | `string` | | 备品名称 | +|   `recommended` | `int` | | 是否推荐：0=否 1=是 | +|   `sizeOptions` | `string[]` | | 可选尺码列表 | +|   `sortOrder` | `int` | | 排序权重 | +|   `specifications` | `string` | | 规格参数（JSON格式） | +|   `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +|   `subtitle` | `string` | | 副标题 | +|   `suppliesId` | `string` | | 备品ID | +|   `tags` | `备品标签视图[]` | | 标签列表 | +|     `createdAt` | `string` | | 创建时间 | +|     `tagColor` | `string` | | 标签颜色 | +|     `tagId` | `string` | | 标签ID | +|     `tagName` | `string` | | 标签名称 | +|     `tagType` | `int` | | 标签类型：1=系统标签 2=自定义标签 | +|     `useCount` | `int` | | 使用次数 | +|   `unit` | `string` | | 计量单位 | +|   `updatedAt` | `string` | | 更新时间 | +|   `usageNotes` | `string` | | 使用注意事项 | +|   `videoMaterialIds` | `string[]` | | 视频素材ID列表 | +|   `videoUrls` | `string[]` | | 视频URL列表 | +|   `viewCount` | `int` | | 浏览量 | +|   `weight` | `number` | | 重量（kg） | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/supplies/item/{suppliesId} + +**备品详情** + +获取备品完整信息，包含素材URL、标签等。 + +**关联字典**： +- supplies_category：备品分类（详情显示） +- billing_type：计费方式（详情显示） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `suppliesId` | `integer` | | 备品ID | + +**响应** `统一响应结果«备品详情视图»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `备品详情视图` | | 响应数据 | +|   `bannerMaterialIds` | `string[]` | | 轮播图素材ID列表 | +|   `bannerUrls` | `string[]` | | 轮播图URL列表 | +|   `basePrice` | `number` | | 基础单价（元） | +|   `billingType` | `string` | | 计费方式编码 | +|   `billingTypeName` | `string` | | 计费方式名称 | +|   `brand` | `string` | | 品牌 | +|   `categoryCode` | `string` | | 分类编码 | +|   `categoryName` | `string` | | 分类名称 | +|   `coverMaterialId` | `string` | | 封面素材ID | +|   `coverUrl` | `string` | | 封面图URL | +|   `createdAt` | `string` | | 创建时间 | +|   `createdBy` | `string` | | 创建人ID | +|   `createdByName` | `string` | | 创建人姓名 | +|   `description` | `string` | | 备品描述 | +|   `featureIntro` | `string` | | 图文详情（JSON格式） | +|   `highlights` | `string` | | 亮点摘要 | +|   `includes` | `string[]` | | 包含物品清单 | +|   `model` | `string` | | 型号 | +|   `name` | `string` | | 备品名称 | +|   `recommended` | `int` | | 是否推荐：0=否 1=是 | +|   `sizeOptions` | `string[]` | | 可选尺码列表 | +|   `sortOrder` | `int` | | 排序权重 | +|   `specifications` | `string` | | 规格参数（JSON格式） | +|   `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +|   `subtitle` | `string` | | 副标题 | +|   `suppliesId` | `string` | | 备品ID | +|   `tags` | `备品标签视图[]` | | 标签列表 | +|     `createdAt` | `string` | | 创建时间 | +|     `tagColor` | `string` | | 标签颜色 | +|     `tagId` | `string` | | 标签ID | +|     `tagName` | `string` | | 标签名称 | +|     `tagType` | `int` | | 标签类型：1=系统标签 2=自定义标签 | +|     `useCount` | `int` | | 使用次数 | +|   `unit` | `string` | | 计量单位 | +|   `updatedAt` | `string` | | 更新时间 | +|   `usageNotes` | `string` | | 使用注意事项 | +|   `videoMaterialIds` | `string[]` | | 视频素材ID列表 | +|   `videoUrls` | `string[]` | | 视频URL列表 | +|   `viewCount` | `int` | | 浏览量 | +|   `weight` | `number` | | 重量（kg） | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/supplies/item/{suppliesId} + +**更新备品** + +更新备品基本信息，不改变当前状态。 + +**关联字典**： +- supplies_category：备品分类（表单选择） +- billing_type：计费方式（表单选择） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `suppliesId` | `integer` | | 备品ID | + +**请求体** `备品更新请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `bannerMaterialIds` | `string[]` | | 轮播图素材ID列表 | +| `basePrice` | `number` | | 基础单价（元） | +| `billingType` | `string` | | 计费方式：PER_ITEM=按件 PER_DAY=按天 | +| `brand` | `string` | | 品牌 | +| `categoryCode` | `string` | | 分类编码 | +| `coverMaterialId` | `string` | | 封面素材ID | +| `description` | `string` | | 备品描述 | +| `featureIntro` | `string` | | 图文详情（JSON格式） | +| `highlights` | `string` | | 亮点摘要 | +| `includes` | `string[]` | | 包含物品清单 | +| `model` | `string` | | 型号 | +| `name` | `string` | | 备品名称 | +| `recommended` | `int` | | 是否推荐：0=否 1=是 | +| `sizeOptions` | `string[]` | | 可选尺码列表 | +| `sortOrder` | `int` | | 排序权重（数字越大越靠前） | +| `specifications` | `string` | | 规格参数（JSON格式） | +| `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +| `subtitle` | `string` | | 副标题 | +| `unit` | `string` | | 计量单位 | +| `usageNotes` | `string` | | 使用注意事项 | +| `videoMaterialIds` | `string[]` | | 视频素材ID列表 | +| `weight` | `number` | | 重量（kg） | + +**响应** `统一响应结果«备品详情视图»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `备品详情视图` | | 响应数据 | +|   `bannerMaterialIds` | `string[]` | | 轮播图素材ID列表 | +|   `bannerUrls` | `string[]` | | 轮播图URL列表 | +|   `basePrice` | `number` | | 基础单价（元） | +|   `billingType` | `string` | | 计费方式编码 | +|   `billingTypeName` | `string` | | 计费方式名称 | +|   `brand` | `string` | | 品牌 | +|   `categoryCode` | `string` | | 分类编码 | +|   `categoryName` | `string` | | 分类名称 | +|   `coverMaterialId` | `string` | | 封面素材ID | +|   `coverUrl` | `string` | | 封面图URL | +|   `createdAt` | `string` | | 创建时间 | +|   `createdBy` | `string` | | 创建人ID | +|   `createdByName` | `string` | | 创建人姓名 | +|   `description` | `string` | | 备品描述 | +|   `featureIntro` | `string` | | 图文详情（JSON格式） | +|   `highlights` | `string` | | 亮点摘要 | +|   `includes` | `string[]` | | 包含物品清单 | +|   `model` | `string` | | 型号 | +|   `name` | `string` | | 备品名称 | +|   `recommended` | `int` | | 是否推荐：0=否 1=是 | +|   `sizeOptions` | `string[]` | | 可选尺码列表 | +|   `sortOrder` | `int` | | 排序权重 | +|   `specifications` | `string` | | 规格参数（JSON格式） | +|   `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +|   `subtitle` | `string` | | 副标题 | +|   `suppliesId` | `string` | | 备品ID | +|   `tags` | `备品标签视图[]` | | 标签列表 | +|     `createdAt` | `string` | | 创建时间 | +|     `tagColor` | `string` | | 标签颜色 | +|     `tagId` | `string` | | 标签ID | +|     `tagName` | `string` | | 标签名称 | +|     `tagType` | `int` | | 标签类型：1=系统标签 2=自定义标签 | +|     `useCount` | `int` | | 使用次数 | +|   `unit` | `string` | | 计量单位 | +|   `updatedAt` | `string` | | 更新时间 | +|   `usageNotes` | `string` | | 使用注意事项 | +|   `videoMaterialIds` | `string[]` | | 视频素材ID列表 | +|   `videoUrls` | `string[]` | | 视频URL列表 | +|   `viewCount` | `int` | | 浏览量 | +|   `weight` | `number` | | 重量（kg） | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/supplies/item/{suppliesId} + +**删除备品** + +软删除备品。仅SUPER_ADMIN或创建者可操作。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `suppliesId` | `integer` | | 备品ID | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/supplies/item/{suppliesId}/status + +**上下架切换** + +直接修改状态（跳过审批），仅限SUPER_ADMIN。状态值：0=草稿，1=上架，2=下架。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `suppliesId` | `integer` | | 备品ID | + +**请求体** `备品状态变更请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `status` | `int` | 是 | 目标状态：0=草稿 1=上架 2=下架 | +| `suppliesIds` | `string[]` | | 备品ID列表（批量操作） | + +**响应** `统一响应结果«Void»` + +--- + +### `POST` /admin/supplies/item/{suppliesId}/submit-approval + +**提交启用/禁用审批** + +向企微OA提交审批。targetStatus=1申请上架，targetStatus=2申请下架。返回审批单号spNo。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `suppliesId` | `integer` | | 备品ID | + +**请求体** `备品审批提交请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `reason` | `string` | 是 | 审批理由 | +| `targetStatus` | `int` | 是 | 目标状态：1=上架 2=下架 | + +**响应** `统一响应结果«Map«string,string»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `object` | | 响应数据 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/supplies/items + +**备品列表** + +分页查询备品列表，支持按名称、状态、分类等条件筛选。 + +**关联字典**： +- supplies_category：备品分类（筛选+列表显示） +- billing_type：计费方式（列表显示） + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `billingType` | `string` | | 计费方式：PER_ITEM=按件 PER_DAY=按天 | PER_ITEM | +| `categoryCode` | `string` | | 分类编码 | OUTDOOR_GEAR | +| `keyword` | `string` | | 搜索关键词（名称/副标题模糊搜索） | 登山杖 | +| `maxPrice` | `number` | | 最高价格 | 500.0 | +| `minPrice` | `number` | | 最低价格 | 10.0 | +| `page` | `integer(int32)` | | 页码 | 1 | +| `pageSize` | `integer(int32)` | | 每页条数 | 20 | +| `recommended` | `integer(int32)` | | 是否推荐：0=否 1=是 | 1 | +| `sortBy` | `string` | | 排序字段 | createdAt | +| `sortDir` | `string` | | 排序方向：asc=升序 desc=降序 | desc | +| `status` | `integer(int32)` | | 状态：0=草稿 1=上架 2=下架 | 1 | +| `tagId` | `integer(int64)` | | 标签ID | 100 | +| `tagIds` | `string` | | 标签ID列表（逗号分隔） | 100,101,102 | + +**响应** `统一响应结果«分页结果«备品列表视图»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«备品列表视图»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `备品列表视图[]` | | 数据列表 | +|     `approvalNo` | `string` | | 审批编号 | +|     `basePrice` | `number` | | 基础单价（元） | +|     `billingType` | `string` | | 计费方式编码 | +|     `billingTypeName` | `string` | | 计费方式名称 | +|     `categoryCode` | `string` | | 分类编码 | +|     `categoryName` | `string` | | 分类名称 | +|     `coverUrl` | `string` | | 封面图URL | +|     `createdAt` | `string` | | 创建时间 | +|     `highlights` | `string` | | 亮点摘要 | +|     `name` | `string` | | 备品名称 | +|     `pendingStatus` | `int` | | 待审批目标状态 | +|     `recommended` | `int` | | 是否推荐：0=否 1=是 | +|     `sortOrder` | `int` | | 排序权重 | +|     `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +|     `subtitle` | `string` | | 副标题 | +|     `suppliesId` | `string` | | 备品ID | +|     `tags` | `备品标签视图[]` | | 标签列表 | +|     `unit` | `string` | | 计量单位 | +|     `viewCount` | `int` | | 浏览量 | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/supplies/items/batch + +**批量删除** + +批量软删除多个备品。仅SUPER_ADMIN或创建者可操作。 + +**请求体** `备品批量删除请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `suppliesIds` | `string[]` | 是 | 备品ID列表 | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/supplies/items/batch/status + +**批量上下架** + +批量修改多个备品的状态，跳过审批流程。 + +**请求体** `备品状态变更请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `status` | `int` | 是 | 目标状态：0=草稿 1=上架 2=下架 | +| `suppliesIds` | `string[]` | | 备品ID列表（批量操作） | + +**响应** `统一响应结果«Void»` + +--- + +## 房型价格日历 + +### `GET` /admin/hotel/room-type/{roomTypeId}/prices + +**查询价格日历** + +按月查询房型的每日价格和可售状态。每个房型有独立的价格日历。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `roomTypeId` | `integer` | | 房型ID | + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `month` | `integer(int32)` | | 月份 | | +| `year` | `integer(int32)` | | 年份 | | + +**响应** `统一响应结果«酒店房型价格日历VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `酒店房型价格日历VO` | | 响应数据 | +|   `hotelId` | `string` | | 酒店ID | +|   `month` | `int` | | 月份 | +|   `prices` | `酒店房型价格日历日VO[]` | | 价格日历明细列表 | +|     `costPrice` | `number` | | 成本价（元） | +|     `date` | `string` | | 日期 | +|     `remark` | `string` | | 备注 | +|     `status` | `int` | | 状态：0=不可售 1=可售 | +|     `stock` | `int` | | 库存数量 | +|     `stockUsed` | `int` | | 已用库存 | +|   `roomTypeId` | `string` | | 房型ID | +|   `roomTypeName` | `string` | | 房型名称 | +|   `stockEnabled` | `boolean` | | 是否启用库存管理 | +|   `year` | `int` | | 年份 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/hotel/room-type/{roomTypeId}/prices + +**批量设置价格日历** + +在指定日期范围内批量设置房型的成本价和可售状态。支持按星期过滤和排除特定日期。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `roomTypeId` | `integer` | | 房型ID | + +**请求体** `酒店房型价格日历设置请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `costPrice` | `number` | 是 | 成本价（元） | +| `endDate` | `string` | 是 | 结束日期（yyyy-MM-dd） | +| `excludeDates` | `string[]` | | 排除日期列表 | +| `remark` | `string` | | 备注 | +| `selectedWeekdays` | `int[]` | | 指定星期几（1=周一 7=周日） | +| `startDate` | `string` | 是 | 开始日期（yyyy-MM-dd） | +| `status` | `int` | | 状态：0=不可售 1=可售 | +| `stock` | `int` | | 库存数量 | +| `weekdayOnly` | `boolean` | | 是否仅工作日 | +| `weekendOnly` | `boolean` | | 是否仅周末 | + +**响应** `统一响应结果«Void»` + +--- + +### `DELETE` /admin/hotel/room-type/{roomTypeId}/prices + +**删除价格日历** + +删除指定日期范围内房型的所有价格记录。日期格式：yyyy-MM-dd。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `roomTypeId` | `integer` | | 房型ID | + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `endDate` | `string` | | 结束日期 | | +| `startDate` | `string` | | 开始日期 | | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/hotel/room-type/{roomTypeId}/prices/batch-status + +**批量修改日期可售状态** + +批量修改指定日期范围内房型的可售状态，不影响价格。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `roomTypeId` | `integer` | | 房型ID | + +**请求体** `酒店房型价格日历状态变更请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `endDate` | `string` | 是 | 结束日期（yyyy-MM-dd） | +| `remark` | `string` | | 备注 | +| `startDate` | `string` | 是 | 开始日期（yyyy-MM-dd） | +| `status` | `int` | 是 | 状态：0=不可售 1=可售 | + +**响应** `统一响应结果«Void»` + +--- + +## 房型管理 + +### `GET` /admin/hotel/room-type/{roomTypeId} + +**房型详情** + +获取房型完整信息，包含价格、入住人数、素材等。 + +**关联字典**： +- room_category：房型分类（列表/详情显示） +- bed_type：床型（列表/详情显示） +- window_type：窗户类型（列表/详情显示） +- bathroom_type：卫浴类型（列表/详情显示） +- room_facility：房间设施（列表/详情显示） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `roomTypeId` | `integer` | | 房型ID | + +**响应** `统一响应结果«房型详情VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `房型详情VO` | | 响应数据 | +|   `approvalNo` | `string` | | 审批单号 | +|   `bannerMaterialIds` | `string[]` | | 横幅素材ID列表 | +|   `bannerUrls` | `string[]` | | 横幅图URL列表 | +|   `basePrice` | `number` | | 基础成本价（元） | +|   `bathroomType` | `string` | | 卫浴类型 | +|   `bedCount` | `int` | | 床位数量 | +|   `bedSize` | `string` | | 床尺寸 | +|   `bedType` | `string` | | 床型 | +|   `coverMaterialId` | `string` | | 封面素材ID | +|   `coverUrl` | `string` | | 封面图URL | +|   `createdAt` | `string` | | 创建时间 | +|   `description` | `string` | | 房型描述 | +|   `floorInfo` | `string` | | 楼层信息 | +|   `hotelId` | `string` | | 所属酒店ID | +|   `maxOccupancy` | `int` | | 最多入住人数 | +|   `name` | `string` | | 房型名称 | +|   `pendingStatus` | `int` | | 待审批目标状态 | +|   `roomArea` | `number` | | 房间面积（平方米） | +|   `roomCategory` | `string` | | 房型分类 | +|   `roomFacilities` | `string` | | 房间设施（JSON） | +|   `roomTypeId` | `string` | | 房型ID | +|   `sortOrder` | `int` | | 排序权重 | +|   `status` | `int` | | 状态：0=禁用 1=启用 | +|   `totalRooms` | `int` | | 总房间数 | +|   `updatedAt` | `string` | | 更新时间 | +|   `videoMaterialId` | `string` | | 视频素材ID | +|   `videoUrl` | `string` | | 视频URL | +|   `windowType` | `string` | | 窗型 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/hotel/room-type/{roomTypeId} + +**更新房型** + +更新房型基本信息，不改变当前状态。 + +**关联字典**： +- room_category：房型分类（表单选择） +- bed_type：床型（表单选择） +- window_type：窗户类型（表单选择） +- bathroom_type：卫浴类型（表单选择） +- room_facility：房间设施（表单多选） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `roomTypeId` | `integer` | | 房型ID | + +**请求体** `房型更新请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `bannerMaterialIds` | `string[]` | | 横幅素材ID列表 | +| `basePrice` | `number` | | 基础成本价（元） | +| `bathroomType` | `string` | | 卫浴类型 | +| `bedCount` | `int` | | 床位数量 | +| `bedSize` | `string` | | 床尺寸 | +| `bedType` | `string` | | 床型 | +| `coverMaterialId` | `string` | | 封面素材ID | +| `description` | `string` | | 房型描述 | +| `floorInfo` | `string` | | 楼层信息 | +| `maxOccupancy` | `int` | | 最多入住人数 | +| `name` | `string` | | 房型名称 | +| `roomArea` | `number` | | 房间面积（平方米） | +| `roomCategory` | `string` | | 房型分类 | +| `roomFacilities` | `string` | | 房间设施（JSON） | +| `sortOrder` | `int` | | 排序权重，值越大越靠前 | +| `totalRooms` | `int` | | 总房间数 | +| `videoMaterialId` | `string` | | 视频素材ID | +| `windowType` | `string` | | 窗型 | + +**响应** `统一响应结果«房型详情VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `房型详情VO` | | 响应数据 | +|   `approvalNo` | `string` | | 审批单号 | +|   `bannerMaterialIds` | `string[]` | | 横幅素材ID列表 | +|   `bannerUrls` | `string[]` | | 横幅图URL列表 | +|   `basePrice` | `number` | | 基础成本价（元） | +|   `bathroomType` | `string` | | 卫浴类型 | +|   `bedCount` | `int` | | 床位数量 | +|   `bedSize` | `string` | | 床尺寸 | +|   `bedType` | `string` | | 床型 | +|   `coverMaterialId` | `string` | | 封面素材ID | +|   `coverUrl` | `string` | | 封面图URL | +|   `createdAt` | `string` | | 创建时间 | +|   `description` | `string` | | 房型描述 | +|   `floorInfo` | `string` | | 楼层信息 | +|   `hotelId` | `string` | | 所属酒店ID | +|   `maxOccupancy` | `int` | | 最多入住人数 | +|   `name` | `string` | | 房型名称 | +|   `pendingStatus` | `int` | | 待审批目标状态 | +|   `roomArea` | `number` | | 房间面积（平方米） | +|   `roomCategory` | `string` | | 房型分类 | +|   `roomFacilities` | `string` | | 房间设施（JSON） | +|   `roomTypeId` | `string` | | 房型ID | +|   `sortOrder` | `int` | | 排序权重 | +|   `status` | `int` | | 状态：0=禁用 1=启用 | +|   `totalRooms` | `int` | | 总房间数 | +|   `updatedAt` | `string` | | 更新时间 | +|   `videoMaterialId` | `string` | | 视频素材ID | +|   `videoUrl` | `string` | | 视频URL | +|   `windowType` | `string` | | 窗型 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/hotel/room-type/{roomTypeId} + +**删除房型** + +软删除房型及其价格日历数据。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `roomTypeId` | `integer` | | 房型ID | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/hotel/room-type/{roomTypeId}/status + +**启用/禁用房型** + +直接修改房型状态（跳过审批）。status=0禁用，status=1启用。禁用后该房型不会出现在C端展示中。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `roomTypeId` | `integer` | | 房型ID | + +**请求体** `房型状态变更请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `status` | `int` | 是 | 状态：0=禁用 1=启用 | + +**响应** `统一响应结果«Void»` + +--- + +### `POST` /admin/hotel/room-type/{roomTypeId}/submit-approval + +**提交房型启用/禁用审批** + +向企微OA提交房型启用/禁用审批。审批流程与住宿共享同一模板。返回审批单号spNo。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `roomTypeId` | `integer` | | 房型ID | + +**请求体** `酒店审批提交请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `reason` | `string` | 是 | 审批理由 | +| `targetStatus` | `int` | 是 | 目标状态：1=上架 2=下架 | + +**响应** `统一响应结果«Map«string,string»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `object` | | 响应数据 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/hotel/{hotelId}/room-type + +**创建房型** + +在指定住宿下创建房型（如标准间、大床房、套房等）。每个房型有独立的价格日历、最大入住人数(maxOccupancy)和基础价格(basePrice)。房型初始状态为草稿(status=0)，需独立审批后才能启用。创建后可通过「提交房型启用审批」接口提交企微OA审批。 + +**关联字典**： +- room_category：房型分类（表单选择） +- bed_type：床型（表单选择） +- window_type：窗户类型（表单选择） +- bathroom_type：卫浴类型（表单选择） +- room_facility：房间设施（表单多选） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `hotelId` | `integer` | | 住宿ID | + +**请求体** `房型创建请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `bannerMaterialIds` | `string[]` | | 横幅素材ID列表 | +| `basePrice` | `number` | | 基础成本价（元） | +| `bathroomType` | `string` | | 卫浴类型 | +| `bedCount` | `int` | | 床位数量 | +| `bedSize` | `string` | | 床尺寸 | +| `bedType` | `string` | 是 | 床型 | +| `coverMaterialId` | `string` | | 封面素材ID | +| `description` | `string` | | 房型描述 | +| `floorInfo` | `string` | | 楼层信息 | +| `maxOccupancy` | `int` | | 最多入住人数 | +| `name` | `string` | 是 | 房型名称 | +| `roomArea` | `number` | | 房间面积（平方米） | +| `roomCategory` | `string` | 是 | 房型分类 | +| `roomFacilities` | `string` | | 房间设施（JSON） | +| `sortOrder` | `int` | | 排序权重，值越大越靠前 | +| `totalRooms` | `int` | | 总房间数 | +| `videoMaterialId` | `string` | | 视频素材ID | +| `windowType` | `string` | | 窗型 | + +**响应** `统一响应结果«房型详情VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `房型详情VO` | | 响应数据 | +|   `approvalNo` | `string` | | 审批单号 | +|   `bannerMaterialIds` | `string[]` | | 横幅素材ID列表 | +|   `bannerUrls` | `string[]` | | 横幅图URL列表 | +|   `basePrice` | `number` | | 基础成本价（元） | +|   `bathroomType` | `string` | | 卫浴类型 | +|   `bedCount` | `int` | | 床位数量 | +|   `bedSize` | `string` | | 床尺寸 | +|   `bedType` | `string` | | 床型 | +|   `coverMaterialId` | `string` | | 封面素材ID | +|   `coverUrl` | `string` | | 封面图URL | +|   `createdAt` | `string` | | 创建时间 | +|   `description` | `string` | | 房型描述 | +|   `floorInfo` | `string` | | 楼层信息 | +|   `hotelId` | `string` | | 所属酒店ID | +|   `maxOccupancy` | `int` | | 最多入住人数 | +|   `name` | `string` | | 房型名称 | +|   `pendingStatus` | `int` | | 待审批目标状态 | +|   `roomArea` | `number` | | 房间面积（平方米） | +|   `roomCategory` | `string` | | 房型分类 | +|   `roomFacilities` | `string` | | 房间设施（JSON） | +|   `roomTypeId` | `string` | | 房型ID | +|   `sortOrder` | `int` | | 排序权重 | +|   `status` | `int` | | 状态：0=禁用 1=启用 | +|   `totalRooms` | `int` | | 总房间数 | +|   `updatedAt` | `string` | | 更新时间 | +|   `videoMaterialId` | `string` | | 视频素材ID | +|   `videoUrl` | `string` | | 视频URL | +|   `windowType` | `string` | | 窗型 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/hotel/{hotelId}/room-types + +**房型列表** + +获取指定住宿下的所有房型列表（不分页），按sortOrder排序。 + +**关联字典**： +- room_category：房型分类（列表/详情显示） +- bed_type：床型（列表/详情显示） +- window_type：窗户类型（列表/详情显示） +- bathroom_type：卫浴类型（列表/详情显示） +- room_facility：房间设施（列表/详情显示） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `hotelId` | `integer` | | 住宿ID | + +**响应** `统一响应结果«List«房型详情VO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `房型详情VO[]` | | 响应数据 | +|   `approvalNo` | `string` | | 审批单号 | +|   `bannerMaterialIds` | `string[]` | | 横幅素材ID列表 | +|   `bannerUrls` | `string[]` | | 横幅图URL列表 | +|   `basePrice` | `number` | | 基础成本价（元） | +|   `bathroomType` | `string` | | 卫浴类型 | +|   `bedCount` | `int` | | 床位数量 | +|   `bedSize` | `string` | | 床尺寸 | +|   `bedType` | `string` | | 床型 | +|   `coverMaterialId` | `string` | | 封面素材ID | +|   `coverUrl` | `string` | | 封面图URL | +|   `createdAt` | `string` | | 创建时间 | +|   `description` | `string` | | 房型描述 | +|   `floorInfo` | `string` | | 楼层信息 | +|   `hotelId` | `string` | | 所属酒店ID | +|   `maxOccupancy` | `int` | | 最多入住人数 | +|   `name` | `string` | | 房型名称 | +|   `pendingStatus` | `int` | | 待审批目标状态 | +|   `roomArea` | `number` | | 房间面积（平方米） | +|   `roomCategory` | `string` | | 房型分类 | +|   `roomFacilities` | `string` | | 房间设施（JSON） | +|   `roomTypeId` | `string` | | 房型ID | +|   `sortOrder` | `int` | | 排序权重 | +|   `status` | `int` | | 状态：0=禁用 1=启用 | +|   `totalRooms` | `int` | | 总房间数 | +|   `updatedAt` | `string` | | 更新时间 | +|   `videoMaterialId` | `string` | | 视频素材ID | +|   `videoUrl` | `string` | | 视频URL | +|   `windowType` | `string` | | 窗型 | +| `message` | `string` | | 响应消息 | + +--- + +## 景区价格日历 + +### `GET` /admin/scenic/spot/{scenicId}/prices + +**查询价格日历** + +按月查询景区的每日价格和可售状态。返回指定年月中所有已设置价格的日期，未设置的日期不返回。用于前端日历组件渲染。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `scenicId` | `integer` | | 景区ID | + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `month` | `integer(int32)` | | 月份 | | +| `year` | `integer(int32)` | | 年份 | | + +**响应** `统一响应结果«价格日历月视图»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `价格日历月视图` | | 响应数据 | +|   `month` | `int` | | 月份 | +|   `prices` | `价格日历日数据[]` | | 每日价格列表 | +|     `costPrice` | `number` | | 成本价（元） | +|     `date` | `string` | | 日期 | +|     `remark` | `string` | | 备注 | +|     `status` | `int` | | 状态：0=不可用 1=可用 | +|     `stock` | `int` | | 总库存 | +|     `stockUsed` | `int` | | 已用库存 | +|   `scenicId` | `string` | | 景区ID | +|   `scenicName` | `string` | | 景区名称 | +|   `stockEnabled` | `boolean` | | 是否启用库存管理 | +|   `year` | `int` | | 年份 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/scenic/spot/{scenicId}/prices + +**批量设置价格** + +在指定日期范围内批量设置成本价、库存和可售状态。支持weekdayOnly/weekendOnly/selectedWeekdays过滤特定星期，支持excludeDates排除特定日期。已有价格的日期会被覆盖更新。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `scenicId` | `integer` | | 景区ID | + +**请求体** `价格日历批量设置请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `costPrice` | `number` | 是 | 成本价（元） | +| `endDate` | `string` | 是 | 结束日期 | +| `excludeDates` | `string[]` | | 排除的日期列表 | +| `remark` | `string` | | 备注 | +| `selectedWeekdays` | `int[]` | | 选中的星期（1=周一...7=周日），为空时不做过滤 | +| `startDate` | `string` | 是 | 开始日期 | +| `status` | `int` | | 状态：0=不可用 1=可用 | +| `stock` | `int` | | 库存数量 | +| `weekdayOnly` | `boolean` | | 仅工作日 | +| `weekendOnly` | `boolean` | | 仅周末 | + +**响应** `统一响应结果«Void»` + +--- + +### `DELETE` /admin/scenic/spot/{scenicId}/prices + +**批量清除价格** + +删除指定日期范围内的所有价格记录。删除后该日期范围将显示为未设置状态。日期格式：yyyy-MM-dd。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `scenicId` | `integer` | | 景区ID | + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `endDate` | `string` | | 结束日期 | | +| `startDate` | `string` | | 开始日期 | | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/scenic/spot/{scenicId}/prices/status + +**批量修改可售状态** + +批量修改指定日期范围内的可售状态，不影响价格和库存。status=0不可售，status=1可售。用于临时关闭/开放某些日期的售卖。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `scenicId` | `integer` | | 景区ID | + +**请求体** `价格日历状态变更请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `endDate` | `string` | 是 | 结束日期 | +| `remark` | `string` | | 备注 | +| `startDate` | `string` | 是 | 开始日期 | +| `status` | `int` | 是 | 目标状态：0=不可用 1=可用 | + +**响应** `统一响应结果«Void»` + +--- + +## 景区季节内容 + +### `PUT` /admin/scenic/spot/{scenicId}/season/{seasonType} + +**保存/更新季节内容** + +创建或更新指定景区的季节内容。seasonType为季节标识（如spring/summer/autumn/winter）。如果该季节已存在则更新，不存在则创建。支持设置季节别名（如「樱花季」）、月份范围、独立封面和轮播图。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `scenicId` | `integer` | | 景区ID | +| `seasonType` | `string` | | 季节类型 | + +**请求体** `景区季节保存请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `bannerMaterialIds` | `string[]` | | 轮播图素材ID列表 | +| `coverMaterialId` | `string` | | 封面素材ID | +| `description` | `string` | | 季节描述 | +| `highlights` | `string` | | 季节亮点 | +| `monthEnd` | `int` | 是 | 结束月份（1-12） | +| `monthStart` | `int` | 是 | 开始月份（1-12） | +| `playGuide` | `string` | | 游玩攻略（富文本JSON） | +| `seasonName` | `string` | | 季节别名 | +| `tips` | `string` | | 温馨提示 | +| `videoMaterialIds` | `string[]` | | 视频素材ID列表 | + +**响应** `统一响应结果«景区季节内容»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `景区季节内容` | | 响应数据 | +|   `bannerMaterialIds` | `string[]` | | 轮播图素材ID列表 | +|   `bannerUrls` | `string[]` | | 轮播图URL列表 | +|   `coverMaterialId` | `string` | | 封面素材ID | +|   `coverUrl` | `string` | | 封面图URL | +|   `createdAt` | `string` | | 创建时间 | +|   `description` | `string` | | 季节描述 | +|   `highlights` | `string` | | 季节亮点 | +|   `monthEnd` | `int` | | 结束月份 | +|   `monthStart` | `int` | | 开始月份 | +|   `playGuide` | `string` | | 游玩攻略（富文本JSON） | +|   `scenicId` | `string` | | 景区ID | +|   `seasonId` | `string` | | 季节ID | +|   `seasonName` | `string` | | 季节别名 | +|   `seasonType` | `string` | | 季节类型：spring/summer/autumn/winter | +|   `tips` | `string` | | 温馨提示 | +|   `updatedAt` | `string` | | 更新时间 | +|   `videoMaterialIds` | `string[]` | | 视频素材ID列表 | +|   `videoUrls` | `string[]` | | 视频URL列表 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/scenic/spot/{scenicId}/season/{seasonType} + +**删除季节内容** + +删除指定景区的某个季节内容，同时清理关联的素材引用。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `scenicId` | `integer` | | 景区ID | +| `seasonType` | `string` | | 季节类型 | + +**响应** `统一响应结果«Void»` + +--- + +### `GET` /admin/scenic/spot/{scenicId}/seasons + +**获取景区全部季节内容** + +返回景区的所有季节内容列表（春/夏/秋/冬）。季节内容是景区独有功能，其他资源类型没有此概念。每个季节可设置独立的封面、轮播图、亮点描述和游玩攻略。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `scenicId` | `integer` | | 景区ID | + +**响应** `统一响应结果«List«景区季节内容»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `景区季节内容[]` | | 响应数据 | +|   `bannerMaterialIds` | `string[]` | | 轮播图素材ID列表 | +|   `bannerUrls` | `string[]` | | 轮播图URL列表 | +|   `coverMaterialId` | `string` | | 封面素材ID | +|   `coverUrl` | `string` | | 封面图URL | +|   `createdAt` | `string` | | 创建时间 | +|   `description` | `string` | | 季节描述 | +|   `highlights` | `string` | | 季节亮点 | +|   `monthEnd` | `int` | | 结束月份 | +|   `monthStart` | `int` | | 开始月份 | +|   `playGuide` | `string` | | 游玩攻略（富文本JSON） | +|   `scenicId` | `string` | | 景区ID | +|   `seasonId` | `string` | | 季节ID | +|   `seasonName` | `string` | | 季节别名 | +|   `seasonType` | `string` | | 季节类型：spring/summer/autumn/winter | +|   `tips` | `string` | | 温馨提示 | +|   `updatedAt` | `string` | | 更新时间 | +|   `videoMaterialIds` | `string[]` | | 视频素材ID列表 | +|   `videoUrls` | `string[]` | | 视频URL列表 | +| `message` | `string` | | 响应消息 | + +--- + +## 景区标签管理 + +### `PUT` /admin/scenic/spot/{scenicId}/tags + +**更新景区标签** + +全量替换指定景区的标签列表。传入tagIds为该景区最终要关联的标签ID列表，为空则清除所有标签。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `scenicId` | `integer` | | 景区ID | + +**请求体** `景区标签更新请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagIds` | `string[]` | | 标签ID列表（全量替换） | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/scenic/spots/batch/tags + +**批量打标签** + +对多个景区批量添加或移除标签。addTagIds为要添加的标签，removeTagIds为要移除的标签，两者可同时使用。增量操作，不影响未指定的标签。 + +**请求体** `景区批量标签操作请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `addTagIds` | `string[]` | | 要添加的标签ID列表 | +| `removeTagIds` | `string[]` | | 要移除的标签ID列表 | +| `scenicIds` | `string[]` | 是 | 景区ID列表 | + +**响应** `统一响应结果«Void»` + +--- + +### `POST` /admin/scenic/tag + +**创建管理标签** + +创建预设标签，标签名不可重复。可指定颜色(tagColor)，默认为#409EFF。预设标签在标签管理页面展示和维护。 + +**请求体** `标签创建请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagColor` | `string` | | 标签颜色（十六进制） | +| `tagName` | `string` | 是 | 标签名称 | + +**响应** `统一响应结果«景区标签»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `景区标签` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `tagColor` | `string` | | 标签颜色（十六进制） | +|   `tagId` | `string` | | 标签ID | +|   `tagName` | `string` | | 标签名称 | +|   `tagType` | `int` | | 标签类型：0=自定义 1=系统预设 | +|   `useCount` | `int` | | 使用次数 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/scenic/tag/adhoc + +**解析自定义标签** + +输入标签名称，如果已存在则直接返回，不存在则自动创建。用于景区编辑时快速输入新标签，避免先到标签管理页面创建。 + +**请求体** `标签创建请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagColor` | `string` | | 标签颜色（十六进制） | +| `tagName` | `string` | 是 | 标签名称 | + +**响应** `统一响应结果«景区标签»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `景区标签` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `tagColor` | `string` | | 标签颜色（十六进制） | +|   `tagId` | `string` | | 标签ID | +|   `tagName` | `string` | | 标签名称 | +|   `tagType` | `int` | | 标签类型：0=自定义 1=系统预设 | +|   `useCount` | `int` | | 使用次数 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/scenic/tag/{tagId} + +**编辑标签** + +修改标签名称或颜色。修改后所有关联此标签的景区会自动生效。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagId` | `integer` | | 标签ID | + +**请求体** `标签更新请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagColor` | `string` | | 标签颜色（十六进制） | +| `tagName` | `string` | | 标签名称 | + +**响应** `统一响应结果«景区标签»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `景区标签` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `tagColor` | `string` | | 标签颜色（十六进制） | +|   `tagId` | `string` | | 标签ID | +|   `tagName` | `string` | | 标签名称 | +|   `tagType` | `int` | | 标签类型：0=自定义 1=系统预设 | +|   `useCount` | `int` | | 使用次数 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/scenic/tag/{tagId} + +**删除标签** + +删除标签并自动解除所有景区与该标签的关联关系。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagId` | `integer` | | 标签ID | + +**响应** `统一响应结果«Void»` + +--- + +### `GET` /admin/scenic/tags + +**获取管理标签列表（分页）** + +分页查询景区标签库中的所有标签，支持按关键词搜索。标签分为预设标签（管理员创建）和自定义标签（adhoc接口创建），此接口返回全部类型。 + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `keyword` | `string` | | 关键词 | | +| `page` | `integer(int32)` | | 页码 | | +| `pageSize` | `integer(int32)` | | 每页条数 | | + +**响应** `统一响应结果«分页结果«景区标签»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«景区标签»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `景区标签[]` | | 数据列表 | +|     `createdAt` | `string` | | 创建时间 | +|     `tagColor` | `string` | | 标签颜色（十六进制） | +|     `tagId` | `string` | | 标签ID | +|     `tagName` | `string` | | 标签名称 | +|     `tagType` | `int` | | 标签类型：0=自定义 1=系统预设 | +|     `useCount` | `int` | | 使用次数 | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/scenic/tags/all + +**获取全部标签** + +不分页返回所有标签，用于景区编辑时的标签选择下拉列表。 + +**响应** `统一响应结果«List«景区标签»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `景区标签[]` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `tagColor` | `string` | | 标签颜色（十六进制） | +|   `tagId` | `string` | | 标签ID | +|   `tagName` | `string` | | 标签名称 | +|   `tagType` | `int` | | 标签类型：0=自定义 1=系统预设 | +|   `useCount` | `int` | | 使用次数 | +| `message` | `string` | | 响应消息 | + +--- + +## 景区管理 + +### `POST` /admin/scenic/spot + +**创建景区** + +新建一个景区资源，初始状态为草稿(status=0)。创建后需通过「提交启用审批」接口走企微OA审批流程才能上架。支持富文本字段（featureIntro/detailContent等），素材ID从素材库获取。 + +**关联字典**： +- scenic_facility：景区设施（表单多选） +- scenic_honor：景区荣誉（表单多选） + +**请求体** `景区创建请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `address` | `string` | | 详细地址 | +| `arrangement` | `string` | | 行程安排（富文本JSON） | +| `backupContactPerson` | `string` | | 备用联系人姓名 | +| `backupContactPhone` | `string` | | 备用联系人电话 | +| `bannerMaterialIds` | `string[]` | | 轮播图素材ID列表 | +| `city` | `string` | 是 | 城市（行政区划） | +| `cityName` | `string` | 是 | 所在城市（展示用） | +| `closedDay` | `string` | | 闭园日 | +| `contactPerson` | `string` | | 联系人姓名 | +| `contactPhone` | `string` | | 联系人电话 | +| `coverMaterialId` | `string` | | 封面素材ID | +| `cultureExperience` | `string` | | 文化体验（富文本JSON） | +| `description` | `string` | | 景区描述 | +| `detailContent` | `string` | | 详情内容（富文本JSON） | +| `district` | `string` | | 区/县 | +| `facilities` | `string[]` | | 设施编码列表 | +| `featureIntro` | `string` | | 特色介绍（富文本JSON） | +| `highlightSpots` | `string` | | 亮点景点（富文本JSON） | +| `highlights` | `string` | | 亮点简介 | +| `honors` | `string[]` | | 荣誉称号列表 | +| `interactiveExperience` | `string` | | 互动体验（富文本JSON） | +| `latitude` | `number` | 是 | 纬度 | +| `longitude` | `number` | 是 | 经度 | +| `name` | `string` | 是 | 景区名称 | +| `openTime` | `string` | | 开放时间 | +| `photographyGuide` | `string` | | 摄影指南（富文本JSON） | +| `province` | `string` | 是 | 省份 | +| `sceneryExperience` | `string` | | 风景体验（富文本JSON） | +| `sortOrder` | `int` | | 排序权重，越大越靠前 | +| `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +| `travelPrep` | `string` | | 出行准备（富文本JSON） | +| `videoMaterialIds` | `string[]` | | 视频素材ID列表 | + +**响应** `统一响应结果«景区详情»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `景区详情` | | 响应数据 | +|   `address` | `string` | | 详细地址 | +|   `arrangement` | `string` | | 行程安排（富文本JSON） | +|   `backupContactPerson` | `string` | | 备用联系人姓名 | +|   `backupContactPhone` | `string` | | 备用联系人电话 | +|   `bannerMaterialIds` | `string[]` | | 轮播图素材ID列表 | +|   `bannerUrls` | `string[]` | | 轮播图URL列表 | +|   `city` | `string` | | 城市（行政区划） | +|   `cityName` | `string` | | 所在城市（展示用） | +|   `closedDay` | `string` | | 闭园日 | +|   `contactPerson` | `string` | | 联系人姓名 | +|   `contactPhone` | `string` | | 联系人电话 | +|   `coverMaterialId` | `string` | | 封面素材ID | +|   `coverUrl` | `string` | | 封面图URL | +|   `createdAt` | `string` | | 创建时间 | +|   `createdBy` | `string` | | 创建人ID | +|   `createdByName` | `string` | | 创建人姓名 | +|   `cultureExperience` | `string` | | 文化体验（富文本JSON） | +|   `description` | `string` | | 景区描述 | +|   `detailContent` | `string` | | 详情内容（富文本JSON） | +|   `district` | `string` | | 区/县 | +|   `facilities` | `string[]` | | 设施编码列表 | +|   `facilityNames` | `string[]` | | 设施名称列表 | +|   `featureIntro` | `string` | | 特色介绍（富文本JSON） | +|   `highlightSpots` | `string` | | 亮点景点（富文本JSON） | +|   `highlights` | `string` | | 亮点简介 | +|   `honors` | `string[]` | | 荣誉称号列表 | +|   `interactiveExperience` | `string` | | 互动体验（富文本JSON） | +|   `latitude` | `number` | | 纬度 | +|   `longitude` | `number` | | 经度 | +|   `name` | `string` | | 景区名称 | +|   `openTime` | `string` | | 开放时间 | +|   `photographyGuide` | `string` | | 摄影指南（富文本JSON） | +|   `province` | `string` | | 省份 | +|   `rating` | `number` | | 评分 | +|   `reviewCount` | `int` | | 评论数 | +|   `sceneryExperience` | `string` | | 风景体验（富文本JSON） | +|   `scenicId` | `string` | | 景区ID | +|   `sortOrder` | `int` | | 排序权重 | +|   `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +|   `tags` | `景区标签[]` | | 标签列表 | +|     `createdAt` | `string` | | 创建时间 | +|     `tagColor` | `string` | | 标签颜色（十六进制） | +|     `tagId` | `string` | | 标签ID | +|     `tagName` | `string` | | 标签名称 | +|     `tagType` | `int` | | 标签类型：0=自定义 1=系统预设 | +|     `useCount` | `int` | | 使用次数 | +|   `travelPrep` | `string` | | 出行准备（富文本JSON） | +|   `updatedAt` | `string` | | 更新时间 | +|   `videoMaterialIds` | `string[]` | | 视频素材ID列表 | +|   `videoUrls` | `string[]` | | 视频URL列表 | +|   `viewCount` | `int` | | 浏览量 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/scenic/spot/{scenicId} + +**景区详情** + +获取景区完整信息，包含富文本内容、素材URL、标签列表、季节内容等。素材ID会自动解析为OSS访问地址。 + +**关联字典**： +- scenic_facility：景区设施（详情显示） +- scenic_honor：景区荣誉（详情显示） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `scenicId` | `integer` | | 景区ID | + +**响应** `统一响应结果«景区详情»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `景区详情` | | 响应数据 | +|   `address` | `string` | | 详细地址 | +|   `arrangement` | `string` | | 行程安排（富文本JSON） | +|   `backupContactPerson` | `string` | | 备用联系人姓名 | +|   `backupContactPhone` | `string` | | 备用联系人电话 | +|   `bannerMaterialIds` | `string[]` | | 轮播图素材ID列表 | +|   `bannerUrls` | `string[]` | | 轮播图URL列表 | +|   `city` | `string` | | 城市（行政区划） | +|   `cityName` | `string` | | 所在城市（展示用） | +|   `closedDay` | `string` | | 闭园日 | +|   `contactPerson` | `string` | | 联系人姓名 | +|   `contactPhone` | `string` | | 联系人电话 | +|   `coverMaterialId` | `string` | | 封面素材ID | +|   `coverUrl` | `string` | | 封面图URL | +|   `createdAt` | `string` | | 创建时间 | +|   `createdBy` | `string` | | 创建人ID | +|   `createdByName` | `string` | | 创建人姓名 | +|   `cultureExperience` | `string` | | 文化体验（富文本JSON） | +|   `description` | `string` | | 景区描述 | +|   `detailContent` | `string` | | 详情内容（富文本JSON） | +|   `district` | `string` | | 区/县 | +|   `facilities` | `string[]` | | 设施编码列表 | +|   `facilityNames` | `string[]` | | 设施名称列表 | +|   `featureIntro` | `string` | | 特色介绍（富文本JSON） | +|   `highlightSpots` | `string` | | 亮点景点（富文本JSON） | +|   `highlights` | `string` | | 亮点简介 | +|   `honors` | `string[]` | | 荣誉称号列表 | +|   `interactiveExperience` | `string` | | 互动体验（富文本JSON） | +|   `latitude` | `number` | | 纬度 | +|   `longitude` | `number` | | 经度 | +|   `name` | `string` | | 景区名称 | +|   `openTime` | `string` | | 开放时间 | +|   `photographyGuide` | `string` | | 摄影指南（富文本JSON） | +|   `province` | `string` | | 省份 | +|   `rating` | `number` | | 评分 | +|   `reviewCount` | `int` | | 评论数 | +|   `sceneryExperience` | `string` | | 风景体验（富文本JSON） | +|   `scenicId` | `string` | | 景区ID | +|   `sortOrder` | `int` | | 排序权重 | +|   `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +|   `tags` | `景区标签[]` | | 标签列表 | +|     `createdAt` | `string` | | 创建时间 | +|     `tagColor` | `string` | | 标签颜色（十六进制） | +|     `tagId` | `string` | | 标签ID | +|     `tagName` | `string` | | 标签名称 | +|     `tagType` | `int` | | 标签类型：0=自定义 1=系统预设 | +|     `useCount` | `int` | | 使用次数 | +|   `travelPrep` | `string` | | 出行准备（富文本JSON） | +|   `updatedAt` | `string` | | 更新时间 | +|   `videoMaterialIds` | `string[]` | | 视频素材ID列表 | +|   `videoUrls` | `string[]` | | 视频URL列表 | +|   `viewCount` | `int` | | 浏览量 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/scenic/spot/{scenicId} + +**更新景区** + +更新景区基本信息和富文本内容。更新不会改变当前状态。如果景区已上架，修改后仍保持上架状态，无需重新审批。 + +**关联字典**： +- scenic_facility：景区设施（表单多选） +- scenic_honor：景区荣誉（表单多选） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `scenicId` | `integer` | | 景区ID | + +**请求体** `景区更新请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `address` | `string` | | 详细地址 | +| `arrangement` | `string` | | 行程安排（富文本JSON） | +| `backupContactPerson` | `string` | | 备用联系人姓名 | +| `backupContactPhone` | `string` | | 备用联系人电话 | +| `bannerMaterialIds` | `string[]` | | 轮播图素材ID列表 | +| `city` | `string` | | 城市（行政区划） | +| `cityName` | `string` | | 所在城市（展示用） | +| `closedDay` | `string` | | 闭园日 | +| `contactPerson` | `string` | | 联系人姓名 | +| `contactPhone` | `string` | | 联系人电话 | +| `coverMaterialId` | `string` | | 封面素材ID | +| `cultureExperience` | `string` | | 文化体验（富文本JSON） | +| `description` | `string` | | 景区描述 | +| `detailContent` | `string` | | 详情内容（富文本JSON） | +| `district` | `string` | | 区/县 | +| `facilities` | `string[]` | | 设施编码列表 | +| `featureIntro` | `string` | | 特色介绍（富文本JSON） | +| `highlightSpots` | `string` | | 亮点景点（富文本JSON） | +| `highlights` | `string` | | 亮点简介 | +| `honors` | `string[]` | | 荣誉称号列表 | +| `interactiveExperience` | `string` | | 互动体验（富文本JSON） | +| `latitude` | `number` | | 纬度 | +| `longitude` | `number` | | 经度 | +| `name` | `string` | | 景区名称 | +| `openTime` | `string` | | 开放时间 | +| `photographyGuide` | `string` | | 摄影指南（富文本JSON） | +| `province` | `string` | | 省份 | +| `sceneryExperience` | `string` | | 风景体验（富文本JSON） | +| `sortOrder` | `int` | | 排序权重，越大越靠前 | +| `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +| `travelPrep` | `string` | | 出行准备（富文本JSON） | +| `videoMaterialIds` | `string[]` | | 视频素材ID列表 | + +**响应** `统一响应结果«景区详情»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `景区详情` | | 响应数据 | +|   `address` | `string` | | 详细地址 | +|   `arrangement` | `string` | | 行程安排（富文本JSON） | +|   `backupContactPerson` | `string` | | 备用联系人姓名 | +|   `backupContactPhone` | `string` | | 备用联系人电话 | +|   `bannerMaterialIds` | `string[]` | | 轮播图素材ID列表 | +|   `bannerUrls` | `string[]` | | 轮播图URL列表 | +|   `city` | `string` | | 城市（行政区划） | +|   `cityName` | `string` | | 所在城市（展示用） | +|   `closedDay` | `string` | | 闭园日 | +|   `contactPerson` | `string` | | 联系人姓名 | +|   `contactPhone` | `string` | | 联系人电话 | +|   `coverMaterialId` | `string` | | 封面素材ID | +|   `coverUrl` | `string` | | 封面图URL | +|   `createdAt` | `string` | | 创建时间 | +|   `createdBy` | `string` | | 创建人ID | +|   `createdByName` | `string` | | 创建人姓名 | +|   `cultureExperience` | `string` | | 文化体验（富文本JSON） | +|   `description` | `string` | | 景区描述 | +|   `detailContent` | `string` | | 详情内容（富文本JSON） | +|   `district` | `string` | | 区/县 | +|   `facilities` | `string[]` | | 设施编码列表 | +|   `facilityNames` | `string[]` | | 设施名称列表 | +|   `featureIntro` | `string` | | 特色介绍（富文本JSON） | +|   `highlightSpots` | `string` | | 亮点景点（富文本JSON） | +|   `highlights` | `string` | | 亮点简介 | +|   `honors` | `string[]` | | 荣誉称号列表 | +|   `interactiveExperience` | `string` | | 互动体验（富文本JSON） | +|   `latitude` | `number` | | 纬度 | +|   `longitude` | `number` | | 经度 | +|   `name` | `string` | | 景区名称 | +|   `openTime` | `string` | | 开放时间 | +|   `photographyGuide` | `string` | | 摄影指南（富文本JSON） | +|   `province` | `string` | | 省份 | +|   `rating` | `number` | | 评分 | +|   `reviewCount` | `int` | | 评论数 | +|   `sceneryExperience` | `string` | | 风景体验（富文本JSON） | +|   `scenicId` | `string` | | 景区ID | +|   `sortOrder` | `int` | | 排序权重 | +|   `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +|   `tags` | `景区标签[]` | | 标签列表 | +|     `createdAt` | `string` | | 创建时间 | +|     `tagColor` | `string` | | 标签颜色（十六进制） | +|     `tagId` | `string` | | 标签ID | +|     `tagName` | `string` | | 标签名称 | +|     `tagType` | `int` | | 标签类型：0=自定义 1=系统预设 | +|     `useCount` | `int` | | 使用次数 | +|   `travelPrep` | `string` | | 出行准备（富文本JSON） | +|   `updatedAt` | `string` | | 更新时间 | +|   `videoMaterialIds` | `string[]` | | 视频素材ID列表 | +|   `videoUrls` | `string[]` | | 视频URL列表 | +|   `viewCount` | `int` | | 浏览量 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/scenic/spot/{scenicId} + +**删除景区** + +软删除景区（设置deleted_at）。仅SUPER_ADMIN角色或创建者本人可删除。已上架的景区需先下架再删除。删除后会同时清理关联的素材引用。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `scenicId` | `integer` | | 景区ID | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/scenic/spot/{scenicId}/status + +**上下架切换** + +直接修改景区状态（跳过审批流程），仅限SUPER_ADMIN使用。普通管理员应使用「提交启用/禁用审批」接口。状态值：0=草稿，1=上架，2=下架。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `scenicId` | `integer` | | 景区ID | + +**请求体** `景区状态变更请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `scenicIds` | `string[]` | | 景区ID列表 | +| `status` | `int` | 是 | 目标状态：0=草稿 1=上架 2=下架 | + +**响应** `统一响应结果«Void»` + +--- + +### `POST` /admin/scenic/spot/{scenicId}/submit-approval + +**提交启用/禁用审批** + +向企微OA提交审批申请。targetStatus=1表示申请上架，targetStatus=2表示申请下架。提交后景区进入PENDING_APPROVAL状态，企微审批通过/拒绝后通过回调自动更新状态。返回企微审批单号spNo。同一景区不可重复提交未完成的审批。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `scenicId` | `integer` | | 景区ID | + +**请求体** `审批提交请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `reason` | `string` | 是 | 审批理由 | +| `targetStatus` | `int` | 是 | 目标状态：1=上架 2=下架 | + +**响应** `统一响应结果«Map«string,string»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `object` | | 响应数据 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/scenic/spots + +**景区列表** + +分页查询景区列表，支持按名称关键词、状态(0草稿/1上架/2下架)、城市等条件筛选。返回列表摘要信息（不含富文本详情），按sortOrder倒序+创建时间倒序排列。 + +**关联字典**： +- scenic_facility：景区设施（列表显示） +- scenic_honor：景区荣誉（列表显示） + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `city` | `string` | | 城市筛选（行政区划） | 杭州市 | +| `cityKeyword` | `string` | | 城市/区域关键词模糊搜索（匹配城市名、省份、地址） | 海拉尔 | +| `cityName` | `string` | | 城市名称筛选（展示用） | 杭州 | +| `facility` | `string` | | 设施编码筛选 | parking | +| `keyword` | `string` | | 搜索关键词（名称/地址模糊匹配） | 西湖 | +| `page` | `integer(int32)` | | 页码 | 1 | +| `pageSize` | `integer(int32)` | | 每页条数 | 20 | +| `province` | `string` | | 省份筛选 | 浙江省 | +| `sortBy` | `string` | | 排序字段：name/rating/viewCount/sortOrder/createdAt | sortOrder | +| `sortDir` | `string` | | 排序方向：asc/desc | desc | +| `status` | `integer(int32)` | | 状态筛选：0=草稿 1=上架 2=下架 | 1 | +| `tagId` | `integer(int64)` | | 标签ID筛选（单个） | | +| `tagIds` | `string` | | 标签ID筛选（多个，逗号分隔） | 1,2,3 | + +**响应** `统一响应结果«分页结果«景区列表项»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«景区列表项»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `景区列表项[]` | | 数据列表 | +|     `approvalNo` | `string` | | 审批编号（审批中时有值） | +|     `cityName` | `string` | | 所在城市 | +|     `contactPerson` | `string` | | 联系人姓名 | +|     `contactPhone` | `string` | | 联系人电话 | +|     `coverUrl` | `string` | | 封面图URL | +|     `createdAt` | `string` | | 创建时间 | +|     `highlights` | `string` | | 亮点简介 | +|     `honors` | `string[]` | | 荣誉称号列表 | +|     `latitude` | `number` | | 纬度 | +|     `longitude` | `number` | | 经度 | +|     `name` | `string` | | 景区名称 | +|     `pendingStatus` | `int` | | 待审批目标状态 | +|     `rating` | `number` | | 评分 | +|     `reviewCount` | `int` | | 评论数 | +|     `scenicId` | `string` | | 景区ID | +|     `sortOrder` | `int` | | 排序权重 | +|     `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +|     `tags` | `景区标签[]` | | 标签列表 | +|     `viewCount` | `int` | | 浏览量 | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/scenic/spots/batch + +**批量删除** + +批量软删除多个景区。权限校验同单个删除：仅SUPER_ADMIN或创建者可操作。部分失败不影响其他景区的删除。 + +**请求体** `景区批量删除请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `scenicIds` | `string[]` | 是 | 景区ID列表 | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/scenic/spots/batch/status + +**批量上下架** + +批量修改多个景区的状态。scenicIds为景区ID列表（字符串格式），status为目标状态。跳过审批流程，适用于批量管理场景。 + +**请求体** `景区状态变更请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `scenicIds` | `string[]` | | 景区ID列表 | +| `status` | `int` | 是 | 目标状态：0=草稿 1=上架 2=下架 | + +**响应** `统一响应结果«Void»` + +--- + +## 服务人员价格日历 + +### `GET` /admin/staff/type/{staffType}/prices + +**查询价格日历（按人员类型）** + +按月查询指定人员类型的每日服务费用和可调度状态。注意：价格日历按人员类型维度管理，非按个人维度。同一类型的所有人员共享同一套价格。 + +**关联字典**： +- staff_type（人员类型）→ staffType路径参数 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `staffType` | `string` | | 人员类型: GUIDE/GUIDE_ASSISTANT/PHOTOGRAPHER/LEADER/OTHER | + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `month` | `integer(int32)` | | 月份 | | +| `year` | `integer(int32)` | | 年份 | | + +**响应** `统一响应结果«服务人员价格日历VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `服务人员价格日历VO` | | 响应数据 | +|   `month` | `int` | | 月份 | +|   `prices` | `服务人员价格日历日VO[]` | | 价格日历明细列表 | +|     `costPrice` | `number` | | 日薪（元） | +|     `date` | `string` | | 日期 | +|     `remark` | `string` | | 备注 | +|     `status` | `int` | | 状态：0=不可用 1=可用 | +|     `stock` | `int` | | 库存数量 | +|     `stockUsed` | `int` | | 已用库存 | +|   `staffType` | `string` | | 人员类型: GUIDE/GUIDE_ASSISTANT/PHOTOGRAPHER/LEADER/OTHER | +|   `staffTypeName` | `string` | | 人员类型名称 | +|   `stockEnabled` | `boolean` | | 是否启用库存管理 | +|   `year` | `int` | | 年份 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/staff/type/{staffType}/prices + +**批量设置价格（按人员类型）** + +在指定日期范围内批量设置该类型人员的服务成本价和可调度状态。 + +**关联字典**： +- staff_type（人员类型）→ staffType路径参数 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `staffType` | `string` | | 人员类型: GUIDE/GUIDE_ASSISTANT/PHOTOGRAPHER/LEADER/OTHER | + +**请求体** `服务人员价格日历设置请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `costPrice` | `number` | 是 | 日薪（元） | +| `endDate` | `string` | 是 | 结束日期 | +| `excludeDates` | `LocalDate[]` | | 排除日期列表 | +| `remark` | `string` | | 备注 | +| `selectedWeekdays` | `int[]` | | 指定星期几（1=周一 7=周日） | +| `startDate` | `string` | 是 | 开始日期 | +| `status` | `int` | | 状态：0=不可用 1=可用 | +| `stock` | `int` | | 库存数量 | +| `weekdayOnly` | `boolean` | | 是否仅工作日 | +| `weekendOnly` | `boolean` | | 是否仅周末 | + +**响应** `统一响应结果«Void»` + +--- + +### `DELETE` /admin/staff/type/{staffType}/prices + +**清除价格日历（按人员类型）** + +删除指定日期范围内该类型人员的价格记录。日期格式：yyyy-MM-dd。 + +**关联字典**： +- staff_type（人员类型）→ staffType路径参数 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `staffType` | `string` | | 人员类型: GUIDE/GUIDE_ASSISTANT/PHOTOGRAPHER/LEADER/OTHER | + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `endDate` | `string(date)` | | 结束日期 | | +| `startDate` | `string(date)` | | 开始日期 | | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/staff/type/{staffType}/prices/batch-status + +**批量修改调度状态（按人员类型）** + +批量修改日期范围内的可调度状态，不影响价格。 + +**关联字典**： +- staff_type（人员类型）→ staffType路径参数 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `staffType` | `string` | | 人员类型: GUIDE/GUIDE_ASSISTANT/PHOTOGRAPHER/LEADER/OTHER | + +**请求体** `服务人员价格日历状态变更请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `endDate` | `string` | 是 | 结束日期 | +| `remark` | `string` | | 备注 | +| `startDate` | `string` | 是 | 开始日期 | +| `status` | `int` | 是 | 状态：0=不可用 1=可用 | + +**响应** `统一响应结果«Void»` + +--- + +## 服务人员标签管理 + +### `PUT` /admin/staff/batch/tags + +**批量添加/移除标签** + +对多个人员批量添加/移除标签。增量操作。 + +**请求体** `人员批量标签操作请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `addTagIds` | `long[]` | | 要添加的标签ID列表 | +| `removeTagIds` | `long[]` | | 要移除的标签ID列表 | +| `staffIds` | `long[]` | 是 | 人员ID列表 | + +**响应** `统一响应结果«Void»` + +--- + +### `POST` /admin/staff/tag + +**创建标签** + +创建预设标签，标签名不可重复。 + +**请求体** `服务人员标签创建请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagColor` | `string` | | 标签颜色（十六进制） | +| `tagName` | `string` | 是 | 标签名称 | + +**响应** `统一响应结果«服务人员标签VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `服务人员标签VO` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `tagColor` | `string` | | 标签颜色（十六进制） | +|   `tagId` | `string` | | 标签ID | +|   `tagName` | `string` | | 标签名称 | +|   `tagType` | `int` | | 标签类型：0=预设 1=自定义 | +|   `useCount` | `int` | | 使用次数 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/staff/tag/adhoc + +**解析自定义标签** + +按名称查找或自动创建标签。 + +**请求体** `服务人员标签创建请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagColor` | `string` | | 标签颜色（十六进制） | +| `tagName` | `string` | 是 | 标签名称 | + +**响应** `统一响应结果«服务人员标签VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `服务人员标签VO` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `tagColor` | `string` | | 标签颜色（十六进制） | +|   `tagId` | `string` | | 标签ID | +|   `tagName` | `string` | | 标签名称 | +|   `tagType` | `int` | | 标签类型：0=预设 1=自定义 | +|   `useCount` | `int` | | 使用次数 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/staff/tag/{tagId} + +**更新标签** + +修改标签名称或颜色。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagId` | `integer` | | 标签ID | + +**请求体** `服务人员标签更新请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagColor` | `string` | | 标签颜色（十六进制） | +| `tagName` | `string` | | 标签名称 | + +**响应** `统一响应结果«服务人员标签VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `服务人员标签VO` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `tagColor` | `string` | | 标签颜色（十六进制） | +|   `tagId` | `string` | | 标签ID | +|   `tagName` | `string` | | 标签名称 | +|   `tagType` | `int` | | 标签类型：0=预设 1=自定义 | +|   `useCount` | `int` | | 使用次数 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/staff/tag/{tagId} + +**删除标签** + +删除标签并解除所有人员与该标签的关联。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagId` | `integer` | | 标签ID | + +**响应** `统一响应结果«Void»` + +--- + +### `GET` /admin/staff/tags + +**预设标签列表（分页）** + +分页查询服务人员标签库，支持按关键词搜索。 + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `keyword` | `string` | | 关键词 | | +| `page` | `integer(int32)` | | 页码 | | +| `pageSize` | `integer(int32)` | | 每页条数 | | + +**响应** `统一响应结果«分页结果«服务人员标签VO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«服务人员标签VO»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `服务人员标签VO[]` | | 数据列表 | +|     `createdAt` | `string` | | 创建时间 | +|     `tagColor` | `string` | | 标签颜色（十六进制） | +|     `tagId` | `string` | | 标签ID | +|     `tagName` | `string` | | 标签名称 | +|     `tagType` | `int` | | 标签类型：0=预设 1=自定义 | +|     `useCount` | `int` | | 使用次数 | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/staff/tags/all + +**全部标签列表** + +不分页返回所有标签，用于人员编辑时的标签选择。 + +**响应** `统一响应结果«List«服务人员标签VO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `服务人员标签VO[]` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `tagColor` | `string` | | 标签颜色（十六进制） | +|   `tagId` | `string` | | 标签ID | +|   `tagName` | `string` | | 标签名称 | +|   `tagType` | `int` | | 标签类型：0=预设 1=自定义 | +|   `useCount` | `int` | | 使用次数 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/staff/{staffId}/tags + +**设置人员标签** + +全量替换指定人员的标签列表。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `staffId` | `integer` | | 人员ID | + +**请求体** `设置人员标签请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagIds` | `long[]` | 是 | 标签ID列表 | + +**响应** `统一响应结果«Void»` + +--- + +## 服务人员管理 + +### `POST` /admin/staff + +**创建服务人员** + +新建服务人员（导游/领队/摄影师/助理等）。人员类型(staffType)决定了其在价格日历中的归类。需走企微审批上架后才能被产品引用。 + +**关联字典**： +- staff_type：人员类型（表单选择） +- guide_level：导游等级（表单选择） +- driver_license_type：驾照类型（表单选择） +- language：语言能力（表单多选） +- guide_specialty：导游专长（表单多选） +- guide_service_area：服务区域（表单多选） + +**请求体** `服务人员创建请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `bannerMaterialIds` | `string[]` | | 横幅素材ID列表 | +| `birthDate` | `string` | | 出生日期 | +| `certificateUrls` | `string[]` | | 资质证书URL列表 | +| `coverMaterialId` | `string` | | 封面素材ID | +| `description` | `string` | | 人员描述 | +| `emergencyContact` | `string` | | 紧急联系人 | +| `emergencyPhone` | `string` | | 紧急联系电话 | +| `ethnicity` | `string` | | 民族 | +| `gender` | `int` | | 性别：0=女 1=男 | +| `guideCardNo` | `string` | | 导游证号 | +| `guideLanguage` | `string` | | 导游语种 | +| `guideLevel` | `string` | | 导游等级 | +| `highlights` | `string` | | 人员亮点 | +| `idCardUrls` | `string[]` | | 证件照URL列表 | +| `languages` | `string[]` | | 掌握语言（JSON数组） | +| `licenseExpiry` | `string` | | 执照到期日 | +| `licenseNo` | `string` | | 执照编号 | +| `licenseType` | `string` | | 执照类型 | +| `name` | `string` | 是 | 姓名 | +| `nationality` | `string` | | 国籍 | +| `nativePlace` | `string` | | 籍贯 | +| `phone` | `string` | | 手机号 | +| `photoUrls` | `string[]` | | 个人照片URL列表 | +| `priceExcludes` | `string` | | 价格不包含内容 | +| `priceIncludes` | `string` | | 价格包含内容 | +| `serviceAreas` | `string[]` | | 服务区域（JSON数组） | +| `sortOrder` | `int` | | 排序权重，值越大越靠前 | +| `specialties` | `string[]` | | 擅长领域（JSON数组） | +| `staffType` | `string` | 是 | 人员类型 | +| `videoMaterialIds` | `string[]` | | 视频素材ID列表 | +| `yearsOfExperience` | `int` | | 从业年限 | + +**响应** `统一响应结果«服务人员详情VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `服务人员详情VO` | | 响应数据 | +|   `bannerMaterialIds` | `string[]` | | 横幅素材ID列表 | +|   `bannerUrls` | `string[]` | | 横幅图URL列表 | +|   `birthDate` | `string` | | 出生日期 | +|   `certificateUrls` | `string[]` | | 资质证书URL列表 | +|   `coverMaterialId` | `string` | | 封面素材ID | +|   `coverUrl` | `string` | | 封面图URL | +|   `createdAt` | `string` | | 创建时间 | +|   `createdBy` | `string` | | 创建者ID | +|   `description` | `string` | | 人员描述 | +|   `emergencyContact` | `string` | | 紧急联系人 | +|   `emergencyPhone` | `string` | | 紧急联系电话 | +|   `ethnicity` | `string` | | 民族 | +|   `gender` | `int` | | 性别：0=女 1=男 | +|   `guideCardNo` | `string` | | 导游证号 | +|   `guideLanguage` | `string` | | 导游语种 | +|   `guideLevel` | `string` | | 导游等级 | +|   `highlights` | `string` | | 人员亮点 | +|   `idCardUrls` | `string[]` | | 证件照URL列表 | +|   `languages` | `string[]` | | 掌握语言 | +|   `licenseExpiry` | `string` | | 执照到期日 | +|   `licenseNo` | `string` | | 执照编号 | +|   `licenseType` | `string` | | 执照类型 | +|   `name` | `string` | | 姓名 | +|   `nationality` | `string` | | 国籍 | +|   `nativePlace` | `string` | | 籍贯 | +|   `phone` | `string` | | 手机号 | +|   `photoUrls` | `string[]` | | 个人照片URL列表 | +|   `priceExcludes` | `string` | | 价格不包含内容 | +|   `priceIncludes` | `string` | | 价格包含内容 | +|   `rating` | `number` | | 评分 | +|   `reviewCount` | `int` | | 评价数 | +|   `serviceAreas` | `string[]` | | 服务区域 | +|   `sortOrder` | `int` | | 排序权重 | +|   `specialties` | `string[]` | | 擅长领域 | +|   `staffId` | `string` | | 人员ID | +|   `staffType` | `string` | | 人员类型 | +|   `status` | `int` | | 状态：0=禁用 1=启用 | +|   `tags` | `服务人员标签VO[]` | | 标签列表 | +|     `createdAt` | `string` | | 创建时间 | +|     `tagColor` | `string` | | 标签颜色（十六进制） | +|     `tagId` | `string` | | 标签ID | +|     `tagName` | `string` | | 标签名称 | +|     `tagType` | `int` | | 标签类型：0=预设 1=自定义 | +|     `useCount` | `int` | | 使用次数 | +|   `updatedAt` | `string` | | 更新时间 | +|   `videoMaterialIds` | `string[]` | | 视频素材ID列表 | +|   `videoUrls` | `string[]` | | 视频URL列表 | +|   `viewCount` | `int` | | 浏览量 | +|   `yearsOfExperience` | `int` | | 从业年限 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/staff/batch + +**批量删除** + +批量软删除多个服务人员。仅SUPER_ADMIN或创建者可操作。 + +**请求体** `人员批量删除请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `staffIds` | `long[]` | 是 | 人员ID列表 | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/staff/batch/status + +**批量更新状态** + +批量修改多个服务人员的状态，跳过审批流程。 + +**请求体** `人员状态请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `staffIds` | `long[]` | | 人员ID列表（批量操作时使用） | +| `status` | `int` | 是 | 目标状态：0=草稿 1=上架 2=下架 | + +**响应** `统一响应结果«Void»` + +--- + +### `GET` /admin/staff/list + +**服务人员列表** + +分页查询服务人员列表，支持按姓名、状态、人员类型等条件筛选。 + +**关联字典**： +- staff_type：人员类型（筛选+列表显示） +- guide_level：导游等级（列表显示） +- driver_license_type：驾照类型（列表显示） +- language：语言能力（列表显示） +- guide_specialty：导游专长（列表显示） +- guide_service_area：服务区域（列表显示） + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `keyword` | `string` | | 搜索关键词（姓名/描述模糊匹配） | 张导 | +| `page` | `integer(int32)` | | 页码 | 1 | +| `pageSize` | `integer(int32)` | | 每页条数 | 20 | +| `sortBy` | `string` | | 排序字段 | createdAt | +| `sortDir` | `string` | | 排序方向：asc/desc | desc | +| `staffType` | `string` | | 人员类型筛选 | GUIDE | +| `status` | `integer(int32)` | | 状态筛选：0=禁用 1=启用 | 1 | +| `tagId` | `integer(int64)` | | 标签ID（单个） | | +| `tagIds` | `string` | | 标签ID列表（逗号分隔） | 1,2,3 | + +**响应** `统一响应结果«分页结果«服务人员列表VO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«服务人员列表VO»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `服务人员列表VO[]` | | 数据列表 | +|     `approvalNo` | `string` | | 审批单号 | +|     `coverUrl` | `string` | | 封面图URL | +|     `createdAt` | `string` | | 创建时间 | +|     `highlights` | `string` | | 人员亮点 | +|     `name` | `string` | | 姓名 | +|     `pendingStatus` | `int` | | 待审批目标状态 | +|     `phone` | `string` | | 手机号 | +|     `rating` | `number` | | 评分 | +|     `sortOrder` | `int` | | 排序权重 | +|     `staffId` | `string` | | 人员ID | +|     `staffType` | `string` | | 人员类型 | +|     `status` | `int` | | 状态：0=禁用 1=启用 | +|     `tags` | `服务人员标签VO[]` | | 标签列表 | +|     `viewCount` | `int` | | 浏览量 | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/staff/{staffId} + +**服务人员详情** + +获取服务人员完整信息，包含素材URL、标签、技能描述等。 + +**关联字典**： +- staff_type：人员类型（详情显示） +- guide_level：导游等级（详情显示） +- driver_license_type：驾照类型（详情显示） +- language：语言能力（详情显示） +- guide_specialty：导游专长（详情显示） +- guide_service_area：服务区域（详情显示） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `staffId` | `integer` | | 人员ID | + +**响应** `统一响应结果«服务人员详情VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `服务人员详情VO` | | 响应数据 | +|   `bannerMaterialIds` | `string[]` | | 横幅素材ID列表 | +|   `bannerUrls` | `string[]` | | 横幅图URL列表 | +|   `birthDate` | `string` | | 出生日期 | +|   `certificateUrls` | `string[]` | | 资质证书URL列表 | +|   `coverMaterialId` | `string` | | 封面素材ID | +|   `coverUrl` | `string` | | 封面图URL | +|   `createdAt` | `string` | | 创建时间 | +|   `createdBy` | `string` | | 创建者ID | +|   `description` | `string` | | 人员描述 | +|   `emergencyContact` | `string` | | 紧急联系人 | +|   `emergencyPhone` | `string` | | 紧急联系电话 | +|   `ethnicity` | `string` | | 民族 | +|   `gender` | `int` | | 性别：0=女 1=男 | +|   `guideCardNo` | `string` | | 导游证号 | +|   `guideLanguage` | `string` | | 导游语种 | +|   `guideLevel` | `string` | | 导游等级 | +|   `highlights` | `string` | | 人员亮点 | +|   `idCardUrls` | `string[]` | | 证件照URL列表 | +|   `languages` | `string[]` | | 掌握语言 | +|   `licenseExpiry` | `string` | | 执照到期日 | +|   `licenseNo` | `string` | | 执照编号 | +|   `licenseType` | `string` | | 执照类型 | +|   `name` | `string` | | 姓名 | +|   `nationality` | `string` | | 国籍 | +|   `nativePlace` | `string` | | 籍贯 | +|   `phone` | `string` | | 手机号 | +|   `photoUrls` | `string[]` | | 个人照片URL列表 | +|   `priceExcludes` | `string` | | 价格不包含内容 | +|   `priceIncludes` | `string` | | 价格包含内容 | +|   `rating` | `number` | | 评分 | +|   `reviewCount` | `int` | | 评价数 | +|   `serviceAreas` | `string[]` | | 服务区域 | +|   `sortOrder` | `int` | | 排序权重 | +|   `specialties` | `string[]` | | 擅长领域 | +|   `staffId` | `string` | | 人员ID | +|   `staffType` | `string` | | 人员类型 | +|   `status` | `int` | | 状态：0=禁用 1=启用 | +|   `tags` | `服务人员标签VO[]` | | 标签列表 | +|     `createdAt` | `string` | | 创建时间 | +|     `tagColor` | `string` | | 标签颜色（十六进制） | +|     `tagId` | `string` | | 标签ID | +|     `tagName` | `string` | | 标签名称 | +|     `tagType` | `int` | | 标签类型：0=预设 1=自定义 | +|     `useCount` | `int` | | 使用次数 | +|   `updatedAt` | `string` | | 更新时间 | +|   `videoMaterialIds` | `string[]` | | 视频素材ID列表 | +|   `videoUrls` | `string[]` | | 视频URL列表 | +|   `viewCount` | `int` | | 浏览量 | +|   `yearsOfExperience` | `int` | | 从业年限 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/staff/{staffId} + +**更新服务人员** + +更新服务人员基本信息，不改变当前状态。 + +**关联字典**： +- staff_type：人员类型（表单选择） +- guide_level：导游等级（表单选择） +- driver_license_type：驾照类型（表单选择） +- language：语言能力（表单多选） +- guide_specialty：导游专长（表单多选） +- guide_service_area：服务区域（表单多选） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `staffId` | `integer` | | 人员ID | + +**请求体** `服务人员更新请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `bannerMaterialIds` | `string[]` | | 横幅素材ID列表 | +| `birthDate` | `string` | | 出生日期 | +| `certificateUrls` | `string[]` | | 资质证书URL列表 | +| `coverMaterialId` | `string` | | 封面素材ID | +| `description` | `string` | | 人员描述 | +| `emergencyContact` | `string` | | 紧急联系人 | +| `emergencyPhone` | `string` | | 紧急联系电话 | +| `ethnicity` | `string` | | 民族 | +| `gender` | `int` | | 性别：0=女 1=男 | +| `guideCardNo` | `string` | | 导游证号 | +| `guideLanguage` | `string` | | 导游语种 | +| `guideLevel` | `string` | | 导游等级 | +| `highlights` | `string` | | 人员亮点 | +| `idCardUrls` | `string[]` | | 证件照URL列表 | +| `languages` | `string[]` | | 掌握语言（JSON数组） | +| `licenseExpiry` | `string` | | 执照到期日 | +| `licenseNo` | `string` | | 执照编号 | +| `licenseType` | `string` | | 执照类型 | +| `name` | `string` | | 姓名 | +| `nationality` | `string` | | 国籍 | +| `nativePlace` | `string` | | 籍贯 | +| `phone` | `string` | | 手机号 | +| `photoUrls` | `string[]` | | 个人照片URL列表 | +| `priceExcludes` | `string` | | 价格不包含内容 | +| `priceIncludes` | `string` | | 价格包含内容 | +| `serviceAreas` | `string[]` | | 服务区域（JSON数组） | +| `sortOrder` | `int` | | 排序权重，值越大越靠前 | +| `specialties` | `string[]` | | 擅长领域（JSON数组） | +| `staffType` | `string` | | 人员类型 | +| `videoMaterialIds` | `string[]` | | 视频素材ID列表 | +| `yearsOfExperience` | `int` | | 从业年限 | + +**响应** `统一响应结果«服务人员详情VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `服务人员详情VO` | | 响应数据 | +|   `bannerMaterialIds` | `string[]` | | 横幅素材ID列表 | +|   `bannerUrls` | `string[]` | | 横幅图URL列表 | +|   `birthDate` | `string` | | 出生日期 | +|   `certificateUrls` | `string[]` | | 资质证书URL列表 | +|   `coverMaterialId` | `string` | | 封面素材ID | +|   `coverUrl` | `string` | | 封面图URL | +|   `createdAt` | `string` | | 创建时间 | +|   `createdBy` | `string` | | 创建者ID | +|   `description` | `string` | | 人员描述 | +|   `emergencyContact` | `string` | | 紧急联系人 | +|   `emergencyPhone` | `string` | | 紧急联系电话 | +|   `ethnicity` | `string` | | 民族 | +|   `gender` | `int` | | 性别：0=女 1=男 | +|   `guideCardNo` | `string` | | 导游证号 | +|   `guideLanguage` | `string` | | 导游语种 | +|   `guideLevel` | `string` | | 导游等级 | +|   `highlights` | `string` | | 人员亮点 | +|   `idCardUrls` | `string[]` | | 证件照URL列表 | +|   `languages` | `string[]` | | 掌握语言 | +|   `licenseExpiry` | `string` | | 执照到期日 | +|   `licenseNo` | `string` | | 执照编号 | +|   `licenseType` | `string` | | 执照类型 | +|   `name` | `string` | | 姓名 | +|   `nationality` | `string` | | 国籍 | +|   `nativePlace` | `string` | | 籍贯 | +|   `phone` | `string` | | 手机号 | +|   `photoUrls` | `string[]` | | 个人照片URL列表 | +|   `priceExcludes` | `string` | | 价格不包含内容 | +|   `priceIncludes` | `string` | | 价格包含内容 | +|   `rating` | `number` | | 评分 | +|   `reviewCount` | `int` | | 评价数 | +|   `serviceAreas` | `string[]` | | 服务区域 | +|   `sortOrder` | `int` | | 排序权重 | +|   `specialties` | `string[]` | | 擅长领域 | +|   `staffId` | `string` | | 人员ID | +|   `staffType` | `string` | | 人员类型 | +|   `status` | `int` | | 状态：0=禁用 1=启用 | +|   `tags` | `服务人员标签VO[]` | | 标签列表 | +|     `createdAt` | `string` | | 创建时间 | +|     `tagColor` | `string` | | 标签颜色（十六进制） | +|     `tagId` | `string` | | 标签ID | +|     `tagName` | `string` | | 标签名称 | +|     `tagType` | `int` | | 标签类型：0=预设 1=自定义 | +|     `useCount` | `int` | | 使用次数 | +|   `updatedAt` | `string` | | 更新时间 | +|   `videoMaterialIds` | `string[]` | | 视频素材ID列表 | +|   `videoUrls` | `string[]` | | 视频URL列表 | +|   `viewCount` | `int` | | 浏览量 | +|   `yearsOfExperience` | `int` | | 从业年限 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/staff/{staffId} + +**删除服务人员** + +软删除服务人员。仅SUPER_ADMIN或创建者可操作。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `staffId` | `integer` | | 人员ID | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/staff/{staffId}/status + +**更新状态** + +直接修改人员状态（跳过审批），仅限SUPER_ADMIN。状态值：0=草稿，1=启用，2=禁用。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `staffId` | `integer` | | 人员ID | + +**请求体** `人员状态请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `staffIds` | `long[]` | | 人员ID列表（批量操作时使用） | +| `status` | `int` | 是 | 目标状态：0=草稿 1=上架 2=下架 | + +**响应** `统一响应结果«Void»` + +--- + +### `POST` /admin/staff/{staffId}/submit-approval + +**提交审批** + +向企微OA提交人员启用/禁用审批。targetStatus=1申请启用，targetStatus=2申请禁用。返回审批单号spNo。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `staffId` | `integer` | | 人员ID | + +**请求体** `人员审批提交请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `reason` | `string` | | 审批原因 | +| `targetStatus` | `int` | 是 | 目标状态 | + +**响应** `统一响应结果«Map«string,string»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `object` | | 响应数据 | +| `message` | `string` | | 响应消息 | + +--- + +## 服务价格日历 + +### `GET` /admin/service/item/{serviceId}/prices + +**查询价格日历** + +按月查询增值服务的每日价格和可售状态。仅付费服务(isPaid=true)需要设置价格日历。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `serviceId` | `integer` | | 服务ID | + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `month` | `integer(int32)` | | 月份 | | +| `year` | `integer(int32)` | | 年份 | | + +**响应** `统一响应结果«服务项价格日历VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `服务项价格日历VO` | | 响应数据 | +|   `month` | `int` | | 月份 | +|   `prices` | `服务项价格日历日VO[]` | | 价格日历明细列表 | +|     `costPrice` | `number` | | 成本价（元） | +|     `date` | `string` | | 日期 | +|     `remark` | `string` | | 备注 | +|     `status` | `int` | | 状态：0=不可售 1=可售 | +|     `stock` | `int` | | 库存数量 | +|     `stockUsed` | `int` | | 已用库存 | +|   `serviceId` | `string` | | 服务项ID | +|   `serviceName` | `string` | | 服务项名称 | +|   `stockEnabled` | `boolean` | | 是否启用库存管理 | +|   `year` | `int` | | 年份 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/service/item/{serviceId}/prices + +**批量设置价格** + +在指定日期范围内批量设置服务的成本价和可售状态。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `serviceId` | `integer` | | 服务ID | + +**请求体** `服务项价格日历设置请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `costPrice` | `number` | 是 | 成本价（元） | +| `endDate` | `string` | 是 | 结束日期（yyyy-MM-dd） | +| `excludeDates` | `string[]` | | 排除日期列表 | +| `remark` | `string` | | 备注 | +| `selectedWeekdays` | `int[]` | | 指定星期几（1=周一 7=周日） | +| `startDate` | `string` | 是 | 开始日期（yyyy-MM-dd） | +| `status` | `int` | | 状态：0=不可售 1=可售 | +| `stock` | `int` | | 库存数量 | +| `weekdayOnly` | `boolean` | | 是否仅工作日 | +| `weekendOnly` | `boolean` | | 是否仅周末 | + +**响应** `统一响应结果«Void»` + +--- + +### `DELETE` /admin/service/item/{serviceId}/prices + +**批量清除价格** + +删除指定日期范围内的价格记录。日期格式：yyyy-MM-dd。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `serviceId` | `integer` | | 服务ID | + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `endDate` | `string` | | 结束日期 | | +| `startDate` | `string` | | 开始日期 | | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/service/item/{serviceId}/prices/batch-status + +**批量修改可售状态** + +批量修改日期范围内的可售状态，不影响价格。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `serviceId` | `integer` | | 服务ID | + +**请求体** `服务项价格日历状态变更请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `endDate` | `string` | 是 | 结束日期（yyyy-MM-dd） | +| `remark` | `string` | | 备注 | +| `startDate` | `string` | 是 | 开始日期（yyyy-MM-dd） | +| `status` | `int` | 是 | 状态：0=不可售 1=可售 | + +**响应** `统一响应结果«Void»` + +--- + +## 服务标签管理 + +### `PUT` /admin/service/item/{serviceId}/tags + +**更新服务标签** + +全量替换指定服务的标签列表。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `serviceId` | `integer` | | 服务ID | + +**请求体** `服务项标签更新请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagIds` | `string[]` | | 标签ID列表（全量替换） | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/service/items/batch/tags + +**批量打标签** + +对多个服务批量添加/移除标签。增量操作。 + +**请求体** `服务项批量标签操作请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `addTagIds` | `string[]` | | 要添加的标签ID列表 | +| `removeTagIds` | `string[]` | | 要移除的标签ID列表 | +| `serviceIds` | `string[]` | 是 | 服务ID列表 | + +**响应** `统一响应结果«Void»` + +--- + +### `POST` /admin/service/tag + +**创建管理标签** + +创建预设标签，标签名不可重复。 + +**请求体** `服务标签创建请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagColor` | `string` | | 标签颜色（十六进制） | +| `tagName` | `string` | 是 | 标签名称 | + +**响应** `统一响应结果«服务标签VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `服务标签VO` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `tagColor` | `string` | | 标签颜色（十六进制） | +|   `tagId` | `string` | | 标签ID | +|   `tagName` | `string` | | 标签名称 | +|   `tagType` | `int` | | 标签类型：0=自定义 1=系统 | +|   `useCount` | `int` | | 使用次数 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/service/tag/adhoc + +**解析自定义标签** + +按名称查找或自动创建标签。 + +**请求体** `服务标签创建请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagColor` | `string` | | 标签颜色（十六进制） | +| `tagName` | `string` | 是 | 标签名称 | + +**响应** `统一响应结果«服务标签VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `服务标签VO` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `tagColor` | `string` | | 标签颜色（十六进制） | +|   `tagId` | `string` | | 标签ID | +|   `tagName` | `string` | | 标签名称 | +|   `tagType` | `int` | | 标签类型：0=自定义 1=系统 | +|   `useCount` | `int` | | 使用次数 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/service/tag/{tagId} + +**编辑标签** + +修改标签名称或颜色，所有关联服务自动生效。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagId` | `integer` | | 标签ID | + +**请求体** `服务标签更新请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagColor` | `string` | | 标签颜色（十六进制） | +| `tagName` | `string` | | 标签名称 | + +**响应** `统一响应结果«服务标签VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `服务标签VO` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `tagColor` | `string` | | 标签颜色（十六进制） | +|   `tagId` | `string` | | 标签ID | +|   `tagName` | `string` | | 标签名称 | +|   `tagType` | `int` | | 标签类型：0=自定义 1=系统 | +|   `useCount` | `int` | | 使用次数 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/service/tag/{tagId} + +**删除标签** + +删除标签并解除所有服务与该标签的关联。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagId` | `integer` | | 标签ID | + +**响应** `统一响应结果«Void»` + +--- + +### `GET` /admin/service/tags + +**获取管理标签列表（分页）** + +分页查询增值服务标签库，支持按关键词搜索。 + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `keyword` | `string` | | 关键词 | | +| `page` | `integer(int32)` | | 页码 | | +| `pageSize` | `integer(int32)` | | 每页条数 | | + +**响应** `统一响应结果«分页结果«服务标签VO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«服务标签VO»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `服务标签VO[]` | | 数据列表 | +|     `createdAt` | `string` | | 创建时间 | +|     `tagColor` | `string` | | 标签颜色（十六进制） | +|     `tagId` | `string` | | 标签ID | +|     `tagName` | `string` | | 标签名称 | +|     `tagType` | `int` | | 标签类型：0=自定义 1=系统 | +|     `useCount` | `int` | | 使用次数 | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/service/tags/all + +**获取全部标签** + +不分页返回所有标签，用于服务编辑时的标签选择。 + +**响应** `统一响应结果«List«服务标签VO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `服务标签VO[]` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `tagColor` | `string` | | 标签颜色（十六进制） | +|   `tagId` | `string` | | 标签ID | +|   `tagName` | `string` | | 标签名称 | +|   `tagType` | `int` | | 标签类型：0=自定义 1=系统 | +|   `useCount` | `int` | | 使用次数 | +| `message` | `string` | | 响应消息 | + +--- + +## 游玩项目价格日历 + +### `GET` /admin/activity/item/{activityId}/prices + +**查询价格日历** + +按月查询游玩项目的每日价格和可接待状态。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `activityId` | `integer` | | 游玩项目ID | + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `month` | `integer(int32)` | | 月份 | | +| `year` | `integer(int32)` | | 年份 | | + +**响应** `统一响应结果«活动价格日历视图»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `活动价格日历视图` | | 响应数据 | +|   `activityId` | `string` | | 活动项目ID | +|   `activityName` | `string` | | 活动项目名称 | +|   `month` | `int` | | 月份 | +|   `prices` | `活动价格日历日视图[]` | | 价格日历每日数据列表 | +|     `costPrice` | `number` | | 成本价（元） | +|     `date` | `string` | | 日期 | +|     `remark` | `string` | | 备注 | +|     `status` | `int` | | 状态：0=不可用 1=可用 | +|     `stock` | `int` | | 库存数量 | +|     `stockUsed` | `int` | | 已用库存 | +|   `stockEnabled` | `boolean` | | 是否启用库存管理 | +|   `year` | `int` | | 年份 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/activity/item/{activityId}/prices + +**批量设置价格** + +在指定日期范围内批量设置成本价和可接待状态。支持按星期过滤和排除特定日期。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `activityId` | `integer` | | 游玩项目ID | + +**请求体** `活动价格日历设置请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `costPrice` | `number` | 是 | 成本价（元） | +| `endDate` | `string` | 是 | 结束日期 | +| `excludeDates` | `string[]` | | 排除日期列表 | +| `remark` | `string` | | 备注 | +| `selectedWeekdays` | `int[]` | | 指定星期几（1=周一 7=周日） | +| `startDate` | `string` | 是 | 开始日期 | +| `status` | `int` | | 状态：0=不可用 1=可用 | +| `stock` | `int` | | 库存数量 | +| `weekdayOnly` | `boolean` | | 是否仅工作日 | +| `weekendOnly` | `boolean` | | 是否仅周末 | + +**响应** `统一响应结果«Void»` + +--- + +### `DELETE` /admin/activity/item/{activityId}/prices + +**批量清除价格** + +删除指定日期范围内的所有价格记录。日期格式：yyyy-MM-dd。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `activityId` | `integer` | | 游玩项目ID | + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `endDate` | `string` | | 结束日期 | | +| `startDate` | `string` | | 开始日期 | | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/activity/item/{activityId}/prices/batch-status + +**批量修改可接待状态** + +批量修改指定日期范围内的可接待状态，不影响价格。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `activityId` | `integer` | | 游玩项目ID | + +**请求体** `活动价格日历状态变更请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `endDate` | `string` | 是 | 结束日期 | +| `remark` | `string` | | 备注 | +| `startDate` | `string` | 是 | 开始日期 | +| `status` | `int` | 是 | 状态：0=不可用 1=可用 | + +**响应** `统一响应结果«Void»` + +--- + +## 游玩项目标签管理 + +### `PUT` /admin/activity/item/{activityId}/tags + +**更新项目标签** + +全量替换指定项目的标签列表。传入tagIds为最终关联的标签ID列表，为空则清除所有标签。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `activityId` | `integer` | | 游玩项目ID | + +**请求体** `活动项目标签更新请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagIds` | `string[]` | | 标签ID列表 | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/activity/items/batch/tags + +**批量打标签** + +对多个项目批量添加/移除标签。增量操作，不影响未指定的标签。 + +**请求体** `活动项目批量标签操作请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `activityIds` | `string[]` | 是 | 活动项目ID列表 | +| `addTagIds` | `string[]` | | 要添加的标签ID列表 | +| `removeTagIds` | `string[]` | | 要移除的标签ID列表 | + +**响应** `统一响应结果«Void»` + +--- + +### `POST` /admin/activity/tag + +**创建管理标签** + +创建预设标签，标签名不可重复。可指定颜色(tagColor)，默认#409EFF。 + +**请求体** `活动标签创建请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagColor` | `string` | | 标签颜色（十六进制） | +| `tagName` | `string` | 是 | 标签名称 | + +**响应** `统一响应结果«活动标签视图»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `活动标签视图` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `tagColor` | `string` | | 标签颜色 | +|   `tagId` | `string` | | 标签ID | +|   `tagName` | `string` | | 标签名称 | +|   `tagType` | `int` | | 标签类型：1=系统标签 2=自定义标签 | +|   `useCount` | `int` | | 使用次数 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/activity/tag/adhoc + +**解析自定义标签** + +按名称查找或自动创建标签。用于项目编辑时快速输入新标签。 + +**请求体** `活动标签创建请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagColor` | `string` | | 标签颜色（十六进制） | +| `tagName` | `string` | 是 | 标签名称 | + +**响应** `统一响应结果«活动标签视图»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `活动标签视图` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `tagColor` | `string` | | 标签颜色 | +|   `tagId` | `string` | | 标签ID | +|   `tagName` | `string` | | 标签名称 | +|   `tagType` | `int` | | 标签类型：1=系统标签 2=自定义标签 | +|   `useCount` | `int` | | 使用次数 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/activity/tag/{tagId} + +**编辑标签** + +修改标签名称或颜色，所有关联项目自动生效。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagId` | `integer` | | 标签ID | + +**请求体** `活动标签更新请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagColor` | `string` | | 标签颜色（十六进制） | +| `tagName` | `string` | | 标签名称 | + +**响应** `统一响应结果«活动标签视图»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `活动标签视图` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `tagColor` | `string` | | 标签颜色 | +|   `tagId` | `string` | | 标签ID | +|   `tagName` | `string` | | 标签名称 | +|   `tagType` | `int` | | 标签类型：1=系统标签 2=自定义标签 | +|   `useCount` | `int` | | 使用次数 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/activity/tag/{tagId} + +**删除标签** + +删除标签并自动解除所有项目与该标签的关联。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagId` | `integer` | | 标签ID | + +**响应** `统一响应结果«Void»` + +--- + +### `GET` /admin/activity/tags + +**获取管理标签列表（分页）** + +分页查询游玩项目标签库，支持按关键词搜索。包含预设标签和自定义标签。 + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `keyword` | `string` | | 关键词 | | +| `page` | `integer(int32)` | | 页码 | | +| `pageSize` | `integer(int32)` | | 每页条数 | | + +**响应** `统一响应结果«分页结果«活动标签视图»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«活动标签视图»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `活动标签视图[]` | | 数据列表 | +|     `createdAt` | `string` | | 创建时间 | +|     `tagColor` | `string` | | 标签颜色 | +|     `tagId` | `string` | | 标签ID | +|     `tagName` | `string` | | 标签名称 | +|     `tagType` | `int` | | 标签类型：1=系统标签 2=自定义标签 | +|     `useCount` | `int` | | 使用次数 | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/activity/tags/all + +**获取全部标签** + +不分页返回所有标签，用于项目编辑时的标签选择下拉。 + +**响应** `统一响应结果«List«活动标签视图»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `活动标签视图[]` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `tagColor` | `string` | | 标签颜色 | +|   `tagId` | `string` | | 标签ID | +|   `tagName` | `string` | | 标签名称 | +|   `tagType` | `int` | | 标签类型：1=系统标签 2=自定义标签 | +|   `useCount` | `int` | | 使用次数 | +| `message` | `string` | | 响应消息 | + +--- + +## 游玩项目管理 + +### `POST` /admin/activity/item + +**创建游玩项目** + +新建游玩项目资源（如漂流、骑行、篝火晚会等），初始状态为草稿(status=0)。需通过「提交启用/禁用审批」走企微审批后上架。支持按项收费(PER_ITEM)和按人收费(PER_PERSON)两种计费方式。 + +**关联字典**： +- activity_category：活动分类（表单选择） +- activity_billing_type：计费方式（表单选择） + +**请求体** `活动项目创建请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `address` | `string` | | 详细地址 | +| `ageMax` | `int` | | 最大年龄限制 | +| `ageMin` | `int` | | 最小年龄限制 | +| `bannerMaterialIds` | `string[]` | | 轮播图素材ID列表 | +| `bestSeason` | `string` | | 最佳季节 | +| `billingType` | `string` | 是 | 计费方式：PER_PERSON=按人 PER_GROUP=按团 PER_HOUR=按时 | +| `categoryCode` | `string` | 是 | 分类编码 | +| `city` | `string` | | 城市 | +| `contactPhone` | `string` | | 联系电话 | +| `coverMaterialId` | `string` | | 封面素材ID | +| `dailyCapacity` | `int` | | 每日接待上限 | +| `description` | `string` | | 项目描述 | +| `district` | `string` | | 区县 | +| `durationMinutes` | `int` | | 体验时长（分钟） | +| `environmentType` | `string` | | 环境类型：INDOOR=室内 OUTDOOR=室外 BOTH=室内外 | +| `groupSizeMax` | `int` | | 单次最多人数 | +| `groupSizeMin` | `int` | | 最少成行人数 | +| `healthNotes` | `string` | | 健康须知 | +| `highlights` | `string` | | 项目亮点 | +| `latitude` | `number` | | 纬度 | +| `longitude` | `number` | | 经度 | +| `name` | `string` | 是 | 项目名称 | +| `physicalLevel` | `string` | | 体力要求：LOW=低 MEDIUM=中 HIGH=高 | +| `providedEquipment` | `string` | | 提供装备说明 | +| `province` | `string` | | 省份 | +| `requiredEquipment` | `string` | | 需自备装备说明 | +| `safetyNotes` | `string` | | 安全须知 | +| `sortOrder` | `int` | | 排序权重（数字越大越靠前） | +| `subtitle` | `string` | | 副标题 | +| `unit` | `string` | | 计量单位 | +| `usageNotes` | `string` | | 使用注意事项 | +| `videoMaterialIds` | `string[]` | | 视频素材ID列表 | +| `weatherDependent` | `int` | | 是否受天气影响：0=否 1=是 | +| `whatExcluded` | `string` | | 费用不包含说明 | +| `whatIncluded` | `string` | | 费用包含说明 | + +**响应** `统一响应结果«活动项目详情视图»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `活动项目详情视图` | | 响应数据 | +|   `activityId` | `string` | | 活动项目ID | +|   `address` | `string` | | 详细地址 | +|   `ageMax` | `int` | | 最大年龄限制 | +|   `ageMin` | `int` | | 最小年龄限制 | +|   `bannerMaterialIds` | `string[]` | | 轮播图素材ID列表 | +|   `bannerUrls` | `string[]` | | 轮播图URL列表 | +|   `bestSeason` | `string` | | 最佳季节 | +|   `billingType` | `string` | | 计费方式：PER_PERSON=按人 PER_GROUP=按团 PER_HOUR=按时 | +|   `categoryCode` | `string` | | 分类编码 | +|   `city` | `string` | | 城市 | +|   `contactPhone` | `string` | | 联系电话 | +|   `coverMaterialId` | `string` | | 封面素材ID | +|   `coverUrl` | `string` | | 封面图URL | +|   `createdAt` | `string` | | 创建时间 | +|   `createdBy` | `string` | | 创建人ID | +|   `dailyCapacity` | `int` | | 每日接待上限 | +|   `description` | `string` | | 项目描述 | +|   `district` | `string` | | 区县 | +|   `durationMinutes` | `int` | | 体验时长（分钟） | +|   `environmentType` | `string` | | 环境类型：INDOOR=室内 OUTDOOR=室外 BOTH=室内外 | +|   `groupSizeMax` | `int` | | 单次最多人数 | +|   `groupSizeMin` | `int` | | 最少成行人数 | +|   `healthNotes` | `string` | | 健康须知 | +|   `highlights` | `string` | | 项目亮点 | +|   `latitude` | `number` | | 纬度 | +|   `longitude` | `number` | | 经度 | +|   `name` | `string` | | 项目名称 | +|   `physicalLevel` | `string` | | 体力要求：LOW=低 MEDIUM=中 HIGH=高 | +|   `providedEquipment` | `string` | | 提供装备说明 | +|   `province` | `string` | | 省份 | +|   `requiredEquipment` | `string` | | 需自备装备说明 | +|   `safetyNotes` | `string` | | 安全须知 | +|   `sortOrder` | `int` | | 排序权重 | +|   `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +|   `subtitle` | `string` | | 副标题 | +|   `tags` | `活动标签视图[]` | | 标签列表 | +|     `createdAt` | `string` | | 创建时间 | +|     `tagColor` | `string` | | 标签颜色 | +|     `tagId` | `string` | | 标签ID | +|     `tagName` | `string` | | 标签名称 | +|     `tagType` | `int` | | 标签类型：1=系统标签 2=自定义标签 | +|     `useCount` | `int` | | 使用次数 | +|   `unit` | `string` | | 计量单位 | +|   `updatedAt` | `string` | | 更新时间 | +|   `usageNotes` | `string` | | 使用注意事项 | +|   `videoMaterialIds` | `string[]` | | 视频素材ID列表 | +|   `videoUrls` | `string[]` | | 视频URL列表 | +|   `viewCount` | `int` | | 浏览量 | +|   `weatherDependent` | `int` | | 是否受天气影响：0=否 1=是 | +|   `whatExcluded` | `string` | | 费用不包含说明 | +|   `whatIncluded` | `string` | | 费用包含说明 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/activity/item/{activityId} + +**游玩项目详情** + +获取游玩项目完整信息，包含富文本内容、素材URL、标签、价格日历等。 + +**关联字典**： +- activity_category：活动分类（详情显示） +- activity_billing_type：计费方式（详情显示） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `activityId` | `integer` | | 游玩项目ID | + +**响应** `统一响应结果«活动项目详情视图»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `活动项目详情视图` | | 响应数据 | +|   `activityId` | `string` | | 活动项目ID | +|   `address` | `string` | | 详细地址 | +|   `ageMax` | `int` | | 最大年龄限制 | +|   `ageMin` | `int` | | 最小年龄限制 | +|   `bannerMaterialIds` | `string[]` | | 轮播图素材ID列表 | +|   `bannerUrls` | `string[]` | | 轮播图URL列表 | +|   `bestSeason` | `string` | | 最佳季节 | +|   `billingType` | `string` | | 计费方式：PER_PERSON=按人 PER_GROUP=按团 PER_HOUR=按时 | +|   `categoryCode` | `string` | | 分类编码 | +|   `city` | `string` | | 城市 | +|   `contactPhone` | `string` | | 联系电话 | +|   `coverMaterialId` | `string` | | 封面素材ID | +|   `coverUrl` | `string` | | 封面图URL | +|   `createdAt` | `string` | | 创建时间 | +|   `createdBy` | `string` | | 创建人ID | +|   `dailyCapacity` | `int` | | 每日接待上限 | +|   `description` | `string` | | 项目描述 | +|   `district` | `string` | | 区县 | +|   `durationMinutes` | `int` | | 体验时长（分钟） | +|   `environmentType` | `string` | | 环境类型：INDOOR=室内 OUTDOOR=室外 BOTH=室内外 | +|   `groupSizeMax` | `int` | | 单次最多人数 | +|   `groupSizeMin` | `int` | | 最少成行人数 | +|   `healthNotes` | `string` | | 健康须知 | +|   `highlights` | `string` | | 项目亮点 | +|   `latitude` | `number` | | 纬度 | +|   `longitude` | `number` | | 经度 | +|   `name` | `string` | | 项目名称 | +|   `physicalLevel` | `string` | | 体力要求：LOW=低 MEDIUM=中 HIGH=高 | +|   `providedEquipment` | `string` | | 提供装备说明 | +|   `province` | `string` | | 省份 | +|   `requiredEquipment` | `string` | | 需自备装备说明 | +|   `safetyNotes` | `string` | | 安全须知 | +|   `sortOrder` | `int` | | 排序权重 | +|   `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +|   `subtitle` | `string` | | 副标题 | +|   `tags` | `活动标签视图[]` | | 标签列表 | +|     `createdAt` | `string` | | 创建时间 | +|     `tagColor` | `string` | | 标签颜色 | +|     `tagId` | `string` | | 标签ID | +|     `tagName` | `string` | | 标签名称 | +|     `tagType` | `int` | | 标签类型：1=系统标签 2=自定义标签 | +|     `useCount` | `int` | | 使用次数 | +|   `unit` | `string` | | 计量单位 | +|   `updatedAt` | `string` | | 更新时间 | +|   `usageNotes` | `string` | | 使用注意事项 | +|   `videoMaterialIds` | `string[]` | | 视频素材ID列表 | +|   `videoUrls` | `string[]` | | 视频URL列表 | +|   `viewCount` | `int` | | 浏览量 | +|   `weatherDependent` | `int` | | 是否受天气影响：0=否 1=是 | +|   `whatExcluded` | `string` | | 费用不包含说明 | +|   `whatIncluded` | `string` | | 费用包含说明 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/activity/item/{activityId} + +**更新游玩项目** + +更新游玩项目基本信息，不改变当前状态。已上架的项目修改后仍保持上架。 + +**关联字典**： +- activity_category：活动分类（表单选择） +- activity_billing_type：计费方式（表单选择） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `activityId` | `integer` | | 游玩项目ID | + +**请求体** `活动项目更新请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `address` | `string` | | 详细地址 | +| `ageMax` | `int` | | 最大年龄限制 | +| `ageMin` | `int` | | 最小年龄限制 | +| `bannerMaterialIds` | `string[]` | | 轮播图素材ID列表 | +| `bestSeason` | `string` | | 最佳季节 | +| `billingType` | `string` | | 计费方式：PER_PERSON=按人 PER_GROUP=按团 PER_HOUR=按时 | +| `categoryCode` | `string` | | 分类编码 | +| `city` | `string` | | 城市 | +| `contactPhone` | `string` | | 联系电话 | +| `coverMaterialId` | `string` | | 封面素材ID | +| `dailyCapacity` | `int` | | 每日接待上限 | +| `description` | `string` | | 项目描述 | +| `district` | `string` | | 区县 | +| `durationMinutes` | `int` | | 体验时长（分钟） | +| `environmentType` | `string` | | 环境类型：INDOOR=室内 OUTDOOR=室外 BOTH=室内外 | +| `groupSizeMax` | `int` | | 单次最多人数 | +| `groupSizeMin` | `int` | | 最少成行人数 | +| `healthNotes` | `string` | | 健康须知 | +| `highlights` | `string` | | 项目亮点 | +| `latitude` | `number` | | 纬度 | +| `longitude` | `number` | | 经度 | +| `name` | `string` | | 项目名称 | +| `physicalLevel` | `string` | | 体力要求：LOW=低 MEDIUM=中 HIGH=高 | +| `providedEquipment` | `string` | | 提供装备说明 | +| `province` | `string` | | 省份 | +| `requiredEquipment` | `string` | | 需自备装备说明 | +| `safetyNotes` | `string` | | 安全须知 | +| `sortOrder` | `int` | | 排序权重（数字越大越靠前） | +| `subtitle` | `string` | | 副标题 | +| `unit` | `string` | | 计量单位 | +| `usageNotes` | `string` | | 使用注意事项 | +| `videoMaterialIds` | `string[]` | | 视频素材ID列表 | +| `weatherDependent` | `int` | | 是否受天气影响：0=否 1=是 | +| `whatExcluded` | `string` | | 费用不包含说明 | +| `whatIncluded` | `string` | | 费用包含说明 | + +**响应** `统一响应结果«活动项目详情视图»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `活动项目详情视图` | | 响应数据 | +|   `activityId` | `string` | | 活动项目ID | +|   `address` | `string` | | 详细地址 | +|   `ageMax` | `int` | | 最大年龄限制 | +|   `ageMin` | `int` | | 最小年龄限制 | +|   `bannerMaterialIds` | `string[]` | | 轮播图素材ID列表 | +|   `bannerUrls` | `string[]` | | 轮播图URL列表 | +|   `bestSeason` | `string` | | 最佳季节 | +|   `billingType` | `string` | | 计费方式：PER_PERSON=按人 PER_GROUP=按团 PER_HOUR=按时 | +|   `categoryCode` | `string` | | 分类编码 | +|   `city` | `string` | | 城市 | +|   `contactPhone` | `string` | | 联系电话 | +|   `coverMaterialId` | `string` | | 封面素材ID | +|   `coverUrl` | `string` | | 封面图URL | +|   `createdAt` | `string` | | 创建时间 | +|   `createdBy` | `string` | | 创建人ID | +|   `dailyCapacity` | `int` | | 每日接待上限 | +|   `description` | `string` | | 项目描述 | +|   `district` | `string` | | 区县 | +|   `durationMinutes` | `int` | | 体验时长（分钟） | +|   `environmentType` | `string` | | 环境类型：INDOOR=室内 OUTDOOR=室外 BOTH=室内外 | +|   `groupSizeMax` | `int` | | 单次最多人数 | +|   `groupSizeMin` | `int` | | 最少成行人数 | +|   `healthNotes` | `string` | | 健康须知 | +|   `highlights` | `string` | | 项目亮点 | +|   `latitude` | `number` | | 纬度 | +|   `longitude` | `number` | | 经度 | +|   `name` | `string` | | 项目名称 | +|   `physicalLevel` | `string` | | 体力要求：LOW=低 MEDIUM=中 HIGH=高 | +|   `providedEquipment` | `string` | | 提供装备说明 | +|   `province` | `string` | | 省份 | +|   `requiredEquipment` | `string` | | 需自备装备说明 | +|   `safetyNotes` | `string` | | 安全须知 | +|   `sortOrder` | `int` | | 排序权重 | +|   `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +|   `subtitle` | `string` | | 副标题 | +|   `tags` | `活动标签视图[]` | | 标签列表 | +|     `createdAt` | `string` | | 创建时间 | +|     `tagColor` | `string` | | 标签颜色 | +|     `tagId` | `string` | | 标签ID | +|     `tagName` | `string` | | 标签名称 | +|     `tagType` | `int` | | 标签类型：1=系统标签 2=自定义标签 | +|     `useCount` | `int` | | 使用次数 | +|   `unit` | `string` | | 计量单位 | +|   `updatedAt` | `string` | | 更新时间 | +|   `usageNotes` | `string` | | 使用注意事项 | +|   `videoMaterialIds` | `string[]` | | 视频素材ID列表 | +|   `videoUrls` | `string[]` | | 视频URL列表 | +|   `viewCount` | `int` | | 浏览量 | +|   `weatherDependent` | `int` | | 是否受天气影响：0=否 1=是 | +|   `whatExcluded` | `string` | | 费用不包含说明 | +|   `whatIncluded` | `string` | | 费用包含说明 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/activity/item/{activityId} + +**删除游玩项目** + +软删除游玩项目。仅SUPER_ADMIN或创建者可操作。删除后关联的素材引用会被清理。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `activityId` | `integer` | | 游玩项目ID | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/activity/item/{activityId}/status + +**启用/禁用切换** + +直接修改状态（跳过审批），仅限SUPER_ADMIN。状态值：0=草稿，1=上架，2=下架。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `activityId` | `integer` | | 游玩项目ID | + +**请求体** `活动项目状态变更请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `activityIds` | `string[]` | | 活动项目ID列表（批量操作） | +| `status` | `int` | 是 | 目标状态：0=草稿 1=上架 2=下架 | + +**响应** `统一响应结果«Void»` + +--- + +### `POST` /admin/activity/item/{activityId}/submit-approval + +**提交启用/禁用审批** + +向企微OA提交审批。targetStatus=1申请上架，targetStatus=2申请下架。审批通过后自动更新状态，返回审批单号spNo。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `activityId` | `integer` | | 游玩项目ID | + +**请求体** `活动项目审批提交请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `reason` | `string` | 是 | 审批理由 | +| `targetStatus` | `int` | 是 | 目标状态：1=上架 2=下架 | + +**响应** `统一响应结果«Map«string,string»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `object` | | 响应数据 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/activity/items + +**游玩项目列表** + +分页查询游玩项目列表，支持按名称、状态、分类等条件筛选。返回摘要信息，按sortOrder倒序+创建时间倒序排列。 + +**关联字典**： +- activity_category：活动分类（筛选+列表显示） +- activity_billing_type：计费方式（列表显示） + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `billingType` | `string` | | 计费方式：PER_PERSON=按人 PER_GROUP=按团 PER_HOUR=按时 | PER_PERSON | +| `categoryCode` | `string` | | 分类编码 | OUTDOOR | +| `city` | `string` | | 城市 | 拉萨市 | +| `cityKeyword` | `string` | | 城市/区域关键词模糊搜索（匹配城市名、省份、地址） | 海拉尔 | +| `environmentType` | `string` | | 环境类型：INDOOR=室内 OUTDOOR=室外 BOTH=室内外 | OUTDOOR | +| `keyword` | `string` | | 搜索关键词（名称/副标题模糊搜索） | 骑马 | +| `page` | `integer(int32)` | | 页码 | 1 | +| `pageSize` | `integer(int32)` | | 每页条数 | 20 | +| `physicalLevel` | `string` | | 体力要求：LOW=低 MEDIUM=中 HIGH=高 | MEDIUM | +| `sortBy` | `string` | | 排序字段 | createdAt | +| `sortDir` | `string` | | 排序方向：asc=升序 desc=降序 | desc | +| `status` | `integer(int32)` | | 状态：0=草稿 1=上架 2=下架 | 1 | +| `tagId` | `integer(int64)` | | 标签ID | 100 | +| `tagIds` | `string` | | 标签ID列表（逗号分隔） | 100,101,102 | +| `weatherDependent` | `integer(int32)` | | 是否受天气影响：0=否 1=是 | 1 | + +**响应** `统一响应结果«分页结果«活动项目列表视图»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«活动项目列表视图»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `活动项目列表视图[]` | | 数据列表 | +|     `activityId` | `string` | | 活动项目ID | +|     `approvalNo` | `string` | | 审批编号 | +|     `billingType` | `string` | | 计费方式编码 | +|     `categoryCode` | `string` | | 分类编码 | +|     `city` | `string` | | 城市 | +|     `coverUrl` | `string` | | 封面图URL | +|     `createdAt` | `string` | | 创建时间 | +|     `durationMinutes` | `int` | | 体验时长（分钟） | +|     `environmentType` | `string` | | 环境类型：INDOOR=室内 OUTDOOR=室外 BOTH=室内外 | +|     `highlights` | `string` | | 项目亮点 | +|     `latitude` | `number` | | 纬度 | +|     `longitude` | `number` | | 经度 | +|     `name` | `string` | | 项目名称 | +|     `pendingStatus` | `int` | | 待审批目标状态 | +|     `physicalLevel` | `string` | | 体力要求：LOW=低 MEDIUM=中 HIGH=高 | +|     `sortOrder` | `int` | | 排序权重 | +|     `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +|     `subtitle` | `string` | | 副标题 | +|     `tags` | `活动标签视图[]` | | 标签列表 | +|     `unit` | `string` | | 计量单位 | +|     `viewCount` | `int` | | 浏览量 | +|     `weatherDependent` | `int` | | 是否受天气影响：0=否 1=是 | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/activity/items/batch + +**批量删除** + +批量软删除多个游玩项目。仅SUPER_ADMIN或创建者可操作。 + +**请求体** `活动项目批量删除请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `activityIds` | `string[]` | 是 | 活动项目ID列表 | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/activity/items/batch/status + +**批量启用/禁用** + +批量修改多个游玩项目的状态，跳过审批流程。 + +**请求体** `活动项目状态变更请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `activityIds` | `string[]` | | 活动项目ID列表（批量操作） | +| `status` | `int` | 是 | 目标状态：0=草稿 1=上架 2=下架 | + +**响应** `统一响应结果«Void»` + +--- + +## 费用项价格日历 + +### `GET` /admin/cost/item/{costId}/prices + +**查询价格日历** + +按月查询费用项的每日价格。费用项价格日历用于产品报价计算时按日期获取成本价。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `costId` | `integer` | | 费用项ID | + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `month` | `integer(int32)` | | 月份 | | +| `year` | `integer(int32)` | | 年份 | | + +**响应** `统一响应结果«费用项价格日历VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `费用项价格日历VO` | | 响应数据 | +|   `days` | `费用项价格日历日VO[]` | | 价格日历明细列表 | +|     `date` | `string` | | 日期（yyyy-MM-dd） | +|     `remark` | `string` | | 备注 | +|     `status` | `int` | | 状态：0=不可用 1=可用 | +|     `unitPrice` | `number` | | 单价（元） | +|   `yearMonth` | `string` | | 年月（yyyy-MM） | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/cost/item/{costId}/prices + +**批量设置价格** + +在指定日期范围内批量设置费用项的成本价。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `costId` | `integer` | | 费用项ID | + +**请求体** `费用项价格日历设置请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `dayFilter` | `string` | | 日期过滤：weekday=仅工作日 weekend=仅周末 | +| `endDate` | `string` | 是 | 结束日期 | +| `excludeDates` | `LocalDate[]` | | 排除日期列表 | +| `remark` | `string` | | 备注 | +| `selectedWeekdays` | `int[]` | | 指定星期几（1=周一 7=周日） | +| `startDate` | `string` | 是 | 开始日期 | +| `unitPrice` | `number` | 是 | 单价（元） | + +**响应** `统一响应结果«Void»` + +--- + +### `DELETE` /admin/cost/item/{costId}/prices + +**清除价格日历** + +删除指定日期范围内费用项的价格记录。日期格式：yyyy-MM-dd。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `costId` | `integer` | | 费用项ID | + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `endDate` | `string(date)` | | 结束日期 | | +| `startDate` | `string(date)` | | 开始日期 | | + +**响应** `统一响应结果«Void»` + +--- + +## 费用项管理 + +### `POST` /admin/cost/item + +**创建费用项** + +新建费用项（如门票成本、餐费、保险费等），用于产品报价计算。费用项有独立的价格日历，价格变更会记录变更日志。创建后需走企微审批上架。 + +**关联字典**： +- cost_category：费用分类（表单选择） +- cost_apply_role：适用角色（表单选择） +- cost_unit：计量单位（表单选择） + +**请求体** `费用项创建请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `applyRole` | `string` | 是 | 适用角色 | +| `calcHint` | `string` | | 计算提示 | +| `categoryCode` | `string` | 是 | 费用分类编码 | +| `defaultFormula` | `string` | | 默认计算公式 | +| `description` | `string` | | 费用描述 | +| `name` | `string` | 是 | 费用名称 | +| `remark` | `string` | | 备注 | +| `sortOrder` | `int` | | 排序权重，值越大越靠前 | +| `unit` | `string` | | 计价单位 | +| `unitPrice` | `number` | 是 | 单价（元） | + +**响应** `统一响应结果«费用项详情VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `费用项详情VO` | | 响应数据 | +|   `applyRole` | `string` | | 适用角色 | +|   `approvalNo` | `string` | | 审批单号 | +|   `calcHint` | `string` | | 计算提示 | +|   `categoryCode` | `string` | | 费用分类编码 | +|   `costId` | `string` | | 费用项ID | +|   `createdAt` | `string` | | 创建时间 | +|   `createdBy` | `string` | | 创建者ID | +|   `defaultFormula` | `string` | | 默认计算公式 | +|   `description` | `string` | | 费用描述 | +|   `name` | `string` | | 费用名称 | +|   `pendingStatus` | `int` | | 待审批目标状态 | +|   `refCount` | `int` | | 引用次数 | +|   `remark` | `string` | | 备注 | +|   `sortOrder` | `int` | | 排序权重 | +|   `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +|   `unit` | `string` | | 计价单位 | +|   `unitPrice` | `number` | | 单价（元） | +|   `updatedAt` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/cost/item/{costId} + +**费用项详情** + +获取费用项完整信息，包含当前价格、引用计数等。 + +**关联字典**： +- cost_category：费用分类（详情显示） +- cost_apply_role：适用角色（详情显示） +- cost_unit：计量单位（详情显示） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `costId` | `integer` | | 费用项ID | + +**响应** `统一响应结果«费用项详情VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `费用项详情VO` | | 响应数据 | +|   `applyRole` | `string` | | 适用角色 | +|   `approvalNo` | `string` | | 审批单号 | +|   `calcHint` | `string` | | 计算提示 | +|   `categoryCode` | `string` | | 费用分类编码 | +|   `costId` | `string` | | 费用项ID | +|   `createdAt` | `string` | | 创建时间 | +|   `createdBy` | `string` | | 创建者ID | +|   `defaultFormula` | `string` | | 默认计算公式 | +|   `description` | `string` | | 费用描述 | +|   `name` | `string` | | 费用名称 | +|   `pendingStatus` | `int` | | 待审批目标状态 | +|   `refCount` | `int` | | 引用次数 | +|   `remark` | `string` | | 备注 | +|   `sortOrder` | `int` | | 排序权重 | +|   `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +|   `unit` | `string` | | 计价单位 | +|   `unitPrice` | `number` | | 单价（元） | +|   `updatedAt` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/cost/item/{costId} + +**更新费用项** + +更新费用项信息。如果修改了价格，会自动记录价格变更日志。 + +**关联字典**： +- cost_category：费用分类（表单选择） +- cost_apply_role：适用角色（表单选择） +- cost_unit：计量单位（表单选择） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `costId` | `integer` | | 费用项ID | + +**请求体** `费用项更新请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `applyRole` | `string` | | 适用角色 | +| `calcHint` | `string` | | 计算提示 | +| `categoryCode` | `string` | | 费用分类编码 | +| `changeReason` | `string` | | 价格变更原因（修改单价时必填） | +| `defaultFormula` | `string` | | 默认计算公式 | +| `description` | `string` | | 费用描述 | +| `name` | `string` | | 费用名称 | +| `remark` | `string` | | 备注 | +| `sortOrder` | `int` | | 排序权重，值越大越靠前 | +| `unit` | `string` | | 计价单位 | +| `unitPrice` | `number` | | 单价（元） | + +**响应** `统一响应结果«费用项详情VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `费用项详情VO` | | 响应数据 | +|   `applyRole` | `string` | | 适用角色 | +|   `approvalNo` | `string` | | 审批单号 | +|   `calcHint` | `string` | | 计算提示 | +|   `categoryCode` | `string` | | 费用分类编码 | +|   `costId` | `string` | | 费用项ID | +|   `createdAt` | `string` | | 创建时间 | +|   `createdBy` | `string` | | 创建者ID | +|   `defaultFormula` | `string` | | 默认计算公式 | +|   `description` | `string` | | 费用描述 | +|   `name` | `string` | | 费用名称 | +|   `pendingStatus` | `int` | | 待审批目标状态 | +|   `refCount` | `int` | | 引用次数 | +|   `remark` | `string` | | 备注 | +|   `sortOrder` | `int` | | 排序权重 | +|   `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +|   `unit` | `string` | | 计价单位 | +|   `unitPrice` | `number` | | 单价（元） | +|   `updatedAt` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/cost/item/{costId} + +**删除费用项** + +软删除费用项。仅SUPER_ADMIN或创建者可操作。被产品引用(refCount>0)的费用项不建议删除。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `costId` | `integer` | | 费用项ID | + +**响应** `统一响应结果«Void»` + +--- + +### `GET` /admin/cost/item/{costId}/price-logs + +**费用项价格变更记录** + +查询费用项的历史价格变更记录，按时间倒序排列。用于追溯价格调整历史。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `costId` | `integer` | | 费用项ID | + +**响应** `统一响应结果«List«费用项价格变更日志VO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `费用项价格变更日志VO[]` | | 响应数据 | +|   `changeReason` | `string` | | 变更原因 | +|   `changedAt` | `string` | | 变更时间 | +|   `changedBy` | `string` | | 变更人ID | +|   `costId` | `string` | | 费用项ID | +|   `id` | `long` | | 日志ID | +|   `newPrice` | `number` | | 变更后价格（元） | +|   `oldPrice` | `number` | | 变更前价格（元） | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/cost/item/{costId}/submit-approval + +**提交审批** + +向企微OA提交费用项启用/禁用审批。targetStatus=1申请上架，targetStatus=2申请下架。返回审批单号spNo。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `costId` | `integer` | | 费用项ID | + +**请求体** `费用项审批提交请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `reason` | `string` | | 审批原因 | +| `targetStatus` | `int` | 是 | 目标状态 | + +**响应** `统一响应结果«Map«string,string»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `object` | | 响应数据 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/cost/items + +**费用项列表** + +分页查询费用项列表，支持按名称、状态等条件筛选。 + +**关联字典**： +- cost_category：费用分类（筛选+列表显示） +- cost_apply_role：适用角色（筛选+列表显示） +- cost_unit：计量单位（列表显示） + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `applyRole` | `string` | | 适用角色筛选 | ADULT | +| `categoryCode` | `string` | | 费用分类编码筛选 | GUIDE | +| `keyword` | `string` | | 搜索关键词（名称模糊匹配） | 导游 | +| `page` | `integer(int32)` | | 页码 | 1 | +| `pageSize` | `integer(int32)` | | 每页条数 | 20 | +| `sortBy` | `string` | | 排序字段 | createdAt | +| `sortDir` | `string` | | 排序方向：asc/desc | desc | +| `status` | `integer(int32)` | | 状态筛选：0=草稿 1=上架 2=下架 | 1 | + +**响应** `统一响应结果«分页结果«费用项列表VO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«费用项列表VO»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `费用项列表VO[]` | | 数据列表 | +|     `applyRole` | `string` | | 适用角色 | +|     `approvalNo` | `string` | | 审批单号 | +|     `categoryCode` | `string` | | 费用分类编码 | +|     `costId` | `string` | | 费用项ID | +|     `createdAt` | `string` | | 创建时间 | +|     `name` | `string` | | 费用名称 | +|     `pendingStatus` | `int` | | 待审批目标状态 | +|     `refCount` | `int` | | 引用次数 | +|     `sortOrder` | `int` | | 排序权重 | +|     `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +|     `unit` | `string` | | 计价单位 | +|     `unitPrice` | `number` | | 单价（元） | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/cost/items/enabled + +**启用的费用项列表** + +查询所有已启用(status=1)的费用项，不分页。用于产品编排时选择费用项的下拉列表。 + +**关联字典**： +- cost_category：费用分类（列表显示） +- cost_apply_role：适用角色（列表显示） +- cost_unit：计量单位（列表显示） + +**响应** `统一响应结果«List«费用项详情VO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `费用项详情VO[]` | | 响应数据 | +|   `applyRole` | `string` | | 适用角色 | +|   `approvalNo` | `string` | | 审批单号 | +|   `calcHint` | `string` | | 计算提示 | +|   `categoryCode` | `string` | | 费用分类编码 | +|   `costId` | `string` | | 费用项ID | +|   `createdAt` | `string` | | 创建时间 | +|   `createdBy` | `string` | | 创建者ID | +|   `defaultFormula` | `string` | | 默认计算公式 | +|   `description` | `string` | | 费用描述 | +|   `name` | `string` | | 费用名称 | +|   `pendingStatus` | `int` | | 待审批目标状态 | +|   `refCount` | `int` | | 引用次数 | +|   `remark` | `string` | | 备注 | +|   `sortOrder` | `int` | | 排序权重 | +|   `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +|   `unit` | `string` | | 计价单位 | +|   `unitPrice` | `number` | | 单价（元） | +|   `updatedAt` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +## 车型价格日历 + +### `GET` /admin/vehicle/model/{vehicleId}/prices + +**查询价格日历** + +按月查询车型的每日租赁价格和可调度状态。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `vehicleId` | `integer` | | 车型ID | + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `month` | `integer(int32)` | | 月份 | | +| `year` | `integer(int32)` | | 年份 | | + +**响应** `统一响应结果«车型价格日历VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `车型价格日历VO` | | 响应数据 | +|   `month` | `int` | | 月份 | +|   `prices` | `车型价格日历日VO[]` | | 价格日历明细列表 | +|     `costPrice` | `number` | | 日租价（元） | +|     `date` | `string` | | 日期 | +|     `remark` | `string` | | 备注 | +|     `status` | `int` | | 状态：0=不可租 1=可租 | +|     `stock` | `int` | | 库存数量 | +|     `stockUsed` | `int` | | 已用库存 | +|   `stockEnabled` | `boolean` | | 是否启用库存管理 | +|   `vehicleId` | `string` | | 车型ID | +|   `vehicleName` | `string` | | 车型名称 | +|   `year` | `int` | | 年份 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/vehicle/model/{vehicleId}/prices + +**批量设置价格** + +在指定日期范围内批量设置车型的租赁成本价和可调度状态。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `vehicleId` | `integer` | | 车型ID | + +**请求体** `车型价格日历设置请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `costPrice` | `number` | 是 | 日租价（元） | +| `endDate` | `string` | 是 | 结束日期 | +| `excludeDates` | `LocalDate[]` | | 排除日期列表 | +| `remark` | `string` | | 备注 | +| `selectedWeekdays` | `int[]` | | 指定星期几（1=周一 7=周日） | +| `startDate` | `string` | 是 | 开始日期 | +| `status` | `int` | | 状态：0=不可租 1=可租 | +| `stock` | `int` | | 库存数量 | +| `weekdayOnly` | `boolean` | | 是否仅工作日 | +| `weekendOnly` | `boolean` | | 是否仅周末 | + +**响应** `统一响应结果«Void»` + +--- + +### `DELETE` /admin/vehicle/model/{vehicleId}/prices + +**清除价格日历** + +删除指定日期范围内车型的价格记录。日期格式：yyyy-MM-dd。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `vehicleId` | `integer` | | 车型ID | + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `endDate` | `string(date)` | | 结束日期 | | +| `startDate` | `string(date)` | | 开始日期 | | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/vehicle/model/{vehicleId}/prices/batch-status + +**批量修改调度状态** + +批量修改日期范围内车型的可调度状态，不影响价格。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `vehicleId` | `integer` | | 车型ID | + +**请求体** `车型价格日历状态变更请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `endDate` | `string` | 是 | 结束日期 | +| `remark` | `string` | | 备注 | +| `startDate` | `string` | 是 | 开始日期 | +| `status` | `int` | 是 | 状态：0=不可租 1=可租 | + +**响应** `统一响应结果«Void»` + +--- + +## 车型标签管理 + +### `PUT` /admin/vehicle/model/{vehicleId}/tags + +**设置车型标签** + +全量替换指定车型的标签列表。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `vehicleId` | `integer` | | 车型ID | + +**请求体** `设置车型标签请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagIds` | `long[]` | 是 | 标签ID列表 | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/vehicle/models/batch/tags + +**批量添加/移除标签** + +对多个车型批量添加/移除标签。增量操作。 + +**请求体** `车型批量标签操作请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `addTagIds` | `long[]` | | 要添加的标签ID列表 | +| `removeTagIds` | `long[]` | | 要移除的标签ID列表 | +| `vehicleIds` | `long[]` | 是 | 车型ID列表 | + +**响应** `统一响应结果«Void»` + +--- + +### `POST` /admin/vehicle/tag + +**创建标签** + +创建预设标签，标签名不可重复。 + +**请求体** `车辆标签创建请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagColor` | `string` | | 标签颜色（十六进制） | +| `tagName` | `string` | 是 | 标签名称 | + +**响应** `统一响应结果«车辆标签VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `车辆标签VO` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `tagColor` | `string` | | 标签颜色（十六进制） | +|   `tagId` | `string` | | 标签ID | +|   `tagName` | `string` | | 标签名称 | +|   `tagType` | `int` | | 标签类型：0=自定义 1=系统 | +|   `useCount` | `int` | | 使用次数 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/vehicle/tag/adhoc + +**解析自定义标签** + +按名称查找或自动创建标签。 + +**请求体** `车辆标签创建请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagColor` | `string` | | 标签颜色（十六进制） | +| `tagName` | `string` | 是 | 标签名称 | + +**响应** `统一响应结果«车辆标签VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `车辆标签VO` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `tagColor` | `string` | | 标签颜色（十六进制） | +|   `tagId` | `string` | | 标签ID | +|   `tagName` | `string` | | 标签名称 | +|   `tagType` | `int` | | 标签类型：0=自定义 1=系统 | +|   `useCount` | `int` | | 使用次数 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/vehicle/tag/{tagId} + +**更新标签** + +修改标签名称或颜色。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagId` | `integer` | | 标签ID | + +**请求体** `车辆标签更新请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagColor` | `string` | | 标签颜色（十六进制） | +| `tagName` | `string` | | 标签名称 | + +**响应** `统一响应结果«车辆标签VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `车辆标签VO` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `tagColor` | `string` | | 标签颜色（十六进制） | +|   `tagId` | `string` | | 标签ID | +|   `tagName` | `string` | | 标签名称 | +|   `tagType` | `int` | | 标签类型：0=自定义 1=系统 | +|   `useCount` | `int` | | 使用次数 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/vehicle/tag/{tagId} + +**删除标签** + +删除标签并解除所有车型与该标签的关联。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagId` | `integer` | | 标签ID | + +**响应** `统一响应结果«Void»` + +--- + +### `GET` /admin/vehicle/tags + +**预设标签列表（分页）** + +分页查询车型标签库，支持按关键词搜索。 + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `keyword` | `string` | | 关键词 | | +| `page` | `integer(int32)` | | 页码 | | +| `pageSize` | `integer(int32)` | | 每页条数 | | + +**响应** `统一响应结果«分页结果«车辆标签VO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«车辆标签VO»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `车辆标签VO[]` | | 数据列表 | +|     `createdAt` | `string` | | 创建时间 | +|     `tagColor` | `string` | | 标签颜色（十六进制） | +|     `tagId` | `string` | | 标签ID | +|     `tagName` | `string` | | 标签名称 | +|     `tagType` | `int` | | 标签类型：0=自定义 1=系统 | +|     `useCount` | `int` | | 使用次数 | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/vehicle/tags/all + +**全部标签列表** + +不分页返回所有标签，用于车型编辑时的标签选择。 + +**响应** `统一响应结果«List«车辆标签VO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `车辆标签VO[]` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `tagColor` | `string` | | 标签颜色（十六进制） | +|   `tagId` | `string` | | 标签ID | +|   `tagName` | `string` | | 标签名称 | +|   `tagType` | `int` | | 标签类型：0=自定义 1=系统 | +|   `useCount` | `int` | | 使用次数 | +| `message` | `string` | | 响应消息 | + +--- + +## 车型管理 + +### `POST` /admin/vehicle/model + +**创建车型** + +新建车型资源（如7座商务车、14座中巴等），初始状态为草稿(status=0)。车型有独立的价格日历用于报价计算。需走企微审批上架。 + +**关联字典**： +- vehicle_type：车辆类型（表单选择） + +**请求体** `车型创建请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `bannerMaterialIds` | `string[]` | | 横幅素材ID列表 | +| `basePrice` | `number` | | 基础日租价（元） | +| `brand` | `string` | 是 | 品牌 | +| `comfortFeatures` | `string` | | 舒适配置（JSON） | +| `coverMaterialId` | `string` | | 封面素材ID | +| `description` | `string` | | 车型描述 | +| `driveType` | `string` | | 驱动方式 | +| `engineType` | `string` | | 动力类型 | +| `highlights` | `string` | | 车型亮点 | +| `luggageCapacity` | `string` | | 行李容量描述 | +| `modelSeries` | `string` | | 车系 | +| `modelYear` | `int` | | 年款 | +| `name` | `string` | 是 | 车型名称 | +| `passengerCount` | `int` | 是 | 可乘坐人数 | +| `priceExcludes` | `string` | | 价格不包含内容 | +| `priceIncludes` | `string` | | 价格包含内容 | +| `seatCount` | `int` | 是 | 座位数 | +| `sortOrder` | `int` | | 排序权重，值越大越靠前 | +| `subtitle` | `string` | | 副标题 | +| `transmission` | `string` | | 变速箱类型 | +| `usageNotes` | `string` | | 使用须知 | +| `vehicleType` | `string` | 是 | 车型分类 | +| `videoMaterialIds` | `string[]` | | 视频素材ID列表 | + +**响应** `统一响应结果«车型详情VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `车型详情VO` | | 响应数据 | +|   `bannerMaterialIds` | `string[]` | | 横幅素材ID列表 | +|   `bannerUrls` | `string[]` | | 横幅图URL列表 | +|   `basePrice` | `number` | | 基础日租价（元） | +|   `brand` | `string` | | 品牌 | +|   `comfortFeatures` | `string` | | 舒适配置（JSON） | +|   `coverMaterialId` | `string` | | 封面素材ID | +|   `coverUrl` | `string` | | 封面图URL | +|   `createdAt` | `string` | | 创建时间 | +|   `createdBy` | `string` | | 创建者ID | +|   `description` | `string` | | 车型描述 | +|   `driveType` | `string` | | 驱动方式 | +|   `engineType` | `string` | | 动力类型 | +|   `highlights` | `string` | | 车型亮点 | +|   `luggageCapacity` | `string` | | 行李容量描述 | +|   `modelSeries` | `string` | | 车系 | +|   `modelYear` | `int` | | 年款 | +|   `name` | `string` | | 车型名称 | +|   `passengerCount` | `int` | | 可乘坐人数 | +|   `priceExcludes` | `string` | | 价格不包含内容 | +|   `priceIncludes` | `string` | | 价格包含内容 | +|   `seatCount` | `int` | | 座位数 | +|   `sortOrder` | `int` | | 排序权重 | +|   `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +|   `subtitle` | `string` | | 副标题 | +|   `tags` | `车辆标签VO[]` | | 标签列表 | +|     `createdAt` | `string` | | 创建时间 | +|     `tagColor` | `string` | | 标签颜色（十六进制） | +|     `tagId` | `string` | | 标签ID | +|     `tagName` | `string` | | 标签名称 | +|     `tagType` | `int` | | 标签类型：0=自定义 1=系统 | +|     `useCount` | `int` | | 使用次数 | +|   `transmission` | `string` | | 变速箱类型 | +|   `updatedAt` | `string` | | 更新时间 | +|   `usageNotes` | `string` | | 使用须知 | +|   `vehicleId` | `string` | | 车型ID | +|   `vehicleType` | `string` | | 车型分类 | +|   `videoMaterialIds` | `string[]` | | 视频素材ID列表 | +|   `videoUrls` | `string[]` | | 视频URL列表 | +|   `viewCount` | `int` | | 浏览量 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/vehicle/model/{vehicleId} + +**车型详情** + +获取车型完整信息，包含座位数、品牌、素材URL、标签等。 + +**关联字典**： +- vehicle_type：车辆类型（详情显示） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `vehicleId` | `integer` | | 车型ID | + +**响应** `统一响应结果«车型详情VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `车型详情VO` | | 响应数据 | +|   `bannerMaterialIds` | `string[]` | | 横幅素材ID列表 | +|   `bannerUrls` | `string[]` | | 横幅图URL列表 | +|   `basePrice` | `number` | | 基础日租价（元） | +|   `brand` | `string` | | 品牌 | +|   `comfortFeatures` | `string` | | 舒适配置（JSON） | +|   `coverMaterialId` | `string` | | 封面素材ID | +|   `coverUrl` | `string` | | 封面图URL | +|   `createdAt` | `string` | | 创建时间 | +|   `createdBy` | `string` | | 创建者ID | +|   `description` | `string` | | 车型描述 | +|   `driveType` | `string` | | 驱动方式 | +|   `engineType` | `string` | | 动力类型 | +|   `highlights` | `string` | | 车型亮点 | +|   `luggageCapacity` | `string` | | 行李容量描述 | +|   `modelSeries` | `string` | | 车系 | +|   `modelYear` | `int` | | 年款 | +|   `name` | `string` | | 车型名称 | +|   `passengerCount` | `int` | | 可乘坐人数 | +|   `priceExcludes` | `string` | | 价格不包含内容 | +|   `priceIncludes` | `string` | | 价格包含内容 | +|   `seatCount` | `int` | | 座位数 | +|   `sortOrder` | `int` | | 排序权重 | +|   `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +|   `subtitle` | `string` | | 副标题 | +|   `tags` | `车辆标签VO[]` | | 标签列表 | +|     `createdAt` | `string` | | 创建时间 | +|     `tagColor` | `string` | | 标签颜色（十六进制） | +|     `tagId` | `string` | | 标签ID | +|     `tagName` | `string` | | 标签名称 | +|     `tagType` | `int` | | 标签类型：0=自定义 1=系统 | +|     `useCount` | `int` | | 使用次数 | +|   `transmission` | `string` | | 变速箱类型 | +|   `updatedAt` | `string` | | 更新时间 | +|   `usageNotes` | `string` | | 使用须知 | +|   `vehicleId` | `string` | | 车型ID | +|   `vehicleType` | `string` | | 车型分类 | +|   `videoMaterialIds` | `string[]` | | 视频素材ID列表 | +|   `videoUrls` | `string[]` | | 视频URL列表 | +|   `viewCount` | `int` | | 浏览量 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/vehicle/model/{vehicleId} + +**更新车型** + +更新车型基本信息，不改变当前状态。 + +**关联字典**： +- vehicle_type：车辆类型（表单选择） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `vehicleId` | `integer` | | 车型ID | + +**请求体** `车型更新请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `bannerMaterialIds` | `string[]` | | 横幅素材ID列表 | +| `basePrice` | `number` | | 基础日租价（元） | +| `brand` | `string` | | 品牌 | +| `comfortFeatures` | `string` | | 舒适配置（JSON） | +| `coverMaterialId` | `string` | | 封面素材ID | +| `description` | `string` | | 车型描述 | +| `driveType` | `string` | | 驱动方式 | +| `engineType` | `string` | | 动力类型 | +| `highlights` | `string` | | 车型亮点 | +| `luggageCapacity` | `string` | | 行李容量描述 | +| `modelSeries` | `string` | | 车系 | +| `modelYear` | `int` | | 年款 | +| `name` | `string` | | 车型名称 | +| `passengerCount` | `int` | | 可乘坐人数 | +| `priceExcludes` | `string` | | 价格不包含内容 | +| `priceIncludes` | `string` | | 价格包含内容 | +| `seatCount` | `int` | | 座位数 | +| `sortOrder` | `int` | | 排序权重，值越大越靠前 | +| `subtitle` | `string` | | 副标题 | +| `transmission` | `string` | | 变速箱类型 | +| `usageNotes` | `string` | | 使用须知 | +| `vehicleType` | `string` | | 车型分类 | +| `videoMaterialIds` | `string[]` | | 视频素材ID列表 | + +**响应** `统一响应结果«车型详情VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `车型详情VO` | | 响应数据 | +|   `bannerMaterialIds` | `string[]` | | 横幅素材ID列表 | +|   `bannerUrls` | `string[]` | | 横幅图URL列表 | +|   `basePrice` | `number` | | 基础日租价（元） | +|   `brand` | `string` | | 品牌 | +|   `comfortFeatures` | `string` | | 舒适配置（JSON） | +|   `coverMaterialId` | `string` | | 封面素材ID | +|   `coverUrl` | `string` | | 封面图URL | +|   `createdAt` | `string` | | 创建时间 | +|   `createdBy` | `string` | | 创建者ID | +|   `description` | `string` | | 车型描述 | +|   `driveType` | `string` | | 驱动方式 | +|   `engineType` | `string` | | 动力类型 | +|   `highlights` | `string` | | 车型亮点 | +|   `luggageCapacity` | `string` | | 行李容量描述 | +|   `modelSeries` | `string` | | 车系 | +|   `modelYear` | `int` | | 年款 | +|   `name` | `string` | | 车型名称 | +|   `passengerCount` | `int` | | 可乘坐人数 | +|   `priceExcludes` | `string` | | 价格不包含内容 | +|   `priceIncludes` | `string` | | 价格包含内容 | +|   `seatCount` | `int` | | 座位数 | +|   `sortOrder` | `int` | | 排序权重 | +|   `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +|   `subtitle` | `string` | | 副标题 | +|   `tags` | `车辆标签VO[]` | | 标签列表 | +|     `createdAt` | `string` | | 创建时间 | +|     `tagColor` | `string` | | 标签颜色（十六进制） | +|     `tagId` | `string` | | 标签ID | +|     `tagName` | `string` | | 标签名称 | +|     `tagType` | `int` | | 标签类型：0=自定义 1=系统 | +|     `useCount` | `int` | | 使用次数 | +|   `transmission` | `string` | | 变速箱类型 | +|   `updatedAt` | `string` | | 更新时间 | +|   `usageNotes` | `string` | | 使用须知 | +|   `vehicleId` | `string` | | 车型ID | +|   `vehicleType` | `string` | | 车型分类 | +|   `videoMaterialIds` | `string[]` | | 视频素材ID列表 | +|   `videoUrls` | `string[]` | | 视频URL列表 | +|   `viewCount` | `int` | | 浏览量 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/vehicle/model/{vehicleId} + +**删除车型** + +软删除车型。仅SUPER_ADMIN或创建者可操作。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `vehicleId` | `integer` | | 车型ID | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/vehicle/model/{vehicleId}/status + +**更新状态** + +直接修改车型状态（跳过审批），仅限SUPER_ADMIN。状态值：0=草稿，1=上架，2=下架。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `vehicleId` | `integer` | | 车型ID | + +**请求体** `车型状态请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `status` | `int` | 是 | 目标状态：0=草稿 1=上架 2=下架 | +| `vehicleIds` | `long[]` | | 车型ID列表（批量操作时使用） | + +**响应** `统一响应结果«Void»` + +--- + +### `POST` /admin/vehicle/model/{vehicleId}/submit-approval + +**提交审批** + +向企微OA提交车型启用/禁用审批。targetStatus=1申请上架，targetStatus=2申请下架。返回审批单号spNo。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `vehicleId` | `integer` | | 车型ID | + +**请求体** `车型审批提交请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `reason` | `string` | | 审批原因 | +| `targetStatus` | `int` | 是 | 目标状态 | + +**响应** `统一响应结果«Map«string,string»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `object` | | 响应数据 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/vehicle/models + +**车型列表** + +分页查询车型列表，支持按名称、状态、车辆类型等条件筛选。 + +**关联字典**： +- vehicle_type：车辆类型（筛选+列表显示） + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `brand` | `string` | | 品牌筛选 | 别克 | +| `keyword` | `string` | | 搜索关键词（名称/品牌模糊匹配） | 别克 | +| `maxPrice` | `number` | | 最高价格筛选 | 2000.0 | +| `maxSeatCount` | `integer(int32)` | | 最多座位数筛选 | 15 | +| `minPrice` | `number` | | 最低价格筛选 | 500.0 | +| `minSeatCount` | `integer(int32)` | | 最少座位数筛选 | 5 | +| `page` | `integer(int32)` | | 页码 | 1 | +| `pageSize` | `integer(int32)` | | 每页条数 | 20 | +| `sortBy` | `string` | | 排序字段 | createdAt | +| `sortDir` | `string` | | 排序方向：asc/desc | desc | +| `status` | `integer(int32)` | | 状态筛选：0=草稿 1=上架 2=下架 | 1 | +| `tagId` | `integer(int64)` | | 标签ID（单个） | | +| `tagIds` | `string` | | 标签ID列表（逗号分隔） | 1,2,3 | +| `vehicleType` | `string` | | 车型分类筛选 | MPV | + +**响应** `统一响应结果«分页结果«车型列表VO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«车型列表VO»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `车型列表VO[]` | | 数据列表 | +|     `approvalNo` | `string` | | 审批单号 | +|     `basePrice` | `number` | | 基础日租价（元） | +|     `brand` | `string` | | 品牌 | +|     `coverUrl` | `string` | | 封面图URL | +|     `createdAt` | `string` | | 创建时间 | +|     `highlights` | `string` | | 车型亮点 | +|     `modelSeries` | `string` | | 车系 | +|     `name` | `string` | | 车型名称 | +|     `passengerCount` | `int` | | 可乘坐人数 | +|     `pendingStatus` | `int` | | 待审批目标状态 | +|     `seatCount` | `int` | | 座位数 | +|     `sortOrder` | `int` | | 排序权重 | +|     `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +|     `subtitle` | `string` | | 副标题 | +|     `tags` | `车辆标签VO[]` | | 标签列表 | +|     `vehicleId` | `string` | | 车型ID | +|     `vehicleType` | `string` | | 车型分类 | +|     `viewCount` | `int` | | 浏览量 | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/vehicle/models/all + +**车型全量列表（不分页，用于下拉选择）** + +返回所有车型列表，可选按状态筛选。适用于产品编排时选择车型的下拉选择框。不分页返回全部数据。 + +**关联字典**： +- vehicle_type：车辆类型（列表显示） + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `status` | `integer(int32)` | | 状态筛选：1=上架 | | + +**响应** `统一响应结果«List«车型列表VO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `车型列表VO[]` | | 响应数据 | +|   `approvalNo` | `string` | | 审批单号 | +|   `basePrice` | `number` | | 基础日租价（元） | +|   `brand` | `string` | | 品牌 | +|   `coverUrl` | `string` | | 封面图URL | +|   `createdAt` | `string` | | 创建时间 | +|   `highlights` | `string` | | 车型亮点 | +|   `modelSeries` | `string` | | 车系 | +|   `name` | `string` | | 车型名称 | +|   `passengerCount` | `int` | | 可乘坐人数 | +|   `pendingStatus` | `int` | | 待审批目标状态 | +|   `seatCount` | `int` | | 座位数 | +|   `sortOrder` | `int` | | 排序权重 | +|   `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +|   `subtitle` | `string` | | 副标题 | +|   `tags` | `车辆标签VO[]` | | 标签列表 | +|     `createdAt` | `string` | | 创建时间 | +|     `tagColor` | `string` | | 标签颜色（十六进制） | +|     `tagId` | `string` | | 标签ID | +|     `tagName` | `string` | | 标签名称 | +|     `tagType` | `int` | | 标签类型：0=自定义 1=系统 | +|     `useCount` | `int` | | 使用次数 | +|   `vehicleId` | `string` | | 车型ID | +|   `vehicleType` | `string` | | 车型分类 | +|   `viewCount` | `int` | | 浏览量 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/vehicle/models/batch + +**批量删除** + +批量软删除多个车型。仅SUPER_ADMIN或创建者可操作。 + +**请求体** `车型批量删除请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `vehicleIds` | `long[]` | 是 | 车型ID列表 | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/vehicle/models/batch/status + +**批量更新状态** + +批量修改多个车型的状态，跳过审批流程。 + +**请求体** `车型状态请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `status` | `int` | 是 | 目标状态：0=草稿 1=上架 2=下架 | +| `vehicleIds` | `long[]` | | 车型ID列表（批量操作时使用） | + +**响应** `统一响应结果«Void»` + +--- + +## 餐厅标签管理 + +### `PUT` /admin/restaurant/item/{restaurantId}/tags + +**更新餐厅标签** + +全量替换指定餐厅的标签列表。传入tagIds为最终关联的标签ID列表，为空则清除所有标签。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `restaurantId` | `integer` | | 餐厅ID | + +**请求体** `餐厅标签更新请求_1` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagIds` | `string[]` | | 标签ID列表 | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/restaurant/items/batch/tags + +**批量打标签** + +对多个餐厅批量添加/移除标签。增量操作，不影响未指定的标签。 + +**请求体** `餐厅批量标签操作请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `addTagIds` | `string[]` | | 要添加的标签ID列表 | +| `removeTagIds` | `string[]` | | 要移除的标签ID列表 | +| `restaurantIds` | `string[]` | 是 | 餐厅ID列表 | + +**响应** `统一响应结果«Void»` + +--- + +### `POST` /admin/restaurant/tag + +**创建管理标签** + +创建预设标签，标签名不可重复。可指定颜色(tagColor)，默认#409EFF。 + +**请求体** `餐厅标签创建请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagColor` | `string` | | 标签颜色（十六进制） | +| `tagName` | `string` | 是 | 标签名称 | + +**响应** `统一响应结果«餐厅标签视图»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `餐厅标签视图` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `tagColor` | `string` | | 标签颜色 | +|   `tagId` | `string` | | 标签ID | +|   `tagName` | `string` | | 标签名称 | +|   `tagType` | `int` | | 标签类型：1=系统标签 2=自定义标签 | +|   `useCount` | `int` | | 使用次数 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/restaurant/tag/adhoc + +**解析自定义标签** + +按名称查找或自动创建标签。用于餐厅编辑时快速输入新标签。 + +**请求体** `餐厅标签创建请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagColor` | `string` | | 标签颜色（十六进制） | +| `tagName` | `string` | 是 | 标签名称 | + +**响应** `统一响应结果«餐厅标签视图»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `餐厅标签视图` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `tagColor` | `string` | | 标签颜色 | +|   `tagId` | `string` | | 标签ID | +|   `tagName` | `string` | | 标签名称 | +|   `tagType` | `int` | | 标签类型：1=系统标签 2=自定义标签 | +|   `useCount` | `int` | | 使用次数 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/restaurant/tag/{tagId} + +**编辑标签** + +修改标签名称或颜色，所有关联餐厅自动生效。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagId` | `integer` | | 标签ID | + +**请求体** `餐厅标签更新请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagColor` | `string` | | 标签颜色（十六进制） | +| `tagName` | `string` | | 标签名称 | + +**响应** `统一响应结果«餐厅标签视图»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `餐厅标签视图` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `tagColor` | `string` | | 标签颜色 | +|   `tagId` | `string` | | 标签ID | +|   `tagName` | `string` | | 标签名称 | +|   `tagType` | `int` | | 标签类型：1=系统标签 2=自定义标签 | +|   `useCount` | `int` | | 使用次数 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/restaurant/tag/{tagId} + +**删除标签** + +删除标签并解除所有餐厅与该标签的关联。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `tagId` | `integer` | | 标签ID | + +**响应** `统一响应结果«Void»` + +--- + +### `GET` /admin/restaurant/tags + +**获取管理标签列表（分页）** + +分页查询餐厅标签库，支持按关键词搜索。包含预设标签和自定义标签。 + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `keyword` | `string` | | 关键词 | | +| `page` | `integer(int32)` | | 页码 | | +| `pageSize` | `integer(int32)` | | 每页条数 | | + +**响应** `统一响应结果«分页结果«餐厅标签视图»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«餐厅标签视图»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `餐厅标签视图[]` | | 数据列表 | +|     `createdAt` | `string` | | 创建时间 | +|     `tagColor` | `string` | | 标签颜色 | +|     `tagId` | `string` | | 标签ID | +|     `tagName` | `string` | | 标签名称 | +|     `tagType` | `int` | | 标签类型：1=系统标签 2=自定义标签 | +|     `useCount` | `int` | | 使用次数 | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/restaurant/tags/all + +**获取全部标签** + +不分页返回所有标签，用于餐厅编辑时的标签选择下拉。 + +**响应** `统一响应结果«List«餐厅标签视图»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `餐厅标签视图[]` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `tagColor` | `string` | | 标签颜色 | +|   `tagId` | `string` | | 标签ID | +|   `tagName` | `string` | | 标签名称 | +|   `tagType` | `int` | | 标签类型：1=系统标签 2=自定义标签 | +|   `useCount` | `int` | | 使用次数 | +| `message` | `string` | | 响应消息 | + +--- + +## 餐厅管理 + +### `POST` /admin/restaurant/item + +**创建餐厅** + +新建餐厅资源，初始状态为草稿(status=0)。餐厅没有价格日历，费用通过产品报价中的费用项管理。需走企微审批流程上架。 + +**关联字典**： +- restaurant_category：餐厅分类（表单选择） +- cuisine_type：菜系类型（表单多选） +- environment_type：环境类型（表单多选） +- restaurant_facility：餐厅设施（表单多选） + +**纯文本字段**： +- cityName：城市名称（手动输入，如「拉萨」「海拉尔」） + +**请求体** `餐厅创建请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `address` | `string` | | 详细地址 | +| `arrangement` | `string` | | 座位布局说明 | +| `bannerMaterialIds` | `string[]` | | 轮播图素材ID列表 | +| `businessHours` | `string` | | 营业时间 | +| `capacity` | `int` | | 容纳人数 | +| `categoryCode` | `string` | 是 | 分类编码 | +| `city` | `string` | 是 | 城市 | +| `cityName` | `string` | 是 | 城市名称（纯文本输入） | +| `closedDay` | `string` | | 休息日 | +| `coverMaterialId` | `string` | | 封面素材ID | +| `cuisineType` | `string` | | 菜系类型 | +| `description` | `string` | | 餐厅描述 | +| `district` | `string` | | 区县 | +| `environmentType` | `string` | | 环境类型 | +| `facilities` | `string[]` | | 设施列表 | +| `featureIntro` | `string` | | 图文详情（JSON格式） | +| `featuredMenu` | `string` | | 招牌菜单（JSON格式） | +| `groupSizeMax` | `int` | | 最多接待人数 | +| `groupSizeMin` | `int` | | 最少成行人数 | +| `hasPrivateRoom` | `int` | | 是否有包间：0=无 1=有 | +| `highlights` | `string` | | 亮点摘要 | +| `latitude` | `number` | 是 | 纬度 | +| `longitude` | `number` | 是 | 经度 | +| `minAdvanceHours` | `int` | | 最少提前预约小时数 | +| `name` | `string` | 是 | 餐厅名称 | +| `phone` | `string` | | 联系电话 | +| `pricePerPerson` | `number` | | 人均消费（元） | +| `province` | `string` | 是 | 省份 | +| `recommended` | `int` | | 是否推荐：0=否 1=是 | +| `reservationRequired` | `int` | | 是否需要预约：0=否 1=是 | +| `sortOrder` | `int` | | 排序权重（数字越大越靠前） | +| `subtitle` | `string` | | 副标题 | +| `videoMaterialIds` | `string[]` | | 视频素材ID列表 | + +**响应** `统一响应结果«餐厅详情视图»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `餐厅详情视图` | | 响应数据 | +|   `address` | `string` | | 详细地址 | +|   `arrangement` | `string` | | 座位布局说明 | +|   `bannerMaterialIds` | `string[]` | | 轮播图素材ID列表 | +|   `bannerUrls` | `string[]` | | 轮播图URL列表 | +|   `businessHours` | `string` | | 营业时间 | +|   `capacity` | `int` | | 容纳人数 | +|   `categoryCode` | `string` | | 分类编码 | +|   `categoryName` | `string` | | 分类名称 | +|   `city` | `string` | | 城市 | +|   `cityName` | `string` | | 城市名称（纯文本） | +|   `closedDay` | `string` | | 休息日 | +|   `coverMaterialId` | `string` | | 封面素材ID | +|   `coverUrl` | `string` | | 封面图URL | +|   `createdAt` | `string` | | 创建时间 | +|   `createdBy` | `string` | | 创建人ID | +|   `createdByName` | `string` | | 创建人姓名 | +|   `cuisineType` | `string` | | 菜系类型编码 | +|   `cuisineTypeName` | `string` | | 菜系类型名称 | +|   `description` | `string` | | 餐厅描述 | +|   `district` | `string` | | 区县 | +|   `environmentType` | `string` | | 环境类型 | +|   `facilities` | `string[]` | | 设施编码列表 | +|   `facilityNames` | `string[]` | | 设施名称列表 | +|   `featureIntro` | `string` | | 图文详情（JSON格式） | +|   `featuredMenu` | `string` | | 招牌菜单（JSON格式） | +|   `groupSizeMax` | `int` | | 最多接待人数 | +|   `groupSizeMin` | `int` | | 最少成行人数 | +|   `hasPrivateRoom` | `int` | | 是否有包间：0=无 1=有 | +|   `highlights` | `string` | | 亮点摘要 | +|   `latitude` | `number` | | 纬度 | +|   `longitude` | `number` | | 经度 | +|   `minAdvanceHours` | `int` | | 最少提前预约小时数 | +|   `name` | `string` | | 餐厅名称 | +|   `phone` | `string` | | 联系电话 | +|   `pricePerPerson` | `number` | | 人均消费（元） | +|   `province` | `string` | | 省份 | +|   `rating` | `number` | | 评分 | +|   `recommended` | `int` | | 是否推荐：0=否 1=是 | +|   `reservationRequired` | `int` | | 是否需要预约：0=否 1=是 | +|   `restaurantId` | `string` | | 餐厅ID | +|   `reviewCount` | `int` | | 评论数 | +|   `sortOrder` | `int` | | 排序权重 | +|   `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +|   `subtitle` | `string` | | 副标题 | +|   `tags` | `餐厅标签视图[]` | | 标签列表 | +|     `createdAt` | `string` | | 创建时间 | +|     `tagColor` | `string` | | 标签颜色 | +|     `tagId` | `string` | | 标签ID | +|     `tagName` | `string` | | 标签名称 | +|     `tagType` | `int` | | 标签类型：1=系统标签 2=自定义标签 | +|     `useCount` | `int` | | 使用次数 | +|   `updatedAt` | `string` | | 更新时间 | +|   `videoMaterialIds` | `string[]` | | 视频素材ID列表 | +|   `videoUrls` | `string[]` | | 视频URL列表 | +|   `viewCount` | `int` | | 浏览量 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/restaurant/item/{restaurantId} + +**餐厅详情** + +获取餐厅完整信息，包含素材URL、标签、富文本介绍等。 + +**关联字典**： +- restaurant_category：餐厅分类（详情显示） +- cuisine_type：菜系类型（详情显示） +- environment_type：环境类型（详情显示） +- restaurant_facility：餐厅设施（详情显示） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `restaurantId` | `integer` | | 餐厅ID | + +**响应** `统一响应结果«餐厅详情视图»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `餐厅详情视图` | | 响应数据 | +|   `address` | `string` | | 详细地址 | +|   `arrangement` | `string` | | 座位布局说明 | +|   `bannerMaterialIds` | `string[]` | | 轮播图素材ID列表 | +|   `bannerUrls` | `string[]` | | 轮播图URL列表 | +|   `businessHours` | `string` | | 营业时间 | +|   `capacity` | `int` | | 容纳人数 | +|   `categoryCode` | `string` | | 分类编码 | +|   `categoryName` | `string` | | 分类名称 | +|   `city` | `string` | | 城市 | +|   `cityName` | `string` | | 城市名称（纯文本） | +|   `closedDay` | `string` | | 休息日 | +|   `coverMaterialId` | `string` | | 封面素材ID | +|   `coverUrl` | `string` | | 封面图URL | +|   `createdAt` | `string` | | 创建时间 | +|   `createdBy` | `string` | | 创建人ID | +|   `createdByName` | `string` | | 创建人姓名 | +|   `cuisineType` | `string` | | 菜系类型编码 | +|   `cuisineTypeName` | `string` | | 菜系类型名称 | +|   `description` | `string` | | 餐厅描述 | +|   `district` | `string` | | 区县 | +|   `environmentType` | `string` | | 环境类型 | +|   `facilities` | `string[]` | | 设施编码列表 | +|   `facilityNames` | `string[]` | | 设施名称列表 | +|   `featureIntro` | `string` | | 图文详情（JSON格式） | +|   `featuredMenu` | `string` | | 招牌菜单（JSON格式） | +|   `groupSizeMax` | `int` | | 最多接待人数 | +|   `groupSizeMin` | `int` | | 最少成行人数 | +|   `hasPrivateRoom` | `int` | | 是否有包间：0=无 1=有 | +|   `highlights` | `string` | | 亮点摘要 | +|   `latitude` | `number` | | 纬度 | +|   `longitude` | `number` | | 经度 | +|   `minAdvanceHours` | `int` | | 最少提前预约小时数 | +|   `name` | `string` | | 餐厅名称 | +|   `phone` | `string` | | 联系电话 | +|   `pricePerPerson` | `number` | | 人均消费（元） | +|   `province` | `string` | | 省份 | +|   `rating` | `number` | | 评分 | +|   `recommended` | `int` | | 是否推荐：0=否 1=是 | +|   `reservationRequired` | `int` | | 是否需要预约：0=否 1=是 | +|   `restaurantId` | `string` | | 餐厅ID | +|   `reviewCount` | `int` | | 评论数 | +|   `sortOrder` | `int` | | 排序权重 | +|   `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +|   `subtitle` | `string` | | 副标题 | +|   `tags` | `餐厅标签视图[]` | | 标签列表 | +|     `createdAt` | `string` | | 创建时间 | +|     `tagColor` | `string` | | 标签颜色 | +|     `tagId` | `string` | | 标签ID | +|     `tagName` | `string` | | 标签名称 | +|     `tagType` | `int` | | 标签类型：1=系统标签 2=自定义标签 | +|     `useCount` | `int` | | 使用次数 | +|   `updatedAt` | `string` | | 更新时间 | +|   `videoMaterialIds` | `string[]` | | 视频素材ID列表 | +|   `videoUrls` | `string[]` | | 视频URL列表 | +|   `viewCount` | `int` | | 浏览量 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/restaurant/item/{restaurantId} + +**更新餐厅** + +更新餐厅基本信息，不改变当前状态。 + +**关联字典**： +- restaurant_category：餐厅分类（表单选择） +- cuisine_type：菜系类型（表单多选） +- environment_type：环境类型（表单多选） +- restaurant_facility：餐厅设施（表单多选） + +**纯文本字段**： +- cityName：城市名称（手动输入） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `restaurantId` | `integer` | | 餐厅ID | + +**请求体** `餐厅更新请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `address` | `string` | | 详细地址 | +| `arrangement` | `string` | | 座位布局说明 | +| `bannerMaterialIds` | `string[]` | | 轮播图素材ID列表 | +| `businessHours` | `string` | | 营业时间 | +| `capacity` | `int` | | 容纳人数 | +| `categoryCode` | `string` | | 分类编码 | +| `city` | `string` | | 城市 | +| `cityName` | `string` | | 城市名称（纯文本输入） | +| `closedDay` | `string` | | 休息日 | +| `coverMaterialId` | `string` | | 封面素材ID | +| `cuisineType` | `string` | | 菜系类型 | +| `description` | `string` | | 餐厅描述 | +| `district` | `string` | | 区县 | +| `environmentType` | `string` | | 环境类型 | +| `facilities` | `string[]` | | 设施列表 | +| `featureIntro` | `string` | | 图文详情（JSON格式） | +| `featuredMenu` | `string` | | 招牌菜单（JSON格式） | +| `groupSizeMax` | `int` | | 最多接待人数 | +| `groupSizeMin` | `int` | | 最少成行人数 | +| `hasPrivateRoom` | `int` | | 是否有包间：0=无 1=有 | +| `highlights` | `string` | | 亮点摘要 | +| `latitude` | `number` | | 纬度 | +| `longitude` | `number` | | 经度 | +| `minAdvanceHours` | `int` | | 最少提前预约小时数 | +| `name` | `string` | | 餐厅名称 | +| `phone` | `string` | | 联系电话 | +| `pricePerPerson` | `number` | | 人均消费（元） | +| `province` | `string` | | 省份 | +| `recommended` | `int` | | 是否推荐：0=否 1=是 | +| `reservationRequired` | `int` | | 是否需要预约：0=否 1=是 | +| `sortOrder` | `int` | | 排序权重（数字越大越靠前） | +| `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +| `subtitle` | `string` | | 副标题 | +| `videoMaterialIds` | `string[]` | | 视频素材ID列表 | + +**响应** `统一响应结果«餐厅详情视图»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `餐厅详情视图` | | 响应数据 | +|   `address` | `string` | | 详细地址 | +|   `arrangement` | `string` | | 座位布局说明 | +|   `bannerMaterialIds` | `string[]` | | 轮播图素材ID列表 | +|   `bannerUrls` | `string[]` | | 轮播图URL列表 | +|   `businessHours` | `string` | | 营业时间 | +|   `capacity` | `int` | | 容纳人数 | +|   `categoryCode` | `string` | | 分类编码 | +|   `categoryName` | `string` | | 分类名称 | +|   `city` | `string` | | 城市 | +|   `cityName` | `string` | | 城市名称（纯文本） | +|   `closedDay` | `string` | | 休息日 | +|   `coverMaterialId` | `string` | | 封面素材ID | +|   `coverUrl` | `string` | | 封面图URL | +|   `createdAt` | `string` | | 创建时间 | +|   `createdBy` | `string` | | 创建人ID | +|   `createdByName` | `string` | | 创建人姓名 | +|   `cuisineType` | `string` | | 菜系类型编码 | +|   `cuisineTypeName` | `string` | | 菜系类型名称 | +|   `description` | `string` | | 餐厅描述 | +|   `district` | `string` | | 区县 | +|   `environmentType` | `string` | | 环境类型 | +|   `facilities` | `string[]` | | 设施编码列表 | +|   `facilityNames` | `string[]` | | 设施名称列表 | +|   `featureIntro` | `string` | | 图文详情（JSON格式） | +|   `featuredMenu` | `string` | | 招牌菜单（JSON格式） | +|   `groupSizeMax` | `int` | | 最多接待人数 | +|   `groupSizeMin` | `int` | | 最少成行人数 | +|   `hasPrivateRoom` | `int` | | 是否有包间：0=无 1=有 | +|   `highlights` | `string` | | 亮点摘要 | +|   `latitude` | `number` | | 纬度 | +|   `longitude` | `number` | | 经度 | +|   `minAdvanceHours` | `int` | | 最少提前预约小时数 | +|   `name` | `string` | | 餐厅名称 | +|   `phone` | `string` | | 联系电话 | +|   `pricePerPerson` | `number` | | 人均消费（元） | +|   `province` | `string` | | 省份 | +|   `rating` | `number` | | 评分 | +|   `recommended` | `int` | | 是否推荐：0=否 1=是 | +|   `reservationRequired` | `int` | | 是否需要预约：0=否 1=是 | +|   `restaurantId` | `string` | | 餐厅ID | +|   `reviewCount` | `int` | | 评论数 | +|   `sortOrder` | `int` | | 排序权重 | +|   `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +|   `subtitle` | `string` | | 副标题 | +|   `tags` | `餐厅标签视图[]` | | 标签列表 | +|     `createdAt` | `string` | | 创建时间 | +|     `tagColor` | `string` | | 标签颜色 | +|     `tagId` | `string` | | 标签ID | +|     `tagName` | `string` | | 标签名称 | +|     `tagType` | `int` | | 标签类型：1=系统标签 2=自定义标签 | +|     `useCount` | `int` | | 使用次数 | +|   `updatedAt` | `string` | | 更新时间 | +|   `videoMaterialIds` | `string[]` | | 视频素材ID列表 | +|   `videoUrls` | `string[]` | | 视频URL列表 | +|   `viewCount` | `int` | | 浏览量 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/restaurant/item/{restaurantId} + +**删除餐厅** + +软删除餐厅。仅SUPER_ADMIN或创建者可操作。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `restaurantId` | `integer` | | 餐厅ID | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/restaurant/item/{restaurantId}/status + +**上下架切换** + +直接修改状态（跳过审批），仅限SUPER_ADMIN。状态值：0=草稿，1=上架，2=下架。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `restaurantId` | `integer` | | 餐厅ID | + +**请求体** `餐厅状态变更请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `restaurantIds` | `string[]` | | 餐厅ID列表（批量操作） | +| `status` | `int` | 是 | 目标状态：0=草稿 1=上架 2=下架 | + +**响应** `统一响应结果«Void»` + +--- + +### `POST` /admin/restaurant/item/{restaurantId}/submit-approval + +**提交启用/禁用审批** + +向企微OA提交审批。targetStatus=1申请上架，targetStatus=2申请下架。返回审批单号spNo。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `restaurantId` | `integer` | | 餐厅ID | + +**请求体** `餐厅审批提交请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `reason` | `string` | 是 | 审批理由 | +| `targetStatus` | `int` | 是 | 目标状态：1=上架 2=下架 | + +**响应** `统一响应结果«Map«string,string»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `object` | | 响应数据 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/restaurant/items + +**餐厅列表** + +分页查询餐厅列表，支持按名称、状态、分类、城市等条件筛选。 + +**关联字典**： +- restaurant_category：餐厅分类（筛选+列表显示） +- cuisine_type：菜系类型（列表显示） +- environment_type：环境类型（列表显示） +- restaurant_facility：餐厅设施（列表显示） + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `categoryCode` | `string` | | 分类编码 | TIBETAN | +| `city` | `string` | | 城市 | 拉萨市 | +| `cityName` | `string` | | 城市名称筛选（纯文本） | 拉萨 | +| `cuisineType` | `string` | | 菜系类型 | TIBETAN | +| `keyword` | `string` | | 搜索关键词（名称/副标题模糊搜索） | 藏餐 | +| `page` | `integer(int32)` | | 页码 | 1 | +| `pageSize` | `integer(int32)` | | 每页条数 | 20 | +| `province` | `string` | | 省份 | 西藏自治区 | +| `recommended` | `integer(int32)` | | 是否推荐：0=否 1=是 | 1 | +| `sortBy` | `string` | | 排序字段 | createdAt | +| `sortDir` | `string` | | 排序方向：asc=升序 desc=降序 | desc | +| `status` | `integer(int32)` | | 状态：0=草稿 1=上架 2=下架 | 1 | +| `tagId` | `integer(int64)` | | 标签ID | 100 | +| `tagIds` | `string` | | 标签ID列表（逗号分隔） | 100,101,102 | + +**响应** `统一响应结果«分页结果«餐厅列表视图»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«餐厅列表视图»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `餐厅列表视图[]` | | 数据列表 | +|     `approvalNo` | `string` | | 审批编号 | +|     `categoryCode` | `string` | | 分类编码 | +|     `categoryName` | `string` | | 分类名称 | +|     `cityName` | `string` | | 城市名称（纯文本） | +|     `coverUrl` | `string` | | 封面图URL | +|     `createdAt` | `string` | | 创建时间 | +|     `cuisineType` | `string` | | 菜系类型编码 | +|     `cuisineTypeName` | `string` | | 菜系类型名称 | +|     `highlights` | `string` | | 亮点摘要 | +|     `name` | `string` | | 餐厅名称 | +|     `pendingStatus` | `int` | | 待审批目标状态 | +|     `pricePerPerson` | `number` | | 人均消费（元） | +|     `rating` | `number` | | 评分 | +|     `recommended` | `int` | | 是否推荐：0=否 1=是 | +|     `restaurantId` | `string` | | 餐厅ID | +|     `reviewCount` | `int` | | 评论数 | +|     `sortOrder` | `int` | | 排序权重 | +|     `status` | `int` | | 状态：0=草稿 1=上架 2=下架 | +|     `subtitle` | `string` | | 副标题 | +|     `tags` | `餐厅标签视图[]` | | 标签列表 | +|     `viewCount` | `int` | | 浏览量 | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/restaurant/items/batch + +**批量删除** + +批量软删除多个餐厅。仅SUPER_ADMIN或创建者可操作。 + +**请求体** `餐厅批量删除请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `restaurantIds` | `string[]` | 是 | 餐厅ID列表 | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/restaurant/items/batch/status + +**批量上下架** + +批量修改多个餐厅的状态，跳过审批流程。 + +**请求体** `餐厅状态变更请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `restaurantIds` | `string[]` | | 餐厅ID列表（批量操作） | +| `status` | `int` | 是 | 目标状态：0=草稿 1=上架 2=下架 | + +**响应** `统一响应结果«Void»` + +--- diff --git a/2026-03/17_0951/hl-user-service.md b/2026-03/17_0951/hl-user-service.md new file mode 100644 index 0000000..2978f52 --- /dev/null +++ b/2026-03/17_0951/hl-user-service.md @@ -0,0 +1,4501 @@ +# 用户服务 API 文档 + +**服务**: `hl-user-service` +**接口总数**: 135 + +## 目录 + +- **Banner管理接口** (5 个接口) +- **个人中心** (6 个接口) +- **个人中心（旧路径，已废弃）** (5 个接口) +- **企业微信同步接口** (7 个接口) +- **前端配置管理接口** (8 个接口) +- **字典管理接口** (12 个接口) +- **定时任务接口** (8 个接口) +- **客户管理接口** (4 个接口) +- **小程序接口** (21 个接口) +- **常见问题管理接口** (8 个接口) +- **探索分类管理接口** (5 个接口) +- **用户协议管理接口** (5 个接口) +- **管理员管理接口** (8 个接口) +- **管理员认证接口** (14 个接口) +- **联系我们管理接口** (5 个接口) +- **菜单管理接口** (7 个接口) +- **角色管理接口** (7 个接口) + +--- + +## Banner管理接口 + +### `GET` /admin/banner + +**Banner列表** + +分页查询Banner列表，支持按关键词和状态筛选。 + +**关联字典**： +- common_status（通用状态）：请求参数status和返回字段status（0=禁用, 1=启用） + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `keyword` | `string` | | 搜索关键词 | | +| `page` | `integer(int32)` | | 页码 | | +| `pageSize` | `integer(int32)` | | 每页条数 | | +| `status` | `integer(int32)` | | 状态 | | + +**响应** `统一响应结果«分页结果«Banner VO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«Banner VO»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `Banner VO[]` | | 数据列表 | +|     `createdAt` | `string` | | 创建时间 | +|     `endTime` | `string` | | 展示结束时间 | +|     `id` | `string` | | Banner ID | +|     `imageUrl` | `string` | | 图片URL（图片类型为图片，视频类型为封面图） | +|     `linkId` | `string` | | 链接目标ID（PRODUCT/SCENIC/ACTIVITY/HOTEL时有值） | +|     `linkTargetName` | `string` | | 链接目标名称（用于后台展示） | +|     `linkType` | `string` | | 链接类型：NONE=无链接 PRODUCT=产品 SCENIC=景区 ACTIVITY=活动 HOTEL=酒店 PAGE=小程序页面 WEBVIEW=网页 | +|     `linkUrl` | `string` | | 链接URL（PAGE时为路由名，WEBVIEW时为完整URL） | +|     `materialId` | `long` | | 素材库关联ID | +|     `mediaType` | `string` | | 媒体类型: IMAGE/VIDEO | +|     `sortOrder` | `int` | | 排序号 | +|     `startTime` | `string` | | 展示开始时间 | +|     `status` | `int` | | 状态：0=下线 1=上线 | +|     `subtitle` | `string` | | 副标题 | +|     `tags` | `string[]` | | 标签列表 | +|     `title` | `string` | | 标题 | +|     `videoUrl` | `string` | | 视频URL（媒体类型为VIDEO时有值） | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/banner + +**创建Banner** + +创建新的首页轮播图，包括标题、封面图、跳转链接、排序等。 + +**权限**：需要管理员登录。 +**注意**：创建后默认为启用状态，小程序端将按排序展示。 + +**请求体** `Banner请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `endTime` | `string` | | 展示结束时间 | +| `imageUrl` | `string` | 是 | Banner图片URL（图片类型时为图片，视频类型时为封面图） | +| `linkId` | `string` | | 链接目标ID（linkType=PRODUCT时为产品ID） | +| `linkTargetName` | `string` | | 链接目标名称（用于后台展示） | +| `linkType` | `string` | | 链接类型：NONE=无链接 PRODUCT=产品 SCENIC=景区 ACTIVITY=活动 HOTEL=酒店 PAGE=小程序页面 WEBVIEW=网页 | +| `linkUrl` | `string` | | 链接URL（linkType=WEBVIEW/PAGE时生效） | +| `materialId` | `long` | | 素材库关联ID（从素材库选择时传入） | +| `mediaType` | `string` | | 媒体类型: IMAGE/VIDEO | +| `sortOrder` | `int` | | 排序号（越小越靠前） | +| `startTime` | `string` | | 展示开始时间 | +| `status` | `int` | | 状态：0=下线 1=上线 | +| `subtitle` | `string` | | 副标题 | +| `tags` | `string` | | 标签（逗号分隔） | +| `title` | `string` | 是 | Banner标题 | +| `videoUrl` | `string` | | 视频URL（媒体类型为VIDEO时必填） | + +**响应** `统一响应结果«Banner VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `Banner VO` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `endTime` | `string` | | 展示结束时间 | +|   `id` | `string` | | Banner ID | +|   `imageUrl` | `string` | | 图片URL（图片类型为图片，视频类型为封面图） | +|   `linkId` | `string` | | 链接目标ID（PRODUCT/SCENIC/ACTIVITY/HOTEL时有值） | +|   `linkTargetName` | `string` | | 链接目标名称（用于后台展示） | +|   `linkType` | `string` | | 链接类型：NONE=无链接 PRODUCT=产品 SCENIC=景区 ACTIVITY=活动 HOTEL=酒店 PAGE=小程序页面 WEBVIEW=网页 | +|   `linkUrl` | `string` | | 链接URL（PAGE时为路由名，WEBVIEW时为完整URL） | +|   `materialId` | `long` | | 素材库关联ID | +|   `mediaType` | `string` | | 媒体类型: IMAGE/VIDEO | +|   `sortOrder` | `int` | | 排序号 | +|   `startTime` | `string` | | 展示开始时间 | +|   `status` | `int` | | 状态：0=下线 1=上线 | +|   `subtitle` | `string` | | 副标题 | +|   `tags` | `string[]` | | 标签列表 | +|   `title` | `string` | | 标题 | +|   `videoUrl` | `string` | | 视频URL（媒体类型为VIDEO时有值） | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/banner/{id} + +**Banner详情** + +获取指定Banner的详细信息，包括标题、图片、跳转链接、排序等。 + +**权限**：需要管理员登录。 + +**关联字典**： +- common_status（通用状态）：返回字段status（0=禁用, 1=启用） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `id` | `integer` | | 轮播图ID | + +**响应** `统一响应结果«Banner VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `Banner VO` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `endTime` | `string` | | 展示结束时间 | +|   `id` | `string` | | Banner ID | +|   `imageUrl` | `string` | | 图片URL（图片类型为图片，视频类型为封面图） | +|   `linkId` | `string` | | 链接目标ID（PRODUCT/SCENIC/ACTIVITY/HOTEL时有值） | +|   `linkTargetName` | `string` | | 链接目标名称（用于后台展示） | +|   `linkType` | `string` | | 链接类型：NONE=无链接 PRODUCT=产品 SCENIC=景区 ACTIVITY=活动 HOTEL=酒店 PAGE=小程序页面 WEBVIEW=网页 | +|   `linkUrl` | `string` | | 链接URL（PAGE时为路由名，WEBVIEW时为完整URL） | +|   `materialId` | `long` | | 素材库关联ID | +|   `mediaType` | `string` | | 媒体类型: IMAGE/VIDEO | +|   `sortOrder` | `int` | | 排序号 | +|   `startTime` | `string` | | 展示开始时间 | +|   `status` | `int` | | 状态：0=下线 1=上线 | +|   `subtitle` | `string` | | 副标题 | +|   `tags` | `string[]` | | 标签列表 | +|   `title` | `string` | | 标题 | +|   `videoUrl` | `string` | | 视频URL（媒体类型为VIDEO时有值） | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/banner/{id} + +**更新Banner** + +更新指定Banner的标题、封面图、跳转链接、排序、状态等信息。 + +**权限**：需要管理员登录。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `id` | `integer` | | 轮播图ID | + +**请求体** `Banner请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `endTime` | `string` | | 展示结束时间 | +| `imageUrl` | `string` | 是 | Banner图片URL（图片类型时为图片，视频类型时为封面图） | +| `linkId` | `string` | | 链接目标ID（linkType=PRODUCT时为产品ID） | +| `linkTargetName` | `string` | | 链接目标名称（用于后台展示） | +| `linkType` | `string` | | 链接类型：NONE=无链接 PRODUCT=产品 SCENIC=景区 ACTIVITY=活动 HOTEL=酒店 PAGE=小程序页面 WEBVIEW=网页 | +| `linkUrl` | `string` | | 链接URL（linkType=WEBVIEW/PAGE时生效） | +| `materialId` | `long` | | 素材库关联ID（从素材库选择时传入） | +| `mediaType` | `string` | | 媒体类型: IMAGE/VIDEO | +| `sortOrder` | `int` | | 排序号（越小越靠前） | +| `startTime` | `string` | | 展示开始时间 | +| `status` | `int` | | 状态：0=下线 1=上线 | +| `subtitle` | `string` | | 副标题 | +| `tags` | `string` | | 标签（逗号分隔） | +| `title` | `string` | 是 | Banner标题 | +| `videoUrl` | `string` | | 视频URL（媒体类型为VIDEO时必填） | + +**响应** `统一响应结果«Banner VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `Banner VO` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `endTime` | `string` | | 展示结束时间 | +|   `id` | `string` | | Banner ID | +|   `imageUrl` | `string` | | 图片URL（图片类型为图片，视频类型为封面图） | +|   `linkId` | `string` | | 链接目标ID（PRODUCT/SCENIC/ACTIVITY/HOTEL时有值） | +|   `linkTargetName` | `string` | | 链接目标名称（用于后台展示） | +|   `linkType` | `string` | | 链接类型：NONE=无链接 PRODUCT=产品 SCENIC=景区 ACTIVITY=活动 HOTEL=酒店 PAGE=小程序页面 WEBVIEW=网页 | +|   `linkUrl` | `string` | | 链接URL（PAGE时为路由名，WEBVIEW时为完整URL） | +|   `materialId` | `long` | | 素材库关联ID | +|   `mediaType` | `string` | | 媒体类型: IMAGE/VIDEO | +|   `sortOrder` | `int` | | 排序号 | +|   `startTime` | `string` | | 展示开始时间 | +|   `status` | `int` | | 状态：0=下线 1=上线 | +|   `subtitle` | `string` | | 副标题 | +|   `tags` | `string[]` | | 标签列表 | +|   `title` | `string` | | 标题 | +|   `videoUrl` | `string` | | 视频URL（媒体类型为VIDEO时有值） | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/banner/{id} + +**删除Banner** + +删除指定的Banner记录（软删除）。 + +**权限**：需要管理员登录。 +**注意**：删除后小程序首页将不再展示该Banner。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `id` | `integer` | | 轮播图ID | + +**响应** `统一响应结果«Void»` + +--- + +## 个人中心 + +### `GET` /admin/profile/dashboard + +**工作台仪表盘（角色分发，支持时间范围）** + +根据当前管理员角色返回不同的仪表盘数据。CUSTOMIZER（定制师）：待处理订单数、产品数、评价统计等。SUPER_ADMIN/ADMIN：全局概览（订单、收入、用户增长等）。ROOM_MANAGER（客房管理）：房间分配概览。VEHICLE_MANAGER（车辆管理）：车辆调度概览。FINANCE（财务）：收支统计。MATERIAL_ADMIN（素材管理）：素材库概览。period取值：today=今日 week=本周 month=本月。需要管理员认证。 + +**关联字典**： +- order_status（订单状态）：仪表盘中订单统计按状态分组展示 + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `period` | `string` | | 时间范围: today/week/month | | + +**响应** `统一响应结果«object»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `object` | | 响应数据 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/profile/me + +**获取我的个人资料** + +获取当前登录管理员的个人资料，根据角色返回不同的资料内容。 +定制师角色会返回认证等级、个人简介、擅长领域等附加信息。 + +**权限**：需要管理员登录。 + +**关联字典**： +- designer_cert_level（认证等级）：返回字段certLevel（none/bronze/silver/gold/diamond） + +**响应** `统一响应结果«个人资料VO（角色感知）»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `个人资料VO（角色感知）` | | 响应数据 | +|   `adminId` | `string` | | 管理员用户ID | +|   `avatar` | `string` | | 头像URL | +|   `certLevel` | `string` | | 认证等级（定制师专属） | +|   `certified` | `boolean` | | 是否已认证（定制师专属） | +|   `contactQrUrl` | `string` | | 企业微信联系二维码URL | +|   `createdAt` | `string` | | 创建时间 | +|   `description` | `string` | | 个人简介（定制师专属） | +|   `experience` | `int` | | 从业年限（定制师专属） | +|   `isFeatured` | `boolean` | | 是否推荐（定制师专属） | +|   `motto` | `string` | | 座右铭（定制师专属） | +|   `name` | `string` | | 姓名 | +|   `phone` | `string` | | 手机号 | +|   `role` | `string` | | 当前角色key | +|   `roleName` | `string` | | 角色中文名 | +|   `serviceAreas` | `string[]` | | 服务区域（定制师专属） | +|   `sortOrder` | `int` | | 展示排序（定制师专属） | +|   `specialties` | `string[]` | | 擅长领域（定制师专属） | +|   `updatedAt` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/profile/me + +**更新我的个人资料** + +更新当前登录管理员的个人资料，支持修改昵称、头像、个人简介等。 +定制师角色可额外更新擅长领域、服务区域等信息。 + +**权限**：需要管理员登录。 + +**请求体** `更新定制师个人资料请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `certLevel` | `string` | | 认证等级：none/bronze/silver/gold/diamond | +| `certified` | `boolean` | | 是否已认证 | +| `description` | `string` | | 个人简介 | +| `experience` | `int` | | 从业年限 | +| `isFeatured` | `boolean` | | 是否推荐 | +| `motto` | `string` | | 座右铭 | +| `serviceAreas` | `string[]` | | 服务区域列表 | +| `sortOrder` | `int` | | 展示排序 | +| `specialties` | `string[]` | | 擅长领域列表 | + +**响应** `统一响应结果«个人资料VO（角色感知）»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `个人资料VO（角色感知）` | | 响应数据 | +|   `adminId` | `string` | | 管理员用户ID | +|   `avatar` | `string` | | 头像URL | +|   `certLevel` | `string` | | 认证等级（定制师专属） | +|   `certified` | `boolean` | | 是否已认证（定制师专属） | +|   `contactQrUrl` | `string` | | 企业微信联系二维码URL | +|   `createdAt` | `string` | | 创建时间 | +|   `description` | `string` | | 个人简介（定制师专属） | +|   `experience` | `int` | | 从业年限（定制师专属） | +|   `isFeatured` | `boolean` | | 是否推荐（定制师专属） | +|   `motto` | `string` | | 座右铭（定制师专属） | +|   `name` | `string` | | 姓名 | +|   `phone` | `string` | | 手机号 | +|   `role` | `string` | | 当前角色key | +|   `roleName` | `string` | | 角色中文名 | +|   `serviceAreas` | `string[]` | | 服务区域（定制师专属） | +|   `sortOrder` | `int` | | 展示排序（定制师专属） | +|   `specialties` | `string[]` | | 擅长领域（定制师专属） | +|   `updatedAt` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/profile/orders + +**订单列表** + +查询当前定制师的订单列表，支持按状态筛选。 + +**关联字典**： +- order_status（订单状态）：请求参数status和返回字段status + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `keyword` | `string` | | 搜索关键词 | | +| `page` | `integer(int32)` | | 页码 | | +| `pageSize` | `integer(int32)` | | 每页条数 | | +| `status` | `string` | | 订单状态 | | + +**响应** `统一响应结果«分页结果«Map«string,object»»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«Map«string,object»»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `Map«string,object»[]` | | 数据列表 | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/profile/products + +**产品列表** + +查询当前定制师的产品列表，支持按状态筛选。 + +**关联字典**： +- product_status（产品状态）：请求参数status和返回字段status + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `keyword` | `string` | | 搜索关键词 | | +| `page` | `integer(int32)` | | 页码 | | +| `pageSize` | `integer(int32)` | | 每页条数 | | +| `status` | `string` | | 产品状态 | | + +**响应** `统一响应结果«分页结果«Map«string,object»»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«Map«string,object»»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `Map«string,object»[]` | | 数据列表 | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/profile/reviews + +**我的评价列表** + +查询当前定制师收到的评价列表，支持按评价等级筛选。 + +**关联字典**： +- rating_level（评价等级）：GOOD=好评, MEDIUM=中评, BAD=差评（筛选条件+列表展示） + + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `page` | `integer(int32)` | | 页码 | | +| `pageSize` | `integer(int32)` | | 每页条数 | | +| `ratingLevel` | `string` | | 评价等级: GOOD/MEDIUM/BAD | | + +**响应** `统一响应结果«分页结果«Map«string,object»»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«Map«string,object»»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `Map«string,object»[]` | | 数据列表 | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +## 个人中心（旧路径，已废弃） + +### `GET` /admin/designer/dashboard + +**工作台概览（已废弃，请使用 /admin/profile/dashboard）** + +已废弃接口，请迁移至 GET /admin/profile/dashboard。 + +**权限**：需要管理员登录。 + +**响应** `统一响应结果«定制师工作台VO（重构版）»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `定制师工作台VO（重构版）` | | 响应数据 | +|   `calendarEvents` | `Map«string,object»[]` | | 日历事件 | +|   `customerStats` | `客户统计` | | 客户统计 | +|     `customerAddCount` | `int` | | 新增客户数 | +|     `customerLossCount` | `int` | | 客户流失数 | +|   `funnel` | `object` | | 转化漏斗 | +|   `overview` | `数据概览` | | 数据概览 | +|     `gmv` | `number` | | 当期GMV | +|     `gmvDiffRate` | `number` | | 与前一期GMV增长率 | +|     `orderCount` | `long` | | 当期订单数 | +|     `orderCountDiff` | `long` | | 与前一期订单数差值 | +|     `period` | `string` | | 当期时间范围 | +|   `productStats` | `产品统计` | | 产品统计 | +|     `publishedProducts` | `int` | | 已上架产品数 | +|     `totalProducts` | `int` | | 产品总数 | +|   `ranking` | `Map«string,object»[]` | | 本月业绩排行 | +|   `reviewStats` | `评价统计` | | 评价统计 | +|     `averageRating` | `number` | | 平均评分(1-5) | +|     `goodRate` | `number` | | 好评率(%) | +|     `totalReviews` | `int` | | 评价总数 | +|   `shortcuts` | `快捷入口[]` | | 快捷入口列表 | +|     `icon` | `string` | | 图标 | +|     `name` | `string` | | 名称 | +|     `path` | `string` | | 路径 | +|   `todos` | `object` | | 待办汇总 | +|   `trend` | `Map«string,object»[]` | | 数据趋势（按天） | +|   `upcomingTrips` | `Map«string,object»[]` | | 即将出行列表 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/designer/orders + +**我的订单列表（已废弃，请使用 /admin/profile/orders）** + +已废弃接口。 + +**关联字典**： +- order_status（订单状态）：请求参数status和返回字段status + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `keyword` | `string` | | keyword | | +| `page` | `integer(int32)` | | page | | +| `pageSize` | `integer(int32)` | | pageSize | | +| `status` | `string` | | status | | + +**响应** `统一响应结果«分页结果«Map«string,object»»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«Map«string,object»»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `Map«string,object»[]` | | 数据列表 | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/designer/products + +**我的产品列表（已废弃，请使用 /admin/profile/products）** + +已废弃接口。 + +**关联字典**： +- product_status（产品状态）：请求参数status和返回字段status + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `keyword` | `string` | | keyword | | +| `page` | `integer(int32)` | | page | | +| `pageSize` | `integer(int32)` | | pageSize | | +| `status` | `string` | | status | | + +**响应** `统一响应结果«分页结果«Map«string,object»»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«Map«string,object»»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `Map«string,object»[]` | | 数据列表 | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/designer/profile + +**获取我的个人资料（已废弃，请使用 /admin/profile/me）** + +已废弃接口。 + +**关联字典**： +- designer_cert_level（认证等级）：返回字段certLevel（none/bronze/silver/gold/diamond） + +**响应** `统一响应结果«定制师个人资料VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `定制师个人资料VO` | | 响应数据 | +|   `adminId` | `string` | | 管理员用户ID | +|   `avatar` | `string` | | 头像URL | +|   `certLevel` | `string` | | 认证等级：none/bronze/silver/gold/diamond | +|   `certified` | `boolean` | | 是否已认证 | +|   `contactQrUrl` | `string` | | 企业微信联系二维码URL | +|   `createdAt` | `string` | | 创建时间 | +|   `description` | `string` | | 个人简介 | +|   `experience` | `int` | | 从业年限 | +|   `isFeatured` | `boolean` | | 是否推荐 | +|   `motto` | `string` | | 座右铭 | +|   `name` | `string` | | 姓名（优先取企微名称，否则管理员用户名） | +|   `phone` | `string` | | 手机号 | +|   `serviceAreas` | `string[]` | | 服务区域列表 | +|   `sortOrder` | `int` | | 展示排序 | +|   `specialties` | `string[]` | | 擅长领域列表 | +|   `updatedAt` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/designer/profile + +**更新我的个人资料（已废弃，请使用 PUT /admin/profile/me）** + +已废弃接口，请迁移至 PUT /admin/profile/me。 + +**权限**：需要管理员登录。 + +**请求体** `更新定制师个人资料请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `certLevel` | `string` | | 认证等级：none/bronze/silver/gold/diamond | +| `certified` | `boolean` | | 是否已认证 | +| `description` | `string` | | 个人简介 | +| `experience` | `int` | | 从业年限 | +| `isFeatured` | `boolean` | | 是否推荐 | +| `motto` | `string` | | 座右铭 | +| `serviceAreas` | `string[]` | | 服务区域列表 | +| `sortOrder` | `int` | | 展示排序 | +| `specialties` | `string[]` | | 擅长领域列表 | + +**响应** `统一响应结果«定制师个人资料VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `定制师个人资料VO` | | 响应数据 | +|   `adminId` | `string` | | 管理员用户ID | +|   `avatar` | `string` | | 头像URL | +|   `certLevel` | `string` | | 认证等级：none/bronze/silver/gold/diamond | +|   `certified` | `boolean` | | 是否已认证 | +|   `contactQrUrl` | `string` | | 企业微信联系二维码URL | +|   `createdAt` | `string` | | 创建时间 | +|   `description` | `string` | | 个人简介 | +|   `experience` | `int` | | 从业年限 | +|   `isFeatured` | `boolean` | | 是否推荐 | +|   `motto` | `string` | | 座右铭 | +|   `name` | `string` | | 姓名（优先取企微名称，否则管理员用户名） | +|   `phone` | `string` | | 手机号 | +|   `serviceAreas` | `string[]` | | 服务区域列表 | +|   `sortOrder` | `int` | | 展示排序 | +|   `specialties` | `string[]` | | 擅长领域列表 | +|   `updatedAt` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +## 企业微信同步接口 + +### `GET` /admin/wechat/departments + +**部门列表（部门管理页面）** + +获取已同步的所有企业微信部门列表（平铺结构），用于部门管理页面展示。 +包含部门ID、名称、上级部门ID、排序等信息。 + +**权限**：需要管理员登录。 + +**响应** `统一响应结果«List«WechatDepartment»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `WechatDepartment[]` | | 响应数据 | +|   `createdAt` | `string` | | | +|   `deptId` | `long` | | | +|   `deptName` | `string` | | | +|   `orderIndex` | `int` | | | +|   `parentId` | `long` | | | +|   `status` | `string` | | | +|   `syncedAt` | `string` | | | +|   `updatedAt` | `string` | | | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/wechat/departments/tree + +**部门树（下拉筛选）** + +以树形结构返回企业微信部门数据。用于部门筛选下拉框，每个节点包含id/label/children。需要管理员认证。 + +**响应** `统一响应结果«List«Map«string,object»»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `Map«string,object»[]` | | 响应数据 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/wechat/sync/all + +**手动同步全部（部门+用户）** + +一键同步企业微信的部门和用户数据，先同步部门再同步用户。推荐使用此接口而非单独同步，确保部门和用户数据一致性。同步过程为异步执行，接口立即返回成功。需要SUPER_ADMIN角色。 + +**响应** `统一响应结果«Void»` + +--- + +### `POST` /admin/wechat/sync/departments + +**手动同步部门** + +从企业微信拉取最新的部门列表并同步到本地数据库。通常在企业微信后台调整组织架构后手动触发。也可通过定时任务自动执行。需要SUPER_ADMIN角色。 + +**响应** `统一响应结果«Void»` + +--- + +### `GET` /admin/wechat/sync/status + +**同步状态（最后同步时间）** + +获取企业微信数据的最后同步时间和状态。 +返回部门和用户各自的最后同步时间，用于管理页面展示同步状态。 + +**权限**：需要管理员登录。 + +**响应** `统一响应结果«Map«string,object»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `object` | | 响应数据 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/wechat/sync/users + +**手动同步用户** + +从企业微信拉取所有部门的成员列表并同步到本地数据库。包括姓名、手机号、职位、部门归属等信息。需先同步部门再同步用户，或直接使用[同步全部]接口。需要SUPER_ADMIN角色。 + +**响应** `统一响应结果«Void»` + +--- + +### `GET` /admin/wechat/users + +**查询企业微信用户（分页+搜索）** + +分页查询已同步的企业微信用户列表。支持按姓名/手机号/职位关键词搜索，按部门ID和状态筛选。status取值：1=已激活 2=已禁用 4=未关注。用于管理员绑定企微账号时选择企微用户。需要管理员认证。 + +**关联字典**： +- wechat_user_status（企微用户状态）：请求参数status和返回字段status（1=已激活, 2=已禁用, 4=未关注） + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `deptId` | `integer(int64)` | | 部门ID筛选 | | +| `keyword` | `string` | | 关键词搜索（姓名/手机/职位） | | +| `page` | `integer(int32)` | | 页码 | | +| `pageSize` | `integer(int32)` | | 每页条数 | | +| `status` | `integer(int32)` | | 状态筛选(1=已激活,2=已禁用,4=未关注) | | + +**响应** `统一响应结果«分页结果«WechatUser»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«WechatUser»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `WechatUser[]` | | 数据列表 | +|     `avatar` | `string` | | | +|     `createdAt` | `string` | | | +|     `deptIds` | `string` | | | +|     `deptNames` | `string` | | | +|     `email` | `string` | | | +|     `gender` | `int` | | | +|     `mobile` | `string` | | | +|     `name` | `string` | | | +|     `position` | `string` | | | +|     `status` | `int` | | | +|     `syncedAt` | `string` | | | +|     `updatedAt` | `string` | | | +|     `userid` | `string` | | | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +## 前端配置管理接口 + +### `GET` /admin/frontend-config + +**配置列表** + +分页查询前端配置列表，支持按关键词、分组和状态筛选。 + +**关联字典**： +- common_status（通用状态）：请求参数status和返回字段status（0=禁用, 1=启用） + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `configGroup` | `string` | | 配置分组 | | +| `keyword` | `string` | | 搜索关键词 | | +| `page` | `integer(int32)` | | 页码 | | +| `pageSize` | `integer(int32)` | | 每页条数 | | +| `status` | `integer(int32)` | | 状态 | | + +**响应** `统一响应结果«分页结果«前端配置 VO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«前端配置 VO»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `前端配置 VO[]` | | 数据列表 | +|     `configGroup` | `string` | | 配置分组: COLOR/PAGE/SECRET/GENERAL | +|     `configKey` | `string` | | 配置键 | +|     `configType` | `string` | | 值类型 | +|     `configValue` | `string` | | 配置值(SECRET类型脱敏) | +|     `createdAt` | `string` | | 创建时间 | +|     `description` | `string` | | 配置项描述 | +|     `id` | `string` | | 配置ID | +|     `label` | `string` | | 配置项中文名称 | +|     `sortOrder` | `int` | | 排序号 | +|     `status` | `int` | | 状态: 0=禁用 1=启用 | +|     `updatedAt` | `string` | | 更新时间 | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/frontend-config + +**创建配置** + +创建新的前端配置项，用于控制前端页面的展示和行为。 + +**权限**：需要管理员登录。 +**注意**：configKey 必须全局唯一，不能与已有配置重复。可通过 sensitive 字段标记是否为敏感配置（敏感配置不会通过公开接口暴露给小程序）。 + +**请求体** `前端配置请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `configGroup` | `string` | 是 | 配置分组 | +| `configKey` | `string` | 是 | 配置键 | +| `configType` | `string` | 是 | 值类型 | +| `configValue` | `string` | | 配置值 | +| `description` | `string` | | 配置项描述 | +| `label` | `string` | 是 | 配置项中文名称 | +| `sortOrder` | `int` | | 排序号 | +| `status` | `int` | | 状态: 0=禁用 1=启用 | + +**响应** `统一响应结果«前端配置 VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `前端配置 VO` | | 响应数据 | +|   `configGroup` | `string` | | 配置分组: COLOR/PAGE/SECRET/GENERAL | +|   `configKey` | `string` | | 配置键 | +|   `configType` | `string` | | 值类型 | +|   `configValue` | `string` | | 配置值(SECRET类型脱敏) | +|   `createdAt` | `string` | | 创建时间 | +|   `description` | `string` | | 配置项描述 | +|   `id` | `string` | | 配置ID | +|   `label` | `string` | | 配置项中文名称 | +|   `sortOrder` | `int` | | 排序号 | +|   `status` | `int` | | 状态: 0=禁用 1=启用 | +|   `updatedAt` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/frontend-config/all + +**配置列表（不分页）** + +获取所有前端配置项的完整列表（不分页），支持按分组和状态筛选。 +适用于需要一次性加载全部配置的场景。 + +**权限**：需要管理员登录。 + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `configGroup` | `string` | | 配置分组 | | +| `status` | `integer(int32)` | | 状态 | | + +**响应** `统一响应结果«List«前端配置 VO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `前端配置 VO[]` | | 响应数据 | +|   `configGroup` | `string` | | 配置分组: COLOR/PAGE/SECRET/GENERAL | +|   `configKey` | `string` | | 配置键 | +|   `configType` | `string` | | 值类型 | +|   `configValue` | `string` | | 配置值(SECRET类型脱敏) | +|   `createdAt` | `string` | | 创建时间 | +|   `description` | `string` | | 配置项描述 | +|   `id` | `string` | | 配置ID | +|   `label` | `string` | | 配置项中文名称 | +|   `sortOrder` | `int` | | 排序号 | +|   `status` | `int` | | 状态: 0=禁用 1=启用 | +|   `updatedAt` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/frontend-config/by-key/{key} + +**按key查询配置** + +根据配置键（configKey）获取指定的前端配置项。 +configKey为全局唯一标识，如 app_name、primary_color 等。 + +**权限**：需要管理员登录。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `key` | `string` | | 配置键 | + +**响应** `统一响应结果«前端配置 VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `前端配置 VO` | | 响应数据 | +|   `configGroup` | `string` | | 配置分组: COLOR/PAGE/SECRET/GENERAL | +|   `configKey` | `string` | | 配置键 | +|   `configType` | `string` | | 值类型 | +|   `configValue` | `string` | | 配置值(SECRET类型脱敏) | +|   `createdAt` | `string` | | 创建时间 | +|   `description` | `string` | | 配置项描述 | +|   `id` | `string` | | 配置ID | +|   `label` | `string` | | 配置项中文名称 | +|   `sortOrder` | `int` | | 排序号 | +|   `status` | `int` | | 状态: 0=禁用 1=启用 | +|   `updatedAt` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/frontend-config/groups + +**获取所有分组** + +获取前端配置中所有已使用的分组名称列表。 +用于配置管理页面的分组筛选下拉框。 + +**权限**：需要管理员登录。 + +**响应** `统一响应结果«List«string»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `string[]` | | 响应数据 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/frontend-config/{id} + +**配置详情** + +根据配置ID获取指定前端配置项的详细信息，包括key、value、分组、描述等。 + +**权限**：需要管理员登录。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `id` | `integer` | | 配置ID | + +**响应** `统一响应结果«前端配置 VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `前端配置 VO` | | 响应数据 | +|   `configGroup` | `string` | | 配置分组: COLOR/PAGE/SECRET/GENERAL | +|   `configKey` | `string` | | 配置键 | +|   `configType` | `string` | | 值类型 | +|   `configValue` | `string` | | 配置值(SECRET类型脱敏) | +|   `createdAt` | `string` | | 创建时间 | +|   `description` | `string` | | 配置项描述 | +|   `id` | `string` | | 配置ID | +|   `label` | `string` | | 配置项中文名称 | +|   `sortOrder` | `int` | | 排序号 | +|   `status` | `int` | | 状态: 0=禁用 1=启用 | +|   `updatedAt` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/frontend-config/{id} + +**更新配置** + +更新指定前端配置项的值、分组、描述、状态等信息。 + +**权限**：需要管理员登录。 +**注意**：修改后前端会实时使用新值（如有缓存需等待刷新）。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `id` | `integer` | | 配置ID | + +**请求体** `前端配置请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `configGroup` | `string` | 是 | 配置分组 | +| `configKey` | `string` | 是 | 配置键 | +| `configType` | `string` | 是 | 值类型 | +| `configValue` | `string` | | 配置值 | +| `description` | `string` | | 配置项描述 | +| `label` | `string` | 是 | 配置项中文名称 | +| `sortOrder` | `int` | | 排序号 | +| `status` | `int` | | 状态: 0=禁用 1=启用 | + +**响应** `统一响应结果«前端配置 VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `前端配置 VO` | | 响应数据 | +|   `configGroup` | `string` | | 配置分组: COLOR/PAGE/SECRET/GENERAL | +|   `configKey` | `string` | | 配置键 | +|   `configType` | `string` | | 值类型 | +|   `configValue` | `string` | | 配置值(SECRET类型脱敏) | +|   `createdAt` | `string` | | 创建时间 | +|   `description` | `string` | | 配置项描述 | +|   `id` | `string` | | 配置ID | +|   `label` | `string` | | 配置项中文名称 | +|   `sortOrder` | `int` | | 排序号 | +|   `status` | `int` | | 状态: 0=禁用 1=启用 | +|   `updatedAt` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/frontend-config/{id} + +**删除配置** + +删除指定的前端配置项（软删除）。 + +**权限**：需要管理员登录。 +**注意**：删除后前端将无法获取该配置，可能影响页面展示，请确认无引用后再删除。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `id` | `integer` | | 配置ID | + +**响应** `统一响应结果«Void»` + +--- + +## 字典管理接口 + +### `GET` /admin/dict/all + +**获取所有字典数据** + +获取系统全部字典类型及其字典数据，按字典类型分组返回。用于后台管理系统初始化时一次性加载所有下拉选项。返回结果包含dictType编码、dictName名称、dataList数据列表。需要管理员认证。 + +**字典层级说明**： +- 字典类型（SysDictType）：一级分类，如 admin_status、order_status、id_card_type 等 +- 字典数据（SysDictData）：二级选项，归属于某个字典类型，如 admin_status 下的 ACTIVE/LOCKED/DISABLED +- 前端通过 dictType 编码查找对应的 dataList，用 dictValue 匹配实际数据进行翻译展示 + + +**响应** `统一响应结果«List«字典VO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `字典VO[]` | | 响应数据 | +|   `dataList` | `字典数据项VO[]` | | 字典数据列表 | +|     `dictLabel` | `string` | | 字典标签 | +|     `dictValue` | `string` | | 字典值 | +|     `sort` | `int` | | 排序号 | +|   `dictName` | `string` | | 字典名称 | +|   `dictType` | `string` | | 字典类型标识 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/dict/data + +**创建字典数据** + +在指定字典类型下新增一条字典数据项。dictValue为前端匹配的值（如ACTIVE），dictLabel为前端展示的标签（如'启用'）。支持树形字典数据（通过parentId设置父级）。 + +**请求体** `创建字典数据请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `dictLabel` | `string` | 是 | 字典标签 | +| `dictType` | `string` | 是 | 字典类型 | +| `dictValue` | `string` | 是 | 字典值 | +| `remark` | `string` | | 备注 | +| `sortOrder` | `int` | | 排序号 | + +**响应** `统一响应结果«SysDictData»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `SysDictData` | | 响应数据 | +|   `createdAt` | `string` | | | +|   `dictDataId` | `long` | | | +|   `dictLabel` | `string` | | | +|   `dictType` | `string` | | | +|   `dictValue` | `string` | | | +|   `remark` | `string` | | | +|   `sortOrder` | `int` | | | +|   `status` | `string` | | | +|   `updatedAt` | `string` | | | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/dict/data/detail/{dictDataId} + +**根据ID获取字典数据详情** + +获取单个字典数据项的详细信息，包括dictValue、dictLabel、cssClass等。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `dictDataId` | `integer` | | 字典数据ID | + +**响应** `统一响应结果«SysDictData»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `SysDictData` | | 响应数据 | +|   `createdAt` | `string` | | | +|   `dictDataId` | `long` | | | +|   `dictLabel` | `string` | | | +|   `dictType` | `string` | | | +|   `dictValue` | `string` | | | +|   `remark` | `string` | | | +|   `sortOrder` | `int` | | | +|   `status` | `string` | | | +|   `updatedAt` | `string` | | | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/dict/data/tree/{dictTypeId} + +**按类型查询字典数据（树形结构）** + +根据字典类型ID查询其下所有字典数据，以树形结构返回（支持父子级字典数据）。用于多级联动下拉框场景（如省市区）。需要管理员认证。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `dictTypeId` | `integer` | | 字典类型ID | + +**响应** `统一响应结果«List«SysDictData»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `SysDictData[]` | | 响应数据 | +|   `createdAt` | `string` | | | +|   `dictDataId` | `long` | | | +|   `dictLabel` | `string` | | | +|   `dictType` | `string` | | | +|   `dictValue` | `string` | | | +|   `remark` | `string` | | | +|   `sortOrder` | `int` | | | +|   `status` | `string` | | | +|   `updatedAt` | `string` | | | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/dict/data/{dictType} + +**按类型查询字典数据** + +根据字典类型编码（如order_status）查询其下所有字典数据（平铺列表）。用于单层下拉框场景。需要管理员认证。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `dictType` | `string` | | 字典类型编码 | + +**响应** `统一响应结果«List«SysDictData»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `SysDictData[]` | | 响应数据 | +|   `createdAt` | `string` | | | +|   `dictDataId` | `long` | | | +|   `dictLabel` | `string` | | | +|   `dictType` | `string` | | | +|   `dictValue` | `string` | | | +|   `remark` | `string` | | | +|   `sortOrder` | `int` | | | +|   `status` | `string` | | | +|   `updatedAt` | `string` | | | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/dict/data/{id} + +**更新字典数据** + +更新字典数据项的标签、样式类型、排序号等。dictValue建议不修改以免影响已有业务数据。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `id` | `integer` | | 字典数据ID | + +**请求体** `更新字典数据请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `dictLabel` | `string` | | 字典标签 | +| `dictValue` | `string` | | 字典值 | +| `remark` | `string` | | 备注 | +| `sortOrder` | `int` | | 排序号 | +| `status` | `string` | | 状态：ACTIVE=启用 DISABLED=禁用 | + +**响应** `统一响应结果«SysDictData»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `SysDictData` | | 响应数据 | +|   `createdAt` | `string` | | | +|   `dictDataId` | `long` | | | +|   `dictLabel` | `string` | | | +|   `dictType` | `string` | | | +|   `dictValue` | `string` | | | +|   `remark` | `string` | | | +|   `sortOrder` | `int` | | | +|   `status` | `string` | | | +|   `updatedAt` | `string` | | | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/dict/data/{id} + +**删除字典数据** + +删除指定字典数据项（软删除）。删除后不影响已引用该字典值的业务数据。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `id` | `integer` | | 字典数据ID | + +**响应** `统一响应结果«Void»` + +--- + +### `GET` /admin/dict/type + +**分页查询字典类型** + +分页查询字典类型列表，支持按分类（category）筛选。字典类型是字典数据的上级分组，管理字典类型即管理有哪些可供前端使用的下拉选项组。 + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `category` | `string` | | 字典分类 | | +| `page` | `integer(int32)` | | 页码 | | +| `pageSize` | `integer(int32)` | | 每页条数 | | + +**响应** `统一响应结果«分页结果«SysDictType»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«SysDictType»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `SysDictType[]` | | 数据列表 | +|     `category` | `string` | | | +|     `createdAt` | `string` | | | +|     `dictName` | `string` | | | +|     `dictType` | `string` | | | +|     `dictTypeId` | `long` | | | +|     `remark` | `string` | | | +|     `status` | `string` | | | +|     `updatedAt` | `string` | | | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/dict/type + +**创建字典类型** + +新建一个字典类型（如：订单状态、证件类型等）。字典类型编码（dictType）全局唯一，创建后不可修改。需要管理员认证，建议仅SUPER_ADMIN/ADMIN角色操作。 + +**已有字典类型示例**： +- admin_status（管理员状态）、common_status（通用状态）、login_status（登录状态） +- order_status（订单状态）、product_status（产品状态）、rating_level（评价等级） +- id_card_type（证件类型）、gender（性别）、traveler_type（出行人类型） +- contact_channel_type（联系方式渠道类型）、favorite_resource_type（收藏资源类型）、footprint_resource_type（足迹资源类型） + + +**请求体** `创建字典类型请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `category` | `string` | | 字典分类 | +| `dictName` | `string` | 是 | 字典名称 | +| `dictType` | `string` | 是 | 字典类型标识 | +| `remark` | `string` | | 备注 | + +**响应** `统一响应结果«SysDictType»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `SysDictType` | | 响应数据 | +|   `category` | `string` | | | +|   `createdAt` | `string` | | | +|   `dictName` | `string` | | | +|   `dictType` | `string` | | | +|   `dictTypeId` | `long` | | | +|   `remark` | `string` | | | +|   `status` | `string` | | | +|   `updatedAt` | `string` | | | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/dict/type/{dictTypeId} + +**根据ID获取字典类型详情** + +获取单个字典类型的详细信息，包括编码、名称、分类、状态等。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `dictTypeId` | `integer` | | 字典类型ID | + +**响应** `统一响应结果«SysDictType»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `SysDictType` | | 响应数据 | +|   `category` | `string` | | | +|   `createdAt` | `string` | | | +|   `dictName` | `string` | | | +|   `dictType` | `string` | | | +|   `dictTypeId` | `long` | | | +|   `remark` | `string` | | | +|   `status` | `string` | | | +|   `updatedAt` | `string` | | | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/dict/type/{id} + +**更新字典类型** + +更新字典类型的名称、分类、备注等信息。字典类型编码（dictType）不可修改。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `id` | `integer` | | 字典类型ID | + +**请求体** `更新字典类型请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `dictName` | `string` | | 字典名称 | +| `remark` | `string` | | 备注 | +| `status` | `string` | | 状态：ACTIVE=启用 DISABLED=禁用 | + +**响应** `统一响应结果«SysDictType»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `SysDictType` | | 响应数据 | +|   `category` | `string` | | | +|   `createdAt` | `string` | | | +|   `dictName` | `string` | | | +|   `dictType` | `string` | | | +|   `dictTypeId` | `long` | | | +|   `remark` | `string` | | | +|   `status` | `string` | | | +|   `updatedAt` | `string` | | | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/dict/type/{id} + +**删除字典类型** + +删除字典类型及其下所有字典数据（软删除）。如果该字典类型已被业务引用，删除后不影响已有数据，但新的表单将无法选择该字典值。需要管理员认证。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `id` | `integer` | | 字典类型ID | + +**响应** `统一响应结果«Void»` + +--- + +## 定时任务接口 + +### `GET` /admin/job + +**分页查询定时任务** + +分页查询定时任务列表。 + +**关联字典**： +- job_group（任务分组）：DEFAULT=默认分组, SYSTEM=系统任务, WECHAT=企微同步, INSURANCE=保险同步 +- job_misfire_policy（执行策略）：DEFAULT=默认策略, FIRE_ONCE=立即触发一次, DO_NOTHING=不触发 +- job_status（任务状态）：ACTIVE=启用, PAUSED=已暂停 + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `page` | `integer(int32)` | | 页码 | | +| `pageSize` | `integer(int32)` | | 每页条数 | | + +**响应** `统一响应结果«分页结果«定时任务信息»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«定时任务信息»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `定时任务信息[]` | | 数据列表 | +|     `concurrent` | `boolean` | | 是否允许并发执行 | +|     `createdAt` | `string` | | 创建时间 | +|     `cronExpression` | `string` | | Cron表达式 | +|     `invokeTarget` | `string` | | 调用目标（Bean名称.方法名） | +|     `jobGroup` | `string` | | 任务分组 | +|     `jobId` | `long` | | 任务ID | +|     `jobName` | `string` | | 任务名称 | +|     `misfirePolicy` | `string` | | 计划执行策略 | +|     `remark` | `string` | | 备注 | +|     `status` | `string` | | 任务状态 | +|     `updatedAt` | `string` | | 更新时间 | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/job + +**创建定时任务** + +创建新的定时任务。invokeTarget格式为'Bean名称.方法名'（如wechatSyncService.syncAll），方法必须是无参公开方法。cronExpression为标准6位Cron表达式（秒 分 时 日 月 周）。创建后任务默认为暂停状态（PAUSED），需手动调用[恢复任务]接口启用。 + +**关联字典**： +- job_group（任务分组）：DEFAULT=默认分组, SYSTEM=系统任务, WECHAT=企微同步, INSURANCE=保险同步 +- job_misfire_policy（执行策略）：DEFAULT=默认策略, FIRE_ONCE=立即触发一次, DO_NOTHING=不触发 +- job_status（任务状态）：ACTIVE=启用, PAUSED=已暂停 + +需要SUPER_ADMIN角色。 + +**请求体** `创建定时任务请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `concurrent` | `boolean` | | 是否允许并发执行 | +| `cronExpression` | `string` | 是 | Cron表达式，标准6位（秒 分 时 日 月 周） | +| `invokeTarget` | `string` | 是 | 调用目标（Bean名称.方法名），方法必须是无参公开方法 | +| `jobGroup` | `string` | | 任务分组，字典类型：job_group（DEFAULT=默认分组, SYSTEM=系统任务, WECHAT=企微同步, INSURANCE=保险同步） | +| `jobName` | `string` | 是 | 任务名称 | +| `misfirePolicy` | `string` | | 计划执行策略，字典类型：job_misfire_policy（DEFAULT=默认策略, FIRE_ONCE=立即触发一次, DO_NOTHING=不触发） | +| `remark` | `string` | | 备注 | + +**响应** `统一响应结果«定时任务信息»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `定时任务信息` | | 响应数据 | +|   `concurrent` | `boolean` | | 是否允许并发执行 | +|   `createdAt` | `string` | | 创建时间 | +|   `cronExpression` | `string` | | Cron表达式 | +|   `invokeTarget` | `string` | | 调用目标（Bean名称.方法名） | +|   `jobGroup` | `string` | | 任务分组 | +|   `jobId` | `long` | | 任务ID | +|   `jobName` | `string` | | 任务名称 | +|   `misfirePolicy` | `string` | | 计划执行策略 | +|   `remark` | `string` | | 备注 | +|   `status` | `string` | | 任务状态 | +|   `updatedAt` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/job/{jobId} + +**更新定时任务** + +更新指定定时任务的名称、Cron表达式、调用目标等信息。 +修改Cron表达式后任务将按新的计划执行。 + +**关联字典**： +- job_group（任务分组）：DEFAULT=默认分组, SYSTEM=系统任务, WECHAT=企微同步, INSURANCE=保险同步 +- job_misfire_policy（执行策略）：DEFAULT=默认策略, FIRE_ONCE=立即触发一次, DO_NOTHING=不触发 + +**权限**：需要SUPER_ADMIN角色。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `jobId` | `integer` | | 定时任务ID | + +**请求体** `更新定时任务请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `concurrent` | `boolean` | | 是否允许并发执行 | +| `cronExpression` | `string` | | Cron表达式，标准6位（秒 分 时 日 月 周） | +| `invokeTarget` | `string` | | 调用目标（Bean名称.方法名），方法必须是无参公开方法 | +| `jobGroup` | `string` | | 任务分组，字典类型：job_group（DEFAULT=默认分组, SYSTEM=系统任务, WECHAT=企微同步, INSURANCE=保险同步） | +| `jobName` | `string` | | 任务名称 | +| `misfirePolicy` | `string` | | 计划执行策略，字典类型：job_misfire_policy（DEFAULT=默认策略, FIRE_ONCE=立即触发一次, DO_NOTHING=不触发） | +| `remark` | `string` | | 备注 | + +**响应** `统一响应结果«定时任务信息»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `定时任务信息` | | 响应数据 | +|   `concurrent` | `boolean` | | 是否允许并发执行 | +|   `createdAt` | `string` | | 创建时间 | +|   `cronExpression` | `string` | | Cron表达式 | +|   `invokeTarget` | `string` | | 调用目标（Bean名称.方法名） | +|   `jobGroup` | `string` | | 任务分组 | +|   `jobId` | `long` | | 任务ID | +|   `jobName` | `string` | | 任务名称 | +|   `misfirePolicy` | `string` | | 计划执行策略 | +|   `remark` | `string` | | 备注 | +|   `status` | `string` | | 任务状态 | +|   `updatedAt` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/job/{jobId} + +**删除定时任务** + +删除指定的定时任务（软删除），同时从调度器中移除该任务。 + +**权限**：需要SUPER_ADMIN角色。 +**注意**：删除后任务将不再执行，但历史执行日志仍可查看。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `jobId` | `integer` | | 定时任务ID | + +**响应** `统一响应结果«Void»` + +--- + +### `GET` /admin/job/{jobId}/logs + +**查询任务日志** + +分页查询指定定时任务的执行日志，按执行时间倒序排列。日志包含执行状态（成功/失败）、执行耗时、异常信息等。 + +**关联字典**：job_log_status（日志状态）：SUCCESS=成功, FAIL=失败 + +需要管理员认证。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `jobId` | `integer` | | 定时任务ID | + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `page` | `integer(int32)` | | 页码 | | +| `pageSize` | `integer(int32)` | | 每页条数 | | + +**响应** `统一响应结果«分页结果«定时任务执行日志»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«定时任务执行日志»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `定时任务执行日志[]` | | 数据列表 | +|     `createdAt` | `string` | | 创建时间 | +|     `endTime` | `string` | | 结束时间 | +|     `invokeTarget` | `string` | | 调用目标 | +|     `jobId` | `long` | | 任务ID | +|     `jobLogId` | `long` | | 日志ID | +|     `jobName` | `string` | | 任务名称 | +|     `message` | `string` | | 执行结果/异常信息 | +|     `startTime` | `string` | | 开始时间 | +|     `status` | `string` | | 执行状态 | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/job/{jobId}/pause + +**暂停任务** + +暂停指定的定时任务，任务状态变为PAUSED。暂停后任务不再按Cron计划执行，但可通过[恢复任务]接口重新启用。 + +**关联字典**：job_status（任务状态）：ACTIVE=启用, PAUSED=已暂停 + +需要SUPER_ADMIN角色。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `jobId` | `integer` | | 定时任务ID | + +**响应** `统一响应结果«Void»` + +--- + +### `POST` /admin/job/{jobId}/resume + +**恢复任务** + +恢复已暂停的定时任务，任务状态变为ACTIVE。恢复后任务按Cron计划继续执行。 + +**关联字典**：job_status（任务状态）：ACTIVE=启用, PAUSED=已暂停 + +需要SUPER_ADMIN角色。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `jobId` | `integer` | | 定时任务ID | + +**响应** `统一响应结果«Void»` + +--- + +### `POST` /admin/job/{jobId}/trigger + +**立即执行一次** + +立即触发一次定时任务的执行，不影响原有的Cron计划。无论任务当前状态是ACTIVE还是PAUSED，都可以手动触发。执行结果可在任务日志中查看。需要SUPER_ADMIN角色。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `jobId` | `integer` | | 定时任务ID | + +**响应** `统一响应结果«Void»` + +--- + +## 客户管理接口 + +### `GET` /admin/customer + +**客户列表** + +分页查询小程序注册的C端用户（客户）列表。支持按昵称/手机号/真实姓名关键词搜索，按状态筛选。status取值：ACTIVE=正常 BANNED=已封禁。需要管理员认证。 + +**关联字典**： +- user_status（用户状态）：请求参数status和返回字段status（ACTIVE=正常, BANNED=已封禁） +- gender（性别）：返回字段gender（0=女, 1=男） +- id_card_type（证件类型）：返回字段idCardType + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `keyword` | `string` | | 搜索关键词 | | +| `page` | `integer(int32)` | | 页码 | | +| `pageSize` | `integer(int32)` | | 每页条数 | | +| `status` | `string` | | 状态 | | + +**响应** `统一响应结果«分页结果«客户信息VO（管理端）»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«客户信息VO（管理端）»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `客户信息VO（管理端）[]` | | 数据列表 | +|     `avatar` | `string` | | 头像URL | +|     `createdAt` | `string` | | 创建时间 | +|     `nickname` | `string` | | 昵称 | +|     `phone` | `string` | | 手机号（不脱敏） | +|     `status` | `string` | | 状态，关联字典user_status：ACTIVE=正常, BANNED=已封禁 | +|     `updatedAt` | `string` | | 更新时间 | +|     `userId` | `long` | | 用户ID | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/customer/{userId} + +**客户详情** + +获取指定客户的详细信息。 + +**关联字典**： +- user_status（用户状态）：返回字段status +- gender（性别）：返回字段gender +- id_card_type（证件类型）：返回字段idCardType + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `userId` | `integer` | | 用户ID | + +**响应** `统一响应结果«客户信息VO（管理端）»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `客户信息VO（管理端）` | | 响应数据 | +|   `avatar` | `string` | | 头像URL | +|   `createdAt` | `string` | | 创建时间 | +|   `nickname` | `string` | | 昵称 | +|   `phone` | `string` | | 手机号（不脱敏） | +|   `status` | `string` | | 状态，关联字典user_status：ACTIVE=正常, BANNED=已封禁 | +|   `updatedAt` | `string` | | 更新时间 | +|   `userId` | `long` | | 用户ID | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/customer/{userId}/ban + +**封禁客户** + +封禁指定的C端用户，状态变为BANNED。封禁后该用户无法登录小程序，已有的Token将失效。封禁操作不会删除用户数据，可通过[解封客户]接口恢复。需要管理员认证。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `userId` | `integer` | | 用户ID | + +**响应** `统一响应结果«Void»` + +--- + +### `POST` /admin/customer/{userId}/unban + +**解封客户** + +解封已封禁的C端用户，状态恢复为ACTIVE。解封后用户可正常登录小程序。需要管理员认证。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `userId` | `integer` | | 用户ID | + +**响应** `统一响应结果«Void»` + +--- + +## 小程序接口 + +### `GET` /dict/all + +**获取所有字典数据（公开接口）** + +获取系统全部字典类型及其字典数据，供小程序C端使用。无需认证即可调用。返回格式与管理端 /admin/dict/all 一致。 + +**字典层级说明**： +- 每个元素包含 dictType（编码）、dictName（名称）、dataList（字典数据列表） +- 前端通过 dictType 匹配业务字段，用 dataList 中的 dictValue/dictLabel 做翻译展示 +- 常用字典：order_status、product_status、id_card_type、gender、traveler_type、favorite_resource_type、footprint_resource_type + + +**响应** `统一响应结果«List«字典VO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `字典VO[]` | | 响应数据 | +|   `dataList` | `字典数据项VO[]` | | 字典数据列表 | +|     `dictLabel` | `string` | | 字典标签 | +|     `dictValue` | `string` | | 字典值 | +|     `sort` | `int` | | 排序号 | +|   `dictName` | `string` | | 字典名称 | +|   `dictType` | `string` | | 字典类型标识 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /user/account + +**注销账号** + +永久注销当前用户账号（软删除）。注销后该账号的openid和手机号将被释放，可用于重新注册。注销操作不可撤销，请谨慎调用。需要小程序用户认证。 + +**响应** `统一响应结果«Void»` + +--- + +### `GET` /user/favorite + +**收藏列表** + +分页查询当前用户的所有收藏记录，按收藏时间倒序排列。返回收藏记录的基础信息（不包含资源详情），需前端根据targetType和targetId再查详情。需要小程序用户认证。 + +**关联字典**： +- favorite_resource_type（收藏资源类型）：返回字段targetType，前端据此判断跳转到哪种资源详情页 + + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `page` | `integer(int32)` | | 页码 | | +| `pageSize` | `integer(int32)` | | 每页条数 | | + +**响应** `统一响应结果«分页结果«Favorite»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«Favorite»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `Favorite[]` | | 数据列表 | +|     `createdAt` | `string` | | | +|     `deletedAt` | `string` | | | +|     `favoriteId` | `long` | | | +|     `targetId` | `long` | | | +|     `targetType` | `string` | | | +|     `updatedAt` | `string` | | | +|     `userId` | `long` | | | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /user/favorite + +**添加收藏** + +将指定资源添加到当前用户的收藏列表。同一用户对同一资源不可重复收藏，重复收藏会报错。targetType取值：SCENIC_SPOT/ACTIVITY/HOTEL/PRODUCT/EXPLORE等。需要小程序用户认证。 + +**关联字典**： +- favorite_resource_type（收藏资源类型）：SCENIC_SPOT=景区, ACTIVITY=活动, HOTEL=酒店, PRODUCT=产品, EXPLORE=探索（请求参数targetType） + + +**请求体** `收藏请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `targetId` | `long` | 是 | 收藏目标ID | +| `targetType` | `string` | 是 | 收藏类型，关联字典favorite_resource_type | + +**响应** `统一响应结果«Favorite»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `Favorite` | | 响应数据 | +|   `createdAt` | `string` | | | +|   `deletedAt` | `string` | | | +|   `favoriteId` | `long` | | | +|   `targetId` | `long` | | | +|   `targetType` | `string` | | | +|   `updatedAt` | `string` | | | +|   `userId` | `long` | | | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /user/favorite/check + +**检查是否已收藏** + +检查当前用户是否已收藏指定类型的资源。返回true=已收藏，false=未收藏。targetType取值：SCENIC_SPOT/ACTIVITY/HOTEL/PRODUCT/EXPLORE等。需要小程序用户认证。 + +**关联字典**： +- favorite_resource_type（收藏资源类型）：SCENIC_SPOT=景区, ACTIVITY=活动, HOTEL=酒店, PRODUCT=产品, EXPLORE=探索（请求参数targetType） + + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `targetId` | `integer(int64)` | | 目标资源ID | | +| `targetType` | `string` | | 目标类型 | | + +**响应** `统一响应结果«boolean»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `boolean` | | 响应数据 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /user/favorite/{favoriteId} + +**删除收藏** + +根据收藏记录ID取消收藏。只能删除自己的收藏记录，删除他人的收藏会报权限错误。需要小程序用户认证。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `favoriteId` | `integer` | | 收藏ID | + +**响应** `统一响应结果«Void»` + +--- + +### `GET` /user/footprint + +**足迹列表** + +分页查询当前用户的浏览足迹，按浏览时间倒序排列。需要小程序用户认证。 + +**关联字典**： +- footprint_resource_type（足迹资源类型）：返回字段resourceType，前端据此判断跳转到哪种资源详情页 + + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `page` | `integer(int32)` | | 页码 | | +| `pageSize` | `integer(int32)` | | 每页条数 | | + +**响应** `统一响应结果«分页结果«Footprint»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«Footprint»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `Footprint[]` | | 数据列表 | +|     `createdAt` | `string` | | | +|     `deletedAt` | `string` | | | +|     `footprintId` | `long` | | | +|     `resourceId` | `long` | | | +|     `resourceType` | `string` | | | +|     `updatedAt` | `string` | | | +|     `userId` | `long` | | | +|     `visitTime` | `string` | | | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /user/footprint + +**添加足迹** + +记录用户浏览资源的足迹。同一用户对同一资源多次浏览只保留最新一条记录（更新时间）。resourceType取值：SCENIC_SPOT/ACTIVITY/HOTEL/PRODUCT等。通常由前端在进入资源详情页时自动调用。需要小程序用户认证。 + +**关联字典**： +- footprint_resource_type（足迹资源类型）：SCENIC_SPOT=景区, ACTIVITY=活动, HOTEL=酒店, PRODUCT=产品（请求参数resourceType） + + +**请求体** `足迹请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `resourceId` | `long` | 是 | 资源ID | +| `resourceType` | `string` | 是 | 资源类型，关联字典footprint_resource_type | + +**响应** `统一响应结果«Footprint»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `Footprint` | | 响应数据 | +|   `createdAt` | `string` | | | +|   `deletedAt` | `string` | | | +|   `footprintId` | `long` | | | +|   `resourceId` | `long` | | | +|   `resourceType` | `string` | | | +|   `updatedAt` | `string` | | | +|   `userId` | `long` | | | +|   `visitTime` | `string` | | | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /user/footprint/{footprintId} + +**删除足迹** + +根据足迹记录ID删除单条浏览足迹。只能删除自己的足迹记录。需要小程序用户认证。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `footprintId` | `integer` | | 足迹ID | + +**响应** `统一响应结果«Void»` + +--- + +### `POST` /user/login + +**微信登录** + +小程序用户通过微信授权码（wx.login获取的code）登录。可选传入phoneCode用于获取手机号绑定，avatar和nickname用于设置头像昵称。首次登录自动注册，返回JWT Token。needProfile=true表示需补充实名信息。无需认证即可调用。 + +**请求体** `微信小程序登录请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `avatar` | `string` | | 用户头像URL | +| `code` | `string` | 是 | 微信登录授权码 | +| `nickname` | `string` | | 用户昵称 | +| `phoneCode` | `string` | | 手机号授权码（用于获取手机号） | + +**响应** `统一响应结果«用户登录响应»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `用户登录响应` | | 响应数据 | +|   `avatar` | `string` | | 头像URL | +|   `isNewUser` | `boolean` | | 是否新用户 | +|   `needProfile` | `boolean` | | 是否需要完善资料（realName为空时为true） | +|   `nickname` | `string` | | 昵称 | +|   `phone` | `string` | | 手机号 | +|   `token` | `string` | | 登录令牌 | +|   `userId` | `long` | | 用户ID | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /user/login/sms + +**手机号验证码登录** + +小程序用户通过手机号+短信验证码登录。首次登录自动注册账号，返回JWT Token。登录成功后若needProfile=true，表示需要补充个人信息（实名认证），前端应跳转到信息补充页。无需认证即可调用。 + +**请求体** `短信验证码登录请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `string` | 是 | 短信验证码（6位数字） | +| `phone` | `string` | 是 | 手机号 | + +**响应** `统一响应结果«用户登录响应»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `用户登录响应` | | 响应数据 | +|   `avatar` | `string` | | 头像URL | +|   `isNewUser` | `boolean` | | 是否新用户 | +|   `needProfile` | `boolean` | | 是否需要完善资料（realName为空时为true） | +|   `nickname` | `string` | | 昵称 | +|   `phone` | `string` | | 手机号 | +|   `token` | `string` | | 登录令牌 | +|   `userId` | `long` | | 用户ID | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /user/logout + +**用户登出** + +清除当前用户的登录状态并使Token失效。需要小程序用户认证。 + +**响应** `统一响应结果«Void»` + +--- + +### `GET` /user/profile + +**获取用户信息** + +获取当前登录用户的个人资料，包括昵称、头像、手机号（脱敏）、实名信息等。手机号返回脱敏格式（如138****0000），证件号同样脱敏处理。需要小程序用户认证（Token中的userId）。 + +**关联字典**： +- id_card_type（证件类型）：ID_CARD=身份证, PASSPORT=护照 +- gender（性别）：0=女, 1=男 + + +**响应** `统一响应结果«用户信息VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `用户信息VO` | | 响应数据 | +|   `avatar` | `string` | | 头像URL | +|   `birthday` | `string` | | 出生日期 | +|   `createdAt` | `string` | | 创建时间 | +|   `email` | `string` | | 邮箱 | +|   `gender` | `int` | | 性别，关联字典gender：0=女, 1=男 | +|   `idCardNo` | `string` | | 证件号码 | +|   `idCardType` | `string` | | 证件类型，关联字典id_card_type：ID_CARD=身份证, PASSPORT=护照 | +|   `nationality` | `string` | | 国籍 | +|   `needProfile` | `boolean` | | 是否需要完善资料（realName为空时为true） | +|   `nickname` | `string` | | 昵称 | +|   `phone` | `string` | | 手机号（脱敏） | +|   `realName` | `string` | | 真实姓名 | +|   `status` | `string` | | 状态，关联字典user_status：ACTIVE=正常, BANNED=已封禁 | +|   `updatedAt` | `string` | | 更新时间 | +|   `userId` | `long` | | 用户ID | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /user/profile + +**更新用户信息** + +更新当前用户的个人资料。首次登录补充信息时realName/idCardType/idCardNo为必填（使用ProfileCompletion验证组）。如果传入身份证号，后端自动解析性别和出生日期。更新手机号后会自动绑定匹配的待绑定订单。需要小程序用户认证。 + +**关联字典**： +- id_card_type（证件类型）：ID_CARD=身份证, PASSPORT=护照（请求参数idCardType） +- gender（性别）：0=女, 1=男 + + +**请求体** `更新用户资料请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `avatar` | `string` | | 头像URL | +| `birthday` | `string` | | 出生日期（从身份证号自动解析） | +| `email` | `string` | | 邮箱 | +| `gender` | `string` | | 性别：MALE=男 FEMALE=女（从身份证号自动解析） | +| `idCardNo` | `string` | | 证件号码（首次登录必填） | +| `idCardType` | `string` | | 证件类型：ID_CARD=身份证 PASSPORT=护照（首次登录必填） | +| `nationality` | `string` | | 国籍（默认中国） | +| `nickname` | `string` | | 昵称 | +| `phone` | `string` | | 手机号 | +| `realName` | `string` | | 真实姓名（首次登录必填） | + +**响应** `统一响应结果«用户信息VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `用户信息VO` | | 响应数据 | +|   `avatar` | `string` | | 头像URL | +|   `birthday` | `string` | | 出生日期 | +|   `createdAt` | `string` | | 创建时间 | +|   `email` | `string` | | 邮箱 | +|   `gender` | `int` | | 性别，关联字典gender：0=女, 1=男 | +|   `idCardNo` | `string` | | 证件号码 | +|   `idCardType` | `string` | | 证件类型，关联字典id_card_type：ID_CARD=身份证, PASSPORT=护照 | +|   `nationality` | `string` | | 国籍 | +|   `needProfile` | `boolean` | | 是否需要完善资料（realName为空时为true） | +|   `nickname` | `string` | | 昵称 | +|   `phone` | `string` | | 手机号（脱敏） | +|   `realName` | `string` | | 真实姓名 | +|   `status` | `string` | | 状态，关联字典user_status：ACTIVE=正常, BANNED=已封禁 | +|   `updatedAt` | `string` | | 更新时间 | +|   `userId` | `long` | | 用户ID | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /user/sms/send + +**发送短信验证码** + +向指定手机号发送6位数字短信验证码，用于小程序手机号登录。同一手机号60秒内不可重复发送，每日最多发送10次。验证码有效期5分钟。无需认证即可调用。 + +**请求体** `发送短信验证码请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `phone` | `string` | 是 | 手机号 | + +**响应** `统一响应结果«Void»` + +--- + +### `GET` /user/traveler + +**出行人列表** + +获取当前用户的所有出行人列表。如果用户已完成实名认证（realName不为空），列表首项会自动注入一个'本人'虚拟出行人（travelerId=0）。默认出行人排在前面，其余按创建时间排序。需要小程序用户认证。 + +**关联字典**： +- gender（性别）：返回字段gender +- id_card_type（证件类型）：返回字段idCardType +- traveler_type（出行人类型）：返回字段travelerType + +**响应** `统一响应结果«List«Traveler»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `Traveler[]` | | 响应数据 | +|   `birthday` | `string` | | | +|   `createdAt` | `string` | | | +|   `deletedAt` | `string` | | | +|   `email` | `string` | | | +|   `emergencyContact` | `string` | | | +|   `emergencyPhone` | `string` | | | +|   `gender` | `int` | | | +|   `idCardNo` | `string` | | | +|   `idCardType` | `string` | | | +|   `isDefault` | `int` | | | +|   `name` | `string` | | | +|   `nationality` | `string` | | | +|   `phone` | `string` | | | +|   `travelerId` | `long` | | | +|   `travelerType` | `string` | | | +|   `updatedAt` | `string` | | | +|   `userId` | `long` | | | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /user/traveler + +**新增出行人** + +为当前用户添加一位出行人信息，用于下单时选择。出行人类型（成人/儿童/婴儿）根据出生日期自动判断，无需手动传入。如果传入身份证号，后端自动校验格式并解析性别。每个用户最多可添加20位出行人。需要小程序用户认证。 + +**关联字典**： +- gender（性别）：请求/返回字段gender（0=女, 1=男） +- id_card_type（证件类型）：请求/返回字段idCardType（ID_CARD=身份证, PASSPORT=护照等） +- traveler_type（出行人类型）：返回字段travelerType（ADULT=成人, CHILD=儿童, INFANT=婴儿，自动计算） + +**请求体** `出行人请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `birthday` | `string` | 是 | 出生日期（必填，后端根据此字段自动判断人员类型） | +| `email` | `string` | | 邮箱 | +| `emergencyContact` | `string` | | 紧急联系人姓名 | +| `emergencyPhone` | `string` | | 紧急联系人电话 | +| `gender` | `int` | | 性别，关联字典gender：0=女, 1=男 | +| `idCardNo` | `string` | | 证件号码 | +| `idCardType` | `string` | | 证件类型，关联字典id_card_type：ID_CARD=身份证, PASSPORT=护照 | +| `isDefault` | `boolean` | | 是否设为默认出行人 | +| `name` | `string` | 是 | 出行人姓名 | +| `nationality` | `string` | | 国籍 | +| `phone` | `string` | | 手机号 | + +**响应** `统一响应结果«Traveler»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `Traveler` | | 响应数据 | +|   `birthday` | `string` | | | +|   `createdAt` | `string` | | | +|   `deletedAt` | `string` | | | +|   `email` | `string` | | | +|   `emergencyContact` | `string` | | | +|   `emergencyPhone` | `string` | | | +|   `gender` | `int` | | | +|   `idCardNo` | `string` | | | +|   `idCardType` | `string` | | | +|   `isDefault` | `int` | | | +|   `name` | `string` | | | +|   `nationality` | `string` | | | +|   `phone` | `string` | | | +|   `travelerId` | `long` | | | +|   `travelerType` | `string` | | | +|   `updatedAt` | `string` | | | +|   `userId` | `long` | | | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /user/traveler/{travelerId} + +**出行人详情** + +获取指定出行人的详细信息。 + +**关联字典**： +- gender（性别）：返回字段gender +- id_card_type（证件类型）：返回字段idCardType +- traveler_type（出行人类型）：返回字段travelerType + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `travelerId` | `integer` | | 出行人ID | + +**响应** `统一响应结果«Traveler»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `Traveler` | | 响应数据 | +|   `birthday` | `string` | | | +|   `createdAt` | `string` | | | +|   `deletedAt` | `string` | | | +|   `email` | `string` | | | +|   `emergencyContact` | `string` | | | +|   `emergencyPhone` | `string` | | | +|   `gender` | `int` | | | +|   `idCardNo` | `string` | | | +|   `idCardType` | `string` | | | +|   `isDefault` | `int` | | | +|   `name` | `string` | | | +|   `nationality` | `string` | | | +|   `phone` | `string` | | | +|   `travelerId` | `long` | | | +|   `travelerType` | `string` | | | +|   `updatedAt` | `string` | | | +|   `userId` | `long` | | | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /user/traveler/{travelerId} + +**更新出行人** + +更新指定出行人的信息。 + +**关联字典**： +- gender（性别）：请求/返回字段gender +- id_card_type（证件类型）：请求/返回字段idCardType +- traveler_type（出行人类型）：返回字段travelerType（自动计算） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `travelerId` | `integer` | | 出行人ID | + +**请求体** `出行人请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `birthday` | `string` | 是 | 出生日期（必填，后端根据此字段自动判断人员类型） | +| `email` | `string` | | 邮箱 | +| `emergencyContact` | `string` | | 紧急联系人姓名 | +| `emergencyPhone` | `string` | | 紧急联系人电话 | +| `gender` | `int` | | 性别，关联字典gender：0=女, 1=男 | +| `idCardNo` | `string` | | 证件号码 | +| `idCardType` | `string` | | 证件类型，关联字典id_card_type：ID_CARD=身份证, PASSPORT=护照 | +| `isDefault` | `boolean` | | 是否设为默认出行人 | +| `name` | `string` | 是 | 出行人姓名 | +| `nationality` | `string` | | 国籍 | +| `phone` | `string` | | 手机号 | + +**响应** `统一响应结果«Traveler»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `Traveler` | | 响应数据 | +|   `birthday` | `string` | | | +|   `createdAt` | `string` | | | +|   `deletedAt` | `string` | | | +|   `email` | `string` | | | +|   `emergencyContact` | `string` | | | +|   `emergencyPhone` | `string` | | | +|   `gender` | `int` | | | +|   `idCardNo` | `string` | | | +|   `idCardType` | `string` | | | +|   `isDefault` | `int` | | | +|   `name` | `string` | | | +|   `nationality` | `string` | | | +|   `phone` | `string` | | | +|   `travelerId` | `long` | | | +|   `travelerType` | `string` | | | +|   `updatedAt` | `string` | | | +|   `userId` | `long` | | | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /user/traveler/{travelerId} + +**删除出行人** + +删除指定的出行人记录（软删除）。 + +**权限**：需要小程序用户认证。 +**注意**：如果该出行人已关联到未完成的订单，删除不影响订单中的出行人快照数据。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `travelerId` | `integer` | | 出行人ID | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /user/traveler/{travelerId}/default + +**设为默认出行人** + +将指定出行人设为默认。每个用户只能有一个默认出行人，设置新的默认会自动取消原来的默认。默认出行人在下单时会被自动选中。需要小程序用户认证。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `travelerId` | `integer` | | 出行人ID | + +**响应** `统一响应结果«Void»` + +--- + +## 常见问题管理接口 + +### `GET` /admin/faq/categories + +**分类列表** + +获取所有FAQ分类的完整列表（不分页）。 +每个分类包含名称、排序号、状态等信息。 + +**权限**：需要管理员登录。 + +**响应** `统一响应结果«List«常见问题分类VO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `常见问题分类VO[]` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `id` | `long` | | 分类ID | +|   `items` | `常见问题条目VO[]` | | 条目列表（仅内部接口返回） | +|     `answer` | `string` | | 回答 | +|     `categoryId` | `long` | | 所属分类ID | +|     `createdAt` | `string` | | 创建时间 | +|     `id` | `long` | | 条目ID | +|     `question` | `string` | | 问题 | +|     `sortOrder` | `int` | | 排序号 | +|     `status` | `int` | | 状态：0=禁用 1=启用 | +|     `updatedAt` | `string` | | 更新时间 | +|   `name` | `string` | | 分类名称 | +|   `sortOrder` | `int` | | 排序号 | +|   `status` | `int` | | 状态：0=禁用 1=启用 | +|   `updatedAt` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/faq/categories + +**创建分类** + +创建新的FAQ分类，用于对常见问题进行归类。 + +**权限**：需要管理员登录。 +**注意**：分类名称不能重复。 + +**请求体** `常见问题分类请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `name` | `string` | 是 | 分类名称 | +| `sortOrder` | `int` | | 排序号 | +| `status` | `int` | | 状态：0=禁用 1=启用 | + +**响应** `统一响应结果«常见问题分类VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `常见问题分类VO` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `id` | `long` | | 分类ID | +|   `items` | `常见问题条目VO[]` | | 条目列表（仅内部接口返回） | +|     `answer` | `string` | | 回答 | +|     `categoryId` | `long` | | 所属分类ID | +|     `createdAt` | `string` | | 创建时间 | +|     `id` | `long` | | 条目ID | +|     `question` | `string` | | 问题 | +|     `sortOrder` | `int` | | 排序号 | +|     `status` | `int` | | 状态：0=禁用 1=启用 | +|     `updatedAt` | `string` | | 更新时间 | +|   `name` | `string` | | 分类名称 | +|   `sortOrder` | `int` | | 排序号 | +|   `status` | `int` | | 状态：0=禁用 1=启用 | +|   `updatedAt` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/faq/categories/{id} + +**更新分类** + +更新指定FAQ分类的名称、排序号、状态等信息。 + +**权限**：需要管理员登录。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `id` | `integer` | | 分类ID | + +**请求体** `常见问题分类请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `name` | `string` | 是 | 分类名称 | +| `sortOrder` | `int` | | 排序号 | +| `status` | `int` | | 状态：0=禁用 1=启用 | + +**响应** `统一响应结果«常见问题分类VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `常见问题分类VO` | | 响应数据 | +|   `createdAt` | `string` | | 创建时间 | +|   `id` | `long` | | 分类ID | +|   `items` | `常见问题条目VO[]` | | 条目列表（仅内部接口返回） | +|     `answer` | `string` | | 回答 | +|     `categoryId` | `long` | | 所属分类ID | +|     `createdAt` | `string` | | 创建时间 | +|     `id` | `long` | | 条目ID | +|     `question` | `string` | | 问题 | +|     `sortOrder` | `int` | | 排序号 | +|     `status` | `int` | | 状态：0=禁用 1=启用 | +|     `updatedAt` | `string` | | 更新时间 | +|   `name` | `string` | | 分类名称 | +|   `sortOrder` | `int` | | 排序号 | +|   `status` | `int` | | 状态：0=禁用 1=启用 | +|   `updatedAt` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/faq/categories/{id} + +**删除分类** + +删除指定的FAQ分类（软删除）。 + +**权限**：需要管理员登录。 +**注意**：删除分类不会删除其下的条目，但条目将变为无分类状态。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `id` | `integer` | | 分类ID | + +**响应** `统一响应结果«Void»` + +--- + +### `GET` /admin/faq/items + +**条目列表** + +查询FAQ条目列表，支持按分类ID筛选。 +返回问题标题、回答内容（富文本）、排序号等。 + +**权限**：需要管理员登录。 + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `categoryId` | `integer(int64)` | | 分类ID（可选） | | + +**响应** `统一响应结果«List«常见问题条目VO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `常见问题条目VO[]` | | 响应数据 | +|   `answer` | `string` | | 回答 | +|   `categoryId` | `long` | | 所属分类ID | +|   `createdAt` | `string` | | 创建时间 | +|   `id` | `long` | | 条目ID | +|   `question` | `string` | | 问题 | +|   `sortOrder` | `int` | | 排序号 | +|   `status` | `int` | | 状态：0=禁用 1=启用 | +|   `updatedAt` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/faq/items + +**创建条目** + +创建一条常见问题，包含问题标题和回答（支持富文本）。 + +**权限**：需要管理员登录。 +**注意**：需指定所属分类ID，排序号越小越靠前。 + +**请求体** `常见问题条目请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `answer` | `string` | | 回答（支持富文本） | +| `categoryId` | `long` | 是 | 所属分类ID | +| `question` | `string` | 是 | 问题 | +| `sortOrder` | `int` | | 排序号 | +| `status` | `int` | | 状态：0=禁用 1=启用 | + +**响应** `统一响应结果«常见问题条目VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `常见问题条目VO` | | 响应数据 | +|   `answer` | `string` | | 回答 | +|   `categoryId` | `long` | | 所属分类ID | +|   `createdAt` | `string` | | 创建时间 | +|   `id` | `long` | | 条目ID | +|   `question` | `string` | | 问题 | +|   `sortOrder` | `int` | | 排序号 | +|   `status` | `int` | | 状态：0=禁用 1=启用 | +|   `updatedAt` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/faq/items/{id} + +**更新条目** + +更新指定FAQ条目的问题标题、回答内容、排序号等信息。 + +**权限**：需要管理员登录。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `id` | `integer` | | 条目ID | + +**请求体** `常见问题条目请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `answer` | `string` | | 回答（支持富文本） | +| `categoryId` | `long` | 是 | 所属分类ID | +| `question` | `string` | 是 | 问题 | +| `sortOrder` | `int` | | 排序号 | +| `status` | `int` | | 状态：0=禁用 1=启用 | + +**响应** `统一响应结果«常见问题条目VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `常见问题条目VO` | | 响应数据 | +|   `answer` | `string` | | 回答 | +|   `categoryId` | `long` | | 所属分类ID | +|   `createdAt` | `string` | | 创建时间 | +|   `id` | `long` | | 条目ID | +|   `question` | `string` | | 问题 | +|   `sortOrder` | `int` | | 排序号 | +|   `status` | `int` | | 状态：0=禁用 1=启用 | +|   `updatedAt` | `string` | | 更新时间 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/faq/items/{id} + +**删除条目** + +删除指定的FAQ条目（软删除）。 + +**权限**：需要管理员登录。 +**注意**：删除后小程序FAQ页面将不再展示该条目。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `id` | `integer` | | 条目ID | + +**响应** `统一响应结果«Void»` + +--- + +## 探索分类管理接口 + +### `GET` /admin/explore/category + +**探索分类列表** + +分页查询探索分类列表，支持按关键词和状态筛选。 + +**关联字典**： +- common_status（通用状态）：请求参数status和返回字段status（0=禁用, 1=启用） + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `keyword` | `string` | | 搜索关键词 | | +| `page` | `integer(int32)` | | 页码 | | +| `pageSize` | `integer(int32)` | | 每页条数 | | +| `status` | `integer(int32)` | | 状态 | | + +**响应** `统一响应结果«分页结果«探索分类 VO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«探索分类 VO»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `探索分类 VO[]` | | 数据列表 | +|     `coverUrl` | `string` | | 封面图URL | +|     `createdAt` | `string` | | 创建时间 | +|     `favoriteCount` | `int` | | 收藏数 | +|     `iconUrl` | `string` | | 图标URL | +|     `id` | `string` | | 分类ID | +|     `likeCount` | `int` | | 点赞数 | +|     `resourceCount` | `int` | | 关联资源数量 | +|     `sortOrder` | `int` | | 排序号 | +|     `status` | `int` | | 状态：0=下线 1=上线 | +|     `subtitle` | `string` | | 副标题 | +|     `title` | `string` | | 分类标题 | +|     `viewCount` | `int` | | 浏览量 | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/explore/category + +**创建探索分类** + +创建新的探索分类，用于小程序探索页面的分类展示。 +可关联多个景区资源，设置封面图和描述文字。 + +**权限**：需要管理员登录。 + +**请求体** `探索分类请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `coverUrl` | `string` | 是 | 封面图URL | +| `description` | `string` | | 分类描述 | +| `iconUrl` | `string` | | 图标URL | +| `resources` | `探索分类资源请求[]` | | 关联资源列表 | +|   `coverUrl` | `string` | | 封面图URL | +|   `description` | `string` | | 资源简介(支持HTML) | +|   `resourceId` | `long` | | 资源ID | +|   `resourceName` | `string` | | 资源名称 | +|   `resourceType` | `string` | | 资源类型 | +| `sortOrder` | `int` | | 排序号（越小越靠前） | +| `status` | `int` | | 状态：0=下线 1=上线 | +| `subtitle` | `string` | | 副标题 | +| `title` | `string` | 是 | 分类标题 | + +**响应** `统一响应结果«Void»` + +--- + +### `GET` /admin/explore/category/{id} + +**探索分类详情** + +获取指定探索分类的详细信息，包括标题、封面图、描述、关联的景区资源列表等。 + +**权限**：需要管理员登录。 + +**关联字典**： +- common_status（通用状态）：返回字段status（0=禁用, 1=启用） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `id` | `integer` | | 分类ID | + +**响应** `统一响应结果«探索分类详情 VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `探索分类详情 VO` | | 响应数据 | +|   `coverUrl` | `string` | | 封面图URL | +|   `createdAt` | `string` | | 创建时间 | +|   `description` | `string` | | 分类描述 | +|   `favoriteCount` | `int` | | 收藏数 | +|   `iconUrl` | `string` | | 图标URL | +|   `id` | `string` | | 分类ID | +|   `isFavorited` | `boolean` | | 当前用户是否已收藏 | +|   `isLiked` | `boolean` | | 当前用户是否已点赞 | +|   `likeCount` | `int` | | 点赞数 | +|   `resources` | `探索分类关联资源项[]` | | 关联资源列表 | +|     `coverUrl` | `string` | | 封面图URL | +|     `description` | `string` | | 资源简介(支持HTML) | +|     `resourceId` | `string` | | 资源ID | +|     `resourceName` | `string` | | 资源名称 | +|     `resourceType` | `string` | | 资源类型 | +|     `sortOrder` | `int` | | 排序号 | +|   `subtitle` | `string` | | 副标题 | +|   `title` | `string` | | 分类标题 | +|   `viewCount` | `int` | | 浏览量 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/explore/category/{id} + +**更新探索分类** + +更新指定探索分类的标题、封面图、描述、关联资源、状态等信息。 + +**权限**：需要管理员登录。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `id` | `integer` | | 分类ID | + +**请求体** `探索分类请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `coverUrl` | `string` | 是 | 封面图URL | +| `description` | `string` | | 分类描述 | +| `iconUrl` | `string` | | 图标URL | +| `resources` | `探索分类资源请求[]` | | 关联资源列表 | +|   `coverUrl` | `string` | | 封面图URL | +|   `description` | `string` | | 资源简介(支持HTML) | +|   `resourceId` | `long` | | 资源ID | +|   `resourceName` | `string` | | 资源名称 | +|   `resourceType` | `string` | | 资源类型 | +| `sortOrder` | `int` | | 排序号（越小越靠前） | +| `status` | `int` | | 状态：0=下线 1=上线 | +| `subtitle` | `string` | | 副标题 | +| `title` | `string` | 是 | 分类标题 | + +**响应** `统一响应结果«Void»` + +--- + +### `DELETE` /admin/explore/category/{id} + +**删除探索分类** + +删除指定的探索分类（软删除），同时清除关联的资源绑定关系。 + +**权限**：需要管理员登录。 +**注意**：删除后小程序探索页面将不再展示该分类。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `id` | `integer` | | 分类ID | + +**响应** `统一响应结果«Void»` + +--- + +## 用户协议管理接口 + +### `GET` /admin/agreement + +**协议列表** + +分页查询用户协议列表，支持按关键词和状态筛选。 + +**关联字典**： +- common_status（通用状态）：请求参数status和返回字段status（0=禁用, 1=启用） + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `keyword` | `string` | | 搜索关键词 | | +| `page` | `integer(int32)` | | 页码 | | +| `pageSize` | `integer(int32)` | | 每页条数 | | +| `status` | `integer(int32)` | | 状态 | | + +**响应** `统一响应结果«分页结果«协议 VO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«协议 VO»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `协议 VO[]` | | 数据列表 | +|     `content` | `string` | | 协议内容（HTML富文本） | +|     `createTime` | `string` | | 创建时间 | +|     `id` | `string` | | 协议ID | +|     `sortOrder` | `int` | | 排序号 | +|     `status` | `int` | | 状态：0=下线 1=上线 | +|     `title` | `string` | | 协议标题 | +|     `type` | `string` | | 协议类型标识 | +|     `updateTime` | `string` | | 更新时间 | +|     `version` | `string` | | 版本号 | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/agreement + +**新增协议** + +创建新的用户协议，如用户服务协议、隐私政策等。 + +**权限**：需要管理员登录。 +**注意**：协议类型（type）需唯一，同一类型不能重复创建。内容支持富文本。 + +**请求体** `协议请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `content` | `string` | 是 | 协议内容（HTML富文本） | +| `sortOrder` | `int` | | 排序号（越小越靠前） | +| `status` | `int` | | 状态：0=下线 1=上线 | +| `title` | `string` | 是 | 协议标题 | +| `type` | `string` | 是 | 协议类型标识（唯一） | +| `version` | `string` | | 版本号 | + +**响应** `统一响应结果«协议 VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `协议 VO` | | 响应数据 | +|   `content` | `string` | | 协议内容（HTML富文本） | +|   `createTime` | `string` | | 创建时间 | +|   `id` | `string` | | 协议ID | +|   `sortOrder` | `int` | | 排序号 | +|   `status` | `int` | | 状态：0=下线 1=上线 | +|   `title` | `string` | | 协议标题 | +|   `type` | `string` | | 协议类型标识 | +|   `updateTime` | `string` | | 更新时间 | +|   `version` | `string` | | 版本号 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/agreement/{id} + +**协议详情** + +获取指定用户协议的详细信息，包括标题、内容（富文本）、版本号等。 + +**权限**：需要管理员登录。 + +**关联字典**： +- common_status（通用状态）：返回字段status（0=禁用, 1=启用） + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `id` | `integer` | | 协议ID | + +**响应** `统一响应结果«协议 VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `协议 VO` | | 响应数据 | +|   `content` | `string` | | 协议内容（HTML富文本） | +|   `createTime` | `string` | | 创建时间 | +|   `id` | `string` | | 协议ID | +|   `sortOrder` | `int` | | 排序号 | +|   `status` | `int` | | 状态：0=下线 1=上线 | +|   `title` | `string` | | 协议标题 | +|   `type` | `string` | | 协议类型标识 | +|   `updateTime` | `string` | | 更新时间 | +|   `version` | `string` | | 版本号 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/agreement/{id} + +**编辑协议** + +更新指定用户协议的标题、内容、状态等信息。 + +**权限**：需要管理员登录。 +**注意**：修改后小程序端会实时展示新内容。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `id` | `integer` | | 协议ID | + +**请求体** `协议请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `content` | `string` | 是 | 协议内容（HTML富文本） | +| `sortOrder` | `int` | | 排序号（越小越靠前） | +| `status` | `int` | | 状态：0=下线 1=上线 | +| `title` | `string` | 是 | 协议标题 | +| `type` | `string` | 是 | 协议类型标识（唯一） | +| `version` | `string` | | 版本号 | + +**响应** `统一响应结果«协议 VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `协议 VO` | | 响应数据 | +|   `content` | `string` | | 协议内容（HTML富文本） | +|   `createTime` | `string` | | 创建时间 | +|   `id` | `string` | | 协议ID | +|   `sortOrder` | `int` | | 排序号 | +|   `status` | `int` | | 状态：0=下线 1=上线 | +|   `title` | `string` | | 协议标题 | +|   `type` | `string` | | 协议类型标识 | +|   `updateTime` | `string` | | 更新时间 | +|   `version` | `string` | | 版本号 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/agreement/{id} + +**删除协议** + +删除指定的用户协议记录（软删除）。 + +**权限**：需要管理员登录。 +**注意**：删除后小程序端将无法查看该协议。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `id` | `integer` | | 协议ID | + +**响应** `统一响应结果«Void»` + +--- + +## 管理员管理接口 + +### `GET` /admin/user + +**管理员列表** + +分页查询管理员列表，支持按角色、状态、企微绑定状态筛选。status取值：ACTIVE=正常 LOCKED=已锁定 DISABLED=已禁用。wechatBound：true=已绑定企业微信 false=未绑定。需要管理员认证。 + +**关联字典**： +- admin_status（管理员状态）：ACTIVE=启用, LOCKED=锁定, DISABLED=禁用（筛选条件+列表展示） + + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `page` | `integer(int32)` | | 页码 | | +| `pageSize` | `integer(int32)` | | 每页条数 | | +| `roleId` | `integer(int64)` | | 角色ID | | +| `status` | `string` | | 状态 | | +| `wechatBound` | `boolean` | | 是否绑定企业微信: true=已绑定, false=未绑定 | | + +**响应** `统一响应结果«分页结果«AdminUser»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«AdminUser»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `AdminUser[]` | | 数据列表 | +|     `adminId` | `long` | | | +|     `avatar` | `string` | | | +|     `contactQrUrl` | `string` | | | +|     `createdAt` | `string` | | | +|     `currentRoleId` | `long` | | | +|     `effectiveAvatar` | `string` | | | +|     `enterpriseWechatDeptNames` | `string` | | | +|     `enterpriseWechatId` | `string` | | | +|     `enterpriseWechatName` | `string` | | | +|     `failedLoginCount` | `int` | | | +|     `lockedUntil` | `string` | | | +|     `passwordChangedAt` | `string` | | | +|     `roleKey` | `string` | | | +|     `roleName` | `string` | | | +|     `roles` | `SysRole[]` | | | +|     `status` | `string` | | | +|     `updatedAt` | `string` | | | +|     `username` | `string` | | | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/user + +**创建管理员** + +创建新的后台管理员账号。默认密码为Admin@123456，管理员首次登录后建议修改密码。可通过roleIds分配多个角色，也兼容旧的单角色roleId参数。需要SUPER_ADMIN或ADMIN角色。 + +**关联字典**： +- admin_status（管理员状态）：ACTIVE=启用, LOCKED=锁定, DISABLED=禁用 + + +**请求体** `创建管理员请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `roleId` | `long` | | 角色ID（已废弃，请使用roleIds） | +| `roleIds` | `long[]` | | 角色ID列表（多角色） | +| `username` | `string` | 是 | 用户名 | + +**响应** `统一响应结果«AdminUser»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `AdminUser` | | 响应数据 | +|   `adminId` | `long` | | | +|   `avatar` | `string` | | | +|   `contactQrUrl` | `string` | | | +|   `createdAt` | `string` | | | +|   `currentRoleId` | `long` | | | +|   `effectiveAvatar` | `string` | | | +|   `enterpriseWechatDeptNames` | `string` | | | +|   `enterpriseWechatId` | `string` | | | +|   `enterpriseWechatName` | `string` | | | +|   `failedLoginCount` | `int` | | | +|   `lockedUntil` | `string` | | | +|   `passwordChangedAt` | `string` | | | +|   `roleKey` | `string` | | | +|   `roleName` | `string` | | | +|   `roles` | `SysRole[]` | | | +|     `createdAt` | `string` | | | +|     `remark` | `string` | | | +|     `roleId` | `long` | | | +|     `roleKey` | `string` | | | +|     `roleName` | `string` | | | +|     `sortOrder` | `int` | | | +|     `status` | `string` | | | +|     `updatedAt` | `string` | | | +|   `status` | `string` | | | +|   `updatedAt` | `string` | | | +|   `username` | `string` | | | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/user/{adminId} + +**获取管理员详情** + +获取指定管理员的完整信息。 + +**关联字典**： +- admin_status（管理员状态）：ACTIVE=启用, LOCKED=锁定, DISABLED=禁用 + + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `adminId` | `integer` | | 管理员ID | + +**响应** `统一响应结果«AdminUser»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `AdminUser` | | 响应数据 | +|   `adminId` | `long` | | | +|   `avatar` | `string` | | | +|   `contactQrUrl` | `string` | | | +|   `createdAt` | `string` | | | +|   `currentRoleId` | `long` | | | +|   `effectiveAvatar` | `string` | | | +|   `enterpriseWechatDeptNames` | `string` | | | +|   `enterpriseWechatId` | `string` | | | +|   `enterpriseWechatName` | `string` | | | +|   `failedLoginCount` | `int` | | | +|   `lockedUntil` | `string` | | | +|   `passwordChangedAt` | `string` | | | +|   `roleKey` | `string` | | | +|   `roleName` | `string` | | | +|   `roles` | `SysRole[]` | | | +|     `createdAt` | `string` | | | +|     `remark` | `string` | | | +|     `roleId` | `long` | | | +|     `roleKey` | `string` | | | +|     `roleName` | `string` | | | +|     `sortOrder` | `int` | | | +|     `status` | `string` | | | +|     `updatedAt` | `string` | | | +|   `status` | `string` | | | +|   `updatedAt` | `string` | | | +|   `username` | `string` | | | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/user/{adminId} + +**更新管理员** + +更新管理员信息，包括用户名、状态、角色分配等。 + +**关联字典**： +- admin_status（管理员状态）：ACTIVE=启用, LOCKED=锁定, DISABLED=禁用 + + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `adminId` | `integer` | | 管理员ID | + +**请求体** `更新管理员请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `enterpriseWechatId` | `string` | | 企业微信用户ID | +| `roleId` | `long` | | 角色ID（已废弃，请使用roleIds） | +| `roleIds` | `long[]` | | 角色ID列表（多角色） | + +**响应** `统一响应结果«AdminUser»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `AdminUser` | | 响应数据 | +|   `adminId` | `long` | | | +|   `avatar` | `string` | | | +|   `contactQrUrl` | `string` | | | +|   `createdAt` | `string` | | | +|   `currentRoleId` | `long` | | | +|   `effectiveAvatar` | `string` | | | +|   `enterpriseWechatDeptNames` | `string` | | | +|   `enterpriseWechatId` | `string` | | | +|   `enterpriseWechatName` | `string` | | | +|   `failedLoginCount` | `int` | | | +|   `lockedUntil` | `string` | | | +|   `passwordChangedAt` | `string` | | | +|   `roleKey` | `string` | | | +|   `roleName` | `string` | | | +|   `roles` | `SysRole[]` | | | +|     `createdAt` | `string` | | | +|     `remark` | `string` | | | +|     `roleId` | `long` | | | +|     `roleKey` | `string` | | | +|     `roleName` | `string` | | | +|     `sortOrder` | `int` | | | +|     `status` | `string` | | | +|     `updatedAt` | `string` | | | +|   `status` | `string` | | | +|   `updatedAt` | `string` | | | +|   `username` | `string` | | | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/user/{adminId} + +**删除管理员** + +删除指定管理员账号（软删除）。不能删除自己的账号，不能删除SUPER_ADMIN角色的账号（除非操作者也是SUPER_ADMIN）。删除后该管理员的登录状态自动失效。需要SUPER_ADMIN或ADMIN角色。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `adminId` | `integer` | | 管理员ID | + +**响应** `统一响应结果«Void»` + +--- + +### `POST` /admin/user/{adminId}/reset-password + +**重置密码** + +将指定管理员的密码重置为默认密码（Admin@123456）。用于管理员忘记密码时由上级管理员操作重置。重置后管理员可用默认密码登录，建议立即修改。需要SUPER_ADMIN或ADMIN角色。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `adminId` | `integer` | | 管理员ID | + +**响应** `统一响应结果«Void»` + +--- + +### `POST` /admin/user/{adminId}/unlock + +**解锁管理员** + +解锁因登录失败次数过多而被锁定的管理员账号。管理员连续5次登录失败后账号自动锁定30分钟，此接口可立即解锁。需要SUPER_ADMIN或ADMIN角色。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `adminId` | `integer` | | 管理员ID | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/user/{adminId}/wechat-binding + +**修改企业微信绑定（支持换绑）** + +为管理员绑定或更换企业微信账号。绑定后管理员可通过企业微信扫码登录，并可接收审批通知。如果目标企微ID已被其他管理员绑定，需设置forceRebind=true强制换绑。需要管理员认证。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `adminId` | `integer` | | 管理员ID | + +**请求体** `企业微信绑定请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `enterpriseWechatId` | `string` | | 企业微信ID（为空则解绑） | +| `forceRebind` | `boolean` | | 是否强制换绑（当ID已被其他管理员占用时） | + +**响应** `统一响应结果«Map«string,object»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `object` | | 响应数据 | +| `message` | `string` | | 响应消息 | + +--- + +## 管理员认证接口 + +### `GET` /admin/auth/2fa/callback + +**2FA企微扫码回调** + +企业微信OAuth回调地址，用户扫码授权后微信服务器回调此接口。此接口由微信服务器调用，非前端直接调用。回调成功后将state对应的会话标记为已扫码，前端轮询 /2fa/check 即可获取结果。返回HTML页面（成功/失败提示），不返回JSON。 + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `code` | `string` | | 授权码 | | +| `state` | `string` | | 会话状态 | | + +**响应** `string` + +--- + +### `GET` /admin/auth/2fa/check + +**查询2FA扫码状态** + +前端轮询此接口检查2FA扫码验证是否完成。返回status字段：PENDING=等待扫码，SCANNED=已完成验证（附带token和用户信息）。建议轮询间隔2秒，超过5分钟未扫码会话自动失效。无需认证即可调用（登录流程中使用）。 + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `state` | `string` | | 会话状态 | | + +**响应** `统一响应结果«Map«string,object»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `object` | | 响应数据 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/auth/2fa/confirm + +**手动确认扫码（内网穿透环境workaround，默认关闭）** + +在内网穿透环境下，企微回调可能无法正常到达，此接口作为手动替代方案。 +需在Nacos配置中开启 auth.2fa-confirm-enabled=true 才可使用。 + +**权限**：无需认证（登录流程中使用）。 +**注意**：生产环境应保持关闭，仅限开发/测试时使用。 + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `adminId` | `string` | | 管理员ID | | +| `state` | `string` | | 会话状态 | | + +**响应** `统一响应结果«Void»` + +--- + +### `GET` /admin/auth/2fa/qrcode + +**生成2FA扫码会话** + +生成企业微信扫码二维码的会话信息，用于新设备二次验证。返回包含qrcodeUrl（二维码链接）和state（会话标识）。前端展示二维码后通过轮询 /2fa/check 接口检查扫码状态。无需认证即可调用（登录流程中使用）。 + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `adminId` | `integer(int64)` | | 管理员ID | | + +**响应** `统一响应结果«Map«string,object»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `object` | | 响应数据 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/auth/avatar + +**更新头像** + +管理员更新自己的头像。需先通过文件服务上传图片获取OSS URL和fileId，再调用此接口绑定。旧头像的文件引用会自动解绑。需要管理员认证。 + +**请求体** `头像更新请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `avatar` | `string` | 是 | 头像URL | +| `fileId` | `long` | | 文件ID | + +**响应** `统一响应结果«Void»` + +--- + +### `GET` /admin/auth/info + +**获取当前管理员信息** + +获取当前登录管理员的完整信息，包括用户名、头像、角色列表、当前角色、菜单权限等。前端页面初始化时调用此接口获取用户信息和权限数据。需要管理员认证。 + +**响应** `统一响应结果«管理员登录响应»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `管理员登录响应` | | 响应数据 | +|   `adminId` | `long` | | 管理员ID | +|   `avatar` | `string` | | 头像URL | +|   `requireTwoFa` | `boolean` | | 是否需要二次验证 | +|   `requireWechatBind` | `boolean` | | 是否需要绑定企业微信 | +|   `role` | `string` | | 角色标识（主角色） | +|   `roleName` | `string` | | 角色名称（主角色） | +|   `roles` | `角色信息[]` | | 角色列表（多角色） | +|     `roleId` | `long` | | 角色ID | +|     `roleKey` | `string` | | 角色标识 | +|     `roleName` | `string` | | 角色名称 | +|   `token` | `string` | | 登录令牌 | +|   `username` | `string` | | 用户名 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/auth/login + +**管理员登录** + +管理员通过用户名+密码登录后台管理系统。首次在新设备登录时需要进行企业微信扫码二次验证（2FA），返回needTwoFa=true。登录失败5次后账号将被锁定30分钟。无需认证即可调用。 + +**请求体** `管理员登录请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `password` | `string` | 是 | 密码 | +| `username` | `string` | 是 | 用户名 | + +**响应** `统一响应结果«管理员登录响应»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `管理员登录响应` | | 响应数据 | +|   `adminId` | `long` | | 管理员ID | +|   `avatar` | `string` | | 头像URL | +|   `requireTwoFa` | `boolean` | | 是否需要二次验证 | +|   `requireWechatBind` | `boolean` | | 是否需要绑定企业微信 | +|   `role` | `string` | | 角色标识（主角色） | +|   `roleName` | `string` | | 角色名称（主角色） | +|   `roles` | `角色信息[]` | | 角色列表（多角色） | +|     `roleId` | `long` | | 角色ID | +|     `roleKey` | `string` | | 角色标识 | +|     `roleName` | `string` | | 角色名称 | +|   `token` | `string` | | 登录令牌 | +|   `username` | `string` | | 用户名 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/auth/logout + +**管理员登出** + +清除管理员的登录状态并使当前Token失效。前端应在登出后清除本地存储的Token和用户信息。需要管理员认证。 + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/auth/password + +**修改密码** + +管理员修改自己的登录密码。需验证旧密码正确后才能设置新密码，新密码须满足复杂度要求（8-128位，含大小写字母和数字）。修改成功后当前Token仍然有效，无需重新登录。需要管理员认证（Token中的adminId）。 + +**请求体** `修改密码请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `newPassword` | `string` | 是 | 新密码（8-128位，须含大小写字母和数字） | +| `oldPassword` | `string` | 是 | 旧密码 | + +**响应** `统一响应结果«Void»` + +--- + +### `POST` /admin/auth/switch-role + +**切换当前角色** + +多角色管理员切换当前活跃角色。切换后返回新的Token和角色对应的菜单权限，前端需更新本地Token并刷新菜单。只能切换到该管理员已分配的角色，否则报错。需要管理员认证。 + +**请求体** `角色切换请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `roleId` | `long` | 是 | 目标角色ID | + +**响应** `统一响应结果«管理员登录响应»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `管理员登录响应` | | 响应数据 | +|   `adminId` | `long` | | 管理员ID | +|   `avatar` | `string` | | 头像URL | +|   `requireTwoFa` | `boolean` | | 是否需要二次验证 | +|   `requireWechatBind` | `boolean` | | 是否需要绑定企业微信 | +|   `role` | `string` | | 角色标识（主角色） | +|   `roleName` | `string` | | 角色名称（主角色） | +|   `roles` | `角色信息[]` | | 角色列表（多角色） | +|     `roleId` | `long` | | 角色ID | +|     `roleKey` | `string` | | 角色标识 | +|     `roleName` | `string` | | 角色名称 | +|   `token` | `string` | | 登录令牌 | +|   `username` | `string` | | 用户名 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/auth/wechat-qr + +**生成企业微信扫码登录会话** + +生成企业微信扫码直接登录的会话信息（非2FA验证，而是扫码替代密码登录）。返回包含qrcodeUrl和state。前端展示二维码后通过轮询 /wechat-qr/status 检查登录状态。无需认证即可调用。 + +**响应** `统一响应结果«Map«string,object»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `object` | | 响应数据 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/auth/wechat-qr/callback + +**企业微信扫码登录回调** + +企业微信OAuth回调地址，扫码登录授权后微信服务器回调此接口。此接口由微信服务器调用，非前端直接调用。回调后标记会话为已扫码，前端通过轮询 /wechat-qr/status 获取登录结果。返回HTML页面，不返回JSON。 + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `code` | `string` | | 授权码 | | +| `state` | `string` | | 会话状态 | | + +**响应** `string` + +--- + +### `GET` /admin/auth/wechat-qr/status + +**查询企业微信扫码登录状态** + +前端轮询此接口检查扫码登录是否完成。返回status字段：PENDING=等待扫码，SCANNED=已扫码登录成功（附带token和用户信息）。建议轮询间隔2秒，超过5分钟未扫码会话自动失效。无需认证即可调用。 + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `state` | `string` | | 会话状态 | | + +**响应** `统一响应结果«Map«string,object»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `object` | | 响应数据 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/auth/wechat/verify-2fa + +**2FA验证** + +新设备登录时的企业微信二次验证。管理员登录返回needTwoFa=true后，前端调用此接口提交验证码完成登录。验证通过后设备将被标记为可信设备，后续登录不再需要2FA。无需认证即可调用。 + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `adminId` | `integer(int64)` | | 管理员ID | | + +**请求体** `二次验证请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `string` | 是 | 验证码 | + +**响应** `统一响应结果«管理员登录响应»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `管理员登录响应` | | 响应数据 | +|   `adminId` | `long` | | 管理员ID | +|   `avatar` | `string` | | 头像URL | +|   `requireTwoFa` | `boolean` | | 是否需要二次验证 | +|   `requireWechatBind` | `boolean` | | 是否需要绑定企业微信 | +|   `role` | `string` | | 角色标识（主角色） | +|   `roleName` | `string` | | 角色名称（主角色） | +|   `roles` | `角色信息[]` | | 角色列表（多角色） | +|     `roleId` | `long` | | 角色ID | +|     `roleKey` | `string` | | 角色标识 | +|     `roleName` | `string` | | 角色名称 | +|   `token` | `string` | | 登录令牌 | +|   `username` | `string` | | 用户名 | +| `message` | `string` | | 响应消息 | + +--- + +## 联系我们管理接口 + +### `GET` /admin/contact + +**联系方式列表** + +分页查询联系方式列表，支持按关键词和状态筛选。 + +**关联字典**： +- contact_channel_type（联系渠道类型）：返回字段channelType（PHONE=电话, WECHAT=微信, EMAIL=邮箱等） +- common_status（通用状态）：请求参数status和返回字段status + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `keyword` | `string` | | 搜索关键词 | | +| `page` | `integer(int32)` | | 页码 | | +| `pageSize` | `integer(int32)` | | 每页条数 | | +| `status` | `integer(int32)` | | 状态 | | + +**响应** `统一响应结果«分页结果«联系我们 VO»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«联系我们 VO»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `联系我们 VO[]` | | 数据列表 | +|     `channelType` | `string` | | 渠道类型，关联字典contact_channel_type：ABOUT=关于我们, ONLINE_CS=在线客服, PHONE=电话咨询 | +|     `content` | `string` | | 富文本内容（关于我们类型使用） | +|     `createdAt` | `string` | | 创建时间 | +|     `icon` | `string` | | 图标URL | +|     `id` | `string` | | 联系方式ID | +|     `sortOrder` | `int` | | 排序号 | +|     `status` | `int` | | 状态，关联字典common_status：0=下线, 1=上线 | +|     `subtitle` | `string` | | 副标题/描述 | +|     `title` | `string` | | 标题 | +|     `value` | `string` | | 渠道值 | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/contact + +**创建联系方式** + +新增一条联系方式记录。 + +**关联字典**： +- contact_channel_type（联系渠道类型）：请求字段channelType + +**请求体** `联系我们请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `channelType` | `string` | 是 | 渠道类型，关联字典contact_channel_type：ABOUT=关于我们, ONLINE_CS=在线客服, PHONE=电话咨询 | +| `content` | `string` | | 富文本内容（关于我们类型使用） | +| `icon` | `string` | | 图标URL | +| `sortOrder` | `int` | | 排序号（越小越靠前） | +| `status` | `int` | | 状态，关联字典common_status：0=下线, 1=上线 | +| `subtitle` | `string` | | 副标题/描述 | +| `title` | `string` | 是 | 标题 | +| `value` | `string` | | 渠道值（电话号码/客服链接等） | + +**响应** `统一响应结果«联系我们 VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `联系我们 VO` | | 响应数据 | +|   `channelType` | `string` | | 渠道类型，关联字典contact_channel_type：ABOUT=关于我们, ONLINE_CS=在线客服, PHONE=电话咨询 | +|   `content` | `string` | | 富文本内容（关于我们类型使用） | +|   `createdAt` | `string` | | 创建时间 | +|   `icon` | `string` | | 图标URL | +|   `id` | `string` | | 联系方式ID | +|   `sortOrder` | `int` | | 排序号 | +|   `status` | `int` | | 状态，关联字典common_status：0=下线, 1=上线 | +|   `subtitle` | `string` | | 副标题/描述 | +|   `title` | `string` | | 标题 | +|   `value` | `string` | | 渠道值 | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/contact/{id} + +**联系方式详情** + +获取指定联系方式的详细信息。 + +**关联字典**： +- contact_channel_type（联系渠道类型）：返回字段channelType +- common_status（通用状态）：返回字段status + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `id` | `integer` | | 联系方式ID | + +**响应** `统一响应结果«联系我们 VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `联系我们 VO` | | 响应数据 | +|   `channelType` | `string` | | 渠道类型，关联字典contact_channel_type：ABOUT=关于我们, ONLINE_CS=在线客服, PHONE=电话咨询 | +|   `content` | `string` | | 富文本内容（关于我们类型使用） | +|   `createdAt` | `string` | | 创建时间 | +|   `icon` | `string` | | 图标URL | +|   `id` | `string` | | 联系方式ID | +|   `sortOrder` | `int` | | 排序号 | +|   `status` | `int` | | 状态，关联字典common_status：0=下线, 1=上线 | +|   `subtitle` | `string` | | 副标题/描述 | +|   `title` | `string` | | 标题 | +|   `value` | `string` | | 渠道值 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/contact/{id} + +**更新联系方式** + +更新指定联系方式记录。 + +**关联字典**： +- contact_channel_type（联系渠道类型）：请求字段channelType + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `id` | `integer` | | 联系方式ID | + +**请求体** `联系我们请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `channelType` | `string` | 是 | 渠道类型，关联字典contact_channel_type：ABOUT=关于我们, ONLINE_CS=在线客服, PHONE=电话咨询 | +| `content` | `string` | | 富文本内容（关于我们类型使用） | +| `icon` | `string` | | 图标URL | +| `sortOrder` | `int` | | 排序号（越小越靠前） | +| `status` | `int` | | 状态，关联字典common_status：0=下线, 1=上线 | +| `subtitle` | `string` | | 副标题/描述 | +| `title` | `string` | 是 | 标题 | +| `value` | `string` | | 渠道值（电话号码/客服链接等） | + +**响应** `统一响应结果«联系我们 VO»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `联系我们 VO` | | 响应数据 | +|   `channelType` | `string` | | 渠道类型，关联字典contact_channel_type：ABOUT=关于我们, ONLINE_CS=在线客服, PHONE=电话咨询 | +|   `content` | `string` | | 富文本内容（关于我们类型使用） | +|   `createdAt` | `string` | | 创建时间 | +|   `icon` | `string` | | 图标URL | +|   `id` | `string` | | 联系方式ID | +|   `sortOrder` | `int` | | 排序号 | +|   `status` | `int` | | 状态，关联字典common_status：0=下线, 1=上线 | +|   `subtitle` | `string` | | 副标题/描述 | +|   `title` | `string` | | 标题 | +|   `value` | `string` | | 渠道值 | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/contact/{id} + +**删除联系方式** + +删除指定的联系方式记录（软删除）。 + +**权限**：需要管理员登录。 +**注意**：删除后小程序端将不再展示该联系方式。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `id` | `integer` | | 联系方式ID | + +**响应** `统一响应结果«Void»` + +--- + +## 菜单管理接口 + +### `POST` /admin/menu + +**创建菜单** + +创建新的菜单/目录/按钮。menuType取值：DIRECTORY=目录（含子菜单） MENU=页面菜单 BUTTON=操作按钮。目录和菜单需设置path路由路径，菜单还需设置component组件路径。按钮类型需设置permissionCode权限标识（如system:user:add）。需要SUPER_ADMIN角色。 + +**关联字典**： +- menu_type（菜单类型）：请求/返回字段menuType（DIRECTORY=目录, MENU=菜单, BUTTON=按钮） +- common_status（通用状态）：返回字段status + +**请求体** `创建菜单请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `component` | `string` | | 组件路径 | +| `icon` | `string` | | 菜单图标 | +| `isCache` | `boolean` | | 是否缓存(true=缓存 false=不缓存) | +| `menuName` | `string` | 是 | 菜单名称 | +| `menuType` | `string` | 是 | 菜单类型：DIRECTORY=目录 MENU=菜单 BUTTON=按钮 | +| `parentId` | `long` | | 父菜单ID（顶级菜单为空） | +| `path` | `string` | | 路由路径 | +| `permissionCode` | `string` | | 权限标识 | +| `sortOrder` | `int` | | 排序号 | +| `visible` | `boolean` | | 是否可见 | + +**响应** `统一响应结果«SysMenu»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `SysMenu` | | 响应数据 | +|   `children` | `SysMenu[]` | | | +|     `children` | `SysMenu[]` | | | +|     `component` | `string` | | | +|     `createdAt` | `string` | | | +|     `icon` | `string` | | | +|     `isCache` | `boolean` | | | +|     `menuId` | `long` | | | +|     `menuName` | `string` | | | +|     `menuType` | `string` | | | +|     `parentId` | `long` | | | +|     `path` | `string` | | | +|     `permissionCode` | `string` | | | +|     `sortOrder` | `int` | | | +|     `status` | `string` | | | +|     `updatedAt` | `string` | | | +|     `visible` | `boolean` | | | +|   `component` | `string` | | | +|   `createdAt` | `string` | | | +|   `icon` | `string` | | | +|   `isCache` | `boolean` | | | +|   `menuId` | `long` | | | +|   `menuName` | `string` | | | +|   `menuType` | `string` | | | +|   `parentId` | `long` | | | +|   `path` | `string` | | | +|   `permissionCode` | `string` | | | +|   `sortOrder` | `int` | | | +|   `status` | `string` | | | +|   `updatedAt` | `string` | | | +|   `visible` | `boolean` | | | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/menu/my + +**获取当前管理员菜单** + +获取当前登录管理员的菜单树（基于其当前角色的权限）。SUPER_ADMIN角色返回完整菜单树，其他角色返回已授权的菜单子集。前端登录后调用此接口动态生成路由和侧边栏菜单。需要管理员认证。 + +**响应** `统一响应结果«List«SysMenu»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `SysMenu[]` | | 响应数据 | +|   `children` | `SysMenu[]` | | | +|     `children` | `SysMenu[]` | | | +|     `component` | `string` | | | +|     `createdAt` | `string` | | | +|     `icon` | `string` | | | +|     `isCache` | `boolean` | | | +|     `menuId` | `long` | | | +|     `menuName` | `string` | | | +|     `menuType` | `string` | | | +|     `parentId` | `long` | | | +|     `path` | `string` | | | +|     `permissionCode` | `string` | | | +|     `sortOrder` | `int` | | | +|     `status` | `string` | | | +|     `updatedAt` | `string` | | | +|     `visible` | `boolean` | | | +|   `component` | `string` | | | +|   `createdAt` | `string` | | | +|   `icon` | `string` | | | +|   `isCache` | `boolean` | | | +|   `menuId` | `long` | | | +|   `menuName` | `string` | | | +|   `menuType` | `string` | | | +|   `parentId` | `long` | | | +|   `path` | `string` | | | +|   `permissionCode` | `string` | | | +|   `sortOrder` | `int` | | | +|   `status` | `string` | | | +|   `updatedAt` | `string` | | | +|   `visible` | `boolean` | | | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/menu/tree + +**获取完整菜单树** + +获取系统所有菜单的完整树形结构。用于角色权限配置页面展示完整的菜单树供勾选。仅SUPER_ADMIN可查看完整菜单树。需要管理员认证。 + +**关联字典**： +- menu_type（菜单类型）：返回字段menuType +- common_status（通用状态）：返回字段status + +**响应** `统一响应结果«List«SysMenu»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `SysMenu[]` | | 响应数据 | +|   `children` | `SysMenu[]` | | | +|     `children` | `SysMenu[]` | | | +|     `component` | `string` | | | +|     `createdAt` | `string` | | | +|     `icon` | `string` | | | +|     `isCache` | `boolean` | | | +|     `menuId` | `long` | | | +|     `menuName` | `string` | | | +|     `menuType` | `string` | | | +|     `parentId` | `long` | | | +|     `path` | `string` | | | +|     `permissionCode` | `string` | | | +|     `sortOrder` | `int` | | | +|     `status` | `string` | | | +|     `updatedAt` | `string` | | | +|     `visible` | `boolean` | | | +|   `component` | `string` | | | +|   `createdAt` | `string` | | | +|   `icon` | `string` | | | +|   `isCache` | `boolean` | | | +|   `menuId` | `long` | | | +|   `menuName` | `string` | | | +|   `menuType` | `string` | | | +|   `parentId` | `long` | | | +|   `path` | `string` | | | +|   `permissionCode` | `string` | | | +|   `sortOrder` | `int` | | | +|   `status` | `string` | | | +|   `updatedAt` | `string` | | | +|   `visible` | `boolean` | | | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/menu/tree/role/{roleId} + +**获取角色菜单树** + +获取指定角色已分配的菜单树形结构。 +用于角色权限配置页面，展示该角色已拥有的菜单权限。 + +**权限**：需要管理员登录。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `roleId` | `integer` | | 角色ID | + +**响应** `统一响应结果«List«SysMenu»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `SysMenu[]` | | 响应数据 | +|   `children` | `SysMenu[]` | | | +|     `children` | `SysMenu[]` | | | +|     `component` | `string` | | | +|     `createdAt` | `string` | | | +|     `icon` | `string` | | | +|     `isCache` | `boolean` | | | +|     `menuId` | `long` | | | +|     `menuName` | `string` | | | +|     `menuType` | `string` | | | +|     `parentId` | `long` | | | +|     `path` | `string` | | | +|     `permissionCode` | `string` | | | +|     `sortOrder` | `int` | | | +|     `status` | `string` | | | +|     `updatedAt` | `string` | | | +|     `visible` | `boolean` | | | +|   `component` | `string` | | | +|   `createdAt` | `string` | | | +|   `icon` | `string` | | | +|   `isCache` | `boolean` | | | +|   `menuId` | `long` | | | +|   `menuName` | `string` | | | +|   `menuType` | `string` | | | +|   `parentId` | `long` | | | +|   `path` | `string` | | | +|   `permissionCode` | `string` | | | +|   `sortOrder` | `int` | | | +|   `status` | `string` | | | +|   `updatedAt` | `string` | | | +|   `visible` | `boolean` | | | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/menu/{menuId} + +**获取菜单详情** + +获取指定菜单的详细信息，包括名称、路径、组件、图标、排序、权限标识等。 + +**权限**：需要管理员登录。 + +**关联字典**： +- menu_type（菜单类型）：返回字段menuType（DIRECTORY=目录, MENU=菜单, BUTTON=按钮） +- common_status（通用状态）：返回字段status + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `menuId` | `integer` | | 菜单ID | + +**响应** `统一响应结果«SysMenu»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `SysMenu` | | 响应数据 | +|   `children` | `SysMenu[]` | | | +|     `children` | `SysMenu[]` | | | +|     `component` | `string` | | | +|     `createdAt` | `string` | | | +|     `icon` | `string` | | | +|     `isCache` | `boolean` | | | +|     `menuId` | `long` | | | +|     `menuName` | `string` | | | +|     `menuType` | `string` | | | +|     `parentId` | `long` | | | +|     `path` | `string` | | | +|     `permissionCode` | `string` | | | +|     `sortOrder` | `int` | | | +|     `status` | `string` | | | +|     `updatedAt` | `string` | | | +|     `visible` | `boolean` | | | +|   `component` | `string` | | | +|   `createdAt` | `string` | | | +|   `icon` | `string` | | | +|   `isCache` | `boolean` | | | +|   `menuId` | `long` | | | +|   `menuName` | `string` | | | +|   `menuType` | `string` | | | +|   `parentId` | `long` | | | +|   `path` | `string` | | | +|   `permissionCode` | `string` | | | +|   `sortOrder` | `int` | | | +|   `status` | `string` | | | +|   `updatedAt` | `string` | | | +|   `visible` | `boolean` | | | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/menu/{menuId} + +**更新菜单** + +更新指定菜单的名称、路径、组件、图标、排序、状态等信息。 + +**权限**：需要SUPER_ADMIN角色。 +**注意**：修改后需清除 Redis 菜单缓存才能生效。 + +**关联字典**： +- menu_type（菜单类型）：请求字段menuType（DIRECTORY=目录, MENU=菜单, BUTTON=按钮） +- common_status（通用状态）：请求字段status + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `menuId` | `integer` | | 菜单ID | + +**请求体** `更新菜单请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `component` | `string` | | 组件路径 | +| `icon` | `string` | | 菜单图标 | +| `isCache` | `boolean` | | 是否缓存(true=缓存 false=不缓存) | +| `menuName` | `string` | | 菜单名称 | +| `menuType` | `string` | | 菜单类型：DIRECTORY=目录 MENU=菜单 BUTTON=按钮 | +| `parentId` | `long` | | 父菜单ID | +| `path` | `string` | | 路由路径 | +| `permissionCode` | `string` | | 权限标识 | +| `sortOrder` | `int` | | 排序号 | +| `status` | `string` | | 状态：ACTIVE=启用 DISABLED=禁用 | +| `visible` | `boolean` | | 是否可见 | + +**响应** `统一响应结果«SysMenu»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `SysMenu` | | 响应数据 | +|   `children` | `SysMenu[]` | | | +|     `children` | `SysMenu[]` | | | +|     `component` | `string` | | | +|     `createdAt` | `string` | | | +|     `icon` | `string` | | | +|     `isCache` | `boolean` | | | +|     `menuId` | `long` | | | +|     `menuName` | `string` | | | +|     `menuType` | `string` | | | +|     `parentId` | `long` | | | +|     `path` | `string` | | | +|     `permissionCode` | `string` | | | +|     `sortOrder` | `int` | | | +|     `status` | `string` | | | +|     `updatedAt` | `string` | | | +|     `visible` | `boolean` | | | +|   `component` | `string` | | | +|   `createdAt` | `string` | | | +|   `icon` | `string` | | | +|   `isCache` | `boolean` | | | +|   `menuId` | `long` | | | +|   `menuName` | `string` | | | +|   `menuType` | `string` | | | +|   `parentId` | `long` | | | +|   `path` | `string` | | | +|   `permissionCode` | `string` | | | +|   `sortOrder` | `int` | | | +|   `status` | `string` | | | +|   `updatedAt` | `string` | | | +|   `visible` | `boolean` | | | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/menu/{menuId} + +**删除菜单** + +删除指定的菜单/目录/按钮（软删除）。 + +**权限**：需要SUPER_ADMIN角色。 +**注意**：如果该菜单有子菜单，需先删除子菜单才能删除父菜单。删除后需清除 Redis 菜单缓存才能生效。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `menuId` | `integer` | | 菜单ID | + +**响应** `统一响应结果«Void»` + +--- + +## 角色管理接口 + +### `GET` /admin/role + +**分页查询角色** + +分页查询系统角色列表，支持按状态筛选。 + +**关联字典**： +- common_status（通用状态）：ACTIVE=启用, DISABLED=禁用（筛选条件+列表展示） + + +**查询参数** + +| 参数 | 类型 | 必填 | 说明 | 示例 | +| --- | --- | --- | --- | --- | +| `page` | `integer(int32)` | | 页码 | | +| `pageSize` | `integer(int32)` | | 每页条数 | | +| `status` | `string` | | 状态 | | + +**响应** `统一响应结果«分页结果«SysRole»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `分页结果«SysRole»` | | 响应数据 | +|   `page` | `int` | | 当前页码 | +|   `pageSize` | `int` | | 每页条数 | +|   `records` | `SysRole[]` | | 数据列表 | +|     `createdAt` | `string` | | | +|     `remark` | `string` | | | +|     `roleId` | `long` | | | +|     `roleKey` | `string` | | | +|     `roleName` | `string` | | | +|     `sortOrder` | `int` | | | +|     `status` | `string` | | | +|     `updatedAt` | `string` | | | +|   `total` | `int` | | 总记录数 | +| `message` | `string` | | 响应消息 | + +--- + +### `POST` /admin/role + +**创建角色** + +创建新的系统角色。角色标识（roleKey）全局唯一，创建后不可修改，用于代码中的权限判断。创建后需通过[分配菜单权限]接口为角色授权菜单。需要SUPER_ADMIN角色。 + +**请求体** `创建角色请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `remark` | `string` | | 备注 | +| `roleKey` | `string` | 是 | 角色标识 | +| `roleName` | `string` | 是 | 角色名称 | +| `sortOrder` | `int` | | 排序号 | + +**响应** `统一响应结果«SysRole»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `SysRole` | | 响应数据 | +|   `createdAt` | `string` | | | +|   `remark` | `string` | | | +|   `roleId` | `long` | | | +|   `roleKey` | `string` | | | +|   `roleName` | `string` | | | +|   `sortOrder` | `int` | | | +|   `status` | `string` | | | +|   `updatedAt` | `string` | | | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/role/all + +**获取所有角色(下拉)** + +获取所有状态正常的角色列表，用于下拉选择框。不分页，返回全部角色。创建管理员、筛选管理员列表时使用。需要管理员认证。 + +**响应** `统一响应结果«List«SysRole»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `SysRole[]` | | 响应数据 | +|   `createdAt` | `string` | | | +|   `remark` | `string` | | | +|   `roleId` | `long` | | | +|   `roleKey` | `string` | | | +|   `roleName` | `string` | | | +|   `sortOrder` | `int` | | | +|   `status` | `string` | | | +|   `updatedAt` | `string` | | | +| `message` | `string` | | 响应消息 | + +--- + +### `GET` /admin/role/{roleId} + +**获取角色详情(含菜单ID)** + +获取角色基本信息及其已分配的菜单ID列表。返回role对象和menuIds数组，用于角色编辑页面回显已勾选的菜单。需要管理员认证。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `roleId` | `integer` | | 角色ID | + +**响应** `统一响应结果«Map«string,object»»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `object` | | 响应数据 | +| `message` | `string` | | 响应消息 | + +--- + +### `PUT` /admin/role/{roleId} + +**更新角色** + +更新角色名称、状态等信息。角色标识（roleKey）不可修改。 + +**关联字典**： +- common_status（通用状态）：ACTIVE=启用, DISABLED=禁用 + + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `roleId` | `integer` | | 角色ID | + +**请求体** `更新角色请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `remark` | `string` | | 备注 | +| `roleName` | `string` | | 角色名称 | +| `sortOrder` | `int` | | 排序号 | +| `status` | `string` | | 状态：ACTIVE=启用 DISABLED=禁用 | + +**响应** `统一响应结果«SysRole»` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `code` | `int` | | 状态码 | +| `data` | `SysRole` | | 响应数据 | +|   `createdAt` | `string` | | | +|   `remark` | `string` | | | +|   `roleId` | `long` | | | +|   `roleKey` | `string` | | | +|   `roleName` | `string` | | | +|   `sortOrder` | `int` | | | +|   `status` | `string` | | | +|   `updatedAt` | `string` | | | +| `message` | `string` | | 响应消息 | + +--- + +### `DELETE` /admin/role/{roleId} + +**删除角色** + +删除指定角色（软删除）。如果该角色下还有关联的管理员，将无法删除，需先解除绑定关系。内置角色（SUPER_ADMIN等）不可删除。需要SUPER_ADMIN角色。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `roleId` | `integer` | | 角色ID | + +**响应** `统一响应结果«Void»` + +--- + +### `PUT` /admin/role/{roleId}/menus + +**分配菜单权限** + +为指定角色分配菜单权限（全量覆盖模式）。传入的menuIds将完全替换该角色原有的菜单权限。分配后该角色的所有在线管理员下次请求 /admin/menu/my 时会获取到新的菜单树。注意：需同步清除Redis中的菜单缓存，否则前端拿到的是旧菜单。需要SUPER_ADMIN角色。 + +**路径参数** + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `roleId` | `integer` | | 角色ID | + +**请求体** `分配菜单权限请求` + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `menuIds` | `long[]` | 是 | 菜单ID列表 | + +**响应** `统一响应结果«Void»` + +--- diff --git a/changelogs/2026-03/2026-03-17_0951_d650272_fix_2FA.md b/changelogs/2026-03/2026-03-17_0951_d650272_fix_2FA.md new file mode 100644 index 0000000..7d8fa03 --- /dev/null +++ b/changelogs/2026-03/2026-03-17_0951_d650272_fix_2FA.md @@ -0,0 +1,33 @@ +# 接口变更记录 — 2026-03-17 09:51 + +> **提交** `d650272` · **作者** wx · **时间** 2026-03-17 09:51:48 +0800 +> +> fix: 测试环境2FA验证修复 + 管理员列表关键词搜索 + +## 变更总览 + +- **用户服务** + - AdminUser (改1) + +--- + +## 用户服务 + +### AdminUser + +#### ✏️ `GET` /admin/user — 管理员列表 + +- 参数: page(int), pageSize(int), roleId(Long), status(String), wechatBound(Boolean) → page(int), pageSize(int), roleId(Long), status(String), wechatBound(Boolean), keyword(String) + +--- + +
+📁 全部变更文件 (点击展开) + +``` +M hl-user-service/src/main/java/com/hulalv/user/controller/AdminUserController.java +M hl-user-service/src/main/java/com/hulalv/user/service/AdminAuthService.java +M hl-user-service/src/main/java/com/hulalv/user/service/AdminUserService.java +M hl-user-service/src/test/java/com/hulalv/user/service/AdminUserServiceTest.java +``` +
\ No newline at end of file