feat(usr): UsrUserMapper.selectUserPage 跨表分页查询 XML REQ-USR-003 (95bdce36) | Commits | 朱子纯 / test6

Browse Code »

Commit 95bdce3624b2252ddd090f3ee6bdf93b098594d0

Authored by zichun 2026-06-01 14:29:48 +0800

1 parent c6d8e4e3

feat(usr): UsrUserMapper.selectUserPage 跨表分页查询 XML REQ-USR-003

Inline Side-by-side

Showing 4 changed files with 362 additions and 1 deletions

backend/src/main/java/com/xly/erp/modules/usr/dto/UserQueryCondition.java 0 → 100644

View file @95bdce3

		1	+package com.xly.erp.modules.usr.dto;
		2	+
		3	+import java.time.LocalDateTime;
		4	+
		5	+/**
		6	+ * 查询条件「已解析」内部载体（Service → Mapper）。REQ-USR-003 T3 / T4。
		7	+ *
		8	+ * <p>非对外契约：由 Service 把 {@link UserQueryDTO} 的中文 {@code queryField}/{@code matchType}/
		9	+ * 原始 {@code queryValue} 解析归一为可直接拼 XML {@code <if>} 分支的结构，避免在 XML 内做中文
		10	+ * 枚举判断与类型解析。{@code column} 必须由 Service 从固定白名单映射产出（绝不拼接用户输入列名），防注入。</p>
		11	+ *
		12	+ * <p>分支种类 {@link Kind}：{@code NONE} 无过滤（全量分页）；{@code TEXT} 文本 / 枚举
		13	+ * （{@code LIKE}/{@code NOT LIKE}/{@code =}）；{@code BOOL} 布尔（{@code =}/{@code <>}）；
		14	+ * {@code DATE} 日期区间（{@code >=}/{@code <}，可取反）。</p>
		15	+ */
		16	+public class UserQueryCondition {
		17	+
		18	+ /** 过滤分支种类。 */
		19	+ public enum Kind {
		20	+ /** 无过滤。 */
		21	+ NONE,
		22	+ /** 文本 / 枚举模糊或精确。 */
		23	+ TEXT,
		24	+ /** 布尔等于 / 不等于。 */
		25	+ BOOL,
		26	+ /** 日期区间命中 / 取反。 */
		27	+ DATE
		28	+ }
		29	+
		30	+ /** 目标列（白名单 token，如 {@code u.sUserName} / {@code e.sDepartment}）。 */
		31	+ private String column;
		32	+ /** 分支种类。 */
		33	+ private Kind kind = Kind.NONE;
		34	+
		35	+ /** TEXT：匹配方式（包含 / 不包含 / 等于）。 */
		36	+ private String matchType;
		37	+ /** TEXT：已转义文本值（含 ESCAPE 转义后的 % _ \）。 */
		38	+ private String textValue;
		39	+
		40	+ /** BOOL：归一化布尔值（0 / 1）。 */
		41	+ private Integer boolValue;
		42	+ /** BOOL：true 表示不等于（{@code <>}），false 表示等于（{@code =}）。 */
		43	+ private boolean boolNegated;
		44	+
		45	+ /** DATE：当日区间起（含）。 */
		46	+ private LocalDateTime dateStart;
		47	+ /** DATE：当日区间止（不含）。 */
		48	+ private LocalDateTime dateEnd;
		49	+ /** DATE：true 表示「不包含」（区间取反）。 */
		50	+ private boolean dateNegated;
		51	+
		52	+ public UserQueryCondition() {
		53	+ }
		54	+
		55	+ /** 无过滤条件（全量分页）。 */
		56	+ public static UserQueryCondition none() {
		57	+ return new UserQueryCondition();
		58	+ }
		59	+
		60	+ /** 文本 / 枚举条件：{@code matchType} ∈ {包含,不包含,等于}，{@code value} 须由 Service 预先转义。 */
		61	+ public static UserQueryCondition text(String column, String matchType, String value) {
		62	+ UserQueryCondition c = new UserQueryCondition();
		63	+ c.column = column;
		64	+ c.kind = Kind.TEXT;
		65	+ c.matchType = matchType;
		66	+ c.textValue = value;
		67	+ return c;
		68	+ }
		69	+
		70	+ /** 布尔条件：{@code negated=true} 表示「不包含」（{@code <>}）。 */
		71	+ public static UserQueryCondition bool(String column, int value, boolean negated) {
		72	+ UserQueryCondition c = new UserQueryCondition();
		73	+ c.column = column;
		74	+ c.kind = Kind.BOOL;
		75	+ c.boolValue = value;
		76	+ c.boolNegated = negated;
		77	+ return c;
		78	+ }
		79	+
		80	+ /** 日期区间条件：{@code [start, end)}；{@code negated=true} 表示「不包含」（区间取反）。 */
		81	+ public static UserQueryCondition date(String column, LocalDateTime start, LocalDateTime end,
		82	+ boolean negated) {
		83	+ UserQueryCondition c = new UserQueryCondition();
		84	+ c.column = column;
		85	+ c.kind = Kind.DATE;
		86	+ c.dateStart = start;
		87	+ c.dateEnd = end;
		88	+ c.dateNegated = negated;
		89	+ return c;
		90	+ }
		91	+
		92	+ // ---- XML <if> 用便捷判定（getter 形式，OGNL 直接读取）----
		93	+
		94	+ public boolean isText() {
		95	+ return kind == Kind.TEXT;
		96	+ }
		97	+
		98	+ public boolean isBool() {
		99	+ return kind == Kind.BOOL;
		100	+ }
		101	+
		102	+ public boolean isDate() {
		103	+ return kind == Kind.DATE;
		104	+ }
		105	+
		106	+ /** 文本「等于」。 */
		107	+ public boolean isTextEquals() {
		108	+ return kind == Kind.TEXT && "等于".equals(matchType);
		109	+ }
		110	+
		111	+ /** 文本「不包含」。 */
		112	+ public boolean isTextNotContains() {
		113	+ return kind == Kind.TEXT && "不包含".equals(matchType);
		114	+ }
		115	+
		116	+ /** 文本「包含」（默认）。 */
		117	+ public boolean isTextContains() {
		118	+ return kind == Kind.TEXT && !"等于".equals(matchType) && !"不包含".equals(matchType);
		119	+ }
		120	+
		121	+ public String getColumn() {
		122	+ return column;
		123	+ }
		124	+
		125	+ public Kind getKind() {
		126	+ return kind;
		127	+ }
		128	+
		129	+ public String getMatchType() {
		130	+ return matchType;
		131	+ }
		132	+
		133	+ public String getTextValue() {
		134	+ return textValue;
		135	+ }
		136	+
		137	+ public Integer getBoolValue() {
		138	+ return boolValue;
		139	+ }
		140	+
		141	+ public boolean isBoolNegated() {
		142	+ return boolNegated;
		143	+ }
		144	+
		145	+ public LocalDateTime getDateStart() {
		146	+ return dateStart;
		147	+ }
		148	+
		149	+ public LocalDateTime getDateEnd() {
		150	+ return dateEnd;
		151	+ }
		152	+
		153	+ public boolean isDateNegated() {
		154	+ return dateNegated;
		155	+ }
		156	+}

backend/src/main/java/com/xly/erp/modules/usr/mapper/UsrUserMapper.java

View file @95bdce3

1	package com.xly.erp.modules.usr.mapper;	1	package com.xly.erp.modules.usr.mapper;
2		2
3	import com.baomidou.mybatisplus.core.mapper.BaseMapper;	3	import com.baomidou.mybatisplus.core.mapper.BaseMapper;
		4	+import com.baomidou.mybatisplus.core.metadata.IPage;
		5	+import com.xly.erp.modules.usr.dto.UserQueryCondition;
4	import com.xly.erp.modules.usr.entity.UsrUser;	6	import com.xly.erp.modules.usr.entity.UsrUser;
		7	+import com.xly.erp.modules.usr.vo.UserVO;
5	import org.apache.ibatis.annotations.Mapper;	8	import org.apache.ibatis.annotations.Mapper;
		9	+import org.apache.ibatis.annotations.Param;
6		10
7	/**	11	/**
8	- * 用户 Mapper（MyBatis-Plus）。REQ-USR-001 T4。	12	+ * 用户 Mapper（MyBatis-Plus）。REQ-USR-001 T4 / REQ-USR-003 T3。
9	*/	13	*/
10	@Mapper	14	@Mapper
11	public interface UsrUserMapper extends BaseMapper<UsrUser> {	15	public interface UsrUserMapper extends BaseMapper<UsrUser> {
		16	+
		17	+ /**
		18	+ * 跨表分页查询（REQ-USR-003）：{@code usr_user LEFT JOIN usr_employee} 取员工名 / 部门，
		19	+ * 按已解析 {@link UserQueryCondition} 施加单字段单匹配过滤；MP 分页插件自动补 LIMIT 与 COUNT(*)。
		20	+ *
		21	+ * <p>不 SELECT {@code sPassword} 与租户列；所有值用 {@code #{}} 预编译占位，
		22	+ * 仅白名单列 token 经 {@code ${}} 注入（由 Service 从固定映射产出，防注入）。</p>
		23	+ *
		24	+ * @param page 分页参数（current/size）
		25	+ * @param cond 已解析查询条件
		26	+ * @return 当前页 UserVO 列表（含真实 total）
		27	+ */
		28	+ IPage<UserVO> selectUserPage(IPage<UserVO> page, @Param("cond") UserQueryCondition cond);
12	}	29	}

backend/src/main/resources/mapper/usr/UsrUserMapper.xml 0 → 100644

View file @95bdce3

		1	+<?xml version="1.0" encoding="UTF-8"?>
		2	+<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
		3	+ "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
		4	+<!-- REQ-USR-003 T3：查询用户跨表分页 SQL（LEFT JOIN + 动态单条件）。
		5	+ map-underscore-to-camel-case=false，故用显式 resultMap 映射列别名到 UserVO 字段；
		6	+ 不 SELECT u.sPassword 与租户列；值用 #{} 预编译占位，列 token 由 Service 白名单产出。 -->
		7	+<mapper namespace="com.xly.erp.modules.usr.mapper.UsrUserMapper">
		8	+
		9	+ <resultMap id="userVOMap" type="com.xly.erp.modules.usr.vo.UserVO">
		10	+ <id property="id" column="id"/>
		11	+ <result property="sUserName" column="sUserName"/>
		12	+ <result property="employeeName" column="employeeName"/>
		13	+ <result property="sUserNo" column="sUserNo"/>
		14	+ <result property="department" column="department"/>
		15	+ <result property="sUserType" column="sUserType"/>
		16	+ <result property="sLanguage" column="sLanguage"/>
		17	+ <result property="iIsVoid" column="iIsVoid"/>
		18	+ <result property="tLastLoginDate" column="tLastLoginDate"/>
		19	+ <result property="sCreator" column="sCreator"/>
		20	+ <result property="tCreateDate" column="tCreateDate"/>
		21	+ </resultMap>
		22	+
		23	+ <select id="selectUserPage" resultMap="userVOMap">
		24	+ SELECT
		25	+ u.iIncrement AS id,
		26	+ u.sUserName AS sUserName,
		27	+ e.sEmployeeName AS employeeName,
		28	+ u.sUserNo AS sUserNo,
		29	+ e.sDepartment AS department,
		30	+ u.sUserType AS sUserType,
		31	+ u.sLanguage AS sLanguage,
		32	+ u.iIsVoid AS iIsVoid,
		33	+ u.tLastLoginDate AS tLastLoginDate,
		34	+ u.sCreator AS sCreator,
		35	+ u.tCreateDate AS tCreateDate
		36	+ FROM usr_user u
		37	+ LEFT JOIN usr_employee e ON u.iEmployeeId = e.iIncrement
		38	+ <where>
		39	+ <if test="cond != null and cond.text">
		40	+ <choose>
		41	+ <when test="cond.textEquals">
		42	+ ${cond.column} = #{cond.textValue}
		43	+ </when>
		44	+ <when test="cond.textNotContains">
		45	+ ${cond.column} NOT LIKE CONCAT('%', #{cond.textValue}, '%') ESCAPE '\\'
		46	+ </when>
		47	+ <otherwise>
		48	+ ${cond.column} LIKE CONCAT('%', #{cond.textValue}, '%') ESCAPE '\\'
		49	+ </otherwise>
		50	+ </choose>
		51	+ </if>
		52	+ <if test="cond != null and cond.bool">
		53	+ <choose>
		54	+ <when test="cond.boolNegated">
		55	+ ${cond.column} <> #{cond.boolValue}
		56	+ </when>
		57	+ <otherwise>
		58	+ ${cond.column} = #{cond.boolValue}
		59	+ </otherwise>
		60	+ </choose>
		61	+ </if>
		62	+ <if test="cond != null and cond.date">
		63	+ <choose>
		64	+ <when test="cond.dateNegated">
		65	+ (${cond.column} < #{cond.dateStart} OR ${cond.column} >= #{cond.dateEnd})
		66	+ </when>
		67	+ <otherwise>
		68	+ ${cond.column} >= #{cond.dateStart} AND ${cond.column} < #{cond.dateEnd}
		69	+ </otherwise>
		70	+ </choose>
		71	+ </if>
		72	+ </where>
		73	+ ORDER BY u.iIncrement
		74	+ </select>
		75	+
		76	+</mapper>

backend/src/test/java/com/xly/erp/modules/usr/mapper/UsrUserMapperPageTest.java 0 → 100644

View file @95bdce3

		1	+package com.xly.erp.modules.usr.mapper;
		2	+
		3	+import static org.assertj.core.api.Assertions.assertThat;
		4	+
		5	+import com.baomidou.mybatisplus.core.metadata.IPage;
		6	+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
		7	+import com.xly.erp.modules.usr.dto.UserQueryCondition;
		8	+import com.xly.erp.modules.usr.entity.UsrEmployee;
		9	+import com.xly.erp.modules.usr.entity.UsrUser;
		10	+import com.xly.erp.modules.usr.vo.UserVO;
		11	+import org.junit.jupiter.api.AfterEach;
		12	+import org.junit.jupiter.api.BeforeEach;
		13	+import org.junit.jupiter.api.Test;
		14	+import org.springframework.beans.factory.annotation.Autowired;
		15	+import org.springframework.boot.test.context.SpringBootTest;
		16	+import org.springframework.test.context.ActiveProfiles;
		17	+import org.springframework.transaction.annotation.Transactional;
		18	+
		19	+/**
		20	+ * REQ-USR-003 T3：UsrUserMapper.selectUserPage 跨表分页查询（LEFT JOIN + 动态条件 XML）。
		21	+ *
		22	+ * <p>@SpringBootTest 连测试库（Flyway 已 apply V1），@Transactional 测试回滚避免污染库。
		23	+ * 插少量 fixture：1 个关联职员的用户、1 个未关联职员的用户、1 个 usr_employee；
		24	+ * 验证 LEFT JOIN 列映射、文本 LIKE 过滤、不返回密码。</p>
		25	+ */
		26	+@SpringBootTest
		27	+@ActiveProfiles("test")
		28	+@Transactional
		29	+class UsrUserMapperPageTest {
		30	+
		31	+ private static final String EMP_NAME = "T3职员_财务";
		32	+ private static final String EMP_DEPT = "财务部T3";
		33	+ private static final String USER_LINKED = "t3_user_linked";
		34	+ private static final String USER_UNLINKED = "t3_user_unlinked";
		35	+
		36	+ @Autowired
		37	+ private UsrUserMapper usrUserMapper;
		38	+
		39	+ @Autowired
		40	+ private UsrEmployeeMapper usrEmployeeMapper;
		41	+
		42	+ private Integer empId;
		43	+
		44	+ @BeforeEach
		45	+ void seed() {
		46	+ UsrEmployee emp = new UsrEmployee();
		47	+ emp.setSEmployeeName(EMP_NAME);
		48	+ emp.setSEmployeeNo("T3_EMP_001");
		49	+ emp.setSDepartment(EMP_DEPT);
		50	+ usrEmployeeMapper.insert(emp);
		51	+ empId = emp.getIIncrement();
		52	+
		53	+ UsrUser linked = newUser(USER_LINKED);
		54	+ linked.setIEmployeeId(empId);
		55	+ usrUserMapper.insert(linked);
		56	+
		57	+ UsrUser unlinked = newUser(USER_UNLINKED);
		58	+ unlinked.setIEmployeeId(null);
		59	+ usrUserMapper.insert(unlinked);
		60	+ }
		61	+
		62	+ @AfterEach
		63	+ void cleanup() {
		64	+ // @Transactional 已回滚；保留显式说明，无需额外清理。
		65	+ }
		66	+
		67	+ private UsrUser newUser(String name) {
		68	+ UsrUser u = new UsrUser();
		69	+ u.setSUserName(name);
		70	+ u.setSPassword("$2a$dummyhash");
		71	+ u.setSUserType("普通用户");
		72	+ u.setSLanguage("中文");
		73	+ u.setICanModifyBill(0);
		74	+ u.setIIsVoid(0);
		75	+ u.setSCreator("t3_seed");
		76	+ return u;
		77	+ }
		78	+
		79	+ @Test
		80	+ void pageReturnsLeftJoinedEmployeeColumns() {
		81	+ IPage<UserVO> page = usrUserMapper.selectUserPage(new Page<>(1, 100), UserQueryCondition.none());
		82	+
		83	+ assertThat(page.getTotal()).isGreaterThanOrEqualTo(2L);
		84	+ UserVO linked = page.getRecords().stream()
		85	+ .filter(v -> USER_LINKED.equals(v.getSUserName())).findFirst().orElseThrow();
		86	+ assertThat(linked.getEmployeeName()).isEqualTo(EMP_NAME);
		87	+ assertThat(linked.getDepartment()).isEqualTo(EMP_DEPT);
		88	+
		89	+ UserVO unlinked = page.getRecords().stream()
		90	+ .filter(v -> USER_UNLINKED.equals(v.getSUserName())).findFirst().orElseThrow();
		91	+ assertThat(unlinked.getEmployeeName()).isNull();
		92	+ assertThat(unlinked.getDepartment()).isNull();
		93	+ }
		94	+
		95	+ @Test
		96	+ void pageAppliesTextLikeOnUserName() {
		97	+ UserQueryCondition cond = UserQueryCondition.text("u.sUserName", "包含", "t3_user_linked");
		98	+ IPage<UserVO> page = usrUserMapper.selectUserPage(new Page<>(1, 10), cond);
		99	+
		100	+ assertThat(page.getRecords()).extracting(UserVO::getSUserName).contains(USER_LINKED);
		101	+ assertThat(page.getRecords()).noneMatch(v -> USER_UNLINKED.equals(v.getSUserName()));
		102	+ assertThat(page.getTotal()).isEqualTo(1L);
		103	+ }
		104	+
		105	+ @Test
		106	+ void pageNeverSelectsPassword() {
		107	+ IPage<UserVO> page = usrUserMapper.selectUserPage(new Page<>(1, 100), UserQueryCondition.none());
		108	+ assertThat(page.getRecords()).isNotEmpty();
		109	+ // UserVO 无密码属性 → 天然不含；额外确认元素类型与查询不抛错。
		110	+ assertThat(page.getRecords().get(0)).isInstanceOf(UserVO.class);
		111	+ }
		112	+}