feat: 更新json

docs/openapi.json

@@ -3,7 +3,7 @@
   "info": {
     "title": "WebGame 后端接口文档",
     "version": "1.0.0",
-    "description": "WebGame 游戏后端 REST API 接口文档"
+    "description": "WebGame 游戏后端 REST API 接口文档。认证采用双 Token 机制：Access Token（30 分钟有效，每次请求携带） + Refresh Token（30 天有效，仅用于刷新 Access Token）。"
   },
   "servers": [
     {
@@ -12,15 +12,15 @@
     }
   ],
   "tags": [
-    { "name": "账号", "description": "账号相关接口（登录、注册，无需认证）" },
+    { "name": "账号", "description": "账号相关接口（登录、注册、刷新令牌，无需认证）" },
-    { "name": "用户", "description": "用户相关接口（需登录认证）" }
+    { "name": "用户", "description": "用户相关接口（需 Access Token 认证）" }
   ],
   "paths": {
     "/account/login": {
       "post": {
         "tags": ["账号"],
         "summary": "用户登录",
-        "description": "使用用户名和密码进行登录认证，成功返回 Sa-Token 令牌。该接口无需登录即可调用。",
+        "description": "使用用户名和密码进行登录认证，成功返回 Access Token 和 Refresh Token。该接口无需登录即可调用。",
         "operationId": "login",
         "security": [],
         "requestBody": {
@@ -37,7 +37,7 @@
         },
         "responses": {
           "200": {
-            "description": "登录成功，返回 token",
+            "description": "登录成功，返回双 Token",
             "content": {
               "application/json": {
                 "schema": {
@@ -55,7 +55,8 @@
                   "code": 0,
                   "message": "success",
                   "data": {
-                    "token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+                    "accessToken": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+                    "refreshToken": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
                   }
                 }
               }
@@ -70,7 +71,7 @@
       "post": {
         "tags": ["账号"],
         "summary": "用户注册",
-        "description": "注册新账号。用户名长度 3-32 位，密码长度 6-64 位。注册成功后自动登录并返回 token。该接口无需登录即可调用。",
+        "description": "注册新账号。用户名长度 3-32 位，密码长度 6-64 位。注册成功后自动登录并返回双 Token。该接口无需登录即可调用。",
         "operationId": "register",
         "security": [],
         "requestBody": {
@@ -87,7 +88,7 @@
         },
         "responses": {
           "200": {
-            "description": "注册成功，自动登录返回 token",
+            "description": "注册成功，自动登录返回双 Token",
             "content": {
               "application/json": {
                 "schema": {
@@ -105,7 +106,58 @@
                   "code": 0,
                   "message": "success",
                   "data": {
-                    "token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+                    "accessToken": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+                    "refreshToken": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
+                  }
+                }
+              }
+            }
+          },
+          "400": { "$ref": "#/components/responses/BadRequest" },
+          "500": { "$ref": "#/components/responses/InternalError" }
+        }
+      }
+    },
+    "/account/refresh": {
+      "post": {
+        "tags": ["账号"],
+        "summary": "刷新 Access Token",
+        "description": "当 Access Token 过期（30 分钟）后，使用 Refresh Token 换取新的 Access Token。Refresh Token 保持不变，仅在满 30 天或重新登录时更新。该接口无需登录即可调用。",
+        "operationId": "refresh",
+        "security": [],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": { "$ref": "#/components/schemas/RefreshTokenRequest" },
+              "example": {
+                "refreshToken": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "刷新成功，返回新的 Access Token 和原 Refresh Token",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    { "$ref": "#/components/schemas/ApiResponse" },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": { "$ref": "#/components/schemas/LoginResponse" }
+                      }
+                    }
+                  ]
+                },
+                "example": {
+                  "code": 0,
+                  "message": "success",
+                  "data": {
+                    "accessToken": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
+                    "refreshToken": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
                   }
                 }
               }
@@ -120,7 +172,7 @@
       "get": {
         "tags": ["用户"],
         "summary": "获取当前登录用户信息",
-        "description": "根据请求头中的 saToken 获取当前登录用户的详细信息，包括昵称、头像、个性签名、年龄、性别、生日。需登录认证。",
+        "description": "根据请求头中的 saToken（Access Token）获取当前登录用户的详细信息，包括昵称、头像、个性签名、年龄、性别、生日。需登录认证。",
         "operationId": "getUserInfo",
         "security": [{ "saToken": [] }],
         "responses": {
@@ -166,7 +218,7 @@
         "type": "apiKey",
         "in": "header",
         "name": "saToken",
-        "description": "Sa-Token 认证令牌。登录/注册成功后返回的 token 值，在后续请求的 Header 中携带。"
+        "description": "Access Token（登录/注册/刷新接口返回的 accessToken 值）。有效期 30 分钟，过期后使用 /account/refresh 接口获取新 Token。"
       }
     },
     "schemas": {
@@ -232,15 +284,33 @@
           }
         }
       },
+      "RefreshTokenRequest": {
+        "type": "object",
+        "description": "刷新令牌请求体",
+        "required": ["refreshToken"],
+        "properties": {
+          "refreshToken": {
+            "type": "string",
+            "description": "刷新令牌，登录/注册时返回的 refreshToken 值，不能为空",
+            "minLength": 1,
+            "example": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
+          }
+        }
+      },
       "LoginResponse": {
         "type": "object",
-        "description": "登录或注册成功时返回的认证令牌",
+        "description": "登录、注册或刷新令牌成功时返回的认证令牌对",
-        "required": ["token"],
+        "required": ["accessToken", "refreshToken"],
         "properties": {
-          "token": {
+          "accessToken": {
             "type": "string",
-            "description": "Sa-Token 认证令牌（UUID 格式）。后续请求需在 Header 中通过 saToken 字段携带此值。",
+            "description": "Access Token（UUID 格式），有效期 30 分钟。后续请求需在 Header 中通过 saToken 字段携带此值。过期后使用 /account/refresh 接口刷新。",
             "example": "12345678-1234-1234-1234-123456789abc"
+          },
+          "refreshToken": {
+            "type": "string",
+            "description": "Refresh Token（64 位十六进制随机字符串），有效期 30 天。仅用于 /account/refresh 接口换取新的 Access Token。刷新时不变，重新登录时替换。",
+            "example": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
           }
         }
       },
@@ -348,6 +418,22 @@
                   "data": null
                 }
               },
+              "refreshTokenInvalid": {
+                "summary": "刷新令牌无效或已过期",
+                "value": {
+                  "code": 1003,
+                  "message": "刷新令牌无效或已过期",
+                  "data": null
+                }
+              },
+              "refreshTokenMissing": {
+                "summary": "缺少刷新令牌",
+                "value": {
+                  "code": 1004,
+                  "message": "缺少刷新令牌",
+                  "data": null
+                }
+              },
               "userNotFound": {
                 "summary": "用户不存在",
                 "value": {
@@ -361,7 +447,7 @@
         }
       },
       "Unauthorized": {
-        "description": "未登录或 token 无效（HTTP 200 但 code=401）",
+        "description": "未登录或 Access Token 无效/过期（HTTP 200 但 code=401）",
         "content": {
           "application/json": {
             "schema": { "$ref": "#/components/schemas/ErrorResponse" },
@@ -450,6 +536,16 @@
             "message": "用户名或密码错误",
             "description": "登录时用户名或密码不匹配"
           },
+          "REFRESH_TOKEN_INVALID": {
+            "code": 1003,
+            "message": "刷新令牌无效或已过期",
+            "description": "Refresh Token 不存在或已过期（30 天），需重新登录"
+          },
+          "REFRESH_TOKEN_MISSING": {
+            "code": 1004,
+            "message": "缺少刷新令牌",
+            "description": "请求体中的 refreshToken 字段为空"
+          },
           "USER_NOT_FOUND": {
             "code": 2001,
             "message": "用户不存在",