BJ_FS / urbanops

  # UrbanOps 系统鉴权方式说明文档
  
  > **项目**: 蓟城山水集团全域智能运营管理平台 (UrbanOps)  
  > **版本**: 基于 2026-06-11 代码分析  
  > **适用对象**: 前端开发、第三方对接、运维部署
  
  ---
  
  ## 目录
  
  - [1. 鉴权体系概览](#1-鉴权体系概览)
  - [2. Token 令牌鉴权（核心机制）](#2-token-令牌鉴权核心机制)
  - [3. 用户名密码登录鉴权](#3-用户名密码登录鉴权)
  - [4. 短信验证码登录鉴权](#4-短信验证码登录鉴权)
  - [5. OAuth2 授权服务器](#5-oauth2-授权服务器)
  - [6. API 签名鉴权（第三方对接）](#6-api-签名鉴权第三方对接)
  - [7. 社交登录鉴权（JustAuth）](#7-社交登录鉴权justauth)
  - [8. UAA SSO 单点登录](#8-uaa-sso-单点登录)
  - [9. RBAC 权限鉴权](#9-rbac-权限鉴权)
  - [10. 租户隔离鉴权](#10-租户隔离鉴权)
  - [11. 数据权限鉴权（行级安全）](#11-数据权限鉴权行级安全)
  - [12. API 加密](#12-api-加密)
  - [13. 接口前缀与鉴权方式对照表](#13-接口前缀与鉴权方式对照表)
  
  ---
  
  ## 1. 鉴权体系概览
  
  UrbanOps 采用 **多层鉴权架构**，从请求进入系统到数据返回，依次经过以下安全层级：
  
  ```
  请求到达
    │
    ├── 第0层: API 加密过滤 (ApiEncryptFilter)          ← 可选，按 @ApiEncrypt 注解启用
    │
    ├── 第1层: 租户隔离 (TenantSecurityWebFilter)       ← /admin-api/, /app-api/ 强制
    │
    ├── 第2层: Token 令牌校验 (TokenAuthenticationFilter) ← /admin-api/, /app-api/ 强制
    │
    ├── 第3层: 方法级权限 (Spring Security @PreAuthorize) ← /admin-api/ 方法级
    │
    └── 第4层: 数据权限 (DeptDataPermissionRule)          ← /admin-api/ MyBatis SQL 注入
  ```
  
  ---
  
  ## 2. Token 令牌鉴权（核心机制）
  
  ### 2.1 概述
  
  Token 令牌鉴权是系统的核心认证方式，覆盖所有 `/admin-api/` 和 `/app-api/` 接口。系统通过自定义 `TokenAuthenticationFilter` 拦截每个请求，提取并验证 Token。
  
  ### 2.2 核心类
  
  | 类名 | 路径 |
  |------|------|
  | `TokenAuthenticationFilter` | `urbanops-framework/urbanops-spring-boot-starter-security/src/main/java/com/zteits/urbanops/framework/security/core/filter/TokenAuthenticationFilter.java` |
  | `SecurityProperties` | `urbanops-framework/urbanops-spring-boot-starter-security/src/main/java/com/zteits/urbanops/framework/security/config/SecurityProperties.java` |
  | `OAuth2TokenServiceImpl` | `urbanops-module-system/src/main/java/com/zteits/urbanops/module/system/service/oauth2/OAuth2TokenServiceImpl.java` |
  | `SecurityFrameworkUtils` | `urbanops-framework/urbanops-spring-boot-starter-security/src/main/java/com/zteits/urbanops/framework/security/core/util/SecurityFrameworkUtils.java` |
  
  ### 2.3 配置项
  
  ```yaml
  # application.yaml
  urbanops:
    security:
      token-header: Authorization        # 请求头名称
      token-parameter: token             # Query参数名称（WebSocket场景用）
      mock-enable: false                 # 开发环境Mock模式开关
      mock-secret: test                  # Mock模式密钥前缀
      password-encoder-length: 4         # BCrypt加密强度
  ```
  
  ### 2.4 工作流程
  
  ```
  客户端请求（带 Authorization: Bearer {token}）
    │
    ▼
  TokenAuthenticationFilter.doFilterInternal()
    │
    ├── 1. 提取 Token
    │     方式A: 从请求头 Authorization 提取
    │     方式B: 从查询参数 ?token=xxx 提取（WebSocket 场景）
    │
    ├── 2. 推断 userType
    │     /admin-api/ → ADMIN(2)
    │     /app-api/   → MEMBER(1)
    │
    ├── 3. 调用 oauth2TokenApi.checkAccessToken(token) 校验
    │     先查 Redis（key: oauth2_access_token:{token}）
    │     缓存未命中则查 MySQL（system_oauth2_access_token 表）
    │
    ├── 4. 校验 userType 匹配
    │     防止 admin token 访问 app 接口（反之亦然）
    │
    ├── 5. 构建 LoginUser 对象
    │     包含 userId, userType, tenantId, scopes, userInfo
    │
    └── 6. 设置到 SecurityContextHolder
         后续 Controller 可通过 SecurityFrameworkUtils.getLoginUser() 获取
  ```
  
  ### 2.5 实现代码示例
  
  **Token 提取与验证核心代码：** `TokenAuthenticationFilter.java`
  
  ```java
  @RequiredArgsConstructor
  public class TokenAuthenticationFilter extends OncePerRequestFilter {
  
      private final SecurityProperties securityProperties;
      private final GlobalExceptionHandler globalExceptionHandler;
  
      @Override
      protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
                                      FilterChain chain) throws ServletException, IOException {
          // 从请求头或查询参数中提取 Token
          String token = SecurityFrameworkUtils.obtainAuthorization(
                  request, securityProperties.getTokenHeader(), 
                  securityProperties.getTokenParameter());
          
          if (StrUtil.isNotEmpty(token)) {
              Integer userType = WebFrameworkUtils.getLoginUserType(request);
              try {
                  // 1. 基于 token 构建登录用户
                  LoginUser loginUser = buildLoginUserByToken(token, userType);
                  // 2. 模拟登录（开发环境 fallback）
                  if (loginUser == null) {
                      loginUser = mockLoginUser(request, token, userType);
                  }
                  // 3. 设置当前用户到 SecurityContext
                  if (loginUser != null) {
                      SecurityFrameworkUtils.setLoginUser(loginUser, request);
                  }
              } catch (Throwable ex) {
                  // Token 非法或过期，直接返回错误 JSON，中断过滤器链
                  CommonResult<?> result = globalExceptionHandler.allExceptionHandler(request, ex);
                  ServletUtils.writeJSON(response, result);
                  return;
              }
          }
          // 4. 继续执行后续过滤器
          chain.doFilter(request, response);
      }
  
      private LoginUser buildLoginUserByToken(String token, Integer userType) {
          // 调用内部 OAuth2 服务校验 token
          OAuth2AccessTokenCheckRespDTO accessToken = oauth2TokenApi.checkAccessToken(token);
          if (accessToken == null) {
              return null;
          }
          // 校验用户类型匹配
          if (ObjectUtil.notEqual(accessToken.getUserType(), userType)) {
              throw new AccessDeniedException("错误的用户类型");
          }
          // 构建 LoginUser
          LoginUser loginUser = new LoginUser();
          loginUser.setId(accessToken.getUserId());
          loginUser.setUserType(accessToken.getUserType());
          loginUser.setTenantId(accessToken.getTenantId());
          loginUser.setScopes(accessToken.getScopes());
          loginUser.setContext(accessToken.getUserInfo());
          return loginUser;
      }
  }
  ```
  
  **Token 生成核心代码：** `OAuth2TokenServiceImpl.java`
  
  ```java
  @Service
  public class OAuth2TokenServiceImpl implements OAuth2TokenService {
  
      @Resource
      private OAuth2AccessTokenMapper oauth2AccessTokenMapper;
      @Resource
      private OAuth2AccessTokenRedisDAO oauth2AccessTokenRedisDAO;
      @Resource
      private OAuth2RefreshTokenMapper oauth2RefreshTokenMapper;
  
      @Override
      public OAuth2AccessTokenDO createAccessToken(Long userId, Integer userType, 
                                                    String clientId, List<String> scopes) {
          OAuth2ClientDO client = oauth2ClientService.validOAuthClientFromCache(clientId);
          // 生成 Token（UUID 无连字符）
          OAuth2AccessTokenDO accessToken = new OAuth2AccessTokenDO();
          accessToken.setAccessToken(IdUtil.fastSimpleUUID());   // 32位十六进制
          accessToken.setRefreshToken(IdUtil.fastSimpleUUID());
          accessToken.setUserId(userId);
          accessToken.setUserType(userType);
          accessToken.setClientId(clientId);
          accessToken.setScopes(scopes);
          accessToken.setExpiresTime(LocalDateTime.now()
                  .plusSeconds(client.getAccessTokenValiditySeconds()));
          // 双重存储：MySQL + Redis
          oauth2AccessTokenMapper.insert(accessToken);
          oauth2AccessTokenRedisDAO.set(accessToken);
          return accessToken;
      }
  
      @Override
      public OAuth2AccessTokenCheckRespDTO checkAccessToken(String accessToken) {
          // 先从 Redis 缓存获取（高性能）
          OAuth2AccessTokenDO accessTokenDO = oauth2AccessTokenRedisDAO.get(accessToken);
          if (accessTokenDO == null) {
              // 缓存未命中，查 MySQL 兜底
              accessTokenDO = oauth2AccessTokenMapper.selectByAccessToken(accessToken);
              if (accessTokenDO != null) {
                  // 回写 Redis 缓存
                  oauth2AccessTokenRedisDAO.set(accessTokenDO);
              }
          }
          if (accessTokenDO == null || isExpired(accessTokenDO)) {
              throw exception(OAUTH2_ACCESS_TOKEN_NOT_FOUND_OR_EXPIRED);
          }
          return convertToCheckDTO(accessTokenDO);
      }
  }
  ```
  
  ### 2.6 调用示例
  
  ```bash
  # 请求管理后台接口（需要在请求头带上 Token）
  curl -X GET "https://test.jichengshanshui.com.cn:28302/admin-api/system/dept/list" \
    -H "Authorization: Bearer a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
  
  # 返回成功示例
  {
    "code": 0,
    "msg": "成功",
    "data": { ... }
  }
  
  # Token 无效返回示例
  {
    "code": 401,
    "msg": "访问令牌不存在或已过期"
  }
  ```
  
  ---
  
  ## 3. 用户名密码登录鉴权
  
  ### 3.1 概述
  
  系统提供标准的用户名+密码登录方式，通过 BCrypt 密码比对验证用户身份，登录成功后返回 accessToken 和 refreshToken。
  
  ### 3.2 核心类
  
  | 类名 | 路径 |
  |------|------|
  | `AuthController` | `urbanops-module-system/src/main/java/com/zteits/urbanops/module/system/controller/admin/auth/AuthController.java` |
  | `AdminAuthServiceImpl` | `urbanops-module-system/src/main/java/com/zteits/urbanops/module/system/service/auth/AdminAuthServiceImpl.java` |
  | `BCryptPasswordEncoder` | `urbanops-framework/urbanops-spring-boot-starter-security/src/main/java/com/zteits/urbanops/framework/security/config/UrbanopsSecurityAutoConfiguration.java` |
  
  ### 3.3 工作流程
  
  ```
  POST /system/auth/login { username, password }
    │
    ▼
  AuthController.login()
    │
    ▼
  AdminAuthService.login()
    │
    ├── 1. authenticate(username, password)
    │      ├── 根据 username 查询 AdminUserDO
    │      ├── 如果未找到，尝试按手机号查询
    │      ├── BCrypt 比对密码（强度4）
    │      ├── 检查用户状态（是否禁用）
    │      └── 记录登录日志
    │
    ├── 2. 处理社交账号绑定（可选）
    │
    └── 3. createTokenAfterLoginSuccess()
           ├── 创建 OAuth2AccessTokenDO
           ├── 存储到 MySQL + Redis
           └── 返回 { accessToken, refreshToken, expiresTime }
  ```
  
  ### 3.4 实现代码示例
  
  **Controller 层：** `AuthController.java`
  
  ```java
  @Tag(name = "管理后台 - 认证")
  @RestController
  @RequestMapping("/system/auth")
  @Validated
  public class AuthController {
  
      @Resource
      private AdminAuthService authService;
  
      @PostMapping("/login")
      @PermitAll
      @Operation(summary = "使用账号密码登录")
      public CommonResult<AuthLoginRespVO> login(@RequestBody @Valid AuthLoginReqVO reqVO) {
          return success(authService.login(reqVO));
      }
  }
  ```
  
  **Service 实现层 — 身份验证：** `AdminAuthServiceImpl.java`
  
  ```java
  @Service
  public class AdminAuthServiceImpl implements AdminAuthService {
  
      @Resource
      private AdminUserService userService;
  
      /**
       * 账号密码认证
       */
      public AdminUserDO authenticate(String username, String password) {
          final LoginLogTypeEnum logTypeEnum = LoginLogTypeEnum.LOGIN_USERNAME;
          
          // 1. 校验账号是否存在（先按用户名，再按手机号）
          AdminUserDO user = userService.getUserByUsername(username);
          if (user == null) {
              user = userService.getUserByMobile(username);
              if (user == null) {
                  createLoginLog(null, username, logTypeEnum, LoginResultEnum.BAD_CREDENTIALS);
                  throw exception(AUTH_LOGIN_BAD_CREDENTIALS);
              }
          }
          
          // 2. BCrypt 密码比对
          if (!userService.isPasswordMatch(password, user.getPassword())) {
              createLoginLog(user.getId(), username, logTypeEnum, LoginResultEnum.BAD_CREDENTIALS);
              throw exception(AUTH_LOGIN_BAD_CREDENTIALS);
          }
          
          // 3. 校验用户状态
          if (CommonStatusEnum.isDisable(user.getStatus())) {
              createLoginLog(user.getId(), username, logTypeEnum, LoginResultEnum.USER_DISABLED);
              throw exception(AUTH_LOGIN_USER_DISABLED);
          }
          return user;
      }
  
      /**
       * 登录：认证 → 创建 Token → 返回
       */
      @Override
      @DataPermission(enable = false)  // 关闭数据权限（登录时无需数据过滤）
      public AuthLoginRespVO login(AuthLoginReqVO reqVO) {
          AdminUserDO user = authenticate(reqVO.getUsername(), reqVO.getPassword());
          return createTokenAfterLoginSuccess(user.getId(), reqVO.getUsername(), 
                  LoginLogTypeEnum.LOGIN_USERNAME);
      }
  
      private AuthLoginRespVO createTokenAfterLoginSuccess(Long userId, String username, 
                                                            LoginLogTypeEnum logType) {
          // 创建 Token
          OAuth2AccessTokenDO accessToken = oauth2TokenService.createAccessToken(
                  userId, UserTypeEnum.ADMIN.getValue(), 
                  OAuth2ClientConstants.CLIENT_ID_DEFAULT, null);
          // 记录登录成功日志
          createLoginLog(userId, username, logType, LoginResultEnum.SUCCESS);
          // 返回结果
          return AuthConvert.INSTANCE.convert(accessToken);
      }
  }
  ```
  
  ### 3.5 调用示例
  
  ```bash
  # 用户名密码登录
  curl -X POST "https://test.jichengshanshui.com.cn:28302/admin-api/system/auth/login" \
    -H "Content-Type: application/json" \
    -d '{
      "username": "admin",
      "password": "admin123"
    }'
  
  # 返回示例
  {
    "code": 0,
    "msg": "成功",
    "data": {
      "accessToken": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
      "refreshToken": "p6o5n4m3l2k1j0i9h8g7f6e5d4c3b2a1",
      "expiresTime": "2026-06-12T10:30:00",
      "userId": 1,
      "userType": 2
    }
  }
  ```
  
  ---
  
  ## 4. 短信验证码登录鉴权
  
  ### 4.1 概述
  
  系统支持通过短信验证码方式进行免密登录，先发送验证码到用户手机，再通过验证码完成身份认证。
  
  ### 4.2 核心类
  
  | 类名 | 路径 |
  |------|------|
  | `AuthController` | `urbanops-module-system/.../controller/admin/auth/AuthController.java` |
  | `AdminAuthServiceImpl` | `urbanops-module-system/.../service/auth/AdminAuthServiceImpl.java` |
  | `SmsCodeApi` | `urbanops-framework/urbanops-common/.../biz/system/sms/SmsCodeApi.java` |
  
  ### 4.3 工作流程
  
  ```
  ① 发送验证码
  POST /system/auth/send-sms-code { mobile }
    │
    ▼
  AuthController.sendSmsCode()
    └── smsCodeApi.sendSmsCode(mobile, scene)
          └── 发送短信 + 存储验证码到 Redis（带过期时间）
  
  ② 验证码登录
  POST /system/auth/sms-login { mobile, code }
    │
    ▼
  AuthController.smsLogin()
    │
    ▼
  AdminAuthService.smsLogin()
    ├── 1. smsCodeApi.useSmsCode(mobile, code)  ← 校验验证码
    ├── 2. userService.getUserByMobile(mobile)   ← 查找用户
    └── 3. createTokenAfterLoginSuccess()         ← 创建 Token
  ```
  
  ### 4.4 实现代码示例
  
  **Controller 层：** `AuthController.java`
  
  ```java
  @PostMapping("/send-sms-code")
  @PermitAll
  @Operation(summary = "发送手机验证码")
  public CommonResult<Boolean> sendSmsCode(@RequestBody @Valid AuthSendSmsReqVO reqVO) {
      smsCodeApi.sendSmsCode(reqVO.getMobile(), SmsSceneEnum.ADMIN_MEMBER_LOGIN.getScene(), 
                             WebFrameworkUtils.getClientIP());
      return success(true);
  }
  
  @PostMapping("/sms-login")
  @PermitAll
  @Operation(summary = "使用短信验证码登录")
  public CommonResult<AuthLoginRespVO> smsLogin(@RequestBody @Valid AuthSmsLoginReqVO reqVO) {
      return success(authService.smsLogin(reqVO));
  }
  ```
  
  **Service 实现层：** `AdminAuthServiceImpl.java`
  
  ```java
  @Override
  public AuthLoginRespVO smsLogin(AuthSmsLoginReqVO reqVO) {
      // 1. 校验验证码（一次性消费，用过即删）
      smsCodeApi.useSmsCode(
              AuthConvert.INSTANCE.convert(
                      reqVO, 
                      SmsSceneEnum.ADMIN_MEMBER_LOGIN.getScene(), 
                      getClientIP()
              )
      );
      
      // 2. 根据手机号获取用户
      AdminUserDO user = userService.getUserByMobile(reqVO.getMobile());
      if (user == null) {
          throw exception(USER_NOT_EXISTS);
      }
      
      // 3. 创建 Token
      return createTokenAfterLoginSuccess(
              user.getId(), reqVO.getMobile(), LoginLogTypeEnum.LOGIN_MOBILE);
  }
  ```
  
  ### 4.5 调用示例
  
  ```bash
  # 步骤1: 发送短信验证码
  curl -X POST "https://test.jichengshanshui.com.cn:28302/admin-api/system/auth/send-sms-code" \
    -H "Content-Type: application/json" \
    -d '{"mobile": "13800138000"}'
  
  # 返回
  { "code": 0, "msg": "成功", "data": true }
  
  # 步骤2: 验证码登录
  curl -X POST "https://test.jichengshanshui.com.cn:28302/admin-api/system/auth/sms-login" \
    -H "Content-Type: application/json" \
    -d '{
      "mobile": "13800138000",
      "code": "123456"
    }'
  
  # 返回（同密码登录）
  {
    "code": 0,
    "msg": "成功",
    "data": {
      "accessToken": "x1y2z3...",
      "refreshToken": "z3y2x1...",
      "expiresTime": "2026-06-12T10:30:00"
    }
  }
  ```
  
  ---
  
  ## 5. OAuth2 授权服务器
  
  ### 5.1 概述
  
  系统内置完整的 OAuth2 授权服务器实现，支持 5 种标准授权模式，可同时作为授权服务和资源服务对外提供标准 OAuth2 接口。
  
  ### 5.2 核心类
  
  | 类名 | 路径 |
  |------|------|
  | `OAuth2OpenController` | `urbanops-module-system/.../controller/admin/oauth2/OAuth2OpenController.java` |
  | `OAuth2GrantServiceImpl` | `urbanops-module-system/.../service/oauth2/OAuth2GrantServiceImpl.java` |
  | `OAuth2TokenServiceImpl` | `urbanops-module-system/.../service/oauth2/OAuth2TokenServiceImpl.java` |
  | `OAuth2ClientServiceImpl` | `urbanops-module-system/.../service/oauth2/OAuth2ClientServiceImpl.java` |
  | `OAuth2GrantTypeEnum` | `urbanops-module-system/.../enums/oauth2/OAuth2GrantTypeEnum.java` |
  
  ### 5.3 支持的授权模式
  
  | 授权模式 | grant_type 值 | 说明 |
  |----------|--------------|------|
  | 密码模式 | `password` | 直接使用用户名+密码换取 Token |
  | 授权码模式 | `authorization_code` | 先获取授权码 code，再换取 Token |
  | 客户端模式 | `client_credentials` | 客户端以自己的名义访问资源 |
  | 刷新令牌 | `refresh_token` | 使用 refreshToken 刷新 accessToken |
  | 隐式模式 | `implicit` | 通过 `/authorize` 端点直接返回 Token |
  
  ### 5.4 OAuth2 端点
  
  | 端点 | 方法 | 鉴权方式 | 说明 |
  |------|------|----------|------|
  | `/system/oauth2/token` | POST | `@PermitAll` (client_id + client_secret Basic Auth) | 签发 Token |
  | `/system/oauth2/check-token` | POST | `@PermitAll` (client_id + client_secret Basic Auth) | 校验 Token |
  | `/system/oauth2/revoke-token` | DELETE | `@PermitAll` (client_id + client_secret Basic Auth) | 撤销 Token |
  | `/system/oauth2/authorize` | GET | `@PermitAll` (需已登录用户) | 授权页面（SSO 入口） |
  | `/system/oauth2/authorize` | POST | `@PermitAll` (需已登录用户) | 用户确认授权 |
  
  ### 5.5 实现代码示例
  
  **`/token` 端点核心代码：** `OAuth2OpenController.java`
  
  ```java
  @Tag(name = "管理后台 - OAuth2.0")
  @RestController
  @RequestMapping("/system/oauth2")
  @Validated
  public class OAuth2OpenController {
  
      @Resource
      private OAuth2GrantService oauth2GrantService;
      @Resource
      private OAuth2ClientService oauth2ClientService;
  
      @PostMapping("/token")
      @PermitAll
      @Operation(summary = "获得访问令牌", 
                 description = "支持 authorization_code / password / client_credentials / refresh_token 四种模式")
      public CommonResult<OAuth2OpenAccessTokenRespVO> postAccessToken(
              HttpServletRequest request,
              @RequestParam("grant_type") String grantType,
              @RequestParam(value = "code", required = false) String code,
              @RequestParam(value = "redirect_uri", required = false) String redirectUri,
              @RequestParam(value = "state", required = false) String state,
              @RequestParam(value = "username", required = false) String username,
              @RequestParam(value = "password", required = false) String password,
              @RequestParam(value = "scope", required = false) String scope,
              @RequestParam(value = "refresh_token", required = false) String refreshToken) {
  
          List<String> scopes = OAuth2Utils.buildScopes(scope);
          OAuth2GrantTypeEnum grantTypeEnum = OAuth2GrantTypeEnum.getByGrantType(grantType);
  
          // 1. 解析 Basic Auth，获取 client_id 和 client_secret
          String[] clientIdAndSecret = obtainBasicAuthorization(request);
          // 2. 校验客户端合法性
          OAuth2ClientDO client = oauth2ClientService.validOAuthClientFromCache(
                  clientIdAndSecret[0], clientIdAndSecret[1], 
                  grantType, scopes, redirectUri);
  
          // 3. 根据授权模式分发处理
          OAuth2AccessTokenDO accessTokenDO;
          switch (grantTypeEnum) {
              case AUTHORIZATION_CODE:
                  accessTokenDO = oauth2GrantService.grantAuthorizationCodeForAccessToken(
                          client.getClientId(), code, redirectUri, state);
                  break;
              case PASSWORD:
                  accessTokenDO = oauth2GrantService.grantPassword(
                          username, password, client.getClientId(), scopes);
                  break;
              case CLIENT_CREDENTIALS:
                  accessTokenDO = oauth2GrantService.grantClientCredentials(
                          client.getClientId(), scopes);
                  break;
              case REFRESH_TOKEN:
                  accessTokenDO = oauth2GrantService.grantRefreshToken(
                          refreshToken, client.getClientId());
                  break;
              default:
                  throw new IllegalArgumentException("未知授权类型：" + grantType);
          }
          
          Assert.notNull(accessTokenDO, "访问令牌不能为空");
          return success(OAuth2OpenConvert.INSTANCE.convert(accessTokenDO));
      }
  
      /**
       * 从请求头解析 Basic Auth 获取 client_id:client_secret
       */
      private String[] obtainBasicAuthorization(HttpServletRequest request) {
          String header = request.getHeader("Authorization");
          if (StrUtil.isEmpty(header) || !header.startsWith("Basic ")) {
              throw exception(ErrorCodeConstants.UNKNOWN);
          }
          String base64Credentials = header.substring(6);
          String credentials = new String(Base64.getDecoder().decode(base64Credentials));
          return credentials.split(":", 2);
      }
  }
  ```
  
  **各授权模式的实现：** `OAuth2GrantServiceImpl.java`
  
  ```java
  @Service
  public class OAuth2GrantServiceImpl implements OAuth2GrantService {
  
      @Resource
      private OAuth2TokenService oauth2TokenService;
      @Resource
      private AdminAuthService adminAuthService;
  
      /**
       * 密码模式：直接用用户名密码换 Token
       */
      @Override
      public OAuth2AccessTokenDO grantPassword(String username, String password, 
                                                String clientId, List<String> scopes) {
          // BCrypt 验证用户名密码
          AdminUserDO user = adminAuthService.authenticate(username, password);
          Assert.notNull(user, "用户不能为空！");
          return oauth2TokenService.createAccessToken(
                  user.getId(), UserTypeEnum.ADMIN.getValue(), clientId, scopes);
      }
  
      /**
       * 授权码模式：用 code 换取 Token
       */
      @Override
      public OAuth2AccessTokenDO grantAuthorizationCodeForAccessToken(
              String clientId, String code, String redirectUri, String state) {
          OAuth2CodeDO codeDO = oauth2CodeService.validCode(code);
          Assert.notNull(codeDO, "授权码不存在");
          // 校验 clientId、redirectUri、state 是否匹配
          oauth2CodeService.validateCode(codeDO, clientId, redirectUri, state);
          // 删除已使用的授权码
          oauth2CodeService.deleteCode(code);
          return oauth2TokenService.createAccessToken(
                  codeDO.getUserId(), codeDO.getUserType(), 
                  clientId, codeDO.getScopes());
      }
  
      /**
       * 客户端模式：系统用户 Token（userId=0）
       */
      @Override
      public OAuth2AccessTokenDO grantClientCredentials(String clientId, List<String> scopes) {
          return oauth2TokenService.createAccessToken(
                  0L, UserTypeEnum.ADMIN.getValue(), clientId, scopes);
      }
  
      /**
       * 刷新令牌：用 refreshToken 刷新 accessToken
       */
      @Override
      public OAuth2AccessTokenDO grantRefreshToken(String refreshToken, String clientId) {
          return oauth2TokenService.refreshAccessToken(refreshToken, clientId);
      }
  }
  ```
  
  ### 5.6 调用示例
  
  ```bash
  # 密码模式：客户端凭证 Basic Auth + 用户密码换取 Token
  curl -X POST "https://test.jichengshanshui.com.cn:28302/admin-api/system/oauth2/token" \
    -H "Authorization: Basic ZGVmYXVsdDphZG1pbjEyMw==" \
    -d "grant_type=password&username=admin&password=admin123"
  
  # 客户端模式：仅用客户端凭证换取 Token
  curl -X POST "https://test.jichengshanshui.com.cn:28302/admin-api/system/oauth2/token" \
    -H "Authorization: Basic ZGVmYXVsdDphZG1pbjEyMw==" \
    -d "grant_type=client_credentials"
  
  # 刷新令牌
  curl -X POST "https://test.jichengshanshui.com.cn:28302/admin-api/system/oauth2/token" \
    -H "Authorization: Basic ZGVmYXVsdDphZG1pbjEyMw==" \
    -d "grant_type=refresh_token&refresh_token=abc123..."
  
  # 返回格式
  {
    "code": 0,
    "msg": "成功",
    "data": {
      "access_token": "a1b2c3d4...",
      "refresh_token": "p6o5n4m3...",
      "token_type": "bearer",
      "expires_in": 7200,
      "scope": "read write"
    }
  }
  ```
  
  ---
  
  ## 6. API 签名鉴权（第三方对接）
  
  ### 6.1 概述
  
  面向 `/open-api/` 前缀的第三方系统对接接口，通过 HMAC-SHA256 请求签名机制实现无状态的接口鉴权，防止请求被篡改、重放。
  
  ### 6.2 核心类
  
  | 类名 | 路径 |
  |------|------|
  | `@ApiSignature` 注解 | `urbanops-framework/urbanops-spring-boot-starter-protection/src/main/java/com/zteits/urbanops/framework/signature/core/annotation/ApiSignature.java` |
  | `ApiSignatureAspect` 切面 | `urbanops-framework/urbanops-spring-boot-starter-protection/src/main/java/com/zteits/urbanops/framework/signature/core/aop/ApiSignatureAspect.java` |
  
  ### 6.3 签名参数（请求头）
  
  | 请求头 | 类型 | 说明 |
  |--------|------|------|
  | `appId` | string | 应用唯一标识（由平台分配） |
  | `timestamp` | long | 请求时间戳（毫秒） |
  | `nonce` | string | 随机字符串（>= 10 位，防重放） |
  | `sign` | string | 签名字符串（SHA256 结果） |
  
  ### 6.4 签名规则
  
  ```
  签名字符串 = sorted(queryParams, by key) 
             + requestBody 
             + sorted({appId, timestamp, nonce} headers, by key) 
             + appSecret
  
  最终签名 = SHA256(签名字符串)
  ```
  
  ### 6.5 工作流程
  
  ```
  客户端请求（带 appId, timestamp, nonce, sign 请求头）
    │
    ▼
  @ApiSignature 注解的方法
    │
    ▼
  ApiSignatureAspect.beforePointCut()  ← @Before AOP 拦截
    │
    ├── 1. verifyHeaders() 校验请求头完整性
    │      ├── appId 非空
    │      ├── timestamp 在时间窗口内（默认 60s）
    │      ├── nonce 长度 >= 10
    │      └── sign 非空
    │
    ├── 2. 从 Redis 根据 appId 获取 appSecret
    │
    ├── 3. 服务端按相同规则计算签名字符串
    │      serverSignStr = sorted(queryParams) + body + sorted(headers) + appSecret
    │
    ├── 4. 比对签名：SHA256(serverSignStr) == clientSign
    │
    └── 5. nonce 防重放：存入 Redis（有效期 = timeout * 2）
  ```
  
  ### 6.6 实现代码示例
  
  **@ApiSignature 注解定义：**
  
  ```java
  @Inherited
  @Documented
  @Target({ElementType.METHOD, ElementType.TYPE})
  @Retention(RetentionPolicy.RUNTIME)
  public @interface ApiSignature {
      
      /** 签名超时时间，默认 60 秒 */
      int timeout() default 60;
      
      /** 超时时间单位，默认秒 */
      TimeUnit timeUnit() default TimeUnit.SECONDS;
      
      /** 签名校验失败提示信息 */
      String message() default "签名不正确";
      
      /** 应用ID 请求头字段名 */
      String appId() default "appId";
      
      /** 时间戳 请求头字段名 */
      String timestamp() default "timestamp";
      
      /** 随机数 请求头字段名（长度 >= 10） */
      String nonce() default "nonce";
      
      /** 签名 请求头字段名 */
      String sign() default "sign";
  }
  ```
  
  **签名校验切面实现：** `ApiSignatureAspect.java`
  
  ```java
  @Aspect
  @RequiredArgsConstructor
  public class ApiSignatureAspect {
  
      private final ApiSignatureRedisDAO signatureRedisDAO;
  
      /**
       * @Before 拦截所有标注 @ApiSignature 的方法
       */
      @Before("@annotation(signature)")
      public void beforePointCut(JoinPoint joinPoint, ApiSignature signature) {
          HttpServletRequest request = ServletUtils.getRequest();
          if (!verifySignature(signature, request)) {
              throw new ServiceException(GlobalErrorCodeConstants.BAD_REQUEST.getCode(), 
                                         signature.message());
          }
      }
  
      /**
       * 完整的签名验证流程
       */
      public boolean verifySignature(ApiSignature signature, HttpServletRequest request) {
          // 1. 校验请求头完整性
          if (!verifyHeaders(signature, request)) {
              return false;
          }
          
          // 2. 根据 appId 获取 appSecret
          String appId = request.getHeader(signature.appId());
          String appSecret = signatureRedisDAO.getAppSecret(appId);
          Assert.notNull(appSecret, "[appId({})] 找不到对应的 appSecret", appId);
  
          // 3. 服务端按相同规则构造签名字符串
          String serverSignatureString = buildSignatureString(signature, request, appSecret);
          String serverSignature = DigestUtil.sha256Hex(serverSignatureString);
  
          // 4. 比对客户端签名
          String clientSignature = request.getHeader(signature.sign());
          if (ObjUtil.notEqual(clientSignature, serverSignature)) {
              return false;
          }
  
          // 5. nonce 防重放（存入 Redis，过期时间 = timeout * 2）
          String nonce = request.getHeader(signature.nonce());
          if (BooleanUtil.isFalse(
                  signatureRedisDAO.setNonce(appId, nonce, signature.timeout() * 2, signature.timeUnit()))) {
              throw new ServiceException(GlobalErrorCodeConstants.REPEATED_REQUESTS.getCode(), 
                                         "存在重复请求");
          }
          return true;
      }
  
      /**
       * 校验请求头参数
       */
      private boolean verifyHeaders(ApiSignature signature, HttpServletRequest request) {
          String appId = request.getHeader(signature.appId());
          String timestamp = request.getHeader(signature.timestamp());
          String nonce = request.getHeader(signature.nonce());
          String sign = request.getHeader(signature.sign());
  
          // appId 不能为空
          if (StrUtil.isBlank(appId)) return false;
          // timestamp 必须在有效时间窗口内
          if (StrUtil.isBlank(timestamp)) return false;
          long ts = Long.parseLong(timestamp);
          long now = System.currentTimeMillis();
          long timeoutMs = signature.timeUnit().toMillis(signature.timeout());
          if (Math.abs(now - ts) > timeoutMs) return false;
          // nonce 长度必须 >= 10
          if (StrUtil.length(nonce) < 10) return false;
          // sign 不能为空
          if (StrUtil.isBlank(sign)) return false;
  
          return true;
      }
  
      /**
       * 构造签名字符串：
       * sorted(GET参数) + 请求体 + sorted(Header加签参数) + appSecret
       */
      private String buildSignatureString(ApiSignature signature, HttpServletRequest request, 
                                           String appSecret) {
          StringBuilder sb = new StringBuilder();
          
          // 1. 排序后的查询参数
          Map<String, String[]> paramMap = request.getParameterMap();
          if (CollUtil.isNotEmpty(paramMap)) {
              TreeMap<String, String> sorted = new TreeMap<>();
              paramMap.forEach((key, values) -> sorted.put(key, values[0]));
              sorted.forEach((key, value) -> sb.append(value));
          }
          
          // 2. 请求体（POST/PUT 场景）
          String body = ServletUtils.getBody(request);
          if (StrUtil.isNotBlank(body)) {
              sb.append(body);
          }
          
          // 3. 排序后的加签头参数
          TreeMap<String, String> headerMap = new TreeMap<>();
          headerMap.put(signature.appId(), request.getHeader(signature.appId()));
          headerMap.put(signature.timestamp(), request.getHeader(signature.timestamp()));
          headerMap.put(signature.nonce(), request.getHeader(signature.nonce()));
          headerMap.values().forEach(sb::append);
          
          // 4. 追加 appSecret
          sb.append(appSecret);
          
          return sb.toString();
      }
  }
  ```
  
  ### 6.7 使用示例
  
  **服务端 Controller：**
  
  ```java
  @RestController
  @RequestMapping("/open-api/partner")
  public class PartnerOpenController {
  
      @PostMapping("/data-sync")
      @ApiSignature(timeout = 120, message = "签名验证失败，请检查签名参数")
      public CommonResult<String> syncData(@RequestBody PartnerDataDTO data) {
          // 签名已在 AOP 层面自动验证，此处可以直接处理业务
          partnerService.syncData(data);
          return success("同步成功");
      }
  }
  ```
  
  **客户端调用示例（Java）：**
  
  ```java
  public class ApiSignatureClient {
  
      private static final String APP_ID = "your_app_id";
      private static final String APP_SECRET = "your_app_secret";
  
      public static String callOpenApi(String url, String requestBody) {
          // 1. 生成参数
          String timestamp = String.valueOf(System.currentTimeMillis());
          String nonce = RandomUtil.randomString(16);
  
          // 2. 构造签名字符串
          String signStr = requestBody + APP_ID + timestamp + nonce + APP_SECRET;
          String sign = DigestUtil.sha256Hex(signStr);
  
          // 3. 发起请求
          HttpResponse response = HttpRequest.post(url)
                  .header("appId", APP_ID)
                  .header("timestamp", timestamp)
                  .header("nonce", nonce)
                  .header("sign", sign)
                  .header("Content-Type", "application/json")
                  .body(requestBody)
                  .execute();
  
          return response.body();
      }
  }
  ```
  
  **cURL 调用示例：**
  
  ```bash
  # 计算签名（shell 示例）
  APP_ID="my_app_001"
  APP_SECRET="my_secret_key"
  TIMESTAMP=$(date +%s%3N)
  NONCE=$(openssl rand -hex 16)
  BODY='{"name":"test","value":123}'
  SIGN_STR="${BODY}${APP_ID}${TIMESTAMP}${NONCE}${APP_SECRET}"
  SIGN=$(echo -n "$SIGN_STR" | openssl dgst -sha256 -hex | awk '{print $2}')
  
  # 发起请求
  curl -X POST "https://test.jichengshanshui.com.cn:28302/open-api/partner/data-sync" \
    -H "Content-Type: application/json" \
    -H "appId: ${APP_ID}" \
    -H "timestamp: ${TIMESTAMP}" \
    -H "nonce: ${NONCE}" \
    -H "sign: ${SIGN}" \
    -d "${BODY}"
  
  # 签名失败返回
  { "code": 400, "msg": "签名验证失败，请检查签名参数" }
  ```
  
  ---
  
  ## 7. 社交登录鉴权（JustAuth）
  
  ### 7.1 概述
  
  系统集成 JustAuth 1.16.7，支持 30+ 第三方社交平台登录。用户可通过微信、QQ、钉钉、GitHub 等平台授权后登录系统。
  
  ### 7.2 核心类
  
  | 类名 | 路径 |
  |------|------|
  | `AuthRequestFactory` | `urbanops-module-system/.../framework/justauth/core/AuthRequestFactory.java` |
  | `UrbanopsJustAuthConfiguration` | `urbanops-module-system/.../framework/justauth/config/UrbanopsJustAuthConfiguration.java` |
  | `RedisStateCache` | JustAuth 内置（State 存储到 Redis） |
  
  ### 7.3 支持的平台
  
  GitHub · 微信开放平台 · 微信公众号 · 微信小程序 · 企业微信 · 微信网站应用 · QQ · 微博 · 钉钉 · 支付宝 · Google · Facebook · Apple · 飞书 · 以及 30+ 其他平台
  
  ### 7.4 工作流程
  
  ```
  用户点击"社交登录"
    │
    ▼
  GET /system/auth/social-auth-redirect?type={platform}&redirectUri={url}
    │
    ├── AuthRequestFactory.get(type) 获取对应平台的 AuthRequest
    ├── 生成授权 URL（含 state 参数，state 存入 Redis）
    └── 前端 302 跳转到第三方授权页面
          │
          ▼
  用户授权后，第三方回调 redirectUri（带 code + state 参数）
    │
    ▼
  前端提取 code + state，调用后端
    │
    ▼
  POST /system/auth/social-login { type, code, state }
    │
    ├── 1. AuthRequestFactory.get(type).login(callback)
    │       ├── getAccessToken(AuthCallback) → 用 code 换 accessToken
    │       └── getUserInfo(AuthToken)         → 获取用户信息
    │
    ├── 2. 根据 socialUserId 查找绑定关系
    ├── 3. 自动注册 / 绑定已有用户
    └── 4. createTokenAfterLoginSuccess()
  ```
  
  ### 7.5 实现代码示例
  
  **JustAuth 配置类：** `UrbanopsJustAuthConfiguration.java`
  
  ```java
  @Configuration(proxyBeanMethods = false)
  @EnableConfigurationProperties({JustAuthProperties.class})
  public class UrbanopsJustAuthConfiguration {
  
      /**
       * 创建 AuthRequest 工厂（条件 Bean：justauth.enabled=true 时激活）
       */
      @Bean
      @ConditionalOnProperty(prefix = "justauth", value = {"enabled"}, 
                             havingValue = "true", matchIfMissing = true)
      public AuthRequestFactory authRequestFactory(JustAuthProperties properties, 
                                                    AuthStateCache authStateCache) {
          return new AuthRequestFactory(properties, authStateCache);
      }
  
      /**
       * OAuth2 State 参数缓存（Redis 存储，防 CSRF）
       */
      @Bean
      public AuthStateCache authStateCache(
              RedisTemplate<String, String> justAuthRedisCacheTemplate,
              JustAuthProperties justAuthProperties) {
          return new RedisStateCache(justAuthRedisCacheTemplate, 
                                     justAuthProperties.getCache());
      }
  }
  ```
  
  **社交登录请求工厂：** `AuthRequestFactory.java`
  
  ```java
  public class AuthRequestFactory {
  
      private final JustAuthProperties properties;
      private final AuthStateCache authStateCache;
      private final ConcurrentHashMap<String, AuthRequest> requestCache = new ConcurrentHashMap<>();
  
      /**
       * 获取指定平台的授权请求对象
       */
      public AuthRequest get(String source) {
          return requestCache.computeIfAbsent(source, this::getDefaultRequest);
      }
  
      /**
       * 根据平台名称创建对应的 JustAuth 请求类
       */
      private AuthRequest getDefaultRequest(String source) {
          AuthConfig config = properties.getType().get(source);
          Assert.notNull(config, "平台 [{}] 的配置不存在", source);
          
          // 注入自定义 state 缓存（Redis）
          config.setAuthStateCache(authStateCache);
  
          switch (source.toUpperCase()) {
              case "GITHUB":
                  return new AuthGithubRequest(config, authStateCache);
              case "WECHAT_OPEN":
                  return new AuthWeChatOpenRequest(config, authStateCache);
              case "WECHAT_MP":
                  return new AuthWeChatMpRequest(config, authStateCache);
              case "QQ":
                  return new AuthQqRequest(config, authStateCache);
              case "DINGTALK":
                  return new AuthDingTalkRequest(config, authStateCache);
              case "FEISHU":
                  return new AuthFeishuRequest(config, authStateCache);
              case "ALIPAY":
                  return new AuthAlipayRequest(config, authStateCache);
              case "GOOGLE":
                  return new AuthGoogleRequest(config, authStateCache);
              case "FACEBOOK":
                  return new AuthFacebookRequest(config, authStateCache);
              case "APPLE":
                  return new AuthAppleRequest(config, authStateCache);
              case "UAA":
                  return new AuthUaaRequest(config, authStateCache);  // 自定义 UAA SSO
              // ... 30+ 其他平台 ...
              default:
                  return null;
          }
      }
  }
  ```
  
  ### 7.6 调用示例
  
  ```bash
  # 步骤1: 获取社交登录授权 URL
  curl -X GET "https://test.jichengshanshui.com.cn:28302/admin-api/system/auth/social-auth-redirect?type=GITHUB&redirectUri=https://example.com/callback"
  
  # 返回
  {
    "code": 0,
    "data": {
      "url": "https://github.com/login/oauth/authorize?client_id=xxx&redirect_uri=xxx&state=xxx"
    }
  }
  
  # 步骤2: 用户跳转到 GitHub 授权，回调到 redirectUri
  # 浏览器地址栏: https://example.com/callback?code=abc123&state=xxx
  
  # 步骤3: 前端提取 code + state，调用后端完成登录
  curl -X POST "https://test.jichengshanshui.com.cn:28302/admin-api/system/auth/social-login" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "GITHUB",
      "code": "abc123",
      "state": "xxx"
    }'
  
  # 返回（同密码登录）
  {
    "code": 0,
    "msg": "成功",
    "data": {
      "accessToken": "token...",
      "refreshToken": "refresh..."
    }
  }
  ```
  
  ---
  
  ## 8. UAA SSO 单点登录
  
  ### 8.1 概述
  
  系统对接集团统一认证平台 UAA（Unified Authentication Application），通过自定义 `AuthUaaRequest` 实现企业级单点登录。用户登录 UAA 后即可无缝访问 UrbanOps。
  
  ### 8.2 核心类
  
  | 类名 | 路径 |
  |------|------|
  | `AuthUaaRequest` | `urbanops-module-system/.../framework/justauth/core/AuthUaaRequest.java` |
  | `SsoService` | `urbanops-module-system/.../service/oauth2/SsoService.java` |
  | `CustomerAuthSource.UAA` | 自定义 AuthSource 枚举值 |
  
  ### 8.3 UAA 配置
  
  ```yaml
  sso:
    client:
      switch-state: true
      client-id: urbanops
      client-secret: ${SSO_CLIENT_SECRET}
      base-url: https://uaa.fangshanparking.com:28201
      redirect-uri: ${urbanops.base-url}/admin-api/system/auth/social-login
      jwt-public-key: MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...
  ```
  
  ### 8.4 工作流程
  
  ```
  用户访问 UrbanOps → 未登录 → 重定向到 UAA 登录页
    │
    ▼
  UAA 登录成功后回调 redirectUri（带 authorization_code）
    │
    ▼
  POST /system/auth/social-login { type: "UAA", code, state }
    │
    ▼
  AuthUaaRequest
    ├── getAccessToken(callback)
    │     └── POST https://uaa.fangshanparking.com:28201/oauth2/token
    │          code=xxx&grant_type=authorization_code&redirect_uri=xxx
    │
    └── getUserInfo(authToken)
          └── 使用 pub.cer 公钥解密 JWT token（RSA256）
               ├── 提取 account（工号）
               ├── 提取公司 ID
               ├── 提取业务线
               └── 构建 AuthUser 对象
  ```
  
  ### 8.5 实现代码示例
  
  **自定义 UAA JustAuth 请求：** `AuthUaaRequest.java`
  
  ```java
  public class AuthUaaRequest extends AuthDefaultRequest {
  
      public AuthUaaRequest(AuthConfig config, AuthStateCache authStateCache) {
          super(config, CustomerAuthSource.UAA, authStateCache);
      }
  
      /**
       * 步骤1：用 authorization_code 向 UAA 服务器换取 access_token
       */
      @Override
      public AuthToken getAccessToken(AuthCallback authCallback) {
          String tokenUrl = source.accessToken();
          
          // 构造请求体
          Map<String, String> params = new HashMap<>();
          params.put("code", authCallback.getCode());
          params.put("grant_type", "authorization_code");
          params.put("redirect_uri", authCallback.getRedirectUri());
  
          // POST /oauth2/token
          String response = new HttpUtils(config.getHttpConfig())
                  .post(tokenUrl, params, this.config.isIgnoreRedirect());
          
          JSONObject json = JSONUtil.parseObj(response);
          
          // 校验响应
          checkResponse(json);
          
          return AuthToken.builder()
                  .accessToken(json.getStr("access_token"))
                  // ...其他字段...
                  .build();
      }
  
      /**
       * 步骤2：从 JWT access_token 中解析用户身份信息
       */
      @Override
      public AuthUser getUserInfo(AuthToken authToken) {
          try {
              // 从 classpath 读取 UAA 公钥证书
              CertificateFactory certificateFactory = CertificateFactory.getInstance("X.509");
              ClassPathResource resource = new ClassPathResource("pub.cer");
              Certificate certificate = certificateFactory.generateCertificate(resource.getInputStream());
              RSAPublicKey publicKey = (RSAPublicKey) certificate.getPublicKey();
  
              // 创建 JWT 验证器（RSA256 算法）
              Algorithm algorithm = Algorithm.RSA256(publicKey, null);
              JWTVerifier verifier = JWT.require(algorithm)
                      .acceptLeeway(60)          // 允许 60 秒时钟偏差
                      .build();
  
              // 验证并解析 JWT
              DecodedJWT decodedJWT = verifier.verify(authToken.getAccessToken());
              DecodedJWT jwt = JWT.decode(authToken.getAccessToken());
  
              // 提取 JWT payload 中的用户信息
              String staffNo = jwt.getClaim("account").asString();      // 工号
              String companyId = jwt.getClaim("company_id").asString(); // 公司ID
              String busiLine = jwt.getClaim("busi_line").asString();   // 业务线
  
              return AuthUser.builder()
                      .uuid(staffNo)
                      .username(staffNo)
                      .nickname(staffNo)
                      .gender(AuthUserGender.UNKNOWN)
                      .token(authToken)
                      .source(this.source.toString())
                      .build();
  
          } catch (Exception e) {
              throw new BusinessException("UAA SSO 登录失败：" + e.getMessage(), e);
          }
      }
  
      /**
       * 校验 UAA 返回的 Token 响应
       */
      private void checkResponse(JSONObject json) {
          if (json.containsKey("error")) {
              throw new AuthException(json.getStr("error_description"));
          }
      }
  }
  ```
  
  ---
  
  ## 9. RBAC 权限鉴权
  
  ### 9.1 概述
  
  系统采用基于角色的访问控制（RBAC）模型，通过 Spring Security 的 `@PreAuthorize` 注解在方法级别进行权限控制。权限表达式中的 `@ss` Bean 提供 `hasPermission`、`hasRole`、`hasScope` 三个维度的权限判断。
  
  ### 9.2 核心类
  
  | 类名 | 路径 |
  |------|------|
  | `SecurityFrameworkServiceImpl` (Bean name: `ss`) | `urbanops-framework/urbanops-spring-boot-starter-security/src/main/java/com/zteits/urbanops/framework/security/core/service/SecurityFrameworkServiceImpl.java` |
  | `PermissionCommonApi` | `urbanops-framework/urbanops-common/src/main/java/com/zteits/urbanops/framework/common/biz/system/permission/PermissionCommonApi.java` |
  
  ### 9.3 权限格式规范
  
  ```
  {模块}:{实体}:{操作}
  
  示例：
    system:dept:create          — 系统管理 · 部门 · 创建
    system:dept:update          — 系统管理 · 部门 · 更新
    system:user:query           — 系统管理 · 用户 · 查询
    workorder:event-info:create — 工单调度 · 事件 · 创建
    workorder:event-info:end    — 工单调度 · 事件 · 结单
    bpm:garden-inspection:create— 工作流 · 园林巡检 · 创建
  ```
  
  ### 9.4 权限方法一览
  
  | SpEL 表达式 | 说明 |
  |-------------|------|
  | `@ss.hasPermission('perm')` | 检查单一权限 |
  | `@ss.hasAnyPermissions('a','b')` | 检查任一权限（满足一个即可） |
  | `@ss.hasRole('admin')` | 检查单一角色 |
  | `@ss.hasAnyRoles('admin','manager')` | 检查任一角色 |
  | `@ss.hasScope('read')` | 检查 OAuth2 scope |
  
  ### 9.5 实现代码示例
  
  **SecurityFrameworkServiceImpl — `@ss` Bean 实现：**
  
  ```java
  /**
   * 安全框架服务实现
   * Bean 名称：ss
   * 用于 @PreAuthorize("@ss.hasPermission(...)") 等表达式
   */
  @Service("ss")
  public class SecurityFrameworkServiceImpl implements SecurityFrameworkService {
  
      @Resource
      private PermissionCommonApi permissionApi;
  
      @Override
      public boolean hasPermission(String permission) {
          return hasAnyPermissions(permission);
      }
  
      @Override
      public boolean hasAnyPermissions(String... permissions) {
          // 特殊场景：跨租户访问时，跳过权限校验
          if (skipPermissionCheck()) {
              return true;
          }
          // 标准 RBAC 权限校验
          Long userId = getLoginUserId();
          if (userId == null) {
              return false;
          }
          // 调用权限公共 API（查询用户角色 → 角色菜单 → 菜单权限标识）
          return permissionApi.hasAnyPermissions(userId, permissions);
      }
  
      @Override
      public boolean hasAnyRoles(String... roles) {
          if (skipPermissionCheck()) {
              return true;
          }
          Long userId = getLoginUserId();
          if (userId == null) {
              return false;
          }
          return permissionApi.hasAnyRoles(userId, roles);
      }
  
      @Override
      public boolean hasAnyScopes(String... scope) {
          if (skipPermissionCheck()) {
              return true;
          }
          LoginUser user = SecurityFrameworkUtils.getLoginUser();
          if (user == null) {
              return false;
          }
          // 检查 LoginUser 的 scopes 列表中是否包含目标 scope
          return CollUtil.containsAny(user.getScopes(), Arrays.asList(scope));
      }
  
      /**
       * 跨租户访问时自动跳过权限检查
       * 逻辑：如果当前请求租户ID != 用户所属租户ID，说明是跨租户访问，自动放行
       */
      private boolean skipPermissionCheck() {
          LoginUser user = SecurityFrameworkUtils.getLoginUser();
          if (user == null) return false;
          Long visitTenantId = TenantContextHolder.getTenantId();
          return visitTenantId != null 
                 && !Objects.equals(user.getTenantId(), visitTenantId);
      }
  }
  ```
  
  **Controller 中的 @PreAuthorize 使用示例：** `TenantController.java`
  
  ```java
  @Tag(name = "管理后台 - 租户")
  @RestController
  @RequestMapping("/system/tenant")
  @Validated
  public class TenantController {
  
      @Resource
      private TenantService tenantService;
  
      @PostMapping("/create")
      @Operation(summary = "创建租户")
      @PreAuthorize("@ss.hasPermission('system:tenant:create')")
      public CommonResult<Long> createTenant(@Valid @RequestBody TenantSaveReqVO createReqVO) {
          return success(tenantService.createTenant(createReqVO));
      }
  
      @PutMapping("/update")
      @Operation(summary = "更新租户")
      @PreAuthorize("@ss.hasPermission('system:tenant:update')")
      public CommonResult<Boolean> updateTenant(@Valid @RequestBody TenantSaveReqVO updateReqVO) {
          tenantService.updateTenant(updateReqVO);
          return success(true);
      }
  
      @DeleteMapping("/delete")
      @Operation(summary = "删除租户")
      @PreAuthorize("@ss.hasPermission('system:tenant:delete')")
      public CommonResult<Boolean> deleteTenant(@RequestParam("id") Long id) {
          tenantService.deleteTenant(id);
          return success(true);
      }
  
      @GetMapping("/page")
      @Operation(summary = "获得租户分页")
      @PreAuthorize("@ss.hasPermission('system:tenant:query')")
      public CommonResult<PageResult<TenantRespVO>> getTenantPage(@Valid TenantPageReqVO pageReqVO) {
          return success(tenantService.getTenantPage(pageReqVO));
      }
  }
  ```
  
  ### 9.6 前端权限控制
  
  ```vue
  <template>
    <!-- 按钮级别权限控制（v-hasPermi 指令） -->
    <el-button v-hasPermi="['system:tenant:create']" type="primary">
      新增租户
    </el-button>
    
    <!-- 角色级别权限控制（v-hasRole 指令） -->
    <div v-hasRole="['admin']">
      管理员专属内容
    </div>
  </template>
  ```
  
  ---
  
  ## 10. 租户隔离鉴权
  
  ### 10.1 概述
  
  系统为多租户 SaaS 架构，通过 `TenantSecurityWebFilter` 在请求级别强制租户隔离，确保用户只能访问自己所属租户的数据，防止租户间数据越权。
  
  ### 10.2 核心类
  
  | 类名 | 路径 |
  |------|------|
  | `TenantSecurityWebFilter` | `urbanops-framework/urbanops-spring-boot-starter-biz-tenant/src/main/java/com/zteits/urbanops/framework/tenant/core/security/TenantSecurityWebFilter.java` |
  | `TenantContextHolder` | 租户上下文持有者（ThreadLocal） |
  
  ### 10.3 工作流程
  
  ```
  请求到达
    │
    ▼
  TenantSecurityWebFilter.doFilterInternal()
    │
    ├── 1. 如果请求头/参数中没有 tenantId
    │      └── 自动从 LoginUser.tenantId 填充
    │
    ├── 2. 如果请求中的 tenantId != LoginUser.tenantId
    │      └── 判定为跨租户越权访问 → 直接返回 403
    │
    ├── 3. 如果 tenantId 为空 且 不在白名单中
    │      └── 返回 400 "请求的租户标识未传递"
    │
    ├── 4. 校验租户合法性
    │      └── tenantFrameworkService.validTenant(tenantId)
    │           ├── 租户存在
    │           ├── 租户未被禁用
    │           └── 租户未过期
    │
    └── 5. 放行
  ```
  
  ### 10.4 实现代码示例
  
  **租户隔离过滤器：** `TenantSecurityWebFilter.java`
  
  ```java
  @RequiredArgsConstructor
  public class TenantSecurityWebFilter extends ApiRequestFilter {
  
      private final TenantProperties tenantProperties;
      private final TenantFrameworkService tenantFrameworkService;
  
      @Override
      protected void doFilterInternal(HttpServletRequest request, 
                                       HttpServletResponse response, 
                                       FilterChain chain) throws ServletException, IOException {
          Long tenantId = TenantContextHolder.getTenantId();
          LoginUser user = SecurityFrameworkUtils.getLoginUser();
  
          // ========== 1. 已登录用户的租户校验 ==========
          if (user != null) {
              if (tenantId == null) {
                  // 请求未带租户ID → 自动使用用户所属租户
                  tenantId = user.getTenantId();
                  TenantContextHolder.setTenantId(tenantId);
              } else if (!Objects.equals(user.getTenantId(), tenantId)) {
                  // 跨租户访问 → 拒绝请求
                  log.error("[doFilterInternal][租户({}) User({}/{}) 越权访问租户({}) URL({}/{})]",
                          user.getTenantId(), user.getId(), user.getUserType(),
                          tenantId, request.getRequestURI(), request.getMethod());
                  ServletUtils.writeJSON(response, 
                      CommonResult.error(GlobalErrorCodeConstants.FORBIDDEN.getCode(),
                                         "您无权访问该租户的数据"));
                  return;  // ← 直接中断请求
              }
          }
  
          // ========== 2. 租户合法性校验 ==========
          if (!isIgnoreUrl(request)) {
              // 非白名单 URL：必须有租户ID
              if (tenantId == null) {
                  ServletUtils.writeJSON(response, 
                      CommonResult.error(GlobalErrorCodeConstants.BAD_REQUEST.getCode(),
                                         "请求的租户标识未传递，请进行排查"));
                  return;
              }
              // 校验租户是否有效（未被禁用、未过期等）
              tenantFrameworkService.validTenant(tenantId);
          } else {
              // 白名单 URL（如登录接口）：允许无租户ID
              if (tenantId == null) {
                  TenantContextHolder.setIgnore(true);
              }
          }
  
          chain.doFilter(request, response);
      }
  
      /**
       * 判断当前 URL 是否在租户忽略白名单中
       */
      private boolean isIgnoreUrl(HttpServletRequest request) {
          return tenantProperties.getIgnoreUrls().stream()
                  .anyMatch(url -> WebFrameworkUtils.match(url, request));
      }
  }
  ```
  
  ### 10.5 配置示例
  
  ```yaml
  urbanops:
    tenant:
      ignore-urls:
        - /system/auth/login
        - /system/auth/sms-login
        - /system/oauth2/**
        - /swagger-ui/**
        - /v3/api-docs/**
  ```
  
  ---
  
  ## 11. 数据权限鉴权（行级安全）
  
  ### 11.1 概述
  
  数据权限是 RBAC 权限模型的补充，在 SQL 层面注入 `WHERE` 条件，实现行级数据过滤。用户根据其数据权限范围，只能看到：
  - **全部数据**（ALL）
  - **本部门及下级部门数据**（DEPT_SCOPE）
  - **仅本人数据**（SELF）
  
  ### 11.2 核心类
  
  | 类名 | 路径 |
  |------|------|
  | `@DataPermission` 注解 | `urbanops-framework/urbanops-spring-boot-starter-biz-data-permission/src/main/java/com/zteits/urbanops/framework/datapermission/core/annotation/DataPermission.java` |
  | `DeptDataPermissionRule` | `urbanops-framework/urbanops-spring-boot-starter-biz-data-permission/src/main/java/com/zteits/urbanops/framework/datapermission/core/rule/dept/DeptDataPermissionRule.java` |
  
  ### 11.3 @DataPermission 注解
  
  ```java
  @Target({ElementType.TYPE, ElementType.METHOD})
  @Retention(RetentionPolicy.RUNTIME)
  @Documented
  public @interface DataPermission {
      
      /** 是否启用数据权限，默认 true */
      boolean enable() default true;
      
      /** 指定启用的数据权限规则 */
      Class<? extends DataPermissionRule>[] includeRules() default {};
      
      /** 指定排除的数据权限规则 */
      Class<? extends DataPermissionRule>[] excludeRules() default {};
  }
  ```
  
  ### 11.4 SQL 注入逻辑
  
  | 数据权限范围 | 生成的 SQL WHERE 条件 |
  |-------------|--------------------|
  | ALL（全部）| 不注入条件（查全部）|
  | DEPT（部门）| `WHERE dept_id IN (1, 2, 3)` |
  | SELF（仅本人）| `WHERE creator = 5`（或 `user_id = 5`）|
  | DEPT + SELF | `WHERE (dept_id IN (1, 2, 3) OR creator = 5)` |
  | NONE（无权限）| `WHERE null = null` |
  
  ### 11.5 实现代码示例
  
  **部门数据权限规则：** `DeptDataPermissionRule.java`
  
  ```java
  @Component
  public class DeptDataPermissionRule implements DataPermissionRule {
  
      private static final String CONTEXT_KEY = DeptDataPermissionRule.class.getSimpleName();
  
      @Resource
      private PermissionCommonApi permissionApi;
  
      /**
       * 根据当前用户的数据权限范围，构造 SQL 过滤表达式
       */
      @Override
      public Expression getExpression(String tableName, Alias tableAlias) {
          LoginUser loginUser = SecurityFrameworkUtils.getLoginUser();
          if (loginUser == null) {
              return null;
          }
          // 仅对 ADMIN 类型用户生效
          if (ObjectUtil.notEqual(loginUser.getUserType(), UserTypeEnum.ADMIN.getValue())) {
              return null;
          }
  
          // 从缓存或远程 API 获取用户的数据权限配置
          DeptDataPermissionRespDTO deptDataPermission = loginUser.getContext(
                  CONTEXT_KEY, DeptDataPermissionRespDTO.class);
          if (deptDataPermission == null) {
              deptDataPermission = permissionApi.getDeptDataPermission(loginUser.getId());
              loginUser.setContext(CONTEXT_KEY, deptDataPermission);
          }
  
          // 情况1: 全部数据权限 → 不注入任何条件
          if (deptDataPermission.getAll()) {
              return null;
          }
  
          // 情况2: 既无部门权限，也无本人权限 → 查不到任何数据
          if (CollUtil.isEmpty(deptDataPermission.getDeptIds()) 
                  && Boolean.FALSE.equals(deptDataPermission.getSelf())) {
              return new EqualsTo(null, null);  // WHERE null = null
          }
  
          // 情况3: 拼接部门和本人的 OR 条件
          Expression deptExpression = buildDeptExpression(
                  tableName, tableAlias, deptDataPermission.getDeptIds());
          Expression userExpression = buildUserExpression(
                  tableName, tableAlias, deptDataPermission.getSelf(), loginUser.getId());
  
          if (deptExpression == null) return userExpression;
          if (userExpression == null) return deptExpression;
          
          // 组合: (dept_id IN (1,2,3) OR creator = 5)
          return new ParenthesizedExpressionList(
                  new OrExpression(deptExpression, userExpression));
      }
  
      /**
       * 构造部门条件：dept_id IN (1, 2, 3)
       */
      private Expression buildDeptExpression(String tableName, Alias tableAlias, 
                                              Set<Long> deptIds) {
          if (CollUtil.isEmpty(deptIds)) {
              return null;
          }
          return new InExpression(new Column(tableAlias, "dept_id"), 
                                  new ExpressionList(deptIds));
      }
  
      /**
       * 构造本人条件：creator = 5（或 user_id = 5）
       */
      private Expression buildUserExpression(String tableName, Alias tableAlias, 
                                              Boolean self, Long userId) {
          if (BooleanUtil.isFalse(self)) {
              return null;
          }
          return new EqualsTo(new Column(tableAlias, "creator"), 
                              new LongValue(userId));
      }
  }
  ```
  
  **Service 层使用示例：** `AdminAuthServiceImpl.java`
  
  ```java
  @Service
  public class AdminAuthServiceImpl implements AdminAuthService {
  
      /**
       * 登录方法：不需要数据权限过滤
       * 通过 @DataPermission(enable = false) 禁用行级过滤
       */
      @Override
      @DataPermission(enable = false)
      public AuthLoginRespVO login(AuthLoginReqVO reqVO) {
          AdminUserDO user = authenticate(reqVO.getUsername(), reqVO.getPassword());
          return createTokenAfterLoginSuccess(user.getId(), reqVO.getUsername(), 
                                              LoginLogTypeEnum.LOGIN_USERNAME);
      }
  
      /**
       * 列表查询方法：默认启用数据权限
       * 用户只能看到自己部门或自己的数据
       */
      @Override
      public PageResult<AdminUserRespVO> getUserPage(AdminUserPageReqVO reqVO) {
          // MyBatis 查询时会自动注入 dept_id IN (...) OR creator = ? 条件
          Page<AdminUserDO> page = userMapper.selectPage(reqVO, 
                  new LambdaQueryWrapperX<AdminUserDO>()
                          .likeIfPresent(AdminUserDO::getUsername, reqVO.getUsername()));
          return AdminUserConvert.INSTANCE.convertPage(page);
      }
  }
  ```
  
  ---
  
  ## 12. API 加密
  
  ### 12.1 概述
  
  系统支持对请求体和响应体进行 AES 或 RSA 加解密，通过 `@ApiEncrypt` 注解在方法级别控制，防止敏感数据在传输过程中被窃取。
  
  ### 12.2 核心类
  
  | 类名 | 路径 |
  |------|------|
  | `@ApiEncrypt` 注解 | `urbanops-framework/urbanops-spring-boot-starter-web/src/main/java/com/zteits/urbanops/framework/encrypt/core/annotation/ApiEncrypt.java` |
  | `ApiEncryptFilter` | `urbanops-framework/urbanops-spring-boot-starter-web/src/main/java/com/zteits/urbanops/framework/encrypt/core/filter/ApiEncryptFilter.java` |
  
  ### 12.3 @ApiEncrypt 注解
  
  ```java
  @Documented
  @Target({ElementType.TYPE, ElementType.METHOD})
  @Retention(RetentionPolicy.RUNTIME)
  public @interface ApiEncrypt {
  
      /** 是否对请求参数进行解密（默认 true） */
      boolean request() default true;
  
      /** 是否对响应结果进行加密（默认 true） */
      boolean response() default true;
  }
  ```
  
  ### 12.4 实现代码示例
  
  **API 加密过滤器：** `ApiEncryptFilter.java`
  
  ```java
  @RequiredArgsConstructor
  public class ApiEncryptFilter extends ApiRequestFilter {
  
      private final ApiEncryptProperties apiEncryptProperties;
  
      @Override
      protected void doFilterInternal(HttpServletRequest request, 
                                       HttpServletResponse response, 
                                       FilterChain chain) throws ServletException, IOException {
          // 1. 获取 Controller 方法上的 @ApiEncrypt 注解
          ApiEncrypt apiEncrypt = getApiEncrypt(request);
          boolean requestEnable = apiEncrypt != null && apiEncrypt.request();
          boolean responseEnable = apiEncrypt != null && apiEncrypt.response();
          String encryptHeader = request.getHeader(apiEncryptProperties.getHeader());
  
          // 不需要加解密 → 直接放行
          if (!requestEnable && !responseEnable && StrUtil.isBlank(encryptHeader)) {
              chain.doFilter(request, response);
              return;
          }
  
          // 2. 解密请求体（POST/PUT/DELETE 请求）
          if (ObjectUtils.equalsAny(HttpMethod.valueOf(request.getMethod()), 
                  HttpMethod.POST, HttpMethod.PUT, HttpMethod.DELETE)) {
              if (StrUtil.isNotBlank(encryptHeader)) {
                  // 使用加密请求包装器（AES 或 RSA 解密）
                  request = new ApiDecryptRequestWrapper(request,
                          requestSymmetricDecryptor,   // AES 解密器
                          requestAsymmetricDecryptor); // RSA 解密器
              } else if (requestEnable) {
                  throw invalidParamException("请求未包含加密标头，请检查是否正确配置了加密标头");
              }
          }
  
          // 3. 包装响应对象（用于后续加密输出）
          if (responseEnable) {
              response = new ApiEncryptResponseWrapper(response);
          }
  
          // 4. 执行后续过滤器链
          chain.doFilter(request, response);
  
          // 5. 加密响应体
          if (responseEnable) {
              ((ApiEncryptResponseWrapper) response).encrypt(
                      apiEncryptProperties,
                      responseSymmetricEncryptor,   // AES 加密器
                      responseAsymmetricEncryptor); // RSA 加密器
          }
      }
  }
  ```
  
  ### 12.5 使用示例
  
  ```java
  @RestController
  @RequestMapping("/admin-api/system/user")
  public class UserController {
  
      /**
       * 创建用户：请求体加密传输，响应结果也加密返回
       */
      @PostMapping("/create")
      @ApiEncrypt(request = true, response = true)
      @PreAuthorize("@ss.hasPermission('system:user:create')")
      public CommonResult<Long> createUser(@RequestBody UserSaveReqVO reqVO) {
          return success(userService.createUser(reqVO));
      }
  }
  ```
  
  ```yaml
  # application.yaml
  urbanops:
    api-encrypt:
      enable: true
      header: X-Encrypt              # 加密请求头标识
      algorithm: AES                 # AES / RSA
      request-aes-key: ${API_ENCRYPT_REQ_KEY}
      response-aes-key: ${API_ENCRYPT_RESP_KEY}
  ```
  
  ---
  
  ## 13. 接口前缀与鉴权方式对照表
  
  | 接口前缀 | 鉴权方式 | 认证类型 | 权限控制 | 租户隔离 | 适用场景 |
  |----------|----------|----------|----------|----------|----------|
  | `/admin-api/` | Bearer Token + RBAC | Token（登录后获取） | `@PreAuthorize("@ss.hasPermission(...)")` | ✅ 强制 | 管理后台 Web |
  | `/app-api/` | Bearer Token | Token（移动端登录获取） | 宽松（大多 @PermitAll） | ✅ 强制 | 移动端 App / 小程序 |
  | `/open-api/` | HMAC-SHA256 签名 | appId + appSecret 签名 | 无（由签名保证） | ❌ | 第三方系统对接 |
  | `/pub-api/` | 无 | 无 | 无 | ❌ | 支付回调等公开回调 |
  | `/system/auth/*` | 无（`@PermitAll`） | BCrypt 密码 / 短信验证码 / 社交登录 | 无 | ❌ | 登录入口 |
  | `/system/oauth2/*` | client_id + client_secret (Basic Auth) | OAuth2 标准协议 | OAuth2 Scope | ❌ | 授权服务器端点 |
  | `/swagger-ui/**` | 无 | 无 | 无 | ❌ | API 文档（开发环境） |
  | `/actuator/**` | 无（可配置） | 无 | 无 | ❌ | 健康检查 / 监控 |
  | WebSocket | `?token=xxx` 查询参数 | Token | 无 | ❌ | WebSocket 连接 |
  
  ---
  
  ## 附录：完整鉴权流程图
  
  ```
                            ┌─────────────────────────────┐
                            │       客户端请求到达          │
                            └──────────┬──────────────────┘
                                       │
                            ┌──────────▼──────────────────┐
                            │ 1. ApiEncryptFilter          │
                            │    @ApiEncrypt 注解的方法     │
                            │    解密请求体（AES/RSA）     │
                            └──────────┬──────────────────┘
                                       │
                            ┌──────────▼──────────────────┐
                            │ 2. TenantSecurityWebFilter   │
                            │    Tenant 租户隔离校验        │
                            │    防止跨租户越权            │
                            └──────────┬──────────────────┘
                                       │
                            ┌──────────▼──────────────────┐
                            │ 3. TokenAuthenticationFilter │
                            │    Bearer Token 提取 & 校验   │
                            │    userType 匹配检查          │
                            └──────────┬──────────────────┘
                                       │
                            ┌──────────▼──────────────────┐
                            │ 4. Spring Security           │
                            │    @PreAuthorize             │
                            │    "@ss.hasPermission(...)"  │
                            │    "@ss.hasRole(...)"        │
                            │    "@ss.hasScope(...)"       │
                            └──────────┬──────────────────┘
                                       │
                            ┌──────────▼──────────────────┐
                            │ 5. @ApiSignature AOP         │
                            │    (仅 /open-api/ 接口)      │
                            │    HMAC-SHA256 签名验证      │
                            └──────────┬──────────────────┘
                                       │
                            ┌──────────▼──────────────────┐
                            │ 6. Controller 方法执行       │
                            └──────────┬──────────────────┘
                                       │
                            ┌──────────▼──────────────────┐
                            │ 7. DeptDataPermissionRule    │
                            │    MyBatis SQL 行级过滤      │
                            │    dept_id IN (...) OR       │
                            │    creator = ?               │
                            └──────────┬──────────────────┘
                                       │
                            ┌──────────▼──────────────────┐
                            │ 8. ApiEncryptResponseWrapper │
                            │    加密响应体（AES/RSA）     │
                            └──────────┬──────────────────┘
                                       │
                            ┌──────────▼──────────────────┐
                            │        返回客户端            │
                            └─────────────────────────────┘
  ```
  
  ---
  
  > 📌 **本文档基于 2026-06-11 项目代码分析生成，如项目安全机制有变更，请同步更新本文档。**