feat(mcp): add agent.user.list.query for agent-role user listing

查询 m0.user 中 enterprise_type=1 的代理角色用户,返回所属权限组、
dept_user 部门岗位明细与当前站点;行级权限复用 visibleAgentIds
(总部全量/代理商自己+直属下级+代管),mobile 原样不脱敏,
idcard/password/openid 不进白名单,不返回位置字段。
设计:doc/agent-user-list-mcp-tool-design.md(2026-10-13 王恒拍板)
This commit is contained in:
my_local_kimi_dev2
2026-10-13 11:33:19 +08:00
parent f4eb2387db
commit e1fcae2eb1
9 changed files with 909 additions and 6 deletions
@@ -0,0 +1,66 @@
package me.iiv.agent.entity.m0;
import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import lombok.Getter;
import lombok.Setter;
import lombok.ToString;
import java.io.Serializable;
/**
* 部门人员(m0.dept_user)。dept_name/post_name 为冗余快照,
* 与老系统 /user/listByPage 一致:以 dept_user 关联记录为准返回,不回查 dept 表。
*/
@Getter
@Setter
@ToString
@TableName("dept_user")
public class DeptUser implements Serializable {
private static final long serialVersionUID = 1L;
@TableId(value = "id", type = IdType.AUTO)
private Long id;
/**
* 数据状态
*/
private Integer softDelete;
/**
* 人员id
*/
private Long userId;
/**
* 部门id
*/
private Long deptId;
/**
* 部门名称
*/
private String deptName;
/**
* 岗位id
*/
private Long postId;
/**
* 岗位名称
*/
private String postName;
/**
* 是否部门负责(0:否;1:是)
*/
private Integer isManager;
/**
* 是否主岗(0:否;1:是)
*/
private Integer isKey;
}
@@ -0,0 +1,11 @@
package me.iiv.agent.mapper.m0;
import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import me.iiv.agent.entity.m0.DeptUser;
/**
* 部门人员(dept_user)Mapper 接口
*/
public interface DeptUserMapper extends BaseMapper<DeptUser> {
}
@@ -0,0 +1,262 @@
package me.iiv.agent.mcp.tool;
import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import me.iiv.agent.entity.m0.Agent;
import me.iiv.agent.entity.m0.Authority;
import me.iiv.agent.entity.m0.DeptUser;
import me.iiv.agent.entity.m0.District;
import me.iiv.agent.entity.m0.User;
import me.iiv.agent.mapper.m0.AgentMapper;
import me.iiv.agent.mapper.m0.AuthorityMapper;
import me.iiv.agent.mapper.m0.DeptUserMapper;
import me.iiv.agent.mapper.m0.DistrictMapper;
import me.iiv.agent.mapper.m0.UserMapper;
import me.iiv.agent.mcp.ToolObject;
import me.iiv.agent.mcp.XqTool;
import me.iiv.agent.permission.PermissionService;
import me.iiv.agent.security.AuthContextHolder;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;
import org.springframework.stereotype.Component;
import org.springframework.util.StringUtils;
import java.text.SimpleDateFormat;
import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.stream.Collectors;
/**
* 代理角色用户工具:agent.user.list.query(对应老系统 UserController.listByPage 的
* enterprise_type=1 子集)。设计文档:doc/agent-user-list-mcp-tool-design.md。
* 判定口径 user.enterprise_type=1(强制)+ soft_delete=0;mobile 原样返回不脱敏,
* idcard/password/weixin_openid/weixin_name/ding_user_id 不进返回白名单;不返回位置字段。
*/
@Component
public class AgentUserTools implements ToolObject {
private static final int DEFAULT_ROWS = 20;
private static final int MAX_ROWS = 100;
final UserMapper userMapper;
final DeptUserMapper deptUserMapper;
final AgentMapper agentMapper;
final AuthorityMapper authorityMapper;
final DistrictMapper districtMapper;
final PermissionService permissionService;
public AgentUserTools(UserMapper userMapper, DeptUserMapper deptUserMapper,
AgentMapper agentMapper, AuthorityMapper authorityMapper,
DistrictMapper districtMapper, PermissionService permissionService) {
this.userMapper = userMapper;
this.deptUserMapper = deptUserMapper;
this.agentMapper = agentMapper;
this.authorityMapper = authorityMapper;
this.districtMapper = districtMapper;
this.permissionService = permissionService;
}
/**
* 查询代理角色用户列表。强制 enterprise_type=1 + soft_delete=0,固定 id DESC,
* selectCount + LIMIT 物理分页(项目未注册 MP 分页拦截器,禁用 selectPage)。
* agentName/authorityName/districtName/deptList 按页批量 IN 富化,无 N+1。
*/
@XqTool(category = "agent", kind = "read")
@Tool(name = "agent.user.list.query", description = "分页查询代理角色用户(user.enterprise_type=1)列表,返回所属权限组、部门岗位明细。"
+ "行级权限:总部身份(权限组 isagent=0)可看全部,可传任意 agentId;代理商身份(isagent=1)只能看自己+直属下级+授权代管代理商范围内的用户,"
+ "传 agentId 时必须在可见范围内,否则拒绝。"
+ "enterpriseType 含义:1=代理 2=物业(本工具恒为 1);approle 含义:1=运维 2=保洁 3=富士康 4=老化 5=物业 6=代理;"
+ "roleType 含义:0=管理 1=普通;workStatus 含义:0=上班 1=下班 2=请假 3=休息。"
+ "分页:page 从 1 开始,rows 默认 20、上限 100,超出自动截断为 100 并在返回的 notice 字段提示。"
+ "返回 total(符合条件的总数)、records(本页记录);mobile 原样返回不脱敏,不含 idcard/password 等敏感字段与位置字段。")
public Map<String, Object> agentUserListQuery(
@ToolParam(required = false, description = "所属代理商 id,精确匹配,且必须在当前身份可见范围内") Long agentId,
@ToolParam(required = false, description = "用户姓名,模糊匹配") String name,
@ToolParam(required = false, description = "手机号,模糊匹配") String mobile,
@ToolParam(required = false, description = "员工编号/工号,模糊匹配") String no,
@ToolParam(required = false, description = "权限组 id,精确匹配(仍强制叠加 enterprise_type=1)") Long authorityId,
@ToolParam(required = false, description = "部门 id,精确匹配(查 dept_user 关联)") Long deptId,
@ToolParam(required = false, description = "工作状态,精确匹配:0=上班 1=下班 2=请假 3=休息") Integer workStatus,
@ToolParam(required = false, description = "页码,从 1 开始,默认 1") Integer page,
@ToolParam(required = false, description = "每页条数,默认 20,上限 100(超出截断为 100)") Integer rows) {
User currentUser = AuthContextHolder.get().getUser();
int pageNo = page == null || page < 1 ? 1 : page;
boolean truncated = rows != null && rows > MAX_ROWS;
int pageSize = rows == null || rows < 1 ? DEFAULT_ROWS : Math.min(rows, MAX_ROWS);
LambdaQueryWrapper<User> wrapper = new LambdaQueryWrapper<User>()
.eq(User::getEnterpriseType, 1)
.eq(User::getSoftDelete, 0);
if (StringUtils.hasText(name)) {
wrapper.like(User::getName, name);
}
if (StringUtils.hasText(mobile)) {
wrapper.like(User::getMobile, mobile);
}
if (StringUtils.hasText(no)) {
wrapper.like(User::getNo, no);
}
if (authorityId != null) {
wrapper.eq(User::getAuthorityId, authorityId);
}
if (workStatus != null) {
wrapper.eq(User::getWorkStatus, workStatus);
}
if (deptId != null) {
List<Long> deptUserIds = deptUserMapper.selectList(new LambdaQueryWrapper<DeptUser>()
.eq(DeptUser::getSoftDelete, 0)
.eq(DeptUser::getDeptId, deptId)
.select(DeptUser::getUserId))
.stream().map(DeptUser::getUserId).filter(Objects::nonNull)
.distinct().collect(Collectors.toList());
wrapper.in(User::getId, deptUserIds.isEmpty() ? List.of(0L) : deptUserIds);
}
permissionService.applyAgentUserRowFilter(wrapper, currentUser, agentId);
Long total = userMapper.selectCount(wrapper);
wrapper.select(User::getId, User::getName, User::getNo, User::getLoginAccount,
User::getMobile, User::getAgentId, User::getAuthorityId,
User::getEnterpriseType, User::getApprole, User::getRoleType,
User::getWorkStatus, User::getDeptId, User::getDeptName, User::getPostName,
User::getDistrictId, User::getLastLoginTime, User::getCreateTime)
.orderByDesc(User::getId)
.last("LIMIT " + (long) (pageNo - 1) * pageSize + "," + pageSize);
List<User> users = userMapper.selectList(wrapper);
// 按页批量富化:代理商/权限组/站点名称 + dept_user 部门岗位明细(消除 N+1)
List<Long> agentIds = users.stream().map(User::getAgentId)
.filter(Objects::nonNull).distinct().collect(Collectors.toList());
Map<Long, String> agentNames = agentIds.isEmpty()
? Map.of()
: agentMapper.selectBatchIds(agentIds).stream()
.collect(Collectors.toMap(Agent::getId, Agent::getName, (a, b) -> a));
List<Long> authorityIds = users.stream().map(User::getAuthorityId)
.filter(Objects::nonNull).distinct().collect(Collectors.toList());
Map<Long, String> authorityNames = authorityIds.isEmpty()
? Map.of()
: authorityMapper.selectBatchIds(authorityIds).stream()
.collect(Collectors.toMap(Authority::getId, Authority::getName, (a, b) -> a));
List<Long> districtIds = users.stream().map(User::getDistrictId)
.filter(Objects::nonNull).filter(id -> id != 0).distinct().collect(Collectors.toList());
Map<Long, String> districtNames = districtIds.isEmpty()
? Map.of()
: districtMapper.selectBatchIds(districtIds).stream()
.collect(Collectors.toMap(District::getId, District::getDistrictName, (a, b) -> a));
List<Long> userIds = users.stream().map(User::getId)
.filter(Objects::nonNull).distinct().collect(Collectors.toList());
Map<Long, List<DeptUser>> deptUsersByUserId = userIds.isEmpty()
? Map.of()
: deptUserMapper.selectList(new LambdaQueryWrapper<DeptUser>()
.eq(DeptUser::getSoftDelete, 0)
.in(DeptUser::getUserId, userIds))
.stream().collect(Collectors.groupingBy(DeptUser::getUserId));
SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");
List<Map<String, Object>> records = new ArrayList<>();
for (User user : users) {
Map<String, Object> record = new LinkedHashMap<>();
record.put("id", user.getId());
record.put("name", user.getName());
record.put("no", user.getNo());
record.put("loginAccount", user.getLoginAccount());
record.put("mobile", user.getMobile());
record.put("agentId", user.getAgentId());
record.put("agentName", user.getAgentId() == null ? null : agentNames.get(user.getAgentId()));
record.put("authorityId", user.getAuthorityId());
record.put("authorityName",
user.getAuthorityId() == null ? null : authorityNames.get(user.getAuthorityId()));
record.put("enterpriseType", user.getEnterpriseType());
record.put("enterpriseTypeText", enterpriseTypeText(user.getEnterpriseType()));
record.put("approle", user.getApprole());
record.put("approleText", approleText(user.getApprole()));
record.put("roleType", user.getRoleType());
record.put("roleTypeText", roleTypeText(user.getRoleType()));
record.put("workStatus", user.getWorkStatus());
record.put("workStatusText", workStatusText(user.getWorkStatus()));
record.put("deptId", user.getDeptId());
record.put("deptName", user.getDeptName());
record.put("postName", user.getPostName());
List<Map<String, Object>> deptList = new ArrayList<>();
for (DeptUser deptUser : deptUsersByUserId.getOrDefault(user.getId(), List.of())) {
Map<String, Object> dept = new LinkedHashMap<>();
dept.put("deptId", deptUser.getDeptId());
dept.put("deptName", deptUser.getDeptName());
dept.put("postId", deptUser.getPostId());
dept.put("postName", deptUser.getPostName());
dept.put("isManager", deptUser.getIsManager());
dept.put("isKey", deptUser.getIsKey());
deptList.add(dept);
}
record.put("deptList", deptList);
record.put("districtId", user.getDistrictId());
record.put("districtName",
user.getDistrictId() == null ? null : districtNames.get(user.getDistrictId()));
record.put("lastLoginTime",
user.getLastLoginTime() == null ? null : sdf.format(user.getLastLoginTime()));
record.put("createTime", user.getCreateTime() == null ? null : sdf.format(user.getCreateTime()));
records.add(record);
}
Map<String, Object> result = new LinkedHashMap<>();
result.put("total", total);
result.put("page", pageNo);
result.put("rows", pageSize);
if (truncated) {
result.put("notice", "rows 超过上限 100,已截断为 100");
}
result.put("records", records);
return result;
}
private static String enterpriseTypeText(Integer value) {
if (value == null) {
return null;
}
return switch (value) {
case 1 -> "代理";
case 2 -> "物业";
default -> "未知(" + value + ")";
};
}
private static String approleText(Integer value) {
if (value == null) {
return null;
}
return switch (value) {
case 1 -> "运维";
case 2 -> "保洁";
case 3 -> "富士康";
case 4 -> "老化";
case 5 -> "物业";
case 6 -> "代理";
default -> "未知(" + value + ")";
};
}
private static String roleTypeText(Integer value) {
if (value == null) {
return null;
}
return switch (value) {
case 0 -> "管理";
case 1 -> "普通";
default -> "未知(" + value + ")";
};
}
private static String workStatusText(Integer value) {
if (value == null) {
return null;
}
return switch (value) {
case 0 -> "上班";
case 1 -> "下班";
case 2 -> "请假";
case 3 -> "休息";
default -> "未知(" + value + ")";
};
}
}
@@ -159,6 +159,30 @@ public class PermissionService {
return new ArrayList<>(ids);
}
/**
* 代理角色用户(m0.user,enterprise_type=1)行权限(agent.user.list.query 专用):
* 总部(isagent!=1,含 tenant_service 服务主体)不加过滤,可按任意 agentId 精确查;
* 代理商(isagent=1)user.agent_id IN visibleAgentIds(自己+直属下级+warehouse_agent_auth 代管);
* 传 agentId 时必须在可见集合内,否则拒绝访问。
*/
public void applyAgentUserRowFilter(LambdaQueryWrapper<User> wrapper, User user, Long agentId) {
List<Long> visibleIds = visibleAgentIds(user);
if (visibleIds == null) {
if (agentId != null) {
wrapper.eq(User::getAgentId, agentId);
}
return;
}
if (agentId != null) {
if (!visibleIds.contains(agentId)) {
throw new IllegalStateException("无权访问该代理商");
}
wrapper.eq(User::getAgentId, agentId);
return;
}
wrapper.in(User::getAgentId, visibleIds);
}
/**
* 出库单权限:总部看全部;代理身份可看所属代理范围内的主单、其代理范围所属/负责仓库
* 涉及的主单,以及本人参与审批或处理的主单。关联范围使用 EXISTS 落在同一个主查询中,