conti-backend/docs/04-security-auth.md

# 04. 安全与认证方案

## 决策

Spring Security + JWT，由 `identity-store` 模块统一签发，由 `platform-security` 统一校验，对应架构图里 `Auth and Token Center`；门店/角色上下文在认证之后注入 `@RequestScope` bean，供各 domain 读取，对应架构图 `Store Context` 的职责。

JWT 的签发与校验**用 Spring Security 内置的 `NimbusJwtEncoder`/`NimbusJwtDecoder`，不引入 jjwt**，理由见文末附录。

## 结构约定

```
platform-security/
  JwtProperties                 # security.jwt.* 配置绑定 + 启动期校验
  JwtEncoderConfig                # NimbusJwtEncoder / NimbusJwtDecoder（HS256）
  AccessTokenIssuer                # 签发 access token（claims 结构见下）
  StoreContextFilter                # 认证之后执行：把 Jwt claims 写进 StoreContextHolder
  StoreContextHolder                 # @RequestScope bean，持有当前 用户+门店+角色
  ApiResultAuthenticationEntryPoint    # 401 → ApiResult JSON
  ApiResultAccessDeniedHandler          # 403 → ApiResult JSON
  SecurityConfig                         # 统一 SecurityFilterChain

domains/identity-store/
  负责登录、refresh token 签发/轮换/撤销、门店列表与切换、菜单权限
```

## 端点契约（与客户端已实现的行为对齐）

以下五个端点的路径、请求体、响应体**必须**与客户端文档 [../05-networking.md](../../conti-retail-app/docs/05-networking.md)、[../11-store-context-and-session.md](../../conti-retail-app/docs/11-store-context-and-session.md) 一致，客户端的自动刷新、切店、登出、冷启动恢复流程已经按这个契约实现：

| 端点 | 认证 | 说明 |
| --- | --- | --- |
| `POST /api/v1/auth/login` | 免认证 | `{ username, password }` → `{ accessToken, refreshToken, user }` |
| `POST /api/v1/auth/refresh` | 免认证 | `{ refreshToken }` → `{ accessToken, refreshToken }`。**必须免认证**：调用它的时候 access token 恰好已经过期 |
| `POST /api/v1/auth/logout` | 需认证 | `{ refreshToken }` → `ApiResult<Unit>`。撤销该 refresh token；客户端 3 秒超时、失败不阻断本地登出 |
| `GET /api/v1/auth/me` | 需认证 | → `{ user, currentStoreId }`。客户端冷启动时用本地 token 调它恢复会话（客户端 `11-store-context-and-session.md` 的启动流程）。**必须是轻量查询**，不做任何写操作——它在每次冷启动都会被调用 |
| `POST /api/v1/stores/{id}/switch` | 需认证 | → `StoreContext`（含新的 `accessToken` + 菜单），见下面"切换门店" |

客户端冷启动的完整顺序是 `GET /auth/me` → `GET /api/v1/stores/accessible`（后者见 [06-api-design.md](./06-api-design.md)）：先确认身份还有效，再拉可选门店列表。这两个接口在 401 时都会触发客户端的串行刷新流程，所以它们的 401 必须是标准的 `ApiResult` JSON（见下面 `ApiResultAuthenticationEntryPoint`），不能是 500。

其余端点的路径与响应包装规则见 [06-api-design.md](./06-api-design.md)。

## Token 配置与校验

```kotlin
// platform-security/.../JwtProperties.kt
@ConfigurationProperties(prefix = "security.jwt")
@Validated
data class JwtProperties(
    /** 当前签发用的密钥 ID，写进 JWT header 的 kid，用于密钥轮换，见"密钥轮换"一节。 */
    @field:NotBlank val activeKeyId: String,
    /** kid -> base64 密钥，允许同时持有多个用于校验，只有 activeKeyId 用于签发。 */
    val keys: Map<String, String> = emptyMap(),
    @field:Min(5) val accessTokenTtlMinutes: Long = 30,
    @field:Min(1) val refreshTokenTtlDays: Long = 30,
) {
    @PostConstruct
    fun validate() {
        val key = keys[activeKeyId] ?: error("security.jwt.keys 里没有 activeKeyId=$activeKeyId 对应的密钥")
        require(Base64.getDecoder().decode(key).size >= 32) {
            "HS256 密钥长度必须 ≥ 32 字节，当前配置不满足"   // 启动即失败，不允许带着弱密钥跑起来
        }
    }
}
```

```kotlin
// platform-security/.../JwtEncoderConfig.kt
@Configuration
@EnableConfigurationProperties(JwtProperties::class)
class JwtEncoderConfig(private val props: JwtProperties) {

    private fun secretKey(keyId: String): SecretKey =
        SecretKeySpec(Base64.getDecoder().decode(props.keys.getValue(keyId)), "HmacSHA256")

    @Bean
    fun jwtEncoder(): JwtEncoder {
        val jwkSet = JWKSet(
            props.keys.keys.map { kid ->
                OctetSequenceKey.Builder(secretKey(kid)).keyID(kid).algorithm(JWSAlgorithm.HS256).build()
            },
        )
        return NimbusJwtEncoder(ImmutableJWKSet(jwkSet))
    }

    @Bean
    fun jwtDecoder(): JwtDecoder =
        // 校验时按 header 里的 kid 选密钥，所以轮换期间新旧 token 都能验过
        NimbusJwtDecoder.withSecretKey(secretKey(props.activeKeyId))
            .macAlgorithm(MacAlgorithm.HS256)
            .build()
}
```

```kotlin
// platform-security/.../AccessTokenIssuer.kt
@Component
class AccessTokenIssuer(
    private val jwtEncoder: JwtEncoder,
    private val props: JwtProperties,
    private val clock: Clock,
) {
    fun issue(userId: Long, storeId: Long, roles: List<String>): String {
        val now = clock.instant()
        val claims = JwtClaimsSet.builder()
            .subject(userId.toString())
            .claim("storeId", storeId)
            .claim("roles", roles)
            .id(UUID.randomUUID().toString())        // jti
            .issuedAt(now)
            .expiresAt(now.plus(props.accessTokenTtlMinutes, ChronoUnit.MINUTES))
            .build()
        val header = JwsHeader.with(MacAlgorithm.HS256).keyId(props.activeKeyId).build()
        return jwtEncoder.encode(JwtEncoderParameters.from(header, claims)).tokenValue
    }
}
```

### Access Token 的 claims 结构

```json
{
  "sub": "1024",
  "storeId": 7,
  "roles": ["STORE_MANAGER"],
  "jti": "9f2b6e2e-2f3a-4b7a-9b0a-2c8e6f5a1d3c",
  "iat": 1735600000,
  "exp": 1735601800
}
```

`jti` 只用于**审计关联**（跟 `traceId` 一起打进日志，方便事后查"这个用户当时用的是哪个 access token"），不用于撤销判断——access token 本身依然是无状态的，服务端不会为了撤销去反查 `jti`，那样就失去了 JWT 免查库校验的意义。真正需要撤销能力的是下面的 refresh token。

## `StoreContextHolder` 与上下文注入

```kotlin
// platform-security/.../StoreContextHolder.kt
@Component
@RequestScope   // 默认 proxyMode = TARGET_CLASS，可以直接注入到单例 bean 里
class StoreContextHolder {
    var userId: Long? = null
    var storeId: Long? = null
    var roles: List<String> = emptyList()

    fun currentUserId(): Long = userId ?: throw IllegalStateException("未认证请求不应到达这里")
    fun currentStoreId(): Long = storeId ?: throw IllegalStateException("未绑定门店的请求不应到达这里")
}
```

Kotlin 里这个类必须是 `open` 的（CGLIB 代理要求），`kotlin-spring` 插件会因为 `@Component` 自动放开，不需要手写 `open`——但如果哪天把 `@Component` 换成了别的注册方式，这里会以一个不太好懂的报错炸掉，值得记一笔。

```kotlin
// platform-security/.../StoreContextFilter.kt
// 注意：这个 filter 只负责"把已经验过的 claims 搬进 StoreContextHolder"，
// 不做任何解析或验签——验签由 Spring Security 的 BearerTokenAuthenticationFilter 做完了。
// 这一点很关键：token 无效时的 401 响应由标准的 AuthenticationEntryPoint 产出，
// 不会出现"自己写的 filter 里抛异常 → @RestControllerAdvice 接不住 → 返回 500"的情况。
class StoreContextFilter(
    private val storeContextHolder: ObjectFactory<StoreContextHolder>,
) : OncePerRequestFilter() {

    override fun doFilterInternal(request: HttpServletRequest, response: HttpServletResponse, chain: FilterChain) {
        val jwt = (SecurityContextHolder.getContext().authentication as? JwtAuthenticationToken)?.token
        if (jwt != null) {
            val ctx = storeContextHolder.`object`
            ctx.userId = jwt.subject.toLong()
            ctx.storeId = jwt.getClaim<Number>("storeId")?.toLong()
            ctx.roles = jwt.getClaimAsStringList("roles") ?: emptyList()

            // 客户端会带 X-Store-Id（见 06-api-design.md 的统一请求头约定）。
            // 服务端一律以 token 里的 storeId 为准；不一致时记一条 warn 用于排查
            // （切店瞬间客户端可能还在用旧 header，直接拒绝会误伤正常请求）。
            request.getHeader("X-Store-Id")?.toLongOrNull()?.let { headerStoreId ->
                if (headerStoreId != ctx.storeId) {
                    logger.warn("X-Store-Id($headerStoreId) 与 token storeId(${ctx.storeId}) 不一致，以 token 为准")
                }
            }
        }
        chain.doFilter(request, response)
    }
}
```

其他 domain 里的 `application` 层直接注入 `StoreContextHolder` 拿当前上下文，不自己解析 token：

```kotlin
@Service
class WorkbenchAppService(
    private val storeContextHolder: StoreContextHolder,
    private val tileRepository: WorkbenchTileRepository,
) {
    fun listTiles(): List<TileResponse> {
        val userId = storeContextHolder.currentUserId()
        val storeId = storeContextHolder.currentStoreId()
        // ...
    }
}
```

## `SecurityConfig`

```kotlin
@Configuration
@EnableWebSecurity
@EnableMethodSecurity          // 开启 @PreAuthorize
class SecurityConfig(
    private val storeContextHolder: ObjectFactory<StoreContextHolder>,
    private val entryPoint: ApiResultAuthenticationEntryPoint,
    private val accessDeniedHandler: ApiResultAccessDeniedHandler,
    private val environment: Environment,
) {
    @Bean
    fun filterChain(http: HttpSecurity): SecurityFilterChain {
        val isProd = environment.acceptsProfiles(Profiles.of("prod"))

        http
            .csrf { it.disable() }   // 无状态 API + Bearer token，不存在 CSRF 的前提
            .sessionManagement { it.sessionCreationPolicy(SessionCreationPolicy.STATELESS) }
            .authorizeHttpRequests { auth ->
                auth.requestMatchers(
                    "/actuator/health/**",       // 存活/就绪探针，见 08-observability.md
                    "/api/v1/auth/login",
                    "/api/v1/auth/refresh",      // 调它的时候 access token 已过期，必须免认证
                ).permitAll()

                if (!isProd) {
                    // 接口文档只在非生产环境开放；生产环境走内网文档站或 CI 产物
                    auth.requestMatchers("/swagger-ui/**", "/v3/api-docs/**").permitAll()
                }

                auth.anyRequest().authenticated()
            }
            .oauth2ResourceServer { oauth2 ->
                oauth2.jwt { jwt -> jwt.jwtAuthenticationConverter(rolesConverter()) }
                oauth2.authenticationEntryPoint(entryPoint)      // token 缺失/过期/签名错 → 统一 401 JSON
            }
            .exceptionHandling {
                it.authenticationEntryPoint(entryPoint)
                it.accessDeniedHandler(accessDeniedHandler)      // 认证过但权限不足 → 统一 403 JSON
            }
            .addFilterAfter(
                StoreContextFilter(storeContextHolder),
                BearerTokenAuthenticationFilter::class.java,      // 必须在认证之后
            )
        return http.build()
    }

    private fun rolesConverter(): Converter<Jwt, AbstractAuthenticationToken> {
        val authorities = JwtGrantedAuthoritiesConverter().apply {
            setAuthoritiesClaimName("roles")
            setAuthorityPrefix("ROLE_")
        }
        return JwtAuthenticationConverter().apply { setJwtGrantedAuthoritiesConverter(authorities) }
    }
}
```

```kotlin
// platform-security/.../ApiResultAuthenticationEntryPoint.kt
@Component
class ApiResultAuthenticationEntryPoint(
    private val objectMapper: ObjectMapper,
) : AuthenticationEntryPoint {
    override fun commence(req: HttpServletRequest, resp: HttpServletResponse, ex: AuthenticationException) {
        resp.status = HttpStatus.UNAUTHORIZED.value()          // 必须是 401：客户端只在 401 时触发刷新
        resp.contentType = MediaType.APPLICATION_JSON_VALUE
        resp.characterEncoding = Charsets.UTF_8.name()
        objectMapper.writeValue(
            resp.outputStream,
            ApiResult.error(ErrorCode.UNAUTHORIZED, "登录状态已失效，请重新登录"),
        )
    }
}
```

**为什么这两个 handler 必须存在**：Spring Security 的过滤器跑在 `DispatcherServlet` **之前**，这里抛出的异常 `@RestControllerAdvice`（[06-api-design.md](./06-api-design.md) 的 `GlobalExceptionHandler`）根本接不到。如果不显式处理，token 过期会返回一个空 body 的 401 或者 Spring 默认的错误页——而客户端 [../05-networking.md](../../conti-retail-app/docs/05-networking.md) 是**严格按 HTTP 401 + `ApiResult` 结构**来判断"要不要触发 token 刷新"的。这里返回错了，整条自动刷新链路就是断的，表现为用户莫名其妙被登出。

## Refresh Token：不用 Redis，直接用现有 MySQL

Access token TTL 短（30 分钟），到期后客户端用 refresh token 换新的 access token，避免频繁重新登录。Refresh token **不是 JWT**，是一个不透明的随机字符串（`SecureRandom` 生成 32 字节，base64url 编码）：因为 refresh token 需要能被服务端主动吊销（登出、检测到被盗用），JWT 本身无状态、签发后没法在不额外存储的情况下撤销——既然撤销必须要有一张表来查，索性让 refresh token 本身就是这张表的查询 key，不需要再多一层"签发 JWT 又要验签"的复杂度。

```kotlin
// domains/identity-store/infrastructure/persistence/RefreshTokenEntity.kt
@Entity
@Table(name = "refresh_token", schema = "identity_store")
class RefreshTokenEntity(
    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    val id: Long = 0,

    @Column(nullable = false)
    val userId: Long,

    @Column(name = "token_hash", nullable = false, length = 64)
    val tokenHash: String,               // SHA-256(原始 token) 的 hex，不存明文

    @Column(nullable = false)
    val expiresAt: Instant,

    @Column
    var revokedAt: Instant? = null,

    @Column
    var replacedByTokenId: Long? = null,  // 轮换链，用于检测"已撤销的旧 token 被重放"
) : BaseEntity()
```

```sql
-- domains/identity-store/src/main/resources/db/migration/identity_store/V2__refresh_token.sql
create table refresh_token (
    id                      bigint       not null auto_increment,
    user_id                 bigint       not null,
    token_hash              char(64)     not null,
    expires_at              datetime(6)  not null,
    revoked_at              datetime(6),
    replaced_by_token_id    bigint,
    -- BaseEntity 的四个审计列，缺任何一个第一次插入就会失败，见 03-persistence.md
    created_at              datetime(6)  not null,
    updated_at              datetime(6)  not null,
    created_by              varchar(64),
    updated_by              varchar(64),
    primary key (id),
    unique key uk_refresh_token_hash (token_hash),
    key idx_refresh_token_user_id (user_id),
    key idx_refresh_token_expires_at (expires_at),
    constraint fk_refresh_token_user foreign key (user_id) references user (id)
) engine = InnoDB default charset = utf8mb4 collate = utf8mb4_0900_ai_ci;
```

```kotlin
// domains/identity-store/application/RefreshTokenService.kt
@Service
class RefreshTokenService(
    private val repository: RefreshTokenJpaRepository,
    private val props: JwtProperties,
    private val clock: Clock,
) {
    fun issue(userId: Long): String {
        val rawToken = generateOpaqueToken()
        repository.save(
            RefreshTokenEntity(
                userId = userId,
                tokenHash = sha256Hex(rawToken),
                expiresAt = clock.instant().plus(props.refreshTokenTtlDays, ChronoUnit.DAYS),
            ),
        )
        return rawToken          // 返回明文给客户端，库里只有 hash
    }

    @Transactional
    fun rotate(rawToken: String): RotatedTokens {
        val existing = repository.findByTokenHash(sha256Hex(rawToken))
            ?: throw InvalidRefreshTokenException()      // 从来不存在的 token

        // 重放检测：这个 token 存在，但已经被轮换掉了 —— 说明它很可能已泄漏，
        // 因为正常客户端拿到新 token 后不会再用旧的。撤销该用户全部 refresh token，强制重新登录。
        if (existing.revokedAt != null) {
            repository.revokeAllByUserId(existing.userId, clock.instant())
            log.warn("检测到 refresh token 重放，已撤销用户 {} 的全部 refresh token", existing.userId)
            throw InvalidRefreshTokenException()
        }
        if (existing.expiresAt.isBefore(clock.instant())) {
            throw InvalidRefreshTokenException()
        }

        val newRawToken = generateOpaqueToken()
        val rotated = repository.save(
            RefreshTokenEntity(
                userId = existing.userId,
                tokenHash = sha256Hex(newRawToken),      // 存 hash
                expiresAt = clock.instant().plus(props.refreshTokenTtlDays, ChronoUnit.DAYS),
            ),
        )
        existing.revokedAt = clock.instant()
        existing.replacedByTokenId = rotated.id

        return RotatedTokens(userId = existing.userId, refreshToken = newRawToken)   // 返回明文
    }

    @Transactional
    fun revoke(rawToken: String) {
        repository.findByTokenHash(sha256Hex(rawToken))
            ?.takeIf { it.revokedAt == null }
            ?.let { it.revokedAt = clock.instant() }
        // 登出场景：token 不存在或已撤销都视为成功，不给调用方任何"这个 token 存不存在"的信号
    }

    fun revokeAllByUser(userId: Long) = repository.revokeAllByUserId(userId, clock.instant())  // 强制下线
}

data class RotatedTokens(val userId: Long, val refreshToken: String)
```

- **轮换（rotation）**：每次用 refresh token 换 access token，同时签发一个新的 refresh token，旧的立刻标记 `revokedAt`。旧 token 之后又被用一次，就落进上面的重放分支——**注意"从来没见过的 token"和"已撤销的 token"必须分成两个分支处理**，合在一起写会让重放检测形同虚设（客户端 [../11-store-context-and-session.md](../../conti-retail-app/docs/11-store-context-and-session.md) 的串行刷新设计正是建立在"重放即全量撤销"这条规则上的）。
- **过期清理**：加一个定时任务定期删掉 `expires_at < now()` 且已撤销的行。**注意多副本下这个任务会在每个 Pod 各跑一次**，处理方式见 [12-concurrency-and-scheduling.md](./12-concurrency-and-scheduling.md)。

### 为什么现阶段不引入 Redis

Redis 常被用来存 refresh token/session，图的是两点：**自动过期（TTL）**和**高并发读写性能**。这两点目前都不是硬约束：

- 过期：一张表 + 一个定时清理任务就够，只是没有 Redis"写入即设 TTL、到期自动消失"那么省事。
- 性能：refresh token 校验只发生在"access token 过期后换新"这一低频动作上，不是每次请求都查，MySQL 上一个唯一索引足够支撑。
- 额外成本：引入 Redis 意味着在 K8s 上多起一个有状态服务（持久化、备份、连接池配置、AKS 里再开一条访问路径），这跟 [09-build-deploy.md](./09-build-deploy.md)、[07-config-governance.md](./07-config-governance.md) 里"能用现有基础设施就不额外引入运维负担"的取舍一致。

结论：refresh token 存现有 MySQL 就够，不引入 Redis；如果以后出现 Redis 能解决、MySQL 解决不了的场景（比如跨实例分布式限流、高频缓存），到时候再评估，届时 refresh token 也可以顺带迁过去，不存在现在这张表以后没法迁移的问题。

## 切换门店

```kotlin
@RestController
@RequestMapping("/api/v1/stores")
class StoreController(private val storeAppService: StoreAppService) {

    @Operation(summary = "切换当前门店，返回新的门店上下文与重新签发的 access token")
    @PostMapping("/{storeId}/switch")
    fun switchStore(@PathVariable storeId: Long): ApiResult<StoreContextResponse> =
        ApiResult.ok(storeAppService.switchStore(storeId))
}
```

```kotlin
@Service
class StoreAppService(
    private val storeRepository: StoreRepository,
    private val accessTokenIssuer: AccessTokenIssuer,
    private val storeContextHolder: StoreContextHolder,
    private val eventPublisher: ApplicationEventPublisher,
) {
    @Transactional
    fun switchStore(targetStoreId: Long): StoreContextResponse {
        val userId = storeContextHolder.currentUserId()

        // 1. 必须校验目标门店对当前用户可访问 —— 否则任何人改一下 URL 里的 id 就能进别人的门店
        val store = storeRepository.findAccessibleStore(userId, targetStoreId)
            ?: throw BusinessException(ErrorCode.STORE_NOT_ACCESSIBLE, "无权访问该门店", HttpStatus.FORBIDDEN)

        val roles = storeRepository.findRoles(userId, targetStoreId)

        // 2. 重新签发 access token —— 新 token 里的 storeId 是目标门店。
        //    这一步不能省：token 里的 storeId 决定了后续所有请求的数据范围，
        //    只改客户端本地状态不换 token，等于门店没真的切过去。
        val accessToken = accessTokenIssuer.issue(userId, targetStoreId, roles)

        // 3. 切店会使旧门店下的 WebView 票据失效（架构图 Flow 2）。
        //    走领域事件，不由 identity-store 直接改 webview-ticket 的表，见 11-cross-domain-collaboration.md
        eventPublisher.publishEvent(StoreSwitchedEvent(userId, from = storeContextHolder.storeId, to = targetStoreId))

        return StoreContextResponse(accessToken, store.toInfo(), roles, menuOf(roles))
    }
}
```

refresh token **不随切店轮换**：它绑定的是用户身份而不是门店，切店只换 access token。

## 越权与数据隔离规则

这是这套系统里最容易出、也最贵的一类漏洞（一个门店看到另一个门店的数据），单独立规则：

1. **所有涉及门店数据的查询，必须以 `storeContextHolder.currentStoreId()` 作为过滤条件**，而不是用请求参数里传来的 `storeId`。请求参数可以被任意篡改，token 里的不行。
2. **确实需要按路径/参数指定 `storeId` 的接口（如切店），必须先校验该用户对目标门店的可访问性**，校验不过返回 `STORE_NOT_ACCESSIBLE`。上面的 `findAccessibleStore` 就是这个模式：把权限校验合进查询条件，而不是"先查出来再判断"——后者很容易漏判，前者查不到就是没权限。
3. **按 ID 查单条记录时，`where id = ? and store_id = ?`**，不要只按主键查完再比对——只按主键查会让"不存在"和"没权限"走不同的代码路径，容易漏掉后者，而且响应差异本身就是一种信息泄漏。
4. 这三条在 code review 里是必看项，新增查询方法时优先检查。

### 接口级权限 vs 菜单权限

- **菜单权限**（切店时返回的 `menu`）只决定 APP 上显示什么，是 UI 层的便利，**不构成安全边界**。客户端拿到的菜单里没有某一项，不代表它调不到对应接口。
- **接口级权限**用 `@PreAuthorize` 在 `application` 层（或 Controller）上显式声明，这才是真正的边界：

  ```kotlin
  @PreAuthorize("hasRole('STORE_MANAGER')")
  fun approveProcurement(id: Long) { ... }
  ```
- 两者的数据来源应该是同一份角色/权限配置，但**必须两边都做**。只做菜单不做接口校验，等于没做。

## 密码存储与登录保护

- **密码用 BCrypt 存储**（`BCryptPasswordEncoder`，强度 12），存 hash，绝不存明文或可逆加密。用 `DelegatingPasswordEncoder`（Spring Security 默认）让 hash 带 `{bcrypt}` 前缀，将来换算法时新旧可以共存。
- **登录失败限流**：`user` 表上加 `failed_attempts` / `locked_until` 两列，同一账号连续失败 5 次锁定 15 分钟。放在数据库而不是内存里，是因为多副本下内存计数各算各的，等于没限。
- **IP 维度的限流放在 API Gateway 做**，后端不重复实现——后端看到的往往是网关的 IP，自己做也做不准。
- **登录失败的响应不区分"用户不存在"和"密码错误"**，统一返回同一个错误码和文案，避免被用来枚举账号。
- 密码、token、`Authorization` 头等敏感字段**不允许进日志**，脱敏规则见 [08-observability.md](./08-observability.md)。

## 密钥轮换

JWT 签名密钥放在 K8s Secret 里（见 [07-config-governance.md](./07-config-governance.md)），轮换按 `kid` 分三步走，全程不需要让用户重新登录：

1. **加新密钥**：在 `security.jwt.keys` 里加一个新 `kid`，但 `activeKeyId` 保持旧的。这时新旧密钥都能验签，签发仍用旧的。滚动更新完成后所有实例都认识新密钥。
2. **切签发**：把 `activeKeyId` 改成新 `kid`。此时新签发的 token 用新密钥，还在有效期内的旧 token 仍能验过。
3. **删旧密钥**：等超过一个 access token TTL（30 分钟）后，从 `keys` 里移除旧 `kid`。

三步之间必须各自完成一次滚动更新，不能合并成一次改动——合并了会出现"某些实例已经用新密钥签发，另一些实例还不认识新密钥"的窗口，表现为随机 401。

## 关键规则

- `API Gateway` 已做 TLS/路由，后端服务只需要校验 JWT 签名和 claims，不重复做接入层的事。
- 门店/角色上下文在统一 filter 里从已认证的 `Jwt` 写入 `StoreContextHolder`，各 domain 通过它读取，不各自解析 token。
- 切换门店必须重新签发 access token，并联动使 `webview-ticket` 的当前票据失效（架构图 Flow 2）——走领域事件，不跨模块直接改表。
- `webview-ticket` 用的票据是独立的短时票据机制（见 [05-integration-layer.md](./05-integration-layer.md)），不复用登录 JWT，避免票据泄漏后长期有效。

## 附录一：为什么用 Spring Security 内置的 Nimbus，而不是 jjwt

jjwt 是 Java 生态里很常见的 JWT 库，但在我们这个版本基线（Spring Boot 4 / [01-project-structure.md](./01-project-structure.md)）下它有个具体问题：jjwt 的 JSON 序列化模块 `jjwt-jackson` 依赖 **Jackson 2**（`com.fasterxml.jackson`），而 Boot 4 默认用的是 **Jackson 3**（`tools.jackson`）。两者包名不同、不二进制兼容，用 jjwt 就意味着要在同一个应用里同时带两套 Jackson——能跑，但多一份依赖、多一处升级时要照顾的地方，还容易让人误以为 `ObjectMapper` 只有一个。

Spring Security 本身就自带基于 Nimbus JOSE + JWT 的 `JwtEncoder`/`JwtDecoder`（`spring-boot-starter-oauth2-resource-server`），版本由 Boot BOM 管，不引入第二套 JSON 库。更重要的是，用它就能顺带用上 `oauth2ResourceServer` 这套标准链路：**token 的解析和验签由框架的 filter 完成，失败时走标准的 `AuthenticationEntryPoint` 返回 401**——而自己写 filter 解析 token 时，最常见的 bug 恰恰是异常没接住导致返回 500（详见上面 handler 那一节）。选它是同时解决依赖和正确性两个问题。

代价：Nimbus 的 API 比 jjwt 的链式 builder 略啰嗦一点（多一个 `JwtClaimsSet`/`JwsHeader` 的概念），以及如果团队里有人熟悉 jjwt 需要适应一下。如果后续确实要换回 jjwt，注意版本要选和 Jackson 3 兼容的，或者自己实现 jjwt 的 `Serializer`/`Deserializer` 接口接到 Jackson 3 上。

## 附录二：为什么用 `RequestScope` bean 而不是 `ThreadLocal`

传统做法常见用 `ThreadLocal` 存当前用户上下文，但 `ThreadLocal` 有两个常见坑：

1. **忘记清理**：请求处理完不手动 `remove()`，线程池复用线程时，下一个请求可能读到上一个请求残留的上下文——在 Tomcat 这种线程池容器里是真实发生过的安全事故类型。
2. **线程切换场景失效**：一旦把工作交给另一个线程池（比如 `workbench` 首页的并行聚合，见 [11-cross-domain-collaboration.md](./11-cross-domain-collaboration.md)），`ThreadLocal` 绑定的线程和实际干活的线程就不是同一个了。

Spring 的 `@RequestScope` bean 由容器管理生命周期，请求结束自动销毁，不需要手动清理，语义上也更清楚地表达"这个对象的生命周期等于一次 HTTP 请求"。

需要注意的是 `@RequestScope` 也**不会自动跨线程传播**：并行聚合时子线程里拿不到它。那种场景要么把需要的值（`userId`/`storeId`）作为方法参数显式传进去（推荐，最不容易出错），要么给线程池配 `TaskDecorator` 显式搬运上下文——两种做法的取舍见 11 篇。

## 待补充

- 权限模型细节：角色-权限-菜单三张表怎么设计，是否需要按门店维度分配不同角色。

## 参考链接

- [Spring Security 官方文档](https://docs.spring.io/spring-security/reference/index.html)
- [Spring Security: JWT 支持（JwtEncoder / JwtDecoder）](https://docs.spring.io/spring-security/reference/servlet/oauth2/resource-server/jwt.html)
- [OWASP JWT 安全实践](https://cheatsheetseries.owasp.org/cheatsheets/JSON_Web_Token_for_Java_Cheat_Sheet.html)
- [OWASP 认证 Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html)
- [Auth0: Refresh Token Rotation](https://auth0.com/docs/secure/tokens/refresh-tokens/refresh-token-rotation)