From fe9ee4d1e64a547edeb7e24e20d1801dc11cdf31 Mon Sep 17 00:00:00 2001
From: PIGCLOUD <wangiegie@gmail.com>
Date: Sun, 2 Aug 2026 23:27:00 +0800
Subject: [PATCH] =?UTF-8?q?fix(upms):=20=E6=9B=B4=E6=96=B0=E4=B8=8A?=
 =?UTF-8?q?=E4=BC=A0=E6=96=87=E4=BB=B6=E6=96=B9=E6=B3=95=E6=96=87=E6=A1=A3?=
 =?UTF-8?q?=EF=BC=8C=E5=A2=9E=E5=8A=A0=E8=B7=AF=E5=BE=84=E6=A0=A1=E9=AA=8C?=
 =?UTF-8?q?=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../service/impl/SysFileServiceImpl.java      | 26 ++++++++++++-------
 1 file changed, 17 insertions(+), 9 deletions(-)

diff --git a/pigx-upms/pigx-upms-biz/src/main/java/com/pig4cloud/pigx/admin/service/impl/SysFileServiceImpl.java b/pigx-upms/pigx-upms-biz/src/main/java/com/pig4cloud/pigx/admin/service/impl/SysFileServiceImpl.java
index 9042da0f3..2ca659108 100644
--- a/pigx-upms/pigx-upms-biz/src/main/java/com/pig4cloud/pigx/admin/service/impl/SysFileServiceImpl.java
+++ b/pigx-upms/pigx-upms-biz/src/main/java/com/pig4cloud/pigx/admin/service/impl/SysFileServiceImpl.java
@@ -77,14 +77,18 @@ public class SysFileServiceImpl extends ServiceImpl<SysFileMapper, SysFile> impl
     private final FileProperties properties;
 
     /**
-     * 上传文件
+     * 上传文件到当前配置的存储桶，并写入文件管理记录。
+     * <p>
+     * {@code fileName} 为空时按 UUID 生成存储名；本地存储模式下会校验路径不得逃逸存储根目录。
+     * </p>
      *
-     * @param file     文件流
-     * @param fileName
-     * @param dir      文件夹
-     * @param groupId  分组ID
-     * @param type     类型
-     * @return
+     * @param file     上传文件流，不可为 {@code null}
+     * @param fileName 目标存储文件名；为空时自动生成（无扩展名时不追加尾部点号）
+     * @param dir      相对目录，可为空表示桶根路径
+     * @param groupId  文件分组 ID，可为空
+     * @param type     业务文件类型标识，可为空
+     * @return 成功时 data 含 {@code bucketName}、{@code fileName}、{@code url}；
+     * 路径非法返回失败（{@code sys.file.path.invalid}），上传异常返回失败（{@code sys.file.upload.failed}）
      */
     @Override
     public R uploadFile(MultipartFile file, String fileName, String dir, Long groupId, String type) {
@@ -297,10 +301,14 @@ public class SysFileServiceImpl extends ServiceImpl<SysFileMapper, SysFile> impl
 
     /**
      * 校验文件存储路径，确保文件始终位于配置的存储桶目录内。
+     * <p>
+     * 仅本地存储（{@link FileType#LOCAL}）生效；非本地类型直接返回。
+     * </p>
      *
      * @param bucketName 存储桶名称
-     * @param dir 相对目录
-     * @param fileName 文件名
+     * @param dir        相对目录，可为空
+     * @param fileName   文件名
+     * @throws IllegalArgumentException 本地 {@code basePath} 为空，或路径存在目录穿越时抛出
      */
     private void validateStoragePath(String bucketName, String dir, String fileName) {
         if (properties.getType() != FileType.LOCAL) {