API 鉴权实战（一）：AK/SK、API Key、RBAC 与统一认证授权架构设计

<!-- pom.xml -->
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <scope>provided</scope>
</dependency>

@Component
@RequiredArgsConstructor
public class ApiKeyAuthFilter extends OncePerRequestFilter {

    private final AppAccessKeyMapper appAccessKeyMapper;

    private static final String HEADER_NAME = "X-API-Key";

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain chain) throws ServletException, IOException {
        String apiKey = request.getHeader(HEADER_NAME);
        if (apiKey == null || apiKey.isBlank()) {
            response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
            response.getWriter().write("{\"error\":\"Missing API Key\"}");
            return;
        }

        AppAccessKey keyInfo = appAccessKeyMapper.findByAccessKey(apiKey);
        if (keyInfo == null || keyInfo.getStatus() != 1) {
            response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
            response.getWriter().write("{\"error\":\"Invalid API Key\"}");
            return;
        }

        if (keyInfo.getExpiredAt() != null && keyInfo.getExpiredAt().isBefore(LocalDateTime.now())) {
            response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
            response.getWriter().write("{\"error\":\"API Key expired\"}");
            return;
        }

        request.setAttribute("appId", keyInfo.getAppId());
        request.setAttribute("appCode", keyInfo.getAppCode());
        chain.doFilter(request, response);
    }
}

CanonicalRequest = HTTP_METHOD + "\n"
                 + CANONICAL_URI + "\n"
                 + CANONICAL_QUERY_STRING + "\n"
                 + CANONICAL_HEADERS + "\n"
                 + SIGNED_HEADERS + "\n"
                 + BODY_SHA256

StringToSign = "HMAC-SHA256" + "\n"
             + TIMESTAMP + "\n"
             + NONCE + "\n"
             + SHA256(CanonicalRequest)

Signature = Base64(HMAC-SHA256(SecretKey, StringToSign))

Authorization: AK-HMAC AccessKey=AKIDxxxx, Signature=<signature>, Timestamp=<timestamp>, Nonce=<nonce>

public class AkSkUtils {

    /**
     * 生成签名
     */
    public static String sign(String method, String path, String queryString,
                              String timestamp, String nonce, String secretKey) {
        String sortedParams = sortQueryString(queryString);
        String stringToSign = method + "\n"
                + path + "\n"
                + sortedParams + "\n"
                + timestamp + "\n"
                + nonce;
        return Base64.getEncoder().encodeToString(
                HmacUtils.hmacSha256(secretKey, stringToSign));
    }

    /**
     * 验证签名（时间常量比较，防时序攻击）
     */
    public static boolean verify(String method, String path, String queryString,
                                 String timestamp, String nonce,
                                 String secretKey, String expectedSignature) {
        String actual = sign(method, path, queryString, timestamp, nonce, secretKey);
        return MessageDigest.isEqual(
                actual.getBytes(StandardCharsets.UTF_8),
                expectedSignature.getBytes(StandardCharsets.UTF_8));
    }

    /**
     * 查询参数按 key 字典序排序
     */
    public static String sortQueryString(String queryString) {
        if (queryString == null || queryString.isBlank()) {
            return "";
        }
        TreeMap<String, String> params = new TreeMap<>();
        for (String pair : queryString.split("&")) {
            String[] kv = pair.split("=", 2);
            params.put(kv[0], kv.length > 1 ? kv[1] : "");
        }
        return params.entrySet().stream()
                .map(e -> e.getKey() + "=" + e.getValue())
                .collect(Collectors.joining("&"));
    }

    public static String generateAccessKey() {
        return "AK-" + UUID.randomUUID().toString().replace("-", "").substring(0, 16).toUpperCase();
    }

    public static String generateSecretKey() {
        return "SK-" + UUID.randomUUID().toString().replace("-", "");
    }
}

@Component
@RequiredArgsConstructor
public class AkSkAuthFilter extends OncePerRequestFilter {

    private final AppAccessKeyMapper appAccessKeyMapper;
    private final RedisTemplate<String, String> redisTemplate;

    private static final long MAX_TIMESTAMP_DIFF_MS = 300_000; // 5 分钟

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain chain) throws ServletException, IOException {

        String authHeader = request.getHeader("Authorization");
        if (authHeader == null || !authHeader.startsWith("AK-HMAC ")) {
            response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
            response.getWriter().write("{\"error\":\"Missing Authorization header\"}");
            return;
        }

        Map<String, String> params = parseAuthHeader(authHeader);
        String accessKey = params.get("AccessKey");
        String signature = params.get("Signature");
        String timestamp = params.get("Timestamp");
        String nonce = params.get("Nonce");

        // 校验必填参数
        if (accessKey == null || signature == null || timestamp == null || nonce == null) {
            response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
            response.getWriter().write("{\"error\":\"Incomplete auth params\"}");
            return;
        }

        // 防重放：校验时间戳
        long requestTime;
        try {
            requestTime = Long.parseLong(timestamp);
        } catch (NumberFormatException e) {
            response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
            response.getWriter().write("{\"error\":\"Invalid timestamp\"}");
            return;
        }
        if (Math.abs(System.currentTimeMillis() - requestTime) > MAX_TIMESTAMP_DIFF_MS) {
            response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
            response.getWriter().write("{\"error\":\"Request expired\"}");
            return;
        }

        // 防重放：校验 Nonce（按 accessKey 维度存 Redis，TTL 5 分钟）
        String nonceKey = "auth:nonce:" + accessKey + ":" + nonce;
        Boolean isNew = redisTemplate.opsForValue().setIfAbsent(nonceKey, "1", 5, TimeUnit.MINUTES);
        if (Boolean.FALSE.equals(isNew)) {
            response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
            response.getWriter().write("{\"error\":\"Duplicate nonce\"}");
            return;
        }

        // 根据 AK 查找 App
        AppAccessKey keyInfo = appAccessKeyMapper.findByAccessKey(accessKey);
        if (keyInfo == null || keyInfo.getStatus() != 1) {
            response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
            response.getWriter().write("{\"error\":\"Invalid Access Key\"}");
            return;
        }

        // 验证签名
        String method = request.getMethod();
        String path = request.getRequestURI();
        String queryString = request.getQueryString();

        boolean valid = AkSkUtils.verify(method, path, queryString,
                timestamp, nonce, keyInfo.getSecretKey(), signature);

        if (!valid) {
            response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
            response.getWriter().write("{\"error\":\"Signature mismatch\"}");
            return;
        }

        // 放入上下文
        request.setAttribute("appId", keyInfo.getAppId());
        request.setAttribute("appCode", keyInfo.getAppCode());
        request.setAttribute("subjectType", "APP");

        chain.doFilter(request, response);
    }

    private Map<String, String> parseAuthHeader(String header) {
        String params = header.substring("AK-HMAC ".length());
        Map<String, String> map = new HashMap<>();
        for (String part : params.split(",")) {
            String[] kv = part.trim().split("=", 2);
            if (kv.length == 2) {
                map.put(kv[0].trim(), kv[1].trim());
            }
        }
        return map;
    }

    @Override
    protected boolean shouldNotFilter(HttpServletRequest request) {
        return "OPTIONS".equalsIgnoreCase(request.getMethod());
    }
}

public class AkSkClient {

    /**
     * 构造带签名的请求头
     */
    public static HttpHeaders buildAuthHeaders(String method, String path,
                                               String queryString,
                                               String accessKey,
                                               String secretKey) {
        String timestamp = String.valueOf(System.currentTimeMillis());
        String nonce = UUID.randomUUID().toString();

        String signature = AkSkUtils.sign(method, path, queryString,
                timestamp, nonce, secretKey);

        String authValue = "AK-HMAC "
                + "AccessKey=" + accessKey + ", "
                + "Signature=" + signature + ", "
                + "Timestamp=" + timestamp + ", "
                + "Nonce=" + nonce;

        HttpHeaders headers = new HttpHeaders();
        headers.set("Authorization", authValue);
        return headers;
    }

    /**
     * 使用示例
     */
    public static void main(String[] args) {
        String ak = "AK-X1Y2Z3W4V5U6T7S8";
        String sk = "SK-a1b2c3d4-e5f6-7890-abcd-ef1234567890";

        HttpHeaders headers = buildAuthHeaders(
                "GET", "/api/products", "page=1&size=10", ak, sk);

        RestTemplate restTemplate = new RestTemplate();
        HttpEntity<Void> entity = new HttpEntity<>(headers);
        ResponseEntity<String> response = restTemplate.exchange(
                "https://api.example.com/api/products?page=1&size=10",
                HttpMethod.GET, entity, String.class);
        System.out.println(response.getBody());
    }
}

@Component
public class JwtUtils {

    @Value("${jwt.secret}")
    private String secret;

    @Value("${jwt.expiration:7200}")
    private long expirationSeconds;

    /**
     * 签发 Token
     */
    public String generateToken(Long userId, String username, String tenantId) {
        Date now = new Date();
        Date expireAt = new Date(now.getTime() + expirationSeconds * 1000);

        return Jwts.builder()
                .setSubject(String.valueOf(userId))
                .claim("username", username)
                .claim("tenantId", tenantId)
                .setIssuedAt(now)
                .setExpiration(expireAt)
                .signWith(Keys.hmacShaKeyFor(secret.getBytes(StandardCharsets.UTF_8)))
                .compact();
    }

    /**
     * 解析 Token
     */
    public Claims parseToken(String token) {
        return Jwts.parserBuilder()
                .setSigningKey(Keys.hmacShaKeyFor(secret.getBytes(StandardCharsets.UTF_8)))
                .build()
                .parseClaimsJws(token)
                .getBody();
    }

    /**
     * 从 Token 中提取 userId
     */
    public Long getUserId(String token) {
        Claims claims = parseToken(token);
        return Long.parseLong(claims.getSubject());
    }
}

public class InternalTokenUtils {

    // 从 KMS / 配置中心 / 环境变量注入,不要硬编码在代码里
    private static final Supplier<String> SECRET_PROVIDER = () -> System.getenv("INTERNAL_TOKEN_SIGNING_KEY");

    /**
     * 网关为服务签发内部 Token
     */
    public static String generateToken(String serviceName, Set<String> scopes) {
        String payload = JSON.toJSONString(Map.of(
                "serviceName", serviceName,
                "scopes", scopes,
                "issuedAt", System.currentTimeMillis(),
                "expireAt", System.currentTimeMillis() + 3600_000
        ));
        return Base64.getEncoder().encodeToString(payload.getBytes())
                + "." + HmacUtils.hmacSha256Hex(SECRET_PROVIDER.get(), payload);
    }

    /**
     * 服务端验证内部 Token
     */
    public static boolean verify(String token) {
        int dotIdx = token.lastIndexOf('.');
        if (dotIdx == -1) return false;

        String payloadBase64 = token.substring(0, dotIdx);
        String signature = token.substring(dotIdx + 1);
        String payload = new String(Base64.getDecoder().decode(payloadBase64));

        String expectedSig = HmacUtils.hmacSha256Hex(SECRET_PROVIDER.get(), payload);
        if (!MessageDigest.isEqual(expectedSig.getBytes(), signature.getBytes())) {
            return false;
        }

        // 检查过期
        Map<String, Object> data = JSON.parseObject(payload, Map.class);
        long expireAt = ((Number) data.get("expireAt")).longValue();
        return System.currentTimeMillis() < expireAt;
    }
}

-- 用户表
CREATE TABLE sys_user (
    id          BIGINT PRIMARY KEY AUTO_INCREMENT,
    username    VARCHAR(64) NOT NULL UNIQUE,
    password    VARCHAR(128) NOT NULL,
    tenant_id   VARCHAR(64) NOT NULL DEFAULT 'default',
    status      TINYINT DEFAULT 1 COMMENT '1=启用 0=禁用',
    created_at  DATETIME DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_tenant (tenant_id)
) COMMENT='用户表';

-- 角色表
CREATE TABLE sys_role (
    id          BIGINT PRIMARY KEY AUTO_INCREMENT,
    role_code   VARCHAR(64) NOT NULL COMMENT '角色编码',
    role_name   VARCHAR(128) NOT NULL COMMENT '角色名称',
    tenant_id   VARCHAR(64) NOT NULL DEFAULT 'default',
    status      TINYINT DEFAULT 1,
    UNIQUE KEY uk_tenant_code (tenant_id, role_code)
) COMMENT='角色表';

-- 权限表
CREATE TABLE sys_permission (
    id              BIGINT PRIMARY KEY AUTO_INCREMENT,
    permission_code VARCHAR(128) NOT NULL UNIQUE COMMENT '权限编码，如 product:create',
    permission_name VARCHAR(128) NOT NULL COMMENT '权限名称',
    resource_type   VARCHAR(32) COMMENT '资源类型：api/menu/button',
    description     VARCHAR(512)
) COMMENT='权限表';

-- 用户-角色关联
CREATE TABLE sys_user_role (
    user_id     BIGINT NOT NULL,
    role_id     BIGINT NOT NULL,
    PRIMARY KEY (user_id, role_id),
    INDEX idx_role (role_id)
) COMMENT='用户-角色关联';

-- 角色-权限关联
CREATE TABLE sys_role_permission (
    role_id         BIGINT NOT NULL,
    permission_id   BIGINT NOT NULL,
    PRIMARY KEY (role_id, permission_id),
    INDEX idx_permission (permission_id)
) COMMENT='角色-权限关联';

@Mapper
public interface UserRoleMapper {

    /**
     * 查询用户的角色编码集合
     */
    @Select("SELECT r.role_code FROM sys_role r " +
            "INNER JOIN sys_user_role ur ON ur.role_id = r.id " +
            "WHERE ur.user_id = #{userId} AND r.status = 1")
    Set<String> findRoleCodesByUserId(@Param("userId") Long userId);

    /**
     * 查询用户的权限编码集合（通过角色关联）
     */
    @Select("SELECT DISTINCT p.permission_code FROM sys_permission p " +
            "INNER JOIN sys_role_permission rp ON rp.permission_id = p.id " +
            "INNER JOIN sys_user_role ur ON ur.role_id = rp.role_id " +
            "WHERE ur.user_id = #{userId}")
    Set<String> findPermissionCodesByUserId(@Param("userId") Long userId);
}

-- 角色继承关系表
CREATE TABLE sys_role_hierarchy (
    parent_role_id  BIGINT NOT NULL COMMENT '被继承的角色（父）',
    child_role_id   BIGINT NOT NULL COMMENT '继承者（子）',
    PRIMARY KEY (parent_role_id, child_role_id),
    INDEX idx_child (child_role_id)
) COMMENT='角色继承关系（child 继承 parent 的权限）';

-- employee(id=1), manager(id=2), director(id=3)
INSERT INTO sys_role_hierarchy VALUES (1, 2);  -- manager 继承 employee
INSERT INTO sys_role_hierarchy VALUES (2, 3);  -- director 继承 manager

@Service
@RequiredArgsConstructor
public class RoleHierarchyService {

    private final RoleHierarchyMapper roleHierarchyMapper;
    private final RolePermissionMapper rolePermissionMapper;

    /**
     * 递归获取角色的所有父角色 ID（包括自己）
     */
    public Set<Long> getAllParentRoleIds(Long roleId) {
        Set<Long> result = new HashSet<>();
        result.add(roleId);
        collectParentRoleIds(roleId, result, new HashSet<>());
        return result;
    }

    private void collectParentRoleIds(Long roleId, Set<Long> result, Set<Long> visited) {
        if (visited.contains(roleId)) return; // 防循环
        visited.add(roleId);

        List<Long> parentIds = roleHierarchyMapper.findParentRoleIds(roleId);
        for (Long parentId : parentIds) {
            if (result.add(parentId)) {
                collectParentRoleIds(parentId, result, visited);
            }
        }
    }

    /**
     * 获取角色的全部权限（含继承）
     */
    public Set<String> getPermissionCodesWithHierarchy(Long roleId) {
        Set<Long> allRoleIds = getAllParentRoleIds(roleId);
        return rolePermissionMapper.findPermissionCodesByRoleIds(allRoleIds);
    }
}

-- 静态互斥角色组
CREATE TABLE sys_ssd_group (
    id          BIGINT PRIMARY KEY AUTO_INCREMENT,
    group_name  VARCHAR(128) NOT NULL COMMENT '互斥组名称，如 财务互斥组',
    max_members INT NOT NULL DEFAULT 1 COMMENT '该组最多允许用户拥有几个角色'
) COMMENT='静态互斥角色组';

-- 互斥组-角色关联
CREATE TABLE sys_ssd_group_role (
    group_id    BIGINT NOT NULL,
    role_id     BIGINT NOT NULL,
    PRIMARY KEY (group_id, role_id)
) COMMENT='互斥组包含的角色';

@Service
@RequiredArgsConstructor
public class RoleConstraintService {

    private final SsdGroupMapper ssdGroupMapper;

    /**
     * 检查给用户分配新角色是否违反 SSD 约束
     */
    public void checkSsdConstraint(Long userId, Long newRoleId) {
        List<SsdGroup> groups = ssdGroupMapper.findGroupsByRoleId(newRoleId);
        for (SsdGroup group : groups) {
            // 查询用户在该互斥组中已拥有的角色数
            int ownedCount = ssdGroupMapper.countUserRolesInGroup(userId, group.getId());
            if (ownedCount >= group.getMaxMembers()) {
                throw new ForbiddenException(
                    "违反互斥约束：角色 " + newRoleId + " 属于互斥组 [" + group.getGroupName()
                    + "]，你已拥有该组 " + ownedCount + " 个角色，上限 " + group.getMaxMembers());
            }
        }
    }
}

public class SessionRoleManager {

    private static final ThreadLocal<Set<Long>> ACTIVE_ROLES = ThreadLocal.withInitial(HashSet::new);

    /**
     * 激活角色（登录后选择激活哪些角色）
     */
    public void activateRole(Long userId, Long roleId) {
        Set<Long> active = ACTIVE_ROLES.get();

        // 检查 DSD 约束
        checkDsdConstraint(userId, roleId, active);

        active.add(roleId);
    }

    private void checkDsdConstraint(Long userId, Long roleId, Set<Long> activeRoles) {
        List<SsdGroup> groups = ssdGroupMapper.findGroupsByRoleId(roleId);
        for (SsdGroup group : groups) {
            long conflictCount = activeRoles.stream()
                    .filter(activeRoleId -> ssdGroupMapper.isRoleInGroup(activeRoleId, group.getId()))
                    .count();
            if (conflictCount >= group.getMaxMembers()) {
                throw new ForbiddenException("动态互斥约束：不能同时激活同一互斥组的多个角色");
            }
        }
    }
}

@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface RequirePermission {
    String value();
    Logical logical() default Logical.AND;

    enum Logical { AND, OR }
}

@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface RequireRole {
    String value();
}

@Aspect
@Component
@RequiredArgsConstructor
public class PermissionAspect {

    private final UserRoleMapper userRoleMapper;

    @Around("@annotation(requirePermission)")
    public Object checkPermission(ProceedingJoinPoint pjp,
                                  RequirePermission requirePermission) throws Throwable {
        Long userId = SecurityContextHolder.getCurrentUserId();
        if (userId == null) {
            throw new UnauthorizedException("未登录");
        }

        Set<String> userPerms = getUserPermissions(userId);
        String required = requirePermission.value();

        boolean hasPermission;
        if (requirePermission.logical() == Logical.AND) {
            hasPermission = userPerms.contains(required);
        } else {
            hasPermission = userPerms.contains(required);
        }

        if (!hasPermission) {
            throw new ForbiddenException("权限不足：需要 " + required);
        }

        return pjp.proceed();
    }

    @Around("@annotation(requireRole)")
    public Object checkRole(ProceedingJoinPoint pjp,
                            RequireRole requireRole) throws Throwable {
        Long userId = SecurityContextHolder.getCurrentUserId();
        if (userId == null) {
            throw new UnauthorizedException("未登录");
        }

        Set<String> userRoles = userRoleMapper.findRoleCodesByUserId(userId);
        if (!userRoles.contains(requireRole.value())) {
            throw new ForbiddenException("角色不足：需要 " + requireRole.value());
        }

        return pjp.proceed();
    }

    private Set<String> getUserPermissions(Long userId) {
        return userRoleMapper.findPermissionCodesByUserId(userId);
    }
}

@RestController
@RequestMapping("/products")
public class ProductController {

    @RequirePermission("product:create")
    @PostMapping
    public Product create(@RequestBody ProductDTO dto) { ... }

    @RequirePermission("product:read")
    @GetMapping("/{id}")
    public Product get(@PathVariable Long id) { ... }

    @RequirePermission("product:update")
    @PutMapping("/{id}")
    public Product update(@PathVariable Long id, @RequestBody ProductDTO dto) { ... }

    @RequirePermission("product:delete")
    @DeleteMapping("/{id}")
    public void delete(@PathVariable Long id) { ... }
}

❌ 错误：App 绑到用户（张三创建的 App，张三离职了怎么办？）
✅ 正确：App 绑到租户（公司），由租户管理员管理

租户管理员登录管理后台
  → "创建应用"
  → 填写应用名称、选择业务类型
  → 系统自动生成 appid + appkey（AK/SK 对）
  → 租户管理员分配 scope（从自己的权限范围里选）
  → 租户管理员指定开发者（谁能用这个 appkey 对接）

子公司A
  ├── App: 电商系统    → appkey_1（独立计费、独立限流）
  ├── App: CRM 系统    → appkey_2（独立计费、独立限流）
  └── App: AI 客服     → appkey_3（独立计费、独立限流）

三个 appkey 互相隔离：一个被吊销不影响其他两个

-- 租户表（公司/子公司）
CREATE TABLE iam_tenant (
    id              BIGINT PRIMARY KEY AUTO_INCREMENT,
    tenant_code     VARCHAR(64) NOT NULL UNIQUE COMMENT '租户编码，如 sub_a_001',
    tenant_name     VARCHAR(256) NOT NULL COMMENT '公司/子公司名称',
    parent_id       BIGINT DEFAULT NULL COMMENT '父租户 ID，支持集团→子公司层级',
    admin_user_id   BIGINT NOT NULL COMMENT '租户管理员（创建者）',
    status          TINYINT NOT NULL DEFAULT 1 COMMENT '1=正常 0=禁用',
    created_at      DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_parent (parent_id)
) COMMENT='租户表';

-- 用户-租户关联（一个用户可以属于多个租户）
CREATE TABLE iam_user_tenant (
    user_id         BIGINT NOT NULL,
    tenant_id       BIGINT NOT NULL,
    role_in_tenant  VARCHAR(64) NOT NULL DEFAULT 'member' COMMENT 'admin/member/developer',
    PRIMARY KEY (user_id, tenant_id)
) COMMENT='用户-租户关联';

-- 应用表（绑定到租户）
CREATE TABLE iam_app (
    id              BIGINT PRIMARY KEY AUTO_INCREMENT,
    app_id          VARCHAR(64) NOT NULL UNIQUE COMMENT '应用标识，系统生成',
    app_code        VARCHAR(64) NOT NULL COMMENT '应用编码（业务可读）',
    app_name        VARCHAR(128) NOT NULL COMMENT '应用名称',
    tenant_id       BIGINT NOT NULL COMMENT '所属租户（公司/子公司）',
    app_type        VARCHAR(32) NOT NULL DEFAULT 'business' COMMENT 'business/ai/open_platform',
    status          TINYINT NOT NULL DEFAULT 1 COMMENT '1=正常 0=禁用',
    created_by      BIGINT NOT NULL COMMENT '创建者 userId',
    created_at      DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_tenant (tenant_id),
    INDEX idx_created_by (created_by)
) COMMENT='应用表（绑定到租户）';

-- 应用密钥表（一个 App 可以有多组密钥）
CREATE TABLE iam_app_access_key (
    id              BIGINT PRIMARY KEY AUTO_INCREMENT,
    app_id          VARCHAR(64) NOT NULL,
    access_key      VARCHAR(64) NOT NULL UNIQUE COMMENT '公开标识，即 AK',
    secret_key      VARCHAR(128) NOT NULL COMMENT '加密存储，即 SK',
    key_name        VARCHAR(128) DEFAULT NULL COMMENT '密钥名称，如"生产环境"、"测试环境"',
    status          TINYINT NOT NULL DEFAULT 1 COMMENT '1=启用 0=禁用 2=已吊销',
    expire_at       DATETIME DEFAULT NULL,
    last_used_at    DATETIME DEFAULT NULL,
    created_at      DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_access_key (access_key),
    INDEX idx_app_id (app_id)
) COMMENT='应用密钥表（一个 App 可以有多组密钥，支持轮换）';

1. 平台创建租户
   平台管理员 → 创建"子公司A"租户 → 指定张三为租户管理员

2. 租户管理员创建 App
   张三登录 → "我的应用" → "创建应用"
     → 应用名称：电商系统
     → 应用类型：business
     → 系统自动生成：appid=APP_003, AK=AKIDxxxx, SK=your-secret-key
     → 张三拿到 AK/SK，交给开发团队

3. 开发者对接
   李四（开发者）拿到 AK/SK
     → 按照 API 文档对接
     → 调用时用 AK/SK 签名

4. 日常管理
   张三可以：
     → 查看 APP_003 的调用量和账单
     → 轮换密钥（旧密钥 7 天过渡期）
     → 调整 scope（只能选自己权限范围内的）
     → 吊销密钥（发现异常时）
     → 指定其他开发者

5. 人员变动
   张三离职 → 平台管理员将租户管理员转给王五
   → App 和 appkey 不受影响，业务不中断
   → 王五接管所有 App 的管理权

边界 1：租户边界
  子公司A 的 App 不能访问子公司B 的数据
  （通过 tenant_id 隔离，每个请求校验）

边界 2：创建者权限边界
  租户管理员只有 [product:*, order:read] 权限
  → 他创建的 App 最多只能有 [product:*, order:read]
  → 不能越权分配 [admin:delete]（他自己都没有）

// 典型的 AI API 调用（如 OpenAI、百度文心、通义千问）
POST https://api.openai.com/v1/chat/completions
Authorization: Bearer your-api-key  ← 这是单字符串 API Key,要按密钥保护
Content-Type: application/json

{"model": "gpt-4", "messages": [...]}

// 我们的 AI 开放平台调用方式
POST https://ai.example.com/api/v1/image/generate
Authorization: AK-HMAC AccessKey=AKID_APP_003, Signature=<signature>, Timestamp=<timestamp>, Nonce=<nonce>
Content-Type: application/json

{"model": "seedream", "prompt": "一只猫"}

子公司A 管理后台
├── 应用管理
│   ├── 电商系统（APP_003）
│   │   ├── 密钥管理 [生产环境] [测试环境]
│   │   ├── Scope 配置 [product:read, product:write, order:*]
│   │   ├── 调用统计 [今日 12,345 次]
│   │   └── 额度设置 [每日上限 100,000]
│   │
│   ├── CRM 系统（APP_004）
│   │   ├── 密钥管理 [生产环境]
│   │   ├── Scope 配置 [customer:*, order:read]
│   │   └── ...
│   │
│   └── [+ 创建应用]
│
├── 成员管理
│   ├── 张三（admin）→ 可管理所有 App
│   ├── 李四（developer）→ 可使用 APP_003 的密钥
│   └── 王五（developer）→ 可使用 APP_004 的密钥
│
└── 账单
    ├── APP_003：本月 ¥1,234
    ├── APP_004：本月 ¥567
    └── 合计：¥1,801

/**
 * 租户内 App 管理权限校验
 */
@Service
@RequiredArgsConstructor
public class TenantAppService {

    private final AppMapper appMapper;
    private final UserTenantMapper userTenantMapper;

    /**
     * 校验用户是否有权管理该 App
     * 规则：必须是同一租户的 admin，或者是 App 的创建者
     */
    public void checkManagePermission(Long userId, String appId) {
        App app = appMapper.findByAppId(appId);
        if (app == null) throw new NotFoundException("应用不存在");

        // 检查是否是同一租户
        UserTenant ut = userTenantMapper.find(userId, app.getTenantId());
        if (ut == null) throw new ForbiddenException("你不是该租户成员");

        // admin 可以管理所有 App，member 只能管理自己创建的
        if (!"admin".equals(ut.getRoleInTenant())
                && !app.getCreatedBy().equals(userId)) {
            throw new ForbiddenException("无权管理该应用");
        }
    }

    /**
     * 租户管理员创建 App
     */
    public App createApp(Long userId, String appName, String appType) {
        // 校验是租户 admin
        UserTenant ut = userTenantMapper.find(userId, currentTenantId());
        if (ut == null || !"admin".equals(ut.getRoleInTenant())) {
            throw new ForbiddenException("只有租户管理员可以创建应用");
        }

        String appId = "APP_" + generateId();
        App app = App.builder()
                .appId(appId)
                .appName(appName)
                .appType(appType)
                .tenantId(currentTenantId())
                .createdBy(userId)
                .status(1)
                .build();
        appMapper.insert(app);

        // 自动生成第一组密钥
        generateAccessKey(appId, "默认密钥");

        return app;
    }

    /**
     * 生成密钥（一个 App 可以有多组，支持环境隔离）
     */
    public AppAccessKey generateAccessKey(String appId, String keyName) {
        String ak = AkSkUtils.generateAccessKey();
        String sk = AkSkUtils.generateSecretKey();

        AppAccessKey key = AppAccessKey.builder()
                .appId(appId)
                .accessKey(ak)
                .secretKey(encrypt(sk)) // 加密存储
                .keyName(keyName)
                .status(1)
                .build();
        accessKeyMapper.insert(key);

        // SK 只在创建时返回一次
        key.setSecretKey(sk); // 明文返回给调用方
        return key;
    }
}