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

日期：`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](./PHONE_AUTH_AXUM_REAL_SMS_PROVIDER_DESIGN_2026-04-22.md)
2. [PHONE_SMS_REAL_PROVIDER_MANUAL_VERIFICATION_RUNBOOK_2026-04-23.md](./PHONE_SMS_REAL_PROVIDER_MANUAL_VERIFICATION_RUNBOOK_2026-04-23.md)