feat: add authenticated phone binding

docs/refactor/auth-payment-provider-plan.md

@@ -127,6 +127,20 @@ Supabase Auth 可继续作为最终 JWT 用户体系目标；本地重构期先
 
 微信网页 OAuth 和 QQ OAuth 也必须在后端完成 code 换 token、获取 openid/unionid、验错、账号合并和登录事件审计。旧 PocketBase hooks 中的邀请码/销售归属逻辑后续应拆到 `referral` feature，不继续堆在 auth 模块里。
 
+## 手机号绑定/换绑
+
+已实现 `POST /api/auth/phone/bind`。适用场景包括微信/QQ 登录后强制绑定手机号，以及个人中心更换手机号。
+
+流程：
+
+1. 前端调用 `POST /api/auth/sms/send`，`purpose` 必须是 `bind_phone`。
+2. 前端在登录态下调用 `POST /api/auth/phone/bind`，提交 `phone` 和验证码。
+3. 后端校验当前 session/JWT 属于当前租户，不信任 `x-user-id`。
+4. 后端校验手机号未被其它账号占用，成功后更新 `platform_users.phone` 和 `user_identities(provider='phone')`。
+5. 换绑成功会删除当前用户旧手机号 identity，并撤销其它迁移期 `tk_` session；当前 session 保持可用。
+
+前端不能用 `login` 用途验证码绑定手机号；接口会返回 `PHONE_BIND_PURPOSE_REQUIRED`。手机号已被其它账号占用时返回 `PHONE_ALREADY_BOUND`。
+
 ## 支付 Provider
 
 支付不走 Supabase 内置能力。推荐继续扩展 `commerce`：