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) {