On branch 001-label-backend-spec

Changes to be committed:
	new file:   src/main/java/com/label/common/shiro/BearerToken.java
	new file:   src/main/java/com/label/common/shiro/ShiroConfig.java
	new file:   src/main/java/com/label/common/shiro/TokenFilter.java
	new file:   src/main/java/com/label/common/shiro/TokenPrincipal.java
	new file:   src/main/java/com/label/common/shiro/UserRealm.java
	modified:   src/main/java/com/label/common/statemachine/DatasetStatus.java
	new file:   src/test/java/com/label/AbstractIntegrationTest.java
	new file:   src/test/java/com/label/unit/StateMachineTest.java
	new file:   src/test/resources/db/init.sql

src/main/java/com/label/common/shiro/BearerToken.java

@@ -0,0 +1,26 @@
+package com.label.common.shiro;
+
+import org.apache.shiro.authc.AuthenticationToken;
+
+/**
+ * Shiro AuthenticationToken wrapper for Bearer token strings.
+ */
+public class BearerToken implements AuthenticationToken {
+    private final String token;
+    private final TokenPrincipal principal;
+
+    public BearerToken(String token, TokenPrincipal principal) {
+        this.token = token;
+        this.principal = principal;
+    }
+
+    @Override
+    public Object getPrincipal() {
+        return principal;
+    }
+
+    @Override
+    public Object getCredentials() {
+        return token;
+    }
+}

src/main/java/com/label/common/shiro/ShiroConfig.java

@@ -0,0 +1,71 @@
+package com.label.common.shiro;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.label.common.redis.RedisService;
+import org.apache.shiro.mgt.SecurityManager;
+import org.apache.shiro.realm.Realm;
+import org.apache.shiro.spring.web.ShiroFilterFactoryBean;
+import org.apache.shiro.web.mgt.DefaultWebSecurityManager;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+import jakarta.servlet.Filter;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Shiro security configuration.
+ *
+ * Filter chain:
+ *   /api/auth/login  → anon  (no auth required)
+ *   /api/auth/logout → tokenFilter
+ *   /api/**          → tokenFilter (all other API endpoints require auth)
+ *   /actuator/**     → anon  (health check)
+ *   /**              → anon  (default)
+ *
+ * NOTE: spring.mvc.pathmatch.matching-strategy=ant_path_matcher MUST be set
+ * in application.yml for Shiro to work correctly with Spring Boot 3.
+ */
+@Configuration
+public class ShiroConfig {
+
+    @Bean
+    public UserRealm userRealm(RedisService redisService) {
+        return new UserRealm(redisService);
+    }
+
+    @Bean
+    public SecurityManager securityManager(UserRealm userRealm) {
+        DefaultWebSecurityManager manager = new DefaultWebSecurityManager();
+        manager.setRealms(List.of(userRealm));
+        return manager;
+    }
+
+    @Bean
+    public TokenFilter tokenFilter(RedisService redisService, ObjectMapper objectMapper) {
+        return new TokenFilter(redisService, objectMapper);
+    }
+
+    @Bean
+    public ShiroFilterFactoryBean shiroFilterFactoryBean(SecurityManager securityManager,
+                                                          TokenFilter tokenFilter) {
+        ShiroFilterFactoryBean factory = new ShiroFilterFactoryBean();
+        factory.setSecurityManager(securityManager);
+
+        // Register custom filters
+        Map<String, Filter> filters = new LinkedHashMap<>();
+        filters.put("tokenFilter", tokenFilter);
+        factory.setFilters(filters);
+
+        // Filter chain definition (ORDER MATTERS - first match wins)
+        Map<String, String> filterChainDef = new LinkedHashMap<>();
+        filterChainDef.put("/api/auth/login", "anon");
+        filterChainDef.put("/actuator/**", "anon");
+        filterChainDef.put("/api/**", "tokenFilter");
+        filterChainDef.put("/**", "anon");
+        factory.setFilterChainDefinitionMap(filterChainDef);
+
+        return factory;
+    }
+}

src/main/java/com/label/common/shiro/TokenFilter.java

@@ -0,0 +1,95 @@
+package com.label.common.shiro;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.label.common.context.CompanyContext;
+import com.label.common.redis.RedisKeyManager;
+import com.label.common.redis.RedisService;
+import com.label.common.result.Result;
+import jakarta.servlet.FilterChain;
+import jakarta.servlet.ServletException;
+import jakarta.servlet.ServletRequest;
+import jakarta.servlet.ServletResponse;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.apache.shiro.web.filter.PathMatchingFilter;
+import org.springframework.http.MediaType;
+
+import java.io.IOException;
+import java.util.Map;
+
+/**
+ * Shiro filter: parses "Authorization: Bearer {uuid}", validates against Redis,
+ * injects CompanyContext and Shiro subject principals.
+ *
+ * KEY DESIGN:
+ * - CompanyContext.clear() MUST be called in finally block to prevent thread pool leakage
+ * - Token lookup is from Redis Hash token:{uuid} → {userId, role, companyId, username}
+ * - 401 on missing/invalid token; filter continues for valid token
+ */
+@Slf4j
+@RequiredArgsConstructor
+public class TokenFilter extends PathMatchingFilter {
+
+    private final RedisService redisService;
+    private final ObjectMapper objectMapper;
+
+    @Override
+    protected boolean onPreHandle(ServletRequest request, ServletResponse response, Object mappedValue) throws Exception {
+        HttpServletRequest req = (HttpServletRequest) request;
+        HttpServletResponse resp = (HttpServletResponse) response;
+
+        String authHeader = req.getHeader("Authorization");
+        if (authHeader == null || !authHeader.startsWith("Bearer ")) {
+            writeUnauthorized(resp, "缺少或无效的认证令牌");
+            return false;
+        }
+
+        String token = authHeader.substring(7).trim();
+        String tokenKey = RedisKeyManager.tokenKey(token);
+        Map<Object, Object> tokenData = redisService.hGetAll(tokenKey);
+
+        if (tokenData == null || tokenData.isEmpty()) {
+            writeUnauthorized(resp, "令牌已过期或不存在");
+            return false;
+        }
+
+        try {
+            Long userId = Long.parseLong(tokenData.get("userId").toString());
+            String role = tokenData.get("role").toString();
+            Long companyId = Long.parseLong(tokenData.get("companyId").toString());
+            String username = tokenData.get("username").toString();
+
+            // Inject company context (must be cleared in finally)
+            CompanyContext.set(companyId);
+
+            // Bind Shiro subject with token principal
+            TokenPrincipal principal = new TokenPrincipal(userId, role, companyId, username, token);
+            request.setAttribute("__token_principal__", principal);
+
+            return true;
+        } catch (Exception e) {
+            log.error("解析 Token 数据失败: {}", e.getMessage());
+            writeUnauthorized(resp, "令牌数据格式错误");
+            return false;
+        }
+    }
+
+    @Override
+    public void doFilterInternal(ServletRequest request, ServletResponse response, FilterChain chain)
+            throws ServletException, IOException {
+        try {
+            super.doFilterInternal(request, response, chain);
+        } finally {
+            // CRITICAL: Always clear ThreadLocal to prevent leakage in thread pool
+            CompanyContext.clear();
+        }
+    }
+
+    private void writeUnauthorized(HttpServletResponse resp, String message) throws IOException {
+        resp.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
+        resp.setContentType(MediaType.APPLICATION_JSON_VALUE + ";charset=UTF-8");
+        resp.getWriter().write(objectMapper.writeValueAsString(Result.failure("UNAUTHORIZED", message)));
+    }
+}

src/main/java/com/label/common/shiro/TokenPrincipal.java

@@ -0,0 +1,18 @@
+package com.label.common.shiro;
+
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+import java.io.Serializable;
+
+/**
+ * Shiro principal carrying the authenticated user's session data.
+ */
+@Getter
+@AllArgsConstructor
+public class TokenPrincipal implements Serializable {
+    private final Long userId;
+    private final String role;
+    private final Long companyId;
+    private final String username;
+    private final String token;
+}

src/main/java/com/label/common/shiro/UserRealm.java

@@ -0,0 +1,87 @@
+package com.label.common.shiro;
+
+import com.label.common.redis.RedisKeyManager;
+import com.label.common.redis.RedisService;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.apache.shiro.authc.*;
+import org.apache.shiro.authz.AuthorizationInfo;
+import org.apache.shiro.authz.SimpleAuthorizationInfo;
+import org.apache.shiro.realm.AuthorizingRealm;
+import org.apache.shiro.subject.PrincipalCollection;
+
+/**
+ * Shiro Realm for role-based authorization using token-based authentication.
+ *
+ * Role hierarchy (addInheritedRoles):
+ *   ADMIN ⊃ REVIEWER ⊃ ANNOTATOR ⊃ UPLOADER
+ *
+ * Permission lookup order:
+ *   1. Redis user:perm:{userId} (TTL 5 min)
+ *   2. If miss: use role from TokenPrincipal
+ */
+@Slf4j
+@RequiredArgsConstructor
+public class UserRealm extends AuthorizingRealm {
+
+    private static final long PERM_CACHE_TTL = 300L; // 5 minutes
+
+    private final RedisService redisService;
+
+    @Override
+    public boolean supports(AuthenticationToken token) {
+        return token instanceof BearerToken;
+    }
+
+    @Override
+    protected AuthenticationInfo doGetAuthenticationInfo(AuthenticationToken token) throws AuthenticationException {
+        // Token validation is done in TokenFilter; this realm only handles authorization
+        // For authentication, we trust the token that was validated by TokenFilter
+        return new SimpleAuthenticationInfo(token.getPrincipal(), token.getCredentials(), getName());
+    }
+
+    @Override
+    protected AuthorizationInfo doGetAuthorizationInfo(PrincipalCollection principals) {
+        TokenPrincipal principal = (TokenPrincipal) principals.getPrimaryPrincipal();
+        if (principal == null) {
+            return new SimpleAuthorizationInfo();
+        }
+
+        String role = getRoleFromCacheOrPrincipal(principal);
+        SimpleAuthorizationInfo info = new SimpleAuthorizationInfo();
+        info.addRole(role);
+        addInheritedRoles(info, role);
+        return info;
+    }
+
+    private String getRoleFromCacheOrPrincipal(TokenPrincipal principal) {
+        String permKey = RedisKeyManager.userPermKey(principal.getUserId());
+        String cachedRole = redisService.get(permKey);
+        if (cachedRole != null && !cachedRole.isEmpty()) {
+            return cachedRole;
+        }
+        // Cache miss: use role from token, then refresh cache
+        String role = principal.getRole();
+        redisService.set(permKey, role, PERM_CACHE_TTL);
+        return role;
+    }
+
+    /**
+     * ADMIN inherits all roles: ADMIN ⊃ REVIEWER ⊃ ANNOTATOR ⊃ UPLOADER
+     */
+    private void addInheritedRoles(SimpleAuthorizationInfo info, String role) {
+        switch (role) {
+            case "ADMIN":
+                info.addRole("REVIEWER");
+                // fall through
+            case "REVIEWER":
+                info.addRole("ANNOTATOR");
+                // fall through
+            case "ANNOTATOR":
+                info.addRole("UPLOADER");
+                break;
+            default:
+                break;
+        }
+    }
+}