Merge remote-tracking branch 'origin/master'

2026-08-26 15:12:29 +08:00
commit 3ff79fbfae
@@ -67,8 +67,7 @@ public interface RemoteUserService {
     * @return 含准确总数的轻量用户分页；调用方必须检查业务状态和空数据
     */
    @PostMapping("/user/basic-page")
-    R<Page<UserVO>> getScopeBasicUserPage(@RequestParam("current") Long current, @RequestParam("size") Long size,
-                                          @RequestBody UserDTO userDTO);
+    R<Page<UserVO>> getScopeBasicUserPage(@RequestParam("current") Long current, @RequestParam("size") Long size, @RequestBody UserDTO userDTO);

    /**
     * 按当前登录人的数据权限分页查询导出所需的完整用户主资料和身份资料。
@@ -4,9 +4,10 @@ package com.bsd.pjcloud.admin.api.vo.base;
 * 用户及其所属部门的通用数据契约。
 *
 * <p>历史业务模型使用 {@code userMobile}、{@code userAvatar}、{@code userDeptName} 等字段，
- * 标准别名用于直接适配管理端 {@code UserInfoCell} 组件，同时通过默认方法保持已有实现兼容。</p>
+ * 标准别名用于直接适配管理端 {@code UserInfoCell} 组件，同时通过默认方法保持已有实现兼容。
+ * 本接口继承基础用户契约，使实现类可以直接用于只要求用户主资料的通用装配方法。</p>
 */
-public interface BaseUserDeptInterface {
+public interface BaseUserDeptInterface extends BaseUserInterface, BaseUserPhoneInterface {
    /**
     * 获取用户主键。
     *
@@ -114,6 +115,7 @@ public interface BaseUserDeptInterface {
     *
     * @return 用户手机号；未绑定时为空
     */
+    @Override
    default String getPhone() {
        return getUserMobile();
    }
@@ -123,6 +125,7 @@ public interface BaseUserDeptInterface {
     *
     * @param phone 用户手机号，未绑定时可为空
     */
+    @Override
    default void setPhone(String phone) {
        setUserMobile(phone);
    }
@@ -9,9 +9,10 @@ import java.util.List;
 * 管理端用户身份信息组件使用的通用数据契约。
 *
 * <p>字段与 {@code UserIdentityInfo} 组件的输入保持一致，业务 VO 实现该接口后可直接承载
- * UPMS 批量查询得到的身份类型、学生资料和老师资料。</p>
+ * UPMS 批量查询得到的身份类型、学生资料和老师资料。标准手机号方法继承自
+ * {@link BaseUserPhoneInterface}，避免与用户部门接口的历史字段默认适配产生继承冲突。</p>
 */
-public interface BaseUserIdentityInterface {
+public interface BaseUserIdentityInterface extends BaseUserPhoneInterface {

    /**
     * 获取用户主键，用于批量查询和回填身份资料。
@@ -27,20 +28,6 @@ public interface BaseUserIdentityInterface {
     */
    void setUserId(Long userId);

-    /**
-     * 获取默认用户身份展示的手机号。
-     *
-     * @return 用户绑定手机号；未绑定时可为空
-     */
-    String getPhone();
-
-    /**
-     * 设置默认用户身份展示的手机号。
-     *
-     * @param phone 用户绑定手机号，未绑定时可为空
-     */
-    void setPhone(String phone);
-
    /**
     * 获取用户拥有的身份协议编码。
     *
@@ -0,0 +1,24 @@
+package com.bsd.pjcloud.admin.api.vo.base;
+
+/**
+ * 用户标准手机号的公共数据契约。
+ *
+ * <p>用户部门与用户身份接口都会使用标准手机号。将方法声明收敛到共同父接口，可让部门接口继续
+ * 提供历史字段适配的默认实现，同时避免两个无关接口组成交叉类型时产生默认方法与抽象方法冲突。</p>
+ */
+public interface BaseUserPhoneInterface {
+
+    /**
+     * 获取用户标准手机号。
+     *
+     * @return 用户绑定手机号；未绑定或尚未补充用户资料时可为空
+     */
+    String getPhone();
+
+    /**
+     * 设置用户标准手机号。
+     *
+     * @param phone 用户绑定手机号；未绑定或需要清空展示值时可为空
+     */
+    void setPhone(String phone);
+}
@@ -97,10 +97,14 @@ public class SysUserController {

    private final SysUserService userService;

-    /** 用户 Excel 导入导出服务，统一承接用户模块的文件转换与导入编排。 */
+    /**
+     * 用户 Excel 导入导出服务，统一承接用户模块的文件转换与导入编排。
+     */
    private final SysUserImportExportService userImportExportService;

-    /** 用户 Excel 导出服务，独立承接模板填充、身份资料组装和结果文件保存。 */
+    /**
+     * 用户 Excel 导出服务，独立承接模板填充、身份资料组装和结果文件保存。
+     */
    private final SysUserExportService userExportService;

    private final RemoterVisitorService remoterVisitorService;
@@ -110,7 +114,9 @@ public class SysUserController {
    private final SysRoleService sysRoleService;

    private final SysUserRoleService sysUserRoleService;
-    /** 学生身份服务，用于跨服务开卡导入按学校和学号精确定位学生。 */
+    /**
+     * 学生身份服务，用于跨服务开卡导入按学校和学号精确定位学生。
+     */
    private final SysUserStudentService sysUserStudentService;
    private final SysMessageService sysMessageService;
    /* ************************************* start 回调 start ************************************* */
@@ -162,7 +168,7 @@ public class SysUserController {
     * 根据学校和学号精确查询学生用户，供钱包学生开卡导入校验使用。
     *
     * @param schoolName 学生身份扩展信息中的学校名称
-     * @param studentNo 学生身份扩展信息中的学号
+     * @param studentNo  学生身份扩展信息中的学号
     * @return 唯一学生用户；不存在时返回失败响应
     */
    @GetMapping("/get-student-by-school-and-no")
@@ -336,14 +342,15 @@ public class SysUserController {
     *
     * <p>该接口供无需返回角色、岗位、人脸和审批信息、但可能按人脸录入状态筛选的业务列表调用，避免复用管理端完整用户分页产生额外查询。</p>
     *
-     * @param page 分页参数
+     * @param page    分页参数
     * @param userDTO 用户关键字、部门树和指定用户筛选条件
     * @return 包含用户总数、基础信息、部门和身份资料的轻量分页
     */
    @ApiCryptoAes
    @PostMapping("/basic-page")
    public R<IPage<UserVO>> getBasicUserPage(@ParameterObject Page page, @RequestBody UserDTO userDTO) {
-        return R.ok(userService.getBasicUsersPage(page, userDTO, DataScope.of()));
+        DataScope dataScope = DataScope.of();
+        return R.ok(userService.getBasicUsersPage(page, userDTO, dataScope));
    }

    /**
@@ -351,7 +358,7 @@ public class SysUserController {
     *
     * <p>该接口供跨服务后台导出分批读取，返回账号主资料、角色岗位和身份扩展，跳过人脸及审批流程。</p>
     *
-     * @param page 分页参数
+     * @param page    分页参数
     * @param userDTO 用户关键字、部门树和指定用户筛选条件
     * @return 包含用户总数和完整导出资料的分页
     */
@@ -468,11 +475,11 @@ public class SysUserController {
    }

    /**
-	 * 导入后台用户基础信息，接口同步校验整份 Excel，校验通过后返回异步任务供调用端轮询。
+     * 导入后台用户基础信息，接口同步校验整份 Excel，校验通过后返回异步任务供调用端轮询。
     *
-     * @param excelVOList Excel 中解析出的后台用户数据
+     * @param excelVOList   Excel 中解析出的后台用户数据
     * @param bindingResult Excel 通用校验产生的错误信息
-	 * @return 校验失败时包含对应行号和错误原因；校验通过时包含异步任务 ID 和初始进度
+     * @return 校验失败时包含对应行号和错误原因；校验通过时包含异步任务 ID 和初始进度
     */
    @PostMapping("/import")
    @HasPermission("sys_user_import")
@@ -481,11 +488,11 @@ public class SysUserController {
    }

    /**
-	 * 导入学生用户，接口同步校验整份 Excel，校验通过后返回异步任务供调用端轮询。
+     * 导入学生用户，接口同步校验整份 Excel，校验通过后返回异步任务供调用端轮询。
     *
     * @param studentUserExcelList Excel 中解析出的学生用户数据
-     * @param bindingResult Excel 通用校验产生的错误信息
-	 * @return 校验失败时包含对应行号和错误原因；校验通过时包含异步任务 ID 和初始进度
+     * @param bindingResult        Excel 通用校验产生的错误信息
+     * @return 校验失败时包含对应行号和错误原因；校验通过时包含异步任务 ID 和初始进度
     */
    @PostMapping("/import-student")
    @HasPermission("sys_student_user_export")
@@ -495,12 +502,12 @@ public class SysUserController {
    }

    /**
-	 * 导入学生家长用户，接口同步校验整份 Excel，校验通过后返回异步任务供调用端轮询。
+     * 导入学生家长用户，接口同步校验整份 Excel，校验通过后返回异步任务供调用端轮询。
     * <p>手机号和部门必填；姓名为空时按“手机号 + 学生家长”生成，手机号同时作为登录账号和初始密码。</p>
     *
     * @param guardianUserExcelList Excel 中解析出的学生家长用户数据
-     * @param bindingResult Excel 通用校验产生的错误信息
-	 * @return 校验失败时包含对应行号和错误原因；校验通过时包含异步任务 ID 和初始进度
+     * @param bindingResult         Excel 通用校验产生的错误信息
+     * @return 校验失败时包含对应行号和错误原因；校验通过时包含异步任务 ID 和初始进度
     */
    @PostMapping("/import-guardian")
    @HasPermission("sys_guardian_user_export")
@@ -510,12 +517,12 @@ public class SysUserController {
    }

    /**
-	 * 导入老师用户，接口同步校验整份 Excel，校验通过后返回异步任务供调用端轮询。
+     * 导入老师用户，接口同步校验整份 Excel，校验通过后返回异步任务供调用端轮询。
     * <p>模板中的手机号作为登录账号，学号写入老师扩展表，老师身份单独保存为 TEACHER。</p>
     *
     * @param teacherUserExcelList Excel 中解析出的老师用户数据
-     * @param bindingResult Excel 通用校验产生的错误信息
-	 * @return 校验失败时包含对应行号和错误原因；校验通过时包含异步任务 ID 和初始进度
+     * @param bindingResult        Excel 通用校验产生的错误信息
+     * @return 校验失败时包含对应行号和错误原因；校验通过时包含异步任务 ID 和初始进度
     */
    @PostMapping("/import-teacher")
    @HasPermission("sys_teacher_user_export")
@@ -525,12 +532,12 @@ public class SysUserController {
    }

    /**
-	 * 导入用户及 Excel 中内嵌的人脸图片，接口同步校验并复制图片字节，校验通过后返回异步任务供调用端轮询。
+     * 导入用户及 Excel 中内嵌的人脸图片，接口同步校验并复制图片字节，校验通过后返回异步任务供调用端轮询。
     *
-     * @param file 原始 Excel 文件，用于读取内嵌的人脸图片
-     * @param excelList Excel 中解析出的用户数据
+     * @param file          原始 Excel 文件，用于读取内嵌的人脸图片
+     * @param excelList     Excel 中解析出的用户数据
     * @param bindingResult Excel 通用校验产生的错误信息
-	 * @return 校验失败时包含校验或图片处理错误；校验通过时包含异步任务 ID 和初始进度
+     * @return 校验失败时包含校验或图片处理错误；校验通过时包含异步任务 ID 和初始进度
     */
    @PostMapping("/import-face")
    @HasPermission("sys_user_import")
@@ -342,7 +342,8 @@ public class SysUserServiceImpl extends ServiceImpl<SysUserMapper, SysUser> impl
     */
    @Override
    public IPage<UserVO> getUsersWithRolePage(Page page, UserDTO userDTO, DataScope dataScope) {
-        if (ObjectUtil.isNotEmpty(dataScope)) {
+        if (dataScope != null) {
+            // 用户查询只按所属部门做数据权限过滤，不能再用用户创建人限制可见范围。
            dataScope.setScopeUserName(null);
        }
        IPage<UserVO> list = baseMapper.getUserVosPage(page, userDTO, dataScope);
@@ -378,8 +379,8 @@ public class SysUserServiceImpl extends ServiceImpl<SysUserMapper, SysUser> impl
     */
    @Override
    public IPage<UserVO> getBasicUsersPage(Page page, UserDTO userDTO, DataScope dataScope) {
-        if (ObjectUtil.isNotEmpty(dataScope)) {
-            // 用户查询只按所属部门做数据权限过滤，不能再用用户创建人限制可见范围。
+        if (dataScope != null) {
+            // DataScope 继承 HashMap，不能使用集合非空判断；此查询只按所属部门过滤。
            dataScope.setScopeUserName(null);
        }
        IPage<UserVO> list = baseMapper.getBasicUserPage(page, userDTO, dataScope);
@@ -401,7 +402,7 @@ public class SysUserServiceImpl extends ServiceImpl<SysUserMapper, SysUser> impl
     */
    @Override
    public IPage<UserVO> getExportUsersPage(Page page, UserDTO userDTO, DataScope dataScope) {
-        if (ObjectUtil.isNotEmpty(dataScope)) {
+        if (dataScope != null) {
            // 导出与列表使用相同的部门数据权限口径，不按创建人额外缩小用户范围。
            dataScope.setScopeUserName(null);
        }