wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态
hl-api-changelog/2026-03/17_0958/hl-material-service.md
API Changelog Bot 60ef4ba1a8 docs: 2026-03/17_0958 sync 13 services (0 breaking)
2026-03-17 09:58:52 +08:00

37 KiB
原始文件 Blame 文件历史

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