@Data
@EqualsAndHashCode(callSuper = true)
@TableName("sys_user")
public class SysUser extends BaseEntity {
    
    /** 主键ID - 自增策略 */
    @TableId(type = IdType.AUTO)
    private Long userId;

    /** 用户账号 - 支持Excel导出 */
    @Excel(name = "用户账号")
    private String userName;

    /** 用户性别 - 字典转换导出 */
    @Excel(name = "用户性别", readConverterExp = "0=男,1=女,2=未知")
    private String sex;

    /** 用户状态 - 字典类型 */
    @Excel(name = "用户状态", dictType = "sys_normal_disable")
    private String status;

    /** 部门名称 - 非数据库字段，用于关联查询展示 */
    @TableField(exist = false)
    private String deptName;

    /** 角色列表 - 非数据库字段，用于业务处理 */
    @TableField(exist = false)
    private List<SysRole> roles;

    /** 逻辑删除字段 */
    @TableLogic
    private String delFlag;
}

@SaCheckPermission        // 权限校验
@Log                      // 操作日志
@RepeatSubmit             // 防重复提交
@RateLimiter             // 接口限流
@PostMapping/GetMapping  // 请求映射
public R<Void> method(@Validated @RequestBody Bo bo) { ... }

@RestController
@RequestMapping("/system/user")
public class SysUserController extends BaseController {

    /**
     * 新增用户
     * 完整注解配置示例：权限+日志+防重+校验
     */
    @SaCheckPermission("system:user:add")
    @Log(title = "用户管理", businessType = BusinessType.INSERT)
    @RepeatSubmit()
    @PostMapping
    public R<Void> add(@Validated @RequestBody SysUserBo user) {
        // 数据权限校验
        deptService.checkDeptDataScope(user.getDeptId());
        
        // 业务唯一性校验
        if (!userService.checkUserNameUnique(user)) {
            return R.fail("新增用户'" + user.getUserName() + "'失败，登录账号已存在");
        } else if (StringUtils.isNotEmpty(user.getPhonenumber()) && !userService.checkPhoneUnique(user)) {
            return R.fail("新增用户'" + user.getUserName() + "'失败，手机号码已存在");
        } else if (StringUtils.isNotEmpty(user.getEmail()) && !userService.checkEmailUnique(user)) {
            return R.fail("新增用户'" + user.getUserName() + "'失败，邮箱账号已存在");
        }
        
        // 多租户场景校验
        if (TenantHelper.isEnable()) {
            if (!tenantService.checkAccountBalance(TenantHelper.getTenantId())) {
                return R.fail("当前租户下用户名额不足，请联系管理员");
            }
        }
        
        // 密码加密处理
        user.setPassword(BCrypt.hashpw(user.getPassword()));
        return toAjax(userService.insertUser(user));
    }

    /**
     * 导出用户数据
     * 导出操作必须记录日志并校验权限
     */
    @Log(title = "用户管理", businessType = BusinessType.EXPORT)
    @SaCheckPermission("system:user:export")
    @PostMapping("/export")
    public void export(SysUserBo user, HttpServletResponse response) {
        List<SysUserExportVo> list = userService.selectUserExportList(user);
        ExcelUtil.exportExcel(list, "用户数据", SysUserExportVo.class, response);
    }

    /**
     * 查询用户列表（带数据权限过滤）
     */
    @SaCheckPermission("system:user:list")
    @GetMapping("/list")
    @DataScope(deptAlias = "d", userAlias = "u")
    public TableDataInfo<SysUserVo> list(SysUserBo user) {
        return userService.selectPageUserList(user);
    }

    /**
     * 删除用户（支持批量删除）
     */
    @SaCheckPermission("system:user:remove")
    @Log(title = "用户管理", businessType = BusinessType.DELETE)
    @DeleteMapping("/{userIds}")
    public R<Void> remove(@PathVariable Long[] userIds) {
        if (ArrayUtil.contains(userIds, getUserId())) {
            return R.fail("当前用户不能删除");
        }
        return toAjax(userService.deleteUserByIds(userIds));
    }

    /**
     * 重置密码
     * 敏感操作需要防重复提交
     */
    @SaCheckPermission("system:user:resetPwd")
    @Log(title = "用户管理", businessType = BusinessType.UPDATE)
    @RepeatSubmit()
    @PutMapping("/resetPwd")
    public R<Void> resetPwd(@Validated @RequestBody SysUserBo user) {
        userService.checkUserAllowed(user.getUserId());
        user.setPassword(BCrypt.hashpw(user.getPassword()));
        return toAjax(userService.resetUserPwd(user.getUserId(), user.getPassword()));
    }

    /**
     * 获取验证码（公开接口，无需权限校验）
     * 但需要限流防止接口滥用
     */
    @RateLimiter(count = 5, time = 60)
    @GetMapping("/captchaImage")
    public R<CaptchaVo> getCaptchaImage() {
        return R.ok(captchaService.createCaptcha());
    }
}

@Service
public class SysUserServiceImpl implements ISysUserService {

    /** 新增用户 - 涉及用户表+用户角色关联表，需要事务 */
    @Override
    @Transactional(rollbackFor = Exception.class)
    public int insertUser(SysUserBo user) {
        // 插入用户基本信息
        SysUser sysUser = MapstructUtils.convert(user, SysUser.class);
        int rows = baseMapper.insert(sysUser);
        user.setUserId(sysUser.getUserId());
        // 新增用户与角色关联
        insertUserRole(user);
        // 新增用户与岗位关联
        insertUserPost(user);
        return rows;
    }

    /** 查询方法 - 使用只读事务优化 */
    @Override
    @Transactional(readOnly = true)
    public SysUserVo selectUserById(Long userId) {
        return baseMapper.selectVoById(userId);
    }

    /** 删除用户 - 级联删除多表数据 */
    @Override
    @Transactional(rollbackFor = Exception.class)
    public int deleteUserByIds(Long[] userIds) {
        for (Long userId : userIds) {
            checkUserAllowed(userId);
            checkUserDataScope(userId);
        }
        // 删除用户与角色关联
        userRoleMapper.delete(new LambdaQueryWrapper<SysUserRole>()
            .in(SysUserRole::getUserId, Arrays.asList(userIds)));
        // 删除用户与岗位关联
        userPostMapper.delete(new LambdaQueryWrapper<SysUserPost>()
            .in(SysUserPost::getUserId, Arrays.asList(userIds)));
        // 删除用户
        return baseMapper.deleteBatchIds(Arrays.asList(userIds));
    }
}

public class SysUserBo extends BaseEntity {

    /** 用户ID - 编辑时必填，新增时不填 */
    @NotNull(message = "用户ID不能为空", groups = { EditGroup.class })
    private Long userId;

    /** 用户账号 - 新增和编辑都必填 */
    @NotBlank(message = "用户账号不能为空", groups = { AddGroup.class, EditGroup.class })
    @Size(min = 0, max = 30, message = "用户账号长度不能超过{max}个字符")
    private String userName;

    /** 用户昵称 */
    @NotBlank(message = "用户昵称不能为空")
    @Size(min = 0, max = 30, message = "用户昵称长度不能超过{max}个字符")
    private String nickName;

    /** 用户邮箱 */
    @Email(message = "邮箱格式不正确")
    @Size(min = 0, max = 50, message = "邮箱长度不能超过{max}个字符")
    private String email;

    /** 手机号码 */
    @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不正确")
    private String phonenumber;

    /** 用户密码 - 新增时必填 */
    @NotBlank(message = "用户密码不能为空", groups = { AddGroup.class })
    @Size(min = 5, max = 20, message = "用户密码长度必须在{min}到{max}个字符之间")
    private String password;

    /** 角色ID数组 - 至少选择一个角色 */
    @NotEmpty(message = "用户角色不能为空")
    private Long[] roleIds;
}

// Controller中使用分组校验
@PostMapping
public R<Void> add(@Validated(AddGroup.class) @RequestBody SysUserBo user) { ... }

@PutMapping
public R<Void> edit(@Validated(EditGroup.class) @RequestBody SysUserBo user) { ... }

public class SysUserVo {

    /** 手机号脱敏 - 显示为 138****5678 */
    @Sensitive(strategy = SensitiveStrategy.PHONE)
    private String phonenumber;

    /** 身份证脱敏 - 显示前6后4位 */
    @Sensitive(strategy = SensitiveStrategy.ID_CARD)
    private String idCard;

    /** 邮箱脱敏 - 用户名部分脱敏 */
    @Sensitive(strategy = SensitiveStrategy.EMAIL)
    private String email;

    /** 银行卡脱敏 - 显示前4后4位 */
    @Sensitive(strategy = SensitiveStrategy.BANK_CARD)
    private String bankCard;
}

开始开发
  ├─ 定义实体类？
  │   ├─ 添加 @Data + @TableName + @TableId
  │   ├─ 需要导出？添加 @Excel
  │   ├─ 有非DB字段？添加 @TableField(exist = false)
  │   └─ 逻辑删除？添加 @TableLogic
  │
  ├─ 开发Controller接口？
  │   ├─ 公开接口（登录/验证码）？仅添加 @RateLimiter
  │   ├─ 查询接口？添加 @SaCheckPermission
  │   ├─ 增删改接口？添加 @SaCheckPermission + @Log + @RepeatSubmit
  │   ├─ 导出接口？添加 @SaCheckPermission + @Log(EXPORT)
  │   └─ 参数校验？添加 @Validated + BO中定义校验规则
  │
  ├─ 编写Service业务逻辑？
  │   ├─ 纯查询？添加 @Transactional(readOnly = true)
  │   ├─ 涉及多表操作？添加 @Transactional(rollbackFor = Exception.class)
  │   └─ 单表简单操作？可不加事务注解
  │
  └─ 定义BO/DTO？
      ├─ 必填字段？添加 @NotNull / @NotBlank / @NotEmpty
      ├─ 字符串长度限制？添加 @Size(min, max)
      ├─ 邮箱/手机号？添加 @Email / @Pattern
      └─ 新增/编辑规则不同？使用分组校验 AddGroup/EditGroup

// 错误写法
public R<Void> add(@RequestBody SysUserBo user) { ... }

// 正确写法
public R<Void> add(@Validated @RequestBody SysUserBo user) { ... }

// 正确配置
@Excel(name = "用户性别", dictType = "sys_user_sex")
private String sex;

// 或使用readConverterExp
@Excel(name = "用户性别", readConverterExp = "0=男,1=女,2=未知")
private String sex;

// 全局配置表忽略租户
@TableName(value = "sys_dict_data", excludeProperty = "tenantId")
public class SysDictData extends BaseEntity { ... }

// 异步任务传递租户上下文
String tenantId = TenantHelper.getTenantId();
CompletableFuture.runAsync(() -> {
    TenantHelper.setTenantId(tenantId);
    // 业务逻辑
});

// Controller方法注解顺序
@SaCheckPermission("权限标识")      // 1. 权限校验
@Log(title = "模块", businessType)  // 2. 操作日志
@RepeatSubmit()                     // 3. 防重复提交
@RateLimiter(count, time)          // 4. 接口限流
@PostMapping("/path")               // 5. 请求映射
public R<Vo> method(@Validated @RequestBody Bo bo) { ... }

system:user:list    // 用户列表查询
system:user:add     // 新增用户
system:user:edit    // 编辑用户
system:user:remove  // 删除用户
system:user:export  // 导出用户
system:user:import  // 导入用户
system:user:resetPwd // 重置密码

// Service层抛出业务异常
throw new ServiceException("用户名已存在");

// 全局异常处理器自动捕获并返回统一格式
@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(ServiceException.class)
    public R<Void> handleServiceException(ServiceException e) {
        return R.fail(e.getMessage());
    }
}