# Login Region Risk Architecture

本文档定义登录地区、语言和时区限制的当前推荐方案。方案按当前产品取舍设计：不引入 `pending_risk` 会话，不让各玩法服务分别判断风险状态；用户在未知 IP 首次登录时可以进入 App，后台异步 IP 风控命中不支持国家后撤销 session 并踢下线，后续同一 IP 再登录会在入口直接拒绝。

## Scope

| Capability | Owner | Rule |
| --- | --- | --- |
| 真实入口 IP 提取 | `gateway-service` | 从可信上游 header 或 `RemoteAddr` 提取，不信任前端 JSON 里的 IP |
| 语言和时区快速判断 | `gateway-service` | 只做入口级弱信号拦截，命中明显不支持配置时直接拒绝登录 |
| IP 风控缓存读取 | `gateway-service` | 登录前读取 Redis IP 决策缓存，`blocked` 直接拒绝，`allowed/unknown/miss` 放行并触发复核 |
| 登录、session 和 token | `user-service` | 仍是 session owner；登录成功后创建 `auth_sessions` 并签发 token |
| 异步 IP 风控任务 | `cron-service` 调度，`user-service` 执行 | 按优先级顺序查询 IP Geo 源；当前一个不可用时才降级到下一个，写持久审计和 Redis 缓存 |
| session 撤销 | `user-service` | 命中不支持国家后撤销 session，写撤销原因和审计 |
| 登录态接口统一拦截 | `gateway-service` | JWT 校验后统一检查 session 是否已撤销，避免玩法服务散落判断 |
| 房间/IM 踢下线 | `gateway-service` 编排，`room-service`/腾讯云 IM 执行 | 只能走 Room Cell 命令或腾讯云 IM 服务端接口，不能直接改 room Redis |
| 后台登录日志 | `hyapp-admin-server` | 只在用户管理一级菜单下新增二级菜单“登录日志”，不单独做风控策略后台 |

## Non-Goals

| Non-goal | Reason |
| --- | --- |
| 不做 `pending_risk` session | 当前阶段要降低接入成本，避免设计白名单接口和受限权限集 |
| 不在玩法服务判断地区风险 | 房间、礼物、钱包、VIP、任务都不应该各自写 `risk_status` 判断，容易漏 |
| 不把 IP Geo 查询接口放进同步登录路径 | 外部接口慢、超时或不稳定会拖慢登录 |
| 不信任前端传过来的 IP | 客户端字段可伪造，只能作为调试或兼容字段记录 |
| 不靠“清客户端 token”完成踢下线 | JWT 已签发后客户端仍可能继续使用，必须服务端撤销 session 并由 gateway 拦截 |
| 不把 Redis 当唯一事实来源 | Redis 只做快查缓存；审计、任务、明文 IP 和撤销原因必须能在 MySQL 追溯 |
| 不做独立风控后台 | 当前后台只提供登录日志查看，不提供策略编辑、provider 管理或人工改判 |

## Core Decision

采用“入口快拦 + 登录后异步复核 + session 统一撤销”的模型：

```mermaid
flowchart LR
  C["Client"] --> G["gateway-service"]
  G --> LangTZ["language/timezone fast guard"]
  G --> Cache["Redis IP decision cache"]
  Cache -->|blocked| Deny["reject login"]
  Cache -->|allowed/miss/unknown| U["user-service Auth"]
  U --> Session[("auth_sessions")]
  U --> Resp["token response"]
  U --> Job[("login_ip_risk_jobs / outbox")]
  Job --> RiskBatch["cron triggered IP risk batch"]
  RiskBatch --> IP1["IP Geo A"]
  IP1 -. "unavailable/timeout" .-> IP2["IP Geo B"]
  IP2 -. "unavailable/timeout" .-> IP3["IP Geo C"]
  IP3 -. "unavailable/timeout" .-> IP4["IP Geo D"]
  RiskBatch --> Decision[("risk decision + Redis cache")]
  RiskBatch -->|blocked| Revoke["revoke session"]
  Revoke --> Kick["IM/Room kick"]
```

这个方案接受一个明确边界：未知 IP 第一次可能短暂进入 App。通过 Redis 缓存和 session 撤销，同一个 IP 后续不能反复完整登录。

## Login Flow

### Password Login

```mermaid
sequenceDiagram
  participant App
  participant Gateway
  participant User as user-service
  participant Redis
  participant Risk as cron-service/user-service batch

  App->>Gateway: POST /api/v1/auth/account/login
  Gateway->>Gateway: extract trusted client_ip
  Gateway->>Gateway: check language/timezone config
  Gateway->>Redis: GET ip decision
  alt ip blocked
    Gateway-->>App: AUTH_LOGIN_BLOCKED
  else allowed/miss/unknown
    Gateway->>User: LoginPassword(meta.client_ip, language, timezone)
    User->>User: verify password and create session
    User->>User: enqueue login_ip_risk_job
    User-->>Gateway: token(session_id)
    Gateway-->>App: token
    Risk->>Risk: async resolve IP by provider fallback chain
    alt unsupported country
      Risk->>User: RevokeSession(session_id, reason)
      Risk->>Redis: SET ip decision = blocked
      Risk->>Gateway: trigger kick orchestration
    else allowed country
      Risk->>Redis: SET ip decision = allowed
    end
  end
```

### Third Party Login

三方登录和密码登录使用同一套入口风控，只是 `user-service` 在创建或复用用户 session 后写风险任务。三方首次注册时，客户端提交的 `country` 仍然只是用户选择国家；IP 国家由服务端 IP Geo 结果决定，不能用 `country` 替代风控国家。

## Gateway Fast Guard

gateway 只做三件事：

1. 提取可信入口 IP。
2. 对 `language` 和 `timezone` 做简单配置判断。
3. 查询 Redis IP 决策缓存，命中 `blocked` 时拒绝登录。

### Trusted IP

可信 IP 来源顺序：

```text
trusted edge header -> X-Forwarded-For first public IP -> RemoteAddr
```

前端提交的 `ip` 字段不参与判断。旧客户端如果还传 IP，只能写入审计扩展字段，不能作为风控依据。

### Language And Timezone

语言和时区是弱信号，因为客户端可以修改。它们只能做入口快速拦截：

```yaml
login_risk:
  blocked_languages:
    - zh-CN
  blocked_language_primary_tags:
    - zh
  blocked_timezones:
    - Asia/Shanghai
  blocked_timezone_prefixes:
    - Asia/
```

规则：

- `language` 按 BCP 47 轻量格式校验，例如 `en-US`、`zh-CN`。
- `timezone` 必须是 IANA 名称，例如 `America/Los_Angeles`。
- 命中阻断配置时，gateway 返回 `AUTH_LOGIN_BLOCKED`。
- 未传、格式异常或不可信时，不直接推断国家；只记录审计。

### IP Decision Cache

Redis key 建议不要保存明文 IP：

```text
login_risk:ip:{app_code}:{sha256(ip)}
```

Value：

```json
{
  "decision": "blocked",
  "country": "CN",
  "source": "geo_provider_chain",
  "checked_at_ms": 1710000000000,
  "expires_at_ms": 1710604800000
}
```

决策值：

| Decision | Gateway Action |
| --- | --- |
| `blocked` | 登录前直接拒绝 |
| `allowed` | 放行登录，可低频复核 |
| `unknown` | 放行登录，必须异步复核 |
| miss | 放行登录，必须异步复核 |

TTL 建议：

| Decision | TTL |
| --- | --- |
| `blocked` | 7 到 30 天 |
| `allowed` | 1 到 7 天 |
| `unknown` | 10 到 60 分钟 |

可用性策略：Redis 不可用时放行登录，只记录错误和告警；不能因为 Redis 故障阻断登录。

## Async IP Risk Check

异步 IP 风控 batch 按优先级顺序调用 IP Geo 源，不阻塞登录响应。一次任务只使用一个可用 provider 的结果；只有当前 provider 超时、不可用或返回不可解析结果时，才请求下一个 provider。

### Job

风险任务需要包含：

| Field | Rule |
| --- | --- |
| `job_id` | 幂等任务 ID |
| `app_code` | 多 App 隔离 |
| `session_id` | 命中后撤销的 session |
| `user_id` | 审计和踢下线目标 |
| `client_ip` | 明文入口 IP，后台登录日志直接展示 |
| `client_ip_hash` | 缓存 key、索引和日志关联字段，避免普通日志输出明文 IP |
| `channel` | 登录渠道：`account/google/facebook/twitter/tiktok` |
| `platform` | 客户端平台：`android/ios` |
| `language` | 登录时客户端语言 |
| `timezone` | 登录时客户端时区 |
| `request_id` | 串联登录日志 |
| `status` | `pending/running/completed/failed/skipped` |
| `created_at_ms` | 任务创建时间 |
| `updated_at_ms` | 任务更新时间 |

任务可以落 MySQL 表 `login_ip_risk_jobs`，也可以由 user outbox 派生。首版如果没有统一 MQ，优先用 MySQL 任务表 + cron-service 调度的 batch claim，避免 Redis list 丢失导致永远不复核。MySQL 写任务失败时不影响登录结果，但必须记录错误和告警。

### Provider Fallback Chain

batch 行为：

1. 先查 Redis 是否已有新鲜决策；已有 `blocked/allowed` 可以跳过外部查询。
2. miss 时按配置顺序调用第一个 provider。
3. 如果 provider 在 timeout 内返回有效国家码，立即停止查询后续 provider。
4. 如果 provider 超时、不可用、限流、返回空国家或返回不可解析结果，记录失败原因并降级到下一个 provider。
5. 所有 provider 都失败时，输出 `unknown`，写短 TTL 缓存并等待后续任务重试；如果缓存也不可用，只记录日志和告警。
6. 有效国家码命中不支持国家时输出 `blocked`；有效国家码未命中不支持国家时输出 `allowed`。
7. 写 MySQL 决策记录和 Redis 缓存。
8. 如果命中不支持国家，撤销当前 session 并触发踢下线。

该模型没有“结果冲突”问题，因为同一个任务不会同时采信多个 provider。provider 顺序就是信任优先级：

| Case | Decision |
| --- | --- |
| 第一个可用 provider 返回不支持国家 | `blocked` |
| 第一个可用 provider 返回支持国家 | `allowed` |
| provider 超时、不可用或返回无效结果 | 请求下一个 provider |
| 所有 provider 都失败 | `unknown`，短 TTL，后续重试 |

不支持国家列表必须来自配置，不应硬编码在风控逻辑里；当前后台不提供策略编辑能力。

## Session Revocation

命中不支持国家时，撤销 session 是核心动作。

```text
auth_sessions.revoked_at_ms = now
auth_sessions.revoked_reason = GEO_POLICY_BLOCKED
```

当前表只有 `revoked_at_ms`，实现时建议补充：

| Field | Reason |
| --- | --- |
| `revoked_reason` | 区分用户 logout、refresh 轮换、后台封禁、IP 风控撤销 |
| `revoked_request_id` | 串联风险任务和审计 |
| `revoked_by` | `risk_worker`、`user_logout`、`admin` |

撤销成功后写 Redis denylist：

```text
auth:revoked_session:{app_code}:{session_id} = GEO_POLICY_BLOCKED
TTL = access token remaining ttl + safety window
```

## Gateway Session Guard

如果 access token 是 JWT，只校验签名不够。用户已经拿到 access token 后，即使 `auth_sessions` 被撤销，JWT 在过期前仍然能访问接口。

因此 gateway 必须增加统一 session guard：

```text
Authorization JWT valid
+ sid exists
+ auth:revoked_session:{app_code}:{sid} not exists
```

首版可以先只查 Redis denylist，不对每个请求同步查 MySQL：

- 登录成功时不需要写 active cache。
- 风控撤销 session 时写 denylist。
- logout、refresh 轮换、后台封禁同样写 denylist。
- access token TTL 到期后 denylist 自然失效。

后续如果需要更强一致性，再增加 `ValidateSession` RPC 或 `auth:active_session` cache。

所有 App 登录态接口都走 gateway middleware，因此玩法服务不需要感知风险状态：

```mermaid
flowchart TD
  Req["Business Request"] --> JWT["Verify JWT"]
  JWT --> SID["Read sid claim"]
  SID --> Deny["Check Redis revoked_session"]
  Deny -->|revoked| Fail["SESSION_REVOKED"]
  Deny -->|active| Handler["Business handler"]
```

## Kick Offline

踢下线分三层，按能做到的程度逐步接入：

| Layer | Action | Required |
| --- | --- | --- |
| API | gateway session guard 返回 `SESSION_REVOKED` | 必须 |
| IM | 调腾讯云 IM 服务端接口踢下线或发系统消息通知客户端清 token | 建议 |
| Room | 如果用户在房间，通过 room-service Room Cell 命令踢出或触发离房 | 建议 |

不能直接删除 room-service Redis presence 或麦位缓存。房间状态 owner 是 Room Cell，风险踢人必须走 room-service 的命令入口；如果首版没有踢人命令，至少依靠 session guard 阻止后续 HTTP 操作，并让房间 heartbeat/断线补偿释放状态。

## Error Codes

建议新增稳定业务码：

| Code | HTTP | gRPC | Meaning |
| --- | --- | --- | --- |
| `AUTH_LOGIN_BLOCKED` | 403 | `PermissionDenied` | 登录入口命中地区、语言、时区或 IP 风控策略 |
| `SESSION_REVOKED` | 401 | `Unauthenticated` | session 已撤销，客户端必须清登录态 |

客户端行为：

- `AUTH_LOGIN_BLOCKED`：停留登录页，展示地区不支持类提示。
- `SESSION_REVOKED`：清本地 token，退出房间/IM，回登录页。
- 普通 5xx 或网络失败不能清 token。

## Audit And Observability

必须记录：

| Event | Fields |
| --- | --- |
| `login_fast_guard_blocked` | `request_id/app_code/client_ip_hash/language/timezone/block_reason` |
| `login_ip_risk_job_created` | `request_id/app_code/session_id/user_id/client_ip/client_ip_hash/channel/platform` |
| `login_ip_geo_provider_attempt` | `job_id/provider/order/country/status/duration_ms/error_code` |
| `login_ip_risk_decision` | `job_id/session_id/user_id/decision/country/confidence` |
| `login_session_revoked_by_risk` | `job_id/session_id/user_id/reason/country` |
| `kick_offline_result` | `session_id/user_id/im_result/room_result` |

敏感规则：

- 不记录明文 access token、refresh token、三方 credential。
- 明文 IP 可以落 MySQL 业务表，供后台登录日志查看；普通服务日志仍只记录 `client_ip_hash`，避免日志系统大范围暴露明文 IP。
- provider 返回原始报文不进日志，只记录本次尝试的顺序、标准化国家码、耗时和错误码。

## Data Model

### `login_ip_risk_jobs`

```sql
CREATE TABLE login_ip_risk_jobs (
  app_code VARCHAR(32) NOT NULL,
  job_id VARCHAR(96) NOT NULL,
  session_id VARCHAR(96) NOT NULL,
  user_id BIGINT NOT NULL,
  client_ip VARCHAR(64) NOT NULL,
  client_ip_hash VARCHAR(128) NOT NULL,
  channel VARCHAR(32) NOT NULL,
  platform VARCHAR(16) NOT NULL,
  language VARCHAR(32) NOT NULL DEFAULT '',
  timezone VARCHAR(64) NOT NULL DEFAULT '',
  request_id VARCHAR(96) NOT NULL DEFAULT '',
  status VARCHAR(32) NOT NULL,
  decision VARCHAR(32) NOT NULL DEFAULT '',
  country_code VARCHAR(3) NOT NULL DEFAULT '',
  failure_reason VARCHAR(128) NOT NULL DEFAULT '',
  locked_by VARCHAR(128) NULL,
  locked_until_ms BIGINT NULL,
  attempt_count INT NOT NULL DEFAULT 0,
  created_at_ms BIGINT NOT NULL,
  updated_at_ms BIGINT NOT NULL,
  PRIMARY KEY (app_code, job_id),
  KEY idx_login_ip_risk_jobs_status (app_code, status, updated_at_ms),
  KEY idx_login_ip_risk_jobs_session (app_code, session_id),
  KEY idx_login_ip_risk_jobs_user (app_code, user_id, created_at_ms),
  KEY idx_login_ip_risk_jobs_ip (app_code, client_ip_hash, updated_at_ms)
);
```

### `login_ip_risk_decisions`

```sql
CREATE TABLE login_ip_risk_decisions (
  app_code VARCHAR(32) NOT NULL,
  decision_id VARCHAR(96) NOT NULL,
  client_ip VARCHAR(64) NOT NULL,
  client_ip_hash VARCHAR(128) NOT NULL,
  decision VARCHAR(32) NOT NULL,
  country_code VARCHAR(3) NOT NULL DEFAULT '',
  confidence INT NOT NULL DEFAULT 0,
  provider_attempts_json JSON NOT NULL,
  decided_at_ms BIGINT NOT NULL,
  expires_at_ms BIGINT NOT NULL,
  created_at_ms BIGINT NOT NULL,
  PRIMARY KEY (app_code, decision_id),
  KEY idx_login_ip_risk_decisions_ip (app_code, client_ip_hash, decided_at_ms),
  KEY idx_login_ip_risk_decisions_country (app_code, country_code, decided_at_ms),
  KEY idx_login_ip_risk_decisions_expires (app_code, expires_at_ms)
);
```

### `login_audit` Additions

现有 `login_audit` 已记录登录类型、provider、结果和失败原因。为了支撑后台登录日志，需要把登录入口展示字段补齐：

```sql
ALTER TABLE login_audit
  ADD COLUMN channel VARCHAR(32) NOT NULL DEFAULT '',
  ADD COLUMN platform VARCHAR(16) NOT NULL DEFAULT '',
  ADD COLUMN client_ip VARCHAR(64) NOT NULL DEFAULT '',
  ADD COLUMN ip_country_code VARCHAR(3) NOT NULL DEFAULT '',
  ADD COLUMN blocked TINYINT(1) NOT NULL DEFAULT 0,
  ADD COLUMN block_reason VARCHAR(64) NOT NULL DEFAULT '',
  ADD KEY idx_login_audit_user_created (app_code, user_id, created_at_ms),
  ADD KEY idx_login_audit_blocked (app_code, blocked, created_at_ms),
  ADD KEY idx_login_audit_ip_country (app_code, ip_country_code, created_at_ms);
```

字段口径：

| Field | Rule |
| --- | --- |
| `channel` | `account/google/facebook/twitter/tiktok`，三方 provider 必须归一成这几个展示值 |
| `platform` | `android/ios`，来自客户端请求体或可信 header |
| `client_ip` | 明文入口 IP，来自 gateway 提取结果 |
| `ip_country_code` | IP Geo 解析出的国家码，未解析时为空 |
| `blocked` | 当前登录是否被语言、时区、IP cache 或异步 IP 风控阻断 |
| `block_reason` | `language/timezone/ip_cache/ip_async` 等稳定原因 |

### `auth_sessions` Additions

```sql
ALTER TABLE auth_sessions
  ADD COLUMN revoked_reason VARCHAR(64) NOT NULL DEFAULT '',
  ADD COLUMN revoked_request_id VARCHAR(96) NOT NULL DEFAULT '',
  ADD COLUMN revoked_by VARCHAR(64) NOT NULL DEFAULT '';
```

## Admin Login Logs

后台管理当前只做查询和展示，不做风控配置编辑。入口位置：

```text
用户管理
  └── 登录日志
```

### List Page

列表按登录事件展示，默认按 `created_at_ms DESC` 分页。

展示字段：

| Column | Source |
| --- | --- |
| 用户 ID | `login_audit.user_id` |
| 短号 | join `users.current_display_user_id` |
| 昵称 | join `users.username` |
| 国家/区域 | join `users.country/region_id`，只作用户资料快照展示 |
| 登录 IP | `login_audit.client_ip` |
| IP 所在国家 | `login_audit.ip_country_code` |
| 渠道 | `login_audit.channel`，值为 `account/google/facebook/twitter/tiktok` |
| 平台 | `login_audit.platform`，值为 `android/ios` |
| 结果 | `success/failed/blocked/revoked` |
| 屏蔽原因 | `login_audit.block_reason` |
| 登录时间 | `login_audit.created_at_ms` |

交互规则：

- `blocked=true` 或 `failure_code=AUTH_LOGIN_BLOCKED` 的表格行背景显示红色。
- 如果异步 IP 风控在登录成功后撤销 session，该次登录日志也要更新为屏蔽态，行背景显示红色。
- 点击任意用户行，进入该用户历史登录日志侧栏或详情页。
- 列表只读，不提供解除屏蔽、修改策略、重试 provider 或手动踢下线按钮。

筛选条件：

| Filter | Rule |
| --- | --- |
| 用户 ID / 短号 | 精确搜索，短号需要先解析成 `user_id` |
| IP | 精确搜索明文 IP |
| IP 国家 | 按 `ip_country_code` |
| 渠道 | `account/google/facebook/twitter/tiktok` |
| 平台 | `android/ios` |
| 是否屏蔽 | `all/blocked/not_blocked` |
| 时间范围 | 按 `created_at_ms` |

### User History

点击用户行后展示该用户历史登录日志：

| Field | Rule |
| --- | --- |
| 用户基础信息 | user_id、短号、昵称、头像、当前国家、当前区域 |
| 最近登录列表 | 按时间倒序展示该用户所有登录事件 |
| 风控结果 | 展示 IP 国家、是否屏蔽、屏蔽原因、撤销 session 时间 |
| 渠道和平台 | 展示每次登录的 channel/platform |

用户历史页只读。若后续需要手动封禁、解封或策略配置，必须走独立后台能力和审计，不混在登录日志里。

## Configuration

首版配置放 gateway、user-service 和 cron-service 的 YAML。当前后台只做登录日志查看，不管理不支持国家、provider 顺序或语言/时区策略：

```yaml
login_risk:
  enabled: true
  fast_guard:
    blocked_languages: []
    blocked_language_primary_tags: []
    blocked_timezones: []
    blocked_timezone_prefixes: []
  ip:
    unsupported_countries:
      - CN
    blocked_ttl_sec: 2592000
    allowed_ttl_sec: 604800
    unknown_ttl_sec: 1800
    provider_timeout_ms: 800
    providers:
      - primary_geo
      - fallback_geo_a
      - fallback_geo_b
      - fallback_geo_c

# services/cron-service/configs/config*.yaml
tasks:
  login_ip_risk:
    enabled: true
    interval: 5s
    timeout: 3s
    lock_ttl: 30s
    batch_size: 100
```

配置原则：

- gateway 快速判断和 user-service IP 风控策略的不支持国家列表必须同源，避免 gateway 放行但后台风控用另一套规则。
- provider 顺序必须显式配置，顺序代表信任优先级；不要在代码里随机切换。
- 线上配置不要写 provider secret；provider key 走密钥系统或环境变量。
- 多 App 时按 `app_code` 覆盖策略。

## Failure Policy

| Failure | Policy |
| --- | --- |
| Redis 不可用 | 放行登录；记录错误和告警，不读写 IP decision cache；session denylist 失效属于踢下线实时性下降，不能阻断登录 |
| MySQL 写登录日志或风险任务失败 | 放行登录；记录 error 和告警，后续依赖下次登录或缓存命中补偿 |
| 所有 IP provider 都失败 | 放行登录；能写缓存则写 `unknown` 短 TTL，不能写缓存也不阻塞 |
| 前置 provider 不可用 | 自动降级到下一个 provider；如果全部不可用则放行 |
| session 已经 logout | 后台风控撤销幂等成功，不重复踢 |
| 用户已换新 session | 只撤销命中的 `session_id`；如果 IP 已 blocked，后续登录会被 gateway 拒绝 |
| 踢 IM 失败 | session 已撤销仍然生效；记录补偿任务或等待客户端下一次 API 返回 `SESSION_REVOKED` |
| 房间踢出失败 | 不直接改 Redis；记录补偿，依赖 Room Cell/heartbeat 兜底 |

## Implementation Sequence

1. 增加 `AUTH_LOGIN_BLOCKED` 错误码，并确认 gateway 对 `SESSION_REVOKED` 的客户端语义。
2. gateway 登录入口增加 language/timezone fast guard 和 IP decision cache 读取。
3. 登录请求把 `client_ip/language/timezone` 透传到 user-service；密码登录也需要补这两个字段。
4. user-service 登录成功后创建 `login_ip_risk_jobs`，任务至少包含 `session_id/user_id/client_ip/client_ip_hash/channel/platform/request_id`。
5. 扩展 `login_audit`，保存明文 IP、IP 国家、渠道、平台、是否屏蔽和屏蔽原因。
6. 实现 `UserCronService.ProcessLoginIPRiskBatch`：MySQL claim 任务，按优先级顺序调用 provider fallback chain，写决策和 Redis cache。
7. user-service 增加按 `session_id` 撤销 session 的内部能力，并写撤销原因。
8. gateway 增加统一 session denylist middleware，JWT 校验后查 `auth:revoked_session:{app_code}:{sid}`。
9. 风控撤销 session 时写 Redis denylist，并把对应登录审计更新为屏蔽态。
10. 接入腾讯云 IM 踢下线或系统消息通知。
11. 增加 room-service 踢人命令或复用现有 Room Cell 管理命令，不直接操作 room Redis。
12. admin 在用户管理下新增二级菜单“登录日志”，支持列表、筛选、红色屏蔽行和用户历史登录日志。
13. 增加日志、指标和告警：provider 超时率、unknown 比例、blocked 数、撤销数、踢下线失败数。

## Test Cases

| Case | Expected |
| --- | --- |
| language 命中阻断 | gateway 直接返回 `AUTH_LOGIN_BLOCKED`，不调用 user-service 登录 |
| timezone 命中阻断 | gateway 直接返回 `AUTH_LOGIN_BLOCKED` |
| IP cache blocked | gateway 直接返回 `AUTH_LOGIN_BLOCKED` |
| IP cache miss | 登录成功，创建风险任务 |
| 后台风控判定 allowed | 写 allowed cache，不撤销 session |
| 后台风控判定 blocked | 撤销 session，写 blocked cache，写 denylist，触发踢下线 |
| blocked 后同 IP 再登录 | gateway 登录前拒绝 |
| 已撤销 session 调业务接口 | gateway middleware 返回 `SESSION_REVOKED` |
| provider 全失败 | 放行，能写缓存则写 unknown cache，不踢下线 |
| 第一个 provider 不可用、第二个 provider 返回 blocked country | 写 blocked cache，撤销 session |
| 登录日志列表含 blocked 行 | 该行背景为红色 |
| 点击用户登录日志行 | 展示该用户历史登录日志 |
| refresh 使用已撤销 session | user-service 返回 `SESSION_REVOKED` |

## Open Decisions

| Decision | Recommendation |
| --- | --- |
| Redis/MySQL/IP 查询不可用时是否阻断登录 | 当前方案统一 fail-open：全部放行，只记录错误和告警 |
| 第一个可用 provider 命中不支持国家是否踢 | 当前方案直接踢；provider 顺序代表信任优先级 |
| 明文 IP 是否落库 | 明文 IP 落 MySQL，普通服务日志仍只打 hash |
| 是否做后台管理页面 | 只做用户管理下的“登录日志”二级菜单，不做策略编辑后台 |

## Final Rule

当前阶段最重要的工程约束是：地区风险只在 gateway 入口和 user-service session 层处理，玩法服务不感知风险状态。只要 gateway 统一检查 session denylist，后台异步命中后撤销 session 就能对房间、钱包、礼物、VIP、消息等所有 HTTP 业务统一生效。