feat: 完善媒体管理与备份迁移流程

- 视频上传生成缩略图并提供占位封面和失败原因展示
- 支持 HLS 按需重新封装 MP4，并限制临时文件生命周期与访问权限
- 完善视频、文件 API 文档、搜索、批量删除和单次转码质量参数
- 修复备份恢复与跨后端迁移遗漏缩略图、HLS 清单和分片的问题
- 将备份任务、归档和下载权限按用户隔离
- 增加仅清理当前用户数据的高危存储清空流程和二次文字确认
- 修复 S3 中文文件名元数据及 CLI 数据库连接问题
- 补充备份恢复、用户隔离、媒体资源和转码相关测试

server/api/files/index.get.ts

@@ -1,3 +1,4 @@
+import type { H3Event } from 'h3'
 import type { FileListResponse } from '~/types/file'
 import type { MediaType, TranscodeStatus } from '../../utils/storage/types'
 import { requireApiOrAdminAuth, getImageUserFilter } from '../../utils/access'
@@ -21,7 +22,10 @@ import {
 } from '../../utils/image-query'
 import { listImages, searchImages } from '../../utils/storage'
 
-export default defineEventHandler(async (event) => {
+export async function handleFileList(
+  event: H3Event,
+  forcedKind?: MediaType
+): Promise<FileListResponse> {
   await requireApiOrAdminAuth(event)
 
   const query = getQuery(event)
@@ -51,7 +55,7 @@ export default defineEventHandler(async (event) => {
   }
 
   // 文件床按类型分工：视频库看 media_type=video，文件库看 media_type=file
-  const kindRaw = typeof query.kind === 'string' ? query.kind.trim() : ''
+  const kindRaw = forcedKind ?? (typeof query.kind === 'string' ? query.kind.trim() : '')
   if (kindRaw && kindRaw !== 'file' && kindRaw !== 'video') {
     createApiError(event, 'INVALID_REQUEST', '无效的文件类型筛选', 400)
   }
@@ -111,6 +115,7 @@ export default defineEventHandler(async (event) => {
       ...(uploadSource === 'web' || uploadSource === 'api' ? { uploadSource } : {}),
       transcodeStatus: stored.transcodeStatus ?? 'none',
       transcodeProgress: stored.transcodeProgress ?? 0,
+      ...(stored.transcodeError ? { transcodeError: stored.transcodeError } : {}),
       ...(stored.transcodePreset ? { transcodePreset: stored.transcodePreset } : {}),
       ...(stored.sourceDeleted ? { sourceDeleted: true } : {}),
       ...(stored.thumbKey
@@ -138,4 +143,6 @@ export default defineEventHandler(async (event) => {
   }
 
   return response
-})
+}
+
+export default defineEventHandler(handleFileList)