更新统一使用 PHPDoc + PSR-19 标准注释

app/http/admin/controller/file/FileRecordController.php

@@ -3,6 +3,7 @@
 namespace app\http\admin\controller\file;
 
 use app\common\base\BaseController;
+use app\exception\ValidationException;
 use app\http\admin\validation\FileRecordValidator;
 use app\service\file\FileRecordService;
 use Webman\Http\UploadFile;
@@ -11,14 +12,28 @@ use support\Response;
 
 /**
  * 文件控制器。
+ *
+ * @property FileRecordService $fileRecordService 文件记录服务
  */
 class FileRecordController extends BaseController
 {
+    /**
+ * 构造方法。
+     *
+     * @param FileRecordService $fileRecordService 文件记录服务
+     * @return void
+     */
     public function __construct(
         protected FileRecordService $fileRecordService
     ) {
     }
 
+    /**
+     * 查询文件记录列表
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
     public function index(Request $request): Response
     {
         $data = $this->validated($request->all(), FileRecordValidator::class, 'index');
@@ -32,11 +47,24 @@ class FileRecordController extends BaseController
         );
     }
 
+    /**
+     * 获取文件记录选项
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
     public function options(Request $request): Response
     {
         return $this->success($this->fileRecordService->options());
     }
 
+    /**
+     * 查询文件记录详情
+     *
+     * @param Request $request 请求对象
+     * @param string $id 文件记录ID
+     * @return Response 响应对象
+     */
     public function show(Request $request, string $id): Response
     {
         $data = $this->validated(['id' => (int) $id], FileRecordValidator::class, 'show');
@@ -44,12 +72,19 @@ class FileRecordController extends BaseController
         return $this->success($this->fileRecordService->detail((int) $data['id']));
     }
 
+    /**
+     * 上传文件记录
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     * @throws ValidationException
+     */
     public function upload(Request $request): Response
     {
         $data = $this->validated(array_merge($this->payload($request), ['scene' => $request->input('scene')]), FileRecordValidator::class, 'store');
         $uploadedFile = $request->file('file');
         if ($uploadedFile === null) {
-            return $this->fail('请先选择上传文件', 400);
+            throw new ValidationException('请先选择上传文件');
         }
 
         $createdBy = $this->currentAdminId($request);
@@ -63,6 +98,10 @@ class FileRecordController extends BaseController
                 }
             }
 
+            if ($items === []) {
+                throw new ValidationException('上传文件无效');
+            }
+
             return $this->success([
                 'list' => $items,
                 'total' => count($items),
@@ -70,12 +109,18 @@ class FileRecordController extends BaseController
         }
 
         if (!$uploadedFile instanceof UploadFile) {
-            return $this->fail('上传文件无效', 400);
+            throw new ValidationException('上传文件无效');
         }
 
         return $this->success($this->fileRecordService->upload($uploadedFile, $data, $createdBy, $createdByName));
     }
 
+    /**
+     * 导入远程文件记录
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
     public function importRemote(Request $request): Response
     {
         $data = $this->validated($this->payload($request), FileRecordValidator::class, 'importRemote');
@@ -92,6 +137,13 @@ class FileRecordController extends BaseController
         );
     }
 
+    /**
+     * 获取文件预览响应。
+     *
+     * @param Request $request 请求对象
+     * @param string $id 文件记录ID
+     * @return Response 响应对象
+     */
     public function preview(Request $request, string $id): Response
     {
         $data = $this->validated(['id' => (int) $id], FileRecordValidator::class, 'preview');
@@ -99,6 +151,13 @@ class FileRecordController extends BaseController
         return $this->fileRecordService->previewResponse((int) $data['id']);
     }
 
+    /**
+     * 获取文件下载响应。
+     *
+     * @param Request $request 请求对象
+     * @param string $id 文件记录ID
+     * @return Response 响应对象
+     */
     public function download(Request $request, string $id): Response
     {
         $data = $this->validated(['id' => (int) $id], FileRecordValidator::class, 'download');
@@ -106,13 +165,23 @@ class FileRecordController extends BaseController
         return $this->fileRecordService->downloadResponse((int) $data['id']);
     }
 
+    /**
+     * 删除文件记录
+     *
+     * @param Request $request 请求对象
+     * @param string $id 文件记录ID
+     * @return Response 响应对象
+     */
     public function destroy(Request $request, string $id): Response
     {
         $data = $this->validated(['id' => (int) $id], FileRecordValidator::class, 'destroy');
-        if (!$this->fileRecordService->delete((int) $data['id'])) {
-            return $this->fail('文件不存在', 404);
-        }
+        $this->fileRecordService->delete((int) $data['id']);
 
         return $this->success(true);
     }
 }
+
+
+
+
+