# 素材服务 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»`

---