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

sms_auth_event 表设计

日期：2026-04-21

1. 文档目的

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

目标是把短信鉴权事件表固定成一张“短信发送与验证码校验的统计源表”，并明确：

1. 哪些短信相关动作要写入事件
2. 哪些动作不应该写进这张表
3. 发送频控、失败次数限制、captcha 触发、风险保护分别依赖什么统计口径
4. 它与 auth_risk_block、auth_audit_log 的边界

2. 当前基线

当前 Node 后端已经存在 sms_auth_events 表，并有稳定的读写链路：

1. POST /api/auth/phone/send-code 在短信发送成功后写入一条 send_code 事件
2. POST /api/auth/phone/login 在验证码校验成功或失败后写入 verify_code 事件
3. POST /api/auth/wechat/bind-phone 在绑定手机号时复用同一套 verify_code 事件
4. POST /api/auth/phone/change 在换绑手机号时复用同一套 verify_code 事件
5. 发送频控、失败次数限制、captcha 触发与风险保护，全部依赖这张表统计

当前 Node sms_auth_events 字段基线：

1. id
2. phone_number
3. scene
4. action
5. success
6. ip
7. user_agent
8. created_at

当前已落地的 scene 基线：

1. login
2. bind_phone
3. change_phone

当前已落地的 action 基线：

1. send_code
2. verify_code

3. 表职责边界

3.1 sms_auth_event 负责

1. 记录短信验证码发送成功事件
2. 记录短信验证码校验成功或失败事件
3. 作为手机号维度与 IP 维度的短信鉴权统计源
4. 为发送频控、失败次数限制、captcha 触发、风险保护提供统一统计基础

3.2 它不负责

1. 保存验证码明文或验证码 hash
2. 保存阿里云短信 provider 的完整原始响应
3. 记录当前风险保护是否仍生效
4. 记录账号安全动作的长期审计历史

3.3 与其他表的边界

1. sms_auth_event 负责“发生过哪些短信发送/校验事件”
2. auth_risk_block 负责“经过统计后当前是否处于保护状态”
3. auth_audit_log 负责“账号维度发生过哪些安全动作”

4. 访问级别

sms_auth_event 固定为 private table。

原因：

1. 原始手机号、原始 IP、原始 UA 都属于敏感安全数据
2. 这张表主要服务于后端风控与统计，不直接对前端暴露
3. 前端不应该直接查询或订阅短信验证码操作明细

5. 字段设计

字段名	类型	必填	说明
sms_event_id	String	是	主键，建议继续沿用 smsev_* 前缀。
phone_e164	String	是	标准化后的 E.164 手机号。
scene	String	是	业务场景，枚举固定为 login、bind_phone、change_phone。
action	String	是	动作类型，枚举固定为 send_code、verify_code。
success	bool	是	当前动作是否成功。
ip	Option<String>	否	请求来源 IP；缺失时为 null。
user_agent	Option<String>	否	请求来源 UA；缺失时为 null。
created_at	String	是	事件发生时间，UTC RFC3339。

补充约束：

1. 当前阶段不存 provider_request_id，因为这张表不是供应商排障日志表。
2. 当前阶段不存 provider_code、provider_message，避免把供应商响应日志职责压进统计源表。
3. 当前阶段不存 user_id，因为验证码发送和校验发生时，场景并不总是已经稳定归属到某个正式账号。

6. 枚举与语义设计

6.1 scene

当前阶段固定只支持：

1. login
2. bind_phone
3. change_phone

解释：

1. login 对应手机号验证码登录
2. bind_phone 对应微信待激活账号绑定手机号
3. change_phone 对应正式账号更换手机号

6.2 action

当前阶段固定只支持：

1. send_code
2. verify_code

解释：

1. send_code 表示验证码已成功发出
2. verify_code 表示一次验证码校验尝试已经结束

6.3 success

固定语义：

1. send_code + success = true 表示供应商确认发送成功
2. verify_code + success = true 表示验证码校验通过
3. verify_code + success = false 表示验证码校验失败或已失效

当前阶段特别约束：

1. send_code + success = false 暂不入表
2. 发送失败继续由应用日志、供应商日志与 tracing 承担排障，不混入当前统计口径

这样做的原因是：

1. 现有发送频控按 action = send_code 的总数统计
2. Node 当前只在发送成功后写事件
3. 若直接把发送失败也写入，会改变当前频控语义

7. 统计口径设计

7.1 发送频控

固定统计来源：

1. 按手机号统计 action = send_code 的事件数
2. 按 IP 统计 action = send_code 的事件数

当前 Node 兼容窗口：

1. 单手机号：过去 1 天
2. 单 IP：过去 1 小时

7.2 验证失败次数限制

固定统计来源：

1. 按手机号统计 action = verify_code AND success = false
2. 按 IP 统计 action = verify_code AND success = false

当前 Node 兼容窗口：

1. 单手机号：过去 1 小时
2. 单 IP：过去 1 小时

7.3 captcha 触发

固定统计来源：

1. 按手机号统计 verify_code 失败次数
2. 按 IP 统计 verify_code 失败次数

说明：

1. captcha challenge 自身不写进 sms_auth_event
2. captcha_required 审计事件继续写进 auth_audit_log

7.4 风险保护触发

固定统计来源：

1. 按手机号统计 verify_code 失败次数
2. 按 IP 统计 verify_code 失败次数

说明：

1. 风险保护命中后真正的当前态写进 auth_risk_block
2. sms_auth_event 只提供统计基础，不直接承载保护状态

8. 写入规则

8.1 POST /api/auth/phone/send-code

固定流程：

1. 先检查当前手机号 / 当前 IP 是否存在活跃 auth_risk_block
2. 再根据 sms_auth_event 统计发送频控
3. 再根据 sms_auth_event 统计决定是否需要 captcha
4. 短信 provider 返回发送成功后，写入一条：
   • scene = 当前请求场景
   • action = send_code
   • success = true

8.2 POST /api/auth/phone/login

固定流程：

1. 先检查当前手机号 / 当前 IP 是否存在活跃 auth_risk_block
2. 再根据 sms_auth_event 统计失败次数限制
3. 校验成功时写入：
   • scene = login
   • action = verify_code
   • success = true
4. 校验失败时写入：
   • scene = login
   • action = verify_code
   • success = false
5. 校验失败写入完成后，再按统计结果决定是否触发 auth_risk_block

8.3 POST /api/auth/wechat/bind-phone

固定流程：

1. 与手机号登录复用同一套校验前检查
2. 校验成功写入 bind_phone + verify_code + success = true
3. 校验失败写入 bind_phone + verify_code + success = false
4. 校验失败后再决定是否触发 auth_risk_block

8.4 POST /api/auth/phone/change

固定流程：

1. 与手机号登录复用同一套校验前检查
2. 校验成功写入 change_phone + verify_code + success = true
3. 校验失败写入 change_phone + verify_code + success = false
4. 校验失败后再决定是否触发 auth_risk_block

9. 查询索引与统计要求

9.1 必须具备的唯一约束

1. sms_event_id 主键唯一

9.2 必须具备的查询索引

1. (phone_e164, action, created_at DESC) 作用：支撑按手机号统计发送次数与失败次数
2. (ip, action, created_at DESC) 作用：支撑按 IP 统计发送次数与失败次数
3. (phone_e164, action, success, created_at DESC) 作用：支撑按手机号统计 verify_code 失败窗口
4. (ip, action, success, created_at DESC) 作用：支撑按 IP 统计 verify_code 失败窗口

说明：

1. 当前阶段不强求单独按 scene 建主索引，因为已有统计主要按手机号/IP 与动作窗口展开。
2. scene 继续作为事件上下文字段保留，便于后续如果要细分某一场景的频控，再追加索引。

10. 读取规则

当前阶段 sms_auth_event 不直接对外暴露 DTO。

它只支撑后端内部这几类聚合查询：

1. count_since_by_phone(phone_e164, action, success?, since)
2. count_since_by_ip(ip, action, success?, since)

读取约束：

1. ip = null 时，按 IP 统计固定返回 0
2. 统计窗口由 Axum 应用层提供，不把“过去 1 小时”“过去 1 天”写死进表层
3. 表层只提供原子计数，不在表层拼装“是否需要 captcha / 是否需要封禁”的业务判断

11. 与其他鉴权表的协作规则

11.1 与 auth_risk_block

固定规则：

1. sms_auth_event 先累积失败事实
2. Axum 根据失败统计决定是否写入或刷新 auth_risk_block
3. 不能直接从 auth_risk_block 反推历史失败次数

11.2 与 auth_audit_log

固定规则：

1. sms_auth_event 不承担安全操作审计展示职责
2. captcha_required、risk_block_phone、risk_block_ip 等用户可见安全事件，继续写进 auth_audit_log
3. 不允许为了省表而把 sms_auth_event 直接拿去充当账号操作记录

12. 与当前 Node sms_auth_events 的映射关系

Node 列	新字段	迁移规则
id	sms_event_id	原样迁移。
phone_number	phone_e164	重命名迁移，值原样保留。
scene	scene	原样迁移。
action	action	原样迁移。
success	success	原样迁移。
ip	ip	原样迁移。
user_agent	user_agent	原样迁移。
created_at	created_at	原样迁移。

13. reducer / service 落地约束

13.1 module-auth reducer 层

必须至少具备：

1. append_sms_auth_event

说明：

1. 这是一张追加型统计源表，不做就地更新。
2. 后续若要做归档或清理，再单独增加 maintenance reducer 或离线清理任务。

13.2 Axum 应用层

固定负责：

1. 标准化手机号为 E.164
2. 组织 scene、action、success
3. 在正确的时机写入事件
4. 基于统计结果决定是否触发 captcha 与 auth_risk_block

14. 不允许的设计漂移

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

1. 把验证码明文、验证码 hash 写进 sms_auth_event
2. 把阿里云 provider 的完整响应 JSON 直接写进 sms_auth_event
3. 把当前是否被保护的状态写进 sms_auth_event
4. 发送失败也无条件入表，却继续沿用当前“按 send_code 总量限流”的统计口径
5. 为了展示账号安全记录，直接把 sms_auth_event 暴露给前端

15. 本任务完成定义

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

1. 发送与校验事件的写入范围已经固定。
2. 当前发送频控、失败限制、captcha 触发与风险保护的统计口径已经固定。
3. 已和 auth_risk_block、auth_audit_log 明确切开职责。
4. 后续可以直接按这份文档编码 reducer、计数查询与 Axum 应用层判断逻辑。

16. 依据文件

1. server-node/src/repositories/smsAuthEventRepository.ts
2. server-node/src/auth/authService.ts
3. server-node/src/services/smsVerificationService.ts
4. server-node/src/routes/authRoutes.ts
5. server-node/src/db/migrations.ts
6. packages/shared/src/contracts/auth.ts
7. docs/prd/ACCOUNT_SYSTEM_AND_LOGIN_ENTRY_PRD_2026-04-09.md
8. docs/prd/MY_TAB_SETTINGS_AND_SECURITY_PRD_2026-04-16.md
9. docs/technical/SPACETIMEDB_AUTH_AUDIT_LOG_TABLE_DESIGN_2026-04-21.md
10. docs/technical/SPACETIMEDB_AUTH_RISK_BLOCK_TABLE_DESIGN_2026-04-21.md