Genarrative/docs/technical/SPACETIMEDB_AUTH_RISK_BLOCK_TABLE_DESIGN_2026-04-21.md

auth_risk_block 表设计

日期：2026-04-21

1. 文档目的

这份文档用于完成 M2 的第五条任务：设计 auth_risk_block。

目标是把鉴权风控保护表明确为“当前生效态真相表”，并固定：

1. 什么叫活跃封禁
2. 什么叫解除封禁
3. 它与 auth_audit_log 的边界
4. /api/auth/risk-blocks 与 /api/auth/risk-blocks/:scopeType/lift 的读写语义

2. 当前基线

当前 Node 后端已经存在 auth_risk_blocks 表，并具备以下能力：

1. 当手机号验证码失败次数达到阈值时，创建或刷新手机号保护
2. 当 IP 验证失败次数达到阈值时，创建或刷新网络保护
3. GET /api/auth/risk-blocks 返回当前用户手机号与当前请求 IP 命中的保护
4. POST /api/auth/risk-blocks/:scopeType/lift 支持用户主动解除当前手机号或当前网络保护

当前 Node auth_risk_blocks 字段基线：

1. id
2. scope_type
3. scope_key
4. reason
5. expires_at
6. lifted_at
7. created_at
8. updated_at

当前已落地的 scope 基线：

1. phone
2. ip

当前已落地的 reason 基线：

1. sms_verify_failures

3. 表职责边界

3.1 auth_risk_block 负责

1. 记录某个手机号或某个 IP 当前是否处于保护状态
2. 记录这次保护何时过期
3. 记录这次保护是否已被手动解除
4. 作为 /api/auth/risk-blocks 的唯一事实来源

3.2 它不负责

1. 记录所有历史触发次数
2. 记录所有历史解除动作
3. 生成用户可读标题和说明文案
4. 短信频控与失败次数统计

3.3 与其他表的边界

1. sms_auth_event 负责失败次数统计源数据
2. auth_risk_block 负责统计之后得到的“当前保护状态”
3. auth_audit_log 负责记录“何时触发保护 / 何时解除保护”的历史事实

4. 访问级别

auth_risk_block 固定为 private table。

原因：

1. 原始手机号与原始 IP 都属于敏感安全数据
2. 前端只应该通过已鉴权接口读取当前命中的保护摘要
3. 不能让客户端直接订阅或查询全表

5. 字段设计

字段名	类型	必填	说明
risk_block_id	String	是	主键，建议继续沿用 risk_* 前缀。
scope_type	String	是	保护作用域，枚举固定为 phone、ip。
scope_key	String	是	作用域主体键；phone 时为 E.164 手机号，ip 时为原始 IP。
reason_code	String	是	触发原因码，当前固定为 sms_verify_failures。
expires_at	String	是	当前保护的失效时间，UTC RFC3339。
lifted_at	Option<String>	否	手动解除时间；为 null 表示未手动解除。
created_at	String	是	首次创建该保护记录的时间。
updated_at	String	是	最近一次刷新保护或解除保护的时间。

补充约束：

1. 当前阶段不额外存 user_id，因为 IP 保护天然不是账号主键作用域。
2. 当前阶段不额外存 remaining_seconds，读取时按 expires_at 动态计算。
3. 当前阶段不把标题或 detail 文案入库，继续由 Axum 读取时派生。

6. 作用域设计

6.1 phone

固定规则：

1. scope_key 必须是标准化后的 E.164 手机号
2. 主要用于手机号验证码登录、绑定手机号、换绑手机号
3. 查询时通过当前账号的主手机号命中

6.2 ip

固定规则：

1. scope_key 为请求来源 IP 原文
2. 主要用于防御同一网络环境的异常尝试
3. 查询时通过当前请求上下文中的 IP 命中

7. 活跃态定义

一条 auth_risk_block 只有同时满足以下条件，才视为活跃：

1. lifted_at = null
2. expires_at > now

说明：

1. 超时失效不需要额外更新行状态。
2. 手动解除必须显式写 lifted_at。

8. 写入规则

8.1 创建或刷新保护

触发点：

1. 手机号验证码失败次数达到手机号阈值
2. IP 验证失败次数达到 IP 阈值

写入规则：

1. 先按 (scope_type, scope_key) 查当前活跃保护
2. 若已有活跃保护，则更新：
   • reason_code
   • expires_at
   • updated_at
3. 若不存在活跃保护，则新建一条记录

关键约束：

1. 风控表是“当前态表”，因此允许刷新同一条活跃记录
2. 触发保护的历史事实不在这里重复保留，由 auth_audit_log 承担

8.2 手动解除保护

触发点：

1. POST /api/auth/risk-blocks/phone/lift
2. POST /api/auth/risk-blocks/ip/lift

写入规则：

1. 只更新当前活跃保护
2. 写入：
   • lifted_at = now
   • updated_at = now
3. 不删除行

8.3 自动超时

触发点：

1. 当前时间超过 expires_at

写入规则：

1. 不做同步更新
2. 查询活跃状态时自然排除

9. 唯一约束与索引

9.1 必须具备的唯一约束

1. risk_block_id 主键唯一

9.2 必须具备的查询索引

1. (scope_type, scope_key, expires_at DESC) 作用：查当前活跃保护
2. (scope_type, scope_key, lifted_at, expires_at DESC) 作用：提升当前活跃保护查找效率
3. (expires_at, lifted_at) 作用：后续定时清理或后台巡检

说明：

1. 当前阶段不强行加“同 scope 只有一条记录”的数据库唯一约束，因为历史已失效/已解除记录允许共存。
2. 活跃唯一性由“查询时只取未解除且未过期的最新一条”保证。

10. 对外读取规则

10.1 /api/auth/risk-blocks

固定读取：

1. 当前账号主手机号命中的活跃 phone 保护
2. 当前请求 IP 命中的活跃 ip 保护

固定返回：

1. scopeType
2. title
3. detail
4. expiresAt
5. remainingSeconds

其中：

1. title 读取时按 scope_type 派生
2. detail 读取时按 scope_type + expires_at 派生
3. remainingSeconds 读取时按 expires_at - now 计算

10.2 标题派生规则

1. phone -> 手机号保护中
2. ip -> 当前网络保护中

10.3 detail 派生规则

1. phone -> 该手机号因异常尝试已被临时保护，请约 N 分钟后再试
2. ip -> 当前网络因异常尝试已被临时保护，请约 N 分钟后再试

11. 与当前 Node auth_risk_blocks 的映射关系

Node 列	新字段	迁移规则
id	risk_block_id	原样迁移。
scope_type	scope_type	原样迁移。
scope_key	scope_key	原样迁移。
reason	reason_code	重命名迁移，值当前原样保留。
expires_at	expires_at	原样迁移。
lifted_at	lifted_at	原样迁移。
created_at	created_at	原样迁移。
updated_at	updated_at	原样迁移。

12. reducer / service 落地约束

12.1 module-auth reducer 层

必须至少具备：

1. upsert_auth_risk_block
2. lift_auth_risk_block

12.2 Axum 应用层

固定负责：

1. 根据 sms_auth_event 统计结果决定是否触发保护
2. 计算新的 expires_at
3. 读取保护时派生标题、detail 与剩余秒数
4. 解除保护成功后同步写 auth_audit_log

13. 与 auth_audit_log 的协作规则

13.1 触发保护时

必须：

1. 先写或刷新 auth_risk_block
2. 再写 auth_audit_log

13.2 解除保护时

必须：

1. 先写 lifted_at
2. 再写 risk_unblock_phone 或 risk_unblock_ip 审计

13.3 禁止的反向依赖

禁止：

1. 从 auth_audit_log 回推当前是否仍在保护中

14. 不允许的设计漂移

后续实现时禁止出现以下情况：

1. 为了保存历史，把每次刷新保护都新建一条新活跃记录而不复用现有活跃记录
2. 手动解除时直接删行，导致无法保留解除痕迹
3. 把 remainingSeconds 这类瞬时值入库
4. 把风控表当作审计表使用
5. 把 scope_key 脱敏后再入库，导致无法稳定命中当前作用域

15. 本任务完成定义

当以下条件满足时，设计 auth_risk_block 视为完成：

1. 当前态与历史态边界已经和 auth_audit_log 切开。
2. scope、活跃态、刷新态、解除态的规则已明确。
3. /api/auth/risk-blocks 与 /lift 的读取和写入语义已固定。
4. 后续可以直接按这份文档编码 reducer、view 与 Axum 接口。

16. 依据文件

1. server-node/src/repositories/authRiskBlockRepository.ts
2. server-node/src/auth/authService.ts
3. server-node/src/routes/authRoutes.ts
4. server-node/src/db/migrations.ts
5. packages/shared/src/contracts/auth.ts
6. docs/prd/MY_TAB_SETTINGS_AND_SECURITY_PRD_2026-04-16.md
7. docs/technical/SPACETIMEDB_AUTH_AUDIT_LOG_TABLE_DESIGN_2026-04-21.md
8. docs/technical/SPACETIMEDB_REFRESH_SESSION_TABLE_DESIGN_2026-04-21.md