whale-town-end/docs/api/openapi.yaml

openapi: 3.0.3
info:
  title: Pixel Game Server - Auth API
  description: 像素游戏服务器用户认证API接口文档
  version: 1.0.0
  contact:
    name: API Support
    email: support@example.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://localhost:3000
    description: 开发环境

tags:
  - name: auth
    description: 用户认证相关接口

paths:
  /auth/login:
    post:
      tags:
        - auth
      summary: 用户登录
      description: 支持用户名、邮箱或手机号登录
      operationId: login
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginDto'
            example:
              identifier: testuser
              password: password123
      responses:
        '200':
          description: 登录成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
              example:
                success: true
                data:
                  user:
                    id: "1"
                    username: testuser
                    nickname: 测试用户
                    email: test@example.com
                    phone: "+8613800138000"
                    avatar_url: https://example.com/avatar.jpg
                    role: 1
                    created_at: "2025-12-17T10:00:00.000Z"
                  access_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
                  refresh_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
                  is_new_user: false
                  message: 登录成功
                message: 登录成功
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 用户名或密码错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /auth/register:
    post:
      tags:
        - auth
      summary: 用户注册
      description: 创建新用户账户
      operationId: register
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterDto'
            example:
              username: newuser
              password: password123
              nickname: 新用户
              email: newuser@example.com
              phone: "+8613800138001"
      responses:
        '201':
          description: 注册成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterResponse'
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: 用户名或邮箱已存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /auth/github:
    post:
      tags:
        - auth
      summary: GitHub OAuth登录
      description: 使用GitHub账户登录或注册
      operationId: githubOAuth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GitHubOAuthDto'
            example:
              github_id: "12345678"
              username: octocat
              nickname: The Octocat
              email: octocat@github.com
              avatar_url: https://github.com/images/error/octocat_happy.gif
      responses:
        '200':
          description: GitHub登录成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GitHubOAuthResponse'
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: GitHub认证失败
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /auth/forgot-password:
    post:
      tags:
        - auth
      summary: 发送密码重置验证码
      description: 向用户邮箱或手机发送密码重置验证码
      operationId: forgotPassword
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ForgotPasswordDto'
            example:
              identifier: test@example.com
      responses:
        '200':
          description: 验证码发送成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForgotPasswordResponse'
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 用户不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /auth/reset-password:
    post:
      tags:
        - auth
      summary: 重置密码
      description: 使用验证码重置用户密码
      operationId: resetPassword
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResetPasswordDto'
            example:
              identifier: test@example.com
              verification_code: "123456"
              new_password: newpassword123
      responses:
        '200':
          description: 密码重置成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommonResponse'
        '400':
          description: 请求参数错误或验证码无效
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 用户不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /auth/change-password:
    put:
      tags:
        - auth
      summary: 修改密码
      description: 用户修改自己的密码（需要提供旧密码）
      operationId: changePassword
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangePasswordDto'
            example:
              user_id: "1"
              old_password: oldpassword123
              new_password: newpassword123
      responses:
        '200':
          description: 密码修改成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommonResponse'
        '400':
          description: 请求参数错误或旧密码不正确
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 用户不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  schemas:
    LoginDto:
      type: object
      required:
        - identifier
        - password
      properties:
        identifier:
          type: string
          description: 登录标识符，支持用户名、邮箱或手机号
          minLength: 1
          maxLength: 100
          example: testuser
        password:
          type: string
          description: 用户密码
          minLength: 1
          maxLength: 128
          example: password123

    RegisterDto:
      type: object
      required:
        - username
        - password
        - nickname
      properties:
        username:
          type: string
          description: 用户名，只能包含字母、数字和下划线
          minLength: 1
          maxLength: 50
          pattern: '^[a-zA-Z0-9_]+$'
          example: testuser
        password:
          type: string
          description: 密码，必须包含字母和数字，长度8-128字符
          minLength: 8
          maxLength: 128
          pattern: '^(?=.*[a-zA-Z])(?=.*\d)'
          example: password123
        nickname:
          type: string
          description: 用户昵称
          minLength: 1
          maxLength: 50
          example: 测试用户
        email:
          type: string
          format: email
          description: 邮箱地址（可选）
          example: test@example.com
        phone:
          type: string
          description: 手机号码（可选）
          example: "+8613800138000"

    GitHubOAuthDto:
      type: object
      required:
        - github_id
        - username
        - nickname
      properties:
        github_id:
          type: string
          description: GitHub用户ID
          minLength: 1
          maxLength: 100
          example: "12345678"
        username:
          type: string
          description: GitHub用户名
          minLength: 1
          maxLength: 50
          example: octocat
        nickname:
          type: string
          description: GitHub显示名称
          minLength: 1
          maxLength: 50
          example: The Octocat
        email:
          type: string
          format: email
          description: GitHub邮箱地址（可选）
          example: octocat@github.com
        avatar_url:
          type: string
          description: GitHub头像URL（可选）
          example: https://github.com/images/error/octocat_happy.gif

    ForgotPasswordDto:
      type: object
      required:
        - identifier
      properties:
        identifier:
          type: string
          description: 邮箱或手机号
          minLength: 1
          maxLength: 100
          example: test@example.com

    ResetPasswordDto:
      type: object
      required:
        - identifier
        - verification_code
        - new_password
      properties:
        identifier:
          type: string
          description: 邮箱或手机号
          minLength: 1
          maxLength: 100
          example: test@example.com
        verification_code:
          type: string
          description: 6位数字验证码
          pattern: '^\d{6}$'
          example: "123456"
        new_password:
          type: string
          description: 新密码，必须包含字母和数字，长度8-128字符
          minLength: 8
          maxLength: 128
          pattern: '^(?=.*[a-zA-Z])(?=.*\d)'
          example: newpassword123

    ChangePasswordDto:
      type: object
      required:
        - user_id
        - old_password
        - new_password
      properties:
        user_id:
          type: string
          description: 用户ID（实际应用中应从JWT令牌中获取）
          example: "1"
        old_password:
          type: string
          description: 当前密码
          minLength: 1
          maxLength: 128
          example: oldpassword123
        new_password:
          type: string
          description: 新密码，必须包含字母和数字，长度8-128字符
          minLength: 8
          maxLength: 128
          pattern: '^(?=.*[a-zA-Z])(?=.*\d)'
          example: newpassword123

    UserInfo:
      type: object
      properties:
        id:
          type: string
          description: 用户ID
          example: "1"
        username:
          type: string
          description: 用户名
          example: testuser
        nickname:
          type: string
          description: 用户昵称
          example: 测试用户
        email:
          type: string
          format: email
          description: 邮箱地址
          example: test@example.com
        phone:
          type: string
          description: 手机号码
          example: "+8613800138000"
        avatar_url:
          type: string
          description: 头像URL
          example: https://example.com/avatar.jpg
        role:
          type: integer
          description: 用户角色
          example: 1
        created_at:
          type: string
          format: date-time
          description: 创建时间
          example: "2025-12-17T10:00:00.000Z"

    LoginResponseData:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/UserInfo'
        access_token:
          type: string
          description: 访问令牌
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        refresh_token:
          type: string
          description: 刷新令牌
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        is_new_user:
          type: boolean
          description: 是否为新用户
          example: false
        message:
          type: string
          description: 响应消息
          example: 登录成功

    LoginResponse:
      type: object
      properties:
        success:
          type: boolean
          description: 请求是否成功
          example: true
        data:
          $ref: '#/components/schemas/LoginResponseData'
        message:
          type: string
          description: 响应消息
          example: 登录成功

    RegisterResponse:
      type: object
      properties:
        success:
          type: boolean
          description: 请求是否成功
          example: true
        data:
          $ref: '#/components/schemas/LoginResponseData'
        message:
          type: string
          description: 响应消息
          example: 注册成功

    GitHubOAuthResponse:
      type: object
      properties:
        success:
          type: boolean
          description: 请求是否成功
          example: true
        data:
          $ref: '#/components/schemas/LoginResponseData'
        message:
          type: string
          description: 响应消息
          example: GitHub登录成功

    ForgotPasswordResponseData:
      type: object
      properties:
        verification_code:
          type: string
          description: 验证码（仅用于演示，实际应用中不应返回）
          example: "123456"

    ForgotPasswordResponse:
      type: object
      properties:
        success:
          type: boolean
          description: 请求是否成功
          example: true
        data:
          $ref: '#/components/schemas/ForgotPasswordResponseData'
        message:
          type: string
          description: 响应消息
          example: 验证码已发送，请查收

    CommonResponse:
      type: object
      properties:
        success:
          type: boolean
          description: 请求是否成功
          example: true
        message:
          type: string
          description: 响应消息
          example: 操作成功

    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          description: 请求是否成功
          example: false
        message:
          type: string
          description: 错误消息
          example: 操作失败
        error_code:
          type: string
          description: 错误代码
          example: OPERATION_FAILED