chore: checkpoint local workspace changes

docs/technical/PHONE_SMS_SEND_CODE_OBSERVABILITY_FIX_2026-04-23.md

@@ -0,0 +1,113 @@
+# 手机验证码发送链路可观测性补强
+
+日期：`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)