api-specification.yaml

openapi: 3.0.3
info:
  title: 한국 여행 가이드 API
  description: OAuth 기반 인증, AI 채팅, Guest-Guide 매칭을 지원하는 여행 가이드 서비스 (MVP)
  version: 2.0.0
  contact:
    name: 개발팀
    email: dev@example.com

servers:
  - url: http://localhost:8080
    description: 로컬 개발 서버

tags:
  - name: auth
    description: 인증 및 권한 관리
  - name: users
    description: 사용자 정보 관리
  - name: aichat
    description: AI 채팅 도메인
  - name: userchat
    description: 유저 채팅 도메인 (Guest-Guide)
  - name: rate
    description: 평가 도메인 (AI 세션 및 가이드 평가)

components:
  schemas:
    ApiResponse:
      type: object
      properties:
        msg:
          type: string
          description: 응답 메시지
        data:
          type: object
          description: 응답 데이터
          nullable: true

    # Auth Schemas
    UserRole:
      type: string
      enum: [USER, ADMIN, GUIDE, PENDING]
      description: 사용자 역할

    UserRoleUpdateRequest:
      type: object
      required:
        - role
      properties:
        role:
          $ref: "#/components/schemas/UserRole"

    LoginResponse:
      type: object
      properties:
        accessToken:
          type: string
          description: JWT Access Token

    AccessTokenResponse:
      type: object
      properties:
        accessToken:
          type: string
          description: 새로 발급된 JWT Access Token

    # User Schemas
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: 사용자 고유 식별자
        email:
          type: string
          format: email
          description: 사용자 이메일
        nickname:
          type: string
          description: 사용자 닉네임
        profileImageUrl:
          type: string
          format: uri
          nullable: true
          description: 프로필 이미지 URL
        role:
          $ref: "#/components/schemas/UserRole"
        location:
          type: string
          nullable: true
          description: 가이드 활동 지역 (GUIDE만)
        description:
          type: string
          nullable: true
          description: 사용자 소개글
        createdAt:
          type: string
          format: date-time
          description: 가입 일시
        lastLoginAt:
          type: string
          format: date-time
          description: 최종 로그인 일시

    UserResponse:
      type: object
      properties:
        id:
          type: integer
          format: int64
        email:
          type: string
          format: email
        nickname:
          type: string
        profileImageUrl:
          type: string
          format: uri
          nullable: true
        role:
          $ref: "#/components/schemas/UserRole"

    UserUpdateRequest:
      type: object
      properties:
        nickname:
          type: string
          nullable: true
        profileImageUrl:
          type: string
          format: uri
          nullable: true

    # AI Chat Domain Schemas
    SessionsResponse:
      type: object
      properties:
        sessionId:
          type: integer
          format: int64
          description: 세션 고유 식별자
        sessionTitle:
          type: string
          description: 세션 제목

    SessionMessagesResponse:
      type: object
      properties:
        content:
          type: string
          description: 메시지 내용
        senderType:
          type: string
          enum: [USER, AI]
          description: 발신자 유형

    AiChatResponse:
      type: object
      properties:
        userMessage:
          type: string
          description: 사용자 메시지 내용
        aiMessage:
          type: string
          description: AI 응답 메시지 내용

    UpdateSessionTitleResponse:
      type: object
      properties:
        newTitle:
          type: string
          description: 수정된 세션 제목

    # User Chat Domain Schemas
    ChatRoomResponse:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: 채팅방 고유 식별자
        title:
          type: string
          description: 채팅방 내부 식별용 기본 제목 (Guide-사용자 ID 조합)
        displayTitle:
          type: string
          description: 요청자 기준 상대 닉네임을 포함한 표현용 제목 (예: "홍길동님과의 채팅")
        guideId:
          type: integer
          format: int64
          description: 가이드 ID
        userId:
          type: integer
          format: int64
          description: 게스트 ID
        updatedAt:
          type: string
          format: date-time
          description: 최근 메시지 기준 갱신 시각 (Asia/Seoul)
        lastMessageId:
          type: integer
          format: int64
          nullable: true
          description: 마지막 메시지 ID (없다면 null)

    ChatRoomStartRequest:
      type: object
      required:
        - guideId
        - userId
      properties:
        guideId:
          type: integer
          format: int64
          description: 대화를 시작할 가이드 ID
        userId:
          type: integer
          format: int64
          description: 채팅을 요청한 사용자 ID

    ChatMessageResponse:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: 메시지 고유 식별자
        roomId:
          type: integer
          format: int64
          description: 채팅방 ID
        senderId:
          type: integer
          format: int64
          description: 발신자 ID
        content:
          type: string
          description: 메시지 내용
        createdAt:
          type: string
          format: date-time
          description: 메시지 전송 시간 (Asia/Seoul)

    ChatMessageSendRequest:
      type: object
      required:
        - content
      properties:
        content:
          type: string
          description: 전송할 메시지 내용

    # Rating Schemas
    RateTargetType:
      type: string
      enum: [AI_SESSION, GUIDE]
      description: 평가 대상 타입

    Rate:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: 평가 고유 식별자
        user:
          $ref: "#/components/schemas/UserResponse"
          description: 평가를 남긴 사용자
        targetType:
          $ref: "#/components/schemas/RateTargetType"
        targetId:
          type: integer
          format: int64
          description: 평가 대상의 ID
        rating:
          type: integer
          minimum: 1
          maximum: 5
          description: 평점 1-5
        comment:
          type: string
          nullable: true
          description: 평가 코멘트
        createdAt:
          type: string
          format: date-time
          description: 평가 일시

    RateRequest:
      type: object
      required:
        - rating
      properties:
        rating:
          type: integer
          minimum: 1
          maximum: 5
        comment:
          type: string
          nullable: true

    RateResponse:
      type: object
      properties:
        id:
          type: integer
          format: int64
        raterNickname:
          type: string
        rating:
          type: integer
        comment:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time

    GuideRatingSummaryResponse:
      type: object
      properties:
        averageRating:
          type: number
          format: double
        totalRatings:
          type: integer
        ratings:
          type: array
          items:
            $ref: "#/components/schemas/RateResponse"

  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - BearerAuth: []

paths:
  # ===================
  # Auth APIs
  # ===================
  /api/auth/role:
    post:
      tags:
        - auth
      summary: 신규 사용자 역할 선택
      description: OAuth 최초 로그인 후, 사용자의 역할을 선택하고 정식으로 가입을 완료합니다.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserRoleUpdateRequest"
      responses:
        "200":
          description: 역할 선택 및 로그인 성공
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        $ref: "#/components/schemas/LoginResponse"
        "401":
          description: 인증 실패 (유효하지 않은 registerToken)

  /api/auth/logout:
    post:
      tags:
        - auth
      summary: 로그아웃
      description: 현재 사용자의 Access Token을 만료시켜 로그아웃 처리합니다.
      security:
        - BearerAuth: []
      responses:
        "200":
          description: 로그아웃 성공
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /api/auth/refresh:
    post:
      tags:
        - auth
      summary: Access Token 재발급
      description: 쿠키에 담긴 Refresh Token을 사용하여 만료된 Access Token을 재발급합니다.
      security: []
      responses:
        "200":
          description: 토큰 재발급 성공
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        $ref: "#/components/schemas/AccessTokenResponse"
        "401":
          description: 유효하지 않은 Refresh Token

  # ===================
  # User APIs
  # ===================
  /api/users/me:
    get:
      tags:
        - users
      summary: 내 정보 조회
      description: 현재 로그인된 사용자의 프로필 정보를 조회합니다.
      security:
        - BearerAuth: []
      responses:
        "200":
          description: 내 정보 조회 성공
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        $ref: "#/components/schemas/UserResponse"
    patch:
      tags:
        - users
      summary: 내 프로필 수정
      description: 현재 로그인된 사용자의 프로필 정보(닉네임, 프로필 이미지)를 수정합니다.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserUpdateRequest"
      responses:
        "200":
          description: 프로필 수정 성공
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        $ref: "#/components/schemas/UserResponse"
    delete:
      tags:
        - users
      summary: 회원 탈퇴
      description: 현재 로그인된 사용자 계정을 영구적으로 삭제합니다.
      security:
        - BearerAuth: []
      responses:
        "200":
          description: 회원 탈퇴 성공
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  # ===================
  # AI Chat Domain APIs
  # ===================
  /api/aichat/sessions:
    get:
      tags:
        - aichat
      summary: AI 채팅 세션 목록 조회
      description: 사용자의 AI 채팅 세션 목록을 최신순으로 조회
      parameters:
        - name: userId
          in: query
          required: true
          schema:
            type: integer
            format: int64
          description: 사용자 ID
      responses:
        "200":
          description: 세션 목록 조회 성공
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/SessionsResponse"

    post:
      tags:
        - aichat
      summary: 새 AI 채팅 세션 생성
      description: 새로운 AI 채팅 세션을 생성합니다
      parameters:
        - name: userId
          in: query
          required: true
          schema:
            type: integer
            format: int64
          description: 사용자 ID
      responses:
        "200":
          description: 세션 생성 성공
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        $ref: "#/components/schemas/SessionsResponse"

  /api/aichat/sessions/{sessionId}:
    delete:
      tags:
        - aichat
      summary: AI 채팅 세션 삭제
      description: AI 채팅 세션과 모든 메시지를 영구적으로 삭제합니다
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: AI 채팅 세션 ID
        - name: userId
          in: query
          required: true
          schema:
            type: integer
            format: int64
          description: 사용자 ID
      responses:
        "200":
          description: 세션 삭제 완료
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "404":
          description: 세션을 찾을 수 없음

  /api/aichat/sessions/{sessionId}/messages:
    get:
      tags:
        - aichat
      summary: AI 채팅 메시지 조회
      description: 특정 AI 채팅 세션의 메시지 이력을 시간순으로 조회
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: AI 채팅 세션 ID
        - name: userId
          in: query
          required: true
          schema:
            type: integer
            format: int64
          description: 사용자 ID
      responses:
        "200":
          description: 채팅 기록 조회 성공
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/SessionMessagesResponse"

    post:
      tags:
        - aichat
      summary: AI에게 메시지 전송
      description: AI 채팅 세션에 메시지를 전송하고 AI 응답을 받습니다
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: AI 채팅 세션 ID
        - name: userId
          in: query
          required: true
          schema:
            type: integer
            format: int64
          description: 사용자 ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - message
              properties:
                message:
                  type: string
                  description: 사용자 메시지 내용
      responses:
        "200":
          description: 메시지 전송 및 AI 응답 완료
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        $ref: "#/components/schemas/AiChatResponse"

  /api/aichat/sessions/{sessionId}/title:
    patch:
      tags:
        - aichat
      summary: AI 채팅 세션 제목 수정
      description: AI 채팅 세션의 제목을 사용자가 직접 수정합니다
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: AI 채팅 세션 ID
        - name: userId
          in: query
          required: true
          schema:
            type: integer
            format: int64
          description: 사용자 ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - newTitle
              properties:
                newTitle:
                  type: string
                  maxLength: 100
                  description: 새로운 세션 제목
      responses:
        "200":
          description: 제목 수정 성공
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        $ref: "#/components/schemas/UpdateSessionTitleResponse"
        "404":
          description: 세션을 찾을 수 없음
        "403":
          description: 권한 없음

  # ===================
  # User Chat Domain APIs
  # ===================
  /api/userchat/rooms:
    get:
      tags:
        - userchat
      summary: 내 채팅방 목록 조회
      description: 인증된 사용자가 참여한 채팅방 목록을 최근 업데이트 순으로 돌려줍니다.
      security:
        - BearerAuth: []
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            format: int32
            default: 20
            minimum: 1
            maximum: 100
          description: 응답에 포함할 최대 채팅방 수 (기본 20)
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: "커서 기반 페이지네이션 포인터. '{updatedAt ISO-8601}|{roomId}' 형식이며 이전 응답의 nextCursor를 그대로 전달합니다."
      responses:
        "200":
          description: 채팅방 목록 조회 성공
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          rooms:
                            type: array
                            items:
                              $ref: "#/components/schemas/ChatRoomResponse"
                          nextCursor:
                            type: string
                            nullable: true
                            description: 다음 페이지 요청 시 사용할 커서 (없으면 null)

  /api/userchat/rooms/start:
    post:
      tags:
        - userchat
      summary: 1:1 채팅방 생성 또는 재사용
      description: 가이드-게스트 조합으로 채팅방을 생성하며, 기존 방이 있으면 재사용합니다.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ChatRoomStartRequest"
      responses:
        "200":
          description: 채팅방 생성 또는 기존 방 반환
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        $ref: "#/components/schemas/ChatRoomResponse"
        "403":
          description: 인증되지 않은 사용자 또는 참여자가 아닙니다.

  /api/userchat/rooms/{roomId}:
    get:
      tags:
        - userchat
      summary: 채팅방 단건 조회
      description: 채팅방 참여자만 상세 정보를 조회할 수 있습니다.
      security:
        - BearerAuth: []
      parameters:
        - name: roomId
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: 채팅방 ID
      responses:
        "200":
          description: 채팅방 조회 성공
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        $ref: "#/components/schemas/ChatRoomResponse"
        "403":
          description: 채팅방 참여자가 아닙니다.
        "404":
          description: 채팅방을 찾을 수 없음

    delete:
      tags:
        - userchat
      summary: 채팅방 삭제
      description: 채팅방과 모든 메시지를 삭제합니다 (생성자만 가능).
      security:
        - BearerAuth: []
      parameters:
        - name: roomId
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: 채팅방 ID
      responses:
        "200":
          description: 채팅방 삭제 완료
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "403":
          description: 채팅방 생성자가 아닙니다.
        "404":
          description: 채팅방을 찾을 수 없음

  /api/userchat/rooms/{roomId}/messages:
    get:
      tags:
        - userchat
      summary: 채팅방 메시지 조회
      description: 특정 채팅방의 메시지를 시간순으로 가져옵니다.
      security:
        - BearerAuth: []
      parameters:
        - name: roomId
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: 채팅방 ID
        - name: after
          in: query
          required: false
          schema:
            type: integer
            format: int64
          description: 해당 메시지 ID 이후의 메시지만 조회
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            format: int32
            default: 50
            minimum: 1
            maximum: 200
          description: 최대 조회 건수 (기본 50)
      responses:
        "200":
          description: 메시지 조회 성공
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/ChatMessageResponse"
        "403":
          description: 채팅방 참여자가 아닙니다.
        "404":
          description: 채팅방을 찾을 수 없음

    post:
      tags:
        - userchat
      summary: 채팅방에 메시지 전송
      description: 채팅방에 새 메시지를 전송합니다.
      security:
        - BearerAuth: []
      parameters:
        - name: roomId
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: 채팅방 ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ChatMessageSendRequest"
      responses:
        "201":
          description: 메시지 전송 성공
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        $ref: "#/components/schemas/ChatMessageResponse"
        "403":
          description: 채팅방 참여자가 아닙니다.
        "404":
          description: 채팅방을 찾을 수 없음

  # ===================
  # Rate Domain APIs
  # ===================
  /api/rate/guides/{guideId}:
    put:
      tags:
        - rate
      summary: 가이드 평가 생성/수정
      description: 특정 가이드에 대한 평점을 생성하거나 수정합니다. (USER만 가능)
      security:
        - BearerAuth: []
      parameters:
        - name: guideId
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: 평가할 가이드의 ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RateRequest"
      responses:
        "200":
          description: 평가 성공
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        $ref: "#/components/schemas/RateResponse"

  /api/rate/aichat/sessions/{sessionId}:
    put:
      tags:
        - rate
      summary: AI 채팅 세션 평가 생성/수정
      description: 특정 AI 채팅 세션에 대한 평가를 생성하거나 수정합니다. (세션 소유자만 가능)
      security:
        - BearerAuth: []
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: integer
            format: int64
          description: 평가할 AI 채팅 세션의 ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RateRequest"
      responses:
        "200":
          description: 평가 성공
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        $ref: "#/components/schemas/RateResponse"

  /api/rate/guides/my:
    get:
      tags:
        - rate
      summary: 내가 받은 가이드 평가 조회
      description: 현재 로그인한 가이드가 자신이 받은 모든 평가 요약과 목록을 조회합니다. (GUIDE만 가능)
      security:
        - BearerAuth: []
      responses:
        "200":
          description: 내 평가 목록 조회 성공
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        $ref: "#/components/schemas/GuideRatingSummaryResponse"

  /api/rate/admin/aichat/sessions:
    get:
      tags:
        - rate
      summary: 관리자의 모든 AI 채팅 평가 조회
      description: 관리자가 모든 AI 채팅 세션의 평가 목록을 페이지 단위로 조회합니다.
      security:
        - BearerAuth: []
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            description: 페이지 번호 (0부터 시작)
            default: 0
        - in: query
          name: size
          schema:
            type: integer
            description: 페이지당 개수
            default: 20
        - in: query
          name: sort
          schema:
            type: string
            description: "정렬 기준 (예: createdAt,desc)"
      responses:
        "200":
          description: AI 채팅 평가 목록 조회 성공
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ApiResponse"
                  - type: object
                    properties:
                      data:
                        type: object
                        description: Page<RateResponse> 형태