---

req_id: REQ-USR-003 date: 2026-05-08

module: usr

Spec: REQ-USR-003 — 查询用户

目标

超级管理员可按 8 种查询字段 + 3 种匹配方式组合筛选，分页浏览本品牌下的用户列表；列表同时展示关联职员的员工名与部门。

输入 / 触发

HTTP 请求：GET /api/usr/users（需 Bearer Token 鉴权）

Query 参数：

参数	类型	必填	默认值	说明
queryField	String	否	username	查询字段枚举，见下表
matchType	String	否	contains	匹配方式枚举：contains / notContains / equals
queryValue	String	否	—	查询值；空字符串或不传 = 全部
page	int	否	1	页码，从 1 开始
pageSize	int	否	20	每页条数，最大 100

queryField 枚举（前端显示名 → 参数值 → 后端列）：

前端显示	参数值	后端列
用户名	username	u.sUsername
员工名	staffName	s.sStaffName
用户号	userCode	u.sUserCode
部门	department	s.sDepartment
用户类型	userType	u.sUserType
作废	disabled	u.bIsDisabled
登录日期	lastLoginDate	u.tLastLoginDate
制单人	creator	u.sCreatorUsername

输出 / 结果

HTTP 200，Result<PageVO<UserListItemVO>>

PageVO<T> 结构（通用分页包装）：

{
  "total": 25,
  "page": 1,
  "pageSize": 20,
  "list": [ ...UserListItemVO... ]
}

UserListItemVO 字段（禁止返回 sPasswordHash / iLoginFailCount / tLockUntil）：

JSON 字段	来源列	可 null
sId	usr_user.sId	否
sUsername	usr_user.sUsername	否
sUserCode	usr_user.sUserCode	否
sUserType	usr_user.sUserType	否
sLanguage	usr_user.sLanguage	否
bIsDisabled	usr_user.bIsDisabled	否
tLastLoginDate	usr_user.tLastLoginDate	是
sCreatorUsername	usr_user.sCreatorUsername	是
tCreateDate	usr_user.tCreateDate	否
sStaffName	tStaff.sStaffName	是（LEFT JOIN）
sDepartment	tStaff.sDepartment	是（LEFT JOIN）

业务规则

1. 多租户隔离：所有查询必须附加 u.sBrandsId = principal.brandId()
2. queryValue 为空：忽略查询条件，返回该品牌全部用户
3. 匹配方式映射（文本字段：username / staffName / userCode / department / userType / creator）：
   • contains → LIKE '%value%'
   • notContains → NOT LIKE '%value%'
   • equals → = 'value'
4. 布尔字段（disabled）：仅有意义的匹配是 equals；queryValue="是" → bIsDisabled = 1；"否" → bIsDisabled = 0；其他值（包括 contains/notContains 的非 "是"/"否"）忽略条件
5. 日期字段（lastLoginDate）：queryValue 格式 YYYY-MM-DD；无论 matchType 为何，均使用 DATE(tLastLoginDate) = 'YYYY-MM-DD'
6. pageSize 截断：pageSize > 100 时强制截断为 100
7. 分页越界：page 超出总页数时返回最后一页（MyBatis-Plus Page 默认行为）
8. 职员 JOIN：LEFT JOIN tStaff s ON u.sEmployeeId = s.sId AND s.sBrandsId = u.sBrandsId AND s.bDeleted = 0；未关联职员时 sStaffName / sDepartment 为 null

边界与约束

• 接口为只读，无写副作用
• 鉴权失败返回 401（SecurityConfig.authenticationEntryPoint 已配置）
• 单次最多返回 100 条

依赖的 schema 表 / 字段

• usr_user (别名 u)：sId, sUsername, sUserCode, sUserType, sLanguage, bIsDisabled, sEmployeeId, sCreatorUsername, tLastLoginDate, tCreateDate, sBrandsId
• tStaff (别名 s)：sId, sStaffName, sDepartment, sBrandsId, bDeleted

依赖的接口

• POST /api/auth/login（REQ-USR-004，获取 Bearer Token 供本接口鉴权使用）

验收标准

1. GET /api/usr/users（无参）HTTP 200，返回本品牌所有用户，不含密码字段
2. queryField=username&matchType=contains&queryValue=admin 仅返回 sUsername 含 "admin" 的用户
3. queryField=disabled&matchType=equals&queryValue=是 仅返回 bIsDisabled=1 的记录
4. 无匹配条件时返回 { total: 0, list: [] } 而非 4xx/5xx
5. page=999（超出总页）返回最后一页而不报错
6. Token 品牌 A 无法查到品牌 B 的用户（多租户隔离）
7. 响应 JSON 中不含 sPasswordHash / iLoginFailCount / tLockUntil
8. 无 Token 请求返回 401