Genarrative/docs/technical/PHONE_SMS_SEND_CODE_OBSERVABILITY_FIX_2026-04-23.md

手机验证码发送链路可观测性补强

日期：2026-04-23

1. 文档目的

这份文档用于冻结 Rust api-server + module-auth + platform-auth 在手机号验证码发送链路上的新增日志口径，解决当前排查成本过高的问题：

1. 前端点击“获取验证码”后，只能看到 /api/auth/phone/send-code 返回了 500。
2. 服务端虽然已有部分失败日志，但关键上下文不完整，仍需要人工反推是哪一层失败。
3. 阿里云真实返回 UNKNOWN、check frequency failed 这类错误时，缺少足够字段判断是本地冷却、上游频控、配置异常还是响应解析问题。

2. 本次补强范围

本次只补强短信发送链路日志，不改前端 UI，不扩散到无关模块：

1. server-rs/crates/api-server
2. server-rs/crates/module-auth
3. server-rs/crates/platform-auth

3. 日志补强目标

新增日志后，排查一次 send-code 失败时，单看日志应能回答：

1. 请求是否真的进入 api-server
2. 当前使用的是 mock 还是 aliyun
3. 手机号和场景是否已经通过服务端规范化
4. 失败发生在本地冷却检查前、阿里云请求发出前、阿里云返回后，还是快照写入阶段
5. 阿里云返回的 HTTP 状态、Code、Message、RequestId 是否可见

4. 新增日志位置

4.1 api-server

在 POST /api/auth/phone/send-code handler 内新增发送前日志，至少输出：

1. request_id
2. operation
3. scene
4. provider
5. phone_input_masked

失败日志继续保留，但补充：

1. provider
2. phone_input_masked

4.2 module-auth

在 PhoneAuthService::send_code 内新增：

1. 规范化手机号后、调用 provider 前的调试日志
2. 本地冷却命中时的日志
3. provider 成功后、写入本地验证码快照前的日志

字段至少包含：

1. scene
2. phone_e164_masked
3. phone_national_masked
4. provider
5. cooldown_seconds
6. expires_in_seconds
7. provider_request_id
8. provider_out_id

4.3 platform-auth

在阿里云 provider 内新增：

1. 发起 SendSmsVerifyCode 前的日志
2. 收到阿里云 HTTP 响应后的日志
3. 错误分类前的日志

字段至少包含：

1. provider=aliyun
2. scene
3. phone_masked
4. endpoint
5. http_status
6. provider_code
7. provider_message
8. provider_request_id
9. provider_out_id

5. 约束

为了避免日志变成新的风险源，本次必须满足：

1. 不打印完整手机号
2. 不打印验证码明文
3. 不打印 AccessKeySecret
4. 不打印完整签名串
5. 只打印排查发送链路需要的最小字段

6. 验收标准

补强后再次请求 /api/auth/phone/send-code，无论成功还是失败，都应满足：

1. api-server 能看到请求进入日志
2. module-auth 能看到 provider 调用前的规范化结果
3. platform-auth 能看到阿里云返回的状态和关键字段
4. 如果失败，日志里可以直接区分：
   • 本地冷却
   • 阿里云配置缺失
   • 阿里云上游失败
   • 阿里云频控或业务拒绝

7. 关联文档

1. PHONE_AUTH_AXUM_REAL_SMS_PROVIDER_DESIGN_2026-04-22.md
2. PHONE_SMS_REAL_PROVIDER_MANUAL_VERIFICATION_RUNBOOK_2026-04-23.md