From a8d7e79264db868ef348fe2f2badf3263c922295 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Tue, 17 Mar 2026 09:51:48 +0800 Subject: [PATCH] docs: 2026-03/17_0951 sync 13 services (0 breaking) --- 2026-03/17_0951/CHANGES.md | 5 + 2026-03/17_0951/hl-contract-service.md | 793 ++++++ 2026-03/17_0951/hl-file-service.md | 331 +++ 2026-03/17_0951/hl-guide-service.md | 727 +++++ 2026-03/17_0951/hl-material-service.md | 968 +++++++ 2026-03/17_0951/hl-monitor-service.md | 553 ++++ 2026-03/17_0951/hl-mp-service.md | 3634 ++++++++++++++++++++++++ 2026-03/17_0951/hl-payment-service.md | 282 ++ 2026-03/17_0951/hl-review-service.md | 236 ++ 2026-03/17_0951/hl-task-service.md | 924 ++++++ 10 files changed, 8453 insertions(+) create mode 100644 2026-03/17_0951/CHANGES.md create mode 100644 2026-03/17_0951/hl-contract-service.md create mode 100644 2026-03/17_0951/hl-file-service.md create mode 100644 2026-03/17_0951/hl-guide-service.md create mode 100644 2026-03/17_0951/hl-material-service.md create mode 100644 2026-03/17_0951/hl-monitor-service.md create mode 100644 2026-03/17_0951/hl-mp-service.md create mode 100644 2026-03/17_0951/hl-payment-service.md create mode 100644 2026-03/17_0951/hl-review-service.md create mode 100644 2026-03/17_0951/hl-task-service.md diff --git a/2026-03/17_0951/CHANGES.md b/2026-03/17_0951/CHANGES.md new file mode 100644 index 0000000..643dce0 --- /dev/null +++ b/2026-03/17_0951/CHANGES.md @@ -0,0 +1,5 @@ +# 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 new file mode 100644 index 0000000..7c4fc19 --- /dev/null +++ b/2026-03/17_0951/hl-contract-service.md @@ -0,0 +1,793 @@ +# 合同服务 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 new file mode 100644 index 0000000..7c17ab6 --- /dev/null +++ b/2026-03/17_0951/hl-file-service.md @@ -0,0 +1,331 @@ +# 文件服务 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 new file mode 100644 index 0000000..d01c9cc --- /dev/null +++ b/2026-03/17_0951/hl-guide-service.md @@ -0,0 +1,727 @@ +# 攻略服务 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 new file mode 100644 index 0000000..c8ed7fb --- /dev/null +++ b/2026-03/17_0951/hl-material-service.md @@ -0,0 +1,968 @@ +# 素材服务 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 new file mode 100644 index 0000000..188a26a --- /dev/null +++ b/2026-03/17_0951/hl-monitor-service.md @@ -0,0 +1,553 @@ +# 监控服务 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 new file mode 100644 index 0000000..720fbe0 --- /dev/null +++ b/2026-03/17_0951/hl-mp-service.md @@ -0,0 +1,3634 @@ +# 小程序聚合服务 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-payment-service.md b/2026-03/17_0951/hl-payment-service.md new file mode 100644 index 0000000..9982afc --- /dev/null +++ b/2026-03/17_0951/hl-payment-service.md @@ -0,0 +1,282 @@ +# 支付服务 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-review-service.md b/2026-03/17_0951/hl-review-service.md new file mode 100644 index 0000000..dbb2fda --- /dev/null +++ b/2026-03/17_0951/hl-review-service.md @@ -0,0 +1,236 @@ +# 评价服务 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 new file mode 100644 index 0000000..0631450 --- /dev/null +++ b/2026-03/17_0951/hl-task-service.md @@ -0,0 +1,924 @@ +# 任务服务 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` | | 响应消息 | + +---