docs: 2026-03/17_0958 sync 13 services (0 breaking)
这个提交包含在：
API Changelog Bot
父节点
a8d7e79264
当前提交
60ef4ba1a8
文件差异内容过多而无法显示
加载差异
11
2026-03/17_0958/CHANGES.md
普通文件
11
2026-03/17_0958/CHANGES.md
普通文件
@ -0,0 +1,11 @@
|
||||
# API 变更通知
|
||||
|
||||
**更新时间**: 2026-03-17 09:58
|
||||
|
||||
## ℹ️ 新增 (1)
|
||||
|
||||
### 用户服务
|
||||
|
||||
**新增参数**
|
||||
|
||||
- `GET /admin/user` 新增参数 `keyword`
|
||||
@ -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` | | 响应消息 |
|
||||
|
||||
---
|
||||
331
2026-03/17_0958/hl-file-service.md
普通文件
331
2026-03/17_0958/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` | | 响应消息 |
|
||||
|
||||
---
|
||||
727
2026-03/17_0958/hl-guide-service.md
普通文件
727
2026-03/17_0958/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»`
|
||||
|
||||
---
|
||||
@ -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»`
|
||||
|
||||
---
|
||||
@ -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` | | 响应消息 |
|
||||
|
||||
---
|
||||
3634
2026-03/17_0958/hl-mp-service.md
普通文件
3634
2026-03/17_0958/hl-mp-service.md
普通文件
文件差异内容过多而无法显示
加载差异
3594
2026-03/17_0958/hl-order-service.md
普通文件
3594
2026-03/17_0958/hl-order-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` | | 响应消息 |
|
||||
|
||||
---
|
||||
5188
2026-03/17_0958/hl-product-service.md
普通文件
5188
2026-03/17_0958/hl-product-service.md
普通文件
文件差异内容过多而无法显示
加载差异
6998
2026-03/17_0958/hl-resource-service.md
普通文件
6998
2026-03/17_0958/hl-resource-service.md
普通文件
文件差异内容过多而无法显示
加载差异
236
2026-03/17_0958/hl-review-service.md
普通文件
236
2026-03/17_0958/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»`
|
||||
|
||||
---
|
||||
924
2026-03/17_0958/hl-task-service.md
普通文件
924
2026-03/17_0958/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` | | 响应消息 |
|
||||
|
||||
---
|
||||
4502
2026-03/17_0958/hl-user-service.md
普通文件
4502
2026-03/17_0958/hl-user-service.md
普通文件
文件差异内容过多而无法显示
加载差异
正在加载...
x
在新工单中引用
屏蔽一个用户