!483 同步cloud版本

Merge pull request !483 from AprilWind/dev-docs

ruoyi-admin/src/main/java/org/dromara/web/controller/CaptchaController.java

@@ -120,6 +120,7 @@ public class CaptchaController {
         AbstractCaptcha captcha = SpringUtils.getBean(captchaProperties.getCategory().getClazz());
         captcha.setGenerator(codeGenerator);
         captcha.createCode();
+        // 如果是数学验证码，使用SpEL表达式处理验证码结果
         String code = captcha.getCode();
         if (isMath) {
             ExpressionParser parser = new SpelExpressionParser();

ruoyi-admin/src/main/java/org/dromara/web/domain/vo/TenantListVo.java

@@ -13,10 +13,19 @@ import lombok.Data;
 @AutoMapper(target = SysTenantVo.class)
 public class TenantListVo {
 
+    /**
+     * 租户编号
+     */
     private String tenantId;
 
+    /**
+     * 企业名称
+     */
     private String companyName;
 
+    /**
+     * 域名
+     */
     private String domain;
 
 }

ruoyi-admin/src/main/java/org/dromara/web/service/IAuthStrategy.java

@@ -18,6 +18,11 @@ public interface IAuthStrategy {
 
     /**
      * 登录
+     *
+     * @param body      登录对象
+     * @param client    授权管理视图对象
+     * @param grantType 授权类型
+     * @return 登录验证信息
      */
     static LoginVo login(String body, SysClientVo client, String grantType) {
         // 授权类型和客户端id
@@ -31,6 +36,10 @@ public interface IAuthStrategy {
 
     /**
      * 登录
+     *
+     * @param body   登录对象
+     * @param client 授权管理视图对象
+     * @return 登录验证信息
      */
     LoginVo login(String body, SysClientVo client);
 

ruoyi-common/ruoyi-common-core/src/main/java/org/dromara/common/core/service/UserService.java

@@ -23,4 +23,20 @@ public interface UserService {
      */
     String selectNicknameById(Long userId);
 
+    /**
+     * 通过用户ID查询用户手机号
+     *
+     * @param userId 用户id
+     * @return 用户手机号
+     */
+    String selectPhonenumberById(Long userId);
+
+    /**
+     * 通过用户ID查询用户邮箱
+     *
+     * @param userId 用户id
+     * @return 用户邮箱
+     */
+    String selectEmailById(Long userId);
+
 }

ruoyi-common/ruoyi-common-satoken/src/main/java/org/dromara/common/satoken/utils/LoginHelper.java

@@ -101,13 +101,18 @@ public class LoginHelper {
         return Convert.toLong(getExtra(DEPT_KEY));
     }
 
+    /**
+     * 获取当前 Token 的扩展信息
+     *
+     * @param key 键值
+     * @return 对应的扩展数据
+     */
     private static Object getExtra(String key) {
         try {
             return StpUtil.getExtra(key);
         } catch (Exception e) {
             return null;
         }
-
     }
 
     /**
@@ -135,12 +140,17 @@ public class LoginHelper {
         return UserConstants.SUPER_ADMIN_ID.equals(userId);
     }
 
+    /**
+     * 是否为超级管理员
+     *
+     * @return 结果
+     */
     public static boolean isSuperAdmin() {
         return isSuperAdmin(getUserId());
     }
 
     /**
-     * 是否为超级管理员
+     * 是否为租户管理员
      *
      * @param rolePermission 角色权限标识组
      * @return 结果
@@ -149,10 +159,20 @@ public class LoginHelper {
         return rolePermission.contains(TenantConstants.TENANT_ADMIN_ROLE_KEY);
     }
 
+    /**
+     * 是否为租户管理员
+     *
+     * @return 结果
+     */
     public static boolean isTenantAdmin() {
         return Convert.toBool(isTenantAdmin(getLoginUser().getRolePermission()));
     }
 
+    /**
+     * 检查当前用户是否已登录
+     *
+     * @return 结果
+     */
     public static boolean isLogin() {
         return getLoginUser() != null;
     }

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysOssConfigService.java

@@ -31,12 +31,11 @@ public interface ISysOssConfigService {
      */
     TableDataInfo<SysOssConfigVo> queryPageList(SysOssConfigBo bo, PageQuery pageQuery);
 
-
     /**
      * 根据新增业务对象插入对象存储配置
      *
      * @param bo 对象存储配置新增业务对象
-     * @return
+     * @return 结果
      */
     Boolean insertByBo(SysOssConfigBo bo);
 
@@ -44,7 +43,7 @@ public interface ISysOssConfigService {
      * 根据编辑业务对象修改对象存储配置
      *
      * @param bo 对象存储配置编辑业务对象
-     * @return
+     * @return 结果
      */
     Boolean updateByBo(SysOssConfigBo bo);
 
@@ -53,7 +52,7 @@ public interface ISysOssConfigService {
      *
      * @param ids     主键集合
      * @param isValid 是否校验,true-删除前校验,false-不校验
-     * @return
+     * @return 结果
      */
     Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid);
 

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysOssService.java

@@ -19,18 +19,62 @@ import java.util.List;
  */
 public interface ISysOssService {
 
+    /**
+     * 查询OSS对象存储列表
+     *
+     * @param sysOss    OSS对象存储分页查询对象
+     * @param pageQuery 分页查询实体类
+     * @return 结果
+     */
     TableDataInfo<SysOssVo> queryPageList(SysOssBo sysOss, PageQuery pageQuery);
 
+    /**
+     * 根据一组 ossIds 获取对应的 SysOssVo 列表
+     *
+     * @param ossIds 一组文件在数据库中的唯一标识集合
+     * @return 包含 SysOssVo 对象的列表
+     */
     List<SysOssVo> listByIds(Collection<Long> ossIds);
 
+    /**
+     * 根据 ossId 从缓存或数据库中获取 SysOssVo 对象
+     *
+     * @param ossId 文件在数据库中的唯一标识
+     * @return SysOssVo 对象，包含文件信息
+     */
     SysOssVo getById(Long ossId);
 
+    /**
+     * 上传 MultipartFile 到对象存储服务，并保存文件信息到数据库
+     *
+     * @param file 要上传的 MultipartFile 对象
+     * @return 上传成功后的 SysOssVo 对象，包含文件信息
+     */
     SysOssVo upload(MultipartFile file);
 
+    /**
+     * 上传文件到对象存储服务，并保存文件信息到数据库
+     *
+     * @param file 要上传的文件对象
+     * @return 上传成功后的 SysOssVo 对象，包含文件信息
+     */
     SysOssVo upload(File file);
 
+    /**
+     * 文件下载方法，支持一次性下载完整文件
+     *
+     * @param ossId    OSS对象ID
+     * @param response HttpServletResponse对象，用于设置响应头和向客户端发送文件内容
+     */
     void download(Long ossId, HttpServletResponse response) throws IOException;
 
+    /**
+     * 删除OSS对象存储
+     *
+     * @param ids     OSS对象ID串
+     * @param isValid 判断是否需要校验
+     * @return 结果
+     */
     Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid);
 
 }

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysUserService.java

@@ -206,8 +206,8 @@ public interface ISysUserService {
     /**
      * 通过部门id查询当前部门所有用户
      *
-     * @param deptId
-     * @return
+     * @param deptId 部门id
+     * @return 结果
      */
     List<SysUserVo> selectUserListByDept(Long deptId);
 }

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysLogininforServiceImpl.java

@@ -59,10 +59,10 @@ public class SysLogininforServiceImpl implements ISysLogininforService {
         final UserAgent userAgent = UserAgentUtil.parse(request.getHeader("User-Agent"));
         final String ip = ServletUtils.getClientIP(request);
         // 客户端信息
-        String clientid = request.getHeader(LoginHelper.CLIENT_KEY);
+        String clientId = request.getHeader(LoginHelper.CLIENT_KEY);
         SysClientVo client = null;
-        if (StringUtils.isNotBlank(clientid)) {
-            client = clientService.queryByClientId(clientid);
+        if (StringUtils.isNotBlank(clientId)) {
+            client = clientService.queryByClientId(clientId);
         }
 
         String address = AddressUtils.getRealAddressByIP(ip);

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysOssServiceImpl.java

@@ -6,6 +6,8 @@ import cn.hutool.core.util.ObjectUtil;
 import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
 import com.baomidou.mybatisplus.core.toolkit.Wrappers;
 import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
+import jakarta.servlet.http.HttpServletResponse;
+import lombok.RequiredArgsConstructor;
 import org.dromara.common.core.constant.CacheNames;
 import org.dromara.common.core.exception.ServiceException;
 import org.dromara.common.core.service.OssService;
@@ -25,8 +27,6 @@ import org.dromara.system.domain.bo.SysOssBo;
 import org.dromara.system.domain.vo.SysOssVo;
 import org.dromara.system.mapper.SysOssMapper;
 import org.dromara.system.service.ISysOssService;
-import jakarta.servlet.http.HttpServletResponse;
-import lombok.RequiredArgsConstructor;
 import org.jetbrains.annotations.NotNull;
 import org.springframework.cache.annotation.Cacheable;
 import org.springframework.http.MediaType;
@@ -36,7 +36,10 @@ import org.springframework.web.multipart.MultipartFile;
 import java.io.File;
 import java.io.IOException;
 import java.io.InputStream;
-import java.util.*;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.List;
+import java.util.Map;
 
 /**
  * 文件上传 服务层实现
@@ -49,6 +52,13 @@ public class SysOssServiceImpl implements ISysOssService, OssService {
 
     private final SysOssMapper baseMapper;
 
+    /**
+     * 查询OSS对象存储列表
+     *
+     * @param bo        OSS对象存储分页查询对象
+     * @param pageQuery 分页查询实体类
+     * @return 结果
+     */
     @Override
     public TableDataInfo<SysOssVo> queryPageList(SysOssBo bo, PageQuery pageQuery) {
         LambdaQueryWrapper<SysOss> lqw = buildQueryWrapper(bo);
@@ -58,6 +68,12 @@ public class SysOssServiceImpl implements ISysOssService, OssService {
         return TableDataInfo.build(result);
     }
 
+    /**
+     * 根据一组 ossIds 获取对应的 SysOssVo 列表
+     *
+     * @param ossIds 一组文件在数据库中的唯一标识集合
+     * @return 包含 SysOssVo 对象的列表
+     */
     @Override
     public List<SysOssVo> listByIds(Collection<Long> ossIds) {
         List<SysOssVo> list = new ArrayList<>();
@@ -75,6 +91,12 @@ public class SysOssServiceImpl implements ISysOssService, OssService {
         return list;
     }
 
+    /**
+     * 根据一组 ossIds 获取对应文件的 URL 列表
+     *
+     * @param ossIds 以逗号分隔的 ossId 字符串
+     * @return 以逗号分隔的文件 URL 字符串
+     */
     @Override
     public String selectUrlByIds(String ossIds) {
         List<String> list = new ArrayList<>();
@@ -107,12 +129,25 @@ public class SysOssServiceImpl implements ISysOssService, OssService {
         return lqw;
     }
 
+    /**
+     * 根据 ossId 从缓存或数据库中获取 SysOssVo 对象
+     *
+     * @param ossId 文件在数据库中的唯一标识
+     * @return SysOssVo 对象，包含文件信息
+     */
     @Cacheable(cacheNames = CacheNames.SYS_OSS, key = "#ossId")
     @Override
     public SysOssVo getById(Long ossId) {
         return baseMapper.selectVoById(ossId);
     }
 
+
+    /**
+     * 文件下载方法，支持一次性下载完整文件
+     *
+     * @param ossId    OSS对象ID
+     * @param response HttpServletResponse对象，用于设置响应头和向客户端发送文件内容
+     */
     @Override
     public void download(Long ossId, HttpServletResponse response) throws IOException {
         SysOssVo sysOss = SpringUtils.getAopProxy(this).getById(ossId);
@@ -122,7 +157,7 @@ public class SysOssServiceImpl implements ISysOssService, OssService {
         FileUtils.setAttachmentResponseHeader(response, sysOss.getOriginalName());
         response.setContentType(MediaType.APPLICATION_OCTET_STREAM_VALUE + "; charset=UTF-8");
         OssClient storage = OssFactory.instance(sysOss.getService());
-        try(InputStream inputStream = storage.getObjectContent(sysOss.getUrl())) {
+        try (InputStream inputStream = storage.getObjectContent(sysOss.getUrl())) {
             int available = inputStream.available();
             IoUtil.copy(inputStream, response.getOutputStream(), available);
             response.setContentLength(available);
@@ -131,6 +166,13 @@ public class SysOssServiceImpl implements ISysOssService, OssService {
         }
     }
 
+    /**
+     * 上传 MultipartFile 到对象存储服务，并保存文件信息到数据库
+     *
+     * @param file 要上传的 MultipartFile 对象
+     * @return 上传成功后的 SysOssVo 对象，包含文件信息
+     * @throws ServiceException 如果上传过程中发生异常，则抛出 ServiceException 异常
+     */
     @Override
     public SysOssVo upload(MultipartFile file) {
         String originalfileName = file.getOriginalFilename();
@@ -146,6 +188,12 @@ public class SysOssServiceImpl implements ISysOssService, OssService {
         return buildResultEntity(originalfileName, suffix, storage.getConfigKey(), uploadResult);
     }
 
+    /**
+     * 上传文件到对象存储服务，并保存文件信息到数据库
+     *
+     * @param file 要上传的文件对象
+     * @return 上传成功后的 SysOssVo 对象，包含文件信息
+     */
     @Override
     public SysOssVo upload(File file) {
         String originalfileName = file.getName();
@@ -169,6 +217,13 @@ public class SysOssServiceImpl implements ISysOssService, OssService {
         return this.matchingUrl(sysOssVo);
     }
 
+    /**
+     * 删除OSS对象存储
+     *
+     * @param ids     OSS对象ID串
+     * @param isValid 判断是否需要校验
+     * @return 结果
+     */
     @Override
     public Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid) {
         if (isValid) {
@@ -183,7 +238,7 @@ public class SysOssServiceImpl implements ISysOssService, OssService {
     }
 
     /**
-     * 匹配Url
+     * 桶类型为 private 的URL 修改为临时URL时长为120s
      *
      * @param oss OSS对象
      * @return oss 匹配Url的OSS对象

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysUserServiceImpl.java

@@ -524,8 +524,8 @@ public class SysUserServiceImpl implements ISysUserService, UserService {
     /**
      * 通过部门id查询当前部门所有用户
      *
-     * @param deptId
-     * @return
+     * @param deptId 部门ID
+     * @return 用户信息集合信息
      */
     @Override
     public List<SysUserVo> selectUserListByDept(Long deptId) {
@@ -535,6 +535,12 @@ public class SysUserServiceImpl implements ISysUserService, UserService {
         return baseMapper.selectVoList(lqw);
     }
 
+    /**
+     * 通过用户ID查询用户账户
+     *
+     * @param userId 用户ID
+     * @return 用户账户
+     */
     @Cacheable(cacheNames = CacheNames.SYS_USER_NAME, key = "#userId")
     @Override
     public String selectUserNameById(Long userId) {
@@ -543,6 +549,12 @@ public class SysUserServiceImpl implements ISysUserService, UserService {
         return ObjectUtil.isNull(sysUser) ? null : sysUser.getUserName();
     }
 
+    /**
+     * 通过用户ID查询用户账户
+     *
+     * @param userId 用户ID
+     * @return 用户账户
+     */
     @Override
     @Cacheable(cacheNames = CacheNames.SYS_NICKNAME, key = "#userId")
     public String selectNicknameById(Long userId) {
@@ -550,4 +562,30 @@ public class SysUserServiceImpl implements ISysUserService, UserService {
             .select(SysUser::getNickName).eq(SysUser::getUserId, userId));
         return ObjectUtil.isNull(sysUser) ? null : sysUser.getNickName();
     }
+    /**
+     * 通过用户ID查询用户手机号
+     *
+     * @param userId 用户id
+     * @return 用户手机号
+     */
+    @Override
+    public String selectPhonenumberById(Long userId) {
+        SysUser sysUser = baseMapper.selectOne(new LambdaQueryWrapper<SysUser>()
+            .select(SysUser::getPhonenumber).eq(SysUser::getUserId, userId));
+        return ObjectUtil.isNull(sysUser) ? null : sysUser.getPhonenumber();
+    }
+
+    /**
+     * 通过用户ID查询用户邮箱
+     *
+     * @param userId 用户id
+     * @return 用户邮箱
+     */
+    @Override
+    public String selectEmailById(Long userId) {
+        SysUser sysUser = baseMapper.selectOne(new LambdaQueryWrapper<SysUser>()
+            .select(SysUser::getEmail).eq(SysUser::getUserId, userId));
+        return ObjectUtil.isNull(sysUser) ? null : sysUser.getEmail();
+    }
+
 }