\App\Http\Controllers\AdminMaintainFileController

文件维护控制器

职责：文件库模块全部 HTTP 接口的入口——文件/目录/公共目录/上传下载/回收站/批量操作，校验入参、编排服务、组装统一响应，业务下沉 MaintainFileService；下载/预览的 StreamedResponse 在本层组装（Service 只回文件指针信息）。

┌────────────────── 分区导航（按此顺序阅读）──────────────────┐ 分区 1 · 文件列表 index 分区 2 · 目录管理 folders / folderStore / folderUpdate / folderDestroy 分区 3 · 公共目录 publicFolderStore / publicFolderUpdate / publicFolderDestroy 分区 4 · 场景与用量 scenes / usage 分区 5 · 预览与下载 preview / download 分区 6 · 反向引用 refs 分区 7 · 上传 store 分区 8 · 元信息更新 update 分区 9 · 回收站 destroy / forceDestroy / restore / purgeTrash 分区 10 · 批量操作 batch 分区 11 · 单文件操作 rename / move / copy └────────────────────────────────────────────────────────────┘

Summary

Methods

Properties

Constants

__construct()
index()
folders()
folderStore()
folderUpdate()
folderDestroy()
publicFolderStore()
publicFolderUpdate()
publicFolderDestroy()
scenes()
usage()
userStats()
overview()
duplicates()
danglingRefs()
preview()
download()
refs()
store()
update()
destroy()
forceDestroy()
restore()
purgeTrash()
batch()
rename()
move()
copy()

No public properties found

No constants found

No protected methods found

No protected properties found

N/A

No private methods found

$fileService

N/A

File: Backend-Admin-PHP/app/Http/Controllers/Admin/MaintainFileController.php
Package: Application
Class hierarchy: \App\Http\Controllers\Controller

\App\Http\Controllers\Admin\MaintainFileController
Uses traits: \App\Http\Controllers\Concerns\ManagesFolders
Uses

Tags

None found

Properties

$fileService

$fileService : \App\Services\Admin\MaintainFileService

Type

MaintainFileService

Methods

__construct()

__construct(\App\Services\Admin\MaintainFileService  $fileService) : mixed

Parameters

\App\Services\Admin\MaintainFileService

$fileService

Returns

mixed —

index()

index(\App\Http\Requests\Admin\MaintainFileIndexRequest  $request) : \Illuminate\Http\JsonResponse

文件列表

status=trash 时返回回收站内容。

Parameters

\App\Http\Requests\Admin\MaintainFileIndexRequest

$request

Returns

\Illuminate\Http\JsonResponse —

folders()

folders(\Illuminate\Http\Request  $request) : \Illuminate\Http\JsonResponse

目录列表

返回双分区目录数据： personal 为个人空间目录树，平铺结构，附每目录文件计数，豁免管理员传 user_id 可查看任意用户；public 为公共空间目录树，user_id=0，全员可见，附 is_public/can_write 标记；can_manage_public 表示操作者对公共空间的完整管理权。

Parameters

\Illuminate\Http\Request

$request

Returns

\Illuminate\Http\JsonResponse —

folderStore()

folderStore(\App\Http\Requests\Admin\MaintainFileRequest  $request) : \Illuminate\Http\JsonResponse

新建目录

在个人空间新建逻辑目录：同级重名拦截，父级须为本人目录（单源 ManagesFolders）。

Parameters

\App\Http\Requests\Admin\MaintainFileRequest

$request

Returns

\Illuminate\Http\JsonResponse —

Inherited from: \App\Http\Controllers\Admin\MaintainFileController
Uses

Tags

requestMediaType	application/json 说明：JSON 请求体（复用含 file 校验的 Request 类会被 Scramble 误判为 multipart，此处显式标注）

folderUpdate()

folderUpdate(\App\Http\Requests\Admin\MaintainFileRequest  $request, \App\Models\SysFileFolder  $folder) : \Illuminate\Http\JsonResponse

更新目录

支持重命名、移父级与同级排序；目录名同级不可重复（单源 ManagesFolders）。

Parameters

\App\Http\Requests\Admin\MaintainFileRequest	$request
\App\Models\SysFileFolder	$folder

Returns

\Illuminate\Http\JsonResponse —

Inherited from: \App\Http\Controllers\Admin\MaintainFileController
Uses

Tags

requestMediaType	application/json 说明：JSON 请求体（复用含 file 校验的 Request 类会被 Scramble 误判为 multipart，此处显式标注）

folderDestroy()

folderDestroy(\App\Models\SysFileFolder  $folder) : \Illuminate\Http\JsonResponse

删除目录

仅空目录允许删除，目录下仍有子目录或文件时拒绝（单源 ManagesFolders）。

Parameters

\App\Models\SysFileFolder

$folder

Returns

\Illuminate\Http\JsonResponse —

publicFolderStore()

publicFolderStore(\App\Http\Requests\Admin\MaintainFileRequest  $request) : \Illuminate\Http\JsonResponse

新建公共目录

仅豁免管理员或公共目录维护标志用户可建，权限由 Service 校验。

Parameters

\App\Http\Requests\Admin\MaintainFileRequest

$request

Returns

\Illuminate\Http\JsonResponse —

Inherited from: \App\Http\Controllers\Admin\MaintainFileController
Uses

Tags

requestMediaType	application/json 说明：JSON 请求体（复用含 file 校验的 Request 类会被 Scramble 误判为 multipart，此处显式标注）

publicFolderUpdate()

publicFolderUpdate(\App\Http\Requests\Admin\MaintainFileRequest  $request, \App\Models\SysFileFolder  $folder) : \Illuminate\Http\JsonResponse

更新公共目录

支持重命名、移父级、排序与启停。

Parameters

\App\Http\Requests\Admin\MaintainFileRequest	$request
\App\Models\SysFileFolder	$folder

Returns

\Illuminate\Http\JsonResponse —

Inherited from: \App\Http\Controllers\Admin\MaintainFileController
Uses

Tags

requestMediaType	application/json 说明：JSON 请求体（复用含 file 校验的 Request 类会被 Scramble 误判为 multipart，此处显式标注）

publicFolderDestroy()

publicFolderDestroy(\App\Models\SysFileFolder  $folder) : \Illuminate\Http\JsonResponse

删除公共目录

仅空目录允许删除，目录下仍有子目录或文件时拒绝。

Parameters

\App\Models\SysFileFolder

$folder

Returns

\Illuminate\Http\JsonResponse —

scenes()

scenes() : \Illuminate\Http\JsonResponse

上传场景清单

下发 FileScene 注册表全部场景，供管理页场景筛选项与上传归属使用。

Returns

\Illuminate\Http\JsonResponse —

usage()

usage(\Illuminate\Http\Request  $request) : \Illuminate\Http\JsonResponse

空间用量

返回我的空间用量：总大小与文件数，并附按文件类型分段统计。

Parameters

\Illuminate\Http\Request

$request

Returns

\Illuminate\Http\JsonResponse —

userStats()

userStats() : \Illuminate\Http\JsonResponse

全站用户文件统计

平台全局视角的用户导航数据源：每用户文件数/总大小（仅豁免管理员）。

Returns

\Illuminate\Http\JsonResponse —

overview()

overview() : \Illuminate\Http\JsonResponse

全站文件概览

运维台账顶栏聚合：总量/今日新增/回收站/上传者数/孤儿文件（仅豁免管理员）。

Returns

\Illuminate\Http\JsonResponse —

duplicates()

duplicates() : \Illuminate\Http\JsonResponse

全站重复文件

内容哈希聚族的重复文件清单与浪费空间汇总（仅豁免管理员）。

Returns

\Illuminate\Http\JsonResponse —

danglingRefs()

danglingRefs() : \Illuminate\Http\JsonResponse

配置侧悬空引用

引用了回收站/已删除文件的配置项清单（仅豁免管理员）。

Returns

\Illuminate\Http\JsonResponse —

preview()

preview(\App\Models\SysFile  $file, \Illuminate\Http\Request  $request) : \Symfony\Component\HttpFoundation\StreamedResponse|\Illuminate\Http\JsonResponse

图片内联预览

?variant=thumb 取缩略图，缺省取原图；网格/列表缩略图与 Quick Look 原图经此端点，同源 Cookie 天然携带。Service 回文件指针信息， StreamedResponse 在本层组装（单源 streamFile 编排）。

Parameters

\App\Models\SysFile	$file
\Illuminate\Http\Request	$request

Returns

\Symfony\Component\HttpFoundation\StreamedResponse|\Illuminate\Http\JsonResponse —

download()

download(\App\Models\SysFile  $file) : \Symfony\Component\HttpFoundation\StreamedResponse|\Illuminate\Http\JsonResponse

下载文件

私有盘鉴权下载：需登录且归属校验通过，豁免或本人可下；响应强制附件方式不内联渲染。Service 回文件指针信息， StreamedResponse 在本层组装（单源 streamFile 编排）。

Parameters

\App\Models\SysFile

$file

Returns

\Symfony\Component\HttpFoundation\StreamedResponse|\Illuminate\Http\JsonResponse —

refs()

refs(\App\Models\SysFile  $file) : \Illuminate\Http\JsonResponse

文件反向引用

返回引用了该文件的配置项清单，删除文件前确认引用关系用。

Parameters

\App\Models\SysFile

$file

Returns

\Illuminate\Http\JsonResponse —

store()

store(\App\Http\Requests\Admin\MaintainFileRequest  $request) : \Illuminate\Http\JsonResponse

上传文件

上传文件到个人空间：按 file_type 分类归档，scene 记录上传场景归属，文件经安全净化后落盘，图片自动生成缩略图。

Parameters

\App\Http\Requests\Admin\MaintainFileRequest

$request

Returns

\Illuminate\Http\JsonResponse —

update()

update(\App\Http\Requests\Admin\MaintainFileRequest  $request, \App\Models\SysFile  $file) : \Illuminate\Http\JsonResponse

更新文件元信息

更新文件分类与标签，不触碰物理文件；分类必须落在文件分类白名单内。

Parameters

\App\Http\Requests\Admin\MaintainFileRequest	$request
\App\Models\SysFile	$file

Returns

\Illuminate\Http\JsonResponse —

Inherited from: \App\Http\Controllers\Admin\MaintainFileController
Uses

Tags

requestMediaType	application/json 说明：JSON 请求体（复用含 file 校验的 Request 类会被 Scramble 误判为 multipart，此处显式标注）

destroy()

destroy(\App\Models\SysFile  $file) : \Illuminate\Http\JsonResponse

移入回收站

软删除：文件进入回收站，保留物理文件与记录，可恢复或彻底删除。

Parameters

\App\Models\SysFile

$file

Returns

\Illuminate\Http\JsonResponse —

forceDestroy()

forceDestroy(\App\Models\SysFile  $file) : \Illuminate\Http\JsonResponse

彻底删除

物理删除文件与记录，仅回收站内文件可执行，删除后不可恢复。

Parameters

\App\Models\SysFile

$file

Returns

\Illuminate\Http\JsonResponse —

restore()

restore(\App\Models\SysFile  $file) : \Illuminate\Http\JsonResponse

从回收站恢复

将回收站文件恢复为正常状态，重新出现在原目录。

Parameters

\App\Models\SysFile

$file

Returns

\Illuminate\Http\JsonResponse —

purgeTrash()

purgeTrash() : \Illuminate\Http\JsonResponse

清空回收站

物理删除回收站内全部文件，操作不可恢复，返回清理数量。

Returns

\Illuminate\Http\JsonResponse —

batch()

batch(\App\Http\Requests\Admin\MaintainFileRequest  $request) : \Illuminate\Http\JsonResponse

批量操作

无权限操作的 id 会被跳过，并在响应中说明 skipped 数量。

Parameters

\App\Http\Requests\Admin\MaintainFileRequest

$request

Returns

\Illuminate\Http\JsonResponse —

Inherited from: \App\Http\Controllers\Admin\MaintainFileController
Uses

Tags

requestMediaType	application/json 说明：JSON 请求体（复用含 file 校验的 Request 类会被 Scramble 误判为 multipart，此处显式标注）

rename()

rename(\App\Http\Requests\Admin\MaintainFileRequest  $request, \App\Models\SysFile  $file) : \Illuminate\Http\JsonResponse

重命名

修改文件名，仅动记录不动物理文件；同目录下文件名不可重复。

Parameters

\App\Http\Requests\Admin\MaintainFileRequest	$request
\App\Models\SysFile	$file

Returns

\Illuminate\Http\JsonResponse —

Inherited from: \App\Http\Controllers\Admin\MaintainFileController
Uses

Tags

requestMediaType	application/json 说明：JSON 请求体（复用含 file 校验的 Request 类会被 Scramble 误判为 multipart，此处显式标注）

move()

move(\App\Http\Requests\Admin\MaintainFileRequest  $request, \App\Models\SysFile  $file) : \Illuminate\Http\JsonResponse

移动文件到目录

逻辑层操作：只改 folder_id 归属，物理路径不动。

Parameters

\App\Http\Requests\Admin\MaintainFileRequest	$request
\App\Models\SysFile	$file

Returns

\Illuminate\Http\JsonResponse —

Inherited from: \App\Http\Controllers\Admin\MaintainFileController
Uses

Tags

requestMediaType	application/json 说明：JSON 请求体（复用含 file 校验的 Request 类会被 Scramble 误判为 multipart，此处显式标注）

copy()

copy(\App\Models\SysFile  $file) : \Illuminate\Http\JsonResponse

复制文件

复制生成新文件记录，物理文件复用存储，同目录新副本。

Parameters

\App\Models\SysFile

$file

Returns

\Illuminate\Http\JsonResponse —