feat: 扩展用户管理统一搜索范围

- 支持按账号、昵称、电话、邮件和角色名搜索 - 补充搜索提示、特殊字符处理及前后端测试
2026-08-07 12:14:55 +08:00
parent 6544cdcff0
commit 170b315459
6 changed files with 252 additions and 1 deletions
--- a/easyflow-api/easyflow-api-admin/src/main/java/tech/easyflow/admin/controller/system/SysAccountController.java
+++ b/easyflow-api/easyflow-api-admin/src/main/java/tech/easyflow/admin/controller/system/SysAccountController.java
@@ -5,7 +5,10 @@ import cn.dev33.satoken.stp.StpUtil;
 import cn.hutool.crypto.digest.BCrypt;
 import com.alibaba.fastjson2.JSONObject;
 import com.mybatisflex.core.paginate.Page;
+import com.mybatisflex.core.query.QueryCondition;
+import com.mybatisflex.core.query.QueryMethods;
 import com.mybatisflex.core.query.QueryWrapper;
+import jakarta.servlet.http.HttpServletRequest;
 import jakarta.servlet.http.HttpServletResponse;
 import org.springframework.dao.DuplicateKeyException;
 import org.springframework.transaction.annotation.Transactional;
@@ -49,6 +52,10 @@ import java.util.Map;
 import java.util.Set;
 import java.util.stream.Collectors;

+import static tech.easyflow.system.entity.table.SysAccountRoleTableDef.SYS_ACCOUNT_ROLE;
+import static tech.easyflow.system.entity.table.SysAccountTableDef.SYS_ACCOUNT;
+import static tech.easyflow.system.entity.table.SysRoleTableDef.SYS_ROLE;
+
 /**
 * 用户表 控制层。
 *
@@ -58,6 +65,7 @@ import java.util.stream.Collectors;
@RestController("sysAccountController")
@RequestMapping("/api/v1/sysAccount")
 public class SysAccountController extends BaseCurdController<SysAccountService, SysAccount> {
+    private static final String ACCOUNT_SEARCH_KEYWORD_PARAM = "keyword";
    private static final String SUPER_ADMIN_HOME_PATH = "/dashboard/workspace";
    private static final String USER_HOME_PATH = "/ai/agent-chat";

@@ -81,6 +89,53 @@ public class SysAccountController extends BaseCurdController<SysAccountService,
        this.sysRoleService = sysRoleService;
    }

+    /**
+     * 构造账号列表查询条件。
+     *
+     * <p>统一关键字同时匹配账号、昵称、电话、邮件和已关联角色名称。角色条件使用相关
+     * {@code EXISTS} 子查询，避免多角色关联导致分页记录重复。</p>
+     *
+     * @param request 当前 HTTP 请求
+     * @return 账号列表查询条件
+     */
+    @Override
+    protected QueryWrapper buildQueryWrapper(HttpServletRequest request) {
+        String keyword = request.getParameter(ACCOUNT_SEARCH_KEYWORD_PARAM);
+        if (!StringUtil.hasText(keyword)) {
+            return super.buildQueryWrapper(request);
+        }
+
+        String likePattern = "%" + escapeLikeKeyword(keyword.trim()) + "%";
+        QueryWrapper roleExistsQuery = QueryMethods.selectOne()
+                .from(SYS_ACCOUNT_ROLE)
+                .innerJoin(SYS_ROLE)
+                .on(SYS_ACCOUNT_ROLE.ROLE_ID.eq(SYS_ROLE.ID))
+                .where(SYS_ACCOUNT_ROLE.ACCOUNT_ID.eq(SYS_ACCOUNT.ID))
+                // 关联角色必须与账号属于同一租户，避免异常关系数据跨租户命中。
+                .and(SYS_ROLE.TENANT_ID.eq(SYS_ACCOUNT.TENANT_ID))
+                .and(SYS_ROLE.ROLE_NAME.likeRaw(likePattern));
+        QueryCondition keywordCondition = SYS_ACCOUNT.LOGIN_NAME.likeRaw(likePattern)
+                .or(SYS_ACCOUNT.NICKNAME.likeRaw(likePattern))
+                .or(SYS_ACCOUNT.MOBILE.likeRaw(likePattern))
+                .or(SYS_ACCOUNT.EMAIL.likeRaw(likePattern))
+                .or(QueryMethods.exists(roleExistsQuery));
+
+        return QueryWrapper.create().and(keywordCondition);
+    }
+
+    /**
+     * 转义 MySQL LIKE 模式中的特殊字符，使用户输入按普通文本匹配。
+     *
+     * @param keyword 已去除首尾空格的关键字
+     * @return 可安全放入 LIKE 模式的文本
+     */
+    private String escapeLikeKeyword(String keyword) {
+        return keyword
+                .replace("\\", "\\\\")
+                .replace("%", "\\%")
+                .replace("_", "\\_");
+    }
+
    @Override
    @LogRecord("分页查询")
    protected Page<SysAccount> queryPage(Page<SysAccount> page, QueryWrapper queryWrapper) {
--- a/easyflow-api/easyflow-api-admin/src/test/java/tech/easyflow/admin/controller/system/SysAccountControllerTest.java
+++ b/easyflow-api/easyflow-api-admin/src/test/java/tech/easyflow/admin/controller/system/SysAccountControllerTest.java
@@ -2,6 +2,7 @@ package tech.easyflow.admin.controller.system;

 import com.alibaba.fastjson2.JSONObject;
 import com.mybatisflex.core.query.QueryWrapper;
+import jakarta.servlet.http.HttpServletRequest;
 import org.mockito.MockedStatic;
 import org.testng.annotations.Test;
 import tech.easyflow.auth.service.AuthCredentialKeyService;
@@ -15,7 +16,9 @@ import tech.easyflow.system.service.SysAccountService;
 import tech.easyflow.system.service.SysRoleService;

 import java.math.BigInteger;
+import java.util.Collections;
 import java.util.List;
+import java.util.Locale;
 import java.util.Map;
 import java.util.concurrent.atomic.AtomicReference;

@@ -27,12 +30,79 @@ import static org.mockito.Mockito.never;
 import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;
 import static org.testng.Assert.assertEquals;
+import static org.testng.Assert.assertFalse;
+import static org.testng.Assert.assertTrue;

 /**
 * {@link SysAccountController} 创建账号测试。
 */
 public class SysAccountControllerTest {

+    /**
+     * 验证统一关键字覆盖账号字段和关联角色名称，并保留租户关联条件。
+     */
+    @Test
+    public void buildQueryWrapperShouldSearchAccountFieldsAndRoleName() {
+        SysAccountController controller = new SysAccountController(
+                mock(SysAccountService.class),
+                mock(AuthCredentialKeyService.class),
+                mock(SysRoleService.class)
+        );
+        HttpServletRequest request = mock(HttpServletRequest.class);
+        when(request.getParameter("keyword")).thenReturn("  search-user  ");
+
+        QueryWrapper queryWrapper = controller.buildQueryWrapper(request);
+
+        String sql = queryWrapper.toSQL().toLowerCase(Locale.ROOT);
+        assertTrue(sql.contains("login_name"), sql);
+        assertTrue(sql.contains("nickname"), sql);
+        assertTrue(sql.contains("mobile"), sql);
+        assertTrue(sql.contains("email"), sql);
+        assertTrue(sql.contains("exists"), sql);
+        assertTrue(sql.contains("tb_sys_account_role"), sql);
+        assertTrue(sql.contains("tb_sys_role"), sql);
+        assertTrue(sql.contains("role_name"), sql);
+        assertTrue(sql.contains("tenant_id"), sql);
+        assertTrue(sql.contains("search-user"), sql);
+    }
+
+    /**
+     * 验证空关键字不会产生额外筛选条件。
+     */
+    @Test
+    public void buildQueryWrapperShouldIgnoreBlankKeyword() {
+        SysAccountController controller = new SysAccountController(
+                mock(SysAccountService.class),
+                mock(AuthCredentialKeyService.class),
+                mock(SysRoleService.class)
+        );
+        HttpServletRequest request = mock(HttpServletRequest.class);
+        when(request.getParameter("keyword")).thenReturn("  ");
+        when(request.getParameterMap()).thenReturn(Collections.emptyMap());
+
+        QueryWrapper queryWrapper = controller.buildQueryWrapper(request);
+
+        assertFalse(queryWrapper.hasCondition());
+    }
+
+    /**
+     * 验证 LIKE 通配符和反斜杠按普通字符参与搜索。
+     */
+    @Test
+    public void buildQueryWrapperShouldEscapeLikePatternCharacters() {
+        SysAccountController controller = new SysAccountController(
+                mock(SysAccountService.class),
+                mock(AuthCredentialKeyService.class),
+                mock(SysRoleService.class)
+        );
+        HttpServletRequest request = mock(HttpServletRequest.class);
+        when(request.getParameter("keyword")).thenReturn("a_b%c\\d");
+
+        String sql = controller.buildQueryWrapper(request).toSQL();
+
+        assertTrue(sql.contains("a\\\\_b\\\\%c\\\\\\\\d"), sql);
+    }
+
    /**
     * 验证创建用户时保留表单选择的部门，不被操作者部门覆盖。
     */