From 25f262c1acda0eb266a337d84279293dc217be3d Mon Sep 17 00:00:00 2001
From: wood chen <wood@czl.net>
Date: Mon, 17 Feb 2025 05:20:27 +0800
Subject: [PATCH] docs: Update OAuth 2.0 documentation with detailed error
 codes and security guidelines

---
 src/app/()/page.tsx | 23 +++++++++++++++++------
 1 file changed, 17 insertions(+), 6 deletions(-)

diff --git a/src/app/()/page.tsx b/src/app/()/page.tsx
index 5aabf76..a78c55f 100644
--- a/src/app/()/page.tsx
+++ b/src/app/()/page.tsx
@@ -127,9 +127,9 @@ const response = await fetch('https://connect.q58.club/api/oauth/access_token',
 
 // 返回数据示例:
 {
-  "access_token": "at_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", // 访问令牌
+  "access_token": "at_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", // 访问令牌，以 at_ 开头
   "token_type": "bearer",   // 令牌类型
-  "expires_in": 604800      // 令牌有效期(秒)
+  "expires_in": 604800      // 令牌有效期(秒)，默认7天
 }
 
 // 3. 获取用户信息
@@ -145,7 +145,7 @@ const userInfo = await fetch('https://connect.q58.club/api/oauth/user', {
   "email": "user@example.com",   // 用户邮箱
   "username": "username",        // 用户名
   "name": "用户昵称",            // 用户昵称
-  "avatarUrl": "https://...",   // 头像URL
+  "avatar_url": "https://...",   // 头像URL
   "admin": false,               // 是否是管理员
   "moderator": false,           // 是否是版主
   "groups": ["group1", "group2"] // 用户所属的论坛用户组
@@ -161,12 +161,23 @@ const userInfo = await fetch('https://connect.q58.club/api/oauth/user', {
                     <li>admin - 获取用户的管理权限状态</li>
                   </ul>
                   <p className="mt-4">
-                    <strong>安全建议：</strong>
+                    <strong>安全说明：</strong>
                   </p>
                   <ul className="list-inside list-disc space-y-1">
-                    <li>请务必在服务器端验证 access_token 的有效性</li>
+                    <li>授权码(code)是一次性的，使用后立即失效</li>
+                    <li>授权码有效期为10分钟</li>
+                    <li>access_token 有效期为7天，请在过期前重新获取</li>
+                    <li>请确保回调地址(redirect_uri)与应用注册时完全一致</li>
                     <li>建议使用 HTTPS 确保数据传输安全</li>
-                    <li>请妥善保管 client_secret，不要泄露给客户端</li>
+                  </ul>
+                  <p className="mt-4">
+                    <strong>错误说明：</strong>
+                  </p>
+                  <ul className="list-inside list-disc space-y-1">
+                    <li>400 Invalid code params - 授权码参数缺失</li>
+                    <li>400 Invalid code credentials - 授权码无效或已过期</li>
+                    <li>400 Invalid redirect uri - 回调地址不匹配</li>
+                    <li>401 Invalid access token - 访问令牌无效或已过期</li>
                   </ul>
                 </div>
               </div>