969 行
37 KiB
Markdown
969 行
37 KiB
Markdown
# 素材服务 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»`
|
||
|
||
---
|