diff --git a/2026-03/17_0928/CHANGES.md b/2026-03/17_0928/CHANGES.md deleted file mode 100644 index c6a0ab6..0000000 --- a/2026-03/17_0928/CHANGES.md +++ /dev/null @@ -1,5 +0,0 @@ -# API 变更通知 - -**更新时间**: 2026-03-17 09:28 - -> 无变更 \ No newline at end of file diff --git a/2026-03/17_0928/hl-contract-service.md b/2026-03/17_0928/hl-contract-service.md deleted file mode 100644 index 7c4fc19..0000000 --- a/2026-03/17_0928/hl-contract-service.md +++ /dev/null @@ -1,793 +0,0 @@ -# 合同服务 API 文档 - -**服务**: `hl-contract-service` -**接口总数**: 18 - -## 目录 - -- **合同管理** (12 个接口) -- **补充约定模板管理** (6 个接口) - ---- - -## 合同管理 - -### `GET` /admin/contract/active-by-order/{orderId} - -**获取订单有效合同** - -返回订单当前有效的合同（非作废状态的最新合同），用于检查订单是否已有签署中或已签署的合同。 - -**权限**：需管理员登录。 - -**关联字典**： -- contract_status：合同状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«合同信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同信息` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/agencies - -**可用旅行社列表** - -返回系统配置的旅行社列表，创建合同时选择签约旅行社 - -**响应** `统一响应结果«List«旅行社信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `旅行社信息[]` | | 响应数据 | -|   `agencyAddress` | `string` | | 旅行社地址 | -|   `agencyName` | `string` | | 旅行社名称 | -|   `businessLicenseNumber` | `string` | | 营业执照号 | -|   `businessScope` | `string` | | 经营范围 | -|   `code` | `string` | | 旅行社编码 | -|   `licenseNumber` | `string` | | 旅行社许可证号 | -|   `regionId` | `string` | | 地区ID | -|   `transactorName` | `string` | | 经办人姓名 | -|   `transactorPhone` | `string` | | 经办人电话 | -|   `zjParentId` | `int` | | 属地管理机构ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/by-order/{orderId} - -**按订单查询合同** - -查询指定订单下的所有合同记录（含已作废），按创建时间倒序排列。用于订单详情页展示合同历史。 - -**权限**：需管理员登录。 - -**关联字典**： -- contract_status：合同状态（列表显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«List«合同信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同信息[]` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/contract/create - -**创建合同(标准模式)** - -标准电子签约流程：创建合同 → 平台生成合同PDF → 发送签署短信给出行人 → 出行人在线签署 → 回调更新状态。状态流转：CREATED → SIGNING → SIGNED - -**请求体** `创建合同请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `adultCost` | `number` | 是 | 成人费用 | -| `agencyCode` | `string` | | 旅行社编号（可选，默认使用配置值） | -| `childCost` | `number` | | 儿童费用 | -| `contactName` | `string` | 是 | 联系人姓名 | -| `contactPhone` | `string` | 是 | 联系人电话 | -| `contractType` | `string` | | 合同类型: TOUR-旅游合同(默认), INSURANCE-保险单 | -| `days` | `int` | | 行程天数 | -| `departureCity` | `string` | | 出发城市 | -| `departureDate` | `string` | 是 | 出发日期 | -| `destination` | `string` | 是 | 目的地 | -| `disputeResolution` | `int` | | 争议解决方式: 1-仲裁 2-诉讼 | -| `groupId` | `string` | | 团号 | -| `leastCustomerNumber` | `int` | | 最低成团人数 | -| `nights` | `int` | | 住宿晚数 | -| `orderId` | `long` | | 订单ID | -| `paymentMethod` | `int` | | 付款方式: 1-现金 2-转账 3-在线 | -| `returnDate` | `string` | 是 | 返回日期 | -| `routeName` | `string` | 是 | 线路名称 | -| `signatoryIdNumber` | `string` | 是 | 签署人证件号码 | -| `signatoryIdType` | `int` | | 签署人证件类型: 1-身份证 | -| `signatoryMode` | `int` | | 签署模式: 1-短信 2-现场 3-线下 | -| `signatoryName` | `string` | 是 | 签署人姓名 | -| `signatoryPhone` | `string` | 是 | 签署人电话 | -| `signingPlace` | `string` | | 签约地点 | -| `supplementaryClause` | `string` | | 补充约定内容 | -| `templateCode` | `string` | 是 | 模板编码 | -| `totalAmount` | `number` | 是 | 合同总金额 | -| `transactorName` | `string` | | 经办人姓名 | -| `transactorPhone` | `string` | | 经办人电话 | -| `travelers` | `合同出行人请求[]` | 是 | 出行人列表 | -|   `age` | `int` | | 年龄 | -|   `gender` | `string` | | 性别: male/female | -|   `health` | `string` | | 健康信息 | -|   `idCardNo` | `string` | 是 | 证件号码 | -|   `idCardType` | `int` | | 证件类型: 1-身份证 2-护照 | -|   `isChild` | `boolean` | | 是否儿童 | -|   `isSigner` | `boolean` | | 是否签署人 | -|   `name` | `string` | 是 | 姓名 | -|   `phone` | `string` | | 手机号 | -| `vehicleModel` | `string` | | 车型名称(产品快照) | - -**响应** `统一响应结果«合同详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同详情` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `statusLogs` | `合同状态变更日志[]` | | 状态变更日志 | -|     `createTime` | `string` | | 创建时间 | -|     `logId` | `long` | | 日志ID | -|     `newStatus` | `string` | | 新状态 | -|     `oldStatus` | `string` | | 旧状态 | -|     `source` | `string` | | 变更来源 | -|   `supplementaryClause` | `string` | | 补充约定内容 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -|   `travelers` | `合同出行人信息[]` | | 出行人列表 | -|     `idCardNo` | `string` | | 证件号码 | -|     `idCardType` | `string` | | 证件类型 | -|     `isSigner` | `boolean` | | 是否签署人 | -|     `name` | `string` | | 姓名 | -|     `phone` | `string` | | 手机号 | -|     `travelerId` | `long` | | 出行人ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/list - -**合同列表** - -分页查询合同记录，支持按订单号、合同状态、旅行社筛选 - -**关联字典**： -- contract_status：合同状态（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `orderId` | `integer(int64)` | | 订单ID | 1001 | -| `page` | `integer(int32)` | | 页码 | 1 | -| `pageSize` | `integer(int32)` | | 每页条数 | 20 | -| `platform` | `string` | | 签约平台 | TOURAGE | -| `status` | `string` | | 合同状态 | SIGNED | - -**响应** `统一响应结果«分页结果«合同信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«合同信息»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `合同信息[]` | | 数据列表 | -|     `agencyCode` | `string` | | 旅行社编号 | -|     `contactName` | `string` | | 联系人姓名 | -|     `contactPhone` | `string` | | 联系人电话 | -|     `contractId` | `long` | | 合同ID | -|     `contractNumber` | `string` | | 合同编号 | -|     `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|     `createTime` | `string` | | 创建时间 | -|     `departureDate` | `string` | | 出发日期 | -|     `destination` | `string` | | 目的地 | -|     `fileUrl` | `string` | | 合同文件URL | -|     `mode` | `string` | | 签约模式: STANDARD/SYNC | -|     `orderId` | `long` | | 订单ID | -|     `platform` | `string` | | 签约平台 | -|     `qrCodeUrl` | `string` | | 二维码URL | -|     `returnDate` | `string` | | 返回日期 | -|     `signUrl` | `string` | | 签署URL | -|     `status` | `string` | | 合同状态 | -|     `statusLabel` | `string` | | 合同状态标签 | -|     `templateCode` | `string` | | 模板编码 | -|     `templateName` | `string` | | 模板名称 | -|     `totalAmount` | `number` | | 合同总金额 | -|     `touristCount` | `int` | | 出行人数 | -|     `travelAgencyName` | `string` | | 旅行社名称 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/contract/report - -**报备合同(同步模式)** - -线下签约模式：创建合同记录 → 管理员上传已签署的PDF → 同步到12301报备平台。状态流转：CREATED → UPLOADED → REPORTED - -**请求体** `报备合同请求（同步模式）` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `adultCost` | `number` | 是 | 成人费用 | -| `agencyCode` | `string` | | 旅行社编号 | -| `childCost` | `number` | | 儿童费用 | -| `contactName` | `string` | 是 | 联系人姓名 | -| `contactPhone` | `string` | 是 | 联系人电话 | -| `contractType` | `string` | | 合同类型: TOUR-旅游合同(默认), INSURANCE-保险单 | -| `days` | `int` | | 行程天数 | -| `departureCity` | `string` | | 出发城市 | -| `departureDate` | `string` | 是 | 出发日期 | -| `destination` | `string` | 是 | 目的地 | -| `disputeResolution` | `int` | | 争议解决方式: 1-仲裁 2-诉讼 | -| `groupId` | `string` | | 团号 | -| `leastCustomerNumber` | `int` | | 最低成团人数 | -| `nights` | `int` | | 住宿晚数 | -| `orderId` | `long` | | 订单ID | -| `paymentMethod` | `int` | | 付款方式: 1-现金 2-转账 3-在线 | -| `returnDate` | `string` | 是 | 返回日期 | -| `routeName` | `string` | 是 | 线路名称 | -| `signatoryIdNumber` | `string` | 是 | 签署人证件号码 | -| `signatoryIdType` | `int` | | 签署人证件类型: 1-身份证 | -| `signatoryMode` | `int` | | 签署模式（同步模式默认2-现场） | -| `signatoryName` | `string` | 是 | 签署人姓名 | -| `signatoryPhone` | `string` | 是 | 签署人电话 | -| `signingPlace` | `string` | | 签约地点 | -| `supplementaryClause` | `string` | | 补充约定内容 | -| `templateCode` | `string` | 是 | 模板编码 | -| `totalAmount` | `number` | 是 | 合同总金额 | -| `transactorName` | `string` | | 经办人姓名 | -| `transactorPhone` | `string` | | 经办人电话 | -| `travelers` | `合同出行人请求[]` | 是 | 出行人列表 | -|   `age` | `int` | | 年龄 | -|   `gender` | `string` | | 性别: male/female | -|   `health` | `string` | | 健康信息 | -|   `idCardNo` | `string` | 是 | 证件号码 | -|   `idCardType` | `int` | | 证件类型: 1-身份证 2-护照 | -|   `isChild` | `boolean` | | 是否儿童 | -|   `isSigner` | `boolean` | | 是否签署人 | -|   `name` | `string` | 是 | 姓名 | -|   `phone` | `string` | | 手机号 | - -**响应** `统一响应结果«合同详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同详情` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `statusLogs` | `合同状态变更日志[]` | | 状态变更日志 | -|     `createTime` | `string` | | 创建时间 | -|     `logId` | `long` | | 日志ID | -|     `newStatus` | `string` | | 新状态 | -|     `oldStatus` | `string` | | 旧状态 | -|     `source` | `string` | | 变更来源 | -|   `supplementaryClause` | `string` | | 补充约定内容 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -|   `travelers` | `合同出行人信息[]` | | 出行人列表 | -|     `idCardNo` | `string` | | 证件号码 | -|     `idCardType` | `string` | | 证件类型 | -|     `isSigner` | `boolean` | | 是否签署人 | -|     `name` | `string` | | 姓名 | -|     `phone` | `string` | | 手机号 | -|     `travelerId` | `long` | | 出行人ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/templates - -**合同模板列表** - -返回合同平台可用的合同模板列表，创建合同时选择模板 - -**响应** `统一响应结果«List«合同模板信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同模板信息[]` | | 响应数据 | -|   `createTime` | `string` | | 创建时间 | -|   `description` | `string` | | 模板描述 | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `platform` | `string` | | 签约平台 | -|   `status` | `string` | | 模板状态 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateId` | `long` | | 模板ID | -|   `templateName` | `string` | | 模板名称 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/{id} - -**合同详情** - -**关联字典**： -- contract_status：合同状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 合同ID | - -**响应** `统一响应结果«合同详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同详情` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `statusLogs` | `合同状态变更日志[]` | | 状态变更日志 | -|     `createTime` | `string` | | 创建时间 | -|     `logId` | `long` | | 日志ID | -|     `newStatus` | `string` | | 新状态 | -|     `oldStatus` | `string` | | 旧状态 | -|     `source` | `string` | | 变更来源 | -|   `supplementaryClause` | `string` | | 补充约定内容 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -|   `travelers` | `合同出行人信息[]` | | 出行人列表 | -|     `idCardNo` | `string` | | 证件号码 | -|     `idCardType` | `string` | | 证件类型 | -|     `isSigner` | `boolean` | | 是否签署人 | -|     `name` | `string` | | 姓名 | -|     `phone` | `string` | | 手机号 | -|     `travelerId` | `long` | | 出行人ID | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/contract/{id}/invalidate - -**作废合同** - -将合同标记为作废状态（不可恢复）。作废后该合同不再有效，可重新为订单创建新合同 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 合同ID | - -**响应** `统一响应结果«合同信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同信息` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/contract/{id}/resend-sms - -**重发签署短信** - -重新发送签署短信给出行人，用于签署短信过期或未收到的场景。仅SIGNING状态的合同可操作 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 合同ID | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/{id}/status - -**刷新合同状态(从平台同步)** - -主动查询合同平台的最新签署状态并同步到本地，适用于回调未到达的场景 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 合同ID | - -**响应** `统一响应结果«合同信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同信息` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/contract/{id}/upload-pdf - -**上传已签署PDF(同步模式)** - -同步模式专用：上传线下签署完成的合同PDF文件，上传后合同状态变为UPLOADED，可进一步报备 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 合同ID | - -**响应** `统一响应结果«合同信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同信息` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -| `message` | `string` | | 响应消息 | - ---- - -## 补充约定模板管理 - -### `POST` /admin/contract/clause-template - -**创建补充约定模板** - -创建合同补充约定的模板，支持变量占位符。创建后默认启用 - -**请求体** `补充约定模板请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `content` | `string` | 是 | 模板内容 | -| `name` | `string` | 是 | 模板名称 | -| `sortOrder` | `int` | | 排序（升序） | - -**响应** `统一响应结果«补充约定模板»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `补充约定模板` | | 响应数据 | -|   `content` | `string` | | 模板内容 | -|   `createTime` | `string` | | 创建时间 | -|   `name` | `string` | | 模板名称 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `string` | | 状态: ACTIVE/INACTIVE | -|   `templateId` | `long` | | 模板ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/clause-template/list - -**获取启用的补充约定模板列表（创建合同用）** - -返回所有启用状态的补充约定模板，创建合同时选择需要附加的补充约定条款。 - -**权限**：需管理员登录。 - -**响应** `统一响应结果«List«补充约定模板»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `补充约定模板[]` | | 响应数据 | -|   `content` | `string` | | 模板内容 | -|   `createTime` | `string` | | 创建时间 | -|   `name` | `string` | | 模板名称 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `string` | | 状态: ACTIVE/INACTIVE | -|   `templateId` | `long` | | 模板ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/clause-template/list-all - -**获取全部补充约定模板（管理页用）** - -**关联字典**： -- common_status：通用状态（列表显示，ACTIVE=启用/INACTIVE=停用） - -**响应** `统一响应结果«List«补充约定模板»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `补充约定模板[]` | | 响应数据 | -|   `content` | `string` | | 模板内容 | -|   `createTime` | `string` | | 创建时间 | -|   `name` | `string` | | 模板名称 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `string` | | 状态: ACTIVE/INACTIVE | -|   `templateId` | `long` | | 模板ID | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/contract/clause-template/{id} - -**更新补充约定模板** - -更新模板的标题和内容。已被合同引用的模板更新不影响已创建的合同（合同记录的是快照内容）。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 模板ID | - -**请求体** `补充约定模板请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `content` | `string` | 是 | 模板内容 | -| `name` | `string` | 是 | 模板名称 | -| `sortOrder` | `int` | | 排序（升序） | - -**响应** `统一响应结果«补充约定模板»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `补充约定模板` | | 响应数据 | -|   `content` | `string` | | 模板内容 | -|   `createTime` | `string` | | 创建时间 | -|   `name` | `string` | | 模板名称 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `string` | | 状态: ACTIVE/INACTIVE | -|   `templateId` | `long` | | 模板ID | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/contract/clause-template/{id} - -**删除补充约定模板** - -软删除模板。已被合同引用的模板仍可删除，不影响已创建的合同 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 模板ID | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/contract/clause-template/{id}/toggle-status - -**切换模板启用/停用状态** - -**关联字典**： -- common_status：通用状态（状态切换，ACTIVE=启用/INACTIVE=停用） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 模板ID | - -**响应** `统一响应结果«补充约定模板»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `补充约定模板` | | 响应数据 | -|   `content` | `string` | | 模板内容 | -|   `createTime` | `string` | | 创建时间 | -|   `name` | `string` | | 模板名称 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `string` | | 状态: ACTIVE/INACTIVE | -|   `templateId` | `long` | | 模板ID | -| `message` | `string` | | 响应消息 | - ---- diff --git a/2026-03/17_0928/hl-file-service.md b/2026-03/17_0928/hl-file-service.md deleted file mode 100644 index 7c17ab6..0000000 --- a/2026-03/17_0928/hl-file-service.md +++ /dev/null @@ -1,331 +0,0 @@ -# 文件服务 API 文档 - -**服务**: `hl-file-service` -**接口总数**: 11 - -## 目录 - -- **C端文件上传** (3 个接口) -- **文件管理** (8 个接口) - ---- - -## C端文件上传 - -### `GET` /mp/file/preview-by-url - -**文件在线预览** - -返回HTML预览页面，小程序通过web-view打开。支持PDF、图片、Office文档 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `url` | `string` | | 文件完整URL | | - ---- - -### `POST` /mp/file/upload - -**上传文件（C端用户）** - -小程序端直接上传文件，支持头像、评价图片等场景。groupKey决定存储路径和文件策略，默认为avatar - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `groupKey` | `string` | | 文件分组标识 | | - -**响应** `统一响应结果«文件信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `文件信息` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `fileHash` | `string` | | 文件MD5哈希 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `groupKey` | `string` | | 业务分组 | -|   `mimeType` | `string` | | MIME类型 | -|   `ossUrl` | `string` | | OSS地址 | -|   `previewUrl` | `string` | | 预览地址 | -|   `refCount` | `int` | | 引用次数 | -|   `status` | `string` | | 文件状态 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/file/{fileId}/preview - -**文件内容流式预览** - -流式输出文件内容，设置正确的Content-Type头。用于小程序端通过web-view直接预览图片和PDF等文件。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `fileId` | `integer` | | 文件ID | - ---- - -## 文件管理 - -### `GET` /admin/file/list - -**文件列表（分页）** - -支持按文件类型、分组、上传者等条件筛选，按上传时间倒序分页返回 - -**关联字典**： -- file_type：文件类型（列表筛选+显示） -- file_status：文件状态（显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `endDate` | `string` | | 结束日期 | 2026-12-31 | -| `fileType` | `string` | | 文件类型 | image | -| `groupKey` | `string` | | 业务分组 | scenic | -| `keyword` | `string` | | 搜索关键词 | 风景 | -| `page` | `integer(int32)` | | 页码 | 1 | -| `pageSize` | `integer(int32)` | | 每页条数 | 20 | -| `startDate` | `string` | | 开始日期 | 2026-01-01 | - -**响应** `统一响应结果«IPage«文件信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `IPage«文件信息»` | | 响应数据 | -|   `current` | `long` | | | -|   `pages` | `long` | | | -|   `records` | `文件信息[]` | | | -|     `createdAt` | `string` | | 创建时间 | -|     `fileHash` | `string` | | 文件MD5哈希 | -|     `fileId` | `string` | | 文件ID | -|     `fileName` | `string` | | 文件名 | -|     `fileSize` | `long` | | 文件大小(字节) | -|     `fileType` | `string` | | 文件类型 | -|     `groupKey` | `string` | | 业务分组 | -|     `mimeType` | `string` | | MIME类型 | -|     `ossUrl` | `string` | | OSS地址 | -|     `previewUrl` | `string` | | 预览地址 | -|     `refCount` | `int` | | 引用次数 | -|     `status` | `string` | | 文件状态 | -|     `thumbnailUrl` | `string` | | 缩略图地址 | -|   `size` | `long` | | | -|   `total` | `long` | | | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/file/stats - -**存储统计** - -返回文件总数、总存储空间、各类型文件占比等统计信息 - -**响应** `统一响应结果«文件统计信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `文件统计信息` | | 响应数据 | -|   `countByGroup` | `object` | | 按分组统计文件数量 | -|   `countByType` | `object` | | 按类型统计文件数量 | -|   `sizeByType` | `object` | | 按类型统计文件大小 | -|   `totalCount` | `long` | | 文件总数 | -|   `totalSize` | `long` | | 文件总大小(字节) | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/file/upload/confirm - -**确认上传完成** - -上传流程第二步：前端直传OSS完成后调用此接口，系统验证文件存在性并创建文件记录。支持MD5去重，相同文件不会重复存储 - -**请求体** `上传确认请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `fileId` | `string` | 是 | 文件ID | - -**响应** `统一响应结果«文件信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `文件信息` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `fileHash` | `string` | | 文件MD5哈希 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `groupKey` | `string` | | 业务分组 | -|   `mimeType` | `string` | | MIME类型 | -|   `ossUrl` | `string` | | OSS地址 | -|   `previewUrl` | `string` | | 预览地址 | -|   `refCount` | `int` | | 引用次数 | -|   `status` | `string` | | 文件状态 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/file/upload/token - -**请求上传凭证** - -上传流程第一步：前端请求上传凭证 → 获取OSS预签名URL和临时凭证 → 前端直传OSS → 调用确认上传接口。凭证有效期有限，过期需重新请求 - -**请求体** `上传令牌请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `fileHash` | `string` | 是 | 文件MD5哈希 | -| `fileName` | `string` | 是 | 文件名 | -| `fileSize` | `long` | 是 | 文件大小(字节) | -| `forcePresigned` | `boolean` | | 强制使用预签名URL（跳过STS分片模式） | -| `groupKey` | `string` | | 业务分组 | - -**响应** `统一响应结果«上传令牌信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `上传令牌信息` | | 响应数据 | -|   `bucket` | `string` | | OSS Bucket名称 | -|   `contentType` | `string` | | 上传时必须使用的Content-Type（与预签名URL签名一致） | -|   `expireAt` | `string` | | 过期时间 | -|   `file` | `文件信息` | | 秒传文件信息 | -|     `createdAt` | `string` | | 创建时间 | -|     `fileHash` | `string` | | 文件MD5哈希 | -|     `fileId` | `string` | | 文件ID | -|     `fileName` | `string` | | 文件名 | -|     `fileSize` | `long` | | 文件大小(字节) | -|     `fileType` | `string` | | 文件类型 | -|     `groupKey` | `string` | | 业务分组 | -|     `mimeType` | `string` | | MIME类型 | -|     `ossUrl` | `string` | | OSS地址 | -|     `previewUrl` | `string` | | 预览地址 | -|     `refCount` | `int` | | 引用次数 | -|     `status` | `string` | | 文件状态 | -|     `thumbnailUrl` | `string` | | 缩略图地址 | -|   `fileId` | `string` | | 文件ID | -|   `ossKey` | `string` | | OSS对象Key | -|   `presignedUrl` | `string` | | 预签名上传URL | -|   `region` | `string` | | OSS Region | -|   `stsToken` | `STS临时凭证信息` | | STS临时凭证 | -|     `accessKeyId` | `string` | | AccessKey ID | -|     `accessKeySecret` | `string` | | AccessKey Secret | -|     `expiration` | `string` | | 过期时间 | -|     `securityToken` | `string` | | 安全令牌 | -|   `uploadMode` | `string` | | 上传模式: PRESIGNED_URL/STS_MULTIPART/INSTANT | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/file/{fileId} - -**文件详情** - -**关联字典**： -- file_type：文件类型（显示） -- file_status：文件状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `fileId` | `integer` | | 文件ID | - -**响应** `统一响应结果«文件信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `文件信息` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `fileHash` | `string` | | 文件MD5哈希 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `groupKey` | `string` | | 业务分组 | -|   `mimeType` | `string` | | MIME类型 | -|   `ossUrl` | `string` | | OSS地址 | -|   `previewUrl` | `string` | | 预览地址 | -|   `refCount` | `int` | | 引用次数 | -|   `status` | `string` | | 文件状态 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/file/{fileId} - -**删除文件** - -软删除文件记录，如果文件存在引用关系则不允许删除。OSS上的物理文件由定时任务清理 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `fileId` | `integer` | | 文件ID | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/file/{fileId}/preview - -**文件内容流式预览** - -流式输出文件内容，设置正确的Content-Type头，支持浏览器直接预览图片和PDF等文件 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `fileId` | `integer` | | 文件ID | - ---- - -### `GET` /admin/file/{fileId}/refs - -**文件引用列表** - -查看文件被哪些业务实体引用（如景区封面、酒店图片等），用于判断文件是否可安全删除 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `fileId` | `integer` | | 文件ID | - -**响应** `统一响应结果«List«文件引用信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `文件引用信息[]` | | 响应数据 | -|   `bizId` | `string` | | 业务ID | -|   `bizType` | `string` | | 业务类型 | -|   `createdAt` | `string` | | 创建时间 | -|   `fileId` | `string` | | 文件ID | -|   `refId` | `string` | | 引用ID | -| `message` | `string` | | 响应消息 | - ---- diff --git a/2026-03/17_0928/hl-guide-service.md b/2026-03/17_0928/hl-guide-service.md deleted file mode 100644 index d01c9cc..0000000 --- a/2026-03/17_0928/hl-guide-service.md +++ /dev/null @@ -1,727 +0,0 @@ -# 攻略服务 API 文档 - -**服务**: `hl-guide-service` -**接口总数**: 21 - -## 目录 - -- **攻略分类管理** (7 个接口) -- **攻略文章管理** (8 个接口) -- **攻略标签管理** (6 个接口) - ---- - -## 攻略分类管理 - -### `POST` /admin/guide/category - -**创建分类** - -创建攻略分类，分类名称不可重复。创建后默认启用，排序值越小越靠前。 - -**权限**：需管理员登录。 - -**请求体** `CategoryCreateRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryName` | `string` | 是 | 分类名称 | -| `coverMaterialId` | `long` | | 封面素材ID | -| `coverUrl` | `string` | | 封面URL | -| `description` | `string` | | 描述 | -| `icon` | `string` | | 图标 | -| `sortOrder` | `int` | | 排序（默认0） | - -**响应** `统一响应结果«攻略分类»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略分类` | | 响应数据 | -|   `articleCount` | `int` | | 文章数量 | -|   `categoryId` | `long` | | 分类ID | -|   `categoryName` | `string` | | 分类名称 | -|   `coverMaterialId` | `long` | | 封面素材ID | -|   `coverUrl` | `string` | | 封面URL | -|   `createdAt` | `string` | | 创建时间 | -|   `description` | `string` | | 描述 | -|   `icon` | `string` | | 图标 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `int` | | 状态：0=禁用，1=启用 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/guide/category/enabled - -**启用的分类列表** - -仅返回状态为启用的分类，创建文章时用于选择分类 - -**响应** `统一响应结果«List«攻略分类»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略分类[]` | | 响应数据 | -|   `articleCount` | `int` | | 文章数量 | -|   `categoryId` | `long` | | 分类ID | -|   `categoryName` | `string` | | 分类名称 | -|   `coverMaterialId` | `long` | | 封面素材ID | -|   `coverUrl` | `string` | | 封面URL | -|   `createdAt` | `string` | | 创建时间 | -|   `description` | `string` | | 描述 | -|   `icon` | `string` | | 图标 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `int` | | 状态：0=禁用，1=启用 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/guide/category/list - -**分类列表** - -返回全部攻略分类（含启用和停用），按排序值升序排列 - -**关联字典**： -- common_status：通用状态（列表显示，ACTIVE=启用/INACTIVE=停用） - -**响应** `统一响应结果«List«攻略分类»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略分类[]` | | 响应数据 | -|   `articleCount` | `int` | | 文章数量 | -|   `categoryId` | `long` | | 分类ID | -|   `categoryName` | `string` | | 分类名称 | -|   `coverMaterialId` | `long` | | 封面素材ID | -|   `coverUrl` | `string` | | 封面URL | -|   `createdAt` | `string` | | 创建时间 | -|   `description` | `string` | | 描述 | -|   `icon` | `string` | | 图标 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `int` | | 状态：0=禁用，1=启用 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/guide/category/{categoryId} - -**更新分类** - -更新攻略分类的名称、图标、描述等信息。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryId` | `integer` | 是 | categoryId | - -**请求体** `CategoryUpdateRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryName` | `string` | | 分类名称 | -| `coverMaterialId` | `long` | | 封面素材ID | -| `coverUrl` | `string` | | 封面URL | -| `description` | `string` | | 描述 | -| `icon` | `string` | | 图标 | -| `sortOrder` | `int` | | 排序 | - -**响应** `统一响应结果«攻略分类»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略分类` | | 响应数据 | -|   `articleCount` | `int` | | 文章数量 | -|   `categoryId` | `long` | | 分类ID | -|   `categoryName` | `string` | | 分类名称 | -|   `coverMaterialId` | `long` | | 封面素材ID | -|   `coverUrl` | `string` | | 封面URL | -|   `createdAt` | `string` | | 创建时间 | -|   `description` | `string` | | 描述 | -|   `icon` | `string` | | 图标 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `int` | | 状态：0=禁用，1=启用 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/guide/category/{categoryId} - -**删除分类** - -删除分类前需确保分类下无文章，否则删除失败 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryId` | `integer` | 是 | categoryId | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/guide/category/{categoryId}/sort - -**更新分类排序** - -更新分类的排序值，排序值越小越靠前。影响小程序端分类导航的展示顺序。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryId` | `integer` | 是 | categoryId | - -**请求体** `CategorySortRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `sortOrder` | `int` | 是 | 排序值 | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/guide/category/{categoryId}/status - -**更新分类状态** - -启用或停用分类。停用后该分类下的文章不会在小程序端展示，但不影响已有文章 - -**关联字典**： -- common_status：通用状态（状态切换，ACTIVE=启用/INACTIVE=停用） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryId` | `integer` | 是 | categoryId | - -**请求体** `StatusRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `status` | `int` | 是 | 状态值 | - -**响应** `统一响应结果«Void»` - ---- - -## 攻略文章管理 - -### `POST` /admin/guide/article - -**创建文章** - -创建攻略文章，需指定分类。创建后默认为草稿状态，需手动发布后小程序端才可见。 - -**权限**：需管理员登录。 - -**关联字典**： -- wiki_status：文章状态（创建后默认DRAFT） - -**请求体** `ArticleCreateRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `authorName` | `string` | | 作者名称 | -| `bannerMaterialIds` | `long[]` | | 轮播图素材ID列表 | -| `categoryId` | `long` | 是 | 分类ID | -| `content` | `string` | | 正文内容 | -| `coverMaterialId` | `long` | | 封面素材ID | -| `coverUrl` | `string` | | 封面URL | -| `resources` | `ArticleResourceItem[]` | | 关联资源列表 | -|   `resourceId` | `long` | 是 | 资源ID | -|   `resourceName` | `string` | 是 | 资源名称 | -|   `resourceType` | `string` | 是 | 资源类型：SCENIC/RESTAURANT/HOTEL/ACTIVITY/PRODUCT | -|   `sortOrder` | `int` | | 排序 | -| `sortOrder` | `int` | | 排序（默认0） | -| `source` | `string` | | 来源 | -| `subtitle` | `string` | | 副标题 | -| `summary` | `string` | | 摘要 | -| `tagIds` | `long[]` | | 标签ID列表 | -| `title` | `string` | 是 | 标题 | - -**响应** `统一响应结果«攻略文章详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略文章详情` | | 响应数据 | -|   `articleId` | `long` | | 文章ID | -|   `authorName` | `string` | | 作者名称 | -|   `bannerMaterialIds` | `long[]` | | 轮播图素材ID列表 | -|   `categoryId` | `long` | | 分类ID | -|   `categoryName` | `string` | | 分类名称 | -|   `content` | `string` | | 正文内容 | -|   `coverMaterialId` | `long` | | 封面素材ID | -|   `coverUrl` | `string` | | 封面URL | -|   `createdAt` | `string` | | 创建时间 | -|   `favoriteCount` | `int` | | 收藏数 | -|   `isRecommend` | `int` | | 是否推荐：0=否，1=是 | -|   `isTop` | `int` | | 是否置顶：0=否，1=是 | -|   `likeCount` | `int` | | 点赞数 | -|   `publishTime` | `string` | | 发布时间 | -|   `resources` | `文章关联资源[]` | | 关联资源列表 | -|     `resourceId` | `long` | | 资源ID | -|     `resourceName` | `string` | | 资源名称 | -|     `resourceType` | `string` | | 资源类型：SCENIC/RESTAURANT/HOTEL/ACTIVITY/PRODUCT | -|     `sortOrder` | `int` | | 排序 | -|   `sortOrder` | `int` | | 排序 | -|   `source` | `string` | | 来源 | -|   `status` | `int` | | 状态：0=草稿，1=已发布，2=已下架 | -|   `subtitle` | `string` | | 副标题 | -|   `summary` | `string` | | 摘要 | -|   `tags` | `攻略标签[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `long` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `tagType` | `int` | | 标签类型：0=系统管理，1=自定义 | -|     `useCount` | `int` | | 使用次数 | -|   `title` | `string` | | 标题 | -|   `updatedAt` | `string` | | 更新时间 | -|   `viewCount` | `int` | | 浏览量 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/guide/article/list - -**文章列表** - -分页查询攻略文章，支持按分类、状态、关键词筛选 - -**关联字典**： -- wiki_status：文章状态（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `categoryId` | `integer(int64)` | | 分类ID | | -| `isRecommend` | `integer(int32)` | | 是否推荐：0=否，1=是 | | -| `isTop` | `integer(int32)` | | 是否置顶：0=否，1=是 | | -| `keyword` | `string` | | 关键词（搜索标题/摘要） | | -| `orderBy` | `string` | | 排序字段：sortOrder/publishTime/viewCount/createdAt（默认createdAt） | | -| `orderDir` | `string` | | 排序方向：asc/desc（默认desc） | | -| `page` | `integer(int32)` | | 页码（默认1） | | -| `pageSize` | `integer(int32)` | | 每页数量（默认20，最大100） | | -| `status` | `integer(int32)` | | 状态：0=草稿，1=已发布，2=已下架 | | - -**响应** `统一响应结果«分页结果«攻略文章列表项»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«攻略文章列表项»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `攻略文章列表项[]` | | 数据列表 | -|     `articleId` | `long` | | 文章ID | -|     `categoryId` | `long` | | 分类ID | -|     `categoryName` | `string` | | 分类名称 | -|     `coverUrl` | `string` | | 封面URL | -|     `createdAt` | `string` | | 创建时间 | -|     `isRecommend` | `int` | | 是否推荐：0=否，1=是 | -|     `isTop` | `int` | | 是否置顶：0=否，1=是 | -|     `publishTime` | `string` | | 发布时间 | -|     `sortOrder` | `int` | | 排序 | -|     `status` | `int` | | 状态：0=草稿，1=已发布，2=已下架 | -|     `summary` | `string` | | 摘要 | -|     `tags` | `攻略标签[]` | | 标签列表 | -|     `title` | `string` | | 标题 | -|     `viewCount` | `int` | | 浏览量 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/guide/article/{articleId} - -**文章详情** - -**关联字典**： -- wiki_status：文章状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | 是 | articleId | - -**响应** `统一响应结果«攻略文章详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略文章详情` | | 响应数据 | -|   `articleId` | `long` | | 文章ID | -|   `authorName` | `string` | | 作者名称 | -|   `bannerMaterialIds` | `long[]` | | 轮播图素材ID列表 | -|   `categoryId` | `long` | | 分类ID | -|   `categoryName` | `string` | | 分类名称 | -|   `content` | `string` | | 正文内容 | -|   `coverMaterialId` | `long` | | 封面素材ID | -|   `coverUrl` | `string` | | 封面URL | -|   `createdAt` | `string` | | 创建时间 | -|   `favoriteCount` | `int` | | 收藏数 | -|   `isRecommend` | `int` | | 是否推荐：0=否，1=是 | -|   `isTop` | `int` | | 是否置顶：0=否，1=是 | -|   `likeCount` | `int` | | 点赞数 | -|   `publishTime` | `string` | | 发布时间 | -|   `resources` | `文章关联资源[]` | | 关联资源列表 | -|     `resourceId` | `long` | | 资源ID | -|     `resourceName` | `string` | | 资源名称 | -|     `resourceType` | `string` | | 资源类型：SCENIC/RESTAURANT/HOTEL/ACTIVITY/PRODUCT | -|     `sortOrder` | `int` | | 排序 | -|   `sortOrder` | `int` | | 排序 | -|   `source` | `string` | | 来源 | -|   `status` | `int` | | 状态：0=草稿，1=已发布，2=已下架 | -|   `subtitle` | `string` | | 副标题 | -|   `summary` | `string` | | 摘要 | -|   `tags` | `攻略标签[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `long` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `tagType` | `int` | | 标签类型：0=系统管理，1=自定义 | -|     `useCount` | `int` | | 使用次数 | -|   `title` | `string` | | 标题 | -|   `updatedAt` | `string` | | 更新时间 | -|   `viewCount` | `int` | | 浏览量 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/guide/article/{articleId} - -**更新文章** - -更新攻略文章的标题、内容、封面图、分类等信息。已发布的文章更新后立即生效。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | 是 | articleId | - -**请求体** `ArticleUpdateRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `authorName` | `string` | | 作者名称 | -| `bannerMaterialIds` | `long[]` | | 轮播图素材ID列表 | -| `categoryId` | `long` | | 分类ID | -| `content` | `string` | | 正文内容 | -| `coverMaterialId` | `long` | | 封面素材ID | -| `coverUrl` | `string` | | 封面URL | -| `resources` | `ArticleResourceItem[]` | | 关联资源列表 | -|   `resourceId` | `long` | 是 | 资源ID | -|   `resourceName` | `string` | 是 | 资源名称 | -|   `resourceType` | `string` | 是 | 资源类型：SCENIC/RESTAURANT/HOTEL/ACTIVITY/PRODUCT | -|   `sortOrder` | `int` | | 排序 | -| `sortOrder` | `int` | | 排序 | -| `source` | `string` | | 来源 | -| `subtitle` | `string` | | 副标题 | -| `summary` | `string` | | 摘要 | -| `tagIds` | `long[]` | | 标签ID列表 | -| `title` | `string` | | 标题 | - -**响应** `统一响应结果«攻略文章详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略文章详情` | | 响应数据 | -|   `articleId` | `long` | | 文章ID | -|   `authorName` | `string` | | 作者名称 | -|   `bannerMaterialIds` | `long[]` | | 轮播图素材ID列表 | -|   `categoryId` | `long` | | 分类ID | -|   `categoryName` | `string` | | 分类名称 | -|   `content` | `string` | | 正文内容 | -|   `coverMaterialId` | `long` | | 封面素材ID | -|   `coverUrl` | `string` | | 封面URL | -|   `createdAt` | `string` | | 创建时间 | -|   `favoriteCount` | `int` | | 收藏数 | -|   `isRecommend` | `int` | | 是否推荐：0=否，1=是 | -|   `isTop` | `int` | | 是否置顶：0=否，1=是 | -|   `likeCount` | `int` | | 点赞数 | -|   `publishTime` | `string` | | 发布时间 | -|   `resources` | `文章关联资源[]` | | 关联资源列表 | -|     `resourceId` | `long` | | 资源ID | -|     `resourceName` | `string` | | 资源名称 | -|     `resourceType` | `string` | | 资源类型：SCENIC/RESTAURANT/HOTEL/ACTIVITY/PRODUCT | -|     `sortOrder` | `int` | | 排序 | -|   `sortOrder` | `int` | | 排序 | -|   `source` | `string` | | 来源 | -|   `status` | `int` | | 状态：0=草稿，1=已发布，2=已下架 | -|   `subtitle` | `string` | | 副标题 | -|   `summary` | `string` | | 摘要 | -|   `tags` | `攻略标签[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `long` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `tagType` | `int` | | 标签类型：0=系统管理，1=自定义 | -|     `useCount` | `int` | | 使用次数 | -|   `title` | `string` | | 标题 | -|   `updatedAt` | `string` | | 更新时间 | -|   `viewCount` | `int` | | 浏览量 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/guide/article/{articleId} - -**删除文章** - -软删除攻略文章，同时清除文章的标签关联。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | 是 | articleId | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/guide/article/{articleId}/recommend - -**设置推荐** - -设置/取消文章推荐。推荐文章会在小程序首页和推荐列表中优先展示 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | 是 | articleId | - -**请求体** `RecommendRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `isRecommend` | `int` | 是 | 是否推荐：0=否，1=是 | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/guide/article/{articleId}/status - -**发布/下架** - -切换文章发布状态。发布后小程序端可见，下架后小程序端不再展示但管理端仍可查看 - -**关联字典**： -- wiki_status：文章状态（状态切换） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | 是 | articleId | - -**请求体** `StatusRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `status` | `int` | 是 | 状态值 | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/guide/article/{articleId}/top - -**设置置顶** - -设置/取消文章置顶。置顶文章在分类列表中始终排在最前面 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | 是 | articleId | - -**请求体** `TopRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `isTop` | `int` | 是 | 是否置顶：0=否，1=是 | - -**响应** `统一响应结果«Void»` - ---- - -## 攻略标签管理 - -### `POST` /admin/guide/tag - -**创建标签** - -创建攻略系统标签，标签名称不可重复。创建后可用于文章分类和筛选。 - -**权限**：需管理员登录。 - -**请求体** `TagCreateRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagColor` | `string` | | 标签颜色（十六进制） | -| `tagName` | `string` | 是 | 标签名称 | -| `tagType` | `int` | | 标签类型：0=系统管理，1=自定义（默认0） | - -**响应** `统一响应结果«攻略标签»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略标签` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `long` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `tagType` | `int` | | 标签类型：0=系统管理，1=自定义 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/guide/tag/all - -**所有标签列表** - -返回全部标签（含系统标签和用户自定义标签），用于文章编辑时的标签选择器 - -**响应** `统一响应结果«List«攻略标签»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略标签[]` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `long` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `tagType` | `int` | | 标签类型：0=系统管理，1=自定义 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/guide/tag/article/{articleId} - -**更新文章标签** - -全量替换文章的标签关联，传入新的标签ID列表（空数组表示清除所有标签） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | 是 | articleId | - -**请求体** `ArticleTagUpdateRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagIds` | `long[]` | 是 | 标签ID列表 | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/guide/tag/managed - -**系统标签列表** - -返回管理员创建的系统标签（不含用户自定义标签），用于标签管理页 - -**响应** `统一响应结果«List«攻略标签»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略标签[]` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `long` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `tagType` | `int` | | 标签类型：0=系统管理，1=自定义 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/guide/tag/{tagId} - -**更新标签** - -更新标签名称。标签名称不可与其他已有标签重复。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagId` | `integer` | 是 | tagId | - -**请求体** `TagUpdateRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagColor` | `string` | | 标签颜色（十六进制） | -| `tagName` | `string` | | 标签名称 | - -**响应** `统一响应结果«攻略标签»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略标签` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `long` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `tagType` | `int` | | 标签类型：0=系统管理，1=自定义 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/guide/tag/{tagId} - -**删除标签** - -删除标签并自动解除与所有文章的关联关系。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagId` | `integer` | 是 | tagId | - -**响应** `统一响应结果«Void»` - ---- diff --git a/2026-03/17_0928/hl-material-service.md b/2026-03/17_0928/hl-material-service.md deleted file mode 100644 index c8ed7fb..0000000 --- a/2026-03/17_0928/hl-material-service.md +++ /dev/null @@ -1,968 +0,0 @@ -# 素材服务 API 文档 - -**服务**: `hl-material-service` -**接口总数**: 28 - -## 目录 - -- **小程序-素材** (1 个接口) -- **素材分类权限管理** (2 个接口) -- **素材标签管理** (6 个接口) -- **素材管理** (19 个接口) - ---- - -## 小程序-素材 - -### `GET` /mp/material/miniprogram - -**获取小程序分类下的全部素材** - -返回miniprogram分类下的所有素材，用于小程序端展示公共素材资源（如引导页图片、默认头像等） - -**响应** `统一响应结果«List«素材信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材信息[]` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `categoryPath` | `string` | | 完整分类路径（如：攻略管理 / 999 / 888） | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `string` | | 创建人ID | -|   `createdByName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 素材描述 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `imageHeight` | `int` | | 图片高度 | -|   `imageWidth` | `int` | | 图片宽度 | -|   `materialId` | `string` | | 素材ID | -|   `materialName` | `string` | | 素材名称 | -|   `ossUrl` | `string` | | OSS地址 | -|   `refCount` | `int` | | 引用次数 | -|   `subCategoryId` | `string` | | 子分类ID | -|   `subCategoryName` | `string` | | 子分类名称 | -|   `tags` | `素材标签信息[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdByName` | `string` | | 创建人姓名 | -|     `managed` | `boolean` | | 是否系统管理标签 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `string` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `useCount` | `int` | | 使用次数 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -## 素材分类权限管理 - -### `GET` /admin/material/category/permissions/{roleCode} - -**获取角色的分类权限** - -仅超级管理员可操作。返回指定角色可访问的素材分类编码列表 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `roleCode` | `string` | | 角色编码 | - -**响应** `统一响应结果«List«string»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `string[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/material/category/permissions/{roleCode} - -**更新角色的分类权限** - -仅超级管理员可操作。全量替换指定角色的素材分类访问权限，传入允许访问的分类编码列表 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `roleCode` | `string` | | 角色编码 | - -**请求体** `分类权限更新请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryCodes` | `string[]` | 是 | 分类编码列表 | - -**响应** `统一响应结果«Void»` - ---- - -## 素材标签管理 - -### `POST` /admin/material/tag - -**创建管理标签** - -创建系统级素材标签，标签名称不可重复。创建后可用于素材分类和筛选。 - -**权限**：需管理员登录。 - -**请求体** `创建标签请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagColor` | `string` | | 标签颜色 | -| `tagName` | `string` | 是 | 标签名称 | - -**响应** `统一响应结果«素材标签信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材标签信息` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdByName` | `string` | | 创建人姓名 | -|   `managed` | `boolean` | | 是否系统管理标签 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `string` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/tag/adhoc - -**解析自定义标签（按名称查找或创建）** - -按标签名称查找已有标签，不存在则自动创建为用户自定义标签。用于素材上传时输入自由标签文本的场景。 - -**权限**：需管理员登录。 - -**请求体** `创建标签请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagColor` | `string` | | 标签颜色 | -| `tagName` | `string` | 是 | 标签名称 | - -**响应** `统一响应结果«素材标签信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材标签信息` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdByName` | `string` | | 创建人姓名 | -|   `managed` | `boolean` | | 是否系统管理标签 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `string` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/material/tag/{tagId} - -**编辑标签** - -更新标签名称。标签名称不可与其他已有标签重复。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagId` | `integer` | | 标签ID | - -**请求体** `更新标签请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagColor` | `string` | | 标签颜色 | -| `tagName` | `string` | | 标签名称 | - -**响应** `统一响应结果«素材标签信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材标签信息` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdByName` | `string` | | 创建人姓名 | -|   `managed` | `boolean` | | 是否系统管理标签 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `string` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/material/tag/{tagId} - -**删除标签** - -删除标签并自动解除与所有素材的关联关系。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagId` | `integer` | | 标签ID | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/material/tags - -**获取管理标签（标签管理用）** - -返回管理员创建的系统标签列表（不含用户自定义标签），用于标签管理页的CRUD操作。 - -**响应** `统一响应结果«List«素材标签信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材标签信息[]` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdByName` | `string` | | 创建人姓名 | -|   `managed` | `boolean` | | 是否系统管理标签 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `string` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/material/tags/all - -**获取全部标签（选择器用，含自定义标签）** - -返回所有标签（含系统标签和用户自定义标签），用于素材上传/编辑时的标签选择器。 - -**响应** `统一响应结果«List«素材标签信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材标签信息[]` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdByName` | `string` | | 创建人姓名 | -|   `managed` | `boolean` | | 是否系统管理标签 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `string` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -## 素材管理 - -### `DELETE` /admin/material/batch - -**批量删除素材** - -批量删除素材，返回删除结果（成功数/失败数/失败原因）。有引用关系的素材会跳过并记录失败原因 - -**请求体** `批量删除素材请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `materialIds` | `string[]` | 是 | 素材ID列表 | - -**响应** `统一响应结果«批量删除结果»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `批量删除结果` | | 响应数据 | -|   `failedItems` | `删除失败项[]` | | 失败项列表 | -|     `materialId` | `string` | | 素材ID | -|     `reason` | `string` | | 失败原因 | -|   `successCount` | `int` | | 成功删除数量 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/material/batch/tags - -**批量更新标签** - -对多个素材同时添加和/或移除标签，支持增量操作（addTagIds新增，removeTagIds移除） - -**请求体** `批量标签操作请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `addTagIds` | `string[]` | | 要添加的标签ID列表 | -| `materialIds` | `string[]` | 是 | 素材ID列表 | -| `removeTagIds` | `string[]` | | 要移除的标签ID列表 | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/material/categories - -**获取有权限的分类列表（含素材数量）** - -返回当前角色有权限查看的素材分类树，每个分类包含素材数量统计。超级管理员可见全部分类 - -**响应** `统一响应结果«List«素材分类信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材分类信息[]` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `children` | `素材分类信息[]` | | 子分类列表 | -|     `categoryCode` | `string` | | 分类编码 | -|     `categoryName` | `string` | | 分类名称 | -|     `children` | `素材分类信息[]` | | 子分类列表 | -|     `materialCount` | `int` | | 素材数量 | -|     `parentId` | `string` | | 父子分类ID | -|     `subCategoryId` | `string` | | 子分类ID | -|   `materialCount` | `int` | | 素材数量 | -|   `parentId` | `string` | | 父子分类ID | -|   `subCategoryId` | `string` | | 子分类ID | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/category/sub - -**创建子分类** - -在一级分类下创建子分类，分类编码自动生成。子分类用于更细粒度的素材归档 - -**请求体** `Create subcategory request` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryName` | `string` | 是 | 子分类名称 | -| `parentCode` | `string` | 是 | 根分类编码(scenic/hotel等) | -| `parentId` | `long` | | 父子分类ID(为空则创建在根分类下) | -| `sortOrder` | `int` | | 排序值 | - -**响应** `统一响应结果«素材分类信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材分类信息` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `children` | `素材分类信息[]` | | 子分类列表 | -|     `categoryCode` | `string` | | 分类编码 | -|     `categoryName` | `string` | | 分类名称 | -|     `children` | `素材分类信息[]` | | 子分类列表 | -|     `materialCount` | `int` | | 素材数量 | -|     `parentId` | `string` | | 父子分类ID | -|     `subCategoryId` | `string` | | 子分类ID | -|   `materialCount` | `int` | | 素材数量 | -|   `parentId` | `string` | | 父子分类ID | -|   `subCategoryId` | `string` | | 子分类ID | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/material/category/sub/{categoryId} - -**更新子分类** - -更新子分类的名称或排序值。仅有该分类权限的管理员可操作。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryId` | `integer` | | 子分类ID | - -**请求体** `Update subcategory request` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryName` | `string` | | Subcategory name | -| `sortOrder` | `int` | | Sort order | - -**响应** `统一响应结果«素材分类信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材分类信息` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `children` | `素材分类信息[]` | | 子分类列表 | -|     `categoryCode` | `string` | | 分类编码 | -|     `categoryName` | `string` | | 分类名称 | -|     `children` | `素材分类信息[]` | | 子分类列表 | -|     `materialCount` | `int` | | 素材数量 | -|     `parentId` | `string` | | 父子分类ID | -|     `subCategoryId` | `string` | | 子分类ID | -|   `materialCount` | `int` | | 素材数量 | -|   `parentId` | `string` | | 父子分类ID | -|   `subCategoryId` | `string` | | 子分类ID | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/material/category/sub/{categoryId} - -**删除子分类** - -删除子分类前需确保分类下无素材，否则删除失败 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryId` | `integer` | | 子分类ID | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/material/list - -**素材列表** - -分页查询素材，支持按分类、标签、文件类型、关键词筛选。返回结果受角色分类权限限制 - -**关联字典**： -- file_type：文件类型（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `categoryCode` | `string` | | 分类编码 | scenic | -| `createdBy` | `integer(int64)` | | 创建人ID | 1001 | -| `endDate` | `string` | | 结束日期 | 2026-12-31 | -| `fileType` | `string` | | 文件类型 | image | -| `keyword` | `string` | | 搜索关键词 | 风景 | -| `orderBy` | `string` | | 排序字段 | createdAt | -| `orderDir` | `string` | | 排序方向: asc/desc | desc | -| `page` | `integer(int32)` | | 页码 | 1 | -| `pageSize` | `integer(int32)` | | 每页条数 | 20 | -| `startDate` | `string` | | 开始日期 | 2026-01-01 | -| `subCategoryId` | `integer(int64)` | | 子分类ID | 2030000000000001 | -| `tagIds` | `string` | | 标签ID列表(逗号分隔) | 1,2,3 | - -**响应** `统一响应结果«分页结果«素材信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«素材信息»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `素材信息[]` | | 数据列表 | -|     `categoryCode` | `string` | | 分类编码 | -|     `categoryName` | `string` | | 分类名称 | -|     `categoryPath` | `string` | | 完整分类路径（如：攻略管理 / 999 / 888） | -|     `createdAt` | `string` | | 创建时间 | -|     `createdBy` | `string` | | 创建人ID | -|     `createdByName` | `string` | | 创建人姓名 | -|     `description` | `string` | | 素材描述 | -|     `fileId` | `string` | | 文件ID | -|     `fileName` | `string` | | 文件名 | -|     `fileSize` | `long` | | 文件大小(字节) | -|     `fileType` | `string` | | 文件类型 | -|     `imageHeight` | `int` | | 图片高度 | -|     `imageWidth` | `int` | | 图片宽度 | -|     `materialId` | `string` | | 素材ID | -|     `materialName` | `string` | | 素材名称 | -|     `ossUrl` | `string` | | OSS地址 | -|     `refCount` | `int` | | 引用次数 | -|     `subCategoryId` | `string` | | 子分类ID | -|     `subCategoryName` | `string` | | 子分类名称 | -|     `tags` | `素材标签信息[]` | | 标签列表 | -|     `thumbnailUrl` | `string` | | 缩略图地址 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/upload/chunk - -**分片上传-上传分片** - -大文件上传第二步：逐个上传分片数据，分片索引从0开始。支持断点续传，已上传的分片无需重传。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `chunkIndex` | `integer(int32)` | | 分片索引（从0开始） | | -| `uploadId` | `string` | | 上传ID | | - -**响应** `统一响应结果«分片上传结果»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分片上传结果` | | 响应数据 | -|   `etag` | `string` | | 分片ETag | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/upload/chunk/cancel - -**分片上传-取消** - -取消分片上传任务，清理已上传的分片数据和OSS临时文件。仅上传发起者可取消。 - -**请求体** `分片上传取消请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `uploadId` | `string` | 是 | 上传ID | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /admin/material/upload/chunk/complete - -**分片上传-完成合并** - -大文件上传第三步：所有分片上传完成后调用，OSS端合并分片为完整文件并创建素材记录。 - -**请求体** `分片上传完成请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `uploadId` | `string` | 是 | 上传ID | - -**响应** `统一响应结果«素材信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材信息` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `categoryPath` | `string` | | 完整分类路径（如：攻略管理 / 999 / 888） | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `string` | | 创建人ID | -|   `createdByName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 素材描述 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `imageHeight` | `int` | | 图片高度 | -|   `imageWidth` | `int` | | 图片宽度 | -|   `materialId` | `string` | | 素材ID | -|   `materialName` | `string` | | 素材名称 | -|   `ossUrl` | `string` | | OSS地址 | -|   `refCount` | `int` | | 引用次数 | -|   `subCategoryId` | `string` | | 子分类ID | -|   `subCategoryName` | `string` | | 子分类名称 | -|   `tags` | `素材标签信息[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdByName` | `string` | | 创建人姓名 | -|     `managed` | `boolean` | | 是否系统管理标签 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `string` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `useCount` | `int` | | 使用次数 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/upload/chunk/init - -**分片上传-初始化** - -大文件上传第一步：初始化分片上传任务，返回uploadId和每个分片的预签名URL。前端按分片并发上传后调用完成合并接口。 - -**权限**：需管理员登录，受角色分类权限限制。 - -**请求体** `分片上传初始化请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `contentType` | `string` | 是 | 文件MIME类型 | -| `fileSize` | `long` | 是 | 文件大小（字节） | -| `filename` | `string` | 是 | 文件名 | -| `materialId` | `string` | | 关联素材ID（可选，用于更新已有素材） | - -**响应** `统一响应结果«分片上传初始化结果»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分片上传初始化结果` | | 响应数据 | -|   `chunkSize` | `int` | | 推荐分片大小（字节） | -|   `uploadId` | `string` | | 上传ID | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/upload/confirm - -**确认上传完成** - -上传素材第二步：前端直传OSS完成后调用此接口创建素材记录，支持MD5去重 - -**关联字典**： -- material_tag：素材标签（上传时可选标签） - -**请求体** `素材上传确认请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `description` | `string` | | 素材描述 | -| `materialId` | `string` | 是 | 素材ID | -| `tagIds` | `string[]` | | 标签ID列表 | - -**响应** `统一响应结果«素材信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材信息` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `categoryPath` | `string` | | 完整分类路径（如：攻略管理 / 999 / 888） | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `string` | | 创建人ID | -|   `createdByName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 素材描述 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `imageHeight` | `int` | | 图片高度 | -|   `imageWidth` | `int` | | 图片宽度 | -|   `materialId` | `string` | | 素材ID | -|   `materialName` | `string` | | 素材名称 | -|   `ossUrl` | `string` | | OSS地址 | -|   `refCount` | `int` | | 引用次数 | -|   `subCategoryId` | `string` | | 子分类ID | -|   `subCategoryName` | `string` | | 子分类名称 | -|   `tags` | `素材标签信息[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdByName` | `string` | | 创建人姓名 | -|     `managed` | `boolean` | | 是否系统管理标签 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `string` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `useCount` | `int` | | 使用次数 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/upload/folder - -**文件夹上传初始化（创建分类+批量获取凭证）** - -支持整个文件夹上传：自动根据文件夹名创建子分类，为每个文件批量获取上传凭证，前端逐一上传后批量确认 - -**请求体** `文件夹上传初始化请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryCode` | `string` | 是 | 分类编码 | -| `files` | `文件夹上传文件项[]` | 是 | 文件列表 | -|   `contentType` | `string` | 是 | 文件MIME类型 | -|   `fileSize` | `long` | 是 | 文件大小(字节) | -|   `filename` | `string` | 是 | 文件名 | -|   `folderPath` | `string` | 是 | 文件所在文件夹路径（与folderPaths中的路径对应） | -|   `materialName` | `string` | | 素材名称 | -|   `md5` | `string` | 是 | 文件MD5 | -| `folderPaths` | `string[]` | 是 | 文件夹路径列表（如 ["999", "999/888"]） | - -**响应** `统一响应结果«文件夹上传初始化结果»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `文件夹上传初始化结果` | | 响应数据 | -|   `fileTokens` | `文件上传凭证项[]` | | 各文件的上传凭证列表 | -|     `bucket` | `string` | | OSS Bucket名称 | -|     `error` | `string` | | 错误信息（该文件获取凭证失败时） | -|     `filename` | `string` | | 文件名 | -|     `folderPath` | `string` | | 文件夹路径 | -|     `instantUpload` | `boolean` | | 是否秒传（文件已存在） | -|     `materialId` | `string` | | 素材ID | -|     `ossKey` | `string` | | OSS对象Key | -|     `region` | `string` | | OSS Region | -|     `stsToken` | `STS临时凭证信息` | | STS临时凭证 | -|     `uploadHeaders` | `object` | | 上传请求头 | -|     `uploadMethod` | `string` | | 上传方式: PUT/POST | -|     `uploadUrl` | `string` | | 上传URL | -|   `folderCategoryMap` | `object` | | 文件夹路径 → 子分类ID 映射 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/upload/token - -**获取上传凭证** - -上传素材第一步：获取OSS预签名URL和凭证。前端使用凭证直传OSS后调用确认上传。支持基于角色的分类权限校验 - -**请求体** `素材上传令牌请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryCode` | `string` | 是 | 分类编码 | -| `contentType` | `string` | 是 | 文件MIME类型 | -| `fileSize` | `long` | 是 | 文件大小(字节) | -| `filename` | `string` | 是 | 文件名 | -| `materialName` | `string` | | 素材名称 | -| `md5` | `string` | 是 | 文件MD5 | -| `subCategoryId` | `long` | | 子分类ID（文件夹上传时使用） | - -**响应** `统一响应结果«素材上传令牌信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材上传令牌信息` | | 响应数据 | -|   `bucket` | `string` | | OSS Bucket名称 | -|   `contentType` | `string` | | 上传时必须使用的Content-Type（与预签名URL签名一致） | -|   `expireAt` | `string` | | 过期时间 | -|   `fileId` | `string` | | 文件ID | -|   `instantUpload` | `boolean` | | 是否秒传 | -|   `material` | `素材信息` | | 秒传时返回的素材信息 | -|     `categoryCode` | `string` | | 分类编码 | -|     `categoryName` | `string` | | 分类名称 | -|     `categoryPath` | `string` | | 完整分类路径（如：攻略管理 / 999 / 888） | -|     `createdAt` | `string` | | 创建时间 | -|     `createdBy` | `string` | | 创建人ID | -|     `createdByName` | `string` | | 创建人姓名 | -|     `description` | `string` | | 素材描述 | -|     `fileId` | `string` | | 文件ID | -|     `fileName` | `string` | | 文件名 | -|     `fileSize` | `long` | | 文件大小(字节) | -|     `fileType` | `string` | | 文件类型 | -|     `imageHeight` | `int` | | 图片高度 | -|     `imageWidth` | `int` | | 图片宽度 | -|     `materialId` | `string` | | 素材ID | -|     `materialName` | `string` | | 素材名称 | -|     `ossUrl` | `string` | | OSS地址 | -|     `refCount` | `int` | | 引用次数 | -|     `subCategoryId` | `string` | | 子分类ID | -|     `subCategoryName` | `string` | | 子分类名称 | -|     `tags` | `素材标签信息[]` | | 标签列表 | -|     `thumbnailUrl` | `string` | | 缩略图地址 | -|   `materialId` | `string` | | 素材ID | -|   `ossKey` | `string` | | OSS对象Key | -|   `region` | `string` | | OSS Region | -|   `stsToken` | `STS临时凭证信息` | | STS临时凭证 | -|     `accessKeyId` | `string` | | AccessKey ID | -|     `accessKeySecret` | `string` | | AccessKey Secret | -|     `expiration` | `string` | | 过期时间 | -|     `securityToken` | `string` | | 安全令牌 | -|   `uploadMode` | `string` | | 上传模式: PRESIGNED_URL/STS_MULTIPART | -|   `uploadUrl` | `string` | | 上传URL | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/material/{materialId} - -**素材详情** - -返回素材完整信息，包含文件名、URL、分类、标签、文件大小、上传者等。受角色分类权限限制。 - -**关联字典**： -- file_type：文件类型（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `materialId` | `integer` | | 素材ID | - -**响应** `统一响应结果«素材信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材信息` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `categoryPath` | `string` | | 完整分类路径（如：攻略管理 / 999 / 888） | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `string` | | 创建人ID | -|   `createdByName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 素材描述 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `imageHeight` | `int` | | 图片高度 | -|   `imageWidth` | `int` | | 图片宽度 | -|   `materialId` | `string` | | 素材ID | -|   `materialName` | `string` | | 素材名称 | -|   `ossUrl` | `string` | | OSS地址 | -|   `refCount` | `int` | | 引用次数 | -|   `subCategoryId` | `string` | | 子分类ID | -|   `subCategoryName` | `string` | | 子分类名称 | -|   `tags` | `素材标签信息[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdByName` | `string` | | 创建人姓名 | -|     `managed` | `boolean` | | 是否系统管理标签 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `string` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `useCount` | `int` | | 使用次数 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/material/{materialId} - -**更新素材信息** - -**关联字典**： -- material_tag：素材标签（编辑时选择标签） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `materialId` | `integer` | | 素材ID | - -**请求体** `更新素材请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryCode` | `string` | | 分类编码 | -| `description` | `string` | | 素材描述 | -| `materialName` | `string` | | 素材名称 | -| `subCategoryId` | `long` | | 子分类ID（0表示清除子分类） | - -**响应** `统一响应结果«素材信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材信息` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `categoryPath` | `string` | | 完整分类路径（如：攻略管理 / 999 / 888） | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `string` | | 创建人ID | -|   `createdByName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 素材描述 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `imageHeight` | `int` | | 图片高度 | -|   `imageWidth` | `int` | | 图片宽度 | -|   `materialId` | `string` | | 素材ID | -|   `materialName` | `string` | | 素材名称 | -|   `ossUrl` | `string` | | OSS地址 | -|   `refCount` | `int` | | 引用次数 | -|   `subCategoryId` | `string` | | 子分类ID | -|   `subCategoryName` | `string` | | 子分类名称 | -|   `tags` | `素材标签信息[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdByName` | `string` | | 创建人姓名 | -|     `managed` | `boolean` | | 是否系统管理标签 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `string` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `useCount` | `int` | | 使用次数 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/material/{materialId} - -**删除素材** - -删除素材记录。如果素材存在引用关系（被景区、酒店等使用），则不允许删除 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `materialId` | `integer` | | 素材ID | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/material/{materialId}/refs - -**查看素材引用记录** - -查看素材被哪些业务实体引用（如景区封面、酒店轮播图等），用于判断素材是否可安全删除 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `materialId` | `integer` | | 素材ID | - -**响应** `统一响应结果«List«素材引用信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材引用信息[]` | | 响应数据 | -|   `bizId` | `string` | | 业务ID | -|   `bizName` | `string` | | 业务名称 | -|   `bizType` | `string` | | 业务类型 | -|   `bizTypeName` | `string` | | 业务类型名称 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdByName` | `string` | | 创建人姓名 | -|   `id` | `string` | | 引用ID | -|   `materialId` | `string` | | 素材ID | -|   `usageType` | `string` | | 用途类型 | -|   `usageTypeName` | `string` | | 用途类型名称 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/material/{materialId}/tags - -**更新素材标签** - -全量替换单个素材的标签，传入新的标签ID列表 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `materialId` | `integer` | | 素材ID | - -**请求体** `更新素材标签请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagIds` | `string[]` | 是 | 标签ID列表 | - -**响应** `统一响应结果«Void»` - ---- diff --git a/2026-03/17_0928/hl-monitor-service.md b/2026-03/17_0928/hl-monitor-service.md deleted file mode 100644 index 188a26a..0000000 --- a/2026-03/17_0928/hl-monitor-service.md +++ /dev/null @@ -1,553 +0,0 @@ -# 监控服务 API 文档 - -**服务**: `hl-monitor-service` -**接口总数**: 18 - -## 目录 - -- **MySQL监控** (3 个接口) -- **Redis监控** (1 个接口) -- **RocketMQ监控** (3 个接口) -- **企微审批日志** (2 个接口) -- **操作日志** (2 个接口) -- **数据清理** (1 个接口) -- **服务监控** (1 个接口) -- **消息通知日志** (2 个接口) -- **登录日志** (1 个接口) -- **错误日志** (2 个接口) - ---- - -## MySQL监控 - -### `GET` /admin/monitor/mysql - -**MySQL实时监控数据** - -返回MySQL实时状态：连接数、QPS、缓冲池命中率、线程状态、慢查询计数等核心指标 - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/mysql/slow-queries - -**慢SQL查询统计** - -仅超级管理员可操作。查询慢SQL统计信息，返回执行时间最长的SQL语句及其执行次数、平均耗时等 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `limit` | `integer(int32)` | | 返回条数 | | -| `type` | `string` | | 查询类型 | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/mysql/tables - -**表空间列表** - -查询各数据库表的空间占用情况，包含数据大小、索引大小、行数等信息。可指定schema筛选，仅允许查询hl_前缀的数据库 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `schema` | `string` | | 数据库名 | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## Redis监控 - -### `GET` /admin/monitor/redis - -**Redis实时监控数据** - -返回Redis实时状态：内存使用量、连接数、Key数量、命中率、每秒命令数等核心指标 - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## RocketMQ监控 - -### `GET` /admin/monitor/rocketmq - -**RocketMQ概览** - -返回RocketMQ集群状态：Broker状态、Topic数量、消息积压量、生产者/消费者连接数等核心指标 - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/rocketmq/consumer-groups - -**消费者组统计** - -返回各消费者组的消费进度、积压量和在线消费者实例信息 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/rocketmq/topics - -**Topic统计** - -返回各Topic的消息量、最新偏移量和消费进度等信息 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## 企微审批日志 - -### `GET` /admin/monitor/approval-logs - -**审批日志分页查询** - -查询企微OA审批流程记录，支持按审批状态(1-审批中/2-已通过/3-已驳回/4-已撤销)、申请人、模板名称筛选 - -**关联字典**： -- approval_sp_status：审批状态（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `applyUserName` | `string` | | 申请人姓名 | | -| `endTime` | `string` | | 结束时间 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `spName` | `string` | | 审批模板名称 | | -| `spStatus` | `integer(int32)` | | 审批状态 | | -| `startTime` | `string` | | 开始时间 | | - -**响应** `统一响应结果«分页结果«审批日志»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«审批日志»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `审批日志[]` | | 数据列表 | -|     `applyData` | `string` | | 申请表单数据(JSON) | -|     `applyTime` | `string` | | 申请时间 | -|     `applyUserId` | `string` | | 申请人企微UserID | -|     `applyUserName` | `string` | | 申请人姓名 | -|     `approvalLogId` | `long` | | 审批日志ID | -|     `approvalNodes` | `string` | | 审批节点详情(JSON) | -|     `createdAt` | `string` | | 创建时间 | -|     `notifyNodes` | `string` | | 抄送节点详情(JSON) | -|     `spName` | `string` | | 审批模板名称 | -|     `spStatus` | `int` | | 审批状态: 1-审批中, 2-已通过, 3-已驳回, 4-已撤销, 6-通过后撤销, 7-已删除 | -|     `templateId` | `string` | | 审批模板ID | -|     `thirdNo` | `string` | | 审批编号 | -|     `updatedAt` | `string` | | 更新时间 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/approval-logs/{id} - -**审批日志详情** - -**关联字典**： -- approval_sp_status：审批状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 日志ID | - -**响应** `统一响应结果«审批日志»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `审批日志` | | 响应数据 | -|   `applyData` | `string` | | 申请表单数据(JSON) | -|   `applyTime` | `string` | | 申请时间 | -|   `applyUserId` | `string` | | 申请人企微UserID | -|   `applyUserName` | `string` | | 申请人姓名 | -|   `approvalLogId` | `long` | | 审批日志ID | -|   `approvalNodes` | `string` | | 审批节点详情(JSON) | -|   `createdAt` | `string` | | 创建时间 | -|   `notifyNodes` | `string` | | 抄送节点详情(JSON) | -|   `spName` | `string` | | 审批模板名称 | -|   `spStatus` | `int` | | 审批状态: 1-审批中, 2-已通过, 3-已驳回, 4-已撤销, 6-通过后撤销, 7-已删除 | -|   `templateId` | `string` | | 审批模板ID | -|   `thirdNo` | `string` | | 审批编号 | -|   `updatedAt` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -## 操作日志 - -### `GET` /admin/monitor/operation-logs - -**操作日志分页查询** - -查询管理员的操作记录，支持按模块、管理员、状态、时间范围筛选。记录包含请求参数、响应结果和耗时信息 - -**关联字典**： -- operation_log_status：操作状态（列表筛选+显示，0=成功/1=失败） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `adminId` | `integer(int64)` | | 管理员ID | | -| `endTime` | `string` | | 结束时间 | | -| `module` | `string` | | 模块名称 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `startTime` | `string` | | 开始时间 | | -| `status` | `integer(int32)` | | 状态 | | - -**响应** `统一响应结果«分页结果«操作日志»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«操作日志»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `操作日志[]` | | 数据列表 | -|     `adminId` | `long` | | 管理员ID | -|     `adminName` | `string` | | 管理员名称 | -|     `createdAt` | `string` | | 创建时间 | -|     `description` | `string` | | 操作描述 | -|     `duration` | `int` | | 耗时(毫秒) | -|     `errorMsg` | `string` | | 错误信息 | -|     `ipAddress` | `string` | | IP地址 | -|     `module` | `string` | | 操作模块 | -|     `operationLogId` | `long` | | 操作日志ID | -|     `requestMethod` | `string` | | 请求方法 | -|     `requestParams` | `string` | | 请求参数(JSON) | -|     `requestUrl` | `string` | | 请求URL | -|     `responseCode` | `int` | | 响应状态码 | -|     `responseMsg` | `string` | | 响应消息 | -|     `serviceName` | `string` | | 服务名称 | -|     `status` | `int` | | 状态: 0-成功, 1-失败 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/operation-logs/{id} - -**操作日志详情** - -返回单条操作日志的完整信息，包含操作模块、操作描述、请求参数、响应结果、操作耗时、操作人信息、IP地址等。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 日志ID | - -**响应** `统一响应结果«操作日志»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `操作日志` | | 响应数据 | -|   `adminId` | `long` | | 管理员ID | -|   `adminName` | `string` | | 管理员名称 | -|   `createdAt` | `string` | | 创建时间 | -|   `description` | `string` | | 操作描述 | -|   `duration` | `int` | | 耗时(毫秒) | -|   `errorMsg` | `string` | | 错误信息 | -|   `ipAddress` | `string` | | IP地址 | -|   `module` | `string` | | 操作模块 | -|   `operationLogId` | `long` | | 操作日志ID | -|   `requestMethod` | `string` | | 请求方法 | -|   `requestParams` | `string` | | 请求参数(JSON) | -|   `requestUrl` | `string` | | 请求URL | -|   `responseCode` | `int` | | 响应状态码 | -|   `responseMsg` | `string` | | 响应消息 | -|   `serviceName` | `string` | | 服务名称 | -|   `status` | `int` | | 状态: 0-成功, 1-失败 | -| `message` | `string` | | 响应消息 | - ---- - -## 数据清理 - -### `POST` /admin/monitor/data-retention/cleanup - -**手动触发数据清理** - -仅超级管理员可操作。按数据保留策略清理过期日志（操作日志/错误日志/通知日志等），返回各类型清理的记录数 - -**响应** `统一响应结果«Map«string,int»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## 服务监控 - -### `GET` /admin/monitor/services - -**微服务列表和健康状态** - -从Nacos注册中心获取所有微服务的实例列表和健康状态，包含IP、端口、注册时间和健康检查结果 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## 消息通知日志 - -### `GET` /admin/monitor/notification-logs - -**消息通知日志分页查询** - -查询各渠道（短信/站内信/企微/公众号）的通知发送记录，支持按通知类型、用户、发送状态筛选 - -**关联字典**： -- notification_send_status：发送状态（列表筛选+显示，0=待发送/1=成功/2=失败） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `endTime` | `string` | | 结束时间 | | -| `notificationType` | `string` | | 通知类型 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `sendStatus` | `integer(int32)` | | 发送状态 | | -| `startTime` | `string` | | 开始时间 | | -| `userName` | `string` | | 用户名 | | - -**响应** `统一响应结果«分页结果«通知日志»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«通知日志»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `通知日志[]` | | 数据列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `externalUserId` | `string` | | 外部联系人ID | -|     `externalUserName` | `string` | | 外部联系人姓名 | -|     `failReason` | `string` | | 失败原因 | -|     `messageContent` | `string` | | 消息内容 | -|     `notificationLogId` | `long` | | 通知日志ID | -|     `notificationType` | `string` | | 通知类型: ADD_EXTERNAL_CONTACT/DEL_FOLLOW_USER/DEL_EXTERNAL_CONTACT | -|     `sendStatus` | `int` | | 发送状态: 0-成功, 1-失败, 2-已过滤 | -|     `serviceName` | `string` | | 来源服务名称 | -|     `userId` | `string` | | 员工企微UserID | -|     `userName` | `string` | | 员工姓名 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/notification-logs/{id} - -**消息通知日志详情** - -返回单条通知发送日志的完整信息，包含通知类型、接收用户、发送渠道、发送状态、失败原因（如有）、消息内容等。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 日志ID | - -**响应** `统一响应结果«通知日志»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `通知日志` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `externalUserId` | `string` | | 外部联系人ID | -|   `externalUserName` | `string` | | 外部联系人姓名 | -|   `failReason` | `string` | | 失败原因 | -|   `messageContent` | `string` | | 消息内容 | -|   `notificationLogId` | `long` | | 通知日志ID | -|   `notificationType` | `string` | | 通知类型: ADD_EXTERNAL_CONTACT/DEL_FOLLOW_USER/DEL_EXTERNAL_CONTACT | -|   `sendStatus` | `int` | | 发送状态: 0-成功, 1-失败, 2-已过滤 | -|   `serviceName` | `string` | | 来源服务名称 | -|   `userId` | `string` | | 员工企微UserID | -|   `userName` | `string` | | 员工姓名 | -| `message` | `string` | | 响应消息 | - ---- - -## 登录日志 - -### `GET` /admin/monitor/login-logs - -**登录日志分页查询** - -查询管理员登录记录（代理到user-service），包含登录IP、设备信息、登录方式和登录结果 - -**关联字典**： -- login_status：登录状态（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `adminId` | `integer(int64)` | | 管理员ID | | -| `endTime` | `string` | | 结束时间 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `startTime` | `string` | | 开始时间 | | -| `status` | `string` | | 状态 | | - -**响应** `统一响应结果«object»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## 错误日志 - -### `GET` /admin/monitor/error-logs - -**错误日志分页查询** - -查询各微服务的异常记录，支持按服务名称、异常类名、时间范围筛选。堆栈信息仅保留com.hulalv包内的调用帧 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `endTime` | `string` | | 结束时间 | | -| `exceptionClass` | `string` | | 异常类名 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `serviceName` | `string` | | 服务名称 | | -| `startTime` | `string` | | 开始时间 | | - -**响应** `统一响应结果«分页结果«错误日志»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«错误日志»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `错误日志[]` | | 数据列表 | -|     `adminId` | `long` | | 管理员ID | -|     `createdAt` | `string` | | 创建时间 | -|     `errorLogId` | `long` | | 错误日志ID | -|     `exceptionClass` | `string` | | 异常类名 | -|     `exceptionMessage` | `string` | | 异常消息 | -|     `ipAddress` | `string` | | IP地址 | -|     `requestMethod` | `string` | | 请求方法 | -|     `requestParams` | `string` | | 请求参数(JSON) | -|     `requestUrl` | `string` | | 请求URL | -|     `serviceName` | `string` | | 服务名称 | -|     `stackTrace` | `string` | | 堆栈跟踪 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/error-logs/{id} - -**错误日志详情** - -返回单条错误日志的完整信息，包含异常类名、错误消息、过滤后的堆栈信息（仅com.hulalv包内调用帧）、请求URL、请求参数等。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 日志ID | - -**响应** `统一响应结果«错误日志»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `错误日志` | | 响应数据 | -|   `adminId` | `long` | | 管理员ID | -|   `createdAt` | `string` | | 创建时间 | -|   `errorLogId` | `long` | | 错误日志ID | -|   `exceptionClass` | `string` | | 异常类名 | -|   `exceptionMessage` | `string` | | 异常消息 | -|   `ipAddress` | `string` | | IP地址 | -|   `requestMethod` | `string` | | 请求方法 | -|   `requestParams` | `string` | | 请求参数(JSON) | -|   `requestUrl` | `string` | | 请求URL | -|   `serviceName` | `string` | | 服务名称 | -|   `stackTrace` | `string` | | 堆栈跟踪 | -| `message` | `string` | | 响应消息 | - ---- diff --git a/2026-03/17_0928/hl-mp-service.md b/2026-03/17_0928/hl-mp-service.md deleted file mode 100644 index 720fbe0..0000000 --- a/2026-03/17_0928/hl-mp-service.md +++ /dev/null @@ -1,3634 +0,0 @@ -# 小程序聚合服务 API 文档 - -**服务**: `hl-mp-service` -**接口总数**: 132 - -## 目录 - -- **C端 - 产品接口** (8 个接口) -- **C端 - 公共接口** (6 个接口) -- **C端 - 出行人接口** (6 个接口) -- **C端 - 前端配置接口** (2 个接口) -- **C端 - 发票接口** (4 个接口) -- **C端 - 合同接口** (5 个接口) -- **C端 - 天气接口** (3 个接口) -- **C端 - 字典接口** (1 个接口) -- **C端 - 定制师接口** (5 个接口) -- **C端 - 徽章接口** (1 个接口) -- **C端 - 心愿单接口** (2 个接口) -- **C端 - 探索接口** (5 个接口) -- **C端 - 搜索接口** (1 个接口) -- **C端 - 支付接口** (3 个接口) -- **C端 - 收藏接口** (6 个接口) -- **C端 - 攻略接口** (4 个接口) -- **C端 - 景区接口** (3 个接口) -- **C端 - 活动接口** (2 个接口) -- **C端 - 消息接口** (5 个接口) -- **C端 - 用户接口** (8 个接口) -- **C端 - 相册接口** (4 个接口) -- **C端 - 行程接口** (4 个接口) -- **C端 - 订单接口** (11 个接口) -- **C端 - 评价接口** (13 个接口) -- **C端 - 足迹接口** (4 个接口) -- **C端 - 轮播图接口** (1 个接口) -- **C端 - 退款接口** (7 个接口) -- **C端 - 通用点赞** (3 个接口) -- **C端 - 酒店接口** (2 个接口) -- **C端 - 餐厅接口** (2 个接口) -- **C端 - 首页接口** (1 个接口) - ---- - -## C端 - 产品接口 - -### `GET` /mp/product/batch/{batchId}/combos - -**GROUP批次套餐列表** - -返回指定批次的所有套餐（名称、人数组合、价格、库存） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `batchId` | `integer` | | 批次ID | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/product/lines - -**产品线列表** - -返回所有已启用的产品线，用于小程序首页或筛选栏展示 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/product/list - -**产品列表** - -分页查询已上架产品，支持按关键词、产品类型(CORE/ROUTE/CUSTOM/GROUP)、季节、天数、目的地、产品线筛选和排序 - -**关联字典（BFF透传）**： -- product_type：产品类型（列表筛选+显示） -- product_status：产品状态（透传自product-service） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `destination` | `string` | | 目的地 | | -| `keyword` | `string` | | 搜索关键词 | | -| `lineId` | `string` | | 产品线ID | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `productType` | `string` | | 产品类型：CORE/ROUTE/CUSTOM/GROUP | | -| `season` | `string` | | 季节 | | -| `sortBy` | `string` | | 排序字段 | | -| `sortDir` | `string` | | 排序方向 | | -| `tripDays` | `integer(int32)` | | 天数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/product/{productId} - -**产品详情（聚合收藏状态）** - -聚合流程：获取产品详情 → 并行查询收藏状态 → 异步记录足迹 → 返回聚合数据。支持未登录访问（不返回收藏状态） - -**关联字典（BFF透传）**： -- product_type：产品类型（显示） -- product_status：产品状态（透传自product-service） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `productId` | `integer` | | 产品ID | - -**响应** `统一响应结果«C端产品详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `C端产品详情` | | 响应数据 | -|   `chatMessages` | `Map«string,object»[]` | | 群聊最近消息（来自会话存档） | -|   `earliestBookingDate` | `string` | | 最早可订日期(如 2026-07-15) | -|   `earlyBirdDiscount` | `number` | | 早鸟优惠金额(元/人) | -|   `earlyBirdPlanName` | `string` | | 早鸟计划名称 | -|   `isFavorited` | `boolean` | | 是否已收藏（null表示未登录） | -|   `participantFamilyCount` | `int` | | 参与家庭数 | -|   `product` | `object` | | 产品详情（来自product-service） | -|   `reviewStats` | `object` | | 评价统计数据 | -|   `topLikedReview` | `object` | | 最高点赞评价 | -|   `topRatedReview` | `object` | | 最高评分评价 | -|   `totalSold` | `int` | | 已购人数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/product/{productId}/batch-calendar - -**GROUP批次日历** - -返回可报名批次列表（出发日期、剩余名额等），仅ENROLLING和CONFIRMED状态 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `productId` | `integer` | | 产品ID | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/product/{productId}/group-quote - -**GROUP报价** - -返回指定批次的各套餐报价（totalSellPrice） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `productId` | `integer` | | 产品ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `batchId` | `integer(int64)` | | 批次ID | | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/product/{productId}/price-calendar - -**价格日历** - -返回产品指定日期范围内的每日价格，用于日历组件展示。不传日期时默认返回未来一个月 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `productId` | `integer` | | 产品ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `endDate` | `string` | | 结束日期 | | -| `startDate` | `string` | | 开始日期 | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/product/{productId}/quote - -**报价计算（含早鸟优惠）** - -报价流程：传入出发日期+人数 → 价格日历计算基础报价（与下单一致） → 匹配早鸟优惠方案 → 返回明细报价+优惠信息。 - -支付方式说明： -- FULL: 全额支付，需一次性付清全部金额 -- DEPOSIT: 定金+尾款，先付定金（比例由产品配置），出行前补齐尾款 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `productId` | `integer` | | 产品ID | - -**请求体** `产品报价请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `adultCount` | `int` | 是 | 成人数量 | -| `babyCount` | `int` | | 婴儿数量 | -| `childCount` | `int` | | 儿童数量 | -| `childNeedBed` | `boolean` | | 儿童是否需要床位 | -| `departureDate` | `string` | 是 | 出发日期 | -| `youngChildCount` | `int` | | 幼儿数量 | - -**响应** `统一响应结果«产品报价结果»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `产品报价结果` | | 响应数据 | -|   `adultSellPrice` | `number` | | 成人单价 | -|   `babySellPrice` | `number` | | 幼童单价（固定价） | -|   `childSellPrice` | `number` | | 儿童单价 | -|   `childWithBedFee` | `number` | | 儿童加床费 | -|   `depositPayment` | `定金支付选项` | | 定金支付信息（仅paymentMode=DEPOSIT时有值） | -|     `balanceAmount` | `number` | | 尾款金额（出行前需付） | -|     `depositAmount` | `number` | | 定金金额（首次需付） | -|     `depositRatio` | `int` | | 定金比例(%) | -|     `description` | `string` | | 说明 | -|   `earlyBirdDiscount` | `早鸟优惠信息` | | 早鸟优惠信息，无优惠时为null | -|     `discountAmount` | `number` | | 优惠金额 | -|     `minPeople` | `int` | | 最低人数要求 | -|     `planId` | `long` | | 优惠方案ID | -|     `planName` | `string` | | 优惠方案名称 | -|   `finalPrice` | `number` | | 最终价（早鸟优惠后） | -|   `fullPayment` | `全额支付选项` | | 全额支付信息 | -|     `amount` | `number` | | 应付金额 | -|     `description` | `string` | | 说明 | -|   `grandTotalSellPrice` | `number` | | 总售价（优惠前） | -|   `paymentMode` | `string` | | 支付方式: FULL(全额支付) / DEPOSIT(定金+尾款) | -|   `totalAdultSellPrice` | `number` | | 成人小计 | -|   `totalBabySellPrice` | `number` | | 幼童小计 | -|   `totalChildSellPrice` | `number` | | 儿童小计 | -|   `totalYoungChildSellPrice` | `number` | | 小童小计 | -|   `youngChildSellPrice` | `number` | | 小童单价（儿童价×折扣比例） | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 公共接口 - -### `GET` /mp/common/agreement/list - -**协议列表** - -获取所有已上线的协议列表（不含内容，仅含类型、标题、版本） - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/common/agreement/{type} - -**获取协议文本** - -获取指定类型的协议文本（如隐私政策、用户协议），返回富文本内容 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `type` | `string` | 是 | 协议类型: privacy(隐私政策) / user(用户协议) | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/common/config - -**应用配置** - -获取应用全局配置信息 - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/common/contact - -**联系方式列表** - -获取有效的联系方式列表（电话/微信/邮箱等） - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/common/faq - -**FAQ列表** - -获取常见问题列表（按分类分组） - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/common/feedback - -**提交反馈** - -提交用户反馈，支持文字内容和图片附件 - -**请求体** `提交反馈请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `contact` | `string` | | 联系方式 | -| `content` | `string` | 是 | 反馈内容 | -| `images` | `string[]` | | 图片URL列表 | - -**响应** `统一响应结果«Void»` - ---- - -## C端 - 出行人接口 - -### `GET` /mp/user/traveler - -**出行人列表** - -返回当前用户的所有出行人列表。如果用户已完善实名信息，列表中会自动包含一条「本人」虚拟记录(travelerId=0) - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/user/traveler - -**添加出行人** - -添加常用出行人信息（姓名/证件/联系方式等），下单时可快速选择。单个用户最多50个出行人 - -**请求体** `修改)` - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/user/traveler/{id} - -**出行人详情** - -获取单个出行人的完整信息（姓名、证件信息、联系方式等）。 - -**权限**：需登录，仅能查看自己的出行人。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 出行人ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /mp/user/traveler/{id} - -**更新出行人** - -修改出行人信息，支持部分更新（只传需要修改的字段）。已关联订单的出行人修改不影响历史订单记录。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 出行人ID | - -**请求体** `修改)` - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /mp/user/traveler/{id} - -**删除出行人** - -删除常用出行人记录。默认出行人不可删除，需先取消默认后再删除。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 出行人ID | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /mp/user/traveler/{id}/default - -**设为默认出行人** - -设为默认出行人后，下单时自动作为第一个出行人。每个用户只能有一个默认出行人 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 出行人ID | - -**响应** `统一响应结果«Void»` - ---- - -## C端 - 前端配置接口 - -### `GET` /mp/config - -**获取所有非敏感前端配置** - -返回所有非SECRET类型的前端配置项（如主题色、客服电话、版本号等）。不含敏感配置，可安全传输给小程序端。 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/config/group/{group} - -**按分组获取非敏感前端配置** - -按配置分组获取前端配置项，如UI分组、功能开关分组等。用于小程序按需加载特定分组的配置。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `group` | `string` | | 配置分组 | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 发票接口 - -### `POST` /mp/invoice/apply - -**申请开票** - -开票流程：订单完成后 → 填写发票信息(抬头/税号/类型) → 提交开票申请 → 管理员处理 → 发送电子发票 - -**请求体** `发票申请请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `email` | `string` | | 接收邮箱 | -| `invoiceTitle` | `string` | 是 | 发票抬头 | -| `invoiceType` | `string` | 是 | 发票类型: PERSONAL(个人)/COMPANY(企业) | -| `orderId` | `string` | 是 | 订单ID | -| `taxpayerId` | `string` | | 纳税人识别号（企业发票必填） | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/invoice/order/{orderId} - -**通过订单ID查询发票** - -查询指定订单的发票信息，如果订单未开票则返回null - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/invoice/{id} - -**发票详情** - -获取发票的完整信息，包含开票状态、发票抬头、税号、金额、电子发票文件链接等 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 发票ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/invoice/{invoiceId}/reissue - -**发票换开** - -对已开发票申请换开（修改抬头/税号等），原发票作废后重新开具新发票 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `invoiceId` | `integer` | | 发票ID | - -**请求体** `发票换开请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `email` | `string` | | 接收邮箱 | -| `invoiceTitle` | `string` | 是 | 发票抬头 | -| `taxNumber` | `string` | | 纳税人识别号（企业发票必填） | -| `titleType` | `string` | 是 | 抬头类型: PERSONAL(个人)/COMPANY(企业) | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 合同接口 - -### `GET` /mp/contract/by-order/{orderId} - -**按订单查合同** - -返回订单关联的最新有效合同（非作废） - -**关联字典（BFF透传）**： -- contract_status：合同状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/contract/by-order/{orderId}/all - -**按订单查所有合同** - -返回订单关联的所有有效合同（TOUR+INSURANCE各一条） - -**关联字典（BFF透传）**： -- contract_status：合同状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/contract/list - -**合同列表** - -**关联字典（BFF透传）**： -- contract_status：合同状态（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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` | | 响应消息 | - ---- - -### `POST` /mp/contract/{contractId}/resend-sms - -**重新发送合同签署短信** - -重新向出行人发送合同签署短信通知，适用于出行人未收到短信或短信过期的场景。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `contractId` | `integer` | | 合同ID | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/contract/{id} - -**合同详情** - -返回合同基本信息、签署状态、出行人签署详情及合同文件下载链接 - -**关联字典（BFF透传）**： -- contract_status：合同状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 合同ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 天气接口 - -### `GET` /mp/weather/forecast - -**获取指定城市天气预报** - -通过高德天气API查询指定城市未来3天的天气预报信息 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `city` | `string` | | 城市名称 | | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/weather/itinerary/{orderId} - -**获取订单行程天气** - -根据订单行程中的目的地城市，批量查询每日天气信息，用于行程详情页展示 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/weather/live - -**获取指定城市实况天气** - -通过高德天气API查询指定城市的实时天气（温度、湿度、风向等） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `city` | `string` | | 城市名称 | | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 字典接口 - -### `GET` /dict/all - -**获取所有字典数据** - -获取系统全部字典数据（按字典类型分组），用于小程序端的下拉选项、枚举映射等。建议前端缓存此数据 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 定制师接口 - -### `GET` /mp/designer - -**定制师列表(含真实产品数和评分，综合排序)** - -获取定制师列表，聚合层会补充每个定制师的真实产品数量和评价评分。按综合排序（评分>路线数>咨询人数），用于小程序定制师推荐页。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `limit` | `integer(int32)` | | 每页条数 | | -| `page` | `integer(int32)` | | 页码 | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/designer/featured - -**推荐定制师(综合排序第一名)** - -获取综合排序排名第一的定制师信息（含产品数和评分），用于首页推荐定制师卡片展示。 - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/designer/{id} - -**定制师详情(含产品数量和评分)** - -获取定制师完整个人信息，聚合层会补充该定制师的已发布产品数量和综合评分，用于定制师个人主页展示。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 定制师ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/designer/{id}/products - -**定制师已发布产品列表** - -**关联字典（BFF透传）**： -- product_type：产品类型（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 定制师ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/designer/{id}/reviews - -**定制师产品评价列表** - -**关联字典（BFF透传）**： -- rating_level：评价等级（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 定制师ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 徽章接口 - -### `GET` /mp/badge - -**获取徽章数据** - -返回用户的徽章统计（未读消息数、待办事项数等），用于「我的」页面角标展示 - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 心愿单接口 - -### `GET` /mp/wish - -**心愿单列表** - -返回当前用户的心愿单列表，按创建时间倒序排列 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/wish - -**创建心愿** - -创建旅行心愿，描述想去的地方和时间偏好，定制师可据此推荐产品 - -**请求体** `创建心愿单请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `notes` | `string` | | 备注 | -| `productId` | `string` | 是 | 产品ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 探索接口 - -### `GET` /mp/explore/list - -**探索列表** - -获取已启用的探索分类列表（图文攻略内容），支持综合/最新/最热排序，分页返回。用于小程序探索频道首页瀑布流展示。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `sortType` | `string` | | 排序方式：comprehensive/newest/hottest | | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/explore/{id} - -**探索详情** - -自动增加浏览量，已登录时返回点赞/收藏状态 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 探索分类ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/explore/{id}/favorite - -**切换收藏** - -对探索内容收藏/取消收藏，返回当前收藏状态（true=已收藏）。收藏后可在'我的收藏'中查看。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 探索分类ID | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/explore/{id}/like - -**切换点赞** - -对探索内容点赞/取消点赞，返回当前点赞状态（true=已点赞）。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 探索分类ID | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/explore/{id}/view - -**浏览+1** - -增加探索内容的浏览计数。前端进入探索详情页时调用，无需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 探索分类ID | - -**响应** `统一响应结果«Void»` - ---- - -## C端 - 搜索接口 - -### `GET` /mp/search - -**搜索产品** - -按关键词搜索已上架产品（匹配产品名称和描述），支持按产品类型进一步筛选 - -**关联字典（BFF透传）**： -- product_type：产品类型（筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `keyword` | `string` | | 搜索关键词 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `productType` | `string` | | 产品类型：CORE/ROUTE/CUSTOM/GROUP | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 支付接口 - -### `POST` /mp/payment/prepay - -**发起支付** - -支付流程：选择支付方式(JSAPI/H5) → 调用微信支付API → 返回支付参数 → 前端调起微信支付 - -**关联字典（BFF透传）**： -- payment_status：支付状态（返回字段） - -**请求体** `支付预下单请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `clientIp` | `string` | | 客户端IP（H5支付必填） | -| `orderId` | `string` | 是 | 订单ID | -| `tradeType` | `string` | 是 | 支付方式: JSAPI(小程序支付)/H5(H5支付) | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/payment/status/{orderId} - -**查询支付状态** - -**关联字典（BFF透传）**： -- payment_status：支付状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/payment/transactions/{orderId} - -**订单交易记录列表** - -**关联字典（BFF透传）**： -- payment_status：支付状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 收藏接口 - -### `GET` /mp/user/favorite - -**收藏列表（含资源摘要）** - -分页查询收藏列表，聚合层会补充每个收藏项对应资源的摘要信息（名称、封面图、价格等）。支持按目标类型筛选。 - -**权限**：需登录。 - -**关联字典**： -- favorite_resource_type：收藏资源类型（PRODUCT/SCENIC/RESTAURANT/ACTIVITY） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `targetType` | `string` | | 目标类型筛选（字典：favorite_resource_type）：PRODUCT/SCENIC/RESTAURANT/ACTIVITY | | - -**响应** `统一响应结果«分页结果«收藏列表项（含资源摘要）»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«收藏列表项（含资源摘要）»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `收藏列表项（含资源摘要）[]` | | 数据列表 | -|     `coverUrl` | `string` | | 封面图URL | -|     `createdAt` | `string` | | 收藏时间 | -|     `favoriteId` | `string` | | 收藏记录ID | -|     `name` | `string` | | 资源名称 | -|     `tags` | `string[]` | | 标签列表 | -|     `targetId` | `string` | | 目标资源ID | -|     `targetType` | `string` | | 目标类型（字典：favorite_resource_type） | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/user/favorite - -**添加收藏** - -将产品/景区/餐厅/活动加入收藏。同一目标重复收藏会返回已有收藏记录 - -**请求体** `收藏请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `targetId` | `string` | 是 | 目标资源ID | -| `targetType` | `string` | 是 | 目标类型（字典：favorite_resource_type） | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /mp/user/favorite/batch - -**批量删除收藏** - -批量删除多条收藏记录，传入收藏记录ID列表。用于收藏管理页面的批量操作。 - -**权限**：需登录，仅能删除自己的收藏。 - -**请求体** `long[]` - -**响应** `统一响应结果«Void»` - ---- - -### `DELETE` /mp/user/favorite/by-target - -**按目标取消收藏** - -通过目标类型+目标ID取消收藏，适用于详情页点击取消收藏的场景（不需要知道收藏记录ID）。 - -**权限**：需登录。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `targetId` | `integer(int64)` | | 目标资源ID | | -| `targetType` | `string` | | 目标类型 | | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /mp/user/favorite/check - -**检查是否已收藏** - -检查当前用户是否已收藏指定资源，用于详情页收藏按钮状态显示。 - -**权限**：需登录。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `targetId` | `integer(int64)` | | 目标资源ID | | -| `targetType` | `string` | | 目标类型（字典：favorite_resource_type） | | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /mp/user/favorite/{id} - -**取消收藏** - -通过收藏记录ID取消收藏，适用于收藏列表页的删除操作。 - -**权限**：需登录，仅能删除自己的收藏。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 收藏记录ID | - -**响应** `统一响应结果«Void»` - ---- - -## C端 - 攻略接口 - -### `GET` /mp/wiki/article/{articleId} - -**文章详情** - -**关联字典（BFF透传）**： -- wiki_status：文章状态（返回字段） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | | 文章ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/wiki/categories - -**攻略分类列表** - -获取所有已启用的攻略分类，按排序值排列。用于小程序攻略频道的分类导航展示。 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/wiki/category/{categoryId}/articles - -**分类文章列表** - -分页查询指定攻略分类下已发布的文章列表，按发布时间倒序排列。用于攻略分类详情页。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryId` | `integer` | | 攻略分类ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/wiki/recommend-articles - -**推荐文章列表** - -获取编辑推荐的攻略文章列表（按推荐权重排序），用于首页或攻略频道的推荐位展示。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `limit` | `integer(int32)` | | 返回条数 | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 景区接口 - -### `GET` /mp/scenic/list - -**景区列表** - -分页查询已上架的景区列表，支持按关键词和城市筛选。聚合层透传resource-service的景区数据。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `city` | `string` | | 城市 | | -| `keyword` | `string` | | 关键词 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/scenic/{scenicId} - -**景区详情** - -获取景区完整信息（含季节素材、图文详情、价格等），自动注入静态地图图片URL用于详情页地图展示。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `scenicId` | `integer` | | 景区ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/scenic/{scenicId}/nearby - -**附近景区（地理+探索分类聚合）** - -聚合两个数据源：1.基于经纬度的地理位置附近景区（resource-service）；2.探索分类关联的景区（user-service）。去重合并后返回，用于景区详情页底部'附近推荐'展示。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `scenicId` | `integer` | | 景区ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `limit` | `integer(int32)` | | 返回条数 | | -| `radius` | `number(double)` | | 搜索半径(km) | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 活动接口 - -### `GET` /mp/activity/list - -**活动列表** - -分页查询已上架的活动列表，支持关键词和分类筛选。聚合层透传resource-service的活动数据给小程序前端。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `categoryCode` | `string` | | 分类 | | -| `keyword` | `string` | | 关键词 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/activity/{activityId} - -**活动详情** - -获取活动完整信息（含图文详情、价格等），自动注入静态地图图片URL用于详情页地图展示。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `activityId` | `integer` | | 活动ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 消息接口 - -### `GET` /mp/message/list - -**消息列表** - -消息列表，支持按分类筛选，按时间倒序分页返回 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `category` | `string` | | 消息分类筛选，不传返回全部 | | -| `page` | `integer(int32)` | | 页码，默认1 | | -| `pageSize` | `integer(int32)` | | 每页条数，默认20 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /mp/message/read-all - -**全部标记已读** - -将指定分类或全部消息标记为已读，不传category则全部已读 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `category` | `string` | | 消息分类，不传则将所有分类标记为已读 | | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /mp/message/summary - -**消息摘要** - -获取各分类的未读数量和最新一条消息，用于消息中心首页展示 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /mp/message/{id} - -**删除消息** - -删除单条消息 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | 是 | 消息ID | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /mp/message/{id}/read - -**标记已读** - -标记单条消息为已读 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | 是 | 消息ID | - -**响应** `统一响应结果«Void»` - ---- - -## C端 - 用户接口 - -### `DELETE` /mp/user/account - -**注销账号** - -注销后用户数据将被软删除，30天内可联系客服恢复 - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /mp/user/login - -**微信登录** - -登录流程：小程序wx.login获取code → 后端换取openid → 查找/创建用户 → 返回JWT令牌+needProfile标记 - -**请求体** `微信登录请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `string` | 是 | 微信授权code | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/user/login/sms - -**短信登录** - -登录流程：获取验证码 → 验证手机号+验证码 → 查找/创建用户 → 返回JWT令牌 - -**请求体** `短信验证码登录请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `string` | 是 | 验证码 | -| `phone` | `string` | 是 | 手机号 | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/user/logout - -**用户登出** - -清除用户登录状态和服务端缓存的令牌信息。登出后需重新登录获取新令牌。 - -**权限**：需登录。 - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /mp/user/ocr/idcard - -**身份证OCR识别** - -将身份证图片上传到OSS后，传入ossUrl进行OCR识别。返回姓名、身份证号、性别、民族等结构化数据，可用于自动填充出行人信息 - -**请求体** `身份证OCR识别请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `imgUrl` | `string` | 是 | 身份证图片的OSS地址 | - -**响应** `统一响应结果«Map«string,string»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/user/profile - -**获取用户信息** - -获取当前登录用户的个人资料，包含头像、昵称、手机号、实名信息等 - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /mp/user/profile - -**更新用户信息** - -更新当前用户的个人资料，支持部分更新（只传需要修改的字段）。首次完善资料时realName为必填 - -**请求体** `更新个人资料请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `avatar` | `string` | | 头像URL | -| `birthday` | `string` | | 生日 | -| `email` | `string` | | 邮箱 | -| `gender` | `int` | | 性别: 1=男, 2=女 | -| `nationality` | `string` | | 国籍 | -| `nickname` | `string` | | 昵称 | -| `phone` | `string` | | 手机号 | -| `realName` | `string` | | 真实姓名 | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/user/sms/send - -**发送短信验证码** - -向指定手机号发送登录验证码，有效期5分钟，60秒内不可重复发送 - -**请求体** `发送短信验证码请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `phone` | `string` | 是 | 手机号 | - -**响应** `统一响应结果«Void»` - ---- - -## C端 - 相册接口 - -### `GET` /mp/album/file/{albumFileId}/download-url - -**获取文件下载链接** - -获取文件的预签名下载URL，有效期有限 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `albumFileId` | `integer` | 是 | 相册文件ID | - -**响应** `统一响应结果«string»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `string` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/album/folder/{folderId}/files - -**文件夹下的文件列表** - -获取文件夹下的文件列表（分页），含图片和视频 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `folderId` | `integer` | 是 | 文件夹ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码，默认1 | | -| `size` | `integer(int32)` | | 每页数量，默认20 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/album/order/{orderId}/folders - -**订单的文件夹列表** - -获取订单下的相册文件夹列表 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | 是 | 订单ID | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/album/orders - -**有相册的订单列表** - -获取当前登录用户有相册的订单列表 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 行程接口 - -### `GET` /mp/trip/list - -**行程列表** - -获取当前登录用户的行程列表（已确认及进行中的订单对应的行程） - -**关联字典（BFF透传）**： -- order_status：订单/行程状态（显示） - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/trip/today - -**今日行程** - -获取今日行程（如果有正在进行中的行程），无行程时data为null - -**关联字典（BFF透传）**： -- order_status：订单/行程状态（显示） - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/trip/weather - -**天气查询** - -高德天气API代理，传入城市名称返回实时天气信息 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `city` | `string` | 是 | 城市名称，如「成都」「拉萨」 | | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/trip/{orderId} - -**行程详情** - -获取订单对应的行程详情，含每日行程节点信息（景点/酒店/餐厅等） - -**关联字典（BFF透传）**： -- order_status：订单/行程状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | 是 | 订单ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 订单接口 - -### `POST` /mp/order/bind-by-contact - -**绑定未绑定的订单** - -绑定流程：用户登录 → 完善个人资料 → 自动通过联系人手机号+姓名匹配 → 将userId=NULL的订单绑定到当前用户 - -**请求体** `通过联系人信息绑定订单请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `contactName` | `string` | 是 | 联系人姓名 | -| `contactPhone` | `string` | 是 | 联系人手机号 | - -**响应** `统一响应结果«int»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `int` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/count - -**各状态订单数量** - -统计当前用户各状态的订单数量，用于「我的」页面的订单状态角标展示 - -**关联字典（BFF透传）**： -- order_status：订单状态（状态分类统计） - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/order/create - -**创建订单** - -下单流程：选择产品 → 填写联系人/出行人信息 → 报价计算 → 创建订单 → 返回订单ID - -**请求体** `C端创建订单请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `adultCount` | `int` | | 成人数 | -| `babyCount` | `int` | | 幼童数 | -| `childCount` | `int` | | 儿童数 | -| `childNeedBed` | `boolean` | | 儿童是否需要床位 | -| `contactName` | `string` | 是 | 联系人姓名 | -| `contactPhone` | `string` | 是 | 联系人电话 | -| `customizerId` | `string` | | 定制师ID(通过分享链接下单时传入) | -| `departureDate` | `string` | | 出发日期(GROUP产品从团期获取，可不传) | -| `groupBatchId` | `string` | | 团期ID(GROUP产品必填) | -| `productId` | `string` | 是 | 产品ID | -| `remark` | `string` | | 备注 | -| `roomCount` | `int` | | 房间数(GROUP产品，默认1) | -| `sharerOpenid` | `string` | | 分享人微信openid（通过分享进入下单时传入，用于记录分享关系） | -| `travelers` | `出行人信息[]` | | 出行人列表 | -|   `birthday` | `string` | | 出生日期 | -|   `email` | `string` | | 电子邮箱 | -|   `emergencyContact` | `string` | | 紧急联系人 | -|   `emergencyPhone` | `string` | | 紧急联系电话 | -|   `gender` | `int` | | 性别（1=男, 2=女） | -|   `idCardNo` | `string` | | 证件号码 | -|   `idCardType` | `string` | | 证件类型 | -|   `name` | `string` | 是 | 出行人姓名 | -|   `nationality` | `string` | | 国籍 | -|   `phone` | `string` | | 手机号 | -|   `travelerType` | `string` | | 出行人类型（ADULT/CHILD/YOUNG_CHILD/BABY） | -| `youngChildCount` | `int` | | 小童数 | - -**响应** `统一响应结果«订单详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `订单详情` | | 响应数据 | -|   `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` | `Map«string,object»[]` | | 优惠列表 | -|   `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` | | 支付模式（FULL/DEPOSIT） | -|   `processStatus` | `string` | | 内部流程状态 | -|   `processStatusLabel` | `string` | | 内部流程状态标签 | -|   `productCoverUrl` | `string` | | 产品封面图URL | -|   `productId` | `long` | | 产品ID | -|   `productName` | `string` | | 产品名称 | -|   `productSnapshot` | `string` | | 产品快照JSON | -|   `productType` | `string` | | 产品类型（CORE/ROUTE/CUSTOM/GROUP） | -|   `readyAt` | `string` | | 就绪时间 | -|   `refundAmount` | `number` | | 退款金额 | -|   `remark` | `string` | | 备注 | -|   `returnDate` | `string` | | 返程日期（出发日期 + 行程天数 - 1） | -|   `reviewed` | `boolean` | | 是否已评价 | -|   `roomInfo` | `string` | | 房间信息 | -|   `status` | `string` | | 订单状态（PENDING_PAY/DEPOSIT_PAID/PAID/CONFIRMED/IN_PROGRESS/COMPLETED/CANCELLED） | -|   `statusLabel` | `string` | | 订单状态标签 | -|   `timeline` | `Map«string,object»[]` | | 时间线列表 | -|   `todos` | `Map«string,object»[]` | | 待办列表 | -|   `totalPrice` | `number` | | 总售价 | -|   `travelers` | `Map«string,object»[]` | | 出行人列表 | -|   `tripDays` | `int` | | 行程天数 | -|   `tripNights` | `int` | | 行程晚数 | -|   `unlockRequestedAt` | `string` | | 解锁请求时间 | -|   `userId` | `long` | | 用户ID | -|   `vehicleInfo` | `string` | | 车辆信息 | -|   `youngChildCount` | `int` | | 小童数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/list - -**订单列表** - -分页查询当前用户的订单列表，支持按状态筛选。返回订单摘要信息（不含详细出行人信息） - -**关联字典（BFF透传）**： -- order_status：订单状态（列表筛选+显示） -- product_type：产品类型（订单卡片显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `status` | `string` | | 状态 | | - -**响应** `统一响应结果«分页结果«订单列表项»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«订单列表项»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `订单列表项[]` | | 数据列表 | -|     `adultCount` | `int` | | 成人数 | -|     `babyCount` | `int` | | 幼童数 | -|     `balanceAmount` | `number` | | 尾款金额 | -|     `childCount` | `int` | | 儿童数 | -|     `contracts` | `Map«string,object»[]` | | 合同列表（含signUrl/fileUrl/status等） | -|     `createTime` | `string` | | 创建时间 | -|     `daysUntilDeparture` | `int` | | 距出发天数（负数表示已出发） | -|     `departureDate` | `string` | | 出发日期 | -|     `depositAmount` | `number` | | 定金金额 | -|     `displayName` | `string` | | 显示名称（未支付=手机号+姓名，已支付=订单号） | -|     `displayStatus` | `string` | | C端简化状态（PENDING_PAY/PENDING_DEPARTURE/PENDING_REVIEW/REFUND/CANCELLED） | -|     `displayStatusLabel` | `string` | | C端简化状态标签 | -|     `expiryTime` | `string` | | 支付截止时间（PENDING_PAY状态有效） | -|     `insurances` | `Map«string,object»[]` | | 保险订单列表（含productName/extPolicyNo/status等） | -|     `nextAction` | `string` | | 下一步操作提示 | -|     `orderId` | `long` | | 订单ID | -|     `orderNo` | `string` | | 订单编号 | -|     `paidAmount` | `number` | | 已付金额 | -|     `paymentMode` | `string` | | 支付模式（FULL/DEPOSIT） | -|     `processStatus` | `string` | | 内部流程状态（字典：order_process_status） | -|     `processStatusLabel` | `string` | | 内部流程状态标签（字典：order_process_status 翻译） | -|     `productCoverUrl` | `string` | | 产品封面图URL | -|     `productId` | `long` | | 产品ID | -|     `productName` | `string` | | 产品名称 | -|     `productType` | `string` | | 产品类型（CORE/ROUTE/CUSTOM/GROUP） | -|     `status` | `string` | | 订单状态（PENDING_PAY/DEPOSIT_PAID/PAID/CONFIRMED/IN_PROGRESS/COMPLETED/CANCELLED） | -|     `statusLabel` | `string` | | 订单状态标签 | -|     `totalPrice` | `number` | | 总售价 | -|     `tripDays` | `int` | | 行程天数 | -|     `tripNights` | `int` | | 行程晚数 | -|     `youngChildCount` | `int` | | 小童数 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/lookup - -**通过联系人手机号+姓名查找订单（无需登录）** - -无需登录即可查询。用于管理员代下单场景：管理员创建订单后，用户通过联系人手机号+姓名查找订单并绑定到自己账号。仅返回尚未绑定用户(userId=NULL)的订单。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `contactName` | `string` | | 联系人姓名 | | -| `contactPhone` | `string` | | 联系人手机号 | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/upcoming - -**即将出发的订单** - -查询3天内即将出发的订单（状态为已确认/待出发/出行中），含合同和保险信息，按出发日期升序 - -**响应** `统一响应结果«List«订单列表项»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `订单列表项[]` | | 响应数据 | -|   `adultCount` | `int` | | 成人数 | -|   `babyCount` | `int` | | 幼童数 | -|   `balanceAmount` | `number` | | 尾款金额 | -|   `childCount` | `int` | | 儿童数 | -|   `contracts` | `Map«string,object»[]` | | 合同列表（含signUrl/fileUrl/status等） | -|   `createTime` | `string` | | 创建时间 | -|   `daysUntilDeparture` | `int` | | 距出发天数（负数表示已出发） | -|   `departureDate` | `string` | | 出发日期 | -|   `depositAmount` | `number` | | 定金金额 | -|   `displayName` | `string` | | 显示名称（未支付=手机号+姓名，已支付=订单号） | -|   `displayStatus` | `string` | | C端简化状态（PENDING_PAY/PENDING_DEPARTURE/PENDING_REVIEW/REFUND/CANCELLED） | -|   `displayStatusLabel` | `string` | | C端简化状态标签 | -|   `expiryTime` | `string` | | 支付截止时间（PENDING_PAY状态有效） | -|   `insurances` | `Map«string,object»[]` | | 保险订单列表（含productName/extPolicyNo/status等） | -|   `nextAction` | `string` | | 下一步操作提示 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `paidAmount` | `number` | | 已付金额 | -|   `paymentMode` | `string` | | 支付模式（FULL/DEPOSIT） | -|   `processStatus` | `string` | | 内部流程状态（字典：order_process_status） | -|   `processStatusLabel` | `string` | | 内部流程状态标签（字典：order_process_status 翻译） | -|   `productCoverUrl` | `string` | | 产品封面图URL | -|   `productId` | `long` | | 产品ID | -|   `productName` | `string` | | 产品名称 | -|   `productType` | `string` | | 产品类型（CORE/ROUTE/CUSTOM/GROUP） | -|   `status` | `string` | | 订单状态（PENDING_PAY/DEPOSIT_PAID/PAID/CONFIRMED/IN_PROGRESS/COMPLETED/CANCELLED） | -|   `statusLabel` | `string` | | 订单状态标签 | -|   `totalPrice` | `number` | | 总售价 | -|   `tripDays` | `int` | | 行程天数 | -|   `tripNights` | `int` | | 行程晚数 | -|   `youngChildCount` | `int` | | 小童数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/{orderId} - -**订单详情** - -获取订单完整信息，包含产品快照、出行人列表、支付信息、合同状态等 - -**关联字典（BFF透传）**： -- order_status：订单状态（显示） -- product_type：产品类型（显示） -- contract_status：合同状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«订单详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `订单详情` | | 响应数据 | -|   `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` | `Map«string,object»[]` | | 优惠列表 | -|   `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` | | 支付模式（FULL/DEPOSIT） | -|   `processStatus` | `string` | | 内部流程状态 | -|   `processStatusLabel` | `string` | | 内部流程状态标签 | -|   `productCoverUrl` | `string` | | 产品封面图URL | -|   `productId` | `long` | | 产品ID | -|   `productName` | `string` | | 产品名称 | -|   `productSnapshot` | `string` | | 产品快照JSON | -|   `productType` | `string` | | 产品类型（CORE/ROUTE/CUSTOM/GROUP） | -|   `readyAt` | `string` | | 就绪时间 | -|   `refundAmount` | `number` | | 退款金额 | -|   `remark` | `string` | | 备注 | -|   `returnDate` | `string` | | 返程日期（出发日期 + 行程天数 - 1） | -|   `reviewed` | `boolean` | | 是否已评价 | -|   `roomInfo` | `string` | | 房间信息 | -|   `status` | `string` | | 订单状态（PENDING_PAY/DEPOSIT_PAID/PAID/CONFIRMED/IN_PROGRESS/COMPLETED/CANCELLED） | -|   `statusLabel` | `string` | | 订单状态标签 | -|   `timeline` | `Map«string,object»[]` | | 时间线列表 | -|   `todos` | `Map«string,object»[]` | | 待办列表 | -|   `totalPrice` | `number` | | 总售价 | -|   `travelers` | `Map«string,object»[]` | | 出行人列表 | -|   `tripDays` | `int` | | 行程天数 | -|   `tripNights` | `int` | | 行程晚数 | -|   `unlockRequestedAt` | `string` | | 解锁请求时间 | -|   `userId` | `long` | | 用户ID | -|   `vehicleInfo` | `string` | | 车辆信息 | -|   `youngChildCount` | `int` | | 小童数 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/order/{orderId}/approve-unlock - -**同意解锁订单** - -用户同意管理员的修改请求，解除订单锁定状态，允许管理员继续修改订单 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /mp/order/{orderId}/cancel - -**取消订单** - -取消规则：仅PENDING_PAY/DEPOSIT_PAID状态可用户取消，取消后不可恢复 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**请求体** `用户取消订单请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reason` | `string` | | 取消原因 | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /mp/order/{orderId}/edit - -**修改订单** - -用户可修改出发日期和出行人。仅待支付/已付定金/已支付/已确认/待付尾款/待出发状态可修改，清单已确认的订单不允许修改。修改后重走内部流程 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**请求体** `修改订单请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `departureDate` | `string` | | 出发日期 | -| `travelers` | `出行人信息_1[]` | | 出行人列表（提供则替换全部出行人） | -|   `birthday` | `string` | | 出生日期 | -|   `email` | `string` | | 电子邮箱 | -|   `emergencyContact` | `string` | | 紧急联系人 | -|   `emergencyPhone` | `string` | | 紧急联系电话 | -|   `gender` | `int` | | 性别 | -|   `idCardNo` | `string` | | 证件号码 | -|   `idCardType` | `string` | | 证件类型 | -|   `name` | `string` | 是 | 出行人姓名 | -|   `nationality` | `string` | | 国籍 | -|   `phone` | `string` | | 手机号 | -|   `travelerType` | `string` | | 出行人类型 | - -**响应** `统一响应结果«订单详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `订单详情` | | 响应数据 | -|   `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` | `Map«string,object»[]` | | 优惠列表 | -|   `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` | | 支付模式（FULL/DEPOSIT） | -|   `processStatus` | `string` | | 内部流程状态 | -|   `processStatusLabel` | `string` | | 内部流程状态标签 | -|   `productCoverUrl` | `string` | | 产品封面图URL | -|   `productId` | `long` | | 产品ID | -|   `productName` | `string` | | 产品名称 | -|   `productSnapshot` | `string` | | 产品快照JSON | -|   `productType` | `string` | | 产品类型（CORE/ROUTE/CUSTOM/GROUP） | -|   `readyAt` | `string` | | 就绪时间 | -|   `refundAmount` | `number` | | 退款金额 | -|   `remark` | `string` | | 备注 | -|   `returnDate` | `string` | | 返程日期（出发日期 + 行程天数 - 1） | -|   `reviewed` | `boolean` | | 是否已评价 | -|   `roomInfo` | `string` | | 房间信息 | -|   `status` | `string` | | 订单状态（PENDING_PAY/DEPOSIT_PAID/PAID/CONFIRMED/IN_PROGRESS/COMPLETED/CANCELLED） | -|   `statusLabel` | `string` | | 订单状态标签 | -|   `timeline` | `Map«string,object»[]` | | 时间线列表 | -|   `todos` | `Map«string,object»[]` | | 待办列表 | -|   `totalPrice` | `number` | | 总售价 | -|   `travelers` | `Map«string,object»[]` | | 出行人列表 | -|   `tripDays` | `int` | | 行程天数 | -|   `tripNights` | `int` | | 行程晚数 | -|   `unlockRequestedAt` | `string` | | 解锁请求时间 | -|   `userId` | `long` | | 用户ID | -|   `vehicleInfo` | `string` | | 车辆信息 | -|   `youngChildCount` | `int` | | 小童数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/{orderId}/resources - -**订单资源详情（按分类）** - -解析产品快照，提取资源详情按分类返回 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«Map«string,List«Map«string,object»»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 评价接口 - -### `POST` /mp/review/create - -**创建评价** - -评价流程：订单完成后 → 查询可评价目标列表 → 对每个目标(酒店/景区/活动等)提交评价 → 自动内容审核 → 审核通过后公开展示 - -**关联字典（BFF透传）**： -- review_status：评价审核状态（返回字段） -- rating_level：评价等级（返回字段） - -**请求体** `创建评价请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `content` | `string` | 是 | 评价内容(10-500字) | -| `images` | `评价图片项[]` | | 评价图片列表（最多9张） | -|   `fileId` | `long` | | 文件ID | -|   `imageUrl` | `string` | 是 | 图片URL | -| `orderId` | `long` | 是 | 订单ID | -| `ratings` | `object` | 是 | 评分数据（key为评分类别字典的dictValue，value为1-5整数）。先调用 GET /mp/review/rating-categories 获取评分维度，required=true的必填。示例: {"ratingItinerary":5,"ratingAccommodation":4,"ratingDriver":5,"ratingDining":4,"ratingOverall":5} | -| `videos` | `评价视频项[]` | | 评价视频列表（最多3个） | -|   `coverUrl` | `string` | | 视频封面URL | -|   `duration` | `int` | | 视频时长(秒) | -|   `fileId` | `long` | | 文件ID | -|   `videoUrl` | `string` | 是 | 视频URL | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/featured - -**精选评价列表(公开)** - -无需登录，返回精选评价数组，用于评价浏览页 - -**关联字典（BFF透传）**： -- rating_level：评价等级（显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `limit` | `integer(int32)` | | 数量限制 | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/my - -**我的评价列表** - -**关联字典（BFF透传）**： -- review_status：评价审核状态（显示） -- rating_level：评价等级（显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/order/{orderId}/reviewable-targets - -**订单可评价目标列表** - -返回订单中可评价的资源目标列表（景区/酒店/活动等），用于评价页面展示可评价项。已评价的目标不会重复出现。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/order/{orderId}/reviewed - -**检查订单是否已评价** - -检查指定订单是否已提交评价，用于订单详情页决定是否显示'去评价'按钮。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/product/{productId} - -**按产品ID查看评价列表** - -返回评价列表+统计数据，支持好中差评/有图/有视频筛选 - -**关联字典（BFF透传）**： -- rating_level：评价等级（筛选+显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `productId` | `integer` | | 产品ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `hasImage` | `boolean` | | 是否有图片 | | -| `hasVideo` | `boolean` | | 是否有视频 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `ratingLevel` | `string` | | 评价等级: GOOD/MEDIUM/BAD | | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/product/{productId}/highlights - -**产品精选评价(最高评分+最高点赞+统计)** - -用于产品详情页评价区域展示 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `productId` | `integer` | | 产品ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/rating-categories - -**评分类别列表** - -从字典读取评价时需要填写的评分维度，前端据此渲染评分组件。字典类型: review_rating_category，remark字段包含扩展JSON(required/min/max) - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/search - -**关键词搜索评价(公开)** - -按关键词搜索已通过的评价内容，支持按目标类型和目标ID筛选 - -**关联字典（BFF透传）**： -- rating_level：评价等级（显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `keyword` | `string` | 是 | 搜索关键词 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `targetId` | `integer(int64)` | | 目标ID(可选) | | -| `targetType` | `string` | | 目标类型(可选): PRODUCT/SCENIC_SPOT/ACTIVITY/HOTEL等 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/stats - -**评价统计(平均分、数量)** - -获取指定目标的评价统计数据（平均评分、总评价数等），用于详情页评价区域展示。产品showReview关闭时返回空统计。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `targetId` | `integer(int64)` | | 目标ID | | -| `targetType` | `string` | | 目标类型 | | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/target - -**某目标的已通过评价(公开)** - -**关联字典（BFF透传）**： -- rating_level：评价等级（筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `hasImage` | `boolean` | | 是否有图片 | | -| `hasVideo` | `boolean` | | 是否有视频 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `ratingLevel` | `string` | | 评价等级: GOOD/MEDIUM/BAD | | -| `targetId` | `integer(int64)` | | 目标ID | | -| `targetType` | `string` | | 目标类型 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/review/{reviewId}/like - -**点赞/取消点赞评价** - -对评价进行点赞或取消点赞操作，返回当前点赞状态和点赞总数。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reviewId` | `integer` | | 评价ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/{reviewId}/like/check - -**检查是否已点赞** - -检查当前用户是否已点赞指定评价，用于评价列表/详情的点赞按钮状态展示。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reviewId` | `integer` | | 评价ID | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 足迹接口 - -### `GET` /mp/user/footprint - -**足迹列表（含资源摘要）** - -分页查询浏览足迹列表，聚合层会补充每条足迹对应资源的摘要信息（名称、封面图等）。支持按资源类型筛选，按浏览时间倒序。 - -**权限**：需登录。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `resourceType` | `string` | | 资源类型筛选：PRODUCT/SCENIC/RESTAURANT/ACTIVITY | | - -**响应** `统一响应结果«分页结果«足迹列表项（含资源摘要）»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«足迹列表项（含资源摘要）»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `足迹列表项（含资源摘要）[]` | | 数据列表 | -|     `coverUrl` | `string` | | 封面图URL | -|     `footprintId` | `string` | | 足迹记录ID | -|     `name` | `string` | | 资源名称 | -|     `resourceId` | `string` | | 资源ID | -|     `resourceType` | `string` | | 资源类型：PRODUCT/SCENIC/RESTAURANT/ACTIVITY | -|     `tags` | `string[]` | | 标签列表 | -|     `visitTime` | `string` | | 浏览时间 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/user/footprint - -**记录足迹** - -记录用户浏览资源的足迹，同一资源重复浏览会更新浏览时间而非新增记录 - -**请求体** `添加足迹请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `resourceId` | `string` | 是 | 资源ID | -| `resourceType` | `string` | 是 | 资源类型: PRODUCT/SCENIC/RESTAURANT/ACTIVITY | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /mp/user/footprint/batch - -**批量删除足迹** - -批量删除多条浏览足迹记录，传入足迹ID列表。用于足迹管理页面的批量清理。 - -**权限**：需登录，仅能删除自己的足迹。 - -**请求体** `long[]` - -**响应** `统一响应结果«Void»` - ---- - -### `DELETE` /mp/user/footprint/{id} - -**删除足迹** - -删除单条浏览足迹记录。 - -**权限**：需登录，仅能删除自己的足迹。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 足迹ID | - -**响应** `统一响应结果«Void»` - ---- - -## C端 - 轮播图接口 - -### `GET` /mp/banner/active - -**获取当前生效的轮播图列表** - -返回当前处于有效期内的轮播图，按排序值排列。用于小程序首页顶部轮播展示，透传自user-service。 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 退款接口 - -### `GET` /mp/order/refund-reasons - -**退款原因列表** - -返回系统预设的退款原因选项，用于退款申请页面的原因选择 - -**响应** `统一响应结果«List«退款原因»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款原因[]` | | 响应数据 | -|   `category` | `string` | | 分类: GENERAL(通用)/PRODUCT(产品问题)/SERVICE(服务问题) | -|   `enabled` | `boolean` | | 是否启用 | -|   `reasonId` | `long` | | 原因ID | -|   `reasonText` | `string` | | 原因描述 | -|   `sortOrder` | `int` | | 排序序号 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/refund/{applicationId} - -**退款申请详情** - -获取退款申请的完整信息，包含审核状态、退款金额、退款进度和操作记录 - -**关联字典（BFF透传）**： -- order_status：订单状态（显示） -- payment_status：支付/退款状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `applicationId` | `integer` | | 退款申请ID | - -**响应** `统一响应结果«退款申请详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款申请详情` | | 响应数据 | -|   `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` | | 审批编号（企微OA审批编号） | -|   `autoRefundDeadline` | `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` | | 退款类型: DEPOSIT(定金)/BALANCE(尾款)/FULL(全款) | -|   `refundTypeLabel` | `string` | | 退款类型中文标签 | -|   `refundedAt` | `string` | | 退款完成时间 | -|   `reviewAdminId` | `long` | | 审批管理员ID | -|   `reviewAdminName` | `string` | | 审批管理员姓名 | -|   `reviewRemark` | `string` | | 审批备注 | -|   `reviewedAt` | `string` | | 审批时间 | -|   `status` | `string` | | 退款状态: PENDING(待审核)/APPROVED(已通过)/REJECTED(已拒绝)/REFUNDING(退款中)/REFUNDED(已退款)/CANCELLED(已撤回)/APPEALING(申诉中)/APPEAL_APPROVED(申诉通过)/APPEAL_REJECTED(申诉驳回) | -|   `statusLabel` | `string` | | 退款状态中文标签 | -|   `updateTime` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/order/refund/{applicationId}/appeal - -**发起申诉** - -退款被拒绝后，用户可在3天内发起一次申诉，由上级管理员重新审核 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `applicationId` | `integer` | | 退款申请ID | - -**请求体** `退款申诉请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `appealReason` | `string` | 是 | 申诉原因 | -| `evidence` | `string[]` | | 申诉凭证图片URL列表 | - -**响应** `统一响应结果«退款申请详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款申请详情` | | 响应数据 | -|   `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` | | 审批编号（企微OA审批编号） | -|   `autoRefundDeadline` | `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` | | 退款类型: DEPOSIT(定金)/BALANCE(尾款)/FULL(全款) | -|   `refundTypeLabel` | `string` | | 退款类型中文标签 | -|   `refundedAt` | `string` | | 退款完成时间 | -|   `reviewAdminId` | `long` | | 审批管理员ID | -|   `reviewAdminName` | `string` | | 审批管理员姓名 | -|   `reviewRemark` | `string` | | 审批备注 | -|   `reviewedAt` | `string` | | 审批时间 | -|   `status` | `string` | | 退款状态: PENDING(待审核)/APPROVED(已通过)/REJECTED(已拒绝)/REFUNDING(退款中)/REFUNDED(已退款)/CANCELLED(已撤回)/APPEALING(申诉中)/APPEAL_APPROVED(申诉通过)/APPEAL_REJECTED(申诉驳回) | -|   `statusLabel` | `string` | | 退款状态中文标签 | -|   `updateTime` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/order/refund/{applicationId}/cancel - -**撤回退款申请** - -仅PENDING状态的退款申请可撤回，撤回后订单恢复到原状态 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `applicationId` | `integer` | | 退款申请ID | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /mp/order/{orderId}/refund - -**提交退款申请** - -退款流程：获取退款预览 → 选择退款原因 → 提交退款申请 → 管理员审核 → 审核通过后自动退款到原支付方式 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**请求体** `退款申请请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `images` | `string[]` | | 退款凭证图片URL列表 | -| `reasonDetail` | `string` | | 退款补充说明 | -| `reasonId` | `string` | | 退款原因ID（已废弃，改用字典） | -| `reasonText` | `string` | 是 | 退款原因文本 | -| `reasonValue` | `string` | | 退款原因字典值 | -| `refundType` | `string` | 是 | 退款类型（FULL/DEPOSIT/BALANCE） | - -**响应** `统一响应结果«退款申请详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款申请详情` | | 响应数据 | -|   `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` | | 审批编号（企微OA审批编号） | -|   `autoRefundDeadline` | `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` | | 退款类型: DEPOSIT(定金)/BALANCE(尾款)/FULL(全款) | -|   `refundTypeLabel` | `string` | | 退款类型中文标签 | -|   `refundedAt` | `string` | | 退款完成时间 | -|   `reviewAdminId` | `long` | | 审批管理员ID | -|   `reviewAdminName` | `string` | | 审批管理员姓名 | -|   `reviewRemark` | `string` | | 审批备注 | -|   `reviewedAt` | `string` | | 审批时间 | -|   `status` | `string` | | 退款状态: PENDING(待审核)/APPROVED(已通过)/REJECTED(已拒绝)/REFUNDING(退款中)/REFUNDED(已退款)/CANCELLED(已撤回)/APPEALING(申诉中)/APPEAL_APPROVED(申诉通过)/APPEAL_REJECTED(申诉驳回) | -|   `statusLabel` | `string` | | 退款状态中文标签 | -|   `updateTime` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/{orderId}/refund-detail - -**根据订单ID获取最新退款详情** - -查询订单关联的最新一条退款申请详情，无退款记录时返回null - -**关联字典（BFF透传）**： -- order_status：订单状态（显示） -- payment_status：支付/退款状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `string` | | 订单ID | - -**响应** `统一响应结果«退款申请详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款申请详情` | | 响应数据 | -|   `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` | | 审批编号（企微OA审批编号） | -|   `autoRefundDeadline` | `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` | | 退款类型: DEPOSIT(定金)/BALANCE(尾款)/FULL(全款) | -|   `refundTypeLabel` | `string` | | 退款类型中文标签 | -|   `refundedAt` | `string` | | 退款完成时间 | -|   `reviewAdminId` | `long` | | 审批管理员ID | -|   `reviewAdminName` | `string` | | 审批管理员姓名 | -|   `reviewRemark` | `string` | | 审批备注 | -|   `reviewedAt` | `string` | | 审批时间 | -|   `status` | `string` | | 退款状态: PENDING(待审核)/APPROVED(已通过)/REJECTED(已拒绝)/REFUNDING(退款中)/REFUNDED(已退款)/CANCELLED(已撤回)/APPEALING(申诉中)/APPEAL_APPROVED(申诉通过)/APPEAL_REJECTED(申诉驳回) | -|   `statusLabel` | `string` | | 退款状态中文标签 | -|   `updateTime` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/{orderId}/refund-preview - -**退款金额预览** - -根据退款政策和订单出发日期计算可退金额，展示退款比例和扣除金额明细 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«退款预览»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款预览` | | 响应数据 | -|   `calculatedAmount` | `number` | | 计算退款金额 | -|   `daysBeforeDept` | `int` | | 距出发天数 | -|   `departureDate` | `string` | | 出发日期 | -|   `message` | `string` | | 提示信息 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单号 | -|   `paidAmount` | `number` | | 已付金额 | -|   `policyId` | `long` | | 匹配的退款政策ID | -|   `policyName` | `string` | | 匹配的退款政策名称 | -|   `refundRatio` | `int` | | 退款比例（百分比） | -|   `refundType` | `string` | | 退款类型: DEPOSIT/BALANCE/FULL | -|   `refundable` | `boolean` | | 是否可退款 | -|   `rules` | `退款规则项[]` | | 退款规则列表（按天数降序） | -|     `matched` | `boolean` | | 是否当前命中此规则 | -|     `minDays` | `int` | | 最低天数 | -|     `refundRatio` | `int` | | 退款比例（百分比） | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 通用点赞 - -### `POST` /mp/like/{targetType}/batch-check - -**批量检查点赞状态** - -批量检查当前用户是否已对多个目标点赞，返回已点赞的目标ID列表。用于列表页批量展示点赞状态。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `targetType` | `string` | | 目标类型 | - -**请求体** `string[]` - -**响应** `统一响应结果«List«string»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `string[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/like/{targetType}/{targetId} - -**切换点赞** - -点赞/取消点赞，返回 {liked: true/false, likeCount: 点赞数} - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `targetId` | `integer` | | 目标ID | -| `targetType` | `string` | | 目标类型: REVIEW/EXPLORE/GUIDE等 | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/like/{targetType}/{targetId}/check - -**检查是否已点赞** - -检查当前用户是否已对指定目标点赞，用于前端点赞按钮状态展示。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `targetId` | `integer` | | 目标ID | -| `targetType` | `string` | | 目标类型 | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 酒店接口 - -### `GET` /mp/hotel/list - -**酒店列表** - -分页查询已上架的酒店列表，支持按关键词、城市、星级筛选。聚合层透传resource-service的酒店数据。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `city` | `string` | | 城市 | | -| `keyword` | `string` | | 关键词 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `starLevel` | `integer(int32)` | | 星级 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/hotel/{hotelId} - -**酒店详情** - -获取酒店完整信息（含房型列表、图文详情、价格等），自动注入静态地图图片URL用于详情页地图展示。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `hotelId` | `integer` | | 酒店ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 餐厅接口 - -### `GET` /mp/restaurant/list - -**餐厅列表** - -分页查询已上架的餐厅列表，支持按关键词和城市筛选。聚合层透传resource-service的餐厅数据。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `city` | `string` | | 城市 | | -| `keyword` | `string` | | 关键词 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/restaurant/{restaurantId} - -**餐厅详情** - -获取餐厅完整信息（含菜品、图文详情等），自动注入静态地图图片URL用于详情页地图展示。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `restaurantId` | `integer` | | 餐厅ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 首页接口 - -### `GET` /mp/home - -**首页数据** - -聚合流程：并行获取推荐产品列表+产品线列表+轮播图 → Redis缓存5分钟 → 返回聚合数据 - -**关联字典（BFF透传）**： -- product_type：产品类型（产品卡片显示） -- product_status：产品状态（透传自product-service） - -**响应** `统一响应结果«首页聚合数据»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `首页聚合数据` | | 响应数据 | -|   `banners` | `Map«string,object»[]` | | 轮播图Banner列表 | -|   `contactInfo` | `Map«string,object»[]` | | 联系我们列表 | -|   `exploreTopics` | `Map«string,object»[]` | | 探索专题列表 | -|   `featuredDesigner` | `object` | | 推荐定制师 | -|   `featuredReviews` | `Map«string,object»[]` | | 首页精选评价列表 | -|   `productLines` | `Map«string,object»[]` | | 产品线分类列表 | -|   `recommendProducts` | `Map«string,object»[]` | | 推荐产品列表 | -| `message` | `string` | | 响应消息 | - ---- diff --git a/2026-03/17_0928/hl-order-service.md b/2026-03/17_0928/hl-order-service.md deleted file mode 100644 index ed3738c..0000000 --- a/2026-03/17_0928/hl-order-service.md +++ /dev/null @@ -1,3594 +0,0 @@ -# 订单服务 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_0928/hl-payment-service.md b/2026-03/17_0928/hl-payment-service.md deleted file mode 100644 index 9982afc..0000000 --- a/2026-03/17_0928/hl-payment-service.md +++ /dev/null @@ -1,282 +0,0 @@ -# 支付服务 API 文档 - -**服务**: `hl-payment-service` -**接口总数**: 7 - -## 目录 - -- **支付管理** (7 个接口) - ---- - -## 支付管理 - -### `GET` /admin/payment/list - -**支付交易列表** - -分页查询支付交易记录，支持按订单号、交易状态、交易类型筛选 - -**关联字典**： -- payment_mode：支付模式（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `endDate` | `string` | | 结束日期 | 2026-12-31 | -| `mchId` | `string` | | 商户号 | 1246532201 | -| `orderNo` | `string` | | 订单编号 | HL20260301120000001234 | -| `page` | `integer(int32)` | | 页码 | 1 | -| `pageSize` | `integer(int32)` | | 每页条数 | 20 | -| `startDate` | `string` | | 开始日期 | 2026-01-01 | -| `status` | `string` | | 支付状态 | SUCCESS | -| `tradeType` | `string` | | 交易类型: JSAPI/H5 | JSAPI | - -**响应** `统一响应结果«分页结果«支付交易信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«支付交易信息»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `支付交易信息[]` | | 数据列表 | -|     `createTime` | `string` | | 创建时间 | -|     `mchId` | `string` | | 商户号 | -|     `orderId` | `long` | | 订单ID | -|     `orderNo` | `string` | | 订单编号 | -|     `outTradeNo` | `string` | | 商户订单号 | -|     `payTime` | `string` | | 支付时间 | -|     `payType` | `string` | | 支付类型: FULL/DEPOSIT/BALANCE | -|     `status` | `string` | | 交易状态 | -|     `totalAmount` | `number` | | 交易金额 | -|     `tradeType` | `string` | | 交易类型: JSAPI/H5 | -|     `transactionId` | `long` | | 交易ID | -|     `transactionIdWx` | `string` | | 微信支付交易号 | -|     `userId` | `long` | | 用户ID | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/payment/order/{orderId} - -**按订单查询交易** - -查询指定订单的所有支付交易记录 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«List«支付交易信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `支付交易信息[]` | | 响应数据 | -|   `createTime` | `string` | | 创建时间 | -|   `mchId` | `string` | | 商户号 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `outTradeNo` | `string` | | 商户订单号 | -|   `payTime` | `string` | | 支付时间 | -|   `payType` | `string` | | 支付类型: FULL/DEPOSIT/BALANCE | -|   `status` | `string` | | 交易状态 | -|   `totalAmount` | `number` | | 交易金额 | -|   `tradeType` | `string` | | 交易类型: JSAPI/H5 | -|   `transactionId` | `long` | | 交易ID | -|   `transactionIdWx` | `string` | | 微信支付交易号 | -|   `userId` | `long` | | 用户ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/payment/refund/order/{orderId} - -**按订单查询退款** - -查询指定订单的所有退款记录 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«List«退款记录信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款记录信息[]` | | 响应数据 | -|   `createTime` | `string` | | 创建时间 | -|   `mchId` | `string` | | 商户号 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `outRefundNo` | `string` | | 商户退款单号 | -|   `reason` | `string` | | 退款原因 | -|   `refundAmount` | `number` | | 退款金额 | -|   `refundId` | `long` | | 退款ID | -|   `refundIdWx` | `string` | | 微信退款单号 | -|   `status` | `string` | | 退款状态 | -|   `successTime` | `string` | | 退款成功时间 | -|   `totalAmount` | `number` | | 订单总金额 | -|   `transactionId` | `long` | | 交易ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/payment/refund/{refundId} - -**退款详情** - -获取单笔退款记录的完整信息，包含微信退款单号和退款状态 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `refundId` | `integer` | | 退款ID | - -**响应** `统一响应结果«退款记录信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款记录信息` | | 响应数据 | -|   `createTime` | `string` | | 创建时间 | -|   `mchId` | `string` | | 商户号 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `outRefundNo` | `string` | | 商户退款单号 | -|   `reason` | `string` | | 退款原因 | -|   `refundAmount` | `number` | | 退款金额 | -|   `refundId` | `long` | | 退款ID | -|   `refundIdWx` | `string` | | 微信退款单号 | -|   `status` | `string` | | 退款状态 | -|   `successTime` | `string` | | 退款成功时间 | -|   `totalAmount` | `number` | | 订单总金额 | -|   `transactionId` | `long` | | 交易ID | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/payment/{orderId}/refund - -**发起退款** - -退款流程：验证订单 → 查找原支付交易 → 调用微信退款API → 记录退款单 → 等待微信回调更新状态 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**请求体** `退款请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `amount` | `number` | 是 | 退款金额 | -| `orderId` | `long` | 是 | 订单ID | -| `reason` | `string` | | 退款原因 | - -**响应** `统一响应结果«退款记录信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款记录信息` | | 响应数据 | -|   `createTime` | `string` | | 创建时间 | -|   `mchId` | `string` | | 商户号 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `outRefundNo` | `string` | | 商户退款单号 | -|   `reason` | `string` | | 退款原因 | -|   `refundAmount` | `number` | | 退款金额 | -|   `refundId` | `long` | | 退款ID | -|   `refundIdWx` | `string` | | 微信退款单号 | -|   `status` | `string` | | 退款状态 | -|   `successTime` | `string` | | 退款成功时间 | -|   `totalAmount` | `number` | | 订单总金额 | -|   `transactionId` | `long` | | 交易ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/payment/{transactionId} - -**交易详情** - -获取单笔交易的完整信息，包含微信支付流水号 - -**关联字典**： -- payment_mode：支付模式（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `transactionId` | `integer` | | 交易ID | - -**响应** `统一响应结果«支付交易信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `支付交易信息` | | 响应数据 | -|   `createTime` | `string` | | 创建时间 | -|   `mchId` | `string` | | 商户号 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `outTradeNo` | `string` | | 商户订单号 | -|   `payTime` | `string` | | 支付时间 | -|   `payType` | `string` | | 支付类型: FULL/DEPOSIT/BALANCE | -|   `status` | `string` | | 交易状态 | -|   `totalAmount` | `number` | | 交易金额 | -|   `tradeType` | `string` | | 交易类型: JSAPI/H5 | -|   `transactionId` | `long` | | 交易ID | -|   `transactionIdWx` | `string` | | 微信支付交易号 | -|   `userId` | `long` | | 用户ID | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/payment/{transactionId}/sync - -**同步支付状态** - -主动查询微信支付状态并同步本地数据，适用于回调未到达的场景 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `transactionId` | `integer` | | 交易ID | - -**响应** `统一响应结果«支付交易信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `支付交易信息` | | 响应数据 | -|   `createTime` | `string` | | 创建时间 | -|   `mchId` | `string` | | 商户号 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `outTradeNo` | `string` | | 商户订单号 | -|   `payTime` | `string` | | 支付时间 | -|   `payType` | `string` | | 支付类型: FULL/DEPOSIT/BALANCE | -|   `status` | `string` | | 交易状态 | -|   `totalAmount` | `number` | | 交易金额 | -|   `tradeType` | `string` | | 交易类型: JSAPI/H5 | -|   `transactionId` | `long` | | 交易ID | -|   `transactionIdWx` | `string` | | 微信支付交易号 | -|   `userId` | `long` | | 用户ID | -| `message` | `string` | | 响应消息 | - ---- diff --git a/2026-03/17_0928/hl-product-service.md b/2026-03/17_0928/hl-product-service.md deleted file mode 100644 index 06de89c..0000000 --- a/2026-03/17_0928/hl-product-service.md +++ /dev/null @@ -1,5188 +0,0 @@ -# 产品服务 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_0928/hl-resource-service.md b/2026-03/17_0928/hl-resource-service.md deleted file mode 100644 index 4bea593..0000000 --- a/2026-03/17_0928/hl-resource-service.md +++ /dev/null @@ -1,6998 +0,0 @@ -# 资源服务 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_0928/hl-review-service.md b/2026-03/17_0928/hl-review-service.md deleted file mode 100644 index dbb2fda..0000000 --- a/2026-03/17_0928/hl-review-service.md +++ /dev/null @@ -1,236 +0,0 @@ -# 评价服务 API 文档 - -**服务**: `hl-review-service` -**接口总数**: 6 - -## 目录 - -- **管理端-评价审核** (6 个接口) - ---- - -## 管理端-评价审核 - -### `GET` /admin/review/list - -**评价列表(支持好中差评/有图/有视频筛选)** - -分页查询全部评价（含待审核/已通过/已拒绝），支持按评价等级、是否有图/视频、目标类型筛选 - -**关联字典**： -- review_status：评价审核状态（列表筛选+显示） -- rating_level：评价等级（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `hasImage` | `boolean` | | 是否有图片: true/false | | -| `hasVideo` | `boolean` | | 是否有视频: true/false | | -| `keyword` | `string` | | 搜索关键词 | 风景 | -| `maxRating` | `integer(int32)` | | 最高评分(整体满意度) | 5 | -| `minRating` | `integer(int32)` | | 最低评分(整体满意度) | 3 | -| `page` | `integer(int32)` | | 页码 | 1 | -| `pageSize` | `integer(int32)` | | 每页条数 | 20 | -| `productType` | `string` | | 产品类型（字典 review_product_type） | CORE | -| `ratingLevel` | `string` | | 评价等级: GOOD/MEDIUM/BAD | GOOD | -| `reviewType` | `string` | | 评论类型（字典 review_type） | PRODUCT | -| `status` | `string` | | 评价状态 | APPROVED | -| `targetId` | `integer(int64)` | | 评价目标ID | 2001 | -| `targetType` | `string` | | 评价目标类型 | PRODUCT | - -**响应** `统一响应结果«分页结果«评价列表项(管理端)»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«评价列表项(管理端)»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `评价列表项(管理端)[]` | | 数据列表 | -|     `auditedAt` | `string` | | 审核时间 | -|     `auditorName` | `string` | | 审核人姓名 | -|     `content` | `string` | | 评价内容 | -|     `createdAt` | `string` | | 创建时间 | -|     `hasReply` | `boolean` | | 是否已回复 | -|     `imageCount` | `int` | | 图片数量 | -|     `orderId` | `string` | | 订单ID | -|     `orderNo` | `string` | | 订单编号 | -|     `productType` | `string` | | 产品类型 | -|     `productTypeLabel` | `string` | | 产品类型标签 | -|     `ratingAccommodation` | `int` | | 住宿安排评分(1-5) | -|     `ratingDining` | `int` | | 餐饮质量评分(1-5) | -|     `ratingDriver` | `int` | | 司机服务评分(1-5) | -|     `ratingItinerary` | `int` | | 行程安排评分(1-5) | -|     `ratingLevel` | `string` | | 评价等级: GOOD/MEDIUM/BAD | -|     `ratingLevelLabel` | `string` | | 评价等级标签 | -|     `ratingOverall` | `int` | | 整体满意度评分(1-5) | -|     `rejectReason` | `string` | | 拒绝原因 | -|     `reviewId` | `string` | | 评价ID | -|     `reviewType` | `string` | | 评论类型 | -|     `reviewTypeLabel` | `string` | | 评论类型标签 | -|     `status` | `string` | | 评价状态 | -|     `statusLabel` | `string` | | 评价状态标签 | -|     `targetId` | `string` | | 评价目标ID | -|     `targetName` | `string` | | 评价目标名称 | -|     `targetType` | `string` | | 评价目标类型 | -|     `targetTypeLabel` | `string` | | 评价目标类型标签 | -|     `userAvatar` | `string` | | 用户头像 | -|     `userNickname` | `string` | | 用户昵称 | -|     `videoCount` | `int` | | 视频数量 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/review/{reviewId} - -**评价详情** - -**关联字典**： -- review_status：评价审核状态（显示） -- rating_level：评价等级（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reviewId` | `integer` | | 评价ID | - -**响应** `统一响应结果«评价详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `评价详情` | | 响应数据 | -|   `adminReply` | `string` | | 管理员回复内容 | -|   `adminReplyAt` | `string` | | 回复时间 | -|   `adminReplyName` | `string` | | 回复管理员姓名 | -|   `auditedAt` | `string` | | 审核时间 | -|   `auditorAdminId` | `string` | | 审核人ID | -|   `auditorName` | `string` | | 审核人姓名 | -|   `content` | `string` | | 评价内容 | -|   `createdAt` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期(冗余自订单) | -|   `hasImage` | `boolean` | | 是否有图片 | -|   `hasVideo` | `boolean` | | 是否有视频 | -|   `imageCount` | `int` | | 图片数量 | -|   `images` | `评价图片信息[]` | | 评价图片列表 | -|     `fileId` | `string` | | 文件ID | -|     `imageId` | `string` | | 图片ID | -|     `imageUrl` | `string` | | 图片URL | -|     `sortOrder` | `int` | | 排序序号 | -|   `machineResult` | `string` | | 机审结果 | -|   `orderId` | `string` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `productType` | `string` | | 产品类型 | -|   `productTypeLabel` | `string` | | 产品类型标签 | -|   `ratingAccommodation` | `int` | | 住宿安排评分(1-5) | -|   `ratingDining` | `int` | | 餐饮质量评分(1-5) | -|   `ratingDriver` | `int` | | 司机服务评分(1-5) | -|   `ratingItinerary` | `int` | | 行程安排评分(1-5) | -|   `ratingLevel` | `string` | | 评价等级: GOOD/MEDIUM/BAD | -|   `ratingLevelLabel` | `string` | | 评价等级标签: 好评/中评/差评 | -|   `ratingOverall` | `int` | | 整体满意度评分(1-5) | -|   `rejectReason` | `string` | | 拒绝原因 | -|   `reviewId` | `string` | | 评价ID | -|   `reviewType` | `string` | | 评论类型 | -|   `reviewTypeLabel` | `string` | | 评论类型标签 | -|   `status` | `string` | | 评价状态 | -|   `statusLabel` | `string` | | 评价状态标签 | -|   `targetId` | `string` | | 评价目标ID | -|   `targetName` | `string` | | 评价目标名称 | -|   `targetType` | `string` | | 评价目标类型 | -|   `targetTypeLabel` | `string` | | 评价目标类型标签 | -|   `userAvatar` | `string` | | 用户头像 | -|   `userId` | `string` | | 用户ID | -|   `userNickname` | `string` | | 用户昵称 | -|   `videoCount` | `int` | | 视频数量 | -|   `videos` | `评价视频信息[]` | | 评价视频列表 | -|     `coverUrl` | `string` | | 视频封面URL | -|     `duration` | `int` | | 视频时长(秒) | -|     `fileId` | `string` | | 文件ID | -|     `sortOrder` | `int` | | 排序序号 | -|     `videoId` | `string` | | 视频ID | -|     `videoUrl` | `string` | | 视频URL | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/review/{reviewId}/approve - -**通过评价** - -审核通过评价，通过后评价在小程序端公开展示。状态流转：PENDING_REVIEW → APPROVED - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reviewId` | `integer` | | 评价ID | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /admin/review/{reviewId}/override-approve - -**覆盖通过(机器拒绝的)** - -对阿里云内容审核自动拒绝的评价进行人工覆盖通过。状态流转：AUTO_REJECTED → APPROVED - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reviewId` | `integer` | | 评价ID | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /admin/review/{reviewId}/reject - -**拒绝评价** - -审核拒绝评价，需填写拒绝原因。拒绝后评价不公开展示。状态流转：PENDING_REVIEW → REJECTED - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reviewId` | `integer` | | 评价ID | - -**请求体** `拒绝评价请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `rejectReason` | `string` | 是 | 拒绝原因 | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /admin/review/{reviewId}/reply - -**回复评价(每条评价仅可回复一次)** - -管理员回复用户评价，回复内容在小程序端公开展示。每条评价仅允许回复一次，不可修改。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reviewId` | `integer` | | 评价ID | - -**请求体** `管理员回复请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `replyContent` | `string` | 是 | 回复内容 | - -**响应** `统一响应结果«Void»` - ---- diff --git a/2026-03/17_0928/hl-task-service.md b/2026-03/17_0928/hl-task-service.md deleted file mode 100644 index 0631450..0000000 --- a/2026-03/17_0928/hl-task-service.md +++ /dev/null @@ -1,924 +0,0 @@ -# 任务服务 API 文档 - -**服务**: `hl-task-service` -**接口总数**: 27 - -## 目录 - -- **WebSocket 实时推送** (1 个接口) -- **任务看板管理** (13 个接口) -- **任务管理** (13 个接口) - ---- - -## WebSocket 实时推送 - -### `GET` /admin/task/board/ws-doc/info - -**WebSocket 连接说明** - -## 连接信息 - -| 项目 | 值 | -|------|-------| -| **连接地址** | `ws://{host}:8092/ws/task` | -| **协议** | STOMP over WebSocket（SockJS 降级方案） | -| **跨域** | 允许所有源 (`*`) | - -## 订阅频道 - -| 订阅地址 | 说明 | -|------------|-------------| -| `/topic/board/{boardId}` | 订阅指定看板，接收该看板下的实时任务事件 | - -## 推送消息格式 - -```json -{ - "event": "TASK_CREATED", - "data": { ... }, - "timestamp": 1709539200000 -} -``` - -## 事件类型 - -| 事件 | 说明 | data 内容 | -|-------|------------|------| -| TASK_CREATED | 任务创建 | 任务对象 | -| TASK_UPDATED | 任务更新 | 任务对象 | -| TASK_DELETED | 任务删除 | 任务ID | -| TASK_MOVED | 任务移动（状态变更） | 任务对象 | -| COMMENT_ADDED | 新增评论 | 评论对象 | - -## 前端接入示例 (SockJS + STOMP) - -```javascript -import SockJS from 'sockjs-client' -import { Stomp } from '@stomp/stompjs' - -const socket = new SockJS('http://localhost:8092/ws/task') -const stompClient = Stomp.over(socket) - -stompClient.connect({}, () => { - stompClient.subscribe('/topic/board/123', (msg) => { - const { event, data, timestamp } = JSON.parse(msg.body) - console.log('Event:', event, 'Data:', data) - }) -}) -``` - -**响应** `object` - ---- - -## 任务看板管理 - -### `POST` /admin/task/board - -**创建自定义看板** - -创建自定义看板，自动添加创建者为看板成员，并创建默认状态列（待办、进行中、已完成）。 - -**权限**：需管理员登录。 - -**请求体** `创建看板请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardName` | `string` | 是 | 看板名称 | -| `deptId` | `long` | | 部门ID | -| `description` | `string` | | 看板描述 | -| `memberIds` | `long[]` | | 成员ID列表 | - -**响应** `统一响应结果«看板信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板信息` | | 响应数据 | -|   `boardId` | `long` | | 看板ID | -|   `boardName` | `string` | | 看板名称 | -|   `boardType` | `string` | | 看板类型 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `deptId` | `long` | | 部门ID | -|   `deptName` | `string` | | 部门名称 | -|   `description` | `string` | | 看板描述 | -|   `statuses` | `看板状态信息[]` | | 状态列表 | -|     `isPreset` | `boolean` | | 是否预设状态 | -|     `sortOrder` | `int` | | 排序序号 | -|     `statusColor` | `string` | | 状态颜色 | -|     `statusId` | `long` | | 状态ID | -|     `statusName` | `string` | | 状态名称 | -|     `taskCount` | `int` | | 该状态下的任务数量 | -|   `taskCount` | `int` | | 任务总数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/task/board/{boardId} - -**看板详情** - -返回看板基本信息（名称、描述、创建者），不含任务数据。查看任务请使用「获取看板任务」接口 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**响应** `统一响应结果«看板信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板信息` | | 响应数据 | -|   `boardId` | `long` | | 看板ID | -|   `boardName` | `string` | | 看板名称 | -|   `boardType` | `string` | | 看板类型 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `deptId` | `long` | | 部门ID | -|   `deptName` | `string` | | 部门名称 | -|   `description` | `string` | | 看板描述 | -|   `statuses` | `看板状态信息[]` | | 状态列表 | -|     `isPreset` | `boolean` | | 是否预设状态 | -|     `sortOrder` | `int` | | 排序序号 | -|     `statusColor` | `string` | | 状态颜色 | -|     `statusId` | `long` | | 状态ID | -|     `statusName` | `string` | | 状态名称 | -|     `taskCount` | `int` | | 该状态下的任务数量 | -|   `taskCount` | `int` | | 任务总数 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/task/board/{boardId} - -**更新看板** - -更新看板的名称和描述。仅看板创建者或超级管理员可操作。 - -**权限**：需管理员登录，且为看板创建者或超级管理员。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**请求体** `更新看板请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardName` | `string` | | 看板名称 | -| `description` | `string` | | 看板描述 | - -**响应** `统一响应结果«看板信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板信息` | | 响应数据 | -|   `boardId` | `long` | | 看板ID | -|   `boardName` | `string` | | 看板名称 | -|   `boardType` | `string` | | 看板类型 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `deptId` | `long` | | 部门ID | -|   `deptName` | `string` | | 部门名称 | -|   `description` | `string` | | 看板描述 | -|   `statuses` | `看板状态信息[]` | | 状态列表 | -|     `isPreset` | `boolean` | | 是否预设状态 | -|     `sortOrder` | `int` | | 排序序号 | -|     `statusColor` | `string` | | 状态颜色 | -|     `statusId` | `long` | | 状态ID | -|     `statusName` | `string` | | 状态名称 | -|     `taskCount` | `int` | | 该状态下的任务数量 | -|   `taskCount` | `int` | | 任务总数 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/task/board/{boardId} - -**删除看板** - -删除看板及其下所有状态列和任务（级联删除）。仅看板创建者或超级管理员可操作 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**响应** `统一响应结果«Void»` - ---- - -### `DELETE` /admin/task/board/{boardId}/member/{targetAdminId} - -**移除成员** - -从看板中移除指定成员。仅看板创建者或超级管理员可操作，不能移除创建者自己 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | -| `targetAdminId` | `integer` | | 目标管理员ID | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/task/board/{boardId}/members - -**获取看板成员** - -返回看板的所有成员列表，包含成员的管理员ID和姓名 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**响应** `统一响应结果«List«看板成员信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板成员信息[]` | | 响应数据 | -|   `adminId` | `long` | | 管理员ID | -|   `avatarUrl` | `string` | | 头像地址 | -|   `joinedAt` | `string` | | 加入时间 | -|   `role` | `string` | | 角色: OWNER/MEMBER | -|   `username` | `string` | | 用户名 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/task/board/{boardId}/members - -**添加成员** - -批量添加管理员为看板成员，成为成员后可以查看看板、创建和操作任务。 - -**权限**：需管理员登录，且为看板创建者或超级管理员。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**请求体** `添加成员请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `adminIds` | `long[]` | 是 | 管理员ID列表 | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /admin/task/board/{boardId}/status - -**创建状态列** - -在看板中创建新的状态列（如测试中、待发布等），自动排到末尾。任务通过拖拽在不同状态列间流转。 - -**权限**：需管理员登录且为看板成员。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**请求体** `创建状态请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `statusColor` | `string` | | 状态颜色 | -| `statusName` | `string` | 是 | 状态名称 | - -**响应** `统一响应结果«看板状态信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板状态信息` | | 响应数据 | -|   `isPreset` | `boolean` | | 是否预设状态 | -|   `sortOrder` | `int` | | 排序序号 | -|   `statusColor` | `string` | | 状态颜色 | -|   `statusId` | `long` | | 状态ID | -|   `statusName` | `string` | | 状态名称 | -|   `taskCount` | `int` | | 该状态下的任务数量 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/task/board/{boardId}/status/sort - -**状态列排序** - -批量更新状态列的排序顺序。传入状态列ID数组，数组下标即为新的排序值。操作完成后通过WebSocket推送STATUS_REORDERED事件 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**请求体** `状态排序请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `statusIds` | `long[]` | 是 | 状态ID列表(按排序顺序) | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/task/board/{boardId}/statuses - -**获取看板状态列** - -返回看板的所有状态列（如待办、进行中、已完成），按排序字段升序排列。拖拽任务到不同状态列实现状态流转 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**响应** `统一响应结果«List«看板状态信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板状态信息[]` | | 响应数据 | -|   `isPreset` | `boolean` | | 是否预设状态 | -|   `sortOrder` | `int` | | 排序序号 | -|   `statusColor` | `string` | | 状态颜色 | -|   `statusId` | `long` | | 状态ID | -|   `statusName` | `string` | | 状态名称 | -|   `taskCount` | `int` | | 该状态下的任务数量 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/task/boards - -**获取可见看板列表** - -返回当前管理员可见的看板列表：超级管理员可见所有看板，普通管理员仅可见自己创建的或作为成员的看板 - -**响应** `统一响应结果«List«看板信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板信息[]` | | 响应数据 | -|   `boardId` | `long` | | 看板ID | -|   `boardName` | `string` | | 看板名称 | -|   `boardType` | `string` | | 看板类型 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `deptId` | `long` | | 部门ID | -|   `deptName` | `string` | | 部门名称 | -|   `description` | `string` | | 看板描述 | -|   `statuses` | `看板状态信息[]` | | 状态列表 | -|     `isPreset` | `boolean` | | 是否预设状态 | -|     `sortOrder` | `int` | | 排序序号 | -|     `statusColor` | `string` | | 状态颜色 | -|     `statusId` | `long` | | 状态ID | -|     `statusName` | `string` | | 状态名称 | -|     `taskCount` | `int` | | 该状态下的任务数量 | -|   `taskCount` | `int` | | 任务总数 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/task/status/{statusId} - -**更新状态列** - -更新状态列的名称和颜色。 - -**权限**：需管理员登录且为看板成员。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `statusId` | `integer` | | 状态列ID | - -**请求体** `更新状态请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `statusColor` | `string` | | 状态颜色 | -| `statusName` | `string` | | 状态名称 | - -**响应** `统一响应结果«看板状态信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板状态信息` | | 响应数据 | -|   `isPreset` | `boolean` | | 是否预设状态 | -|   `sortOrder` | `int` | | 排序序号 | -|   `statusColor` | `string` | | 状态颜色 | -|   `statusId` | `long` | | 状态ID | -|   `statusName` | `string` | | 状态名称 | -|   `taskCount` | `int` | | 该状态下的任务数量 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/task/status/{statusId} - -**删除状态列** - -删除看板的状态列。如果状态列下有任务则不允许删除，需先移动或删除任务 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `statusId` | `integer` | | 状态列ID | - -**响应** `统一响应结果«Void»` - ---- - -## 任务管理 - -### `POST` /admin/task - -**创建任务** - -在指定看板和状态列下创建任务。创建成功后通过WebSocket推送TASK_CREATED事件，并通知被分配的负责人 - -**关联字典**： -- task_priority：任务优先级（创建时选择） - -**请求体** `创建任务请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `assigneeIds` | `long[]` | | 负责人ID列表 | -| `boardId` | `long` | 是 | 看板ID | -| `description` | `string` | | 任务描述 | -| `dueDate` | `string` | | 截止日期 | -| `priority` | `string` | | 优先级: LOW/MEDIUM/HIGH/URGENT | -| `statusId` | `long` | | 状态ID | -| `title` | `string` | 是 | 任务标题 | - -**响应** `统一响应结果«任务信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `任务信息` | | 响应数据 | -|   `assignees` | `负责人信息[]` | | 负责人列表 | -|     `adminId` | `long` | | 管理员ID | -|     `avatarUrl` | `string` | | 头像地址 | -|     `username` | `string` | | 用户名 | -|     `wechatName` | `string` | | 企微昵称 | -|   `boardId` | `long` | | 看板ID | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 任务描述 | -|   `dueDate` | `string` | | 截止日期 | -|   `overdue` | `boolean` | | 是否逾期 | -|   `parentId` | `long` | | 父任务ID | -|   `priority` | `string` | | 优先级: LOW/MEDIUM/HIGH/URGENT | -|   `sortOrder` | `int` | | 排序序号 | -|   `statusColor` | `string` | | 状态颜色 | -|   `statusId` | `long` | | 状态ID | -|   `statusName` | `string` | | 状态名称 | -|   `subtaskCompleted` | `int` | | 已完成子任务数 | -|   `subtaskTotal` | `int` | | 子任务总数 | -|   `subtasks` | `子任务信息[]` | | 子任务列表 | -|     `completed` | `boolean` | | 是否已完成 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdBy` | `long` | | 创建人ID | -|     `creatorName` | `string` | | 创建人姓名 | -|     `taskId` | `long` | | 子任务ID | -|     `title` | `string` | | 子任务标题 | -|   `taskId` | `long` | | 任务ID | -|   `title` | `string` | | 任务标题 | -|   `updatedAt` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/task/board/{boardId}/tasks - -**获取看板任务(按状态分组)** - -返回看板下所有任务，按状态列分组。支持按优先级(HIGH/MEDIUM/LOW)和负责人筛选，每组内按排序值升序排列 - -**关联字典**： -- task_priority：任务优先级（列表筛选+显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `assigneeId` | `integer(int64)` | | 负责人ID | | -| `priority` | `string` | | 优先级 | | - -**响应** `统一响应结果«List«看板任务分组信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板任务分组信息[]` | | 响应数据 | -|   `sortOrder` | `int` | | 排序序号 | -|   `statusColor` | `string` | | 状态颜色 | -|   `statusId` | `long` | | 状态ID | -|   `statusName` | `string` | | 状态名称 | -|   `tasks` | `任务信息[]` | | 该状态下的任务列表 | -|     `assignees` | `负责人信息[]` | | 负责人列表 | -|     `boardId` | `long` | | 看板ID | -|     `createdAt` | `string` | | 创建时间 | -|     `createdBy` | `long` | | 创建人ID | -|     `creatorName` | `string` | | 创建人姓名 | -|     `description` | `string` | | 任务描述 | -|     `dueDate` | `string` | | 截止日期 | -|     `overdue` | `boolean` | | 是否逾期 | -|     `parentId` | `long` | | 父任务ID | -|     `priority` | `string` | | 优先级: LOW/MEDIUM/HIGH/URGENT | -|     `sortOrder` | `int` | | 排序序号 | -|     `statusColor` | `string` | | 状态颜色 | -|     `statusId` | `long` | | 状态ID | -|     `statusName` | `string` | | 状态名称 | -|     `subtaskCompleted` | `int` | | 已完成子任务数 | -|     `subtaskTotal` | `int` | | 子任务总数 | -|     `subtasks` | `子任务信息[]` | | 子任务列表 | -|     `taskId` | `long` | | 任务ID | -|     `title` | `string` | | 任务标题 | -|     `updatedAt` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/task/comment/{commentId} - -**删除评论** - -仅评论作者本人可删除自己的评论，系统自动生成的活动记录不可删除 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `commentId` | `integer` | | 评论ID | - -**响应** `统一响应结果«Void»` - ---- - -### `DELETE` /admin/task/subtask/{subtaskId} - -**删除子任务** - -删除指定子任务。 - -**权限**：需管理员登录且为看板成员。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `subtaskId` | `integer` | | 子任务ID | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/task/subtask/{subtaskId}/toggle - -**切换子任务完成状态** - -切换子任务的完成/未完成状态（toggle），完成状态切换会自动记录到任务时间线 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `subtaskId` | `integer` | | 子任务ID | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/task/{taskId} - -**任务详情** - -返回任务完整信息，包含子任务列表、负责人信息、附件列表等 - -**关联字典**： -- task_priority：任务优先级（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**响应** `统一响应结果«任务信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `任务信息` | | 响应数据 | -|   `assignees` | `负责人信息[]` | | 负责人列表 | -|     `adminId` | `long` | | 管理员ID | -|     `avatarUrl` | `string` | | 头像地址 | -|     `username` | `string` | | 用户名 | -|     `wechatName` | `string` | | 企微昵称 | -|   `boardId` | `long` | | 看板ID | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 任务描述 | -|   `dueDate` | `string` | | 截止日期 | -|   `overdue` | `boolean` | | 是否逾期 | -|   `parentId` | `long` | | 父任务ID | -|   `priority` | `string` | | 优先级: LOW/MEDIUM/HIGH/URGENT | -|   `sortOrder` | `int` | | 排序序号 | -|   `statusColor` | `string` | | 状态颜色 | -|   `statusId` | `long` | | 状态ID | -|   `statusName` | `string` | | 状态名称 | -|   `subtaskCompleted` | `int` | | 已完成子任务数 | -|   `subtaskTotal` | `int` | | 子任务总数 | -|   `subtasks` | `子任务信息[]` | | 子任务列表 | -|     `completed` | `boolean` | | 是否已完成 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdBy` | `long` | | 创建人ID | -|     `creatorName` | `string` | | 创建人姓名 | -|     `taskId` | `long` | | 子任务ID | -|     `title` | `string` | | 子任务标题 | -|   `taskId` | `long` | | 任务ID | -|   `title` | `string` | | 任务标题 | -|   `updatedAt` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/task/{taskId} - -**更新任务** - -更新任务的标题、描述、优先级、截止日期、负责人等信息。更新后通过WebSocket推送TASK_UPDATED事件，如果修改了负责人则额外通知新负责人。 - -**权限**：需管理员登录且为看板成员。 - -**关联字典**： -- task_priority：任务优先级（编辑时选择） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**请求体** `更新任务请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `assigneeIds` | `long[]` | | 负责人ID列表 | -| `description` | `string` | | 任务描述 | -| `dueDate` | `string` | | 截止日期 | -| `priority` | `string` | | 优先级: LOW/MEDIUM/HIGH/URGENT | -| `title` | `string` | | 任务标题 | - -**响应** `统一响应结果«任务信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `任务信息` | | 响应数据 | -|   `assignees` | `负责人信息[]` | | 负责人列表 | -|     `adminId` | `long` | | 管理员ID | -|     `avatarUrl` | `string` | | 头像地址 | -|     `username` | `string` | | 用户名 | -|     `wechatName` | `string` | | 企微昵称 | -|   `boardId` | `long` | | 看板ID | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 任务描述 | -|   `dueDate` | `string` | | 截止日期 | -|   `overdue` | `boolean` | | 是否逾期 | -|   `parentId` | `long` | | 父任务ID | -|   `priority` | `string` | | 优先级: LOW/MEDIUM/HIGH/URGENT | -|   `sortOrder` | `int` | | 排序序号 | -|   `statusColor` | `string` | | 状态颜色 | -|   `statusId` | `long` | | 状态ID | -|   `statusName` | `string` | | 状态名称 | -|   `subtaskCompleted` | `int` | | 已完成子任务数 | -|   `subtaskTotal` | `int` | | 子任务总数 | -|   `subtasks` | `子任务信息[]` | | 子任务列表 | -|     `completed` | `boolean` | | 是否已完成 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdBy` | `long` | | 创建人ID | -|     `creatorName` | `string` | | 创建人姓名 | -|     `taskId` | `long` | | 子任务ID | -|     `title` | `string` | | 子任务标题 | -|   `taskId` | `long` | | 任务ID | -|   `title` | `string` | | 任务标题 | -|   `updatedAt` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/task/{taskId} - -**删除任务** - -删除任务及其所有子任务、评论和时间线记录（级联删除）。删除后通过WebSocket推送TASK_DELETED事件。 - -**权限**：需管理员登录且为看板成员。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /admin/task/{taskId}/comment - -**添加评论** - -在任务时间线中添加评论，添加后自动通知任务负责人 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**请求体** `创建评论请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `content` | `string` | 是 | 评论内容 | - -**响应** `统一响应结果«时间线条目»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `时间线条目` | | 响应数据 | -|   `action` | `string` | | 操作类型 | -|   `adminAvatar` | `string` | | 管理员头像 | -|   `adminId` | `long` | | 管理员ID | -|   `adminName` | `string` | | 管理员姓名 | -|   `content` | `string` | | 内容 | -|   `createdAt` | `string` | | 创建时间 | -|   `id` | `long` | | 条目ID | -|   `newValue` | `string` | | 新值 | -|   `oldValue` | `string` | | 旧值 | -|   `type` | `string` | | 类型: COMMENT/ACTIVITY | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/task/{taskId}/sort - -**任务排序** - -更新任务在同一状态列内的排序位置，用于拖拽排序 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**请求体** `任务排序请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `statusId` | `long` | 是 | 状态ID | -| `taskIds` | `long[]` | 是 | 任务ID列表(按排序顺序) | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/task/{taskId}/status - -**变更任务状态** - -将任务移动到指定状态列（拖拽操作），自动记录状态变更到时间线，并通过WebSocket推送TASK_STATUS_CHANGED事件 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**请求体** `变更任务状态请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `statusId` | `long` | 是 | 目标状态ID | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /admin/task/{taskId}/subtask - -**创建子任务** - -在指定任务下创建子任务（待办项），用于拆分任务的执行步骤。子任务默认为未完成状态。 - -**权限**：需管理员登录且为看板成员。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**请求体** `创建子任务请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `title` | `string` | 是 | 子任务标题 | - -**响应** `统一响应结果«子任务信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `子任务信息` | | 响应数据 | -|   `completed` | `boolean` | | 是否已完成 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `taskId` | `long` | | 子任务ID | -|   `title` | `string` | | 子任务标题 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/task/{taskId}/timeline - -**获取任务时间线** - -返回任务的完整操作记录，包含评论和系统自动记录的状态变更、人员分配等活动，按时间正序排列 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**响应** `统一响应结果«List«时间线条目»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `时间线条目[]` | | 响应数据 | -|   `action` | `string` | | 操作类型 | -|   `adminAvatar` | `string` | | 管理员头像 | -|   `adminId` | `long` | | 管理员ID | -|   `adminName` | `string` | | 管理员姓名 | -|   `content` | `string` | | 内容 | -|   `createdAt` | `string` | | 创建时间 | -|   `id` | `long` | | 条目ID | -|   `newValue` | `string` | | 新值 | -|   `oldValue` | `string` | | 旧值 | -|   `type` | `string` | | 类型: COMMENT/ACTIVITY | -| `message` | `string` | | 响应消息 | - ---- diff --git a/2026-03/17_0928/hl-user-service.md b/2026-03/17_0928/hl-user-service.md deleted file mode 100644 index 2978f52..0000000 --- a/2026-03/17_0928/hl-user-service.md +++ /dev/null @@ -1,4501 +0,0 @@ -# 用户服务 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/2026-03/17_0951/CHANGES.md b/2026-03/17_0951/CHANGES.md deleted file mode 100644 index 643dce0..0000000 --- a/2026-03/17_0951/CHANGES.md +++ /dev/null @@ -1,5 +0,0 @@ -# API 变更通知 - -**更新时间**: 2026-03-17 09:51 - -> 无变更 \ No newline at end of file diff --git a/2026-03/17_0951/hl-contract-service.md b/2026-03/17_0951/hl-contract-service.md deleted file mode 100644 index 7c4fc19..0000000 --- a/2026-03/17_0951/hl-contract-service.md +++ /dev/null @@ -1,793 +0,0 @@ -# 合同服务 API 文档 - -**服务**: `hl-contract-service` -**接口总数**: 18 - -## 目录 - -- **合同管理** (12 个接口) -- **补充约定模板管理** (6 个接口) - ---- - -## 合同管理 - -### `GET` /admin/contract/active-by-order/{orderId} - -**获取订单有效合同** - -返回订单当前有效的合同（非作废状态的最新合同），用于检查订单是否已有签署中或已签署的合同。 - -**权限**：需管理员登录。 - -**关联字典**： -- contract_status：合同状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«合同信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同信息` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/agencies - -**可用旅行社列表** - -返回系统配置的旅行社列表，创建合同时选择签约旅行社 - -**响应** `统一响应结果«List«旅行社信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `旅行社信息[]` | | 响应数据 | -|   `agencyAddress` | `string` | | 旅行社地址 | -|   `agencyName` | `string` | | 旅行社名称 | -|   `businessLicenseNumber` | `string` | | 营业执照号 | -|   `businessScope` | `string` | | 经营范围 | -|   `code` | `string` | | 旅行社编码 | -|   `licenseNumber` | `string` | | 旅行社许可证号 | -|   `regionId` | `string` | | 地区ID | -|   `transactorName` | `string` | | 经办人姓名 | -|   `transactorPhone` | `string` | | 经办人电话 | -|   `zjParentId` | `int` | | 属地管理机构ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/by-order/{orderId} - -**按订单查询合同** - -查询指定订单下的所有合同记录（含已作废），按创建时间倒序排列。用于订单详情页展示合同历史。 - -**权限**：需管理员登录。 - -**关联字典**： -- contract_status：合同状态（列表显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«List«合同信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同信息[]` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/contract/create - -**创建合同(标准模式)** - -标准电子签约流程：创建合同 → 平台生成合同PDF → 发送签署短信给出行人 → 出行人在线签署 → 回调更新状态。状态流转：CREATED → SIGNING → SIGNED - -**请求体** `创建合同请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `adultCost` | `number` | 是 | 成人费用 | -| `agencyCode` | `string` | | 旅行社编号（可选，默认使用配置值） | -| `childCost` | `number` | | 儿童费用 | -| `contactName` | `string` | 是 | 联系人姓名 | -| `contactPhone` | `string` | 是 | 联系人电话 | -| `contractType` | `string` | | 合同类型: TOUR-旅游合同(默认), INSURANCE-保险单 | -| `days` | `int` | | 行程天数 | -| `departureCity` | `string` | | 出发城市 | -| `departureDate` | `string` | 是 | 出发日期 | -| `destination` | `string` | 是 | 目的地 | -| `disputeResolution` | `int` | | 争议解决方式: 1-仲裁 2-诉讼 | -| `groupId` | `string` | | 团号 | -| `leastCustomerNumber` | `int` | | 最低成团人数 | -| `nights` | `int` | | 住宿晚数 | -| `orderId` | `long` | | 订单ID | -| `paymentMethod` | `int` | | 付款方式: 1-现金 2-转账 3-在线 | -| `returnDate` | `string` | 是 | 返回日期 | -| `routeName` | `string` | 是 | 线路名称 | -| `signatoryIdNumber` | `string` | 是 | 签署人证件号码 | -| `signatoryIdType` | `int` | | 签署人证件类型: 1-身份证 | -| `signatoryMode` | `int` | | 签署模式: 1-短信 2-现场 3-线下 | -| `signatoryName` | `string` | 是 | 签署人姓名 | -| `signatoryPhone` | `string` | 是 | 签署人电话 | -| `signingPlace` | `string` | | 签约地点 | -| `supplementaryClause` | `string` | | 补充约定内容 | -| `templateCode` | `string` | 是 | 模板编码 | -| `totalAmount` | `number` | 是 | 合同总金额 | -| `transactorName` | `string` | | 经办人姓名 | -| `transactorPhone` | `string` | | 经办人电话 | -| `travelers` | `合同出行人请求[]` | 是 | 出行人列表 | -|   `age` | `int` | | 年龄 | -|   `gender` | `string` | | 性别: male/female | -|   `health` | `string` | | 健康信息 | -|   `idCardNo` | `string` | 是 | 证件号码 | -|   `idCardType` | `int` | | 证件类型: 1-身份证 2-护照 | -|   `isChild` | `boolean` | | 是否儿童 | -|   `isSigner` | `boolean` | | 是否签署人 | -|   `name` | `string` | 是 | 姓名 | -|   `phone` | `string` | | 手机号 | -| `vehicleModel` | `string` | | 车型名称(产品快照) | - -**响应** `统一响应结果«合同详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同详情` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `statusLogs` | `合同状态变更日志[]` | | 状态变更日志 | -|     `createTime` | `string` | | 创建时间 | -|     `logId` | `long` | | 日志ID | -|     `newStatus` | `string` | | 新状态 | -|     `oldStatus` | `string` | | 旧状态 | -|     `source` | `string` | | 变更来源 | -|   `supplementaryClause` | `string` | | 补充约定内容 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -|   `travelers` | `合同出行人信息[]` | | 出行人列表 | -|     `idCardNo` | `string` | | 证件号码 | -|     `idCardType` | `string` | | 证件类型 | -|     `isSigner` | `boolean` | | 是否签署人 | -|     `name` | `string` | | 姓名 | -|     `phone` | `string` | | 手机号 | -|     `travelerId` | `long` | | 出行人ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/list - -**合同列表** - -分页查询合同记录，支持按订单号、合同状态、旅行社筛选 - -**关联字典**： -- contract_status：合同状态（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `orderId` | `integer(int64)` | | 订单ID | 1001 | -| `page` | `integer(int32)` | | 页码 | 1 | -| `pageSize` | `integer(int32)` | | 每页条数 | 20 | -| `platform` | `string` | | 签约平台 | TOURAGE | -| `status` | `string` | | 合同状态 | SIGNED | - -**响应** `统一响应结果«分页结果«合同信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«合同信息»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `合同信息[]` | | 数据列表 | -|     `agencyCode` | `string` | | 旅行社编号 | -|     `contactName` | `string` | | 联系人姓名 | -|     `contactPhone` | `string` | | 联系人电话 | -|     `contractId` | `long` | | 合同ID | -|     `contractNumber` | `string` | | 合同编号 | -|     `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|     `createTime` | `string` | | 创建时间 | -|     `departureDate` | `string` | | 出发日期 | -|     `destination` | `string` | | 目的地 | -|     `fileUrl` | `string` | | 合同文件URL | -|     `mode` | `string` | | 签约模式: STANDARD/SYNC | -|     `orderId` | `long` | | 订单ID | -|     `platform` | `string` | | 签约平台 | -|     `qrCodeUrl` | `string` | | 二维码URL | -|     `returnDate` | `string` | | 返回日期 | -|     `signUrl` | `string` | | 签署URL | -|     `status` | `string` | | 合同状态 | -|     `statusLabel` | `string` | | 合同状态标签 | -|     `templateCode` | `string` | | 模板编码 | -|     `templateName` | `string` | | 模板名称 | -|     `totalAmount` | `number` | | 合同总金额 | -|     `touristCount` | `int` | | 出行人数 | -|     `travelAgencyName` | `string` | | 旅行社名称 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/contract/report - -**报备合同(同步模式)** - -线下签约模式：创建合同记录 → 管理员上传已签署的PDF → 同步到12301报备平台。状态流转：CREATED → UPLOADED → REPORTED - -**请求体** `报备合同请求（同步模式）` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `adultCost` | `number` | 是 | 成人费用 | -| `agencyCode` | `string` | | 旅行社编号 | -| `childCost` | `number` | | 儿童费用 | -| `contactName` | `string` | 是 | 联系人姓名 | -| `contactPhone` | `string` | 是 | 联系人电话 | -| `contractType` | `string` | | 合同类型: TOUR-旅游合同(默认), INSURANCE-保险单 | -| `days` | `int` | | 行程天数 | -| `departureCity` | `string` | | 出发城市 | -| `departureDate` | `string` | 是 | 出发日期 | -| `destination` | `string` | 是 | 目的地 | -| `disputeResolution` | `int` | | 争议解决方式: 1-仲裁 2-诉讼 | -| `groupId` | `string` | | 团号 | -| `leastCustomerNumber` | `int` | | 最低成团人数 | -| `nights` | `int` | | 住宿晚数 | -| `orderId` | `long` | | 订单ID | -| `paymentMethod` | `int` | | 付款方式: 1-现金 2-转账 3-在线 | -| `returnDate` | `string` | 是 | 返回日期 | -| `routeName` | `string` | 是 | 线路名称 | -| `signatoryIdNumber` | `string` | 是 | 签署人证件号码 | -| `signatoryIdType` | `int` | | 签署人证件类型: 1-身份证 | -| `signatoryMode` | `int` | | 签署模式（同步模式默认2-现场） | -| `signatoryName` | `string` | 是 | 签署人姓名 | -| `signatoryPhone` | `string` | 是 | 签署人电话 | -| `signingPlace` | `string` | | 签约地点 | -| `supplementaryClause` | `string` | | 补充约定内容 | -| `templateCode` | `string` | 是 | 模板编码 | -| `totalAmount` | `number` | 是 | 合同总金额 | -| `transactorName` | `string` | | 经办人姓名 | -| `transactorPhone` | `string` | | 经办人电话 | -| `travelers` | `合同出行人请求[]` | 是 | 出行人列表 | -|   `age` | `int` | | 年龄 | -|   `gender` | `string` | | 性别: male/female | -|   `health` | `string` | | 健康信息 | -|   `idCardNo` | `string` | 是 | 证件号码 | -|   `idCardType` | `int` | | 证件类型: 1-身份证 2-护照 | -|   `isChild` | `boolean` | | 是否儿童 | -|   `isSigner` | `boolean` | | 是否签署人 | -|   `name` | `string` | 是 | 姓名 | -|   `phone` | `string` | | 手机号 | - -**响应** `统一响应结果«合同详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同详情` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `statusLogs` | `合同状态变更日志[]` | | 状态变更日志 | -|     `createTime` | `string` | | 创建时间 | -|     `logId` | `long` | | 日志ID | -|     `newStatus` | `string` | | 新状态 | -|     `oldStatus` | `string` | | 旧状态 | -|     `source` | `string` | | 变更来源 | -|   `supplementaryClause` | `string` | | 补充约定内容 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -|   `travelers` | `合同出行人信息[]` | | 出行人列表 | -|     `idCardNo` | `string` | | 证件号码 | -|     `idCardType` | `string` | | 证件类型 | -|     `isSigner` | `boolean` | | 是否签署人 | -|     `name` | `string` | | 姓名 | -|     `phone` | `string` | | 手机号 | -|     `travelerId` | `long` | | 出行人ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/templates - -**合同模板列表** - -返回合同平台可用的合同模板列表，创建合同时选择模板 - -**响应** `统一响应结果«List«合同模板信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同模板信息[]` | | 响应数据 | -|   `createTime` | `string` | | 创建时间 | -|   `description` | `string` | | 模板描述 | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `platform` | `string` | | 签约平台 | -|   `status` | `string` | | 模板状态 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateId` | `long` | | 模板ID | -|   `templateName` | `string` | | 模板名称 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/{id} - -**合同详情** - -**关联字典**： -- contract_status：合同状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 合同ID | - -**响应** `统一响应结果«合同详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同详情` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `statusLogs` | `合同状态变更日志[]` | | 状态变更日志 | -|     `createTime` | `string` | | 创建时间 | -|     `logId` | `long` | | 日志ID | -|     `newStatus` | `string` | | 新状态 | -|     `oldStatus` | `string` | | 旧状态 | -|     `source` | `string` | | 变更来源 | -|   `supplementaryClause` | `string` | | 补充约定内容 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -|   `travelers` | `合同出行人信息[]` | | 出行人列表 | -|     `idCardNo` | `string` | | 证件号码 | -|     `idCardType` | `string` | | 证件类型 | -|     `isSigner` | `boolean` | | 是否签署人 | -|     `name` | `string` | | 姓名 | -|     `phone` | `string` | | 手机号 | -|     `travelerId` | `long` | | 出行人ID | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/contract/{id}/invalidate - -**作废合同** - -将合同标记为作废状态（不可恢复）。作废后该合同不再有效，可重新为订单创建新合同 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 合同ID | - -**响应** `统一响应结果«合同信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同信息` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/contract/{id}/resend-sms - -**重发签署短信** - -重新发送签署短信给出行人，用于签署短信过期或未收到的场景。仅SIGNING状态的合同可操作 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 合同ID | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/{id}/status - -**刷新合同状态(从平台同步)** - -主动查询合同平台的最新签署状态并同步到本地，适用于回调未到达的场景 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 合同ID | - -**响应** `统一响应结果«合同信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同信息` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/contract/{id}/upload-pdf - -**上传已签署PDF(同步模式)** - -同步模式专用：上传线下签署完成的合同PDF文件，上传后合同状态变为UPLOADED，可进一步报备 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 合同ID | - -**响应** `统一响应结果«合同信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同信息` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -| `message` | `string` | | 响应消息 | - ---- - -## 补充约定模板管理 - -### `POST` /admin/contract/clause-template - -**创建补充约定模板** - -创建合同补充约定的模板，支持变量占位符。创建后默认启用 - -**请求体** `补充约定模板请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `content` | `string` | 是 | 模板内容 | -| `name` | `string` | 是 | 模板名称 | -| `sortOrder` | `int` | | 排序（升序） | - -**响应** `统一响应结果«补充约定模板»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `补充约定模板` | | 响应数据 | -|   `content` | `string` | | 模板内容 | -|   `createTime` | `string` | | 创建时间 | -|   `name` | `string` | | 模板名称 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `string` | | 状态: ACTIVE/INACTIVE | -|   `templateId` | `long` | | 模板ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/clause-template/list - -**获取启用的补充约定模板列表（创建合同用）** - -返回所有启用状态的补充约定模板，创建合同时选择需要附加的补充约定条款。 - -**权限**：需管理员登录。 - -**响应** `统一响应结果«List«补充约定模板»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `补充约定模板[]` | | 响应数据 | -|   `content` | `string` | | 模板内容 | -|   `createTime` | `string` | | 创建时间 | -|   `name` | `string` | | 模板名称 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `string` | | 状态: ACTIVE/INACTIVE | -|   `templateId` | `long` | | 模板ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/clause-template/list-all - -**获取全部补充约定模板（管理页用）** - -**关联字典**： -- common_status：通用状态（列表显示，ACTIVE=启用/INACTIVE=停用） - -**响应** `统一响应结果«List«补充约定模板»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `补充约定模板[]` | | 响应数据 | -|   `content` | `string` | | 模板内容 | -|   `createTime` | `string` | | 创建时间 | -|   `name` | `string` | | 模板名称 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `string` | | 状态: ACTIVE/INACTIVE | -|   `templateId` | `long` | | 模板ID | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/contract/clause-template/{id} - -**更新补充约定模板** - -更新模板的标题和内容。已被合同引用的模板更新不影响已创建的合同（合同记录的是快照内容）。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 模板ID | - -**请求体** `补充约定模板请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `content` | `string` | 是 | 模板内容 | -| `name` | `string` | 是 | 模板名称 | -| `sortOrder` | `int` | | 排序（升序） | - -**响应** `统一响应结果«补充约定模板»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `补充约定模板` | | 响应数据 | -|   `content` | `string` | | 模板内容 | -|   `createTime` | `string` | | 创建时间 | -|   `name` | `string` | | 模板名称 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `string` | | 状态: ACTIVE/INACTIVE | -|   `templateId` | `long` | | 模板ID | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/contract/clause-template/{id} - -**删除补充约定模板** - -软删除模板。已被合同引用的模板仍可删除，不影响已创建的合同 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 模板ID | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/contract/clause-template/{id}/toggle-status - -**切换模板启用/停用状态** - -**关联字典**： -- common_status：通用状态（状态切换，ACTIVE=启用/INACTIVE=停用） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 模板ID | - -**响应** `统一响应结果«补充约定模板»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `补充约定模板` | | 响应数据 | -|   `content` | `string` | | 模板内容 | -|   `createTime` | `string` | | 创建时间 | -|   `name` | `string` | | 模板名称 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `string` | | 状态: ACTIVE/INACTIVE | -|   `templateId` | `long` | | 模板ID | -| `message` | `string` | | 响应消息 | - ---- diff --git a/2026-03/17_0951/hl-file-service.md b/2026-03/17_0951/hl-file-service.md deleted file mode 100644 index 7c17ab6..0000000 --- a/2026-03/17_0951/hl-file-service.md +++ /dev/null @@ -1,331 +0,0 @@ -# 文件服务 API 文档 - -**服务**: `hl-file-service` -**接口总数**: 11 - -## 目录 - -- **C端文件上传** (3 个接口) -- **文件管理** (8 个接口) - ---- - -## C端文件上传 - -### `GET` /mp/file/preview-by-url - -**文件在线预览** - -返回HTML预览页面，小程序通过web-view打开。支持PDF、图片、Office文档 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `url` | `string` | | 文件完整URL | | - ---- - -### `POST` /mp/file/upload - -**上传文件（C端用户）** - -小程序端直接上传文件，支持头像、评价图片等场景。groupKey决定存储路径和文件策略，默认为avatar - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `groupKey` | `string` | | 文件分组标识 | | - -**响应** `统一响应结果«文件信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `文件信息` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `fileHash` | `string` | | 文件MD5哈希 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `groupKey` | `string` | | 业务分组 | -|   `mimeType` | `string` | | MIME类型 | -|   `ossUrl` | `string` | | OSS地址 | -|   `previewUrl` | `string` | | 预览地址 | -|   `refCount` | `int` | | 引用次数 | -|   `status` | `string` | | 文件状态 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/file/{fileId}/preview - -**文件内容流式预览** - -流式输出文件内容，设置正确的Content-Type头。用于小程序端通过web-view直接预览图片和PDF等文件。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `fileId` | `integer` | | 文件ID | - ---- - -## 文件管理 - -### `GET` /admin/file/list - -**文件列表（分页）** - -支持按文件类型、分组、上传者等条件筛选，按上传时间倒序分页返回 - -**关联字典**： -- file_type：文件类型（列表筛选+显示） -- file_status：文件状态（显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `endDate` | `string` | | 结束日期 | 2026-12-31 | -| `fileType` | `string` | | 文件类型 | image | -| `groupKey` | `string` | | 业务分组 | scenic | -| `keyword` | `string` | | 搜索关键词 | 风景 | -| `page` | `integer(int32)` | | 页码 | 1 | -| `pageSize` | `integer(int32)` | | 每页条数 | 20 | -| `startDate` | `string` | | 开始日期 | 2026-01-01 | - -**响应** `统一响应结果«IPage«文件信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `IPage«文件信息»` | | 响应数据 | -|   `current` | `long` | | | -|   `pages` | `long` | | | -|   `records` | `文件信息[]` | | | -|     `createdAt` | `string` | | 创建时间 | -|     `fileHash` | `string` | | 文件MD5哈希 | -|     `fileId` | `string` | | 文件ID | -|     `fileName` | `string` | | 文件名 | -|     `fileSize` | `long` | | 文件大小(字节) | -|     `fileType` | `string` | | 文件类型 | -|     `groupKey` | `string` | | 业务分组 | -|     `mimeType` | `string` | | MIME类型 | -|     `ossUrl` | `string` | | OSS地址 | -|     `previewUrl` | `string` | | 预览地址 | -|     `refCount` | `int` | | 引用次数 | -|     `status` | `string` | | 文件状态 | -|     `thumbnailUrl` | `string` | | 缩略图地址 | -|   `size` | `long` | | | -|   `total` | `long` | | | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/file/stats - -**存储统计** - -返回文件总数、总存储空间、各类型文件占比等统计信息 - -**响应** `统一响应结果«文件统计信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `文件统计信息` | | 响应数据 | -|   `countByGroup` | `object` | | 按分组统计文件数量 | -|   `countByType` | `object` | | 按类型统计文件数量 | -|   `sizeByType` | `object` | | 按类型统计文件大小 | -|   `totalCount` | `long` | | 文件总数 | -|   `totalSize` | `long` | | 文件总大小(字节) | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/file/upload/confirm - -**确认上传完成** - -上传流程第二步：前端直传OSS完成后调用此接口，系统验证文件存在性并创建文件记录。支持MD5去重，相同文件不会重复存储 - -**请求体** `上传确认请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `fileId` | `string` | 是 | 文件ID | - -**响应** `统一响应结果«文件信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `文件信息` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `fileHash` | `string` | | 文件MD5哈希 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `groupKey` | `string` | | 业务分组 | -|   `mimeType` | `string` | | MIME类型 | -|   `ossUrl` | `string` | | OSS地址 | -|   `previewUrl` | `string` | | 预览地址 | -|   `refCount` | `int` | | 引用次数 | -|   `status` | `string` | | 文件状态 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/file/upload/token - -**请求上传凭证** - -上传流程第一步：前端请求上传凭证 → 获取OSS预签名URL和临时凭证 → 前端直传OSS → 调用确认上传接口。凭证有效期有限，过期需重新请求 - -**请求体** `上传令牌请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `fileHash` | `string` | 是 | 文件MD5哈希 | -| `fileName` | `string` | 是 | 文件名 | -| `fileSize` | `long` | 是 | 文件大小(字节) | -| `forcePresigned` | `boolean` | | 强制使用预签名URL（跳过STS分片模式） | -| `groupKey` | `string` | | 业务分组 | - -**响应** `统一响应结果«上传令牌信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `上传令牌信息` | | 响应数据 | -|   `bucket` | `string` | | OSS Bucket名称 | -|   `contentType` | `string` | | 上传时必须使用的Content-Type（与预签名URL签名一致） | -|   `expireAt` | `string` | | 过期时间 | -|   `file` | `文件信息` | | 秒传文件信息 | -|     `createdAt` | `string` | | 创建时间 | -|     `fileHash` | `string` | | 文件MD5哈希 | -|     `fileId` | `string` | | 文件ID | -|     `fileName` | `string` | | 文件名 | -|     `fileSize` | `long` | | 文件大小(字节) | -|     `fileType` | `string` | | 文件类型 | -|     `groupKey` | `string` | | 业务分组 | -|     `mimeType` | `string` | | MIME类型 | -|     `ossUrl` | `string` | | OSS地址 | -|     `previewUrl` | `string` | | 预览地址 | -|     `refCount` | `int` | | 引用次数 | -|     `status` | `string` | | 文件状态 | -|     `thumbnailUrl` | `string` | | 缩略图地址 | -|   `fileId` | `string` | | 文件ID | -|   `ossKey` | `string` | | OSS对象Key | -|   `presignedUrl` | `string` | | 预签名上传URL | -|   `region` | `string` | | OSS Region | -|   `stsToken` | `STS临时凭证信息` | | STS临时凭证 | -|     `accessKeyId` | `string` | | AccessKey ID | -|     `accessKeySecret` | `string` | | AccessKey Secret | -|     `expiration` | `string` | | 过期时间 | -|     `securityToken` | `string` | | 安全令牌 | -|   `uploadMode` | `string` | | 上传模式: PRESIGNED_URL/STS_MULTIPART/INSTANT | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/file/{fileId} - -**文件详情** - -**关联字典**： -- file_type：文件类型（显示） -- file_status：文件状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `fileId` | `integer` | | 文件ID | - -**响应** `统一响应结果«文件信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `文件信息` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `fileHash` | `string` | | 文件MD5哈希 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `groupKey` | `string` | | 业务分组 | -|   `mimeType` | `string` | | MIME类型 | -|   `ossUrl` | `string` | | OSS地址 | -|   `previewUrl` | `string` | | 预览地址 | -|   `refCount` | `int` | | 引用次数 | -|   `status` | `string` | | 文件状态 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/file/{fileId} - -**删除文件** - -软删除文件记录，如果文件存在引用关系则不允许删除。OSS上的物理文件由定时任务清理 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `fileId` | `integer` | | 文件ID | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/file/{fileId}/preview - -**文件内容流式预览** - -流式输出文件内容，设置正确的Content-Type头，支持浏览器直接预览图片和PDF等文件 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `fileId` | `integer` | | 文件ID | - ---- - -### `GET` /admin/file/{fileId}/refs - -**文件引用列表** - -查看文件被哪些业务实体引用（如景区封面、酒店图片等），用于判断文件是否可安全删除 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `fileId` | `integer` | | 文件ID | - -**响应** `统一响应结果«List«文件引用信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `文件引用信息[]` | | 响应数据 | -|   `bizId` | `string` | | 业务ID | -|   `bizType` | `string` | | 业务类型 | -|   `createdAt` | `string` | | 创建时间 | -|   `fileId` | `string` | | 文件ID | -|   `refId` | `string` | | 引用ID | -| `message` | `string` | | 响应消息 | - ---- diff --git a/2026-03/17_0951/hl-guide-service.md b/2026-03/17_0951/hl-guide-service.md deleted file mode 100644 index d01c9cc..0000000 --- a/2026-03/17_0951/hl-guide-service.md +++ /dev/null @@ -1,727 +0,0 @@ -# 攻略服务 API 文档 - -**服务**: `hl-guide-service` -**接口总数**: 21 - -## 目录 - -- **攻略分类管理** (7 个接口) -- **攻略文章管理** (8 个接口) -- **攻略标签管理** (6 个接口) - ---- - -## 攻略分类管理 - -### `POST` /admin/guide/category - -**创建分类** - -创建攻略分类，分类名称不可重复。创建后默认启用，排序值越小越靠前。 - -**权限**：需管理员登录。 - -**请求体** `CategoryCreateRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryName` | `string` | 是 | 分类名称 | -| `coverMaterialId` | `long` | | 封面素材ID | -| `coverUrl` | `string` | | 封面URL | -| `description` | `string` | | 描述 | -| `icon` | `string` | | 图标 | -| `sortOrder` | `int` | | 排序（默认0） | - -**响应** `统一响应结果«攻略分类»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略分类` | | 响应数据 | -|   `articleCount` | `int` | | 文章数量 | -|   `categoryId` | `long` | | 分类ID | -|   `categoryName` | `string` | | 分类名称 | -|   `coverMaterialId` | `long` | | 封面素材ID | -|   `coverUrl` | `string` | | 封面URL | -|   `createdAt` | `string` | | 创建时间 | -|   `description` | `string` | | 描述 | -|   `icon` | `string` | | 图标 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `int` | | 状态：0=禁用，1=启用 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/guide/category/enabled - -**启用的分类列表** - -仅返回状态为启用的分类，创建文章时用于选择分类 - -**响应** `统一响应结果«List«攻略分类»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略分类[]` | | 响应数据 | -|   `articleCount` | `int` | | 文章数量 | -|   `categoryId` | `long` | | 分类ID | -|   `categoryName` | `string` | | 分类名称 | -|   `coverMaterialId` | `long` | | 封面素材ID | -|   `coverUrl` | `string` | | 封面URL | -|   `createdAt` | `string` | | 创建时间 | -|   `description` | `string` | | 描述 | -|   `icon` | `string` | | 图标 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `int` | | 状态：0=禁用，1=启用 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/guide/category/list - -**分类列表** - -返回全部攻略分类（含启用和停用），按排序值升序排列 - -**关联字典**： -- common_status：通用状态（列表显示，ACTIVE=启用/INACTIVE=停用） - -**响应** `统一响应结果«List«攻略分类»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略分类[]` | | 响应数据 | -|   `articleCount` | `int` | | 文章数量 | -|   `categoryId` | `long` | | 分类ID | -|   `categoryName` | `string` | | 分类名称 | -|   `coverMaterialId` | `long` | | 封面素材ID | -|   `coverUrl` | `string` | | 封面URL | -|   `createdAt` | `string` | | 创建时间 | -|   `description` | `string` | | 描述 | -|   `icon` | `string` | | 图标 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `int` | | 状态：0=禁用，1=启用 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/guide/category/{categoryId} - -**更新分类** - -更新攻略分类的名称、图标、描述等信息。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryId` | `integer` | 是 | categoryId | - -**请求体** `CategoryUpdateRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryName` | `string` | | 分类名称 | -| `coverMaterialId` | `long` | | 封面素材ID | -| `coverUrl` | `string` | | 封面URL | -| `description` | `string` | | 描述 | -| `icon` | `string` | | 图标 | -| `sortOrder` | `int` | | 排序 | - -**响应** `统一响应结果«攻略分类»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略分类` | | 响应数据 | -|   `articleCount` | `int` | | 文章数量 | -|   `categoryId` | `long` | | 分类ID | -|   `categoryName` | `string` | | 分类名称 | -|   `coverMaterialId` | `long` | | 封面素材ID | -|   `coverUrl` | `string` | | 封面URL | -|   `createdAt` | `string` | | 创建时间 | -|   `description` | `string` | | 描述 | -|   `icon` | `string` | | 图标 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `int` | | 状态：0=禁用，1=启用 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/guide/category/{categoryId} - -**删除分类** - -删除分类前需确保分类下无文章，否则删除失败 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryId` | `integer` | 是 | categoryId | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/guide/category/{categoryId}/sort - -**更新分类排序** - -更新分类的排序值，排序值越小越靠前。影响小程序端分类导航的展示顺序。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryId` | `integer` | 是 | categoryId | - -**请求体** `CategorySortRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `sortOrder` | `int` | 是 | 排序值 | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/guide/category/{categoryId}/status - -**更新分类状态** - -启用或停用分类。停用后该分类下的文章不会在小程序端展示，但不影响已有文章 - -**关联字典**： -- common_status：通用状态（状态切换，ACTIVE=启用/INACTIVE=停用） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryId` | `integer` | 是 | categoryId | - -**请求体** `StatusRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `status` | `int` | 是 | 状态值 | - -**响应** `统一响应结果«Void»` - ---- - -## 攻略文章管理 - -### `POST` /admin/guide/article - -**创建文章** - -创建攻略文章，需指定分类。创建后默认为草稿状态，需手动发布后小程序端才可见。 - -**权限**：需管理员登录。 - -**关联字典**： -- wiki_status：文章状态（创建后默认DRAFT） - -**请求体** `ArticleCreateRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `authorName` | `string` | | 作者名称 | -| `bannerMaterialIds` | `long[]` | | 轮播图素材ID列表 | -| `categoryId` | `long` | 是 | 分类ID | -| `content` | `string` | | 正文内容 | -| `coverMaterialId` | `long` | | 封面素材ID | -| `coverUrl` | `string` | | 封面URL | -| `resources` | `ArticleResourceItem[]` | | 关联资源列表 | -|   `resourceId` | `long` | 是 | 资源ID | -|   `resourceName` | `string` | 是 | 资源名称 | -|   `resourceType` | `string` | 是 | 资源类型：SCENIC/RESTAURANT/HOTEL/ACTIVITY/PRODUCT | -|   `sortOrder` | `int` | | 排序 | -| `sortOrder` | `int` | | 排序（默认0） | -| `source` | `string` | | 来源 | -| `subtitle` | `string` | | 副标题 | -| `summary` | `string` | | 摘要 | -| `tagIds` | `long[]` | | 标签ID列表 | -| `title` | `string` | 是 | 标题 | - -**响应** `统一响应结果«攻略文章详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略文章详情` | | 响应数据 | -|   `articleId` | `long` | | 文章ID | -|   `authorName` | `string` | | 作者名称 | -|   `bannerMaterialIds` | `long[]` | | 轮播图素材ID列表 | -|   `categoryId` | `long` | | 分类ID | -|   `categoryName` | `string` | | 分类名称 | -|   `content` | `string` | | 正文内容 | -|   `coverMaterialId` | `long` | | 封面素材ID | -|   `coverUrl` | `string` | | 封面URL | -|   `createdAt` | `string` | | 创建时间 | -|   `favoriteCount` | `int` | | 收藏数 | -|   `isRecommend` | `int` | | 是否推荐：0=否，1=是 | -|   `isTop` | `int` | | 是否置顶：0=否，1=是 | -|   `likeCount` | `int` | | 点赞数 | -|   `publishTime` | `string` | | 发布时间 | -|   `resources` | `文章关联资源[]` | | 关联资源列表 | -|     `resourceId` | `long` | | 资源ID | -|     `resourceName` | `string` | | 资源名称 | -|     `resourceType` | `string` | | 资源类型：SCENIC/RESTAURANT/HOTEL/ACTIVITY/PRODUCT | -|     `sortOrder` | `int` | | 排序 | -|   `sortOrder` | `int` | | 排序 | -|   `source` | `string` | | 来源 | -|   `status` | `int` | | 状态：0=草稿，1=已发布，2=已下架 | -|   `subtitle` | `string` | | 副标题 | -|   `summary` | `string` | | 摘要 | -|   `tags` | `攻略标签[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `long` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `tagType` | `int` | | 标签类型：0=系统管理，1=自定义 | -|     `useCount` | `int` | | 使用次数 | -|   `title` | `string` | | 标题 | -|   `updatedAt` | `string` | | 更新时间 | -|   `viewCount` | `int` | | 浏览量 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/guide/article/list - -**文章列表** - -分页查询攻略文章，支持按分类、状态、关键词筛选 - -**关联字典**： -- wiki_status：文章状态（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `categoryId` | `integer(int64)` | | 分类ID | | -| `isRecommend` | `integer(int32)` | | 是否推荐：0=否，1=是 | | -| `isTop` | `integer(int32)` | | 是否置顶：0=否，1=是 | | -| `keyword` | `string` | | 关键词（搜索标题/摘要） | | -| `orderBy` | `string` | | 排序字段：sortOrder/publishTime/viewCount/createdAt（默认createdAt） | | -| `orderDir` | `string` | | 排序方向：asc/desc（默认desc） | | -| `page` | `integer(int32)` | | 页码（默认1） | | -| `pageSize` | `integer(int32)` | | 每页数量（默认20，最大100） | | -| `status` | `integer(int32)` | | 状态：0=草稿，1=已发布，2=已下架 | | - -**响应** `统一响应结果«分页结果«攻略文章列表项»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«攻略文章列表项»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `攻略文章列表项[]` | | 数据列表 | -|     `articleId` | `long` | | 文章ID | -|     `categoryId` | `long` | | 分类ID | -|     `categoryName` | `string` | | 分类名称 | -|     `coverUrl` | `string` | | 封面URL | -|     `createdAt` | `string` | | 创建时间 | -|     `isRecommend` | `int` | | 是否推荐：0=否，1=是 | -|     `isTop` | `int` | | 是否置顶：0=否，1=是 | -|     `publishTime` | `string` | | 发布时间 | -|     `sortOrder` | `int` | | 排序 | -|     `status` | `int` | | 状态：0=草稿，1=已发布，2=已下架 | -|     `summary` | `string` | | 摘要 | -|     `tags` | `攻略标签[]` | | 标签列表 | -|     `title` | `string` | | 标题 | -|     `viewCount` | `int` | | 浏览量 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/guide/article/{articleId} - -**文章详情** - -**关联字典**： -- wiki_status：文章状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | 是 | articleId | - -**响应** `统一响应结果«攻略文章详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略文章详情` | | 响应数据 | -|   `articleId` | `long` | | 文章ID | -|   `authorName` | `string` | | 作者名称 | -|   `bannerMaterialIds` | `long[]` | | 轮播图素材ID列表 | -|   `categoryId` | `long` | | 分类ID | -|   `categoryName` | `string` | | 分类名称 | -|   `content` | `string` | | 正文内容 | -|   `coverMaterialId` | `long` | | 封面素材ID | -|   `coverUrl` | `string` | | 封面URL | -|   `createdAt` | `string` | | 创建时间 | -|   `favoriteCount` | `int` | | 收藏数 | -|   `isRecommend` | `int` | | 是否推荐：0=否，1=是 | -|   `isTop` | `int` | | 是否置顶：0=否，1=是 | -|   `likeCount` | `int` | | 点赞数 | -|   `publishTime` | `string` | | 发布时间 | -|   `resources` | `文章关联资源[]` | | 关联资源列表 | -|     `resourceId` | `long` | | 资源ID | -|     `resourceName` | `string` | | 资源名称 | -|     `resourceType` | `string` | | 资源类型：SCENIC/RESTAURANT/HOTEL/ACTIVITY/PRODUCT | -|     `sortOrder` | `int` | | 排序 | -|   `sortOrder` | `int` | | 排序 | -|   `source` | `string` | | 来源 | -|   `status` | `int` | | 状态：0=草稿，1=已发布，2=已下架 | -|   `subtitle` | `string` | | 副标题 | -|   `summary` | `string` | | 摘要 | -|   `tags` | `攻略标签[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `long` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `tagType` | `int` | | 标签类型：0=系统管理，1=自定义 | -|     `useCount` | `int` | | 使用次数 | -|   `title` | `string` | | 标题 | -|   `updatedAt` | `string` | | 更新时间 | -|   `viewCount` | `int` | | 浏览量 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/guide/article/{articleId} - -**更新文章** - -更新攻略文章的标题、内容、封面图、分类等信息。已发布的文章更新后立即生效。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | 是 | articleId | - -**请求体** `ArticleUpdateRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `authorName` | `string` | | 作者名称 | -| `bannerMaterialIds` | `long[]` | | 轮播图素材ID列表 | -| `categoryId` | `long` | | 分类ID | -| `content` | `string` | | 正文内容 | -| `coverMaterialId` | `long` | | 封面素材ID | -| `coverUrl` | `string` | | 封面URL | -| `resources` | `ArticleResourceItem[]` | | 关联资源列表 | -|   `resourceId` | `long` | 是 | 资源ID | -|   `resourceName` | `string` | 是 | 资源名称 | -|   `resourceType` | `string` | 是 | 资源类型：SCENIC/RESTAURANT/HOTEL/ACTIVITY/PRODUCT | -|   `sortOrder` | `int` | | 排序 | -| `sortOrder` | `int` | | 排序 | -| `source` | `string` | | 来源 | -| `subtitle` | `string` | | 副标题 | -| `summary` | `string` | | 摘要 | -| `tagIds` | `long[]` | | 标签ID列表 | -| `title` | `string` | | 标题 | - -**响应** `统一响应结果«攻略文章详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略文章详情` | | 响应数据 | -|   `articleId` | `long` | | 文章ID | -|   `authorName` | `string` | | 作者名称 | -|   `bannerMaterialIds` | `long[]` | | 轮播图素材ID列表 | -|   `categoryId` | `long` | | 分类ID | -|   `categoryName` | `string` | | 分类名称 | -|   `content` | `string` | | 正文内容 | -|   `coverMaterialId` | `long` | | 封面素材ID | -|   `coverUrl` | `string` | | 封面URL | -|   `createdAt` | `string` | | 创建时间 | -|   `favoriteCount` | `int` | | 收藏数 | -|   `isRecommend` | `int` | | 是否推荐：0=否，1=是 | -|   `isTop` | `int` | | 是否置顶：0=否，1=是 | -|   `likeCount` | `int` | | 点赞数 | -|   `publishTime` | `string` | | 发布时间 | -|   `resources` | `文章关联资源[]` | | 关联资源列表 | -|     `resourceId` | `long` | | 资源ID | -|     `resourceName` | `string` | | 资源名称 | -|     `resourceType` | `string` | | 资源类型：SCENIC/RESTAURANT/HOTEL/ACTIVITY/PRODUCT | -|     `sortOrder` | `int` | | 排序 | -|   `sortOrder` | `int` | | 排序 | -|   `source` | `string` | | 来源 | -|   `status` | `int` | | 状态：0=草稿，1=已发布，2=已下架 | -|   `subtitle` | `string` | | 副标题 | -|   `summary` | `string` | | 摘要 | -|   `tags` | `攻略标签[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `long` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `tagType` | `int` | | 标签类型：0=系统管理，1=自定义 | -|     `useCount` | `int` | | 使用次数 | -|   `title` | `string` | | 标题 | -|   `updatedAt` | `string` | | 更新时间 | -|   `viewCount` | `int` | | 浏览量 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/guide/article/{articleId} - -**删除文章** - -软删除攻略文章，同时清除文章的标签关联。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | 是 | articleId | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/guide/article/{articleId}/recommend - -**设置推荐** - -设置/取消文章推荐。推荐文章会在小程序首页和推荐列表中优先展示 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | 是 | articleId | - -**请求体** `RecommendRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `isRecommend` | `int` | 是 | 是否推荐：0=否，1=是 | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/guide/article/{articleId}/status - -**发布/下架** - -切换文章发布状态。发布后小程序端可见，下架后小程序端不再展示但管理端仍可查看 - -**关联字典**： -- wiki_status：文章状态（状态切换） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | 是 | articleId | - -**请求体** `StatusRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `status` | `int` | 是 | 状态值 | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/guide/article/{articleId}/top - -**设置置顶** - -设置/取消文章置顶。置顶文章在分类列表中始终排在最前面 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | 是 | articleId | - -**请求体** `TopRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `isTop` | `int` | 是 | 是否置顶：0=否，1=是 | - -**响应** `统一响应结果«Void»` - ---- - -## 攻略标签管理 - -### `POST` /admin/guide/tag - -**创建标签** - -创建攻略系统标签，标签名称不可重复。创建后可用于文章分类和筛选。 - -**权限**：需管理员登录。 - -**请求体** `TagCreateRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagColor` | `string` | | 标签颜色（十六进制） | -| `tagName` | `string` | 是 | 标签名称 | -| `tagType` | `int` | | 标签类型：0=系统管理，1=自定义（默认0） | - -**响应** `统一响应结果«攻略标签»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略标签` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `long` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `tagType` | `int` | | 标签类型：0=系统管理，1=自定义 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/guide/tag/all - -**所有标签列表** - -返回全部标签（含系统标签和用户自定义标签），用于文章编辑时的标签选择器 - -**响应** `统一响应结果«List«攻略标签»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略标签[]` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `long` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `tagType` | `int` | | 标签类型：0=系统管理，1=自定义 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/guide/tag/article/{articleId} - -**更新文章标签** - -全量替换文章的标签关联，传入新的标签ID列表（空数组表示清除所有标签） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | 是 | articleId | - -**请求体** `ArticleTagUpdateRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagIds` | `long[]` | 是 | 标签ID列表 | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/guide/tag/managed - -**系统标签列表** - -返回管理员创建的系统标签（不含用户自定义标签），用于标签管理页 - -**响应** `统一响应结果«List«攻略标签»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略标签[]` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `long` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `tagType` | `int` | | 标签类型：0=系统管理，1=自定义 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/guide/tag/{tagId} - -**更新标签** - -更新标签名称。标签名称不可与其他已有标签重复。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagId` | `integer` | 是 | tagId | - -**请求体** `TagUpdateRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagColor` | `string` | | 标签颜色（十六进制） | -| `tagName` | `string` | | 标签名称 | - -**响应** `统一响应结果«攻略标签»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略标签` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `long` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `tagType` | `int` | | 标签类型：0=系统管理，1=自定义 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/guide/tag/{tagId} - -**删除标签** - -删除标签并自动解除与所有文章的关联关系。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagId` | `integer` | 是 | tagId | - -**响应** `统一响应结果«Void»` - ---- diff --git a/2026-03/17_0951/hl-material-service.md b/2026-03/17_0951/hl-material-service.md deleted file mode 100644 index c8ed7fb..0000000 --- a/2026-03/17_0951/hl-material-service.md +++ /dev/null @@ -1,968 +0,0 @@ -# 素材服务 API 文档 - -**服务**: `hl-material-service` -**接口总数**: 28 - -## 目录 - -- **小程序-素材** (1 个接口) -- **素材分类权限管理** (2 个接口) -- **素材标签管理** (6 个接口) -- **素材管理** (19 个接口) - ---- - -## 小程序-素材 - -### `GET` /mp/material/miniprogram - -**获取小程序分类下的全部素材** - -返回miniprogram分类下的所有素材，用于小程序端展示公共素材资源（如引导页图片、默认头像等） - -**响应** `统一响应结果«List«素材信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材信息[]` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `categoryPath` | `string` | | 完整分类路径（如：攻略管理 / 999 / 888） | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `string` | | 创建人ID | -|   `createdByName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 素材描述 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `imageHeight` | `int` | | 图片高度 | -|   `imageWidth` | `int` | | 图片宽度 | -|   `materialId` | `string` | | 素材ID | -|   `materialName` | `string` | | 素材名称 | -|   `ossUrl` | `string` | | OSS地址 | -|   `refCount` | `int` | | 引用次数 | -|   `subCategoryId` | `string` | | 子分类ID | -|   `subCategoryName` | `string` | | 子分类名称 | -|   `tags` | `素材标签信息[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdByName` | `string` | | 创建人姓名 | -|     `managed` | `boolean` | | 是否系统管理标签 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `string` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `useCount` | `int` | | 使用次数 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -## 素材分类权限管理 - -### `GET` /admin/material/category/permissions/{roleCode} - -**获取角色的分类权限** - -仅超级管理员可操作。返回指定角色可访问的素材分类编码列表 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `roleCode` | `string` | | 角色编码 | - -**响应** `统一响应结果«List«string»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `string[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/material/category/permissions/{roleCode} - -**更新角色的分类权限** - -仅超级管理员可操作。全量替换指定角色的素材分类访问权限，传入允许访问的分类编码列表 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `roleCode` | `string` | | 角色编码 | - -**请求体** `分类权限更新请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryCodes` | `string[]` | 是 | 分类编码列表 | - -**响应** `统一响应结果«Void»` - ---- - -## 素材标签管理 - -### `POST` /admin/material/tag - -**创建管理标签** - -创建系统级素材标签，标签名称不可重复。创建后可用于素材分类和筛选。 - -**权限**：需管理员登录。 - -**请求体** `创建标签请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagColor` | `string` | | 标签颜色 | -| `tagName` | `string` | 是 | 标签名称 | - -**响应** `统一响应结果«素材标签信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材标签信息` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdByName` | `string` | | 创建人姓名 | -|   `managed` | `boolean` | | 是否系统管理标签 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `string` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/tag/adhoc - -**解析自定义标签（按名称查找或创建）** - -按标签名称查找已有标签，不存在则自动创建为用户自定义标签。用于素材上传时输入自由标签文本的场景。 - -**权限**：需管理员登录。 - -**请求体** `创建标签请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagColor` | `string` | | 标签颜色 | -| `tagName` | `string` | 是 | 标签名称 | - -**响应** `统一响应结果«素材标签信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材标签信息` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdByName` | `string` | | 创建人姓名 | -|   `managed` | `boolean` | | 是否系统管理标签 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `string` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/material/tag/{tagId} - -**编辑标签** - -更新标签名称。标签名称不可与其他已有标签重复。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagId` | `integer` | | 标签ID | - -**请求体** `更新标签请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagColor` | `string` | | 标签颜色 | -| `tagName` | `string` | | 标签名称 | - -**响应** `统一响应结果«素材标签信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材标签信息` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdByName` | `string` | | 创建人姓名 | -|   `managed` | `boolean` | | 是否系统管理标签 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `string` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/material/tag/{tagId} - -**删除标签** - -删除标签并自动解除与所有素材的关联关系。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagId` | `integer` | | 标签ID | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/material/tags - -**获取管理标签（标签管理用）** - -返回管理员创建的系统标签列表（不含用户自定义标签），用于标签管理页的CRUD操作。 - -**响应** `统一响应结果«List«素材标签信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材标签信息[]` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdByName` | `string` | | 创建人姓名 | -|   `managed` | `boolean` | | 是否系统管理标签 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `string` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/material/tags/all - -**获取全部标签（选择器用，含自定义标签）** - -返回所有标签（含系统标签和用户自定义标签），用于素材上传/编辑时的标签选择器。 - -**响应** `统一响应结果«List«素材标签信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材标签信息[]` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdByName` | `string` | | 创建人姓名 | -|   `managed` | `boolean` | | 是否系统管理标签 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `string` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -## 素材管理 - -### `DELETE` /admin/material/batch - -**批量删除素材** - -批量删除素材，返回删除结果（成功数/失败数/失败原因）。有引用关系的素材会跳过并记录失败原因 - -**请求体** `批量删除素材请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `materialIds` | `string[]` | 是 | 素材ID列表 | - -**响应** `统一响应结果«批量删除结果»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `批量删除结果` | | 响应数据 | -|   `failedItems` | `删除失败项[]` | | 失败项列表 | -|     `materialId` | `string` | | 素材ID | -|     `reason` | `string` | | 失败原因 | -|   `successCount` | `int` | | 成功删除数量 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/material/batch/tags - -**批量更新标签** - -对多个素材同时添加和/或移除标签，支持增量操作（addTagIds新增，removeTagIds移除） - -**请求体** `批量标签操作请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `addTagIds` | `string[]` | | 要添加的标签ID列表 | -| `materialIds` | `string[]` | 是 | 素材ID列表 | -| `removeTagIds` | `string[]` | | 要移除的标签ID列表 | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/material/categories - -**获取有权限的分类列表（含素材数量）** - -返回当前角色有权限查看的素材分类树，每个分类包含素材数量统计。超级管理员可见全部分类 - -**响应** `统一响应结果«List«素材分类信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材分类信息[]` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `children` | `素材分类信息[]` | | 子分类列表 | -|     `categoryCode` | `string` | | 分类编码 | -|     `categoryName` | `string` | | 分类名称 | -|     `children` | `素材分类信息[]` | | 子分类列表 | -|     `materialCount` | `int` | | 素材数量 | -|     `parentId` | `string` | | 父子分类ID | -|     `subCategoryId` | `string` | | 子分类ID | -|   `materialCount` | `int` | | 素材数量 | -|   `parentId` | `string` | | 父子分类ID | -|   `subCategoryId` | `string` | | 子分类ID | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/category/sub - -**创建子分类** - -在一级分类下创建子分类，分类编码自动生成。子分类用于更细粒度的素材归档 - -**请求体** `Create subcategory request` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryName` | `string` | 是 | 子分类名称 | -| `parentCode` | `string` | 是 | 根分类编码(scenic/hotel等) | -| `parentId` | `long` | | 父子分类ID(为空则创建在根分类下) | -| `sortOrder` | `int` | | 排序值 | - -**响应** `统一响应结果«素材分类信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材分类信息` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `children` | `素材分类信息[]` | | 子分类列表 | -|     `categoryCode` | `string` | | 分类编码 | -|     `categoryName` | `string` | | 分类名称 | -|     `children` | `素材分类信息[]` | | 子分类列表 | -|     `materialCount` | `int` | | 素材数量 | -|     `parentId` | `string` | | 父子分类ID | -|     `subCategoryId` | `string` | | 子分类ID | -|   `materialCount` | `int` | | 素材数量 | -|   `parentId` | `string` | | 父子分类ID | -|   `subCategoryId` | `string` | | 子分类ID | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/material/category/sub/{categoryId} - -**更新子分类** - -更新子分类的名称或排序值。仅有该分类权限的管理员可操作。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryId` | `integer` | | 子分类ID | - -**请求体** `Update subcategory request` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryName` | `string` | | Subcategory name | -| `sortOrder` | `int` | | Sort order | - -**响应** `统一响应结果«素材分类信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材分类信息` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `children` | `素材分类信息[]` | | 子分类列表 | -|     `categoryCode` | `string` | | 分类编码 | -|     `categoryName` | `string` | | 分类名称 | -|     `children` | `素材分类信息[]` | | 子分类列表 | -|     `materialCount` | `int` | | 素材数量 | -|     `parentId` | `string` | | 父子分类ID | -|     `subCategoryId` | `string` | | 子分类ID | -|   `materialCount` | `int` | | 素材数量 | -|   `parentId` | `string` | | 父子分类ID | -|   `subCategoryId` | `string` | | 子分类ID | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/material/category/sub/{categoryId} - -**删除子分类** - -删除子分类前需确保分类下无素材，否则删除失败 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryId` | `integer` | | 子分类ID | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/material/list - -**素材列表** - -分页查询素材，支持按分类、标签、文件类型、关键词筛选。返回结果受角色分类权限限制 - -**关联字典**： -- file_type：文件类型（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `categoryCode` | `string` | | 分类编码 | scenic | -| `createdBy` | `integer(int64)` | | 创建人ID | 1001 | -| `endDate` | `string` | | 结束日期 | 2026-12-31 | -| `fileType` | `string` | | 文件类型 | image | -| `keyword` | `string` | | 搜索关键词 | 风景 | -| `orderBy` | `string` | | 排序字段 | createdAt | -| `orderDir` | `string` | | 排序方向: asc/desc | desc | -| `page` | `integer(int32)` | | 页码 | 1 | -| `pageSize` | `integer(int32)` | | 每页条数 | 20 | -| `startDate` | `string` | | 开始日期 | 2026-01-01 | -| `subCategoryId` | `integer(int64)` | | 子分类ID | 2030000000000001 | -| `tagIds` | `string` | | 标签ID列表(逗号分隔) | 1,2,3 | - -**响应** `统一响应结果«分页结果«素材信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«素材信息»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `素材信息[]` | | 数据列表 | -|     `categoryCode` | `string` | | 分类编码 | -|     `categoryName` | `string` | | 分类名称 | -|     `categoryPath` | `string` | | 完整分类路径（如：攻略管理 / 999 / 888） | -|     `createdAt` | `string` | | 创建时间 | -|     `createdBy` | `string` | | 创建人ID | -|     `createdByName` | `string` | | 创建人姓名 | -|     `description` | `string` | | 素材描述 | -|     `fileId` | `string` | | 文件ID | -|     `fileName` | `string` | | 文件名 | -|     `fileSize` | `long` | | 文件大小(字节) | -|     `fileType` | `string` | | 文件类型 | -|     `imageHeight` | `int` | | 图片高度 | -|     `imageWidth` | `int` | | 图片宽度 | -|     `materialId` | `string` | | 素材ID | -|     `materialName` | `string` | | 素材名称 | -|     `ossUrl` | `string` | | OSS地址 | -|     `refCount` | `int` | | 引用次数 | -|     `subCategoryId` | `string` | | 子分类ID | -|     `subCategoryName` | `string` | | 子分类名称 | -|     `tags` | `素材标签信息[]` | | 标签列表 | -|     `thumbnailUrl` | `string` | | 缩略图地址 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/upload/chunk - -**分片上传-上传分片** - -大文件上传第二步：逐个上传分片数据，分片索引从0开始。支持断点续传，已上传的分片无需重传。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `chunkIndex` | `integer(int32)` | | 分片索引（从0开始） | | -| `uploadId` | `string` | | 上传ID | | - -**响应** `统一响应结果«分片上传结果»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分片上传结果` | | 响应数据 | -|   `etag` | `string` | | 分片ETag | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/upload/chunk/cancel - -**分片上传-取消** - -取消分片上传任务，清理已上传的分片数据和OSS临时文件。仅上传发起者可取消。 - -**请求体** `分片上传取消请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `uploadId` | `string` | 是 | 上传ID | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /admin/material/upload/chunk/complete - -**分片上传-完成合并** - -大文件上传第三步：所有分片上传完成后调用，OSS端合并分片为完整文件并创建素材记录。 - -**请求体** `分片上传完成请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `uploadId` | `string` | 是 | 上传ID | - -**响应** `统一响应结果«素材信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材信息` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `categoryPath` | `string` | | 完整分类路径（如：攻略管理 / 999 / 888） | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `string` | | 创建人ID | -|   `createdByName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 素材描述 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `imageHeight` | `int` | | 图片高度 | -|   `imageWidth` | `int` | | 图片宽度 | -|   `materialId` | `string` | | 素材ID | -|   `materialName` | `string` | | 素材名称 | -|   `ossUrl` | `string` | | OSS地址 | -|   `refCount` | `int` | | 引用次数 | -|   `subCategoryId` | `string` | | 子分类ID | -|   `subCategoryName` | `string` | | 子分类名称 | -|   `tags` | `素材标签信息[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdByName` | `string` | | 创建人姓名 | -|     `managed` | `boolean` | | 是否系统管理标签 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `string` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `useCount` | `int` | | 使用次数 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/upload/chunk/init - -**分片上传-初始化** - -大文件上传第一步：初始化分片上传任务，返回uploadId和每个分片的预签名URL。前端按分片并发上传后调用完成合并接口。 - -**权限**：需管理员登录，受角色分类权限限制。 - -**请求体** `分片上传初始化请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `contentType` | `string` | 是 | 文件MIME类型 | -| `fileSize` | `long` | 是 | 文件大小（字节） | -| `filename` | `string` | 是 | 文件名 | -| `materialId` | `string` | | 关联素材ID（可选，用于更新已有素材） | - -**响应** `统一响应结果«分片上传初始化结果»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分片上传初始化结果` | | 响应数据 | -|   `chunkSize` | `int` | | 推荐分片大小（字节） | -|   `uploadId` | `string` | | 上传ID | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/upload/confirm - -**确认上传完成** - -上传素材第二步：前端直传OSS完成后调用此接口创建素材记录，支持MD5去重 - -**关联字典**： -- material_tag：素材标签（上传时可选标签） - -**请求体** `素材上传确认请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `description` | `string` | | 素材描述 | -| `materialId` | `string` | 是 | 素材ID | -| `tagIds` | `string[]` | | 标签ID列表 | - -**响应** `统一响应结果«素材信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材信息` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `categoryPath` | `string` | | 完整分类路径（如：攻略管理 / 999 / 888） | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `string` | | 创建人ID | -|   `createdByName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 素材描述 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `imageHeight` | `int` | | 图片高度 | -|   `imageWidth` | `int` | | 图片宽度 | -|   `materialId` | `string` | | 素材ID | -|   `materialName` | `string` | | 素材名称 | -|   `ossUrl` | `string` | | OSS地址 | -|   `refCount` | `int` | | 引用次数 | -|   `subCategoryId` | `string` | | 子分类ID | -|   `subCategoryName` | `string` | | 子分类名称 | -|   `tags` | `素材标签信息[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdByName` | `string` | | 创建人姓名 | -|     `managed` | `boolean` | | 是否系统管理标签 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `string` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `useCount` | `int` | | 使用次数 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/upload/folder - -**文件夹上传初始化（创建分类+批量获取凭证）** - -支持整个文件夹上传：自动根据文件夹名创建子分类，为每个文件批量获取上传凭证，前端逐一上传后批量确认 - -**请求体** `文件夹上传初始化请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryCode` | `string` | 是 | 分类编码 | -| `files` | `文件夹上传文件项[]` | 是 | 文件列表 | -|   `contentType` | `string` | 是 | 文件MIME类型 | -|   `fileSize` | `long` | 是 | 文件大小(字节) | -|   `filename` | `string` | 是 | 文件名 | -|   `folderPath` | `string` | 是 | 文件所在文件夹路径（与folderPaths中的路径对应） | -|   `materialName` | `string` | | 素材名称 | -|   `md5` | `string` | 是 | 文件MD5 | -| `folderPaths` | `string[]` | 是 | 文件夹路径列表（如 ["999", "999/888"]） | - -**响应** `统一响应结果«文件夹上传初始化结果»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `文件夹上传初始化结果` | | 响应数据 | -|   `fileTokens` | `文件上传凭证项[]` | | 各文件的上传凭证列表 | -|     `bucket` | `string` | | OSS Bucket名称 | -|     `error` | `string` | | 错误信息（该文件获取凭证失败时） | -|     `filename` | `string` | | 文件名 | -|     `folderPath` | `string` | | 文件夹路径 | -|     `instantUpload` | `boolean` | | 是否秒传（文件已存在） | -|     `materialId` | `string` | | 素材ID | -|     `ossKey` | `string` | | OSS对象Key | -|     `region` | `string` | | OSS Region | -|     `stsToken` | `STS临时凭证信息` | | STS临时凭证 | -|     `uploadHeaders` | `object` | | 上传请求头 | -|     `uploadMethod` | `string` | | 上传方式: PUT/POST | -|     `uploadUrl` | `string` | | 上传URL | -|   `folderCategoryMap` | `object` | | 文件夹路径 → 子分类ID 映射 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/upload/token - -**获取上传凭证** - -上传素材第一步：获取OSS预签名URL和凭证。前端使用凭证直传OSS后调用确认上传。支持基于角色的分类权限校验 - -**请求体** `素材上传令牌请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryCode` | `string` | 是 | 分类编码 | -| `contentType` | `string` | 是 | 文件MIME类型 | -| `fileSize` | `long` | 是 | 文件大小(字节) | -| `filename` | `string` | 是 | 文件名 | -| `materialName` | `string` | | 素材名称 | -| `md5` | `string` | 是 | 文件MD5 | -| `subCategoryId` | `long` | | 子分类ID（文件夹上传时使用） | - -**响应** `统一响应结果«素材上传令牌信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材上传令牌信息` | | 响应数据 | -|   `bucket` | `string` | | OSS Bucket名称 | -|   `contentType` | `string` | | 上传时必须使用的Content-Type（与预签名URL签名一致） | -|   `expireAt` | `string` | | 过期时间 | -|   `fileId` | `string` | | 文件ID | -|   `instantUpload` | `boolean` | | 是否秒传 | -|   `material` | `素材信息` | | 秒传时返回的素材信息 | -|     `categoryCode` | `string` | | 分类编码 | -|     `categoryName` | `string` | | 分类名称 | -|     `categoryPath` | `string` | | 完整分类路径（如：攻略管理 / 999 / 888） | -|     `createdAt` | `string` | | 创建时间 | -|     `createdBy` | `string` | | 创建人ID | -|     `createdByName` | `string` | | 创建人姓名 | -|     `description` | `string` | | 素材描述 | -|     `fileId` | `string` | | 文件ID | -|     `fileName` | `string` | | 文件名 | -|     `fileSize` | `long` | | 文件大小(字节) | -|     `fileType` | `string` | | 文件类型 | -|     `imageHeight` | `int` | | 图片高度 | -|     `imageWidth` | `int` | | 图片宽度 | -|     `materialId` | `string` | | 素材ID | -|     `materialName` | `string` | | 素材名称 | -|     `ossUrl` | `string` | | OSS地址 | -|     `refCount` | `int` | | 引用次数 | -|     `subCategoryId` | `string` | | 子分类ID | -|     `subCategoryName` | `string` | | 子分类名称 | -|     `tags` | `素材标签信息[]` | | 标签列表 | -|     `thumbnailUrl` | `string` | | 缩略图地址 | -|   `materialId` | `string` | | 素材ID | -|   `ossKey` | `string` | | OSS对象Key | -|   `region` | `string` | | OSS Region | -|   `stsToken` | `STS临时凭证信息` | | STS临时凭证 | -|     `accessKeyId` | `string` | | AccessKey ID | -|     `accessKeySecret` | `string` | | AccessKey Secret | -|     `expiration` | `string` | | 过期时间 | -|     `securityToken` | `string` | | 安全令牌 | -|   `uploadMode` | `string` | | 上传模式: PRESIGNED_URL/STS_MULTIPART | -|   `uploadUrl` | `string` | | 上传URL | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/material/{materialId} - -**素材详情** - -返回素材完整信息，包含文件名、URL、分类、标签、文件大小、上传者等。受角色分类权限限制。 - -**关联字典**： -- file_type：文件类型（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `materialId` | `integer` | | 素材ID | - -**响应** `统一响应结果«素材信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材信息` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `categoryPath` | `string` | | 完整分类路径（如：攻略管理 / 999 / 888） | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `string` | | 创建人ID | -|   `createdByName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 素材描述 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `imageHeight` | `int` | | 图片高度 | -|   `imageWidth` | `int` | | 图片宽度 | -|   `materialId` | `string` | | 素材ID | -|   `materialName` | `string` | | 素材名称 | -|   `ossUrl` | `string` | | OSS地址 | -|   `refCount` | `int` | | 引用次数 | -|   `subCategoryId` | `string` | | 子分类ID | -|   `subCategoryName` | `string` | | 子分类名称 | -|   `tags` | `素材标签信息[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdByName` | `string` | | 创建人姓名 | -|     `managed` | `boolean` | | 是否系统管理标签 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `string` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `useCount` | `int` | | 使用次数 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/material/{materialId} - -**更新素材信息** - -**关联字典**： -- material_tag：素材标签（编辑时选择标签） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `materialId` | `integer` | | 素材ID | - -**请求体** `更新素材请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryCode` | `string` | | 分类编码 | -| `description` | `string` | | 素材描述 | -| `materialName` | `string` | | 素材名称 | -| `subCategoryId` | `long` | | 子分类ID（0表示清除子分类） | - -**响应** `统一响应结果«素材信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材信息` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `categoryPath` | `string` | | 完整分类路径（如：攻略管理 / 999 / 888） | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `string` | | 创建人ID | -|   `createdByName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 素材描述 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `imageHeight` | `int` | | 图片高度 | -|   `imageWidth` | `int` | | 图片宽度 | -|   `materialId` | `string` | | 素材ID | -|   `materialName` | `string` | | 素材名称 | -|   `ossUrl` | `string` | | OSS地址 | -|   `refCount` | `int` | | 引用次数 | -|   `subCategoryId` | `string` | | 子分类ID | -|   `subCategoryName` | `string` | | 子分类名称 | -|   `tags` | `素材标签信息[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdByName` | `string` | | 创建人姓名 | -|     `managed` | `boolean` | | 是否系统管理标签 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `string` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `useCount` | `int` | | 使用次数 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/material/{materialId} - -**删除素材** - -删除素材记录。如果素材存在引用关系（被景区、酒店等使用），则不允许删除 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `materialId` | `integer` | | 素材ID | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/material/{materialId}/refs - -**查看素材引用记录** - -查看素材被哪些业务实体引用（如景区封面、酒店轮播图等），用于判断素材是否可安全删除 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `materialId` | `integer` | | 素材ID | - -**响应** `统一响应结果«List«素材引用信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材引用信息[]` | | 响应数据 | -|   `bizId` | `string` | | 业务ID | -|   `bizName` | `string` | | 业务名称 | -|   `bizType` | `string` | | 业务类型 | -|   `bizTypeName` | `string` | | 业务类型名称 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdByName` | `string` | | 创建人姓名 | -|   `id` | `string` | | 引用ID | -|   `materialId` | `string` | | 素材ID | -|   `usageType` | `string` | | 用途类型 | -|   `usageTypeName` | `string` | | 用途类型名称 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/material/{materialId}/tags - -**更新素材标签** - -全量替换单个素材的标签，传入新的标签ID列表 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `materialId` | `integer` | | 素材ID | - -**请求体** `更新素材标签请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagIds` | `string[]` | 是 | 标签ID列表 | - -**响应** `统一响应结果«Void»` - ---- diff --git a/2026-03/17_0951/hl-monitor-service.md b/2026-03/17_0951/hl-monitor-service.md deleted file mode 100644 index 188a26a..0000000 --- a/2026-03/17_0951/hl-monitor-service.md +++ /dev/null @@ -1,553 +0,0 @@ -# 监控服务 API 文档 - -**服务**: `hl-monitor-service` -**接口总数**: 18 - -## 目录 - -- **MySQL监控** (3 个接口) -- **Redis监控** (1 个接口) -- **RocketMQ监控** (3 个接口) -- **企微审批日志** (2 个接口) -- **操作日志** (2 个接口) -- **数据清理** (1 个接口) -- **服务监控** (1 个接口) -- **消息通知日志** (2 个接口) -- **登录日志** (1 个接口) -- **错误日志** (2 个接口) - ---- - -## MySQL监控 - -### `GET` /admin/monitor/mysql - -**MySQL实时监控数据** - -返回MySQL实时状态：连接数、QPS、缓冲池命中率、线程状态、慢查询计数等核心指标 - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/mysql/slow-queries - -**慢SQL查询统计** - -仅超级管理员可操作。查询慢SQL统计信息，返回执行时间最长的SQL语句及其执行次数、平均耗时等 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `limit` | `integer(int32)` | | 返回条数 | | -| `type` | `string` | | 查询类型 | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/mysql/tables - -**表空间列表** - -查询各数据库表的空间占用情况，包含数据大小、索引大小、行数等信息。可指定schema筛选，仅允许查询hl_前缀的数据库 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `schema` | `string` | | 数据库名 | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## Redis监控 - -### `GET` /admin/monitor/redis - -**Redis实时监控数据** - -返回Redis实时状态：内存使用量、连接数、Key数量、命中率、每秒命令数等核心指标 - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## RocketMQ监控 - -### `GET` /admin/monitor/rocketmq - -**RocketMQ概览** - -返回RocketMQ集群状态：Broker状态、Topic数量、消息积压量、生产者/消费者连接数等核心指标 - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/rocketmq/consumer-groups - -**消费者组统计** - -返回各消费者组的消费进度、积压量和在线消费者实例信息 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/rocketmq/topics - -**Topic统计** - -返回各Topic的消息量、最新偏移量和消费进度等信息 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## 企微审批日志 - -### `GET` /admin/monitor/approval-logs - -**审批日志分页查询** - -查询企微OA审批流程记录，支持按审批状态(1-审批中/2-已通过/3-已驳回/4-已撤销)、申请人、模板名称筛选 - -**关联字典**： -- approval_sp_status：审批状态（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `applyUserName` | `string` | | 申请人姓名 | | -| `endTime` | `string` | | 结束时间 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `spName` | `string` | | 审批模板名称 | | -| `spStatus` | `integer(int32)` | | 审批状态 | | -| `startTime` | `string` | | 开始时间 | | - -**响应** `统一响应结果«分页结果«审批日志»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«审批日志»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `审批日志[]` | | 数据列表 | -|     `applyData` | `string` | | 申请表单数据(JSON) | -|     `applyTime` | `string` | | 申请时间 | -|     `applyUserId` | `string` | | 申请人企微UserID | -|     `applyUserName` | `string` | | 申请人姓名 | -|     `approvalLogId` | `long` | | 审批日志ID | -|     `approvalNodes` | `string` | | 审批节点详情(JSON) | -|     `createdAt` | `string` | | 创建时间 | -|     `notifyNodes` | `string` | | 抄送节点详情(JSON) | -|     `spName` | `string` | | 审批模板名称 | -|     `spStatus` | `int` | | 审批状态: 1-审批中, 2-已通过, 3-已驳回, 4-已撤销, 6-通过后撤销, 7-已删除 | -|     `templateId` | `string` | | 审批模板ID | -|     `thirdNo` | `string` | | 审批编号 | -|     `updatedAt` | `string` | | 更新时间 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/approval-logs/{id} - -**审批日志详情** - -**关联字典**： -- approval_sp_status：审批状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 日志ID | - -**响应** `统一响应结果«审批日志»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `审批日志` | | 响应数据 | -|   `applyData` | `string` | | 申请表单数据(JSON) | -|   `applyTime` | `string` | | 申请时间 | -|   `applyUserId` | `string` | | 申请人企微UserID | -|   `applyUserName` | `string` | | 申请人姓名 | -|   `approvalLogId` | `long` | | 审批日志ID | -|   `approvalNodes` | `string` | | 审批节点详情(JSON) | -|   `createdAt` | `string` | | 创建时间 | -|   `notifyNodes` | `string` | | 抄送节点详情(JSON) | -|   `spName` | `string` | | 审批模板名称 | -|   `spStatus` | `int` | | 审批状态: 1-审批中, 2-已通过, 3-已驳回, 4-已撤销, 6-通过后撤销, 7-已删除 | -|   `templateId` | `string` | | 审批模板ID | -|   `thirdNo` | `string` | | 审批编号 | -|   `updatedAt` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -## 操作日志 - -### `GET` /admin/monitor/operation-logs - -**操作日志分页查询** - -查询管理员的操作记录，支持按模块、管理员、状态、时间范围筛选。记录包含请求参数、响应结果和耗时信息 - -**关联字典**： -- operation_log_status：操作状态（列表筛选+显示，0=成功/1=失败） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `adminId` | `integer(int64)` | | 管理员ID | | -| `endTime` | `string` | | 结束时间 | | -| `module` | `string` | | 模块名称 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `startTime` | `string` | | 开始时间 | | -| `status` | `integer(int32)` | | 状态 | | - -**响应** `统一响应结果«分页结果«操作日志»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«操作日志»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `操作日志[]` | | 数据列表 | -|     `adminId` | `long` | | 管理员ID | -|     `adminName` | `string` | | 管理员名称 | -|     `createdAt` | `string` | | 创建时间 | -|     `description` | `string` | | 操作描述 | -|     `duration` | `int` | | 耗时(毫秒) | -|     `errorMsg` | `string` | | 错误信息 | -|     `ipAddress` | `string` | | IP地址 | -|     `module` | `string` | | 操作模块 | -|     `operationLogId` | `long` | | 操作日志ID | -|     `requestMethod` | `string` | | 请求方法 | -|     `requestParams` | `string` | | 请求参数(JSON) | -|     `requestUrl` | `string` | | 请求URL | -|     `responseCode` | `int` | | 响应状态码 | -|     `responseMsg` | `string` | | 响应消息 | -|     `serviceName` | `string` | | 服务名称 | -|     `status` | `int` | | 状态: 0-成功, 1-失败 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/operation-logs/{id} - -**操作日志详情** - -返回单条操作日志的完整信息，包含操作模块、操作描述、请求参数、响应结果、操作耗时、操作人信息、IP地址等。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 日志ID | - -**响应** `统一响应结果«操作日志»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `操作日志` | | 响应数据 | -|   `adminId` | `long` | | 管理员ID | -|   `adminName` | `string` | | 管理员名称 | -|   `createdAt` | `string` | | 创建时间 | -|   `description` | `string` | | 操作描述 | -|   `duration` | `int` | | 耗时(毫秒) | -|   `errorMsg` | `string` | | 错误信息 | -|   `ipAddress` | `string` | | IP地址 | -|   `module` | `string` | | 操作模块 | -|   `operationLogId` | `long` | | 操作日志ID | -|   `requestMethod` | `string` | | 请求方法 | -|   `requestParams` | `string` | | 请求参数(JSON) | -|   `requestUrl` | `string` | | 请求URL | -|   `responseCode` | `int` | | 响应状态码 | -|   `responseMsg` | `string` | | 响应消息 | -|   `serviceName` | `string` | | 服务名称 | -|   `status` | `int` | | 状态: 0-成功, 1-失败 | -| `message` | `string` | | 响应消息 | - ---- - -## 数据清理 - -### `POST` /admin/monitor/data-retention/cleanup - -**手动触发数据清理** - -仅超级管理员可操作。按数据保留策略清理过期日志（操作日志/错误日志/通知日志等），返回各类型清理的记录数 - -**响应** `统一响应结果«Map«string,int»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## 服务监控 - -### `GET` /admin/monitor/services - -**微服务列表和健康状态** - -从Nacos注册中心获取所有微服务的实例列表和健康状态，包含IP、端口、注册时间和健康检查结果 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## 消息通知日志 - -### `GET` /admin/monitor/notification-logs - -**消息通知日志分页查询** - -查询各渠道（短信/站内信/企微/公众号）的通知发送记录，支持按通知类型、用户、发送状态筛选 - -**关联字典**： -- notification_send_status：发送状态（列表筛选+显示，0=待发送/1=成功/2=失败） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `endTime` | `string` | | 结束时间 | | -| `notificationType` | `string` | | 通知类型 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `sendStatus` | `integer(int32)` | | 发送状态 | | -| `startTime` | `string` | | 开始时间 | | -| `userName` | `string` | | 用户名 | | - -**响应** `统一响应结果«分页结果«通知日志»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«通知日志»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `通知日志[]` | | 数据列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `externalUserId` | `string` | | 外部联系人ID | -|     `externalUserName` | `string` | | 外部联系人姓名 | -|     `failReason` | `string` | | 失败原因 | -|     `messageContent` | `string` | | 消息内容 | -|     `notificationLogId` | `long` | | 通知日志ID | -|     `notificationType` | `string` | | 通知类型: ADD_EXTERNAL_CONTACT/DEL_FOLLOW_USER/DEL_EXTERNAL_CONTACT | -|     `sendStatus` | `int` | | 发送状态: 0-成功, 1-失败, 2-已过滤 | -|     `serviceName` | `string` | | 来源服务名称 | -|     `userId` | `string` | | 员工企微UserID | -|     `userName` | `string` | | 员工姓名 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/notification-logs/{id} - -**消息通知日志详情** - -返回单条通知发送日志的完整信息，包含通知类型、接收用户、发送渠道、发送状态、失败原因（如有）、消息内容等。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 日志ID | - -**响应** `统一响应结果«通知日志»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `通知日志` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `externalUserId` | `string` | | 外部联系人ID | -|   `externalUserName` | `string` | | 外部联系人姓名 | -|   `failReason` | `string` | | 失败原因 | -|   `messageContent` | `string` | | 消息内容 | -|   `notificationLogId` | `long` | | 通知日志ID | -|   `notificationType` | `string` | | 通知类型: ADD_EXTERNAL_CONTACT/DEL_FOLLOW_USER/DEL_EXTERNAL_CONTACT | -|   `sendStatus` | `int` | | 发送状态: 0-成功, 1-失败, 2-已过滤 | -|   `serviceName` | `string` | | 来源服务名称 | -|   `userId` | `string` | | 员工企微UserID | -|   `userName` | `string` | | 员工姓名 | -| `message` | `string` | | 响应消息 | - ---- - -## 登录日志 - -### `GET` /admin/monitor/login-logs - -**登录日志分页查询** - -查询管理员登录记录（代理到user-service），包含登录IP、设备信息、登录方式和登录结果 - -**关联字典**： -- login_status：登录状态（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `adminId` | `integer(int64)` | | 管理员ID | | -| `endTime` | `string` | | 结束时间 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `startTime` | `string` | | 开始时间 | | -| `status` | `string` | | 状态 | | - -**响应** `统一响应结果«object»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## 错误日志 - -### `GET` /admin/monitor/error-logs - -**错误日志分页查询** - -查询各微服务的异常记录，支持按服务名称、异常类名、时间范围筛选。堆栈信息仅保留com.hulalv包内的调用帧 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `endTime` | `string` | | 结束时间 | | -| `exceptionClass` | `string` | | 异常类名 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `serviceName` | `string` | | 服务名称 | | -| `startTime` | `string` | | 开始时间 | | - -**响应** `统一响应结果«分页结果«错误日志»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«错误日志»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `错误日志[]` | | 数据列表 | -|     `adminId` | `long` | | 管理员ID | -|     `createdAt` | `string` | | 创建时间 | -|     `errorLogId` | `long` | | 错误日志ID | -|     `exceptionClass` | `string` | | 异常类名 | -|     `exceptionMessage` | `string` | | 异常消息 | -|     `ipAddress` | `string` | | IP地址 | -|     `requestMethod` | `string` | | 请求方法 | -|     `requestParams` | `string` | | 请求参数(JSON) | -|     `requestUrl` | `string` | | 请求URL | -|     `serviceName` | `string` | | 服务名称 | -|     `stackTrace` | `string` | | 堆栈跟踪 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/error-logs/{id} - -**错误日志详情** - -返回单条错误日志的完整信息，包含异常类名、错误消息、过滤后的堆栈信息（仅com.hulalv包内调用帧）、请求URL、请求参数等。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 日志ID | - -**响应** `统一响应结果«错误日志»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `错误日志` | | 响应数据 | -|   `adminId` | `long` | | 管理员ID | -|   `createdAt` | `string` | | 创建时间 | -|   `errorLogId` | `long` | | 错误日志ID | -|   `exceptionClass` | `string` | | 异常类名 | -|   `exceptionMessage` | `string` | | 异常消息 | -|   `ipAddress` | `string` | | IP地址 | -|   `requestMethod` | `string` | | 请求方法 | -|   `requestParams` | `string` | | 请求参数(JSON) | -|   `requestUrl` | `string` | | 请求URL | -|   `serviceName` | `string` | | 服务名称 | -|   `stackTrace` | `string` | | 堆栈跟踪 | -| `message` | `string` | | 响应消息 | - ---- diff --git a/2026-03/17_0951/hl-mp-service.md b/2026-03/17_0951/hl-mp-service.md deleted file mode 100644 index 720fbe0..0000000 --- a/2026-03/17_0951/hl-mp-service.md +++ /dev/null @@ -1,3634 +0,0 @@ -# 小程序聚合服务 API 文档 - -**服务**: `hl-mp-service` -**接口总数**: 132 - -## 目录 - -- **C端 - 产品接口** (8 个接口) -- **C端 - 公共接口** (6 个接口) -- **C端 - 出行人接口** (6 个接口) -- **C端 - 前端配置接口** (2 个接口) -- **C端 - 发票接口** (4 个接口) -- **C端 - 合同接口** (5 个接口) -- **C端 - 天气接口** (3 个接口) -- **C端 - 字典接口** (1 个接口) -- **C端 - 定制师接口** (5 个接口) -- **C端 - 徽章接口** (1 个接口) -- **C端 - 心愿单接口** (2 个接口) -- **C端 - 探索接口** (5 个接口) -- **C端 - 搜索接口** (1 个接口) -- **C端 - 支付接口** (3 个接口) -- **C端 - 收藏接口** (6 个接口) -- **C端 - 攻略接口** (4 个接口) -- **C端 - 景区接口** (3 个接口) -- **C端 - 活动接口** (2 个接口) -- **C端 - 消息接口** (5 个接口) -- **C端 - 用户接口** (8 个接口) -- **C端 - 相册接口** (4 个接口) -- **C端 - 行程接口** (4 个接口) -- **C端 - 订单接口** (11 个接口) -- **C端 - 评价接口** (13 个接口) -- **C端 - 足迹接口** (4 个接口) -- **C端 - 轮播图接口** (1 个接口) -- **C端 - 退款接口** (7 个接口) -- **C端 - 通用点赞** (3 个接口) -- **C端 - 酒店接口** (2 个接口) -- **C端 - 餐厅接口** (2 个接口) -- **C端 - 首页接口** (1 个接口) - ---- - -## C端 - 产品接口 - -### `GET` /mp/product/batch/{batchId}/combos - -**GROUP批次套餐列表** - -返回指定批次的所有套餐（名称、人数组合、价格、库存） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `batchId` | `integer` | | 批次ID | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/product/lines - -**产品线列表** - -返回所有已启用的产品线，用于小程序首页或筛选栏展示 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/product/list - -**产品列表** - -分页查询已上架产品，支持按关键词、产品类型(CORE/ROUTE/CUSTOM/GROUP)、季节、天数、目的地、产品线筛选和排序 - -**关联字典（BFF透传）**： -- product_type：产品类型（列表筛选+显示） -- product_status：产品状态（透传自product-service） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `destination` | `string` | | 目的地 | | -| `keyword` | `string` | | 搜索关键词 | | -| `lineId` | `string` | | 产品线ID | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `productType` | `string` | | 产品类型：CORE/ROUTE/CUSTOM/GROUP | | -| `season` | `string` | | 季节 | | -| `sortBy` | `string` | | 排序字段 | | -| `sortDir` | `string` | | 排序方向 | | -| `tripDays` | `integer(int32)` | | 天数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/product/{productId} - -**产品详情（聚合收藏状态）** - -聚合流程：获取产品详情 → 并行查询收藏状态 → 异步记录足迹 → 返回聚合数据。支持未登录访问（不返回收藏状态） - -**关联字典（BFF透传）**： -- product_type：产品类型（显示） -- product_status：产品状态（透传自product-service） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `productId` | `integer` | | 产品ID | - -**响应** `统一响应结果«C端产品详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `C端产品详情` | | 响应数据 | -|   `chatMessages` | `Map«string,object»[]` | | 群聊最近消息（来自会话存档） | -|   `earliestBookingDate` | `string` | | 最早可订日期(如 2026-07-15) | -|   `earlyBirdDiscount` | `number` | | 早鸟优惠金额(元/人) | -|   `earlyBirdPlanName` | `string` | | 早鸟计划名称 | -|   `isFavorited` | `boolean` | | 是否已收藏（null表示未登录） | -|   `participantFamilyCount` | `int` | | 参与家庭数 | -|   `product` | `object` | | 产品详情（来自product-service） | -|   `reviewStats` | `object` | | 评价统计数据 | -|   `topLikedReview` | `object` | | 最高点赞评价 | -|   `topRatedReview` | `object` | | 最高评分评价 | -|   `totalSold` | `int` | | 已购人数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/product/{productId}/batch-calendar - -**GROUP批次日历** - -返回可报名批次列表（出发日期、剩余名额等），仅ENROLLING和CONFIRMED状态 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `productId` | `integer` | | 产品ID | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/product/{productId}/group-quote - -**GROUP报价** - -返回指定批次的各套餐报价（totalSellPrice） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `productId` | `integer` | | 产品ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `batchId` | `integer(int64)` | | 批次ID | | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/product/{productId}/price-calendar - -**价格日历** - -返回产品指定日期范围内的每日价格，用于日历组件展示。不传日期时默认返回未来一个月 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `productId` | `integer` | | 产品ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `endDate` | `string` | | 结束日期 | | -| `startDate` | `string` | | 开始日期 | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/product/{productId}/quote - -**报价计算（含早鸟优惠）** - -报价流程：传入出发日期+人数 → 价格日历计算基础报价（与下单一致） → 匹配早鸟优惠方案 → 返回明细报价+优惠信息。 - -支付方式说明： -- FULL: 全额支付，需一次性付清全部金额 -- DEPOSIT: 定金+尾款，先付定金（比例由产品配置），出行前补齐尾款 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `productId` | `integer` | | 产品ID | - -**请求体** `产品报价请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `adultCount` | `int` | 是 | 成人数量 | -| `babyCount` | `int` | | 婴儿数量 | -| `childCount` | `int` | | 儿童数量 | -| `childNeedBed` | `boolean` | | 儿童是否需要床位 | -| `departureDate` | `string` | 是 | 出发日期 | -| `youngChildCount` | `int` | | 幼儿数量 | - -**响应** `统一响应结果«产品报价结果»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `产品报价结果` | | 响应数据 | -|   `adultSellPrice` | `number` | | 成人单价 | -|   `babySellPrice` | `number` | | 幼童单价（固定价） | -|   `childSellPrice` | `number` | | 儿童单价 | -|   `childWithBedFee` | `number` | | 儿童加床费 | -|   `depositPayment` | `定金支付选项` | | 定金支付信息（仅paymentMode=DEPOSIT时有值） | -|     `balanceAmount` | `number` | | 尾款金额（出行前需付） | -|     `depositAmount` | `number` | | 定金金额（首次需付） | -|     `depositRatio` | `int` | | 定金比例(%) | -|     `description` | `string` | | 说明 | -|   `earlyBirdDiscount` | `早鸟优惠信息` | | 早鸟优惠信息，无优惠时为null | -|     `discountAmount` | `number` | | 优惠金额 | -|     `minPeople` | `int` | | 最低人数要求 | -|     `planId` | `long` | | 优惠方案ID | -|     `planName` | `string` | | 优惠方案名称 | -|   `finalPrice` | `number` | | 最终价（早鸟优惠后） | -|   `fullPayment` | `全额支付选项` | | 全额支付信息 | -|     `amount` | `number` | | 应付金额 | -|     `description` | `string` | | 说明 | -|   `grandTotalSellPrice` | `number` | | 总售价（优惠前） | -|   `paymentMode` | `string` | | 支付方式: FULL(全额支付) / DEPOSIT(定金+尾款) | -|   `totalAdultSellPrice` | `number` | | 成人小计 | -|   `totalBabySellPrice` | `number` | | 幼童小计 | -|   `totalChildSellPrice` | `number` | | 儿童小计 | -|   `totalYoungChildSellPrice` | `number` | | 小童小计 | -|   `youngChildSellPrice` | `number` | | 小童单价（儿童价×折扣比例） | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 公共接口 - -### `GET` /mp/common/agreement/list - -**协议列表** - -获取所有已上线的协议列表（不含内容，仅含类型、标题、版本） - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/common/agreement/{type} - -**获取协议文本** - -获取指定类型的协议文本（如隐私政策、用户协议），返回富文本内容 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `type` | `string` | 是 | 协议类型: privacy(隐私政策) / user(用户协议) | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/common/config - -**应用配置** - -获取应用全局配置信息 - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/common/contact - -**联系方式列表** - -获取有效的联系方式列表（电话/微信/邮箱等） - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/common/faq - -**FAQ列表** - -获取常见问题列表（按分类分组） - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/common/feedback - -**提交反馈** - -提交用户反馈，支持文字内容和图片附件 - -**请求体** `提交反馈请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `contact` | `string` | | 联系方式 | -| `content` | `string` | 是 | 反馈内容 | -| `images` | `string[]` | | 图片URL列表 | - -**响应** `统一响应结果«Void»` - ---- - -## C端 - 出行人接口 - -### `GET` /mp/user/traveler - -**出行人列表** - -返回当前用户的所有出行人列表。如果用户已完善实名信息，列表中会自动包含一条「本人」虚拟记录(travelerId=0) - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/user/traveler - -**添加出行人** - -添加常用出行人信息（姓名/证件/联系方式等），下单时可快速选择。单个用户最多50个出行人 - -**请求体** `修改)` - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/user/traveler/{id} - -**出行人详情** - -获取单个出行人的完整信息（姓名、证件信息、联系方式等）。 - -**权限**：需登录，仅能查看自己的出行人。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 出行人ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /mp/user/traveler/{id} - -**更新出行人** - -修改出行人信息，支持部分更新（只传需要修改的字段）。已关联订单的出行人修改不影响历史订单记录。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 出行人ID | - -**请求体** `修改)` - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /mp/user/traveler/{id} - -**删除出行人** - -删除常用出行人记录。默认出行人不可删除，需先取消默认后再删除。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 出行人ID | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /mp/user/traveler/{id}/default - -**设为默认出行人** - -设为默认出行人后，下单时自动作为第一个出行人。每个用户只能有一个默认出行人 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 出行人ID | - -**响应** `统一响应结果«Void»` - ---- - -## C端 - 前端配置接口 - -### `GET` /mp/config - -**获取所有非敏感前端配置** - -返回所有非SECRET类型的前端配置项（如主题色、客服电话、版本号等）。不含敏感配置，可安全传输给小程序端。 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/config/group/{group} - -**按分组获取非敏感前端配置** - -按配置分组获取前端配置项，如UI分组、功能开关分组等。用于小程序按需加载特定分组的配置。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `group` | `string` | | 配置分组 | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 发票接口 - -### `POST` /mp/invoice/apply - -**申请开票** - -开票流程：订单完成后 → 填写发票信息(抬头/税号/类型) → 提交开票申请 → 管理员处理 → 发送电子发票 - -**请求体** `发票申请请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `email` | `string` | | 接收邮箱 | -| `invoiceTitle` | `string` | 是 | 发票抬头 | -| `invoiceType` | `string` | 是 | 发票类型: PERSONAL(个人)/COMPANY(企业) | -| `orderId` | `string` | 是 | 订单ID | -| `taxpayerId` | `string` | | 纳税人识别号（企业发票必填） | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/invoice/order/{orderId} - -**通过订单ID查询发票** - -查询指定订单的发票信息，如果订单未开票则返回null - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/invoice/{id} - -**发票详情** - -获取发票的完整信息，包含开票状态、发票抬头、税号、金额、电子发票文件链接等 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 发票ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/invoice/{invoiceId}/reissue - -**发票换开** - -对已开发票申请换开（修改抬头/税号等），原发票作废后重新开具新发票 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `invoiceId` | `integer` | | 发票ID | - -**请求体** `发票换开请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `email` | `string` | | 接收邮箱 | -| `invoiceTitle` | `string` | 是 | 发票抬头 | -| `taxNumber` | `string` | | 纳税人识别号（企业发票必填） | -| `titleType` | `string` | 是 | 抬头类型: PERSONAL(个人)/COMPANY(企业) | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 合同接口 - -### `GET` /mp/contract/by-order/{orderId} - -**按订单查合同** - -返回订单关联的最新有效合同（非作废） - -**关联字典（BFF透传）**： -- contract_status：合同状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/contract/by-order/{orderId}/all - -**按订单查所有合同** - -返回订单关联的所有有效合同（TOUR+INSURANCE各一条） - -**关联字典（BFF透传）**： -- contract_status：合同状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/contract/list - -**合同列表** - -**关联字典（BFF透传）**： -- contract_status：合同状态（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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` | | 响应消息 | - ---- - -### `POST` /mp/contract/{contractId}/resend-sms - -**重新发送合同签署短信** - -重新向出行人发送合同签署短信通知，适用于出行人未收到短信或短信过期的场景。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `contractId` | `integer` | | 合同ID | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/contract/{id} - -**合同详情** - -返回合同基本信息、签署状态、出行人签署详情及合同文件下载链接 - -**关联字典（BFF透传）**： -- contract_status：合同状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 合同ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 天气接口 - -### `GET` /mp/weather/forecast - -**获取指定城市天气预报** - -通过高德天气API查询指定城市未来3天的天气预报信息 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `city` | `string` | | 城市名称 | | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/weather/itinerary/{orderId} - -**获取订单行程天气** - -根据订单行程中的目的地城市，批量查询每日天气信息，用于行程详情页展示 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/weather/live - -**获取指定城市实况天气** - -通过高德天气API查询指定城市的实时天气（温度、湿度、风向等） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `city` | `string` | | 城市名称 | | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 字典接口 - -### `GET` /dict/all - -**获取所有字典数据** - -获取系统全部字典数据（按字典类型分组），用于小程序端的下拉选项、枚举映射等。建议前端缓存此数据 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 定制师接口 - -### `GET` /mp/designer - -**定制师列表(含真实产品数和评分，综合排序)** - -获取定制师列表，聚合层会补充每个定制师的真实产品数量和评价评分。按综合排序（评分>路线数>咨询人数），用于小程序定制师推荐页。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `limit` | `integer(int32)` | | 每页条数 | | -| `page` | `integer(int32)` | | 页码 | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/designer/featured - -**推荐定制师(综合排序第一名)** - -获取综合排序排名第一的定制师信息（含产品数和评分），用于首页推荐定制师卡片展示。 - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/designer/{id} - -**定制师详情(含产品数量和评分)** - -获取定制师完整个人信息，聚合层会补充该定制师的已发布产品数量和综合评分，用于定制师个人主页展示。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 定制师ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/designer/{id}/products - -**定制师已发布产品列表** - -**关联字典（BFF透传）**： -- product_type：产品类型（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 定制师ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/designer/{id}/reviews - -**定制师产品评价列表** - -**关联字典（BFF透传）**： -- rating_level：评价等级（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 定制师ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 徽章接口 - -### `GET` /mp/badge - -**获取徽章数据** - -返回用户的徽章统计（未读消息数、待办事项数等），用于「我的」页面角标展示 - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 心愿单接口 - -### `GET` /mp/wish - -**心愿单列表** - -返回当前用户的心愿单列表，按创建时间倒序排列 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/wish - -**创建心愿** - -创建旅行心愿，描述想去的地方和时间偏好，定制师可据此推荐产品 - -**请求体** `创建心愿单请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `notes` | `string` | | 备注 | -| `productId` | `string` | 是 | 产品ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 探索接口 - -### `GET` /mp/explore/list - -**探索列表** - -获取已启用的探索分类列表（图文攻略内容），支持综合/最新/最热排序，分页返回。用于小程序探索频道首页瀑布流展示。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `sortType` | `string` | | 排序方式：comprehensive/newest/hottest | | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/explore/{id} - -**探索详情** - -自动增加浏览量，已登录时返回点赞/收藏状态 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 探索分类ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/explore/{id}/favorite - -**切换收藏** - -对探索内容收藏/取消收藏，返回当前收藏状态（true=已收藏）。收藏后可在'我的收藏'中查看。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 探索分类ID | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/explore/{id}/like - -**切换点赞** - -对探索内容点赞/取消点赞，返回当前点赞状态（true=已点赞）。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 探索分类ID | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/explore/{id}/view - -**浏览+1** - -增加探索内容的浏览计数。前端进入探索详情页时调用，无需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 探索分类ID | - -**响应** `统一响应结果«Void»` - ---- - -## C端 - 搜索接口 - -### `GET` /mp/search - -**搜索产品** - -按关键词搜索已上架产品（匹配产品名称和描述），支持按产品类型进一步筛选 - -**关联字典（BFF透传）**： -- product_type：产品类型（筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `keyword` | `string` | | 搜索关键词 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `productType` | `string` | | 产品类型：CORE/ROUTE/CUSTOM/GROUP | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 支付接口 - -### `POST` /mp/payment/prepay - -**发起支付** - -支付流程：选择支付方式(JSAPI/H5) → 调用微信支付API → 返回支付参数 → 前端调起微信支付 - -**关联字典（BFF透传）**： -- payment_status：支付状态（返回字段） - -**请求体** `支付预下单请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `clientIp` | `string` | | 客户端IP（H5支付必填） | -| `orderId` | `string` | 是 | 订单ID | -| `tradeType` | `string` | 是 | 支付方式: JSAPI(小程序支付)/H5(H5支付) | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/payment/status/{orderId} - -**查询支付状态** - -**关联字典（BFF透传）**： -- payment_status：支付状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/payment/transactions/{orderId} - -**订单交易记录列表** - -**关联字典（BFF透传）**： -- payment_status：支付状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 收藏接口 - -### `GET` /mp/user/favorite - -**收藏列表（含资源摘要）** - -分页查询收藏列表，聚合层会补充每个收藏项对应资源的摘要信息（名称、封面图、价格等）。支持按目标类型筛选。 - -**权限**：需登录。 - -**关联字典**： -- favorite_resource_type：收藏资源类型（PRODUCT/SCENIC/RESTAURANT/ACTIVITY） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `targetType` | `string` | | 目标类型筛选（字典：favorite_resource_type）：PRODUCT/SCENIC/RESTAURANT/ACTIVITY | | - -**响应** `统一响应结果«分页结果«收藏列表项（含资源摘要）»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«收藏列表项（含资源摘要）»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `收藏列表项（含资源摘要）[]` | | 数据列表 | -|     `coverUrl` | `string` | | 封面图URL | -|     `createdAt` | `string` | | 收藏时间 | -|     `favoriteId` | `string` | | 收藏记录ID | -|     `name` | `string` | | 资源名称 | -|     `tags` | `string[]` | | 标签列表 | -|     `targetId` | `string` | | 目标资源ID | -|     `targetType` | `string` | | 目标类型（字典：favorite_resource_type） | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/user/favorite - -**添加收藏** - -将产品/景区/餐厅/活动加入收藏。同一目标重复收藏会返回已有收藏记录 - -**请求体** `收藏请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `targetId` | `string` | 是 | 目标资源ID | -| `targetType` | `string` | 是 | 目标类型（字典：favorite_resource_type） | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /mp/user/favorite/batch - -**批量删除收藏** - -批量删除多条收藏记录，传入收藏记录ID列表。用于收藏管理页面的批量操作。 - -**权限**：需登录，仅能删除自己的收藏。 - -**请求体** `long[]` - -**响应** `统一响应结果«Void»` - ---- - -### `DELETE` /mp/user/favorite/by-target - -**按目标取消收藏** - -通过目标类型+目标ID取消收藏，适用于详情页点击取消收藏的场景（不需要知道收藏记录ID）。 - -**权限**：需登录。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `targetId` | `integer(int64)` | | 目标资源ID | | -| `targetType` | `string` | | 目标类型 | | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /mp/user/favorite/check - -**检查是否已收藏** - -检查当前用户是否已收藏指定资源，用于详情页收藏按钮状态显示。 - -**权限**：需登录。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `targetId` | `integer(int64)` | | 目标资源ID | | -| `targetType` | `string` | | 目标类型（字典：favorite_resource_type） | | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /mp/user/favorite/{id} - -**取消收藏** - -通过收藏记录ID取消收藏，适用于收藏列表页的删除操作。 - -**权限**：需登录，仅能删除自己的收藏。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 收藏记录ID | - -**响应** `统一响应结果«Void»` - ---- - -## C端 - 攻略接口 - -### `GET` /mp/wiki/article/{articleId} - -**文章详情** - -**关联字典（BFF透传）**： -- wiki_status：文章状态（返回字段） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | | 文章ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/wiki/categories - -**攻略分类列表** - -获取所有已启用的攻略分类，按排序值排列。用于小程序攻略频道的分类导航展示。 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/wiki/category/{categoryId}/articles - -**分类文章列表** - -分页查询指定攻略分类下已发布的文章列表，按发布时间倒序排列。用于攻略分类详情页。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryId` | `integer` | | 攻略分类ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/wiki/recommend-articles - -**推荐文章列表** - -获取编辑推荐的攻略文章列表（按推荐权重排序），用于首页或攻略频道的推荐位展示。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `limit` | `integer(int32)` | | 返回条数 | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 景区接口 - -### `GET` /mp/scenic/list - -**景区列表** - -分页查询已上架的景区列表，支持按关键词和城市筛选。聚合层透传resource-service的景区数据。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `city` | `string` | | 城市 | | -| `keyword` | `string` | | 关键词 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/scenic/{scenicId} - -**景区详情** - -获取景区完整信息（含季节素材、图文详情、价格等），自动注入静态地图图片URL用于详情页地图展示。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `scenicId` | `integer` | | 景区ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/scenic/{scenicId}/nearby - -**附近景区（地理+探索分类聚合）** - -聚合两个数据源：1.基于经纬度的地理位置附近景区（resource-service）；2.探索分类关联的景区（user-service）。去重合并后返回，用于景区详情页底部'附近推荐'展示。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `scenicId` | `integer` | | 景区ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `limit` | `integer(int32)` | | 返回条数 | | -| `radius` | `number(double)` | | 搜索半径(km) | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 活动接口 - -### `GET` /mp/activity/list - -**活动列表** - -分页查询已上架的活动列表，支持关键词和分类筛选。聚合层透传resource-service的活动数据给小程序前端。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `categoryCode` | `string` | | 分类 | | -| `keyword` | `string` | | 关键词 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/activity/{activityId} - -**活动详情** - -获取活动完整信息（含图文详情、价格等），自动注入静态地图图片URL用于详情页地图展示。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `activityId` | `integer` | | 活动ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 消息接口 - -### `GET` /mp/message/list - -**消息列表** - -消息列表，支持按分类筛选，按时间倒序分页返回 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `category` | `string` | | 消息分类筛选，不传返回全部 | | -| `page` | `integer(int32)` | | 页码，默认1 | | -| `pageSize` | `integer(int32)` | | 每页条数，默认20 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /mp/message/read-all - -**全部标记已读** - -将指定分类或全部消息标记为已读，不传category则全部已读 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `category` | `string` | | 消息分类，不传则将所有分类标记为已读 | | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /mp/message/summary - -**消息摘要** - -获取各分类的未读数量和最新一条消息，用于消息中心首页展示 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /mp/message/{id} - -**删除消息** - -删除单条消息 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | 是 | 消息ID | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /mp/message/{id}/read - -**标记已读** - -标记单条消息为已读 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | 是 | 消息ID | - -**响应** `统一响应结果«Void»` - ---- - -## C端 - 用户接口 - -### `DELETE` /mp/user/account - -**注销账号** - -注销后用户数据将被软删除，30天内可联系客服恢复 - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /mp/user/login - -**微信登录** - -登录流程：小程序wx.login获取code → 后端换取openid → 查找/创建用户 → 返回JWT令牌+needProfile标记 - -**请求体** `微信登录请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `string` | 是 | 微信授权code | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/user/login/sms - -**短信登录** - -登录流程：获取验证码 → 验证手机号+验证码 → 查找/创建用户 → 返回JWT令牌 - -**请求体** `短信验证码登录请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `string` | 是 | 验证码 | -| `phone` | `string` | 是 | 手机号 | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/user/logout - -**用户登出** - -清除用户登录状态和服务端缓存的令牌信息。登出后需重新登录获取新令牌。 - -**权限**：需登录。 - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /mp/user/ocr/idcard - -**身份证OCR识别** - -将身份证图片上传到OSS后，传入ossUrl进行OCR识别。返回姓名、身份证号、性别、民族等结构化数据，可用于自动填充出行人信息 - -**请求体** `身份证OCR识别请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `imgUrl` | `string` | 是 | 身份证图片的OSS地址 | - -**响应** `统一响应结果«Map«string,string»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/user/profile - -**获取用户信息** - -获取当前登录用户的个人资料，包含头像、昵称、手机号、实名信息等 - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /mp/user/profile - -**更新用户信息** - -更新当前用户的个人资料，支持部分更新（只传需要修改的字段）。首次完善资料时realName为必填 - -**请求体** `更新个人资料请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `avatar` | `string` | | 头像URL | -| `birthday` | `string` | | 生日 | -| `email` | `string` | | 邮箱 | -| `gender` | `int` | | 性别: 1=男, 2=女 | -| `nationality` | `string` | | 国籍 | -| `nickname` | `string` | | 昵称 | -| `phone` | `string` | | 手机号 | -| `realName` | `string` | | 真实姓名 | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/user/sms/send - -**发送短信验证码** - -向指定手机号发送登录验证码，有效期5分钟，60秒内不可重复发送 - -**请求体** `发送短信验证码请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `phone` | `string` | 是 | 手机号 | - -**响应** `统一响应结果«Void»` - ---- - -## C端 - 相册接口 - -### `GET` /mp/album/file/{albumFileId}/download-url - -**获取文件下载链接** - -获取文件的预签名下载URL，有效期有限 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `albumFileId` | `integer` | 是 | 相册文件ID | - -**响应** `统一响应结果«string»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `string` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/album/folder/{folderId}/files - -**文件夹下的文件列表** - -获取文件夹下的文件列表（分页），含图片和视频 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `folderId` | `integer` | 是 | 文件夹ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码，默认1 | | -| `size` | `integer(int32)` | | 每页数量，默认20 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/album/order/{orderId}/folders - -**订单的文件夹列表** - -获取订单下的相册文件夹列表 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | 是 | 订单ID | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/album/orders - -**有相册的订单列表** - -获取当前登录用户有相册的订单列表 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 行程接口 - -### `GET` /mp/trip/list - -**行程列表** - -获取当前登录用户的行程列表（已确认及进行中的订单对应的行程） - -**关联字典（BFF透传）**： -- order_status：订单/行程状态（显示） - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/trip/today - -**今日行程** - -获取今日行程（如果有正在进行中的行程），无行程时data为null - -**关联字典（BFF透传）**： -- order_status：订单/行程状态（显示） - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/trip/weather - -**天气查询** - -高德天气API代理，传入城市名称返回实时天气信息 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `city` | `string` | 是 | 城市名称，如「成都」「拉萨」 | | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/trip/{orderId} - -**行程详情** - -获取订单对应的行程详情，含每日行程节点信息（景点/酒店/餐厅等） - -**关联字典（BFF透传）**： -- order_status：订单/行程状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | 是 | 订单ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 订单接口 - -### `POST` /mp/order/bind-by-contact - -**绑定未绑定的订单** - -绑定流程：用户登录 → 完善个人资料 → 自动通过联系人手机号+姓名匹配 → 将userId=NULL的订单绑定到当前用户 - -**请求体** `通过联系人信息绑定订单请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `contactName` | `string` | 是 | 联系人姓名 | -| `contactPhone` | `string` | 是 | 联系人手机号 | - -**响应** `统一响应结果«int»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `int` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/count - -**各状态订单数量** - -统计当前用户各状态的订单数量，用于「我的」页面的订单状态角标展示 - -**关联字典（BFF透传）**： -- order_status：订单状态（状态分类统计） - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/order/create - -**创建订单** - -下单流程：选择产品 → 填写联系人/出行人信息 → 报价计算 → 创建订单 → 返回订单ID - -**请求体** `C端创建订单请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `adultCount` | `int` | | 成人数 | -| `babyCount` | `int` | | 幼童数 | -| `childCount` | `int` | | 儿童数 | -| `childNeedBed` | `boolean` | | 儿童是否需要床位 | -| `contactName` | `string` | 是 | 联系人姓名 | -| `contactPhone` | `string` | 是 | 联系人电话 | -| `customizerId` | `string` | | 定制师ID(通过分享链接下单时传入) | -| `departureDate` | `string` | | 出发日期(GROUP产品从团期获取，可不传) | -| `groupBatchId` | `string` | | 团期ID(GROUP产品必填) | -| `productId` | `string` | 是 | 产品ID | -| `remark` | `string` | | 备注 | -| `roomCount` | `int` | | 房间数(GROUP产品，默认1) | -| `sharerOpenid` | `string` | | 分享人微信openid（通过分享进入下单时传入，用于记录分享关系） | -| `travelers` | `出行人信息[]` | | 出行人列表 | -|   `birthday` | `string` | | 出生日期 | -|   `email` | `string` | | 电子邮箱 | -|   `emergencyContact` | `string` | | 紧急联系人 | -|   `emergencyPhone` | `string` | | 紧急联系电话 | -|   `gender` | `int` | | 性别（1=男, 2=女） | -|   `idCardNo` | `string` | | 证件号码 | -|   `idCardType` | `string` | | 证件类型 | -|   `name` | `string` | 是 | 出行人姓名 | -|   `nationality` | `string` | | 国籍 | -|   `phone` | `string` | | 手机号 | -|   `travelerType` | `string` | | 出行人类型（ADULT/CHILD/YOUNG_CHILD/BABY） | -| `youngChildCount` | `int` | | 小童数 | - -**响应** `统一响应结果«订单详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `订单详情` | | 响应数据 | -|   `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` | `Map«string,object»[]` | | 优惠列表 | -|   `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` | | 支付模式（FULL/DEPOSIT） | -|   `processStatus` | `string` | | 内部流程状态 | -|   `processStatusLabel` | `string` | | 内部流程状态标签 | -|   `productCoverUrl` | `string` | | 产品封面图URL | -|   `productId` | `long` | | 产品ID | -|   `productName` | `string` | | 产品名称 | -|   `productSnapshot` | `string` | | 产品快照JSON | -|   `productType` | `string` | | 产品类型（CORE/ROUTE/CUSTOM/GROUP） | -|   `readyAt` | `string` | | 就绪时间 | -|   `refundAmount` | `number` | | 退款金额 | -|   `remark` | `string` | | 备注 | -|   `returnDate` | `string` | | 返程日期（出发日期 + 行程天数 - 1） | -|   `reviewed` | `boolean` | | 是否已评价 | -|   `roomInfo` | `string` | | 房间信息 | -|   `status` | `string` | | 订单状态（PENDING_PAY/DEPOSIT_PAID/PAID/CONFIRMED/IN_PROGRESS/COMPLETED/CANCELLED） | -|   `statusLabel` | `string` | | 订单状态标签 | -|   `timeline` | `Map«string,object»[]` | | 时间线列表 | -|   `todos` | `Map«string,object»[]` | | 待办列表 | -|   `totalPrice` | `number` | | 总售价 | -|   `travelers` | `Map«string,object»[]` | | 出行人列表 | -|   `tripDays` | `int` | | 行程天数 | -|   `tripNights` | `int` | | 行程晚数 | -|   `unlockRequestedAt` | `string` | | 解锁请求时间 | -|   `userId` | `long` | | 用户ID | -|   `vehicleInfo` | `string` | | 车辆信息 | -|   `youngChildCount` | `int` | | 小童数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/list - -**订单列表** - -分页查询当前用户的订单列表，支持按状态筛选。返回订单摘要信息（不含详细出行人信息） - -**关联字典（BFF透传）**： -- order_status：订单状态（列表筛选+显示） -- product_type：产品类型（订单卡片显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `status` | `string` | | 状态 | | - -**响应** `统一响应结果«分页结果«订单列表项»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«订单列表项»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `订单列表项[]` | | 数据列表 | -|     `adultCount` | `int` | | 成人数 | -|     `babyCount` | `int` | | 幼童数 | -|     `balanceAmount` | `number` | | 尾款金额 | -|     `childCount` | `int` | | 儿童数 | -|     `contracts` | `Map«string,object»[]` | | 合同列表（含signUrl/fileUrl/status等） | -|     `createTime` | `string` | | 创建时间 | -|     `daysUntilDeparture` | `int` | | 距出发天数（负数表示已出发） | -|     `departureDate` | `string` | | 出发日期 | -|     `depositAmount` | `number` | | 定金金额 | -|     `displayName` | `string` | | 显示名称（未支付=手机号+姓名，已支付=订单号） | -|     `displayStatus` | `string` | | C端简化状态（PENDING_PAY/PENDING_DEPARTURE/PENDING_REVIEW/REFUND/CANCELLED） | -|     `displayStatusLabel` | `string` | | C端简化状态标签 | -|     `expiryTime` | `string` | | 支付截止时间（PENDING_PAY状态有效） | -|     `insurances` | `Map«string,object»[]` | | 保险订单列表（含productName/extPolicyNo/status等） | -|     `nextAction` | `string` | | 下一步操作提示 | -|     `orderId` | `long` | | 订单ID | -|     `orderNo` | `string` | | 订单编号 | -|     `paidAmount` | `number` | | 已付金额 | -|     `paymentMode` | `string` | | 支付模式（FULL/DEPOSIT） | -|     `processStatus` | `string` | | 内部流程状态（字典：order_process_status） | -|     `processStatusLabel` | `string` | | 内部流程状态标签（字典：order_process_status 翻译） | -|     `productCoverUrl` | `string` | | 产品封面图URL | -|     `productId` | `long` | | 产品ID | -|     `productName` | `string` | | 产品名称 | -|     `productType` | `string` | | 产品类型（CORE/ROUTE/CUSTOM/GROUP） | -|     `status` | `string` | | 订单状态（PENDING_PAY/DEPOSIT_PAID/PAID/CONFIRMED/IN_PROGRESS/COMPLETED/CANCELLED） | -|     `statusLabel` | `string` | | 订单状态标签 | -|     `totalPrice` | `number` | | 总售价 | -|     `tripDays` | `int` | | 行程天数 | -|     `tripNights` | `int` | | 行程晚数 | -|     `youngChildCount` | `int` | | 小童数 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/lookup - -**通过联系人手机号+姓名查找订单（无需登录）** - -无需登录即可查询。用于管理员代下单场景：管理员创建订单后，用户通过联系人手机号+姓名查找订单并绑定到自己账号。仅返回尚未绑定用户(userId=NULL)的订单。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `contactName` | `string` | | 联系人姓名 | | -| `contactPhone` | `string` | | 联系人手机号 | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/upcoming - -**即将出发的订单** - -查询3天内即将出发的订单（状态为已确认/待出发/出行中），含合同和保险信息，按出发日期升序 - -**响应** `统一响应结果«List«订单列表项»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `订单列表项[]` | | 响应数据 | -|   `adultCount` | `int` | | 成人数 | -|   `babyCount` | `int` | | 幼童数 | -|   `balanceAmount` | `number` | | 尾款金额 | -|   `childCount` | `int` | | 儿童数 | -|   `contracts` | `Map«string,object»[]` | | 合同列表（含signUrl/fileUrl/status等） | -|   `createTime` | `string` | | 创建时间 | -|   `daysUntilDeparture` | `int` | | 距出发天数（负数表示已出发） | -|   `departureDate` | `string` | | 出发日期 | -|   `depositAmount` | `number` | | 定金金额 | -|   `displayName` | `string` | | 显示名称（未支付=手机号+姓名，已支付=订单号） | -|   `displayStatus` | `string` | | C端简化状态（PENDING_PAY/PENDING_DEPARTURE/PENDING_REVIEW/REFUND/CANCELLED） | -|   `displayStatusLabel` | `string` | | C端简化状态标签 | -|   `expiryTime` | `string` | | 支付截止时间（PENDING_PAY状态有效） | -|   `insurances` | `Map«string,object»[]` | | 保险订单列表（含productName/extPolicyNo/status等） | -|   `nextAction` | `string` | | 下一步操作提示 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `paidAmount` | `number` | | 已付金额 | -|   `paymentMode` | `string` | | 支付模式（FULL/DEPOSIT） | -|   `processStatus` | `string` | | 内部流程状态（字典：order_process_status） | -|   `processStatusLabel` | `string` | | 内部流程状态标签（字典：order_process_status 翻译） | -|   `productCoverUrl` | `string` | | 产品封面图URL | -|   `productId` | `long` | | 产品ID | -|   `productName` | `string` | | 产品名称 | -|   `productType` | `string` | | 产品类型（CORE/ROUTE/CUSTOM/GROUP） | -|   `status` | `string` | | 订单状态（PENDING_PAY/DEPOSIT_PAID/PAID/CONFIRMED/IN_PROGRESS/COMPLETED/CANCELLED） | -|   `statusLabel` | `string` | | 订单状态标签 | -|   `totalPrice` | `number` | | 总售价 | -|   `tripDays` | `int` | | 行程天数 | -|   `tripNights` | `int` | | 行程晚数 | -|   `youngChildCount` | `int` | | 小童数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/{orderId} - -**订单详情** - -获取订单完整信息，包含产品快照、出行人列表、支付信息、合同状态等 - -**关联字典（BFF透传）**： -- order_status：订单状态（显示） -- product_type：产品类型（显示） -- contract_status：合同状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«订单详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `订单详情` | | 响应数据 | -|   `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` | `Map«string,object»[]` | | 优惠列表 | -|   `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` | | 支付模式（FULL/DEPOSIT） | -|   `processStatus` | `string` | | 内部流程状态 | -|   `processStatusLabel` | `string` | | 内部流程状态标签 | -|   `productCoverUrl` | `string` | | 产品封面图URL | -|   `productId` | `long` | | 产品ID | -|   `productName` | `string` | | 产品名称 | -|   `productSnapshot` | `string` | | 产品快照JSON | -|   `productType` | `string` | | 产品类型（CORE/ROUTE/CUSTOM/GROUP） | -|   `readyAt` | `string` | | 就绪时间 | -|   `refundAmount` | `number` | | 退款金额 | -|   `remark` | `string` | | 备注 | -|   `returnDate` | `string` | | 返程日期（出发日期 + 行程天数 - 1） | -|   `reviewed` | `boolean` | | 是否已评价 | -|   `roomInfo` | `string` | | 房间信息 | -|   `status` | `string` | | 订单状态（PENDING_PAY/DEPOSIT_PAID/PAID/CONFIRMED/IN_PROGRESS/COMPLETED/CANCELLED） | -|   `statusLabel` | `string` | | 订单状态标签 | -|   `timeline` | `Map«string,object»[]` | | 时间线列表 | -|   `todos` | `Map«string,object»[]` | | 待办列表 | -|   `totalPrice` | `number` | | 总售价 | -|   `travelers` | `Map«string,object»[]` | | 出行人列表 | -|   `tripDays` | `int` | | 行程天数 | -|   `tripNights` | `int` | | 行程晚数 | -|   `unlockRequestedAt` | `string` | | 解锁请求时间 | -|   `userId` | `long` | | 用户ID | -|   `vehicleInfo` | `string` | | 车辆信息 | -|   `youngChildCount` | `int` | | 小童数 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/order/{orderId}/approve-unlock - -**同意解锁订单** - -用户同意管理员的修改请求，解除订单锁定状态，允许管理员继续修改订单 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /mp/order/{orderId}/cancel - -**取消订单** - -取消规则：仅PENDING_PAY/DEPOSIT_PAID状态可用户取消，取消后不可恢复 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**请求体** `用户取消订单请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reason` | `string` | | 取消原因 | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /mp/order/{orderId}/edit - -**修改订单** - -用户可修改出发日期和出行人。仅待支付/已付定金/已支付/已确认/待付尾款/待出发状态可修改，清单已确认的订单不允许修改。修改后重走内部流程 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**请求体** `修改订单请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `departureDate` | `string` | | 出发日期 | -| `travelers` | `出行人信息_1[]` | | 出行人列表（提供则替换全部出行人） | -|   `birthday` | `string` | | 出生日期 | -|   `email` | `string` | | 电子邮箱 | -|   `emergencyContact` | `string` | | 紧急联系人 | -|   `emergencyPhone` | `string` | | 紧急联系电话 | -|   `gender` | `int` | | 性别 | -|   `idCardNo` | `string` | | 证件号码 | -|   `idCardType` | `string` | | 证件类型 | -|   `name` | `string` | 是 | 出行人姓名 | -|   `nationality` | `string` | | 国籍 | -|   `phone` | `string` | | 手机号 | -|   `travelerType` | `string` | | 出行人类型 | - -**响应** `统一响应结果«订单详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `订单详情` | | 响应数据 | -|   `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` | `Map«string,object»[]` | | 优惠列表 | -|   `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` | | 支付模式（FULL/DEPOSIT） | -|   `processStatus` | `string` | | 内部流程状态 | -|   `processStatusLabel` | `string` | | 内部流程状态标签 | -|   `productCoverUrl` | `string` | | 产品封面图URL | -|   `productId` | `long` | | 产品ID | -|   `productName` | `string` | | 产品名称 | -|   `productSnapshot` | `string` | | 产品快照JSON | -|   `productType` | `string` | | 产品类型（CORE/ROUTE/CUSTOM/GROUP） | -|   `readyAt` | `string` | | 就绪时间 | -|   `refundAmount` | `number` | | 退款金额 | -|   `remark` | `string` | | 备注 | -|   `returnDate` | `string` | | 返程日期（出发日期 + 行程天数 - 1） | -|   `reviewed` | `boolean` | | 是否已评价 | -|   `roomInfo` | `string` | | 房间信息 | -|   `status` | `string` | | 订单状态（PENDING_PAY/DEPOSIT_PAID/PAID/CONFIRMED/IN_PROGRESS/COMPLETED/CANCELLED） | -|   `statusLabel` | `string` | | 订单状态标签 | -|   `timeline` | `Map«string,object»[]` | | 时间线列表 | -|   `todos` | `Map«string,object»[]` | | 待办列表 | -|   `totalPrice` | `number` | | 总售价 | -|   `travelers` | `Map«string,object»[]` | | 出行人列表 | -|   `tripDays` | `int` | | 行程天数 | -|   `tripNights` | `int` | | 行程晚数 | -|   `unlockRequestedAt` | `string` | | 解锁请求时间 | -|   `userId` | `long` | | 用户ID | -|   `vehicleInfo` | `string` | | 车辆信息 | -|   `youngChildCount` | `int` | | 小童数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/{orderId}/resources - -**订单资源详情（按分类）** - -解析产品快照，提取资源详情按分类返回 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«Map«string,List«Map«string,object»»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 评价接口 - -### `POST` /mp/review/create - -**创建评价** - -评价流程：订单完成后 → 查询可评价目标列表 → 对每个目标(酒店/景区/活动等)提交评价 → 自动内容审核 → 审核通过后公开展示 - -**关联字典（BFF透传）**： -- review_status：评价审核状态（返回字段） -- rating_level：评价等级（返回字段） - -**请求体** `创建评价请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `content` | `string` | 是 | 评价内容(10-500字) | -| `images` | `评价图片项[]` | | 评价图片列表（最多9张） | -|   `fileId` | `long` | | 文件ID | -|   `imageUrl` | `string` | 是 | 图片URL | -| `orderId` | `long` | 是 | 订单ID | -| `ratings` | `object` | 是 | 评分数据（key为评分类别字典的dictValue，value为1-5整数）。先调用 GET /mp/review/rating-categories 获取评分维度，required=true的必填。示例: {"ratingItinerary":5,"ratingAccommodation":4,"ratingDriver":5,"ratingDining":4,"ratingOverall":5} | -| `videos` | `评价视频项[]` | | 评价视频列表（最多3个） | -|   `coverUrl` | `string` | | 视频封面URL | -|   `duration` | `int` | | 视频时长(秒) | -|   `fileId` | `long` | | 文件ID | -|   `videoUrl` | `string` | 是 | 视频URL | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/featured - -**精选评价列表(公开)** - -无需登录，返回精选评价数组，用于评价浏览页 - -**关联字典（BFF透传）**： -- rating_level：评价等级（显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `limit` | `integer(int32)` | | 数量限制 | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/my - -**我的评价列表** - -**关联字典（BFF透传）**： -- review_status：评价审核状态（显示） -- rating_level：评价等级（显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/order/{orderId}/reviewable-targets - -**订单可评价目标列表** - -返回订单中可评价的资源目标列表（景区/酒店/活动等），用于评价页面展示可评价项。已评价的目标不会重复出现。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/order/{orderId}/reviewed - -**检查订单是否已评价** - -检查指定订单是否已提交评价，用于订单详情页决定是否显示'去评价'按钮。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/product/{productId} - -**按产品ID查看评价列表** - -返回评价列表+统计数据，支持好中差评/有图/有视频筛选 - -**关联字典（BFF透传）**： -- rating_level：评价等级（筛选+显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `productId` | `integer` | | 产品ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `hasImage` | `boolean` | | 是否有图片 | | -| `hasVideo` | `boolean` | | 是否有视频 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `ratingLevel` | `string` | | 评价等级: GOOD/MEDIUM/BAD | | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/product/{productId}/highlights - -**产品精选评价(最高评分+最高点赞+统计)** - -用于产品详情页评价区域展示 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `productId` | `integer` | | 产品ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/rating-categories - -**评分类别列表** - -从字典读取评价时需要填写的评分维度，前端据此渲染评分组件。字典类型: review_rating_category，remark字段包含扩展JSON(required/min/max) - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/search - -**关键词搜索评价(公开)** - -按关键词搜索已通过的评价内容，支持按目标类型和目标ID筛选 - -**关联字典（BFF透传）**： -- rating_level：评价等级（显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `keyword` | `string` | 是 | 搜索关键词 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `targetId` | `integer(int64)` | | 目标ID(可选) | | -| `targetType` | `string` | | 目标类型(可选): PRODUCT/SCENIC_SPOT/ACTIVITY/HOTEL等 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/stats - -**评价统计(平均分、数量)** - -获取指定目标的评价统计数据（平均评分、总评价数等），用于详情页评价区域展示。产品showReview关闭时返回空统计。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `targetId` | `integer(int64)` | | 目标ID | | -| `targetType` | `string` | | 目标类型 | | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/target - -**某目标的已通过评价(公开)** - -**关联字典（BFF透传）**： -- rating_level：评价等级（筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `hasImage` | `boolean` | | 是否有图片 | | -| `hasVideo` | `boolean` | | 是否有视频 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `ratingLevel` | `string` | | 评价等级: GOOD/MEDIUM/BAD | | -| `targetId` | `integer(int64)` | | 目标ID | | -| `targetType` | `string` | | 目标类型 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/review/{reviewId}/like - -**点赞/取消点赞评价** - -对评价进行点赞或取消点赞操作，返回当前点赞状态和点赞总数。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reviewId` | `integer` | | 评价ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/{reviewId}/like/check - -**检查是否已点赞** - -检查当前用户是否已点赞指定评价，用于评价列表/详情的点赞按钮状态展示。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reviewId` | `integer` | | 评价ID | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 足迹接口 - -### `GET` /mp/user/footprint - -**足迹列表（含资源摘要）** - -分页查询浏览足迹列表，聚合层会补充每条足迹对应资源的摘要信息（名称、封面图等）。支持按资源类型筛选，按浏览时间倒序。 - -**权限**：需登录。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `resourceType` | `string` | | 资源类型筛选：PRODUCT/SCENIC/RESTAURANT/ACTIVITY | | - -**响应** `统一响应结果«分页结果«足迹列表项（含资源摘要）»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«足迹列表项（含资源摘要）»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `足迹列表项（含资源摘要）[]` | | 数据列表 | -|     `coverUrl` | `string` | | 封面图URL | -|     `footprintId` | `string` | | 足迹记录ID | -|     `name` | `string` | | 资源名称 | -|     `resourceId` | `string` | | 资源ID | -|     `resourceType` | `string` | | 资源类型：PRODUCT/SCENIC/RESTAURANT/ACTIVITY | -|     `tags` | `string[]` | | 标签列表 | -|     `visitTime` | `string` | | 浏览时间 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/user/footprint - -**记录足迹** - -记录用户浏览资源的足迹，同一资源重复浏览会更新浏览时间而非新增记录 - -**请求体** `添加足迹请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `resourceId` | `string` | 是 | 资源ID | -| `resourceType` | `string` | 是 | 资源类型: PRODUCT/SCENIC/RESTAURANT/ACTIVITY | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /mp/user/footprint/batch - -**批量删除足迹** - -批量删除多条浏览足迹记录，传入足迹ID列表。用于足迹管理页面的批量清理。 - -**权限**：需登录，仅能删除自己的足迹。 - -**请求体** `long[]` - -**响应** `统一响应结果«Void»` - ---- - -### `DELETE` /mp/user/footprint/{id} - -**删除足迹** - -删除单条浏览足迹记录。 - -**权限**：需登录，仅能删除自己的足迹。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 足迹ID | - -**响应** `统一响应结果«Void»` - ---- - -## C端 - 轮播图接口 - -### `GET` /mp/banner/active - -**获取当前生效的轮播图列表** - -返回当前处于有效期内的轮播图，按排序值排列。用于小程序首页顶部轮播展示，透传自user-service。 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 退款接口 - -### `GET` /mp/order/refund-reasons - -**退款原因列表** - -返回系统预设的退款原因选项，用于退款申请页面的原因选择 - -**响应** `统一响应结果«List«退款原因»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款原因[]` | | 响应数据 | -|   `category` | `string` | | 分类: GENERAL(通用)/PRODUCT(产品问题)/SERVICE(服务问题) | -|   `enabled` | `boolean` | | 是否启用 | -|   `reasonId` | `long` | | 原因ID | -|   `reasonText` | `string` | | 原因描述 | -|   `sortOrder` | `int` | | 排序序号 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/refund/{applicationId} - -**退款申请详情** - -获取退款申请的完整信息，包含审核状态、退款金额、退款进度和操作记录 - -**关联字典（BFF透传）**： -- order_status：订单状态（显示） -- payment_status：支付/退款状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `applicationId` | `integer` | | 退款申请ID | - -**响应** `统一响应结果«退款申请详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款申请详情` | | 响应数据 | -|   `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` | | 审批编号（企微OA审批编号） | -|   `autoRefundDeadline` | `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` | | 退款类型: DEPOSIT(定金)/BALANCE(尾款)/FULL(全款) | -|   `refundTypeLabel` | `string` | | 退款类型中文标签 | -|   `refundedAt` | `string` | | 退款完成时间 | -|   `reviewAdminId` | `long` | | 审批管理员ID | -|   `reviewAdminName` | `string` | | 审批管理员姓名 | -|   `reviewRemark` | `string` | | 审批备注 | -|   `reviewedAt` | `string` | | 审批时间 | -|   `status` | `string` | | 退款状态: PENDING(待审核)/APPROVED(已通过)/REJECTED(已拒绝)/REFUNDING(退款中)/REFUNDED(已退款)/CANCELLED(已撤回)/APPEALING(申诉中)/APPEAL_APPROVED(申诉通过)/APPEAL_REJECTED(申诉驳回) | -|   `statusLabel` | `string` | | 退款状态中文标签 | -|   `updateTime` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/order/refund/{applicationId}/appeal - -**发起申诉** - -退款被拒绝后，用户可在3天内发起一次申诉，由上级管理员重新审核 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `applicationId` | `integer` | | 退款申请ID | - -**请求体** `退款申诉请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `appealReason` | `string` | 是 | 申诉原因 | -| `evidence` | `string[]` | | 申诉凭证图片URL列表 | - -**响应** `统一响应结果«退款申请详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款申请详情` | | 响应数据 | -|   `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` | | 审批编号（企微OA审批编号） | -|   `autoRefundDeadline` | `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` | | 退款类型: DEPOSIT(定金)/BALANCE(尾款)/FULL(全款) | -|   `refundTypeLabel` | `string` | | 退款类型中文标签 | -|   `refundedAt` | `string` | | 退款完成时间 | -|   `reviewAdminId` | `long` | | 审批管理员ID | -|   `reviewAdminName` | `string` | | 审批管理员姓名 | -|   `reviewRemark` | `string` | | 审批备注 | -|   `reviewedAt` | `string` | | 审批时间 | -|   `status` | `string` | | 退款状态: PENDING(待审核)/APPROVED(已通过)/REJECTED(已拒绝)/REFUNDING(退款中)/REFUNDED(已退款)/CANCELLED(已撤回)/APPEALING(申诉中)/APPEAL_APPROVED(申诉通过)/APPEAL_REJECTED(申诉驳回) | -|   `statusLabel` | `string` | | 退款状态中文标签 | -|   `updateTime` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/order/refund/{applicationId}/cancel - -**撤回退款申请** - -仅PENDING状态的退款申请可撤回，撤回后订单恢复到原状态 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `applicationId` | `integer` | | 退款申请ID | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /mp/order/{orderId}/refund - -**提交退款申请** - -退款流程：获取退款预览 → 选择退款原因 → 提交退款申请 → 管理员审核 → 审核通过后自动退款到原支付方式 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**请求体** `退款申请请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `images` | `string[]` | | 退款凭证图片URL列表 | -| `reasonDetail` | `string` | | 退款补充说明 | -| `reasonId` | `string` | | 退款原因ID（已废弃，改用字典） | -| `reasonText` | `string` | 是 | 退款原因文本 | -| `reasonValue` | `string` | | 退款原因字典值 | -| `refundType` | `string` | 是 | 退款类型（FULL/DEPOSIT/BALANCE） | - -**响应** `统一响应结果«退款申请详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款申请详情` | | 响应数据 | -|   `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` | | 审批编号（企微OA审批编号） | -|   `autoRefundDeadline` | `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` | | 退款类型: DEPOSIT(定金)/BALANCE(尾款)/FULL(全款) | -|   `refundTypeLabel` | `string` | | 退款类型中文标签 | -|   `refundedAt` | `string` | | 退款完成时间 | -|   `reviewAdminId` | `long` | | 审批管理员ID | -|   `reviewAdminName` | `string` | | 审批管理员姓名 | -|   `reviewRemark` | `string` | | 审批备注 | -|   `reviewedAt` | `string` | | 审批时间 | -|   `status` | `string` | | 退款状态: PENDING(待审核)/APPROVED(已通过)/REJECTED(已拒绝)/REFUNDING(退款中)/REFUNDED(已退款)/CANCELLED(已撤回)/APPEALING(申诉中)/APPEAL_APPROVED(申诉通过)/APPEAL_REJECTED(申诉驳回) | -|   `statusLabel` | `string` | | 退款状态中文标签 | -|   `updateTime` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/{orderId}/refund-detail - -**根据订单ID获取最新退款详情** - -查询订单关联的最新一条退款申请详情，无退款记录时返回null - -**关联字典（BFF透传）**： -- order_status：订单状态（显示） -- payment_status：支付/退款状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `string` | | 订单ID | - -**响应** `统一响应结果«退款申请详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款申请详情` | | 响应数据 | -|   `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` | | 审批编号（企微OA审批编号） | -|   `autoRefundDeadline` | `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` | | 退款类型: DEPOSIT(定金)/BALANCE(尾款)/FULL(全款) | -|   `refundTypeLabel` | `string` | | 退款类型中文标签 | -|   `refundedAt` | `string` | | 退款完成时间 | -|   `reviewAdminId` | `long` | | 审批管理员ID | -|   `reviewAdminName` | `string` | | 审批管理员姓名 | -|   `reviewRemark` | `string` | | 审批备注 | -|   `reviewedAt` | `string` | | 审批时间 | -|   `status` | `string` | | 退款状态: PENDING(待审核)/APPROVED(已通过)/REJECTED(已拒绝)/REFUNDING(退款中)/REFUNDED(已退款)/CANCELLED(已撤回)/APPEALING(申诉中)/APPEAL_APPROVED(申诉通过)/APPEAL_REJECTED(申诉驳回) | -|   `statusLabel` | `string` | | 退款状态中文标签 | -|   `updateTime` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/{orderId}/refund-preview - -**退款金额预览** - -根据退款政策和订单出发日期计算可退金额，展示退款比例和扣除金额明细 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«退款预览»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款预览` | | 响应数据 | -|   `calculatedAmount` | `number` | | 计算退款金额 | -|   `daysBeforeDept` | `int` | | 距出发天数 | -|   `departureDate` | `string` | | 出发日期 | -|   `message` | `string` | | 提示信息 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单号 | -|   `paidAmount` | `number` | | 已付金额 | -|   `policyId` | `long` | | 匹配的退款政策ID | -|   `policyName` | `string` | | 匹配的退款政策名称 | -|   `refundRatio` | `int` | | 退款比例（百分比） | -|   `refundType` | `string` | | 退款类型: DEPOSIT/BALANCE/FULL | -|   `refundable` | `boolean` | | 是否可退款 | -|   `rules` | `退款规则项[]` | | 退款规则列表（按天数降序） | -|     `matched` | `boolean` | | 是否当前命中此规则 | -|     `minDays` | `int` | | 最低天数 | -|     `refundRatio` | `int` | | 退款比例（百分比） | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 通用点赞 - -### `POST` /mp/like/{targetType}/batch-check - -**批量检查点赞状态** - -批量检查当前用户是否已对多个目标点赞，返回已点赞的目标ID列表。用于列表页批量展示点赞状态。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `targetType` | `string` | | 目标类型 | - -**请求体** `string[]` - -**响应** `统一响应结果«List«string»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `string[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/like/{targetType}/{targetId} - -**切换点赞** - -点赞/取消点赞，返回 {liked: true/false, likeCount: 点赞数} - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `targetId` | `integer` | | 目标ID | -| `targetType` | `string` | | 目标类型: REVIEW/EXPLORE/GUIDE等 | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/like/{targetType}/{targetId}/check - -**检查是否已点赞** - -检查当前用户是否已对指定目标点赞，用于前端点赞按钮状态展示。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `targetId` | `integer` | | 目标ID | -| `targetType` | `string` | | 目标类型 | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 酒店接口 - -### `GET` /mp/hotel/list - -**酒店列表** - -分页查询已上架的酒店列表，支持按关键词、城市、星级筛选。聚合层透传resource-service的酒店数据。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `city` | `string` | | 城市 | | -| `keyword` | `string` | | 关键词 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `starLevel` | `integer(int32)` | | 星级 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/hotel/{hotelId} - -**酒店详情** - -获取酒店完整信息（含房型列表、图文详情、价格等），自动注入静态地图图片URL用于详情页地图展示。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `hotelId` | `integer` | | 酒店ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 餐厅接口 - -### `GET` /mp/restaurant/list - -**餐厅列表** - -分页查询已上架的餐厅列表，支持按关键词和城市筛选。聚合层透传resource-service的餐厅数据。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `city` | `string` | | 城市 | | -| `keyword` | `string` | | 关键词 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/restaurant/{restaurantId} - -**餐厅详情** - -获取餐厅完整信息（含菜品、图文详情等），自动注入静态地图图片URL用于详情页地图展示。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `restaurantId` | `integer` | | 餐厅ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 首页接口 - -### `GET` /mp/home - -**首页数据** - -聚合流程：并行获取推荐产品列表+产品线列表+轮播图 → Redis缓存5分钟 → 返回聚合数据 - -**关联字典（BFF透传）**： -- product_type：产品类型（产品卡片显示） -- product_status：产品状态（透传自product-service） - -**响应** `统一响应结果«首页聚合数据»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `首页聚合数据` | | 响应数据 | -|   `banners` | `Map«string,object»[]` | | 轮播图Banner列表 | -|   `contactInfo` | `Map«string,object»[]` | | 联系我们列表 | -|   `exploreTopics` | `Map«string,object»[]` | | 探索专题列表 | -|   `featuredDesigner` | `object` | | 推荐定制师 | -|   `featuredReviews` | `Map«string,object»[]` | | 首页精选评价列表 | -|   `productLines` | `Map«string,object»[]` | | 产品线分类列表 | -|   `recommendProducts` | `Map«string,object»[]` | | 推荐产品列表 | -| `message` | `string` | | 响应消息 | - ---- diff --git a/2026-03/17_0951/hl-order-service.md b/2026-03/17_0951/hl-order-service.md deleted file mode 100644 index ed3738c..0000000 --- a/2026-03/17_0951/hl-order-service.md +++ /dev/null @@ -1,3594 +0,0 @@ -# 订单服务 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-payment-service.md b/2026-03/17_0951/hl-payment-service.md deleted file mode 100644 index 9982afc..0000000 --- a/2026-03/17_0951/hl-payment-service.md +++ /dev/null @@ -1,282 +0,0 @@ -# 支付服务 API 文档 - -**服务**: `hl-payment-service` -**接口总数**: 7 - -## 目录 - -- **支付管理** (7 个接口) - ---- - -## 支付管理 - -### `GET` /admin/payment/list - -**支付交易列表** - -分页查询支付交易记录，支持按订单号、交易状态、交易类型筛选 - -**关联字典**： -- payment_mode：支付模式（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `endDate` | `string` | | 结束日期 | 2026-12-31 | -| `mchId` | `string` | | 商户号 | 1246532201 | -| `orderNo` | `string` | | 订单编号 | HL20260301120000001234 | -| `page` | `integer(int32)` | | 页码 | 1 | -| `pageSize` | `integer(int32)` | | 每页条数 | 20 | -| `startDate` | `string` | | 开始日期 | 2026-01-01 | -| `status` | `string` | | 支付状态 | SUCCESS | -| `tradeType` | `string` | | 交易类型: JSAPI/H5 | JSAPI | - -**响应** `统一响应结果«分页结果«支付交易信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«支付交易信息»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `支付交易信息[]` | | 数据列表 | -|     `createTime` | `string` | | 创建时间 | -|     `mchId` | `string` | | 商户号 | -|     `orderId` | `long` | | 订单ID | -|     `orderNo` | `string` | | 订单编号 | -|     `outTradeNo` | `string` | | 商户订单号 | -|     `payTime` | `string` | | 支付时间 | -|     `payType` | `string` | | 支付类型: FULL/DEPOSIT/BALANCE | -|     `status` | `string` | | 交易状态 | -|     `totalAmount` | `number` | | 交易金额 | -|     `tradeType` | `string` | | 交易类型: JSAPI/H5 | -|     `transactionId` | `long` | | 交易ID | -|     `transactionIdWx` | `string` | | 微信支付交易号 | -|     `userId` | `long` | | 用户ID | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/payment/order/{orderId} - -**按订单查询交易** - -查询指定订单的所有支付交易记录 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«List«支付交易信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `支付交易信息[]` | | 响应数据 | -|   `createTime` | `string` | | 创建时间 | -|   `mchId` | `string` | | 商户号 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `outTradeNo` | `string` | | 商户订单号 | -|   `payTime` | `string` | | 支付时间 | -|   `payType` | `string` | | 支付类型: FULL/DEPOSIT/BALANCE | -|   `status` | `string` | | 交易状态 | -|   `totalAmount` | `number` | | 交易金额 | -|   `tradeType` | `string` | | 交易类型: JSAPI/H5 | -|   `transactionId` | `long` | | 交易ID | -|   `transactionIdWx` | `string` | | 微信支付交易号 | -|   `userId` | `long` | | 用户ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/payment/refund/order/{orderId} - -**按订单查询退款** - -查询指定订单的所有退款记录 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«List«退款记录信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款记录信息[]` | | 响应数据 | -|   `createTime` | `string` | | 创建时间 | -|   `mchId` | `string` | | 商户号 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `outRefundNo` | `string` | | 商户退款单号 | -|   `reason` | `string` | | 退款原因 | -|   `refundAmount` | `number` | | 退款金额 | -|   `refundId` | `long` | | 退款ID | -|   `refundIdWx` | `string` | | 微信退款单号 | -|   `status` | `string` | | 退款状态 | -|   `successTime` | `string` | | 退款成功时间 | -|   `totalAmount` | `number` | | 订单总金额 | -|   `transactionId` | `long` | | 交易ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/payment/refund/{refundId} - -**退款详情** - -获取单笔退款记录的完整信息，包含微信退款单号和退款状态 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `refundId` | `integer` | | 退款ID | - -**响应** `统一响应结果«退款记录信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款记录信息` | | 响应数据 | -|   `createTime` | `string` | | 创建时间 | -|   `mchId` | `string` | | 商户号 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `outRefundNo` | `string` | | 商户退款单号 | -|   `reason` | `string` | | 退款原因 | -|   `refundAmount` | `number` | | 退款金额 | -|   `refundId` | `long` | | 退款ID | -|   `refundIdWx` | `string` | | 微信退款单号 | -|   `status` | `string` | | 退款状态 | -|   `successTime` | `string` | | 退款成功时间 | -|   `totalAmount` | `number` | | 订单总金额 | -|   `transactionId` | `long` | | 交易ID | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/payment/{orderId}/refund - -**发起退款** - -退款流程：验证订单 → 查找原支付交易 → 调用微信退款API → 记录退款单 → 等待微信回调更新状态 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**请求体** `退款请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `amount` | `number` | 是 | 退款金额 | -| `orderId` | `long` | 是 | 订单ID | -| `reason` | `string` | | 退款原因 | - -**响应** `统一响应结果«退款记录信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款记录信息` | | 响应数据 | -|   `createTime` | `string` | | 创建时间 | -|   `mchId` | `string` | | 商户号 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `outRefundNo` | `string` | | 商户退款单号 | -|   `reason` | `string` | | 退款原因 | -|   `refundAmount` | `number` | | 退款金额 | -|   `refundId` | `long` | | 退款ID | -|   `refundIdWx` | `string` | | 微信退款单号 | -|   `status` | `string` | | 退款状态 | -|   `successTime` | `string` | | 退款成功时间 | -|   `totalAmount` | `number` | | 订单总金额 | -|   `transactionId` | `long` | | 交易ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/payment/{transactionId} - -**交易详情** - -获取单笔交易的完整信息，包含微信支付流水号 - -**关联字典**： -- payment_mode：支付模式（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `transactionId` | `integer` | | 交易ID | - -**响应** `统一响应结果«支付交易信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `支付交易信息` | | 响应数据 | -|   `createTime` | `string` | | 创建时间 | -|   `mchId` | `string` | | 商户号 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `outTradeNo` | `string` | | 商户订单号 | -|   `payTime` | `string` | | 支付时间 | -|   `payType` | `string` | | 支付类型: FULL/DEPOSIT/BALANCE | -|   `status` | `string` | | 交易状态 | -|   `totalAmount` | `number` | | 交易金额 | -|   `tradeType` | `string` | | 交易类型: JSAPI/H5 | -|   `transactionId` | `long` | | 交易ID | -|   `transactionIdWx` | `string` | | 微信支付交易号 | -|   `userId` | `long` | | 用户ID | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/payment/{transactionId}/sync - -**同步支付状态** - -主动查询微信支付状态并同步本地数据，适用于回调未到达的场景 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `transactionId` | `integer` | | 交易ID | - -**响应** `统一响应结果«支付交易信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `支付交易信息` | | 响应数据 | -|   `createTime` | `string` | | 创建时间 | -|   `mchId` | `string` | | 商户号 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `outTradeNo` | `string` | | 商户订单号 | -|   `payTime` | `string` | | 支付时间 | -|   `payType` | `string` | | 支付类型: FULL/DEPOSIT/BALANCE | -|   `status` | `string` | | 交易状态 | -|   `totalAmount` | `number` | | 交易金额 | -|   `tradeType` | `string` | | 交易类型: JSAPI/H5 | -|   `transactionId` | `long` | | 交易ID | -|   `transactionIdWx` | `string` | | 微信支付交易号 | -|   `userId` | `long` | | 用户ID | -| `message` | `string` | | 响应消息 | - ---- diff --git a/2026-03/17_0951/hl-product-service.md b/2026-03/17_0951/hl-product-service.md deleted file mode 100644 index 06de89c..0000000 --- a/2026-03/17_0951/hl-product-service.md +++ /dev/null @@ -1,5188 +0,0 @@ -# 产品服务 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 deleted file mode 100644 index 4bea593..0000000 --- a/2026-03/17_0951/hl-resource-service.md +++ /dev/null @@ -1,6998 +0,0 @@ -# 资源服务 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-review-service.md b/2026-03/17_0951/hl-review-service.md deleted file mode 100644 index dbb2fda..0000000 --- a/2026-03/17_0951/hl-review-service.md +++ /dev/null @@ -1,236 +0,0 @@ -# 评价服务 API 文档 - -**服务**: `hl-review-service` -**接口总数**: 6 - -## 目录 - -- **管理端-评价审核** (6 个接口) - ---- - -## 管理端-评价审核 - -### `GET` /admin/review/list - -**评价列表(支持好中差评/有图/有视频筛选)** - -分页查询全部评价（含待审核/已通过/已拒绝），支持按评价等级、是否有图/视频、目标类型筛选 - -**关联字典**： -- review_status：评价审核状态（列表筛选+显示） -- rating_level：评价等级（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `hasImage` | `boolean` | | 是否有图片: true/false | | -| `hasVideo` | `boolean` | | 是否有视频: true/false | | -| `keyword` | `string` | | 搜索关键词 | 风景 | -| `maxRating` | `integer(int32)` | | 最高评分(整体满意度) | 5 | -| `minRating` | `integer(int32)` | | 最低评分(整体满意度) | 3 | -| `page` | `integer(int32)` | | 页码 | 1 | -| `pageSize` | `integer(int32)` | | 每页条数 | 20 | -| `productType` | `string` | | 产品类型（字典 review_product_type） | CORE | -| `ratingLevel` | `string` | | 评价等级: GOOD/MEDIUM/BAD | GOOD | -| `reviewType` | `string` | | 评论类型（字典 review_type） | PRODUCT | -| `status` | `string` | | 评价状态 | APPROVED | -| `targetId` | `integer(int64)` | | 评价目标ID | 2001 | -| `targetType` | `string` | | 评价目标类型 | PRODUCT | - -**响应** `统一响应结果«分页结果«评价列表项(管理端)»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«评价列表项(管理端)»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `评价列表项(管理端)[]` | | 数据列表 | -|     `auditedAt` | `string` | | 审核时间 | -|     `auditorName` | `string` | | 审核人姓名 | -|     `content` | `string` | | 评价内容 | -|     `createdAt` | `string` | | 创建时间 | -|     `hasReply` | `boolean` | | 是否已回复 | -|     `imageCount` | `int` | | 图片数量 | -|     `orderId` | `string` | | 订单ID | -|     `orderNo` | `string` | | 订单编号 | -|     `productType` | `string` | | 产品类型 | -|     `productTypeLabel` | `string` | | 产品类型标签 | -|     `ratingAccommodation` | `int` | | 住宿安排评分(1-5) | -|     `ratingDining` | `int` | | 餐饮质量评分(1-5) | -|     `ratingDriver` | `int` | | 司机服务评分(1-5) | -|     `ratingItinerary` | `int` | | 行程安排评分(1-5) | -|     `ratingLevel` | `string` | | 评价等级: GOOD/MEDIUM/BAD | -|     `ratingLevelLabel` | `string` | | 评价等级标签 | -|     `ratingOverall` | `int` | | 整体满意度评分(1-5) | -|     `rejectReason` | `string` | | 拒绝原因 | -|     `reviewId` | `string` | | 评价ID | -|     `reviewType` | `string` | | 评论类型 | -|     `reviewTypeLabel` | `string` | | 评论类型标签 | -|     `status` | `string` | | 评价状态 | -|     `statusLabel` | `string` | | 评价状态标签 | -|     `targetId` | `string` | | 评价目标ID | -|     `targetName` | `string` | | 评价目标名称 | -|     `targetType` | `string` | | 评价目标类型 | -|     `targetTypeLabel` | `string` | | 评价目标类型标签 | -|     `userAvatar` | `string` | | 用户头像 | -|     `userNickname` | `string` | | 用户昵称 | -|     `videoCount` | `int` | | 视频数量 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/review/{reviewId} - -**评价详情** - -**关联字典**： -- review_status：评价审核状态（显示） -- rating_level：评价等级（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reviewId` | `integer` | | 评价ID | - -**响应** `统一响应结果«评价详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `评价详情` | | 响应数据 | -|   `adminReply` | `string` | | 管理员回复内容 | -|   `adminReplyAt` | `string` | | 回复时间 | -|   `adminReplyName` | `string` | | 回复管理员姓名 | -|   `auditedAt` | `string` | | 审核时间 | -|   `auditorAdminId` | `string` | | 审核人ID | -|   `auditorName` | `string` | | 审核人姓名 | -|   `content` | `string` | | 评价内容 | -|   `createdAt` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期(冗余自订单) | -|   `hasImage` | `boolean` | | 是否有图片 | -|   `hasVideo` | `boolean` | | 是否有视频 | -|   `imageCount` | `int` | | 图片数量 | -|   `images` | `评价图片信息[]` | | 评价图片列表 | -|     `fileId` | `string` | | 文件ID | -|     `imageId` | `string` | | 图片ID | -|     `imageUrl` | `string` | | 图片URL | -|     `sortOrder` | `int` | | 排序序号 | -|   `machineResult` | `string` | | 机审结果 | -|   `orderId` | `string` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `productType` | `string` | | 产品类型 | -|   `productTypeLabel` | `string` | | 产品类型标签 | -|   `ratingAccommodation` | `int` | | 住宿安排评分(1-5) | -|   `ratingDining` | `int` | | 餐饮质量评分(1-5) | -|   `ratingDriver` | `int` | | 司机服务评分(1-5) | -|   `ratingItinerary` | `int` | | 行程安排评分(1-5) | -|   `ratingLevel` | `string` | | 评价等级: GOOD/MEDIUM/BAD | -|   `ratingLevelLabel` | `string` | | 评价等级标签: 好评/中评/差评 | -|   `ratingOverall` | `int` | | 整体满意度评分(1-5) | -|   `rejectReason` | `string` | | 拒绝原因 | -|   `reviewId` | `string` | | 评价ID | -|   `reviewType` | `string` | | 评论类型 | -|   `reviewTypeLabel` | `string` | | 评论类型标签 | -|   `status` | `string` | | 评价状态 | -|   `statusLabel` | `string` | | 评价状态标签 | -|   `targetId` | `string` | | 评价目标ID | -|   `targetName` | `string` | | 评价目标名称 | -|   `targetType` | `string` | | 评价目标类型 | -|   `targetTypeLabel` | `string` | | 评价目标类型标签 | -|   `userAvatar` | `string` | | 用户头像 | -|   `userId` | `string` | | 用户ID | -|   `userNickname` | `string` | | 用户昵称 | -|   `videoCount` | `int` | | 视频数量 | -|   `videos` | `评价视频信息[]` | | 评价视频列表 | -|     `coverUrl` | `string` | | 视频封面URL | -|     `duration` | `int` | | 视频时长(秒) | -|     `fileId` | `string` | | 文件ID | -|     `sortOrder` | `int` | | 排序序号 | -|     `videoId` | `string` | | 视频ID | -|     `videoUrl` | `string` | | 视频URL | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/review/{reviewId}/approve - -**通过评价** - -审核通过评价，通过后评价在小程序端公开展示。状态流转：PENDING_REVIEW → APPROVED - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reviewId` | `integer` | | 评价ID | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /admin/review/{reviewId}/override-approve - -**覆盖通过(机器拒绝的)** - -对阿里云内容审核自动拒绝的评价进行人工覆盖通过。状态流转：AUTO_REJECTED → APPROVED - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reviewId` | `integer` | | 评价ID | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /admin/review/{reviewId}/reject - -**拒绝评价** - -审核拒绝评价，需填写拒绝原因。拒绝后评价不公开展示。状态流转：PENDING_REVIEW → REJECTED - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reviewId` | `integer` | | 评价ID | - -**请求体** `拒绝评价请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `rejectReason` | `string` | 是 | 拒绝原因 | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /admin/review/{reviewId}/reply - -**回复评价(每条评价仅可回复一次)** - -管理员回复用户评价，回复内容在小程序端公开展示。每条评价仅允许回复一次，不可修改。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reviewId` | `integer` | | 评价ID | - -**请求体** `管理员回复请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `replyContent` | `string` | 是 | 回复内容 | - -**响应** `统一响应结果«Void»` - ---- diff --git a/2026-03/17_0951/hl-task-service.md b/2026-03/17_0951/hl-task-service.md deleted file mode 100644 index 0631450..0000000 --- a/2026-03/17_0951/hl-task-service.md +++ /dev/null @@ -1,924 +0,0 @@ -# 任务服务 API 文档 - -**服务**: `hl-task-service` -**接口总数**: 27 - -## 目录 - -- **WebSocket 实时推送** (1 个接口) -- **任务看板管理** (13 个接口) -- **任务管理** (13 个接口) - ---- - -## WebSocket 实时推送 - -### `GET` /admin/task/board/ws-doc/info - -**WebSocket 连接说明** - -## 连接信息 - -| 项目 | 值 | -|------|-------| -| **连接地址** | `ws://{host}:8092/ws/task` | -| **协议** | STOMP over WebSocket（SockJS 降级方案） | -| **跨域** | 允许所有源 (`*`) | - -## 订阅频道 - -| 订阅地址 | 说明 | -|------------|-------------| -| `/topic/board/{boardId}` | 订阅指定看板，接收该看板下的实时任务事件 | - -## 推送消息格式 - -```json -{ - "event": "TASK_CREATED", - "data": { ... }, - "timestamp": 1709539200000 -} -``` - -## 事件类型 - -| 事件 | 说明 | data 内容 | -|-------|------------|------| -| TASK_CREATED | 任务创建 | 任务对象 | -| TASK_UPDATED | 任务更新 | 任务对象 | -| TASK_DELETED | 任务删除 | 任务ID | -| TASK_MOVED | 任务移动（状态变更） | 任务对象 | -| COMMENT_ADDED | 新增评论 | 评论对象 | - -## 前端接入示例 (SockJS + STOMP) - -```javascript -import SockJS from 'sockjs-client' -import { Stomp } from '@stomp/stompjs' - -const socket = new SockJS('http://localhost:8092/ws/task') -const stompClient = Stomp.over(socket) - -stompClient.connect({}, () => { - stompClient.subscribe('/topic/board/123', (msg) => { - const { event, data, timestamp } = JSON.parse(msg.body) - console.log('Event:', event, 'Data:', data) - }) -}) -``` - -**响应** `object` - ---- - -## 任务看板管理 - -### `POST` /admin/task/board - -**创建自定义看板** - -创建自定义看板，自动添加创建者为看板成员，并创建默认状态列（待办、进行中、已完成）。 - -**权限**：需管理员登录。 - -**请求体** `创建看板请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardName` | `string` | 是 | 看板名称 | -| `deptId` | `long` | | 部门ID | -| `description` | `string` | | 看板描述 | -| `memberIds` | `long[]` | | 成员ID列表 | - -**响应** `统一响应结果«看板信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板信息` | | 响应数据 | -|   `boardId` | `long` | | 看板ID | -|   `boardName` | `string` | | 看板名称 | -|   `boardType` | `string` | | 看板类型 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `deptId` | `long` | | 部门ID | -|   `deptName` | `string` | | 部门名称 | -|   `description` | `string` | | 看板描述 | -|   `statuses` | `看板状态信息[]` | | 状态列表 | -|     `isPreset` | `boolean` | | 是否预设状态 | -|     `sortOrder` | `int` | | 排序序号 | -|     `statusColor` | `string` | | 状态颜色 | -|     `statusId` | `long` | | 状态ID | -|     `statusName` | `string` | | 状态名称 | -|     `taskCount` | `int` | | 该状态下的任务数量 | -|   `taskCount` | `int` | | 任务总数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/task/board/{boardId} - -**看板详情** - -返回看板基本信息（名称、描述、创建者），不含任务数据。查看任务请使用「获取看板任务」接口 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**响应** `统一响应结果«看板信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板信息` | | 响应数据 | -|   `boardId` | `long` | | 看板ID | -|   `boardName` | `string` | | 看板名称 | -|   `boardType` | `string` | | 看板类型 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `deptId` | `long` | | 部门ID | -|   `deptName` | `string` | | 部门名称 | -|   `description` | `string` | | 看板描述 | -|   `statuses` | `看板状态信息[]` | | 状态列表 | -|     `isPreset` | `boolean` | | 是否预设状态 | -|     `sortOrder` | `int` | | 排序序号 | -|     `statusColor` | `string` | | 状态颜色 | -|     `statusId` | `long` | | 状态ID | -|     `statusName` | `string` | | 状态名称 | -|     `taskCount` | `int` | | 该状态下的任务数量 | -|   `taskCount` | `int` | | 任务总数 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/task/board/{boardId} - -**更新看板** - -更新看板的名称和描述。仅看板创建者或超级管理员可操作。 - -**权限**：需管理员登录，且为看板创建者或超级管理员。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**请求体** `更新看板请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardName` | `string` | | 看板名称 | -| `description` | `string` | | 看板描述 | - -**响应** `统一响应结果«看板信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板信息` | | 响应数据 | -|   `boardId` | `long` | | 看板ID | -|   `boardName` | `string` | | 看板名称 | -|   `boardType` | `string` | | 看板类型 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `deptId` | `long` | | 部门ID | -|   `deptName` | `string` | | 部门名称 | -|   `description` | `string` | | 看板描述 | -|   `statuses` | `看板状态信息[]` | | 状态列表 | -|     `isPreset` | `boolean` | | 是否预设状态 | -|     `sortOrder` | `int` | | 排序序号 | -|     `statusColor` | `string` | | 状态颜色 | -|     `statusId` | `long` | | 状态ID | -|     `statusName` | `string` | | 状态名称 | -|     `taskCount` | `int` | | 该状态下的任务数量 | -|   `taskCount` | `int` | | 任务总数 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/task/board/{boardId} - -**删除看板** - -删除看板及其下所有状态列和任务（级联删除）。仅看板创建者或超级管理员可操作 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**响应** `统一响应结果«Void»` - ---- - -### `DELETE` /admin/task/board/{boardId}/member/{targetAdminId} - -**移除成员** - -从看板中移除指定成员。仅看板创建者或超级管理员可操作，不能移除创建者自己 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | -| `targetAdminId` | `integer` | | 目标管理员ID | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/task/board/{boardId}/members - -**获取看板成员** - -返回看板的所有成员列表，包含成员的管理员ID和姓名 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**响应** `统一响应结果«List«看板成员信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板成员信息[]` | | 响应数据 | -|   `adminId` | `long` | | 管理员ID | -|   `avatarUrl` | `string` | | 头像地址 | -|   `joinedAt` | `string` | | 加入时间 | -|   `role` | `string` | | 角色: OWNER/MEMBER | -|   `username` | `string` | | 用户名 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/task/board/{boardId}/members - -**添加成员** - -批量添加管理员为看板成员，成为成员后可以查看看板、创建和操作任务。 - -**权限**：需管理员登录，且为看板创建者或超级管理员。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**请求体** `添加成员请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `adminIds` | `long[]` | 是 | 管理员ID列表 | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /admin/task/board/{boardId}/status - -**创建状态列** - -在看板中创建新的状态列（如测试中、待发布等），自动排到末尾。任务通过拖拽在不同状态列间流转。 - -**权限**：需管理员登录且为看板成员。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**请求体** `创建状态请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `statusColor` | `string` | | 状态颜色 | -| `statusName` | `string` | 是 | 状态名称 | - -**响应** `统一响应结果«看板状态信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板状态信息` | | 响应数据 | -|   `isPreset` | `boolean` | | 是否预设状态 | -|   `sortOrder` | `int` | | 排序序号 | -|   `statusColor` | `string` | | 状态颜色 | -|   `statusId` | `long` | | 状态ID | -|   `statusName` | `string` | | 状态名称 | -|   `taskCount` | `int` | | 该状态下的任务数量 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/task/board/{boardId}/status/sort - -**状态列排序** - -批量更新状态列的排序顺序。传入状态列ID数组，数组下标即为新的排序值。操作完成后通过WebSocket推送STATUS_REORDERED事件 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**请求体** `状态排序请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `statusIds` | `long[]` | 是 | 状态ID列表(按排序顺序) | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/task/board/{boardId}/statuses - -**获取看板状态列** - -返回看板的所有状态列（如待办、进行中、已完成），按排序字段升序排列。拖拽任务到不同状态列实现状态流转 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**响应** `统一响应结果«List«看板状态信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板状态信息[]` | | 响应数据 | -|   `isPreset` | `boolean` | | 是否预设状态 | -|   `sortOrder` | `int` | | 排序序号 | -|   `statusColor` | `string` | | 状态颜色 | -|   `statusId` | `long` | | 状态ID | -|   `statusName` | `string` | | 状态名称 | -|   `taskCount` | `int` | | 该状态下的任务数量 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/task/boards - -**获取可见看板列表** - -返回当前管理员可见的看板列表：超级管理员可见所有看板，普通管理员仅可见自己创建的或作为成员的看板 - -**响应** `统一响应结果«List«看板信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板信息[]` | | 响应数据 | -|   `boardId` | `long` | | 看板ID | -|   `boardName` | `string` | | 看板名称 | -|   `boardType` | `string` | | 看板类型 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `deptId` | `long` | | 部门ID | -|   `deptName` | `string` | | 部门名称 | -|   `description` | `string` | | 看板描述 | -|   `statuses` | `看板状态信息[]` | | 状态列表 | -|     `isPreset` | `boolean` | | 是否预设状态 | -|     `sortOrder` | `int` | | 排序序号 | -|     `statusColor` | `string` | | 状态颜色 | -|     `statusId` | `long` | | 状态ID | -|     `statusName` | `string` | | 状态名称 | -|     `taskCount` | `int` | | 该状态下的任务数量 | -|   `taskCount` | `int` | | 任务总数 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/task/status/{statusId} - -**更新状态列** - -更新状态列的名称和颜色。 - -**权限**：需管理员登录且为看板成员。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `statusId` | `integer` | | 状态列ID | - -**请求体** `更新状态请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `statusColor` | `string` | | 状态颜色 | -| `statusName` | `string` | | 状态名称 | - -**响应** `统一响应结果«看板状态信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板状态信息` | | 响应数据 | -|   `isPreset` | `boolean` | | 是否预设状态 | -|   `sortOrder` | `int` | | 排序序号 | -|   `statusColor` | `string` | | 状态颜色 | -|   `statusId` | `long` | | 状态ID | -|   `statusName` | `string` | | 状态名称 | -|   `taskCount` | `int` | | 该状态下的任务数量 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/task/status/{statusId} - -**删除状态列** - -删除看板的状态列。如果状态列下有任务则不允许删除，需先移动或删除任务 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `statusId` | `integer` | | 状态列ID | - -**响应** `统一响应结果«Void»` - ---- - -## 任务管理 - -### `POST` /admin/task - -**创建任务** - -在指定看板和状态列下创建任务。创建成功后通过WebSocket推送TASK_CREATED事件，并通知被分配的负责人 - -**关联字典**： -- task_priority：任务优先级（创建时选择） - -**请求体** `创建任务请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `assigneeIds` | `long[]` | | 负责人ID列表 | -| `boardId` | `long` | 是 | 看板ID | -| `description` | `string` | | 任务描述 | -| `dueDate` | `string` | | 截止日期 | -| `priority` | `string` | | 优先级: LOW/MEDIUM/HIGH/URGENT | -| `statusId` | `long` | | 状态ID | -| `title` | `string` | 是 | 任务标题 | - -**响应** `统一响应结果«任务信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `任务信息` | | 响应数据 | -|   `assignees` | `负责人信息[]` | | 负责人列表 | -|     `adminId` | `long` | | 管理员ID | -|     `avatarUrl` | `string` | | 头像地址 | -|     `username` | `string` | | 用户名 | -|     `wechatName` | `string` | | 企微昵称 | -|   `boardId` | `long` | | 看板ID | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 任务描述 | -|   `dueDate` | `string` | | 截止日期 | -|   `overdue` | `boolean` | | 是否逾期 | -|   `parentId` | `long` | | 父任务ID | -|   `priority` | `string` | | 优先级: LOW/MEDIUM/HIGH/URGENT | -|   `sortOrder` | `int` | | 排序序号 | -|   `statusColor` | `string` | | 状态颜色 | -|   `statusId` | `long` | | 状态ID | -|   `statusName` | `string` | | 状态名称 | -|   `subtaskCompleted` | `int` | | 已完成子任务数 | -|   `subtaskTotal` | `int` | | 子任务总数 | -|   `subtasks` | `子任务信息[]` | | 子任务列表 | -|     `completed` | `boolean` | | 是否已完成 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdBy` | `long` | | 创建人ID | -|     `creatorName` | `string` | | 创建人姓名 | -|     `taskId` | `long` | | 子任务ID | -|     `title` | `string` | | 子任务标题 | -|   `taskId` | `long` | | 任务ID | -|   `title` | `string` | | 任务标题 | -|   `updatedAt` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/task/board/{boardId}/tasks - -**获取看板任务(按状态分组)** - -返回看板下所有任务，按状态列分组。支持按优先级(HIGH/MEDIUM/LOW)和负责人筛选，每组内按排序值升序排列 - -**关联字典**： -- task_priority：任务优先级（列表筛选+显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `assigneeId` | `integer(int64)` | | 负责人ID | | -| `priority` | `string` | | 优先级 | | - -**响应** `统一响应结果«List«看板任务分组信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板任务分组信息[]` | | 响应数据 | -|   `sortOrder` | `int` | | 排序序号 | -|   `statusColor` | `string` | | 状态颜色 | -|   `statusId` | `long` | | 状态ID | -|   `statusName` | `string` | | 状态名称 | -|   `tasks` | `任务信息[]` | | 该状态下的任务列表 | -|     `assignees` | `负责人信息[]` | | 负责人列表 | -|     `boardId` | `long` | | 看板ID | -|     `createdAt` | `string` | | 创建时间 | -|     `createdBy` | `long` | | 创建人ID | -|     `creatorName` | `string` | | 创建人姓名 | -|     `description` | `string` | | 任务描述 | -|     `dueDate` | `string` | | 截止日期 | -|     `overdue` | `boolean` | | 是否逾期 | -|     `parentId` | `long` | | 父任务ID | -|     `priority` | `string` | | 优先级: LOW/MEDIUM/HIGH/URGENT | -|     `sortOrder` | `int` | | 排序序号 | -|     `statusColor` | `string` | | 状态颜色 | -|     `statusId` | `long` | | 状态ID | -|     `statusName` | `string` | | 状态名称 | -|     `subtaskCompleted` | `int` | | 已完成子任务数 | -|     `subtaskTotal` | `int` | | 子任务总数 | -|     `subtasks` | `子任务信息[]` | | 子任务列表 | -|     `taskId` | `long` | | 任务ID | -|     `title` | `string` | | 任务标题 | -|     `updatedAt` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/task/comment/{commentId} - -**删除评论** - -仅评论作者本人可删除自己的评论，系统自动生成的活动记录不可删除 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `commentId` | `integer` | | 评论ID | - -**响应** `统一响应结果«Void»` - ---- - -### `DELETE` /admin/task/subtask/{subtaskId} - -**删除子任务** - -删除指定子任务。 - -**权限**：需管理员登录且为看板成员。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `subtaskId` | `integer` | | 子任务ID | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/task/subtask/{subtaskId}/toggle - -**切换子任务完成状态** - -切换子任务的完成/未完成状态（toggle），完成状态切换会自动记录到任务时间线 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `subtaskId` | `integer` | | 子任务ID | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/task/{taskId} - -**任务详情** - -返回任务完整信息，包含子任务列表、负责人信息、附件列表等 - -**关联字典**： -- task_priority：任务优先级（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**响应** `统一响应结果«任务信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `任务信息` | | 响应数据 | -|   `assignees` | `负责人信息[]` | | 负责人列表 | -|     `adminId` | `long` | | 管理员ID | -|     `avatarUrl` | `string` | | 头像地址 | -|     `username` | `string` | | 用户名 | -|     `wechatName` | `string` | | 企微昵称 | -|   `boardId` | `long` | | 看板ID | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 任务描述 | -|   `dueDate` | `string` | | 截止日期 | -|   `overdue` | `boolean` | | 是否逾期 | -|   `parentId` | `long` | | 父任务ID | -|   `priority` | `string` | | 优先级: LOW/MEDIUM/HIGH/URGENT | -|   `sortOrder` | `int` | | 排序序号 | -|   `statusColor` | `string` | | 状态颜色 | -|   `statusId` | `long` | | 状态ID | -|   `statusName` | `string` | | 状态名称 | -|   `subtaskCompleted` | `int` | | 已完成子任务数 | -|   `subtaskTotal` | `int` | | 子任务总数 | -|   `subtasks` | `子任务信息[]` | | 子任务列表 | -|     `completed` | `boolean` | | 是否已完成 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdBy` | `long` | | 创建人ID | -|     `creatorName` | `string` | | 创建人姓名 | -|     `taskId` | `long` | | 子任务ID | -|     `title` | `string` | | 子任务标题 | -|   `taskId` | `long` | | 任务ID | -|   `title` | `string` | | 任务标题 | -|   `updatedAt` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/task/{taskId} - -**更新任务** - -更新任务的标题、描述、优先级、截止日期、负责人等信息。更新后通过WebSocket推送TASK_UPDATED事件，如果修改了负责人则额外通知新负责人。 - -**权限**：需管理员登录且为看板成员。 - -**关联字典**： -- task_priority：任务优先级（编辑时选择） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**请求体** `更新任务请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `assigneeIds` | `long[]` | | 负责人ID列表 | -| `description` | `string` | | 任务描述 | -| `dueDate` | `string` | | 截止日期 | -| `priority` | `string` | | 优先级: LOW/MEDIUM/HIGH/URGENT | -| `title` | `string` | | 任务标题 | - -**响应** `统一响应结果«任务信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `任务信息` | | 响应数据 | -|   `assignees` | `负责人信息[]` | | 负责人列表 | -|     `adminId` | `long` | | 管理员ID | -|     `avatarUrl` | `string` | | 头像地址 | -|     `username` | `string` | | 用户名 | -|     `wechatName` | `string` | | 企微昵称 | -|   `boardId` | `long` | | 看板ID | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 任务描述 | -|   `dueDate` | `string` | | 截止日期 | -|   `overdue` | `boolean` | | 是否逾期 | -|   `parentId` | `long` | | 父任务ID | -|   `priority` | `string` | | 优先级: LOW/MEDIUM/HIGH/URGENT | -|   `sortOrder` | `int` | | 排序序号 | -|   `statusColor` | `string` | | 状态颜色 | -|   `statusId` | `long` | | 状态ID | -|   `statusName` | `string` | | 状态名称 | -|   `subtaskCompleted` | `int` | | 已完成子任务数 | -|   `subtaskTotal` | `int` | | 子任务总数 | -|   `subtasks` | `子任务信息[]` | | 子任务列表 | -|     `completed` | `boolean` | | 是否已完成 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdBy` | `long` | | 创建人ID | -|     `creatorName` | `string` | | 创建人姓名 | -|     `taskId` | `long` | | 子任务ID | -|     `title` | `string` | | 子任务标题 | -|   `taskId` | `long` | | 任务ID | -|   `title` | `string` | | 任务标题 | -|   `updatedAt` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/task/{taskId} - -**删除任务** - -删除任务及其所有子任务、评论和时间线记录（级联删除）。删除后通过WebSocket推送TASK_DELETED事件。 - -**权限**：需管理员登录且为看板成员。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /admin/task/{taskId}/comment - -**添加评论** - -在任务时间线中添加评论，添加后自动通知任务负责人 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**请求体** `创建评论请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `content` | `string` | 是 | 评论内容 | - -**响应** `统一响应结果«时间线条目»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `时间线条目` | | 响应数据 | -|   `action` | `string` | | 操作类型 | -|   `adminAvatar` | `string` | | 管理员头像 | -|   `adminId` | `long` | | 管理员ID | -|   `adminName` | `string` | | 管理员姓名 | -|   `content` | `string` | | 内容 | -|   `createdAt` | `string` | | 创建时间 | -|   `id` | `long` | | 条目ID | -|   `newValue` | `string` | | 新值 | -|   `oldValue` | `string` | | 旧值 | -|   `type` | `string` | | 类型: COMMENT/ACTIVITY | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/task/{taskId}/sort - -**任务排序** - -更新任务在同一状态列内的排序位置，用于拖拽排序 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**请求体** `任务排序请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `statusId` | `long` | 是 | 状态ID | -| `taskIds` | `long[]` | 是 | 任务ID列表(按排序顺序) | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/task/{taskId}/status - -**变更任务状态** - -将任务移动到指定状态列（拖拽操作），自动记录状态变更到时间线，并通过WebSocket推送TASK_STATUS_CHANGED事件 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**请求体** `变更任务状态请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `statusId` | `long` | 是 | 目标状态ID | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /admin/task/{taskId}/subtask - -**创建子任务** - -在指定任务下创建子任务（待办项），用于拆分任务的执行步骤。子任务默认为未完成状态。 - -**权限**：需管理员登录且为看板成员。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**请求体** `创建子任务请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `title` | `string` | 是 | 子任务标题 | - -**响应** `统一响应结果«子任务信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `子任务信息` | | 响应数据 | -|   `completed` | `boolean` | | 是否已完成 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `taskId` | `long` | | 子任务ID | -|   `title` | `string` | | 子任务标题 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/task/{taskId}/timeline - -**获取任务时间线** - -返回任务的完整操作记录，包含评论和系统自动记录的状态变更、人员分配等活动，按时间正序排列 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**响应** `统一响应结果«List«时间线条目»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `时间线条目[]` | | 响应数据 | -|   `action` | `string` | | 操作类型 | -|   `adminAvatar` | `string` | | 管理员头像 | -|   `adminId` | `long` | | 管理员ID | -|   `adminName` | `string` | | 管理员姓名 | -|   `content` | `string` | | 内容 | -|   `createdAt` | `string` | | 创建时间 | -|   `id` | `long` | | 条目ID | -|   `newValue` | `string` | | 新值 | -|   `oldValue` | `string` | | 旧值 | -|   `type` | `string` | | 类型: COMMENT/ACTIVITY | -| `message` | `string` | | 响应消息 | - ---- diff --git a/2026-03/17_0951/hl-user-service.md b/2026-03/17_0951/hl-user-service.md deleted file mode 100644 index 2978f52..0000000 --- a/2026-03/17_0951/hl-user-service.md +++ /dev/null @@ -1,4501 +0,0 @@ -# 用户服务 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/2026-03/17_0958/CHANGES.md b/2026-03/17_0958/CHANGES.md deleted file mode 100644 index c6f75ff..0000000 --- a/2026-03/17_0958/CHANGES.md +++ /dev/null @@ -1,11 +0,0 @@ -# API 变更通知 - -**更新时间**: 2026-03-17 09:58 - -## ℹ️ 新增 (1) - -### 用户服务 - -**新增参数** - -- `GET /admin/user` 新增参数 `keyword` diff --git a/2026-03/17_0958/hl-contract-service.md b/2026-03/17_0958/hl-contract-service.md deleted file mode 100644 index 7c4fc19..0000000 --- a/2026-03/17_0958/hl-contract-service.md +++ /dev/null @@ -1,793 +0,0 @@ -# 合同服务 API 文档 - -**服务**: `hl-contract-service` -**接口总数**: 18 - -## 目录 - -- **合同管理** (12 个接口) -- **补充约定模板管理** (6 个接口) - ---- - -## 合同管理 - -### `GET` /admin/contract/active-by-order/{orderId} - -**获取订单有效合同** - -返回订单当前有效的合同（非作废状态的最新合同），用于检查订单是否已有签署中或已签署的合同。 - -**权限**：需管理员登录。 - -**关联字典**： -- contract_status：合同状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«合同信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同信息` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/agencies - -**可用旅行社列表** - -返回系统配置的旅行社列表，创建合同时选择签约旅行社 - -**响应** `统一响应结果«List«旅行社信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `旅行社信息[]` | | 响应数据 | -|   `agencyAddress` | `string` | | 旅行社地址 | -|   `agencyName` | `string` | | 旅行社名称 | -|   `businessLicenseNumber` | `string` | | 营业执照号 | -|   `businessScope` | `string` | | 经营范围 | -|   `code` | `string` | | 旅行社编码 | -|   `licenseNumber` | `string` | | 旅行社许可证号 | -|   `regionId` | `string` | | 地区ID | -|   `transactorName` | `string` | | 经办人姓名 | -|   `transactorPhone` | `string` | | 经办人电话 | -|   `zjParentId` | `int` | | 属地管理机构ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/by-order/{orderId} - -**按订单查询合同** - -查询指定订单下的所有合同记录（含已作废），按创建时间倒序排列。用于订单详情页展示合同历史。 - -**权限**：需管理员登录。 - -**关联字典**： -- contract_status：合同状态（列表显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«List«合同信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同信息[]` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/contract/create - -**创建合同(标准模式)** - -标准电子签约流程：创建合同 → 平台生成合同PDF → 发送签署短信给出行人 → 出行人在线签署 → 回调更新状态。状态流转：CREATED → SIGNING → SIGNED - -**请求体** `创建合同请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `adultCost` | `number` | 是 | 成人费用 | -| `agencyCode` | `string` | | 旅行社编号（可选，默认使用配置值） | -| `childCost` | `number` | | 儿童费用 | -| `contactName` | `string` | 是 | 联系人姓名 | -| `contactPhone` | `string` | 是 | 联系人电话 | -| `contractType` | `string` | | 合同类型: TOUR-旅游合同(默认), INSURANCE-保险单 | -| `days` | `int` | | 行程天数 | -| `departureCity` | `string` | | 出发城市 | -| `departureDate` | `string` | 是 | 出发日期 | -| `destination` | `string` | 是 | 目的地 | -| `disputeResolution` | `int` | | 争议解决方式: 1-仲裁 2-诉讼 | -| `groupId` | `string` | | 团号 | -| `leastCustomerNumber` | `int` | | 最低成团人数 | -| `nights` | `int` | | 住宿晚数 | -| `orderId` | `long` | | 订单ID | -| `paymentMethod` | `int` | | 付款方式: 1-现金 2-转账 3-在线 | -| `returnDate` | `string` | 是 | 返回日期 | -| `routeName` | `string` | 是 | 线路名称 | -| `signatoryIdNumber` | `string` | 是 | 签署人证件号码 | -| `signatoryIdType` | `int` | | 签署人证件类型: 1-身份证 | -| `signatoryMode` | `int` | | 签署模式: 1-短信 2-现场 3-线下 | -| `signatoryName` | `string` | 是 | 签署人姓名 | -| `signatoryPhone` | `string` | 是 | 签署人电话 | -| `signingPlace` | `string` | | 签约地点 | -| `supplementaryClause` | `string` | | 补充约定内容 | -| `templateCode` | `string` | 是 | 模板编码 | -| `totalAmount` | `number` | 是 | 合同总金额 | -| `transactorName` | `string` | | 经办人姓名 | -| `transactorPhone` | `string` | | 经办人电话 | -| `travelers` | `合同出行人请求[]` | 是 | 出行人列表 | -|   `age` | `int` | | 年龄 | -|   `gender` | `string` | | 性别: male/female | -|   `health` | `string` | | 健康信息 | -|   `idCardNo` | `string` | 是 | 证件号码 | -|   `idCardType` | `int` | | 证件类型: 1-身份证 2-护照 | -|   `isChild` | `boolean` | | 是否儿童 | -|   `isSigner` | `boolean` | | 是否签署人 | -|   `name` | `string` | 是 | 姓名 | -|   `phone` | `string` | | 手机号 | -| `vehicleModel` | `string` | | 车型名称(产品快照) | - -**响应** `统一响应结果«合同详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同详情` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `statusLogs` | `合同状态变更日志[]` | | 状态变更日志 | -|     `createTime` | `string` | | 创建时间 | -|     `logId` | `long` | | 日志ID | -|     `newStatus` | `string` | | 新状态 | -|     `oldStatus` | `string` | | 旧状态 | -|     `source` | `string` | | 变更来源 | -|   `supplementaryClause` | `string` | | 补充约定内容 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -|   `travelers` | `合同出行人信息[]` | | 出行人列表 | -|     `idCardNo` | `string` | | 证件号码 | -|     `idCardType` | `string` | | 证件类型 | -|     `isSigner` | `boolean` | | 是否签署人 | -|     `name` | `string` | | 姓名 | -|     `phone` | `string` | | 手机号 | -|     `travelerId` | `long` | | 出行人ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/list - -**合同列表** - -分页查询合同记录，支持按订单号、合同状态、旅行社筛选 - -**关联字典**： -- contract_status：合同状态（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `orderId` | `integer(int64)` | | 订单ID | 1001 | -| `page` | `integer(int32)` | | 页码 | 1 | -| `pageSize` | `integer(int32)` | | 每页条数 | 20 | -| `platform` | `string` | | 签约平台 | TOURAGE | -| `status` | `string` | | 合同状态 | SIGNED | - -**响应** `统一响应结果«分页结果«合同信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«合同信息»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `合同信息[]` | | 数据列表 | -|     `agencyCode` | `string` | | 旅行社编号 | -|     `contactName` | `string` | | 联系人姓名 | -|     `contactPhone` | `string` | | 联系人电话 | -|     `contractId` | `long` | | 合同ID | -|     `contractNumber` | `string` | | 合同编号 | -|     `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|     `createTime` | `string` | | 创建时间 | -|     `departureDate` | `string` | | 出发日期 | -|     `destination` | `string` | | 目的地 | -|     `fileUrl` | `string` | | 合同文件URL | -|     `mode` | `string` | | 签约模式: STANDARD/SYNC | -|     `orderId` | `long` | | 订单ID | -|     `platform` | `string` | | 签约平台 | -|     `qrCodeUrl` | `string` | | 二维码URL | -|     `returnDate` | `string` | | 返回日期 | -|     `signUrl` | `string` | | 签署URL | -|     `status` | `string` | | 合同状态 | -|     `statusLabel` | `string` | | 合同状态标签 | -|     `templateCode` | `string` | | 模板编码 | -|     `templateName` | `string` | | 模板名称 | -|     `totalAmount` | `number` | | 合同总金额 | -|     `touristCount` | `int` | | 出行人数 | -|     `travelAgencyName` | `string` | | 旅行社名称 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/contract/report - -**报备合同(同步模式)** - -线下签约模式：创建合同记录 → 管理员上传已签署的PDF → 同步到12301报备平台。状态流转：CREATED → UPLOADED → REPORTED - -**请求体** `报备合同请求（同步模式）` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `adultCost` | `number` | 是 | 成人费用 | -| `agencyCode` | `string` | | 旅行社编号 | -| `childCost` | `number` | | 儿童费用 | -| `contactName` | `string` | 是 | 联系人姓名 | -| `contactPhone` | `string` | 是 | 联系人电话 | -| `contractType` | `string` | | 合同类型: TOUR-旅游合同(默认), INSURANCE-保险单 | -| `days` | `int` | | 行程天数 | -| `departureCity` | `string` | | 出发城市 | -| `departureDate` | `string` | 是 | 出发日期 | -| `destination` | `string` | 是 | 目的地 | -| `disputeResolution` | `int` | | 争议解决方式: 1-仲裁 2-诉讼 | -| `groupId` | `string` | | 团号 | -| `leastCustomerNumber` | `int` | | 最低成团人数 | -| `nights` | `int` | | 住宿晚数 | -| `orderId` | `long` | | 订单ID | -| `paymentMethod` | `int` | | 付款方式: 1-现金 2-转账 3-在线 | -| `returnDate` | `string` | 是 | 返回日期 | -| `routeName` | `string` | 是 | 线路名称 | -| `signatoryIdNumber` | `string` | 是 | 签署人证件号码 | -| `signatoryIdType` | `int` | | 签署人证件类型: 1-身份证 | -| `signatoryMode` | `int` | | 签署模式（同步模式默认2-现场） | -| `signatoryName` | `string` | 是 | 签署人姓名 | -| `signatoryPhone` | `string` | 是 | 签署人电话 | -| `signingPlace` | `string` | | 签约地点 | -| `supplementaryClause` | `string` | | 补充约定内容 | -| `templateCode` | `string` | 是 | 模板编码 | -| `totalAmount` | `number` | 是 | 合同总金额 | -| `transactorName` | `string` | | 经办人姓名 | -| `transactorPhone` | `string` | | 经办人电话 | -| `travelers` | `合同出行人请求[]` | 是 | 出行人列表 | -|   `age` | `int` | | 年龄 | -|   `gender` | `string` | | 性别: male/female | -|   `health` | `string` | | 健康信息 | -|   `idCardNo` | `string` | 是 | 证件号码 | -|   `idCardType` | `int` | | 证件类型: 1-身份证 2-护照 | -|   `isChild` | `boolean` | | 是否儿童 | -|   `isSigner` | `boolean` | | 是否签署人 | -|   `name` | `string` | 是 | 姓名 | -|   `phone` | `string` | | 手机号 | - -**响应** `统一响应结果«合同详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同详情` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `statusLogs` | `合同状态变更日志[]` | | 状态变更日志 | -|     `createTime` | `string` | | 创建时间 | -|     `logId` | `long` | | 日志ID | -|     `newStatus` | `string` | | 新状态 | -|     `oldStatus` | `string` | | 旧状态 | -|     `source` | `string` | | 变更来源 | -|   `supplementaryClause` | `string` | | 补充约定内容 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -|   `travelers` | `合同出行人信息[]` | | 出行人列表 | -|     `idCardNo` | `string` | | 证件号码 | -|     `idCardType` | `string` | | 证件类型 | -|     `isSigner` | `boolean` | | 是否签署人 | -|     `name` | `string` | | 姓名 | -|     `phone` | `string` | | 手机号 | -|     `travelerId` | `long` | | 出行人ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/templates - -**合同模板列表** - -返回合同平台可用的合同模板列表，创建合同时选择模板 - -**响应** `统一响应结果«List«合同模板信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同模板信息[]` | | 响应数据 | -|   `createTime` | `string` | | 创建时间 | -|   `description` | `string` | | 模板描述 | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `platform` | `string` | | 签约平台 | -|   `status` | `string` | | 模板状态 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateId` | `long` | | 模板ID | -|   `templateName` | `string` | | 模板名称 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/{id} - -**合同详情** - -**关联字典**： -- contract_status：合同状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 合同ID | - -**响应** `统一响应结果«合同详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同详情` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `statusLogs` | `合同状态变更日志[]` | | 状态变更日志 | -|     `createTime` | `string` | | 创建时间 | -|     `logId` | `long` | | 日志ID | -|     `newStatus` | `string` | | 新状态 | -|     `oldStatus` | `string` | | 旧状态 | -|     `source` | `string` | | 变更来源 | -|   `supplementaryClause` | `string` | | 补充约定内容 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -|   `travelers` | `合同出行人信息[]` | | 出行人列表 | -|     `idCardNo` | `string` | | 证件号码 | -|     `idCardType` | `string` | | 证件类型 | -|     `isSigner` | `boolean` | | 是否签署人 | -|     `name` | `string` | | 姓名 | -|     `phone` | `string` | | 手机号 | -|     `travelerId` | `long` | | 出行人ID | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/contract/{id}/invalidate - -**作废合同** - -将合同标记为作废状态（不可恢复）。作废后该合同不再有效，可重新为订单创建新合同 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 合同ID | - -**响应** `统一响应结果«合同信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同信息` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/contract/{id}/resend-sms - -**重发签署短信** - -重新发送签署短信给出行人，用于签署短信过期或未收到的场景。仅SIGNING状态的合同可操作 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 合同ID | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/{id}/status - -**刷新合同状态(从平台同步)** - -主动查询合同平台的最新签署状态并同步到本地，适用于回调未到达的场景 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 合同ID | - -**响应** `统一响应结果«合同信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同信息` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/contract/{id}/upload-pdf - -**上传已签署PDF(同步模式)** - -同步模式专用：上传线下签署完成的合同PDF文件，上传后合同状态变为UPLOADED，可进一步报备 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 合同ID | - -**响应** `统一响应结果«合同信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同信息` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -| `message` | `string` | | 响应消息 | - ---- - -## 补充约定模板管理 - -### `POST` /admin/contract/clause-template - -**创建补充约定模板** - -创建合同补充约定的模板，支持变量占位符。创建后默认启用 - -**请求体** `补充约定模板请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `content` | `string` | 是 | 模板内容 | -| `name` | `string` | 是 | 模板名称 | -| `sortOrder` | `int` | | 排序（升序） | - -**响应** `统一响应结果«补充约定模板»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `补充约定模板` | | 响应数据 | -|   `content` | `string` | | 模板内容 | -|   `createTime` | `string` | | 创建时间 | -|   `name` | `string` | | 模板名称 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `string` | | 状态: ACTIVE/INACTIVE | -|   `templateId` | `long` | | 模板ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/clause-template/list - -**获取启用的补充约定模板列表（创建合同用）** - -返回所有启用状态的补充约定模板，创建合同时选择需要附加的补充约定条款。 - -**权限**：需管理员登录。 - -**响应** `统一响应结果«List«补充约定模板»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `补充约定模板[]` | | 响应数据 | -|   `content` | `string` | | 模板内容 | -|   `createTime` | `string` | | 创建时间 | -|   `name` | `string` | | 模板名称 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `string` | | 状态: ACTIVE/INACTIVE | -|   `templateId` | `long` | | 模板ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/clause-template/list-all - -**获取全部补充约定模板（管理页用）** - -**关联字典**： -- common_status：通用状态（列表显示，ACTIVE=启用/INACTIVE=停用） - -**响应** `统一响应结果«List«补充约定模板»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `补充约定模板[]` | | 响应数据 | -|   `content` | `string` | | 模板内容 | -|   `createTime` | `string` | | 创建时间 | -|   `name` | `string` | | 模板名称 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `string` | | 状态: ACTIVE/INACTIVE | -|   `templateId` | `long` | | 模板ID | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/contract/clause-template/{id} - -**更新补充约定模板** - -更新模板的标题和内容。已被合同引用的模板更新不影响已创建的合同（合同记录的是快照内容）。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 模板ID | - -**请求体** `补充约定模板请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `content` | `string` | 是 | 模板内容 | -| `name` | `string` | 是 | 模板名称 | -| `sortOrder` | `int` | | 排序（升序） | - -**响应** `统一响应结果«补充约定模板»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `补充约定模板` | | 响应数据 | -|   `content` | `string` | | 模板内容 | -|   `createTime` | `string` | | 创建时间 | -|   `name` | `string` | | 模板名称 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `string` | | 状态: ACTIVE/INACTIVE | -|   `templateId` | `long` | | 模板ID | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/contract/clause-template/{id} - -**删除补充约定模板** - -软删除模板。已被合同引用的模板仍可删除，不影响已创建的合同 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 模板ID | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/contract/clause-template/{id}/toggle-status - -**切换模板启用/停用状态** - -**关联字典**： -- common_status：通用状态（状态切换，ACTIVE=启用/INACTIVE=停用） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 模板ID | - -**响应** `统一响应结果«补充约定模板»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `补充约定模板` | | 响应数据 | -|   `content` | `string` | | 模板内容 | -|   `createTime` | `string` | | 创建时间 | -|   `name` | `string` | | 模板名称 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `string` | | 状态: ACTIVE/INACTIVE | -|   `templateId` | `long` | | 模板ID | -| `message` | `string` | | 响应消息 | - ---- diff --git a/2026-03/17_0958/hl-file-service.md b/2026-03/17_0958/hl-file-service.md deleted file mode 100644 index 7c17ab6..0000000 --- a/2026-03/17_0958/hl-file-service.md +++ /dev/null @@ -1,331 +0,0 @@ -# 文件服务 API 文档 - -**服务**: `hl-file-service` -**接口总数**: 11 - -## 目录 - -- **C端文件上传** (3 个接口) -- **文件管理** (8 个接口) - ---- - -## C端文件上传 - -### `GET` /mp/file/preview-by-url - -**文件在线预览** - -返回HTML预览页面，小程序通过web-view打开。支持PDF、图片、Office文档 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `url` | `string` | | 文件完整URL | | - ---- - -### `POST` /mp/file/upload - -**上传文件（C端用户）** - -小程序端直接上传文件，支持头像、评价图片等场景。groupKey决定存储路径和文件策略，默认为avatar - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `groupKey` | `string` | | 文件分组标识 | | - -**响应** `统一响应结果«文件信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `文件信息` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `fileHash` | `string` | | 文件MD5哈希 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `groupKey` | `string` | | 业务分组 | -|   `mimeType` | `string` | | MIME类型 | -|   `ossUrl` | `string` | | OSS地址 | -|   `previewUrl` | `string` | | 预览地址 | -|   `refCount` | `int` | | 引用次数 | -|   `status` | `string` | | 文件状态 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/file/{fileId}/preview - -**文件内容流式预览** - -流式输出文件内容，设置正确的Content-Type头。用于小程序端通过web-view直接预览图片和PDF等文件。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `fileId` | `integer` | | 文件ID | - ---- - -## 文件管理 - -### `GET` /admin/file/list - -**文件列表（分页）** - -支持按文件类型、分组、上传者等条件筛选，按上传时间倒序分页返回 - -**关联字典**： -- file_type：文件类型（列表筛选+显示） -- file_status：文件状态（显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `endDate` | `string` | | 结束日期 | 2026-12-31 | -| `fileType` | `string` | | 文件类型 | image | -| `groupKey` | `string` | | 业务分组 | scenic | -| `keyword` | `string` | | 搜索关键词 | 风景 | -| `page` | `integer(int32)` | | 页码 | 1 | -| `pageSize` | `integer(int32)` | | 每页条数 | 20 | -| `startDate` | `string` | | 开始日期 | 2026-01-01 | - -**响应** `统一响应结果«IPage«文件信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `IPage«文件信息»` | | 响应数据 | -|   `current` | `long` | | | -|   `pages` | `long` | | | -|   `records` | `文件信息[]` | | | -|     `createdAt` | `string` | | 创建时间 | -|     `fileHash` | `string` | | 文件MD5哈希 | -|     `fileId` | `string` | | 文件ID | -|     `fileName` | `string` | | 文件名 | -|     `fileSize` | `long` | | 文件大小(字节) | -|     `fileType` | `string` | | 文件类型 | -|     `groupKey` | `string` | | 业务分组 | -|     `mimeType` | `string` | | MIME类型 | -|     `ossUrl` | `string` | | OSS地址 | -|     `previewUrl` | `string` | | 预览地址 | -|     `refCount` | `int` | | 引用次数 | -|     `status` | `string` | | 文件状态 | -|     `thumbnailUrl` | `string` | | 缩略图地址 | -|   `size` | `long` | | | -|   `total` | `long` | | | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/file/stats - -**存储统计** - -返回文件总数、总存储空间、各类型文件占比等统计信息 - -**响应** `统一响应结果«文件统计信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `文件统计信息` | | 响应数据 | -|   `countByGroup` | `object` | | 按分组统计文件数量 | -|   `countByType` | `object` | | 按类型统计文件数量 | -|   `sizeByType` | `object` | | 按类型统计文件大小 | -|   `totalCount` | `long` | | 文件总数 | -|   `totalSize` | `long` | | 文件总大小(字节) | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/file/upload/confirm - -**确认上传完成** - -上传流程第二步：前端直传OSS完成后调用此接口，系统验证文件存在性并创建文件记录。支持MD5去重，相同文件不会重复存储 - -**请求体** `上传确认请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `fileId` | `string` | 是 | 文件ID | - -**响应** `统一响应结果«文件信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `文件信息` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `fileHash` | `string` | | 文件MD5哈希 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `groupKey` | `string` | | 业务分组 | -|   `mimeType` | `string` | | MIME类型 | -|   `ossUrl` | `string` | | OSS地址 | -|   `previewUrl` | `string` | | 预览地址 | -|   `refCount` | `int` | | 引用次数 | -|   `status` | `string` | | 文件状态 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/file/upload/token - -**请求上传凭证** - -上传流程第一步：前端请求上传凭证 → 获取OSS预签名URL和临时凭证 → 前端直传OSS → 调用确认上传接口。凭证有效期有限，过期需重新请求 - -**请求体** `上传令牌请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `fileHash` | `string` | 是 | 文件MD5哈希 | -| `fileName` | `string` | 是 | 文件名 | -| `fileSize` | `long` | 是 | 文件大小(字节) | -| `forcePresigned` | `boolean` | | 强制使用预签名URL（跳过STS分片模式） | -| `groupKey` | `string` | | 业务分组 | - -**响应** `统一响应结果«上传令牌信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `上传令牌信息` | | 响应数据 | -|   `bucket` | `string` | | OSS Bucket名称 | -|   `contentType` | `string` | | 上传时必须使用的Content-Type（与预签名URL签名一致） | -|   `expireAt` | `string` | | 过期时间 | -|   `file` | `文件信息` | | 秒传文件信息 | -|     `createdAt` | `string` | | 创建时间 | -|     `fileHash` | `string` | | 文件MD5哈希 | -|     `fileId` | `string` | | 文件ID | -|     `fileName` | `string` | | 文件名 | -|     `fileSize` | `long` | | 文件大小(字节) | -|     `fileType` | `string` | | 文件类型 | -|     `groupKey` | `string` | | 业务分组 | -|     `mimeType` | `string` | | MIME类型 | -|     `ossUrl` | `string` | | OSS地址 | -|     `previewUrl` | `string` | | 预览地址 | -|     `refCount` | `int` | | 引用次数 | -|     `status` | `string` | | 文件状态 | -|     `thumbnailUrl` | `string` | | 缩略图地址 | -|   `fileId` | `string` | | 文件ID | -|   `ossKey` | `string` | | OSS对象Key | -|   `presignedUrl` | `string` | | 预签名上传URL | -|   `region` | `string` | | OSS Region | -|   `stsToken` | `STS临时凭证信息` | | STS临时凭证 | -|     `accessKeyId` | `string` | | AccessKey ID | -|     `accessKeySecret` | `string` | | AccessKey Secret | -|     `expiration` | `string` | | 过期时间 | -|     `securityToken` | `string` | | 安全令牌 | -|   `uploadMode` | `string` | | 上传模式: PRESIGNED_URL/STS_MULTIPART/INSTANT | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/file/{fileId} - -**文件详情** - -**关联字典**： -- file_type：文件类型（显示） -- file_status：文件状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `fileId` | `integer` | | 文件ID | - -**响应** `统一响应结果«文件信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `文件信息` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `fileHash` | `string` | | 文件MD5哈希 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `groupKey` | `string` | | 业务分组 | -|   `mimeType` | `string` | | MIME类型 | -|   `ossUrl` | `string` | | OSS地址 | -|   `previewUrl` | `string` | | 预览地址 | -|   `refCount` | `int` | | 引用次数 | -|   `status` | `string` | | 文件状态 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/file/{fileId} - -**删除文件** - -软删除文件记录，如果文件存在引用关系则不允许删除。OSS上的物理文件由定时任务清理 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `fileId` | `integer` | | 文件ID | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/file/{fileId}/preview - -**文件内容流式预览** - -流式输出文件内容，设置正确的Content-Type头，支持浏览器直接预览图片和PDF等文件 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `fileId` | `integer` | | 文件ID | - ---- - -### `GET` /admin/file/{fileId}/refs - -**文件引用列表** - -查看文件被哪些业务实体引用（如景区封面、酒店图片等），用于判断文件是否可安全删除 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `fileId` | `integer` | | 文件ID | - -**响应** `统一响应结果«List«文件引用信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `文件引用信息[]` | | 响应数据 | -|   `bizId` | `string` | | 业务ID | -|   `bizType` | `string` | | 业务类型 | -|   `createdAt` | `string` | | 创建时间 | -|   `fileId` | `string` | | 文件ID | -|   `refId` | `string` | | 引用ID | -| `message` | `string` | | 响应消息 | - ---- diff --git a/2026-03/17_0958/hl-guide-service.md b/2026-03/17_0958/hl-guide-service.md deleted file mode 100644 index d01c9cc..0000000 --- a/2026-03/17_0958/hl-guide-service.md +++ /dev/null @@ -1,727 +0,0 @@ -# 攻略服务 API 文档 - -**服务**: `hl-guide-service` -**接口总数**: 21 - -## 目录 - -- **攻略分类管理** (7 个接口) -- **攻略文章管理** (8 个接口) -- **攻略标签管理** (6 个接口) - ---- - -## 攻略分类管理 - -### `POST` /admin/guide/category - -**创建分类** - -创建攻略分类，分类名称不可重复。创建后默认启用，排序值越小越靠前。 - -**权限**：需管理员登录。 - -**请求体** `CategoryCreateRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryName` | `string` | 是 | 分类名称 | -| `coverMaterialId` | `long` | | 封面素材ID | -| `coverUrl` | `string` | | 封面URL | -| `description` | `string` | | 描述 | -| `icon` | `string` | | 图标 | -| `sortOrder` | `int` | | 排序（默认0） | - -**响应** `统一响应结果«攻略分类»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略分类` | | 响应数据 | -|   `articleCount` | `int` | | 文章数量 | -|   `categoryId` | `long` | | 分类ID | -|   `categoryName` | `string` | | 分类名称 | -|   `coverMaterialId` | `long` | | 封面素材ID | -|   `coverUrl` | `string` | | 封面URL | -|   `createdAt` | `string` | | 创建时间 | -|   `description` | `string` | | 描述 | -|   `icon` | `string` | | 图标 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `int` | | 状态：0=禁用，1=启用 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/guide/category/enabled - -**启用的分类列表** - -仅返回状态为启用的分类，创建文章时用于选择分类 - -**响应** `统一响应结果«List«攻略分类»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略分类[]` | | 响应数据 | -|   `articleCount` | `int` | | 文章数量 | -|   `categoryId` | `long` | | 分类ID | -|   `categoryName` | `string` | | 分类名称 | -|   `coverMaterialId` | `long` | | 封面素材ID | -|   `coverUrl` | `string` | | 封面URL | -|   `createdAt` | `string` | | 创建时间 | -|   `description` | `string` | | 描述 | -|   `icon` | `string` | | 图标 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `int` | | 状态：0=禁用，1=启用 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/guide/category/list - -**分类列表** - -返回全部攻略分类（含启用和停用），按排序值升序排列 - -**关联字典**： -- common_status：通用状态（列表显示，ACTIVE=启用/INACTIVE=停用） - -**响应** `统一响应结果«List«攻略分类»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略分类[]` | | 响应数据 | -|   `articleCount` | `int` | | 文章数量 | -|   `categoryId` | `long` | | 分类ID | -|   `categoryName` | `string` | | 分类名称 | -|   `coverMaterialId` | `long` | | 封面素材ID | -|   `coverUrl` | `string` | | 封面URL | -|   `createdAt` | `string` | | 创建时间 | -|   `description` | `string` | | 描述 | -|   `icon` | `string` | | 图标 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `int` | | 状态：0=禁用，1=启用 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/guide/category/{categoryId} - -**更新分类** - -更新攻略分类的名称、图标、描述等信息。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryId` | `integer` | 是 | categoryId | - -**请求体** `CategoryUpdateRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryName` | `string` | | 分类名称 | -| `coverMaterialId` | `long` | | 封面素材ID | -| `coverUrl` | `string` | | 封面URL | -| `description` | `string` | | 描述 | -| `icon` | `string` | | 图标 | -| `sortOrder` | `int` | | 排序 | - -**响应** `统一响应结果«攻略分类»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略分类` | | 响应数据 | -|   `articleCount` | `int` | | 文章数量 | -|   `categoryId` | `long` | | 分类ID | -|   `categoryName` | `string` | | 分类名称 | -|   `coverMaterialId` | `long` | | 封面素材ID | -|   `coverUrl` | `string` | | 封面URL | -|   `createdAt` | `string` | | 创建时间 | -|   `description` | `string` | | 描述 | -|   `icon` | `string` | | 图标 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `int` | | 状态：0=禁用，1=启用 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/guide/category/{categoryId} - -**删除分类** - -删除分类前需确保分类下无文章，否则删除失败 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryId` | `integer` | 是 | categoryId | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/guide/category/{categoryId}/sort - -**更新分类排序** - -更新分类的排序值，排序值越小越靠前。影响小程序端分类导航的展示顺序。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryId` | `integer` | 是 | categoryId | - -**请求体** `CategorySortRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `sortOrder` | `int` | 是 | 排序值 | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/guide/category/{categoryId}/status - -**更新分类状态** - -启用或停用分类。停用后该分类下的文章不会在小程序端展示，但不影响已有文章 - -**关联字典**： -- common_status：通用状态（状态切换，ACTIVE=启用/INACTIVE=停用） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryId` | `integer` | 是 | categoryId | - -**请求体** `StatusRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `status` | `int` | 是 | 状态值 | - -**响应** `统一响应结果«Void»` - ---- - -## 攻略文章管理 - -### `POST` /admin/guide/article - -**创建文章** - -创建攻略文章，需指定分类。创建后默认为草稿状态，需手动发布后小程序端才可见。 - -**权限**：需管理员登录。 - -**关联字典**： -- wiki_status：文章状态（创建后默认DRAFT） - -**请求体** `ArticleCreateRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `authorName` | `string` | | 作者名称 | -| `bannerMaterialIds` | `long[]` | | 轮播图素材ID列表 | -| `categoryId` | `long` | 是 | 分类ID | -| `content` | `string` | | 正文内容 | -| `coverMaterialId` | `long` | | 封面素材ID | -| `coverUrl` | `string` | | 封面URL | -| `resources` | `ArticleResourceItem[]` | | 关联资源列表 | -|   `resourceId` | `long` | 是 | 资源ID | -|   `resourceName` | `string` | 是 | 资源名称 | -|   `resourceType` | `string` | 是 | 资源类型：SCENIC/RESTAURANT/HOTEL/ACTIVITY/PRODUCT | -|   `sortOrder` | `int` | | 排序 | -| `sortOrder` | `int` | | 排序（默认0） | -| `source` | `string` | | 来源 | -| `subtitle` | `string` | | 副标题 | -| `summary` | `string` | | 摘要 | -| `tagIds` | `long[]` | | 标签ID列表 | -| `title` | `string` | 是 | 标题 | - -**响应** `统一响应结果«攻略文章详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略文章详情` | | 响应数据 | -|   `articleId` | `long` | | 文章ID | -|   `authorName` | `string` | | 作者名称 | -|   `bannerMaterialIds` | `long[]` | | 轮播图素材ID列表 | -|   `categoryId` | `long` | | 分类ID | -|   `categoryName` | `string` | | 分类名称 | -|   `content` | `string` | | 正文内容 | -|   `coverMaterialId` | `long` | | 封面素材ID | -|   `coverUrl` | `string` | | 封面URL | -|   `createdAt` | `string` | | 创建时间 | -|   `favoriteCount` | `int` | | 收藏数 | -|   `isRecommend` | `int` | | 是否推荐：0=否，1=是 | -|   `isTop` | `int` | | 是否置顶：0=否，1=是 | -|   `likeCount` | `int` | | 点赞数 | -|   `publishTime` | `string` | | 发布时间 | -|   `resources` | `文章关联资源[]` | | 关联资源列表 | -|     `resourceId` | `long` | | 资源ID | -|     `resourceName` | `string` | | 资源名称 | -|     `resourceType` | `string` | | 资源类型：SCENIC/RESTAURANT/HOTEL/ACTIVITY/PRODUCT | -|     `sortOrder` | `int` | | 排序 | -|   `sortOrder` | `int` | | 排序 | -|   `source` | `string` | | 来源 | -|   `status` | `int` | | 状态：0=草稿，1=已发布，2=已下架 | -|   `subtitle` | `string` | | 副标题 | -|   `summary` | `string` | | 摘要 | -|   `tags` | `攻略标签[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `long` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `tagType` | `int` | | 标签类型：0=系统管理，1=自定义 | -|     `useCount` | `int` | | 使用次数 | -|   `title` | `string` | | 标题 | -|   `updatedAt` | `string` | | 更新时间 | -|   `viewCount` | `int` | | 浏览量 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/guide/article/list - -**文章列表** - -分页查询攻略文章，支持按分类、状态、关键词筛选 - -**关联字典**： -- wiki_status：文章状态（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `categoryId` | `integer(int64)` | | 分类ID | | -| `isRecommend` | `integer(int32)` | | 是否推荐：0=否，1=是 | | -| `isTop` | `integer(int32)` | | 是否置顶：0=否，1=是 | | -| `keyword` | `string` | | 关键词（搜索标题/摘要） | | -| `orderBy` | `string` | | 排序字段：sortOrder/publishTime/viewCount/createdAt（默认createdAt） | | -| `orderDir` | `string` | | 排序方向：asc/desc（默认desc） | | -| `page` | `integer(int32)` | | 页码（默认1） | | -| `pageSize` | `integer(int32)` | | 每页数量（默认20，最大100） | | -| `status` | `integer(int32)` | | 状态：0=草稿，1=已发布，2=已下架 | | - -**响应** `统一响应结果«分页结果«攻略文章列表项»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«攻略文章列表项»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `攻略文章列表项[]` | | 数据列表 | -|     `articleId` | `long` | | 文章ID | -|     `categoryId` | `long` | | 分类ID | -|     `categoryName` | `string` | | 分类名称 | -|     `coverUrl` | `string` | | 封面URL | -|     `createdAt` | `string` | | 创建时间 | -|     `isRecommend` | `int` | | 是否推荐：0=否，1=是 | -|     `isTop` | `int` | | 是否置顶：0=否，1=是 | -|     `publishTime` | `string` | | 发布时间 | -|     `sortOrder` | `int` | | 排序 | -|     `status` | `int` | | 状态：0=草稿，1=已发布，2=已下架 | -|     `summary` | `string` | | 摘要 | -|     `tags` | `攻略标签[]` | | 标签列表 | -|     `title` | `string` | | 标题 | -|     `viewCount` | `int` | | 浏览量 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/guide/article/{articleId} - -**文章详情** - -**关联字典**： -- wiki_status：文章状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | 是 | articleId | - -**响应** `统一响应结果«攻略文章详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略文章详情` | | 响应数据 | -|   `articleId` | `long` | | 文章ID | -|   `authorName` | `string` | | 作者名称 | -|   `bannerMaterialIds` | `long[]` | | 轮播图素材ID列表 | -|   `categoryId` | `long` | | 分类ID | -|   `categoryName` | `string` | | 分类名称 | -|   `content` | `string` | | 正文内容 | -|   `coverMaterialId` | `long` | | 封面素材ID | -|   `coverUrl` | `string` | | 封面URL | -|   `createdAt` | `string` | | 创建时间 | -|   `favoriteCount` | `int` | | 收藏数 | -|   `isRecommend` | `int` | | 是否推荐：0=否，1=是 | -|   `isTop` | `int` | | 是否置顶：0=否，1=是 | -|   `likeCount` | `int` | | 点赞数 | -|   `publishTime` | `string` | | 发布时间 | -|   `resources` | `文章关联资源[]` | | 关联资源列表 | -|     `resourceId` | `long` | | 资源ID | -|     `resourceName` | `string` | | 资源名称 | -|     `resourceType` | `string` | | 资源类型：SCENIC/RESTAURANT/HOTEL/ACTIVITY/PRODUCT | -|     `sortOrder` | `int` | | 排序 | -|   `sortOrder` | `int` | | 排序 | -|   `source` | `string` | | 来源 | -|   `status` | `int` | | 状态：0=草稿，1=已发布，2=已下架 | -|   `subtitle` | `string` | | 副标题 | -|   `summary` | `string` | | 摘要 | -|   `tags` | `攻略标签[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `long` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `tagType` | `int` | | 标签类型：0=系统管理，1=自定义 | -|     `useCount` | `int` | | 使用次数 | -|   `title` | `string` | | 标题 | -|   `updatedAt` | `string` | | 更新时间 | -|   `viewCount` | `int` | | 浏览量 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/guide/article/{articleId} - -**更新文章** - -更新攻略文章的标题、内容、封面图、分类等信息。已发布的文章更新后立即生效。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | 是 | articleId | - -**请求体** `ArticleUpdateRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `authorName` | `string` | | 作者名称 | -| `bannerMaterialIds` | `long[]` | | 轮播图素材ID列表 | -| `categoryId` | `long` | | 分类ID | -| `content` | `string` | | 正文内容 | -| `coverMaterialId` | `long` | | 封面素材ID | -| `coverUrl` | `string` | | 封面URL | -| `resources` | `ArticleResourceItem[]` | | 关联资源列表 | -|   `resourceId` | `long` | 是 | 资源ID | -|   `resourceName` | `string` | 是 | 资源名称 | -|   `resourceType` | `string` | 是 | 资源类型：SCENIC/RESTAURANT/HOTEL/ACTIVITY/PRODUCT | -|   `sortOrder` | `int` | | 排序 | -| `sortOrder` | `int` | | 排序 | -| `source` | `string` | | 来源 | -| `subtitle` | `string` | | 副标题 | -| `summary` | `string` | | 摘要 | -| `tagIds` | `long[]` | | 标签ID列表 | -| `title` | `string` | | 标题 | - -**响应** `统一响应结果«攻略文章详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略文章详情` | | 响应数据 | -|   `articleId` | `long` | | 文章ID | -|   `authorName` | `string` | | 作者名称 | -|   `bannerMaterialIds` | `long[]` | | 轮播图素材ID列表 | -|   `categoryId` | `long` | | 分类ID | -|   `categoryName` | `string` | | 分类名称 | -|   `content` | `string` | | 正文内容 | -|   `coverMaterialId` | `long` | | 封面素材ID | -|   `coverUrl` | `string` | | 封面URL | -|   `createdAt` | `string` | | 创建时间 | -|   `favoriteCount` | `int` | | 收藏数 | -|   `isRecommend` | `int` | | 是否推荐：0=否，1=是 | -|   `isTop` | `int` | | 是否置顶：0=否，1=是 | -|   `likeCount` | `int` | | 点赞数 | -|   `publishTime` | `string` | | 发布时间 | -|   `resources` | `文章关联资源[]` | | 关联资源列表 | -|     `resourceId` | `long` | | 资源ID | -|     `resourceName` | `string` | | 资源名称 | -|     `resourceType` | `string` | | 资源类型：SCENIC/RESTAURANT/HOTEL/ACTIVITY/PRODUCT | -|     `sortOrder` | `int` | | 排序 | -|   `sortOrder` | `int` | | 排序 | -|   `source` | `string` | | 来源 | -|   `status` | `int` | | 状态：0=草稿，1=已发布，2=已下架 | -|   `subtitle` | `string` | | 副标题 | -|   `summary` | `string` | | 摘要 | -|   `tags` | `攻略标签[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `long` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `tagType` | `int` | | 标签类型：0=系统管理，1=自定义 | -|     `useCount` | `int` | | 使用次数 | -|   `title` | `string` | | 标题 | -|   `updatedAt` | `string` | | 更新时间 | -|   `viewCount` | `int` | | 浏览量 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/guide/article/{articleId} - -**删除文章** - -软删除攻略文章，同时清除文章的标签关联。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | 是 | articleId | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/guide/article/{articleId}/recommend - -**设置推荐** - -设置/取消文章推荐。推荐文章会在小程序首页和推荐列表中优先展示 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | 是 | articleId | - -**请求体** `RecommendRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `isRecommend` | `int` | 是 | 是否推荐：0=否，1=是 | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/guide/article/{articleId}/status - -**发布/下架** - -切换文章发布状态。发布后小程序端可见，下架后小程序端不再展示但管理端仍可查看 - -**关联字典**： -- wiki_status：文章状态（状态切换） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | 是 | articleId | - -**请求体** `StatusRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `status` | `int` | 是 | 状态值 | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/guide/article/{articleId}/top - -**设置置顶** - -设置/取消文章置顶。置顶文章在分类列表中始终排在最前面 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | 是 | articleId | - -**请求体** `TopRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `isTop` | `int` | 是 | 是否置顶：0=否，1=是 | - -**响应** `统一响应结果«Void»` - ---- - -## 攻略标签管理 - -### `POST` /admin/guide/tag - -**创建标签** - -创建攻略系统标签，标签名称不可重复。创建后可用于文章分类和筛选。 - -**权限**：需管理员登录。 - -**请求体** `TagCreateRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagColor` | `string` | | 标签颜色（十六进制） | -| `tagName` | `string` | 是 | 标签名称 | -| `tagType` | `int` | | 标签类型：0=系统管理，1=自定义（默认0） | - -**响应** `统一响应结果«攻略标签»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略标签` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `long` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `tagType` | `int` | | 标签类型：0=系统管理，1=自定义 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/guide/tag/all - -**所有标签列表** - -返回全部标签（含系统标签和用户自定义标签），用于文章编辑时的标签选择器 - -**响应** `统一响应结果«List«攻略标签»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略标签[]` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `long` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `tagType` | `int` | | 标签类型：0=系统管理，1=自定义 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/guide/tag/article/{articleId} - -**更新文章标签** - -全量替换文章的标签关联，传入新的标签ID列表（空数组表示清除所有标签） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | 是 | articleId | - -**请求体** `ArticleTagUpdateRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagIds` | `long[]` | 是 | 标签ID列表 | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/guide/tag/managed - -**系统标签列表** - -返回管理员创建的系统标签（不含用户自定义标签），用于标签管理页 - -**响应** `统一响应结果«List«攻略标签»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略标签[]` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `long` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `tagType` | `int` | | 标签类型：0=系统管理，1=自定义 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/guide/tag/{tagId} - -**更新标签** - -更新标签名称。标签名称不可与其他已有标签重复。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagId` | `integer` | 是 | tagId | - -**请求体** `TagUpdateRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagColor` | `string` | | 标签颜色（十六进制） | -| `tagName` | `string` | | 标签名称 | - -**响应** `统一响应结果«攻略标签»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略标签` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `long` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `tagType` | `int` | | 标签类型：0=系统管理，1=自定义 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/guide/tag/{tagId} - -**删除标签** - -删除标签并自动解除与所有文章的关联关系。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagId` | `integer` | 是 | tagId | - -**响应** `统一响应结果«Void»` - ---- diff --git a/2026-03/17_0958/hl-material-service.md b/2026-03/17_0958/hl-material-service.md deleted file mode 100644 index c8ed7fb..0000000 --- a/2026-03/17_0958/hl-material-service.md +++ /dev/null @@ -1,968 +0,0 @@ -# 素材服务 API 文档 - -**服务**: `hl-material-service` -**接口总数**: 28 - -## 目录 - -- **小程序-素材** (1 个接口) -- **素材分类权限管理** (2 个接口) -- **素材标签管理** (6 个接口) -- **素材管理** (19 个接口) - ---- - -## 小程序-素材 - -### `GET` /mp/material/miniprogram - -**获取小程序分类下的全部素材** - -返回miniprogram分类下的所有素材，用于小程序端展示公共素材资源（如引导页图片、默认头像等） - -**响应** `统一响应结果«List«素材信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材信息[]` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `categoryPath` | `string` | | 完整分类路径（如：攻略管理 / 999 / 888） | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `string` | | 创建人ID | -|   `createdByName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 素材描述 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `imageHeight` | `int` | | 图片高度 | -|   `imageWidth` | `int` | | 图片宽度 | -|   `materialId` | `string` | | 素材ID | -|   `materialName` | `string` | | 素材名称 | -|   `ossUrl` | `string` | | OSS地址 | -|   `refCount` | `int` | | 引用次数 | -|   `subCategoryId` | `string` | | 子分类ID | -|   `subCategoryName` | `string` | | 子分类名称 | -|   `tags` | `素材标签信息[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdByName` | `string` | | 创建人姓名 | -|     `managed` | `boolean` | | 是否系统管理标签 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `string` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `useCount` | `int` | | 使用次数 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -## 素材分类权限管理 - -### `GET` /admin/material/category/permissions/{roleCode} - -**获取角色的分类权限** - -仅超级管理员可操作。返回指定角色可访问的素材分类编码列表 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `roleCode` | `string` | | 角色编码 | - -**响应** `统一响应结果«List«string»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `string[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/material/category/permissions/{roleCode} - -**更新角色的分类权限** - -仅超级管理员可操作。全量替换指定角色的素材分类访问权限，传入允许访问的分类编码列表 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `roleCode` | `string` | | 角色编码 | - -**请求体** `分类权限更新请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryCodes` | `string[]` | 是 | 分类编码列表 | - -**响应** `统一响应结果«Void»` - ---- - -## 素材标签管理 - -### `POST` /admin/material/tag - -**创建管理标签** - -创建系统级素材标签，标签名称不可重复。创建后可用于素材分类和筛选。 - -**权限**：需管理员登录。 - -**请求体** `创建标签请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagColor` | `string` | | 标签颜色 | -| `tagName` | `string` | 是 | 标签名称 | - -**响应** `统一响应结果«素材标签信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材标签信息` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdByName` | `string` | | 创建人姓名 | -|   `managed` | `boolean` | | 是否系统管理标签 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `string` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/tag/adhoc - -**解析自定义标签（按名称查找或创建）** - -按标签名称查找已有标签，不存在则自动创建为用户自定义标签。用于素材上传时输入自由标签文本的场景。 - -**权限**：需管理员登录。 - -**请求体** `创建标签请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagColor` | `string` | | 标签颜色 | -| `tagName` | `string` | 是 | 标签名称 | - -**响应** `统一响应结果«素材标签信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材标签信息` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdByName` | `string` | | 创建人姓名 | -|   `managed` | `boolean` | | 是否系统管理标签 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `string` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/material/tag/{tagId} - -**编辑标签** - -更新标签名称。标签名称不可与其他已有标签重复。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagId` | `integer` | | 标签ID | - -**请求体** `更新标签请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagColor` | `string` | | 标签颜色 | -| `tagName` | `string` | | 标签名称 | - -**响应** `统一响应结果«素材标签信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材标签信息` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdByName` | `string` | | 创建人姓名 | -|   `managed` | `boolean` | | 是否系统管理标签 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `string` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/material/tag/{tagId} - -**删除标签** - -删除标签并自动解除与所有素材的关联关系。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagId` | `integer` | | 标签ID | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/material/tags - -**获取管理标签（标签管理用）** - -返回管理员创建的系统标签列表（不含用户自定义标签），用于标签管理页的CRUD操作。 - -**响应** `统一响应结果«List«素材标签信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材标签信息[]` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdByName` | `string` | | 创建人姓名 | -|   `managed` | `boolean` | | 是否系统管理标签 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `string` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/material/tags/all - -**获取全部标签（选择器用，含自定义标签）** - -返回所有标签（含系统标签和用户自定义标签），用于素材上传/编辑时的标签选择器。 - -**响应** `统一响应结果«List«素材标签信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材标签信息[]` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdByName` | `string` | | 创建人姓名 | -|   `managed` | `boolean` | | 是否系统管理标签 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `string` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -## 素材管理 - -### `DELETE` /admin/material/batch - -**批量删除素材** - -批量删除素材，返回删除结果（成功数/失败数/失败原因）。有引用关系的素材会跳过并记录失败原因 - -**请求体** `批量删除素材请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `materialIds` | `string[]` | 是 | 素材ID列表 | - -**响应** `统一响应结果«批量删除结果»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `批量删除结果` | | 响应数据 | -|   `failedItems` | `删除失败项[]` | | 失败项列表 | -|     `materialId` | `string` | | 素材ID | -|     `reason` | `string` | | 失败原因 | -|   `successCount` | `int` | | 成功删除数量 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/material/batch/tags - -**批量更新标签** - -对多个素材同时添加和/或移除标签，支持增量操作（addTagIds新增，removeTagIds移除） - -**请求体** `批量标签操作请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `addTagIds` | `string[]` | | 要添加的标签ID列表 | -| `materialIds` | `string[]` | 是 | 素材ID列表 | -| `removeTagIds` | `string[]` | | 要移除的标签ID列表 | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/material/categories - -**获取有权限的分类列表（含素材数量）** - -返回当前角色有权限查看的素材分类树，每个分类包含素材数量统计。超级管理员可见全部分类 - -**响应** `统一响应结果«List«素材分类信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材分类信息[]` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `children` | `素材分类信息[]` | | 子分类列表 | -|     `categoryCode` | `string` | | 分类编码 | -|     `categoryName` | `string` | | 分类名称 | -|     `children` | `素材分类信息[]` | | 子分类列表 | -|     `materialCount` | `int` | | 素材数量 | -|     `parentId` | `string` | | 父子分类ID | -|     `subCategoryId` | `string` | | 子分类ID | -|   `materialCount` | `int` | | 素材数量 | -|   `parentId` | `string` | | 父子分类ID | -|   `subCategoryId` | `string` | | 子分类ID | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/category/sub - -**创建子分类** - -在一级分类下创建子分类，分类编码自动生成。子分类用于更细粒度的素材归档 - -**请求体** `Create subcategory request` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryName` | `string` | 是 | 子分类名称 | -| `parentCode` | `string` | 是 | 根分类编码(scenic/hotel等) | -| `parentId` | `long` | | 父子分类ID(为空则创建在根分类下) | -| `sortOrder` | `int` | | 排序值 | - -**响应** `统一响应结果«素材分类信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材分类信息` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `children` | `素材分类信息[]` | | 子分类列表 | -|     `categoryCode` | `string` | | 分类编码 | -|     `categoryName` | `string` | | 分类名称 | -|     `children` | `素材分类信息[]` | | 子分类列表 | -|     `materialCount` | `int` | | 素材数量 | -|     `parentId` | `string` | | 父子分类ID | -|     `subCategoryId` | `string` | | 子分类ID | -|   `materialCount` | `int` | | 素材数量 | -|   `parentId` | `string` | | 父子分类ID | -|   `subCategoryId` | `string` | | 子分类ID | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/material/category/sub/{categoryId} - -**更新子分类** - -更新子分类的名称或排序值。仅有该分类权限的管理员可操作。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryId` | `integer` | | 子分类ID | - -**请求体** `Update subcategory request` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryName` | `string` | | Subcategory name | -| `sortOrder` | `int` | | Sort order | - -**响应** `统一响应结果«素材分类信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材分类信息` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `children` | `素材分类信息[]` | | 子分类列表 | -|     `categoryCode` | `string` | | 分类编码 | -|     `categoryName` | `string` | | 分类名称 | -|     `children` | `素材分类信息[]` | | 子分类列表 | -|     `materialCount` | `int` | | 素材数量 | -|     `parentId` | `string` | | 父子分类ID | -|     `subCategoryId` | `string` | | 子分类ID | -|   `materialCount` | `int` | | 素材数量 | -|   `parentId` | `string` | | 父子分类ID | -|   `subCategoryId` | `string` | | 子分类ID | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/material/category/sub/{categoryId} - -**删除子分类** - -删除子分类前需确保分类下无素材，否则删除失败 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryId` | `integer` | | 子分类ID | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/material/list - -**素材列表** - -分页查询素材，支持按分类、标签、文件类型、关键词筛选。返回结果受角色分类权限限制 - -**关联字典**： -- file_type：文件类型（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `categoryCode` | `string` | | 分类编码 | scenic | -| `createdBy` | `integer(int64)` | | 创建人ID | 1001 | -| `endDate` | `string` | | 结束日期 | 2026-12-31 | -| `fileType` | `string` | | 文件类型 | image | -| `keyword` | `string` | | 搜索关键词 | 风景 | -| `orderBy` | `string` | | 排序字段 | createdAt | -| `orderDir` | `string` | | 排序方向: asc/desc | desc | -| `page` | `integer(int32)` | | 页码 | 1 | -| `pageSize` | `integer(int32)` | | 每页条数 | 20 | -| `startDate` | `string` | | 开始日期 | 2026-01-01 | -| `subCategoryId` | `integer(int64)` | | 子分类ID | 2030000000000001 | -| `tagIds` | `string` | | 标签ID列表(逗号分隔) | 1,2,3 | - -**响应** `统一响应结果«分页结果«素材信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«素材信息»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `素材信息[]` | | 数据列表 | -|     `categoryCode` | `string` | | 分类编码 | -|     `categoryName` | `string` | | 分类名称 | -|     `categoryPath` | `string` | | 完整分类路径（如：攻略管理 / 999 / 888） | -|     `createdAt` | `string` | | 创建时间 | -|     `createdBy` | `string` | | 创建人ID | -|     `createdByName` | `string` | | 创建人姓名 | -|     `description` | `string` | | 素材描述 | -|     `fileId` | `string` | | 文件ID | -|     `fileName` | `string` | | 文件名 | -|     `fileSize` | `long` | | 文件大小(字节) | -|     `fileType` | `string` | | 文件类型 | -|     `imageHeight` | `int` | | 图片高度 | -|     `imageWidth` | `int` | | 图片宽度 | -|     `materialId` | `string` | | 素材ID | -|     `materialName` | `string` | | 素材名称 | -|     `ossUrl` | `string` | | OSS地址 | -|     `refCount` | `int` | | 引用次数 | -|     `subCategoryId` | `string` | | 子分类ID | -|     `subCategoryName` | `string` | | 子分类名称 | -|     `tags` | `素材标签信息[]` | | 标签列表 | -|     `thumbnailUrl` | `string` | | 缩略图地址 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/upload/chunk - -**分片上传-上传分片** - -大文件上传第二步：逐个上传分片数据，分片索引从0开始。支持断点续传，已上传的分片无需重传。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `chunkIndex` | `integer(int32)` | | 分片索引（从0开始） | | -| `uploadId` | `string` | | 上传ID | | - -**响应** `统一响应结果«分片上传结果»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分片上传结果` | | 响应数据 | -|   `etag` | `string` | | 分片ETag | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/upload/chunk/cancel - -**分片上传-取消** - -取消分片上传任务，清理已上传的分片数据和OSS临时文件。仅上传发起者可取消。 - -**请求体** `分片上传取消请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `uploadId` | `string` | 是 | 上传ID | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /admin/material/upload/chunk/complete - -**分片上传-完成合并** - -大文件上传第三步：所有分片上传完成后调用，OSS端合并分片为完整文件并创建素材记录。 - -**请求体** `分片上传完成请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `uploadId` | `string` | 是 | 上传ID | - -**响应** `统一响应结果«素材信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材信息` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `categoryPath` | `string` | | 完整分类路径（如：攻略管理 / 999 / 888） | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `string` | | 创建人ID | -|   `createdByName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 素材描述 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `imageHeight` | `int` | | 图片高度 | -|   `imageWidth` | `int` | | 图片宽度 | -|   `materialId` | `string` | | 素材ID | -|   `materialName` | `string` | | 素材名称 | -|   `ossUrl` | `string` | | OSS地址 | -|   `refCount` | `int` | | 引用次数 | -|   `subCategoryId` | `string` | | 子分类ID | -|   `subCategoryName` | `string` | | 子分类名称 | -|   `tags` | `素材标签信息[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdByName` | `string` | | 创建人姓名 | -|     `managed` | `boolean` | | 是否系统管理标签 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `string` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `useCount` | `int` | | 使用次数 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/upload/chunk/init - -**分片上传-初始化** - -大文件上传第一步：初始化分片上传任务，返回uploadId和每个分片的预签名URL。前端按分片并发上传后调用完成合并接口。 - -**权限**：需管理员登录，受角色分类权限限制。 - -**请求体** `分片上传初始化请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `contentType` | `string` | 是 | 文件MIME类型 | -| `fileSize` | `long` | 是 | 文件大小（字节） | -| `filename` | `string` | 是 | 文件名 | -| `materialId` | `string` | | 关联素材ID（可选，用于更新已有素材） | - -**响应** `统一响应结果«分片上传初始化结果»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分片上传初始化结果` | | 响应数据 | -|   `chunkSize` | `int` | | 推荐分片大小（字节） | -|   `uploadId` | `string` | | 上传ID | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/upload/confirm - -**确认上传完成** - -上传素材第二步：前端直传OSS完成后调用此接口创建素材记录，支持MD5去重 - -**关联字典**： -- material_tag：素材标签（上传时可选标签） - -**请求体** `素材上传确认请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `description` | `string` | | 素材描述 | -| `materialId` | `string` | 是 | 素材ID | -| `tagIds` | `string[]` | | 标签ID列表 | - -**响应** `统一响应结果«素材信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材信息` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `categoryPath` | `string` | | 完整分类路径（如：攻略管理 / 999 / 888） | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `string` | | 创建人ID | -|   `createdByName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 素材描述 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `imageHeight` | `int` | | 图片高度 | -|   `imageWidth` | `int` | | 图片宽度 | -|   `materialId` | `string` | | 素材ID | -|   `materialName` | `string` | | 素材名称 | -|   `ossUrl` | `string` | | OSS地址 | -|   `refCount` | `int` | | 引用次数 | -|   `subCategoryId` | `string` | | 子分类ID | -|   `subCategoryName` | `string` | | 子分类名称 | -|   `tags` | `素材标签信息[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdByName` | `string` | | 创建人姓名 | -|     `managed` | `boolean` | | 是否系统管理标签 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `string` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `useCount` | `int` | | 使用次数 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/upload/folder - -**文件夹上传初始化（创建分类+批量获取凭证）** - -支持整个文件夹上传：自动根据文件夹名创建子分类，为每个文件批量获取上传凭证，前端逐一上传后批量确认 - -**请求体** `文件夹上传初始化请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryCode` | `string` | 是 | 分类编码 | -| `files` | `文件夹上传文件项[]` | 是 | 文件列表 | -|   `contentType` | `string` | 是 | 文件MIME类型 | -|   `fileSize` | `long` | 是 | 文件大小(字节) | -|   `filename` | `string` | 是 | 文件名 | -|   `folderPath` | `string` | 是 | 文件所在文件夹路径（与folderPaths中的路径对应） | -|   `materialName` | `string` | | 素材名称 | -|   `md5` | `string` | 是 | 文件MD5 | -| `folderPaths` | `string[]` | 是 | 文件夹路径列表（如 ["999", "999/888"]） | - -**响应** `统一响应结果«文件夹上传初始化结果»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `文件夹上传初始化结果` | | 响应数据 | -|   `fileTokens` | `文件上传凭证项[]` | | 各文件的上传凭证列表 | -|     `bucket` | `string` | | OSS Bucket名称 | -|     `error` | `string` | | 错误信息（该文件获取凭证失败时） | -|     `filename` | `string` | | 文件名 | -|     `folderPath` | `string` | | 文件夹路径 | -|     `instantUpload` | `boolean` | | 是否秒传（文件已存在） | -|     `materialId` | `string` | | 素材ID | -|     `ossKey` | `string` | | OSS对象Key | -|     `region` | `string` | | OSS Region | -|     `stsToken` | `STS临时凭证信息` | | STS临时凭证 | -|     `uploadHeaders` | `object` | | 上传请求头 | -|     `uploadMethod` | `string` | | 上传方式: PUT/POST | -|     `uploadUrl` | `string` | | 上传URL | -|   `folderCategoryMap` | `object` | | 文件夹路径 → 子分类ID 映射 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/upload/token - -**获取上传凭证** - -上传素材第一步：获取OSS预签名URL和凭证。前端使用凭证直传OSS后调用确认上传。支持基于角色的分类权限校验 - -**请求体** `素材上传令牌请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryCode` | `string` | 是 | 分类编码 | -| `contentType` | `string` | 是 | 文件MIME类型 | -| `fileSize` | `long` | 是 | 文件大小(字节) | -| `filename` | `string` | 是 | 文件名 | -| `materialName` | `string` | | 素材名称 | -| `md5` | `string` | 是 | 文件MD5 | -| `subCategoryId` | `long` | | 子分类ID（文件夹上传时使用） | - -**响应** `统一响应结果«素材上传令牌信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材上传令牌信息` | | 响应数据 | -|   `bucket` | `string` | | OSS Bucket名称 | -|   `contentType` | `string` | | 上传时必须使用的Content-Type（与预签名URL签名一致） | -|   `expireAt` | `string` | | 过期时间 | -|   `fileId` | `string` | | 文件ID | -|   `instantUpload` | `boolean` | | 是否秒传 | -|   `material` | `素材信息` | | 秒传时返回的素材信息 | -|     `categoryCode` | `string` | | 分类编码 | -|     `categoryName` | `string` | | 分类名称 | -|     `categoryPath` | `string` | | 完整分类路径（如：攻略管理 / 999 / 888） | -|     `createdAt` | `string` | | 创建时间 | -|     `createdBy` | `string` | | 创建人ID | -|     `createdByName` | `string` | | 创建人姓名 | -|     `description` | `string` | | 素材描述 | -|     `fileId` | `string` | | 文件ID | -|     `fileName` | `string` | | 文件名 | -|     `fileSize` | `long` | | 文件大小(字节) | -|     `fileType` | `string` | | 文件类型 | -|     `imageHeight` | `int` | | 图片高度 | -|     `imageWidth` | `int` | | 图片宽度 | -|     `materialId` | `string` | | 素材ID | -|     `materialName` | `string` | | 素材名称 | -|     `ossUrl` | `string` | | OSS地址 | -|     `refCount` | `int` | | 引用次数 | -|     `subCategoryId` | `string` | | 子分类ID | -|     `subCategoryName` | `string` | | 子分类名称 | -|     `tags` | `素材标签信息[]` | | 标签列表 | -|     `thumbnailUrl` | `string` | | 缩略图地址 | -|   `materialId` | `string` | | 素材ID | -|   `ossKey` | `string` | | OSS对象Key | -|   `region` | `string` | | OSS Region | -|   `stsToken` | `STS临时凭证信息` | | STS临时凭证 | -|     `accessKeyId` | `string` | | AccessKey ID | -|     `accessKeySecret` | `string` | | AccessKey Secret | -|     `expiration` | `string` | | 过期时间 | -|     `securityToken` | `string` | | 安全令牌 | -|   `uploadMode` | `string` | | 上传模式: PRESIGNED_URL/STS_MULTIPART | -|   `uploadUrl` | `string` | | 上传URL | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/material/{materialId} - -**素材详情** - -返回素材完整信息，包含文件名、URL、分类、标签、文件大小、上传者等。受角色分类权限限制。 - -**关联字典**： -- file_type：文件类型（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `materialId` | `integer` | | 素材ID | - -**响应** `统一响应结果«素材信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材信息` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `categoryPath` | `string` | | 完整分类路径（如：攻略管理 / 999 / 888） | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `string` | | 创建人ID | -|   `createdByName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 素材描述 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `imageHeight` | `int` | | 图片高度 | -|   `imageWidth` | `int` | | 图片宽度 | -|   `materialId` | `string` | | 素材ID | -|   `materialName` | `string` | | 素材名称 | -|   `ossUrl` | `string` | | OSS地址 | -|   `refCount` | `int` | | 引用次数 | -|   `subCategoryId` | `string` | | 子分类ID | -|   `subCategoryName` | `string` | | 子分类名称 | -|   `tags` | `素材标签信息[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdByName` | `string` | | 创建人姓名 | -|     `managed` | `boolean` | | 是否系统管理标签 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `string` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `useCount` | `int` | | 使用次数 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/material/{materialId} - -**更新素材信息** - -**关联字典**： -- material_tag：素材标签（编辑时选择标签） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `materialId` | `integer` | | 素材ID | - -**请求体** `更新素材请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryCode` | `string` | | 分类编码 | -| `description` | `string` | | 素材描述 | -| `materialName` | `string` | | 素材名称 | -| `subCategoryId` | `long` | | 子分类ID（0表示清除子分类） | - -**响应** `统一响应结果«素材信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材信息` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `categoryPath` | `string` | | 完整分类路径（如：攻略管理 / 999 / 888） | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `string` | | 创建人ID | -|   `createdByName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 素材描述 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `imageHeight` | `int` | | 图片高度 | -|   `imageWidth` | `int` | | 图片宽度 | -|   `materialId` | `string` | | 素材ID | -|   `materialName` | `string` | | 素材名称 | -|   `ossUrl` | `string` | | OSS地址 | -|   `refCount` | `int` | | 引用次数 | -|   `subCategoryId` | `string` | | 子分类ID | -|   `subCategoryName` | `string` | | 子分类名称 | -|   `tags` | `素材标签信息[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdByName` | `string` | | 创建人姓名 | -|     `managed` | `boolean` | | 是否系统管理标签 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `string` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `useCount` | `int` | | 使用次数 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/material/{materialId} - -**删除素材** - -删除素材记录。如果素材存在引用关系（被景区、酒店等使用），则不允许删除 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `materialId` | `integer` | | 素材ID | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/material/{materialId}/refs - -**查看素材引用记录** - -查看素材被哪些业务实体引用（如景区封面、酒店轮播图等），用于判断素材是否可安全删除 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `materialId` | `integer` | | 素材ID | - -**响应** `统一响应结果«List«素材引用信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材引用信息[]` | | 响应数据 | -|   `bizId` | `string` | | 业务ID | -|   `bizName` | `string` | | 业务名称 | -|   `bizType` | `string` | | 业务类型 | -|   `bizTypeName` | `string` | | 业务类型名称 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdByName` | `string` | | 创建人姓名 | -|   `id` | `string` | | 引用ID | -|   `materialId` | `string` | | 素材ID | -|   `usageType` | `string` | | 用途类型 | -|   `usageTypeName` | `string` | | 用途类型名称 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/material/{materialId}/tags - -**更新素材标签** - -全量替换单个素材的标签，传入新的标签ID列表 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `materialId` | `integer` | | 素材ID | - -**请求体** `更新素材标签请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagIds` | `string[]` | 是 | 标签ID列表 | - -**响应** `统一响应结果«Void»` - ---- diff --git a/2026-03/17_0958/hl-monitor-service.md b/2026-03/17_0958/hl-monitor-service.md deleted file mode 100644 index 188a26a..0000000 --- a/2026-03/17_0958/hl-monitor-service.md +++ /dev/null @@ -1,553 +0,0 @@ -# 监控服务 API 文档 - -**服务**: `hl-monitor-service` -**接口总数**: 18 - -## 目录 - -- **MySQL监控** (3 个接口) -- **Redis监控** (1 个接口) -- **RocketMQ监控** (3 个接口) -- **企微审批日志** (2 个接口) -- **操作日志** (2 个接口) -- **数据清理** (1 个接口) -- **服务监控** (1 个接口) -- **消息通知日志** (2 个接口) -- **登录日志** (1 个接口) -- **错误日志** (2 个接口) - ---- - -## MySQL监控 - -### `GET` /admin/monitor/mysql - -**MySQL实时监控数据** - -返回MySQL实时状态：连接数、QPS、缓冲池命中率、线程状态、慢查询计数等核心指标 - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/mysql/slow-queries - -**慢SQL查询统计** - -仅超级管理员可操作。查询慢SQL统计信息，返回执行时间最长的SQL语句及其执行次数、平均耗时等 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `limit` | `integer(int32)` | | 返回条数 | | -| `type` | `string` | | 查询类型 | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/mysql/tables - -**表空间列表** - -查询各数据库表的空间占用情况，包含数据大小、索引大小、行数等信息。可指定schema筛选，仅允许查询hl_前缀的数据库 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `schema` | `string` | | 数据库名 | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## Redis监控 - -### `GET` /admin/monitor/redis - -**Redis实时监控数据** - -返回Redis实时状态：内存使用量、连接数、Key数量、命中率、每秒命令数等核心指标 - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## RocketMQ监控 - -### `GET` /admin/monitor/rocketmq - -**RocketMQ概览** - -返回RocketMQ集群状态：Broker状态、Topic数量、消息积压量、生产者/消费者连接数等核心指标 - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/rocketmq/consumer-groups - -**消费者组统计** - -返回各消费者组的消费进度、积压量和在线消费者实例信息 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/rocketmq/topics - -**Topic统计** - -返回各Topic的消息量、最新偏移量和消费进度等信息 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## 企微审批日志 - -### `GET` /admin/monitor/approval-logs - -**审批日志分页查询** - -查询企微OA审批流程记录，支持按审批状态(1-审批中/2-已通过/3-已驳回/4-已撤销)、申请人、模板名称筛选 - -**关联字典**： -- approval_sp_status：审批状态（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `applyUserName` | `string` | | 申请人姓名 | | -| `endTime` | `string` | | 结束时间 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `spName` | `string` | | 审批模板名称 | | -| `spStatus` | `integer(int32)` | | 审批状态 | | -| `startTime` | `string` | | 开始时间 | | - -**响应** `统一响应结果«分页结果«审批日志»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«审批日志»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `审批日志[]` | | 数据列表 | -|     `applyData` | `string` | | 申请表单数据(JSON) | -|     `applyTime` | `string` | | 申请时间 | -|     `applyUserId` | `string` | | 申请人企微UserID | -|     `applyUserName` | `string` | | 申请人姓名 | -|     `approvalLogId` | `long` | | 审批日志ID | -|     `approvalNodes` | `string` | | 审批节点详情(JSON) | -|     `createdAt` | `string` | | 创建时间 | -|     `notifyNodes` | `string` | | 抄送节点详情(JSON) | -|     `spName` | `string` | | 审批模板名称 | -|     `spStatus` | `int` | | 审批状态: 1-审批中, 2-已通过, 3-已驳回, 4-已撤销, 6-通过后撤销, 7-已删除 | -|     `templateId` | `string` | | 审批模板ID | -|     `thirdNo` | `string` | | 审批编号 | -|     `updatedAt` | `string` | | 更新时间 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/approval-logs/{id} - -**审批日志详情** - -**关联字典**： -- approval_sp_status：审批状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 日志ID | - -**响应** `统一响应结果«审批日志»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `审批日志` | | 响应数据 | -|   `applyData` | `string` | | 申请表单数据(JSON) | -|   `applyTime` | `string` | | 申请时间 | -|   `applyUserId` | `string` | | 申请人企微UserID | -|   `applyUserName` | `string` | | 申请人姓名 | -|   `approvalLogId` | `long` | | 审批日志ID | -|   `approvalNodes` | `string` | | 审批节点详情(JSON) | -|   `createdAt` | `string` | | 创建时间 | -|   `notifyNodes` | `string` | | 抄送节点详情(JSON) | -|   `spName` | `string` | | 审批模板名称 | -|   `spStatus` | `int` | | 审批状态: 1-审批中, 2-已通过, 3-已驳回, 4-已撤销, 6-通过后撤销, 7-已删除 | -|   `templateId` | `string` | | 审批模板ID | -|   `thirdNo` | `string` | | 审批编号 | -|   `updatedAt` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -## 操作日志 - -### `GET` /admin/monitor/operation-logs - -**操作日志分页查询** - -查询管理员的操作记录，支持按模块、管理员、状态、时间范围筛选。记录包含请求参数、响应结果和耗时信息 - -**关联字典**： -- operation_log_status：操作状态（列表筛选+显示，0=成功/1=失败） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `adminId` | `integer(int64)` | | 管理员ID | | -| `endTime` | `string` | | 结束时间 | | -| `module` | `string` | | 模块名称 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `startTime` | `string` | | 开始时间 | | -| `status` | `integer(int32)` | | 状态 | | - -**响应** `统一响应结果«分页结果«操作日志»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«操作日志»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `操作日志[]` | | 数据列表 | -|     `adminId` | `long` | | 管理员ID | -|     `adminName` | `string` | | 管理员名称 | -|     `createdAt` | `string` | | 创建时间 | -|     `description` | `string` | | 操作描述 | -|     `duration` | `int` | | 耗时(毫秒) | -|     `errorMsg` | `string` | | 错误信息 | -|     `ipAddress` | `string` | | IP地址 | -|     `module` | `string` | | 操作模块 | -|     `operationLogId` | `long` | | 操作日志ID | -|     `requestMethod` | `string` | | 请求方法 | -|     `requestParams` | `string` | | 请求参数(JSON) | -|     `requestUrl` | `string` | | 请求URL | -|     `responseCode` | `int` | | 响应状态码 | -|     `responseMsg` | `string` | | 响应消息 | -|     `serviceName` | `string` | | 服务名称 | -|     `status` | `int` | | 状态: 0-成功, 1-失败 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/operation-logs/{id} - -**操作日志详情** - -返回单条操作日志的完整信息，包含操作模块、操作描述、请求参数、响应结果、操作耗时、操作人信息、IP地址等。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 日志ID | - -**响应** `统一响应结果«操作日志»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `操作日志` | | 响应数据 | -|   `adminId` | `long` | | 管理员ID | -|   `adminName` | `string` | | 管理员名称 | -|   `createdAt` | `string` | | 创建时间 | -|   `description` | `string` | | 操作描述 | -|   `duration` | `int` | | 耗时(毫秒) | -|   `errorMsg` | `string` | | 错误信息 | -|   `ipAddress` | `string` | | IP地址 | -|   `module` | `string` | | 操作模块 | -|   `operationLogId` | `long` | | 操作日志ID | -|   `requestMethod` | `string` | | 请求方法 | -|   `requestParams` | `string` | | 请求参数(JSON) | -|   `requestUrl` | `string` | | 请求URL | -|   `responseCode` | `int` | | 响应状态码 | -|   `responseMsg` | `string` | | 响应消息 | -|   `serviceName` | `string` | | 服务名称 | -|   `status` | `int` | | 状态: 0-成功, 1-失败 | -| `message` | `string` | | 响应消息 | - ---- - -## 数据清理 - -### `POST` /admin/monitor/data-retention/cleanup - -**手动触发数据清理** - -仅超级管理员可操作。按数据保留策略清理过期日志（操作日志/错误日志/通知日志等），返回各类型清理的记录数 - -**响应** `统一响应结果«Map«string,int»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## 服务监控 - -### `GET` /admin/monitor/services - -**微服务列表和健康状态** - -从Nacos注册中心获取所有微服务的实例列表和健康状态，包含IP、端口、注册时间和健康检查结果 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## 消息通知日志 - -### `GET` /admin/monitor/notification-logs - -**消息通知日志分页查询** - -查询各渠道（短信/站内信/企微/公众号）的通知发送记录，支持按通知类型、用户、发送状态筛选 - -**关联字典**： -- notification_send_status：发送状态（列表筛选+显示，0=待发送/1=成功/2=失败） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `endTime` | `string` | | 结束时间 | | -| `notificationType` | `string` | | 通知类型 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `sendStatus` | `integer(int32)` | | 发送状态 | | -| `startTime` | `string` | | 开始时间 | | -| `userName` | `string` | | 用户名 | | - -**响应** `统一响应结果«分页结果«通知日志»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«通知日志»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `通知日志[]` | | 数据列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `externalUserId` | `string` | | 外部联系人ID | -|     `externalUserName` | `string` | | 外部联系人姓名 | -|     `failReason` | `string` | | 失败原因 | -|     `messageContent` | `string` | | 消息内容 | -|     `notificationLogId` | `long` | | 通知日志ID | -|     `notificationType` | `string` | | 通知类型: ADD_EXTERNAL_CONTACT/DEL_FOLLOW_USER/DEL_EXTERNAL_CONTACT | -|     `sendStatus` | `int` | | 发送状态: 0-成功, 1-失败, 2-已过滤 | -|     `serviceName` | `string` | | 来源服务名称 | -|     `userId` | `string` | | 员工企微UserID | -|     `userName` | `string` | | 员工姓名 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/notification-logs/{id} - -**消息通知日志详情** - -返回单条通知发送日志的完整信息，包含通知类型、接收用户、发送渠道、发送状态、失败原因（如有）、消息内容等。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 日志ID | - -**响应** `统一响应结果«通知日志»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `通知日志` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `externalUserId` | `string` | | 外部联系人ID | -|   `externalUserName` | `string` | | 外部联系人姓名 | -|   `failReason` | `string` | | 失败原因 | -|   `messageContent` | `string` | | 消息内容 | -|   `notificationLogId` | `long` | | 通知日志ID | -|   `notificationType` | `string` | | 通知类型: ADD_EXTERNAL_CONTACT/DEL_FOLLOW_USER/DEL_EXTERNAL_CONTACT | -|   `sendStatus` | `int` | | 发送状态: 0-成功, 1-失败, 2-已过滤 | -|   `serviceName` | `string` | | 来源服务名称 | -|   `userId` | `string` | | 员工企微UserID | -|   `userName` | `string` | | 员工姓名 | -| `message` | `string` | | 响应消息 | - ---- - -## 登录日志 - -### `GET` /admin/monitor/login-logs - -**登录日志分页查询** - -查询管理员登录记录（代理到user-service），包含登录IP、设备信息、登录方式和登录结果 - -**关联字典**： -- login_status：登录状态（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `adminId` | `integer(int64)` | | 管理员ID | | -| `endTime` | `string` | | 结束时间 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `startTime` | `string` | | 开始时间 | | -| `status` | `string` | | 状态 | | - -**响应** `统一响应结果«object»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## 错误日志 - -### `GET` /admin/monitor/error-logs - -**错误日志分页查询** - -查询各微服务的异常记录，支持按服务名称、异常类名、时间范围筛选。堆栈信息仅保留com.hulalv包内的调用帧 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `endTime` | `string` | | 结束时间 | | -| `exceptionClass` | `string` | | 异常类名 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `serviceName` | `string` | | 服务名称 | | -| `startTime` | `string` | | 开始时间 | | - -**响应** `统一响应结果«分页结果«错误日志»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«错误日志»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `错误日志[]` | | 数据列表 | -|     `adminId` | `long` | | 管理员ID | -|     `createdAt` | `string` | | 创建时间 | -|     `errorLogId` | `long` | | 错误日志ID | -|     `exceptionClass` | `string` | | 异常类名 | -|     `exceptionMessage` | `string` | | 异常消息 | -|     `ipAddress` | `string` | | IP地址 | -|     `requestMethod` | `string` | | 请求方法 | -|     `requestParams` | `string` | | 请求参数(JSON) | -|     `requestUrl` | `string` | | 请求URL | -|     `serviceName` | `string` | | 服务名称 | -|     `stackTrace` | `string` | | 堆栈跟踪 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/error-logs/{id} - -**错误日志详情** - -返回单条错误日志的完整信息，包含异常类名、错误消息、过滤后的堆栈信息（仅com.hulalv包内调用帧）、请求URL、请求参数等。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 日志ID | - -**响应** `统一响应结果«错误日志»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `错误日志` | | 响应数据 | -|   `adminId` | `long` | | 管理员ID | -|   `createdAt` | `string` | | 创建时间 | -|   `errorLogId` | `long` | | 错误日志ID | -|   `exceptionClass` | `string` | | 异常类名 | -|   `exceptionMessage` | `string` | | 异常消息 | -|   `ipAddress` | `string` | | IP地址 | -|   `requestMethod` | `string` | | 请求方法 | -|   `requestParams` | `string` | | 请求参数(JSON) | -|   `requestUrl` | `string` | | 请求URL | -|   `serviceName` | `string` | | 服务名称 | -|   `stackTrace` | `string` | | 堆栈跟踪 | -| `message` | `string` | | 响应消息 | - ---- diff --git a/2026-03/17_0958/hl-mp-service.md b/2026-03/17_0958/hl-mp-service.md deleted file mode 100644 index 720fbe0..0000000 --- a/2026-03/17_0958/hl-mp-service.md +++ /dev/null @@ -1,3634 +0,0 @@ -# 小程序聚合服务 API 文档 - -**服务**: `hl-mp-service` -**接口总数**: 132 - -## 目录 - -- **C端 - 产品接口** (8 个接口) -- **C端 - 公共接口** (6 个接口) -- **C端 - 出行人接口** (6 个接口) -- **C端 - 前端配置接口** (2 个接口) -- **C端 - 发票接口** (4 个接口) -- **C端 - 合同接口** (5 个接口) -- **C端 - 天气接口** (3 个接口) -- **C端 - 字典接口** (1 个接口) -- **C端 - 定制师接口** (5 个接口) -- **C端 - 徽章接口** (1 个接口) -- **C端 - 心愿单接口** (2 个接口) -- **C端 - 探索接口** (5 个接口) -- **C端 - 搜索接口** (1 个接口) -- **C端 - 支付接口** (3 个接口) -- **C端 - 收藏接口** (6 个接口) -- **C端 - 攻略接口** (4 个接口) -- **C端 - 景区接口** (3 个接口) -- **C端 - 活动接口** (2 个接口) -- **C端 - 消息接口** (5 个接口) -- **C端 - 用户接口** (8 个接口) -- **C端 - 相册接口** (4 个接口) -- **C端 - 行程接口** (4 个接口) -- **C端 - 订单接口** (11 个接口) -- **C端 - 评价接口** (13 个接口) -- **C端 - 足迹接口** (4 个接口) -- **C端 - 轮播图接口** (1 个接口) -- **C端 - 退款接口** (7 个接口) -- **C端 - 通用点赞** (3 个接口) -- **C端 - 酒店接口** (2 个接口) -- **C端 - 餐厅接口** (2 个接口) -- **C端 - 首页接口** (1 个接口) - ---- - -## C端 - 产品接口 - -### `GET` /mp/product/batch/{batchId}/combos - -**GROUP批次套餐列表** - -返回指定批次的所有套餐（名称、人数组合、价格、库存） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `batchId` | `integer` | | 批次ID | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/product/lines - -**产品线列表** - -返回所有已启用的产品线，用于小程序首页或筛选栏展示 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/product/list - -**产品列表** - -分页查询已上架产品，支持按关键词、产品类型(CORE/ROUTE/CUSTOM/GROUP)、季节、天数、目的地、产品线筛选和排序 - -**关联字典（BFF透传）**： -- product_type：产品类型（列表筛选+显示） -- product_status：产品状态（透传自product-service） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `destination` | `string` | | 目的地 | | -| `keyword` | `string` | | 搜索关键词 | | -| `lineId` | `string` | | 产品线ID | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `productType` | `string` | | 产品类型：CORE/ROUTE/CUSTOM/GROUP | | -| `season` | `string` | | 季节 | | -| `sortBy` | `string` | | 排序字段 | | -| `sortDir` | `string` | | 排序方向 | | -| `tripDays` | `integer(int32)` | | 天数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/product/{productId} - -**产品详情（聚合收藏状态）** - -聚合流程：获取产品详情 → 并行查询收藏状态 → 异步记录足迹 → 返回聚合数据。支持未登录访问（不返回收藏状态） - -**关联字典（BFF透传）**： -- product_type：产品类型（显示） -- product_status：产品状态（透传自product-service） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `productId` | `integer` | | 产品ID | - -**响应** `统一响应结果«C端产品详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `C端产品详情` | | 响应数据 | -|   `chatMessages` | `Map«string,object»[]` | | 群聊最近消息（来自会话存档） | -|   `earliestBookingDate` | `string` | | 最早可订日期(如 2026-07-15) | -|   `earlyBirdDiscount` | `number` | | 早鸟优惠金额(元/人) | -|   `earlyBirdPlanName` | `string` | | 早鸟计划名称 | -|   `isFavorited` | `boolean` | | 是否已收藏（null表示未登录） | -|   `participantFamilyCount` | `int` | | 参与家庭数 | -|   `product` | `object` | | 产品详情（来自product-service） | -|   `reviewStats` | `object` | | 评价统计数据 | -|   `topLikedReview` | `object` | | 最高点赞评价 | -|   `topRatedReview` | `object` | | 最高评分评价 | -|   `totalSold` | `int` | | 已购人数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/product/{productId}/batch-calendar - -**GROUP批次日历** - -返回可报名批次列表（出发日期、剩余名额等），仅ENROLLING和CONFIRMED状态 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `productId` | `integer` | | 产品ID | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/product/{productId}/group-quote - -**GROUP报价** - -返回指定批次的各套餐报价（totalSellPrice） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `productId` | `integer` | | 产品ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `batchId` | `integer(int64)` | | 批次ID | | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/product/{productId}/price-calendar - -**价格日历** - -返回产品指定日期范围内的每日价格，用于日历组件展示。不传日期时默认返回未来一个月 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `productId` | `integer` | | 产品ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `endDate` | `string` | | 结束日期 | | -| `startDate` | `string` | | 开始日期 | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/product/{productId}/quote - -**报价计算（含早鸟优惠）** - -报价流程：传入出发日期+人数 → 价格日历计算基础报价（与下单一致） → 匹配早鸟优惠方案 → 返回明细报价+优惠信息。 - -支付方式说明： -- FULL: 全额支付，需一次性付清全部金额 -- DEPOSIT: 定金+尾款，先付定金（比例由产品配置），出行前补齐尾款 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `productId` | `integer` | | 产品ID | - -**请求体** `产品报价请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `adultCount` | `int` | 是 | 成人数量 | -| `babyCount` | `int` | | 婴儿数量 | -| `childCount` | `int` | | 儿童数量 | -| `childNeedBed` | `boolean` | | 儿童是否需要床位 | -| `departureDate` | `string` | 是 | 出发日期 | -| `youngChildCount` | `int` | | 幼儿数量 | - -**响应** `统一响应结果«产品报价结果»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `产品报价结果` | | 响应数据 | -|   `adultSellPrice` | `number` | | 成人单价 | -|   `babySellPrice` | `number` | | 幼童单价（固定价） | -|   `childSellPrice` | `number` | | 儿童单价 | -|   `childWithBedFee` | `number` | | 儿童加床费 | -|   `depositPayment` | `定金支付选项` | | 定金支付信息（仅paymentMode=DEPOSIT时有值） | -|     `balanceAmount` | `number` | | 尾款金额（出行前需付） | -|     `depositAmount` | `number` | | 定金金额（首次需付） | -|     `depositRatio` | `int` | | 定金比例(%) | -|     `description` | `string` | | 说明 | -|   `earlyBirdDiscount` | `早鸟优惠信息` | | 早鸟优惠信息，无优惠时为null | -|     `discountAmount` | `number` | | 优惠金额 | -|     `minPeople` | `int` | | 最低人数要求 | -|     `planId` | `long` | | 优惠方案ID | -|     `planName` | `string` | | 优惠方案名称 | -|   `finalPrice` | `number` | | 最终价（早鸟优惠后） | -|   `fullPayment` | `全额支付选项` | | 全额支付信息 | -|     `amount` | `number` | | 应付金额 | -|     `description` | `string` | | 说明 | -|   `grandTotalSellPrice` | `number` | | 总售价（优惠前） | -|   `paymentMode` | `string` | | 支付方式: FULL(全额支付) / DEPOSIT(定金+尾款) | -|   `totalAdultSellPrice` | `number` | | 成人小计 | -|   `totalBabySellPrice` | `number` | | 幼童小计 | -|   `totalChildSellPrice` | `number` | | 儿童小计 | -|   `totalYoungChildSellPrice` | `number` | | 小童小计 | -|   `youngChildSellPrice` | `number` | | 小童单价（儿童价×折扣比例） | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 公共接口 - -### `GET` /mp/common/agreement/list - -**协议列表** - -获取所有已上线的协议列表（不含内容，仅含类型、标题、版本） - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/common/agreement/{type} - -**获取协议文本** - -获取指定类型的协议文本（如隐私政策、用户协议），返回富文本内容 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `type` | `string` | 是 | 协议类型: privacy(隐私政策) / user(用户协议) | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/common/config - -**应用配置** - -获取应用全局配置信息 - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/common/contact - -**联系方式列表** - -获取有效的联系方式列表（电话/微信/邮箱等） - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/common/faq - -**FAQ列表** - -获取常见问题列表（按分类分组） - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/common/feedback - -**提交反馈** - -提交用户反馈，支持文字内容和图片附件 - -**请求体** `提交反馈请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `contact` | `string` | | 联系方式 | -| `content` | `string` | 是 | 反馈内容 | -| `images` | `string[]` | | 图片URL列表 | - -**响应** `统一响应结果«Void»` - ---- - -## C端 - 出行人接口 - -### `GET` /mp/user/traveler - -**出行人列表** - -返回当前用户的所有出行人列表。如果用户已完善实名信息，列表中会自动包含一条「本人」虚拟记录(travelerId=0) - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/user/traveler - -**添加出行人** - -添加常用出行人信息（姓名/证件/联系方式等），下单时可快速选择。单个用户最多50个出行人 - -**请求体** `修改)` - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/user/traveler/{id} - -**出行人详情** - -获取单个出行人的完整信息（姓名、证件信息、联系方式等）。 - -**权限**：需登录，仅能查看自己的出行人。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 出行人ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /mp/user/traveler/{id} - -**更新出行人** - -修改出行人信息，支持部分更新（只传需要修改的字段）。已关联订单的出行人修改不影响历史订单记录。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 出行人ID | - -**请求体** `修改)` - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /mp/user/traveler/{id} - -**删除出行人** - -删除常用出行人记录。默认出行人不可删除，需先取消默认后再删除。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 出行人ID | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /mp/user/traveler/{id}/default - -**设为默认出行人** - -设为默认出行人后，下单时自动作为第一个出行人。每个用户只能有一个默认出行人 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 出行人ID | - -**响应** `统一响应结果«Void»` - ---- - -## C端 - 前端配置接口 - -### `GET` /mp/config - -**获取所有非敏感前端配置** - -返回所有非SECRET类型的前端配置项（如主题色、客服电话、版本号等）。不含敏感配置，可安全传输给小程序端。 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/config/group/{group} - -**按分组获取非敏感前端配置** - -按配置分组获取前端配置项，如UI分组、功能开关分组等。用于小程序按需加载特定分组的配置。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `group` | `string` | | 配置分组 | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 发票接口 - -### `POST` /mp/invoice/apply - -**申请开票** - -开票流程：订单完成后 → 填写发票信息(抬头/税号/类型) → 提交开票申请 → 管理员处理 → 发送电子发票 - -**请求体** `发票申请请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `email` | `string` | | 接收邮箱 | -| `invoiceTitle` | `string` | 是 | 发票抬头 | -| `invoiceType` | `string` | 是 | 发票类型: PERSONAL(个人)/COMPANY(企业) | -| `orderId` | `string` | 是 | 订单ID | -| `taxpayerId` | `string` | | 纳税人识别号（企业发票必填） | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/invoice/order/{orderId} - -**通过订单ID查询发票** - -查询指定订单的发票信息，如果订单未开票则返回null - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/invoice/{id} - -**发票详情** - -获取发票的完整信息，包含开票状态、发票抬头、税号、金额、电子发票文件链接等 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 发票ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/invoice/{invoiceId}/reissue - -**发票换开** - -对已开发票申请换开（修改抬头/税号等），原发票作废后重新开具新发票 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `invoiceId` | `integer` | | 发票ID | - -**请求体** `发票换开请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `email` | `string` | | 接收邮箱 | -| `invoiceTitle` | `string` | 是 | 发票抬头 | -| `taxNumber` | `string` | | 纳税人识别号（企业发票必填） | -| `titleType` | `string` | 是 | 抬头类型: PERSONAL(个人)/COMPANY(企业) | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 合同接口 - -### `GET` /mp/contract/by-order/{orderId} - -**按订单查合同** - -返回订单关联的最新有效合同（非作废） - -**关联字典（BFF透传）**： -- contract_status：合同状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/contract/by-order/{orderId}/all - -**按订单查所有合同** - -返回订单关联的所有有效合同（TOUR+INSURANCE各一条） - -**关联字典（BFF透传）**： -- contract_status：合同状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/contract/list - -**合同列表** - -**关联字典（BFF透传）**： -- contract_status：合同状态（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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` | | 响应消息 | - ---- - -### `POST` /mp/contract/{contractId}/resend-sms - -**重新发送合同签署短信** - -重新向出行人发送合同签署短信通知，适用于出行人未收到短信或短信过期的场景。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `contractId` | `integer` | | 合同ID | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/contract/{id} - -**合同详情** - -返回合同基本信息、签署状态、出行人签署详情及合同文件下载链接 - -**关联字典（BFF透传）**： -- contract_status：合同状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 合同ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 天气接口 - -### `GET` /mp/weather/forecast - -**获取指定城市天气预报** - -通过高德天气API查询指定城市未来3天的天气预报信息 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `city` | `string` | | 城市名称 | | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/weather/itinerary/{orderId} - -**获取订单行程天气** - -根据订单行程中的目的地城市，批量查询每日天气信息，用于行程详情页展示 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/weather/live - -**获取指定城市实况天气** - -通过高德天气API查询指定城市的实时天气（温度、湿度、风向等） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `city` | `string` | | 城市名称 | | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 字典接口 - -### `GET` /dict/all - -**获取所有字典数据** - -获取系统全部字典数据（按字典类型分组），用于小程序端的下拉选项、枚举映射等。建议前端缓存此数据 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 定制师接口 - -### `GET` /mp/designer - -**定制师列表(含真实产品数和评分，综合排序)** - -获取定制师列表，聚合层会补充每个定制师的真实产品数量和评价评分。按综合排序（评分>路线数>咨询人数），用于小程序定制师推荐页。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `limit` | `integer(int32)` | | 每页条数 | | -| `page` | `integer(int32)` | | 页码 | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/designer/featured - -**推荐定制师(综合排序第一名)** - -获取综合排序排名第一的定制师信息（含产品数和评分），用于首页推荐定制师卡片展示。 - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/designer/{id} - -**定制师详情(含产品数量和评分)** - -获取定制师完整个人信息，聚合层会补充该定制师的已发布产品数量和综合评分，用于定制师个人主页展示。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 定制师ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/designer/{id}/products - -**定制师已发布产品列表** - -**关联字典（BFF透传）**： -- product_type：产品类型（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 定制师ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/designer/{id}/reviews - -**定制师产品评价列表** - -**关联字典（BFF透传）**： -- rating_level：评价等级（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 定制师ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 徽章接口 - -### `GET` /mp/badge - -**获取徽章数据** - -返回用户的徽章统计（未读消息数、待办事项数等），用于「我的」页面角标展示 - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 心愿单接口 - -### `GET` /mp/wish - -**心愿单列表** - -返回当前用户的心愿单列表，按创建时间倒序排列 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/wish - -**创建心愿** - -创建旅行心愿，描述想去的地方和时间偏好，定制师可据此推荐产品 - -**请求体** `创建心愿单请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `notes` | `string` | | 备注 | -| `productId` | `string` | 是 | 产品ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 探索接口 - -### `GET` /mp/explore/list - -**探索列表** - -获取已启用的探索分类列表（图文攻略内容），支持综合/最新/最热排序，分页返回。用于小程序探索频道首页瀑布流展示。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `sortType` | `string` | | 排序方式：comprehensive/newest/hottest | | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/explore/{id} - -**探索详情** - -自动增加浏览量，已登录时返回点赞/收藏状态 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 探索分类ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/explore/{id}/favorite - -**切换收藏** - -对探索内容收藏/取消收藏，返回当前收藏状态（true=已收藏）。收藏后可在'我的收藏'中查看。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 探索分类ID | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/explore/{id}/like - -**切换点赞** - -对探索内容点赞/取消点赞，返回当前点赞状态（true=已点赞）。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 探索分类ID | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/explore/{id}/view - -**浏览+1** - -增加探索内容的浏览计数。前端进入探索详情页时调用，无需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 探索分类ID | - -**响应** `统一响应结果«Void»` - ---- - -## C端 - 搜索接口 - -### `GET` /mp/search - -**搜索产品** - -按关键词搜索已上架产品（匹配产品名称和描述），支持按产品类型进一步筛选 - -**关联字典（BFF透传）**： -- product_type：产品类型（筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `keyword` | `string` | | 搜索关键词 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `productType` | `string` | | 产品类型：CORE/ROUTE/CUSTOM/GROUP | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 支付接口 - -### `POST` /mp/payment/prepay - -**发起支付** - -支付流程：选择支付方式(JSAPI/H5) → 调用微信支付API → 返回支付参数 → 前端调起微信支付 - -**关联字典（BFF透传）**： -- payment_status：支付状态（返回字段） - -**请求体** `支付预下单请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `clientIp` | `string` | | 客户端IP（H5支付必填） | -| `orderId` | `string` | 是 | 订单ID | -| `tradeType` | `string` | 是 | 支付方式: JSAPI(小程序支付)/H5(H5支付) | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/payment/status/{orderId} - -**查询支付状态** - -**关联字典（BFF透传）**： -- payment_status：支付状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/payment/transactions/{orderId} - -**订单交易记录列表** - -**关联字典（BFF透传）**： -- payment_status：支付状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 收藏接口 - -### `GET` /mp/user/favorite - -**收藏列表（含资源摘要）** - -分页查询收藏列表，聚合层会补充每个收藏项对应资源的摘要信息（名称、封面图、价格等）。支持按目标类型筛选。 - -**权限**：需登录。 - -**关联字典**： -- favorite_resource_type：收藏资源类型（PRODUCT/SCENIC/RESTAURANT/ACTIVITY） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `targetType` | `string` | | 目标类型筛选（字典：favorite_resource_type）：PRODUCT/SCENIC/RESTAURANT/ACTIVITY | | - -**响应** `统一响应结果«分页结果«收藏列表项（含资源摘要）»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«收藏列表项（含资源摘要）»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `收藏列表项（含资源摘要）[]` | | 数据列表 | -|     `coverUrl` | `string` | | 封面图URL | -|     `createdAt` | `string` | | 收藏时间 | -|     `favoriteId` | `string` | | 收藏记录ID | -|     `name` | `string` | | 资源名称 | -|     `tags` | `string[]` | | 标签列表 | -|     `targetId` | `string` | | 目标资源ID | -|     `targetType` | `string` | | 目标类型（字典：favorite_resource_type） | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/user/favorite - -**添加收藏** - -将产品/景区/餐厅/活动加入收藏。同一目标重复收藏会返回已有收藏记录 - -**请求体** `收藏请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `targetId` | `string` | 是 | 目标资源ID | -| `targetType` | `string` | 是 | 目标类型（字典：favorite_resource_type） | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /mp/user/favorite/batch - -**批量删除收藏** - -批量删除多条收藏记录，传入收藏记录ID列表。用于收藏管理页面的批量操作。 - -**权限**：需登录，仅能删除自己的收藏。 - -**请求体** `long[]` - -**响应** `统一响应结果«Void»` - ---- - -### `DELETE` /mp/user/favorite/by-target - -**按目标取消收藏** - -通过目标类型+目标ID取消收藏，适用于详情页点击取消收藏的场景（不需要知道收藏记录ID）。 - -**权限**：需登录。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `targetId` | `integer(int64)` | | 目标资源ID | | -| `targetType` | `string` | | 目标类型 | | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /mp/user/favorite/check - -**检查是否已收藏** - -检查当前用户是否已收藏指定资源，用于详情页收藏按钮状态显示。 - -**权限**：需登录。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `targetId` | `integer(int64)` | | 目标资源ID | | -| `targetType` | `string` | | 目标类型（字典：favorite_resource_type） | | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /mp/user/favorite/{id} - -**取消收藏** - -通过收藏记录ID取消收藏，适用于收藏列表页的删除操作。 - -**权限**：需登录，仅能删除自己的收藏。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 收藏记录ID | - -**响应** `统一响应结果«Void»` - ---- - -## C端 - 攻略接口 - -### `GET` /mp/wiki/article/{articleId} - -**文章详情** - -**关联字典（BFF透传）**： -- wiki_status：文章状态（返回字段） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | | 文章ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/wiki/categories - -**攻略分类列表** - -获取所有已启用的攻略分类，按排序值排列。用于小程序攻略频道的分类导航展示。 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/wiki/category/{categoryId}/articles - -**分类文章列表** - -分页查询指定攻略分类下已发布的文章列表，按发布时间倒序排列。用于攻略分类详情页。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryId` | `integer` | | 攻略分类ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/wiki/recommend-articles - -**推荐文章列表** - -获取编辑推荐的攻略文章列表（按推荐权重排序），用于首页或攻略频道的推荐位展示。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `limit` | `integer(int32)` | | 返回条数 | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 景区接口 - -### `GET` /mp/scenic/list - -**景区列表** - -分页查询已上架的景区列表，支持按关键词和城市筛选。聚合层透传resource-service的景区数据。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `city` | `string` | | 城市 | | -| `keyword` | `string` | | 关键词 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/scenic/{scenicId} - -**景区详情** - -获取景区完整信息（含季节素材、图文详情、价格等），自动注入静态地图图片URL用于详情页地图展示。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `scenicId` | `integer` | | 景区ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/scenic/{scenicId}/nearby - -**附近景区（地理+探索分类聚合）** - -聚合两个数据源：1.基于经纬度的地理位置附近景区（resource-service）；2.探索分类关联的景区（user-service）。去重合并后返回，用于景区详情页底部'附近推荐'展示。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `scenicId` | `integer` | | 景区ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `limit` | `integer(int32)` | | 返回条数 | | -| `radius` | `number(double)` | | 搜索半径(km) | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 活动接口 - -### `GET` /mp/activity/list - -**活动列表** - -分页查询已上架的活动列表，支持关键词和分类筛选。聚合层透传resource-service的活动数据给小程序前端。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `categoryCode` | `string` | | 分类 | | -| `keyword` | `string` | | 关键词 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/activity/{activityId} - -**活动详情** - -获取活动完整信息（含图文详情、价格等），自动注入静态地图图片URL用于详情页地图展示。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `activityId` | `integer` | | 活动ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 消息接口 - -### `GET` /mp/message/list - -**消息列表** - -消息列表，支持按分类筛选，按时间倒序分页返回 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `category` | `string` | | 消息分类筛选，不传返回全部 | | -| `page` | `integer(int32)` | | 页码，默认1 | | -| `pageSize` | `integer(int32)` | | 每页条数，默认20 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /mp/message/read-all - -**全部标记已读** - -将指定分类或全部消息标记为已读，不传category则全部已读 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `category` | `string` | | 消息分类，不传则将所有分类标记为已读 | | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /mp/message/summary - -**消息摘要** - -获取各分类的未读数量和最新一条消息，用于消息中心首页展示 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /mp/message/{id} - -**删除消息** - -删除单条消息 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | 是 | 消息ID | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /mp/message/{id}/read - -**标记已读** - -标记单条消息为已读 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | 是 | 消息ID | - -**响应** `统一响应结果«Void»` - ---- - -## C端 - 用户接口 - -### `DELETE` /mp/user/account - -**注销账号** - -注销后用户数据将被软删除，30天内可联系客服恢复 - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /mp/user/login - -**微信登录** - -登录流程：小程序wx.login获取code → 后端换取openid → 查找/创建用户 → 返回JWT令牌+needProfile标记 - -**请求体** `微信登录请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `string` | 是 | 微信授权code | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/user/login/sms - -**短信登录** - -登录流程：获取验证码 → 验证手机号+验证码 → 查找/创建用户 → 返回JWT令牌 - -**请求体** `短信验证码登录请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `string` | 是 | 验证码 | -| `phone` | `string` | 是 | 手机号 | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/user/logout - -**用户登出** - -清除用户登录状态和服务端缓存的令牌信息。登出后需重新登录获取新令牌。 - -**权限**：需登录。 - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /mp/user/ocr/idcard - -**身份证OCR识别** - -将身份证图片上传到OSS后，传入ossUrl进行OCR识别。返回姓名、身份证号、性别、民族等结构化数据，可用于自动填充出行人信息 - -**请求体** `身份证OCR识别请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `imgUrl` | `string` | 是 | 身份证图片的OSS地址 | - -**响应** `统一响应结果«Map«string,string»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/user/profile - -**获取用户信息** - -获取当前登录用户的个人资料，包含头像、昵称、手机号、实名信息等 - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /mp/user/profile - -**更新用户信息** - -更新当前用户的个人资料，支持部分更新（只传需要修改的字段）。首次完善资料时realName为必填 - -**请求体** `更新个人资料请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `avatar` | `string` | | 头像URL | -| `birthday` | `string` | | 生日 | -| `email` | `string` | | 邮箱 | -| `gender` | `int` | | 性别: 1=男, 2=女 | -| `nationality` | `string` | | 国籍 | -| `nickname` | `string` | | 昵称 | -| `phone` | `string` | | 手机号 | -| `realName` | `string` | | 真实姓名 | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/user/sms/send - -**发送短信验证码** - -向指定手机号发送登录验证码，有效期5分钟，60秒内不可重复发送 - -**请求体** `发送短信验证码请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `phone` | `string` | 是 | 手机号 | - -**响应** `统一响应结果«Void»` - ---- - -## C端 - 相册接口 - -### `GET` /mp/album/file/{albumFileId}/download-url - -**获取文件下载链接** - -获取文件的预签名下载URL，有效期有限 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `albumFileId` | `integer` | 是 | 相册文件ID | - -**响应** `统一响应结果«string»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `string` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/album/folder/{folderId}/files - -**文件夹下的文件列表** - -获取文件夹下的文件列表（分页），含图片和视频 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `folderId` | `integer` | 是 | 文件夹ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码，默认1 | | -| `size` | `integer(int32)` | | 每页数量，默认20 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/album/order/{orderId}/folders - -**订单的文件夹列表** - -获取订单下的相册文件夹列表 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | 是 | 订单ID | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/album/orders - -**有相册的订单列表** - -获取当前登录用户有相册的订单列表 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 行程接口 - -### `GET` /mp/trip/list - -**行程列表** - -获取当前登录用户的行程列表（已确认及进行中的订单对应的行程） - -**关联字典（BFF透传）**： -- order_status：订单/行程状态（显示） - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/trip/today - -**今日行程** - -获取今日行程（如果有正在进行中的行程），无行程时data为null - -**关联字典（BFF透传）**： -- order_status：订单/行程状态（显示） - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/trip/weather - -**天气查询** - -高德天气API代理，传入城市名称返回实时天气信息 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `city` | `string` | 是 | 城市名称，如「成都」「拉萨」 | | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/trip/{orderId} - -**行程详情** - -获取订单对应的行程详情，含每日行程节点信息（景点/酒店/餐厅等） - -**关联字典（BFF透传）**： -- order_status：订单/行程状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | 是 | 订单ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 订单接口 - -### `POST` /mp/order/bind-by-contact - -**绑定未绑定的订单** - -绑定流程：用户登录 → 完善个人资料 → 自动通过联系人手机号+姓名匹配 → 将userId=NULL的订单绑定到当前用户 - -**请求体** `通过联系人信息绑定订单请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `contactName` | `string` | 是 | 联系人姓名 | -| `contactPhone` | `string` | 是 | 联系人手机号 | - -**响应** `统一响应结果«int»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `int` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/count - -**各状态订单数量** - -统计当前用户各状态的订单数量，用于「我的」页面的订单状态角标展示 - -**关联字典（BFF透传）**： -- order_status：订单状态（状态分类统计） - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/order/create - -**创建订单** - -下单流程：选择产品 → 填写联系人/出行人信息 → 报价计算 → 创建订单 → 返回订单ID - -**请求体** `C端创建订单请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `adultCount` | `int` | | 成人数 | -| `babyCount` | `int` | | 幼童数 | -| `childCount` | `int` | | 儿童数 | -| `childNeedBed` | `boolean` | | 儿童是否需要床位 | -| `contactName` | `string` | 是 | 联系人姓名 | -| `contactPhone` | `string` | 是 | 联系人电话 | -| `customizerId` | `string` | | 定制师ID(通过分享链接下单时传入) | -| `departureDate` | `string` | | 出发日期(GROUP产品从团期获取，可不传) | -| `groupBatchId` | `string` | | 团期ID(GROUP产品必填) | -| `productId` | `string` | 是 | 产品ID | -| `remark` | `string` | | 备注 | -| `roomCount` | `int` | | 房间数(GROUP产品，默认1) | -| `sharerOpenid` | `string` | | 分享人微信openid（通过分享进入下单时传入，用于记录分享关系） | -| `travelers` | `出行人信息[]` | | 出行人列表 | -|   `birthday` | `string` | | 出生日期 | -|   `email` | `string` | | 电子邮箱 | -|   `emergencyContact` | `string` | | 紧急联系人 | -|   `emergencyPhone` | `string` | | 紧急联系电话 | -|   `gender` | `int` | | 性别（1=男, 2=女） | -|   `idCardNo` | `string` | | 证件号码 | -|   `idCardType` | `string` | | 证件类型 | -|   `name` | `string` | 是 | 出行人姓名 | -|   `nationality` | `string` | | 国籍 | -|   `phone` | `string` | | 手机号 | -|   `travelerType` | `string` | | 出行人类型（ADULT/CHILD/YOUNG_CHILD/BABY） | -| `youngChildCount` | `int` | | 小童数 | - -**响应** `统一响应结果«订单详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `订单详情` | | 响应数据 | -|   `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` | `Map«string,object»[]` | | 优惠列表 | -|   `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` | | 支付模式（FULL/DEPOSIT） | -|   `processStatus` | `string` | | 内部流程状态 | -|   `processStatusLabel` | `string` | | 内部流程状态标签 | -|   `productCoverUrl` | `string` | | 产品封面图URL | -|   `productId` | `long` | | 产品ID | -|   `productName` | `string` | | 产品名称 | -|   `productSnapshot` | `string` | | 产品快照JSON | -|   `productType` | `string` | | 产品类型（CORE/ROUTE/CUSTOM/GROUP） | -|   `readyAt` | `string` | | 就绪时间 | -|   `refundAmount` | `number` | | 退款金额 | -|   `remark` | `string` | | 备注 | -|   `returnDate` | `string` | | 返程日期（出发日期 + 行程天数 - 1） | -|   `reviewed` | `boolean` | | 是否已评价 | -|   `roomInfo` | `string` | | 房间信息 | -|   `status` | `string` | | 订单状态（PENDING_PAY/DEPOSIT_PAID/PAID/CONFIRMED/IN_PROGRESS/COMPLETED/CANCELLED） | -|   `statusLabel` | `string` | | 订单状态标签 | -|   `timeline` | `Map«string,object»[]` | | 时间线列表 | -|   `todos` | `Map«string,object»[]` | | 待办列表 | -|   `totalPrice` | `number` | | 总售价 | -|   `travelers` | `Map«string,object»[]` | | 出行人列表 | -|   `tripDays` | `int` | | 行程天数 | -|   `tripNights` | `int` | | 行程晚数 | -|   `unlockRequestedAt` | `string` | | 解锁请求时间 | -|   `userId` | `long` | | 用户ID | -|   `vehicleInfo` | `string` | | 车辆信息 | -|   `youngChildCount` | `int` | | 小童数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/list - -**订单列表** - -分页查询当前用户的订单列表，支持按状态筛选。返回订单摘要信息（不含详细出行人信息） - -**关联字典（BFF透传）**： -- order_status：订单状态（列表筛选+显示） -- product_type：产品类型（订单卡片显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `status` | `string` | | 状态 | | - -**响应** `统一响应结果«分页结果«订单列表项»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«订单列表项»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `订单列表项[]` | | 数据列表 | -|     `adultCount` | `int` | | 成人数 | -|     `babyCount` | `int` | | 幼童数 | -|     `balanceAmount` | `number` | | 尾款金额 | -|     `childCount` | `int` | | 儿童数 | -|     `contracts` | `Map«string,object»[]` | | 合同列表（含signUrl/fileUrl/status等） | -|     `createTime` | `string` | | 创建时间 | -|     `daysUntilDeparture` | `int` | | 距出发天数（负数表示已出发） | -|     `departureDate` | `string` | | 出发日期 | -|     `depositAmount` | `number` | | 定金金额 | -|     `displayName` | `string` | | 显示名称（未支付=手机号+姓名，已支付=订单号） | -|     `displayStatus` | `string` | | C端简化状态（PENDING_PAY/PENDING_DEPARTURE/PENDING_REVIEW/REFUND/CANCELLED） | -|     `displayStatusLabel` | `string` | | C端简化状态标签 | -|     `expiryTime` | `string` | | 支付截止时间（PENDING_PAY状态有效） | -|     `insurances` | `Map«string,object»[]` | | 保险订单列表（含productName/extPolicyNo/status等） | -|     `nextAction` | `string` | | 下一步操作提示 | -|     `orderId` | `long` | | 订单ID | -|     `orderNo` | `string` | | 订单编号 | -|     `paidAmount` | `number` | | 已付金额 | -|     `paymentMode` | `string` | | 支付模式（FULL/DEPOSIT） | -|     `processStatus` | `string` | | 内部流程状态（字典：order_process_status） | -|     `processStatusLabel` | `string` | | 内部流程状态标签（字典：order_process_status 翻译） | -|     `productCoverUrl` | `string` | | 产品封面图URL | -|     `productId` | `long` | | 产品ID | -|     `productName` | `string` | | 产品名称 | -|     `productType` | `string` | | 产品类型（CORE/ROUTE/CUSTOM/GROUP） | -|     `status` | `string` | | 订单状态（PENDING_PAY/DEPOSIT_PAID/PAID/CONFIRMED/IN_PROGRESS/COMPLETED/CANCELLED） | -|     `statusLabel` | `string` | | 订单状态标签 | -|     `totalPrice` | `number` | | 总售价 | -|     `tripDays` | `int` | | 行程天数 | -|     `tripNights` | `int` | | 行程晚数 | -|     `youngChildCount` | `int` | | 小童数 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/lookup - -**通过联系人手机号+姓名查找订单（无需登录）** - -无需登录即可查询。用于管理员代下单场景：管理员创建订单后，用户通过联系人手机号+姓名查找订单并绑定到自己账号。仅返回尚未绑定用户(userId=NULL)的订单。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `contactName` | `string` | | 联系人姓名 | | -| `contactPhone` | `string` | | 联系人手机号 | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/upcoming - -**即将出发的订单** - -查询3天内即将出发的订单（状态为已确认/待出发/出行中），含合同和保险信息，按出发日期升序 - -**响应** `统一响应结果«List«订单列表项»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `订单列表项[]` | | 响应数据 | -|   `adultCount` | `int` | | 成人数 | -|   `babyCount` | `int` | | 幼童数 | -|   `balanceAmount` | `number` | | 尾款金额 | -|   `childCount` | `int` | | 儿童数 | -|   `contracts` | `Map«string,object»[]` | | 合同列表（含signUrl/fileUrl/status等） | -|   `createTime` | `string` | | 创建时间 | -|   `daysUntilDeparture` | `int` | | 距出发天数（负数表示已出发） | -|   `departureDate` | `string` | | 出发日期 | -|   `depositAmount` | `number` | | 定金金额 | -|   `displayName` | `string` | | 显示名称（未支付=手机号+姓名，已支付=订单号） | -|   `displayStatus` | `string` | | C端简化状态（PENDING_PAY/PENDING_DEPARTURE/PENDING_REVIEW/REFUND/CANCELLED） | -|   `displayStatusLabel` | `string` | | C端简化状态标签 | -|   `expiryTime` | `string` | | 支付截止时间（PENDING_PAY状态有效） | -|   `insurances` | `Map«string,object»[]` | | 保险订单列表（含productName/extPolicyNo/status等） | -|   `nextAction` | `string` | | 下一步操作提示 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `paidAmount` | `number` | | 已付金额 | -|   `paymentMode` | `string` | | 支付模式（FULL/DEPOSIT） | -|   `processStatus` | `string` | | 内部流程状态（字典：order_process_status） | -|   `processStatusLabel` | `string` | | 内部流程状态标签（字典：order_process_status 翻译） | -|   `productCoverUrl` | `string` | | 产品封面图URL | -|   `productId` | `long` | | 产品ID | -|   `productName` | `string` | | 产品名称 | -|   `productType` | `string` | | 产品类型（CORE/ROUTE/CUSTOM/GROUP） | -|   `status` | `string` | | 订单状态（PENDING_PAY/DEPOSIT_PAID/PAID/CONFIRMED/IN_PROGRESS/COMPLETED/CANCELLED） | -|   `statusLabel` | `string` | | 订单状态标签 | -|   `totalPrice` | `number` | | 总售价 | -|   `tripDays` | `int` | | 行程天数 | -|   `tripNights` | `int` | | 行程晚数 | -|   `youngChildCount` | `int` | | 小童数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/{orderId} - -**订单详情** - -获取订单完整信息，包含产品快照、出行人列表、支付信息、合同状态等 - -**关联字典（BFF透传）**： -- order_status：订单状态（显示） -- product_type：产品类型（显示） -- contract_status：合同状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«订单详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `订单详情` | | 响应数据 | -|   `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` | `Map«string,object»[]` | | 优惠列表 | -|   `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` | | 支付模式（FULL/DEPOSIT） | -|   `processStatus` | `string` | | 内部流程状态 | -|   `processStatusLabel` | `string` | | 内部流程状态标签 | -|   `productCoverUrl` | `string` | | 产品封面图URL | -|   `productId` | `long` | | 产品ID | -|   `productName` | `string` | | 产品名称 | -|   `productSnapshot` | `string` | | 产品快照JSON | -|   `productType` | `string` | | 产品类型（CORE/ROUTE/CUSTOM/GROUP） | -|   `readyAt` | `string` | | 就绪时间 | -|   `refundAmount` | `number` | | 退款金额 | -|   `remark` | `string` | | 备注 | -|   `returnDate` | `string` | | 返程日期（出发日期 + 行程天数 - 1） | -|   `reviewed` | `boolean` | | 是否已评价 | -|   `roomInfo` | `string` | | 房间信息 | -|   `status` | `string` | | 订单状态（PENDING_PAY/DEPOSIT_PAID/PAID/CONFIRMED/IN_PROGRESS/COMPLETED/CANCELLED） | -|   `statusLabel` | `string` | | 订单状态标签 | -|   `timeline` | `Map«string,object»[]` | | 时间线列表 | -|   `todos` | `Map«string,object»[]` | | 待办列表 | -|   `totalPrice` | `number` | | 总售价 | -|   `travelers` | `Map«string,object»[]` | | 出行人列表 | -|   `tripDays` | `int` | | 行程天数 | -|   `tripNights` | `int` | | 行程晚数 | -|   `unlockRequestedAt` | `string` | | 解锁请求时间 | -|   `userId` | `long` | | 用户ID | -|   `vehicleInfo` | `string` | | 车辆信息 | -|   `youngChildCount` | `int` | | 小童数 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/order/{orderId}/approve-unlock - -**同意解锁订单** - -用户同意管理员的修改请求，解除订单锁定状态，允许管理员继续修改订单 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /mp/order/{orderId}/cancel - -**取消订单** - -取消规则：仅PENDING_PAY/DEPOSIT_PAID状态可用户取消，取消后不可恢复 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**请求体** `用户取消订单请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reason` | `string` | | 取消原因 | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /mp/order/{orderId}/edit - -**修改订单** - -用户可修改出发日期和出行人。仅待支付/已付定金/已支付/已确认/待付尾款/待出发状态可修改，清单已确认的订单不允许修改。修改后重走内部流程 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**请求体** `修改订单请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `departureDate` | `string` | | 出发日期 | -| `travelers` | `出行人信息_1[]` | | 出行人列表（提供则替换全部出行人） | -|   `birthday` | `string` | | 出生日期 | -|   `email` | `string` | | 电子邮箱 | -|   `emergencyContact` | `string` | | 紧急联系人 | -|   `emergencyPhone` | `string` | | 紧急联系电话 | -|   `gender` | `int` | | 性别 | -|   `idCardNo` | `string` | | 证件号码 | -|   `idCardType` | `string` | | 证件类型 | -|   `name` | `string` | 是 | 出行人姓名 | -|   `nationality` | `string` | | 国籍 | -|   `phone` | `string` | | 手机号 | -|   `travelerType` | `string` | | 出行人类型 | - -**响应** `统一响应结果«订单详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `订单详情` | | 响应数据 | -|   `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` | `Map«string,object»[]` | | 优惠列表 | -|   `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` | | 支付模式（FULL/DEPOSIT） | -|   `processStatus` | `string` | | 内部流程状态 | -|   `processStatusLabel` | `string` | | 内部流程状态标签 | -|   `productCoverUrl` | `string` | | 产品封面图URL | -|   `productId` | `long` | | 产品ID | -|   `productName` | `string` | | 产品名称 | -|   `productSnapshot` | `string` | | 产品快照JSON | -|   `productType` | `string` | | 产品类型（CORE/ROUTE/CUSTOM/GROUP） | -|   `readyAt` | `string` | | 就绪时间 | -|   `refundAmount` | `number` | | 退款金额 | -|   `remark` | `string` | | 备注 | -|   `returnDate` | `string` | | 返程日期（出发日期 + 行程天数 - 1） | -|   `reviewed` | `boolean` | | 是否已评价 | -|   `roomInfo` | `string` | | 房间信息 | -|   `status` | `string` | | 订单状态（PENDING_PAY/DEPOSIT_PAID/PAID/CONFIRMED/IN_PROGRESS/COMPLETED/CANCELLED） | -|   `statusLabel` | `string` | | 订单状态标签 | -|   `timeline` | `Map«string,object»[]` | | 时间线列表 | -|   `todos` | `Map«string,object»[]` | | 待办列表 | -|   `totalPrice` | `number` | | 总售价 | -|   `travelers` | `Map«string,object»[]` | | 出行人列表 | -|   `tripDays` | `int` | | 行程天数 | -|   `tripNights` | `int` | | 行程晚数 | -|   `unlockRequestedAt` | `string` | | 解锁请求时间 | -|   `userId` | `long` | | 用户ID | -|   `vehicleInfo` | `string` | | 车辆信息 | -|   `youngChildCount` | `int` | | 小童数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/{orderId}/resources - -**订单资源详情（按分类）** - -解析产品快照，提取资源详情按分类返回 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«Map«string,List«Map«string,object»»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 评价接口 - -### `POST` /mp/review/create - -**创建评价** - -评价流程：订单完成后 → 查询可评价目标列表 → 对每个目标(酒店/景区/活动等)提交评价 → 自动内容审核 → 审核通过后公开展示 - -**关联字典（BFF透传）**： -- review_status：评价审核状态（返回字段） -- rating_level：评价等级（返回字段） - -**请求体** `创建评价请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `content` | `string` | 是 | 评价内容(10-500字) | -| `images` | `评价图片项[]` | | 评价图片列表（最多9张） | -|   `fileId` | `long` | | 文件ID | -|   `imageUrl` | `string` | 是 | 图片URL | -| `orderId` | `long` | 是 | 订单ID | -| `ratings` | `object` | 是 | 评分数据（key为评分类别字典的dictValue，value为1-5整数）。先调用 GET /mp/review/rating-categories 获取评分维度，required=true的必填。示例: {"ratingItinerary":5,"ratingAccommodation":4,"ratingDriver":5,"ratingDining":4,"ratingOverall":5} | -| `videos` | `评价视频项[]` | | 评价视频列表（最多3个） | -|   `coverUrl` | `string` | | 视频封面URL | -|   `duration` | `int` | | 视频时长(秒) | -|   `fileId` | `long` | | 文件ID | -|   `videoUrl` | `string` | 是 | 视频URL | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/featured - -**精选评价列表(公开)** - -无需登录，返回精选评价数组，用于评价浏览页 - -**关联字典（BFF透传）**： -- rating_level：评价等级（显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `limit` | `integer(int32)` | | 数量限制 | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/my - -**我的评价列表** - -**关联字典（BFF透传）**： -- review_status：评价审核状态（显示） -- rating_level：评价等级（显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/order/{orderId}/reviewable-targets - -**订单可评价目标列表** - -返回订单中可评价的资源目标列表（景区/酒店/活动等），用于评价页面展示可评价项。已评价的目标不会重复出现。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/order/{orderId}/reviewed - -**检查订单是否已评价** - -检查指定订单是否已提交评价，用于订单详情页决定是否显示'去评价'按钮。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/product/{productId} - -**按产品ID查看评价列表** - -返回评价列表+统计数据，支持好中差评/有图/有视频筛选 - -**关联字典（BFF透传）**： -- rating_level：评价等级（筛选+显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `productId` | `integer` | | 产品ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `hasImage` | `boolean` | | 是否有图片 | | -| `hasVideo` | `boolean` | | 是否有视频 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `ratingLevel` | `string` | | 评价等级: GOOD/MEDIUM/BAD | | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/product/{productId}/highlights - -**产品精选评价(最高评分+最高点赞+统计)** - -用于产品详情页评价区域展示 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `productId` | `integer` | | 产品ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/rating-categories - -**评分类别列表** - -从字典读取评价时需要填写的评分维度，前端据此渲染评分组件。字典类型: review_rating_category，remark字段包含扩展JSON(required/min/max) - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/search - -**关键词搜索评价(公开)** - -按关键词搜索已通过的评价内容，支持按目标类型和目标ID筛选 - -**关联字典（BFF透传）**： -- rating_level：评价等级（显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `keyword` | `string` | 是 | 搜索关键词 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `targetId` | `integer(int64)` | | 目标ID(可选) | | -| `targetType` | `string` | | 目标类型(可选): PRODUCT/SCENIC_SPOT/ACTIVITY/HOTEL等 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/stats - -**评价统计(平均分、数量)** - -获取指定目标的评价统计数据（平均评分、总评价数等），用于详情页评价区域展示。产品showReview关闭时返回空统计。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `targetId` | `integer(int64)` | | 目标ID | | -| `targetType` | `string` | | 目标类型 | | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/target - -**某目标的已通过评价(公开)** - -**关联字典（BFF透传）**： -- rating_level：评价等级（筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `hasImage` | `boolean` | | 是否有图片 | | -| `hasVideo` | `boolean` | | 是否有视频 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `ratingLevel` | `string` | | 评价等级: GOOD/MEDIUM/BAD | | -| `targetId` | `integer(int64)` | | 目标ID | | -| `targetType` | `string` | | 目标类型 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/review/{reviewId}/like - -**点赞/取消点赞评价** - -对评价进行点赞或取消点赞操作，返回当前点赞状态和点赞总数。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reviewId` | `integer` | | 评价ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/{reviewId}/like/check - -**检查是否已点赞** - -检查当前用户是否已点赞指定评价，用于评价列表/详情的点赞按钮状态展示。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reviewId` | `integer` | | 评价ID | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 足迹接口 - -### `GET` /mp/user/footprint - -**足迹列表（含资源摘要）** - -分页查询浏览足迹列表，聚合层会补充每条足迹对应资源的摘要信息（名称、封面图等）。支持按资源类型筛选，按浏览时间倒序。 - -**权限**：需登录。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `resourceType` | `string` | | 资源类型筛选：PRODUCT/SCENIC/RESTAURANT/ACTIVITY | | - -**响应** `统一响应结果«分页结果«足迹列表项（含资源摘要）»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«足迹列表项（含资源摘要）»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `足迹列表项（含资源摘要）[]` | | 数据列表 | -|     `coverUrl` | `string` | | 封面图URL | -|     `footprintId` | `string` | | 足迹记录ID | -|     `name` | `string` | | 资源名称 | -|     `resourceId` | `string` | | 资源ID | -|     `resourceType` | `string` | | 资源类型：PRODUCT/SCENIC/RESTAURANT/ACTIVITY | -|     `tags` | `string[]` | | 标签列表 | -|     `visitTime` | `string` | | 浏览时间 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/user/footprint - -**记录足迹** - -记录用户浏览资源的足迹，同一资源重复浏览会更新浏览时间而非新增记录 - -**请求体** `添加足迹请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `resourceId` | `string` | 是 | 资源ID | -| `resourceType` | `string` | 是 | 资源类型: PRODUCT/SCENIC/RESTAURANT/ACTIVITY | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /mp/user/footprint/batch - -**批量删除足迹** - -批量删除多条浏览足迹记录，传入足迹ID列表。用于足迹管理页面的批量清理。 - -**权限**：需登录，仅能删除自己的足迹。 - -**请求体** `long[]` - -**响应** `统一响应结果«Void»` - ---- - -### `DELETE` /mp/user/footprint/{id} - -**删除足迹** - -删除单条浏览足迹记录。 - -**权限**：需登录，仅能删除自己的足迹。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 足迹ID | - -**响应** `统一响应结果«Void»` - ---- - -## C端 - 轮播图接口 - -### `GET` /mp/banner/active - -**获取当前生效的轮播图列表** - -返回当前处于有效期内的轮播图，按排序值排列。用于小程序首页顶部轮播展示，透传自user-service。 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 退款接口 - -### `GET` /mp/order/refund-reasons - -**退款原因列表** - -返回系统预设的退款原因选项，用于退款申请页面的原因选择 - -**响应** `统一响应结果«List«退款原因»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款原因[]` | | 响应数据 | -|   `category` | `string` | | 分类: GENERAL(通用)/PRODUCT(产品问题)/SERVICE(服务问题) | -|   `enabled` | `boolean` | | 是否启用 | -|   `reasonId` | `long` | | 原因ID | -|   `reasonText` | `string` | | 原因描述 | -|   `sortOrder` | `int` | | 排序序号 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/refund/{applicationId} - -**退款申请详情** - -获取退款申请的完整信息，包含审核状态、退款金额、退款进度和操作记录 - -**关联字典（BFF透传）**： -- order_status：订单状态（显示） -- payment_status：支付/退款状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `applicationId` | `integer` | | 退款申请ID | - -**响应** `统一响应结果«退款申请详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款申请详情` | | 响应数据 | -|   `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` | | 审批编号（企微OA审批编号） | -|   `autoRefundDeadline` | `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` | | 退款类型: DEPOSIT(定金)/BALANCE(尾款)/FULL(全款) | -|   `refundTypeLabel` | `string` | | 退款类型中文标签 | -|   `refundedAt` | `string` | | 退款完成时间 | -|   `reviewAdminId` | `long` | | 审批管理员ID | -|   `reviewAdminName` | `string` | | 审批管理员姓名 | -|   `reviewRemark` | `string` | | 审批备注 | -|   `reviewedAt` | `string` | | 审批时间 | -|   `status` | `string` | | 退款状态: PENDING(待审核)/APPROVED(已通过)/REJECTED(已拒绝)/REFUNDING(退款中)/REFUNDED(已退款)/CANCELLED(已撤回)/APPEALING(申诉中)/APPEAL_APPROVED(申诉通过)/APPEAL_REJECTED(申诉驳回) | -|   `statusLabel` | `string` | | 退款状态中文标签 | -|   `updateTime` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/order/refund/{applicationId}/appeal - -**发起申诉** - -退款被拒绝后，用户可在3天内发起一次申诉，由上级管理员重新审核 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `applicationId` | `integer` | | 退款申请ID | - -**请求体** `退款申诉请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `appealReason` | `string` | 是 | 申诉原因 | -| `evidence` | `string[]` | | 申诉凭证图片URL列表 | - -**响应** `统一响应结果«退款申请详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款申请详情` | | 响应数据 | -|   `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` | | 审批编号（企微OA审批编号） | -|   `autoRefundDeadline` | `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` | | 退款类型: DEPOSIT(定金)/BALANCE(尾款)/FULL(全款) | -|   `refundTypeLabel` | `string` | | 退款类型中文标签 | -|   `refundedAt` | `string` | | 退款完成时间 | -|   `reviewAdminId` | `long` | | 审批管理员ID | -|   `reviewAdminName` | `string` | | 审批管理员姓名 | -|   `reviewRemark` | `string` | | 审批备注 | -|   `reviewedAt` | `string` | | 审批时间 | -|   `status` | `string` | | 退款状态: PENDING(待审核)/APPROVED(已通过)/REJECTED(已拒绝)/REFUNDING(退款中)/REFUNDED(已退款)/CANCELLED(已撤回)/APPEALING(申诉中)/APPEAL_APPROVED(申诉通过)/APPEAL_REJECTED(申诉驳回) | -|   `statusLabel` | `string` | | 退款状态中文标签 | -|   `updateTime` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/order/refund/{applicationId}/cancel - -**撤回退款申请** - -仅PENDING状态的退款申请可撤回，撤回后订单恢复到原状态 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `applicationId` | `integer` | | 退款申请ID | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /mp/order/{orderId}/refund - -**提交退款申请** - -退款流程：获取退款预览 → 选择退款原因 → 提交退款申请 → 管理员审核 → 审核通过后自动退款到原支付方式 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**请求体** `退款申请请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `images` | `string[]` | | 退款凭证图片URL列表 | -| `reasonDetail` | `string` | | 退款补充说明 | -| `reasonId` | `string` | | 退款原因ID（已废弃，改用字典） | -| `reasonText` | `string` | 是 | 退款原因文本 | -| `reasonValue` | `string` | | 退款原因字典值 | -| `refundType` | `string` | 是 | 退款类型（FULL/DEPOSIT/BALANCE） | - -**响应** `统一响应结果«退款申请详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款申请详情` | | 响应数据 | -|   `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` | | 审批编号（企微OA审批编号） | -|   `autoRefundDeadline` | `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` | | 退款类型: DEPOSIT(定金)/BALANCE(尾款)/FULL(全款) | -|   `refundTypeLabel` | `string` | | 退款类型中文标签 | -|   `refundedAt` | `string` | | 退款完成时间 | -|   `reviewAdminId` | `long` | | 审批管理员ID | -|   `reviewAdminName` | `string` | | 审批管理员姓名 | -|   `reviewRemark` | `string` | | 审批备注 | -|   `reviewedAt` | `string` | | 审批时间 | -|   `status` | `string` | | 退款状态: PENDING(待审核)/APPROVED(已通过)/REJECTED(已拒绝)/REFUNDING(退款中)/REFUNDED(已退款)/CANCELLED(已撤回)/APPEALING(申诉中)/APPEAL_APPROVED(申诉通过)/APPEAL_REJECTED(申诉驳回) | -|   `statusLabel` | `string` | | 退款状态中文标签 | -|   `updateTime` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/{orderId}/refund-detail - -**根据订单ID获取最新退款详情** - -查询订单关联的最新一条退款申请详情，无退款记录时返回null - -**关联字典（BFF透传）**： -- order_status：订单状态（显示） -- payment_status：支付/退款状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `string` | | 订单ID | - -**响应** `统一响应结果«退款申请详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款申请详情` | | 响应数据 | -|   `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` | | 审批编号（企微OA审批编号） | -|   `autoRefundDeadline` | `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` | | 退款类型: DEPOSIT(定金)/BALANCE(尾款)/FULL(全款) | -|   `refundTypeLabel` | `string` | | 退款类型中文标签 | -|   `refundedAt` | `string` | | 退款完成时间 | -|   `reviewAdminId` | `long` | | 审批管理员ID | -|   `reviewAdminName` | `string` | | 审批管理员姓名 | -|   `reviewRemark` | `string` | | 审批备注 | -|   `reviewedAt` | `string` | | 审批时间 | -|   `status` | `string` | | 退款状态: PENDING(待审核)/APPROVED(已通过)/REJECTED(已拒绝)/REFUNDING(退款中)/REFUNDED(已退款)/CANCELLED(已撤回)/APPEALING(申诉中)/APPEAL_APPROVED(申诉通过)/APPEAL_REJECTED(申诉驳回) | -|   `statusLabel` | `string` | | 退款状态中文标签 | -|   `updateTime` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/{orderId}/refund-preview - -**退款金额预览** - -根据退款政策和订单出发日期计算可退金额，展示退款比例和扣除金额明细 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«退款预览»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款预览` | | 响应数据 | -|   `calculatedAmount` | `number` | | 计算退款金额 | -|   `daysBeforeDept` | `int` | | 距出发天数 | -|   `departureDate` | `string` | | 出发日期 | -|   `message` | `string` | | 提示信息 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单号 | -|   `paidAmount` | `number` | | 已付金额 | -|   `policyId` | `long` | | 匹配的退款政策ID | -|   `policyName` | `string` | | 匹配的退款政策名称 | -|   `refundRatio` | `int` | | 退款比例（百分比） | -|   `refundType` | `string` | | 退款类型: DEPOSIT/BALANCE/FULL | -|   `refundable` | `boolean` | | 是否可退款 | -|   `rules` | `退款规则项[]` | | 退款规则列表（按天数降序） | -|     `matched` | `boolean` | | 是否当前命中此规则 | -|     `minDays` | `int` | | 最低天数 | -|     `refundRatio` | `int` | | 退款比例（百分比） | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 通用点赞 - -### `POST` /mp/like/{targetType}/batch-check - -**批量检查点赞状态** - -批量检查当前用户是否已对多个目标点赞，返回已点赞的目标ID列表。用于列表页批量展示点赞状态。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `targetType` | `string` | | 目标类型 | - -**请求体** `string[]` - -**响应** `统一响应结果«List«string»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `string[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/like/{targetType}/{targetId} - -**切换点赞** - -点赞/取消点赞，返回 {liked: true/false, likeCount: 点赞数} - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `targetId` | `integer` | | 目标ID | -| `targetType` | `string` | | 目标类型: REVIEW/EXPLORE/GUIDE等 | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/like/{targetType}/{targetId}/check - -**检查是否已点赞** - -检查当前用户是否已对指定目标点赞，用于前端点赞按钮状态展示。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `targetId` | `integer` | | 目标ID | -| `targetType` | `string` | | 目标类型 | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 酒店接口 - -### `GET` /mp/hotel/list - -**酒店列表** - -分页查询已上架的酒店列表，支持按关键词、城市、星级筛选。聚合层透传resource-service的酒店数据。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `city` | `string` | | 城市 | | -| `keyword` | `string` | | 关键词 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `starLevel` | `integer(int32)` | | 星级 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/hotel/{hotelId} - -**酒店详情** - -获取酒店完整信息（含房型列表、图文详情、价格等），自动注入静态地图图片URL用于详情页地图展示。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `hotelId` | `integer` | | 酒店ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 餐厅接口 - -### `GET` /mp/restaurant/list - -**餐厅列表** - -分页查询已上架的餐厅列表，支持按关键词和城市筛选。聚合层透传resource-service的餐厅数据。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `city` | `string` | | 城市 | | -| `keyword` | `string` | | 关键词 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/restaurant/{restaurantId} - -**餐厅详情** - -获取餐厅完整信息（含菜品、图文详情等），自动注入静态地图图片URL用于详情页地图展示。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `restaurantId` | `integer` | | 餐厅ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 首页接口 - -### `GET` /mp/home - -**首页数据** - -聚合流程：并行获取推荐产品列表+产品线列表+轮播图 → Redis缓存5分钟 → 返回聚合数据 - -**关联字典（BFF透传）**： -- product_type：产品类型（产品卡片显示） -- product_status：产品状态（透传自product-service） - -**响应** `统一响应结果«首页聚合数据»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `首页聚合数据` | | 响应数据 | -|   `banners` | `Map«string,object»[]` | | 轮播图Banner列表 | -|   `contactInfo` | `Map«string,object»[]` | | 联系我们列表 | -|   `exploreTopics` | `Map«string,object»[]` | | 探索专题列表 | -|   `featuredDesigner` | `object` | | 推荐定制师 | -|   `featuredReviews` | `Map«string,object»[]` | | 首页精选评价列表 | -|   `productLines` | `Map«string,object»[]` | | 产品线分类列表 | -|   `recommendProducts` | `Map«string,object»[]` | | 推荐产品列表 | -| `message` | `string` | | 响应消息 | - ---- diff --git a/2026-03/17_0958/hl-order-service.md b/2026-03/17_0958/hl-order-service.md deleted file mode 100644 index ed3738c..0000000 --- a/2026-03/17_0958/hl-order-service.md +++ /dev/null @@ -1,3594 +0,0 @@ -# 订单服务 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_0958/hl-payment-service.md b/2026-03/17_0958/hl-payment-service.md deleted file mode 100644 index 9982afc..0000000 --- a/2026-03/17_0958/hl-payment-service.md +++ /dev/null @@ -1,282 +0,0 @@ -# 支付服务 API 文档 - -**服务**: `hl-payment-service` -**接口总数**: 7 - -## 目录 - -- **支付管理** (7 个接口) - ---- - -## 支付管理 - -### `GET` /admin/payment/list - -**支付交易列表** - -分页查询支付交易记录，支持按订单号、交易状态、交易类型筛选 - -**关联字典**： -- payment_mode：支付模式（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `endDate` | `string` | | 结束日期 | 2026-12-31 | -| `mchId` | `string` | | 商户号 | 1246532201 | -| `orderNo` | `string` | | 订单编号 | HL20260301120000001234 | -| `page` | `integer(int32)` | | 页码 | 1 | -| `pageSize` | `integer(int32)` | | 每页条数 | 20 | -| `startDate` | `string` | | 开始日期 | 2026-01-01 | -| `status` | `string` | | 支付状态 | SUCCESS | -| `tradeType` | `string` | | 交易类型: JSAPI/H5 | JSAPI | - -**响应** `统一响应结果«分页结果«支付交易信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«支付交易信息»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `支付交易信息[]` | | 数据列表 | -|     `createTime` | `string` | | 创建时间 | -|     `mchId` | `string` | | 商户号 | -|     `orderId` | `long` | | 订单ID | -|     `orderNo` | `string` | | 订单编号 | -|     `outTradeNo` | `string` | | 商户订单号 | -|     `payTime` | `string` | | 支付时间 | -|     `payType` | `string` | | 支付类型: FULL/DEPOSIT/BALANCE | -|     `status` | `string` | | 交易状态 | -|     `totalAmount` | `number` | | 交易金额 | -|     `tradeType` | `string` | | 交易类型: JSAPI/H5 | -|     `transactionId` | `long` | | 交易ID | -|     `transactionIdWx` | `string` | | 微信支付交易号 | -|     `userId` | `long` | | 用户ID | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/payment/order/{orderId} - -**按订单查询交易** - -查询指定订单的所有支付交易记录 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«List«支付交易信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `支付交易信息[]` | | 响应数据 | -|   `createTime` | `string` | | 创建时间 | -|   `mchId` | `string` | | 商户号 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `outTradeNo` | `string` | | 商户订单号 | -|   `payTime` | `string` | | 支付时间 | -|   `payType` | `string` | | 支付类型: FULL/DEPOSIT/BALANCE | -|   `status` | `string` | | 交易状态 | -|   `totalAmount` | `number` | | 交易金额 | -|   `tradeType` | `string` | | 交易类型: JSAPI/H5 | -|   `transactionId` | `long` | | 交易ID | -|   `transactionIdWx` | `string` | | 微信支付交易号 | -|   `userId` | `long` | | 用户ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/payment/refund/order/{orderId} - -**按订单查询退款** - -查询指定订单的所有退款记录 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«List«退款记录信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款记录信息[]` | | 响应数据 | -|   `createTime` | `string` | | 创建时间 | -|   `mchId` | `string` | | 商户号 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `outRefundNo` | `string` | | 商户退款单号 | -|   `reason` | `string` | | 退款原因 | -|   `refundAmount` | `number` | | 退款金额 | -|   `refundId` | `long` | | 退款ID | -|   `refundIdWx` | `string` | | 微信退款单号 | -|   `status` | `string` | | 退款状态 | -|   `successTime` | `string` | | 退款成功时间 | -|   `totalAmount` | `number` | | 订单总金额 | -|   `transactionId` | `long` | | 交易ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/payment/refund/{refundId} - -**退款详情** - -获取单笔退款记录的完整信息，包含微信退款单号和退款状态 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `refundId` | `integer` | | 退款ID | - -**响应** `统一响应结果«退款记录信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款记录信息` | | 响应数据 | -|   `createTime` | `string` | | 创建时间 | -|   `mchId` | `string` | | 商户号 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `outRefundNo` | `string` | | 商户退款单号 | -|   `reason` | `string` | | 退款原因 | -|   `refundAmount` | `number` | | 退款金额 | -|   `refundId` | `long` | | 退款ID | -|   `refundIdWx` | `string` | | 微信退款单号 | -|   `status` | `string` | | 退款状态 | -|   `successTime` | `string` | | 退款成功时间 | -|   `totalAmount` | `number` | | 订单总金额 | -|   `transactionId` | `long` | | 交易ID | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/payment/{orderId}/refund - -**发起退款** - -退款流程：验证订单 → 查找原支付交易 → 调用微信退款API → 记录退款单 → 等待微信回调更新状态 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**请求体** `退款请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `amount` | `number` | 是 | 退款金额 | -| `orderId` | `long` | 是 | 订单ID | -| `reason` | `string` | | 退款原因 | - -**响应** `统一响应结果«退款记录信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款记录信息` | | 响应数据 | -|   `createTime` | `string` | | 创建时间 | -|   `mchId` | `string` | | 商户号 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `outRefundNo` | `string` | | 商户退款单号 | -|   `reason` | `string` | | 退款原因 | -|   `refundAmount` | `number` | | 退款金额 | -|   `refundId` | `long` | | 退款ID | -|   `refundIdWx` | `string` | | 微信退款单号 | -|   `status` | `string` | | 退款状态 | -|   `successTime` | `string` | | 退款成功时间 | -|   `totalAmount` | `number` | | 订单总金额 | -|   `transactionId` | `long` | | 交易ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/payment/{transactionId} - -**交易详情** - -获取单笔交易的完整信息，包含微信支付流水号 - -**关联字典**： -- payment_mode：支付模式（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `transactionId` | `integer` | | 交易ID | - -**响应** `统一响应结果«支付交易信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `支付交易信息` | | 响应数据 | -|   `createTime` | `string` | | 创建时间 | -|   `mchId` | `string` | | 商户号 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `outTradeNo` | `string` | | 商户订单号 | -|   `payTime` | `string` | | 支付时间 | -|   `payType` | `string` | | 支付类型: FULL/DEPOSIT/BALANCE | -|   `status` | `string` | | 交易状态 | -|   `totalAmount` | `number` | | 交易金额 | -|   `tradeType` | `string` | | 交易类型: JSAPI/H5 | -|   `transactionId` | `long` | | 交易ID | -|   `transactionIdWx` | `string` | | 微信支付交易号 | -|   `userId` | `long` | | 用户ID | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/payment/{transactionId}/sync - -**同步支付状态** - -主动查询微信支付状态并同步本地数据，适用于回调未到达的场景 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `transactionId` | `integer` | | 交易ID | - -**响应** `统一响应结果«支付交易信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `支付交易信息` | | 响应数据 | -|   `createTime` | `string` | | 创建时间 | -|   `mchId` | `string` | | 商户号 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `outTradeNo` | `string` | | 商户订单号 | -|   `payTime` | `string` | | 支付时间 | -|   `payType` | `string` | | 支付类型: FULL/DEPOSIT/BALANCE | -|   `status` | `string` | | 交易状态 | -|   `totalAmount` | `number` | | 交易金额 | -|   `tradeType` | `string` | | 交易类型: JSAPI/H5 | -|   `transactionId` | `long` | | 交易ID | -|   `transactionIdWx` | `string` | | 微信支付交易号 | -|   `userId` | `long` | | 用户ID | -| `message` | `string` | | 响应消息 | - ---- diff --git a/2026-03/17_0958/hl-product-service.md b/2026-03/17_0958/hl-product-service.md deleted file mode 100644 index 06de89c..0000000 --- a/2026-03/17_0958/hl-product-service.md +++ /dev/null @@ -1,5188 +0,0 @@ -# 产品服务 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_0958/hl-resource-service.md b/2026-03/17_0958/hl-resource-service.md deleted file mode 100644 index 4bea593..0000000 --- a/2026-03/17_0958/hl-resource-service.md +++ /dev/null @@ -1,6998 +0,0 @@ -# 资源服务 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_0958/hl-review-service.md b/2026-03/17_0958/hl-review-service.md deleted file mode 100644 index dbb2fda..0000000 --- a/2026-03/17_0958/hl-review-service.md +++ /dev/null @@ -1,236 +0,0 @@ -# 评价服务 API 文档 - -**服务**: `hl-review-service` -**接口总数**: 6 - -## 目录 - -- **管理端-评价审核** (6 个接口) - ---- - -## 管理端-评价审核 - -### `GET` /admin/review/list - -**评价列表(支持好中差评/有图/有视频筛选)** - -分页查询全部评价（含待审核/已通过/已拒绝），支持按评价等级、是否有图/视频、目标类型筛选 - -**关联字典**： -- review_status：评价审核状态（列表筛选+显示） -- rating_level：评价等级（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `hasImage` | `boolean` | | 是否有图片: true/false | | -| `hasVideo` | `boolean` | | 是否有视频: true/false | | -| `keyword` | `string` | | 搜索关键词 | 风景 | -| `maxRating` | `integer(int32)` | | 最高评分(整体满意度) | 5 | -| `minRating` | `integer(int32)` | | 最低评分(整体满意度) | 3 | -| `page` | `integer(int32)` | | 页码 | 1 | -| `pageSize` | `integer(int32)` | | 每页条数 | 20 | -| `productType` | `string` | | 产品类型（字典 review_product_type） | CORE | -| `ratingLevel` | `string` | | 评价等级: GOOD/MEDIUM/BAD | GOOD | -| `reviewType` | `string` | | 评论类型（字典 review_type） | PRODUCT | -| `status` | `string` | | 评价状态 | APPROVED | -| `targetId` | `integer(int64)` | | 评价目标ID | 2001 | -| `targetType` | `string` | | 评价目标类型 | PRODUCT | - -**响应** `统一响应结果«分页结果«评价列表项(管理端)»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«评价列表项(管理端)»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `评价列表项(管理端)[]` | | 数据列表 | -|     `auditedAt` | `string` | | 审核时间 | -|     `auditorName` | `string` | | 审核人姓名 | -|     `content` | `string` | | 评价内容 | -|     `createdAt` | `string` | | 创建时间 | -|     `hasReply` | `boolean` | | 是否已回复 | -|     `imageCount` | `int` | | 图片数量 | -|     `orderId` | `string` | | 订单ID | -|     `orderNo` | `string` | | 订单编号 | -|     `productType` | `string` | | 产品类型 | -|     `productTypeLabel` | `string` | | 产品类型标签 | -|     `ratingAccommodation` | `int` | | 住宿安排评分(1-5) | -|     `ratingDining` | `int` | | 餐饮质量评分(1-5) | -|     `ratingDriver` | `int` | | 司机服务评分(1-5) | -|     `ratingItinerary` | `int` | | 行程安排评分(1-5) | -|     `ratingLevel` | `string` | | 评价等级: GOOD/MEDIUM/BAD | -|     `ratingLevelLabel` | `string` | | 评价等级标签 | -|     `ratingOverall` | `int` | | 整体满意度评分(1-5) | -|     `rejectReason` | `string` | | 拒绝原因 | -|     `reviewId` | `string` | | 评价ID | -|     `reviewType` | `string` | | 评论类型 | -|     `reviewTypeLabel` | `string` | | 评论类型标签 | -|     `status` | `string` | | 评价状态 | -|     `statusLabel` | `string` | | 评价状态标签 | -|     `targetId` | `string` | | 评价目标ID | -|     `targetName` | `string` | | 评价目标名称 | -|     `targetType` | `string` | | 评价目标类型 | -|     `targetTypeLabel` | `string` | | 评价目标类型标签 | -|     `userAvatar` | `string` | | 用户头像 | -|     `userNickname` | `string` | | 用户昵称 | -|     `videoCount` | `int` | | 视频数量 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/review/{reviewId} - -**评价详情** - -**关联字典**： -- review_status：评价审核状态（显示） -- rating_level：评价等级（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reviewId` | `integer` | | 评价ID | - -**响应** `统一响应结果«评价详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `评价详情` | | 响应数据 | -|   `adminReply` | `string` | | 管理员回复内容 | -|   `adminReplyAt` | `string` | | 回复时间 | -|   `adminReplyName` | `string` | | 回复管理员姓名 | -|   `auditedAt` | `string` | | 审核时间 | -|   `auditorAdminId` | `string` | | 审核人ID | -|   `auditorName` | `string` | | 审核人姓名 | -|   `content` | `string` | | 评价内容 | -|   `createdAt` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期(冗余自订单) | -|   `hasImage` | `boolean` | | 是否有图片 | -|   `hasVideo` | `boolean` | | 是否有视频 | -|   `imageCount` | `int` | | 图片数量 | -|   `images` | `评价图片信息[]` | | 评价图片列表 | -|     `fileId` | `string` | | 文件ID | -|     `imageId` | `string` | | 图片ID | -|     `imageUrl` | `string` | | 图片URL | -|     `sortOrder` | `int` | | 排序序号 | -|   `machineResult` | `string` | | 机审结果 | -|   `orderId` | `string` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `productType` | `string` | | 产品类型 | -|   `productTypeLabel` | `string` | | 产品类型标签 | -|   `ratingAccommodation` | `int` | | 住宿安排评分(1-5) | -|   `ratingDining` | `int` | | 餐饮质量评分(1-5) | -|   `ratingDriver` | `int` | | 司机服务评分(1-5) | -|   `ratingItinerary` | `int` | | 行程安排评分(1-5) | -|   `ratingLevel` | `string` | | 评价等级: GOOD/MEDIUM/BAD | -|   `ratingLevelLabel` | `string` | | 评价等级标签: 好评/中评/差评 | -|   `ratingOverall` | `int` | | 整体满意度评分(1-5) | -|   `rejectReason` | `string` | | 拒绝原因 | -|   `reviewId` | `string` | | 评价ID | -|   `reviewType` | `string` | | 评论类型 | -|   `reviewTypeLabel` | `string` | | 评论类型标签 | -|   `status` | `string` | | 评价状态 | -|   `statusLabel` | `string` | | 评价状态标签 | -|   `targetId` | `string` | | 评价目标ID | -|   `targetName` | `string` | | 评价目标名称 | -|   `targetType` | `string` | | 评价目标类型 | -|   `targetTypeLabel` | `string` | | 评价目标类型标签 | -|   `userAvatar` | `string` | | 用户头像 | -|   `userId` | `string` | | 用户ID | -|   `userNickname` | `string` | | 用户昵称 | -|   `videoCount` | `int` | | 视频数量 | -|   `videos` | `评价视频信息[]` | | 评价视频列表 | -|     `coverUrl` | `string` | | 视频封面URL | -|     `duration` | `int` | | 视频时长(秒) | -|     `fileId` | `string` | | 文件ID | -|     `sortOrder` | `int` | | 排序序号 | -|     `videoId` | `string` | | 视频ID | -|     `videoUrl` | `string` | | 视频URL | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/review/{reviewId}/approve - -**通过评价** - -审核通过评价，通过后评价在小程序端公开展示。状态流转：PENDING_REVIEW → APPROVED - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reviewId` | `integer` | | 评价ID | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /admin/review/{reviewId}/override-approve - -**覆盖通过(机器拒绝的)** - -对阿里云内容审核自动拒绝的评价进行人工覆盖通过。状态流转：AUTO_REJECTED → APPROVED - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reviewId` | `integer` | | 评价ID | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /admin/review/{reviewId}/reject - -**拒绝评价** - -审核拒绝评价，需填写拒绝原因。拒绝后评价不公开展示。状态流转：PENDING_REVIEW → REJECTED - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reviewId` | `integer` | | 评价ID | - -**请求体** `拒绝评价请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `rejectReason` | `string` | 是 | 拒绝原因 | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /admin/review/{reviewId}/reply - -**回复评价(每条评价仅可回复一次)** - -管理员回复用户评价，回复内容在小程序端公开展示。每条评价仅允许回复一次，不可修改。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reviewId` | `integer` | | 评价ID | - -**请求体** `管理员回复请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `replyContent` | `string` | 是 | 回复内容 | - -**响应** `统一响应结果«Void»` - ---- diff --git a/2026-03/17_0958/hl-task-service.md b/2026-03/17_0958/hl-task-service.md deleted file mode 100644 index 0631450..0000000 --- a/2026-03/17_0958/hl-task-service.md +++ /dev/null @@ -1,924 +0,0 @@ -# 任务服务 API 文档 - -**服务**: `hl-task-service` -**接口总数**: 27 - -## 目录 - -- **WebSocket 实时推送** (1 个接口) -- **任务看板管理** (13 个接口) -- **任务管理** (13 个接口) - ---- - -## WebSocket 实时推送 - -### `GET` /admin/task/board/ws-doc/info - -**WebSocket 连接说明** - -## 连接信息 - -| 项目 | 值 | -|------|-------| -| **连接地址** | `ws://{host}:8092/ws/task` | -| **协议** | STOMP over WebSocket（SockJS 降级方案） | -| **跨域** | 允许所有源 (`*`) | - -## 订阅频道 - -| 订阅地址 | 说明 | -|------------|-------------| -| `/topic/board/{boardId}` | 订阅指定看板，接收该看板下的实时任务事件 | - -## 推送消息格式 - -```json -{ - "event": "TASK_CREATED", - "data": { ... }, - "timestamp": 1709539200000 -} -``` - -## 事件类型 - -| 事件 | 说明 | data 内容 | -|-------|------------|------| -| TASK_CREATED | 任务创建 | 任务对象 | -| TASK_UPDATED | 任务更新 | 任务对象 | -| TASK_DELETED | 任务删除 | 任务ID | -| TASK_MOVED | 任务移动（状态变更） | 任务对象 | -| COMMENT_ADDED | 新增评论 | 评论对象 | - -## 前端接入示例 (SockJS + STOMP) - -```javascript -import SockJS from 'sockjs-client' -import { Stomp } from '@stomp/stompjs' - -const socket = new SockJS('http://localhost:8092/ws/task') -const stompClient = Stomp.over(socket) - -stompClient.connect({}, () => { - stompClient.subscribe('/topic/board/123', (msg) => { - const { event, data, timestamp } = JSON.parse(msg.body) - console.log('Event:', event, 'Data:', data) - }) -}) -``` - -**响应** `object` - ---- - -## 任务看板管理 - -### `POST` /admin/task/board - -**创建自定义看板** - -创建自定义看板，自动添加创建者为看板成员，并创建默认状态列（待办、进行中、已完成）。 - -**权限**：需管理员登录。 - -**请求体** `创建看板请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardName` | `string` | 是 | 看板名称 | -| `deptId` | `long` | | 部门ID | -| `description` | `string` | | 看板描述 | -| `memberIds` | `long[]` | | 成员ID列表 | - -**响应** `统一响应结果«看板信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板信息` | | 响应数据 | -|   `boardId` | `long` | | 看板ID | -|   `boardName` | `string` | | 看板名称 | -|   `boardType` | `string` | | 看板类型 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `deptId` | `long` | | 部门ID | -|   `deptName` | `string` | | 部门名称 | -|   `description` | `string` | | 看板描述 | -|   `statuses` | `看板状态信息[]` | | 状态列表 | -|     `isPreset` | `boolean` | | 是否预设状态 | -|     `sortOrder` | `int` | | 排序序号 | -|     `statusColor` | `string` | | 状态颜色 | -|     `statusId` | `long` | | 状态ID | -|     `statusName` | `string` | | 状态名称 | -|     `taskCount` | `int` | | 该状态下的任务数量 | -|   `taskCount` | `int` | | 任务总数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/task/board/{boardId} - -**看板详情** - -返回看板基本信息（名称、描述、创建者），不含任务数据。查看任务请使用「获取看板任务」接口 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**响应** `统一响应结果«看板信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板信息` | | 响应数据 | -|   `boardId` | `long` | | 看板ID | -|   `boardName` | `string` | | 看板名称 | -|   `boardType` | `string` | | 看板类型 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `deptId` | `long` | | 部门ID | -|   `deptName` | `string` | | 部门名称 | -|   `description` | `string` | | 看板描述 | -|   `statuses` | `看板状态信息[]` | | 状态列表 | -|     `isPreset` | `boolean` | | 是否预设状态 | -|     `sortOrder` | `int` | | 排序序号 | -|     `statusColor` | `string` | | 状态颜色 | -|     `statusId` | `long` | | 状态ID | -|     `statusName` | `string` | | 状态名称 | -|     `taskCount` | `int` | | 该状态下的任务数量 | -|   `taskCount` | `int` | | 任务总数 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/task/board/{boardId} - -**更新看板** - -更新看板的名称和描述。仅看板创建者或超级管理员可操作。 - -**权限**：需管理员登录，且为看板创建者或超级管理员。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**请求体** `更新看板请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardName` | `string` | | 看板名称 | -| `description` | `string` | | 看板描述 | - -**响应** `统一响应结果«看板信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板信息` | | 响应数据 | -|   `boardId` | `long` | | 看板ID | -|   `boardName` | `string` | | 看板名称 | -|   `boardType` | `string` | | 看板类型 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `deptId` | `long` | | 部门ID | -|   `deptName` | `string` | | 部门名称 | -|   `description` | `string` | | 看板描述 | -|   `statuses` | `看板状态信息[]` | | 状态列表 | -|     `isPreset` | `boolean` | | 是否预设状态 | -|     `sortOrder` | `int` | | 排序序号 | -|     `statusColor` | `string` | | 状态颜色 | -|     `statusId` | `long` | | 状态ID | -|     `statusName` | `string` | | 状态名称 | -|     `taskCount` | `int` | | 该状态下的任务数量 | -|   `taskCount` | `int` | | 任务总数 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/task/board/{boardId} - -**删除看板** - -删除看板及其下所有状态列和任务（级联删除）。仅看板创建者或超级管理员可操作 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**响应** `统一响应结果«Void»` - ---- - -### `DELETE` /admin/task/board/{boardId}/member/{targetAdminId} - -**移除成员** - -从看板中移除指定成员。仅看板创建者或超级管理员可操作，不能移除创建者自己 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | -| `targetAdminId` | `integer` | | 目标管理员ID | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/task/board/{boardId}/members - -**获取看板成员** - -返回看板的所有成员列表，包含成员的管理员ID和姓名 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**响应** `统一响应结果«List«看板成员信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板成员信息[]` | | 响应数据 | -|   `adminId` | `long` | | 管理员ID | -|   `avatarUrl` | `string` | | 头像地址 | -|   `joinedAt` | `string` | | 加入时间 | -|   `role` | `string` | | 角色: OWNER/MEMBER | -|   `username` | `string` | | 用户名 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/task/board/{boardId}/members - -**添加成员** - -批量添加管理员为看板成员，成为成员后可以查看看板、创建和操作任务。 - -**权限**：需管理员登录，且为看板创建者或超级管理员。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**请求体** `添加成员请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `adminIds` | `long[]` | 是 | 管理员ID列表 | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /admin/task/board/{boardId}/status - -**创建状态列** - -在看板中创建新的状态列（如测试中、待发布等），自动排到末尾。任务通过拖拽在不同状态列间流转。 - -**权限**：需管理员登录且为看板成员。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**请求体** `创建状态请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `statusColor` | `string` | | 状态颜色 | -| `statusName` | `string` | 是 | 状态名称 | - -**响应** `统一响应结果«看板状态信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板状态信息` | | 响应数据 | -|   `isPreset` | `boolean` | | 是否预设状态 | -|   `sortOrder` | `int` | | 排序序号 | -|   `statusColor` | `string` | | 状态颜色 | -|   `statusId` | `long` | | 状态ID | -|   `statusName` | `string` | | 状态名称 | -|   `taskCount` | `int` | | 该状态下的任务数量 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/task/board/{boardId}/status/sort - -**状态列排序** - -批量更新状态列的排序顺序。传入状态列ID数组，数组下标即为新的排序值。操作完成后通过WebSocket推送STATUS_REORDERED事件 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**请求体** `状态排序请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `statusIds` | `long[]` | 是 | 状态ID列表(按排序顺序) | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/task/board/{boardId}/statuses - -**获取看板状态列** - -返回看板的所有状态列（如待办、进行中、已完成），按排序字段升序排列。拖拽任务到不同状态列实现状态流转 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**响应** `统一响应结果«List«看板状态信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板状态信息[]` | | 响应数据 | -|   `isPreset` | `boolean` | | 是否预设状态 | -|   `sortOrder` | `int` | | 排序序号 | -|   `statusColor` | `string` | | 状态颜色 | -|   `statusId` | `long` | | 状态ID | -|   `statusName` | `string` | | 状态名称 | -|   `taskCount` | `int` | | 该状态下的任务数量 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/task/boards - -**获取可见看板列表** - -返回当前管理员可见的看板列表：超级管理员可见所有看板，普通管理员仅可见自己创建的或作为成员的看板 - -**响应** `统一响应结果«List«看板信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板信息[]` | | 响应数据 | -|   `boardId` | `long` | | 看板ID | -|   `boardName` | `string` | | 看板名称 | -|   `boardType` | `string` | | 看板类型 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `deptId` | `long` | | 部门ID | -|   `deptName` | `string` | | 部门名称 | -|   `description` | `string` | | 看板描述 | -|   `statuses` | `看板状态信息[]` | | 状态列表 | -|     `isPreset` | `boolean` | | 是否预设状态 | -|     `sortOrder` | `int` | | 排序序号 | -|     `statusColor` | `string` | | 状态颜色 | -|     `statusId` | `long` | | 状态ID | -|     `statusName` | `string` | | 状态名称 | -|     `taskCount` | `int` | | 该状态下的任务数量 | -|   `taskCount` | `int` | | 任务总数 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/task/status/{statusId} - -**更新状态列** - -更新状态列的名称和颜色。 - -**权限**：需管理员登录且为看板成员。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `statusId` | `integer` | | 状态列ID | - -**请求体** `更新状态请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `statusColor` | `string` | | 状态颜色 | -| `statusName` | `string` | | 状态名称 | - -**响应** `统一响应结果«看板状态信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板状态信息` | | 响应数据 | -|   `isPreset` | `boolean` | | 是否预设状态 | -|   `sortOrder` | `int` | | 排序序号 | -|   `statusColor` | `string` | | 状态颜色 | -|   `statusId` | `long` | | 状态ID | -|   `statusName` | `string` | | 状态名称 | -|   `taskCount` | `int` | | 该状态下的任务数量 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/task/status/{statusId} - -**删除状态列** - -删除看板的状态列。如果状态列下有任务则不允许删除，需先移动或删除任务 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `statusId` | `integer` | | 状态列ID | - -**响应** `统一响应结果«Void»` - ---- - -## 任务管理 - -### `POST` /admin/task - -**创建任务** - -在指定看板和状态列下创建任务。创建成功后通过WebSocket推送TASK_CREATED事件，并通知被分配的负责人 - -**关联字典**： -- task_priority：任务优先级（创建时选择） - -**请求体** `创建任务请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `assigneeIds` | `long[]` | | 负责人ID列表 | -| `boardId` | `long` | 是 | 看板ID | -| `description` | `string` | | 任务描述 | -| `dueDate` | `string` | | 截止日期 | -| `priority` | `string` | | 优先级: LOW/MEDIUM/HIGH/URGENT | -| `statusId` | `long` | | 状态ID | -| `title` | `string` | 是 | 任务标题 | - -**响应** `统一响应结果«任务信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `任务信息` | | 响应数据 | -|   `assignees` | `负责人信息[]` | | 负责人列表 | -|     `adminId` | `long` | | 管理员ID | -|     `avatarUrl` | `string` | | 头像地址 | -|     `username` | `string` | | 用户名 | -|     `wechatName` | `string` | | 企微昵称 | -|   `boardId` | `long` | | 看板ID | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 任务描述 | -|   `dueDate` | `string` | | 截止日期 | -|   `overdue` | `boolean` | | 是否逾期 | -|   `parentId` | `long` | | 父任务ID | -|   `priority` | `string` | | 优先级: LOW/MEDIUM/HIGH/URGENT | -|   `sortOrder` | `int` | | 排序序号 | -|   `statusColor` | `string` | | 状态颜色 | -|   `statusId` | `long` | | 状态ID | -|   `statusName` | `string` | | 状态名称 | -|   `subtaskCompleted` | `int` | | 已完成子任务数 | -|   `subtaskTotal` | `int` | | 子任务总数 | -|   `subtasks` | `子任务信息[]` | | 子任务列表 | -|     `completed` | `boolean` | | 是否已完成 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdBy` | `long` | | 创建人ID | -|     `creatorName` | `string` | | 创建人姓名 | -|     `taskId` | `long` | | 子任务ID | -|     `title` | `string` | | 子任务标题 | -|   `taskId` | `long` | | 任务ID | -|   `title` | `string` | | 任务标题 | -|   `updatedAt` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/task/board/{boardId}/tasks - -**获取看板任务(按状态分组)** - -返回看板下所有任务，按状态列分组。支持按优先级(HIGH/MEDIUM/LOW)和负责人筛选，每组内按排序值升序排列 - -**关联字典**： -- task_priority：任务优先级（列表筛选+显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `assigneeId` | `integer(int64)` | | 负责人ID | | -| `priority` | `string` | | 优先级 | | - -**响应** `统一响应结果«List«看板任务分组信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板任务分组信息[]` | | 响应数据 | -|   `sortOrder` | `int` | | 排序序号 | -|   `statusColor` | `string` | | 状态颜色 | -|   `statusId` | `long` | | 状态ID | -|   `statusName` | `string` | | 状态名称 | -|   `tasks` | `任务信息[]` | | 该状态下的任务列表 | -|     `assignees` | `负责人信息[]` | | 负责人列表 | -|     `boardId` | `long` | | 看板ID | -|     `createdAt` | `string` | | 创建时间 | -|     `createdBy` | `long` | | 创建人ID | -|     `creatorName` | `string` | | 创建人姓名 | -|     `description` | `string` | | 任务描述 | -|     `dueDate` | `string` | | 截止日期 | -|     `overdue` | `boolean` | | 是否逾期 | -|     `parentId` | `long` | | 父任务ID | -|     `priority` | `string` | | 优先级: LOW/MEDIUM/HIGH/URGENT | -|     `sortOrder` | `int` | | 排序序号 | -|     `statusColor` | `string` | | 状态颜色 | -|     `statusId` | `long` | | 状态ID | -|     `statusName` | `string` | | 状态名称 | -|     `subtaskCompleted` | `int` | | 已完成子任务数 | -|     `subtaskTotal` | `int` | | 子任务总数 | -|     `subtasks` | `子任务信息[]` | | 子任务列表 | -|     `taskId` | `long` | | 任务ID | -|     `title` | `string` | | 任务标题 | -|     `updatedAt` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/task/comment/{commentId} - -**删除评论** - -仅评论作者本人可删除自己的评论，系统自动生成的活动记录不可删除 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `commentId` | `integer` | | 评论ID | - -**响应** `统一响应结果«Void»` - ---- - -### `DELETE` /admin/task/subtask/{subtaskId} - -**删除子任务** - -删除指定子任务。 - -**权限**：需管理员登录且为看板成员。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `subtaskId` | `integer` | | 子任务ID | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/task/subtask/{subtaskId}/toggle - -**切换子任务完成状态** - -切换子任务的完成/未完成状态（toggle），完成状态切换会自动记录到任务时间线 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `subtaskId` | `integer` | | 子任务ID | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/task/{taskId} - -**任务详情** - -返回任务完整信息，包含子任务列表、负责人信息、附件列表等 - -**关联字典**： -- task_priority：任务优先级（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**响应** `统一响应结果«任务信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `任务信息` | | 响应数据 | -|   `assignees` | `负责人信息[]` | | 负责人列表 | -|     `adminId` | `long` | | 管理员ID | -|     `avatarUrl` | `string` | | 头像地址 | -|     `username` | `string` | | 用户名 | -|     `wechatName` | `string` | | 企微昵称 | -|   `boardId` | `long` | | 看板ID | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 任务描述 | -|   `dueDate` | `string` | | 截止日期 | -|   `overdue` | `boolean` | | 是否逾期 | -|   `parentId` | `long` | | 父任务ID | -|   `priority` | `string` | | 优先级: LOW/MEDIUM/HIGH/URGENT | -|   `sortOrder` | `int` | | 排序序号 | -|   `statusColor` | `string` | | 状态颜色 | -|   `statusId` | `long` | | 状态ID | -|   `statusName` | `string` | | 状态名称 | -|   `subtaskCompleted` | `int` | | 已完成子任务数 | -|   `subtaskTotal` | `int` | | 子任务总数 | -|   `subtasks` | `子任务信息[]` | | 子任务列表 | -|     `completed` | `boolean` | | 是否已完成 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdBy` | `long` | | 创建人ID | -|     `creatorName` | `string` | | 创建人姓名 | -|     `taskId` | `long` | | 子任务ID | -|     `title` | `string` | | 子任务标题 | -|   `taskId` | `long` | | 任务ID | -|   `title` | `string` | | 任务标题 | -|   `updatedAt` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/task/{taskId} - -**更新任务** - -更新任务的标题、描述、优先级、截止日期、负责人等信息。更新后通过WebSocket推送TASK_UPDATED事件，如果修改了负责人则额外通知新负责人。 - -**权限**：需管理员登录且为看板成员。 - -**关联字典**： -- task_priority：任务优先级（编辑时选择） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**请求体** `更新任务请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `assigneeIds` | `long[]` | | 负责人ID列表 | -| `description` | `string` | | 任务描述 | -| `dueDate` | `string` | | 截止日期 | -| `priority` | `string` | | 优先级: LOW/MEDIUM/HIGH/URGENT | -| `title` | `string` | | 任务标题 | - -**响应** `统一响应结果«任务信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `任务信息` | | 响应数据 | -|   `assignees` | `负责人信息[]` | | 负责人列表 | -|     `adminId` | `long` | | 管理员ID | -|     `avatarUrl` | `string` | | 头像地址 | -|     `username` | `string` | | 用户名 | -|     `wechatName` | `string` | | 企微昵称 | -|   `boardId` | `long` | | 看板ID | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 任务描述 | -|   `dueDate` | `string` | | 截止日期 | -|   `overdue` | `boolean` | | 是否逾期 | -|   `parentId` | `long` | | 父任务ID | -|   `priority` | `string` | | 优先级: LOW/MEDIUM/HIGH/URGENT | -|   `sortOrder` | `int` | | 排序序号 | -|   `statusColor` | `string` | | 状态颜色 | -|   `statusId` | `long` | | 状态ID | -|   `statusName` | `string` | | 状态名称 | -|   `subtaskCompleted` | `int` | | 已完成子任务数 | -|   `subtaskTotal` | `int` | | 子任务总数 | -|   `subtasks` | `子任务信息[]` | | 子任务列表 | -|     `completed` | `boolean` | | 是否已完成 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdBy` | `long` | | 创建人ID | -|     `creatorName` | `string` | | 创建人姓名 | -|     `taskId` | `long` | | 子任务ID | -|     `title` | `string` | | 子任务标题 | -|   `taskId` | `long` | | 任务ID | -|   `title` | `string` | | 任务标题 | -|   `updatedAt` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/task/{taskId} - -**删除任务** - -删除任务及其所有子任务、评论和时间线记录（级联删除）。删除后通过WebSocket推送TASK_DELETED事件。 - -**权限**：需管理员登录且为看板成员。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /admin/task/{taskId}/comment - -**添加评论** - -在任务时间线中添加评论，添加后自动通知任务负责人 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**请求体** `创建评论请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `content` | `string` | 是 | 评论内容 | - -**响应** `统一响应结果«时间线条目»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `时间线条目` | | 响应数据 | -|   `action` | `string` | | 操作类型 | -|   `adminAvatar` | `string` | | 管理员头像 | -|   `adminId` | `long` | | 管理员ID | -|   `adminName` | `string` | | 管理员姓名 | -|   `content` | `string` | | 内容 | -|   `createdAt` | `string` | | 创建时间 | -|   `id` | `long` | | 条目ID | -|   `newValue` | `string` | | 新值 | -|   `oldValue` | `string` | | 旧值 | -|   `type` | `string` | | 类型: COMMENT/ACTIVITY | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/task/{taskId}/sort - -**任务排序** - -更新任务在同一状态列内的排序位置，用于拖拽排序 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**请求体** `任务排序请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `statusId` | `long` | 是 | 状态ID | -| `taskIds` | `long[]` | 是 | 任务ID列表(按排序顺序) | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/task/{taskId}/status - -**变更任务状态** - -将任务移动到指定状态列（拖拽操作），自动记录状态变更到时间线，并通过WebSocket推送TASK_STATUS_CHANGED事件 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**请求体** `变更任务状态请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `statusId` | `long` | 是 | 目标状态ID | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /admin/task/{taskId}/subtask - -**创建子任务** - -在指定任务下创建子任务（待办项），用于拆分任务的执行步骤。子任务默认为未完成状态。 - -**权限**：需管理员登录且为看板成员。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**请求体** `创建子任务请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `title` | `string` | 是 | 子任务标题 | - -**响应** `统一响应结果«子任务信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `子任务信息` | | 响应数据 | -|   `completed` | `boolean` | | 是否已完成 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `taskId` | `long` | | 子任务ID | -|   `title` | `string` | | 子任务标题 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/task/{taskId}/timeline - -**获取任务时间线** - -返回任务的完整操作记录，包含评论和系统自动记录的状态变更、人员分配等活动，按时间正序排列 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**响应** `统一响应结果«List«时间线条目»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `时间线条目[]` | | 响应数据 | -|   `action` | `string` | | 操作类型 | -|   `adminAvatar` | `string` | | 管理员头像 | -|   `adminId` | `long` | | 管理员ID | -|   `adminName` | `string` | | 管理员姓名 | -|   `content` | `string` | | 内容 | -|   `createdAt` | `string` | | 创建时间 | -|   `id` | `long` | | 条目ID | -|   `newValue` | `string` | | 新值 | -|   `oldValue` | `string` | | 旧值 | -|   `type` | `string` | | 类型: COMMENT/ACTIVITY | -| `message` | `string` | | 响应消息 | - ---- diff --git a/2026-03/17_0958/hl-user-service.md b/2026-03/17_0958/hl-user-service.md deleted file mode 100644 index 23139d4..0000000 --- a/2026-03/17_0958/hl-user-service.md +++ /dev/null @@ -1,4502 +0,0 @@ -# 用户服务 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 - -**管理员列表** - -分页查询管理员列表，支持按角色、状态、企微绑定状态、关键词筛选。keyword支持模糊匹配用户名和企业微信名称。status取值：ACTIVE=正常 LOCKED=已锁定 DISABLED=已禁用。wechatBound：true=已绑定企业微信 false=未绑定。需要管理员认证。 - -**关联字典**： -- admin_status（管理员状态）：ACTIVE=启用, LOCKED=锁定, DISABLED=禁用（筛选条件+列表展示） - - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `keyword` | `string` | | 关键词（模糊匹配用户名/企业微信名称） | | -| `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/2026-03/17_1009/CHANGES.md b/2026-03/17_1009/CHANGES.md deleted file mode 100644 index 49822e9..0000000 --- a/2026-03/17_1009/CHANGES.md +++ /dev/null @@ -1,5 +0,0 @@ -# API 变更通知 - -**更新时间**: 2026-03-17 10:09 - -> 无变更 \ No newline at end of file diff --git a/2026-03/17_1009/dict-reference.md b/2026-03/17_1009/dict-reference.md deleted file mode 100644 index e62472b..0000000 --- a/2026-03/17_1009/dict-reference.md +++ /dev/null @@ -1,2204 +0,0 @@ -# 数据字典参考 - -**更新时间**: 2026-03-17 10:09 -**字典总数**: 115 - -## 目录 - -- [游玩项目计费方式（`activity_billing_type`）](#activity_billing_type) — 4 项 -- [游玩项目分类（`activity_category`）](#activity_category) — 22 项 -- [游玩项目环境类型（`activity_environment_type`）](#activity_environment_type) — 3 项 -- [游玩项目体力等级（`activity_physical_level`）](#activity_physical_level) — 4 项 -- [管理员状态（`admin_status`）](#admin_status) — 4 项 -- [适用角色（`apply_role`）](#apply_role) — 0 项 -- [审批状态（`approval_sp_status`）](#approval_sp_status) — 7 项 -- [Banner链接类型（`banner_link_type`）](#banner_link_type) — 5 项 -- [Banner媒体类型（`banner_media_type`）](#banner_media_type) — 2 项 -- [团期状态（`batch_status`）](#batch_status) — 8 项 -- [卫浴类型（`bathroom_type`）](#bathroom_type) — 2 项 -- [床型（`bed_type`）](#bed_type) — 6 项 -- [计费方式（`billing_type`）](#billing_type) — 2 项 -- [服务计费方式（`billing_type_service`）](#billing_type_service) — 6 项 -- [日历状态（`calendar_status`）](#calendar_status) — 3 项 -- [城市（`cities`）](#cities) — 15 项 -- [城市筛选（`city`）](#city) — 8 项 -- [通用状态（`common_status`）](#common_status) — 2 项 -- [联系我们渠道类型（`contact_channel_type`）](#contact_channel_type) — 3 项 -- [合同模式（`contract_mode`）](#contract_mode) — 2 项 -- [合同平台（`contract_platform`）](#contract_platform) — 2 项 -- [合同状态（`contract_status`）](#contract_status) — 8 项 -- [费用适用角色（`cost_apply_role`）](#cost_apply_role) — 6 项 -- [成本分类（`cost_category`）](#cost_category) — 15 项 -- [费用项分类（`cost_item_category`）](#cost_item_category) — 9 项 -- [费用计价单位（`cost_unit`）](#cost_unit) — 7 项 -- [菜系类型（`cuisine_type`）](#cuisine_type) — 10 项 -- [部门状态（`dept_status`）](#dept_status) — 2 项 -- [字典分类（`dict_category`）](#dict_category) — 2 项 -- [证件类型（`document_type`）](#document_type) — 6 项 -- [驱动方式（`drive_type`）](#drive_type) — 0 项 -- [驾照类型（`driver_license_type`）](#driver_license_type) — 7 项 -- [动力类型（`engine_type`）](#engine_type) — 4 项 -- [环境类型（`environment_type`）](#environment_type) — 3 项 -- [民族（`ethnicity`）](#ethnicity) — 56 项 -- [收藏资源类型（`favorite_resource_type`）](#favorite_resource_type) — 5 项 -- [文件分组（`file_group`）](#file_group) — 12 项 -- [文件状态（`file_status`）](#file_status) — 3 项 -- [文件类型（`file_type`）](#file_type) — 5 项 -- [浏览历史资源类型（`footprint_resource_type`）](#footprint_resource_type) — 5 项 -- [前端配置分组（`frontend_config_group`）](#frontend_config_group) — 6 项 -- [性别（`gender`）](#gender) — 2 项 -- [导游等级（`guide_level`）](#guide_level) — 4 项 -- [导游服务区域（`guide_service_area`）](#guide_service_area) — 9 项 -- [导游专长（`guide_specialty`）](#guide_specialty) — 7 项 -- [酒店配套设施（`hotel_facility`）](#hotel_facility) — 20 项 -- [酒店星级（`hotel_star_level`）](#hotel_star_level) — 6 项 -- [住宿类型（`hotel_type`）](#hotel_type) — 5 项 -- [证件类型（`id_card_type`）](#id_card_type) — 6 项 -- [保险状态（`insurance_status`）](#insurance_status) — 4 项 -- [任务分组（`job_group`）](#job_group) — 4 项 -- [任务日志状态（`job_log_status`）](#job_log_status) — 2 项 -- [任务补偿策略（`job_misfire_policy`）](#job_misfire_policy) — 3 项 -- [任务状态（`job_status`）](#job_status) — 2 项 -- [语言能力（`language`）](#language) — 8 项 -- [登录状态（`login_status`）](#login_status) — 3 项 -- [素材分类（`material_category`）](#material_category) — 15 项 -- [素材审核状态（`material_review_status`）](#material_review_status) — 2 项 -- [素材标签（`material_tag`）](#material_tag) — 10 项 -- [餐饮类型（`meal_type`）](#meal_type) — 4 项 -- [菜单类型（`menu_type`）](#menu_type) — 3 项 -- [通知渠道（`notification_channel`）](#notification_channel) — 5 项 -- [通知事件分类（`notification_event_category`）](#notification_event_category) — 7 项 -- [通知发送状态（`notification_send_status`）](#notification_send_status) — 4 项 -- [通知类型（`notification_type`）](#notification_type) — 2 项 -- [在线状态（`online_status`）](#online_status) — 2 项 -- [订单变更原因（`order_change_reason`）](#order_change_reason) — 7 项 -- [订单显示状态(C端)（`order_display_status`）](#order_display_status) — 5 项 -- [订单内部流程状态（`order_process_status`）](#order_process_status) — 8 项 -- [订单状态（`order_status`）](#order_status) — 12 项 -- [订单操作类型（`order_timeline_action`）](#order_timeline_action) — 26 项 -- [订单待办类型（`order_todo_type`）](#order_todo_type) — 7 项 -- [支付模式（`payment_mode`）](#payment_mode) — 2 项 -- [产品分类（`product_category`）](#product_category) — 5 项 -- [行程节点类型（`product_node_type`）](#product_node_type) — 10 项 -- [产品状态（`product_status`）](#product_status) — 7 项 -- [产品类型（`product_type`）](#product_type) — 4 项 -- [推送任务状态（`push_task_status`）](#push_task_status) — 4 项 -- [评价等级（`rating_level`）](#rating_level) — 3 项 -- [退款原因（`refund_reason`）](#refund_reason) — 11 项 -- [退款原因分类（`refund_reason_category`）](#refund_reason_category) — 3 项 -- [退款状态（`refund_status`）](#refund_status) — 8 项 -- [退款类型（`refund_type`）](#refund_type) — 3 项 -- [餐厅分类（`restaurant_category`）](#restaurant_category) — 8 项 -- [餐厅设施（`restaurant_facility`）](#restaurant_facility) — 10 项 -- [评分类别（`review_rating_category`）](#review_rating_category) — 6 项 -- [评价审核状态（`review_status`）](#review_status) — 6 项 -- [评价目标类型（`review_target_type`）](#review_target_type) — 5 项 -- [房型分类（`room_category`）](#room_category) — 11 项 -- [房型设施（`room_facility`）](#room_facility) — 44 项 -- [景区设施（`scenic_facility`）](#scenic_facility) — 12 项 -- [景区荣誉称号（`scenic_honor`）](#scenic_honor) — 10 项 -- [季节（`season`）](#season) — 4 项 -- [服务项计费方式（`service_billing_type`）](#service_billing_type) — 6 项 -- [服务分类（`service_category`）](#service_category) — 9 项 -- [服务计价单位（`service_unit`）](#service_unit) — 5 项 -- [结算状态（`settle_status`）](#settle_status) — 4 项 -- [团期人员角色（`staff_role`）](#staff_role) — 4 项 -- [人员类型（`staff_type`）](#staff_type) — 5 项 -- [备品分类（`supplies_category`）](#supplies_category) — 8 项 -- [是否（`sys_yes_no`）](#sys_yes_no) — 2 项 -- [任务优先级（`task_priority`）](#task_priority) — 4 项 -- [变速箱（`transmission`）](#transmission) — 0 项 -- [出行人类型（`traveler_type`）](#traveler_type) — 4 项 -- [出行人年龄规则（`traveler_type_age_rule`）](#traveler_type_age_rule) — 4 项 -- [行程状态（`trip_status`）](#trip_status) — 3 项 -- [行程类型（`trip_type`）](#trip_type) — 4 项 -- [用户状态（`user_status`）](#user_status) — 4 项 -- [车型（`vehicle_type`）](#vehicle_type) — 5 项 -- [百科分类（`wiki_category`）](#wiki_category) — 7 项 -- [文章状态（`wiki_status`）](#wiki_status) — 3 项 -- [窗户类型（`window_type`）](#window_type) — 3 项 -- [工单优先级（`work_order_priority`）](#work_order_priority) — 4 项 -- [工单状态（`work_order_status`）](#work_order_status) — 4 项 -- [工单类型（`work_order_type`）](#work_order_type) — 5 项 - ---- - -## 游玩项目计费方式（`activity_billing_type`） {#activity_billing_type} - -> 游玩项目计费方式字典 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PER_PERSON` | 按人 | ACTIVE | -| `PER_GROUP` | 按组/场 | ACTIVE | -| `PER_HOUR` | 按小时 | ACTIVE | -| `PER_SESSION` | 按场次 | ACTIVE | - ---- - -## 游玩项目分类（`activity_category`） {#activity_category} - -> 游玩项目分类字典 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `horse_riding` | 马术骑行 | ACTIVE | -| `motor_sport` | 机动越野 | ACTIVE | -| `water_sport` | 水上项目 | ACTIVE | -| `archery_combat` | 射箭搏击 | ACTIVE | -| `cultural_experience` | 民俗文化 | ACTIVE | -| `food_craft` | 美食手作 | ACTIVE | -| `nature_explore` | 自然探索 | ACTIVE | -| `campfire_party` | 篝火聚会 | ACTIVE | -| `winter_sport` | 冬季项目 | ACTIVE | -| `parent_child` | 亲子互动 | ACTIVE | -| `OUTDOOR` | 户外运动 | ACTIVE | -| `OUTDOOR_SPORT` | 户外竞技 | ACTIVE | -| `ENTERTAINMENT` | 休闲娱乐 | ACTIVE | -| `ANIMAL` | 动物互动 | ACTIVE | -| `EXTREME` | 极限运动 | ACTIVE | -| `CULTURAL` | 文化体验 | ACTIVE | -| `EDUCATION` | 研学教育 | ACTIVE | -| `PHOTOGRAPHY` | 摄影写真 | ACTIVE | -| `PERFORMANCE` | 演出表演 | ACTIVE | -| `HORSEBACK` | 骑马体验 | ACTIVE | -| `CATERING` | 餐饮服务 | ACTIVE | -| `DINING` | 用餐体验 | ACTIVE | - ---- - -## 游玩项目环境类型（`activity_environment_type`） {#activity_environment_type} - -> 游玩项目环境类型字典 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `INDOOR` | 室内 | ACTIVE | -| `OUTDOOR` | 户外 | ACTIVE | -| `MIXED` | 混合 | ACTIVE | - ---- - -## 游玩项目体力等级（`activity_physical_level`） {#activity_physical_level} - -> 游玩项目体力等级字典 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `EASY` | 休闲 | ACTIVE | -| `MODERATE` | 适中 | ACTIVE | -| `HARD` | 较强 | ACTIVE | -| `EXTREME` | 高强度 | ACTIVE | - ---- - -## 管理员状态（`admin_status`） {#admin_status} - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `ACTIVE` | 正常 | ACTIVE | -| `INACTIVE` | 禁用 | ACTIVE | -| `LOCKED` | 锁定 | ACTIVE | -| `DELETED` | 已删除 | ACTIVE | - -**使用该字典的接口**: - -- `GET /admin/user` — 管理员列表（用户服务） -- `POST /admin/user` — 创建管理员（用户服务） -- `GET /admin/user/{adminId}` — 获取管理员详情（用户服务） -- `PUT /admin/user/{adminId}` — 更新管理员（用户服务） - ---- - -## 适用角色（`apply_role`） {#apply_role} - -**分类**: BUSINESS - -> 暂无字典项 - ---- - -## 审批状态（`approval_sp_status`） {#approval_sp_status} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `1` | 审批中 | ACTIVE | -| `2` | 已通过 | ACTIVE | -| `3` | 已驳回 | ACTIVE | -| `4` | 已撤销 | ACTIVE | -| `6` | 通过后撤销 | ACTIVE | -| `7` | 已删除 | ACTIVE | -| `10` | 已支付 | ACTIVE | - ---- - -## Banner链接类型（`banner_link_type`） {#banner_link_type} - -> 首页Banner点击跳转的链接类型 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PRODUCT` | 产品详情 | ACTIVE | -| `ARTICLE` | 文章详情 | ACTIVE | -| `URL` | 外部链接 | ACTIVE | -| `MINI_PAGE` | 小程序页面 | ACTIVE | -| `NONE` | 无跳转 | ACTIVE | - ---- - -## Banner媒体类型（`banner_media_type`） {#banner_media_type} - -> 首页Banner支持的媒体类型 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `IMAGE` | 图片 | ACTIVE | -| `VIDEO` | 视频 | ACTIVE | - ---- - -## 团期状态（`batch_status`） {#batch_status} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PENDING` | 待开放 | ACTIVE | -| `ENROLLING` | 报名中 | ACTIVE | -| `CONFIRMED` | 已成团 | ACTIVE | -| `FULL` | 已满员 | ACTIVE | -| `CLOSED` | 已截止 | ACTIVE | -| `DISBANDED` | 已散团 | ACTIVE | -| `IN_PROGRESS` | 出行中 | ACTIVE | -| `FINISHED` | 已结束 | ACTIVE | - -**使用该字典的接口**: - -- `POST /admin/product/item/{productId}/batch` — 创建主批次（产品服务） -- `GET /admin/product/item/{productId}/batch/list` — 批次列表(树形)（产品服务） -- `GET /admin/product/item/{productId}/batch/{batchId}` — 批次详情（产品服务） - ---- - -## 卫浴类型（`bathroom_type`） {#bathroom_type} - -> Bathroom types - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PRIVATE` | 独立卫浴 | ACTIVE | -| `SHARED` | 公共卫浴 | ACTIVE | - ---- - -## 床型（`bed_type`） {#bed_type} - -> Bed types - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `SINGLE_BED` | 单人床 | ACTIVE | -| `DOUBLE_BED` | 双人床 | ACTIVE | -| `TWIN_BED` | 双床 | ACTIVE | -| `KING_BED` | 大床 | ACTIVE | -| `TATAMI` | 榻榻米 | ACTIVE | -| `KANG` | 火炕 | ACTIVE | - ---- - -## 计费方式（`billing_type`） {#billing_type} - -> 备品计费方式 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `BY_PERSON` | 按人头 | ACTIVE | -| `BY_COUNT` | 按件 | ACTIVE | - ---- - -## 服务计费方式（`billing_type_service`） {#billing_type_service} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `FLAT_RATE` | 一口价 | ACTIVE | -| `PER_PERSON` | 按人头 | ACTIVE | -| `PER_HOUR` | 按小时 | ACTIVE | -| `PER_DAY` | 按天 | ACTIVE | -| `PER_DISTANCE` | 按距离 | ACTIVE | -| `CUSTOM` | 自定义 | ACTIVE | - ---- - -## 日历状态（`calendar_status`） {#calendar_status} - -> 价格日历中每日的状态 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `AVAILABLE` | 可售 | ACTIVE | -| `SOLD_OUT` | 已售罄 | ACTIVE | -| `CLOSED` | 已关闭 | ACTIVE | - ---- - -## 城市（`cities`） {#cities} - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `hailar` | 海拉尔 | ACTIVE | -| `manzhouli` | 满洲里 | ACTIVE | -| `eergu` | 额尔古纳 | ACTIVE | -| `genhe` | 根河 | ACTIVE | -| `yakeshi` | 牙克石 | ACTIVE | -| `zhalantun` | 扎兰屯 | ACTIVE | -| `aershan` | 阿尔山 | ACTIVE | -| `shiwei` | 室韦 | ACTIVE | -| `enhe` | 恩和 | ACTIVE | -| `heishantou` | 黑山头 | ACTIVE | -| `chenbaerhu` | 陈巴尔虎旗 | ACTIVE | -| `xinbaerhuzuo` | 新巴尔虎左旗 | ACTIVE | -| `xinbaerhuyou` | 新巴尔虎右旗 | ACTIVE | -| `ewenke` | 鄂温克旗 | ACTIVE | -| `moerdaoga` | 莫尔道嘎 | ACTIVE | - -**使用该字典的接口**: - -- `GET /admin/product/district/search` — 搜索行政区划（城市/区县）（产品服务） -- `GET /admin/product/item/{productId}/day/{dayNumber}/nodes` — 获取某天的节点列表（产品服务） -- `PUT /admin/product/node/{nodeId}` — 更新行程节点（产品服务） - ---- - -## 城市筛选（`city`） {#city} - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `hailar` | 海拉尔 | ACTIVE | -| `manzhouli` | 满洲里 | ACTIVE | -| `eergu` | 额尔古纳 | ACTIVE | -| `genhe` | 根河 | ACTIVE | -| `aershan` | 阿尔山 | ACTIVE | -| `shiwei` | 室韦 | ACTIVE | -| `enhe` | 恩和 | ACTIVE | -| `heishantou` | 黑山头 | ACTIVE | - -**使用该字典的接口**: - -- `GET /admin/product/district/search` — 搜索行政区划（城市/区县）（产品服务） -- `POST /admin/product/item/{productId}/day/{dayNumber}/node` — 添加行程节点（产品服务） -- `GET /admin/product/item/{productId}/day/{dayNumber}/nodes` — 获取某天的节点列表（产品服务） -- `PUT /admin/product/node/{nodeId}` — 更新行程节点（产品服务） - ---- - -## 通用状态（`common_status`） {#common_status} - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `ACTIVE` | 启用 | ACTIVE | -| `INACTIVE` | 停用 | ACTIVE | - -**使用该字典的接口**: - -- `GET /admin/banner` — Banner列表（用户服务） -- `GET /admin/banner/{id}` — Banner详情（用户服务） -- `GET /admin/contact` — 联系方式列表（用户服务） -- `GET /admin/contact/{id}` — 联系方式详情（用户服务） -- `GET /admin/explore/category` — 探索分类列表（用户服务） -- `GET /admin/explore/category/{id}` — 探索分类详情（用户服务） -- `GET /admin/frontend-config` — 配置列表（用户服务） -- `GET /admin/agreement` — 协议列表（用户服务） -- `GET /admin/agreement/{id}` — 协议详情（用户服务） -- `GET /admin/role` — 分页查询角色（用户服务） -- `PUT /admin/role/{roleId}` — 更新角色（用户服务） -- `POST /admin/menu` — 创建菜单（用户服务） -- `GET /admin/menu/tree` — 获取完整菜单树（用户服务） -- `GET /admin/menu/{menuId}` — 获取菜单详情（用户服务） -- `PUT /admin/menu/{menuId}` — 更新菜单（用户服务） - ---- - -## 联系我们渠道类型（`contact_channel_type`） {#contact_channel_type} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `ABOUT` | 关于我们 | ACTIVE | -| `ONLINE_CS` | 在线客服 | ACTIVE | -| `PHONE` | 电话咨询 | ACTIVE | - -**使用该字典的接口**: - -- `GET /admin/contact` — 联系方式列表（用户服务） -- `POST /admin/contact` — 创建联系方式（用户服务） -- `GET /admin/contact/{id}` — 联系方式详情（用户服务） -- `PUT /admin/contact/{id}` — 更新联系方式（用户服务） - ---- - -## 合同模式（`contract_mode`） {#contract_mode} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `STANDARD` | 电子签署 | ACTIVE | -| `SYNC` | 纸质上报 | ACTIVE | - ---- - -## 合同平台（`contract_platform`） {#contract_platform} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `12301` | 12301 | ACTIVE | -| `FADADA` | 法大大 | ACTIVE | - ---- - -## 合同状态（`contract_status`） {#contract_status} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PENDING` | 待生成 | ACTIVE | -| `GENERATED` | 已生成 | ACTIVE | -| `SIGNING` | 签署中 | ACTIVE | -| `SIGNED` | 已签署 | ACTIVE | -| `VOIDING` | 作废中 | ACTIVE | -| `VOIDED` | 已作废 | ACTIVE | -| `REPORTED` | 已上报 | ACTIVE | -| `UPLOADED` | 已上传 | ACTIVE | - ---- - -## 费用适用角色（`cost_apply_role`） {#cost_apply_role} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `DRIVER` | 司机 | ACTIVE | -| `GUIDE` | 导游 | ACTIVE | -| `VEHICLE` | 车辆 | ACTIVE | -| `THIRD_PARTY` | 第三方 | ACTIVE | -| `COMPANY` | 公司 | ACTIVE | -| `OTHER` | 其他 | ACTIVE | - ---- - -## 成本分类（`cost_category`） {#cost_category} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `ACCOMMODATION` | 住宿 | ACTIVE | -| `TRANSPORT` | 交通 | ACTIVE | -| `TICKET` | 门票 | ACTIVE | -| `ACTIVITY` | 活动 | ACTIVE | -| `DINING` | 餐饮 | ACTIVE | -| `PERSONAL` | 个人消费 | ACTIVE | -| `VEHICLE_EXTRA` | 车辆附加 | ACTIVE | -| `SELF_PAY` | 自费项目 | ACTIVE | -| `meal_subsidy` | 餐补 | ACTIVE | -| `accommodation_subsidy` | 住宿补贴 | ACTIVE | -| `fuel_cost` | 油费 | ACTIVE | -| `guide_fee` | 导游费 | ACTIVE | -| `insurance` | 保险 | ACTIVE | -| `parking_fee` | 停车费 | ACTIVE | -| `tip` | 小费 | ACTIVE | - ---- - -## 费用项分类（`cost_item_category`） {#cost_item_category} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `meal_subsidy` | 餐饮补贴 | ACTIVE | -| `accommodation_subsidy` | 住宿补贴 | ACTIVE | -| `fuel_cost` | 油费/能源 | ACTIVE | -| `toll_fee` | 过路过桥费 | ACTIVE | -| `parking_fee` | 停车费 | ACTIVE | -| `guide_fee` | 讲解费 | ACTIVE | -| `insurance` | 保险费 | ACTIVE | -| `tip` | 小费/奖励 | ACTIVE | -| `other` | 其他 | ACTIVE | - ---- - -## 费用计价单位（`cost_unit`） {#cost_unit} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PER_PERSON` | 元/人 | ACTIVE | -| `PER_VEHICLE` | 元/台 | ACTIVE | -| `PER_DAY` | 元/天 | ACTIVE | -| `PER_TIME` | 元/次 | ACTIVE | -| `PER_ROOM` | 元/间 | ACTIVE | -| `PER_TABLE` | 元/桌 | ACTIVE | -| `FIXED` | 固定金额 | ACTIVE | - ---- - -## 菜系类型（`cuisine_type`） {#cuisine_type} - -> 餐厅菜系类型 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `local` | 本地菜 | ACTIVE | -| `mongolian` | 蒙餐 | ACTIVE | -| `northeastern` | 东北菜 | ACTIVE | -| `sichuan` | 川菜 | ACTIVE | -| `halal` | 清真 | ACTIVE | -| `russian` | 俄餐 | ACTIVE | -| `western` | 西餐 | ACTIVE | -| `japanese_korean` | 日韩料理 | ACTIVE | -| `fusion` | 融合菜 | ACTIVE | -| `vegetarian` | 素食 | ACTIVE | - ---- - -## 部门状态（`dept_status`） {#dept_status} - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `ACTIVE` | 正常 | ACTIVE | -| `DELETED` | 已删除 | ACTIVE | - ---- - -## 字典分类（`dict_category`） {#dict_category} - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `BASE` | 基础字典 | ACTIVE | -| `BUSINESS` | 业务字典 | ACTIVE | - ---- - -## 证件类型（`document_type`） {#document_type} - -> C端出行人证件类型 - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `ID_CARD` | 居民身份证 | ACTIVE | -| `PASSPORT` | 护照 | ACTIVE | -| `HONG_KONG_MACAO_PASS` | 港澳居民来往内地通行证 | ACTIVE | -| `TAIWAN_PASS` | 台湾居民来往大陆通行证 | ACTIVE | -| `FOREIGN_PERMANENT_RESIDENT` | 外国人永久居留身份证 | ACTIVE | -| `OTHER` | 其他 | ACTIVE | - ---- - -## 驱动方式（`drive_type`） {#drive_type} - -**分类**: BUSINESS - -> 暂无字典项 - ---- - -## 驾照类型（`driver_license_type`） {#driver_license_type} - -> 司机的驾驶证类型 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `C1` | C1 | ACTIVE | -| `C2` | C2 | ACTIVE | -| `B1` | B1 | ACTIVE | -| `B2` | B2 | ACTIVE | -| `A1` | A1 | ACTIVE | -| `A2` | A2 | ACTIVE | -| `A3` | A3 | ACTIVE | - ---- - -## 动力类型（`engine_type`） {#engine_type} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `GASOLINE` | 汽油 | ACTIVE | -| `DIESEL` | 柴油 | ACTIVE | -| `HYBRID` | 混动 | ACTIVE | -| `ELECTRIC` | 纯电 | ACTIVE | - ---- - -## 环境类型（`environment_type`） {#environment_type} - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `INDOOR` | 室内 | ACTIVE | -| `OUTDOOR` | 户外 | ACTIVE | -| `MIXED` | 混合 | ACTIVE | - ---- - -## 民族（`ethnicity`） {#ethnicity} - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `汉族` | 汉族 | ACTIVE | -| `藏族` | 藏族 | ACTIVE | -| `蒙古族` | 蒙古族 | ACTIVE | -| `回族` | 回族 | ACTIVE | -| `维吾尔族` | 维吾尔族 | ACTIVE | -| `苗族` | 苗族 | ACTIVE | -| `彝族` | 彝族 | ACTIVE | -| `壮族` | 壮族 | ACTIVE | -| `布依族` | 布依族 | ACTIVE | -| `朝鲜族` | 朝鲜族 | ACTIVE | -| `满族` | 满族 | ACTIVE | -| `侗族` | 侗族 | ACTIVE | -| `瑶族` | 瑶族 | ACTIVE | -| `白族` | 白族 | ACTIVE | -| `土家族` | 土家族 | ACTIVE | -| `哈尼族` | 哈尼族 | ACTIVE | -| `哈萨克族` | 哈萨克族 | ACTIVE | -| `傣族` | 傣族 | ACTIVE | -| `黎族` | 黎族 | ACTIVE | -| `傈僳族` | 傈僳族 | ACTIVE | -| `佤族` | 佤族 | ACTIVE | -| `畲族` | 畲族 | ACTIVE | -| `高山族` | 高山族 | ACTIVE | -| `拉祜族` | 拉祜族 | ACTIVE | -| `水族` | 水族 | ACTIVE | -| `东乡族` | 东乡族 | ACTIVE | -| `纳西族` | 纳西族 | ACTIVE | -| `景颇族` | 景颇族 | ACTIVE | -| `柯尔克孜族` | 柯尔克孜族 | ACTIVE | -| `土族` | 土族 | ACTIVE | -| `达斡尔族` | 达斡尔族 | ACTIVE | -| `仫佬族` | 仫佬族 | ACTIVE | -| `羌族` | 羌族 | ACTIVE | -| `布朗族` | 布朗族 | ACTIVE | -| `撒拉族` | 撒拉族 | ACTIVE | -| `毛南族` | 毛南族 | ACTIVE | -| `仡佬族` | 仡佬族 | ACTIVE | -| `锡伯族` | 锡伯族 | ACTIVE | -| `阿昌族` | 阿昌族 | ACTIVE | -| `普米族` | 普米族 | ACTIVE | -| `塔吉克族` | 塔吉克族 | ACTIVE | -| `怒族` | 怒族 | ACTIVE | -| `乌孜别克族` | 乌孜别克族 | ACTIVE | -| `俄罗斯族` | 俄罗斯族 | ACTIVE | -| `鄂温克族` | 鄂温克族 | ACTIVE | -| `德昂族` | 德昂族 | ACTIVE | -| `保安族` | 保安族 | ACTIVE | -| `裕固族` | 裕固族 | ACTIVE | -| `京族` | 京族 | ACTIVE | -| `塔塔尔族` | 塔塔尔族 | ACTIVE | -| `独龙族` | 独龙族 | ACTIVE | -| `鄂伦春族` | 鄂伦春族 | ACTIVE | -| `赫哲族` | 赫哲族 | ACTIVE | -| `门巴族` | 门巴族 | ACTIVE | -| `珞巴族` | 珞巴族 | ACTIVE | -| `基诺族` | 基诺族 | ACTIVE | - ---- - -## 收藏资源类型（`favorite_resource_type`） {#favorite_resource_type} - -> 小程序收藏页Tab筛选 - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PRODUCT` | 产品 | ACTIVE | -| `SCENIC` | 景区 | ACTIVE | -| `RESTAURANT` | 餐厅 | ACTIVE | -| `ACTIVITY` | 活动 | ACTIVE | -| `HOTEL` | 酒店 | ACTIVE | - -**使用该字典的接口**: - -- `GET /user/favorite` — 收藏列表（用户服务） -- `POST /user/favorite` — 添加收藏（用户服务） -- `GET /user/favorite/check` — 检查是否已收藏（用户服务） - ---- - -## 文件分组（`file_group`） {#file_group} - -> Business group for files - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `scenic` | 景点 | ACTIVE | -| `hotel` | 酒店 | ACTIVE | -| `activity` | 活动 | ACTIVE | -| `product` | 产品 | ACTIVE | -| `content` | 内容 | ACTIVE | -| `user` | 用户 | ACTIVE | -| `admin` | 管理员 | ACTIVE | -| `system` | 系统 | ACTIVE | -| `other` | 其他 | ACTIVE | -| `avatar` | 头像 | ACTIVE | -| `material` | 素材 | ACTIVE | -| `restaurant` | 餐厅 | ACTIVE | - ---- - -## 文件状态（`file_status`） {#file_status} - -> File lifecycle status - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `UPLOADING` | 上传中 | ACTIVE | -| `ACTIVE` | 正常 | ACTIVE | -| `DELETED` | 已删除 | ACTIVE | - ---- - -## 文件类型（`file_type`） {#file_type} - -> File category types - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `IMAGE` | 图片 | ACTIVE | -| `VIDEO` | 视频 | ACTIVE | -| `AUDIO` | 音频 | ACTIVE | -| `DOCUMENT` | 文档 | ACTIVE | -| `OTHER` | 其他 | ACTIVE | - ---- - -## 浏览历史资源类型（`footprint_resource_type`） {#footprint_resource_type} - -> 小程序浏览历史页面Tab分类 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PRODUCT` | 产品 | ACTIVE | -| `SCENIC` | 景区 | ACTIVE | -| `RESTAURANT` | 餐厅 | ACTIVE | -| `ACTIVITY` | 活动 | ACTIVE | -| `HOTEL` | 酒店 | ACTIVE | - -**使用该字典的接口**: - -- `GET /user/footprint` — 足迹列表（用户服务） -- `POST /user/footprint` — 添加足迹（用户服务） - ---- - -## 前端配置分组（`frontend_config_group`） {#frontend_config_group} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `MP_COLOR` | 小程序-颜色 | ACTIVE | -| `MP_PAGE` | 小程序-页面 | ACTIVE | -| `MP_GENERAL` | 小程序-通用 | ACTIVE | -| `ADMIN_PAGE` | 后台-页面 | ACTIVE | -| `ADMIN_GENERAL` | 后台-通用 | ACTIVE | -| `SECRET` | 第三方Key | ACTIVE | - ---- - -## 性别（`gender`） {#gender} - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `1` | 男 | ACTIVE | -| `2` | 女 | ACTIVE | - -**使用该字典的接口**: - -- `GET /user/profile` — 获取用户信息（用户服务） -- `PUT /user/profile` — 更新用户信息（用户服务） -- `GET /user/traveler` — 出行人列表（用户服务） -- `POST /user/traveler` — 新增出行人（用户服务） -- `GET /user/traveler/{travelerId}` — 出行人详情（用户服务） -- `PUT /user/traveler/{travelerId}` — 更新出行人（用户服务） -- `GET /admin/customer` — 客户列表（用户服务） -- `GET /admin/customer/{userId}` — 客户详情（用户服务） - ---- - -## 导游等级（`guide_level`） {#guide_level} - -> 导游的资质等级 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PRIMARY` | 初级导游 | ACTIVE | -| `INTERMEDIATE` | 中级导游 | ACTIVE | -| `SENIOR` | 高级导游 | ACTIVE | -| `SPECIAL` | 特级导游 | ACTIVE | - ---- - -## 导游服务区域（`guide_service_area`） {#guide_service_area} - -> 导游提供服务的地理区域 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `YUNNAN` | 云南 | ACTIVE | -| `SICHUAN` | 四川 | ACTIVE | -| `GUIZHOU` | 贵州 | ACTIVE | -| `TIBET` | 西藏 | ACTIVE | -| `XINJIANG` | 新疆 | ACTIVE | -| `GANSU` | 甘肃 | ACTIVE | -| `QINGHAI` | 青海 | ACTIVE | -| `HAINAN` | 海南 | ACTIVE | -| `NATIONWIDE` | 全国 | ACTIVE | - ---- - -## 导游专长（`guide_specialty`） {#guide_specialty} - -> 导游的擅长领域 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `HISTORY` | 历史文化 | ACTIVE | -| `NATURE` | 自然风光 | ACTIVE | -| `FOOD` | 美食探索 | ACTIVE | -| `ADVENTURE` | 户外探险 | ACTIVE | -| `PHOTOGRAPHY` | 摄影旅拍 | ACTIVE | -| `FAMILY` | 亲子游 | ACTIVE | -| `BUSINESS` | 商务接待 | ACTIVE | - ---- - -## 酒店配套设施（`hotel_facility`） {#hotel_facility} - -> Hotel-level facilities - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `parking` | 停车场 | ACTIVE | -| `breakfast` | 早餐 | ACTIVE | -| `free_wifi` | 免费WiFi | ACTIVE | -| `gym` | 健身房 | ACTIVE | -| `laundry` | 洗衣房 | ACTIVE | -| `laundry_service` | 代洗服务 | ACTIVE | -| `screen_cast` | 手机投屏 | ACTIVE | -| `robot` | 智能机器人 | ACTIVE | -| `elevator` | 电梯 | ACTIVE | -| `luggage_storage` | 行李寄存 | ACTIVE | -| `front_desk_24h` | 24小时前台 | ACTIVE | -| `business_center` | 商务中心 | ACTIVE | -| `meeting_room` | 会议室 | ACTIVE | -| `pool` | 游泳池 | ACTIVE | -| `spa` | SPA | ACTIVE | -| `shuttle` | 接驳服务 | ACTIVE | -| `kids_area` | 儿童乐园 | ACTIVE | -| `accessibility` | 无障碍设施 | ACTIVE | -| `pet_friendly` | 宠物友好 | ACTIVE | -| `ev_charging` | 充电桩 | ACTIVE | - ---- - -## 酒店星级（`hotel_star_level`） {#hotel_star_level} - -> 酒店的星级等级评定 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `ECONOMY` | 经济型 | ACTIVE | -| `TWO_STAR` | 二星级 | ACTIVE | -| `THREE_STAR` | 三星级 | ACTIVE | -| `FOUR_STAR` | 四星级 | ACTIVE | -| `FIVE_STAR` | 五星级 | ACTIVE | -| `LUXURY` | 豪华型 | ACTIVE | - ---- - -## 住宿类型（`hotel_type`） {#hotel_type} - -> Hotel accommodation types - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `HOTEL` | 酒店 | ACTIVE | -| `HOMESTAY` | 民宿 | ACTIVE | -| `YURT` | 蒙古包 | ACTIVE | -| `RESORT` | 度假村 | ACTIVE | -| `SPECIAL` | 特色住宿 | ACTIVE | - ---- - -## 证件类型（`id_card_type`） {#id_card_type} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `ID_CARD` | 身份证 | ACTIVE | -| `PASSPORT` | 护照 | ACTIVE | -| `HK_MACAU_PASS` | 港澳通行证 | ACTIVE | -| `TAIWAN_PASS` | 台湾通行证 | ACTIVE | -| `MILITARY_ID` | 军官证 | ACTIVE | -| `OTHER` | 其他 | ACTIVE | - -**使用该字典的接口**: - -- `GET /user/profile` — 获取用户信息（用户服务） -- `PUT /user/profile` — 更新用户信息（用户服务） -- `GET /user/traveler` — 出行人列表（用户服务） -- `POST /user/traveler` — 新增出行人（用户服务） -- `GET /user/traveler/{travelerId}` — 出行人详情（用户服务） -- `PUT /user/traveler/{travelerId}` — 更新出行人（用户服务） -- `GET /admin/customer` — 客户列表（用户服务） -- `GET /admin/customer/{userId}` — 客户详情（用户服务） - ---- - -## 保险状态（`insurance_status`） {#insurance_status} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `INSURED` | 已投保 | ACTIVE | -| `PENDING` | 待投保 | ACTIVE | -| `CANCELLED` | 已取消 | ACTIVE | -| `FAILED` | 失败 | ACTIVE | - ---- - -## 任务分组（`job_group`） {#job_group} - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `DEFAULT` | 默认分组 | ACTIVE | -| `SYSTEM` | 系统任务 | ACTIVE | -| `WECHAT` | 企微同步 | ACTIVE | -| `INSURANCE` | 保险同步 | ACTIVE | - -**使用该字典的接口**: - -- `GET /admin/job` — 分页查询定时任务（用户服务） -- `POST /admin/job` — 创建定时任务（用户服务） -- `PUT /admin/job/{jobId}` — 更新定时任务（用户服务） - ---- - -## 任务日志状态（`job_log_status`） {#job_log_status} - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `SUCCESS` | 成功 | ACTIVE | -| `FAIL` | 失败 | ACTIVE | - ---- - -## 任务补偿策略（`job_misfire_policy`） {#job_misfire_policy} - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `DEFAULT` | 默认策略 | ACTIVE | -| `FIRE_ONCE` | 立即触发一次 | ACTIVE | -| `DO_NOTHING` | 不触发 | ACTIVE | - -**使用该字典的接口**: - -- `GET /admin/job` — 分页查询定时任务（用户服务） -- `POST /admin/job` — 创建定时任务（用户服务） -- `PUT /admin/job/{jobId}` — 更新定时任务（用户服务） - ---- - -## 任务状态（`job_status`） {#job_status} - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `ACTIVE` | 启用 | ACTIVE | -| `PAUSED` | 已暂停 | ACTIVE | - -**使用该字典的接口**: - -- `GET /admin/job` — 分页查询定时任务（用户服务） -- `POST /admin/job` — 创建定时任务（用户服务） - ---- - -## 语言能力（`language`） {#language} - -> 人员掌握的语言 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `MANDARIN` | 普通话 | ACTIVE | -| `ENGLISH` | 英语 | ACTIVE | -| `JAPANESE` | 日语 | ACTIVE | -| `KOREAN` | 韩语 | ACTIVE | -| `FRENCH` | 法语 | ACTIVE | -| `SPANISH` | 西班牙语 | ACTIVE | -| `CANTONESE` | 粤语 | ACTIVE | -| `OTHER` | 其他 | ACTIVE | - ---- - -## 登录状态（`login_status`） {#login_status} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `SUCCESS` | 成功 | ACTIVE | -| `FAILED` | 失败 | ACTIVE | -| `LOCKED` | 锁定 | ACTIVE | - ---- - -## 素材分类（`material_category`） {#material_category} - -> 素材库的业务分类 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `scenic` | 景区管理 | ACTIVE | -| `hotel` | 酒店管理 | ACTIVE | -| `activity` | 游玩项目 | ACTIVE | -| `extra_service` | 额外服务 | ACTIVE | -| `extra_fee` | 额外费用 | ACTIVE | -| `vehicle` | 车辆管理 | ACTIVE | -| `guide` | 攻略管理 | ACTIVE | -| `personnel` | 人员管理 | ACTIVE | -| `restaurant` | 餐厅管理 | ACTIVE | -| `supplies` | 备品管理 | ACTIVE | -| `service` | 服务管理 | ACTIVE | -| `product` | 产品管理 | ACTIVE | -| `meal` | 餐食 | ACTIVE | -| `miniprogram` | 小程序 | ACTIVE | -| `system` | 系统素材 | ACTIVE | - ---- - -## 素材审核状态（`material_review_status`） {#material_review_status} - -> 素材上传审核状态 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PENDING` | 待审核 | ACTIVE | -| `APPROVED` | 已通过 | ACTIVE | - ---- - -## 素材标签（`material_tag`） {#material_tag} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `landscape` | 风景 | ACTIVE | -| `portrait` | 人物 | ACTIVE | -| `food` | 美食 | ACTIVE | -| `hotel` | 住宿 | ACTIVE | -| `transport` | 交通 | ACTIVE | -| `activity` | 活动 | ACTIVE | -| `winter` | 冬季 | ACTIVE | -| `summer` | 夏季 | ACTIVE | -| `grassland` | 草原 | ACTIVE | -| `forest` | 森林 | ACTIVE | - ---- - -## 餐饮类型（`meal_type`） {#meal_type} - -> 行程中的用餐安排类型 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `BREAKFAST` | 早餐 | ACTIVE | -| `LUNCH` | 午餐 | ACTIVE | -| `DINNER` | 晚餐 | ACTIVE | -| `SELF` | 自理 | ACTIVE | - ---- - -## 菜单类型（`menu_type`） {#menu_type} - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `D` | 目录 | ACTIVE | -| `M` | 菜单 | ACTIVE | -| `B` | 按钮 | ACTIVE | - -**使用该字典的接口**: - -- `POST /admin/menu` — 创建菜单（用户服务） -- `GET /admin/menu/tree` — 获取完整菜单树（用户服务） -- `GET /admin/menu/{menuId}` — 获取菜单详情（用户服务） -- `PUT /admin/menu/{menuId}` — 更新菜单（用户服务） - ---- - -## 通知渠道（`notification_channel`） {#notification_channel} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `SMS` | 短信 | ACTIVE | -| `MINIAPP` | 小程序 | ACTIVE | -| `OA` | 公众号 | ACTIVE | -| `INAPP` | 站内信 | ACTIVE | -| `WECHAT_WORK` | 企业微信 | ACTIVE | - ---- - -## 通知事件分类（`notification_event_category`） {#notification_event_category} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `ORDER` | 订单 | ACTIVE | -| `REFUND` | 退款 | ACTIVE | -| `TRIP` | 行程 | ACTIVE | -| `CONTRACT` | 合同 | ACTIVE | -| `INSURANCE` | 保险 | ACTIVE | -| `ADMIN` | 管理 | ACTIVE | -| `SYSTEM` | 系统 | ACTIVE | - ---- - -## 通知发送状态（`notification_send_status`） {#notification_send_status} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `0` | 成功 | ACTIVE | -| `1` | 失败 | ACTIVE | -| `2` | 已过滤 | ACTIVE | -| `3` | 已跳过(已禁用) | ACTIVE | - ---- - -## 通知类型（`notification_type`） {#notification_type} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `ADD_EXTERNAL_CONTACT` | 新增客户 | ACTIVE | -| `DEL_FOLLOW_USER` | 客户流失 | ACTIVE | - ---- - -## 在线状态（`online_status`） {#online_status} - -> 服务或节点的在线状态 - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `ONLINE` | 在线 | ACTIVE | -| `OFFLINE` | 离线 | ACTIVE | - ---- - -## 订单变更原因（`order_change_reason`） {#order_change_reason} - -> 行程修改/房型变更/车型变更等场景的变更原因 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `CUSTOMER_REQUEST` | 客户要求 | ACTIVE | -| `FREE_UPGRADE` | 免费升级 | ACTIVE | -| `HOTEL_FULL` | 酒店满房 | ACTIVE | -| `VEHICLE_UNAVAILABLE` | 车辆不可用 | ACTIVE | -| `WEATHER` | 天气原因 | ACTIVE | -| `ITINERARY_ADJUST` | 行程调整 | ACTIVE | -| `OTHER` | 其他 | ACTIVE | - ---- - -## 订单显示状态(C端)（`order_display_status`） {#order_display_status} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PENDING_PAY` | 待支付 | ACTIVE | -| `PENDING_DEPARTURE` | 待出行 | ACTIVE | -| `TRAVELLING` | 出行中 | ACTIVE | -| `PENDING_REVIEW` | 待评价 | ACTIVE | -| `AFTER_SALE` | 售后 | ACTIVE | - ---- - -## 订单内部流程状态（`order_process_status`） {#order_process_status} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PENDING_INFO` | 待补全信息 | ACTIVE | -| `PROCESSING` | 待内部流程 | ACTIVE | -| `PENDING_INSURANCE` | 待配保险 | ACTIVE | -| `PENDING_CONTRACT` | 待签合同 | ACTIVE | -| `PENDING_ROOM` | 待配房 | ACTIVE | -| `PENDING_VEHICLE` | 待配车 | ACTIVE | -| `PENDING_FINANCE` | 待核算 | ACTIVE | -| `READY` | 就绪 | ACTIVE | - ---- - -## 订单状态（`order_status`） {#order_status} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PENDING_PAY` | 待支付 | ACTIVE | -| `DEPOSIT_PAID` | 已付定金 | ACTIVE | -| `PAID` | 已全额支付 | ACTIVE | -| `CONFIRMED` | 已确认 | ACTIVE | -| `PENDING_BALANCE` | 待付尾款 | ACTIVE | -| `PENDING_DEPARTURE` | 待出行 | ACTIVE | -| `TRAVELLING` | 旅行中 | ACTIVE | -| `COMPLETED` | 已完成 | ACTIVE | -| `AFTER_SALES` | 售后中 | ACTIVE | -| `CANCELLED` | 已取消 | ACTIVE | -| `REFUNDING` | 退款中 | ACTIVE | -| `REFUNDED` | 已退款 | ACTIVE | - -**使用该字典的接口**: - -- `GET /admin/designer/orders` — 我的订单列表（已废弃，请使用 /admin/profile/orders）（用户服务） -- `GET /admin/profile/dashboard` — 工作台仪表盘（角色分发，支持时间范围）（用户服务） -- `GET /admin/profile/orders` — 订单列表（用户服务） - ---- - -## 订单操作类型（`order_timeline_action`） {#order_timeline_action} - -> 订单操作记录中的action类型 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `CREATED` | 创建订单 | ACTIVE | -| `EDITED` | 编辑订单 | ACTIVE | -| `CONFIRMED` | 订单确认 | ACTIVE | -| `PAYMENT_SUCCESS` | 支付成功 | ACTIVE | -| `DEPOSIT_UPDATED` | 定金变更 | ACTIVE | -| `STATUS_CHANGE` | 状态变更 | ACTIVE | -| `PROCESS_CHANGE` | 流程推进 | ACTIVE | -| `TODO_COMPLETED` | 待办完成 | ACTIVE | -| `ITINERARY_EDITED` | 行程编辑 | ACTIVE | -| `EDIT_CONFIRMED` | 修改确认 | ACTIVE | -| `ADD_DAY` | 新增天数 | ACTIVE | -| `ROOM_ADJUSTED` | 房型调整 | ACTIVE | -| `VEHICLE_ADJUSTED` | 车型调整 | ACTIVE | -| `CHECKLIST_CONFIRMED` | 清单确认 | ACTIVE | -| `CANCELLED` | 取消订单 | ACTIVE | -| `AUTO_CANCELLED` | 自动取消 | ACTIVE | -| `AUTO_COMPLETED` | 自动完成 | ACTIVE | -| `AUTO_TRAVEL_START` | 自动出行 | ACTIVE | -| `DELETED` | 删除订单 | ACTIVE | -| `REFUND_APPLIED` | 申请退款 | ACTIVE | -| `REFUND_APPROVED` | 退款通过 | ACTIVE | -| `REFUND_REJECTED` | 退款驳回 | ACTIVE | -| `REFUND_SUCCESS` | 退款成功 | ACTIVE | -| `REFUND_APPEALED` | 退款申诉 | ACTIVE | -| `REFUND_OA_APPROVED` | 审批通过退款 | ACTIVE | -| `REFUND_OA_REJECTED` | 审批驳回退款 | ACTIVE | - ---- - -## 订单待办类型（`order_todo_type`） {#order_todo_type} - -> 订单待办事项的类型 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `CONFIRM_ORDER` | 确认订单 | ACTIVE | -| `INSURANCE` | 配置保险 | ACTIVE | -| `CONTRACT` | 签订合同 | ACTIVE | -| `ARRANGE_ROOM` | 安排住宿 | ACTIVE | -| `ARRANGE_VEHICLE` | 安排车辆 | ACTIVE | -| `CONFIRM_CHECKLIST` | 确认清单 | ACTIVE | -| `PROCESS_REFUND` | 处理退款 | ACTIVE | - ---- - -## 支付模式（`payment_mode`） {#payment_mode} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `FULL` | 全款 | ACTIVE | -| `DEPOSIT` | 定金+尾款 | ACTIVE | - ---- - -## 产品分类（`product_category`） {#product_category} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `family` | 亲子游 | ACTIVE | -| `honeymoon` | 蜜月旅行 | ACTIVE | -| `photography` | 摄影之旅 | ACTIVE | -| `experience` | 深度体验 | ACTIVE | -| `driving` | 自驾越野 | ACTIVE | - -**使用该字典的接口**: - -- `POST /admin/product/item` — 创建产品（草稿）（产品服务） -- `GET /admin/product/item/{productId}` — 获取产品详情（产品服务） -- `PUT /admin/product/item/{productId}` — 更新产品（产品服务） -- `GET /mp/product/{productId}` — 产品详情（C端）（产品服务） - ---- - -## 行程节点类型（`product_node_type`） {#product_node_type} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `TRANSPORT` | 交通 | ACTIVE | -| `SCENIC` | 景区 | ACTIVE | -| `DINING` | 餐饮 | ACTIVE | -| `ACTIVITY` | 活动 | ACTIVE | -| `PHOTOGRAPHY` | 拍摄 | ACTIVE | -| `HOTEL` | 住宿 | ACTIVE | -| `FREE` | 自由活动 | ACTIVE | -| `CUSTOM` | 自定义 | ACTIVE | -| `SERVICE` | 服务 | ACTIVE | -| `NOTE` | 备注 | ACTIVE | - ---- - -## 产品状态（`product_status`） {#product_status} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `DRAFT` | 草稿 | ACTIVE | -| `PENDING_REVIEW` | 待审核 | ACTIVE | -| `REVIEWED` | 已审核 | ACTIVE | -| `REJECTED` | 已驳回 | ACTIVE | -| `PUBLISHED` | 已上架 | ACTIVE | -| `UNPUBLISHED` | 已下架 | ACTIVE | -| `COMPLETED` | 已完成 | ACTIVE | - -**使用该字典的接口**: - -- `GET /admin/designer/products` — 我的产品列表（已废弃，请使用 /admin/profile/products）（用户服务） -- `GET /admin/profile/products` — 产品列表（用户服务） -- `GET /admin/product/item/list` — 产品列表（产品服务） -- `GET /admin/product/item/{productId}` — 获取产品详情（产品服务） -- `POST /admin/product/item/{productId}/copy` — 复制产品（产品服务） -- `PUT /admin/product/item/{productId}/status` — 产品状态变更（上架/下架/完成）（产品服务） - ---- - -## 产品类型（`product_type`） {#product_type} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `CORE` | 核心产品 | ACTIVE | -| `ROUTE` | 自驾路书 | ACTIVE | -| `CUSTOM` | 私人定制 | ACTIVE | -| `GROUP` | 小蒙马 | ACTIVE | - -**使用该字典的接口**: - -- `POST /admin/product/formula/group` — 创建公式组（产品服务） -- `GET /admin/product/formula/group/list` — 公式组列表（产品服务） -- `GET /admin/product/formula/group/{groupId}` — 公式组详情（产品服务） -- `PUT /admin/product/formula/group/{groupId}` — 更新公式组（产品服务） -- `PUT /admin/product/formula/group/{groupId}/activate` — 激活公式组（产品服务） -- `POST /admin/product/formula/var` — 创建公式变量（产品服务） -- `PUT /admin/product/formula/var/{varId}` — 更新公式变量（产品服务） -- `POST /admin/product/item` — 创建产品（草稿）（产品服务） -- `GET /admin/product/item/list` — 产品列表（产品服务） -- `GET /admin/product/item/{productId}` — 获取产品详情（产品服务） -- `PUT /admin/product/item/{productId}` — 更新产品（产品服务） -- `POST /admin/product/item/{productId}/batch` — 创建主批次（产品服务） -- `POST /admin/product/item/{productId}/copy` — 复制产品（产品服务） -- `GET /admin/product/item/{productId}/group-quote` — GROUP产品报价（按套餐组合）（产品服务） -- `POST /admin/product/item/{productId}/quote` — 计算报价（产品服务） -- `PUT /admin/product/item/{productId}/status` — 产品状态变更（上架/下架/完成）（产品服务） -- `GET /mp/product/list` — 产品列表（C端）（产品服务） -- `GET /mp/product/{productId}` — 产品详情（C端）（产品服务） - ---- - -## 推送任务状态（`push_task_status`） {#push_task_status} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PENDING` | 待发送 | ACTIVE | -| `SENDING` | 发送中 | ACTIVE | -| `COMPLETED` | 已完成 | ACTIVE | -| `FAILED` | 已失败 | ACTIVE | - ---- - -## 评价等级（`rating_level`） {#rating_level} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `GOOD` | 好评 | ACTIVE | -| `MEDIUM` | 中评 | ACTIVE | -| `BAD` | 差评 | ACTIVE | - -**使用该字典的接口**: - -- `GET /admin/profile/reviews` — 我的评价列表（用户服务） - ---- - -## 退款原因（`refund_reason`） {#refund_reason} - -> 退款申请时选择的退款原因 - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `schedule_conflict` | 行程冲突/时间变动 | ACTIVE | -| `personal_reason` | 个人原因（身体不适、家庭突发情况） | ACTIVE | -| `companion_unavailable` | 同行人无法出行 | ACTIVE | -| `better_price` | 找到更合适的产品/价格 | ACTIVE | -| `duplicate_order` | 重复下单/误操作下单 | ACTIVE | -| `product_mismatch` | 产品信息描述不符 | ACTIVE | -| `itinerary_change` | 行程变更 | ACTIVE | -| `supplier_unavailable` | 供应商资源不可用（酒店满房、车辆调度问题） | ACTIVE | -| `customer_service` | 客服沟通问题 | ACTIVE | -| `promise_unmet` | 服务承诺未兑现 | ACTIVE | -| `service_mismatch` | 实际服务与约定不符（住宿降级、餐标缩水） | ACTIVE | - ---- - -## 退款原因分类（`refund_reason_category`） {#refund_reason_category} - -> 退款原因的分类 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `GENERAL` | 通用原因 | ACTIVE | -| `PRODUCT` | 产品相关 | ACTIVE | -| `SERVICE` | 服务相关 | ACTIVE | - ---- - -## 退款状态（`refund_status`） {#refund_status} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PENDING` | 待审批 | ACTIVE | -| `APPROVED` | 已通过 | ACTIVE | -| `REJECTED` | 已驳回 | ACTIVE | -| `REFUNDING` | 退款中 | ACTIVE | -| `REFUNDED` | 已退款 | ACTIVE | -| `APPEALING` | 申诉中 | ACTIVE | -| `APPEAL_APPROVED` | 申诉通过 | ACTIVE | -| `APPEAL_REJECTED` | 申诉驳回 | ACTIVE | - ---- - -## 退款类型（`refund_type`） {#refund_type} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `DEPOSIT` | 定金 | ACTIVE | -| `BALANCE` | 尾款 | ACTIVE | -| `FULL` | 全款 | ACTIVE | - ---- - -## 餐厅分类（`restaurant_category`） {#restaurant_category} - -> 推荐餐厅的分类 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `local_specialty` | 本地特色 | ACTIVE | -| `ethnic_cuisine` | 民族风味 | ACTIVE | -| `farmhouse` | 农家乐 | ACTIVE | -| `hotel_dining` | 酒店餐厅 | ACTIVE | -| `internet_famous` | 网红打卡 | ACTIVE | -| `bbq_hotpot` | 烧烤火锅 | ACTIVE | -| `western` | 西餐咖啡 | ACTIVE | -| `snack_street` | 小吃街 | ACTIVE | - ---- - -## 餐厅设施（`restaurant_facility`） {#restaurant_facility} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `wifi` | WiFi | ACTIVE | -| `parking` | 停车场 | ACTIVE | -| `private_room` | 包间 | ACTIVE | -| `child_seat` | 儿童座椅 | ACTIVE | -| `wheelchair` | 轮椅通道 | ACTIVE | -| `restroom` | 洗手间 | ACTIVE | -| `air_conditioning` | 空调 | ACTIVE | -| `outdoor_seating` | 户外座位 | ACTIVE | -| `charging` | 充电插座 | ACTIVE | -| `tv` | 电视 | ACTIVE | - ---- - -## 评分类别（`review_rating_category`） {#review_rating_category} - -> 评价时需要填写的评分维度 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `ratingOverall` | 整体满意度 | ACTIVE | -| `customizerRating` | 定制师服务 | ACTIVE | -| `ratingItinerary` | 行程安排 | ACTIVE | -| `ratingAccommodation` | 住宿安排 | ACTIVE | -| `ratingDining` | 餐饮质量 | ACTIVE | -| `ratingDriver` | 司机服务 | ACTIVE | - ---- - -## 评价审核状态（`review_status`） {#review_status} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PENDING_REVIEW` | 待审核 | ACTIVE | -| `PENDING_MODERATION` | 机器审核中 | ACTIVE | -| `PENDING_MANUAL` | 待人工审核 | ACTIVE | -| `MACHINE_REJECTED` | 机器拒绝 | ACTIVE | -| `APPROVED` | 已通过 | ACTIVE | -| `REJECTED` | 已拒绝 | ACTIVE | - ---- - -## 评价目标类型（`review_target_type`） {#review_target_type} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PRODUCT` | 产品 | ACTIVE | -| `CUSTOMIZER` | 定制师 | ACTIVE | -| `SCENIC` | 景区 | ACTIVE | -| `ACTIVITY` | 活动 | ACTIVE | -| `HOTEL` | 酒店 | ACTIVE | - ---- - -## 房型分类（`room_category`） {#room_category} - -> Room type categories - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `STANDARD` | 标间 | ACTIVE | -| `SINGLE` | 单人间 | ACTIVE | -| `TWIN` | 双床房 | ACTIVE | -| `QUEEN` | 大床房 | ACTIVE | -| `KING` | 豪华大床 | ACTIVE | -| `DELUXE` | 豪华房 | ACTIVE | -| `SUITE` | 套房 | ACTIVE | -| `FAMILY` | 家庭房 | ACTIVE | -| `YURT` | 蒙古包 | ACTIVE | -| `SPECIAL` | 特色房 | ACTIVE | -| `PARENT_CHILD` | 亲子房 | ACTIVE | - ---- - -## 房型设施（`room_facility`） {#room_facility} - -> Room-level facilities - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `slippers` | 拖鞋 | ACTIVE | -| `wardrobe` | 衣柜/衣架 | ACTIVE | -| `baby_bed` | 婴儿床 | ACTIVE | -| `wifi` | WiFi | ACTIVE | -| `wired_net` | 有线宽带 | ACTIVE | -| `kettle` | 热水壶 | ACTIVE | -| `air_cond` | 空调 | ACTIVE | -| `shower` | 独立淋浴花洒 | ACTIVE | -| `mosquito_net` | 纱窗/蚊帐 | ACTIVE | -| `smart_tv` | 智能电视 | ACTIVE | -| `safe` | 保险箱 | ACTIVE | -| `mini_fridge` | 小冰箱 | ACTIVE | -| `free_water` | 免费瓶装水 | ACTIVE | -| `heating` | 暖气 | ACTIVE | -| `phone` | 独立电话 | ACTIVE | -| `desk` | 书桌 | ACTIVE | -| `kids_toiletry` | 儿童洗漱用品 | ACTIVE | -| `toiletries` | 免费洗漱用品 | ACTIVE | -| `minibar` | 迷你吧 | ACTIVE | -| `hairdryer` | 吹风机 | ACTIVE | -| `charger` | 手机充电器 | ACTIVE | -| `corner_guard` | 防撞角 | ACTIVE | -| `sofa` | 沙发 | ACTIVE | -| `floor_heat` | 地暖 | ACTIVE | -| `usb_port` | USB充电口 | ACTIVE | -| `coffee` | 咖啡机 | ACTIVE | -| `bath_towel` | 浴巾 | ACTIVE | -| `private_bath` | 独立卫浴 | ACTIVE | -| `luggage_rack` | 行李架 | ACTIVE | -| `bt_speaker` | 蓝牙音箱 | ACTIVE | -| `smart_toilet` | 智能马桶 | ACTIVE | -| `bathtub` | 浴缸 | ACTIVE | -| `tea_set` | 茶具 | ACTIVE | -| `blackout` | 遮光窗帘 | ACTIVE | -| `mirror` | 全身镜 | ACTIVE | -| `balcony` | 阳台 | ACTIVE | -| `iron` | 熨斗 | ACTIVE | -| `bathrobe` | 浴袍 | ACTIVE | -| `air_purifier` | 空气净化器 | ACTIVE | -| `power_220v` | 220V电源插座 | ACTIVE | -| `stargazing` | 可看星空 | ACTIVE | -| `face_wash` | 洗面乳 | ACTIVE | -| `body_wash` | 沐浴露 | ACTIVE | -| `screen_cast` | 手机投屏 | ACTIVE | - ---- - -## 景区设施（`scenic_facility`） {#scenic_facility} - -> 景区配套设施 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `parking` | 停车场 | ACTIVE | -| `toilet` | 卫生间 | ACTIVE | -| `restaurant` | 餐饮 | ACTIVE | -| `wifi` | WiFi | ACTIVE | -| `accessible` | 无障碍 | ACTIVE | -| `guide_service` | 导游服务 | ACTIVE | -| `locker` | 储物柜 | ACTIVE | -| `medical` | 医务室 | ACTIVE | -| `gift_shop` | 纪念品店 | ACTIVE | -| `rest_area` | 休息区 | ACTIVE | -| `ev_charging` | 充电桩 | ACTIVE | -| `baby_care` | 母婴室 | ACTIVE | - ---- - -## 景区荣誉称号（`scenic_honor`） {#scenic_honor} - -> 景区荣誉称号（多选） - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `5A` | 5A级景区 | ACTIVE | -| `4A` | 4A级景区 | ACTIVE | -| `3A` | 3A级景区 | ACTIVE | -| `2A` | 2A级景区 | ACTIVE | -| `1A` | 1A级景区 | ACTIVE | -| `WORLD_HERITAGE` | 世界遗产 | ACTIVE | -| `NATIONAL_SCENIC` | 国家级风景名胜区 | ACTIVE | -| `NATIONAL_RESERVE` | 国家级自然保护区 | ACTIVE | -| `NATIONAL_FOREST` | 国家森林公园 | ACTIVE | -| `NATIONAL_GEOPARK` | 国家地质公园 | ACTIVE | - ---- - -## 季节（`season`） {#season} - -> 一年四季 - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `SPRING` | 春季 | ACTIVE | -| `SUMMER` | 夏季 | ACTIVE | -| `AUTUMN` | 秋季 | ACTIVE | -| `WINTER` | 冬季 | ACTIVE | - ---- - -## 服务项计费方式（`service_billing_type`） {#service_billing_type} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `FLAT_RATE` | 一口价 | ACTIVE | -| `PER_PERSON` | 按人头 | ACTIVE | -| `PER_HOUR` | 按小时 | ACTIVE | -| `PER_DAY` | 按天 | ACTIVE | -| `PER_DISTANCE` | 按距离 | ACTIVE | -| `CUSTOM` | 自定义 | ACTIVE | - ---- - -## 服务分类（`service_category`） {#service_category} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `airport_transfer` | 机场接送 | ACTIVE | -| `station_transfer` | 车站接送 | ACTIVE | -| `ceremony` | 仪式活动 | ACTIVE | -| `guide` | 导游服务 | ACTIVE | -| `photography` | 摄影跟拍 | ACTIVE | -| `charter` | 包车服务 | ACTIVE | -| `logistics` | 后勤保障 | ACTIVE | -| `vip` | 贵宾服务 | ACTIVE | -| `free_gift` | 免费赠送 | ACTIVE | - ---- - -## 服务计价单位（`service_unit`） {#service_unit} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PER_PERSON` | 元/人 | ACTIVE | -| `PER_TIME` | 元/次 | ACTIVE | -| `PER_DAY` | 元/天 | ACTIVE | -| `PER_VEHICLE` | 元/台 | ACTIVE | -| `FIXED` | 固定金额 | ACTIVE | - ---- - -## 结算状态（`settle_status`） {#settle_status} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `pending` | 待结算 | ACTIVE | -| `settled` | 已结算 | ACTIVE | -| `processing` | 结算中 | ACTIVE | -| `cancelled` | 已取消 | ACTIVE | - ---- - -## 团期人员角色（`staff_role`） {#staff_role} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `LEADER` | 领队 | ACTIVE | -| `PHOTOGRAPHER` | 摄影师 | ACTIVE | -| `DRIVER` | 司机 | ACTIVE | -| `OTHER` | 其他 | ACTIVE | - ---- - -## 人员类型（`staff_type`） {#staff_type} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `GUIDE` | 导游 | ACTIVE | -| `GUIDE_ASSISTANT` | 导游助理 | ACTIVE | -| `PHOTOGRAPHER` | 摄影师 | ACTIVE | -| `LEADER` | 领队 | ACTIVE | -| `OTHER` | 其他 | ACTIVE | - -**使用该字典的接口**: - -- `GET /admin/staff/type/{staffType}/prices` — 查询价格日历（按人员类型）（资源服务） -- `PUT /admin/staff/type/{staffType}/prices` — 批量设置价格（按人员类型）（资源服务） -- `DELETE /admin/staff/type/{staffType}/prices` — 清除价格日历（按人员类型）（资源服务） -- `PUT /admin/staff/type/{staffType}/prices/batch-status` — 批量修改调度状态（按人员类型）（资源服务） -- `GET /admin/product/item/{productId}/batch/{batchId}` — 批次详情（产品服务） -- `GET /admin/product/item/{productId}/batch/{batchId}/staff` — 服务人员列表（产品服务） -- `POST /admin/product/item/{productId}/batch/{batchId}/staff` — 保存服务人员(全量替换)（产品服务） -- `POST /admin/product/item/{productId}/staff-config` — 添加人员配置（产品服务） -- `GET /admin/product/item/{productId}/staff-configs` — 获取产品人员配置列表（产品服务） -- `PUT /admin/product/staff-config/{id}` — 更新人员配置（产品服务） -- `DELETE /admin/product/staff-config/{id}` — 删除人员配置（产品服务） - ---- - -## 备品分类（`supplies_category`） {#supplies_category} - -> 备品租赁的分类 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `personal_gear` | 个人装备 | ACTIVE | -| `camping_equipment` | 露营设备 | ACTIVE | -| `riding_gear` | 骑行装备 | ACTIVE | -| `electronics` | 电子设备 | ACTIVE | -| `safety_protection` | 安全防护 | ACTIVE | -| `entertainment` | 娱乐器材 | ACTIVE | -| `warmth_gear` | 保暖装备 | ACTIVE | -| `vehicle_accessories` | 车载装备 | ACTIVE | - ---- - -## 是否（`sys_yes_no`） {#sys_yes_no} - -> 通用是否选择 - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `1` | 是 | ACTIVE | -| `0` | 否 | ACTIVE | - ---- - -## 任务优先级（`task_priority`） {#task_priority} - -> 任务看板中任务的优先级 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `LOW` | 低 | ACTIVE | -| `MEDIUM` | 中 | ACTIVE | -| `HIGH` | 高 | ACTIVE | -| `URGENT` | 紧急 | ACTIVE | - ---- - -## 变速箱（`transmission`） {#transmission} - -**分类**: BUSINESS - -> 暂无字典项 - ---- - -## 出行人类型（`traveler_type`） {#traveler_type} - -> 出行人年龄分类，用于订单和出行人管理 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `ADULT` | 成人 | ACTIVE | -| `CHILD` | 儿童 | ACTIVE | -| `YOUNG_CHILD` | 小童 | ACTIVE | -| `BABY` | 幼童 | ACTIVE | - -**使用该字典的接口**: - -- `GET /user/traveler` — 出行人列表（用户服务） -- `POST /user/traveler` — 新增出行人（用户服务） -- `GET /user/traveler/{travelerId}` — 出行人详情（用户服务） -- `PUT /user/traveler/{travelerId}` — 更新出行人（用户服务） - ---- - -## 出行人年龄规则（`traveler_type_age_rule`） {#traveler_type_age_rule} - -> 根据出生日期自动判断出行人类型，remark存JSON格式年龄范围{"minAge":下限,"maxAge":上限}，含下限不含上限 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `BABY` | 幼童 | ACTIVE | -| `YOUNG_CHILD` | 小童 | ACTIVE | -| `CHILD` | 儿童 | ACTIVE | -| `ADULT` | 成人 | ACTIVE | - ---- - -## 行程状态（`trip_status`） {#trip_status} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `draft` | 草稿 | ACTIVE | -| `online` | 已上线 | ACTIVE | -| `offline` | 已下线 | ACTIVE | - ---- - -## 行程类型（`trip_type`） {#trip_type} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `group` | 跟团游 | ACTIVE | -| `free` | 自由行 | ACTIVE | -| `custom` | 定制游 | ACTIVE | -| `semi_free` | 半自由行 | ACTIVE | - ---- - -## 用户状态（`user_status`） {#user_status} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `ACTIVE` | 正常 | ACTIVE | -| `INACTIVE` | 未激活 | ACTIVE | -| `BANNED` | 已封禁 | ACTIVE | -| `DELETED` | 已注销 | ACTIVE | - -**使用该字典的接口**: - -- `GET /admin/customer` — 客户列表（用户服务） -- `GET /admin/customer/{userId}` — 客户详情（用户服务） - ---- - -## 车型（`vehicle_type`） {#vehicle_type} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `SUV` | 越野车 | ACTIVE | -| `SEDAN` | 5座轿车 | ACTIVE | -| `MPV` | 7座商务车 | ACTIVE | -| `MINIBUS` | 9-15座小巴 | ACTIVE | -| `BUS` | 大巴 | ACTIVE | - -**使用该字典的接口**: - -- `POST /admin/product/item/{productId}/price-calendar/auto-calc` — 自动计算成本并同步到价格日历（产品服务） -- `POST /admin/product/item/{productId}/price-calendar/calc-preview` — 测算预览（不写入数据库）（产品服务） -- `GET /admin/product/item/{productId}/pricing` — 获取定价规则（产品服务） -- `POST /admin/product/item/{productId}/pricing` — 保存定价规则（产品服务） - ---- - -## 百科分类（`wiki_category`） {#wiki_category} - -> 百科文章分类 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `scenery` | 绝美风光 | ACTIVE | -| `food` | 特色美食 | ACTIVE | -| `culture` | 民俗文化 | ACTIVE | -| `travel_guide` | 旅行攻略 | ACTIVE | -| `accommodation` | 住宿推荐 | ACTIVE | -| `transport` | 交通出行 | ACTIVE | -| `tips` | 注意事项 | ACTIVE | - ---- - -## 文章状态（`wiki_status`） {#wiki_status} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `0` | 草稿 | ACTIVE | -| `1` | 已发布 | ACTIVE | -| `2` | 已下架 | ACTIVE | - ---- - -## 窗户类型（`window_type`） {#window_type} - -> Window types - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `NO_WINDOW` | 无窗 | ACTIVE | -| `WINDOW` | 有窗 | ACTIVE | -| `SCENIC` | 景观窗 | ACTIVE | - ---- - -## 工单优先级（`work_order_priority`） {#work_order_priority} - -> 客户工单的紧急程度 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `LOW` | 低 | ACTIVE | -| `MEDIUM` | 中 | ACTIVE | -| `HIGH` | 高 | ACTIVE | -| `URGENT` | 紧急 | ACTIVE | - ---- - -## 工单状态（`work_order_status`） {#work_order_status} - -> 客户工单的处理状态 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PENDING` | 待处理 | ACTIVE | -| `PROCESSING` | 处理中 | ACTIVE | -| `COMPLETED` | 已完成 | ACTIVE | -| `CLOSED` | 已关闭 | ACTIVE | - ---- - -## 工单类型（`work_order_type`） {#work_order_type} - -> 客户工单的业务分类 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `REFUND` | 退款申请 | ACTIVE | -| `ITINERARY_CHANGE` | 行程变更 | ACTIVE | -| `COMPLAINT` | 投诉建议 | ACTIVE | -| `INQUIRY` | 咨询 | ACTIVE | -| `OTHER` | 其他 | ACTIVE | - ---- diff --git a/2026-03/17_1009/hl-contract-service.md b/2026-03/17_1009/hl-contract-service.md deleted file mode 100644 index 7c4fc19..0000000 --- a/2026-03/17_1009/hl-contract-service.md +++ /dev/null @@ -1,793 +0,0 @@ -# 合同服务 API 文档 - -**服务**: `hl-contract-service` -**接口总数**: 18 - -## 目录 - -- **合同管理** (12 个接口) -- **补充约定模板管理** (6 个接口) - ---- - -## 合同管理 - -### `GET` /admin/contract/active-by-order/{orderId} - -**获取订单有效合同** - -返回订单当前有效的合同（非作废状态的最新合同），用于检查订单是否已有签署中或已签署的合同。 - -**权限**：需管理员登录。 - -**关联字典**： -- contract_status：合同状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«合同信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同信息` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/agencies - -**可用旅行社列表** - -返回系统配置的旅行社列表，创建合同时选择签约旅行社 - -**响应** `统一响应结果«List«旅行社信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `旅行社信息[]` | | 响应数据 | -|   `agencyAddress` | `string` | | 旅行社地址 | -|   `agencyName` | `string` | | 旅行社名称 | -|   `businessLicenseNumber` | `string` | | 营业执照号 | -|   `businessScope` | `string` | | 经营范围 | -|   `code` | `string` | | 旅行社编码 | -|   `licenseNumber` | `string` | | 旅行社许可证号 | -|   `regionId` | `string` | | 地区ID | -|   `transactorName` | `string` | | 经办人姓名 | -|   `transactorPhone` | `string` | | 经办人电话 | -|   `zjParentId` | `int` | | 属地管理机构ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/by-order/{orderId} - -**按订单查询合同** - -查询指定订单下的所有合同记录（含已作废），按创建时间倒序排列。用于订单详情页展示合同历史。 - -**权限**：需管理员登录。 - -**关联字典**： -- contract_status：合同状态（列表显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«List«合同信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同信息[]` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/contract/create - -**创建合同(标准模式)** - -标准电子签约流程：创建合同 → 平台生成合同PDF → 发送签署短信给出行人 → 出行人在线签署 → 回调更新状态。状态流转：CREATED → SIGNING → SIGNED - -**请求体** `创建合同请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `adultCost` | `number` | 是 | 成人费用 | -| `agencyCode` | `string` | | 旅行社编号（可选，默认使用配置值） | -| `childCost` | `number` | | 儿童费用 | -| `contactName` | `string` | 是 | 联系人姓名 | -| `contactPhone` | `string` | 是 | 联系人电话 | -| `contractType` | `string` | | 合同类型: TOUR-旅游合同(默认), INSURANCE-保险单 | -| `days` | `int` | | 行程天数 | -| `departureCity` | `string` | | 出发城市 | -| `departureDate` | `string` | 是 | 出发日期 | -| `destination` | `string` | 是 | 目的地 | -| `disputeResolution` | `int` | | 争议解决方式: 1-仲裁 2-诉讼 | -| `groupId` | `string` | | 团号 | -| `leastCustomerNumber` | `int` | | 最低成团人数 | -| `nights` | `int` | | 住宿晚数 | -| `orderId` | `long` | | 订单ID | -| `paymentMethod` | `int` | | 付款方式: 1-现金 2-转账 3-在线 | -| `returnDate` | `string` | 是 | 返回日期 | -| `routeName` | `string` | 是 | 线路名称 | -| `signatoryIdNumber` | `string` | 是 | 签署人证件号码 | -| `signatoryIdType` | `int` | | 签署人证件类型: 1-身份证 | -| `signatoryMode` | `int` | | 签署模式: 1-短信 2-现场 3-线下 | -| `signatoryName` | `string` | 是 | 签署人姓名 | -| `signatoryPhone` | `string` | 是 | 签署人电话 | -| `signingPlace` | `string` | | 签约地点 | -| `supplementaryClause` | `string` | | 补充约定内容 | -| `templateCode` | `string` | 是 | 模板编码 | -| `totalAmount` | `number` | 是 | 合同总金额 | -| `transactorName` | `string` | | 经办人姓名 | -| `transactorPhone` | `string` | | 经办人电话 | -| `travelers` | `合同出行人请求[]` | 是 | 出行人列表 | -|   `age` | `int` | | 年龄 | -|   `gender` | `string` | | 性别: male/female | -|   `health` | `string` | | 健康信息 | -|   `idCardNo` | `string` | 是 | 证件号码 | -|   `idCardType` | `int` | | 证件类型: 1-身份证 2-护照 | -|   `isChild` | `boolean` | | 是否儿童 | -|   `isSigner` | `boolean` | | 是否签署人 | -|   `name` | `string` | 是 | 姓名 | -|   `phone` | `string` | | 手机号 | -| `vehicleModel` | `string` | | 车型名称(产品快照) | - -**响应** `统一响应结果«合同详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同详情` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `statusLogs` | `合同状态变更日志[]` | | 状态变更日志 | -|     `createTime` | `string` | | 创建时间 | -|     `logId` | `long` | | 日志ID | -|     `newStatus` | `string` | | 新状态 | -|     `oldStatus` | `string` | | 旧状态 | -|     `source` | `string` | | 变更来源 | -|   `supplementaryClause` | `string` | | 补充约定内容 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -|   `travelers` | `合同出行人信息[]` | | 出行人列表 | -|     `idCardNo` | `string` | | 证件号码 | -|     `idCardType` | `string` | | 证件类型 | -|     `isSigner` | `boolean` | | 是否签署人 | -|     `name` | `string` | | 姓名 | -|     `phone` | `string` | | 手机号 | -|     `travelerId` | `long` | | 出行人ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/list - -**合同列表** - -分页查询合同记录，支持按订单号、合同状态、旅行社筛选 - -**关联字典**： -- contract_status：合同状态（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `orderId` | `integer(int64)` | | 订单ID | 1001 | -| `page` | `integer(int32)` | | 页码 | 1 | -| `pageSize` | `integer(int32)` | | 每页条数 | 20 | -| `platform` | `string` | | 签约平台 | TOURAGE | -| `status` | `string` | | 合同状态 | SIGNED | - -**响应** `统一响应结果«分页结果«合同信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«合同信息»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `合同信息[]` | | 数据列表 | -|     `agencyCode` | `string` | | 旅行社编号 | -|     `contactName` | `string` | | 联系人姓名 | -|     `contactPhone` | `string` | | 联系人电话 | -|     `contractId` | `long` | | 合同ID | -|     `contractNumber` | `string` | | 合同编号 | -|     `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|     `createTime` | `string` | | 创建时间 | -|     `departureDate` | `string` | | 出发日期 | -|     `destination` | `string` | | 目的地 | -|     `fileUrl` | `string` | | 合同文件URL | -|     `mode` | `string` | | 签约模式: STANDARD/SYNC | -|     `orderId` | `long` | | 订单ID | -|     `platform` | `string` | | 签约平台 | -|     `qrCodeUrl` | `string` | | 二维码URL | -|     `returnDate` | `string` | | 返回日期 | -|     `signUrl` | `string` | | 签署URL | -|     `status` | `string` | | 合同状态 | -|     `statusLabel` | `string` | | 合同状态标签 | -|     `templateCode` | `string` | | 模板编码 | -|     `templateName` | `string` | | 模板名称 | -|     `totalAmount` | `number` | | 合同总金额 | -|     `touristCount` | `int` | | 出行人数 | -|     `travelAgencyName` | `string` | | 旅行社名称 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/contract/report - -**报备合同(同步模式)** - -线下签约模式：创建合同记录 → 管理员上传已签署的PDF → 同步到12301报备平台。状态流转：CREATED → UPLOADED → REPORTED - -**请求体** `报备合同请求（同步模式）` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `adultCost` | `number` | 是 | 成人费用 | -| `agencyCode` | `string` | | 旅行社编号 | -| `childCost` | `number` | | 儿童费用 | -| `contactName` | `string` | 是 | 联系人姓名 | -| `contactPhone` | `string` | 是 | 联系人电话 | -| `contractType` | `string` | | 合同类型: TOUR-旅游合同(默认), INSURANCE-保险单 | -| `days` | `int` | | 行程天数 | -| `departureCity` | `string` | | 出发城市 | -| `departureDate` | `string` | 是 | 出发日期 | -| `destination` | `string` | 是 | 目的地 | -| `disputeResolution` | `int` | | 争议解决方式: 1-仲裁 2-诉讼 | -| `groupId` | `string` | | 团号 | -| `leastCustomerNumber` | `int` | | 最低成团人数 | -| `nights` | `int` | | 住宿晚数 | -| `orderId` | `long` | | 订单ID | -| `paymentMethod` | `int` | | 付款方式: 1-现金 2-转账 3-在线 | -| `returnDate` | `string` | 是 | 返回日期 | -| `routeName` | `string` | 是 | 线路名称 | -| `signatoryIdNumber` | `string` | 是 | 签署人证件号码 | -| `signatoryIdType` | `int` | | 签署人证件类型: 1-身份证 | -| `signatoryMode` | `int` | | 签署模式（同步模式默认2-现场） | -| `signatoryName` | `string` | 是 | 签署人姓名 | -| `signatoryPhone` | `string` | 是 | 签署人电话 | -| `signingPlace` | `string` | | 签约地点 | -| `supplementaryClause` | `string` | | 补充约定内容 | -| `templateCode` | `string` | 是 | 模板编码 | -| `totalAmount` | `number` | 是 | 合同总金额 | -| `transactorName` | `string` | | 经办人姓名 | -| `transactorPhone` | `string` | | 经办人电话 | -| `travelers` | `合同出行人请求[]` | 是 | 出行人列表 | -|   `age` | `int` | | 年龄 | -|   `gender` | `string` | | 性别: male/female | -|   `health` | `string` | | 健康信息 | -|   `idCardNo` | `string` | 是 | 证件号码 | -|   `idCardType` | `int` | | 证件类型: 1-身份证 2-护照 | -|   `isChild` | `boolean` | | 是否儿童 | -|   `isSigner` | `boolean` | | 是否签署人 | -|   `name` | `string` | 是 | 姓名 | -|   `phone` | `string` | | 手机号 | - -**响应** `统一响应结果«合同详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同详情` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `statusLogs` | `合同状态变更日志[]` | | 状态变更日志 | -|     `createTime` | `string` | | 创建时间 | -|     `logId` | `long` | | 日志ID | -|     `newStatus` | `string` | | 新状态 | -|     `oldStatus` | `string` | | 旧状态 | -|     `source` | `string` | | 变更来源 | -|   `supplementaryClause` | `string` | | 补充约定内容 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -|   `travelers` | `合同出行人信息[]` | | 出行人列表 | -|     `idCardNo` | `string` | | 证件号码 | -|     `idCardType` | `string` | | 证件类型 | -|     `isSigner` | `boolean` | | 是否签署人 | -|     `name` | `string` | | 姓名 | -|     `phone` | `string` | | 手机号 | -|     `travelerId` | `long` | | 出行人ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/templates - -**合同模板列表** - -返回合同平台可用的合同模板列表，创建合同时选择模板 - -**响应** `统一响应结果«List«合同模板信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同模板信息[]` | | 响应数据 | -|   `createTime` | `string` | | 创建时间 | -|   `description` | `string` | | 模板描述 | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `platform` | `string` | | 签约平台 | -|   `status` | `string` | | 模板状态 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateId` | `long` | | 模板ID | -|   `templateName` | `string` | | 模板名称 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/{id} - -**合同详情** - -**关联字典**： -- contract_status：合同状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 合同ID | - -**响应** `统一响应结果«合同详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同详情` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `statusLogs` | `合同状态变更日志[]` | | 状态变更日志 | -|     `createTime` | `string` | | 创建时间 | -|     `logId` | `long` | | 日志ID | -|     `newStatus` | `string` | | 新状态 | -|     `oldStatus` | `string` | | 旧状态 | -|     `source` | `string` | | 变更来源 | -|   `supplementaryClause` | `string` | | 补充约定内容 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -|   `travelers` | `合同出行人信息[]` | | 出行人列表 | -|     `idCardNo` | `string` | | 证件号码 | -|     `idCardType` | `string` | | 证件类型 | -|     `isSigner` | `boolean` | | 是否签署人 | -|     `name` | `string` | | 姓名 | -|     `phone` | `string` | | 手机号 | -|     `travelerId` | `long` | | 出行人ID | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/contract/{id}/invalidate - -**作废合同** - -将合同标记为作废状态（不可恢复）。作废后该合同不再有效，可重新为订单创建新合同 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 合同ID | - -**响应** `统一响应结果«合同信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同信息` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/contract/{id}/resend-sms - -**重发签署短信** - -重新发送签署短信给出行人，用于签署短信过期或未收到的场景。仅SIGNING状态的合同可操作 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 合同ID | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/{id}/status - -**刷新合同状态(从平台同步)** - -主动查询合同平台的最新签署状态并同步到本地，适用于回调未到达的场景 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 合同ID | - -**响应** `统一响应结果«合同信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同信息` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/contract/{id}/upload-pdf - -**上传已签署PDF(同步模式)** - -同步模式专用：上传线下签署完成的合同PDF文件，上传后合同状态变为UPLOADED，可进一步报备 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 合同ID | - -**响应** `统一响应结果«合同信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同信息` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -| `message` | `string` | | 响应消息 | - ---- - -## 补充约定模板管理 - -### `POST` /admin/contract/clause-template - -**创建补充约定模板** - -创建合同补充约定的模板，支持变量占位符。创建后默认启用 - -**请求体** `补充约定模板请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `content` | `string` | 是 | 模板内容 | -| `name` | `string` | 是 | 模板名称 | -| `sortOrder` | `int` | | 排序（升序） | - -**响应** `统一响应结果«补充约定模板»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `补充约定模板` | | 响应数据 | -|   `content` | `string` | | 模板内容 | -|   `createTime` | `string` | | 创建时间 | -|   `name` | `string` | | 模板名称 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `string` | | 状态: ACTIVE/INACTIVE | -|   `templateId` | `long` | | 模板ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/clause-template/list - -**获取启用的补充约定模板列表（创建合同用）** - -返回所有启用状态的补充约定模板，创建合同时选择需要附加的补充约定条款。 - -**权限**：需管理员登录。 - -**响应** `统一响应结果«List«补充约定模板»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `补充约定模板[]` | | 响应数据 | -|   `content` | `string` | | 模板内容 | -|   `createTime` | `string` | | 创建时间 | -|   `name` | `string` | | 模板名称 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `string` | | 状态: ACTIVE/INACTIVE | -|   `templateId` | `long` | | 模板ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/clause-template/list-all - -**获取全部补充约定模板（管理页用）** - -**关联字典**： -- common_status：通用状态（列表显示，ACTIVE=启用/INACTIVE=停用） - -**响应** `统一响应结果«List«补充约定模板»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `补充约定模板[]` | | 响应数据 | -|   `content` | `string` | | 模板内容 | -|   `createTime` | `string` | | 创建时间 | -|   `name` | `string` | | 模板名称 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `string` | | 状态: ACTIVE/INACTIVE | -|   `templateId` | `long` | | 模板ID | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/contract/clause-template/{id} - -**更新补充约定模板** - -更新模板的标题和内容。已被合同引用的模板更新不影响已创建的合同（合同记录的是快照内容）。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 模板ID | - -**请求体** `补充约定模板请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `content` | `string` | 是 | 模板内容 | -| `name` | `string` | 是 | 模板名称 | -| `sortOrder` | `int` | | 排序（升序） | - -**响应** `统一响应结果«补充约定模板»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `补充约定模板` | | 响应数据 | -|   `content` | `string` | | 模板内容 | -|   `createTime` | `string` | | 创建时间 | -|   `name` | `string` | | 模板名称 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `string` | | 状态: ACTIVE/INACTIVE | -|   `templateId` | `long` | | 模板ID | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/contract/clause-template/{id} - -**删除补充约定模板** - -软删除模板。已被合同引用的模板仍可删除，不影响已创建的合同 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 模板ID | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/contract/clause-template/{id}/toggle-status - -**切换模板启用/停用状态** - -**关联字典**： -- common_status：通用状态（状态切换，ACTIVE=启用/INACTIVE=停用） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 模板ID | - -**响应** `统一响应结果«补充约定模板»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `补充约定模板` | | 响应数据 | -|   `content` | `string` | | 模板内容 | -|   `createTime` | `string` | | 创建时间 | -|   `name` | `string` | | 模板名称 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `string` | | 状态: ACTIVE/INACTIVE | -|   `templateId` | `long` | | 模板ID | -| `message` | `string` | | 响应消息 | - ---- diff --git a/2026-03/17_1009/hl-file-service.md b/2026-03/17_1009/hl-file-service.md deleted file mode 100644 index 7c17ab6..0000000 --- a/2026-03/17_1009/hl-file-service.md +++ /dev/null @@ -1,331 +0,0 @@ -# 文件服务 API 文档 - -**服务**: `hl-file-service` -**接口总数**: 11 - -## 目录 - -- **C端文件上传** (3 个接口) -- **文件管理** (8 个接口) - ---- - -## C端文件上传 - -### `GET` /mp/file/preview-by-url - -**文件在线预览** - -返回HTML预览页面，小程序通过web-view打开。支持PDF、图片、Office文档 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `url` | `string` | | 文件完整URL | | - ---- - -### `POST` /mp/file/upload - -**上传文件（C端用户）** - -小程序端直接上传文件，支持头像、评价图片等场景。groupKey决定存储路径和文件策略，默认为avatar - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `groupKey` | `string` | | 文件分组标识 | | - -**响应** `统一响应结果«文件信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `文件信息` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `fileHash` | `string` | | 文件MD5哈希 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `groupKey` | `string` | | 业务分组 | -|   `mimeType` | `string` | | MIME类型 | -|   `ossUrl` | `string` | | OSS地址 | -|   `previewUrl` | `string` | | 预览地址 | -|   `refCount` | `int` | | 引用次数 | -|   `status` | `string` | | 文件状态 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/file/{fileId}/preview - -**文件内容流式预览** - -流式输出文件内容，设置正确的Content-Type头。用于小程序端通过web-view直接预览图片和PDF等文件。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `fileId` | `integer` | | 文件ID | - ---- - -## 文件管理 - -### `GET` /admin/file/list - -**文件列表（分页）** - -支持按文件类型、分组、上传者等条件筛选，按上传时间倒序分页返回 - -**关联字典**： -- file_type：文件类型（列表筛选+显示） -- file_status：文件状态（显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `endDate` | `string` | | 结束日期 | 2026-12-31 | -| `fileType` | `string` | | 文件类型 | image | -| `groupKey` | `string` | | 业务分组 | scenic | -| `keyword` | `string` | | 搜索关键词 | 风景 | -| `page` | `integer(int32)` | | 页码 | 1 | -| `pageSize` | `integer(int32)` | | 每页条数 | 20 | -| `startDate` | `string` | | 开始日期 | 2026-01-01 | - -**响应** `统一响应结果«IPage«文件信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `IPage«文件信息»` | | 响应数据 | -|   `current` | `long` | | | -|   `pages` | `long` | | | -|   `records` | `文件信息[]` | | | -|     `createdAt` | `string` | | 创建时间 | -|     `fileHash` | `string` | | 文件MD5哈希 | -|     `fileId` | `string` | | 文件ID | -|     `fileName` | `string` | | 文件名 | -|     `fileSize` | `long` | | 文件大小(字节) | -|     `fileType` | `string` | | 文件类型 | -|     `groupKey` | `string` | | 业务分组 | -|     `mimeType` | `string` | | MIME类型 | -|     `ossUrl` | `string` | | OSS地址 | -|     `previewUrl` | `string` | | 预览地址 | -|     `refCount` | `int` | | 引用次数 | -|     `status` | `string` | | 文件状态 | -|     `thumbnailUrl` | `string` | | 缩略图地址 | -|   `size` | `long` | | | -|   `total` | `long` | | | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/file/stats - -**存储统计** - -返回文件总数、总存储空间、各类型文件占比等统计信息 - -**响应** `统一响应结果«文件统计信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `文件统计信息` | | 响应数据 | -|   `countByGroup` | `object` | | 按分组统计文件数量 | -|   `countByType` | `object` | | 按类型统计文件数量 | -|   `sizeByType` | `object` | | 按类型统计文件大小 | -|   `totalCount` | `long` | | 文件总数 | -|   `totalSize` | `long` | | 文件总大小(字节) | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/file/upload/confirm - -**确认上传完成** - -上传流程第二步：前端直传OSS完成后调用此接口，系统验证文件存在性并创建文件记录。支持MD5去重，相同文件不会重复存储 - -**请求体** `上传确认请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `fileId` | `string` | 是 | 文件ID | - -**响应** `统一响应结果«文件信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `文件信息` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `fileHash` | `string` | | 文件MD5哈希 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `groupKey` | `string` | | 业务分组 | -|   `mimeType` | `string` | | MIME类型 | -|   `ossUrl` | `string` | | OSS地址 | -|   `previewUrl` | `string` | | 预览地址 | -|   `refCount` | `int` | | 引用次数 | -|   `status` | `string` | | 文件状态 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/file/upload/token - -**请求上传凭证** - -上传流程第一步：前端请求上传凭证 → 获取OSS预签名URL和临时凭证 → 前端直传OSS → 调用确认上传接口。凭证有效期有限，过期需重新请求 - -**请求体** `上传令牌请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `fileHash` | `string` | 是 | 文件MD5哈希 | -| `fileName` | `string` | 是 | 文件名 | -| `fileSize` | `long` | 是 | 文件大小(字节) | -| `forcePresigned` | `boolean` | | 强制使用预签名URL（跳过STS分片模式） | -| `groupKey` | `string` | | 业务分组 | - -**响应** `统一响应结果«上传令牌信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `上传令牌信息` | | 响应数据 | -|   `bucket` | `string` | | OSS Bucket名称 | -|   `contentType` | `string` | | 上传时必须使用的Content-Type（与预签名URL签名一致） | -|   `expireAt` | `string` | | 过期时间 | -|   `file` | `文件信息` | | 秒传文件信息 | -|     `createdAt` | `string` | | 创建时间 | -|     `fileHash` | `string` | | 文件MD5哈希 | -|     `fileId` | `string` | | 文件ID | -|     `fileName` | `string` | | 文件名 | -|     `fileSize` | `long` | | 文件大小(字节) | -|     `fileType` | `string` | | 文件类型 | -|     `groupKey` | `string` | | 业务分组 | -|     `mimeType` | `string` | | MIME类型 | -|     `ossUrl` | `string` | | OSS地址 | -|     `previewUrl` | `string` | | 预览地址 | -|     `refCount` | `int` | | 引用次数 | -|     `status` | `string` | | 文件状态 | -|     `thumbnailUrl` | `string` | | 缩略图地址 | -|   `fileId` | `string` | | 文件ID | -|   `ossKey` | `string` | | OSS对象Key | -|   `presignedUrl` | `string` | | 预签名上传URL | -|   `region` | `string` | | OSS Region | -|   `stsToken` | `STS临时凭证信息` | | STS临时凭证 | -|     `accessKeyId` | `string` | | AccessKey ID | -|     `accessKeySecret` | `string` | | AccessKey Secret | -|     `expiration` | `string` | | 过期时间 | -|     `securityToken` | `string` | | 安全令牌 | -|   `uploadMode` | `string` | | 上传模式: PRESIGNED_URL/STS_MULTIPART/INSTANT | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/file/{fileId} - -**文件详情** - -**关联字典**： -- file_type：文件类型（显示） -- file_status：文件状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `fileId` | `integer` | | 文件ID | - -**响应** `统一响应结果«文件信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `文件信息` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `fileHash` | `string` | | 文件MD5哈希 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `groupKey` | `string` | | 业务分组 | -|   `mimeType` | `string` | | MIME类型 | -|   `ossUrl` | `string` | | OSS地址 | -|   `previewUrl` | `string` | | 预览地址 | -|   `refCount` | `int` | | 引用次数 | -|   `status` | `string` | | 文件状态 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/file/{fileId} - -**删除文件** - -软删除文件记录，如果文件存在引用关系则不允许删除。OSS上的物理文件由定时任务清理 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `fileId` | `integer` | | 文件ID | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/file/{fileId}/preview - -**文件内容流式预览** - -流式输出文件内容，设置正确的Content-Type头，支持浏览器直接预览图片和PDF等文件 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `fileId` | `integer` | | 文件ID | - ---- - -### `GET` /admin/file/{fileId}/refs - -**文件引用列表** - -查看文件被哪些业务实体引用（如景区封面、酒店图片等），用于判断文件是否可安全删除 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `fileId` | `integer` | | 文件ID | - -**响应** `统一响应结果«List«文件引用信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `文件引用信息[]` | | 响应数据 | -|   `bizId` | `string` | | 业务ID | -|   `bizType` | `string` | | 业务类型 | -|   `createdAt` | `string` | | 创建时间 | -|   `fileId` | `string` | | 文件ID | -|   `refId` | `string` | | 引用ID | -| `message` | `string` | | 响应消息 | - ---- diff --git a/2026-03/17_1009/hl-guide-service.md b/2026-03/17_1009/hl-guide-service.md deleted file mode 100644 index d01c9cc..0000000 --- a/2026-03/17_1009/hl-guide-service.md +++ /dev/null @@ -1,727 +0,0 @@ -# 攻略服务 API 文档 - -**服务**: `hl-guide-service` -**接口总数**: 21 - -## 目录 - -- **攻略分类管理** (7 个接口) -- **攻略文章管理** (8 个接口) -- **攻略标签管理** (6 个接口) - ---- - -## 攻略分类管理 - -### `POST` /admin/guide/category - -**创建分类** - -创建攻略分类，分类名称不可重复。创建后默认启用，排序值越小越靠前。 - -**权限**：需管理员登录。 - -**请求体** `CategoryCreateRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryName` | `string` | 是 | 分类名称 | -| `coverMaterialId` | `long` | | 封面素材ID | -| `coverUrl` | `string` | | 封面URL | -| `description` | `string` | | 描述 | -| `icon` | `string` | | 图标 | -| `sortOrder` | `int` | | 排序（默认0） | - -**响应** `统一响应结果«攻略分类»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略分类` | | 响应数据 | -|   `articleCount` | `int` | | 文章数量 | -|   `categoryId` | `long` | | 分类ID | -|   `categoryName` | `string` | | 分类名称 | -|   `coverMaterialId` | `long` | | 封面素材ID | -|   `coverUrl` | `string` | | 封面URL | -|   `createdAt` | `string` | | 创建时间 | -|   `description` | `string` | | 描述 | -|   `icon` | `string` | | 图标 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `int` | | 状态：0=禁用，1=启用 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/guide/category/enabled - -**启用的分类列表** - -仅返回状态为启用的分类，创建文章时用于选择分类 - -**响应** `统一响应结果«List«攻略分类»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略分类[]` | | 响应数据 | -|   `articleCount` | `int` | | 文章数量 | -|   `categoryId` | `long` | | 分类ID | -|   `categoryName` | `string` | | 分类名称 | -|   `coverMaterialId` | `long` | | 封面素材ID | -|   `coverUrl` | `string` | | 封面URL | -|   `createdAt` | `string` | | 创建时间 | -|   `description` | `string` | | 描述 | -|   `icon` | `string` | | 图标 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `int` | | 状态：0=禁用，1=启用 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/guide/category/list - -**分类列表** - -返回全部攻略分类（含启用和停用），按排序值升序排列 - -**关联字典**： -- common_status：通用状态（列表显示，ACTIVE=启用/INACTIVE=停用） - -**响应** `统一响应结果«List«攻略分类»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略分类[]` | | 响应数据 | -|   `articleCount` | `int` | | 文章数量 | -|   `categoryId` | `long` | | 分类ID | -|   `categoryName` | `string` | | 分类名称 | -|   `coverMaterialId` | `long` | | 封面素材ID | -|   `coverUrl` | `string` | | 封面URL | -|   `createdAt` | `string` | | 创建时间 | -|   `description` | `string` | | 描述 | -|   `icon` | `string` | | 图标 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `int` | | 状态：0=禁用，1=启用 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/guide/category/{categoryId} - -**更新分类** - -更新攻略分类的名称、图标、描述等信息。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryId` | `integer` | 是 | categoryId | - -**请求体** `CategoryUpdateRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryName` | `string` | | 分类名称 | -| `coverMaterialId` | `long` | | 封面素材ID | -| `coverUrl` | `string` | | 封面URL | -| `description` | `string` | | 描述 | -| `icon` | `string` | | 图标 | -| `sortOrder` | `int` | | 排序 | - -**响应** `统一响应结果«攻略分类»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略分类` | | 响应数据 | -|   `articleCount` | `int` | | 文章数量 | -|   `categoryId` | `long` | | 分类ID | -|   `categoryName` | `string` | | 分类名称 | -|   `coverMaterialId` | `long` | | 封面素材ID | -|   `coverUrl` | `string` | | 封面URL | -|   `createdAt` | `string` | | 创建时间 | -|   `description` | `string` | | 描述 | -|   `icon` | `string` | | 图标 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `int` | | 状态：0=禁用，1=启用 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/guide/category/{categoryId} - -**删除分类** - -删除分类前需确保分类下无文章，否则删除失败 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryId` | `integer` | 是 | categoryId | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/guide/category/{categoryId}/sort - -**更新分类排序** - -更新分类的排序值，排序值越小越靠前。影响小程序端分类导航的展示顺序。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryId` | `integer` | 是 | categoryId | - -**请求体** `CategorySortRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `sortOrder` | `int` | 是 | 排序值 | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/guide/category/{categoryId}/status - -**更新分类状态** - -启用或停用分类。停用后该分类下的文章不会在小程序端展示，但不影响已有文章 - -**关联字典**： -- common_status：通用状态（状态切换，ACTIVE=启用/INACTIVE=停用） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryId` | `integer` | 是 | categoryId | - -**请求体** `StatusRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `status` | `int` | 是 | 状态值 | - -**响应** `统一响应结果«Void»` - ---- - -## 攻略文章管理 - -### `POST` /admin/guide/article - -**创建文章** - -创建攻略文章，需指定分类。创建后默认为草稿状态，需手动发布后小程序端才可见。 - -**权限**：需管理员登录。 - -**关联字典**： -- wiki_status：文章状态（创建后默认DRAFT） - -**请求体** `ArticleCreateRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `authorName` | `string` | | 作者名称 | -| `bannerMaterialIds` | `long[]` | | 轮播图素材ID列表 | -| `categoryId` | `long` | 是 | 分类ID | -| `content` | `string` | | 正文内容 | -| `coverMaterialId` | `long` | | 封面素材ID | -| `coverUrl` | `string` | | 封面URL | -| `resources` | `ArticleResourceItem[]` | | 关联资源列表 | -|   `resourceId` | `long` | 是 | 资源ID | -|   `resourceName` | `string` | 是 | 资源名称 | -|   `resourceType` | `string` | 是 | 资源类型：SCENIC/RESTAURANT/HOTEL/ACTIVITY/PRODUCT | -|   `sortOrder` | `int` | | 排序 | -| `sortOrder` | `int` | | 排序（默认0） | -| `source` | `string` | | 来源 | -| `subtitle` | `string` | | 副标题 | -| `summary` | `string` | | 摘要 | -| `tagIds` | `long[]` | | 标签ID列表 | -| `title` | `string` | 是 | 标题 | - -**响应** `统一响应结果«攻略文章详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略文章详情` | | 响应数据 | -|   `articleId` | `long` | | 文章ID | -|   `authorName` | `string` | | 作者名称 | -|   `bannerMaterialIds` | `long[]` | | 轮播图素材ID列表 | -|   `categoryId` | `long` | | 分类ID | -|   `categoryName` | `string` | | 分类名称 | -|   `content` | `string` | | 正文内容 | -|   `coverMaterialId` | `long` | | 封面素材ID | -|   `coverUrl` | `string` | | 封面URL | -|   `createdAt` | `string` | | 创建时间 | -|   `favoriteCount` | `int` | | 收藏数 | -|   `isRecommend` | `int` | | 是否推荐：0=否，1=是 | -|   `isTop` | `int` | | 是否置顶：0=否，1=是 | -|   `likeCount` | `int` | | 点赞数 | -|   `publishTime` | `string` | | 发布时间 | -|   `resources` | `文章关联资源[]` | | 关联资源列表 | -|     `resourceId` | `long` | | 资源ID | -|     `resourceName` | `string` | | 资源名称 | -|     `resourceType` | `string` | | 资源类型：SCENIC/RESTAURANT/HOTEL/ACTIVITY/PRODUCT | -|     `sortOrder` | `int` | | 排序 | -|   `sortOrder` | `int` | | 排序 | -|   `source` | `string` | | 来源 | -|   `status` | `int` | | 状态：0=草稿，1=已发布，2=已下架 | -|   `subtitle` | `string` | | 副标题 | -|   `summary` | `string` | | 摘要 | -|   `tags` | `攻略标签[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `long` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `tagType` | `int` | | 标签类型：0=系统管理，1=自定义 | -|     `useCount` | `int` | | 使用次数 | -|   `title` | `string` | | 标题 | -|   `updatedAt` | `string` | | 更新时间 | -|   `viewCount` | `int` | | 浏览量 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/guide/article/list - -**文章列表** - -分页查询攻略文章，支持按分类、状态、关键词筛选 - -**关联字典**： -- wiki_status：文章状态（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `categoryId` | `integer(int64)` | | 分类ID | | -| `isRecommend` | `integer(int32)` | | 是否推荐：0=否，1=是 | | -| `isTop` | `integer(int32)` | | 是否置顶：0=否，1=是 | | -| `keyword` | `string` | | 关键词（搜索标题/摘要） | | -| `orderBy` | `string` | | 排序字段：sortOrder/publishTime/viewCount/createdAt（默认createdAt） | | -| `orderDir` | `string` | | 排序方向：asc/desc（默认desc） | | -| `page` | `integer(int32)` | | 页码（默认1） | | -| `pageSize` | `integer(int32)` | | 每页数量（默认20，最大100） | | -| `status` | `integer(int32)` | | 状态：0=草稿，1=已发布，2=已下架 | | - -**响应** `统一响应结果«分页结果«攻略文章列表项»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«攻略文章列表项»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `攻略文章列表项[]` | | 数据列表 | -|     `articleId` | `long` | | 文章ID | -|     `categoryId` | `long` | | 分类ID | -|     `categoryName` | `string` | | 分类名称 | -|     `coverUrl` | `string` | | 封面URL | -|     `createdAt` | `string` | | 创建时间 | -|     `isRecommend` | `int` | | 是否推荐：0=否，1=是 | -|     `isTop` | `int` | | 是否置顶：0=否，1=是 | -|     `publishTime` | `string` | | 发布时间 | -|     `sortOrder` | `int` | | 排序 | -|     `status` | `int` | | 状态：0=草稿，1=已发布，2=已下架 | -|     `summary` | `string` | | 摘要 | -|     `tags` | `攻略标签[]` | | 标签列表 | -|     `title` | `string` | | 标题 | -|     `viewCount` | `int` | | 浏览量 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/guide/article/{articleId} - -**文章详情** - -**关联字典**： -- wiki_status：文章状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | 是 | articleId | - -**响应** `统一响应结果«攻略文章详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略文章详情` | | 响应数据 | -|   `articleId` | `long` | | 文章ID | -|   `authorName` | `string` | | 作者名称 | -|   `bannerMaterialIds` | `long[]` | | 轮播图素材ID列表 | -|   `categoryId` | `long` | | 分类ID | -|   `categoryName` | `string` | | 分类名称 | -|   `content` | `string` | | 正文内容 | -|   `coverMaterialId` | `long` | | 封面素材ID | -|   `coverUrl` | `string` | | 封面URL | -|   `createdAt` | `string` | | 创建时间 | -|   `favoriteCount` | `int` | | 收藏数 | -|   `isRecommend` | `int` | | 是否推荐：0=否，1=是 | -|   `isTop` | `int` | | 是否置顶：0=否，1=是 | -|   `likeCount` | `int` | | 点赞数 | -|   `publishTime` | `string` | | 发布时间 | -|   `resources` | `文章关联资源[]` | | 关联资源列表 | -|     `resourceId` | `long` | | 资源ID | -|     `resourceName` | `string` | | 资源名称 | -|     `resourceType` | `string` | | 资源类型：SCENIC/RESTAURANT/HOTEL/ACTIVITY/PRODUCT | -|     `sortOrder` | `int` | | 排序 | -|   `sortOrder` | `int` | | 排序 | -|   `source` | `string` | | 来源 | -|   `status` | `int` | | 状态：0=草稿，1=已发布，2=已下架 | -|   `subtitle` | `string` | | 副标题 | -|   `summary` | `string` | | 摘要 | -|   `tags` | `攻略标签[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `long` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `tagType` | `int` | | 标签类型：0=系统管理，1=自定义 | -|     `useCount` | `int` | | 使用次数 | -|   `title` | `string` | | 标题 | -|   `updatedAt` | `string` | | 更新时间 | -|   `viewCount` | `int` | | 浏览量 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/guide/article/{articleId} - -**更新文章** - -更新攻略文章的标题、内容、封面图、分类等信息。已发布的文章更新后立即生效。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | 是 | articleId | - -**请求体** `ArticleUpdateRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `authorName` | `string` | | 作者名称 | -| `bannerMaterialIds` | `long[]` | | 轮播图素材ID列表 | -| `categoryId` | `long` | | 分类ID | -| `content` | `string` | | 正文内容 | -| `coverMaterialId` | `long` | | 封面素材ID | -| `coverUrl` | `string` | | 封面URL | -| `resources` | `ArticleResourceItem[]` | | 关联资源列表 | -|   `resourceId` | `long` | 是 | 资源ID | -|   `resourceName` | `string` | 是 | 资源名称 | -|   `resourceType` | `string` | 是 | 资源类型：SCENIC/RESTAURANT/HOTEL/ACTIVITY/PRODUCT | -|   `sortOrder` | `int` | | 排序 | -| `sortOrder` | `int` | | 排序 | -| `source` | `string` | | 来源 | -| `subtitle` | `string` | | 副标题 | -| `summary` | `string` | | 摘要 | -| `tagIds` | `long[]` | | 标签ID列表 | -| `title` | `string` | | 标题 | - -**响应** `统一响应结果«攻略文章详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略文章详情` | | 响应数据 | -|   `articleId` | `long` | | 文章ID | -|   `authorName` | `string` | | 作者名称 | -|   `bannerMaterialIds` | `long[]` | | 轮播图素材ID列表 | -|   `categoryId` | `long` | | 分类ID | -|   `categoryName` | `string` | | 分类名称 | -|   `content` | `string` | | 正文内容 | -|   `coverMaterialId` | `long` | | 封面素材ID | -|   `coverUrl` | `string` | | 封面URL | -|   `createdAt` | `string` | | 创建时间 | -|   `favoriteCount` | `int` | | 收藏数 | -|   `isRecommend` | `int` | | 是否推荐：0=否，1=是 | -|   `isTop` | `int` | | 是否置顶：0=否，1=是 | -|   `likeCount` | `int` | | 点赞数 | -|   `publishTime` | `string` | | 发布时间 | -|   `resources` | `文章关联资源[]` | | 关联资源列表 | -|     `resourceId` | `long` | | 资源ID | -|     `resourceName` | `string` | | 资源名称 | -|     `resourceType` | `string` | | 资源类型：SCENIC/RESTAURANT/HOTEL/ACTIVITY/PRODUCT | -|     `sortOrder` | `int` | | 排序 | -|   `sortOrder` | `int` | | 排序 | -|   `source` | `string` | | 来源 | -|   `status` | `int` | | 状态：0=草稿，1=已发布，2=已下架 | -|   `subtitle` | `string` | | 副标题 | -|   `summary` | `string` | | 摘要 | -|   `tags` | `攻略标签[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `long` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `tagType` | `int` | | 标签类型：0=系统管理，1=自定义 | -|     `useCount` | `int` | | 使用次数 | -|   `title` | `string` | | 标题 | -|   `updatedAt` | `string` | | 更新时间 | -|   `viewCount` | `int` | | 浏览量 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/guide/article/{articleId} - -**删除文章** - -软删除攻略文章，同时清除文章的标签关联。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | 是 | articleId | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/guide/article/{articleId}/recommend - -**设置推荐** - -设置/取消文章推荐。推荐文章会在小程序首页和推荐列表中优先展示 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | 是 | articleId | - -**请求体** `RecommendRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `isRecommend` | `int` | 是 | 是否推荐：0=否，1=是 | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/guide/article/{articleId}/status - -**发布/下架** - -切换文章发布状态。发布后小程序端可见，下架后小程序端不再展示但管理端仍可查看 - -**关联字典**： -- wiki_status：文章状态（状态切换） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | 是 | articleId | - -**请求体** `StatusRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `status` | `int` | 是 | 状态值 | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/guide/article/{articleId}/top - -**设置置顶** - -设置/取消文章置顶。置顶文章在分类列表中始终排在最前面 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | 是 | articleId | - -**请求体** `TopRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `isTop` | `int` | 是 | 是否置顶：0=否，1=是 | - -**响应** `统一响应结果«Void»` - ---- - -## 攻略标签管理 - -### `POST` /admin/guide/tag - -**创建标签** - -创建攻略系统标签，标签名称不可重复。创建后可用于文章分类和筛选。 - -**权限**：需管理员登录。 - -**请求体** `TagCreateRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagColor` | `string` | | 标签颜色（十六进制） | -| `tagName` | `string` | 是 | 标签名称 | -| `tagType` | `int` | | 标签类型：0=系统管理，1=自定义（默认0） | - -**响应** `统一响应结果«攻略标签»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略标签` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `long` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `tagType` | `int` | | 标签类型：0=系统管理，1=自定义 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/guide/tag/all - -**所有标签列表** - -返回全部标签（含系统标签和用户自定义标签），用于文章编辑时的标签选择器 - -**响应** `统一响应结果«List«攻略标签»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略标签[]` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `long` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `tagType` | `int` | | 标签类型：0=系统管理，1=自定义 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/guide/tag/article/{articleId} - -**更新文章标签** - -全量替换文章的标签关联，传入新的标签ID列表（空数组表示清除所有标签） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | 是 | articleId | - -**请求体** `ArticleTagUpdateRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagIds` | `long[]` | 是 | 标签ID列表 | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/guide/tag/managed - -**系统标签列表** - -返回管理员创建的系统标签（不含用户自定义标签），用于标签管理页 - -**响应** `统一响应结果«List«攻略标签»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略标签[]` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `long` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `tagType` | `int` | | 标签类型：0=系统管理，1=自定义 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/guide/tag/{tagId} - -**更新标签** - -更新标签名称。标签名称不可与其他已有标签重复。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagId` | `integer` | 是 | tagId | - -**请求体** `TagUpdateRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagColor` | `string` | | 标签颜色（十六进制） | -| `tagName` | `string` | | 标签名称 | - -**响应** `统一响应结果«攻略标签»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略标签` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `long` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `tagType` | `int` | | 标签类型：0=系统管理，1=自定义 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/guide/tag/{tagId} - -**删除标签** - -删除标签并自动解除与所有文章的关联关系。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagId` | `integer` | 是 | tagId | - -**响应** `统一响应结果«Void»` - ---- diff --git a/2026-03/17_1009/hl-material-service.md b/2026-03/17_1009/hl-material-service.md deleted file mode 100644 index c8ed7fb..0000000 --- a/2026-03/17_1009/hl-material-service.md +++ /dev/null @@ -1,968 +0,0 @@ -# 素材服务 API 文档 - -**服务**: `hl-material-service` -**接口总数**: 28 - -## 目录 - -- **小程序-素材** (1 个接口) -- **素材分类权限管理** (2 个接口) -- **素材标签管理** (6 个接口) -- **素材管理** (19 个接口) - ---- - -## 小程序-素材 - -### `GET` /mp/material/miniprogram - -**获取小程序分类下的全部素材** - -返回miniprogram分类下的所有素材，用于小程序端展示公共素材资源（如引导页图片、默认头像等） - -**响应** `统一响应结果«List«素材信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材信息[]` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `categoryPath` | `string` | | 完整分类路径（如：攻略管理 / 999 / 888） | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `string` | | 创建人ID | -|   `createdByName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 素材描述 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `imageHeight` | `int` | | 图片高度 | -|   `imageWidth` | `int` | | 图片宽度 | -|   `materialId` | `string` | | 素材ID | -|   `materialName` | `string` | | 素材名称 | -|   `ossUrl` | `string` | | OSS地址 | -|   `refCount` | `int` | | 引用次数 | -|   `subCategoryId` | `string` | | 子分类ID | -|   `subCategoryName` | `string` | | 子分类名称 | -|   `tags` | `素材标签信息[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdByName` | `string` | | 创建人姓名 | -|     `managed` | `boolean` | | 是否系统管理标签 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `string` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `useCount` | `int` | | 使用次数 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -## 素材分类权限管理 - -### `GET` /admin/material/category/permissions/{roleCode} - -**获取角色的分类权限** - -仅超级管理员可操作。返回指定角色可访问的素材分类编码列表 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `roleCode` | `string` | | 角色编码 | - -**响应** `统一响应结果«List«string»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `string[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/material/category/permissions/{roleCode} - -**更新角色的分类权限** - -仅超级管理员可操作。全量替换指定角色的素材分类访问权限，传入允许访问的分类编码列表 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `roleCode` | `string` | | 角色编码 | - -**请求体** `分类权限更新请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryCodes` | `string[]` | 是 | 分类编码列表 | - -**响应** `统一响应结果«Void»` - ---- - -## 素材标签管理 - -### `POST` /admin/material/tag - -**创建管理标签** - -创建系统级素材标签，标签名称不可重复。创建后可用于素材分类和筛选。 - -**权限**：需管理员登录。 - -**请求体** `创建标签请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagColor` | `string` | | 标签颜色 | -| `tagName` | `string` | 是 | 标签名称 | - -**响应** `统一响应结果«素材标签信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材标签信息` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdByName` | `string` | | 创建人姓名 | -|   `managed` | `boolean` | | 是否系统管理标签 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `string` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/tag/adhoc - -**解析自定义标签（按名称查找或创建）** - -按标签名称查找已有标签，不存在则自动创建为用户自定义标签。用于素材上传时输入自由标签文本的场景。 - -**权限**：需管理员登录。 - -**请求体** `创建标签请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagColor` | `string` | | 标签颜色 | -| `tagName` | `string` | 是 | 标签名称 | - -**响应** `统一响应结果«素材标签信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材标签信息` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdByName` | `string` | | 创建人姓名 | -|   `managed` | `boolean` | | 是否系统管理标签 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `string` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/material/tag/{tagId} - -**编辑标签** - -更新标签名称。标签名称不可与其他已有标签重复。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagId` | `integer` | | 标签ID | - -**请求体** `更新标签请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagColor` | `string` | | 标签颜色 | -| `tagName` | `string` | | 标签名称 | - -**响应** `统一响应结果«素材标签信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材标签信息` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdByName` | `string` | | 创建人姓名 | -|   `managed` | `boolean` | | 是否系统管理标签 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `string` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/material/tag/{tagId} - -**删除标签** - -删除标签并自动解除与所有素材的关联关系。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagId` | `integer` | | 标签ID | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/material/tags - -**获取管理标签（标签管理用）** - -返回管理员创建的系统标签列表（不含用户自定义标签），用于标签管理页的CRUD操作。 - -**响应** `统一响应结果«List«素材标签信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材标签信息[]` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdByName` | `string` | | 创建人姓名 | -|   `managed` | `boolean` | | 是否系统管理标签 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `string` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/material/tags/all - -**获取全部标签（选择器用，含自定义标签）** - -返回所有标签（含系统标签和用户自定义标签），用于素材上传/编辑时的标签选择器。 - -**响应** `统一响应结果«List«素材标签信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材标签信息[]` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdByName` | `string` | | 创建人姓名 | -|   `managed` | `boolean` | | 是否系统管理标签 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `string` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -## 素材管理 - -### `DELETE` /admin/material/batch - -**批量删除素材** - -批量删除素材，返回删除结果（成功数/失败数/失败原因）。有引用关系的素材会跳过并记录失败原因 - -**请求体** `批量删除素材请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `materialIds` | `string[]` | 是 | 素材ID列表 | - -**响应** `统一响应结果«批量删除结果»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `批量删除结果` | | 响应数据 | -|   `failedItems` | `删除失败项[]` | | 失败项列表 | -|     `materialId` | `string` | | 素材ID | -|     `reason` | `string` | | 失败原因 | -|   `successCount` | `int` | | 成功删除数量 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/material/batch/tags - -**批量更新标签** - -对多个素材同时添加和/或移除标签，支持增量操作（addTagIds新增，removeTagIds移除） - -**请求体** `批量标签操作请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `addTagIds` | `string[]` | | 要添加的标签ID列表 | -| `materialIds` | `string[]` | 是 | 素材ID列表 | -| `removeTagIds` | `string[]` | | 要移除的标签ID列表 | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/material/categories - -**获取有权限的分类列表（含素材数量）** - -返回当前角色有权限查看的素材分类树，每个分类包含素材数量统计。超级管理员可见全部分类 - -**响应** `统一响应结果«List«素材分类信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材分类信息[]` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `children` | `素材分类信息[]` | | 子分类列表 | -|     `categoryCode` | `string` | | 分类编码 | -|     `categoryName` | `string` | | 分类名称 | -|     `children` | `素材分类信息[]` | | 子分类列表 | -|     `materialCount` | `int` | | 素材数量 | -|     `parentId` | `string` | | 父子分类ID | -|     `subCategoryId` | `string` | | 子分类ID | -|   `materialCount` | `int` | | 素材数量 | -|   `parentId` | `string` | | 父子分类ID | -|   `subCategoryId` | `string` | | 子分类ID | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/category/sub - -**创建子分类** - -在一级分类下创建子分类，分类编码自动生成。子分类用于更细粒度的素材归档 - -**请求体** `Create subcategory request` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryName` | `string` | 是 | 子分类名称 | -| `parentCode` | `string` | 是 | 根分类编码(scenic/hotel等) | -| `parentId` | `long` | | 父子分类ID(为空则创建在根分类下) | -| `sortOrder` | `int` | | 排序值 | - -**响应** `统一响应结果«素材分类信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材分类信息` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `children` | `素材分类信息[]` | | 子分类列表 | -|     `categoryCode` | `string` | | 分类编码 | -|     `categoryName` | `string` | | 分类名称 | -|     `children` | `素材分类信息[]` | | 子分类列表 | -|     `materialCount` | `int` | | 素材数量 | -|     `parentId` | `string` | | 父子分类ID | -|     `subCategoryId` | `string` | | 子分类ID | -|   `materialCount` | `int` | | 素材数量 | -|   `parentId` | `string` | | 父子分类ID | -|   `subCategoryId` | `string` | | 子分类ID | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/material/category/sub/{categoryId} - -**更新子分类** - -更新子分类的名称或排序值。仅有该分类权限的管理员可操作。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryId` | `integer` | | 子分类ID | - -**请求体** `Update subcategory request` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryName` | `string` | | Subcategory name | -| `sortOrder` | `int` | | Sort order | - -**响应** `统一响应结果«素材分类信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材分类信息` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `children` | `素材分类信息[]` | | 子分类列表 | -|     `categoryCode` | `string` | | 分类编码 | -|     `categoryName` | `string` | | 分类名称 | -|     `children` | `素材分类信息[]` | | 子分类列表 | -|     `materialCount` | `int` | | 素材数量 | -|     `parentId` | `string` | | 父子分类ID | -|     `subCategoryId` | `string` | | 子分类ID | -|   `materialCount` | `int` | | 素材数量 | -|   `parentId` | `string` | | 父子分类ID | -|   `subCategoryId` | `string` | | 子分类ID | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/material/category/sub/{categoryId} - -**删除子分类** - -删除子分类前需确保分类下无素材，否则删除失败 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryId` | `integer` | | 子分类ID | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/material/list - -**素材列表** - -分页查询素材，支持按分类、标签、文件类型、关键词筛选。返回结果受角色分类权限限制 - -**关联字典**： -- file_type：文件类型（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `categoryCode` | `string` | | 分类编码 | scenic | -| `createdBy` | `integer(int64)` | | 创建人ID | 1001 | -| `endDate` | `string` | | 结束日期 | 2026-12-31 | -| `fileType` | `string` | | 文件类型 | image | -| `keyword` | `string` | | 搜索关键词 | 风景 | -| `orderBy` | `string` | | 排序字段 | createdAt | -| `orderDir` | `string` | | 排序方向: asc/desc | desc | -| `page` | `integer(int32)` | | 页码 | 1 | -| `pageSize` | `integer(int32)` | | 每页条数 | 20 | -| `startDate` | `string` | | 开始日期 | 2026-01-01 | -| `subCategoryId` | `integer(int64)` | | 子分类ID | 2030000000000001 | -| `tagIds` | `string` | | 标签ID列表(逗号分隔) | 1,2,3 | - -**响应** `统一响应结果«分页结果«素材信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«素材信息»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `素材信息[]` | | 数据列表 | -|     `categoryCode` | `string` | | 分类编码 | -|     `categoryName` | `string` | | 分类名称 | -|     `categoryPath` | `string` | | 完整分类路径（如：攻略管理 / 999 / 888） | -|     `createdAt` | `string` | | 创建时间 | -|     `createdBy` | `string` | | 创建人ID | -|     `createdByName` | `string` | | 创建人姓名 | -|     `description` | `string` | | 素材描述 | -|     `fileId` | `string` | | 文件ID | -|     `fileName` | `string` | | 文件名 | -|     `fileSize` | `long` | | 文件大小(字节) | -|     `fileType` | `string` | | 文件类型 | -|     `imageHeight` | `int` | | 图片高度 | -|     `imageWidth` | `int` | | 图片宽度 | -|     `materialId` | `string` | | 素材ID | -|     `materialName` | `string` | | 素材名称 | -|     `ossUrl` | `string` | | OSS地址 | -|     `refCount` | `int` | | 引用次数 | -|     `subCategoryId` | `string` | | 子分类ID | -|     `subCategoryName` | `string` | | 子分类名称 | -|     `tags` | `素材标签信息[]` | | 标签列表 | -|     `thumbnailUrl` | `string` | | 缩略图地址 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/upload/chunk - -**分片上传-上传分片** - -大文件上传第二步：逐个上传分片数据，分片索引从0开始。支持断点续传，已上传的分片无需重传。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `chunkIndex` | `integer(int32)` | | 分片索引（从0开始） | | -| `uploadId` | `string` | | 上传ID | | - -**响应** `统一响应结果«分片上传结果»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分片上传结果` | | 响应数据 | -|   `etag` | `string` | | 分片ETag | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/upload/chunk/cancel - -**分片上传-取消** - -取消分片上传任务，清理已上传的分片数据和OSS临时文件。仅上传发起者可取消。 - -**请求体** `分片上传取消请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `uploadId` | `string` | 是 | 上传ID | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /admin/material/upload/chunk/complete - -**分片上传-完成合并** - -大文件上传第三步：所有分片上传完成后调用，OSS端合并分片为完整文件并创建素材记录。 - -**请求体** `分片上传完成请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `uploadId` | `string` | 是 | 上传ID | - -**响应** `统一响应结果«素材信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材信息` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `categoryPath` | `string` | | 完整分类路径（如：攻略管理 / 999 / 888） | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `string` | | 创建人ID | -|   `createdByName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 素材描述 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `imageHeight` | `int` | | 图片高度 | -|   `imageWidth` | `int` | | 图片宽度 | -|   `materialId` | `string` | | 素材ID | -|   `materialName` | `string` | | 素材名称 | -|   `ossUrl` | `string` | | OSS地址 | -|   `refCount` | `int` | | 引用次数 | -|   `subCategoryId` | `string` | | 子分类ID | -|   `subCategoryName` | `string` | | 子分类名称 | -|   `tags` | `素材标签信息[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdByName` | `string` | | 创建人姓名 | -|     `managed` | `boolean` | | 是否系统管理标签 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `string` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `useCount` | `int` | | 使用次数 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/upload/chunk/init - -**分片上传-初始化** - -大文件上传第一步：初始化分片上传任务，返回uploadId和每个分片的预签名URL。前端按分片并发上传后调用完成合并接口。 - -**权限**：需管理员登录，受角色分类权限限制。 - -**请求体** `分片上传初始化请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `contentType` | `string` | 是 | 文件MIME类型 | -| `fileSize` | `long` | 是 | 文件大小（字节） | -| `filename` | `string` | 是 | 文件名 | -| `materialId` | `string` | | 关联素材ID（可选，用于更新已有素材） | - -**响应** `统一响应结果«分片上传初始化结果»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分片上传初始化结果` | | 响应数据 | -|   `chunkSize` | `int` | | 推荐分片大小（字节） | -|   `uploadId` | `string` | | 上传ID | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/upload/confirm - -**确认上传完成** - -上传素材第二步：前端直传OSS完成后调用此接口创建素材记录，支持MD5去重 - -**关联字典**： -- material_tag：素材标签（上传时可选标签） - -**请求体** `素材上传确认请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `description` | `string` | | 素材描述 | -| `materialId` | `string` | 是 | 素材ID | -| `tagIds` | `string[]` | | 标签ID列表 | - -**响应** `统一响应结果«素材信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材信息` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `categoryPath` | `string` | | 完整分类路径（如：攻略管理 / 999 / 888） | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `string` | | 创建人ID | -|   `createdByName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 素材描述 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `imageHeight` | `int` | | 图片高度 | -|   `imageWidth` | `int` | | 图片宽度 | -|   `materialId` | `string` | | 素材ID | -|   `materialName` | `string` | | 素材名称 | -|   `ossUrl` | `string` | | OSS地址 | -|   `refCount` | `int` | | 引用次数 | -|   `subCategoryId` | `string` | | 子分类ID | -|   `subCategoryName` | `string` | | 子分类名称 | -|   `tags` | `素材标签信息[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdByName` | `string` | | 创建人姓名 | -|     `managed` | `boolean` | | 是否系统管理标签 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `string` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `useCount` | `int` | | 使用次数 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/upload/folder - -**文件夹上传初始化（创建分类+批量获取凭证）** - -支持整个文件夹上传：自动根据文件夹名创建子分类，为每个文件批量获取上传凭证，前端逐一上传后批量确认 - -**请求体** `文件夹上传初始化请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryCode` | `string` | 是 | 分类编码 | -| `files` | `文件夹上传文件项[]` | 是 | 文件列表 | -|   `contentType` | `string` | 是 | 文件MIME类型 | -|   `fileSize` | `long` | 是 | 文件大小(字节) | -|   `filename` | `string` | 是 | 文件名 | -|   `folderPath` | `string` | 是 | 文件所在文件夹路径（与folderPaths中的路径对应） | -|   `materialName` | `string` | | 素材名称 | -|   `md5` | `string` | 是 | 文件MD5 | -| `folderPaths` | `string[]` | 是 | 文件夹路径列表（如 ["999", "999/888"]） | - -**响应** `统一响应结果«文件夹上传初始化结果»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `文件夹上传初始化结果` | | 响应数据 | -|   `fileTokens` | `文件上传凭证项[]` | | 各文件的上传凭证列表 | -|     `bucket` | `string` | | OSS Bucket名称 | -|     `error` | `string` | | 错误信息（该文件获取凭证失败时） | -|     `filename` | `string` | | 文件名 | -|     `folderPath` | `string` | | 文件夹路径 | -|     `instantUpload` | `boolean` | | 是否秒传（文件已存在） | -|     `materialId` | `string` | | 素材ID | -|     `ossKey` | `string` | | OSS对象Key | -|     `region` | `string` | | OSS Region | -|     `stsToken` | `STS临时凭证信息` | | STS临时凭证 | -|     `uploadHeaders` | `object` | | 上传请求头 | -|     `uploadMethod` | `string` | | 上传方式: PUT/POST | -|     `uploadUrl` | `string` | | 上传URL | -|   `folderCategoryMap` | `object` | | 文件夹路径 → 子分类ID 映射 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/upload/token - -**获取上传凭证** - -上传素材第一步：获取OSS预签名URL和凭证。前端使用凭证直传OSS后调用确认上传。支持基于角色的分类权限校验 - -**请求体** `素材上传令牌请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryCode` | `string` | 是 | 分类编码 | -| `contentType` | `string` | 是 | 文件MIME类型 | -| `fileSize` | `long` | 是 | 文件大小(字节) | -| `filename` | `string` | 是 | 文件名 | -| `materialName` | `string` | | 素材名称 | -| `md5` | `string` | 是 | 文件MD5 | -| `subCategoryId` | `long` | | 子分类ID（文件夹上传时使用） | - -**响应** `统一响应结果«素材上传令牌信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材上传令牌信息` | | 响应数据 | -|   `bucket` | `string` | | OSS Bucket名称 | -|   `contentType` | `string` | | 上传时必须使用的Content-Type（与预签名URL签名一致） | -|   `expireAt` | `string` | | 过期时间 | -|   `fileId` | `string` | | 文件ID | -|   `instantUpload` | `boolean` | | 是否秒传 | -|   `material` | `素材信息` | | 秒传时返回的素材信息 | -|     `categoryCode` | `string` | | 分类编码 | -|     `categoryName` | `string` | | 分类名称 | -|     `categoryPath` | `string` | | 完整分类路径（如：攻略管理 / 999 / 888） | -|     `createdAt` | `string` | | 创建时间 | -|     `createdBy` | `string` | | 创建人ID | -|     `createdByName` | `string` | | 创建人姓名 | -|     `description` | `string` | | 素材描述 | -|     `fileId` | `string` | | 文件ID | -|     `fileName` | `string` | | 文件名 | -|     `fileSize` | `long` | | 文件大小(字节) | -|     `fileType` | `string` | | 文件类型 | -|     `imageHeight` | `int` | | 图片高度 | -|     `imageWidth` | `int` | | 图片宽度 | -|     `materialId` | `string` | | 素材ID | -|     `materialName` | `string` | | 素材名称 | -|     `ossUrl` | `string` | | OSS地址 | -|     `refCount` | `int` | | 引用次数 | -|     `subCategoryId` | `string` | | 子分类ID | -|     `subCategoryName` | `string` | | 子分类名称 | -|     `tags` | `素材标签信息[]` | | 标签列表 | -|     `thumbnailUrl` | `string` | | 缩略图地址 | -|   `materialId` | `string` | | 素材ID | -|   `ossKey` | `string` | | OSS对象Key | -|   `region` | `string` | | OSS Region | -|   `stsToken` | `STS临时凭证信息` | | STS临时凭证 | -|     `accessKeyId` | `string` | | AccessKey ID | -|     `accessKeySecret` | `string` | | AccessKey Secret | -|     `expiration` | `string` | | 过期时间 | -|     `securityToken` | `string` | | 安全令牌 | -|   `uploadMode` | `string` | | 上传模式: PRESIGNED_URL/STS_MULTIPART | -|   `uploadUrl` | `string` | | 上传URL | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/material/{materialId} - -**素材详情** - -返回素材完整信息，包含文件名、URL、分类、标签、文件大小、上传者等。受角色分类权限限制。 - -**关联字典**： -- file_type：文件类型（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `materialId` | `integer` | | 素材ID | - -**响应** `统一响应结果«素材信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材信息` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `categoryPath` | `string` | | 完整分类路径（如：攻略管理 / 999 / 888） | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `string` | | 创建人ID | -|   `createdByName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 素材描述 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `imageHeight` | `int` | | 图片高度 | -|   `imageWidth` | `int` | | 图片宽度 | -|   `materialId` | `string` | | 素材ID | -|   `materialName` | `string` | | 素材名称 | -|   `ossUrl` | `string` | | OSS地址 | -|   `refCount` | `int` | | 引用次数 | -|   `subCategoryId` | `string` | | 子分类ID | -|   `subCategoryName` | `string` | | 子分类名称 | -|   `tags` | `素材标签信息[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdByName` | `string` | | 创建人姓名 | -|     `managed` | `boolean` | | 是否系统管理标签 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `string` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `useCount` | `int` | | 使用次数 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/material/{materialId} - -**更新素材信息** - -**关联字典**： -- material_tag：素材标签（编辑时选择标签） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `materialId` | `integer` | | 素材ID | - -**请求体** `更新素材请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryCode` | `string` | | 分类编码 | -| `description` | `string` | | 素材描述 | -| `materialName` | `string` | | 素材名称 | -| `subCategoryId` | `long` | | 子分类ID（0表示清除子分类） | - -**响应** `统一响应结果«素材信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材信息` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `categoryPath` | `string` | | 完整分类路径（如：攻略管理 / 999 / 888） | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `string` | | 创建人ID | -|   `createdByName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 素材描述 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `imageHeight` | `int` | | 图片高度 | -|   `imageWidth` | `int` | | 图片宽度 | -|   `materialId` | `string` | | 素材ID | -|   `materialName` | `string` | | 素材名称 | -|   `ossUrl` | `string` | | OSS地址 | -|   `refCount` | `int` | | 引用次数 | -|   `subCategoryId` | `string` | | 子分类ID | -|   `subCategoryName` | `string` | | 子分类名称 | -|   `tags` | `素材标签信息[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdByName` | `string` | | 创建人姓名 | -|     `managed` | `boolean` | | 是否系统管理标签 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `string` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `useCount` | `int` | | 使用次数 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/material/{materialId} - -**删除素材** - -删除素材记录。如果素材存在引用关系（被景区、酒店等使用），则不允许删除 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `materialId` | `integer` | | 素材ID | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/material/{materialId}/refs - -**查看素材引用记录** - -查看素材被哪些业务实体引用（如景区封面、酒店轮播图等），用于判断素材是否可安全删除 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `materialId` | `integer` | | 素材ID | - -**响应** `统一响应结果«List«素材引用信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材引用信息[]` | | 响应数据 | -|   `bizId` | `string` | | 业务ID | -|   `bizName` | `string` | | 业务名称 | -|   `bizType` | `string` | | 业务类型 | -|   `bizTypeName` | `string` | | 业务类型名称 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdByName` | `string` | | 创建人姓名 | -|   `id` | `string` | | 引用ID | -|   `materialId` | `string` | | 素材ID | -|   `usageType` | `string` | | 用途类型 | -|   `usageTypeName` | `string` | | 用途类型名称 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/material/{materialId}/tags - -**更新素材标签** - -全量替换单个素材的标签，传入新的标签ID列表 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `materialId` | `integer` | | 素材ID | - -**请求体** `更新素材标签请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagIds` | `string[]` | 是 | 标签ID列表 | - -**响应** `统一响应结果«Void»` - ---- diff --git a/2026-03/17_1009/hl-monitor-service.md b/2026-03/17_1009/hl-monitor-service.md deleted file mode 100644 index 188a26a..0000000 --- a/2026-03/17_1009/hl-monitor-service.md +++ /dev/null @@ -1,553 +0,0 @@ -# 监控服务 API 文档 - -**服务**: `hl-monitor-service` -**接口总数**: 18 - -## 目录 - -- **MySQL监控** (3 个接口) -- **Redis监控** (1 个接口) -- **RocketMQ监控** (3 个接口) -- **企微审批日志** (2 个接口) -- **操作日志** (2 个接口) -- **数据清理** (1 个接口) -- **服务监控** (1 个接口) -- **消息通知日志** (2 个接口) -- **登录日志** (1 个接口) -- **错误日志** (2 个接口) - ---- - -## MySQL监控 - -### `GET` /admin/monitor/mysql - -**MySQL实时监控数据** - -返回MySQL实时状态：连接数、QPS、缓冲池命中率、线程状态、慢查询计数等核心指标 - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/mysql/slow-queries - -**慢SQL查询统计** - -仅超级管理员可操作。查询慢SQL统计信息，返回执行时间最长的SQL语句及其执行次数、平均耗时等 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `limit` | `integer(int32)` | | 返回条数 | | -| `type` | `string` | | 查询类型 | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/mysql/tables - -**表空间列表** - -查询各数据库表的空间占用情况，包含数据大小、索引大小、行数等信息。可指定schema筛选，仅允许查询hl_前缀的数据库 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `schema` | `string` | | 数据库名 | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## Redis监控 - -### `GET` /admin/monitor/redis - -**Redis实时监控数据** - -返回Redis实时状态：内存使用量、连接数、Key数量、命中率、每秒命令数等核心指标 - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## RocketMQ监控 - -### `GET` /admin/monitor/rocketmq - -**RocketMQ概览** - -返回RocketMQ集群状态：Broker状态、Topic数量、消息积压量、生产者/消费者连接数等核心指标 - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/rocketmq/consumer-groups - -**消费者组统计** - -返回各消费者组的消费进度、积压量和在线消费者实例信息 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/rocketmq/topics - -**Topic统计** - -返回各Topic的消息量、最新偏移量和消费进度等信息 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## 企微审批日志 - -### `GET` /admin/monitor/approval-logs - -**审批日志分页查询** - -查询企微OA审批流程记录，支持按审批状态(1-审批中/2-已通过/3-已驳回/4-已撤销)、申请人、模板名称筛选 - -**关联字典**： -- approval_sp_status：审批状态（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `applyUserName` | `string` | | 申请人姓名 | | -| `endTime` | `string` | | 结束时间 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `spName` | `string` | | 审批模板名称 | | -| `spStatus` | `integer(int32)` | | 审批状态 | | -| `startTime` | `string` | | 开始时间 | | - -**响应** `统一响应结果«分页结果«审批日志»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«审批日志»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `审批日志[]` | | 数据列表 | -|     `applyData` | `string` | | 申请表单数据(JSON) | -|     `applyTime` | `string` | | 申请时间 | -|     `applyUserId` | `string` | | 申请人企微UserID | -|     `applyUserName` | `string` | | 申请人姓名 | -|     `approvalLogId` | `long` | | 审批日志ID | -|     `approvalNodes` | `string` | | 审批节点详情(JSON) | -|     `createdAt` | `string` | | 创建时间 | -|     `notifyNodes` | `string` | | 抄送节点详情(JSON) | -|     `spName` | `string` | | 审批模板名称 | -|     `spStatus` | `int` | | 审批状态: 1-审批中, 2-已通过, 3-已驳回, 4-已撤销, 6-通过后撤销, 7-已删除 | -|     `templateId` | `string` | | 审批模板ID | -|     `thirdNo` | `string` | | 审批编号 | -|     `updatedAt` | `string` | | 更新时间 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/approval-logs/{id} - -**审批日志详情** - -**关联字典**： -- approval_sp_status：审批状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 日志ID | - -**响应** `统一响应结果«审批日志»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `审批日志` | | 响应数据 | -|   `applyData` | `string` | | 申请表单数据(JSON) | -|   `applyTime` | `string` | | 申请时间 | -|   `applyUserId` | `string` | | 申请人企微UserID | -|   `applyUserName` | `string` | | 申请人姓名 | -|   `approvalLogId` | `long` | | 审批日志ID | -|   `approvalNodes` | `string` | | 审批节点详情(JSON) | -|   `createdAt` | `string` | | 创建时间 | -|   `notifyNodes` | `string` | | 抄送节点详情(JSON) | -|   `spName` | `string` | | 审批模板名称 | -|   `spStatus` | `int` | | 审批状态: 1-审批中, 2-已通过, 3-已驳回, 4-已撤销, 6-通过后撤销, 7-已删除 | -|   `templateId` | `string` | | 审批模板ID | -|   `thirdNo` | `string` | | 审批编号 | -|   `updatedAt` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -## 操作日志 - -### `GET` /admin/monitor/operation-logs - -**操作日志分页查询** - -查询管理员的操作记录，支持按模块、管理员、状态、时间范围筛选。记录包含请求参数、响应结果和耗时信息 - -**关联字典**： -- operation_log_status：操作状态（列表筛选+显示，0=成功/1=失败） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `adminId` | `integer(int64)` | | 管理员ID | | -| `endTime` | `string` | | 结束时间 | | -| `module` | `string` | | 模块名称 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `startTime` | `string` | | 开始时间 | | -| `status` | `integer(int32)` | | 状态 | | - -**响应** `统一响应结果«分页结果«操作日志»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«操作日志»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `操作日志[]` | | 数据列表 | -|     `adminId` | `long` | | 管理员ID | -|     `adminName` | `string` | | 管理员名称 | -|     `createdAt` | `string` | | 创建时间 | -|     `description` | `string` | | 操作描述 | -|     `duration` | `int` | | 耗时(毫秒) | -|     `errorMsg` | `string` | | 错误信息 | -|     `ipAddress` | `string` | | IP地址 | -|     `module` | `string` | | 操作模块 | -|     `operationLogId` | `long` | | 操作日志ID | -|     `requestMethod` | `string` | | 请求方法 | -|     `requestParams` | `string` | | 请求参数(JSON) | -|     `requestUrl` | `string` | | 请求URL | -|     `responseCode` | `int` | | 响应状态码 | -|     `responseMsg` | `string` | | 响应消息 | -|     `serviceName` | `string` | | 服务名称 | -|     `status` | `int` | | 状态: 0-成功, 1-失败 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/operation-logs/{id} - -**操作日志详情** - -返回单条操作日志的完整信息，包含操作模块、操作描述、请求参数、响应结果、操作耗时、操作人信息、IP地址等。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 日志ID | - -**响应** `统一响应结果«操作日志»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `操作日志` | | 响应数据 | -|   `adminId` | `long` | | 管理员ID | -|   `adminName` | `string` | | 管理员名称 | -|   `createdAt` | `string` | | 创建时间 | -|   `description` | `string` | | 操作描述 | -|   `duration` | `int` | | 耗时(毫秒) | -|   `errorMsg` | `string` | | 错误信息 | -|   `ipAddress` | `string` | | IP地址 | -|   `module` | `string` | | 操作模块 | -|   `operationLogId` | `long` | | 操作日志ID | -|   `requestMethod` | `string` | | 请求方法 | -|   `requestParams` | `string` | | 请求参数(JSON) | -|   `requestUrl` | `string` | | 请求URL | -|   `responseCode` | `int` | | 响应状态码 | -|   `responseMsg` | `string` | | 响应消息 | -|   `serviceName` | `string` | | 服务名称 | -|   `status` | `int` | | 状态: 0-成功, 1-失败 | -| `message` | `string` | | 响应消息 | - ---- - -## 数据清理 - -### `POST` /admin/monitor/data-retention/cleanup - -**手动触发数据清理** - -仅超级管理员可操作。按数据保留策略清理过期日志（操作日志/错误日志/通知日志等），返回各类型清理的记录数 - -**响应** `统一响应结果«Map«string,int»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## 服务监控 - -### `GET` /admin/monitor/services - -**微服务列表和健康状态** - -从Nacos注册中心获取所有微服务的实例列表和健康状态，包含IP、端口、注册时间和健康检查结果 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## 消息通知日志 - -### `GET` /admin/monitor/notification-logs - -**消息通知日志分页查询** - -查询各渠道（短信/站内信/企微/公众号）的通知发送记录，支持按通知类型、用户、发送状态筛选 - -**关联字典**： -- notification_send_status：发送状态（列表筛选+显示，0=待发送/1=成功/2=失败） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `endTime` | `string` | | 结束时间 | | -| `notificationType` | `string` | | 通知类型 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `sendStatus` | `integer(int32)` | | 发送状态 | | -| `startTime` | `string` | | 开始时间 | | -| `userName` | `string` | | 用户名 | | - -**响应** `统一响应结果«分页结果«通知日志»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«通知日志»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `通知日志[]` | | 数据列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `externalUserId` | `string` | | 外部联系人ID | -|     `externalUserName` | `string` | | 外部联系人姓名 | -|     `failReason` | `string` | | 失败原因 | -|     `messageContent` | `string` | | 消息内容 | -|     `notificationLogId` | `long` | | 通知日志ID | -|     `notificationType` | `string` | | 通知类型: ADD_EXTERNAL_CONTACT/DEL_FOLLOW_USER/DEL_EXTERNAL_CONTACT | -|     `sendStatus` | `int` | | 发送状态: 0-成功, 1-失败, 2-已过滤 | -|     `serviceName` | `string` | | 来源服务名称 | -|     `userId` | `string` | | 员工企微UserID | -|     `userName` | `string` | | 员工姓名 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/notification-logs/{id} - -**消息通知日志详情** - -返回单条通知发送日志的完整信息，包含通知类型、接收用户、发送渠道、发送状态、失败原因（如有）、消息内容等。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 日志ID | - -**响应** `统一响应结果«通知日志»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `通知日志` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `externalUserId` | `string` | | 外部联系人ID | -|   `externalUserName` | `string` | | 外部联系人姓名 | -|   `failReason` | `string` | | 失败原因 | -|   `messageContent` | `string` | | 消息内容 | -|   `notificationLogId` | `long` | | 通知日志ID | -|   `notificationType` | `string` | | 通知类型: ADD_EXTERNAL_CONTACT/DEL_FOLLOW_USER/DEL_EXTERNAL_CONTACT | -|   `sendStatus` | `int` | | 发送状态: 0-成功, 1-失败, 2-已过滤 | -|   `serviceName` | `string` | | 来源服务名称 | -|   `userId` | `string` | | 员工企微UserID | -|   `userName` | `string` | | 员工姓名 | -| `message` | `string` | | 响应消息 | - ---- - -## 登录日志 - -### `GET` /admin/monitor/login-logs - -**登录日志分页查询** - -查询管理员登录记录（代理到user-service），包含登录IP、设备信息、登录方式和登录结果 - -**关联字典**： -- login_status：登录状态（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `adminId` | `integer(int64)` | | 管理员ID | | -| `endTime` | `string` | | 结束时间 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `startTime` | `string` | | 开始时间 | | -| `status` | `string` | | 状态 | | - -**响应** `统一响应结果«object»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## 错误日志 - -### `GET` /admin/monitor/error-logs - -**错误日志分页查询** - -查询各微服务的异常记录，支持按服务名称、异常类名、时间范围筛选。堆栈信息仅保留com.hulalv包内的调用帧 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `endTime` | `string` | | 结束时间 | | -| `exceptionClass` | `string` | | 异常类名 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `serviceName` | `string` | | 服务名称 | | -| `startTime` | `string` | | 开始时间 | | - -**响应** `统一响应结果«分页结果«错误日志»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«错误日志»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `错误日志[]` | | 数据列表 | -|     `adminId` | `long` | | 管理员ID | -|     `createdAt` | `string` | | 创建时间 | -|     `errorLogId` | `long` | | 错误日志ID | -|     `exceptionClass` | `string` | | 异常类名 | -|     `exceptionMessage` | `string` | | 异常消息 | -|     `ipAddress` | `string` | | IP地址 | -|     `requestMethod` | `string` | | 请求方法 | -|     `requestParams` | `string` | | 请求参数(JSON) | -|     `requestUrl` | `string` | | 请求URL | -|     `serviceName` | `string` | | 服务名称 | -|     `stackTrace` | `string` | | 堆栈跟踪 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/error-logs/{id} - -**错误日志详情** - -返回单条错误日志的完整信息，包含异常类名、错误消息、过滤后的堆栈信息（仅com.hulalv包内调用帧）、请求URL、请求参数等。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 日志ID | - -**响应** `统一响应结果«错误日志»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `错误日志` | | 响应数据 | -|   `adminId` | `long` | | 管理员ID | -|   `createdAt` | `string` | | 创建时间 | -|   `errorLogId` | `long` | | 错误日志ID | -|   `exceptionClass` | `string` | | 异常类名 | -|   `exceptionMessage` | `string` | | 异常消息 | -|   `ipAddress` | `string` | | IP地址 | -|   `requestMethod` | `string` | | 请求方法 | -|   `requestParams` | `string` | | 请求参数(JSON) | -|   `requestUrl` | `string` | | 请求URL | -|   `serviceName` | `string` | | 服务名称 | -|   `stackTrace` | `string` | | 堆栈跟踪 | -| `message` | `string` | | 响应消息 | - ---- diff --git a/2026-03/17_1009/hl-mp-service.md b/2026-03/17_1009/hl-mp-service.md deleted file mode 100644 index 720fbe0..0000000 --- a/2026-03/17_1009/hl-mp-service.md +++ /dev/null @@ -1,3634 +0,0 @@ -# 小程序聚合服务 API 文档 - -**服务**: `hl-mp-service` -**接口总数**: 132 - -## 目录 - -- **C端 - 产品接口** (8 个接口) -- **C端 - 公共接口** (6 个接口) -- **C端 - 出行人接口** (6 个接口) -- **C端 - 前端配置接口** (2 个接口) -- **C端 - 发票接口** (4 个接口) -- **C端 - 合同接口** (5 个接口) -- **C端 - 天气接口** (3 个接口) -- **C端 - 字典接口** (1 个接口) -- **C端 - 定制师接口** (5 个接口) -- **C端 - 徽章接口** (1 个接口) -- **C端 - 心愿单接口** (2 个接口) -- **C端 - 探索接口** (5 个接口) -- **C端 - 搜索接口** (1 个接口) -- **C端 - 支付接口** (3 个接口) -- **C端 - 收藏接口** (6 个接口) -- **C端 - 攻略接口** (4 个接口) -- **C端 - 景区接口** (3 个接口) -- **C端 - 活动接口** (2 个接口) -- **C端 - 消息接口** (5 个接口) -- **C端 - 用户接口** (8 个接口) -- **C端 - 相册接口** (4 个接口) -- **C端 - 行程接口** (4 个接口) -- **C端 - 订单接口** (11 个接口) -- **C端 - 评价接口** (13 个接口) -- **C端 - 足迹接口** (4 个接口) -- **C端 - 轮播图接口** (1 个接口) -- **C端 - 退款接口** (7 个接口) -- **C端 - 通用点赞** (3 个接口) -- **C端 - 酒店接口** (2 个接口) -- **C端 - 餐厅接口** (2 个接口) -- **C端 - 首页接口** (1 个接口) - ---- - -## C端 - 产品接口 - -### `GET` /mp/product/batch/{batchId}/combos - -**GROUP批次套餐列表** - -返回指定批次的所有套餐（名称、人数组合、价格、库存） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `batchId` | `integer` | | 批次ID | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/product/lines - -**产品线列表** - -返回所有已启用的产品线，用于小程序首页或筛选栏展示 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/product/list - -**产品列表** - -分页查询已上架产品，支持按关键词、产品类型(CORE/ROUTE/CUSTOM/GROUP)、季节、天数、目的地、产品线筛选和排序 - -**关联字典（BFF透传）**： -- product_type：产品类型（列表筛选+显示） -- product_status：产品状态（透传自product-service） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `destination` | `string` | | 目的地 | | -| `keyword` | `string` | | 搜索关键词 | | -| `lineId` | `string` | | 产品线ID | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `productType` | `string` | | 产品类型：CORE/ROUTE/CUSTOM/GROUP | | -| `season` | `string` | | 季节 | | -| `sortBy` | `string` | | 排序字段 | | -| `sortDir` | `string` | | 排序方向 | | -| `tripDays` | `integer(int32)` | | 天数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/product/{productId} - -**产品详情（聚合收藏状态）** - -聚合流程：获取产品详情 → 并行查询收藏状态 → 异步记录足迹 → 返回聚合数据。支持未登录访问（不返回收藏状态） - -**关联字典（BFF透传）**： -- product_type：产品类型（显示） -- product_status：产品状态（透传自product-service） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `productId` | `integer` | | 产品ID | - -**响应** `统一响应结果«C端产品详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `C端产品详情` | | 响应数据 | -|   `chatMessages` | `Map«string,object»[]` | | 群聊最近消息（来自会话存档） | -|   `earliestBookingDate` | `string` | | 最早可订日期(如 2026-07-15) | -|   `earlyBirdDiscount` | `number` | | 早鸟优惠金额(元/人) | -|   `earlyBirdPlanName` | `string` | | 早鸟计划名称 | -|   `isFavorited` | `boolean` | | 是否已收藏（null表示未登录） | -|   `participantFamilyCount` | `int` | | 参与家庭数 | -|   `product` | `object` | | 产品详情（来自product-service） | -|   `reviewStats` | `object` | | 评价统计数据 | -|   `topLikedReview` | `object` | | 最高点赞评价 | -|   `topRatedReview` | `object` | | 最高评分评价 | -|   `totalSold` | `int` | | 已购人数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/product/{productId}/batch-calendar - -**GROUP批次日历** - -返回可报名批次列表（出发日期、剩余名额等），仅ENROLLING和CONFIRMED状态 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `productId` | `integer` | | 产品ID | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/product/{productId}/group-quote - -**GROUP报价** - -返回指定批次的各套餐报价（totalSellPrice） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `productId` | `integer` | | 产品ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `batchId` | `integer(int64)` | | 批次ID | | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/product/{productId}/price-calendar - -**价格日历** - -返回产品指定日期范围内的每日价格，用于日历组件展示。不传日期时默认返回未来一个月 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `productId` | `integer` | | 产品ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `endDate` | `string` | | 结束日期 | | -| `startDate` | `string` | | 开始日期 | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/product/{productId}/quote - -**报价计算（含早鸟优惠）** - -报价流程：传入出发日期+人数 → 价格日历计算基础报价（与下单一致） → 匹配早鸟优惠方案 → 返回明细报价+优惠信息。 - -支付方式说明： -- FULL: 全额支付，需一次性付清全部金额 -- DEPOSIT: 定金+尾款，先付定金（比例由产品配置），出行前补齐尾款 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `productId` | `integer` | | 产品ID | - -**请求体** `产品报价请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `adultCount` | `int` | 是 | 成人数量 | -| `babyCount` | `int` | | 婴儿数量 | -| `childCount` | `int` | | 儿童数量 | -| `childNeedBed` | `boolean` | | 儿童是否需要床位 | -| `departureDate` | `string` | 是 | 出发日期 | -| `youngChildCount` | `int` | | 幼儿数量 | - -**响应** `统一响应结果«产品报价结果»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `产品报价结果` | | 响应数据 | -|   `adultSellPrice` | `number` | | 成人单价 | -|   `babySellPrice` | `number` | | 幼童单价（固定价） | -|   `childSellPrice` | `number` | | 儿童单价 | -|   `childWithBedFee` | `number` | | 儿童加床费 | -|   `depositPayment` | `定金支付选项` | | 定金支付信息（仅paymentMode=DEPOSIT时有值） | -|     `balanceAmount` | `number` | | 尾款金额（出行前需付） | -|     `depositAmount` | `number` | | 定金金额（首次需付） | -|     `depositRatio` | `int` | | 定金比例(%) | -|     `description` | `string` | | 说明 | -|   `earlyBirdDiscount` | `早鸟优惠信息` | | 早鸟优惠信息，无优惠时为null | -|     `discountAmount` | `number` | | 优惠金额 | -|     `minPeople` | `int` | | 最低人数要求 | -|     `planId` | `long` | | 优惠方案ID | -|     `planName` | `string` | | 优惠方案名称 | -|   `finalPrice` | `number` | | 最终价（早鸟优惠后） | -|   `fullPayment` | `全额支付选项` | | 全额支付信息 | -|     `amount` | `number` | | 应付金额 | -|     `description` | `string` | | 说明 | -|   `grandTotalSellPrice` | `number` | | 总售价（优惠前） | -|   `paymentMode` | `string` | | 支付方式: FULL(全额支付) / DEPOSIT(定金+尾款) | -|   `totalAdultSellPrice` | `number` | | 成人小计 | -|   `totalBabySellPrice` | `number` | | 幼童小计 | -|   `totalChildSellPrice` | `number` | | 儿童小计 | -|   `totalYoungChildSellPrice` | `number` | | 小童小计 | -|   `youngChildSellPrice` | `number` | | 小童单价（儿童价×折扣比例） | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 公共接口 - -### `GET` /mp/common/agreement/list - -**协议列表** - -获取所有已上线的协议列表（不含内容，仅含类型、标题、版本） - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/common/agreement/{type} - -**获取协议文本** - -获取指定类型的协议文本（如隐私政策、用户协议），返回富文本内容 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `type` | `string` | 是 | 协议类型: privacy(隐私政策) / user(用户协议) | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/common/config - -**应用配置** - -获取应用全局配置信息 - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/common/contact - -**联系方式列表** - -获取有效的联系方式列表（电话/微信/邮箱等） - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/common/faq - -**FAQ列表** - -获取常见问题列表（按分类分组） - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/common/feedback - -**提交反馈** - -提交用户反馈，支持文字内容和图片附件 - -**请求体** `提交反馈请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `contact` | `string` | | 联系方式 | -| `content` | `string` | 是 | 反馈内容 | -| `images` | `string[]` | | 图片URL列表 | - -**响应** `统一响应结果«Void»` - ---- - -## C端 - 出行人接口 - -### `GET` /mp/user/traveler - -**出行人列表** - -返回当前用户的所有出行人列表。如果用户已完善实名信息，列表中会自动包含一条「本人」虚拟记录(travelerId=0) - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/user/traveler - -**添加出行人** - -添加常用出行人信息（姓名/证件/联系方式等），下单时可快速选择。单个用户最多50个出行人 - -**请求体** `修改)` - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/user/traveler/{id} - -**出行人详情** - -获取单个出行人的完整信息（姓名、证件信息、联系方式等）。 - -**权限**：需登录，仅能查看自己的出行人。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 出行人ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /mp/user/traveler/{id} - -**更新出行人** - -修改出行人信息，支持部分更新（只传需要修改的字段）。已关联订单的出行人修改不影响历史订单记录。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 出行人ID | - -**请求体** `修改)` - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /mp/user/traveler/{id} - -**删除出行人** - -删除常用出行人记录。默认出行人不可删除，需先取消默认后再删除。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 出行人ID | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /mp/user/traveler/{id}/default - -**设为默认出行人** - -设为默认出行人后，下单时自动作为第一个出行人。每个用户只能有一个默认出行人 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 出行人ID | - -**响应** `统一响应结果«Void»` - ---- - -## C端 - 前端配置接口 - -### `GET` /mp/config - -**获取所有非敏感前端配置** - -返回所有非SECRET类型的前端配置项（如主题色、客服电话、版本号等）。不含敏感配置，可安全传输给小程序端。 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/config/group/{group} - -**按分组获取非敏感前端配置** - -按配置分组获取前端配置项，如UI分组、功能开关分组等。用于小程序按需加载特定分组的配置。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `group` | `string` | | 配置分组 | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 发票接口 - -### `POST` /mp/invoice/apply - -**申请开票** - -开票流程：订单完成后 → 填写发票信息(抬头/税号/类型) → 提交开票申请 → 管理员处理 → 发送电子发票 - -**请求体** `发票申请请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `email` | `string` | | 接收邮箱 | -| `invoiceTitle` | `string` | 是 | 发票抬头 | -| `invoiceType` | `string` | 是 | 发票类型: PERSONAL(个人)/COMPANY(企业) | -| `orderId` | `string` | 是 | 订单ID | -| `taxpayerId` | `string` | | 纳税人识别号（企业发票必填） | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/invoice/order/{orderId} - -**通过订单ID查询发票** - -查询指定订单的发票信息，如果订单未开票则返回null - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/invoice/{id} - -**发票详情** - -获取发票的完整信息，包含开票状态、发票抬头、税号、金额、电子发票文件链接等 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 发票ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/invoice/{invoiceId}/reissue - -**发票换开** - -对已开发票申请换开（修改抬头/税号等），原发票作废后重新开具新发票 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `invoiceId` | `integer` | | 发票ID | - -**请求体** `发票换开请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `email` | `string` | | 接收邮箱 | -| `invoiceTitle` | `string` | 是 | 发票抬头 | -| `taxNumber` | `string` | | 纳税人识别号（企业发票必填） | -| `titleType` | `string` | 是 | 抬头类型: PERSONAL(个人)/COMPANY(企业) | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 合同接口 - -### `GET` /mp/contract/by-order/{orderId} - -**按订单查合同** - -返回订单关联的最新有效合同（非作废） - -**关联字典（BFF透传）**： -- contract_status：合同状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/contract/by-order/{orderId}/all - -**按订单查所有合同** - -返回订单关联的所有有效合同（TOUR+INSURANCE各一条） - -**关联字典（BFF透传）**： -- contract_status：合同状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/contract/list - -**合同列表** - -**关联字典（BFF透传）**： -- contract_status：合同状态（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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` | | 响应消息 | - ---- - -### `POST` /mp/contract/{contractId}/resend-sms - -**重新发送合同签署短信** - -重新向出行人发送合同签署短信通知，适用于出行人未收到短信或短信过期的场景。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `contractId` | `integer` | | 合同ID | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/contract/{id} - -**合同详情** - -返回合同基本信息、签署状态、出行人签署详情及合同文件下载链接 - -**关联字典（BFF透传）**： -- contract_status：合同状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 合同ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 天气接口 - -### `GET` /mp/weather/forecast - -**获取指定城市天气预报** - -通过高德天气API查询指定城市未来3天的天气预报信息 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `city` | `string` | | 城市名称 | | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/weather/itinerary/{orderId} - -**获取订单行程天气** - -根据订单行程中的目的地城市，批量查询每日天气信息，用于行程详情页展示 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/weather/live - -**获取指定城市实况天气** - -通过高德天气API查询指定城市的实时天气（温度、湿度、风向等） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `city` | `string` | | 城市名称 | | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 字典接口 - -### `GET` /dict/all - -**获取所有字典数据** - -获取系统全部字典数据（按字典类型分组），用于小程序端的下拉选项、枚举映射等。建议前端缓存此数据 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 定制师接口 - -### `GET` /mp/designer - -**定制师列表(含真实产品数和评分，综合排序)** - -获取定制师列表，聚合层会补充每个定制师的真实产品数量和评价评分。按综合排序（评分>路线数>咨询人数），用于小程序定制师推荐页。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `limit` | `integer(int32)` | | 每页条数 | | -| `page` | `integer(int32)` | | 页码 | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/designer/featured - -**推荐定制师(综合排序第一名)** - -获取综合排序排名第一的定制师信息（含产品数和评分），用于首页推荐定制师卡片展示。 - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/designer/{id} - -**定制师详情(含产品数量和评分)** - -获取定制师完整个人信息，聚合层会补充该定制师的已发布产品数量和综合评分，用于定制师个人主页展示。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 定制师ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/designer/{id}/products - -**定制师已发布产品列表** - -**关联字典（BFF透传）**： -- product_type：产品类型（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 定制师ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/designer/{id}/reviews - -**定制师产品评价列表** - -**关联字典（BFF透传）**： -- rating_level：评价等级（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 定制师ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 徽章接口 - -### `GET` /mp/badge - -**获取徽章数据** - -返回用户的徽章统计（未读消息数、待办事项数等），用于「我的」页面角标展示 - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 心愿单接口 - -### `GET` /mp/wish - -**心愿单列表** - -返回当前用户的心愿单列表，按创建时间倒序排列 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/wish - -**创建心愿** - -创建旅行心愿，描述想去的地方和时间偏好，定制师可据此推荐产品 - -**请求体** `创建心愿单请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `notes` | `string` | | 备注 | -| `productId` | `string` | 是 | 产品ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 探索接口 - -### `GET` /mp/explore/list - -**探索列表** - -获取已启用的探索分类列表（图文攻略内容），支持综合/最新/最热排序，分页返回。用于小程序探索频道首页瀑布流展示。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `sortType` | `string` | | 排序方式：comprehensive/newest/hottest | | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/explore/{id} - -**探索详情** - -自动增加浏览量，已登录时返回点赞/收藏状态 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 探索分类ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/explore/{id}/favorite - -**切换收藏** - -对探索内容收藏/取消收藏，返回当前收藏状态（true=已收藏）。收藏后可在'我的收藏'中查看。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 探索分类ID | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/explore/{id}/like - -**切换点赞** - -对探索内容点赞/取消点赞，返回当前点赞状态（true=已点赞）。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 探索分类ID | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/explore/{id}/view - -**浏览+1** - -增加探索内容的浏览计数。前端进入探索详情页时调用，无需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 探索分类ID | - -**响应** `统一响应结果«Void»` - ---- - -## C端 - 搜索接口 - -### `GET` /mp/search - -**搜索产品** - -按关键词搜索已上架产品（匹配产品名称和描述），支持按产品类型进一步筛选 - -**关联字典（BFF透传）**： -- product_type：产品类型（筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `keyword` | `string` | | 搜索关键词 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `productType` | `string` | | 产品类型：CORE/ROUTE/CUSTOM/GROUP | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 支付接口 - -### `POST` /mp/payment/prepay - -**发起支付** - -支付流程：选择支付方式(JSAPI/H5) → 调用微信支付API → 返回支付参数 → 前端调起微信支付 - -**关联字典（BFF透传）**： -- payment_status：支付状态（返回字段） - -**请求体** `支付预下单请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `clientIp` | `string` | | 客户端IP（H5支付必填） | -| `orderId` | `string` | 是 | 订单ID | -| `tradeType` | `string` | 是 | 支付方式: JSAPI(小程序支付)/H5(H5支付) | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/payment/status/{orderId} - -**查询支付状态** - -**关联字典（BFF透传）**： -- payment_status：支付状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/payment/transactions/{orderId} - -**订单交易记录列表** - -**关联字典（BFF透传）**： -- payment_status：支付状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 收藏接口 - -### `GET` /mp/user/favorite - -**收藏列表（含资源摘要）** - -分页查询收藏列表，聚合层会补充每个收藏项对应资源的摘要信息（名称、封面图、价格等）。支持按目标类型筛选。 - -**权限**：需登录。 - -**关联字典**： -- favorite_resource_type：收藏资源类型（PRODUCT/SCENIC/RESTAURANT/ACTIVITY） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `targetType` | `string` | | 目标类型筛选（字典：favorite_resource_type）：PRODUCT/SCENIC/RESTAURANT/ACTIVITY | | - -**响应** `统一响应结果«分页结果«收藏列表项（含资源摘要）»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«收藏列表项（含资源摘要）»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `收藏列表项（含资源摘要）[]` | | 数据列表 | -|     `coverUrl` | `string` | | 封面图URL | -|     `createdAt` | `string` | | 收藏时间 | -|     `favoriteId` | `string` | | 收藏记录ID | -|     `name` | `string` | | 资源名称 | -|     `tags` | `string[]` | | 标签列表 | -|     `targetId` | `string` | | 目标资源ID | -|     `targetType` | `string` | | 目标类型（字典：favorite_resource_type） | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/user/favorite - -**添加收藏** - -将产品/景区/餐厅/活动加入收藏。同一目标重复收藏会返回已有收藏记录 - -**请求体** `收藏请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `targetId` | `string` | 是 | 目标资源ID | -| `targetType` | `string` | 是 | 目标类型（字典：favorite_resource_type） | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /mp/user/favorite/batch - -**批量删除收藏** - -批量删除多条收藏记录，传入收藏记录ID列表。用于收藏管理页面的批量操作。 - -**权限**：需登录，仅能删除自己的收藏。 - -**请求体** `long[]` - -**响应** `统一响应结果«Void»` - ---- - -### `DELETE` /mp/user/favorite/by-target - -**按目标取消收藏** - -通过目标类型+目标ID取消收藏，适用于详情页点击取消收藏的场景（不需要知道收藏记录ID）。 - -**权限**：需登录。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `targetId` | `integer(int64)` | | 目标资源ID | | -| `targetType` | `string` | | 目标类型 | | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /mp/user/favorite/check - -**检查是否已收藏** - -检查当前用户是否已收藏指定资源，用于详情页收藏按钮状态显示。 - -**权限**：需登录。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `targetId` | `integer(int64)` | | 目标资源ID | | -| `targetType` | `string` | | 目标类型（字典：favorite_resource_type） | | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /mp/user/favorite/{id} - -**取消收藏** - -通过收藏记录ID取消收藏，适用于收藏列表页的删除操作。 - -**权限**：需登录，仅能删除自己的收藏。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 收藏记录ID | - -**响应** `统一响应结果«Void»` - ---- - -## C端 - 攻略接口 - -### `GET` /mp/wiki/article/{articleId} - -**文章详情** - -**关联字典（BFF透传）**： -- wiki_status：文章状态（返回字段） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | | 文章ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/wiki/categories - -**攻略分类列表** - -获取所有已启用的攻略分类，按排序值排列。用于小程序攻略频道的分类导航展示。 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/wiki/category/{categoryId}/articles - -**分类文章列表** - -分页查询指定攻略分类下已发布的文章列表，按发布时间倒序排列。用于攻略分类详情页。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryId` | `integer` | | 攻略分类ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/wiki/recommend-articles - -**推荐文章列表** - -获取编辑推荐的攻略文章列表（按推荐权重排序），用于首页或攻略频道的推荐位展示。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `limit` | `integer(int32)` | | 返回条数 | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 景区接口 - -### `GET` /mp/scenic/list - -**景区列表** - -分页查询已上架的景区列表，支持按关键词和城市筛选。聚合层透传resource-service的景区数据。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `city` | `string` | | 城市 | | -| `keyword` | `string` | | 关键词 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/scenic/{scenicId} - -**景区详情** - -获取景区完整信息（含季节素材、图文详情、价格等），自动注入静态地图图片URL用于详情页地图展示。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `scenicId` | `integer` | | 景区ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/scenic/{scenicId}/nearby - -**附近景区（地理+探索分类聚合）** - -聚合两个数据源：1.基于经纬度的地理位置附近景区（resource-service）；2.探索分类关联的景区（user-service）。去重合并后返回，用于景区详情页底部'附近推荐'展示。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `scenicId` | `integer` | | 景区ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `limit` | `integer(int32)` | | 返回条数 | | -| `radius` | `number(double)` | | 搜索半径(km) | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 活动接口 - -### `GET` /mp/activity/list - -**活动列表** - -分页查询已上架的活动列表，支持关键词和分类筛选。聚合层透传resource-service的活动数据给小程序前端。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `categoryCode` | `string` | | 分类 | | -| `keyword` | `string` | | 关键词 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/activity/{activityId} - -**活动详情** - -获取活动完整信息（含图文详情、价格等），自动注入静态地图图片URL用于详情页地图展示。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `activityId` | `integer` | | 活动ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 消息接口 - -### `GET` /mp/message/list - -**消息列表** - -消息列表，支持按分类筛选，按时间倒序分页返回 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `category` | `string` | | 消息分类筛选，不传返回全部 | | -| `page` | `integer(int32)` | | 页码，默认1 | | -| `pageSize` | `integer(int32)` | | 每页条数，默认20 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /mp/message/read-all - -**全部标记已读** - -将指定分类或全部消息标记为已读，不传category则全部已读 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `category` | `string` | | 消息分类，不传则将所有分类标记为已读 | | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /mp/message/summary - -**消息摘要** - -获取各分类的未读数量和最新一条消息，用于消息中心首页展示 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /mp/message/{id} - -**删除消息** - -删除单条消息 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | 是 | 消息ID | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /mp/message/{id}/read - -**标记已读** - -标记单条消息为已读 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | 是 | 消息ID | - -**响应** `统一响应结果«Void»` - ---- - -## C端 - 用户接口 - -### `DELETE` /mp/user/account - -**注销账号** - -注销后用户数据将被软删除，30天内可联系客服恢复 - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /mp/user/login - -**微信登录** - -登录流程：小程序wx.login获取code → 后端换取openid → 查找/创建用户 → 返回JWT令牌+needProfile标记 - -**请求体** `微信登录请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `string` | 是 | 微信授权code | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/user/login/sms - -**短信登录** - -登录流程：获取验证码 → 验证手机号+验证码 → 查找/创建用户 → 返回JWT令牌 - -**请求体** `短信验证码登录请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `string` | 是 | 验证码 | -| `phone` | `string` | 是 | 手机号 | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/user/logout - -**用户登出** - -清除用户登录状态和服务端缓存的令牌信息。登出后需重新登录获取新令牌。 - -**权限**：需登录。 - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /mp/user/ocr/idcard - -**身份证OCR识别** - -将身份证图片上传到OSS后，传入ossUrl进行OCR识别。返回姓名、身份证号、性别、民族等结构化数据，可用于自动填充出行人信息 - -**请求体** `身份证OCR识别请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `imgUrl` | `string` | 是 | 身份证图片的OSS地址 | - -**响应** `统一响应结果«Map«string,string»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/user/profile - -**获取用户信息** - -获取当前登录用户的个人资料，包含头像、昵称、手机号、实名信息等 - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /mp/user/profile - -**更新用户信息** - -更新当前用户的个人资料，支持部分更新（只传需要修改的字段）。首次完善资料时realName为必填 - -**请求体** `更新个人资料请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `avatar` | `string` | | 头像URL | -| `birthday` | `string` | | 生日 | -| `email` | `string` | | 邮箱 | -| `gender` | `int` | | 性别: 1=男, 2=女 | -| `nationality` | `string` | | 国籍 | -| `nickname` | `string` | | 昵称 | -| `phone` | `string` | | 手机号 | -| `realName` | `string` | | 真实姓名 | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/user/sms/send - -**发送短信验证码** - -向指定手机号发送登录验证码，有效期5分钟，60秒内不可重复发送 - -**请求体** `发送短信验证码请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `phone` | `string` | 是 | 手机号 | - -**响应** `统一响应结果«Void»` - ---- - -## C端 - 相册接口 - -### `GET` /mp/album/file/{albumFileId}/download-url - -**获取文件下载链接** - -获取文件的预签名下载URL，有效期有限 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `albumFileId` | `integer` | 是 | 相册文件ID | - -**响应** `统一响应结果«string»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `string` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/album/folder/{folderId}/files - -**文件夹下的文件列表** - -获取文件夹下的文件列表（分页），含图片和视频 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `folderId` | `integer` | 是 | 文件夹ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码，默认1 | | -| `size` | `integer(int32)` | | 每页数量，默认20 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/album/order/{orderId}/folders - -**订单的文件夹列表** - -获取订单下的相册文件夹列表 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | 是 | 订单ID | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/album/orders - -**有相册的订单列表** - -获取当前登录用户有相册的订单列表 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 行程接口 - -### `GET` /mp/trip/list - -**行程列表** - -获取当前登录用户的行程列表（已确认及进行中的订单对应的行程） - -**关联字典（BFF透传）**： -- order_status：订单/行程状态（显示） - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/trip/today - -**今日行程** - -获取今日行程（如果有正在进行中的行程），无行程时data为null - -**关联字典（BFF透传）**： -- order_status：订单/行程状态（显示） - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/trip/weather - -**天气查询** - -高德天气API代理，传入城市名称返回实时天气信息 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `city` | `string` | 是 | 城市名称，如「成都」「拉萨」 | | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/trip/{orderId} - -**行程详情** - -获取订单对应的行程详情，含每日行程节点信息（景点/酒店/餐厅等） - -**关联字典（BFF透传）**： -- order_status：订单/行程状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | 是 | 订单ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 订单接口 - -### `POST` /mp/order/bind-by-contact - -**绑定未绑定的订单** - -绑定流程：用户登录 → 完善个人资料 → 自动通过联系人手机号+姓名匹配 → 将userId=NULL的订单绑定到当前用户 - -**请求体** `通过联系人信息绑定订单请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `contactName` | `string` | 是 | 联系人姓名 | -| `contactPhone` | `string` | 是 | 联系人手机号 | - -**响应** `统一响应结果«int»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `int` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/count - -**各状态订单数量** - -统计当前用户各状态的订单数量，用于「我的」页面的订单状态角标展示 - -**关联字典（BFF透传）**： -- order_status：订单状态（状态分类统计） - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/order/create - -**创建订单** - -下单流程：选择产品 → 填写联系人/出行人信息 → 报价计算 → 创建订单 → 返回订单ID - -**请求体** `C端创建订单请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `adultCount` | `int` | | 成人数 | -| `babyCount` | `int` | | 幼童数 | -| `childCount` | `int` | | 儿童数 | -| `childNeedBed` | `boolean` | | 儿童是否需要床位 | -| `contactName` | `string` | 是 | 联系人姓名 | -| `contactPhone` | `string` | 是 | 联系人电话 | -| `customizerId` | `string` | | 定制师ID(通过分享链接下单时传入) | -| `departureDate` | `string` | | 出发日期(GROUP产品从团期获取，可不传) | -| `groupBatchId` | `string` | | 团期ID(GROUP产品必填) | -| `productId` | `string` | 是 | 产品ID | -| `remark` | `string` | | 备注 | -| `roomCount` | `int` | | 房间数(GROUP产品，默认1) | -| `sharerOpenid` | `string` | | 分享人微信openid（通过分享进入下单时传入，用于记录分享关系） | -| `travelers` | `出行人信息[]` | | 出行人列表 | -|   `birthday` | `string` | | 出生日期 | -|   `email` | `string` | | 电子邮箱 | -|   `emergencyContact` | `string` | | 紧急联系人 | -|   `emergencyPhone` | `string` | | 紧急联系电话 | -|   `gender` | `int` | | 性别（1=男, 2=女） | -|   `idCardNo` | `string` | | 证件号码 | -|   `idCardType` | `string` | | 证件类型 | -|   `name` | `string` | 是 | 出行人姓名 | -|   `nationality` | `string` | | 国籍 | -|   `phone` | `string` | | 手机号 | -|   `travelerType` | `string` | | 出行人类型（ADULT/CHILD/YOUNG_CHILD/BABY） | -| `youngChildCount` | `int` | | 小童数 | - -**响应** `统一响应结果«订单详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `订单详情` | | 响应数据 | -|   `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` | `Map«string,object»[]` | | 优惠列表 | -|   `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` | | 支付模式（FULL/DEPOSIT） | -|   `processStatus` | `string` | | 内部流程状态 | -|   `processStatusLabel` | `string` | | 内部流程状态标签 | -|   `productCoverUrl` | `string` | | 产品封面图URL | -|   `productId` | `long` | | 产品ID | -|   `productName` | `string` | | 产品名称 | -|   `productSnapshot` | `string` | | 产品快照JSON | -|   `productType` | `string` | | 产品类型（CORE/ROUTE/CUSTOM/GROUP） | -|   `readyAt` | `string` | | 就绪时间 | -|   `refundAmount` | `number` | | 退款金额 | -|   `remark` | `string` | | 备注 | -|   `returnDate` | `string` | | 返程日期（出发日期 + 行程天数 - 1） | -|   `reviewed` | `boolean` | | 是否已评价 | -|   `roomInfo` | `string` | | 房间信息 | -|   `status` | `string` | | 订单状态（PENDING_PAY/DEPOSIT_PAID/PAID/CONFIRMED/IN_PROGRESS/COMPLETED/CANCELLED） | -|   `statusLabel` | `string` | | 订单状态标签 | -|   `timeline` | `Map«string,object»[]` | | 时间线列表 | -|   `todos` | `Map«string,object»[]` | | 待办列表 | -|   `totalPrice` | `number` | | 总售价 | -|   `travelers` | `Map«string,object»[]` | | 出行人列表 | -|   `tripDays` | `int` | | 行程天数 | -|   `tripNights` | `int` | | 行程晚数 | -|   `unlockRequestedAt` | `string` | | 解锁请求时间 | -|   `userId` | `long` | | 用户ID | -|   `vehicleInfo` | `string` | | 车辆信息 | -|   `youngChildCount` | `int` | | 小童数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/list - -**订单列表** - -分页查询当前用户的订单列表，支持按状态筛选。返回订单摘要信息（不含详细出行人信息） - -**关联字典（BFF透传）**： -- order_status：订单状态（列表筛选+显示） -- product_type：产品类型（订单卡片显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `status` | `string` | | 状态 | | - -**响应** `统一响应结果«分页结果«订单列表项»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«订单列表项»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `订单列表项[]` | | 数据列表 | -|     `adultCount` | `int` | | 成人数 | -|     `babyCount` | `int` | | 幼童数 | -|     `balanceAmount` | `number` | | 尾款金额 | -|     `childCount` | `int` | | 儿童数 | -|     `contracts` | `Map«string,object»[]` | | 合同列表（含signUrl/fileUrl/status等） | -|     `createTime` | `string` | | 创建时间 | -|     `daysUntilDeparture` | `int` | | 距出发天数（负数表示已出发） | -|     `departureDate` | `string` | | 出发日期 | -|     `depositAmount` | `number` | | 定金金额 | -|     `displayName` | `string` | | 显示名称（未支付=手机号+姓名，已支付=订单号） | -|     `displayStatus` | `string` | | C端简化状态（PENDING_PAY/PENDING_DEPARTURE/PENDING_REVIEW/REFUND/CANCELLED） | -|     `displayStatusLabel` | `string` | | C端简化状态标签 | -|     `expiryTime` | `string` | | 支付截止时间（PENDING_PAY状态有效） | -|     `insurances` | `Map«string,object»[]` | | 保险订单列表（含productName/extPolicyNo/status等） | -|     `nextAction` | `string` | | 下一步操作提示 | -|     `orderId` | `long` | | 订单ID | -|     `orderNo` | `string` | | 订单编号 | -|     `paidAmount` | `number` | | 已付金额 | -|     `paymentMode` | `string` | | 支付模式（FULL/DEPOSIT） | -|     `processStatus` | `string` | | 内部流程状态（字典：order_process_status） | -|     `processStatusLabel` | `string` | | 内部流程状态标签（字典：order_process_status 翻译） | -|     `productCoverUrl` | `string` | | 产品封面图URL | -|     `productId` | `long` | | 产品ID | -|     `productName` | `string` | | 产品名称 | -|     `productType` | `string` | | 产品类型（CORE/ROUTE/CUSTOM/GROUP） | -|     `status` | `string` | | 订单状态（PENDING_PAY/DEPOSIT_PAID/PAID/CONFIRMED/IN_PROGRESS/COMPLETED/CANCELLED） | -|     `statusLabel` | `string` | | 订单状态标签 | -|     `totalPrice` | `number` | | 总售价 | -|     `tripDays` | `int` | | 行程天数 | -|     `tripNights` | `int` | | 行程晚数 | -|     `youngChildCount` | `int` | | 小童数 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/lookup - -**通过联系人手机号+姓名查找订单（无需登录）** - -无需登录即可查询。用于管理员代下单场景：管理员创建订单后，用户通过联系人手机号+姓名查找订单并绑定到自己账号。仅返回尚未绑定用户(userId=NULL)的订单。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `contactName` | `string` | | 联系人姓名 | | -| `contactPhone` | `string` | | 联系人手机号 | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/upcoming - -**即将出发的订单** - -查询3天内即将出发的订单（状态为已确认/待出发/出行中），含合同和保险信息，按出发日期升序 - -**响应** `统一响应结果«List«订单列表项»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `订单列表项[]` | | 响应数据 | -|   `adultCount` | `int` | | 成人数 | -|   `babyCount` | `int` | | 幼童数 | -|   `balanceAmount` | `number` | | 尾款金额 | -|   `childCount` | `int` | | 儿童数 | -|   `contracts` | `Map«string,object»[]` | | 合同列表（含signUrl/fileUrl/status等） | -|   `createTime` | `string` | | 创建时间 | -|   `daysUntilDeparture` | `int` | | 距出发天数（负数表示已出发） | -|   `departureDate` | `string` | | 出发日期 | -|   `depositAmount` | `number` | | 定金金额 | -|   `displayName` | `string` | | 显示名称（未支付=手机号+姓名，已支付=订单号） | -|   `displayStatus` | `string` | | C端简化状态（PENDING_PAY/PENDING_DEPARTURE/PENDING_REVIEW/REFUND/CANCELLED） | -|   `displayStatusLabel` | `string` | | C端简化状态标签 | -|   `expiryTime` | `string` | | 支付截止时间（PENDING_PAY状态有效） | -|   `insurances` | `Map«string,object»[]` | | 保险订单列表（含productName/extPolicyNo/status等） | -|   `nextAction` | `string` | | 下一步操作提示 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `paidAmount` | `number` | | 已付金额 | -|   `paymentMode` | `string` | | 支付模式（FULL/DEPOSIT） | -|   `processStatus` | `string` | | 内部流程状态（字典：order_process_status） | -|   `processStatusLabel` | `string` | | 内部流程状态标签（字典：order_process_status 翻译） | -|   `productCoverUrl` | `string` | | 产品封面图URL | -|   `productId` | `long` | | 产品ID | -|   `productName` | `string` | | 产品名称 | -|   `productType` | `string` | | 产品类型（CORE/ROUTE/CUSTOM/GROUP） | -|   `status` | `string` | | 订单状态（PENDING_PAY/DEPOSIT_PAID/PAID/CONFIRMED/IN_PROGRESS/COMPLETED/CANCELLED） | -|   `statusLabel` | `string` | | 订单状态标签 | -|   `totalPrice` | `number` | | 总售价 | -|   `tripDays` | `int` | | 行程天数 | -|   `tripNights` | `int` | | 行程晚数 | -|   `youngChildCount` | `int` | | 小童数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/{orderId} - -**订单详情** - -获取订单完整信息，包含产品快照、出行人列表、支付信息、合同状态等 - -**关联字典（BFF透传）**： -- order_status：订单状态（显示） -- product_type：产品类型（显示） -- contract_status：合同状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«订单详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `订单详情` | | 响应数据 | -|   `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` | `Map«string,object»[]` | | 优惠列表 | -|   `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` | | 支付模式（FULL/DEPOSIT） | -|   `processStatus` | `string` | | 内部流程状态 | -|   `processStatusLabel` | `string` | | 内部流程状态标签 | -|   `productCoverUrl` | `string` | | 产品封面图URL | -|   `productId` | `long` | | 产品ID | -|   `productName` | `string` | | 产品名称 | -|   `productSnapshot` | `string` | | 产品快照JSON | -|   `productType` | `string` | | 产品类型（CORE/ROUTE/CUSTOM/GROUP） | -|   `readyAt` | `string` | | 就绪时间 | -|   `refundAmount` | `number` | | 退款金额 | -|   `remark` | `string` | | 备注 | -|   `returnDate` | `string` | | 返程日期（出发日期 + 行程天数 - 1） | -|   `reviewed` | `boolean` | | 是否已评价 | -|   `roomInfo` | `string` | | 房间信息 | -|   `status` | `string` | | 订单状态（PENDING_PAY/DEPOSIT_PAID/PAID/CONFIRMED/IN_PROGRESS/COMPLETED/CANCELLED） | -|   `statusLabel` | `string` | | 订单状态标签 | -|   `timeline` | `Map«string,object»[]` | | 时间线列表 | -|   `todos` | `Map«string,object»[]` | | 待办列表 | -|   `totalPrice` | `number` | | 总售价 | -|   `travelers` | `Map«string,object»[]` | | 出行人列表 | -|   `tripDays` | `int` | | 行程天数 | -|   `tripNights` | `int` | | 行程晚数 | -|   `unlockRequestedAt` | `string` | | 解锁请求时间 | -|   `userId` | `long` | | 用户ID | -|   `vehicleInfo` | `string` | | 车辆信息 | -|   `youngChildCount` | `int` | | 小童数 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/order/{orderId}/approve-unlock - -**同意解锁订单** - -用户同意管理员的修改请求，解除订单锁定状态，允许管理员继续修改订单 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /mp/order/{orderId}/cancel - -**取消订单** - -取消规则：仅PENDING_PAY/DEPOSIT_PAID状态可用户取消，取消后不可恢复 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**请求体** `用户取消订单请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reason` | `string` | | 取消原因 | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /mp/order/{orderId}/edit - -**修改订单** - -用户可修改出发日期和出行人。仅待支付/已付定金/已支付/已确认/待付尾款/待出发状态可修改，清单已确认的订单不允许修改。修改后重走内部流程 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**请求体** `修改订单请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `departureDate` | `string` | | 出发日期 | -| `travelers` | `出行人信息_1[]` | | 出行人列表（提供则替换全部出行人） | -|   `birthday` | `string` | | 出生日期 | -|   `email` | `string` | | 电子邮箱 | -|   `emergencyContact` | `string` | | 紧急联系人 | -|   `emergencyPhone` | `string` | | 紧急联系电话 | -|   `gender` | `int` | | 性别 | -|   `idCardNo` | `string` | | 证件号码 | -|   `idCardType` | `string` | | 证件类型 | -|   `name` | `string` | 是 | 出行人姓名 | -|   `nationality` | `string` | | 国籍 | -|   `phone` | `string` | | 手机号 | -|   `travelerType` | `string` | | 出行人类型 | - -**响应** `统一响应结果«订单详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `订单详情` | | 响应数据 | -|   `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` | `Map«string,object»[]` | | 优惠列表 | -|   `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` | | 支付模式（FULL/DEPOSIT） | -|   `processStatus` | `string` | | 内部流程状态 | -|   `processStatusLabel` | `string` | | 内部流程状态标签 | -|   `productCoverUrl` | `string` | | 产品封面图URL | -|   `productId` | `long` | | 产品ID | -|   `productName` | `string` | | 产品名称 | -|   `productSnapshot` | `string` | | 产品快照JSON | -|   `productType` | `string` | | 产品类型（CORE/ROUTE/CUSTOM/GROUP） | -|   `readyAt` | `string` | | 就绪时间 | -|   `refundAmount` | `number` | | 退款金额 | -|   `remark` | `string` | | 备注 | -|   `returnDate` | `string` | | 返程日期（出发日期 + 行程天数 - 1） | -|   `reviewed` | `boolean` | | 是否已评价 | -|   `roomInfo` | `string` | | 房间信息 | -|   `status` | `string` | | 订单状态（PENDING_PAY/DEPOSIT_PAID/PAID/CONFIRMED/IN_PROGRESS/COMPLETED/CANCELLED） | -|   `statusLabel` | `string` | | 订单状态标签 | -|   `timeline` | `Map«string,object»[]` | | 时间线列表 | -|   `todos` | `Map«string,object»[]` | | 待办列表 | -|   `totalPrice` | `number` | | 总售价 | -|   `travelers` | `Map«string,object»[]` | | 出行人列表 | -|   `tripDays` | `int` | | 行程天数 | -|   `tripNights` | `int` | | 行程晚数 | -|   `unlockRequestedAt` | `string` | | 解锁请求时间 | -|   `userId` | `long` | | 用户ID | -|   `vehicleInfo` | `string` | | 车辆信息 | -|   `youngChildCount` | `int` | | 小童数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/{orderId}/resources - -**订单资源详情（按分类）** - -解析产品快照，提取资源详情按分类返回 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«Map«string,List«Map«string,object»»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 评价接口 - -### `POST` /mp/review/create - -**创建评价** - -评价流程：订单完成后 → 查询可评价目标列表 → 对每个目标(酒店/景区/活动等)提交评价 → 自动内容审核 → 审核通过后公开展示 - -**关联字典（BFF透传）**： -- review_status：评价审核状态（返回字段） -- rating_level：评价等级（返回字段） - -**请求体** `创建评价请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `content` | `string` | 是 | 评价内容(10-500字) | -| `images` | `评价图片项[]` | | 评价图片列表（最多9张） | -|   `fileId` | `long` | | 文件ID | -|   `imageUrl` | `string` | 是 | 图片URL | -| `orderId` | `long` | 是 | 订单ID | -| `ratings` | `object` | 是 | 评分数据（key为评分类别字典的dictValue，value为1-5整数）。先调用 GET /mp/review/rating-categories 获取评分维度，required=true的必填。示例: {"ratingItinerary":5,"ratingAccommodation":4,"ratingDriver":5,"ratingDining":4,"ratingOverall":5} | -| `videos` | `评价视频项[]` | | 评价视频列表（最多3个） | -|   `coverUrl` | `string` | | 视频封面URL | -|   `duration` | `int` | | 视频时长(秒) | -|   `fileId` | `long` | | 文件ID | -|   `videoUrl` | `string` | 是 | 视频URL | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/featured - -**精选评价列表(公开)** - -无需登录，返回精选评价数组，用于评价浏览页 - -**关联字典（BFF透传）**： -- rating_level：评价等级（显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `limit` | `integer(int32)` | | 数量限制 | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/my - -**我的评价列表** - -**关联字典（BFF透传）**： -- review_status：评价审核状态（显示） -- rating_level：评价等级（显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/order/{orderId}/reviewable-targets - -**订单可评价目标列表** - -返回订单中可评价的资源目标列表（景区/酒店/活动等），用于评价页面展示可评价项。已评价的目标不会重复出现。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/order/{orderId}/reviewed - -**检查订单是否已评价** - -检查指定订单是否已提交评价，用于订单详情页决定是否显示'去评价'按钮。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/product/{productId} - -**按产品ID查看评价列表** - -返回评价列表+统计数据，支持好中差评/有图/有视频筛选 - -**关联字典（BFF透传）**： -- rating_level：评价等级（筛选+显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `productId` | `integer` | | 产品ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `hasImage` | `boolean` | | 是否有图片 | | -| `hasVideo` | `boolean` | | 是否有视频 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `ratingLevel` | `string` | | 评价等级: GOOD/MEDIUM/BAD | | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/product/{productId}/highlights - -**产品精选评价(最高评分+最高点赞+统计)** - -用于产品详情页评价区域展示 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `productId` | `integer` | | 产品ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/rating-categories - -**评分类别列表** - -从字典读取评价时需要填写的评分维度，前端据此渲染评分组件。字典类型: review_rating_category，remark字段包含扩展JSON(required/min/max) - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/search - -**关键词搜索评价(公开)** - -按关键词搜索已通过的评价内容，支持按目标类型和目标ID筛选 - -**关联字典（BFF透传）**： -- rating_level：评价等级（显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `keyword` | `string` | 是 | 搜索关键词 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `targetId` | `integer(int64)` | | 目标ID(可选) | | -| `targetType` | `string` | | 目标类型(可选): PRODUCT/SCENIC_SPOT/ACTIVITY/HOTEL等 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/stats - -**评价统计(平均分、数量)** - -获取指定目标的评价统计数据（平均评分、总评价数等），用于详情页评价区域展示。产品showReview关闭时返回空统计。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `targetId` | `integer(int64)` | | 目标ID | | -| `targetType` | `string` | | 目标类型 | | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/target - -**某目标的已通过评价(公开)** - -**关联字典（BFF透传）**： -- rating_level：评价等级（筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `hasImage` | `boolean` | | 是否有图片 | | -| `hasVideo` | `boolean` | | 是否有视频 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `ratingLevel` | `string` | | 评价等级: GOOD/MEDIUM/BAD | | -| `targetId` | `integer(int64)` | | 目标ID | | -| `targetType` | `string` | | 目标类型 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/review/{reviewId}/like - -**点赞/取消点赞评价** - -对评价进行点赞或取消点赞操作，返回当前点赞状态和点赞总数。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reviewId` | `integer` | | 评价ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/{reviewId}/like/check - -**检查是否已点赞** - -检查当前用户是否已点赞指定评价，用于评价列表/详情的点赞按钮状态展示。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reviewId` | `integer` | | 评价ID | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 足迹接口 - -### `GET` /mp/user/footprint - -**足迹列表（含资源摘要）** - -分页查询浏览足迹列表，聚合层会补充每条足迹对应资源的摘要信息（名称、封面图等）。支持按资源类型筛选，按浏览时间倒序。 - -**权限**：需登录。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `resourceType` | `string` | | 资源类型筛选：PRODUCT/SCENIC/RESTAURANT/ACTIVITY | | - -**响应** `统一响应结果«分页结果«足迹列表项（含资源摘要）»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«足迹列表项（含资源摘要）»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `足迹列表项（含资源摘要）[]` | | 数据列表 | -|     `coverUrl` | `string` | | 封面图URL | -|     `footprintId` | `string` | | 足迹记录ID | -|     `name` | `string` | | 资源名称 | -|     `resourceId` | `string` | | 资源ID | -|     `resourceType` | `string` | | 资源类型：PRODUCT/SCENIC/RESTAURANT/ACTIVITY | -|     `tags` | `string[]` | | 标签列表 | -|     `visitTime` | `string` | | 浏览时间 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/user/footprint - -**记录足迹** - -记录用户浏览资源的足迹，同一资源重复浏览会更新浏览时间而非新增记录 - -**请求体** `添加足迹请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `resourceId` | `string` | 是 | 资源ID | -| `resourceType` | `string` | 是 | 资源类型: PRODUCT/SCENIC/RESTAURANT/ACTIVITY | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /mp/user/footprint/batch - -**批量删除足迹** - -批量删除多条浏览足迹记录，传入足迹ID列表。用于足迹管理页面的批量清理。 - -**权限**：需登录，仅能删除自己的足迹。 - -**请求体** `long[]` - -**响应** `统一响应结果«Void»` - ---- - -### `DELETE` /mp/user/footprint/{id} - -**删除足迹** - -删除单条浏览足迹记录。 - -**权限**：需登录，仅能删除自己的足迹。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 足迹ID | - -**响应** `统一响应结果«Void»` - ---- - -## C端 - 轮播图接口 - -### `GET` /mp/banner/active - -**获取当前生效的轮播图列表** - -返回当前处于有效期内的轮播图，按排序值排列。用于小程序首页顶部轮播展示，透传自user-service。 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 退款接口 - -### `GET` /mp/order/refund-reasons - -**退款原因列表** - -返回系统预设的退款原因选项，用于退款申请页面的原因选择 - -**响应** `统一响应结果«List«退款原因»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款原因[]` | | 响应数据 | -|   `category` | `string` | | 分类: GENERAL(通用)/PRODUCT(产品问题)/SERVICE(服务问题) | -|   `enabled` | `boolean` | | 是否启用 | -|   `reasonId` | `long` | | 原因ID | -|   `reasonText` | `string` | | 原因描述 | -|   `sortOrder` | `int` | | 排序序号 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/refund/{applicationId} - -**退款申请详情** - -获取退款申请的完整信息，包含审核状态、退款金额、退款进度和操作记录 - -**关联字典（BFF透传）**： -- order_status：订单状态（显示） -- payment_status：支付/退款状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `applicationId` | `integer` | | 退款申请ID | - -**响应** `统一响应结果«退款申请详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款申请详情` | | 响应数据 | -|   `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` | | 审批编号（企微OA审批编号） | -|   `autoRefundDeadline` | `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` | | 退款类型: DEPOSIT(定金)/BALANCE(尾款)/FULL(全款) | -|   `refundTypeLabel` | `string` | | 退款类型中文标签 | -|   `refundedAt` | `string` | | 退款完成时间 | -|   `reviewAdminId` | `long` | | 审批管理员ID | -|   `reviewAdminName` | `string` | | 审批管理员姓名 | -|   `reviewRemark` | `string` | | 审批备注 | -|   `reviewedAt` | `string` | | 审批时间 | -|   `status` | `string` | | 退款状态: PENDING(待审核)/APPROVED(已通过)/REJECTED(已拒绝)/REFUNDING(退款中)/REFUNDED(已退款)/CANCELLED(已撤回)/APPEALING(申诉中)/APPEAL_APPROVED(申诉通过)/APPEAL_REJECTED(申诉驳回) | -|   `statusLabel` | `string` | | 退款状态中文标签 | -|   `updateTime` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/order/refund/{applicationId}/appeal - -**发起申诉** - -退款被拒绝后，用户可在3天内发起一次申诉，由上级管理员重新审核 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `applicationId` | `integer` | | 退款申请ID | - -**请求体** `退款申诉请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `appealReason` | `string` | 是 | 申诉原因 | -| `evidence` | `string[]` | | 申诉凭证图片URL列表 | - -**响应** `统一响应结果«退款申请详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款申请详情` | | 响应数据 | -|   `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` | | 审批编号（企微OA审批编号） | -|   `autoRefundDeadline` | `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` | | 退款类型: DEPOSIT(定金)/BALANCE(尾款)/FULL(全款) | -|   `refundTypeLabel` | `string` | | 退款类型中文标签 | -|   `refundedAt` | `string` | | 退款完成时间 | -|   `reviewAdminId` | `long` | | 审批管理员ID | -|   `reviewAdminName` | `string` | | 审批管理员姓名 | -|   `reviewRemark` | `string` | | 审批备注 | -|   `reviewedAt` | `string` | | 审批时间 | -|   `status` | `string` | | 退款状态: PENDING(待审核)/APPROVED(已通过)/REJECTED(已拒绝)/REFUNDING(退款中)/REFUNDED(已退款)/CANCELLED(已撤回)/APPEALING(申诉中)/APPEAL_APPROVED(申诉通过)/APPEAL_REJECTED(申诉驳回) | -|   `statusLabel` | `string` | | 退款状态中文标签 | -|   `updateTime` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/order/refund/{applicationId}/cancel - -**撤回退款申请** - -仅PENDING状态的退款申请可撤回，撤回后订单恢复到原状态 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `applicationId` | `integer` | | 退款申请ID | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /mp/order/{orderId}/refund - -**提交退款申请** - -退款流程：获取退款预览 → 选择退款原因 → 提交退款申请 → 管理员审核 → 审核通过后自动退款到原支付方式 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**请求体** `退款申请请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `images` | `string[]` | | 退款凭证图片URL列表 | -| `reasonDetail` | `string` | | 退款补充说明 | -| `reasonId` | `string` | | 退款原因ID（已废弃，改用字典） | -| `reasonText` | `string` | 是 | 退款原因文本 | -| `reasonValue` | `string` | | 退款原因字典值 | -| `refundType` | `string` | 是 | 退款类型（FULL/DEPOSIT/BALANCE） | - -**响应** `统一响应结果«退款申请详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款申请详情` | | 响应数据 | -|   `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` | | 审批编号（企微OA审批编号） | -|   `autoRefundDeadline` | `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` | | 退款类型: DEPOSIT(定金)/BALANCE(尾款)/FULL(全款) | -|   `refundTypeLabel` | `string` | | 退款类型中文标签 | -|   `refundedAt` | `string` | | 退款完成时间 | -|   `reviewAdminId` | `long` | | 审批管理员ID | -|   `reviewAdminName` | `string` | | 审批管理员姓名 | -|   `reviewRemark` | `string` | | 审批备注 | -|   `reviewedAt` | `string` | | 审批时间 | -|   `status` | `string` | | 退款状态: PENDING(待审核)/APPROVED(已通过)/REJECTED(已拒绝)/REFUNDING(退款中)/REFUNDED(已退款)/CANCELLED(已撤回)/APPEALING(申诉中)/APPEAL_APPROVED(申诉通过)/APPEAL_REJECTED(申诉驳回) | -|   `statusLabel` | `string` | | 退款状态中文标签 | -|   `updateTime` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/{orderId}/refund-detail - -**根据订单ID获取最新退款详情** - -查询订单关联的最新一条退款申请详情，无退款记录时返回null - -**关联字典（BFF透传）**： -- order_status：订单状态（显示） -- payment_status：支付/退款状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `string` | | 订单ID | - -**响应** `统一响应结果«退款申请详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款申请详情` | | 响应数据 | -|   `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` | | 审批编号（企微OA审批编号） | -|   `autoRefundDeadline` | `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` | | 退款类型: DEPOSIT(定金)/BALANCE(尾款)/FULL(全款) | -|   `refundTypeLabel` | `string` | | 退款类型中文标签 | -|   `refundedAt` | `string` | | 退款完成时间 | -|   `reviewAdminId` | `long` | | 审批管理员ID | -|   `reviewAdminName` | `string` | | 审批管理员姓名 | -|   `reviewRemark` | `string` | | 审批备注 | -|   `reviewedAt` | `string` | | 审批时间 | -|   `status` | `string` | | 退款状态: PENDING(待审核)/APPROVED(已通过)/REJECTED(已拒绝)/REFUNDING(退款中)/REFUNDED(已退款)/CANCELLED(已撤回)/APPEALING(申诉中)/APPEAL_APPROVED(申诉通过)/APPEAL_REJECTED(申诉驳回) | -|   `statusLabel` | `string` | | 退款状态中文标签 | -|   `updateTime` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/{orderId}/refund-preview - -**退款金额预览** - -根据退款政策和订单出发日期计算可退金额，展示退款比例和扣除金额明细 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«退款预览»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款预览` | | 响应数据 | -|   `calculatedAmount` | `number` | | 计算退款金额 | -|   `daysBeforeDept` | `int` | | 距出发天数 | -|   `departureDate` | `string` | | 出发日期 | -|   `message` | `string` | | 提示信息 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单号 | -|   `paidAmount` | `number` | | 已付金额 | -|   `policyId` | `long` | | 匹配的退款政策ID | -|   `policyName` | `string` | | 匹配的退款政策名称 | -|   `refundRatio` | `int` | | 退款比例（百分比） | -|   `refundType` | `string` | | 退款类型: DEPOSIT/BALANCE/FULL | -|   `refundable` | `boolean` | | 是否可退款 | -|   `rules` | `退款规则项[]` | | 退款规则列表（按天数降序） | -|     `matched` | `boolean` | | 是否当前命中此规则 | -|     `minDays` | `int` | | 最低天数 | -|     `refundRatio` | `int` | | 退款比例（百分比） | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 通用点赞 - -### `POST` /mp/like/{targetType}/batch-check - -**批量检查点赞状态** - -批量检查当前用户是否已对多个目标点赞，返回已点赞的目标ID列表。用于列表页批量展示点赞状态。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `targetType` | `string` | | 目标类型 | - -**请求体** `string[]` - -**响应** `统一响应结果«List«string»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `string[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/like/{targetType}/{targetId} - -**切换点赞** - -点赞/取消点赞，返回 {liked: true/false, likeCount: 点赞数} - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `targetId` | `integer` | | 目标ID | -| `targetType` | `string` | | 目标类型: REVIEW/EXPLORE/GUIDE等 | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/like/{targetType}/{targetId}/check - -**检查是否已点赞** - -检查当前用户是否已对指定目标点赞，用于前端点赞按钮状态展示。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `targetId` | `integer` | | 目标ID | -| `targetType` | `string` | | 目标类型 | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 酒店接口 - -### `GET` /mp/hotel/list - -**酒店列表** - -分页查询已上架的酒店列表，支持按关键词、城市、星级筛选。聚合层透传resource-service的酒店数据。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `city` | `string` | | 城市 | | -| `keyword` | `string` | | 关键词 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `starLevel` | `integer(int32)` | | 星级 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/hotel/{hotelId} - -**酒店详情** - -获取酒店完整信息（含房型列表、图文详情、价格等），自动注入静态地图图片URL用于详情页地图展示。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `hotelId` | `integer` | | 酒店ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 餐厅接口 - -### `GET` /mp/restaurant/list - -**餐厅列表** - -分页查询已上架的餐厅列表，支持按关键词和城市筛选。聚合层透传resource-service的餐厅数据。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `city` | `string` | | 城市 | | -| `keyword` | `string` | | 关键词 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/restaurant/{restaurantId} - -**餐厅详情** - -获取餐厅完整信息（含菜品、图文详情等），自动注入静态地图图片URL用于详情页地图展示。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `restaurantId` | `integer` | | 餐厅ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 首页接口 - -### `GET` /mp/home - -**首页数据** - -聚合流程：并行获取推荐产品列表+产品线列表+轮播图 → Redis缓存5分钟 → 返回聚合数据 - -**关联字典（BFF透传）**： -- product_type：产品类型（产品卡片显示） -- product_status：产品状态（透传自product-service） - -**响应** `统一响应结果«首页聚合数据»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `首页聚合数据` | | 响应数据 | -|   `banners` | `Map«string,object»[]` | | 轮播图Banner列表 | -|   `contactInfo` | `Map«string,object»[]` | | 联系我们列表 | -|   `exploreTopics` | `Map«string,object»[]` | | 探索专题列表 | -|   `featuredDesigner` | `object` | | 推荐定制师 | -|   `featuredReviews` | `Map«string,object»[]` | | 首页精选评价列表 | -|   `productLines` | `Map«string,object»[]` | | 产品线分类列表 | -|   `recommendProducts` | `Map«string,object»[]` | | 推荐产品列表 | -| `message` | `string` | | 响应消息 | - ---- diff --git a/2026-03/17_1009/hl-order-service.md b/2026-03/17_1009/hl-order-service.md deleted file mode 100644 index ed3738c..0000000 --- a/2026-03/17_1009/hl-order-service.md +++ /dev/null @@ -1,3594 +0,0 @@ -# 订单服务 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_1009/hl-payment-service.md b/2026-03/17_1009/hl-payment-service.md deleted file mode 100644 index 9982afc..0000000 --- a/2026-03/17_1009/hl-payment-service.md +++ /dev/null @@ -1,282 +0,0 @@ -# 支付服务 API 文档 - -**服务**: `hl-payment-service` -**接口总数**: 7 - -## 目录 - -- **支付管理** (7 个接口) - ---- - -## 支付管理 - -### `GET` /admin/payment/list - -**支付交易列表** - -分页查询支付交易记录，支持按订单号、交易状态、交易类型筛选 - -**关联字典**： -- payment_mode：支付模式（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `endDate` | `string` | | 结束日期 | 2026-12-31 | -| `mchId` | `string` | | 商户号 | 1246532201 | -| `orderNo` | `string` | | 订单编号 | HL20260301120000001234 | -| `page` | `integer(int32)` | | 页码 | 1 | -| `pageSize` | `integer(int32)` | | 每页条数 | 20 | -| `startDate` | `string` | | 开始日期 | 2026-01-01 | -| `status` | `string` | | 支付状态 | SUCCESS | -| `tradeType` | `string` | | 交易类型: JSAPI/H5 | JSAPI | - -**响应** `统一响应结果«分页结果«支付交易信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«支付交易信息»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `支付交易信息[]` | | 数据列表 | -|     `createTime` | `string` | | 创建时间 | -|     `mchId` | `string` | | 商户号 | -|     `orderId` | `long` | | 订单ID | -|     `orderNo` | `string` | | 订单编号 | -|     `outTradeNo` | `string` | | 商户订单号 | -|     `payTime` | `string` | | 支付时间 | -|     `payType` | `string` | | 支付类型: FULL/DEPOSIT/BALANCE | -|     `status` | `string` | | 交易状态 | -|     `totalAmount` | `number` | | 交易金额 | -|     `tradeType` | `string` | | 交易类型: JSAPI/H5 | -|     `transactionId` | `long` | | 交易ID | -|     `transactionIdWx` | `string` | | 微信支付交易号 | -|     `userId` | `long` | | 用户ID | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/payment/order/{orderId} - -**按订单查询交易** - -查询指定订单的所有支付交易记录 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«List«支付交易信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `支付交易信息[]` | | 响应数据 | -|   `createTime` | `string` | | 创建时间 | -|   `mchId` | `string` | | 商户号 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `outTradeNo` | `string` | | 商户订单号 | -|   `payTime` | `string` | | 支付时间 | -|   `payType` | `string` | | 支付类型: FULL/DEPOSIT/BALANCE | -|   `status` | `string` | | 交易状态 | -|   `totalAmount` | `number` | | 交易金额 | -|   `tradeType` | `string` | | 交易类型: JSAPI/H5 | -|   `transactionId` | `long` | | 交易ID | -|   `transactionIdWx` | `string` | | 微信支付交易号 | -|   `userId` | `long` | | 用户ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/payment/refund/order/{orderId} - -**按订单查询退款** - -查询指定订单的所有退款记录 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«List«退款记录信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款记录信息[]` | | 响应数据 | -|   `createTime` | `string` | | 创建时间 | -|   `mchId` | `string` | | 商户号 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `outRefundNo` | `string` | | 商户退款单号 | -|   `reason` | `string` | | 退款原因 | -|   `refundAmount` | `number` | | 退款金额 | -|   `refundId` | `long` | | 退款ID | -|   `refundIdWx` | `string` | | 微信退款单号 | -|   `status` | `string` | | 退款状态 | -|   `successTime` | `string` | | 退款成功时间 | -|   `totalAmount` | `number` | | 订单总金额 | -|   `transactionId` | `long` | | 交易ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/payment/refund/{refundId} - -**退款详情** - -获取单笔退款记录的完整信息，包含微信退款单号和退款状态 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `refundId` | `integer` | | 退款ID | - -**响应** `统一响应结果«退款记录信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款记录信息` | | 响应数据 | -|   `createTime` | `string` | | 创建时间 | -|   `mchId` | `string` | | 商户号 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `outRefundNo` | `string` | | 商户退款单号 | -|   `reason` | `string` | | 退款原因 | -|   `refundAmount` | `number` | | 退款金额 | -|   `refundId` | `long` | | 退款ID | -|   `refundIdWx` | `string` | | 微信退款单号 | -|   `status` | `string` | | 退款状态 | -|   `successTime` | `string` | | 退款成功时间 | -|   `totalAmount` | `number` | | 订单总金额 | -|   `transactionId` | `long` | | 交易ID | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/payment/{orderId}/refund - -**发起退款** - -退款流程：验证订单 → 查找原支付交易 → 调用微信退款API → 记录退款单 → 等待微信回调更新状态 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**请求体** `退款请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `amount` | `number` | 是 | 退款金额 | -| `orderId` | `long` | 是 | 订单ID | -| `reason` | `string` | | 退款原因 | - -**响应** `统一响应结果«退款记录信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款记录信息` | | 响应数据 | -|   `createTime` | `string` | | 创建时间 | -|   `mchId` | `string` | | 商户号 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `outRefundNo` | `string` | | 商户退款单号 | -|   `reason` | `string` | | 退款原因 | -|   `refundAmount` | `number` | | 退款金额 | -|   `refundId` | `long` | | 退款ID | -|   `refundIdWx` | `string` | | 微信退款单号 | -|   `status` | `string` | | 退款状态 | -|   `successTime` | `string` | | 退款成功时间 | -|   `totalAmount` | `number` | | 订单总金额 | -|   `transactionId` | `long` | | 交易ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/payment/{transactionId} - -**交易详情** - -获取单笔交易的完整信息，包含微信支付流水号 - -**关联字典**： -- payment_mode：支付模式（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `transactionId` | `integer` | | 交易ID | - -**响应** `统一响应结果«支付交易信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `支付交易信息` | | 响应数据 | -|   `createTime` | `string` | | 创建时间 | -|   `mchId` | `string` | | 商户号 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `outTradeNo` | `string` | | 商户订单号 | -|   `payTime` | `string` | | 支付时间 | -|   `payType` | `string` | | 支付类型: FULL/DEPOSIT/BALANCE | -|   `status` | `string` | | 交易状态 | -|   `totalAmount` | `number` | | 交易金额 | -|   `tradeType` | `string` | | 交易类型: JSAPI/H5 | -|   `transactionId` | `long` | | 交易ID | -|   `transactionIdWx` | `string` | | 微信支付交易号 | -|   `userId` | `long` | | 用户ID | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/payment/{transactionId}/sync - -**同步支付状态** - -主动查询微信支付状态并同步本地数据，适用于回调未到达的场景 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `transactionId` | `integer` | | 交易ID | - -**响应** `统一响应结果«支付交易信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `支付交易信息` | | 响应数据 | -|   `createTime` | `string` | | 创建时间 | -|   `mchId` | `string` | | 商户号 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `outTradeNo` | `string` | | 商户订单号 | -|   `payTime` | `string` | | 支付时间 | -|   `payType` | `string` | | 支付类型: FULL/DEPOSIT/BALANCE | -|   `status` | `string` | | 交易状态 | -|   `totalAmount` | `number` | | 交易金额 | -|   `tradeType` | `string` | | 交易类型: JSAPI/H5 | -|   `transactionId` | `long` | | 交易ID | -|   `transactionIdWx` | `string` | | 微信支付交易号 | -|   `userId` | `long` | | 用户ID | -| `message` | `string` | | 响应消息 | - ---- diff --git a/2026-03/17_1009/hl-product-service.md b/2026-03/17_1009/hl-product-service.md deleted file mode 100644 index f687949..0000000 --- a/2026-03/17_1009/hl-product-service.md +++ /dev/null @@ -1,5235 +0,0 @@ -# 产品服务 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=线路产品 - - 完整字典值: `CORE`=核心产品, `ROUTE`=自驾路书, `CUSTOM`=私人定制, `GROUP`=小蒙马 -- product_category（产品分类）：family=亲子游, honeymoon=蜜月游, photography=旅拍, experience=体验, driving=自驾 - - 完整字典值: `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=线路产品 - - 完整字典值: `CORE`=核心产品, `ROUTE`=自驾路书, `CUSTOM`=私人定制, `GROUP`=小蒙马 -- product_status（产品状态，筛选条件+返回字段）：DRAFT=草稿, PENDING_REVIEW=待审核, REVIEWED=已审核, REJECTED=已驳回, PUBLISHED=已上架, UNPUBLISHED=已下架, COMPLETED=已完成, ORDERED=已下单 - - 完整字典值: `DRAFT`=草稿, `PENDING_REVIEW`=待审核, `REVIEWED`=已审核, `REJECTED`=已驳回, `PUBLISHED`=已上架, `UNPUBLISHED`=已下架, `COMPLETED`=已完成 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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=线路产品 - - 完整字典值: `CORE`=核心产品, `ROUTE`=自驾路书, `CUSTOM`=私人定制, `GROUP`=小蒙马 -- product_status（产品状态）：DRAFT=草稿, PENDING_REVIEW=待审核, REVIEWED=已审核, REJECTED=已驳回, PUBLISHED=已上架, UNPUBLISHED=已下架, COMPLETED=已完成, ORDERED=已下单 - - 完整字典值: `DRAFT`=草稿, `PENDING_REVIEW`=待审核, `REVIEWED`=已审核, `REJECTED`=已驳回, `PUBLISHED`=已上架, `UNPUBLISHED`=已下架, `COMPLETED`=已完成 -- product_category（产品分类）：family=亲子游, honeymoon=蜜月游, photography=旅拍, experience=体验, driving=自驾 - - 完整字典值: `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=线路产品 - - 完整字典值: `CORE`=核心产品, `ROUTE`=自驾路书, `CUSTOM`=私人定制, `GROUP`=小蒙马 -- product_category（产品分类）：family=亲子游, honeymoon=蜜月游, photography=旅拍, experience=体验, driving=自驾 - - 完整字典值: `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=线路产品 - - 完整字典值: `CORE`=核心产品, `ROUTE`=自驾路书, `CUSTOM`=私人定制, `GROUP`=小蒙马 -- product_status（产品状态，复制后固定为 DRAFT） - - 完整字典值: `DRAFT`=草稿, `PENDING_REVIEW`=待审核, `REVIEWED`=已审核, `REJECTED`=已驳回, `PUBLISHED`=已上架, `UNPUBLISHED`=已下架, `COMPLETED`=已完成 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=线路产品 - - 完整字典值: `CORE`=核心产品, `ROUTE`=自驾路书, `CUSTOM`=私人定制, `GROUP`=小蒙马 -- product_status（产品状态，请求+返回字段）：DRAFT=草稿, PENDING_REVIEW=待审核, REVIEWED=已审核, REJECTED=已驳回, PUBLISHED=已上架, UNPUBLISHED=已下架, COMPLETED=已完成, ORDERED=已下单 - - 完整字典值: `DRAFT`=草稿, `PENDING_REVIEW`=待审核, `REVIEWED`=已审核, `REJECTED`=已驳回, `PUBLISHED`=已上架, `UNPUBLISHED`=已下架, `COMPLETED`=已完成 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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（车型）：车辆费用成本计算 - - 完整字典值: `SUV`=越野车, `SEDAN`=5座轿车, `MPV`=7座商务车, `MINIBUS`=9-15座小巴, `BUS`=大巴 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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（车型）：车辆费用成本测算 - - 完整字典值: `SUV`=越野车, `SEDAN`=5座轿车, `MPV`=7座商务车, `MINIBUS`=9-15座小巴, `BUS`=大巴 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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（车型）：费用配置中车辆相关成本显示 - - 完整字典值: `SUV`=越野车, `SEDAN`=5座轿车, `MPV`=7座商务车, `MINIBUS`=9-15座小巴, `BUS`=大巴 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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（车型）：费用配置中车辆相关成本计算 - - 完整字典值: `SUV`=越野车, `SEDAN`=5座轿车, `MPV`=7座商务车, `MINIBUS`=9-15座小巴, `BUS`=大巴 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=线路产品 - - 完整字典值: `CORE`=核心产品, `ROUTE`=自驾路书, `CUSTOM`=私人定制, `GROUP`=小蒙马 - -**请求体** `公式组请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=线路产品 - - 完整字典值: `CORE`=核心产品, `ROUTE`=自驾路书, `CUSTOM`=私人定制, `GROUP`=小蒙马 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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=线路产品 - - 完整字典值: `CORE`=核心产品, `ROUTE`=自驾路书, `CUSTOM`=私人定制, `GROUP`=小蒙马 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=线路产品 - - 完整字典值: `CORE`=核心产品, `ROUTE`=自驾路书, `CUSTOM`=私人定制, `GROUP`=小蒙马 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=线路产品 - - 完整字典值: `CORE`=核心产品, `ROUTE`=自驾路书, `CUSTOM`=私人定制, `GROUP`=小蒙马 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=线路产品 - - 完整字典值: `CORE`=核心产品, `ROUTE`=自驾路书, `CUSTOM`=私人定制, `GROUP`=小蒙马 - -**请求体** `公式变量请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=线路产品 - - 完整字典值: `CORE`=核心产品, `ROUTE`=自驾路书, `CUSTOM`=私人定制, `GROUP`=小蒙马 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=线路产品 - - 完整字典值: `CORE`=核心产品, `ROUTE`=自驾路书, `CUSTOM`=私人定制, `GROUP`=小蒙马 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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=线路产品 - - 完整字典值: `CORE`=核心产品, `ROUTE`=自驾路书, `CUSTOM`=私人定制, `GROUP`=小蒙马 -- product_category（产品分类）：family=亲子游, honeymoon=蜜月游, photography=旅拍, experience=体验, driving=自驾 - - 完整字典值: `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=小蒙马拼团 - - 完整字典值: `CORE`=核心产品, `ROUTE`=自驾路书, `CUSTOM`=私人定制, `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=线路产品 - - 完整字典值: `CORE`=核心产品, `ROUTE`=自驾路书, `CUSTOM`=私人定制, `GROUP`=小蒙马 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=小蒙马拼团 - - 完整字典值: `CORE`=核心产品, `ROUTE`=自驾路书, `CUSTOM`=私人定制, `GROUP`=小蒙马 -- batch_status（批次状态）：PENDING=待开放, ENROLLING=报名中, CONFIRMED=已成团, FULL=已满员, CLOSED=已关闭, DISBANDED=已解散, IN_PROGRESS=进行中, FINISHED=已结束 - - 完整字典值: `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=已结束 - - 完整字典值: `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=已结束 - - 完整字典值: `PENDING`=待开放, `ENROLLING`=报名中, `CONFIRMED`=已成团, `FULL`=已满员, `CLOSED`=已截止, `DISBANDED`=已散团, `IN_PROGRESS`=出行中, `FINISHED`=已结束 -- staff_type（人员类型，服务人员配置）：GUIDE=领队, DRIVER=司机, PHOTOGRAPHER=摄影师, ASSISTANT=助理, OTHER=其他 - - 完整字典值: `GUIDE`=导游, `GUIDE_ASSISTANT`=导游助理, `PHOTOGRAPHER`=摄影师, `LEADER`=领队, `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=其他 - - 完整字典值: `GUIDE`=导游, `GUIDE_ASSISTANT`=导游助理, `PHOTOGRAPHER`=摄影师, `LEADER`=领队, `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=其他 - - 完整字典值: `GUIDE`=导游, `GUIDE_ASSISTANT`=导游助理, `PHOTOGRAPHER`=摄影师, `LEADER`=领队, `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（城市）：搜索结果可用于产品行程中的城市预览 - - 完整字典值: `hailar`=海拉尔, `manzhouli`=满洲里, `eergu`=额尔古纳, `genhe`=根河, `yakeshi`=牙克石, `zhalantun`=扎兰屯, `aershan`=阿尔山, `shiwei`=室韦, `enhe`=恩和, `heishantou`=黑山头, `chenbaerhu`=陈巴尔虎旗, `xinbaerhuzuo`=新巴尔虎左旗, `xinbaerhuyou`=新巴尔虎右旗, `ewenke`=鄂温克旗, `moerdaoga`=莫尔道嘎 -- city（城市筛选）：搜索结果可用于资源面板城市筛选 - - 完整字典值: `hailar`=海拉尔, `manzhouli`=满洲里, `eergu`=额尔古纳, `genhe`=根河, `aershan`=阿尔山, `shiwei`=室韦, `enhe`=恩和, `heishantou`=黑山头 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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（城市，资源面板筛选用）：用于在添加节点时按城市筛选可选资源 - - 完整字典值: `hailar`=海拉尔, `manzhouli`=满洲里, `eergu`=额尔古纳, `genhe`=根河, `aershan`=阿尔山, `shiwei`=室韦, `enhe`=恩和, `heishantou`=黑山头 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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（城市）：资源面板城市筛选 - - 完整字典值: `hailar`=海拉尔, `manzhouli`=满洲里, `eergu`=额尔古纳, `genhe`=根河, `aershan`=阿尔山, `shiwei`=室韦, `enhe`=恩和, `heishantou`=黑山头 -- cities（城市ID映射）：城市名称预览 - - 完整字典值: `hailar`=海拉尔, `manzhouli`=满洲里, `eergu`=额尔古纳, `genhe`=根河, `yakeshi`=牙克石, `zhalantun`=扎兰屯, `aershan`=阿尔山, `shiwei`=室韦, `enhe`=恩和, `heishantou`=黑山头, `chenbaerhu`=陈巴尔虎旗, `xinbaerhuzuo`=新巴尔虎左旗, `xinbaerhuyou`=新巴尔虎右旗, `ewenke`=鄂温克旗, `moerdaoga`=莫尔道嘎 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=其他 - - 完整字典值: `GUIDE`=导游, `GUIDE_ASSISTANT`=导游助理, `PHOTOGRAPHER`=摄影师, `LEADER`=领队, `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=其他 - - 完整字典值: `GUIDE`=导游, `GUIDE_ASSISTANT`=导游助理, `PHOTOGRAPHER`=摄影师, `LEADER`=领队, `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（城市）：资源面板城市筛选 - - 完整字典值: `hailar`=海拉尔, `manzhouli`=满洲里, `eergu`=额尔古纳, `genhe`=根河, `aershan`=阿尔山, `shiwei`=室韦, `enhe`=恩和, `heishantou`=黑山头 -- cities（城市ID映射）：城市名称预览 - - 完整字典值: `hailar`=海拉尔, `manzhouli`=满洲里, `eergu`=额尔古纳, `genhe`=根河, `yakeshi`=牙克石, `zhalantun`=扎兰屯, `aershan`=阿尔山, `shiwei`=室韦, `enhe`=恩和, `heishantou`=黑山头, `chenbaerhu`=陈巴尔虎旗, `xinbaerhuzuo`=新巴尔虎左旗, `xinbaerhuyou`=新巴尔虎右旗, `ewenke`=鄂温克旗, `moerdaoga`=莫尔道嘎 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=其他 - - 完整字典值: `GUIDE`=导游, `GUIDE_ASSISTANT`=导游助理, `PHOTOGRAPHER`=摄影师, `LEADER`=领队, `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=其他 - - 完整字典值: `GUIDE`=导游, `GUIDE_ASSISTANT`=导游助理, `PHOTOGRAPHER`=摄影师, `LEADER`=领队, `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_1009/hl-resource-service.md b/2026-03/17_1009/hl-resource-service.md deleted file mode 100644 index ad1f144..0000000 --- a/2026-03/17_1009/hl-resource-service.md +++ /dev/null @@ -1,7002 +0,0 @@ -# 资源服务 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路径参数 - - 完整字典值: `GUIDE`=导游, `GUIDE_ASSISTANT`=导游助理, `PHOTOGRAPHER`=摄影师, `LEADER`=领队, `OTHER`=其他 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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路径参数 - - 完整字典值: `GUIDE`=导游, `GUIDE_ASSISTANT`=导游助理, `PHOTOGRAPHER`=摄影师, `LEADER`=领队, `OTHER`=其他 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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路径参数 - - 完整字典值: `GUIDE`=导游, `GUIDE_ASSISTANT`=导游助理, `PHOTOGRAPHER`=摄影师, `LEADER`=领队, `OTHER`=其他 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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路径参数 - - 完整字典值: `GUIDE`=导游, `GUIDE_ASSISTANT`=导游助理, `PHOTOGRAPHER`=摄影师, `LEADER`=领队, `OTHER`=其他 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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_1009/hl-review-service.md b/2026-03/17_1009/hl-review-service.md deleted file mode 100644 index dbb2fda..0000000 --- a/2026-03/17_1009/hl-review-service.md +++ /dev/null @@ -1,236 +0,0 @@ -# 评价服务 API 文档 - -**服务**: `hl-review-service` -**接口总数**: 6 - -## 目录 - -- **管理端-评价审核** (6 个接口) - ---- - -## 管理端-评价审核 - -### `GET` /admin/review/list - -**评价列表(支持好中差评/有图/有视频筛选)** - -分页查询全部评价（含待审核/已通过/已拒绝），支持按评价等级、是否有图/视频、目标类型筛选 - -**关联字典**： -- review_status：评价审核状态（列表筛选+显示） -- rating_level：评价等级（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `hasImage` | `boolean` | | 是否有图片: true/false | | -| `hasVideo` | `boolean` | | 是否有视频: true/false | | -| `keyword` | `string` | | 搜索关键词 | 风景 | -| `maxRating` | `integer(int32)` | | 最高评分(整体满意度) | 5 | -| `minRating` | `integer(int32)` | | 最低评分(整体满意度) | 3 | -| `page` | `integer(int32)` | | 页码 | 1 | -| `pageSize` | `integer(int32)` | | 每页条数 | 20 | -| `productType` | `string` | | 产品类型（字典 review_product_type） | CORE | -| `ratingLevel` | `string` | | 评价等级: GOOD/MEDIUM/BAD | GOOD | -| `reviewType` | `string` | | 评论类型（字典 review_type） | PRODUCT | -| `status` | `string` | | 评价状态 | APPROVED | -| `targetId` | `integer(int64)` | | 评价目标ID | 2001 | -| `targetType` | `string` | | 评价目标类型 | PRODUCT | - -**响应** `统一响应结果«分页结果«评价列表项(管理端)»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«评价列表项(管理端)»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `评价列表项(管理端)[]` | | 数据列表 | -|     `auditedAt` | `string` | | 审核时间 | -|     `auditorName` | `string` | | 审核人姓名 | -|     `content` | `string` | | 评价内容 | -|     `createdAt` | `string` | | 创建时间 | -|     `hasReply` | `boolean` | | 是否已回复 | -|     `imageCount` | `int` | | 图片数量 | -|     `orderId` | `string` | | 订单ID | -|     `orderNo` | `string` | | 订单编号 | -|     `productType` | `string` | | 产品类型 | -|     `productTypeLabel` | `string` | | 产品类型标签 | -|     `ratingAccommodation` | `int` | | 住宿安排评分(1-5) | -|     `ratingDining` | `int` | | 餐饮质量评分(1-5) | -|     `ratingDriver` | `int` | | 司机服务评分(1-5) | -|     `ratingItinerary` | `int` | | 行程安排评分(1-5) | -|     `ratingLevel` | `string` | | 评价等级: GOOD/MEDIUM/BAD | -|     `ratingLevelLabel` | `string` | | 评价等级标签 | -|     `ratingOverall` | `int` | | 整体满意度评分(1-5) | -|     `rejectReason` | `string` | | 拒绝原因 | -|     `reviewId` | `string` | | 评价ID | -|     `reviewType` | `string` | | 评论类型 | -|     `reviewTypeLabel` | `string` | | 评论类型标签 | -|     `status` | `string` | | 评价状态 | -|     `statusLabel` | `string` | | 评价状态标签 | -|     `targetId` | `string` | | 评价目标ID | -|     `targetName` | `string` | | 评价目标名称 | -|     `targetType` | `string` | | 评价目标类型 | -|     `targetTypeLabel` | `string` | | 评价目标类型标签 | -|     `userAvatar` | `string` | | 用户头像 | -|     `userNickname` | `string` | | 用户昵称 | -|     `videoCount` | `int` | | 视频数量 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/review/{reviewId} - -**评价详情** - -**关联字典**： -- review_status：评价审核状态（显示） -- rating_level：评价等级（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reviewId` | `integer` | | 评价ID | - -**响应** `统一响应结果«评价详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `评价详情` | | 响应数据 | -|   `adminReply` | `string` | | 管理员回复内容 | -|   `adminReplyAt` | `string` | | 回复时间 | -|   `adminReplyName` | `string` | | 回复管理员姓名 | -|   `auditedAt` | `string` | | 审核时间 | -|   `auditorAdminId` | `string` | | 审核人ID | -|   `auditorName` | `string` | | 审核人姓名 | -|   `content` | `string` | | 评价内容 | -|   `createdAt` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期(冗余自订单) | -|   `hasImage` | `boolean` | | 是否有图片 | -|   `hasVideo` | `boolean` | | 是否有视频 | -|   `imageCount` | `int` | | 图片数量 | -|   `images` | `评价图片信息[]` | | 评价图片列表 | -|     `fileId` | `string` | | 文件ID | -|     `imageId` | `string` | | 图片ID | -|     `imageUrl` | `string` | | 图片URL | -|     `sortOrder` | `int` | | 排序序号 | -|   `machineResult` | `string` | | 机审结果 | -|   `orderId` | `string` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `productType` | `string` | | 产品类型 | -|   `productTypeLabel` | `string` | | 产品类型标签 | -|   `ratingAccommodation` | `int` | | 住宿安排评分(1-5) | -|   `ratingDining` | `int` | | 餐饮质量评分(1-5) | -|   `ratingDriver` | `int` | | 司机服务评分(1-5) | -|   `ratingItinerary` | `int` | | 行程安排评分(1-5) | -|   `ratingLevel` | `string` | | 评价等级: GOOD/MEDIUM/BAD | -|   `ratingLevelLabel` | `string` | | 评价等级标签: 好评/中评/差评 | -|   `ratingOverall` | `int` | | 整体满意度评分(1-5) | -|   `rejectReason` | `string` | | 拒绝原因 | -|   `reviewId` | `string` | | 评价ID | -|   `reviewType` | `string` | | 评论类型 | -|   `reviewTypeLabel` | `string` | | 评论类型标签 | -|   `status` | `string` | | 评价状态 | -|   `statusLabel` | `string` | | 评价状态标签 | -|   `targetId` | `string` | | 评价目标ID | -|   `targetName` | `string` | | 评价目标名称 | -|   `targetType` | `string` | | 评价目标类型 | -|   `targetTypeLabel` | `string` | | 评价目标类型标签 | -|   `userAvatar` | `string` | | 用户头像 | -|   `userId` | `string` | | 用户ID | -|   `userNickname` | `string` | | 用户昵称 | -|   `videoCount` | `int` | | 视频数量 | -|   `videos` | `评价视频信息[]` | | 评价视频列表 | -|     `coverUrl` | `string` | | 视频封面URL | -|     `duration` | `int` | | 视频时长(秒) | -|     `fileId` | `string` | | 文件ID | -|     `sortOrder` | `int` | | 排序序号 | -|     `videoId` | `string` | | 视频ID | -|     `videoUrl` | `string` | | 视频URL | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/review/{reviewId}/approve - -**通过评价** - -审核通过评价，通过后评价在小程序端公开展示。状态流转：PENDING_REVIEW → APPROVED - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reviewId` | `integer` | | 评价ID | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /admin/review/{reviewId}/override-approve - -**覆盖通过(机器拒绝的)** - -对阿里云内容审核自动拒绝的评价进行人工覆盖通过。状态流转：AUTO_REJECTED → APPROVED - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reviewId` | `integer` | | 评价ID | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /admin/review/{reviewId}/reject - -**拒绝评价** - -审核拒绝评价，需填写拒绝原因。拒绝后评价不公开展示。状态流转：PENDING_REVIEW → REJECTED - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reviewId` | `integer` | | 评价ID | - -**请求体** `拒绝评价请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `rejectReason` | `string` | 是 | 拒绝原因 | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /admin/review/{reviewId}/reply - -**回复评价(每条评价仅可回复一次)** - -管理员回复用户评价，回复内容在小程序端公开展示。每条评价仅允许回复一次，不可修改。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reviewId` | `integer` | | 评价ID | - -**请求体** `管理员回复请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `replyContent` | `string` | 是 | 回复内容 | - -**响应** `统一响应结果«Void»` - ---- diff --git a/2026-03/17_1009/hl-task-service.md b/2026-03/17_1009/hl-task-service.md deleted file mode 100644 index 0631450..0000000 --- a/2026-03/17_1009/hl-task-service.md +++ /dev/null @@ -1,924 +0,0 @@ -# 任务服务 API 文档 - -**服务**: `hl-task-service` -**接口总数**: 27 - -## 目录 - -- **WebSocket 实时推送** (1 个接口) -- **任务看板管理** (13 个接口) -- **任务管理** (13 个接口) - ---- - -## WebSocket 实时推送 - -### `GET` /admin/task/board/ws-doc/info - -**WebSocket 连接说明** - -## 连接信息 - -| 项目 | 值 | -|------|-------| -| **连接地址** | `ws://{host}:8092/ws/task` | -| **协议** | STOMP over WebSocket（SockJS 降级方案） | -| **跨域** | 允许所有源 (`*`) | - -## 订阅频道 - -| 订阅地址 | 说明 | -|------------|-------------| -| `/topic/board/{boardId}` | 订阅指定看板，接收该看板下的实时任务事件 | - -## 推送消息格式 - -```json -{ - "event": "TASK_CREATED", - "data": { ... }, - "timestamp": 1709539200000 -} -``` - -## 事件类型 - -| 事件 | 说明 | data 内容 | -|-------|------------|------| -| TASK_CREATED | 任务创建 | 任务对象 | -| TASK_UPDATED | 任务更新 | 任务对象 | -| TASK_DELETED | 任务删除 | 任务ID | -| TASK_MOVED | 任务移动（状态变更） | 任务对象 | -| COMMENT_ADDED | 新增评论 | 评论对象 | - -## 前端接入示例 (SockJS + STOMP) - -```javascript -import SockJS from 'sockjs-client' -import { Stomp } from '@stomp/stompjs' - -const socket = new SockJS('http://localhost:8092/ws/task') -const stompClient = Stomp.over(socket) - -stompClient.connect({}, () => { - stompClient.subscribe('/topic/board/123', (msg) => { - const { event, data, timestamp } = JSON.parse(msg.body) - console.log('Event:', event, 'Data:', data) - }) -}) -``` - -**响应** `object` - ---- - -## 任务看板管理 - -### `POST` /admin/task/board - -**创建自定义看板** - -创建自定义看板，自动添加创建者为看板成员，并创建默认状态列（待办、进行中、已完成）。 - -**权限**：需管理员登录。 - -**请求体** `创建看板请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardName` | `string` | 是 | 看板名称 | -| `deptId` | `long` | | 部门ID | -| `description` | `string` | | 看板描述 | -| `memberIds` | `long[]` | | 成员ID列表 | - -**响应** `统一响应结果«看板信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板信息` | | 响应数据 | -|   `boardId` | `long` | | 看板ID | -|   `boardName` | `string` | | 看板名称 | -|   `boardType` | `string` | | 看板类型 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `deptId` | `long` | | 部门ID | -|   `deptName` | `string` | | 部门名称 | -|   `description` | `string` | | 看板描述 | -|   `statuses` | `看板状态信息[]` | | 状态列表 | -|     `isPreset` | `boolean` | | 是否预设状态 | -|     `sortOrder` | `int` | | 排序序号 | -|     `statusColor` | `string` | | 状态颜色 | -|     `statusId` | `long` | | 状态ID | -|     `statusName` | `string` | | 状态名称 | -|     `taskCount` | `int` | | 该状态下的任务数量 | -|   `taskCount` | `int` | | 任务总数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/task/board/{boardId} - -**看板详情** - -返回看板基本信息（名称、描述、创建者），不含任务数据。查看任务请使用「获取看板任务」接口 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**响应** `统一响应结果«看板信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板信息` | | 响应数据 | -|   `boardId` | `long` | | 看板ID | -|   `boardName` | `string` | | 看板名称 | -|   `boardType` | `string` | | 看板类型 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `deptId` | `long` | | 部门ID | -|   `deptName` | `string` | | 部门名称 | -|   `description` | `string` | | 看板描述 | -|   `statuses` | `看板状态信息[]` | | 状态列表 | -|     `isPreset` | `boolean` | | 是否预设状态 | -|     `sortOrder` | `int` | | 排序序号 | -|     `statusColor` | `string` | | 状态颜色 | -|     `statusId` | `long` | | 状态ID | -|     `statusName` | `string` | | 状态名称 | -|     `taskCount` | `int` | | 该状态下的任务数量 | -|   `taskCount` | `int` | | 任务总数 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/task/board/{boardId} - -**更新看板** - -更新看板的名称和描述。仅看板创建者或超级管理员可操作。 - -**权限**：需管理员登录，且为看板创建者或超级管理员。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**请求体** `更新看板请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardName` | `string` | | 看板名称 | -| `description` | `string` | | 看板描述 | - -**响应** `统一响应结果«看板信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板信息` | | 响应数据 | -|   `boardId` | `long` | | 看板ID | -|   `boardName` | `string` | | 看板名称 | -|   `boardType` | `string` | | 看板类型 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `deptId` | `long` | | 部门ID | -|   `deptName` | `string` | | 部门名称 | -|   `description` | `string` | | 看板描述 | -|   `statuses` | `看板状态信息[]` | | 状态列表 | -|     `isPreset` | `boolean` | | 是否预设状态 | -|     `sortOrder` | `int` | | 排序序号 | -|     `statusColor` | `string` | | 状态颜色 | -|     `statusId` | `long` | | 状态ID | -|     `statusName` | `string` | | 状态名称 | -|     `taskCount` | `int` | | 该状态下的任务数量 | -|   `taskCount` | `int` | | 任务总数 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/task/board/{boardId} - -**删除看板** - -删除看板及其下所有状态列和任务（级联删除）。仅看板创建者或超级管理员可操作 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**响应** `统一响应结果«Void»` - ---- - -### `DELETE` /admin/task/board/{boardId}/member/{targetAdminId} - -**移除成员** - -从看板中移除指定成员。仅看板创建者或超级管理员可操作，不能移除创建者自己 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | -| `targetAdminId` | `integer` | | 目标管理员ID | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/task/board/{boardId}/members - -**获取看板成员** - -返回看板的所有成员列表，包含成员的管理员ID和姓名 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**响应** `统一响应结果«List«看板成员信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板成员信息[]` | | 响应数据 | -|   `adminId` | `long` | | 管理员ID | -|   `avatarUrl` | `string` | | 头像地址 | -|   `joinedAt` | `string` | | 加入时间 | -|   `role` | `string` | | 角色: OWNER/MEMBER | -|   `username` | `string` | | 用户名 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/task/board/{boardId}/members - -**添加成员** - -批量添加管理员为看板成员，成为成员后可以查看看板、创建和操作任务。 - -**权限**：需管理员登录，且为看板创建者或超级管理员。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**请求体** `添加成员请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `adminIds` | `long[]` | 是 | 管理员ID列表 | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /admin/task/board/{boardId}/status - -**创建状态列** - -在看板中创建新的状态列（如测试中、待发布等），自动排到末尾。任务通过拖拽在不同状态列间流转。 - -**权限**：需管理员登录且为看板成员。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**请求体** `创建状态请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `statusColor` | `string` | | 状态颜色 | -| `statusName` | `string` | 是 | 状态名称 | - -**响应** `统一响应结果«看板状态信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板状态信息` | | 响应数据 | -|   `isPreset` | `boolean` | | 是否预设状态 | -|   `sortOrder` | `int` | | 排序序号 | -|   `statusColor` | `string` | | 状态颜色 | -|   `statusId` | `long` | | 状态ID | -|   `statusName` | `string` | | 状态名称 | -|   `taskCount` | `int` | | 该状态下的任务数量 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/task/board/{boardId}/status/sort - -**状态列排序** - -批量更新状态列的排序顺序。传入状态列ID数组，数组下标即为新的排序值。操作完成后通过WebSocket推送STATUS_REORDERED事件 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**请求体** `状态排序请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `statusIds` | `long[]` | 是 | 状态ID列表(按排序顺序) | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/task/board/{boardId}/statuses - -**获取看板状态列** - -返回看板的所有状态列（如待办、进行中、已完成），按排序字段升序排列。拖拽任务到不同状态列实现状态流转 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**响应** `统一响应结果«List«看板状态信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板状态信息[]` | | 响应数据 | -|   `isPreset` | `boolean` | | 是否预设状态 | -|   `sortOrder` | `int` | | 排序序号 | -|   `statusColor` | `string` | | 状态颜色 | -|   `statusId` | `long` | | 状态ID | -|   `statusName` | `string` | | 状态名称 | -|   `taskCount` | `int` | | 该状态下的任务数量 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/task/boards - -**获取可见看板列表** - -返回当前管理员可见的看板列表：超级管理员可见所有看板，普通管理员仅可见自己创建的或作为成员的看板 - -**响应** `统一响应结果«List«看板信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板信息[]` | | 响应数据 | -|   `boardId` | `long` | | 看板ID | -|   `boardName` | `string` | | 看板名称 | -|   `boardType` | `string` | | 看板类型 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `deptId` | `long` | | 部门ID | -|   `deptName` | `string` | | 部门名称 | -|   `description` | `string` | | 看板描述 | -|   `statuses` | `看板状态信息[]` | | 状态列表 | -|     `isPreset` | `boolean` | | 是否预设状态 | -|     `sortOrder` | `int` | | 排序序号 | -|     `statusColor` | `string` | | 状态颜色 | -|     `statusId` | `long` | | 状态ID | -|     `statusName` | `string` | | 状态名称 | -|     `taskCount` | `int` | | 该状态下的任务数量 | -|   `taskCount` | `int` | | 任务总数 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/task/status/{statusId} - -**更新状态列** - -更新状态列的名称和颜色。 - -**权限**：需管理员登录且为看板成员。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `statusId` | `integer` | | 状态列ID | - -**请求体** `更新状态请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `statusColor` | `string` | | 状态颜色 | -| `statusName` | `string` | | 状态名称 | - -**响应** `统一响应结果«看板状态信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板状态信息` | | 响应数据 | -|   `isPreset` | `boolean` | | 是否预设状态 | -|   `sortOrder` | `int` | | 排序序号 | -|   `statusColor` | `string` | | 状态颜色 | -|   `statusId` | `long` | | 状态ID | -|   `statusName` | `string` | | 状态名称 | -|   `taskCount` | `int` | | 该状态下的任务数量 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/task/status/{statusId} - -**删除状态列** - -删除看板的状态列。如果状态列下有任务则不允许删除，需先移动或删除任务 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `statusId` | `integer` | | 状态列ID | - -**响应** `统一响应结果«Void»` - ---- - -## 任务管理 - -### `POST` /admin/task - -**创建任务** - -在指定看板和状态列下创建任务。创建成功后通过WebSocket推送TASK_CREATED事件，并通知被分配的负责人 - -**关联字典**： -- task_priority：任务优先级（创建时选择） - -**请求体** `创建任务请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `assigneeIds` | `long[]` | | 负责人ID列表 | -| `boardId` | `long` | 是 | 看板ID | -| `description` | `string` | | 任务描述 | -| `dueDate` | `string` | | 截止日期 | -| `priority` | `string` | | 优先级: LOW/MEDIUM/HIGH/URGENT | -| `statusId` | `long` | | 状态ID | -| `title` | `string` | 是 | 任务标题 | - -**响应** `统一响应结果«任务信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `任务信息` | | 响应数据 | -|   `assignees` | `负责人信息[]` | | 负责人列表 | -|     `adminId` | `long` | | 管理员ID | -|     `avatarUrl` | `string` | | 头像地址 | -|     `username` | `string` | | 用户名 | -|     `wechatName` | `string` | | 企微昵称 | -|   `boardId` | `long` | | 看板ID | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 任务描述 | -|   `dueDate` | `string` | | 截止日期 | -|   `overdue` | `boolean` | | 是否逾期 | -|   `parentId` | `long` | | 父任务ID | -|   `priority` | `string` | | 优先级: LOW/MEDIUM/HIGH/URGENT | -|   `sortOrder` | `int` | | 排序序号 | -|   `statusColor` | `string` | | 状态颜色 | -|   `statusId` | `long` | | 状态ID | -|   `statusName` | `string` | | 状态名称 | -|   `subtaskCompleted` | `int` | | 已完成子任务数 | -|   `subtaskTotal` | `int` | | 子任务总数 | -|   `subtasks` | `子任务信息[]` | | 子任务列表 | -|     `completed` | `boolean` | | 是否已完成 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdBy` | `long` | | 创建人ID | -|     `creatorName` | `string` | | 创建人姓名 | -|     `taskId` | `long` | | 子任务ID | -|     `title` | `string` | | 子任务标题 | -|   `taskId` | `long` | | 任务ID | -|   `title` | `string` | | 任务标题 | -|   `updatedAt` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/task/board/{boardId}/tasks - -**获取看板任务(按状态分组)** - -返回看板下所有任务，按状态列分组。支持按优先级(HIGH/MEDIUM/LOW)和负责人筛选，每组内按排序值升序排列 - -**关联字典**： -- task_priority：任务优先级（列表筛选+显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `assigneeId` | `integer(int64)` | | 负责人ID | | -| `priority` | `string` | | 优先级 | | - -**响应** `统一响应结果«List«看板任务分组信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板任务分组信息[]` | | 响应数据 | -|   `sortOrder` | `int` | | 排序序号 | -|   `statusColor` | `string` | | 状态颜色 | -|   `statusId` | `long` | | 状态ID | -|   `statusName` | `string` | | 状态名称 | -|   `tasks` | `任务信息[]` | | 该状态下的任务列表 | -|     `assignees` | `负责人信息[]` | | 负责人列表 | -|     `boardId` | `long` | | 看板ID | -|     `createdAt` | `string` | | 创建时间 | -|     `createdBy` | `long` | | 创建人ID | -|     `creatorName` | `string` | | 创建人姓名 | -|     `description` | `string` | | 任务描述 | -|     `dueDate` | `string` | | 截止日期 | -|     `overdue` | `boolean` | | 是否逾期 | -|     `parentId` | `long` | | 父任务ID | -|     `priority` | `string` | | 优先级: LOW/MEDIUM/HIGH/URGENT | -|     `sortOrder` | `int` | | 排序序号 | -|     `statusColor` | `string` | | 状态颜色 | -|     `statusId` | `long` | | 状态ID | -|     `statusName` | `string` | | 状态名称 | -|     `subtaskCompleted` | `int` | | 已完成子任务数 | -|     `subtaskTotal` | `int` | | 子任务总数 | -|     `subtasks` | `子任务信息[]` | | 子任务列表 | -|     `taskId` | `long` | | 任务ID | -|     `title` | `string` | | 任务标题 | -|     `updatedAt` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/task/comment/{commentId} - -**删除评论** - -仅评论作者本人可删除自己的评论，系统自动生成的活动记录不可删除 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `commentId` | `integer` | | 评论ID | - -**响应** `统一响应结果«Void»` - ---- - -### `DELETE` /admin/task/subtask/{subtaskId} - -**删除子任务** - -删除指定子任务。 - -**权限**：需管理员登录且为看板成员。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `subtaskId` | `integer` | | 子任务ID | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/task/subtask/{subtaskId}/toggle - -**切换子任务完成状态** - -切换子任务的完成/未完成状态（toggle），完成状态切换会自动记录到任务时间线 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `subtaskId` | `integer` | | 子任务ID | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/task/{taskId} - -**任务详情** - -返回任务完整信息，包含子任务列表、负责人信息、附件列表等 - -**关联字典**： -- task_priority：任务优先级（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**响应** `统一响应结果«任务信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `任务信息` | | 响应数据 | -|   `assignees` | `负责人信息[]` | | 负责人列表 | -|     `adminId` | `long` | | 管理员ID | -|     `avatarUrl` | `string` | | 头像地址 | -|     `username` | `string` | | 用户名 | -|     `wechatName` | `string` | | 企微昵称 | -|   `boardId` | `long` | | 看板ID | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 任务描述 | -|   `dueDate` | `string` | | 截止日期 | -|   `overdue` | `boolean` | | 是否逾期 | -|   `parentId` | `long` | | 父任务ID | -|   `priority` | `string` | | 优先级: LOW/MEDIUM/HIGH/URGENT | -|   `sortOrder` | `int` | | 排序序号 | -|   `statusColor` | `string` | | 状态颜色 | -|   `statusId` | `long` | | 状态ID | -|   `statusName` | `string` | | 状态名称 | -|   `subtaskCompleted` | `int` | | 已完成子任务数 | -|   `subtaskTotal` | `int` | | 子任务总数 | -|   `subtasks` | `子任务信息[]` | | 子任务列表 | -|     `completed` | `boolean` | | 是否已完成 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdBy` | `long` | | 创建人ID | -|     `creatorName` | `string` | | 创建人姓名 | -|     `taskId` | `long` | | 子任务ID | -|     `title` | `string` | | 子任务标题 | -|   `taskId` | `long` | | 任务ID | -|   `title` | `string` | | 任务标题 | -|   `updatedAt` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/task/{taskId} - -**更新任务** - -更新任务的标题、描述、优先级、截止日期、负责人等信息。更新后通过WebSocket推送TASK_UPDATED事件，如果修改了负责人则额外通知新负责人。 - -**权限**：需管理员登录且为看板成员。 - -**关联字典**： -- task_priority：任务优先级（编辑时选择） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**请求体** `更新任务请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `assigneeIds` | `long[]` | | 负责人ID列表 | -| `description` | `string` | | 任务描述 | -| `dueDate` | `string` | | 截止日期 | -| `priority` | `string` | | 优先级: LOW/MEDIUM/HIGH/URGENT | -| `title` | `string` | | 任务标题 | - -**响应** `统一响应结果«任务信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `任务信息` | | 响应数据 | -|   `assignees` | `负责人信息[]` | | 负责人列表 | -|     `adminId` | `long` | | 管理员ID | -|     `avatarUrl` | `string` | | 头像地址 | -|     `username` | `string` | | 用户名 | -|     `wechatName` | `string` | | 企微昵称 | -|   `boardId` | `long` | | 看板ID | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 任务描述 | -|   `dueDate` | `string` | | 截止日期 | -|   `overdue` | `boolean` | | 是否逾期 | -|   `parentId` | `long` | | 父任务ID | -|   `priority` | `string` | | 优先级: LOW/MEDIUM/HIGH/URGENT | -|   `sortOrder` | `int` | | 排序序号 | -|   `statusColor` | `string` | | 状态颜色 | -|   `statusId` | `long` | | 状态ID | -|   `statusName` | `string` | | 状态名称 | -|   `subtaskCompleted` | `int` | | 已完成子任务数 | -|   `subtaskTotal` | `int` | | 子任务总数 | -|   `subtasks` | `子任务信息[]` | | 子任务列表 | -|     `completed` | `boolean` | | 是否已完成 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdBy` | `long` | | 创建人ID | -|     `creatorName` | `string` | | 创建人姓名 | -|     `taskId` | `long` | | 子任务ID | -|     `title` | `string` | | 子任务标题 | -|   `taskId` | `long` | | 任务ID | -|   `title` | `string` | | 任务标题 | -|   `updatedAt` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/task/{taskId} - -**删除任务** - -删除任务及其所有子任务、评论和时间线记录（级联删除）。删除后通过WebSocket推送TASK_DELETED事件。 - -**权限**：需管理员登录且为看板成员。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /admin/task/{taskId}/comment - -**添加评论** - -在任务时间线中添加评论，添加后自动通知任务负责人 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**请求体** `创建评论请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `content` | `string` | 是 | 评论内容 | - -**响应** `统一响应结果«时间线条目»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `时间线条目` | | 响应数据 | -|   `action` | `string` | | 操作类型 | -|   `adminAvatar` | `string` | | 管理员头像 | -|   `adminId` | `long` | | 管理员ID | -|   `adminName` | `string` | | 管理员姓名 | -|   `content` | `string` | | 内容 | -|   `createdAt` | `string` | | 创建时间 | -|   `id` | `long` | | 条目ID | -|   `newValue` | `string` | | 新值 | -|   `oldValue` | `string` | | 旧值 | -|   `type` | `string` | | 类型: COMMENT/ACTIVITY | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/task/{taskId}/sort - -**任务排序** - -更新任务在同一状态列内的排序位置，用于拖拽排序 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**请求体** `任务排序请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `statusId` | `long` | 是 | 状态ID | -| `taskIds` | `long[]` | 是 | 任务ID列表(按排序顺序) | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/task/{taskId}/status - -**变更任务状态** - -将任务移动到指定状态列（拖拽操作），自动记录状态变更到时间线，并通过WebSocket推送TASK_STATUS_CHANGED事件 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**请求体** `变更任务状态请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `statusId` | `long` | 是 | 目标状态ID | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /admin/task/{taskId}/subtask - -**创建子任务** - -在指定任务下创建子任务（待办项），用于拆分任务的执行步骤。子任务默认为未完成状态。 - -**权限**：需管理员登录且为看板成员。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**请求体** `创建子任务请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `title` | `string` | 是 | 子任务标题 | - -**响应** `统一响应结果«子任务信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `子任务信息` | | 响应数据 | -|   `completed` | `boolean` | | 是否已完成 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `taskId` | `long` | | 子任务ID | -|   `title` | `string` | | 子任务标题 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/task/{taskId}/timeline - -**获取任务时间线** - -返回任务的完整操作记录，包含评论和系统自动记录的状态变更、人员分配等活动，按时间正序排列 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**响应** `统一响应结果«List«时间线条目»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `时间线条目[]` | | 响应数据 | -|   `action` | `string` | | 操作类型 | -|   `adminAvatar` | `string` | | 管理员头像 | -|   `adminId` | `long` | | 管理员ID | -|   `adminName` | `string` | | 管理员姓名 | -|   `content` | `string` | | 内容 | -|   `createdAt` | `string` | | 创建时间 | -|   `id` | `long` | | 条目ID | -|   `newValue` | `string` | | 新值 | -|   `oldValue` | `string` | | 旧值 | -|   `type` | `string` | | 类型: COMMENT/ACTIVITY | -| `message` | `string` | | 响应消息 | - ---- diff --git a/2026-03/17_1009/hl-user-service.md b/2026-03/17_1009/hl-user-service.md deleted file mode 100644 index 161d57a..0000000 --- a/2026-03/17_1009/hl-user-service.md +++ /dev/null @@ -1,4570 +0,0 @@ -# 用户服务 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=启用） - - 完整字典值: `ACTIVE`=启用, `INACTIVE`=停用 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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=启用） - - 完整字典值: `ACTIVE`=启用, `INACTIVE`=停用 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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（订单状态）：仪表盘中订单统计按状态分组展示 - - 完整字典值: `PENDING_PAY`=待支付, `DEPOSIT_PAID`=已付定金, `PAID`=已全额支付, `CONFIRMED`=已确认, `PENDING_BALANCE`=待付尾款, `PENDING_DEPARTURE`=待出行, `TRAVELLING`=旅行中, `COMPLETED`=已完成, `AFTER_SALES`=售后中, `CANCELLED`=已取消, `REFUNDING`=退款中, `REFUNDED`=已退款 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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 - - 完整字典值: `PENDING_PAY`=待支付, `DEPOSIT_PAID`=已付定金, `PAID`=已全额支付, `CONFIRMED`=已确认, `PENDING_BALANCE`=待付尾款, `PENDING_DEPARTURE`=待出行, `TRAVELLING`=旅行中, `COMPLETED`=已完成, `AFTER_SALES`=售后中, `CANCELLED`=已取消, `REFUNDING`=退款中, `REFUNDED`=已退款 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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 - - 完整字典值: `DRAFT`=草稿, `PENDING_REVIEW`=待审核, `REVIEWED`=已审核, `REJECTED`=已驳回, `PUBLISHED`=已上架, `UNPUBLISHED`=已下架, `COMPLETED`=已完成 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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=差评（筛选条件+列表展示） - - 完整字典值: `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 - - 完整字典值: `PENDING_PAY`=待支付, `DEPOSIT_PAID`=已付定金, `PAID`=已全额支付, `CONFIRMED`=已确认, `PENDING_BALANCE`=待付尾款, `PENDING_DEPARTURE`=待出行, `TRAVELLING`=旅行中, `COMPLETED`=已完成, `AFTER_SALES`=售后中, `CANCELLED`=已取消, `REFUNDING`=退款中, `REFUNDED`=已退款 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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 - - 完整字典值: `DRAFT`=草稿, `PENDING_REVIEW`=待审核, `REVIEWED`=已审核, `REJECTED`=已驳回, `PUBLISHED`=已上架, `UNPUBLISHED`=已下架, `COMPLETED`=已完成 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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=启用） - - 完整字典值: `ACTIVE`=启用, `INACTIVE`=停用 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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=保险同步 - - 完整字典值: `DEFAULT`=默认分组, `SYSTEM`=系统任务, `WECHAT`=企微同步, `INSURANCE`=保险同步 -- job_misfire_policy（执行策略）：DEFAULT=默认策略, FIRE_ONCE=立即触发一次, DO_NOTHING=不触发 - - 完整字典值: `DEFAULT`=默认策略, `FIRE_ONCE`=立即触发一次, `DO_NOTHING`=不触发 -- job_status（任务状态）：ACTIVE=启用, PAUSED=已暂停 - - 完整字典值: `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=保险同步 - - 完整字典值: `DEFAULT`=默认分组, `SYSTEM`=系统任务, `WECHAT`=企微同步, `INSURANCE`=保险同步 -- job_misfire_policy（执行策略）：DEFAULT=默认策略, FIRE_ONCE=立即触发一次, DO_NOTHING=不触发 - - 完整字典值: `DEFAULT`=默认策略, `FIRE_ONCE`=立即触发一次, `DO_NOTHING`=不触发 -- job_status（任务状态）：ACTIVE=启用, PAUSED=已暂停 - - 完整字典值: `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=保险同步 - - 完整字典值: `DEFAULT`=默认分组, `SYSTEM`=系统任务, `WECHAT`=企微同步, `INSURANCE`=保险同步 -- job_misfire_policy（执行策略）：DEFAULT=默认策略, FIRE_ONCE=立即触发一次, DO_NOTHING=不触发 - - 完整字典值: `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=已封禁） - - 完整字典值: `ACTIVE`=正常, `INACTIVE`=未激活, `BANNED`=已封禁, `DELETED`=已注销 -- gender（性别）：返回字段gender（0=女, 1=男） - - 完整字典值: `1`=男, `2`=女 -- id_card_type（证件类型）：返回字段idCardType - - 完整字典值: `ID_CARD`=身份证, `PASSPORT`=护照, `HK_MACAU_PASS`=港澳通行证, `TAIWAN_PASS`=台湾通行证, `MILITARY_ID`=军官证, `OTHER`=其他 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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 - - 完整字典值: `ACTIVE`=正常, `INACTIVE`=未激活, `BANNED`=已封禁, `DELETED`=已注销 -- gender（性别）：返回字段gender - - 完整字典值: `1`=男, `2`=女 -- id_card_type（证件类型）：返回字段idCardType - - 完整字典值: `ID_CARD`=身份证, `PASSPORT`=护照, `HK_MACAU_PASS`=港澳通行证, `TAIWAN_PASS`=台湾通行证, `MILITARY_ID`=军官证, `OTHER`=其他 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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，前端据此判断跳转到哪种资源详情页 - - 完整字典值: `PRODUCT`=产品, `SCENIC`=景区, `RESTAURANT`=餐厅, `ACTIVITY`=活动, `HOTEL`=酒店 - - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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） - - 完整字典值: `PRODUCT`=产品, `SCENIC`=景区, `RESTAURANT`=餐厅, `ACTIVITY`=活动, `HOTEL`=酒店 - - -**请求体** `收藏请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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） - - 完整字典值: `PRODUCT`=产品, `SCENIC`=景区, `RESTAURANT`=餐厅, `ACTIVITY`=活动, `HOTEL`=酒店 - - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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，前端据此判断跳转到哪种资源详情页 - - 完整字典值: `PRODUCT`=产品, `SCENIC`=景区, `RESTAURANT`=餐厅, `ACTIVITY`=活动, `HOTEL`=酒店 - - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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） - - 完整字典值: `PRODUCT`=产品, `SCENIC`=景区, `RESTAURANT`=餐厅, `ACTIVITY`=活动, `HOTEL`=酒店 - - -**请求体** `足迹请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=护照 - - 完整字典值: `ID_CARD`=身份证, `PASSPORT`=护照, `HK_MACAU_PASS`=港澳通行证, `TAIWAN_PASS`=台湾通行证, `MILITARY_ID`=军官证, `OTHER`=其他 -- gender（性别）：0=女, 1=男 - - 完整字典值: `1`=男, `2`=女 - - -**响应** `统一响应结果«用户信息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） - - 完整字典值: `ID_CARD`=身份证, `PASSPORT`=护照, `HK_MACAU_PASS`=港澳通行证, `TAIWAN_PASS`=台湾通行证, `MILITARY_ID`=军官证, `OTHER`=其他 -- gender（性别）：0=女, 1=男 - - 完整字典值: `1`=男, `2`=女 - - -**请求体** `更新用户资料请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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 - - 完整字典值: `1`=男, `2`=女 -- id_card_type（证件类型）：返回字段idCardType - - 完整字典值: `ID_CARD`=身份证, `PASSPORT`=护照, `HK_MACAU_PASS`=港澳通行证, `TAIWAN_PASS`=台湾通行证, `MILITARY_ID`=军官证, `OTHER`=其他 -- traveler_type（出行人类型）：返回字段travelerType - - 完整字典值: `ADULT`=成人, `CHILD`=儿童, `YOUNG_CHILD`=小童, `BABY`=幼童 - -**响应** `统一响应结果«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=男） - - 完整字典值: `1`=男, `2`=女 -- id_card_type（证件类型）：请求/返回字段idCardType（ID_CARD=身份证, PASSPORT=护照等） - - 完整字典值: `ID_CARD`=身份证, `PASSPORT`=护照, `HK_MACAU_PASS`=港澳通行证, `TAIWAN_PASS`=台湾通行证, `MILITARY_ID`=军官证, `OTHER`=其他 -- traveler_type（出行人类型）：返回字段travelerType（ADULT=成人, CHILD=儿童, INFANT=婴儿，自动计算） - - 完整字典值: `ADULT`=成人, `CHILD`=儿童, `YOUNG_CHILD`=小童, `BABY`=幼童 - -**请求体** `出行人请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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 - - 完整字典值: `1`=男, `2`=女 -- id_card_type（证件类型）：返回字段idCardType - - 完整字典值: `ID_CARD`=身份证, `PASSPORT`=护照, `HK_MACAU_PASS`=港澳通行证, `TAIWAN_PASS`=台湾通行证, `MILITARY_ID`=军官证, `OTHER`=其他 -- traveler_type（出行人类型）：返回字段travelerType - - 完整字典值: `ADULT`=成人, `CHILD`=儿童, `YOUNG_CHILD`=小童, `BABY`=幼童 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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 - - 完整字典值: `1`=男, `2`=女 -- id_card_type（证件类型）：请求/返回字段idCardType - - 完整字典值: `ID_CARD`=身份证, `PASSPORT`=护照, `HK_MACAU_PASS`=港澳通行证, `TAIWAN_PASS`=台湾通行证, `MILITARY_ID`=军官证, `OTHER`=其他 -- traveler_type（出行人类型）：返回字段travelerType（自动计算） - - 完整字典值: `ADULT`=成人, `CHILD`=儿童, `YOUNG_CHILD`=小童, `BABY`=幼童 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=启用） - - 完整字典值: `ACTIVE`=启用, `INACTIVE`=停用 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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=启用） - - 完整字典值: `ACTIVE`=启用, `INACTIVE`=停用 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=启用） - - 完整字典值: `ACTIVE`=启用, `INACTIVE`=停用 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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=启用） - - 完整字典值: `ACTIVE`=启用, `INACTIVE`=停用 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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 - -**管理员列表** - -分页查询管理员列表，支持按角色、状态、企微绑定状态、关键词筛选。keyword支持模糊匹配用户名和企业微信名称。status取值：ACTIVE=正常 LOCKED=已锁定 DISABLED=已禁用。wechatBound：true=已绑定企业微信 false=未绑定。需要管理员认证。 - -**关联字典**： -- admin_status（管理员状态）：ACTIVE=启用, LOCKED=锁定, DISABLED=禁用（筛选条件+列表展示） - - 完整字典值: `ACTIVE`=正常, `INACTIVE`=禁用, `LOCKED`=锁定, `DELETED`=已删除 - - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `keyword` | `string` | | 关键词（模糊匹配用户名/企业微信名称） | | -| `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=禁用 - - 完整字典值: `ACTIVE`=正常, `INACTIVE`=禁用, `LOCKED`=锁定, `DELETED`=已删除 - - -**请求体** `创建管理员请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=禁用 - - 完整字典值: `ACTIVE`=正常, `INACTIVE`=禁用, `LOCKED`=锁定, `DELETED`=已删除 - - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=禁用 - - 完整字典值: `ACTIVE`=正常, `INACTIVE`=禁用, `LOCKED`=锁定, `DELETED`=已删除 - - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=邮箱等） - - 完整字典值: `ABOUT`=关于我们, `ONLINE_CS`=在线客服, `PHONE`=电话咨询 -- common_status（通用状态）：请求参数status和返回字段status - - 完整字典值: `ACTIVE`=启用, `INACTIVE`=停用 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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 - - 完整字典值: `ABOUT`=关于我们, `ONLINE_CS`=在线客服, `PHONE`=电话咨询 - -**请求体** `联系我们请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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 - - 完整字典值: `ABOUT`=关于我们, `ONLINE_CS`=在线客服, `PHONE`=电话咨询 -- common_status（通用状态）：返回字段status - - 完整字典值: `ACTIVE`=启用, `INACTIVE`=停用 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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 - - 完整字典值: `ABOUT`=关于我们, `ONLINE_CS`=在线客服, `PHONE`=电话咨询 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=按钮） - - 完整字典值: `D`=目录, `M`=菜单, `B`=按钮 -- common_status（通用状态）：返回字段status - - 完整字典值: `ACTIVE`=启用, `INACTIVE`=停用 - -**请求体** `创建菜单请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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 - - 完整字典值: `D`=目录, `M`=菜单, `B`=按钮 -- common_status（通用状态）：返回字段status - - 完整字典值: `ACTIVE`=启用, `INACTIVE`=停用 - -**响应** `统一响应结果«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=按钮） - - 完整字典值: `D`=目录, `M`=菜单, `B`=按钮 -- common_status（通用状态）：返回字段status - - 完整字典值: `ACTIVE`=启用, `INACTIVE`=停用 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=按钮） - - 完整字典值: `D`=目录, `M`=菜单, `B`=按钮 -- common_status（通用状态）：请求字段status - - 完整字典值: `ACTIVE`=启用, `INACTIVE`=停用 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=禁用（筛选条件+列表展示） - - 完整字典值: `ACTIVE`=启用, `INACTIVE`=停用 - - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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=禁用 - - 完整字典值: `ACTIVE`=启用, `INACTIVE`=停用 - - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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/2026-03/17_1012/dict-reference.md b/2026-03/17_1012/dict-reference.md deleted file mode 100644 index 32d706f..0000000 --- a/2026-03/17_1012/dict-reference.md +++ /dev/null @@ -1,2204 +0,0 @@ -# 数据字典参考 - -**更新时间**: 2026-03-17 10:12 -**字典总数**: 115 - -## 目录 - -- [游玩项目计费方式（`activity_billing_type`）](#activity_billing_type) — 4 项 -- [游玩项目分类（`activity_category`）](#activity_category) — 22 项 -- [游玩项目环境类型（`activity_environment_type`）](#activity_environment_type) — 3 项 -- [游玩项目体力等级（`activity_physical_level`）](#activity_physical_level) — 4 项 -- [管理员状态（`admin_status`）](#admin_status) — 4 项 -- [适用角色（`apply_role`）](#apply_role) — 0 项 -- [审批状态（`approval_sp_status`）](#approval_sp_status) — 7 项 -- [Banner链接类型（`banner_link_type`）](#banner_link_type) — 5 项 -- [Banner媒体类型（`banner_media_type`）](#banner_media_type) — 2 项 -- [团期状态（`batch_status`）](#batch_status) — 8 项 -- [卫浴类型（`bathroom_type`）](#bathroom_type) — 2 项 -- [床型（`bed_type`）](#bed_type) — 6 项 -- [计费方式（`billing_type`）](#billing_type) — 2 项 -- [服务计费方式（`billing_type_service`）](#billing_type_service) — 6 项 -- [日历状态（`calendar_status`）](#calendar_status) — 3 项 -- [城市（`cities`）](#cities) — 15 项 -- [城市筛选（`city`）](#city) — 8 项 -- [通用状态（`common_status`）](#common_status) — 2 项 -- [联系我们渠道类型（`contact_channel_type`）](#contact_channel_type) — 3 项 -- [合同模式（`contract_mode`）](#contract_mode) — 2 项 -- [合同平台（`contract_platform`）](#contract_platform) — 2 项 -- [合同状态（`contract_status`）](#contract_status) — 8 项 -- [费用适用角色（`cost_apply_role`）](#cost_apply_role) — 6 项 -- [成本分类（`cost_category`）](#cost_category) — 15 项 -- [费用项分类（`cost_item_category`）](#cost_item_category) — 9 项 -- [费用计价单位（`cost_unit`）](#cost_unit) — 7 项 -- [菜系类型（`cuisine_type`）](#cuisine_type) — 10 项 -- [部门状态（`dept_status`）](#dept_status) — 2 项 -- [字典分类（`dict_category`）](#dict_category) — 2 项 -- [证件类型（`document_type`）](#document_type) — 6 项 -- [驱动方式（`drive_type`）](#drive_type) — 0 项 -- [驾照类型（`driver_license_type`）](#driver_license_type) — 7 项 -- [动力类型（`engine_type`）](#engine_type) — 4 项 -- [环境类型（`environment_type`）](#environment_type) — 3 项 -- [民族（`ethnicity`）](#ethnicity) — 56 项 -- [收藏资源类型（`favorite_resource_type`）](#favorite_resource_type) — 5 项 -- [文件分组（`file_group`）](#file_group) — 12 项 -- [文件状态（`file_status`）](#file_status) — 3 项 -- [文件类型（`file_type`）](#file_type) — 5 项 -- [浏览历史资源类型（`footprint_resource_type`）](#footprint_resource_type) — 5 项 -- [前端配置分组（`frontend_config_group`）](#frontend_config_group) — 6 项 -- [性别（`gender`）](#gender) — 2 项 -- [导游等级（`guide_level`）](#guide_level) — 4 项 -- [导游服务区域（`guide_service_area`）](#guide_service_area) — 9 项 -- [导游专长（`guide_specialty`）](#guide_specialty) — 7 项 -- [酒店配套设施（`hotel_facility`）](#hotel_facility) — 20 项 -- [酒店星级（`hotel_star_level`）](#hotel_star_level) — 6 项 -- [住宿类型（`hotel_type`）](#hotel_type) — 5 项 -- [证件类型（`id_card_type`）](#id_card_type) — 6 项 -- [保险状态（`insurance_status`）](#insurance_status) — 4 项 -- [任务分组（`job_group`）](#job_group) — 4 项 -- [任务日志状态（`job_log_status`）](#job_log_status) — 2 项 -- [任务补偿策略（`job_misfire_policy`）](#job_misfire_policy) — 3 项 -- [任务状态（`job_status`）](#job_status) — 2 项 -- [语言能力（`language`）](#language) — 8 项 -- [登录状态（`login_status`）](#login_status) — 3 项 -- [素材分类（`material_category`）](#material_category) — 15 项 -- [素材审核状态（`material_review_status`）](#material_review_status) — 2 项 -- [素材标签（`material_tag`）](#material_tag) — 10 项 -- [餐饮类型（`meal_type`）](#meal_type) — 4 项 -- [菜单类型（`menu_type`）](#menu_type) — 3 项 -- [通知渠道（`notification_channel`）](#notification_channel) — 5 项 -- [通知事件分类（`notification_event_category`）](#notification_event_category) — 7 项 -- [通知发送状态（`notification_send_status`）](#notification_send_status) — 4 项 -- [通知类型（`notification_type`）](#notification_type) — 2 项 -- [在线状态（`online_status`）](#online_status) — 2 项 -- [订单变更原因（`order_change_reason`）](#order_change_reason) — 7 项 -- [订单显示状态(C端)（`order_display_status`）](#order_display_status) — 5 项 -- [订单内部流程状态（`order_process_status`）](#order_process_status) — 8 项 -- [订单状态（`order_status`）](#order_status) — 12 项 -- [订单操作类型（`order_timeline_action`）](#order_timeline_action) — 26 项 -- [订单待办类型（`order_todo_type`）](#order_todo_type) — 7 项 -- [支付模式（`payment_mode`）](#payment_mode) — 2 项 -- [产品分类（`product_category`）](#product_category) — 5 项 -- [行程节点类型（`product_node_type`）](#product_node_type) — 10 项 -- [产品状态（`product_status`）](#product_status) — 7 项 -- [产品类型（`product_type`）](#product_type) — 4 项 -- [推送任务状态（`push_task_status`）](#push_task_status) — 4 项 -- [评价等级（`rating_level`）](#rating_level) — 3 项 -- [退款原因（`refund_reason`）](#refund_reason) — 11 项 -- [退款原因分类（`refund_reason_category`）](#refund_reason_category) — 3 项 -- [退款状态（`refund_status`）](#refund_status) — 8 项 -- [退款类型（`refund_type`）](#refund_type) — 3 项 -- [餐厅分类（`restaurant_category`）](#restaurant_category) — 8 项 -- [餐厅设施（`restaurant_facility`）](#restaurant_facility) — 10 项 -- [评分类别（`review_rating_category`）](#review_rating_category) — 6 项 -- [评价审核状态（`review_status`）](#review_status) — 6 项 -- [评价目标类型（`review_target_type`）](#review_target_type) — 5 项 -- [房型分类（`room_category`）](#room_category) — 11 项 -- [房型设施（`room_facility`）](#room_facility) — 44 项 -- [景区设施（`scenic_facility`）](#scenic_facility) — 12 项 -- [景区荣誉称号（`scenic_honor`）](#scenic_honor) — 10 项 -- [季节（`season`）](#season) — 4 项 -- [服务项计费方式（`service_billing_type`）](#service_billing_type) — 6 项 -- [服务分类（`service_category`）](#service_category) — 9 项 -- [服务计价单位（`service_unit`）](#service_unit) — 5 项 -- [结算状态（`settle_status`）](#settle_status) — 4 项 -- [团期人员角色（`staff_role`）](#staff_role) — 4 项 -- [人员类型（`staff_type`）](#staff_type) — 5 项 -- [备品分类（`supplies_category`）](#supplies_category) — 8 项 -- [是否（`sys_yes_no`）](#sys_yes_no) — 2 项 -- [任务优先级（`task_priority`）](#task_priority) — 4 项 -- [变速箱（`transmission`）](#transmission) — 0 项 -- [出行人类型（`traveler_type`）](#traveler_type) — 4 项 -- [出行人年龄规则（`traveler_type_age_rule`）](#traveler_type_age_rule) — 4 项 -- [行程状态（`trip_status`）](#trip_status) — 3 项 -- [行程类型（`trip_type`）](#trip_type) — 4 项 -- [用户状态（`user_status`）](#user_status) — 4 项 -- [车型（`vehicle_type`）](#vehicle_type) — 5 项 -- [百科分类（`wiki_category`）](#wiki_category) — 7 项 -- [文章状态（`wiki_status`）](#wiki_status) — 3 项 -- [窗户类型（`window_type`）](#window_type) — 3 项 -- [工单优先级（`work_order_priority`）](#work_order_priority) — 4 项 -- [工单状态（`work_order_status`）](#work_order_status) — 4 项 -- [工单类型（`work_order_type`）](#work_order_type) — 5 项 - ---- - -## 游玩项目计费方式（`activity_billing_type`） {#activity_billing_type} - -> 游玩项目计费方式字典 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PER_PERSON` | 按人 | ACTIVE | -| `PER_GROUP` | 按组/场 | ACTIVE | -| `PER_HOUR` | 按小时 | ACTIVE | -| `PER_SESSION` | 按场次 | ACTIVE | - ---- - -## 游玩项目分类（`activity_category`） {#activity_category} - -> 游玩项目分类字典 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `horse_riding` | 马术骑行 | ACTIVE | -| `motor_sport` | 机动越野 | ACTIVE | -| `water_sport` | 水上项目 | ACTIVE | -| `archery_combat` | 射箭搏击 | ACTIVE | -| `cultural_experience` | 民俗文化 | ACTIVE | -| `food_craft` | 美食手作 | ACTIVE | -| `nature_explore` | 自然探索 | ACTIVE | -| `campfire_party` | 篝火聚会 | ACTIVE | -| `winter_sport` | 冬季项目 | ACTIVE | -| `parent_child` | 亲子互动 | ACTIVE | -| `OUTDOOR` | 户外运动 | ACTIVE | -| `OUTDOOR_SPORT` | 户外竞技 | ACTIVE | -| `ENTERTAINMENT` | 休闲娱乐 | ACTIVE | -| `ANIMAL` | 动物互动 | ACTIVE | -| `EXTREME` | 极限运动 | ACTIVE | -| `CULTURAL` | 文化体验 | ACTIVE | -| `EDUCATION` | 研学教育 | ACTIVE | -| `PHOTOGRAPHY` | 摄影写真 | ACTIVE | -| `PERFORMANCE` | 演出表演 | ACTIVE | -| `HORSEBACK` | 骑马体验 | ACTIVE | -| `CATERING` | 餐饮服务 | ACTIVE | -| `DINING` | 用餐体验 | ACTIVE | - ---- - -## 游玩项目环境类型（`activity_environment_type`） {#activity_environment_type} - -> 游玩项目环境类型字典 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `INDOOR` | 室内 | ACTIVE | -| `OUTDOOR` | 户外 | ACTIVE | -| `MIXED` | 混合 | ACTIVE | - ---- - -## 游玩项目体力等级（`activity_physical_level`） {#activity_physical_level} - -> 游玩项目体力等级字典 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `EASY` | 休闲 | ACTIVE | -| `MODERATE` | 适中 | ACTIVE | -| `HARD` | 较强 | ACTIVE | -| `EXTREME` | 高强度 | ACTIVE | - ---- - -## 管理员状态（`admin_status`） {#admin_status} - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `ACTIVE` | 正常 | ACTIVE | -| `INACTIVE` | 禁用 | ACTIVE | -| `LOCKED` | 锁定 | ACTIVE | -| `DELETED` | 已删除 | ACTIVE | - -**使用该字典的接口**: - -- `GET /admin/user` — 管理员列表（用户服务） -- `POST /admin/user` — 创建管理员（用户服务） -- `GET /admin/user/{adminId}` — 获取管理员详情（用户服务） -- `PUT /admin/user/{adminId}` — 更新管理员（用户服务） - ---- - -## 适用角色（`apply_role`） {#apply_role} - -**分类**: BUSINESS - -> 暂无字典项 - ---- - -## 审批状态（`approval_sp_status`） {#approval_sp_status} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `1` | 审批中 | ACTIVE | -| `2` | 已通过 | ACTIVE | -| `3` | 已驳回 | ACTIVE | -| `4` | 已撤销 | ACTIVE | -| `6` | 通过后撤销 | ACTIVE | -| `7` | 已删除 | ACTIVE | -| `10` | 已支付 | ACTIVE | - ---- - -## Banner链接类型（`banner_link_type`） {#banner_link_type} - -> 首页Banner点击跳转的链接类型 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PRODUCT` | 产品详情 | ACTIVE | -| `ARTICLE` | 文章详情 | ACTIVE | -| `URL` | 外部链接 | ACTIVE | -| `MINI_PAGE` | 小程序页面 | ACTIVE | -| `NONE` | 无跳转 | ACTIVE | - ---- - -## Banner媒体类型（`banner_media_type`） {#banner_media_type} - -> 首页Banner支持的媒体类型 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `IMAGE` | 图片 | ACTIVE | -| `VIDEO` | 视频 | ACTIVE | - ---- - -## 团期状态（`batch_status`） {#batch_status} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PENDING` | 待开放 | ACTIVE | -| `ENROLLING` | 报名中 | ACTIVE | -| `CONFIRMED` | 已成团 | ACTIVE | -| `FULL` | 已满员 | ACTIVE | -| `CLOSED` | 已截止 | ACTIVE | -| `DISBANDED` | 已散团 | ACTIVE | -| `IN_PROGRESS` | 出行中 | ACTIVE | -| `FINISHED` | 已结束 | ACTIVE | - -**使用该字典的接口**: - -- `POST /admin/product/item/{productId}/batch` — 创建主批次（产品服务） -- `GET /admin/product/item/{productId}/batch/list` — 批次列表(树形)（产品服务） -- `GET /admin/product/item/{productId}/batch/{batchId}` — 批次详情（产品服务） - ---- - -## 卫浴类型（`bathroom_type`） {#bathroom_type} - -> Bathroom types - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PRIVATE` | 独立卫浴 | ACTIVE | -| `SHARED` | 公共卫浴 | ACTIVE | - ---- - -## 床型（`bed_type`） {#bed_type} - -> Bed types - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `SINGLE_BED` | 单人床 | ACTIVE | -| `DOUBLE_BED` | 双人床 | ACTIVE | -| `TWIN_BED` | 双床 | ACTIVE | -| `KING_BED` | 大床 | ACTIVE | -| `TATAMI` | 榻榻米 | ACTIVE | -| `KANG` | 火炕 | ACTIVE | - ---- - -## 计费方式（`billing_type`） {#billing_type} - -> 备品计费方式 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `BY_PERSON` | 按人头 | ACTIVE | -| `BY_COUNT` | 按件 | ACTIVE | - ---- - -## 服务计费方式（`billing_type_service`） {#billing_type_service} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `FLAT_RATE` | 一口价 | ACTIVE | -| `PER_PERSON` | 按人头 | ACTIVE | -| `PER_HOUR` | 按小时 | ACTIVE | -| `PER_DAY` | 按天 | ACTIVE | -| `PER_DISTANCE` | 按距离 | ACTIVE | -| `CUSTOM` | 自定义 | ACTIVE | - ---- - -## 日历状态（`calendar_status`） {#calendar_status} - -> 价格日历中每日的状态 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `AVAILABLE` | 可售 | ACTIVE | -| `SOLD_OUT` | 已售罄 | ACTIVE | -| `CLOSED` | 已关闭 | ACTIVE | - ---- - -## 城市（`cities`） {#cities} - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `hailar` | 海拉尔 | ACTIVE | -| `manzhouli` | 满洲里 | ACTIVE | -| `eergu` | 额尔古纳 | ACTIVE | -| `genhe` | 根河 | ACTIVE | -| `yakeshi` | 牙克石 | ACTIVE | -| `zhalantun` | 扎兰屯 | ACTIVE | -| `aershan` | 阿尔山 | ACTIVE | -| `shiwei` | 室韦 | ACTIVE | -| `enhe` | 恩和 | ACTIVE | -| `heishantou` | 黑山头 | ACTIVE | -| `chenbaerhu` | 陈巴尔虎旗 | ACTIVE | -| `xinbaerhuzuo` | 新巴尔虎左旗 | ACTIVE | -| `xinbaerhuyou` | 新巴尔虎右旗 | ACTIVE | -| `ewenke` | 鄂温克旗 | ACTIVE | -| `moerdaoga` | 莫尔道嘎 | ACTIVE | - -**使用该字典的接口**: - -- `GET /admin/product/district/search` — 搜索行政区划（城市/区县）（产品服务） -- `GET /admin/product/item/{productId}/day/{dayNumber}/nodes` — 获取某天的节点列表（产品服务） -- `PUT /admin/product/node/{nodeId}` — 更新行程节点（产品服务） - ---- - -## 城市筛选（`city`） {#city} - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `hailar` | 海拉尔 | ACTIVE | -| `manzhouli` | 满洲里 | ACTIVE | -| `eergu` | 额尔古纳 | ACTIVE | -| `genhe` | 根河 | ACTIVE | -| `aershan` | 阿尔山 | ACTIVE | -| `shiwei` | 室韦 | ACTIVE | -| `enhe` | 恩和 | ACTIVE | -| `heishantou` | 黑山头 | ACTIVE | - -**使用该字典的接口**: - -- `GET /admin/product/district/search` — 搜索行政区划（城市/区县）（产品服务） -- `POST /admin/product/item/{productId}/day/{dayNumber}/node` — 添加行程节点（产品服务） -- `GET /admin/product/item/{productId}/day/{dayNumber}/nodes` — 获取某天的节点列表（产品服务） -- `PUT /admin/product/node/{nodeId}` — 更新行程节点（产品服务） - ---- - -## 通用状态（`common_status`） {#common_status} - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `ACTIVE` | 启用 | ACTIVE | -| `INACTIVE` | 停用 | ACTIVE | - -**使用该字典的接口**: - -- `GET /admin/banner` — Banner列表（用户服务） -- `GET /admin/banner/{id}` — Banner详情（用户服务） -- `GET /admin/contact` — 联系方式列表（用户服务） -- `GET /admin/contact/{id}` — 联系方式详情（用户服务） -- `GET /admin/explore/category` — 探索分类列表（用户服务） -- `GET /admin/explore/category/{id}` — 探索分类详情（用户服务） -- `GET /admin/frontend-config` — 配置列表（用户服务） -- `GET /admin/agreement` — 协议列表（用户服务） -- `GET /admin/agreement/{id}` — 协议详情（用户服务） -- `GET /admin/role` — 分页查询角色（用户服务） -- `PUT /admin/role/{roleId}` — 更新角色（用户服务） -- `POST /admin/menu` — 创建菜单（用户服务） -- `GET /admin/menu/tree` — 获取完整菜单树（用户服务） -- `GET /admin/menu/{menuId}` — 获取菜单详情（用户服务） -- `PUT /admin/menu/{menuId}` — 更新菜单（用户服务） - ---- - -## 联系我们渠道类型（`contact_channel_type`） {#contact_channel_type} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `ABOUT` | 关于我们 | ACTIVE | -| `ONLINE_CS` | 在线客服 | ACTIVE | -| `PHONE` | 电话咨询 | ACTIVE | - -**使用该字典的接口**: - -- `GET /admin/contact` — 联系方式列表（用户服务） -- `POST /admin/contact` — 创建联系方式（用户服务） -- `GET /admin/contact/{id}` — 联系方式详情（用户服务） -- `PUT /admin/contact/{id}` — 更新联系方式（用户服务） - ---- - -## 合同模式（`contract_mode`） {#contract_mode} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `STANDARD` | 电子签署 | ACTIVE | -| `SYNC` | 纸质上报 | ACTIVE | - ---- - -## 合同平台（`contract_platform`） {#contract_platform} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `12301` | 12301 | ACTIVE | -| `FADADA` | 法大大 | ACTIVE | - ---- - -## 合同状态（`contract_status`） {#contract_status} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PENDING` | 待生成 | ACTIVE | -| `GENERATED` | 已生成 | ACTIVE | -| `SIGNING` | 签署中 | ACTIVE | -| `SIGNED` | 已签署 | ACTIVE | -| `VOIDING` | 作废中 | ACTIVE | -| `VOIDED` | 已作废 | ACTIVE | -| `REPORTED` | 已上报 | ACTIVE | -| `UPLOADED` | 已上传 | ACTIVE | - ---- - -## 费用适用角色（`cost_apply_role`） {#cost_apply_role} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `DRIVER` | 司机 | ACTIVE | -| `GUIDE` | 导游 | ACTIVE | -| `VEHICLE` | 车辆 | ACTIVE | -| `THIRD_PARTY` | 第三方 | ACTIVE | -| `COMPANY` | 公司 | ACTIVE | -| `OTHER` | 其他 | ACTIVE | - ---- - -## 成本分类（`cost_category`） {#cost_category} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `ACCOMMODATION` | 住宿 | ACTIVE | -| `TRANSPORT` | 交通 | ACTIVE | -| `TICKET` | 门票 | ACTIVE | -| `ACTIVITY` | 活动 | ACTIVE | -| `DINING` | 餐饮 | ACTIVE | -| `PERSONAL` | 个人消费 | ACTIVE | -| `VEHICLE_EXTRA` | 车辆附加 | ACTIVE | -| `SELF_PAY` | 自费项目 | ACTIVE | -| `meal_subsidy` | 餐补 | ACTIVE | -| `accommodation_subsidy` | 住宿补贴 | ACTIVE | -| `fuel_cost` | 油费 | ACTIVE | -| `guide_fee` | 导游费 | ACTIVE | -| `insurance` | 保险 | ACTIVE | -| `parking_fee` | 停车费 | ACTIVE | -| `tip` | 小费 | ACTIVE | - ---- - -## 费用项分类（`cost_item_category`） {#cost_item_category} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `meal_subsidy` | 餐饮补贴 | ACTIVE | -| `accommodation_subsidy` | 住宿补贴 | ACTIVE | -| `fuel_cost` | 油费/能源 | ACTIVE | -| `toll_fee` | 过路过桥费 | ACTIVE | -| `parking_fee` | 停车费 | ACTIVE | -| `guide_fee` | 讲解费 | ACTIVE | -| `insurance` | 保险费 | ACTIVE | -| `tip` | 小费/奖励 | ACTIVE | -| `other` | 其他 | ACTIVE | - ---- - -## 费用计价单位（`cost_unit`） {#cost_unit} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PER_PERSON` | 元/人 | ACTIVE | -| `PER_VEHICLE` | 元/台 | ACTIVE | -| `PER_DAY` | 元/天 | ACTIVE | -| `PER_TIME` | 元/次 | ACTIVE | -| `PER_ROOM` | 元/间 | ACTIVE | -| `PER_TABLE` | 元/桌 | ACTIVE | -| `FIXED` | 固定金额 | ACTIVE | - ---- - -## 菜系类型（`cuisine_type`） {#cuisine_type} - -> 餐厅菜系类型 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `local` | 本地菜 | ACTIVE | -| `mongolian` | 蒙餐 | ACTIVE | -| `northeastern` | 东北菜 | ACTIVE | -| `sichuan` | 川菜 | ACTIVE | -| `halal` | 清真 | ACTIVE | -| `russian` | 俄餐 | ACTIVE | -| `western` | 西餐 | ACTIVE | -| `japanese_korean` | 日韩料理 | ACTIVE | -| `fusion` | 融合菜 | ACTIVE | -| `vegetarian` | 素食 | ACTIVE | - ---- - -## 部门状态（`dept_status`） {#dept_status} - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `ACTIVE` | 正常 | ACTIVE | -| `DELETED` | 已删除 | ACTIVE | - ---- - -## 字典分类（`dict_category`） {#dict_category} - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `BASE` | 基础字典 | ACTIVE | -| `BUSINESS` | 业务字典 | ACTIVE | - ---- - -## 证件类型（`document_type`） {#document_type} - -> C端出行人证件类型 - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `ID_CARD` | 居民身份证 | ACTIVE | -| `PASSPORT` | 护照 | ACTIVE | -| `HONG_KONG_MACAO_PASS` | 港澳居民来往内地通行证 | ACTIVE | -| `TAIWAN_PASS` | 台湾居民来往大陆通行证 | ACTIVE | -| `FOREIGN_PERMANENT_RESIDENT` | 外国人永久居留身份证 | ACTIVE | -| `OTHER` | 其他 | ACTIVE | - ---- - -## 驱动方式（`drive_type`） {#drive_type} - -**分类**: BUSINESS - -> 暂无字典项 - ---- - -## 驾照类型（`driver_license_type`） {#driver_license_type} - -> 司机的驾驶证类型 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `C1` | C1 | ACTIVE | -| `C2` | C2 | ACTIVE | -| `B1` | B1 | ACTIVE | -| `B2` | B2 | ACTIVE | -| `A1` | A1 | ACTIVE | -| `A2` | A2 | ACTIVE | -| `A3` | A3 | ACTIVE | - ---- - -## 动力类型（`engine_type`） {#engine_type} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `GASOLINE` | 汽油 | ACTIVE | -| `DIESEL` | 柴油 | ACTIVE | -| `HYBRID` | 混动 | ACTIVE | -| `ELECTRIC` | 纯电 | ACTIVE | - ---- - -## 环境类型（`environment_type`） {#environment_type} - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `INDOOR` | 室内 | ACTIVE | -| `OUTDOOR` | 户外 | ACTIVE | -| `MIXED` | 混合 | ACTIVE | - ---- - -## 民族（`ethnicity`） {#ethnicity} - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `汉族` | 汉族 | ACTIVE | -| `藏族` | 藏族 | ACTIVE | -| `蒙古族` | 蒙古族 | ACTIVE | -| `回族` | 回族 | ACTIVE | -| `维吾尔族` | 维吾尔族 | ACTIVE | -| `苗族` | 苗族 | ACTIVE | -| `彝族` | 彝族 | ACTIVE | -| `壮族` | 壮族 | ACTIVE | -| `布依族` | 布依族 | ACTIVE | -| `朝鲜族` | 朝鲜族 | ACTIVE | -| `满族` | 满族 | ACTIVE | -| `侗族` | 侗族 | ACTIVE | -| `瑶族` | 瑶族 | ACTIVE | -| `白族` | 白族 | ACTIVE | -| `土家族` | 土家族 | ACTIVE | -| `哈尼族` | 哈尼族 | ACTIVE | -| `哈萨克族` | 哈萨克族 | ACTIVE | -| `傣族` | 傣族 | ACTIVE | -| `黎族` | 黎族 | ACTIVE | -| `傈僳族` | 傈僳族 | ACTIVE | -| `佤族` | 佤族 | ACTIVE | -| `畲族` | 畲族 | ACTIVE | -| `高山族` | 高山族 | ACTIVE | -| `拉祜族` | 拉祜族 | ACTIVE | -| `水族` | 水族 | ACTIVE | -| `东乡族` | 东乡族 | ACTIVE | -| `纳西族` | 纳西族 | ACTIVE | -| `景颇族` | 景颇族 | ACTIVE | -| `柯尔克孜族` | 柯尔克孜族 | ACTIVE | -| `土族` | 土族 | ACTIVE | -| `达斡尔族` | 达斡尔族 | ACTIVE | -| `仫佬族` | 仫佬族 | ACTIVE | -| `羌族` | 羌族 | ACTIVE | -| `布朗族` | 布朗族 | ACTIVE | -| `撒拉族` | 撒拉族 | ACTIVE | -| `毛南族` | 毛南族 | ACTIVE | -| `仡佬族` | 仡佬族 | ACTIVE | -| `锡伯族` | 锡伯族 | ACTIVE | -| `阿昌族` | 阿昌族 | ACTIVE | -| `普米族` | 普米族 | ACTIVE | -| `塔吉克族` | 塔吉克族 | ACTIVE | -| `怒族` | 怒族 | ACTIVE | -| `乌孜别克族` | 乌孜别克族 | ACTIVE | -| `俄罗斯族` | 俄罗斯族 | ACTIVE | -| `鄂温克族` | 鄂温克族 | ACTIVE | -| `德昂族` | 德昂族 | ACTIVE | -| `保安族` | 保安族 | ACTIVE | -| `裕固族` | 裕固族 | ACTIVE | -| `京族` | 京族 | ACTIVE | -| `塔塔尔族` | 塔塔尔族 | ACTIVE | -| `独龙族` | 独龙族 | ACTIVE | -| `鄂伦春族` | 鄂伦春族 | ACTIVE | -| `赫哲族` | 赫哲族 | ACTIVE | -| `门巴族` | 门巴族 | ACTIVE | -| `珞巴族` | 珞巴族 | ACTIVE | -| `基诺族` | 基诺族 | ACTIVE | - ---- - -## 收藏资源类型（`favorite_resource_type`） {#favorite_resource_type} - -> 小程序收藏页Tab筛选 - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PRODUCT` | 产品 | ACTIVE | -| `SCENIC` | 景区 | ACTIVE | -| `RESTAURANT` | 餐厅 | ACTIVE | -| `ACTIVITY` | 活动 | ACTIVE | -| `HOTEL` | 酒店 | ACTIVE | - -**使用该字典的接口**: - -- `GET /user/favorite` — 收藏列表（用户服务） -- `POST /user/favorite` — 添加收藏（用户服务） -- `GET /user/favorite/check` — 检查是否已收藏（用户服务） - ---- - -## 文件分组（`file_group`） {#file_group} - -> Business group for files - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `scenic` | 景点 | ACTIVE | -| `hotel` | 酒店 | ACTIVE | -| `activity` | 活动 | ACTIVE | -| `product` | 产品 | ACTIVE | -| `content` | 内容 | ACTIVE | -| `user` | 用户 | ACTIVE | -| `admin` | 管理员 | ACTIVE | -| `system` | 系统 | ACTIVE | -| `other` | 其他 | ACTIVE | -| `avatar` | 头像 | ACTIVE | -| `material` | 素材 | ACTIVE | -| `restaurant` | 餐厅 | ACTIVE | - ---- - -## 文件状态（`file_status`） {#file_status} - -> File lifecycle status - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `UPLOADING` | 上传中 | ACTIVE | -| `ACTIVE` | 正常 | ACTIVE | -| `DELETED` | 已删除 | ACTIVE | - ---- - -## 文件类型（`file_type`） {#file_type} - -> File category types - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `IMAGE` | 图片 | ACTIVE | -| `VIDEO` | 视频 | ACTIVE | -| `AUDIO` | 音频 | ACTIVE | -| `DOCUMENT` | 文档 | ACTIVE | -| `OTHER` | 其他 | ACTIVE | - ---- - -## 浏览历史资源类型（`footprint_resource_type`） {#footprint_resource_type} - -> 小程序浏览历史页面Tab分类 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PRODUCT` | 产品 | ACTIVE | -| `SCENIC` | 景区 | ACTIVE | -| `RESTAURANT` | 餐厅 | ACTIVE | -| `ACTIVITY` | 活动 | ACTIVE | -| `HOTEL` | 酒店 | ACTIVE | - -**使用该字典的接口**: - -- `GET /user/footprint` — 足迹列表（用户服务） -- `POST /user/footprint` — 添加足迹（用户服务） - ---- - -## 前端配置分组（`frontend_config_group`） {#frontend_config_group} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `MP_COLOR` | 小程序-颜色 | ACTIVE | -| `MP_PAGE` | 小程序-页面 | ACTIVE | -| `MP_GENERAL` | 小程序-通用 | ACTIVE | -| `ADMIN_PAGE` | 后台-页面 | ACTIVE | -| `ADMIN_GENERAL` | 后台-通用 | ACTIVE | -| `SECRET` | 第三方Key | ACTIVE | - ---- - -## 性别（`gender`） {#gender} - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `1` | 男 | ACTIVE | -| `2` | 女 | ACTIVE | - -**使用该字典的接口**: - -- `GET /user/profile` — 获取用户信息（用户服务） -- `PUT /user/profile` — 更新用户信息（用户服务） -- `GET /user/traveler` — 出行人列表（用户服务） -- `POST /user/traveler` — 新增出行人（用户服务） -- `GET /user/traveler/{travelerId}` — 出行人详情（用户服务） -- `PUT /user/traveler/{travelerId}` — 更新出行人（用户服务） -- `GET /admin/customer` — 客户列表（用户服务） -- `GET /admin/customer/{userId}` — 客户详情（用户服务） - ---- - -## 导游等级（`guide_level`） {#guide_level} - -> 导游的资质等级 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PRIMARY` | 初级导游 | ACTIVE | -| `INTERMEDIATE` | 中级导游 | ACTIVE | -| `SENIOR` | 高级导游 | ACTIVE | -| `SPECIAL` | 特级导游 | ACTIVE | - ---- - -## 导游服务区域（`guide_service_area`） {#guide_service_area} - -> 导游提供服务的地理区域 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `YUNNAN` | 云南 | ACTIVE | -| `SICHUAN` | 四川 | ACTIVE | -| `GUIZHOU` | 贵州 | ACTIVE | -| `TIBET` | 西藏 | ACTIVE | -| `XINJIANG` | 新疆 | ACTIVE | -| `GANSU` | 甘肃 | ACTIVE | -| `QINGHAI` | 青海 | ACTIVE | -| `HAINAN` | 海南 | ACTIVE | -| `NATIONWIDE` | 全国 | ACTIVE | - ---- - -## 导游专长（`guide_specialty`） {#guide_specialty} - -> 导游的擅长领域 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `HISTORY` | 历史文化 | ACTIVE | -| `NATURE` | 自然风光 | ACTIVE | -| `FOOD` | 美食探索 | ACTIVE | -| `ADVENTURE` | 户外探险 | ACTIVE | -| `PHOTOGRAPHY` | 摄影旅拍 | ACTIVE | -| `FAMILY` | 亲子游 | ACTIVE | -| `BUSINESS` | 商务接待 | ACTIVE | - ---- - -## 酒店配套设施（`hotel_facility`） {#hotel_facility} - -> Hotel-level facilities - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `parking` | 停车场 | ACTIVE | -| `breakfast` | 早餐 | ACTIVE | -| `free_wifi` | 免费WiFi | ACTIVE | -| `gym` | 健身房 | ACTIVE | -| `laundry` | 洗衣房 | ACTIVE | -| `laundry_service` | 代洗服务 | ACTIVE | -| `screen_cast` | 手机投屏 | ACTIVE | -| `robot` | 智能机器人 | ACTIVE | -| `elevator` | 电梯 | ACTIVE | -| `luggage_storage` | 行李寄存 | ACTIVE | -| `front_desk_24h` | 24小时前台 | ACTIVE | -| `business_center` | 商务中心 | ACTIVE | -| `meeting_room` | 会议室 | ACTIVE | -| `pool` | 游泳池 | ACTIVE | -| `spa` | SPA | ACTIVE | -| `shuttle` | 接驳服务 | ACTIVE | -| `kids_area` | 儿童乐园 | ACTIVE | -| `accessibility` | 无障碍设施 | ACTIVE | -| `pet_friendly` | 宠物友好 | ACTIVE | -| `ev_charging` | 充电桩 | ACTIVE | - ---- - -## 酒店星级（`hotel_star_level`） {#hotel_star_level} - -> 酒店的星级等级评定 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `ECONOMY` | 经济型 | ACTIVE | -| `TWO_STAR` | 二星级 | ACTIVE | -| `THREE_STAR` | 三星级 | ACTIVE | -| `FOUR_STAR` | 四星级 | ACTIVE | -| `FIVE_STAR` | 五星级 | ACTIVE | -| `LUXURY` | 豪华型 | ACTIVE | - ---- - -## 住宿类型（`hotel_type`） {#hotel_type} - -> Hotel accommodation types - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `HOTEL` | 酒店 | ACTIVE | -| `HOMESTAY` | 民宿 | ACTIVE | -| `YURT` | 蒙古包 | ACTIVE | -| `RESORT` | 度假村 | ACTIVE | -| `SPECIAL` | 特色住宿 | ACTIVE | - ---- - -## 证件类型（`id_card_type`） {#id_card_type} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `ID_CARD` | 身份证 | ACTIVE | -| `PASSPORT` | 护照 | ACTIVE | -| `HK_MACAU_PASS` | 港澳通行证 | ACTIVE | -| `TAIWAN_PASS` | 台湾通行证 | ACTIVE | -| `MILITARY_ID` | 军官证 | ACTIVE | -| `OTHER` | 其他 | ACTIVE | - -**使用该字典的接口**: - -- `GET /user/profile` — 获取用户信息（用户服务） -- `PUT /user/profile` — 更新用户信息（用户服务） -- `GET /user/traveler` — 出行人列表（用户服务） -- `POST /user/traveler` — 新增出行人（用户服务） -- `GET /user/traveler/{travelerId}` — 出行人详情（用户服务） -- `PUT /user/traveler/{travelerId}` — 更新出行人（用户服务） -- `GET /admin/customer` — 客户列表（用户服务） -- `GET /admin/customer/{userId}` — 客户详情（用户服务） - ---- - -## 保险状态（`insurance_status`） {#insurance_status} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `INSURED` | 已投保 | ACTIVE | -| `PENDING` | 待投保 | ACTIVE | -| `CANCELLED` | 已取消 | ACTIVE | -| `FAILED` | 失败 | ACTIVE | - ---- - -## 任务分组（`job_group`） {#job_group} - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `DEFAULT` | 默认分组 | ACTIVE | -| `SYSTEM` | 系统任务 | ACTIVE | -| `WECHAT` | 企微同步 | ACTIVE | -| `INSURANCE` | 保险同步 | ACTIVE | - -**使用该字典的接口**: - -- `GET /admin/job` — 分页查询定时任务（用户服务） -- `POST /admin/job` — 创建定时任务（用户服务） -- `PUT /admin/job/{jobId}` — 更新定时任务（用户服务） - ---- - -## 任务日志状态（`job_log_status`） {#job_log_status} - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `SUCCESS` | 成功 | ACTIVE | -| `FAIL` | 失败 | ACTIVE | - ---- - -## 任务补偿策略（`job_misfire_policy`） {#job_misfire_policy} - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `DEFAULT` | 默认策略 | ACTIVE | -| `FIRE_ONCE` | 立即触发一次 | ACTIVE | -| `DO_NOTHING` | 不触发 | ACTIVE | - -**使用该字典的接口**: - -- `GET /admin/job` — 分页查询定时任务（用户服务） -- `POST /admin/job` — 创建定时任务（用户服务） -- `PUT /admin/job/{jobId}` — 更新定时任务（用户服务） - ---- - -## 任务状态（`job_status`） {#job_status} - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `ACTIVE` | 启用 | ACTIVE | -| `PAUSED` | 已暂停 | ACTIVE | - -**使用该字典的接口**: - -- `GET /admin/job` — 分页查询定时任务（用户服务） -- `POST /admin/job` — 创建定时任务（用户服务） - ---- - -## 语言能力（`language`） {#language} - -> 人员掌握的语言 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `MANDARIN` | 普通话 | ACTIVE | -| `ENGLISH` | 英语 | ACTIVE | -| `JAPANESE` | 日语 | ACTIVE | -| `KOREAN` | 韩语 | ACTIVE | -| `FRENCH` | 法语 | ACTIVE | -| `SPANISH` | 西班牙语 | ACTIVE | -| `CANTONESE` | 粤语 | ACTIVE | -| `OTHER` | 其他 | ACTIVE | - ---- - -## 登录状态（`login_status`） {#login_status} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `SUCCESS` | 成功 | ACTIVE | -| `FAILED` | 失败 | ACTIVE | -| `LOCKED` | 锁定 | ACTIVE | - ---- - -## 素材分类（`material_category`） {#material_category} - -> 素材库的业务分类 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `scenic` | 景区管理 | ACTIVE | -| `hotel` | 酒店管理 | ACTIVE | -| `activity` | 游玩项目 | ACTIVE | -| `extra_service` | 额外服务 | ACTIVE | -| `extra_fee` | 额外费用 | ACTIVE | -| `vehicle` | 车辆管理 | ACTIVE | -| `guide` | 攻略管理 | ACTIVE | -| `personnel` | 人员管理 | ACTIVE | -| `restaurant` | 餐厅管理 | ACTIVE | -| `supplies` | 备品管理 | ACTIVE | -| `service` | 服务管理 | ACTIVE | -| `product` | 产品管理 | ACTIVE | -| `meal` | 餐食 | ACTIVE | -| `miniprogram` | 小程序 | ACTIVE | -| `system` | 系统素材 | ACTIVE | - ---- - -## 素材审核状态（`material_review_status`） {#material_review_status} - -> 素材上传审核状态 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PENDING` | 待审核 | ACTIVE | -| `APPROVED` | 已通过 | ACTIVE | - ---- - -## 素材标签（`material_tag`） {#material_tag} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `landscape` | 风景 | ACTIVE | -| `portrait` | 人物 | ACTIVE | -| `food` | 美食 | ACTIVE | -| `hotel` | 住宿 | ACTIVE | -| `transport` | 交通 | ACTIVE | -| `activity` | 活动 | ACTIVE | -| `winter` | 冬季 | ACTIVE | -| `summer` | 夏季 | ACTIVE | -| `grassland` | 草原 | ACTIVE | -| `forest` | 森林 | ACTIVE | - ---- - -## 餐饮类型（`meal_type`） {#meal_type} - -> 行程中的用餐安排类型 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `BREAKFAST` | 早餐 | ACTIVE | -| `LUNCH` | 午餐 | ACTIVE | -| `DINNER` | 晚餐 | ACTIVE | -| `SELF` | 自理 | ACTIVE | - ---- - -## 菜单类型（`menu_type`） {#menu_type} - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `D` | 目录 | ACTIVE | -| `M` | 菜单 | ACTIVE | -| `B` | 按钮 | ACTIVE | - -**使用该字典的接口**: - -- `POST /admin/menu` — 创建菜单（用户服务） -- `GET /admin/menu/tree` — 获取完整菜单树（用户服务） -- `GET /admin/menu/{menuId}` — 获取菜单详情（用户服务） -- `PUT /admin/menu/{menuId}` — 更新菜单（用户服务） - ---- - -## 通知渠道（`notification_channel`） {#notification_channel} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `SMS` | 短信 | ACTIVE | -| `MINIAPP` | 小程序 | ACTIVE | -| `OA` | 公众号 | ACTIVE | -| `INAPP` | 站内信 | ACTIVE | -| `WECHAT_WORK` | 企业微信 | ACTIVE | - ---- - -## 通知事件分类（`notification_event_category`） {#notification_event_category} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `ORDER` | 订单 | ACTIVE | -| `REFUND` | 退款 | ACTIVE | -| `TRIP` | 行程 | ACTIVE | -| `CONTRACT` | 合同 | ACTIVE | -| `INSURANCE` | 保险 | ACTIVE | -| `ADMIN` | 管理 | ACTIVE | -| `SYSTEM` | 系统 | ACTIVE | - ---- - -## 通知发送状态（`notification_send_status`） {#notification_send_status} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `0` | 成功 | ACTIVE | -| `1` | 失败 | ACTIVE | -| `2` | 已过滤 | ACTIVE | -| `3` | 已跳过(已禁用) | ACTIVE | - ---- - -## 通知类型（`notification_type`） {#notification_type} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `ADD_EXTERNAL_CONTACT` | 新增客户 | ACTIVE | -| `DEL_FOLLOW_USER` | 客户流失 | ACTIVE | - ---- - -## 在线状态（`online_status`） {#online_status} - -> 服务或节点的在线状态 - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `ONLINE` | 在线 | ACTIVE | -| `OFFLINE` | 离线 | ACTIVE | - ---- - -## 订单变更原因（`order_change_reason`） {#order_change_reason} - -> 行程修改/房型变更/车型变更等场景的变更原因 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `CUSTOMER_REQUEST` | 客户要求 | ACTIVE | -| `FREE_UPGRADE` | 免费升级 | ACTIVE | -| `HOTEL_FULL` | 酒店满房 | ACTIVE | -| `VEHICLE_UNAVAILABLE` | 车辆不可用 | ACTIVE | -| `WEATHER` | 天气原因 | ACTIVE | -| `ITINERARY_ADJUST` | 行程调整 | ACTIVE | -| `OTHER` | 其他 | ACTIVE | - ---- - -## 订单显示状态(C端)（`order_display_status`） {#order_display_status} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PENDING_PAY` | 待支付 | ACTIVE | -| `PENDING_DEPARTURE` | 待出行 | ACTIVE | -| `TRAVELLING` | 出行中 | ACTIVE | -| `PENDING_REVIEW` | 待评价 | ACTIVE | -| `AFTER_SALE` | 售后 | ACTIVE | - ---- - -## 订单内部流程状态（`order_process_status`） {#order_process_status} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PENDING_INFO` | 待补全信息 | ACTIVE | -| `PROCESSING` | 待内部流程 | ACTIVE | -| `PENDING_INSURANCE` | 待配保险 | ACTIVE | -| `PENDING_CONTRACT` | 待签合同 | ACTIVE | -| `PENDING_ROOM` | 待配房 | ACTIVE | -| `PENDING_VEHICLE` | 待配车 | ACTIVE | -| `PENDING_FINANCE` | 待核算 | ACTIVE | -| `READY` | 就绪 | ACTIVE | - ---- - -## 订单状态（`order_status`） {#order_status} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PENDING_PAY` | 待支付 | ACTIVE | -| `DEPOSIT_PAID` | 已付定金 | ACTIVE | -| `PAID` | 已全额支付 | ACTIVE | -| `CONFIRMED` | 已确认 | ACTIVE | -| `PENDING_BALANCE` | 待付尾款 | ACTIVE | -| `PENDING_DEPARTURE` | 待出行 | ACTIVE | -| `TRAVELLING` | 旅行中 | ACTIVE | -| `COMPLETED` | 已完成 | ACTIVE | -| `AFTER_SALES` | 售后中 | ACTIVE | -| `CANCELLED` | 已取消 | ACTIVE | -| `REFUNDING` | 退款中 | ACTIVE | -| `REFUNDED` | 已退款 | ACTIVE | - -**使用该字典的接口**: - -- `GET /admin/designer/orders` — 我的订单列表（已废弃，请使用 /admin/profile/orders）（用户服务） -- `GET /admin/profile/dashboard` — 工作台仪表盘（角色分发，支持时间范围）（用户服务） -- `GET /admin/profile/orders` — 订单列表（用户服务） - ---- - -## 订单操作类型（`order_timeline_action`） {#order_timeline_action} - -> 订单操作记录中的action类型 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `CREATED` | 创建订单 | ACTIVE | -| `EDITED` | 编辑订单 | ACTIVE | -| `CONFIRMED` | 订单确认 | ACTIVE | -| `PAYMENT_SUCCESS` | 支付成功 | ACTIVE | -| `DEPOSIT_UPDATED` | 定金变更 | ACTIVE | -| `STATUS_CHANGE` | 状态变更 | ACTIVE | -| `PROCESS_CHANGE` | 流程推进 | ACTIVE | -| `TODO_COMPLETED` | 待办完成 | ACTIVE | -| `ITINERARY_EDITED` | 行程编辑 | ACTIVE | -| `EDIT_CONFIRMED` | 修改确认 | ACTIVE | -| `ADD_DAY` | 新增天数 | ACTIVE | -| `ROOM_ADJUSTED` | 房型调整 | ACTIVE | -| `VEHICLE_ADJUSTED` | 车型调整 | ACTIVE | -| `CHECKLIST_CONFIRMED` | 清单确认 | ACTIVE | -| `CANCELLED` | 取消订单 | ACTIVE | -| `AUTO_CANCELLED` | 自动取消 | ACTIVE | -| `AUTO_COMPLETED` | 自动完成 | ACTIVE | -| `AUTO_TRAVEL_START` | 自动出行 | ACTIVE | -| `DELETED` | 删除订单 | ACTIVE | -| `REFUND_APPLIED` | 申请退款 | ACTIVE | -| `REFUND_APPROVED` | 退款通过 | ACTIVE | -| `REFUND_REJECTED` | 退款驳回 | ACTIVE | -| `REFUND_SUCCESS` | 退款成功 | ACTIVE | -| `REFUND_APPEALED` | 退款申诉 | ACTIVE | -| `REFUND_OA_APPROVED` | 审批通过退款 | ACTIVE | -| `REFUND_OA_REJECTED` | 审批驳回退款 | ACTIVE | - ---- - -## 订单待办类型（`order_todo_type`） {#order_todo_type} - -> 订单待办事项的类型 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `CONFIRM_ORDER` | 确认订单 | ACTIVE | -| `INSURANCE` | 配置保险 | ACTIVE | -| `CONTRACT` | 签订合同 | ACTIVE | -| `ARRANGE_ROOM` | 安排住宿 | ACTIVE | -| `ARRANGE_VEHICLE` | 安排车辆 | ACTIVE | -| `CONFIRM_CHECKLIST` | 确认清单 | ACTIVE | -| `PROCESS_REFUND` | 处理退款 | ACTIVE | - ---- - -## 支付模式（`payment_mode`） {#payment_mode} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `FULL` | 全款 | ACTIVE | -| `DEPOSIT` | 定金+尾款 | ACTIVE | - ---- - -## 产品分类（`product_category`） {#product_category} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `family` | 亲子游 | ACTIVE | -| `honeymoon` | 蜜月旅行 | ACTIVE | -| `photography` | 摄影之旅 | ACTIVE | -| `experience` | 深度体验 | ACTIVE | -| `driving` | 自驾越野 | ACTIVE | - -**使用该字典的接口**: - -- `POST /admin/product/item` — 创建产品（草稿）（产品服务） -- `GET /admin/product/item/{productId}` — 获取产品详情（产品服务） -- `PUT /admin/product/item/{productId}` — 更新产品（产品服务） -- `GET /mp/product/{productId}` — 产品详情（C端）（产品服务） - ---- - -## 行程节点类型（`product_node_type`） {#product_node_type} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `TRANSPORT` | 交通 | ACTIVE | -| `SCENIC` | 景区 | ACTIVE | -| `DINING` | 餐饮 | ACTIVE | -| `ACTIVITY` | 活动 | ACTIVE | -| `PHOTOGRAPHY` | 拍摄 | ACTIVE | -| `HOTEL` | 住宿 | ACTIVE | -| `FREE` | 自由活动 | ACTIVE | -| `CUSTOM` | 自定义 | ACTIVE | -| `SERVICE` | 服务 | ACTIVE | -| `NOTE` | 备注 | ACTIVE | - ---- - -## 产品状态（`product_status`） {#product_status} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `DRAFT` | 草稿 | ACTIVE | -| `PENDING_REVIEW` | 待审核 | ACTIVE | -| `REVIEWED` | 已审核 | ACTIVE | -| `REJECTED` | 已驳回 | ACTIVE | -| `PUBLISHED` | 已上架 | ACTIVE | -| `UNPUBLISHED` | 已下架 | ACTIVE | -| `COMPLETED` | 已完成 | ACTIVE | - -**使用该字典的接口**: - -- `GET /admin/designer/products` — 我的产品列表（已废弃，请使用 /admin/profile/products）（用户服务） -- `GET /admin/profile/products` — 产品列表（用户服务） -- `GET /admin/product/item/list` — 产品列表（产品服务） -- `GET /admin/product/item/{productId}` — 获取产品详情（产品服务） -- `POST /admin/product/item/{productId}/copy` — 复制产品（产品服务） -- `PUT /admin/product/item/{productId}/status` — 产品状态变更（上架/下架/完成）（产品服务） - ---- - -## 产品类型（`product_type`） {#product_type} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `CORE` | 核心产品 | ACTIVE | -| `ROUTE` | 自驾路书 | ACTIVE | -| `CUSTOM` | 私人定制 | ACTIVE | -| `GROUP` | 小蒙马 | ACTIVE | - -**使用该字典的接口**: - -- `POST /admin/product/formula/group` — 创建公式组（产品服务） -- `GET /admin/product/formula/group/list` — 公式组列表（产品服务） -- `GET /admin/product/formula/group/{groupId}` — 公式组详情（产品服务） -- `PUT /admin/product/formula/group/{groupId}` — 更新公式组（产品服务） -- `PUT /admin/product/formula/group/{groupId}/activate` — 激活公式组（产品服务） -- `POST /admin/product/formula/var` — 创建公式变量（产品服务） -- `PUT /admin/product/formula/var/{varId}` — 更新公式变量（产品服务） -- `POST /admin/product/item` — 创建产品（草稿）（产品服务） -- `GET /admin/product/item/list` — 产品列表（产品服务） -- `GET /admin/product/item/{productId}` — 获取产品详情（产品服务） -- `PUT /admin/product/item/{productId}` — 更新产品（产品服务） -- `POST /admin/product/item/{productId}/batch` — 创建主批次（产品服务） -- `POST /admin/product/item/{productId}/copy` — 复制产品（产品服务） -- `GET /admin/product/item/{productId}/group-quote` — GROUP产品报价（按套餐组合）（产品服务） -- `POST /admin/product/item/{productId}/quote` — 计算报价（产品服务） -- `PUT /admin/product/item/{productId}/status` — 产品状态变更（上架/下架/完成）（产品服务） -- `GET /mp/product/list` — 产品列表（C端）（产品服务） -- `GET /mp/product/{productId}` — 产品详情（C端）（产品服务） - ---- - -## 推送任务状态（`push_task_status`） {#push_task_status} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PENDING` | 待发送 | ACTIVE | -| `SENDING` | 发送中 | ACTIVE | -| `COMPLETED` | 已完成 | ACTIVE | -| `FAILED` | 已失败 | ACTIVE | - ---- - -## 评价等级（`rating_level`） {#rating_level} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `GOOD` | 好评 | ACTIVE | -| `MEDIUM` | 中评 | ACTIVE | -| `BAD` | 差评 | ACTIVE | - -**使用该字典的接口**: - -- `GET /admin/profile/reviews` — 我的评价列表（用户服务） - ---- - -## 退款原因（`refund_reason`） {#refund_reason} - -> 退款申请时选择的退款原因 - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `schedule_conflict` | 行程冲突/时间变动 | ACTIVE | -| `personal_reason` | 个人原因（身体不适、家庭突发情况） | ACTIVE | -| `companion_unavailable` | 同行人无法出行 | ACTIVE | -| `better_price` | 找到更合适的产品/价格 | ACTIVE | -| `duplicate_order` | 重复下单/误操作下单 | ACTIVE | -| `product_mismatch` | 产品信息描述不符 | ACTIVE | -| `itinerary_change` | 行程变更 | ACTIVE | -| `supplier_unavailable` | 供应商资源不可用（酒店满房、车辆调度问题） | ACTIVE | -| `customer_service` | 客服沟通问题 | ACTIVE | -| `promise_unmet` | 服务承诺未兑现 | ACTIVE | -| `service_mismatch` | 实际服务与约定不符（住宿降级、餐标缩水） | ACTIVE | - ---- - -## 退款原因分类（`refund_reason_category`） {#refund_reason_category} - -> 退款原因的分类 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `GENERAL` | 通用原因 | ACTIVE | -| `PRODUCT` | 产品相关 | ACTIVE | -| `SERVICE` | 服务相关 | ACTIVE | - ---- - -## 退款状态（`refund_status`） {#refund_status} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PENDING` | 待审批 | ACTIVE | -| `APPROVED` | 已通过 | ACTIVE | -| `REJECTED` | 已驳回 | ACTIVE | -| `REFUNDING` | 退款中 | ACTIVE | -| `REFUNDED` | 已退款 | ACTIVE | -| `APPEALING` | 申诉中 | ACTIVE | -| `APPEAL_APPROVED` | 申诉通过 | ACTIVE | -| `APPEAL_REJECTED` | 申诉驳回 | ACTIVE | - ---- - -## 退款类型（`refund_type`） {#refund_type} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `DEPOSIT` | 定金 | ACTIVE | -| `BALANCE` | 尾款 | ACTIVE | -| `FULL` | 全款 | ACTIVE | - ---- - -## 餐厅分类（`restaurant_category`） {#restaurant_category} - -> 推荐餐厅的分类 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `local_specialty` | 本地特色 | ACTIVE | -| `ethnic_cuisine` | 民族风味 | ACTIVE | -| `farmhouse` | 农家乐 | ACTIVE | -| `hotel_dining` | 酒店餐厅 | ACTIVE | -| `internet_famous` | 网红打卡 | ACTIVE | -| `bbq_hotpot` | 烧烤火锅 | ACTIVE | -| `western` | 西餐咖啡 | ACTIVE | -| `snack_street` | 小吃街 | ACTIVE | - ---- - -## 餐厅设施（`restaurant_facility`） {#restaurant_facility} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `wifi` | WiFi | ACTIVE | -| `parking` | 停车场 | ACTIVE | -| `private_room` | 包间 | ACTIVE | -| `child_seat` | 儿童座椅 | ACTIVE | -| `wheelchair` | 轮椅通道 | ACTIVE | -| `restroom` | 洗手间 | ACTIVE | -| `air_conditioning` | 空调 | ACTIVE | -| `outdoor_seating` | 户外座位 | ACTIVE | -| `charging` | 充电插座 | ACTIVE | -| `tv` | 电视 | ACTIVE | - ---- - -## 评分类别（`review_rating_category`） {#review_rating_category} - -> 评价时需要填写的评分维度 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `ratingOverall` | 整体满意度 | ACTIVE | -| `customizerRating` | 定制师服务 | ACTIVE | -| `ratingItinerary` | 行程安排 | ACTIVE | -| `ratingAccommodation` | 住宿安排 | ACTIVE | -| `ratingDining` | 餐饮质量 | ACTIVE | -| `ratingDriver` | 司机服务 | ACTIVE | - ---- - -## 评价审核状态（`review_status`） {#review_status} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PENDING_REVIEW` | 待审核 | ACTIVE | -| `PENDING_MODERATION` | 机器审核中 | ACTIVE | -| `PENDING_MANUAL` | 待人工审核 | ACTIVE | -| `MACHINE_REJECTED` | 机器拒绝 | ACTIVE | -| `APPROVED` | 已通过 | ACTIVE | -| `REJECTED` | 已拒绝 | ACTIVE | - ---- - -## 评价目标类型（`review_target_type`） {#review_target_type} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PRODUCT` | 产品 | ACTIVE | -| `CUSTOMIZER` | 定制师 | ACTIVE | -| `SCENIC` | 景区 | ACTIVE | -| `ACTIVITY` | 活动 | ACTIVE | -| `HOTEL` | 酒店 | ACTIVE | - ---- - -## 房型分类（`room_category`） {#room_category} - -> Room type categories - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `STANDARD` | 标间 | ACTIVE | -| `SINGLE` | 单人间 | ACTIVE | -| `TWIN` | 双床房 | ACTIVE | -| `QUEEN` | 大床房 | ACTIVE | -| `KING` | 豪华大床 | ACTIVE | -| `DELUXE` | 豪华房 | ACTIVE | -| `SUITE` | 套房 | ACTIVE | -| `FAMILY` | 家庭房 | ACTIVE | -| `YURT` | 蒙古包 | ACTIVE | -| `SPECIAL` | 特色房 | ACTIVE | -| `PARENT_CHILD` | 亲子房 | ACTIVE | - ---- - -## 房型设施（`room_facility`） {#room_facility} - -> Room-level facilities - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `slippers` | 拖鞋 | ACTIVE | -| `wardrobe` | 衣柜/衣架 | ACTIVE | -| `baby_bed` | 婴儿床 | ACTIVE | -| `wifi` | WiFi | ACTIVE | -| `wired_net` | 有线宽带 | ACTIVE | -| `kettle` | 热水壶 | ACTIVE | -| `air_cond` | 空调 | ACTIVE | -| `shower` | 独立淋浴花洒 | ACTIVE | -| `mosquito_net` | 纱窗/蚊帐 | ACTIVE | -| `smart_tv` | 智能电视 | ACTIVE | -| `safe` | 保险箱 | ACTIVE | -| `mini_fridge` | 小冰箱 | ACTIVE | -| `free_water` | 免费瓶装水 | ACTIVE | -| `heating` | 暖气 | ACTIVE | -| `phone` | 独立电话 | ACTIVE | -| `desk` | 书桌 | ACTIVE | -| `kids_toiletry` | 儿童洗漱用品 | ACTIVE | -| `toiletries` | 免费洗漱用品 | ACTIVE | -| `minibar` | 迷你吧 | ACTIVE | -| `hairdryer` | 吹风机 | ACTIVE | -| `charger` | 手机充电器 | ACTIVE | -| `corner_guard` | 防撞角 | ACTIVE | -| `sofa` | 沙发 | ACTIVE | -| `floor_heat` | 地暖 | ACTIVE | -| `usb_port` | USB充电口 | ACTIVE | -| `coffee` | 咖啡机 | ACTIVE | -| `bath_towel` | 浴巾 | ACTIVE | -| `private_bath` | 独立卫浴 | ACTIVE | -| `luggage_rack` | 行李架 | ACTIVE | -| `bt_speaker` | 蓝牙音箱 | ACTIVE | -| `smart_toilet` | 智能马桶 | ACTIVE | -| `bathtub` | 浴缸 | ACTIVE | -| `tea_set` | 茶具 | ACTIVE | -| `blackout` | 遮光窗帘 | ACTIVE | -| `mirror` | 全身镜 | ACTIVE | -| `balcony` | 阳台 | ACTIVE | -| `iron` | 熨斗 | ACTIVE | -| `bathrobe` | 浴袍 | ACTIVE | -| `air_purifier` | 空气净化器 | ACTIVE | -| `power_220v` | 220V电源插座 | ACTIVE | -| `stargazing` | 可看星空 | ACTIVE | -| `face_wash` | 洗面乳 | ACTIVE | -| `body_wash` | 沐浴露 | ACTIVE | -| `screen_cast` | 手机投屏 | ACTIVE | - ---- - -## 景区设施（`scenic_facility`） {#scenic_facility} - -> 景区配套设施 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `parking` | 停车场 | ACTIVE | -| `toilet` | 卫生间 | ACTIVE | -| `restaurant` | 餐饮 | ACTIVE | -| `wifi` | WiFi | ACTIVE | -| `accessible` | 无障碍 | ACTIVE | -| `guide_service` | 导游服务 | ACTIVE | -| `locker` | 储物柜 | ACTIVE | -| `medical` | 医务室 | ACTIVE | -| `gift_shop` | 纪念品店 | ACTIVE | -| `rest_area` | 休息区 | ACTIVE | -| `ev_charging` | 充电桩 | ACTIVE | -| `baby_care` | 母婴室 | ACTIVE | - ---- - -## 景区荣誉称号（`scenic_honor`） {#scenic_honor} - -> 景区荣誉称号（多选） - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `5A` | 5A级景区 | ACTIVE | -| `4A` | 4A级景区 | ACTIVE | -| `3A` | 3A级景区 | ACTIVE | -| `2A` | 2A级景区 | ACTIVE | -| `1A` | 1A级景区 | ACTIVE | -| `WORLD_HERITAGE` | 世界遗产 | ACTIVE | -| `NATIONAL_SCENIC` | 国家级风景名胜区 | ACTIVE | -| `NATIONAL_RESERVE` | 国家级自然保护区 | ACTIVE | -| `NATIONAL_FOREST` | 国家森林公园 | ACTIVE | -| `NATIONAL_GEOPARK` | 国家地质公园 | ACTIVE | - ---- - -## 季节（`season`） {#season} - -> 一年四季 - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `SPRING` | 春季 | ACTIVE | -| `SUMMER` | 夏季 | ACTIVE | -| `AUTUMN` | 秋季 | ACTIVE | -| `WINTER` | 冬季 | ACTIVE | - ---- - -## 服务项计费方式（`service_billing_type`） {#service_billing_type} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `FLAT_RATE` | 一口价 | ACTIVE | -| `PER_PERSON` | 按人头 | ACTIVE | -| `PER_HOUR` | 按小时 | ACTIVE | -| `PER_DAY` | 按天 | ACTIVE | -| `PER_DISTANCE` | 按距离 | ACTIVE | -| `CUSTOM` | 自定义 | ACTIVE | - ---- - -## 服务分类（`service_category`） {#service_category} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `airport_transfer` | 机场接送 | ACTIVE | -| `station_transfer` | 车站接送 | ACTIVE | -| `ceremony` | 仪式活动 | ACTIVE | -| `guide` | 导游服务 | ACTIVE | -| `photography` | 摄影跟拍 | ACTIVE | -| `charter` | 包车服务 | ACTIVE | -| `logistics` | 后勤保障 | ACTIVE | -| `vip` | 贵宾服务 | ACTIVE | -| `free_gift` | 免费赠送 | ACTIVE | - ---- - -## 服务计价单位（`service_unit`） {#service_unit} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PER_PERSON` | 元/人 | ACTIVE | -| `PER_TIME` | 元/次 | ACTIVE | -| `PER_DAY` | 元/天 | ACTIVE | -| `PER_VEHICLE` | 元/台 | ACTIVE | -| `FIXED` | 固定金额 | ACTIVE | - ---- - -## 结算状态（`settle_status`） {#settle_status} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `pending` | 待结算 | ACTIVE | -| `settled` | 已结算 | ACTIVE | -| `processing` | 结算中 | ACTIVE | -| `cancelled` | 已取消 | ACTIVE | - ---- - -## 团期人员角色（`staff_role`） {#staff_role} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `LEADER` | 领队 | ACTIVE | -| `PHOTOGRAPHER` | 摄影师 | ACTIVE | -| `DRIVER` | 司机 | ACTIVE | -| `OTHER` | 其他 | ACTIVE | - ---- - -## 人员类型（`staff_type`） {#staff_type} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `GUIDE` | 导游 | ACTIVE | -| `GUIDE_ASSISTANT` | 导游助理 | ACTIVE | -| `PHOTOGRAPHER` | 摄影师 | ACTIVE | -| `LEADER` | 领队 | ACTIVE | -| `OTHER` | 其他 | ACTIVE | - -**使用该字典的接口**: - -- `GET /admin/staff/type/{staffType}/prices` — 查询价格日历（按人员类型）（资源服务） -- `PUT /admin/staff/type/{staffType}/prices` — 批量设置价格（按人员类型）（资源服务） -- `DELETE /admin/staff/type/{staffType}/prices` — 清除价格日历（按人员类型）（资源服务） -- `PUT /admin/staff/type/{staffType}/prices/batch-status` — 批量修改调度状态（按人员类型）（资源服务） -- `GET /admin/product/item/{productId}/batch/{batchId}` — 批次详情（产品服务） -- `GET /admin/product/item/{productId}/batch/{batchId}/staff` — 服务人员列表（产品服务） -- `POST /admin/product/item/{productId}/batch/{batchId}/staff` — 保存服务人员(全量替换)（产品服务） -- `POST /admin/product/item/{productId}/staff-config` — 添加人员配置（产品服务） -- `GET /admin/product/item/{productId}/staff-configs` — 获取产品人员配置列表（产品服务） -- `PUT /admin/product/staff-config/{id}` — 更新人员配置（产品服务） -- `DELETE /admin/product/staff-config/{id}` — 删除人员配置（产品服务） - ---- - -## 备品分类（`supplies_category`） {#supplies_category} - -> 备品租赁的分类 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `personal_gear` | 个人装备 | ACTIVE | -| `camping_equipment` | 露营设备 | ACTIVE | -| `riding_gear` | 骑行装备 | ACTIVE | -| `electronics` | 电子设备 | ACTIVE | -| `safety_protection` | 安全防护 | ACTIVE | -| `entertainment` | 娱乐器材 | ACTIVE | -| `warmth_gear` | 保暖装备 | ACTIVE | -| `vehicle_accessories` | 车载装备 | ACTIVE | - ---- - -## 是否（`sys_yes_no`） {#sys_yes_no} - -> 通用是否选择 - -**分类**: BASE - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `1` | 是 | ACTIVE | -| `0` | 否 | ACTIVE | - ---- - -## 任务优先级（`task_priority`） {#task_priority} - -> 任务看板中任务的优先级 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `LOW` | 低 | ACTIVE | -| `MEDIUM` | 中 | ACTIVE | -| `HIGH` | 高 | ACTIVE | -| `URGENT` | 紧急 | ACTIVE | - ---- - -## 变速箱（`transmission`） {#transmission} - -**分类**: BUSINESS - -> 暂无字典项 - ---- - -## 出行人类型（`traveler_type`） {#traveler_type} - -> 出行人年龄分类，用于订单和出行人管理 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `ADULT` | 成人 | ACTIVE | -| `CHILD` | 儿童 | ACTIVE | -| `YOUNG_CHILD` | 小童 | ACTIVE | -| `BABY` | 幼童 | ACTIVE | - -**使用该字典的接口**: - -- `GET /user/traveler` — 出行人列表（用户服务） -- `POST /user/traveler` — 新增出行人（用户服务） -- `GET /user/traveler/{travelerId}` — 出行人详情（用户服务） -- `PUT /user/traveler/{travelerId}` — 更新出行人（用户服务） - ---- - -## 出行人年龄规则（`traveler_type_age_rule`） {#traveler_type_age_rule} - -> 根据出生日期自动判断出行人类型，remark存JSON格式年龄范围{"minAge":下限,"maxAge":上限}，含下限不含上限 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `BABY` | 幼童 | ACTIVE | -| `YOUNG_CHILD` | 小童 | ACTIVE | -| `CHILD` | 儿童 | ACTIVE | -| `ADULT` | 成人 | ACTIVE | - ---- - -## 行程状态（`trip_status`） {#trip_status} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `draft` | 草稿 | ACTIVE | -| `online` | 已上线 | ACTIVE | -| `offline` | 已下线 | ACTIVE | - ---- - -## 行程类型（`trip_type`） {#trip_type} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `group` | 跟团游 | ACTIVE | -| `free` | 自由行 | ACTIVE | -| `custom` | 定制游 | ACTIVE | -| `semi_free` | 半自由行 | ACTIVE | - ---- - -## 用户状态（`user_status`） {#user_status} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `ACTIVE` | 正常 | ACTIVE | -| `INACTIVE` | 未激活 | ACTIVE | -| `BANNED` | 已封禁 | ACTIVE | -| `DELETED` | 已注销 | ACTIVE | - -**使用该字典的接口**: - -- `GET /admin/customer` — 客户列表（用户服务） -- `GET /admin/customer/{userId}` — 客户详情（用户服务） - ---- - -## 车型（`vehicle_type`） {#vehicle_type} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `SUV` | 越野车 | ACTIVE | -| `SEDAN` | 5座轿车 | ACTIVE | -| `MPV` | 7座商务车 | ACTIVE | -| `MINIBUS` | 9-15座小巴 | ACTIVE | -| `BUS` | 大巴 | ACTIVE | - -**使用该字典的接口**: - -- `POST /admin/product/item/{productId}/price-calendar/auto-calc` — 自动计算成本并同步到价格日历（产品服务） -- `POST /admin/product/item/{productId}/price-calendar/calc-preview` — 测算预览（不写入数据库）（产品服务） -- `GET /admin/product/item/{productId}/pricing` — 获取定价规则（产品服务） -- `POST /admin/product/item/{productId}/pricing` — 保存定价规则（产品服务） - ---- - -## 百科分类（`wiki_category`） {#wiki_category} - -> 百科文章分类 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `scenery` | 绝美风光 | ACTIVE | -| `food` | 特色美食 | ACTIVE | -| `culture` | 民俗文化 | ACTIVE | -| `travel_guide` | 旅行攻略 | ACTIVE | -| `accommodation` | 住宿推荐 | ACTIVE | -| `transport` | 交通出行 | ACTIVE | -| `tips` | 注意事项 | ACTIVE | - ---- - -## 文章状态（`wiki_status`） {#wiki_status} - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `0` | 草稿 | ACTIVE | -| `1` | 已发布 | ACTIVE | -| `2` | 已下架 | ACTIVE | - ---- - -## 窗户类型（`window_type`） {#window_type} - -> Window types - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `NO_WINDOW` | 无窗 | ACTIVE | -| `WINDOW` | 有窗 | ACTIVE | -| `SCENIC` | 景观窗 | ACTIVE | - ---- - -## 工单优先级（`work_order_priority`） {#work_order_priority} - -> 客户工单的紧急程度 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `LOW` | 低 | ACTIVE | -| `MEDIUM` | 中 | ACTIVE | -| `HIGH` | 高 | ACTIVE | -| `URGENT` | 紧急 | ACTIVE | - ---- - -## 工单状态（`work_order_status`） {#work_order_status} - -> 客户工单的处理状态 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `PENDING` | 待处理 | ACTIVE | -| `PROCESSING` | 处理中 | ACTIVE | -| `COMPLETED` | 已完成 | ACTIVE | -| `CLOSED` | 已关闭 | ACTIVE | - ---- - -## 工单类型（`work_order_type`） {#work_order_type} - -> 客户工单的业务分类 - -**分类**: BUSINESS - -| 值（dict_value） | 标签（dict_label） | 状态 | -| --- | --- | --- | -| `REFUND` | 退款申请 | ACTIVE | -| `ITINERARY_CHANGE` | 行程变更 | ACTIVE | -| `COMPLAINT` | 投诉建议 | ACTIVE | -| `INQUIRY` | 咨询 | ACTIVE | -| `OTHER` | 其他 | ACTIVE | - ---- diff --git a/2026-03/17_1012/hl-contract-service.md b/2026-03/17_1012/hl-contract-service.md deleted file mode 100644 index 7c4fc19..0000000 --- a/2026-03/17_1012/hl-contract-service.md +++ /dev/null @@ -1,793 +0,0 @@ -# 合同服务 API 文档 - -**服务**: `hl-contract-service` -**接口总数**: 18 - -## 目录 - -- **合同管理** (12 个接口) -- **补充约定模板管理** (6 个接口) - ---- - -## 合同管理 - -### `GET` /admin/contract/active-by-order/{orderId} - -**获取订单有效合同** - -返回订单当前有效的合同（非作废状态的最新合同），用于检查订单是否已有签署中或已签署的合同。 - -**权限**：需管理员登录。 - -**关联字典**： -- contract_status：合同状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«合同信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同信息` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/agencies - -**可用旅行社列表** - -返回系统配置的旅行社列表，创建合同时选择签约旅行社 - -**响应** `统一响应结果«List«旅行社信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `旅行社信息[]` | | 响应数据 | -|   `agencyAddress` | `string` | | 旅行社地址 | -|   `agencyName` | `string` | | 旅行社名称 | -|   `businessLicenseNumber` | `string` | | 营业执照号 | -|   `businessScope` | `string` | | 经营范围 | -|   `code` | `string` | | 旅行社编码 | -|   `licenseNumber` | `string` | | 旅行社许可证号 | -|   `regionId` | `string` | | 地区ID | -|   `transactorName` | `string` | | 经办人姓名 | -|   `transactorPhone` | `string` | | 经办人电话 | -|   `zjParentId` | `int` | | 属地管理机构ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/by-order/{orderId} - -**按订单查询合同** - -查询指定订单下的所有合同记录（含已作废），按创建时间倒序排列。用于订单详情页展示合同历史。 - -**权限**：需管理员登录。 - -**关联字典**： -- contract_status：合同状态（列表显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«List«合同信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同信息[]` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/contract/create - -**创建合同(标准模式)** - -标准电子签约流程：创建合同 → 平台生成合同PDF → 发送签署短信给出行人 → 出行人在线签署 → 回调更新状态。状态流转：CREATED → SIGNING → SIGNED - -**请求体** `创建合同请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `adultCost` | `number` | 是 | 成人费用 | -| `agencyCode` | `string` | | 旅行社编号（可选，默认使用配置值） | -| `childCost` | `number` | | 儿童费用 | -| `contactName` | `string` | 是 | 联系人姓名 | -| `contactPhone` | `string` | 是 | 联系人电话 | -| `contractType` | `string` | | 合同类型: TOUR-旅游合同(默认), INSURANCE-保险单 | -| `days` | `int` | | 行程天数 | -| `departureCity` | `string` | | 出发城市 | -| `departureDate` | `string` | 是 | 出发日期 | -| `destination` | `string` | 是 | 目的地 | -| `disputeResolution` | `int` | | 争议解决方式: 1-仲裁 2-诉讼 | -| `groupId` | `string` | | 团号 | -| `leastCustomerNumber` | `int` | | 最低成团人数 | -| `nights` | `int` | | 住宿晚数 | -| `orderId` | `long` | | 订单ID | -| `paymentMethod` | `int` | | 付款方式: 1-现金 2-转账 3-在线 | -| `returnDate` | `string` | 是 | 返回日期 | -| `routeName` | `string` | 是 | 线路名称 | -| `signatoryIdNumber` | `string` | 是 | 签署人证件号码 | -| `signatoryIdType` | `int` | | 签署人证件类型: 1-身份证 | -| `signatoryMode` | `int` | | 签署模式: 1-短信 2-现场 3-线下 | -| `signatoryName` | `string` | 是 | 签署人姓名 | -| `signatoryPhone` | `string` | 是 | 签署人电话 | -| `signingPlace` | `string` | | 签约地点 | -| `supplementaryClause` | `string` | | 补充约定内容 | -| `templateCode` | `string` | 是 | 模板编码 | -| `totalAmount` | `number` | 是 | 合同总金额 | -| `transactorName` | `string` | | 经办人姓名 | -| `transactorPhone` | `string` | | 经办人电话 | -| `travelers` | `合同出行人请求[]` | 是 | 出行人列表 | -|   `age` | `int` | | 年龄 | -|   `gender` | `string` | | 性别: male/female | -|   `health` | `string` | | 健康信息 | -|   `idCardNo` | `string` | 是 | 证件号码 | -|   `idCardType` | `int` | | 证件类型: 1-身份证 2-护照 | -|   `isChild` | `boolean` | | 是否儿童 | -|   `isSigner` | `boolean` | | 是否签署人 | -|   `name` | `string` | 是 | 姓名 | -|   `phone` | `string` | | 手机号 | -| `vehicleModel` | `string` | | 车型名称(产品快照) | - -**响应** `统一响应结果«合同详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同详情` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `statusLogs` | `合同状态变更日志[]` | | 状态变更日志 | -|     `createTime` | `string` | | 创建时间 | -|     `logId` | `long` | | 日志ID | -|     `newStatus` | `string` | | 新状态 | -|     `oldStatus` | `string` | | 旧状态 | -|     `source` | `string` | | 变更来源 | -|   `supplementaryClause` | `string` | | 补充约定内容 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -|   `travelers` | `合同出行人信息[]` | | 出行人列表 | -|     `idCardNo` | `string` | | 证件号码 | -|     `idCardType` | `string` | | 证件类型 | -|     `isSigner` | `boolean` | | 是否签署人 | -|     `name` | `string` | | 姓名 | -|     `phone` | `string` | | 手机号 | -|     `travelerId` | `long` | | 出行人ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/list - -**合同列表** - -分页查询合同记录，支持按订单号、合同状态、旅行社筛选 - -**关联字典**： -- contract_status：合同状态（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `orderId` | `integer(int64)` | | 订单ID | 1001 | -| `page` | `integer(int32)` | | 页码 | 1 | -| `pageSize` | `integer(int32)` | | 每页条数 | 20 | -| `platform` | `string` | | 签约平台 | TOURAGE | -| `status` | `string` | | 合同状态 | SIGNED | - -**响应** `统一响应结果«分页结果«合同信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«合同信息»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `合同信息[]` | | 数据列表 | -|     `agencyCode` | `string` | | 旅行社编号 | -|     `contactName` | `string` | | 联系人姓名 | -|     `contactPhone` | `string` | | 联系人电话 | -|     `contractId` | `long` | | 合同ID | -|     `contractNumber` | `string` | | 合同编号 | -|     `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|     `createTime` | `string` | | 创建时间 | -|     `departureDate` | `string` | | 出发日期 | -|     `destination` | `string` | | 目的地 | -|     `fileUrl` | `string` | | 合同文件URL | -|     `mode` | `string` | | 签约模式: STANDARD/SYNC | -|     `orderId` | `long` | | 订单ID | -|     `platform` | `string` | | 签约平台 | -|     `qrCodeUrl` | `string` | | 二维码URL | -|     `returnDate` | `string` | | 返回日期 | -|     `signUrl` | `string` | | 签署URL | -|     `status` | `string` | | 合同状态 | -|     `statusLabel` | `string` | | 合同状态标签 | -|     `templateCode` | `string` | | 模板编码 | -|     `templateName` | `string` | | 模板名称 | -|     `totalAmount` | `number` | | 合同总金额 | -|     `touristCount` | `int` | | 出行人数 | -|     `travelAgencyName` | `string` | | 旅行社名称 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/contract/report - -**报备合同(同步模式)** - -线下签约模式：创建合同记录 → 管理员上传已签署的PDF → 同步到12301报备平台。状态流转：CREATED → UPLOADED → REPORTED - -**请求体** `报备合同请求（同步模式）` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `adultCost` | `number` | 是 | 成人费用 | -| `agencyCode` | `string` | | 旅行社编号 | -| `childCost` | `number` | | 儿童费用 | -| `contactName` | `string` | 是 | 联系人姓名 | -| `contactPhone` | `string` | 是 | 联系人电话 | -| `contractType` | `string` | | 合同类型: TOUR-旅游合同(默认), INSURANCE-保险单 | -| `days` | `int` | | 行程天数 | -| `departureCity` | `string` | | 出发城市 | -| `departureDate` | `string` | 是 | 出发日期 | -| `destination` | `string` | 是 | 目的地 | -| `disputeResolution` | `int` | | 争议解决方式: 1-仲裁 2-诉讼 | -| `groupId` | `string` | | 团号 | -| `leastCustomerNumber` | `int` | | 最低成团人数 | -| `nights` | `int` | | 住宿晚数 | -| `orderId` | `long` | | 订单ID | -| `paymentMethod` | `int` | | 付款方式: 1-现金 2-转账 3-在线 | -| `returnDate` | `string` | 是 | 返回日期 | -| `routeName` | `string` | 是 | 线路名称 | -| `signatoryIdNumber` | `string` | 是 | 签署人证件号码 | -| `signatoryIdType` | `int` | | 签署人证件类型: 1-身份证 | -| `signatoryMode` | `int` | | 签署模式（同步模式默认2-现场） | -| `signatoryName` | `string` | 是 | 签署人姓名 | -| `signatoryPhone` | `string` | 是 | 签署人电话 | -| `signingPlace` | `string` | | 签约地点 | -| `supplementaryClause` | `string` | | 补充约定内容 | -| `templateCode` | `string` | 是 | 模板编码 | -| `totalAmount` | `number` | 是 | 合同总金额 | -| `transactorName` | `string` | | 经办人姓名 | -| `transactorPhone` | `string` | | 经办人电话 | -| `travelers` | `合同出行人请求[]` | 是 | 出行人列表 | -|   `age` | `int` | | 年龄 | -|   `gender` | `string` | | 性别: male/female | -|   `health` | `string` | | 健康信息 | -|   `idCardNo` | `string` | 是 | 证件号码 | -|   `idCardType` | `int` | | 证件类型: 1-身份证 2-护照 | -|   `isChild` | `boolean` | | 是否儿童 | -|   `isSigner` | `boolean` | | 是否签署人 | -|   `name` | `string` | 是 | 姓名 | -|   `phone` | `string` | | 手机号 | - -**响应** `统一响应结果«合同详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同详情` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `statusLogs` | `合同状态变更日志[]` | | 状态变更日志 | -|     `createTime` | `string` | | 创建时间 | -|     `logId` | `long` | | 日志ID | -|     `newStatus` | `string` | | 新状态 | -|     `oldStatus` | `string` | | 旧状态 | -|     `source` | `string` | | 变更来源 | -|   `supplementaryClause` | `string` | | 补充约定内容 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -|   `travelers` | `合同出行人信息[]` | | 出行人列表 | -|     `idCardNo` | `string` | | 证件号码 | -|     `idCardType` | `string` | | 证件类型 | -|     `isSigner` | `boolean` | | 是否签署人 | -|     `name` | `string` | | 姓名 | -|     `phone` | `string` | | 手机号 | -|     `travelerId` | `long` | | 出行人ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/templates - -**合同模板列表** - -返回合同平台可用的合同模板列表，创建合同时选择模板 - -**响应** `统一响应结果«List«合同模板信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同模板信息[]` | | 响应数据 | -|   `createTime` | `string` | | 创建时间 | -|   `description` | `string` | | 模板描述 | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `platform` | `string` | | 签约平台 | -|   `status` | `string` | | 模板状态 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateId` | `long` | | 模板ID | -|   `templateName` | `string` | | 模板名称 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/{id} - -**合同详情** - -**关联字典**： -- contract_status：合同状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 合同ID | - -**响应** `统一响应结果«合同详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同详情` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `statusLogs` | `合同状态变更日志[]` | | 状态变更日志 | -|     `createTime` | `string` | | 创建时间 | -|     `logId` | `long` | | 日志ID | -|     `newStatus` | `string` | | 新状态 | -|     `oldStatus` | `string` | | 旧状态 | -|     `source` | `string` | | 变更来源 | -|   `supplementaryClause` | `string` | | 补充约定内容 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -|   `travelers` | `合同出行人信息[]` | | 出行人列表 | -|     `idCardNo` | `string` | | 证件号码 | -|     `idCardType` | `string` | | 证件类型 | -|     `isSigner` | `boolean` | | 是否签署人 | -|     `name` | `string` | | 姓名 | -|     `phone` | `string` | | 手机号 | -|     `travelerId` | `long` | | 出行人ID | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/contract/{id}/invalidate - -**作废合同** - -将合同标记为作废状态（不可恢复）。作废后该合同不再有效，可重新为订单创建新合同 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 合同ID | - -**响应** `统一响应结果«合同信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同信息` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/contract/{id}/resend-sms - -**重发签署短信** - -重新发送签署短信给出行人，用于签署短信过期或未收到的场景。仅SIGNING状态的合同可操作 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 合同ID | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/{id}/status - -**刷新合同状态(从平台同步)** - -主动查询合同平台的最新签署状态并同步到本地，适用于回调未到达的场景 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 合同ID | - -**响应** `统一响应结果«合同信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同信息` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/contract/{id}/upload-pdf - -**上传已签署PDF(同步模式)** - -同步模式专用：上传线下签署完成的合同PDF文件，上传后合同状态变为UPLOADED，可进一步报备 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 合同ID | - -**响应** `统一响应结果«合同信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `合同信息` | | 响应数据 | -|   `agencyCode` | `string` | | 旅行社编号 | -|   `contactName` | `string` | | 联系人姓名 | -|   `contactPhone` | `string` | | 联系人电话 | -|   `contractId` | `long` | | 合同ID | -|   `contractNumber` | `string` | | 合同编号 | -|   `contractType` | `string` | | 合同类型: TOUR-旅游合同, INSURANCE-保险单 | -|   `createTime` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期 | -|   `destination` | `string` | | 目的地 | -|   `fileUrl` | `string` | | 合同文件URL | -|   `mode` | `string` | | 签约模式: STANDARD/SYNC | -|   `orderId` | `long` | | 订单ID | -|   `platform` | `string` | | 签约平台 | -|   `qrCodeUrl` | `string` | | 二维码URL | -|   `returnDate` | `string` | | 返回日期 | -|   `signUrl` | `string` | | 签署URL | -|   `status` | `string` | | 合同状态 | -|   `statusLabel` | `string` | | 合同状态标签 | -|   `templateCode` | `string` | | 模板编码 | -|   `templateName` | `string` | | 模板名称 | -|   `totalAmount` | `number` | | 合同总金额 | -|   `touristCount` | `int` | | 出行人数 | -|   `travelAgencyName` | `string` | | 旅行社名称 | -| `message` | `string` | | 响应消息 | - ---- - -## 补充约定模板管理 - -### `POST` /admin/contract/clause-template - -**创建补充约定模板** - -创建合同补充约定的模板，支持变量占位符。创建后默认启用 - -**请求体** `补充约定模板请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `content` | `string` | 是 | 模板内容 | -| `name` | `string` | 是 | 模板名称 | -| `sortOrder` | `int` | | 排序（升序） | - -**响应** `统一响应结果«补充约定模板»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `补充约定模板` | | 响应数据 | -|   `content` | `string` | | 模板内容 | -|   `createTime` | `string` | | 创建时间 | -|   `name` | `string` | | 模板名称 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `string` | | 状态: ACTIVE/INACTIVE | -|   `templateId` | `long` | | 模板ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/clause-template/list - -**获取启用的补充约定模板列表（创建合同用）** - -返回所有启用状态的补充约定模板，创建合同时选择需要附加的补充约定条款。 - -**权限**：需管理员登录。 - -**响应** `统一响应结果«List«补充约定模板»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `补充约定模板[]` | | 响应数据 | -|   `content` | `string` | | 模板内容 | -|   `createTime` | `string` | | 创建时间 | -|   `name` | `string` | | 模板名称 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `string` | | 状态: ACTIVE/INACTIVE | -|   `templateId` | `long` | | 模板ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/contract/clause-template/list-all - -**获取全部补充约定模板（管理页用）** - -**关联字典**： -- common_status：通用状态（列表显示，ACTIVE=启用/INACTIVE=停用） - -**响应** `统一响应结果«List«补充约定模板»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `补充约定模板[]` | | 响应数据 | -|   `content` | `string` | | 模板内容 | -|   `createTime` | `string` | | 创建时间 | -|   `name` | `string` | | 模板名称 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `string` | | 状态: ACTIVE/INACTIVE | -|   `templateId` | `long` | | 模板ID | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/contract/clause-template/{id} - -**更新补充约定模板** - -更新模板的标题和内容。已被合同引用的模板更新不影响已创建的合同（合同记录的是快照内容）。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 模板ID | - -**请求体** `补充约定模板请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `content` | `string` | 是 | 模板内容 | -| `name` | `string` | 是 | 模板名称 | -| `sortOrder` | `int` | | 排序（升序） | - -**响应** `统一响应结果«补充约定模板»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `补充约定模板` | | 响应数据 | -|   `content` | `string` | | 模板内容 | -|   `createTime` | `string` | | 创建时间 | -|   `name` | `string` | | 模板名称 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `string` | | 状态: ACTIVE/INACTIVE | -|   `templateId` | `long` | | 模板ID | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/contract/clause-template/{id} - -**删除补充约定模板** - -软删除模板。已被合同引用的模板仍可删除，不影响已创建的合同 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 模板ID | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/contract/clause-template/{id}/toggle-status - -**切换模板启用/停用状态** - -**关联字典**： -- common_status：通用状态（状态切换，ACTIVE=启用/INACTIVE=停用） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 模板ID | - -**响应** `统一响应结果«补充约定模板»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `补充约定模板` | | 响应数据 | -|   `content` | `string` | | 模板内容 | -|   `createTime` | `string` | | 创建时间 | -|   `name` | `string` | | 模板名称 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `string` | | 状态: ACTIVE/INACTIVE | -|   `templateId` | `long` | | 模板ID | -| `message` | `string` | | 响应消息 | - ---- diff --git a/2026-03/17_1012/hl-file-service.md b/2026-03/17_1012/hl-file-service.md deleted file mode 100644 index 7c17ab6..0000000 --- a/2026-03/17_1012/hl-file-service.md +++ /dev/null @@ -1,331 +0,0 @@ -# 文件服务 API 文档 - -**服务**: `hl-file-service` -**接口总数**: 11 - -## 目录 - -- **C端文件上传** (3 个接口) -- **文件管理** (8 个接口) - ---- - -## C端文件上传 - -### `GET` /mp/file/preview-by-url - -**文件在线预览** - -返回HTML预览页面，小程序通过web-view打开。支持PDF、图片、Office文档 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `url` | `string` | | 文件完整URL | | - ---- - -### `POST` /mp/file/upload - -**上传文件（C端用户）** - -小程序端直接上传文件，支持头像、评价图片等场景。groupKey决定存储路径和文件策略，默认为avatar - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `groupKey` | `string` | | 文件分组标识 | | - -**响应** `统一响应结果«文件信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `文件信息` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `fileHash` | `string` | | 文件MD5哈希 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `groupKey` | `string` | | 业务分组 | -|   `mimeType` | `string` | | MIME类型 | -|   `ossUrl` | `string` | | OSS地址 | -|   `previewUrl` | `string` | | 预览地址 | -|   `refCount` | `int` | | 引用次数 | -|   `status` | `string` | | 文件状态 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/file/{fileId}/preview - -**文件内容流式预览** - -流式输出文件内容，设置正确的Content-Type头。用于小程序端通过web-view直接预览图片和PDF等文件。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `fileId` | `integer` | | 文件ID | - ---- - -## 文件管理 - -### `GET` /admin/file/list - -**文件列表（分页）** - -支持按文件类型、分组、上传者等条件筛选，按上传时间倒序分页返回 - -**关联字典**： -- file_type：文件类型（列表筛选+显示） -- file_status：文件状态（显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `endDate` | `string` | | 结束日期 | 2026-12-31 | -| `fileType` | `string` | | 文件类型 | image | -| `groupKey` | `string` | | 业务分组 | scenic | -| `keyword` | `string` | | 搜索关键词 | 风景 | -| `page` | `integer(int32)` | | 页码 | 1 | -| `pageSize` | `integer(int32)` | | 每页条数 | 20 | -| `startDate` | `string` | | 开始日期 | 2026-01-01 | - -**响应** `统一响应结果«IPage«文件信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `IPage«文件信息»` | | 响应数据 | -|   `current` | `long` | | | -|   `pages` | `long` | | | -|   `records` | `文件信息[]` | | | -|     `createdAt` | `string` | | 创建时间 | -|     `fileHash` | `string` | | 文件MD5哈希 | -|     `fileId` | `string` | | 文件ID | -|     `fileName` | `string` | | 文件名 | -|     `fileSize` | `long` | | 文件大小(字节) | -|     `fileType` | `string` | | 文件类型 | -|     `groupKey` | `string` | | 业务分组 | -|     `mimeType` | `string` | | MIME类型 | -|     `ossUrl` | `string` | | OSS地址 | -|     `previewUrl` | `string` | | 预览地址 | -|     `refCount` | `int` | | 引用次数 | -|     `status` | `string` | | 文件状态 | -|     `thumbnailUrl` | `string` | | 缩略图地址 | -|   `size` | `long` | | | -|   `total` | `long` | | | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/file/stats - -**存储统计** - -返回文件总数、总存储空间、各类型文件占比等统计信息 - -**响应** `统一响应结果«文件统计信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `文件统计信息` | | 响应数据 | -|   `countByGroup` | `object` | | 按分组统计文件数量 | -|   `countByType` | `object` | | 按类型统计文件数量 | -|   `sizeByType` | `object` | | 按类型统计文件大小 | -|   `totalCount` | `long` | | 文件总数 | -|   `totalSize` | `long` | | 文件总大小(字节) | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/file/upload/confirm - -**确认上传完成** - -上传流程第二步：前端直传OSS完成后调用此接口，系统验证文件存在性并创建文件记录。支持MD5去重，相同文件不会重复存储 - -**请求体** `上传确认请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `fileId` | `string` | 是 | 文件ID | - -**响应** `统一响应结果«文件信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `文件信息` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `fileHash` | `string` | | 文件MD5哈希 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `groupKey` | `string` | | 业务分组 | -|   `mimeType` | `string` | | MIME类型 | -|   `ossUrl` | `string` | | OSS地址 | -|   `previewUrl` | `string` | | 预览地址 | -|   `refCount` | `int` | | 引用次数 | -|   `status` | `string` | | 文件状态 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/file/upload/token - -**请求上传凭证** - -上传流程第一步：前端请求上传凭证 → 获取OSS预签名URL和临时凭证 → 前端直传OSS → 调用确认上传接口。凭证有效期有限，过期需重新请求 - -**请求体** `上传令牌请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `fileHash` | `string` | 是 | 文件MD5哈希 | -| `fileName` | `string` | 是 | 文件名 | -| `fileSize` | `long` | 是 | 文件大小(字节) | -| `forcePresigned` | `boolean` | | 强制使用预签名URL（跳过STS分片模式） | -| `groupKey` | `string` | | 业务分组 | - -**响应** `统一响应结果«上传令牌信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `上传令牌信息` | | 响应数据 | -|   `bucket` | `string` | | OSS Bucket名称 | -|   `contentType` | `string` | | 上传时必须使用的Content-Type（与预签名URL签名一致） | -|   `expireAt` | `string` | | 过期时间 | -|   `file` | `文件信息` | | 秒传文件信息 | -|     `createdAt` | `string` | | 创建时间 | -|     `fileHash` | `string` | | 文件MD5哈希 | -|     `fileId` | `string` | | 文件ID | -|     `fileName` | `string` | | 文件名 | -|     `fileSize` | `long` | | 文件大小(字节) | -|     `fileType` | `string` | | 文件类型 | -|     `groupKey` | `string` | | 业务分组 | -|     `mimeType` | `string` | | MIME类型 | -|     `ossUrl` | `string` | | OSS地址 | -|     `previewUrl` | `string` | | 预览地址 | -|     `refCount` | `int` | | 引用次数 | -|     `status` | `string` | | 文件状态 | -|     `thumbnailUrl` | `string` | | 缩略图地址 | -|   `fileId` | `string` | | 文件ID | -|   `ossKey` | `string` | | OSS对象Key | -|   `presignedUrl` | `string` | | 预签名上传URL | -|   `region` | `string` | | OSS Region | -|   `stsToken` | `STS临时凭证信息` | | STS临时凭证 | -|     `accessKeyId` | `string` | | AccessKey ID | -|     `accessKeySecret` | `string` | | AccessKey Secret | -|     `expiration` | `string` | | 过期时间 | -|     `securityToken` | `string` | | 安全令牌 | -|   `uploadMode` | `string` | | 上传模式: PRESIGNED_URL/STS_MULTIPART/INSTANT | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/file/{fileId} - -**文件详情** - -**关联字典**： -- file_type：文件类型（显示） -- file_status：文件状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `fileId` | `integer` | | 文件ID | - -**响应** `统一响应结果«文件信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `文件信息` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `fileHash` | `string` | | 文件MD5哈希 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `groupKey` | `string` | | 业务分组 | -|   `mimeType` | `string` | | MIME类型 | -|   `ossUrl` | `string` | | OSS地址 | -|   `previewUrl` | `string` | | 预览地址 | -|   `refCount` | `int` | | 引用次数 | -|   `status` | `string` | | 文件状态 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/file/{fileId} - -**删除文件** - -软删除文件记录，如果文件存在引用关系则不允许删除。OSS上的物理文件由定时任务清理 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `fileId` | `integer` | | 文件ID | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/file/{fileId}/preview - -**文件内容流式预览** - -流式输出文件内容，设置正确的Content-Type头，支持浏览器直接预览图片和PDF等文件 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `fileId` | `integer` | | 文件ID | - ---- - -### `GET` /admin/file/{fileId}/refs - -**文件引用列表** - -查看文件被哪些业务实体引用（如景区封面、酒店图片等），用于判断文件是否可安全删除 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `fileId` | `integer` | | 文件ID | - -**响应** `统一响应结果«List«文件引用信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `文件引用信息[]` | | 响应数据 | -|   `bizId` | `string` | | 业务ID | -|   `bizType` | `string` | | 业务类型 | -|   `createdAt` | `string` | | 创建时间 | -|   `fileId` | `string` | | 文件ID | -|   `refId` | `string` | | 引用ID | -| `message` | `string` | | 响应消息 | - ---- diff --git a/2026-03/17_1012/hl-guide-service.md b/2026-03/17_1012/hl-guide-service.md deleted file mode 100644 index d01c9cc..0000000 --- a/2026-03/17_1012/hl-guide-service.md +++ /dev/null @@ -1,727 +0,0 @@ -# 攻略服务 API 文档 - -**服务**: `hl-guide-service` -**接口总数**: 21 - -## 目录 - -- **攻略分类管理** (7 个接口) -- **攻略文章管理** (8 个接口) -- **攻略标签管理** (6 个接口) - ---- - -## 攻略分类管理 - -### `POST` /admin/guide/category - -**创建分类** - -创建攻略分类，分类名称不可重复。创建后默认启用，排序值越小越靠前。 - -**权限**：需管理员登录。 - -**请求体** `CategoryCreateRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryName` | `string` | 是 | 分类名称 | -| `coverMaterialId` | `long` | | 封面素材ID | -| `coverUrl` | `string` | | 封面URL | -| `description` | `string` | | 描述 | -| `icon` | `string` | | 图标 | -| `sortOrder` | `int` | | 排序（默认0） | - -**响应** `统一响应结果«攻略分类»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略分类` | | 响应数据 | -|   `articleCount` | `int` | | 文章数量 | -|   `categoryId` | `long` | | 分类ID | -|   `categoryName` | `string` | | 分类名称 | -|   `coverMaterialId` | `long` | | 封面素材ID | -|   `coverUrl` | `string` | | 封面URL | -|   `createdAt` | `string` | | 创建时间 | -|   `description` | `string` | | 描述 | -|   `icon` | `string` | | 图标 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `int` | | 状态：0=禁用，1=启用 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/guide/category/enabled - -**启用的分类列表** - -仅返回状态为启用的分类，创建文章时用于选择分类 - -**响应** `统一响应结果«List«攻略分类»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略分类[]` | | 响应数据 | -|   `articleCount` | `int` | | 文章数量 | -|   `categoryId` | `long` | | 分类ID | -|   `categoryName` | `string` | | 分类名称 | -|   `coverMaterialId` | `long` | | 封面素材ID | -|   `coverUrl` | `string` | | 封面URL | -|   `createdAt` | `string` | | 创建时间 | -|   `description` | `string` | | 描述 | -|   `icon` | `string` | | 图标 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `int` | | 状态：0=禁用，1=启用 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/guide/category/list - -**分类列表** - -返回全部攻略分类（含启用和停用），按排序值升序排列 - -**关联字典**： -- common_status：通用状态（列表显示，ACTIVE=启用/INACTIVE=停用） - -**响应** `统一响应结果«List«攻略分类»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略分类[]` | | 响应数据 | -|   `articleCount` | `int` | | 文章数量 | -|   `categoryId` | `long` | | 分类ID | -|   `categoryName` | `string` | | 分类名称 | -|   `coverMaterialId` | `long` | | 封面素材ID | -|   `coverUrl` | `string` | | 封面URL | -|   `createdAt` | `string` | | 创建时间 | -|   `description` | `string` | | 描述 | -|   `icon` | `string` | | 图标 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `int` | | 状态：0=禁用，1=启用 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/guide/category/{categoryId} - -**更新分类** - -更新攻略分类的名称、图标、描述等信息。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryId` | `integer` | 是 | categoryId | - -**请求体** `CategoryUpdateRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryName` | `string` | | 分类名称 | -| `coverMaterialId` | `long` | | 封面素材ID | -| `coverUrl` | `string` | | 封面URL | -| `description` | `string` | | 描述 | -| `icon` | `string` | | 图标 | -| `sortOrder` | `int` | | 排序 | - -**响应** `统一响应结果«攻略分类»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略分类` | | 响应数据 | -|   `articleCount` | `int` | | 文章数量 | -|   `categoryId` | `long` | | 分类ID | -|   `categoryName` | `string` | | 分类名称 | -|   `coverMaterialId` | `long` | | 封面素材ID | -|   `coverUrl` | `string` | | 封面URL | -|   `createdAt` | `string` | | 创建时间 | -|   `description` | `string` | | 描述 | -|   `icon` | `string` | | 图标 | -|   `sortOrder` | `int` | | 排序 | -|   `status` | `int` | | 状态：0=禁用，1=启用 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/guide/category/{categoryId} - -**删除分类** - -删除分类前需确保分类下无文章，否则删除失败 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryId` | `integer` | 是 | categoryId | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/guide/category/{categoryId}/sort - -**更新分类排序** - -更新分类的排序值，排序值越小越靠前。影响小程序端分类导航的展示顺序。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryId` | `integer` | 是 | categoryId | - -**请求体** `CategorySortRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `sortOrder` | `int` | 是 | 排序值 | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/guide/category/{categoryId}/status - -**更新分类状态** - -启用或停用分类。停用后该分类下的文章不会在小程序端展示，但不影响已有文章 - -**关联字典**： -- common_status：通用状态（状态切换，ACTIVE=启用/INACTIVE=停用） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryId` | `integer` | 是 | categoryId | - -**请求体** `StatusRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `status` | `int` | 是 | 状态值 | - -**响应** `统一响应结果«Void»` - ---- - -## 攻略文章管理 - -### `POST` /admin/guide/article - -**创建文章** - -创建攻略文章，需指定分类。创建后默认为草稿状态，需手动发布后小程序端才可见。 - -**权限**：需管理员登录。 - -**关联字典**： -- wiki_status：文章状态（创建后默认DRAFT） - -**请求体** `ArticleCreateRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `authorName` | `string` | | 作者名称 | -| `bannerMaterialIds` | `long[]` | | 轮播图素材ID列表 | -| `categoryId` | `long` | 是 | 分类ID | -| `content` | `string` | | 正文内容 | -| `coverMaterialId` | `long` | | 封面素材ID | -| `coverUrl` | `string` | | 封面URL | -| `resources` | `ArticleResourceItem[]` | | 关联资源列表 | -|   `resourceId` | `long` | 是 | 资源ID | -|   `resourceName` | `string` | 是 | 资源名称 | -|   `resourceType` | `string` | 是 | 资源类型：SCENIC/RESTAURANT/HOTEL/ACTIVITY/PRODUCT | -|   `sortOrder` | `int` | | 排序 | -| `sortOrder` | `int` | | 排序（默认0） | -| `source` | `string` | | 来源 | -| `subtitle` | `string` | | 副标题 | -| `summary` | `string` | | 摘要 | -| `tagIds` | `long[]` | | 标签ID列表 | -| `title` | `string` | 是 | 标题 | - -**响应** `统一响应结果«攻略文章详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略文章详情` | | 响应数据 | -|   `articleId` | `long` | | 文章ID | -|   `authorName` | `string` | | 作者名称 | -|   `bannerMaterialIds` | `long[]` | | 轮播图素材ID列表 | -|   `categoryId` | `long` | | 分类ID | -|   `categoryName` | `string` | | 分类名称 | -|   `content` | `string` | | 正文内容 | -|   `coverMaterialId` | `long` | | 封面素材ID | -|   `coverUrl` | `string` | | 封面URL | -|   `createdAt` | `string` | | 创建时间 | -|   `favoriteCount` | `int` | | 收藏数 | -|   `isRecommend` | `int` | | 是否推荐：0=否，1=是 | -|   `isTop` | `int` | | 是否置顶：0=否，1=是 | -|   `likeCount` | `int` | | 点赞数 | -|   `publishTime` | `string` | | 发布时间 | -|   `resources` | `文章关联资源[]` | | 关联资源列表 | -|     `resourceId` | `long` | | 资源ID | -|     `resourceName` | `string` | | 资源名称 | -|     `resourceType` | `string` | | 资源类型：SCENIC/RESTAURANT/HOTEL/ACTIVITY/PRODUCT | -|     `sortOrder` | `int` | | 排序 | -|   `sortOrder` | `int` | | 排序 | -|   `source` | `string` | | 来源 | -|   `status` | `int` | | 状态：0=草稿，1=已发布，2=已下架 | -|   `subtitle` | `string` | | 副标题 | -|   `summary` | `string` | | 摘要 | -|   `tags` | `攻略标签[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `long` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `tagType` | `int` | | 标签类型：0=系统管理，1=自定义 | -|     `useCount` | `int` | | 使用次数 | -|   `title` | `string` | | 标题 | -|   `updatedAt` | `string` | | 更新时间 | -|   `viewCount` | `int` | | 浏览量 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/guide/article/list - -**文章列表** - -分页查询攻略文章，支持按分类、状态、关键词筛选 - -**关联字典**： -- wiki_status：文章状态（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `categoryId` | `integer(int64)` | | 分类ID | | -| `isRecommend` | `integer(int32)` | | 是否推荐：0=否，1=是 | | -| `isTop` | `integer(int32)` | | 是否置顶：0=否，1=是 | | -| `keyword` | `string` | | 关键词（搜索标题/摘要） | | -| `orderBy` | `string` | | 排序字段：sortOrder/publishTime/viewCount/createdAt（默认createdAt） | | -| `orderDir` | `string` | | 排序方向：asc/desc（默认desc） | | -| `page` | `integer(int32)` | | 页码（默认1） | | -| `pageSize` | `integer(int32)` | | 每页数量（默认20，最大100） | | -| `status` | `integer(int32)` | | 状态：0=草稿，1=已发布，2=已下架 | | - -**响应** `统一响应结果«分页结果«攻略文章列表项»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«攻略文章列表项»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `攻略文章列表项[]` | | 数据列表 | -|     `articleId` | `long` | | 文章ID | -|     `categoryId` | `long` | | 分类ID | -|     `categoryName` | `string` | | 分类名称 | -|     `coverUrl` | `string` | | 封面URL | -|     `createdAt` | `string` | | 创建时间 | -|     `isRecommend` | `int` | | 是否推荐：0=否，1=是 | -|     `isTop` | `int` | | 是否置顶：0=否，1=是 | -|     `publishTime` | `string` | | 发布时间 | -|     `sortOrder` | `int` | | 排序 | -|     `status` | `int` | | 状态：0=草稿，1=已发布，2=已下架 | -|     `summary` | `string` | | 摘要 | -|     `tags` | `攻略标签[]` | | 标签列表 | -|     `title` | `string` | | 标题 | -|     `viewCount` | `int` | | 浏览量 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/guide/article/{articleId} - -**文章详情** - -**关联字典**： -- wiki_status：文章状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | 是 | articleId | - -**响应** `统一响应结果«攻略文章详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略文章详情` | | 响应数据 | -|   `articleId` | `long` | | 文章ID | -|   `authorName` | `string` | | 作者名称 | -|   `bannerMaterialIds` | `long[]` | | 轮播图素材ID列表 | -|   `categoryId` | `long` | | 分类ID | -|   `categoryName` | `string` | | 分类名称 | -|   `content` | `string` | | 正文内容 | -|   `coverMaterialId` | `long` | | 封面素材ID | -|   `coverUrl` | `string` | | 封面URL | -|   `createdAt` | `string` | | 创建时间 | -|   `favoriteCount` | `int` | | 收藏数 | -|   `isRecommend` | `int` | | 是否推荐：0=否，1=是 | -|   `isTop` | `int` | | 是否置顶：0=否，1=是 | -|   `likeCount` | `int` | | 点赞数 | -|   `publishTime` | `string` | | 发布时间 | -|   `resources` | `文章关联资源[]` | | 关联资源列表 | -|     `resourceId` | `long` | | 资源ID | -|     `resourceName` | `string` | | 资源名称 | -|     `resourceType` | `string` | | 资源类型：SCENIC/RESTAURANT/HOTEL/ACTIVITY/PRODUCT | -|     `sortOrder` | `int` | | 排序 | -|   `sortOrder` | `int` | | 排序 | -|   `source` | `string` | | 来源 | -|   `status` | `int` | | 状态：0=草稿，1=已发布，2=已下架 | -|   `subtitle` | `string` | | 副标题 | -|   `summary` | `string` | | 摘要 | -|   `tags` | `攻略标签[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `long` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `tagType` | `int` | | 标签类型：0=系统管理，1=自定义 | -|     `useCount` | `int` | | 使用次数 | -|   `title` | `string` | | 标题 | -|   `updatedAt` | `string` | | 更新时间 | -|   `viewCount` | `int` | | 浏览量 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/guide/article/{articleId} - -**更新文章** - -更新攻略文章的标题、内容、封面图、分类等信息。已发布的文章更新后立即生效。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | 是 | articleId | - -**请求体** `ArticleUpdateRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `authorName` | `string` | | 作者名称 | -| `bannerMaterialIds` | `long[]` | | 轮播图素材ID列表 | -| `categoryId` | `long` | | 分类ID | -| `content` | `string` | | 正文内容 | -| `coverMaterialId` | `long` | | 封面素材ID | -| `coverUrl` | `string` | | 封面URL | -| `resources` | `ArticleResourceItem[]` | | 关联资源列表 | -|   `resourceId` | `long` | 是 | 资源ID | -|   `resourceName` | `string` | 是 | 资源名称 | -|   `resourceType` | `string` | 是 | 资源类型：SCENIC/RESTAURANT/HOTEL/ACTIVITY/PRODUCT | -|   `sortOrder` | `int` | | 排序 | -| `sortOrder` | `int` | | 排序 | -| `source` | `string` | | 来源 | -| `subtitle` | `string` | | 副标题 | -| `summary` | `string` | | 摘要 | -| `tagIds` | `long[]` | | 标签ID列表 | -| `title` | `string` | | 标题 | - -**响应** `统一响应结果«攻略文章详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略文章详情` | | 响应数据 | -|   `articleId` | `long` | | 文章ID | -|   `authorName` | `string` | | 作者名称 | -|   `bannerMaterialIds` | `long[]` | | 轮播图素材ID列表 | -|   `categoryId` | `long` | | 分类ID | -|   `categoryName` | `string` | | 分类名称 | -|   `content` | `string` | | 正文内容 | -|   `coverMaterialId` | `long` | | 封面素材ID | -|   `coverUrl` | `string` | | 封面URL | -|   `createdAt` | `string` | | 创建时间 | -|   `favoriteCount` | `int` | | 收藏数 | -|   `isRecommend` | `int` | | 是否推荐：0=否，1=是 | -|   `isTop` | `int` | | 是否置顶：0=否，1=是 | -|   `likeCount` | `int` | | 点赞数 | -|   `publishTime` | `string` | | 发布时间 | -|   `resources` | `文章关联资源[]` | | 关联资源列表 | -|     `resourceId` | `long` | | 资源ID | -|     `resourceName` | `string` | | 资源名称 | -|     `resourceType` | `string` | | 资源类型：SCENIC/RESTAURANT/HOTEL/ACTIVITY/PRODUCT | -|     `sortOrder` | `int` | | 排序 | -|   `sortOrder` | `int` | | 排序 | -|   `source` | `string` | | 来源 | -|   `status` | `int` | | 状态：0=草稿，1=已发布，2=已下架 | -|   `subtitle` | `string` | | 副标题 | -|   `summary` | `string` | | 摘要 | -|   `tags` | `攻略标签[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `long` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `tagType` | `int` | | 标签类型：0=系统管理，1=自定义 | -|     `useCount` | `int` | | 使用次数 | -|   `title` | `string` | | 标题 | -|   `updatedAt` | `string` | | 更新时间 | -|   `viewCount` | `int` | | 浏览量 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/guide/article/{articleId} - -**删除文章** - -软删除攻略文章，同时清除文章的标签关联。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | 是 | articleId | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/guide/article/{articleId}/recommend - -**设置推荐** - -设置/取消文章推荐。推荐文章会在小程序首页和推荐列表中优先展示 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | 是 | articleId | - -**请求体** `RecommendRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `isRecommend` | `int` | 是 | 是否推荐：0=否，1=是 | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/guide/article/{articleId}/status - -**发布/下架** - -切换文章发布状态。发布后小程序端可见，下架后小程序端不再展示但管理端仍可查看 - -**关联字典**： -- wiki_status：文章状态（状态切换） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | 是 | articleId | - -**请求体** `StatusRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `status` | `int` | 是 | 状态值 | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/guide/article/{articleId}/top - -**设置置顶** - -设置/取消文章置顶。置顶文章在分类列表中始终排在最前面 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | 是 | articleId | - -**请求体** `TopRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `isTop` | `int` | 是 | 是否置顶：0=否，1=是 | - -**响应** `统一响应结果«Void»` - ---- - -## 攻略标签管理 - -### `POST` /admin/guide/tag - -**创建标签** - -创建攻略系统标签，标签名称不可重复。创建后可用于文章分类和筛选。 - -**权限**：需管理员登录。 - -**请求体** `TagCreateRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagColor` | `string` | | 标签颜色（十六进制） | -| `tagName` | `string` | 是 | 标签名称 | -| `tagType` | `int` | | 标签类型：0=系统管理，1=自定义（默认0） | - -**响应** `统一响应结果«攻略标签»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略标签` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `long` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `tagType` | `int` | | 标签类型：0=系统管理，1=自定义 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/guide/tag/all - -**所有标签列表** - -返回全部标签（含系统标签和用户自定义标签），用于文章编辑时的标签选择器 - -**响应** `统一响应结果«List«攻略标签»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略标签[]` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `long` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `tagType` | `int` | | 标签类型：0=系统管理，1=自定义 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/guide/tag/article/{articleId} - -**更新文章标签** - -全量替换文章的标签关联，传入新的标签ID列表（空数组表示清除所有标签） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | 是 | articleId | - -**请求体** `ArticleTagUpdateRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagIds` | `long[]` | 是 | 标签ID列表 | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/guide/tag/managed - -**系统标签列表** - -返回管理员创建的系统标签（不含用户自定义标签），用于标签管理页 - -**响应** `统一响应结果«List«攻略标签»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略标签[]` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `long` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `tagType` | `int` | | 标签类型：0=系统管理，1=自定义 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/guide/tag/{tagId} - -**更新标签** - -更新标签名称。标签名称不可与其他已有标签重复。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagId` | `integer` | 是 | tagId | - -**请求体** `TagUpdateRequest` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagColor` | `string` | | 标签颜色（十六进制） | -| `tagName` | `string` | | 标签名称 | - -**响应** `统一响应结果«攻略标签»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `攻略标签` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `long` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `tagType` | `int` | | 标签类型：0=系统管理，1=自定义 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/guide/tag/{tagId} - -**删除标签** - -删除标签并自动解除与所有文章的关联关系。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagId` | `integer` | 是 | tagId | - -**响应** `统一响应结果«Void»` - ---- diff --git a/2026-03/17_1012/hl-material-service.md b/2026-03/17_1012/hl-material-service.md deleted file mode 100644 index c8ed7fb..0000000 --- a/2026-03/17_1012/hl-material-service.md +++ /dev/null @@ -1,968 +0,0 @@ -# 素材服务 API 文档 - -**服务**: `hl-material-service` -**接口总数**: 28 - -## 目录 - -- **小程序-素材** (1 个接口) -- **素材分类权限管理** (2 个接口) -- **素材标签管理** (6 个接口) -- **素材管理** (19 个接口) - ---- - -## 小程序-素材 - -### `GET` /mp/material/miniprogram - -**获取小程序分类下的全部素材** - -返回miniprogram分类下的所有素材，用于小程序端展示公共素材资源（如引导页图片、默认头像等） - -**响应** `统一响应结果«List«素材信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材信息[]` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `categoryPath` | `string` | | 完整分类路径（如：攻略管理 / 999 / 888） | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `string` | | 创建人ID | -|   `createdByName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 素材描述 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `imageHeight` | `int` | | 图片高度 | -|   `imageWidth` | `int` | | 图片宽度 | -|   `materialId` | `string` | | 素材ID | -|   `materialName` | `string` | | 素材名称 | -|   `ossUrl` | `string` | | OSS地址 | -|   `refCount` | `int` | | 引用次数 | -|   `subCategoryId` | `string` | | 子分类ID | -|   `subCategoryName` | `string` | | 子分类名称 | -|   `tags` | `素材标签信息[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdByName` | `string` | | 创建人姓名 | -|     `managed` | `boolean` | | 是否系统管理标签 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `string` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `useCount` | `int` | | 使用次数 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -## 素材分类权限管理 - -### `GET` /admin/material/category/permissions/{roleCode} - -**获取角色的分类权限** - -仅超级管理员可操作。返回指定角色可访问的素材分类编码列表 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `roleCode` | `string` | | 角色编码 | - -**响应** `统一响应结果«List«string»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `string[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/material/category/permissions/{roleCode} - -**更新角色的分类权限** - -仅超级管理员可操作。全量替换指定角色的素材分类访问权限，传入允许访问的分类编码列表 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `roleCode` | `string` | | 角色编码 | - -**请求体** `分类权限更新请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryCodes` | `string[]` | 是 | 分类编码列表 | - -**响应** `统一响应结果«Void»` - ---- - -## 素材标签管理 - -### `POST` /admin/material/tag - -**创建管理标签** - -创建系统级素材标签，标签名称不可重复。创建后可用于素材分类和筛选。 - -**权限**：需管理员登录。 - -**请求体** `创建标签请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagColor` | `string` | | 标签颜色 | -| `tagName` | `string` | 是 | 标签名称 | - -**响应** `统一响应结果«素材标签信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材标签信息` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdByName` | `string` | | 创建人姓名 | -|   `managed` | `boolean` | | 是否系统管理标签 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `string` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/tag/adhoc - -**解析自定义标签（按名称查找或创建）** - -按标签名称查找已有标签，不存在则自动创建为用户自定义标签。用于素材上传时输入自由标签文本的场景。 - -**权限**：需管理员登录。 - -**请求体** `创建标签请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagColor` | `string` | | 标签颜色 | -| `tagName` | `string` | 是 | 标签名称 | - -**响应** `统一响应结果«素材标签信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材标签信息` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdByName` | `string` | | 创建人姓名 | -|   `managed` | `boolean` | | 是否系统管理标签 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `string` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/material/tag/{tagId} - -**编辑标签** - -更新标签名称。标签名称不可与其他已有标签重复。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagId` | `integer` | | 标签ID | - -**请求体** `更新标签请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagColor` | `string` | | 标签颜色 | -| `tagName` | `string` | | 标签名称 | - -**响应** `统一响应结果«素材标签信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材标签信息` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdByName` | `string` | | 创建人姓名 | -|   `managed` | `boolean` | | 是否系统管理标签 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `string` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/material/tag/{tagId} - -**删除标签** - -删除标签并自动解除与所有素材的关联关系。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagId` | `integer` | | 标签ID | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/material/tags - -**获取管理标签（标签管理用）** - -返回管理员创建的系统标签列表（不含用户自定义标签），用于标签管理页的CRUD操作。 - -**响应** `统一响应结果«List«素材标签信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材标签信息[]` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdByName` | `string` | | 创建人姓名 | -|   `managed` | `boolean` | | 是否系统管理标签 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `string` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/material/tags/all - -**获取全部标签（选择器用，含自定义标签）** - -返回所有标签（含系统标签和用户自定义标签），用于素材上传/编辑时的标签选择器。 - -**响应** `统一响应结果«List«素材标签信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材标签信息[]` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdByName` | `string` | | 创建人姓名 | -|   `managed` | `boolean` | | 是否系统管理标签 | -|   `tagColor` | `string` | | 标签颜色 | -|   `tagId` | `string` | | 标签ID | -|   `tagName` | `string` | | 标签名称 | -|   `useCount` | `int` | | 使用次数 | -| `message` | `string` | | 响应消息 | - ---- - -## 素材管理 - -### `DELETE` /admin/material/batch - -**批量删除素材** - -批量删除素材，返回删除结果（成功数/失败数/失败原因）。有引用关系的素材会跳过并记录失败原因 - -**请求体** `批量删除素材请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `materialIds` | `string[]` | 是 | 素材ID列表 | - -**响应** `统一响应结果«批量删除结果»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `批量删除结果` | | 响应数据 | -|   `failedItems` | `删除失败项[]` | | 失败项列表 | -|     `materialId` | `string` | | 素材ID | -|     `reason` | `string` | | 失败原因 | -|   `successCount` | `int` | | 成功删除数量 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/material/batch/tags - -**批量更新标签** - -对多个素材同时添加和/或移除标签，支持增量操作（addTagIds新增，removeTagIds移除） - -**请求体** `批量标签操作请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `addTagIds` | `string[]` | | 要添加的标签ID列表 | -| `materialIds` | `string[]` | 是 | 素材ID列表 | -| `removeTagIds` | `string[]` | | 要移除的标签ID列表 | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/material/categories - -**获取有权限的分类列表（含素材数量）** - -返回当前角色有权限查看的素材分类树，每个分类包含素材数量统计。超级管理员可见全部分类 - -**响应** `统一响应结果«List«素材分类信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材分类信息[]` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `children` | `素材分类信息[]` | | 子分类列表 | -|     `categoryCode` | `string` | | 分类编码 | -|     `categoryName` | `string` | | 分类名称 | -|     `children` | `素材分类信息[]` | | 子分类列表 | -|     `materialCount` | `int` | | 素材数量 | -|     `parentId` | `string` | | 父子分类ID | -|     `subCategoryId` | `string` | | 子分类ID | -|   `materialCount` | `int` | | 素材数量 | -|   `parentId` | `string` | | 父子分类ID | -|   `subCategoryId` | `string` | | 子分类ID | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/category/sub - -**创建子分类** - -在一级分类下创建子分类，分类编码自动生成。子分类用于更细粒度的素材归档 - -**请求体** `Create subcategory request` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryName` | `string` | 是 | 子分类名称 | -| `parentCode` | `string` | 是 | 根分类编码(scenic/hotel等) | -| `parentId` | `long` | | 父子分类ID(为空则创建在根分类下) | -| `sortOrder` | `int` | | 排序值 | - -**响应** `统一响应结果«素材分类信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材分类信息` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `children` | `素材分类信息[]` | | 子分类列表 | -|     `categoryCode` | `string` | | 分类编码 | -|     `categoryName` | `string` | | 分类名称 | -|     `children` | `素材分类信息[]` | | 子分类列表 | -|     `materialCount` | `int` | | 素材数量 | -|     `parentId` | `string` | | 父子分类ID | -|     `subCategoryId` | `string` | | 子分类ID | -|   `materialCount` | `int` | | 素材数量 | -|   `parentId` | `string` | | 父子分类ID | -|   `subCategoryId` | `string` | | 子分类ID | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/material/category/sub/{categoryId} - -**更新子分类** - -更新子分类的名称或排序值。仅有该分类权限的管理员可操作。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryId` | `integer` | | 子分类ID | - -**请求体** `Update subcategory request` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryName` | `string` | | Subcategory name | -| `sortOrder` | `int` | | Sort order | - -**响应** `统一响应结果«素材分类信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材分类信息` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `children` | `素材分类信息[]` | | 子分类列表 | -|     `categoryCode` | `string` | | 分类编码 | -|     `categoryName` | `string` | | 分类名称 | -|     `children` | `素材分类信息[]` | | 子分类列表 | -|     `materialCount` | `int` | | 素材数量 | -|     `parentId` | `string` | | 父子分类ID | -|     `subCategoryId` | `string` | | 子分类ID | -|   `materialCount` | `int` | | 素材数量 | -|   `parentId` | `string` | | 父子分类ID | -|   `subCategoryId` | `string` | | 子分类ID | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/material/category/sub/{categoryId} - -**删除子分类** - -删除子分类前需确保分类下无素材，否则删除失败 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryId` | `integer` | | 子分类ID | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/material/list - -**素材列表** - -分页查询素材，支持按分类、标签、文件类型、关键词筛选。返回结果受角色分类权限限制 - -**关联字典**： -- file_type：文件类型（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `categoryCode` | `string` | | 分类编码 | scenic | -| `createdBy` | `integer(int64)` | | 创建人ID | 1001 | -| `endDate` | `string` | | 结束日期 | 2026-12-31 | -| `fileType` | `string` | | 文件类型 | image | -| `keyword` | `string` | | 搜索关键词 | 风景 | -| `orderBy` | `string` | | 排序字段 | createdAt | -| `orderDir` | `string` | | 排序方向: asc/desc | desc | -| `page` | `integer(int32)` | | 页码 | 1 | -| `pageSize` | `integer(int32)` | | 每页条数 | 20 | -| `startDate` | `string` | | 开始日期 | 2026-01-01 | -| `subCategoryId` | `integer(int64)` | | 子分类ID | 2030000000000001 | -| `tagIds` | `string` | | 标签ID列表(逗号分隔) | 1,2,3 | - -**响应** `统一响应结果«分页结果«素材信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«素材信息»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `素材信息[]` | | 数据列表 | -|     `categoryCode` | `string` | | 分类编码 | -|     `categoryName` | `string` | | 分类名称 | -|     `categoryPath` | `string` | | 完整分类路径（如：攻略管理 / 999 / 888） | -|     `createdAt` | `string` | | 创建时间 | -|     `createdBy` | `string` | | 创建人ID | -|     `createdByName` | `string` | | 创建人姓名 | -|     `description` | `string` | | 素材描述 | -|     `fileId` | `string` | | 文件ID | -|     `fileName` | `string` | | 文件名 | -|     `fileSize` | `long` | | 文件大小(字节) | -|     `fileType` | `string` | | 文件类型 | -|     `imageHeight` | `int` | | 图片高度 | -|     `imageWidth` | `int` | | 图片宽度 | -|     `materialId` | `string` | | 素材ID | -|     `materialName` | `string` | | 素材名称 | -|     `ossUrl` | `string` | | OSS地址 | -|     `refCount` | `int` | | 引用次数 | -|     `subCategoryId` | `string` | | 子分类ID | -|     `subCategoryName` | `string` | | 子分类名称 | -|     `tags` | `素材标签信息[]` | | 标签列表 | -|     `thumbnailUrl` | `string` | | 缩略图地址 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/upload/chunk - -**分片上传-上传分片** - -大文件上传第二步：逐个上传分片数据，分片索引从0开始。支持断点续传，已上传的分片无需重传。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `chunkIndex` | `integer(int32)` | | 分片索引（从0开始） | | -| `uploadId` | `string` | | 上传ID | | - -**响应** `统一响应结果«分片上传结果»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分片上传结果` | | 响应数据 | -|   `etag` | `string` | | 分片ETag | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/upload/chunk/cancel - -**分片上传-取消** - -取消分片上传任务，清理已上传的分片数据和OSS临时文件。仅上传发起者可取消。 - -**请求体** `分片上传取消请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `uploadId` | `string` | 是 | 上传ID | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /admin/material/upload/chunk/complete - -**分片上传-完成合并** - -大文件上传第三步：所有分片上传完成后调用，OSS端合并分片为完整文件并创建素材记录。 - -**请求体** `分片上传完成请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `uploadId` | `string` | 是 | 上传ID | - -**响应** `统一响应结果«素材信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材信息` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `categoryPath` | `string` | | 完整分类路径（如：攻略管理 / 999 / 888） | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `string` | | 创建人ID | -|   `createdByName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 素材描述 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `imageHeight` | `int` | | 图片高度 | -|   `imageWidth` | `int` | | 图片宽度 | -|   `materialId` | `string` | | 素材ID | -|   `materialName` | `string` | | 素材名称 | -|   `ossUrl` | `string` | | OSS地址 | -|   `refCount` | `int` | | 引用次数 | -|   `subCategoryId` | `string` | | 子分类ID | -|   `subCategoryName` | `string` | | 子分类名称 | -|   `tags` | `素材标签信息[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdByName` | `string` | | 创建人姓名 | -|     `managed` | `boolean` | | 是否系统管理标签 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `string` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `useCount` | `int` | | 使用次数 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/upload/chunk/init - -**分片上传-初始化** - -大文件上传第一步：初始化分片上传任务，返回uploadId和每个分片的预签名URL。前端按分片并发上传后调用完成合并接口。 - -**权限**：需管理员登录，受角色分类权限限制。 - -**请求体** `分片上传初始化请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `contentType` | `string` | 是 | 文件MIME类型 | -| `fileSize` | `long` | 是 | 文件大小（字节） | -| `filename` | `string` | 是 | 文件名 | -| `materialId` | `string` | | 关联素材ID（可选，用于更新已有素材） | - -**响应** `统一响应结果«分片上传初始化结果»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分片上传初始化结果` | | 响应数据 | -|   `chunkSize` | `int` | | 推荐分片大小（字节） | -|   `uploadId` | `string` | | 上传ID | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/upload/confirm - -**确认上传完成** - -上传素材第二步：前端直传OSS完成后调用此接口创建素材记录，支持MD5去重 - -**关联字典**： -- material_tag：素材标签（上传时可选标签） - -**请求体** `素材上传确认请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `description` | `string` | | 素材描述 | -| `materialId` | `string` | 是 | 素材ID | -| `tagIds` | `string[]` | | 标签ID列表 | - -**响应** `统一响应结果«素材信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材信息` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `categoryPath` | `string` | | 完整分类路径（如：攻略管理 / 999 / 888） | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `string` | | 创建人ID | -|   `createdByName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 素材描述 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `imageHeight` | `int` | | 图片高度 | -|   `imageWidth` | `int` | | 图片宽度 | -|   `materialId` | `string` | | 素材ID | -|   `materialName` | `string` | | 素材名称 | -|   `ossUrl` | `string` | | OSS地址 | -|   `refCount` | `int` | | 引用次数 | -|   `subCategoryId` | `string` | | 子分类ID | -|   `subCategoryName` | `string` | | 子分类名称 | -|   `tags` | `素材标签信息[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdByName` | `string` | | 创建人姓名 | -|     `managed` | `boolean` | | 是否系统管理标签 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `string` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `useCount` | `int` | | 使用次数 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/upload/folder - -**文件夹上传初始化（创建分类+批量获取凭证）** - -支持整个文件夹上传：自动根据文件夹名创建子分类，为每个文件批量获取上传凭证，前端逐一上传后批量确认 - -**请求体** `文件夹上传初始化请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryCode` | `string` | 是 | 分类编码 | -| `files` | `文件夹上传文件项[]` | 是 | 文件列表 | -|   `contentType` | `string` | 是 | 文件MIME类型 | -|   `fileSize` | `long` | 是 | 文件大小(字节) | -|   `filename` | `string` | 是 | 文件名 | -|   `folderPath` | `string` | 是 | 文件所在文件夹路径（与folderPaths中的路径对应） | -|   `materialName` | `string` | | 素材名称 | -|   `md5` | `string` | 是 | 文件MD5 | -| `folderPaths` | `string[]` | 是 | 文件夹路径列表（如 ["999", "999/888"]） | - -**响应** `统一响应结果«文件夹上传初始化结果»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `文件夹上传初始化结果` | | 响应数据 | -|   `fileTokens` | `文件上传凭证项[]` | | 各文件的上传凭证列表 | -|     `bucket` | `string` | | OSS Bucket名称 | -|     `error` | `string` | | 错误信息（该文件获取凭证失败时） | -|     `filename` | `string` | | 文件名 | -|     `folderPath` | `string` | | 文件夹路径 | -|     `instantUpload` | `boolean` | | 是否秒传（文件已存在） | -|     `materialId` | `string` | | 素材ID | -|     `ossKey` | `string` | | OSS对象Key | -|     `region` | `string` | | OSS Region | -|     `stsToken` | `STS临时凭证信息` | | STS临时凭证 | -|     `uploadHeaders` | `object` | | 上传请求头 | -|     `uploadMethod` | `string` | | 上传方式: PUT/POST | -|     `uploadUrl` | `string` | | 上传URL | -|   `folderCategoryMap` | `object` | | 文件夹路径 → 子分类ID 映射 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/material/upload/token - -**获取上传凭证** - -上传素材第一步：获取OSS预签名URL和凭证。前端使用凭证直传OSS后调用确认上传。支持基于角色的分类权限校验 - -**请求体** `素材上传令牌请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryCode` | `string` | 是 | 分类编码 | -| `contentType` | `string` | 是 | 文件MIME类型 | -| `fileSize` | `long` | 是 | 文件大小(字节) | -| `filename` | `string` | 是 | 文件名 | -| `materialName` | `string` | | 素材名称 | -| `md5` | `string` | 是 | 文件MD5 | -| `subCategoryId` | `long` | | 子分类ID（文件夹上传时使用） | - -**响应** `统一响应结果«素材上传令牌信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材上传令牌信息` | | 响应数据 | -|   `bucket` | `string` | | OSS Bucket名称 | -|   `contentType` | `string` | | 上传时必须使用的Content-Type（与预签名URL签名一致） | -|   `expireAt` | `string` | | 过期时间 | -|   `fileId` | `string` | | 文件ID | -|   `instantUpload` | `boolean` | | 是否秒传 | -|   `material` | `素材信息` | | 秒传时返回的素材信息 | -|     `categoryCode` | `string` | | 分类编码 | -|     `categoryName` | `string` | | 分类名称 | -|     `categoryPath` | `string` | | 完整分类路径（如：攻略管理 / 999 / 888） | -|     `createdAt` | `string` | | 创建时间 | -|     `createdBy` | `string` | | 创建人ID | -|     `createdByName` | `string` | | 创建人姓名 | -|     `description` | `string` | | 素材描述 | -|     `fileId` | `string` | | 文件ID | -|     `fileName` | `string` | | 文件名 | -|     `fileSize` | `long` | | 文件大小(字节) | -|     `fileType` | `string` | | 文件类型 | -|     `imageHeight` | `int` | | 图片高度 | -|     `imageWidth` | `int` | | 图片宽度 | -|     `materialId` | `string` | | 素材ID | -|     `materialName` | `string` | | 素材名称 | -|     `ossUrl` | `string` | | OSS地址 | -|     `refCount` | `int` | | 引用次数 | -|     `subCategoryId` | `string` | | 子分类ID | -|     `subCategoryName` | `string` | | 子分类名称 | -|     `tags` | `素材标签信息[]` | | 标签列表 | -|     `thumbnailUrl` | `string` | | 缩略图地址 | -|   `materialId` | `string` | | 素材ID | -|   `ossKey` | `string` | | OSS对象Key | -|   `region` | `string` | | OSS Region | -|   `stsToken` | `STS临时凭证信息` | | STS临时凭证 | -|     `accessKeyId` | `string` | | AccessKey ID | -|     `accessKeySecret` | `string` | | AccessKey Secret | -|     `expiration` | `string` | | 过期时间 | -|     `securityToken` | `string` | | 安全令牌 | -|   `uploadMode` | `string` | | 上传模式: PRESIGNED_URL/STS_MULTIPART | -|   `uploadUrl` | `string` | | 上传URL | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/material/{materialId} - -**素材详情** - -返回素材完整信息，包含文件名、URL、分类、标签、文件大小、上传者等。受角色分类权限限制。 - -**关联字典**： -- file_type：文件类型（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `materialId` | `integer` | | 素材ID | - -**响应** `统一响应结果«素材信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材信息` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `categoryPath` | `string` | | 完整分类路径（如：攻略管理 / 999 / 888） | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `string` | | 创建人ID | -|   `createdByName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 素材描述 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `imageHeight` | `int` | | 图片高度 | -|   `imageWidth` | `int` | | 图片宽度 | -|   `materialId` | `string` | | 素材ID | -|   `materialName` | `string` | | 素材名称 | -|   `ossUrl` | `string` | | OSS地址 | -|   `refCount` | `int` | | 引用次数 | -|   `subCategoryId` | `string` | | 子分类ID | -|   `subCategoryName` | `string` | | 子分类名称 | -|   `tags` | `素材标签信息[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdByName` | `string` | | 创建人姓名 | -|     `managed` | `boolean` | | 是否系统管理标签 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `string` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `useCount` | `int` | | 使用次数 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/material/{materialId} - -**更新素材信息** - -**关联字典**： -- material_tag：素材标签（编辑时选择标签） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `materialId` | `integer` | | 素材ID | - -**请求体** `更新素材请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryCode` | `string` | | 分类编码 | -| `description` | `string` | | 素材描述 | -| `materialName` | `string` | | 素材名称 | -| `subCategoryId` | `long` | | 子分类ID（0表示清除子分类） | - -**响应** `统一响应结果«素材信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材信息` | | 响应数据 | -|   `categoryCode` | `string` | | 分类编码 | -|   `categoryName` | `string` | | 分类名称 | -|   `categoryPath` | `string` | | 完整分类路径（如：攻略管理 / 999 / 888） | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `string` | | 创建人ID | -|   `createdByName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 素材描述 | -|   `fileId` | `string` | | 文件ID | -|   `fileName` | `string` | | 文件名 | -|   `fileSize` | `long` | | 文件大小(字节) | -|   `fileType` | `string` | | 文件类型 | -|   `imageHeight` | `int` | | 图片高度 | -|   `imageWidth` | `int` | | 图片宽度 | -|   `materialId` | `string` | | 素材ID | -|   `materialName` | `string` | | 素材名称 | -|   `ossUrl` | `string` | | OSS地址 | -|   `refCount` | `int` | | 引用次数 | -|   `subCategoryId` | `string` | | 子分类ID | -|   `subCategoryName` | `string` | | 子分类名称 | -|   `tags` | `素材标签信息[]` | | 标签列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdByName` | `string` | | 创建人姓名 | -|     `managed` | `boolean` | | 是否系统管理标签 | -|     `tagColor` | `string` | | 标签颜色 | -|     `tagId` | `string` | | 标签ID | -|     `tagName` | `string` | | 标签名称 | -|     `useCount` | `int` | | 使用次数 | -|   `thumbnailUrl` | `string` | | 缩略图地址 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/material/{materialId} - -**删除素材** - -删除素材记录。如果素材存在引用关系（被景区、酒店等使用），则不允许删除 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `materialId` | `integer` | | 素材ID | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/material/{materialId}/refs - -**查看素材引用记录** - -查看素材被哪些业务实体引用（如景区封面、酒店轮播图等），用于判断素材是否可安全删除 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `materialId` | `integer` | | 素材ID | - -**响应** `统一响应结果«List«素材引用信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `素材引用信息[]` | | 响应数据 | -|   `bizId` | `string` | | 业务ID | -|   `bizName` | `string` | | 业务名称 | -|   `bizType` | `string` | | 业务类型 | -|   `bizTypeName` | `string` | | 业务类型名称 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdByName` | `string` | | 创建人姓名 | -|   `id` | `string` | | 引用ID | -|   `materialId` | `string` | | 素材ID | -|   `usageType` | `string` | | 用途类型 | -|   `usageTypeName` | `string` | | 用途类型名称 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/material/{materialId}/tags - -**更新素材标签** - -全量替换单个素材的标签，传入新的标签ID列表 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `materialId` | `integer` | | 素材ID | - -**请求体** `更新素材标签请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `tagIds` | `string[]` | 是 | 标签ID列表 | - -**响应** `统一响应结果«Void»` - ---- diff --git a/2026-03/17_1012/hl-monitor-service.md b/2026-03/17_1012/hl-monitor-service.md deleted file mode 100644 index 188a26a..0000000 --- a/2026-03/17_1012/hl-monitor-service.md +++ /dev/null @@ -1,553 +0,0 @@ -# 监控服务 API 文档 - -**服务**: `hl-monitor-service` -**接口总数**: 18 - -## 目录 - -- **MySQL监控** (3 个接口) -- **Redis监控** (1 个接口) -- **RocketMQ监控** (3 个接口) -- **企微审批日志** (2 个接口) -- **操作日志** (2 个接口) -- **数据清理** (1 个接口) -- **服务监控** (1 个接口) -- **消息通知日志** (2 个接口) -- **登录日志** (1 个接口) -- **错误日志** (2 个接口) - ---- - -## MySQL监控 - -### `GET` /admin/monitor/mysql - -**MySQL实时监控数据** - -返回MySQL实时状态：连接数、QPS、缓冲池命中率、线程状态、慢查询计数等核心指标 - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/mysql/slow-queries - -**慢SQL查询统计** - -仅超级管理员可操作。查询慢SQL统计信息，返回执行时间最长的SQL语句及其执行次数、平均耗时等 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `limit` | `integer(int32)` | | 返回条数 | | -| `type` | `string` | | 查询类型 | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/mysql/tables - -**表空间列表** - -查询各数据库表的空间占用情况，包含数据大小、索引大小、行数等信息。可指定schema筛选，仅允许查询hl_前缀的数据库 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `schema` | `string` | | 数据库名 | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## Redis监控 - -### `GET` /admin/monitor/redis - -**Redis实时监控数据** - -返回Redis实时状态：内存使用量、连接数、Key数量、命中率、每秒命令数等核心指标 - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## RocketMQ监控 - -### `GET` /admin/monitor/rocketmq - -**RocketMQ概览** - -返回RocketMQ集群状态：Broker状态、Topic数量、消息积压量、生产者/消费者连接数等核心指标 - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/rocketmq/consumer-groups - -**消费者组统计** - -返回各消费者组的消费进度、积压量和在线消费者实例信息 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/rocketmq/topics - -**Topic统计** - -返回各Topic的消息量、最新偏移量和消费进度等信息 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## 企微审批日志 - -### `GET` /admin/monitor/approval-logs - -**审批日志分页查询** - -查询企微OA审批流程记录，支持按审批状态(1-审批中/2-已通过/3-已驳回/4-已撤销)、申请人、模板名称筛选 - -**关联字典**： -- approval_sp_status：审批状态（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `applyUserName` | `string` | | 申请人姓名 | | -| `endTime` | `string` | | 结束时间 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `spName` | `string` | | 审批模板名称 | | -| `spStatus` | `integer(int32)` | | 审批状态 | | -| `startTime` | `string` | | 开始时间 | | - -**响应** `统一响应结果«分页结果«审批日志»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«审批日志»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `审批日志[]` | | 数据列表 | -|     `applyData` | `string` | | 申请表单数据(JSON) | -|     `applyTime` | `string` | | 申请时间 | -|     `applyUserId` | `string` | | 申请人企微UserID | -|     `applyUserName` | `string` | | 申请人姓名 | -|     `approvalLogId` | `long` | | 审批日志ID | -|     `approvalNodes` | `string` | | 审批节点详情(JSON) | -|     `createdAt` | `string` | | 创建时间 | -|     `notifyNodes` | `string` | | 抄送节点详情(JSON) | -|     `spName` | `string` | | 审批模板名称 | -|     `spStatus` | `int` | | 审批状态: 1-审批中, 2-已通过, 3-已驳回, 4-已撤销, 6-通过后撤销, 7-已删除 | -|     `templateId` | `string` | | 审批模板ID | -|     `thirdNo` | `string` | | 审批编号 | -|     `updatedAt` | `string` | | 更新时间 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/approval-logs/{id} - -**审批日志详情** - -**关联字典**： -- approval_sp_status：审批状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 日志ID | - -**响应** `统一响应结果«审批日志»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `审批日志` | | 响应数据 | -|   `applyData` | `string` | | 申请表单数据(JSON) | -|   `applyTime` | `string` | | 申请时间 | -|   `applyUserId` | `string` | | 申请人企微UserID | -|   `applyUserName` | `string` | | 申请人姓名 | -|   `approvalLogId` | `long` | | 审批日志ID | -|   `approvalNodes` | `string` | | 审批节点详情(JSON) | -|   `createdAt` | `string` | | 创建时间 | -|   `notifyNodes` | `string` | | 抄送节点详情(JSON) | -|   `spName` | `string` | | 审批模板名称 | -|   `spStatus` | `int` | | 审批状态: 1-审批中, 2-已通过, 3-已驳回, 4-已撤销, 6-通过后撤销, 7-已删除 | -|   `templateId` | `string` | | 审批模板ID | -|   `thirdNo` | `string` | | 审批编号 | -|   `updatedAt` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -## 操作日志 - -### `GET` /admin/monitor/operation-logs - -**操作日志分页查询** - -查询管理员的操作记录，支持按模块、管理员、状态、时间范围筛选。记录包含请求参数、响应结果和耗时信息 - -**关联字典**： -- operation_log_status：操作状态（列表筛选+显示，0=成功/1=失败） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `adminId` | `integer(int64)` | | 管理员ID | | -| `endTime` | `string` | | 结束时间 | | -| `module` | `string` | | 模块名称 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `startTime` | `string` | | 开始时间 | | -| `status` | `integer(int32)` | | 状态 | | - -**响应** `统一响应结果«分页结果«操作日志»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«操作日志»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `操作日志[]` | | 数据列表 | -|     `adminId` | `long` | | 管理员ID | -|     `adminName` | `string` | | 管理员名称 | -|     `createdAt` | `string` | | 创建时间 | -|     `description` | `string` | | 操作描述 | -|     `duration` | `int` | | 耗时(毫秒) | -|     `errorMsg` | `string` | | 错误信息 | -|     `ipAddress` | `string` | | IP地址 | -|     `module` | `string` | | 操作模块 | -|     `operationLogId` | `long` | | 操作日志ID | -|     `requestMethod` | `string` | | 请求方法 | -|     `requestParams` | `string` | | 请求参数(JSON) | -|     `requestUrl` | `string` | | 请求URL | -|     `responseCode` | `int` | | 响应状态码 | -|     `responseMsg` | `string` | | 响应消息 | -|     `serviceName` | `string` | | 服务名称 | -|     `status` | `int` | | 状态: 0-成功, 1-失败 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/operation-logs/{id} - -**操作日志详情** - -返回单条操作日志的完整信息，包含操作模块、操作描述、请求参数、响应结果、操作耗时、操作人信息、IP地址等。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 日志ID | - -**响应** `统一响应结果«操作日志»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `操作日志` | | 响应数据 | -|   `adminId` | `long` | | 管理员ID | -|   `adminName` | `string` | | 管理员名称 | -|   `createdAt` | `string` | | 创建时间 | -|   `description` | `string` | | 操作描述 | -|   `duration` | `int` | | 耗时(毫秒) | -|   `errorMsg` | `string` | | 错误信息 | -|   `ipAddress` | `string` | | IP地址 | -|   `module` | `string` | | 操作模块 | -|   `operationLogId` | `long` | | 操作日志ID | -|   `requestMethod` | `string` | | 请求方法 | -|   `requestParams` | `string` | | 请求参数(JSON) | -|   `requestUrl` | `string` | | 请求URL | -|   `responseCode` | `int` | | 响应状态码 | -|   `responseMsg` | `string` | | 响应消息 | -|   `serviceName` | `string` | | 服务名称 | -|   `status` | `int` | | 状态: 0-成功, 1-失败 | -| `message` | `string` | | 响应消息 | - ---- - -## 数据清理 - -### `POST` /admin/monitor/data-retention/cleanup - -**手动触发数据清理** - -仅超级管理员可操作。按数据保留策略清理过期日志（操作日志/错误日志/通知日志等），返回各类型清理的记录数 - -**响应** `统一响应结果«Map«string,int»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## 服务监控 - -### `GET` /admin/monitor/services - -**微服务列表和健康状态** - -从Nacos注册中心获取所有微服务的实例列表和健康状态，包含IP、端口、注册时间和健康检查结果 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## 消息通知日志 - -### `GET` /admin/monitor/notification-logs - -**消息通知日志分页查询** - -查询各渠道（短信/站内信/企微/公众号）的通知发送记录，支持按通知类型、用户、发送状态筛选 - -**关联字典**： -- notification_send_status：发送状态（列表筛选+显示，0=待发送/1=成功/2=失败） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `endTime` | `string` | | 结束时间 | | -| `notificationType` | `string` | | 通知类型 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `sendStatus` | `integer(int32)` | | 发送状态 | | -| `startTime` | `string` | | 开始时间 | | -| `userName` | `string` | | 用户名 | | - -**响应** `统一响应结果«分页结果«通知日志»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«通知日志»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `通知日志[]` | | 数据列表 | -|     `createdAt` | `string` | | 创建时间 | -|     `externalUserId` | `string` | | 外部联系人ID | -|     `externalUserName` | `string` | | 外部联系人姓名 | -|     `failReason` | `string` | | 失败原因 | -|     `messageContent` | `string` | | 消息内容 | -|     `notificationLogId` | `long` | | 通知日志ID | -|     `notificationType` | `string` | | 通知类型: ADD_EXTERNAL_CONTACT/DEL_FOLLOW_USER/DEL_EXTERNAL_CONTACT | -|     `sendStatus` | `int` | | 发送状态: 0-成功, 1-失败, 2-已过滤 | -|     `serviceName` | `string` | | 来源服务名称 | -|     `userId` | `string` | | 员工企微UserID | -|     `userName` | `string` | | 员工姓名 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/notification-logs/{id} - -**消息通知日志详情** - -返回单条通知发送日志的完整信息，包含通知类型、接收用户、发送渠道、发送状态、失败原因（如有）、消息内容等。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 日志ID | - -**响应** `统一响应结果«通知日志»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `通知日志` | | 响应数据 | -|   `createdAt` | `string` | | 创建时间 | -|   `externalUserId` | `string` | | 外部联系人ID | -|   `externalUserName` | `string` | | 外部联系人姓名 | -|   `failReason` | `string` | | 失败原因 | -|   `messageContent` | `string` | | 消息内容 | -|   `notificationLogId` | `long` | | 通知日志ID | -|   `notificationType` | `string` | | 通知类型: ADD_EXTERNAL_CONTACT/DEL_FOLLOW_USER/DEL_EXTERNAL_CONTACT | -|   `sendStatus` | `int` | | 发送状态: 0-成功, 1-失败, 2-已过滤 | -|   `serviceName` | `string` | | 来源服务名称 | -|   `userId` | `string` | | 员工企微UserID | -|   `userName` | `string` | | 员工姓名 | -| `message` | `string` | | 响应消息 | - ---- - -## 登录日志 - -### `GET` /admin/monitor/login-logs - -**登录日志分页查询** - -查询管理员登录记录（代理到user-service），包含登录IP、设备信息、登录方式和登录结果 - -**关联字典**： -- login_status：登录状态（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `adminId` | `integer(int64)` | | 管理员ID | | -| `endTime` | `string` | | 结束时间 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `startTime` | `string` | | 开始时间 | | -| `status` | `string` | | 状态 | | - -**响应** `统一响应结果«object»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## 错误日志 - -### `GET` /admin/monitor/error-logs - -**错误日志分页查询** - -查询各微服务的异常记录，支持按服务名称、异常类名、时间范围筛选。堆栈信息仅保留com.hulalv包内的调用帧 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `endTime` | `string` | | 结束时间 | | -| `exceptionClass` | `string` | | 异常类名 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `serviceName` | `string` | | 服务名称 | | -| `startTime` | `string` | | 开始时间 | | - -**响应** `统一响应结果«分页结果«错误日志»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«错误日志»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `错误日志[]` | | 数据列表 | -|     `adminId` | `long` | | 管理员ID | -|     `createdAt` | `string` | | 创建时间 | -|     `errorLogId` | `long` | | 错误日志ID | -|     `exceptionClass` | `string` | | 异常类名 | -|     `exceptionMessage` | `string` | | 异常消息 | -|     `ipAddress` | `string` | | IP地址 | -|     `requestMethod` | `string` | | 请求方法 | -|     `requestParams` | `string` | | 请求参数(JSON) | -|     `requestUrl` | `string` | | 请求URL | -|     `serviceName` | `string` | | 服务名称 | -|     `stackTrace` | `string` | | 堆栈跟踪 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/monitor/error-logs/{id} - -**错误日志详情** - -返回单条错误日志的完整信息，包含异常类名、错误消息、过滤后的堆栈信息（仅com.hulalv包内调用帧）、请求URL、请求参数等。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 日志ID | - -**响应** `统一响应结果«错误日志»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `错误日志` | | 响应数据 | -|   `adminId` | `long` | | 管理员ID | -|   `createdAt` | `string` | | 创建时间 | -|   `errorLogId` | `long` | | 错误日志ID | -|   `exceptionClass` | `string` | | 异常类名 | -|   `exceptionMessage` | `string` | | 异常消息 | -|   `ipAddress` | `string` | | IP地址 | -|   `requestMethod` | `string` | | 请求方法 | -|   `requestParams` | `string` | | 请求参数(JSON) | -|   `requestUrl` | `string` | | 请求URL | -|   `serviceName` | `string` | | 服务名称 | -|   `stackTrace` | `string` | | 堆栈跟踪 | -| `message` | `string` | | 响应消息 | - ---- diff --git a/2026-03/17_1012/hl-mp-service.md b/2026-03/17_1012/hl-mp-service.md deleted file mode 100644 index 720fbe0..0000000 --- a/2026-03/17_1012/hl-mp-service.md +++ /dev/null @@ -1,3634 +0,0 @@ -# 小程序聚合服务 API 文档 - -**服务**: `hl-mp-service` -**接口总数**: 132 - -## 目录 - -- **C端 - 产品接口** (8 个接口) -- **C端 - 公共接口** (6 个接口) -- **C端 - 出行人接口** (6 个接口) -- **C端 - 前端配置接口** (2 个接口) -- **C端 - 发票接口** (4 个接口) -- **C端 - 合同接口** (5 个接口) -- **C端 - 天气接口** (3 个接口) -- **C端 - 字典接口** (1 个接口) -- **C端 - 定制师接口** (5 个接口) -- **C端 - 徽章接口** (1 个接口) -- **C端 - 心愿单接口** (2 个接口) -- **C端 - 探索接口** (5 个接口) -- **C端 - 搜索接口** (1 个接口) -- **C端 - 支付接口** (3 个接口) -- **C端 - 收藏接口** (6 个接口) -- **C端 - 攻略接口** (4 个接口) -- **C端 - 景区接口** (3 个接口) -- **C端 - 活动接口** (2 个接口) -- **C端 - 消息接口** (5 个接口) -- **C端 - 用户接口** (8 个接口) -- **C端 - 相册接口** (4 个接口) -- **C端 - 行程接口** (4 个接口) -- **C端 - 订单接口** (11 个接口) -- **C端 - 评价接口** (13 个接口) -- **C端 - 足迹接口** (4 个接口) -- **C端 - 轮播图接口** (1 个接口) -- **C端 - 退款接口** (7 个接口) -- **C端 - 通用点赞** (3 个接口) -- **C端 - 酒店接口** (2 个接口) -- **C端 - 餐厅接口** (2 个接口) -- **C端 - 首页接口** (1 个接口) - ---- - -## C端 - 产品接口 - -### `GET` /mp/product/batch/{batchId}/combos - -**GROUP批次套餐列表** - -返回指定批次的所有套餐（名称、人数组合、价格、库存） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `batchId` | `integer` | | 批次ID | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/product/lines - -**产品线列表** - -返回所有已启用的产品线，用于小程序首页或筛选栏展示 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/product/list - -**产品列表** - -分页查询已上架产品，支持按关键词、产品类型(CORE/ROUTE/CUSTOM/GROUP)、季节、天数、目的地、产品线筛选和排序 - -**关联字典（BFF透传）**： -- product_type：产品类型（列表筛选+显示） -- product_status：产品状态（透传自product-service） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `destination` | `string` | | 目的地 | | -| `keyword` | `string` | | 搜索关键词 | | -| `lineId` | `string` | | 产品线ID | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `productType` | `string` | | 产品类型：CORE/ROUTE/CUSTOM/GROUP | | -| `season` | `string` | | 季节 | | -| `sortBy` | `string` | | 排序字段 | | -| `sortDir` | `string` | | 排序方向 | | -| `tripDays` | `integer(int32)` | | 天数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/product/{productId} - -**产品详情（聚合收藏状态）** - -聚合流程：获取产品详情 → 并行查询收藏状态 → 异步记录足迹 → 返回聚合数据。支持未登录访问（不返回收藏状态） - -**关联字典（BFF透传）**： -- product_type：产品类型（显示） -- product_status：产品状态（透传自product-service） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `productId` | `integer` | | 产品ID | - -**响应** `统一响应结果«C端产品详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `C端产品详情` | | 响应数据 | -|   `chatMessages` | `Map«string,object»[]` | | 群聊最近消息（来自会话存档） | -|   `earliestBookingDate` | `string` | | 最早可订日期(如 2026-07-15) | -|   `earlyBirdDiscount` | `number` | | 早鸟优惠金额(元/人) | -|   `earlyBirdPlanName` | `string` | | 早鸟计划名称 | -|   `isFavorited` | `boolean` | | 是否已收藏（null表示未登录） | -|   `participantFamilyCount` | `int` | | 参与家庭数 | -|   `product` | `object` | | 产品详情（来自product-service） | -|   `reviewStats` | `object` | | 评价统计数据 | -|   `topLikedReview` | `object` | | 最高点赞评价 | -|   `topRatedReview` | `object` | | 最高评分评价 | -|   `totalSold` | `int` | | 已购人数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/product/{productId}/batch-calendar - -**GROUP批次日历** - -返回可报名批次列表（出发日期、剩余名额等），仅ENROLLING和CONFIRMED状态 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `productId` | `integer` | | 产品ID | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/product/{productId}/group-quote - -**GROUP报价** - -返回指定批次的各套餐报价（totalSellPrice） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `productId` | `integer` | | 产品ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `batchId` | `integer(int64)` | | 批次ID | | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/product/{productId}/price-calendar - -**价格日历** - -返回产品指定日期范围内的每日价格，用于日历组件展示。不传日期时默认返回未来一个月 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `productId` | `integer` | | 产品ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `endDate` | `string` | | 结束日期 | | -| `startDate` | `string` | | 开始日期 | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/product/{productId}/quote - -**报价计算（含早鸟优惠）** - -报价流程：传入出发日期+人数 → 价格日历计算基础报价（与下单一致） → 匹配早鸟优惠方案 → 返回明细报价+优惠信息。 - -支付方式说明： -- FULL: 全额支付，需一次性付清全部金额 -- DEPOSIT: 定金+尾款，先付定金（比例由产品配置），出行前补齐尾款 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `productId` | `integer` | | 产品ID | - -**请求体** `产品报价请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `adultCount` | `int` | 是 | 成人数量 | -| `babyCount` | `int` | | 婴儿数量 | -| `childCount` | `int` | | 儿童数量 | -| `childNeedBed` | `boolean` | | 儿童是否需要床位 | -| `departureDate` | `string` | 是 | 出发日期 | -| `youngChildCount` | `int` | | 幼儿数量 | - -**响应** `统一响应结果«产品报价结果»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `产品报价结果` | | 响应数据 | -|   `adultSellPrice` | `number` | | 成人单价 | -|   `babySellPrice` | `number` | | 幼童单价（固定价） | -|   `childSellPrice` | `number` | | 儿童单价 | -|   `childWithBedFee` | `number` | | 儿童加床费 | -|   `depositPayment` | `定金支付选项` | | 定金支付信息（仅paymentMode=DEPOSIT时有值） | -|     `balanceAmount` | `number` | | 尾款金额（出行前需付） | -|     `depositAmount` | `number` | | 定金金额（首次需付） | -|     `depositRatio` | `int` | | 定金比例(%) | -|     `description` | `string` | | 说明 | -|   `earlyBirdDiscount` | `早鸟优惠信息` | | 早鸟优惠信息，无优惠时为null | -|     `discountAmount` | `number` | | 优惠金额 | -|     `minPeople` | `int` | | 最低人数要求 | -|     `planId` | `long` | | 优惠方案ID | -|     `planName` | `string` | | 优惠方案名称 | -|   `finalPrice` | `number` | | 最终价（早鸟优惠后） | -|   `fullPayment` | `全额支付选项` | | 全额支付信息 | -|     `amount` | `number` | | 应付金额 | -|     `description` | `string` | | 说明 | -|   `grandTotalSellPrice` | `number` | | 总售价（优惠前） | -|   `paymentMode` | `string` | | 支付方式: FULL(全额支付) / DEPOSIT(定金+尾款) | -|   `totalAdultSellPrice` | `number` | | 成人小计 | -|   `totalBabySellPrice` | `number` | | 幼童小计 | -|   `totalChildSellPrice` | `number` | | 儿童小计 | -|   `totalYoungChildSellPrice` | `number` | | 小童小计 | -|   `youngChildSellPrice` | `number` | | 小童单价（儿童价×折扣比例） | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 公共接口 - -### `GET` /mp/common/agreement/list - -**协议列表** - -获取所有已上线的协议列表（不含内容，仅含类型、标题、版本） - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/common/agreement/{type} - -**获取协议文本** - -获取指定类型的协议文本（如隐私政策、用户协议），返回富文本内容 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `type` | `string` | 是 | 协议类型: privacy(隐私政策) / user(用户协议) | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/common/config - -**应用配置** - -获取应用全局配置信息 - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/common/contact - -**联系方式列表** - -获取有效的联系方式列表（电话/微信/邮箱等） - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/common/faq - -**FAQ列表** - -获取常见问题列表（按分类分组） - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/common/feedback - -**提交反馈** - -提交用户反馈，支持文字内容和图片附件 - -**请求体** `提交反馈请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `contact` | `string` | | 联系方式 | -| `content` | `string` | 是 | 反馈内容 | -| `images` | `string[]` | | 图片URL列表 | - -**响应** `统一响应结果«Void»` - ---- - -## C端 - 出行人接口 - -### `GET` /mp/user/traveler - -**出行人列表** - -返回当前用户的所有出行人列表。如果用户已完善实名信息，列表中会自动包含一条「本人」虚拟记录(travelerId=0) - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/user/traveler - -**添加出行人** - -添加常用出行人信息（姓名/证件/联系方式等），下单时可快速选择。单个用户最多50个出行人 - -**请求体** `修改)` - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/user/traveler/{id} - -**出行人详情** - -获取单个出行人的完整信息（姓名、证件信息、联系方式等）。 - -**权限**：需登录，仅能查看自己的出行人。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 出行人ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /mp/user/traveler/{id} - -**更新出行人** - -修改出行人信息，支持部分更新（只传需要修改的字段）。已关联订单的出行人修改不影响历史订单记录。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 出行人ID | - -**请求体** `修改)` - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /mp/user/traveler/{id} - -**删除出行人** - -删除常用出行人记录。默认出行人不可删除，需先取消默认后再删除。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 出行人ID | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /mp/user/traveler/{id}/default - -**设为默认出行人** - -设为默认出行人后，下单时自动作为第一个出行人。每个用户只能有一个默认出行人 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 出行人ID | - -**响应** `统一响应结果«Void»` - ---- - -## C端 - 前端配置接口 - -### `GET` /mp/config - -**获取所有非敏感前端配置** - -返回所有非SECRET类型的前端配置项（如主题色、客服电话、版本号等）。不含敏感配置，可安全传输给小程序端。 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/config/group/{group} - -**按分组获取非敏感前端配置** - -按配置分组获取前端配置项，如UI分组、功能开关分组等。用于小程序按需加载特定分组的配置。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `group` | `string` | | 配置分组 | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 发票接口 - -### `POST` /mp/invoice/apply - -**申请开票** - -开票流程：订单完成后 → 填写发票信息(抬头/税号/类型) → 提交开票申请 → 管理员处理 → 发送电子发票 - -**请求体** `发票申请请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `email` | `string` | | 接收邮箱 | -| `invoiceTitle` | `string` | 是 | 发票抬头 | -| `invoiceType` | `string` | 是 | 发票类型: PERSONAL(个人)/COMPANY(企业) | -| `orderId` | `string` | 是 | 订单ID | -| `taxpayerId` | `string` | | 纳税人识别号（企业发票必填） | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/invoice/order/{orderId} - -**通过订单ID查询发票** - -查询指定订单的发票信息，如果订单未开票则返回null - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/invoice/{id} - -**发票详情** - -获取发票的完整信息，包含开票状态、发票抬头、税号、金额、电子发票文件链接等 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 发票ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/invoice/{invoiceId}/reissue - -**发票换开** - -对已开发票申请换开（修改抬头/税号等），原发票作废后重新开具新发票 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `invoiceId` | `integer` | | 发票ID | - -**请求体** `发票换开请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `email` | `string` | | 接收邮箱 | -| `invoiceTitle` | `string` | 是 | 发票抬头 | -| `taxNumber` | `string` | | 纳税人识别号（企业发票必填） | -| `titleType` | `string` | 是 | 抬头类型: PERSONAL(个人)/COMPANY(企业) | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 合同接口 - -### `GET` /mp/contract/by-order/{orderId} - -**按订单查合同** - -返回订单关联的最新有效合同（非作废） - -**关联字典（BFF透传）**： -- contract_status：合同状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/contract/by-order/{orderId}/all - -**按订单查所有合同** - -返回订单关联的所有有效合同（TOUR+INSURANCE各一条） - -**关联字典（BFF透传）**： -- contract_status：合同状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/contract/list - -**合同列表** - -**关联字典（BFF透传）**： -- contract_status：合同状态（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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` | | 响应消息 | - ---- - -### `POST` /mp/contract/{contractId}/resend-sms - -**重新发送合同签署短信** - -重新向出行人发送合同签署短信通知，适用于出行人未收到短信或短信过期的场景。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `contractId` | `integer` | | 合同ID | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/contract/{id} - -**合同详情** - -返回合同基本信息、签署状态、出行人签署详情及合同文件下载链接 - -**关联字典（BFF透传）**： -- contract_status：合同状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 合同ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 天气接口 - -### `GET` /mp/weather/forecast - -**获取指定城市天气预报** - -通过高德天气API查询指定城市未来3天的天气预报信息 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `city` | `string` | | 城市名称 | | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/weather/itinerary/{orderId} - -**获取订单行程天气** - -根据订单行程中的目的地城市，批量查询每日天气信息，用于行程详情页展示 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/weather/live - -**获取指定城市实况天气** - -通过高德天气API查询指定城市的实时天气（温度、湿度、风向等） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `city` | `string` | | 城市名称 | | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 字典接口 - -### `GET` /dict/all - -**获取所有字典数据** - -获取系统全部字典数据（按字典类型分组），用于小程序端的下拉选项、枚举映射等。建议前端缓存此数据 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 定制师接口 - -### `GET` /mp/designer - -**定制师列表(含真实产品数和评分，综合排序)** - -获取定制师列表，聚合层会补充每个定制师的真实产品数量和评价评分。按综合排序（评分>路线数>咨询人数），用于小程序定制师推荐页。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `limit` | `integer(int32)` | | 每页条数 | | -| `page` | `integer(int32)` | | 页码 | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/designer/featured - -**推荐定制师(综合排序第一名)** - -获取综合排序排名第一的定制师信息（含产品数和评分），用于首页推荐定制师卡片展示。 - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/designer/{id} - -**定制师详情(含产品数量和评分)** - -获取定制师完整个人信息，聚合层会补充该定制师的已发布产品数量和综合评分，用于定制师个人主页展示。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 定制师ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/designer/{id}/products - -**定制师已发布产品列表** - -**关联字典（BFF透传）**： -- product_type：产品类型（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 定制师ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/designer/{id}/reviews - -**定制师产品评价列表** - -**关联字典（BFF透传）**： -- rating_level：评价等级（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 定制师ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 徽章接口 - -### `GET` /mp/badge - -**获取徽章数据** - -返回用户的徽章统计（未读消息数、待办事项数等），用于「我的」页面角标展示 - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 心愿单接口 - -### `GET` /mp/wish - -**心愿单列表** - -返回当前用户的心愿单列表，按创建时间倒序排列 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/wish - -**创建心愿** - -创建旅行心愿，描述想去的地方和时间偏好，定制师可据此推荐产品 - -**请求体** `创建心愿单请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `notes` | `string` | | 备注 | -| `productId` | `string` | 是 | 产品ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 探索接口 - -### `GET` /mp/explore/list - -**探索列表** - -获取已启用的探索分类列表（图文攻略内容），支持综合/最新/最热排序，分页返回。用于小程序探索频道首页瀑布流展示。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `sortType` | `string` | | 排序方式：comprehensive/newest/hottest | | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/explore/{id} - -**探索详情** - -自动增加浏览量，已登录时返回点赞/收藏状态 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 探索分类ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/explore/{id}/favorite - -**切换收藏** - -对探索内容收藏/取消收藏，返回当前收藏状态（true=已收藏）。收藏后可在'我的收藏'中查看。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 探索分类ID | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/explore/{id}/like - -**切换点赞** - -对探索内容点赞/取消点赞，返回当前点赞状态（true=已点赞）。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 探索分类ID | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/explore/{id}/view - -**浏览+1** - -增加探索内容的浏览计数。前端进入探索详情页时调用，无需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 探索分类ID | - -**响应** `统一响应结果«Void»` - ---- - -## C端 - 搜索接口 - -### `GET` /mp/search - -**搜索产品** - -按关键词搜索已上架产品（匹配产品名称和描述），支持按产品类型进一步筛选 - -**关联字典（BFF透传）**： -- product_type：产品类型（筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `keyword` | `string` | | 搜索关键词 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `productType` | `string` | | 产品类型：CORE/ROUTE/CUSTOM/GROUP | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 支付接口 - -### `POST` /mp/payment/prepay - -**发起支付** - -支付流程：选择支付方式(JSAPI/H5) → 调用微信支付API → 返回支付参数 → 前端调起微信支付 - -**关联字典（BFF透传）**： -- payment_status：支付状态（返回字段） - -**请求体** `支付预下单请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `clientIp` | `string` | | 客户端IP（H5支付必填） | -| `orderId` | `string` | 是 | 订单ID | -| `tradeType` | `string` | 是 | 支付方式: JSAPI(小程序支付)/H5(H5支付) | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/payment/status/{orderId} - -**查询支付状态** - -**关联字典（BFF透传）**： -- payment_status：支付状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/payment/transactions/{orderId} - -**订单交易记录列表** - -**关联字典（BFF透传）**： -- payment_status：支付状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 收藏接口 - -### `GET` /mp/user/favorite - -**收藏列表（含资源摘要）** - -分页查询收藏列表，聚合层会补充每个收藏项对应资源的摘要信息（名称、封面图、价格等）。支持按目标类型筛选。 - -**权限**：需登录。 - -**关联字典**： -- favorite_resource_type：收藏资源类型（PRODUCT/SCENIC/RESTAURANT/ACTIVITY） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `targetType` | `string` | | 目标类型筛选（字典：favorite_resource_type）：PRODUCT/SCENIC/RESTAURANT/ACTIVITY | | - -**响应** `统一响应结果«分页结果«收藏列表项（含资源摘要）»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«收藏列表项（含资源摘要）»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `收藏列表项（含资源摘要）[]` | | 数据列表 | -|     `coverUrl` | `string` | | 封面图URL | -|     `createdAt` | `string` | | 收藏时间 | -|     `favoriteId` | `string` | | 收藏记录ID | -|     `name` | `string` | | 资源名称 | -|     `tags` | `string[]` | | 标签列表 | -|     `targetId` | `string` | | 目标资源ID | -|     `targetType` | `string` | | 目标类型（字典：favorite_resource_type） | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/user/favorite - -**添加收藏** - -将产品/景区/餐厅/活动加入收藏。同一目标重复收藏会返回已有收藏记录 - -**请求体** `收藏请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `targetId` | `string` | 是 | 目标资源ID | -| `targetType` | `string` | 是 | 目标类型（字典：favorite_resource_type） | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /mp/user/favorite/batch - -**批量删除收藏** - -批量删除多条收藏记录，传入收藏记录ID列表。用于收藏管理页面的批量操作。 - -**权限**：需登录，仅能删除自己的收藏。 - -**请求体** `long[]` - -**响应** `统一响应结果«Void»` - ---- - -### `DELETE` /mp/user/favorite/by-target - -**按目标取消收藏** - -通过目标类型+目标ID取消收藏，适用于详情页点击取消收藏的场景（不需要知道收藏记录ID）。 - -**权限**：需登录。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `targetId` | `integer(int64)` | | 目标资源ID | | -| `targetType` | `string` | | 目标类型 | | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /mp/user/favorite/check - -**检查是否已收藏** - -检查当前用户是否已收藏指定资源，用于详情页收藏按钮状态显示。 - -**权限**：需登录。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `targetId` | `integer(int64)` | | 目标资源ID | | -| `targetType` | `string` | | 目标类型（字典：favorite_resource_type） | | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /mp/user/favorite/{id} - -**取消收藏** - -通过收藏记录ID取消收藏，适用于收藏列表页的删除操作。 - -**权限**：需登录，仅能删除自己的收藏。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 收藏记录ID | - -**响应** `统一响应结果«Void»` - ---- - -## C端 - 攻略接口 - -### `GET` /mp/wiki/article/{articleId} - -**文章详情** - -**关联字典（BFF透传）**： -- wiki_status：文章状态（返回字段） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `articleId` | `integer` | | 文章ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/wiki/categories - -**攻略分类列表** - -获取所有已启用的攻略分类，按排序值排列。用于小程序攻略频道的分类导航展示。 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/wiki/category/{categoryId}/articles - -**分类文章列表** - -分页查询指定攻略分类下已发布的文章列表，按发布时间倒序排列。用于攻略分类详情页。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `categoryId` | `integer` | | 攻略分类ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/wiki/recommend-articles - -**推荐文章列表** - -获取编辑推荐的攻略文章列表（按推荐权重排序），用于首页或攻略频道的推荐位展示。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `limit` | `integer(int32)` | | 返回条数 | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 景区接口 - -### `GET` /mp/scenic/list - -**景区列表** - -分页查询已上架的景区列表，支持按关键词和城市筛选。聚合层透传resource-service的景区数据。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `city` | `string` | | 城市 | | -| `keyword` | `string` | | 关键词 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/scenic/{scenicId} - -**景区详情** - -获取景区完整信息（含季节素材、图文详情、价格等），自动注入静态地图图片URL用于详情页地图展示。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `scenicId` | `integer` | | 景区ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/scenic/{scenicId}/nearby - -**附近景区（地理+探索分类聚合）** - -聚合两个数据源：1.基于经纬度的地理位置附近景区（resource-service）；2.探索分类关联的景区（user-service）。去重合并后返回，用于景区详情页底部'附近推荐'展示。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `scenicId` | `integer` | | 景区ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `limit` | `integer(int32)` | | 返回条数 | | -| `radius` | `number(double)` | | 搜索半径(km) | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 活动接口 - -### `GET` /mp/activity/list - -**活动列表** - -分页查询已上架的活动列表，支持关键词和分类筛选。聚合层透传resource-service的活动数据给小程序前端。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `categoryCode` | `string` | | 分类 | | -| `keyword` | `string` | | 关键词 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/activity/{activityId} - -**活动详情** - -获取活动完整信息（含图文详情、价格等），自动注入静态地图图片URL用于详情页地图展示。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `activityId` | `integer` | | 活动ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 消息接口 - -### `GET` /mp/message/list - -**消息列表** - -消息列表，支持按分类筛选，按时间倒序分页返回 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `category` | `string` | | 消息分类筛选，不传返回全部 | | -| `page` | `integer(int32)` | | 页码，默认1 | | -| `pageSize` | `integer(int32)` | | 每页条数，默认20 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /mp/message/read-all - -**全部标记已读** - -将指定分类或全部消息标记为已读，不传category则全部已读 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `category` | `string` | | 消息分类，不传则将所有分类标记为已读 | | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /mp/message/summary - -**消息摘要** - -获取各分类的未读数量和最新一条消息，用于消息中心首页展示 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /mp/message/{id} - -**删除消息** - -删除单条消息 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | 是 | 消息ID | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /mp/message/{id}/read - -**标记已读** - -标记单条消息为已读 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | 是 | 消息ID | - -**响应** `统一响应结果«Void»` - ---- - -## C端 - 用户接口 - -### `DELETE` /mp/user/account - -**注销账号** - -注销后用户数据将被软删除，30天内可联系客服恢复 - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /mp/user/login - -**微信登录** - -登录流程：小程序wx.login获取code → 后端换取openid → 查找/创建用户 → 返回JWT令牌+needProfile标记 - -**请求体** `微信登录请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `string` | 是 | 微信授权code | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/user/login/sms - -**短信登录** - -登录流程：获取验证码 → 验证手机号+验证码 → 查找/创建用户 → 返回JWT令牌 - -**请求体** `短信验证码登录请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `string` | 是 | 验证码 | -| `phone` | `string` | 是 | 手机号 | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/user/logout - -**用户登出** - -清除用户登录状态和服务端缓存的令牌信息。登出后需重新登录获取新令牌。 - -**权限**：需登录。 - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /mp/user/ocr/idcard - -**身份证OCR识别** - -将身份证图片上传到OSS后，传入ossUrl进行OCR识别。返回姓名、身份证号、性别、民族等结构化数据，可用于自动填充出行人信息 - -**请求体** `身份证OCR识别请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `imgUrl` | `string` | 是 | 身份证图片的OSS地址 | - -**响应** `统一响应结果«Map«string,string»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/user/profile - -**获取用户信息** - -获取当前登录用户的个人资料，包含头像、昵称、手机号、实名信息等 - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /mp/user/profile - -**更新用户信息** - -更新当前用户的个人资料，支持部分更新（只传需要修改的字段）。首次完善资料时realName为必填 - -**请求体** `更新个人资料请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `avatar` | `string` | | 头像URL | -| `birthday` | `string` | | 生日 | -| `email` | `string` | | 邮箱 | -| `gender` | `int` | | 性别: 1=男, 2=女 | -| `nationality` | `string` | | 国籍 | -| `nickname` | `string` | | 昵称 | -| `phone` | `string` | | 手机号 | -| `realName` | `string` | | 真实姓名 | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/user/sms/send - -**发送短信验证码** - -向指定手机号发送登录验证码，有效期5分钟，60秒内不可重复发送 - -**请求体** `发送短信验证码请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `phone` | `string` | 是 | 手机号 | - -**响应** `统一响应结果«Void»` - ---- - -## C端 - 相册接口 - -### `GET` /mp/album/file/{albumFileId}/download-url - -**获取文件下载链接** - -获取文件的预签名下载URL，有效期有限 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `albumFileId` | `integer` | 是 | 相册文件ID | - -**响应** `统一响应结果«string»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `string` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/album/folder/{folderId}/files - -**文件夹下的文件列表** - -获取文件夹下的文件列表（分页），含图片和视频 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `folderId` | `integer` | 是 | 文件夹ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码，默认1 | | -| `size` | `integer(int32)` | | 每页数量，默认20 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/album/order/{orderId}/folders - -**订单的文件夹列表** - -获取订单下的相册文件夹列表 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | 是 | 订单ID | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/album/orders - -**有相册的订单列表** - -获取当前登录用户有相册的订单列表 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 行程接口 - -### `GET` /mp/trip/list - -**行程列表** - -获取当前登录用户的行程列表（已确认及进行中的订单对应的行程） - -**关联字典（BFF透传）**： -- order_status：订单/行程状态（显示） - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/trip/today - -**今日行程** - -获取今日行程（如果有正在进行中的行程），无行程时data为null - -**关联字典（BFF透传）**： -- order_status：订单/行程状态（显示） - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/trip/weather - -**天气查询** - -高德天气API代理，传入城市名称返回实时天气信息 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `city` | `string` | 是 | 城市名称，如「成都」「拉萨」 | | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/trip/{orderId} - -**行程详情** - -获取订单对应的行程详情，含每日行程节点信息（景点/酒店/餐厅等） - -**关联字典（BFF透传）**： -- order_status：订单/行程状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | 是 | 订单ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 订单接口 - -### `POST` /mp/order/bind-by-contact - -**绑定未绑定的订单** - -绑定流程：用户登录 → 完善个人资料 → 自动通过联系人手机号+姓名匹配 → 将userId=NULL的订单绑定到当前用户 - -**请求体** `通过联系人信息绑定订单请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `contactName` | `string` | 是 | 联系人姓名 | -| `contactPhone` | `string` | 是 | 联系人手机号 | - -**响应** `统一响应结果«int»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `int` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/count - -**各状态订单数量** - -统计当前用户各状态的订单数量，用于「我的」页面的订单状态角标展示 - -**关联字典（BFF透传）**： -- order_status：订单状态（状态分类统计） - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/order/create - -**创建订单** - -下单流程：选择产品 → 填写联系人/出行人信息 → 报价计算 → 创建订单 → 返回订单ID - -**请求体** `C端创建订单请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `adultCount` | `int` | | 成人数 | -| `babyCount` | `int` | | 幼童数 | -| `childCount` | `int` | | 儿童数 | -| `childNeedBed` | `boolean` | | 儿童是否需要床位 | -| `contactName` | `string` | 是 | 联系人姓名 | -| `contactPhone` | `string` | 是 | 联系人电话 | -| `customizerId` | `string` | | 定制师ID(通过分享链接下单时传入) | -| `departureDate` | `string` | | 出发日期(GROUP产品从团期获取，可不传) | -| `groupBatchId` | `string` | | 团期ID(GROUP产品必填) | -| `productId` | `string` | 是 | 产品ID | -| `remark` | `string` | | 备注 | -| `roomCount` | `int` | | 房间数(GROUP产品，默认1) | -| `sharerOpenid` | `string` | | 分享人微信openid（通过分享进入下单时传入，用于记录分享关系） | -| `travelers` | `出行人信息[]` | | 出行人列表 | -|   `birthday` | `string` | | 出生日期 | -|   `email` | `string` | | 电子邮箱 | -|   `emergencyContact` | `string` | | 紧急联系人 | -|   `emergencyPhone` | `string` | | 紧急联系电话 | -|   `gender` | `int` | | 性别（1=男, 2=女） | -|   `idCardNo` | `string` | | 证件号码 | -|   `idCardType` | `string` | | 证件类型 | -|   `name` | `string` | 是 | 出行人姓名 | -|   `nationality` | `string` | | 国籍 | -|   `phone` | `string` | | 手机号 | -|   `travelerType` | `string` | | 出行人类型（ADULT/CHILD/YOUNG_CHILD/BABY） | -| `youngChildCount` | `int` | | 小童数 | - -**响应** `统一响应结果«订单详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `订单详情` | | 响应数据 | -|   `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` | `Map«string,object»[]` | | 优惠列表 | -|   `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` | | 支付模式（FULL/DEPOSIT） | -|   `processStatus` | `string` | | 内部流程状态 | -|   `processStatusLabel` | `string` | | 内部流程状态标签 | -|   `productCoverUrl` | `string` | | 产品封面图URL | -|   `productId` | `long` | | 产品ID | -|   `productName` | `string` | | 产品名称 | -|   `productSnapshot` | `string` | | 产品快照JSON | -|   `productType` | `string` | | 产品类型（CORE/ROUTE/CUSTOM/GROUP） | -|   `readyAt` | `string` | | 就绪时间 | -|   `refundAmount` | `number` | | 退款金额 | -|   `remark` | `string` | | 备注 | -|   `returnDate` | `string` | | 返程日期（出发日期 + 行程天数 - 1） | -|   `reviewed` | `boolean` | | 是否已评价 | -|   `roomInfo` | `string` | | 房间信息 | -|   `status` | `string` | | 订单状态（PENDING_PAY/DEPOSIT_PAID/PAID/CONFIRMED/IN_PROGRESS/COMPLETED/CANCELLED） | -|   `statusLabel` | `string` | | 订单状态标签 | -|   `timeline` | `Map«string,object»[]` | | 时间线列表 | -|   `todos` | `Map«string,object»[]` | | 待办列表 | -|   `totalPrice` | `number` | | 总售价 | -|   `travelers` | `Map«string,object»[]` | | 出行人列表 | -|   `tripDays` | `int` | | 行程天数 | -|   `tripNights` | `int` | | 行程晚数 | -|   `unlockRequestedAt` | `string` | | 解锁请求时间 | -|   `userId` | `long` | | 用户ID | -|   `vehicleInfo` | `string` | | 车辆信息 | -|   `youngChildCount` | `int` | | 小童数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/list - -**订单列表** - -分页查询当前用户的订单列表，支持按状态筛选。返回订单摘要信息（不含详细出行人信息） - -**关联字典（BFF透传）**： -- order_status：订单状态（列表筛选+显示） -- product_type：产品类型（订单卡片显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `status` | `string` | | 状态 | | - -**响应** `统一响应结果«分页结果«订单列表项»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«订单列表项»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `订单列表项[]` | | 数据列表 | -|     `adultCount` | `int` | | 成人数 | -|     `babyCount` | `int` | | 幼童数 | -|     `balanceAmount` | `number` | | 尾款金额 | -|     `childCount` | `int` | | 儿童数 | -|     `contracts` | `Map«string,object»[]` | | 合同列表（含signUrl/fileUrl/status等） | -|     `createTime` | `string` | | 创建时间 | -|     `daysUntilDeparture` | `int` | | 距出发天数（负数表示已出发） | -|     `departureDate` | `string` | | 出发日期 | -|     `depositAmount` | `number` | | 定金金额 | -|     `displayName` | `string` | | 显示名称（未支付=手机号+姓名，已支付=订单号） | -|     `displayStatus` | `string` | | C端简化状态（PENDING_PAY/PENDING_DEPARTURE/PENDING_REVIEW/REFUND/CANCELLED） | -|     `displayStatusLabel` | `string` | | C端简化状态标签 | -|     `expiryTime` | `string` | | 支付截止时间（PENDING_PAY状态有效） | -|     `insurances` | `Map«string,object»[]` | | 保险订单列表（含productName/extPolicyNo/status等） | -|     `nextAction` | `string` | | 下一步操作提示 | -|     `orderId` | `long` | | 订单ID | -|     `orderNo` | `string` | | 订单编号 | -|     `paidAmount` | `number` | | 已付金额 | -|     `paymentMode` | `string` | | 支付模式（FULL/DEPOSIT） | -|     `processStatus` | `string` | | 内部流程状态（字典：order_process_status） | -|     `processStatusLabel` | `string` | | 内部流程状态标签（字典：order_process_status 翻译） | -|     `productCoverUrl` | `string` | | 产品封面图URL | -|     `productId` | `long` | | 产品ID | -|     `productName` | `string` | | 产品名称 | -|     `productType` | `string` | | 产品类型（CORE/ROUTE/CUSTOM/GROUP） | -|     `status` | `string` | | 订单状态（PENDING_PAY/DEPOSIT_PAID/PAID/CONFIRMED/IN_PROGRESS/COMPLETED/CANCELLED） | -|     `statusLabel` | `string` | | 订单状态标签 | -|     `totalPrice` | `number` | | 总售价 | -|     `tripDays` | `int` | | 行程天数 | -|     `tripNights` | `int` | | 行程晚数 | -|     `youngChildCount` | `int` | | 小童数 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/lookup - -**通过联系人手机号+姓名查找订单（无需登录）** - -无需登录即可查询。用于管理员代下单场景：管理员创建订单后，用户通过联系人手机号+姓名查找订单并绑定到自己账号。仅返回尚未绑定用户(userId=NULL)的订单。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `contactName` | `string` | | 联系人姓名 | | -| `contactPhone` | `string` | | 联系人手机号 | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/upcoming - -**即将出发的订单** - -查询3天内即将出发的订单（状态为已确认/待出发/出行中），含合同和保险信息，按出发日期升序 - -**响应** `统一响应结果«List«订单列表项»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `订单列表项[]` | | 响应数据 | -|   `adultCount` | `int` | | 成人数 | -|   `babyCount` | `int` | | 幼童数 | -|   `balanceAmount` | `number` | | 尾款金额 | -|   `childCount` | `int` | | 儿童数 | -|   `contracts` | `Map«string,object»[]` | | 合同列表（含signUrl/fileUrl/status等） | -|   `createTime` | `string` | | 创建时间 | -|   `daysUntilDeparture` | `int` | | 距出发天数（负数表示已出发） | -|   `departureDate` | `string` | | 出发日期 | -|   `depositAmount` | `number` | | 定金金额 | -|   `displayName` | `string` | | 显示名称（未支付=手机号+姓名，已支付=订单号） | -|   `displayStatus` | `string` | | C端简化状态（PENDING_PAY/PENDING_DEPARTURE/PENDING_REVIEW/REFUND/CANCELLED） | -|   `displayStatusLabel` | `string` | | C端简化状态标签 | -|   `expiryTime` | `string` | | 支付截止时间（PENDING_PAY状态有效） | -|   `insurances` | `Map«string,object»[]` | | 保险订单列表（含productName/extPolicyNo/status等） | -|   `nextAction` | `string` | | 下一步操作提示 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `paidAmount` | `number` | | 已付金额 | -|   `paymentMode` | `string` | | 支付模式（FULL/DEPOSIT） | -|   `processStatus` | `string` | | 内部流程状态（字典：order_process_status） | -|   `processStatusLabel` | `string` | | 内部流程状态标签（字典：order_process_status 翻译） | -|   `productCoverUrl` | `string` | | 产品封面图URL | -|   `productId` | `long` | | 产品ID | -|   `productName` | `string` | | 产品名称 | -|   `productType` | `string` | | 产品类型（CORE/ROUTE/CUSTOM/GROUP） | -|   `status` | `string` | | 订单状态（PENDING_PAY/DEPOSIT_PAID/PAID/CONFIRMED/IN_PROGRESS/COMPLETED/CANCELLED） | -|   `statusLabel` | `string` | | 订单状态标签 | -|   `totalPrice` | `number` | | 总售价 | -|   `tripDays` | `int` | | 行程天数 | -|   `tripNights` | `int` | | 行程晚数 | -|   `youngChildCount` | `int` | | 小童数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/{orderId} - -**订单详情** - -获取订单完整信息，包含产品快照、出行人列表、支付信息、合同状态等 - -**关联字典（BFF透传）**： -- order_status：订单状态（显示） -- product_type：产品类型（显示） -- contract_status：合同状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«订单详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `订单详情` | | 响应数据 | -|   `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` | `Map«string,object»[]` | | 优惠列表 | -|   `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` | | 支付模式（FULL/DEPOSIT） | -|   `processStatus` | `string` | | 内部流程状态 | -|   `processStatusLabel` | `string` | | 内部流程状态标签 | -|   `productCoverUrl` | `string` | | 产品封面图URL | -|   `productId` | `long` | | 产品ID | -|   `productName` | `string` | | 产品名称 | -|   `productSnapshot` | `string` | | 产品快照JSON | -|   `productType` | `string` | | 产品类型（CORE/ROUTE/CUSTOM/GROUP） | -|   `readyAt` | `string` | | 就绪时间 | -|   `refundAmount` | `number` | | 退款金额 | -|   `remark` | `string` | | 备注 | -|   `returnDate` | `string` | | 返程日期（出发日期 + 行程天数 - 1） | -|   `reviewed` | `boolean` | | 是否已评价 | -|   `roomInfo` | `string` | | 房间信息 | -|   `status` | `string` | | 订单状态（PENDING_PAY/DEPOSIT_PAID/PAID/CONFIRMED/IN_PROGRESS/COMPLETED/CANCELLED） | -|   `statusLabel` | `string` | | 订单状态标签 | -|   `timeline` | `Map«string,object»[]` | | 时间线列表 | -|   `todos` | `Map«string,object»[]` | | 待办列表 | -|   `totalPrice` | `number` | | 总售价 | -|   `travelers` | `Map«string,object»[]` | | 出行人列表 | -|   `tripDays` | `int` | | 行程天数 | -|   `tripNights` | `int` | | 行程晚数 | -|   `unlockRequestedAt` | `string` | | 解锁请求时间 | -|   `userId` | `long` | | 用户ID | -|   `vehicleInfo` | `string` | | 车辆信息 | -|   `youngChildCount` | `int` | | 小童数 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/order/{orderId}/approve-unlock - -**同意解锁订单** - -用户同意管理员的修改请求，解除订单锁定状态，允许管理员继续修改订单 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /mp/order/{orderId}/cancel - -**取消订单** - -取消规则：仅PENDING_PAY/DEPOSIT_PAID状态可用户取消，取消后不可恢复 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**请求体** `用户取消订单请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reason` | `string` | | 取消原因 | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /mp/order/{orderId}/edit - -**修改订单** - -用户可修改出发日期和出行人。仅待支付/已付定金/已支付/已确认/待付尾款/待出发状态可修改，清单已确认的订单不允许修改。修改后重走内部流程 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**请求体** `修改订单请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `departureDate` | `string` | | 出发日期 | -| `travelers` | `出行人信息_1[]` | | 出行人列表（提供则替换全部出行人） | -|   `birthday` | `string` | | 出生日期 | -|   `email` | `string` | | 电子邮箱 | -|   `emergencyContact` | `string` | | 紧急联系人 | -|   `emergencyPhone` | `string` | | 紧急联系电话 | -|   `gender` | `int` | | 性别 | -|   `idCardNo` | `string` | | 证件号码 | -|   `idCardType` | `string` | | 证件类型 | -|   `name` | `string` | 是 | 出行人姓名 | -|   `nationality` | `string` | | 国籍 | -|   `phone` | `string` | | 手机号 | -|   `travelerType` | `string` | | 出行人类型 | - -**响应** `统一响应结果«订单详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `订单详情` | | 响应数据 | -|   `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` | `Map«string,object»[]` | | 优惠列表 | -|   `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` | | 支付模式（FULL/DEPOSIT） | -|   `processStatus` | `string` | | 内部流程状态 | -|   `processStatusLabel` | `string` | | 内部流程状态标签 | -|   `productCoverUrl` | `string` | | 产品封面图URL | -|   `productId` | `long` | | 产品ID | -|   `productName` | `string` | | 产品名称 | -|   `productSnapshot` | `string` | | 产品快照JSON | -|   `productType` | `string` | | 产品类型（CORE/ROUTE/CUSTOM/GROUP） | -|   `readyAt` | `string` | | 就绪时间 | -|   `refundAmount` | `number` | | 退款金额 | -|   `remark` | `string` | | 备注 | -|   `returnDate` | `string` | | 返程日期（出发日期 + 行程天数 - 1） | -|   `reviewed` | `boolean` | | 是否已评价 | -|   `roomInfo` | `string` | | 房间信息 | -|   `status` | `string` | | 订单状态（PENDING_PAY/DEPOSIT_PAID/PAID/CONFIRMED/IN_PROGRESS/COMPLETED/CANCELLED） | -|   `statusLabel` | `string` | | 订单状态标签 | -|   `timeline` | `Map«string,object»[]` | | 时间线列表 | -|   `todos` | `Map«string,object»[]` | | 待办列表 | -|   `totalPrice` | `number` | | 总售价 | -|   `travelers` | `Map«string,object»[]` | | 出行人列表 | -|   `tripDays` | `int` | | 行程天数 | -|   `tripNights` | `int` | | 行程晚数 | -|   `unlockRequestedAt` | `string` | | 解锁请求时间 | -|   `userId` | `long` | | 用户ID | -|   `vehicleInfo` | `string` | | 车辆信息 | -|   `youngChildCount` | `int` | | 小童数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/{orderId}/resources - -**订单资源详情（按分类）** - -解析产品快照，提取资源详情按分类返回 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«Map«string,List«Map«string,object»»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 评价接口 - -### `POST` /mp/review/create - -**创建评价** - -评价流程：订单完成后 → 查询可评价目标列表 → 对每个目标(酒店/景区/活动等)提交评价 → 自动内容审核 → 审核通过后公开展示 - -**关联字典（BFF透传）**： -- review_status：评价审核状态（返回字段） -- rating_level：评价等级（返回字段） - -**请求体** `创建评价请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `content` | `string` | 是 | 评价内容(10-500字) | -| `images` | `评价图片项[]` | | 评价图片列表（最多9张） | -|   `fileId` | `long` | | 文件ID | -|   `imageUrl` | `string` | 是 | 图片URL | -| `orderId` | `long` | 是 | 订单ID | -| `ratings` | `object` | 是 | 评分数据（key为评分类别字典的dictValue，value为1-5整数）。先调用 GET /mp/review/rating-categories 获取评分维度，required=true的必填。示例: {"ratingItinerary":5,"ratingAccommodation":4,"ratingDriver":5,"ratingDining":4,"ratingOverall":5} | -| `videos` | `评价视频项[]` | | 评价视频列表（最多3个） | -|   `coverUrl` | `string` | | 视频封面URL | -|   `duration` | `int` | | 视频时长(秒) | -|   `fileId` | `long` | | 文件ID | -|   `videoUrl` | `string` | 是 | 视频URL | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/featured - -**精选评价列表(公开)** - -无需登录，返回精选评价数组，用于评价浏览页 - -**关联字典（BFF透传）**： -- rating_level：评价等级（显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `limit` | `integer(int32)` | | 数量限制 | | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/my - -**我的评价列表** - -**关联字典（BFF透传）**： -- review_status：评价审核状态（显示） -- rating_level：评价等级（显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/order/{orderId}/reviewable-targets - -**订单可评价目标列表** - -返回订单中可评价的资源目标列表（景区/酒店/活动等），用于评价页面展示可评价项。已评价的目标不会重复出现。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/order/{orderId}/reviewed - -**检查订单是否已评价** - -检查指定订单是否已提交评价，用于订单详情页决定是否显示'去评价'按钮。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/product/{productId} - -**按产品ID查看评价列表** - -返回评价列表+统计数据，支持好中差评/有图/有视频筛选 - -**关联字典（BFF透传）**： -- rating_level：评价等级（筛选+显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `productId` | `integer` | | 产品ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `hasImage` | `boolean` | | 是否有图片 | | -| `hasVideo` | `boolean` | | 是否有视频 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `ratingLevel` | `string` | | 评价等级: GOOD/MEDIUM/BAD | | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/product/{productId}/highlights - -**产品精选评价(最高评分+最高点赞+统计)** - -用于产品详情页评价区域展示 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `productId` | `integer` | | 产品ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/rating-categories - -**评分类别列表** - -从字典读取评价时需要填写的评分维度，前端据此渲染评分组件。字典类型: review_rating_category，remark字段包含扩展JSON(required/min/max) - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/search - -**关键词搜索评价(公开)** - -按关键词搜索已通过的评价内容，支持按目标类型和目标ID筛选 - -**关联字典（BFF透传）**： -- rating_level：评价等级（显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `keyword` | `string` | 是 | 搜索关键词 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `targetId` | `integer(int64)` | | 目标ID(可选) | | -| `targetType` | `string` | | 目标类型(可选): PRODUCT/SCENIC_SPOT/ACTIVITY/HOTEL等 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/stats - -**评价统计(平均分、数量)** - -获取指定目标的评价统计数据（平均评分、总评价数等），用于详情页评价区域展示。产品showReview关闭时返回空统计。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `targetId` | `integer(int64)` | | 目标ID | | -| `targetType` | `string` | | 目标类型 | | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/target - -**某目标的已通过评价(公开)** - -**关联字典（BFF透传）**： -- rating_level：评价等级（筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `hasImage` | `boolean` | | 是否有图片 | | -| `hasVideo` | `boolean` | | 是否有视频 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `ratingLevel` | `string` | | 评价等级: GOOD/MEDIUM/BAD | | -| `targetId` | `integer(int64)` | | 目标ID | | -| `targetType` | `string` | | 目标类型 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/review/{reviewId}/like - -**点赞/取消点赞评价** - -对评价进行点赞或取消点赞操作，返回当前点赞状态和点赞总数。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reviewId` | `integer` | | 评价ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/review/{reviewId}/like/check - -**检查是否已点赞** - -检查当前用户是否已点赞指定评价，用于评价列表/详情的点赞按钮状态展示。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reviewId` | `integer` | | 评价ID | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 足迹接口 - -### `GET` /mp/user/footprint - -**足迹列表（含资源摘要）** - -分页查询浏览足迹列表，聚合层会补充每条足迹对应资源的摘要信息（名称、封面图等）。支持按资源类型筛选，按浏览时间倒序。 - -**权限**：需登录。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `resourceType` | `string` | | 资源类型筛选：PRODUCT/SCENIC/RESTAURANT/ACTIVITY | | - -**响应** `统一响应结果«分页结果«足迹列表项（含资源摘要）»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«足迹列表项（含资源摘要）»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `足迹列表项（含资源摘要）[]` | | 数据列表 | -|     `coverUrl` | `string` | | 封面图URL | -|     `footprintId` | `string` | | 足迹记录ID | -|     `name` | `string` | | 资源名称 | -|     `resourceId` | `string` | | 资源ID | -|     `resourceType` | `string` | | 资源类型：PRODUCT/SCENIC/RESTAURANT/ACTIVITY | -|     `tags` | `string[]` | | 标签列表 | -|     `visitTime` | `string` | | 浏览时间 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/user/footprint - -**记录足迹** - -记录用户浏览资源的足迹，同一资源重复浏览会更新浏览时间而非新增记录 - -**请求体** `添加足迹请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `resourceId` | `string` | 是 | 资源ID | -| `resourceType` | `string` | 是 | 资源类型: PRODUCT/SCENIC/RESTAURANT/ACTIVITY | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /mp/user/footprint/batch - -**批量删除足迹** - -批量删除多条浏览足迹记录，传入足迹ID列表。用于足迹管理页面的批量清理。 - -**权限**：需登录，仅能删除自己的足迹。 - -**请求体** `long[]` - -**响应** `统一响应结果«Void»` - ---- - -### `DELETE` /mp/user/footprint/{id} - -**删除足迹** - -删除单条浏览足迹记录。 - -**权限**：需登录，仅能删除自己的足迹。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `id` | `integer` | | 足迹ID | - -**响应** `统一响应结果«Void»` - ---- - -## C端 - 轮播图接口 - -### `GET` /mp/banner/active - -**获取当前生效的轮播图列表** - -返回当前处于有效期内的轮播图，按排序值排列。用于小程序首页顶部轮播展示，透传自user-service。 - -**响应** `统一响应结果«List«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `Map«string,object»[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 退款接口 - -### `GET` /mp/order/refund-reasons - -**退款原因列表** - -返回系统预设的退款原因选项，用于退款申请页面的原因选择 - -**响应** `统一响应结果«List«退款原因»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款原因[]` | | 响应数据 | -|   `category` | `string` | | 分类: GENERAL(通用)/PRODUCT(产品问题)/SERVICE(服务问题) | -|   `enabled` | `boolean` | | 是否启用 | -|   `reasonId` | `long` | | 原因ID | -|   `reasonText` | `string` | | 原因描述 | -|   `sortOrder` | `int` | | 排序序号 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/refund/{applicationId} - -**退款申请详情** - -获取退款申请的完整信息，包含审核状态、退款金额、退款进度和操作记录 - -**关联字典（BFF透传）**： -- order_status：订单状态（显示） -- payment_status：支付/退款状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `applicationId` | `integer` | | 退款申请ID | - -**响应** `统一响应结果«退款申请详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款申请详情` | | 响应数据 | -|   `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` | | 审批编号（企微OA审批编号） | -|   `autoRefundDeadline` | `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` | | 退款类型: DEPOSIT(定金)/BALANCE(尾款)/FULL(全款) | -|   `refundTypeLabel` | `string` | | 退款类型中文标签 | -|   `refundedAt` | `string` | | 退款完成时间 | -|   `reviewAdminId` | `long` | | 审批管理员ID | -|   `reviewAdminName` | `string` | | 审批管理员姓名 | -|   `reviewRemark` | `string` | | 审批备注 | -|   `reviewedAt` | `string` | | 审批时间 | -|   `status` | `string` | | 退款状态: PENDING(待审核)/APPROVED(已通过)/REJECTED(已拒绝)/REFUNDING(退款中)/REFUNDED(已退款)/CANCELLED(已撤回)/APPEALING(申诉中)/APPEAL_APPROVED(申诉通过)/APPEAL_REJECTED(申诉驳回) | -|   `statusLabel` | `string` | | 退款状态中文标签 | -|   `updateTime` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/order/refund/{applicationId}/appeal - -**发起申诉** - -退款被拒绝后，用户可在3天内发起一次申诉，由上级管理员重新审核 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `applicationId` | `integer` | | 退款申请ID | - -**请求体** `退款申诉请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `appealReason` | `string` | 是 | 申诉原因 | -| `evidence` | `string[]` | | 申诉凭证图片URL列表 | - -**响应** `统一响应结果«退款申请详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款申请详情` | | 响应数据 | -|   `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` | | 审批编号（企微OA审批编号） | -|   `autoRefundDeadline` | `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` | | 退款类型: DEPOSIT(定金)/BALANCE(尾款)/FULL(全款) | -|   `refundTypeLabel` | `string` | | 退款类型中文标签 | -|   `refundedAt` | `string` | | 退款完成时间 | -|   `reviewAdminId` | `long` | | 审批管理员ID | -|   `reviewAdminName` | `string` | | 审批管理员姓名 | -|   `reviewRemark` | `string` | | 审批备注 | -|   `reviewedAt` | `string` | | 审批时间 | -|   `status` | `string` | | 退款状态: PENDING(待审核)/APPROVED(已通过)/REJECTED(已拒绝)/REFUNDING(退款中)/REFUNDED(已退款)/CANCELLED(已撤回)/APPEALING(申诉中)/APPEAL_APPROVED(申诉通过)/APPEAL_REJECTED(申诉驳回) | -|   `statusLabel` | `string` | | 退款状态中文标签 | -|   `updateTime` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/order/refund/{applicationId}/cancel - -**撤回退款申请** - -仅PENDING状态的退款申请可撤回，撤回后订单恢复到原状态 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `applicationId` | `integer` | | 退款申请ID | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /mp/order/{orderId}/refund - -**提交退款申请** - -退款流程：获取退款预览 → 选择退款原因 → 提交退款申请 → 管理员审核 → 审核通过后自动退款到原支付方式 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**请求体** `退款申请请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `images` | `string[]` | | 退款凭证图片URL列表 | -| `reasonDetail` | `string` | | 退款补充说明 | -| `reasonId` | `string` | | 退款原因ID（已废弃，改用字典） | -| `reasonText` | `string` | 是 | 退款原因文本 | -| `reasonValue` | `string` | | 退款原因字典值 | -| `refundType` | `string` | 是 | 退款类型（FULL/DEPOSIT/BALANCE） | - -**响应** `统一响应结果«退款申请详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款申请详情` | | 响应数据 | -|   `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` | | 审批编号（企微OA审批编号） | -|   `autoRefundDeadline` | `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` | | 退款类型: DEPOSIT(定金)/BALANCE(尾款)/FULL(全款) | -|   `refundTypeLabel` | `string` | | 退款类型中文标签 | -|   `refundedAt` | `string` | | 退款完成时间 | -|   `reviewAdminId` | `long` | | 审批管理员ID | -|   `reviewAdminName` | `string` | | 审批管理员姓名 | -|   `reviewRemark` | `string` | | 审批备注 | -|   `reviewedAt` | `string` | | 审批时间 | -|   `status` | `string` | | 退款状态: PENDING(待审核)/APPROVED(已通过)/REJECTED(已拒绝)/REFUNDING(退款中)/REFUNDED(已退款)/CANCELLED(已撤回)/APPEALING(申诉中)/APPEAL_APPROVED(申诉通过)/APPEAL_REJECTED(申诉驳回) | -|   `statusLabel` | `string` | | 退款状态中文标签 | -|   `updateTime` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/{orderId}/refund-detail - -**根据订单ID获取最新退款详情** - -查询订单关联的最新一条退款申请详情，无退款记录时返回null - -**关联字典（BFF透传）**： -- order_status：订单状态（显示） -- payment_status：支付/退款状态（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `string` | | 订单ID | - -**响应** `统一响应结果«退款申请详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款申请详情` | | 响应数据 | -|   `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` | | 审批编号（企微OA审批编号） | -|   `autoRefundDeadline` | `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` | | 退款类型: DEPOSIT(定金)/BALANCE(尾款)/FULL(全款) | -|   `refundTypeLabel` | `string` | | 退款类型中文标签 | -|   `refundedAt` | `string` | | 退款完成时间 | -|   `reviewAdminId` | `long` | | 审批管理员ID | -|   `reviewAdminName` | `string` | | 审批管理员姓名 | -|   `reviewRemark` | `string` | | 审批备注 | -|   `reviewedAt` | `string` | | 审批时间 | -|   `status` | `string` | | 退款状态: PENDING(待审核)/APPROVED(已通过)/REJECTED(已拒绝)/REFUNDING(退款中)/REFUNDED(已退款)/CANCELLED(已撤回)/APPEALING(申诉中)/APPEAL_APPROVED(申诉通过)/APPEAL_REJECTED(申诉驳回) | -|   `statusLabel` | `string` | | 退款状态中文标签 | -|   `updateTime` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/order/{orderId}/refund-preview - -**退款金额预览** - -根据退款政策和订单出发日期计算可退金额，展示退款比例和扣除金额明细 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«退款预览»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款预览` | | 响应数据 | -|   `calculatedAmount` | `number` | | 计算退款金额 | -|   `daysBeforeDept` | `int` | | 距出发天数 | -|   `departureDate` | `string` | | 出发日期 | -|   `message` | `string` | | 提示信息 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单号 | -|   `paidAmount` | `number` | | 已付金额 | -|   `policyId` | `long` | | 匹配的退款政策ID | -|   `policyName` | `string` | | 匹配的退款政策名称 | -|   `refundRatio` | `int` | | 退款比例（百分比） | -|   `refundType` | `string` | | 退款类型: DEPOSIT/BALANCE/FULL | -|   `refundable` | `boolean` | | 是否可退款 | -|   `rules` | `退款规则项[]` | | 退款规则列表（按天数降序） | -|     `matched` | `boolean` | | 是否当前命中此规则 | -|     `minDays` | `int` | | 最低天数 | -|     `refundRatio` | `int` | | 退款比例（百分比） | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 通用点赞 - -### `POST` /mp/like/{targetType}/batch-check - -**批量检查点赞状态** - -批量检查当前用户是否已对多个目标点赞，返回已点赞的目标ID列表。用于列表页批量展示点赞状态。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `targetType` | `string` | | 目标类型 | - -**请求体** `string[]` - -**响应** `统一响应结果«List«string»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `string[]` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /mp/like/{targetType}/{targetId} - -**切换点赞** - -点赞/取消点赞，返回 {liked: true/false, likeCount: 点赞数} - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `targetId` | `integer` | | 目标ID | -| `targetType` | `string` | | 目标类型: REVIEW/EXPLORE/GUIDE等 | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/like/{targetType}/{targetId}/check - -**检查是否已点赞** - -检查当前用户是否已对指定目标点赞，用于前端点赞按钮状态展示。 - -**权限**：需登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `targetId` | `integer` | | 目标ID | -| `targetType` | `string` | | 目标类型 | - -**响应** `统一响应结果«boolean»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `boolean` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 酒店接口 - -### `GET` /mp/hotel/list - -**酒店列表** - -分页查询已上架的酒店列表，支持按关键词、城市、星级筛选。聚合层透传resource-service的酒店数据。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `city` | `string` | | 城市 | | -| `keyword` | `string` | | 关键词 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | -| `starLevel` | `integer(int32)` | | 星级 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/hotel/{hotelId} - -**酒店详情** - -获取酒店完整信息（含房型列表、图文详情、价格等），自动注入静态地图图片URL用于详情页地图展示。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `hotelId` | `integer` | | 酒店ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 餐厅接口 - -### `GET` /mp/restaurant/list - -**餐厅列表** - -分页查询已上架的餐厅列表，支持按关键词和城市筛选。聚合层透传resource-service的餐厅数据。 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `city` | `string` | | 城市 | | -| `keyword` | `string` | | 关键词 | | -| `page` | `integer(int32)` | | 页码 | | -| `pageSize` | `integer(int32)` | | 每页条数 | | - -**响应** `统一响应结果«分页结果«Map«string,object»»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«Map«string,object»»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `Map«string,object»[]` | | 数据列表 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /mp/restaurant/{restaurantId} - -**餐厅详情** - -获取餐厅完整信息（含菜品、图文详情等），自动注入静态地图图片URL用于详情页地图展示。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `restaurantId` | `integer` | | 餐厅ID | - -**响应** `统一响应结果«Map«string,object»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `object` | | 响应数据 | -| `message` | `string` | | 响应消息 | - ---- - -## C端 - 首页接口 - -### `GET` /mp/home - -**首页数据** - -聚合流程：并行获取推荐产品列表+产品线列表+轮播图 → Redis缓存5分钟 → 返回聚合数据 - -**关联字典（BFF透传）**： -- product_type：产品类型（产品卡片显示） -- product_status：产品状态（透传自product-service） - -**响应** `统一响应结果«首页聚合数据»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `首页聚合数据` | | 响应数据 | -|   `banners` | `Map«string,object»[]` | | 轮播图Banner列表 | -|   `contactInfo` | `Map«string,object»[]` | | 联系我们列表 | -|   `exploreTopics` | `Map«string,object»[]` | | 探索专题列表 | -|   `featuredDesigner` | `object` | | 推荐定制师 | -|   `featuredReviews` | `Map«string,object»[]` | | 首页精选评价列表 | -|   `productLines` | `Map«string,object»[]` | | 产品线分类列表 | -|   `recommendProducts` | `Map«string,object»[]` | | 推荐产品列表 | -| `message` | `string` | | 响应消息 | - ---- diff --git a/2026-03/17_1012/hl-order-service.md b/2026-03/17_1012/hl-order-service.md deleted file mode 100644 index ed3738c..0000000 --- a/2026-03/17_1012/hl-order-service.md +++ /dev/null @@ -1,3594 +0,0 @@ -# 订单服务 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_1012/hl-payment-service.md b/2026-03/17_1012/hl-payment-service.md deleted file mode 100644 index 9982afc..0000000 --- a/2026-03/17_1012/hl-payment-service.md +++ /dev/null @@ -1,282 +0,0 @@ -# 支付服务 API 文档 - -**服务**: `hl-payment-service` -**接口总数**: 7 - -## 目录 - -- **支付管理** (7 个接口) - ---- - -## 支付管理 - -### `GET` /admin/payment/list - -**支付交易列表** - -分页查询支付交易记录，支持按订单号、交易状态、交易类型筛选 - -**关联字典**： -- payment_mode：支付模式（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `endDate` | `string` | | 结束日期 | 2026-12-31 | -| `mchId` | `string` | | 商户号 | 1246532201 | -| `orderNo` | `string` | | 订单编号 | HL20260301120000001234 | -| `page` | `integer(int32)` | | 页码 | 1 | -| `pageSize` | `integer(int32)` | | 每页条数 | 20 | -| `startDate` | `string` | | 开始日期 | 2026-01-01 | -| `status` | `string` | | 支付状态 | SUCCESS | -| `tradeType` | `string` | | 交易类型: JSAPI/H5 | JSAPI | - -**响应** `统一响应结果«分页结果«支付交易信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«支付交易信息»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `支付交易信息[]` | | 数据列表 | -|     `createTime` | `string` | | 创建时间 | -|     `mchId` | `string` | | 商户号 | -|     `orderId` | `long` | | 订单ID | -|     `orderNo` | `string` | | 订单编号 | -|     `outTradeNo` | `string` | | 商户订单号 | -|     `payTime` | `string` | | 支付时间 | -|     `payType` | `string` | | 支付类型: FULL/DEPOSIT/BALANCE | -|     `status` | `string` | | 交易状态 | -|     `totalAmount` | `number` | | 交易金额 | -|     `tradeType` | `string` | | 交易类型: JSAPI/H5 | -|     `transactionId` | `long` | | 交易ID | -|     `transactionIdWx` | `string` | | 微信支付交易号 | -|     `userId` | `long` | | 用户ID | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/payment/order/{orderId} - -**按订单查询交易** - -查询指定订单的所有支付交易记录 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«List«支付交易信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `支付交易信息[]` | | 响应数据 | -|   `createTime` | `string` | | 创建时间 | -|   `mchId` | `string` | | 商户号 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `outTradeNo` | `string` | | 商户订单号 | -|   `payTime` | `string` | | 支付时间 | -|   `payType` | `string` | | 支付类型: FULL/DEPOSIT/BALANCE | -|   `status` | `string` | | 交易状态 | -|   `totalAmount` | `number` | | 交易金额 | -|   `tradeType` | `string` | | 交易类型: JSAPI/H5 | -|   `transactionId` | `long` | | 交易ID | -|   `transactionIdWx` | `string` | | 微信支付交易号 | -|   `userId` | `long` | | 用户ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/payment/refund/order/{orderId} - -**按订单查询退款** - -查询指定订单的所有退款记录 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**响应** `统一响应结果«List«退款记录信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款记录信息[]` | | 响应数据 | -|   `createTime` | `string` | | 创建时间 | -|   `mchId` | `string` | | 商户号 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `outRefundNo` | `string` | | 商户退款单号 | -|   `reason` | `string` | | 退款原因 | -|   `refundAmount` | `number` | | 退款金额 | -|   `refundId` | `long` | | 退款ID | -|   `refundIdWx` | `string` | | 微信退款单号 | -|   `status` | `string` | | 退款状态 | -|   `successTime` | `string` | | 退款成功时间 | -|   `totalAmount` | `number` | | 订单总金额 | -|   `transactionId` | `long` | | 交易ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/payment/refund/{refundId} - -**退款详情** - -获取单笔退款记录的完整信息，包含微信退款单号和退款状态 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `refundId` | `integer` | | 退款ID | - -**响应** `统一响应结果«退款记录信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款记录信息` | | 响应数据 | -|   `createTime` | `string` | | 创建时间 | -|   `mchId` | `string` | | 商户号 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `outRefundNo` | `string` | | 商户退款单号 | -|   `reason` | `string` | | 退款原因 | -|   `refundAmount` | `number` | | 退款金额 | -|   `refundId` | `long` | | 退款ID | -|   `refundIdWx` | `string` | | 微信退款单号 | -|   `status` | `string` | | 退款状态 | -|   `successTime` | `string` | | 退款成功时间 | -|   `totalAmount` | `number` | | 订单总金额 | -|   `transactionId` | `long` | | 交易ID | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/payment/{orderId}/refund - -**发起退款** - -退款流程：验证订单 → 查找原支付交易 → 调用微信退款API → 记录退款单 → 等待微信回调更新状态 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `orderId` | `integer` | | 订单ID | - -**请求体** `退款请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `amount` | `number` | 是 | 退款金额 | -| `orderId` | `long` | 是 | 订单ID | -| `reason` | `string` | | 退款原因 | - -**响应** `统一响应结果«退款记录信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `退款记录信息` | | 响应数据 | -|   `createTime` | `string` | | 创建时间 | -|   `mchId` | `string` | | 商户号 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `outRefundNo` | `string` | | 商户退款单号 | -|   `reason` | `string` | | 退款原因 | -|   `refundAmount` | `number` | | 退款金额 | -|   `refundId` | `long` | | 退款ID | -|   `refundIdWx` | `string` | | 微信退款单号 | -|   `status` | `string` | | 退款状态 | -|   `successTime` | `string` | | 退款成功时间 | -|   `totalAmount` | `number` | | 订单总金额 | -|   `transactionId` | `long` | | 交易ID | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/payment/{transactionId} - -**交易详情** - -获取单笔交易的完整信息，包含微信支付流水号 - -**关联字典**： -- payment_mode：支付模式（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `transactionId` | `integer` | | 交易ID | - -**响应** `统一响应结果«支付交易信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `支付交易信息` | | 响应数据 | -|   `createTime` | `string` | | 创建时间 | -|   `mchId` | `string` | | 商户号 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `outTradeNo` | `string` | | 商户订单号 | -|   `payTime` | `string` | | 支付时间 | -|   `payType` | `string` | | 支付类型: FULL/DEPOSIT/BALANCE | -|   `status` | `string` | | 交易状态 | -|   `totalAmount` | `number` | | 交易金额 | -|   `tradeType` | `string` | | 交易类型: JSAPI/H5 | -|   `transactionId` | `long` | | 交易ID | -|   `transactionIdWx` | `string` | | 微信支付交易号 | -|   `userId` | `long` | | 用户ID | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/payment/{transactionId}/sync - -**同步支付状态** - -主动查询微信支付状态并同步本地数据，适用于回调未到达的场景 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `transactionId` | `integer` | | 交易ID | - -**响应** `统一响应结果«支付交易信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `支付交易信息` | | 响应数据 | -|   `createTime` | `string` | | 创建时间 | -|   `mchId` | `string` | | 商户号 | -|   `orderId` | `long` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `outTradeNo` | `string` | | 商户订单号 | -|   `payTime` | `string` | | 支付时间 | -|   `payType` | `string` | | 支付类型: FULL/DEPOSIT/BALANCE | -|   `status` | `string` | | 交易状态 | -|   `totalAmount` | `number` | | 交易金额 | -|   `tradeType` | `string` | | 交易类型: JSAPI/H5 | -|   `transactionId` | `long` | | 交易ID | -|   `transactionIdWx` | `string` | | 微信支付交易号 | -|   `userId` | `long` | | 用户ID | -| `message` | `string` | | 响应消息 | - ---- diff --git a/2026-03/17_1012/hl-product-service.md b/2026-03/17_1012/hl-product-service.md deleted file mode 100644 index f687949..0000000 --- a/2026-03/17_1012/hl-product-service.md +++ /dev/null @@ -1,5235 +0,0 @@ -# 产品服务 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=线路产品 - - 完整字典值: `CORE`=核心产品, `ROUTE`=自驾路书, `CUSTOM`=私人定制, `GROUP`=小蒙马 -- product_category（产品分类）：family=亲子游, honeymoon=蜜月游, photography=旅拍, experience=体验, driving=自驾 - - 完整字典值: `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=线路产品 - - 完整字典值: `CORE`=核心产品, `ROUTE`=自驾路书, `CUSTOM`=私人定制, `GROUP`=小蒙马 -- product_status（产品状态，筛选条件+返回字段）：DRAFT=草稿, PENDING_REVIEW=待审核, REVIEWED=已审核, REJECTED=已驳回, PUBLISHED=已上架, UNPUBLISHED=已下架, COMPLETED=已完成, ORDERED=已下单 - - 完整字典值: `DRAFT`=草稿, `PENDING_REVIEW`=待审核, `REVIEWED`=已审核, `REJECTED`=已驳回, `PUBLISHED`=已上架, `UNPUBLISHED`=已下架, `COMPLETED`=已完成 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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=线路产品 - - 完整字典值: `CORE`=核心产品, `ROUTE`=自驾路书, `CUSTOM`=私人定制, `GROUP`=小蒙马 -- product_status（产品状态）：DRAFT=草稿, PENDING_REVIEW=待审核, REVIEWED=已审核, REJECTED=已驳回, PUBLISHED=已上架, UNPUBLISHED=已下架, COMPLETED=已完成, ORDERED=已下单 - - 完整字典值: `DRAFT`=草稿, `PENDING_REVIEW`=待审核, `REVIEWED`=已审核, `REJECTED`=已驳回, `PUBLISHED`=已上架, `UNPUBLISHED`=已下架, `COMPLETED`=已完成 -- product_category（产品分类）：family=亲子游, honeymoon=蜜月游, photography=旅拍, experience=体验, driving=自驾 - - 完整字典值: `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=线路产品 - - 完整字典值: `CORE`=核心产品, `ROUTE`=自驾路书, `CUSTOM`=私人定制, `GROUP`=小蒙马 -- product_category（产品分类）：family=亲子游, honeymoon=蜜月游, photography=旅拍, experience=体验, driving=自驾 - - 完整字典值: `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=线路产品 - - 完整字典值: `CORE`=核心产品, `ROUTE`=自驾路书, `CUSTOM`=私人定制, `GROUP`=小蒙马 -- product_status（产品状态，复制后固定为 DRAFT） - - 完整字典值: `DRAFT`=草稿, `PENDING_REVIEW`=待审核, `REVIEWED`=已审核, `REJECTED`=已驳回, `PUBLISHED`=已上架, `UNPUBLISHED`=已下架, `COMPLETED`=已完成 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=线路产品 - - 完整字典值: `CORE`=核心产品, `ROUTE`=自驾路书, `CUSTOM`=私人定制, `GROUP`=小蒙马 -- product_status（产品状态，请求+返回字段）：DRAFT=草稿, PENDING_REVIEW=待审核, REVIEWED=已审核, REJECTED=已驳回, PUBLISHED=已上架, UNPUBLISHED=已下架, COMPLETED=已完成, ORDERED=已下单 - - 完整字典值: `DRAFT`=草稿, `PENDING_REVIEW`=待审核, `REVIEWED`=已审核, `REJECTED`=已驳回, `PUBLISHED`=已上架, `UNPUBLISHED`=已下架, `COMPLETED`=已完成 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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（车型）：车辆费用成本计算 - - 完整字典值: `SUV`=越野车, `SEDAN`=5座轿车, `MPV`=7座商务车, `MINIBUS`=9-15座小巴, `BUS`=大巴 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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（车型）：车辆费用成本测算 - - 完整字典值: `SUV`=越野车, `SEDAN`=5座轿车, `MPV`=7座商务车, `MINIBUS`=9-15座小巴, `BUS`=大巴 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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（车型）：费用配置中车辆相关成本显示 - - 完整字典值: `SUV`=越野车, `SEDAN`=5座轿车, `MPV`=7座商务车, `MINIBUS`=9-15座小巴, `BUS`=大巴 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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（车型）：费用配置中车辆相关成本计算 - - 完整字典值: `SUV`=越野车, `SEDAN`=5座轿车, `MPV`=7座商务车, `MINIBUS`=9-15座小巴, `BUS`=大巴 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=线路产品 - - 完整字典值: `CORE`=核心产品, `ROUTE`=自驾路书, `CUSTOM`=私人定制, `GROUP`=小蒙马 - -**请求体** `公式组请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=线路产品 - - 完整字典值: `CORE`=核心产品, `ROUTE`=自驾路书, `CUSTOM`=私人定制, `GROUP`=小蒙马 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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=线路产品 - - 完整字典值: `CORE`=核心产品, `ROUTE`=自驾路书, `CUSTOM`=私人定制, `GROUP`=小蒙马 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=线路产品 - - 完整字典值: `CORE`=核心产品, `ROUTE`=自驾路书, `CUSTOM`=私人定制, `GROUP`=小蒙马 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=线路产品 - - 完整字典值: `CORE`=核心产品, `ROUTE`=自驾路书, `CUSTOM`=私人定制, `GROUP`=小蒙马 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=线路产品 - - 完整字典值: `CORE`=核心产品, `ROUTE`=自驾路书, `CUSTOM`=私人定制, `GROUP`=小蒙马 - -**请求体** `公式变量请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=线路产品 - - 完整字典值: `CORE`=核心产品, `ROUTE`=自驾路书, `CUSTOM`=私人定制, `GROUP`=小蒙马 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=线路产品 - - 完整字典值: `CORE`=核心产品, `ROUTE`=自驾路书, `CUSTOM`=私人定制, `GROUP`=小蒙马 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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=线路产品 - - 完整字典值: `CORE`=核心产品, `ROUTE`=自驾路书, `CUSTOM`=私人定制, `GROUP`=小蒙马 -- product_category（产品分类）：family=亲子游, honeymoon=蜜月游, photography=旅拍, experience=体验, driving=自驾 - - 完整字典值: `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=小蒙马拼团 - - 完整字典值: `CORE`=核心产品, `ROUTE`=自驾路书, `CUSTOM`=私人定制, `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=线路产品 - - 完整字典值: `CORE`=核心产品, `ROUTE`=自驾路书, `CUSTOM`=私人定制, `GROUP`=小蒙马 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=小蒙马拼团 - - 完整字典值: `CORE`=核心产品, `ROUTE`=自驾路书, `CUSTOM`=私人定制, `GROUP`=小蒙马 -- batch_status（批次状态）：PENDING=待开放, ENROLLING=报名中, CONFIRMED=已成团, FULL=已满员, CLOSED=已关闭, DISBANDED=已解散, IN_PROGRESS=进行中, FINISHED=已结束 - - 完整字典值: `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=已结束 - - 完整字典值: `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=已结束 - - 完整字典值: `PENDING`=待开放, `ENROLLING`=报名中, `CONFIRMED`=已成团, `FULL`=已满员, `CLOSED`=已截止, `DISBANDED`=已散团, `IN_PROGRESS`=出行中, `FINISHED`=已结束 -- staff_type（人员类型，服务人员配置）：GUIDE=领队, DRIVER=司机, PHOTOGRAPHER=摄影师, ASSISTANT=助理, OTHER=其他 - - 完整字典值: `GUIDE`=导游, `GUIDE_ASSISTANT`=导游助理, `PHOTOGRAPHER`=摄影师, `LEADER`=领队, `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=其他 - - 完整字典值: `GUIDE`=导游, `GUIDE_ASSISTANT`=导游助理, `PHOTOGRAPHER`=摄影师, `LEADER`=领队, `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=其他 - - 完整字典值: `GUIDE`=导游, `GUIDE_ASSISTANT`=导游助理, `PHOTOGRAPHER`=摄影师, `LEADER`=领队, `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（城市）：搜索结果可用于产品行程中的城市预览 - - 完整字典值: `hailar`=海拉尔, `manzhouli`=满洲里, `eergu`=额尔古纳, `genhe`=根河, `yakeshi`=牙克石, `zhalantun`=扎兰屯, `aershan`=阿尔山, `shiwei`=室韦, `enhe`=恩和, `heishantou`=黑山头, `chenbaerhu`=陈巴尔虎旗, `xinbaerhuzuo`=新巴尔虎左旗, `xinbaerhuyou`=新巴尔虎右旗, `ewenke`=鄂温克旗, `moerdaoga`=莫尔道嘎 -- city（城市筛选）：搜索结果可用于资源面板城市筛选 - - 完整字典值: `hailar`=海拉尔, `manzhouli`=满洲里, `eergu`=额尔古纳, `genhe`=根河, `aershan`=阿尔山, `shiwei`=室韦, `enhe`=恩和, `heishantou`=黑山头 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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（城市，资源面板筛选用）：用于在添加节点时按城市筛选可选资源 - - 完整字典值: `hailar`=海拉尔, `manzhouli`=满洲里, `eergu`=额尔古纳, `genhe`=根河, `aershan`=阿尔山, `shiwei`=室韦, `enhe`=恩和, `heishantou`=黑山头 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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（城市）：资源面板城市筛选 - - 完整字典值: `hailar`=海拉尔, `manzhouli`=满洲里, `eergu`=额尔古纳, `genhe`=根河, `aershan`=阿尔山, `shiwei`=室韦, `enhe`=恩和, `heishantou`=黑山头 -- cities（城市ID映射）：城市名称预览 - - 完整字典值: `hailar`=海拉尔, `manzhouli`=满洲里, `eergu`=额尔古纳, `genhe`=根河, `yakeshi`=牙克石, `zhalantun`=扎兰屯, `aershan`=阿尔山, `shiwei`=室韦, `enhe`=恩和, `heishantou`=黑山头, `chenbaerhu`=陈巴尔虎旗, `xinbaerhuzuo`=新巴尔虎左旗, `xinbaerhuyou`=新巴尔虎右旗, `ewenke`=鄂温克旗, `moerdaoga`=莫尔道嘎 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=其他 - - 完整字典值: `GUIDE`=导游, `GUIDE_ASSISTANT`=导游助理, `PHOTOGRAPHER`=摄影师, `LEADER`=领队, `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=其他 - - 完整字典值: `GUIDE`=导游, `GUIDE_ASSISTANT`=导游助理, `PHOTOGRAPHER`=摄影师, `LEADER`=领队, `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（城市）：资源面板城市筛选 - - 完整字典值: `hailar`=海拉尔, `manzhouli`=满洲里, `eergu`=额尔古纳, `genhe`=根河, `aershan`=阿尔山, `shiwei`=室韦, `enhe`=恩和, `heishantou`=黑山头 -- cities（城市ID映射）：城市名称预览 - - 完整字典值: `hailar`=海拉尔, `manzhouli`=满洲里, `eergu`=额尔古纳, `genhe`=根河, `yakeshi`=牙克石, `zhalantun`=扎兰屯, `aershan`=阿尔山, `shiwei`=室韦, `enhe`=恩和, `heishantou`=黑山头, `chenbaerhu`=陈巴尔虎旗, `xinbaerhuzuo`=新巴尔虎左旗, `xinbaerhuyou`=新巴尔虎右旗, `ewenke`=鄂温克旗, `moerdaoga`=莫尔道嘎 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=其他 - - 完整字典值: `GUIDE`=导游, `GUIDE_ASSISTANT`=导游助理, `PHOTOGRAPHER`=摄影师, `LEADER`=领队, `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=其他 - - 完整字典值: `GUIDE`=导游, `GUIDE_ASSISTANT`=导游助理, `PHOTOGRAPHER`=摄影师, `LEADER`=领队, `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_1012/hl-resource-service.md b/2026-03/17_1012/hl-resource-service.md deleted file mode 100644 index ad1f144..0000000 --- a/2026-03/17_1012/hl-resource-service.md +++ /dev/null @@ -1,7002 +0,0 @@ -# 资源服务 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路径参数 - - 完整字典值: `GUIDE`=导游, `GUIDE_ASSISTANT`=导游助理, `PHOTOGRAPHER`=摄影师, `LEADER`=领队, `OTHER`=其他 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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路径参数 - - 完整字典值: `GUIDE`=导游, `GUIDE_ASSISTANT`=导游助理, `PHOTOGRAPHER`=摄影师, `LEADER`=领队, `OTHER`=其他 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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路径参数 - - 完整字典值: `GUIDE`=导游, `GUIDE_ASSISTANT`=导游助理, `PHOTOGRAPHER`=摄影师, `LEADER`=领队, `OTHER`=其他 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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路径参数 - - 完整字典值: `GUIDE`=导游, `GUIDE_ASSISTANT`=导游助理, `PHOTOGRAPHER`=摄影师, `LEADER`=领队, `OTHER`=其他 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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_1012/hl-review-service.md b/2026-03/17_1012/hl-review-service.md deleted file mode 100644 index dbb2fda..0000000 --- a/2026-03/17_1012/hl-review-service.md +++ /dev/null @@ -1,236 +0,0 @@ -# 评价服务 API 文档 - -**服务**: `hl-review-service` -**接口总数**: 6 - -## 目录 - -- **管理端-评价审核** (6 个接口) - ---- - -## 管理端-评价审核 - -### `GET` /admin/review/list - -**评价列表(支持好中差评/有图/有视频筛选)** - -分页查询全部评价（含待审核/已通过/已拒绝），支持按评价等级、是否有图/视频、目标类型筛选 - -**关联字典**： -- review_status：评价审核状态（列表筛选+显示） -- rating_level：评价等级（列表筛选+显示） - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `hasImage` | `boolean` | | 是否有图片: true/false | | -| `hasVideo` | `boolean` | | 是否有视频: true/false | | -| `keyword` | `string` | | 搜索关键词 | 风景 | -| `maxRating` | `integer(int32)` | | 最高评分(整体满意度) | 5 | -| `minRating` | `integer(int32)` | | 最低评分(整体满意度) | 3 | -| `page` | `integer(int32)` | | 页码 | 1 | -| `pageSize` | `integer(int32)` | | 每页条数 | 20 | -| `productType` | `string` | | 产品类型（字典 review_product_type） | CORE | -| `ratingLevel` | `string` | | 评价等级: GOOD/MEDIUM/BAD | GOOD | -| `reviewType` | `string` | | 评论类型（字典 review_type） | PRODUCT | -| `status` | `string` | | 评价状态 | APPROVED | -| `targetId` | `integer(int64)` | | 评价目标ID | 2001 | -| `targetType` | `string` | | 评价目标类型 | PRODUCT | - -**响应** `统一响应结果«分页结果«评价列表项(管理端)»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `分页结果«评价列表项(管理端)»` | | 响应数据 | -|   `page` | `int` | | 当前页码 | -|   `pageSize` | `int` | | 每页条数 | -|   `records` | `评价列表项(管理端)[]` | | 数据列表 | -|     `auditedAt` | `string` | | 审核时间 | -|     `auditorName` | `string` | | 审核人姓名 | -|     `content` | `string` | | 评价内容 | -|     `createdAt` | `string` | | 创建时间 | -|     `hasReply` | `boolean` | | 是否已回复 | -|     `imageCount` | `int` | | 图片数量 | -|     `orderId` | `string` | | 订单ID | -|     `orderNo` | `string` | | 订单编号 | -|     `productType` | `string` | | 产品类型 | -|     `productTypeLabel` | `string` | | 产品类型标签 | -|     `ratingAccommodation` | `int` | | 住宿安排评分(1-5) | -|     `ratingDining` | `int` | | 餐饮质量评分(1-5) | -|     `ratingDriver` | `int` | | 司机服务评分(1-5) | -|     `ratingItinerary` | `int` | | 行程安排评分(1-5) | -|     `ratingLevel` | `string` | | 评价等级: GOOD/MEDIUM/BAD | -|     `ratingLevelLabel` | `string` | | 评价等级标签 | -|     `ratingOverall` | `int` | | 整体满意度评分(1-5) | -|     `rejectReason` | `string` | | 拒绝原因 | -|     `reviewId` | `string` | | 评价ID | -|     `reviewType` | `string` | | 评论类型 | -|     `reviewTypeLabel` | `string` | | 评论类型标签 | -|     `status` | `string` | | 评价状态 | -|     `statusLabel` | `string` | | 评价状态标签 | -|     `targetId` | `string` | | 评价目标ID | -|     `targetName` | `string` | | 评价目标名称 | -|     `targetType` | `string` | | 评价目标类型 | -|     `targetTypeLabel` | `string` | | 评价目标类型标签 | -|     `userAvatar` | `string` | | 用户头像 | -|     `userNickname` | `string` | | 用户昵称 | -|     `videoCount` | `int` | | 视频数量 | -|   `total` | `int` | | 总记录数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/review/{reviewId} - -**评价详情** - -**关联字典**： -- review_status：评价审核状态（显示） -- rating_level：评价等级（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reviewId` | `integer` | | 评价ID | - -**响应** `统一响应结果«评价详情»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `评价详情` | | 响应数据 | -|   `adminReply` | `string` | | 管理员回复内容 | -|   `adminReplyAt` | `string` | | 回复时间 | -|   `adminReplyName` | `string` | | 回复管理员姓名 | -|   `auditedAt` | `string` | | 审核时间 | -|   `auditorAdminId` | `string` | | 审核人ID | -|   `auditorName` | `string` | | 审核人姓名 | -|   `content` | `string` | | 评价内容 | -|   `createdAt` | `string` | | 创建时间 | -|   `departureDate` | `string` | | 出发日期(冗余自订单) | -|   `hasImage` | `boolean` | | 是否有图片 | -|   `hasVideo` | `boolean` | | 是否有视频 | -|   `imageCount` | `int` | | 图片数量 | -|   `images` | `评价图片信息[]` | | 评价图片列表 | -|     `fileId` | `string` | | 文件ID | -|     `imageId` | `string` | | 图片ID | -|     `imageUrl` | `string` | | 图片URL | -|     `sortOrder` | `int` | | 排序序号 | -|   `machineResult` | `string` | | 机审结果 | -|   `orderId` | `string` | | 订单ID | -|   `orderNo` | `string` | | 订单编号 | -|   `productType` | `string` | | 产品类型 | -|   `productTypeLabel` | `string` | | 产品类型标签 | -|   `ratingAccommodation` | `int` | | 住宿安排评分(1-5) | -|   `ratingDining` | `int` | | 餐饮质量评分(1-5) | -|   `ratingDriver` | `int` | | 司机服务评分(1-5) | -|   `ratingItinerary` | `int` | | 行程安排评分(1-5) | -|   `ratingLevel` | `string` | | 评价等级: GOOD/MEDIUM/BAD | -|   `ratingLevelLabel` | `string` | | 评价等级标签: 好评/中评/差评 | -|   `ratingOverall` | `int` | | 整体满意度评分(1-5) | -|   `rejectReason` | `string` | | 拒绝原因 | -|   `reviewId` | `string` | | 评价ID | -|   `reviewType` | `string` | | 评论类型 | -|   `reviewTypeLabel` | `string` | | 评论类型标签 | -|   `status` | `string` | | 评价状态 | -|   `statusLabel` | `string` | | 评价状态标签 | -|   `targetId` | `string` | | 评价目标ID | -|   `targetName` | `string` | | 评价目标名称 | -|   `targetType` | `string` | | 评价目标类型 | -|   `targetTypeLabel` | `string` | | 评价目标类型标签 | -|   `userAvatar` | `string` | | 用户头像 | -|   `userId` | `string` | | 用户ID | -|   `userNickname` | `string` | | 用户昵称 | -|   `videoCount` | `int` | | 视频数量 | -|   `videos` | `评价视频信息[]` | | 评价视频列表 | -|     `coverUrl` | `string` | | 视频封面URL | -|     `duration` | `int` | | 视频时长(秒) | -|     `fileId` | `string` | | 文件ID | -|     `sortOrder` | `int` | | 排序序号 | -|     `videoId` | `string` | | 视频ID | -|     `videoUrl` | `string` | | 视频URL | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/review/{reviewId}/approve - -**通过评价** - -审核通过评价，通过后评价在小程序端公开展示。状态流转：PENDING_REVIEW → APPROVED - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reviewId` | `integer` | | 评价ID | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /admin/review/{reviewId}/override-approve - -**覆盖通过(机器拒绝的)** - -对阿里云内容审核自动拒绝的评价进行人工覆盖通过。状态流转：AUTO_REJECTED → APPROVED - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reviewId` | `integer` | | 评价ID | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /admin/review/{reviewId}/reject - -**拒绝评价** - -审核拒绝评价，需填写拒绝原因。拒绝后评价不公开展示。状态流转：PENDING_REVIEW → REJECTED - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reviewId` | `integer` | | 评价ID | - -**请求体** `拒绝评价请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `rejectReason` | `string` | 是 | 拒绝原因 | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /admin/review/{reviewId}/reply - -**回复评价(每条评价仅可回复一次)** - -管理员回复用户评价，回复内容在小程序端公开展示。每条评价仅允许回复一次，不可修改。 - -**权限**：需管理员登录。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `reviewId` | `integer` | | 评价ID | - -**请求体** `管理员回复请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `replyContent` | `string` | 是 | 回复内容 | - -**响应** `统一响应结果«Void»` - ---- diff --git a/2026-03/17_1012/hl-task-service.md b/2026-03/17_1012/hl-task-service.md deleted file mode 100644 index 0631450..0000000 --- a/2026-03/17_1012/hl-task-service.md +++ /dev/null @@ -1,924 +0,0 @@ -# 任务服务 API 文档 - -**服务**: `hl-task-service` -**接口总数**: 27 - -## 目录 - -- **WebSocket 实时推送** (1 个接口) -- **任务看板管理** (13 个接口) -- **任务管理** (13 个接口) - ---- - -## WebSocket 实时推送 - -### `GET` /admin/task/board/ws-doc/info - -**WebSocket 连接说明** - -## 连接信息 - -| 项目 | 值 | -|------|-------| -| **连接地址** | `ws://{host}:8092/ws/task` | -| **协议** | STOMP over WebSocket（SockJS 降级方案） | -| **跨域** | 允许所有源 (`*`) | - -## 订阅频道 - -| 订阅地址 | 说明 | -|------------|-------------| -| `/topic/board/{boardId}` | 订阅指定看板，接收该看板下的实时任务事件 | - -## 推送消息格式 - -```json -{ - "event": "TASK_CREATED", - "data": { ... }, - "timestamp": 1709539200000 -} -``` - -## 事件类型 - -| 事件 | 说明 | data 内容 | -|-------|------------|------| -| TASK_CREATED | 任务创建 | 任务对象 | -| TASK_UPDATED | 任务更新 | 任务对象 | -| TASK_DELETED | 任务删除 | 任务ID | -| TASK_MOVED | 任务移动（状态变更） | 任务对象 | -| COMMENT_ADDED | 新增评论 | 评论对象 | - -## 前端接入示例 (SockJS + STOMP) - -```javascript -import SockJS from 'sockjs-client' -import { Stomp } from '@stomp/stompjs' - -const socket = new SockJS('http://localhost:8092/ws/task') -const stompClient = Stomp.over(socket) - -stompClient.connect({}, () => { - stompClient.subscribe('/topic/board/123', (msg) => { - const { event, data, timestamp } = JSON.parse(msg.body) - console.log('Event:', event, 'Data:', data) - }) -}) -``` - -**响应** `object` - ---- - -## 任务看板管理 - -### `POST` /admin/task/board - -**创建自定义看板** - -创建自定义看板，自动添加创建者为看板成员，并创建默认状态列（待办、进行中、已完成）。 - -**权限**：需管理员登录。 - -**请求体** `创建看板请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardName` | `string` | 是 | 看板名称 | -| `deptId` | `long` | | 部门ID | -| `description` | `string` | | 看板描述 | -| `memberIds` | `long[]` | | 成员ID列表 | - -**响应** `统一响应结果«看板信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板信息` | | 响应数据 | -|   `boardId` | `long` | | 看板ID | -|   `boardName` | `string` | | 看板名称 | -|   `boardType` | `string` | | 看板类型 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `deptId` | `long` | | 部门ID | -|   `deptName` | `string` | | 部门名称 | -|   `description` | `string` | | 看板描述 | -|   `statuses` | `看板状态信息[]` | | 状态列表 | -|     `isPreset` | `boolean` | | 是否预设状态 | -|     `sortOrder` | `int` | | 排序序号 | -|     `statusColor` | `string` | | 状态颜色 | -|     `statusId` | `long` | | 状态ID | -|     `statusName` | `string` | | 状态名称 | -|     `taskCount` | `int` | | 该状态下的任务数量 | -|   `taskCount` | `int` | | 任务总数 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/task/board/{boardId} - -**看板详情** - -返回看板基本信息（名称、描述、创建者），不含任务数据。查看任务请使用「获取看板任务」接口 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**响应** `统一响应结果«看板信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板信息` | | 响应数据 | -|   `boardId` | `long` | | 看板ID | -|   `boardName` | `string` | | 看板名称 | -|   `boardType` | `string` | | 看板类型 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `deptId` | `long` | | 部门ID | -|   `deptName` | `string` | | 部门名称 | -|   `description` | `string` | | 看板描述 | -|   `statuses` | `看板状态信息[]` | | 状态列表 | -|     `isPreset` | `boolean` | | 是否预设状态 | -|     `sortOrder` | `int` | | 排序序号 | -|     `statusColor` | `string` | | 状态颜色 | -|     `statusId` | `long` | | 状态ID | -|     `statusName` | `string` | | 状态名称 | -|     `taskCount` | `int` | | 该状态下的任务数量 | -|   `taskCount` | `int` | | 任务总数 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/task/board/{boardId} - -**更新看板** - -更新看板的名称和描述。仅看板创建者或超级管理员可操作。 - -**权限**：需管理员登录，且为看板创建者或超级管理员。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**请求体** `更新看板请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardName` | `string` | | 看板名称 | -| `description` | `string` | | 看板描述 | - -**响应** `统一响应结果«看板信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板信息` | | 响应数据 | -|   `boardId` | `long` | | 看板ID | -|   `boardName` | `string` | | 看板名称 | -|   `boardType` | `string` | | 看板类型 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `deptId` | `long` | | 部门ID | -|   `deptName` | `string` | | 部门名称 | -|   `description` | `string` | | 看板描述 | -|   `statuses` | `看板状态信息[]` | | 状态列表 | -|     `isPreset` | `boolean` | | 是否预设状态 | -|     `sortOrder` | `int` | | 排序序号 | -|     `statusColor` | `string` | | 状态颜色 | -|     `statusId` | `long` | | 状态ID | -|     `statusName` | `string` | | 状态名称 | -|     `taskCount` | `int` | | 该状态下的任务数量 | -|   `taskCount` | `int` | | 任务总数 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/task/board/{boardId} - -**删除看板** - -删除看板及其下所有状态列和任务（级联删除）。仅看板创建者或超级管理员可操作 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**响应** `统一响应结果«Void»` - ---- - -### `DELETE` /admin/task/board/{boardId}/member/{targetAdminId} - -**移除成员** - -从看板中移除指定成员。仅看板创建者或超级管理员可操作，不能移除创建者自己 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | -| `targetAdminId` | `integer` | | 目标管理员ID | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/task/board/{boardId}/members - -**获取看板成员** - -返回看板的所有成员列表，包含成员的管理员ID和姓名 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**响应** `统一响应结果«List«看板成员信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板成员信息[]` | | 响应数据 | -|   `adminId` | `long` | | 管理员ID | -|   `avatarUrl` | `string` | | 头像地址 | -|   `joinedAt` | `string` | | 加入时间 | -|   `role` | `string` | | 角色: OWNER/MEMBER | -|   `username` | `string` | | 用户名 | -| `message` | `string` | | 响应消息 | - ---- - -### `POST` /admin/task/board/{boardId}/members - -**添加成员** - -批量添加管理员为看板成员，成为成员后可以查看看板、创建和操作任务。 - -**权限**：需管理员登录，且为看板创建者或超级管理员。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**请求体** `添加成员请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `adminIds` | `long[]` | 是 | 管理员ID列表 | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /admin/task/board/{boardId}/status - -**创建状态列** - -在看板中创建新的状态列（如测试中、待发布等），自动排到末尾。任务通过拖拽在不同状态列间流转。 - -**权限**：需管理员登录且为看板成员。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**请求体** `创建状态请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `statusColor` | `string` | | 状态颜色 | -| `statusName` | `string` | 是 | 状态名称 | - -**响应** `统一响应结果«看板状态信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板状态信息` | | 响应数据 | -|   `isPreset` | `boolean` | | 是否预设状态 | -|   `sortOrder` | `int` | | 排序序号 | -|   `statusColor` | `string` | | 状态颜色 | -|   `statusId` | `long` | | 状态ID | -|   `statusName` | `string` | | 状态名称 | -|   `taskCount` | `int` | | 该状态下的任务数量 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/task/board/{boardId}/status/sort - -**状态列排序** - -批量更新状态列的排序顺序。传入状态列ID数组，数组下标即为新的排序值。操作完成后通过WebSocket推送STATUS_REORDERED事件 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**请求体** `状态排序请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `statusIds` | `long[]` | 是 | 状态ID列表(按排序顺序) | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/task/board/{boardId}/statuses - -**获取看板状态列** - -返回看板的所有状态列（如待办、进行中、已完成），按排序字段升序排列。拖拽任务到不同状态列实现状态流转 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**响应** `统一响应结果«List«看板状态信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板状态信息[]` | | 响应数据 | -|   `isPreset` | `boolean` | | 是否预设状态 | -|   `sortOrder` | `int` | | 排序序号 | -|   `statusColor` | `string` | | 状态颜色 | -|   `statusId` | `long` | | 状态ID | -|   `statusName` | `string` | | 状态名称 | -|   `taskCount` | `int` | | 该状态下的任务数量 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/task/boards - -**获取可见看板列表** - -返回当前管理员可见的看板列表：超级管理员可见所有看板，普通管理员仅可见自己创建的或作为成员的看板 - -**响应** `统一响应结果«List«看板信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板信息[]` | | 响应数据 | -|   `boardId` | `long` | | 看板ID | -|   `boardName` | `string` | | 看板名称 | -|   `boardType` | `string` | | 看板类型 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `deptId` | `long` | | 部门ID | -|   `deptName` | `string` | | 部门名称 | -|   `description` | `string` | | 看板描述 | -|   `statuses` | `看板状态信息[]` | | 状态列表 | -|     `isPreset` | `boolean` | | 是否预设状态 | -|     `sortOrder` | `int` | | 排序序号 | -|     `statusColor` | `string` | | 状态颜色 | -|     `statusId` | `long` | | 状态ID | -|     `statusName` | `string` | | 状态名称 | -|     `taskCount` | `int` | | 该状态下的任务数量 | -|   `taskCount` | `int` | | 任务总数 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/task/status/{statusId} - -**更新状态列** - -更新状态列的名称和颜色。 - -**权限**：需管理员登录且为看板成员。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `statusId` | `integer` | | 状态列ID | - -**请求体** `更新状态请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `statusColor` | `string` | | 状态颜色 | -| `statusName` | `string` | | 状态名称 | - -**响应** `统一响应结果«看板状态信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板状态信息` | | 响应数据 | -|   `isPreset` | `boolean` | | 是否预设状态 | -|   `sortOrder` | `int` | | 排序序号 | -|   `statusColor` | `string` | | 状态颜色 | -|   `statusId` | `long` | | 状态ID | -|   `statusName` | `string` | | 状态名称 | -|   `taskCount` | `int` | | 该状态下的任务数量 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/task/status/{statusId} - -**删除状态列** - -删除看板的状态列。如果状态列下有任务则不允许删除，需先移动或删除任务 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `statusId` | `integer` | | 状态列ID | - -**响应** `统一响应结果«Void»` - ---- - -## 任务管理 - -### `POST` /admin/task - -**创建任务** - -在指定看板和状态列下创建任务。创建成功后通过WebSocket推送TASK_CREATED事件，并通知被分配的负责人 - -**关联字典**： -- task_priority：任务优先级（创建时选择） - -**请求体** `创建任务请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `assigneeIds` | `long[]` | | 负责人ID列表 | -| `boardId` | `long` | 是 | 看板ID | -| `description` | `string` | | 任务描述 | -| `dueDate` | `string` | | 截止日期 | -| `priority` | `string` | | 优先级: LOW/MEDIUM/HIGH/URGENT | -| `statusId` | `long` | | 状态ID | -| `title` | `string` | 是 | 任务标题 | - -**响应** `统一响应结果«任务信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `任务信息` | | 响应数据 | -|   `assignees` | `负责人信息[]` | | 负责人列表 | -|     `adminId` | `long` | | 管理员ID | -|     `avatarUrl` | `string` | | 头像地址 | -|     `username` | `string` | | 用户名 | -|     `wechatName` | `string` | | 企微昵称 | -|   `boardId` | `long` | | 看板ID | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 任务描述 | -|   `dueDate` | `string` | | 截止日期 | -|   `overdue` | `boolean` | | 是否逾期 | -|   `parentId` | `long` | | 父任务ID | -|   `priority` | `string` | | 优先级: LOW/MEDIUM/HIGH/URGENT | -|   `sortOrder` | `int` | | 排序序号 | -|   `statusColor` | `string` | | 状态颜色 | -|   `statusId` | `long` | | 状态ID | -|   `statusName` | `string` | | 状态名称 | -|   `subtaskCompleted` | `int` | | 已完成子任务数 | -|   `subtaskTotal` | `int` | | 子任务总数 | -|   `subtasks` | `子任务信息[]` | | 子任务列表 | -|     `completed` | `boolean` | | 是否已完成 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdBy` | `long` | | 创建人ID | -|     `creatorName` | `string` | | 创建人姓名 | -|     `taskId` | `long` | | 子任务ID | -|     `title` | `string` | | 子任务标题 | -|   `taskId` | `long` | | 任务ID | -|   `title` | `string` | | 任务标题 | -|   `updatedAt` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/task/board/{boardId}/tasks - -**获取看板任务(按状态分组)** - -返回看板下所有任务，按状态列分组。支持按优先级(HIGH/MEDIUM/LOW)和负责人筛选，每组内按排序值升序排列 - -**关联字典**： -- task_priority：任务优先级（列表筛选+显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `boardId` | `integer` | | 看板ID | - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `assigneeId` | `integer(int64)` | | 负责人ID | | -| `priority` | `string` | | 优先级 | | - -**响应** `统一响应结果«List«看板任务分组信息»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `看板任务分组信息[]` | | 响应数据 | -|   `sortOrder` | `int` | | 排序序号 | -|   `statusColor` | `string` | | 状态颜色 | -|   `statusId` | `long` | | 状态ID | -|   `statusName` | `string` | | 状态名称 | -|   `tasks` | `任务信息[]` | | 该状态下的任务列表 | -|     `assignees` | `负责人信息[]` | | 负责人列表 | -|     `boardId` | `long` | | 看板ID | -|     `createdAt` | `string` | | 创建时间 | -|     `createdBy` | `long` | | 创建人ID | -|     `creatorName` | `string` | | 创建人姓名 | -|     `description` | `string` | | 任务描述 | -|     `dueDate` | `string` | | 截止日期 | -|     `overdue` | `boolean` | | 是否逾期 | -|     `parentId` | `long` | | 父任务ID | -|     `priority` | `string` | | 优先级: LOW/MEDIUM/HIGH/URGENT | -|     `sortOrder` | `int` | | 排序序号 | -|     `statusColor` | `string` | | 状态颜色 | -|     `statusId` | `long` | | 状态ID | -|     `statusName` | `string` | | 状态名称 | -|     `subtaskCompleted` | `int` | | 已完成子任务数 | -|     `subtaskTotal` | `int` | | 子任务总数 | -|     `subtasks` | `子任务信息[]` | | 子任务列表 | -|     `taskId` | `long` | | 任务ID | -|     `title` | `string` | | 任务标题 | -|     `updatedAt` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/task/comment/{commentId} - -**删除评论** - -仅评论作者本人可删除自己的评论，系统自动生成的活动记录不可删除 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `commentId` | `integer` | | 评论ID | - -**响应** `统一响应结果«Void»` - ---- - -### `DELETE` /admin/task/subtask/{subtaskId} - -**删除子任务** - -删除指定子任务。 - -**权限**：需管理员登录且为看板成员。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `subtaskId` | `integer` | | 子任务ID | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/task/subtask/{subtaskId}/toggle - -**切换子任务完成状态** - -切换子任务的完成/未完成状态（toggle），完成状态切换会自动记录到任务时间线 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `subtaskId` | `integer` | | 子任务ID | - -**响应** `统一响应结果«Void»` - ---- - -### `GET` /admin/task/{taskId} - -**任务详情** - -返回任务完整信息，包含子任务列表、负责人信息、附件列表等 - -**关联字典**： -- task_priority：任务优先级（显示） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**响应** `统一响应结果«任务信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `任务信息` | | 响应数据 | -|   `assignees` | `负责人信息[]` | | 负责人列表 | -|     `adminId` | `long` | | 管理员ID | -|     `avatarUrl` | `string` | | 头像地址 | -|     `username` | `string` | | 用户名 | -|     `wechatName` | `string` | | 企微昵称 | -|   `boardId` | `long` | | 看板ID | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 任务描述 | -|   `dueDate` | `string` | | 截止日期 | -|   `overdue` | `boolean` | | 是否逾期 | -|   `parentId` | `long` | | 父任务ID | -|   `priority` | `string` | | 优先级: LOW/MEDIUM/HIGH/URGENT | -|   `sortOrder` | `int` | | 排序序号 | -|   `statusColor` | `string` | | 状态颜色 | -|   `statusId` | `long` | | 状态ID | -|   `statusName` | `string` | | 状态名称 | -|   `subtaskCompleted` | `int` | | 已完成子任务数 | -|   `subtaskTotal` | `int` | | 子任务总数 | -|   `subtasks` | `子任务信息[]` | | 子任务列表 | -|     `completed` | `boolean` | | 是否已完成 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdBy` | `long` | | 创建人ID | -|     `creatorName` | `string` | | 创建人姓名 | -|     `taskId` | `long` | | 子任务ID | -|     `title` | `string` | | 子任务标题 | -|   `taskId` | `long` | | 任务ID | -|   `title` | `string` | | 任务标题 | -|   `updatedAt` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/task/{taskId} - -**更新任务** - -更新任务的标题、描述、优先级、截止日期、负责人等信息。更新后通过WebSocket推送TASK_UPDATED事件，如果修改了负责人则额外通知新负责人。 - -**权限**：需管理员登录且为看板成员。 - -**关联字典**： -- task_priority：任务优先级（编辑时选择） - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**请求体** `更新任务请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `assigneeIds` | `long[]` | | 负责人ID列表 | -| `description` | `string` | | 任务描述 | -| `dueDate` | `string` | | 截止日期 | -| `priority` | `string` | | 优先级: LOW/MEDIUM/HIGH/URGENT | -| `title` | `string` | | 任务标题 | - -**响应** `统一响应结果«任务信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `任务信息` | | 响应数据 | -|   `assignees` | `负责人信息[]` | | 负责人列表 | -|     `adminId` | `long` | | 管理员ID | -|     `avatarUrl` | `string` | | 头像地址 | -|     `username` | `string` | | 用户名 | -|     `wechatName` | `string` | | 企微昵称 | -|   `boardId` | `long` | | 看板ID | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `description` | `string` | | 任务描述 | -|   `dueDate` | `string` | | 截止日期 | -|   `overdue` | `boolean` | | 是否逾期 | -|   `parentId` | `long` | | 父任务ID | -|   `priority` | `string` | | 优先级: LOW/MEDIUM/HIGH/URGENT | -|   `sortOrder` | `int` | | 排序序号 | -|   `statusColor` | `string` | | 状态颜色 | -|   `statusId` | `long` | | 状态ID | -|   `statusName` | `string` | | 状态名称 | -|   `subtaskCompleted` | `int` | | 已完成子任务数 | -|   `subtaskTotal` | `int` | | 子任务总数 | -|   `subtasks` | `子任务信息[]` | | 子任务列表 | -|     `completed` | `boolean` | | 是否已完成 | -|     `createdAt` | `string` | | 创建时间 | -|     `createdBy` | `long` | | 创建人ID | -|     `creatorName` | `string` | | 创建人姓名 | -|     `taskId` | `long` | | 子任务ID | -|     `title` | `string` | | 子任务标题 | -|   `taskId` | `long` | | 任务ID | -|   `title` | `string` | | 任务标题 | -|   `updatedAt` | `string` | | 更新时间 | -| `message` | `string` | | 响应消息 | - ---- - -### `DELETE` /admin/task/{taskId} - -**删除任务** - -删除任务及其所有子任务、评论和时间线记录（级联删除）。删除后通过WebSocket推送TASK_DELETED事件。 - -**权限**：需管理员登录且为看板成员。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /admin/task/{taskId}/comment - -**添加评论** - -在任务时间线中添加评论，添加后自动通知任务负责人 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**请求体** `创建评论请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `content` | `string` | 是 | 评论内容 | - -**响应** `统一响应结果«时间线条目»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `时间线条目` | | 响应数据 | -|   `action` | `string` | | 操作类型 | -|   `adminAvatar` | `string` | | 管理员头像 | -|   `adminId` | `long` | | 管理员ID | -|   `adminName` | `string` | | 管理员姓名 | -|   `content` | `string` | | 内容 | -|   `createdAt` | `string` | | 创建时间 | -|   `id` | `long` | | 条目ID | -|   `newValue` | `string` | | 新值 | -|   `oldValue` | `string` | | 旧值 | -|   `type` | `string` | | 类型: COMMENT/ACTIVITY | -| `message` | `string` | | 响应消息 | - ---- - -### `PUT` /admin/task/{taskId}/sort - -**任务排序** - -更新任务在同一状态列内的排序位置，用于拖拽排序 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**请求体** `任务排序请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `statusId` | `long` | 是 | 状态ID | -| `taskIds` | `long[]` | 是 | 任务ID列表(按排序顺序) | - -**响应** `统一响应结果«Void»` - ---- - -### `PUT` /admin/task/{taskId}/status - -**变更任务状态** - -将任务移动到指定状态列（拖拽操作），自动记录状态变更到时间线，并通过WebSocket推送TASK_STATUS_CHANGED事件 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**请求体** `变更任务状态请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `statusId` | `long` | 是 | 目标状态ID | - -**响应** `统一响应结果«Void»` - ---- - -### `POST` /admin/task/{taskId}/subtask - -**创建子任务** - -在指定任务下创建子任务（待办项），用于拆分任务的执行步骤。子任务默认为未完成状态。 - -**权限**：需管理员登录且为看板成员。 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**请求体** `创建子任务请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `title` | `string` | 是 | 子任务标题 | - -**响应** `统一响应结果«子任务信息»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `子任务信息` | | 响应数据 | -|   `completed` | `boolean` | | 是否已完成 | -|   `createdAt` | `string` | | 创建时间 | -|   `createdBy` | `long` | | 创建人ID | -|   `creatorName` | `string` | | 创建人姓名 | -|   `taskId` | `long` | | 子任务ID | -|   `title` | `string` | | 子任务标题 | -| `message` | `string` | | 响应消息 | - ---- - -### `GET` /admin/task/{taskId}/timeline - -**获取任务时间线** - -返回任务的完整操作记录，包含评论和系统自动记录的状态变更、人员分配等活动，按时间正序排列 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `taskId` | `integer` | | 任务ID | - -**响应** `统一响应结果«List«时间线条目»»` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `code` | `int` | | 状态码 | -| `data` | `时间线条目[]` | | 响应数据 | -|   `action` | `string` | | 操作类型 | -|   `adminAvatar` | `string` | | 管理员头像 | -|   `adminId` | `long` | | 管理员ID | -|   `adminName` | `string` | | 管理员姓名 | -|   `content` | `string` | | 内容 | -|   `createdAt` | `string` | | 创建时间 | -|   `id` | `long` | | 条目ID | -|   `newValue` | `string` | | 新值 | -|   `oldValue` | `string` | | 旧值 | -|   `type` | `string` | | 类型: COMMENT/ACTIVITY | -| `message` | `string` | | 响应消息 | - ---- diff --git a/2026-03/17_1012/hl-user-service.md b/2026-03/17_1012/hl-user-service.md deleted file mode 100644 index 161d57a..0000000 --- a/2026-03/17_1012/hl-user-service.md +++ /dev/null @@ -1,4570 +0,0 @@ -# 用户服务 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=启用） - - 完整字典值: `ACTIVE`=启用, `INACTIVE`=停用 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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=启用） - - 完整字典值: `ACTIVE`=启用, `INACTIVE`=停用 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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（订单状态）：仪表盘中订单统计按状态分组展示 - - 完整字典值: `PENDING_PAY`=待支付, `DEPOSIT_PAID`=已付定金, `PAID`=已全额支付, `CONFIRMED`=已确认, `PENDING_BALANCE`=待付尾款, `PENDING_DEPARTURE`=待出行, `TRAVELLING`=旅行中, `COMPLETED`=已完成, `AFTER_SALES`=售后中, `CANCELLED`=已取消, `REFUNDING`=退款中, `REFUNDED`=已退款 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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 - - 完整字典值: `PENDING_PAY`=待支付, `DEPOSIT_PAID`=已付定金, `PAID`=已全额支付, `CONFIRMED`=已确认, `PENDING_BALANCE`=待付尾款, `PENDING_DEPARTURE`=待出行, `TRAVELLING`=旅行中, `COMPLETED`=已完成, `AFTER_SALES`=售后中, `CANCELLED`=已取消, `REFUNDING`=退款中, `REFUNDED`=已退款 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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 - - 完整字典值: `DRAFT`=草稿, `PENDING_REVIEW`=待审核, `REVIEWED`=已审核, `REJECTED`=已驳回, `PUBLISHED`=已上架, `UNPUBLISHED`=已下架, `COMPLETED`=已完成 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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=差评（筛选条件+列表展示） - - 完整字典值: `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 - - 完整字典值: `PENDING_PAY`=待支付, `DEPOSIT_PAID`=已付定金, `PAID`=已全额支付, `CONFIRMED`=已确认, `PENDING_BALANCE`=待付尾款, `PENDING_DEPARTURE`=待出行, `TRAVELLING`=旅行中, `COMPLETED`=已完成, `AFTER_SALES`=售后中, `CANCELLED`=已取消, `REFUNDING`=退款中, `REFUNDED`=已退款 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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 - - 完整字典值: `DRAFT`=草稿, `PENDING_REVIEW`=待审核, `REVIEWED`=已审核, `REJECTED`=已驳回, `PUBLISHED`=已上架, `UNPUBLISHED`=已下架, `COMPLETED`=已完成 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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=启用） - - 完整字典值: `ACTIVE`=启用, `INACTIVE`=停用 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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=保险同步 - - 完整字典值: `DEFAULT`=默认分组, `SYSTEM`=系统任务, `WECHAT`=企微同步, `INSURANCE`=保险同步 -- job_misfire_policy（执行策略）：DEFAULT=默认策略, FIRE_ONCE=立即触发一次, DO_NOTHING=不触发 - - 完整字典值: `DEFAULT`=默认策略, `FIRE_ONCE`=立即触发一次, `DO_NOTHING`=不触发 -- job_status（任务状态）：ACTIVE=启用, PAUSED=已暂停 - - 完整字典值: `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=保险同步 - - 完整字典值: `DEFAULT`=默认分组, `SYSTEM`=系统任务, `WECHAT`=企微同步, `INSURANCE`=保险同步 -- job_misfire_policy（执行策略）：DEFAULT=默认策略, FIRE_ONCE=立即触发一次, DO_NOTHING=不触发 - - 完整字典值: `DEFAULT`=默认策略, `FIRE_ONCE`=立即触发一次, `DO_NOTHING`=不触发 -- job_status（任务状态）：ACTIVE=启用, PAUSED=已暂停 - - 完整字典值: `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=保险同步 - - 完整字典值: `DEFAULT`=默认分组, `SYSTEM`=系统任务, `WECHAT`=企微同步, `INSURANCE`=保险同步 -- job_misfire_policy（执行策略）：DEFAULT=默认策略, FIRE_ONCE=立即触发一次, DO_NOTHING=不触发 - - 完整字典值: `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=已封禁） - - 完整字典值: `ACTIVE`=正常, `INACTIVE`=未激活, `BANNED`=已封禁, `DELETED`=已注销 -- gender（性别）：返回字段gender（0=女, 1=男） - - 完整字典值: `1`=男, `2`=女 -- id_card_type（证件类型）：返回字段idCardType - - 完整字典值: `ID_CARD`=身份证, `PASSPORT`=护照, `HK_MACAU_PASS`=港澳通行证, `TAIWAN_PASS`=台湾通行证, `MILITARY_ID`=军官证, `OTHER`=其他 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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 - - 完整字典值: `ACTIVE`=正常, `INACTIVE`=未激活, `BANNED`=已封禁, `DELETED`=已注销 -- gender（性别）：返回字段gender - - 完整字典值: `1`=男, `2`=女 -- id_card_type（证件类型）：返回字段idCardType - - 完整字典值: `ID_CARD`=身份证, `PASSPORT`=护照, `HK_MACAU_PASS`=港澳通行证, `TAIWAN_PASS`=台湾通行证, `MILITARY_ID`=军官证, `OTHER`=其他 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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，前端据此判断跳转到哪种资源详情页 - - 完整字典值: `PRODUCT`=产品, `SCENIC`=景区, `RESTAURANT`=餐厅, `ACTIVITY`=活动, `HOTEL`=酒店 - - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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） - - 完整字典值: `PRODUCT`=产品, `SCENIC`=景区, `RESTAURANT`=餐厅, `ACTIVITY`=活动, `HOTEL`=酒店 - - -**请求体** `收藏请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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） - - 完整字典值: `PRODUCT`=产品, `SCENIC`=景区, `RESTAURANT`=餐厅, `ACTIVITY`=活动, `HOTEL`=酒店 - - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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，前端据此判断跳转到哪种资源详情页 - - 完整字典值: `PRODUCT`=产品, `SCENIC`=景区, `RESTAURANT`=餐厅, `ACTIVITY`=活动, `HOTEL`=酒店 - - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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） - - 完整字典值: `PRODUCT`=产品, `SCENIC`=景区, `RESTAURANT`=餐厅, `ACTIVITY`=活动, `HOTEL`=酒店 - - -**请求体** `足迹请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=护照 - - 完整字典值: `ID_CARD`=身份证, `PASSPORT`=护照, `HK_MACAU_PASS`=港澳通行证, `TAIWAN_PASS`=台湾通行证, `MILITARY_ID`=军官证, `OTHER`=其他 -- gender（性别）：0=女, 1=男 - - 完整字典值: `1`=男, `2`=女 - - -**响应** `统一响应结果«用户信息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） - - 完整字典值: `ID_CARD`=身份证, `PASSPORT`=护照, `HK_MACAU_PASS`=港澳通行证, `TAIWAN_PASS`=台湾通行证, `MILITARY_ID`=军官证, `OTHER`=其他 -- gender（性别）：0=女, 1=男 - - 完整字典值: `1`=男, `2`=女 - - -**请求体** `更新用户资料请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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 - - 完整字典值: `1`=男, `2`=女 -- id_card_type（证件类型）：返回字段idCardType - - 完整字典值: `ID_CARD`=身份证, `PASSPORT`=护照, `HK_MACAU_PASS`=港澳通行证, `TAIWAN_PASS`=台湾通行证, `MILITARY_ID`=军官证, `OTHER`=其他 -- traveler_type（出行人类型）：返回字段travelerType - - 完整字典值: `ADULT`=成人, `CHILD`=儿童, `YOUNG_CHILD`=小童, `BABY`=幼童 - -**响应** `统一响应结果«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=男） - - 完整字典值: `1`=男, `2`=女 -- id_card_type（证件类型）：请求/返回字段idCardType（ID_CARD=身份证, PASSPORT=护照等） - - 完整字典值: `ID_CARD`=身份证, `PASSPORT`=护照, `HK_MACAU_PASS`=港澳通行证, `TAIWAN_PASS`=台湾通行证, `MILITARY_ID`=军官证, `OTHER`=其他 -- traveler_type（出行人类型）：返回字段travelerType（ADULT=成人, CHILD=儿童, INFANT=婴儿，自动计算） - - 完整字典值: `ADULT`=成人, `CHILD`=儿童, `YOUNG_CHILD`=小童, `BABY`=幼童 - -**请求体** `出行人请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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 - - 完整字典值: `1`=男, `2`=女 -- id_card_type（证件类型）：返回字段idCardType - - 完整字典值: `ID_CARD`=身份证, `PASSPORT`=护照, `HK_MACAU_PASS`=港澳通行证, `TAIWAN_PASS`=台湾通行证, `MILITARY_ID`=军官证, `OTHER`=其他 -- traveler_type（出行人类型）：返回字段travelerType - - 完整字典值: `ADULT`=成人, `CHILD`=儿童, `YOUNG_CHILD`=小童, `BABY`=幼童 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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 - - 完整字典值: `1`=男, `2`=女 -- id_card_type（证件类型）：请求/返回字段idCardType - - 完整字典值: `ID_CARD`=身份证, `PASSPORT`=护照, `HK_MACAU_PASS`=港澳通行证, `TAIWAN_PASS`=台湾通行证, `MILITARY_ID`=军官证, `OTHER`=其他 -- traveler_type（出行人类型）：返回字段travelerType（自动计算） - - 完整字典值: `ADULT`=成人, `CHILD`=儿童, `YOUNG_CHILD`=小童, `BABY`=幼童 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=启用） - - 完整字典值: `ACTIVE`=启用, `INACTIVE`=停用 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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=启用） - - 完整字典值: `ACTIVE`=启用, `INACTIVE`=停用 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=启用） - - 完整字典值: `ACTIVE`=启用, `INACTIVE`=停用 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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=启用） - - 完整字典值: `ACTIVE`=启用, `INACTIVE`=停用 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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 - -**管理员列表** - -分页查询管理员列表，支持按角色、状态、企微绑定状态、关键词筛选。keyword支持模糊匹配用户名和企业微信名称。status取值：ACTIVE=正常 LOCKED=已锁定 DISABLED=已禁用。wechatBound：true=已绑定企业微信 false=未绑定。需要管理员认证。 - -**关联字典**： -- admin_status（管理员状态）：ACTIVE=启用, LOCKED=锁定, DISABLED=禁用（筛选条件+列表展示） - - 完整字典值: `ACTIVE`=正常, `INACTIVE`=禁用, `LOCKED`=锁定, `DELETED`=已删除 - - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `keyword` | `string` | | 关键词（模糊匹配用户名/企业微信名称） | | -| `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=禁用 - - 完整字典值: `ACTIVE`=正常, `INACTIVE`=禁用, `LOCKED`=锁定, `DELETED`=已删除 - - -**请求体** `创建管理员请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=禁用 - - 完整字典值: `ACTIVE`=正常, `INACTIVE`=禁用, `LOCKED`=锁定, `DELETED`=已删除 - - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=禁用 - - 完整字典值: `ACTIVE`=正常, `INACTIVE`=禁用, `LOCKED`=锁定, `DELETED`=已删除 - - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=邮箱等） - - 完整字典值: `ABOUT`=关于我们, `ONLINE_CS`=在线客服, `PHONE`=电话咨询 -- common_status（通用状态）：请求参数status和返回字段status - - 完整字典值: `ACTIVE`=启用, `INACTIVE`=停用 - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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 - - 完整字典值: `ABOUT`=关于我们, `ONLINE_CS`=在线客服, `PHONE`=电话咨询 - -**请求体** `联系我们请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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 - - 完整字典值: `ABOUT`=关于我们, `ONLINE_CS`=在线客服, `PHONE`=电话咨询 -- common_status（通用状态）：返回字段status - - 完整字典值: `ACTIVE`=启用, `INACTIVE`=停用 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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 - - 完整字典值: `ABOUT`=关于我们, `ONLINE_CS`=在线客服, `PHONE`=电话咨询 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=按钮） - - 完整字典值: `D`=目录, `M`=菜单, `B`=按钮 -- common_status（通用状态）：返回字段status - - 完整字典值: `ACTIVE`=启用, `INACTIVE`=停用 - -**请求体** `创建菜单请求` - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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 - - 完整字典值: `D`=目录, `M`=菜单, `B`=按钮 -- common_status（通用状态）：返回字段status - - 完整字典值: `ACTIVE`=启用, `INACTIVE`=停用 - -**响应** `统一响应结果«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=按钮） - - 完整字典值: `D`=目录, `M`=菜单, `B`=按钮 -- common_status（通用状态）：返回字段status - - 完整字典值: `ACTIVE`=启用, `INACTIVE`=停用 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=按钮） - - 完整字典值: `D`=目录, `M`=菜单, `B`=按钮 -- common_status（通用状态）：请求字段status - - 完整字典值: `ACTIVE`=启用, `INACTIVE`=停用 - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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=禁用（筛选条件+列表展示） - - 完整字典值: `ACTIVE`=启用, `INACTIVE`=停用 - - -**查询参数** - -| 参数 | 类型 | 必填 | 说明 | 示例 | -| --- | --- | --- | --- | --- | -| `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=禁用 - - 完整字典值: `ACTIVE`=启用, `INACTIVE`=停用 - - -**路径参数** - -| 参数 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `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»` - ----