fix: secure email change recovery flow

docs/api.md

@@ -214,9 +214,11 @@ Content-Type: application/json
 
 响应：
 ```json
-{ "success": true, "data": { "message": "邮箱验证成功" } }
+{ "success": true, "data": { "message": "邮箱验证成功", "session_invalidated": false } }
 ```
 
+同一路径也用于确认邮箱变更。邮箱变更成功时 `session_invalidated=true`，服务端会提升 `token_version`，客户端必须清除旧 JWT 并重新登录。
+
 ### 4.7 请求密码重置
 ```http
 POST /auth/forgot-password
@@ -447,7 +449,9 @@ Authorization: Bearer <token>
     "id": "550e8400-e29b-41d4-a716-446655440000",
     "email": "user@example.com",
     "username": "myusername",
-    "role": "user"
+    "role": "user",
+    "email_verified": true,
+    "pending_email": null
   }
 }
 ```
@@ -696,6 +700,17 @@ Authorization: Bearer <admin_token>
 Content-Type: application/json
 ```
 
+修改用户名只需提交 `username`。修改邮箱必须同时提交当前密码：
+
+```json
+{
+  "email": "new@example.com",
+  "current_password": "current-password"
+}
+```
+
+邮箱验证开启时，新邮箱只写入 `pending_email`，确认前主邮箱、登录邮箱和密码恢复地址均保持不变；确认后服务端原子切换主邮箱并撤销全部旧 JWT 与未使用的密码重置链接。邮箱验证关闭时，当前密码校验通过后立即切换邮箱，响应会返回替换当前会话使用的新 `token`。
+
 ### 11.6 S3 存储端点
 
 ```http