meida/docs/开发任务包/T11-短信登录代码先行.md

T11 · 登录·手机号验证码（代码先行，联调后置）

对应任务：T-P1-12b/12c ｜ 需求：FR-ACC-04（6 位、5 分钟、一次性、失败 5 次作废）、FR-ACC-14（三重频控防刷）、TD-32 ｜ 分支：task/t11-auth-sms ｜ worktree：/home/xsl/meida_backend-t11 先读《README.md（协作规程）》，遵守全部纪律。

1. 目标

手机号验证码登录全链路（发送 → 校验 → 建户 → 双令牌）+ 短信轰炸防护。腾讯云短信签名/模板还在审核（《前置开通清单》§1），因此真实发送后置：SmsSender 走 Protocol 隔离，默认 fake 实现（验证码打日志，dev 可用），腾讯实现写好待凭证。

FR-ACC-04 纪律：与华为通道不得互相依赖——本任务不 import 华为相关任何东西，登录成功路径只依赖 identity 域已有设施。

2. 已就绪的契约（协调提交已提供）

配置（config.py 已加，.env.example 已示例）

sms_provider: str = "fake"                 # SMS_PROVIDER: fake | tencent
tencent_sms_secret_id/key/sdk_app_id/sign_name/template_id: str = ""
sms_code_ttl_seconds: int = 300            # 5 分钟（FR-ACC-04）
sms_code_length: int = 6
sms_verify_max_attempts: int = 5           # 校验失败 5 次作废
sms_resend_cooldown_seconds: int = 60      # 同号 60s 内 1 条
sms_hourly_limit: int = 5                  # 同号 1h ≤5
sms_daily_limit: int = 10                  # 同号 24h ≤10
sms_ip_daily_limit: int = 20               # 同 IP 24h ≤20
sms_device_daily_limit: int = 10           # 同设备 24h ≤10

错误码（errors.py 已加，含 meta）

• SMS_CODE_INVALID = 40110（401「验证码错误」hint「请检查后重试」）
• SMS_CODE_EXPIRED = 40111（401「验证码已过期」hint「请重新获取」）
• SMS_SEND_TOO_FREQUENT = 42910（429「发送太频繁了」hint「请稍后再试」）
• SMS_DAILY_LIMIT = 42911（429「今日发送次数已达上限」hint「明天再试」）
• SMS_PROVIDER_FAILED = 61000（502「短信服务暂时不可用」）

依赖与设施

• tencentcloud-sdk-python-sms 已装（协调提交）。
• 可复用（先读再写）：packages/identity/service.py 的 get_or_create_by_external_identity（provider 用 "phone"）与 issue_session（T4）；packages/identity/schemas.py 的 TokenPairResponse——复用，不重复定义、不修改该文件。
• 路由骨架：apps/api/routers/auth_sms.py 空路由（prefix /auth）已注册 main.py——归你填充。apps/api/routers/auth.py 归 T10，禁碰。

号码存储决策（写进代码注释）

V1 简化：id_user_identity 现有列无 phone_enc，用 union_id = "phone:" + sha256(规范化号码)[:16]（E.164 规范化：去 +86/前导零/空白后哈希）。Redis 与日志中一律不存明文号码——键用 sha256(phone) 前 16 位，日志打码 138****1234（FR-ACC-14 掩码要求）。phone_enc 列的补齐属后续迁移任务，不在本批。

3. 实现要点

允许改动：packages/identity/sms_login.py（新建，全部核心逻辑）、apps/api/routers/auth_sms.py、测试文件。不改 identity/{service,repo,schemas,tokens,huawei}.py。

1. packages/identity/sms_login.py：
   • SmsSender Protocol：async def send_code(phone_masked_key: str, code: str) -> None（收掩码键不收明文——防实现层记日志泄漏）；
   • FakeSmsSender：logger.info("sms_code_issued", masked=..., code=...)（dev 专用，注释写明生产必须切 tencent）；
   • TencentSmsSender：包官方 SDK（SmsClient + SendSmsRequest，参数从 settings 读）；构造失败/响应非 ok → AppError(SMS_PROVIDER_FAILED)；本批不要求真实联调，但代码路径要完整可读；
   • SmsAuthService(redis, sender, *, settings)：
     • request_code(phone, ip, device_id)：号码格式校验（大陆手机号正则 ^1[3-9]\d{9}$，写死并注释 V1 只做大陆）→ 先频控后发送：同号 cooldown/hourly/daily、IP daily、设备 daily 全过才生成 6 位随机码（secrets.randbelow，非 random）→ 存 Redis sms:code:{phone_hash}（值 = sha256(code)，不存明文，TTL 300s）+ 计数器自增 → sender 发送；
     • 频控计数键按自然窗口（cooldown 用 TTL；hourly/daily 用 UTC+8 小时/日期桶，对齐 billing 的时区纪律）；
     • verify(phone, code, ip, device_id)：取码哈希比对（恒定时间比较 hmac.compare_digest）→ 错误则 attempts+1（sms:attempts:{phone_hash}，达 5 删码并返回 40110）→ 成功删码（一次性）→ 由调用方建户；
     • 全部日志打码：masked_phone(phone) -> "138****1234"。
2. 路由（auth_sms.py）：
   • POST /auth/sms/send body {phone, device_id}（ip 从 Request.client.host 取）→ 限流错误码透传；
   • POST /auth/sms/verify body {phone, code, device_id} → 成功后 get_or_create_by_external_identity(provider="phone", union_id=..., register_source="phone") + issue_session → ok(TokenPairResponse(...))；
   • 请求/响应模型定义在 sms_login.py 或新建 packages/identity/sms_schemas.py（二选一，不碰共享 schemas）。
3. 刷量测试（FR-ACC-14 验收原文"脚本化刷量测试证明拦截有效"）：集成测试用循环模拟。

4. 测试要求

• 单测 tests/unit/test_sms_login.py（fakeredis 或自写内存 dict 实现 Protocol 化的 redis 接口——参考 InMemoryCostCounter 的做法，不引新依赖）：
  1. 号码正则（非法格式 400 类错误）；
  2. 频控矩阵：cooldown 内二次 → 42910；1h 第 6 条 → 42910；24h 第 11 条 → 42911；IP 第 21 条 / 设备第 11 条 → 42911；
  3. 验证码：错误 4 次可再试、第 5 次后码作废（40110 且码已删）、过期（TTL 模拟）→ 40111、成功后码即失效（二次 verify 40111）；
  4. 掩码函数；恒定时间比较（不 assert 时长，只 assert 行为）。
• 集成 tests/integration/test_auth_sms.py（新文件，SMS_PROVIDER=fake，从响应前的日志拿不到码——测试钩子：fake sender 把码写进 Redis 测试键或直接用 fixture 替换 sender 为捕获型 fake，不要为测试开后门到生产代码）：
  1. send → verify（fixture 捕获的码）→ 200 双令牌，新 access 可用；
  2. 同号再登录同 user_id（映射唯一）；
  3. 刷量脚本化：连发 11 次，第 11 次 42911；换 IP 维度再验一轮；
  4. 错误码 5 次作废路径。

5. 禁改清单

通用禁改之外：packages/identity/{service,repo,schemas,tokens,huawei}.py、apps/api/routers/auth.py、packages/{kb,rules,retrieval}/**。

6. 验收标准（FR-ACC-04 / FR-ACC-14）

1. 验证码 6 位、5 分钟、一次性、失败 5 次作废——四点各有断言；
2. 三重频控全部生效且有脚本化刷量测试证明；
3. 号码与验证码在日志/Redis 均无明文（掩码 + 哈希）；
4. 与华为通道零耦合（不 import huawei 模块）；
5. 全部检查绿（mypy 范围同 T6 列表）。

7. 提交信息

feat(identity): phone SMS login with triple rate limiting and anti-abuse

SmsSender Protocol（fake/tencent）+ 验证码生命周期（哈希存储/一次性/
5 次作废）+ 号码-IP-设备三重频控 + 掩码纪律（FR-ACC-04/14，TD-32；
真实发送待签名审核）。

偏差说明：<如有写在这里，无则写"无">