openapi.yaml

openapi: 3.0.3
info:
  title: AI 기술 면접 연습 플랫폼 API
  version: 0.4.1
  description: 핵심 사용자 흐름과 최신 요구사항 변경안을 반영한 OpenAPI 계약. API 변경 시 docs/requirements.md,
    docs/project/open-items.md와 함께 수정한다. 핵심 성공 응답은 success/data/meta 형태와 예시 응답을 포함한다.
servers:
- url: /api/v1
tags:
- name: Auth
- name: GitHub
- name: Documents
- name: Applications
- name: Interview
- name: Followup
- name: AI
components:
  securitySchemes:
    AuthorizationHeader:
      type: apiKey
      in: header
      name: Authorization
      description: '형식: Bearer {apiKey} {accessToken}'
  schemas:
    Meta:
      type: object
      properties:
        requestId:
          type: string
        timestamp:
          type: string
          format: date-time
        pagination:
          $ref: '#/components/schemas/Pagination'
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            retryable:
              type: boolean
            retryAfterSeconds:
              type: integer
              nullable: true
              description: rate limit 시 재시도까지 기다려야 하는 초. null이면 해당 없음.
            fieldErrors:
              type: array
              items:
                $ref: '#/components/schemas/ErrorDetail'
          required:
          - code
          - message
        meta:
          $ref: '#/components/schemas/Meta'
      required:
      - success
      - error
      - meta
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
        displayName:
          type: string
        email:
          type: string
          nullable: true
        profileImageUrl:
          type: string
          nullable: true
        status:
          type: string
          enum:
          - active
          - withdrawn
      required:
      - id
      - displayName
      - status
    GithubConnection:
      type: object
      properties:
        id:
          type: integer
          format: int64
        userId:
          type: integer
          format: int64
        githubUserId:
          type: integer
          format: int64
        githubLogin:
          type: string
        accessScope:
          type: string
          nullable: true
          description: OAuth 동의 범위. private repository 조회가 필요한 경우 추가 scope가 포함될 수
            있다.
        syncStatus:
          type: string
          enum:
          - pending
          - success
          - failed
        connectedAt:
          type: string
          format: date-time
        lastSyncedAt:
          type: string
          format: date-time
          nullable: true
      required:
      - id
      - userId
      - githubUserId
      - githubLogin
      - syncStatus
      - connectedAt
    Repository:
      type: object
      properties:
        id:
          type: integer
          format: int64
        githubRepoId:
          type: integer
          format: int64
        ownerLogin:
          type: string
        repoName:
          type: string
        fullName:
          type: string
        htmlUrl:
          type: string
        visibility:
          type: string
          enum:
          - public
          - private
          - internal
        defaultBranch:
          type: string
          nullable: true
        isSelected:
          type: boolean
        hasCommits:
          type: boolean
          description: 커밋 동기화 완료 여부. false면 포트폴리오 분석 불가
        analysisStatus:
          allOf:
            - $ref: '#/components/schemas/RepoSyncStatus'
            - description: 분석 상태. 분석 미요청 또는 TTL 만료 시 null
              nullable: true
        pushedAt:
          type: string
          format: date-time
          nullable: true
          description: GitHub pushed_at. 기여/URL 추가 경로는 null
        ownerType:
          type: string
          nullable: true
          enum:
          - owner
          - collaborator
          description: 저장 시점에 결정됨. 기존 데이터는 null
        language:
          type: string
          nullable: true
          description: primary language
      required:
      - id
      - githubRepoId
      - fullName
      - htmlUrl
      - visibility
      - isSelected
      - hasCommits
    SaveContributionRequest:
      type: object
      properties:
        githubRepoId:
          type: integer
          format: int64
        nameWithOwner:
          type: string
          description: 'owner/repo 형식'
          example: spring-projects/spring-security
        url:
          type: string
        language:
          type: string
          nullable: true
        repoSizeKb:
          type: integer
          nullable: true
      required:
      - githubRepoId
      - nameWithOwner
      - url
    AddContributionByUrlRequest:
      type: object
      properties:
        url:
          type: string
          description: 'GitHub repo URL (예: https://github.com/owner/repo)'
      required:
      - url
    ContributedRepo:
      type: object
      properties:
        githubRepoId:
          type: integer
          format: int64
        nameWithOwner:
          type: string
        url:
          type: string
        language:
          type: string
          nullable: true
        repoSizeKb:
          type: integer
          nullable: true
        contributionCount:
          type: integer
        alreadySaved:
          type: boolean
          description: 이미 github_repositories에 저장된 repo 여부
        repositoryId:
          type: integer
          format: int64
          nullable: true
          description: 'github_repositories.id (저장된 경우에만 non-null)'
      required:
      - githubRepoId
      - nameWithOwner
      - url
      - contributionCount
      - alreadySaved
    Document:
      type: object
      properties:
        id:
          type: integer
          format: int64
        documentType:
          type: string
          enum:
          - resume
          - award
          - certificate
          - other
        originalFileName:
          type: string
        mimeType:
          type: string
          description: '허용 MIME type: application/pdf, application/vnd.openxmlformats-officedocument.wordprocessingml.document,
            text/markdown, text/plain'
        fileSizeBytes:
          type: integer
          format: int64
          description: 최대 52428800 bytes (50MB)
        extractStatus:
          type: string
          enum:
          - pending
          - success
          - failed
        uploadedAt:
          type: string
          format: date-time
        extractedAt:
          type: string
          format: date-time
          nullable: true
        extractedText:
          type: string
          nullable: true
      required:
      - id
      - documentType
      - originalFileName
      - mimeType
      - fileSizeBytes
      - extractStatus
      - uploadedAt
    Application:
      type: object
      properties:
        id:
          type: integer
          format: int64
        applicationTitle:
          type: string
          nullable: true
        companyName:
          type: string
          nullable: true
        jobRole:
          type: string
        status:
          type: string
          enum:
          - draft
          - ready
          description: 'draft: 작업 중, ready: jobRole, 1개 이상 source, 1개 이상 question, 모든 question의 유효 답변이 준비되어 면접 질문 생성과 이후 흐름에 사용할 수 있는 상태'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        applicationType:
          type: string
          nullable: true
          description: '지원 유형 예: 신입, 인턴, 경력'
      required:
      - id
      - jobRole
      - status
      - createdAt
      - updatedAt
    ApplicationQuestion:
      type: object
      properties:
        id:
          type: integer
          format: int64
        questionOrder:
          type: integer
        questionText:
          type: string
        generatedAnswer:
          type: string
          nullable: true
        editedAnswer:
          type: string
          nullable: true
        toneOption:
          type: string
          nullable: true
          enum:
          - formal
          - balanced
          - casual
        lengthOption:
          type: string
          nullable: true
          enum:
          - short
          - medium
          - long
          description: short<=700 chars, medium<=1200 chars, long<=1800 chars
        emphasisPoint:
          type: string
          nullable: true
      required:
      - id
      - questionOrder
      - questionText
    InterviewQuestion:
      type: object
      properties:
        id:
          type: integer
          format: int64
        questionOrder:
          type: integer
        questionType:
          type: string
          enum:
          - experience
          - project
          - technical_cs
          - technical_stack
          - behavioral
          - follow_up
        difficultyLevel:
          type: string
          enum:
          - easy
          - medium
          - hard
        questionText:
          type: string
        parentQuestionId:
          type: integer
          format: int64
          nullable: true
        sourceApplicationQuestionId:
          type: integer
          format: int64
          nullable: true
      required:
      - id
      - questionOrder
      - questionType
      - difficultyLevel
      - questionText
    InterviewSession:
      type: object
      properties:
        id:
          type: integer
          format: int64
        questionSetId:
          type: integer
          format: int64
        status:
          type: string
          enum:
          - ready
          - in_progress
          - paused
          - completed
          - feedback_completed
          description: 'ready: 시작 전, in_progress: 진행 중, paused: 일시중지, completed: 종료,
            feedback_completed: 피드백 완료'
        totalScore:
          type: integer
          minimum: 0
          maximum: 100
          nullable: true
        summaryFeedback:
          type: string
          nullable: true
        startedAt:
          type: string
          format: date-time
          nullable: true
        endedAt:
          type: string
          format: date-time
          nullable: true
      required:
      - id
      - questionSetId
      - status
    InterviewSessionCurrentQuestion:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: 세션 질문 id. 질문 세트 원본 질문 id가 아니라 현재 세션 스냅샷 기준 식별자
        questionOrder:
          type: integer
        questionType:
          type: string
          enum:
          - experience
          - project
          - technical_cs
          - technical_stack
          - behavioral
          - follow_up
        difficultyLevel:
          type: string
          enum:
          - easy
          - medium
          - hard
        questionText:
          type: string
      required:
      - id
      - questionOrder
      - questionType
      - difficultyLevel
      - questionText
    InterviewSessionAnswerSummary:
      type: object
      properties:
        answerOrder:
          type: integer
        answerText:
          type: string
          nullable: true
          description: 사용자가 최종 확인한 답변 텍스트. Track A 실시간 음성 입력 v1에서는 확정 transcript도 이 필드에 저장한다.
        isSkipped:
          type: boolean
      required:
      - answerOrder
      - isSkipped
    InterviewSessionTranscriptEntry:
      type: object
      properties:
        question:
          $ref: '#/components/schemas/InterviewSessionCurrentQuestion'
        answer:
          $ref: '#/components/schemas/InterviewSessionAnswerSummary'
      required:
      - question
      - answer
    CompletionFollowupContext:
      type: object
      properties:
        rootQuestion:
          $ref: '#/components/schemas/InterviewSessionCurrentQuestion'
        rootAnswer:
          $ref: '#/components/schemas/InterviewSessionAnswerSummary'
        runtimeFollowupQuestion:
          allOf:
          - $ref: '#/components/schemas/InterviewSessionCurrentQuestion'
          nullable: true
        runtimeFollowupAnswer:
          allOf:
          - $ref: '#/components/schemas/InterviewSessionAnswerSummary'
          nullable: true
        completionFollowupQuestion:
          $ref: '#/components/schemas/InterviewSessionCurrentQuestion'
        parentQuestionOrder:
          type: integer
      required:
      - rootQuestion
      - rootAnswer
      - completionFollowupQuestion
      - parentQuestionOrder
    InterviewSessionDetail:
      type: object
      properties:
        id:
          type: integer
          format: int64
        questionSetId:
          type: integer
          format: int64
        status:
          type: string
          enum:
          - ready
          - in_progress
          - paused
          - completed
          - feedback_completed
          description: 'ready: 시작 전, in_progress: 진행 중, paused: 일시중지, completed: 종료,
            feedback_completed: 피드백 완료'
        currentQuestion:
          allOf:
          - $ref: '#/components/schemas/InterviewSessionCurrentQuestion'
          nullable: true
        completionFollowupContext:
          allOf:
          - $ref: '#/components/schemas/CompletionFollowupContext'
          nullable: true
        transcriptEntries:
          type: array
          description: answered question/answer pair 목록. answerOrder 오름차순이며 현재 미응답 currentQuestion과 system 메시지는 포함하지 않음. Track A 실시간 음성 입력 v1의 현재 interim transcript는 포함하지 않는다.
          items:
            $ref: '#/components/schemas/InterviewSessionTranscriptEntry'
        totalQuestionCount:
          type: integer
        answeredQuestionCount:
          type: integer
        remainingQuestionCount:
          type: integer
        resumeAvailable:
          type: boolean
        lastActivityAt:
          type: string
          format: date-time
          nullable: true
        startedAt:
          type: string
          format: date-time
          nullable: true
        endedAt:
          type: string
          format: date-time
          nullable: true
      required:
      - id
      - questionSetId
      - status
      - completionFollowupContext
      - transcriptEntries
      - totalQuestionCount
      - answeredQuestionCount
      - remainingQuestionCount
      - resumeAvailable
      - totalQuestionCount
      - answeredQuestionCount
      - remainingQuestionCount
      - resumeAvailable
    InterviewSessionTransitionData:
      type: object
      properties:
        sessionId:
          type: integer
          format: int64
        status:
          type: string
          enum:
          - in_progress
          - paused
        updatedAt:
          type: string
          format: date-time
      required:
      - sessionId
      - status
      - updatedAt
    ErrorDetail:
      type: object
      properties:
        field:
          type: string
        reason:
          type: string
      required:
      - field
      - reason
    FeedbackTag:
      type: object
      properties:
        tagId:
          type: integer
          format: int64
        tagName:
          type: string
          enum:
          - 질문 의도 미충족
          - 답변 미완
          - 구체성 부족
          - 문제 해결 설명 부족
          - 답변 구조 미흡
          - 근거 부족
          - 기술 정확도 부족
          - 기술 깊이 부족
          - 선택 근거 부족
          - 표현 명확성 부족
        tagCategory:
          type: string
          enum:
          - content
          - structure
          - evidence
          - communication
          - technical
          - other
      required:
      - tagId
      - tagName
      - tagCategory
    InterviewAnswerResult:
      type: object
      properties:
        answerId:
          type: integer
          format: int64
        questionId:
          type: integer
          format: int64
          description: 세션 질문 id
        questionType:
          type: string
          description: 세션 질문 유형. `follow_up`이면 결과 화면에서 꼬리 질문 배지를 표시할 수 있다.
          enum:
          - experience
          - project
          - technical_cs
          - technical_stack
          - behavioral
          - follow_up
        questionText:
          type: string
        answerText:
          type: string
          nullable: true
        score:
          type: integer
          minimum: 0
          maximum: 100
        evaluationRationale:
          type: string
        tags:
          type: array
          maxItems: 3
          items:
            $ref: '#/components/schemas/FeedbackTag'
      required:
      - answerId
      - questionId
      - questionType
      - questionText
      - score
      - evaluationRationale
      - tags
    InterviewResult:
      type: object
      properties:
        sessionId:
          type: integer
          format: int64
        questionSetId:
          type: integer
          format: int64
        status:
          type: string
          enum:
          - completed
          - feedback_completed
        totalScore:
          type: integer
          minimum: 0
          maximum: 100
        summaryFeedback:
          type: string
        answers:
          type: array
          items:
            $ref: '#/components/schemas/InterviewAnswerResult'
        startedAt:
          type: string
          format: date-time
          nullable: true
        endedAt:
          type: string
          format: date-time
          nullable: true
      required:
      - sessionId
      - questionSetId
      - status
      - totalScore
      - summaryFeedback
      - answers
    Pagination:
      type: object
      properties:
        page:
          type: integer
          example: 1
        size:
          type: integer
          example: 20
        totalElements:
          type: integer
          example: 1
        totalPages:
          type: integer
          example: 1
      required:
      - page
      - size
      - totalElements
      - totalPages
    AuthorizationStartData:
      type: object
      properties:
        provider:
          type: string
          enum:
          - github
          - google
          - kakao
        authorizationUrl:
          type: string
        state:
          type: string
      required:
      - provider
      - authorizationUrl
      - state
    OAuthCallbackData:
      type: object
      properties:
        provider:
          type: string
          enum:
          - github
          - google
          - kakao
        isNewUser:
          type: boolean
        user:
          $ref: '#/components/schemas/User'
      required:
      - provider
      - isNewUser
      - user
    LogoutData:
      type: object
      properties:
        loggedOut:
          type: boolean
          example: true
      required:
      - loggedOut
    RepositorySelectionData:
      type: object
      properties:
        selectedRepositoryIds:
          type: array
          items:
            type: integer
            format: int64
        selectedCount:
          type: integer
      required:
      - selectedRepositoryIds
      - selectedCount
    RepositorySyncData:
      type: object
      properties:
        repositoryId:
          type: integer
          format: int64
        syncStatus:
          type: string
          description: 동기화 시작 요청의 처리 상태. 저장되는 github_connections.sync_status(pending/success/failed)와는 별개다.
          enum:
          - queued
          - running
          - completed
          - failed
        queuedAt:
          type: string
          format: date-time
      required:
      - repositoryId
      - syncStatus
      - queuedAt
    RepoSyncStatus:
      type: object
      nullable: true
      properties:
        repositoryId:
          type: integer
          format: int64
        status:
          type: string
          enum:
          - PENDING
          - IN_PROGRESS
          - COMPLETED
          - SKIPPED
          - FAILED
          description: PENDING=대기중, IN_PROGRESS=처리중, COMPLETED=완료, SKIPPED=분석 생략(skipReason 참조), FAILED=오류
        step:
          type: string
          nullable: true
          description: IN_PROGRESS 시 현재 단계 (significance_check|clone|analysis|summary)
        startedAt:
          type: string
          format: date-time
          nullable: true
        estimatedEndAt:
          type: string
          format: date-time
          nullable: true
        completedAt:
          type: string
          format: date-time
          nullable: true
        error:
          type: string
          nullable: true
        skipReason:
          type: string
          nullable: true
          description: SKIPPED 상태일 때 skip 이유 (예:"커밋이 없습니다. 커밋 동기화를 먼저 실행해주세요.", "최근 변경량이 기준치에 미달합니다.")
      required:
      - repositoryId
      - status
    ApplicationSourceBindingData:
      type: object
      properties:
        applicationId:
          type: integer
          format: int64
        repositoryIds:
          type: array
          items:
            type: integer
            format: int64
        documentIds:
          type: array
          items:
            type: integer
            format: int64
        sourceCount:
          type: integer
      required:
      - applicationId
      - repositoryIds
      - documentIds
      - sourceCount
    GeneratedApplicationAnswer:
      type: object
      properties:
        questionId:
          type: integer
          format: int64
        questionText:
          type: string
        generatedAnswer:
          type: string
        toneOption:
          type: string
          nullable: true
          enum:
          - formal
          - balanced
          - casual
        lengthOption:
          type: string
          nullable: true
          enum:
          - short
          - medium
          - long
      required:
      - questionId
      - questionText
      - generatedAnswer
    ApplicationAnswerGenerationData:
      type: object
      properties:
        applicationId:
          type: integer
          format: int64
        generatedCount:
          type: integer
        regenerate:
          type: boolean
        answers:
          type: array
          items:
            $ref: '#/components/schemas/GeneratedApplicationAnswer'
      required:
      - applicationId
      - generatedCount
      - regenerate
      - answers
    QuestionSetJobStatus:
      type: object
      properties:
        jobId:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - PENDING
          - IN_PROGRESS
          - COMPLETED
          - FAILED
        questionSetId:
          type: integer
          format: int64
          nullable: true
          description: COMPLETED 시 채워진다
        error:
          type: string
          nullable: true
      required:
      - jobId
      - status
    InterviewQuestionSetSummary:
      type: object
      properties:
        questionSetId:
          type: integer
          format: int64
        applicationId:
          type: integer
          format: int64
        title:
          type: string
        questionCount:
          type: integer
        difficultyLevel:
          type: string
          enum:
          - easy
          - medium
          - hard
        createdAt:
          type: string
          format: date-time
      required:
      - questionSetId
      - applicationId
      - title
      - questionCount
      - difficultyLevel
      - createdAt
    InterviewQuestionSetDetail:
      type: object
      properties:
        questionSetId:
          type: integer
          format: int64
        applicationId:
          type: integer
          format: int64
        title:
          type: string
        questionCount:
          type: integer
        difficultyLevel:
          type: string
          enum:
          - easy
          - medium
          - hard
        questions:
          type: array
          items:
            $ref: '#/components/schemas/InterviewQuestion'
        createdAt:
          type: string
          format: date-time
      required:
      - questionSetId
      - applicationId
      - title
      - questionCount
      - difficultyLevel
      - questions
      - createdAt
    SessionAnswerSubmitData:
      type: object
      properties:
        sessionId:
          type: integer
          format: int64
        questionId:
          type: integer
          format: int64
          description: 저장된 세션 질문 id
        answerOrder:
          type: integer
        isSkipped:
          type: boolean
        submittedAt:
          type: string
          format: date-time
      required:
      - sessionId
      - questionId
      - answerOrder
      - isSkipped
      - submittedAt
    SessionCompletionData:
      type: object
      properties:
        sessionId:
          type: integer
          format: int64
        status:
          type: string
          enum:
          - completed
          - feedback_completed
        totalScore:
          type: integer
          minimum: 0
          maximum: 100
        summaryFeedback:
          type: string
        endedAt:
          type: string
          format: date-time
      required:
      - sessionId
      - status
      - totalScore
      - summaryFeedback
      - endedAt
    FollowupQuestionType:
      type: string
      enum:
      - PROJECT
      - PROBLEM
      - TECH
      - COLLABORATION
    FollowupGapType:
      type: string
      enum:
      - ROLE
      - ACTION
      - RESULT
      - REASON
      - METRIC
      - CAUSE
      - VERIFICATION
      - PREVENTION
      - ALTERNATIVE
      - TRADEOFF
      - LIMITATION
      - ISSUE
      - AGREEMENT
      - REFLECTION
      - SCOPE_MIXED
    FollowupFinalAction:
      type: string
      enum:
      - NO_FOLLOW_UP
      - USE_CANDIDATE
      - USE_DYNAMIC
    FollowupCandidateQuestionType:
      type: string
      enum:
      - PROJECT_RESULT_DETAIL
      - PROJECT_RESULT_METRIC
      - PROJECT_APPROACH_REASON
      - PROJECT_SCOPE_NARROW
      - PROJECT_CORE_CLARIFY
      - PROBLEM_CAUSE_DETAIL
      - PROBLEM_VERIFICATION_DETAIL
      - PROBLEM_PREVENTION_DETAIL
      - PROBLEM_CORE_CLARIFY
      - TECH_ALTERNATIVE_COMPARE
      - TECH_TRADEOFF_DETAIL
      - TECH_EFFECT_AFTER_ADOPTION
      - TECH_CORE_CLARIFY
      - COLLAB_ISSUE_DETAIL
      - COLLAB_AGREEMENT_CRITERIA
      - COLLAB_DECISION_REASON
      - COLLAB_RESULT_IMPACT
      - COLLAB_CORE_CLARIFY
    FollowupSignals:
      type: object
      properties:
        ROLE:
          type: boolean
        ACTION:
          type: boolean
        RESULT:
          type: boolean
        REASON:
          type: boolean
        METRIC:
          type: boolean
        CAUSE:
          type: boolean
        VERIFICATION:
          type: boolean
        PREVENTION:
          type: boolean
        ALTERNATIVE:
          type: boolean
        TRADEOFF:
          type: boolean
        LIMITATION:
          type: boolean
        ISSUE:
          type: boolean
        AGREEMENT:
          type: boolean
        REFLECTION:
          type: boolean
        SCOPE_MIXED:
          type: boolean
      required:
      - ROLE
      - ACTION
      - RESULT
      - REASON
      - METRIC
      - CAUSE
      - VERIFICATION
      - PREVENTION
      - ALTERNATIVE
      - TRADEOFF
      - LIMITATION
      - ISSUE
      - AGREEMENT
      - REFLECTION
      - SCOPE_MIXED
    FollowupAnalyzeRequest:
      type: object
      properties:
        questionType:
          $ref: '#/components/schemas/FollowupQuestionType'
        answerText:
          type: string
      required:
      - questionType
      - answerText
    FollowupAnalyzeData:
      type: object
      properties:
        questionType:
          $ref: '#/components/schemas/FollowupQuestionType'
        signals:
          $ref: '#/components/schemas/FollowupSignals'
        orderedMissingGaps:
          type: array
          items:
            $ref: '#/components/schemas/FollowupGapType'
        primaryGap:
          allOf:
          - $ref: '#/components/schemas/FollowupGapType'
          nullable: true
        secondaryGap:
          allOf:
          - $ref: '#/components/schemas/FollowupGapType'
          nullable: true
        finalAction:
          $ref: '#/components/schemas/FollowupFinalAction'
        candidateQuestionTypes:
          type: array
          description: finalAction이 `USE_CANDIDATE`일 때 runtime local deterministic follow-up 템플릿 선택에 쓰는 우선순위 후보 목록. 그 외에는 빈 배열일 수 있다.
          items:
            $ref: '#/components/schemas/FollowupCandidateQuestionType'
      required:
      - questionType
      - signals
      - orderedMissingGaps
      - primaryGap
      - secondaryGap
      - finalAction
      - candidateQuestionTypes
    FollowupAnalyzeApiResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          $ref: '#/components/schemas/FollowupAnalyzeData'
        meta:
          $ref: '#/components/schemas/Meta'
      required:
      - success
      - data
      - meta
security:
- AuthorizationHeader: []
paths:
  /auth/oauth2/{provider}/authorize:
    get:
      tags:
      - Auth
      summary: OAuth2 로그인 시작
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          type: string
          enum:
          - github
          - google
          - kakao
      responses:
        '200':
          description: 인증 URL 반환
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/AuthorizationStartData'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
              examples:
                authorizationStartExample:
                  value:
                    success: true
                    data:
                      provider: github
                      authorizationUrl: https://github.com/login/oauth/authorize?client_id=example&state=st_123
                      state: st_123
                    meta: &id001
                      requestId: req_20260317_0001
                      timestamp: '2026-03-17T10:30:00Z'
        '400':
          description: 지원하지 않는 provider
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidProvider:
                  value:
                    success: false
                    error:
                      code: AUTH_UNSUPPORTED_PROVIDER
                      message: 지원하지 않는 로그인 제공자입니다.
                      retryable: false
                    meta: *id001
  /auth/oauth2/{provider}/callback:
    get:
      tags:
      - Auth
      summary: OAuth2 콜백 처리
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          type: string
          enum:
          - github
          - google
          - kakao
      - name: code
        in: query
        required: false
        schema:
          type: string
      - name: state
        in: query
        required: false
        schema:
          type: string
      - name: error
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: 로그인 성공
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/OAuthCallbackData'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
              examples:
                oauthCallbackSuccess:
                  value:
                    success: true
                    data:
                      provider: github
                      isNewUser: false
                      user:
                        id: 1
                        displayName: q q
                        email: user@example.com
                        profileImageUrl: https://avatars.githubusercontent.com/u/1?v=4
                        status: active
                    meta: *id001
        '401':
          description: 인증 실패
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                oauthFailure:
                  value:
                    success: false
                    error:
                      code: AUTH_PROVIDER_RESPONSE_INVALID
                      message: 소셜 로그인 인증 처리에 실패했습니다.
                      retryable: false
                    meta: *id001
  /users/me:
    get:
      tags:
      - Auth
      summary: 내 정보 조회
      responses:
        '200':
          description: 내 정보
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/User'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
              examples:
                userMeSuccess:
                  value:
                    success: true
                    data:
                      id: 1
                      displayName: q q
                      email: user@example.com
                      profileImageUrl: https://avatars.githubusercontent.com/u/1?v=4
                      status: active
                    meta: *id001
        '401':
          description: 인증 필요
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                authRequired:
                  value:
                    success: false
                    error:
                      code: AUTH_REQUIRED
                      message: 로그인이 필요합니다.
                      retryable: false
                    meta: *id001
  /auth/logout:
    post:
      tags:
      - Auth
      summary: 로그아웃
      responses:
        '200':
          description: 로그아웃 성공
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/LogoutData'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
              examples:
                logoutSuccess:
                  value:
                    success: true
                    data:
                      loggedOut: true
                    meta: *id001
  /github/connections:
    post:
      tags:
      - GitHub
      summary: GitHub 연결 생성 또는 갱신
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                mode:
                  type: string
                  enum:
                  - oauth
                  - url
                githubLogin:
                  type: string
                githubUserId:
                  type: integer
                  format: int64
                accessScope:
                  type: string
                  description: private repository 접근이 필요한 경우 provider 동의로 획득한 scope
                    문자열
                githubProfileUrl:
                  type: string
              required:
              - mode
      responses:
        '201':
          description: 연결 성공
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/GithubConnection'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
              examples:
                githubConnectionSuccess:
                  value:
                    success: true
                    data:
                      id: 10
                      userId: 1
                      githubUserId: 123456
                      githubLogin: octocat
                      accessScope: read:user repo
                      syncStatus: success
                      connectedAt: '2026-03-17T10:29:30Z'
                      lastSyncedAt: '2026-03-17T10:29:50Z'
                    meta: *id001
  /github/connections/refresh:
    post:
      tags:
      - GitHub
      summary: GitHub 연결 갱신 (저장된 토큰으로 repo 목록 동기화)
      description: 저장된 GitHub OAuth 토큰을 사용해 GitHub API에서 repo 목록을 가져오고 DB에 반영한다.
      responses:
        '202':
          description: 갱신 요청 수락
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/GithubConnection'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
        '404':
          description: GitHub 연결 없음
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /github/repositories:
    get:
      tags:
      - GitHub
      summary: 저장소 목록 조회
      parameters:
      - name: selected
        in: query
        required: false
        schema:
          type: boolean
      - name: visibility
        in: query
        required: false
        schema:
          type: string
          enum:
          - public
          - private
          - internal
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
      - name: size
        in: query
        required: false
        schema:
          type: integer
          default: 20
      responses:
        '200':
          description: 저장소 목록
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Repository'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
              examples:
                repositoryListSuccess:
                  value:
                    success: true
                    data:
                    - id: 101
                      githubRepoId: 987654
                      ownerLogin: octocat
                      repoName: ai-interview-platform
                      fullName: octocat/ai-interview-platform
                      htmlUrl: https://github.com/octocat/ai-interview-platform
                      visibility: public
                      defaultBranch: main
                      isSelected: true
                    meta: &id002
                      requestId: req_20260317_0002
                      timestamp: '2026-03-17T10:30:05Z'
                      pagination:
                        page: 1
                        size: 20
                        totalElements: 1
                        totalPages: 1
  /github/repositories/selection:
    put:
      tags:
      - GitHub
      summary: 저장소 선택 상태 저장
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                repositoryIds:
                  type: array
                  items:
                    type: integer
                    format: int64
              required:
              - repositoryIds
      responses:
        '200':
          description: 저장 성공
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/RepositorySelectionData'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
              examples:
                repositorySelectionSuccess:
                  value:
                    success: true
                    data:
                      selectedRepositoryIds:
                      - 101
                      selectedCount: 1
                    meta: *id001
  /github/repositories/{repositoryId}/sync-commits:
    post:
      tags:
      - GitHub
      summary: 저장소 커밋 동기화 시작
      parameters:
      - name: repositoryId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '202':
          description: 동기화 시작
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/RepositorySyncData'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
              examples:
                repositorySyncQueued:
                  value:
                    success: true
                    data:
                      repositoryId: 101
                      syncStatus: queued
                      queuedAt: '2026-03-17T10:31:00Z'
                    meta: *id001
        '403':
          description: private/internal repository 접근 scope 부족
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                privateScopeError:
                  value:
                    success: false
                    error:
                      code: GITHUB_SCOPE_INSUFFICIENT
                      message: private repository 조회 권한이 부족합니다.
                      retryable: false
                      fieldErrors:
                      - field: accessScope
                        reason: missing_private_repo_scope
                    meta: *id001
      description: 선택한 repository의 사용자 본인 commit 동기화를 시작한다. private repository는 GitHub
        OAuth 추가 동의가 있는 경우에만 지원한다.
  /github/repositories/{repositoryId}/analyze:
    post:
      tags:
      - GitHub
      summary: 저장소 분석 파이프라인 시작
      description: |
        clone → 정적 분석 → Code Index 저장 → RepoSummary AI 생성 → MergedSummary 재집계 파이프라인을 비동기로 시작한다.
        커밋 동기화(sync-commits)가 먼저 완료된 상태에서 호출해야 한다.
        Significance Check 미달 시 SKIPPED 상태로 종료되고 LLM 호출 없이 반환한다.
      parameters:
      - name: repositoryId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '202':
          description: 분석 파이프라인 시작 (비동기)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/RepoSyncStatus'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
        '404':
          description: 저장소 없음
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - GitHub
      summary: 분석 파이프라인 취소
      description: PENDING/IN_PROGRESS 상태의 분석을 중단하고 상태를 FAILED로 변경한다. 이미 완료됐거나 없는 분석에 대해서도 200을 반환한다 (idempotent).
      parameters:
      - name: repositoryId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: 취소 성공 (idempotent)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    nullable: true
                    example: null
                  meta:
                    $ref: '#/components/schemas/Meta'
  /github/repositories/{repositoryId}/sync-status:
    get:
      tags:
      - GitHub
      summary: 저장소 커밋 동기화 상태 조회
      description: 특정 저장소의 커밋 동기화 진행 상태를 Redis에서 조회한다. 상태가 없으면 null을 반환한다.
      parameters:
      - name: repositoryId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: 동기화 상태
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/RepoSyncStatus'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
              examples:
                syncInProgress:
                  value:
                    success: true
                    data:
                      repositoryId: 101
                      status: IN_PROGRESS
                      step: "clone"
                      startedAt: '2026-03-17T10:31:00Z'
                      estimatedEndAt: '2026-03-17T10:33:00Z'
                    meta: *id001
                syncCompleted:
                  value:
                    success: true
                    data:
                      repositoryId: 101
                      status: COMPLETED
                      startedAt: '2026-03-17T10:31:00Z'
                      completedAt: '2026-03-17T10:32:45Z'
                    meta: *id001
                syncNotFound:
                  value:
                    success: true
                    data: null
                    meta: *id001
  /github/repositories/{repositoryId}:
    delete:
      tags:
      - GitHub
      summary: 저장소 삭제
      description: 기여 repo를 github_repositories에서 완전히 삭제한다. 진행 중인 분석 취소 + 관련 데이터(커밋, 코드 인덱스, 요약) 삭제 후 MergedSummary 재집계.
      parameters:
      - name: repositoryId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: 삭제 성공
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    nullable: true
                    example: null
                  meta:
                    $ref: '#/components/schemas/Meta'
        '404':
          description: 저장소 없음
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /github/contributions/discovered:
    get:
      tags:
      - GitHub
      summary: 기여한 public repo 탐색
      description: GitHub OAuth 토큰으로 사용자가 커밋을 기여한 public repo 목록을 조회한다. 본인 소유 외에 org, 오픈소스 repo도 포함된다. GitHub OAuth 연동이 필수다.
      parameters:
      - name: yearsOffset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          minimum: 0
        description: '조회 기간 오프셋. 0=최근 2년(기본값), 1=2~4년 전, 2=4~6년 전. "이전 기여 더 불러오기" 기능에 사용한다.'
      responses:
        '200':
          description: 기여 repo 목록
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ContributedRepo'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
              examples:
                contributionListSuccess:
                  value:
                    success: true
                    data:
                    - githubRepoId: 987654
                      nameWithOwner: prgrms-be-devcourse/NBE8-10-final-Team02
                      url: https://github.com/prgrms-be-devcourse/NBE8-10-final-Team02
                      language: Java
                      repoSizeKb: 8240
                      contributionCount: 23
                      alreadySaved: true
                    - githubRepoId: 111222
                      nameWithOwner: spring-projects/spring-security
                      url: https://github.com/spring-projects/spring-security
                      language: Java
                      repoSizeKb: 158000
                      contributionCount: 2
                      alreadySaved: false
                    meta: *id001
        '403':
          description: GitHub OAuth 연동 없음 (access token 없음)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                noOAuthToken:
                  value:
                    success: false
                    error:
                      code: GITHUB_SCOPE_INSUFFICIENT
                      message: 기여 repo 탐색은 GitHub OAuth 연동이 필요합니다.
                      retryable: false
                      fieldErrors: []
                    meta: *id001
  /github/contributions/save:
    post:
      tags:
      - GitHub
      summary: 기여 repo 저장
      description: 기여 탐색 목록에서 선택한 repo를 github_repositories에 저장한다. 이미 저장된 경우 기존 레코드를 그대로 반환한다.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SaveContributionRequest'
      responses:
        '201':
          description: 저장 성공 (또는 기존 레코드 반환)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Repository'
                  meta:
                    $ref: '#/components/schemas/Meta'
              examples:
                saveSuccess:
                  value:
                    success: true
                    data:
                      id: 42
                      githubRepoId: 111222
                      ownerLogin: spring-projects
                      repoName: spring-security
                      fullName: spring-projects/spring-security
                      htmlUrl: https://github.com/spring-projects/spring-security
                      visibility: public
                      defaultBranch: null
                      isSelected: false
                    meta: *id001
        '400':
          description: 요청 형식 오류 (nameWithOwner 형식 불일치 등)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: GitHub OAuth 연동 없음
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                noOAuth:
                  value:
                    success: false
                    error:
                      code: GITHUB_SCOPE_INSUFFICIENT
                      message: GitHub OAuth 연동이 필요합니다.
                      retryable: false
                      fieldErrors: []
                    meta: *id001
  /github/contributions/add-by-url:
    post:
      tags:
      - GitHub
      summary: URL로 기여 repo 직접 추가
      description: 사용자가 직접 입력한 GitHub URL로 기여 repo를 추가한다. 본인(githubLogin)의 커밋이 1개 이상 존재하는 경우에만 저장된다. public repo만 허용한다.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddContributionByUrlRequest'
      responses:
        '201':
          description: 추가 성공 (또는 기존 레코드 반환)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Repository'
                  meta:
                    $ref: '#/components/schemas/Meta'
        '400':
          description: URL 형식 오류
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidUrl:
                  value:
                    success: false
                    error:
                      code: GITHUB_URL_INVALID
                      message: 유효하지 않은 GitHub repo URL입니다.
                      retryable: false
                      fieldErrors: []
                    meta: *id001
        '403':
          description: GitHub OAuth 연동 없음
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                noOAuth:
                  value:
                    success: false
                    error:
                      code: GITHUB_SCOPE_INSUFFICIENT
                      message: GitHub OAuth 연동이 필요합니다.
                      retryable: false
                      fieldErrors: []
                    meta: *id001
        '422':
          description: 본인 커밋 없음
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                noCommit:
                  value:
                    success: false
                    error:
                      code: GITHUB_USER_COMMIT_NOT_IDENTIFIED
                      message: 이 repository에서 본인의 커밋을 찾을 수 없습니다.
                      retryable: false
                      fieldErrors: []
                    meta: *id001
  /portfolios/me/readiness:
    get:
      tags:
      - Portfolio
      summary: 준비 현황 대시보드 조회
      description: |
        현재 사용자의 포트폴리오 준비 상태를 집계해서 반환한다.
        GitHub 연결 상태, 선택된 repository 수, 문서 수/추출 성공/실패,
        다음 추천 행동, 최근 실패 작업 알림을 포함한다.
        v1에서 아직 계산하지 않는 값(recentCollectedCommitCount, recentFailedJobs)은
        status="not_ready"로 고정하고 가짜 숫자를 표시하지 않는다.
      responses:
        '200':
          description: 준비 현황 조회 성공
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      profile:
                        type: object
                        properties:
                          userId:
                            type: integer
                            format: int64
                          displayName:
                            type: string
                          email:
                            type: string
                            nullable: true
                          profileImageUrl:
                            type: string
                            nullable: true
                      github:
                        type: object
                        properties:
                          connectionStatus:
                            type: string
                            enum: [connected, not_connected]
                          scopeStatus:
                            type: string
                            nullable: true
                            enum: [public_only, private_ready, insufficient, not_applicable]
                          selectedRepositoryCount:
                            type: integer
                          recentCollectedCommitCount:
                            type: object
                            properties:
                              status:
                                type: string
                                enum: [not_ready, ready]
                              value:
                                type: integer
                                nullable: true
                      documents:
                        type: object
                        properties:
                          totalCount:
                            type: integer
                          extractSuccessCount:
                            type: integer
                          extractFailedCount:
                            type: integer
                      readiness:
                        type: object
                        properties:
                          missingItems:
                            type: array
                            items:
                              type: string
                          nextRecommendedAction:
                            type: string
                            enum: [connect_github, select_repository, upload_document, retry_document_extraction, start_application]
                          canStartApplication:
                            type: boolean
                      alerts:
                        type: object
                        properties:
                          recentFailedJobs:
                            type: object
                            properties:
                              status:
                                type: string
                                enum: [not_ready, ready]
                              items:
                                type: array
                                nullable: true
                                items:
                                  type: object
                  meta:
                    $ref: '#/components/schemas/Meta'
              examples:
                portfolioReadinessSuccess:
                  value:
                    success: true
                    data:
                      profile:
                        userId: 1
                        displayName: q q
                        email: user@example.com
                        profileImageUrl: https://avatars.githubusercontent.com/u/1?v=4
                      github:
                        connectionStatus: connected
                        scopeStatus: public_only
                        selectedRepositoryCount: 2
                        recentCollectedCommitCount:
                          status: not_ready
                          value: null
                      documents:
                        totalCount: 3
                        extractSuccessCount: 2
                        extractFailedCount: 1
                      readiness:
                        missingItems: []
                        nextRecommendedAction: start_application
                        canStartApplication: true
                      alerts:
                        recentFailedJobs:
                          status: not_ready
                          items: null
                    meta: *id001
        '401':
          description: 인증 필요
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                authRequired:
                  value:
                    success: false
                    error:
                      code: AUTH_REQUIRED
                      message: 로그인이 필요합니다.
                      retryable: false
                    meta: *id001
  /documents:
    post:
      tags:
      - Documents
      summary: 문서 업로드
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                documentType:
                  type: string
                  enum:
                  - resume
                  - award
                  - certificate
                  - other
                  description: resume | award | certificate | other
                file:
                  type: string
                  format: binary
                  description: '허용 형식: PDF, DOCX, MD, TXT / 최대 50MB / 기본 최대 5개'
              required:
              - documentType
              - file
      responses:
        '201':
          description: 업로드 성공
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Document'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
              examples:
                documentUploadSuccess:
                  value:
                    success: true
                    data:
                      id: 301
                      documentType: resume
                      originalFileName: resume_2026.pdf
                      mimeType: application/pdf
                      fileSizeBytes: 834221
                      extractStatus: pending
                      uploadedAt: '2026-03-17T10:31:10Z'
                      extractedAt: null
                      extractedText: null
                    meta: *id001
        '400':
          description: 지원하지 않는 파일 형식 또는 최대 용량 초과
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                documentTooLargeError:
                  value:
                    success: false
                    error:
                      code: DOCUMENT_FILE_TOO_LARGE
                      message: 파일 크기는 50MB를 초과할 수 없습니다.
                      retryable: false
                      fieldErrors:
                      - field: file
                        reason: max_50mb
                    meta: *id001
      description: 이력서, 수상기록 등 문서를 업로드하고 텍스트 추출을 시작한다. 허용 형식은 PDF, DOCX, MD, TXT이고 파일 1개당
        최대 50MB다. 기본 업로드 수는 5개다.
    get:
      tags:
      - Documents
      summary: 문서 목록 조회
      responses:
        '200':
          description: 문서 목록
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Document'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
              examples:
                documentListSuccess:
                  value:
                    success: true
                    data:
                    - &id003
                      id: 301
                      documentType: resume
                      originalFileName: resume_2026.pdf
                      mimeType: application/pdf
                      fileSizeBytes: 834221
                      extractStatus: success
                      uploadedAt: '2026-03-17T10:31:10Z'
                      extractedAt: '2026-03-17T10:31:12Z'
                      extractedText: Spring Boot 기반 프로젝트 경험 ...
                    meta: *id002
  /documents/{documentId}:
    get:
      tags:
      - Documents
      summary: 문서 상세 조회
      parameters:
      - name: documentId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: 문서 상세
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Document'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
              examples:
                documentDetailSuccess:
                  value:
                    success: true
                    data: *id003
                    meta: *id001
    delete:
      tags:
      - Documents
      summary: 문서 삭제
      parameters:
      - name: documentId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '204':
          description: 삭제 성공
        '409':
          description: 참조 중 문서
  /documents/{documentId}/extracted-text:
    patch:
      tags:
      - Documents
      summary: 추출된 텍스트 업데이트
      description: 사용자가 수동으로 추출 텍스트를 편집하여 저장합니다.
      parameters:
      - name: documentId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                extractedText:
                  type: string
                  description: 사용자가 편집한 추출 텍스트
              required:
              - extractedText
      responses:
        '200':
          description: 업데이트 성공
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Document'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
              examples:
                portfolioReadinessSuccess:
                  value:
                    success: true
                    data:
                      profile:
                        userId: 1
                        displayName: q q
                        email: user@example.com
                        profileImageUrl: https://avatars.githubusercontent.com/u/1?v=4
                      github:
                        connectionStatus: connected
                        scopeStatus: public_only
                        selectedRepositoryCount: 2
                        recentCollectedCommitCount:
                          status: not_ready
                          value: null
                      documents:
                        totalCount: 3
                        extractSuccessCount: 2
                        extractFailedCount: 1
                      readiness:
                        missingItems: []
                        nextRecommendedAction: start_application
                        canStartApplication: true
                      alerts:
                        recentFailedJobs:
                          status: not_ready
                          items: null
                    meta: *id001
        '401':
          description: 인증 필요
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                authRequired:
                  value:
                    success: false
                    error:
                      code: AUTH_REQUIRED
                      message: 로그인이 필요합니다.
                      retryable: false
                    meta: *id001
  /applications:
    post:
      tags:
      - Applications
      summary: 지원 단위 생성
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                applicationTitle:
                  type: string
                companyName:
                  type: string
                jobRole:
                  type: string
                applicationType:
                  type: string
                  description: '지원 유형 예: 신입, 인턴, 경력'
              required:
              - jobRole
      responses:
        '201':
          description: 생성 성공
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Application'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
              examples:
                applicationCreateSuccess:
                  value:
                    success: true
                    data: &id004
                      id: 401
                      applicationTitle: 네이버 백엔드 신입 지원
                      companyName: 네이버
                      jobRole: Backend Engineer
                      status: draft
                      createdAt: '2026-03-17T10:32:00Z'
                      updatedAt: '2026-03-17T10:32:00Z'
                      applicationType: 신입
                    meta: *id001
    get:
      tags:
      - Applications
      summary: 지원 단위 목록 조회
      responses:
        '200':
          description: 목록 조회
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Application'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
              examples:
                applicationListSuccess:
                  value:
                    success: true
                    data:
                    - id: 401
                      applicationTitle: 네이버 백엔드 신입 지원
                      companyName: 네이버
                      jobRole: Backend Engineer
                      status: ready
                      createdAt: '2026-03-17T10:32:00Z'
                      updatedAt: '2026-03-17T10:33:10Z'
                      applicationType: 신입
                    meta: *id002
  /applications/{applicationId}:
    get:
      tags:
      - Applications
      summary: 지원 단위 상세 조회
      parameters:
      - name: applicationId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: 상세 조회
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Application'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
              examples:
                applicationDetailSuccess:
                  value:
                    success: true
                    data: *id004
                    meta: *id001
    patch:
      tags:
      - Applications
      summary: 지원 단위 수정
      parameters:
      - name: applicationId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                applicationTitle:
                  type: string
                companyName:
                  type: string
                jobRole:
                  type: string
                status:
                  type: string
                  enum:
                  - draft
                  - ready
                  description: ready는 jobRole, 1개 이상 source, 1개 이상 question, 모든 question의 유효 답변이 준비된 경우에만 허용한다.
                applicationType:
                  type: string
      responses:
        '200':
          description: 수정 성공
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Application'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
              examples:
                applicationUpdateSuccess:
                  value:
                    success: true
                    data:
                      id: 401
                      applicationTitle: 네이버 백엔드 신입 지원
                      companyName: 네이버
                      jobRole: Backend Engineer
                      status: ready
                      createdAt: '2026-03-17T10:32:00Z'
                      updatedAt: '2026-03-17T10:33:10Z'
                      applicationType: 신입
                    meta: *id001
        '409':
          description: ready 승격 조건을 만족하지 못함
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                applicationStatusConflict:
                  value:
                    success: false
                    error:
                      code: APPLICATION_STATUS_CONFLICT
                      message: 지원 준비가 아직 완료되지 않았습니다. source, 문항, 답변을 확인해주세요.
                      retryable: false
                    meta: *id001
    delete:
      tags:
      - Applications
      summary: 지원 단위 삭제
      parameters:
      - name: applicationId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '204':
          description: 삭제 성공
  /applications/{applicationId}/sources:
    put:
      tags:
      - Applications
      summary: 지원 단위 source 저장
      parameters:
      - name: applicationId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                repositoryIds:
                  type: array
                  items:
                    type: integer
                    format: int64
                documentIds:
                  type: array
                  items:
                    type: integer
                    format: int64
      responses:
        '200':
          description: 저장 성공
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/ApplicationSourceBindingData'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
              examples:
                applicationSourcesSuccess:
                  value:
                    success: true
                    data:
                      applicationId: 401
                      repositoryIds:
                      - 101
                      documentIds:
                      - 301
                      sourceCount: 2
                    meta: *id001
  /applications/{applicationId}/questions:
    post:
      tags:
      - Applications
      summary: 자소서 문항 일괄 저장
      parameters:
      - name: applicationId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                questions:
                  type: array
                  items:
                    type: object
                    properties:
                      questionOrder:
                        type: integer
                      questionText:
                        type: string
                      toneOption:
                        type: string
                        enum:
                        - formal
                        - balanced
                        - casual
                      lengthOption:
                        type: string
                        enum:
                        - short
                        - medium
                        - long
                        description: short<=700 chars, medium<=1200 chars, long<=1800
                          chars
                      emphasisPoint:
                        type: string
                    required:
                    - questionOrder
                    - questionText
                  maxItems: 10
              required:
              - questions
      responses:
        '200':
          description: 저장 성공
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApplicationQuestion'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
              examples:
                applicationQuestionsSaveSuccess:
                  value: &id005
                    success: true
                    data:
                    - id: 501
                      questionOrder: 1
                      questionText: 지원 동기를 작성해주세요.
                      generatedAnswer: null
                      editedAnswer: null
                      toneOption: formal
                      lengthOption: medium
                      emphasisPoint: 협업 경험 강조
                    meta: *id002
    get:
      tags:
      - Applications
      summary: 자소서 문항 목록 조회
      parameters:
      - name: applicationId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: 문항 목록
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApplicationQuestion'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
              examples:
                applicationQuestionsSuccess:
                  value: *id005
  /applications/{applicationId}/questions/generate-answers:
    post:
      tags:
      - Applications
      summary: 자소서 초안 생성
      parameters:
      - name: applicationId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                useTemplate:
                  type: boolean
                  default: true
                regenerate:
                  type: boolean
                  default: false
      responses:
        '200':
          description: 생성 성공
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/ApplicationAnswerGenerationData'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
              examples:
                generateAnswersSuccess:
                  value:
                    success: true
                    data:
                      applicationId: 401
                      generatedCount: 1
                      regenerate: false
                      answers:
                      - questionId: 501
                        questionText: 지원 동기를 작성해주세요.
                        generatedAnswer: 사용자 포트폴리오를 기반으로 협업 경험과 기술 선택 이유를 연결해 작성한
                          자소서 초안입니다.
                        toneOption: formal
                        lengthOption: medium
                    meta: *id001
        '502':
          description: AI 생성 실패 또는 결과 형식 불일치
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                aiSchemaError:
                  value:
                    success: false
                    error:
                      code: SELF_INTRO_RESULT_INVALID
                      message: AI 응답 형식이 올바르지 않습니다.
                      retryable: true
                    meta: *id001
        '503':
          description: AI 생성 timeout 또는 일시 장애
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                aiTimeoutError:
                  value:
                    success: false
                    error:
                      code: SELF_INTRO_GENERATION_TIMEOUT
                      message: AI 응답이 지연되고 있습니다. 잠시 후 다시 시도해주세요.
                      retryable: true
                    meta: *id001
      description: 지원 단위의 문항들에 대해 자소서 초안을 생성한다. 문항 수는 최대 10개이며 직무 기본 템플릿을 우선 적용한다.
        서버는 timeout, malformed JSON, schema violation에 대해 최대 2회 재시도한다.
  /interview/question-sets:
    post:
      tags:
      - Interview
      summary: 면접 질문 세트 생성
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                applicationId:
                  type: integer
                  format: int64
                title:
                  type: string
                questionCount:
                  type: integer
                  minimum: 1
                  maximum: 20
                  description: 1회 최대 20개
                difficultyLevel:
                  type: string
                  enum:
                  - easy
                  - medium
                  - hard
                questionTypes:
                  type: array
                  items:
                    type: string
                    enum:
                    - experience
                    - project
                    - technical_cs
                    - technical_stack
                    - behavioral
                    - follow_up
              required:
              - applicationId
              - questionCount
              - difficultyLevel
              - questionTypes
      responses:
        '202':
          description: 생성 작업 접수 (비동기 처리 시작)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/QuestionSetJobStatus'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
              examples:
                questionSetAccepted:
                  value:
                    success: true
                    data:
                      jobId: 550e8400-e29b-41d4-a716-446655440000
                      status: PENDING
                      questionSetId: null
                      error: null
                    meta: *id001
      description: >
        면접 질문 세트 AI 생성을 비동기로 시작한다. 202를 즉시 반환하고
        실제 생성은 백그라운드에서 진행된다.
        진행 상황은 GET /interview/question-sets/status/{jobId}로 폴링한다.
        COMPLETED 상태가 되면 응답의 questionSetId로 세트를 조회할 수 있다.
        서버는 질문 수 불일치, schema violation, malformed JSON에 대해 최대 2회 재시도한다.
    get:
      tags:
      - Interview
      summary: 면접 질문 세트 목록 조회
      responses:
        '200':
          description: 질문 세트 목록
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/InterviewQuestionSetSummary'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
              examples:
                questionSetListSuccess:
                  value:
                    success: true
                    data:
                    - questionSetId: 701
                      applicationId: 401
                      title: 네이버 백엔드 예상 질문 세트
                      questionCount: 5
                      difficultyLevel: medium
                      createdAt: '2026-03-17T10:34:00Z'
                    meta: *id002
  /interview/question-sets/status/{jobId}:
    get:
      tags:
      - Interview
      summary: 면접 질문 세트 생성 작업 상태 조회
      parameters:
      - name: jobId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: 작업 상태
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/QuestionSetJobStatus'
                  meta:
                    $ref: '#/components/schemas/Meta'
              examples:
                completed:
                  value:
                    success: true
                    data:
                      jobId: 550e8400-e29b-41d4-a716-446655440000
                      status: COMPLETED
                      questionSetId: 701
                      error: null
                    meta: *id001
                pending:
                  value:
                    success: true
                    data:
                      jobId: 550e8400-e29b-41d4-a716-446655440000
                      status: IN_PROGRESS
                      questionSetId: null
                      error: null
                    meta: *id001
      description: >
        POST /interview/question-sets 제출 후 jobId로 진행 상태를 폴링한다.
        COMPLETED 시 questionSetId가 채워진다.
        TTL(15분) 만료 후에는 data: null을 반환한다.
  /interview/question-sets/{questionSetId}:
    get:
      tags:
      - Interview
      summary: 면접 질문 세트 상세 조회
      parameters:
      - name: questionSetId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: 질문 세트 상세
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/InterviewQuestionSetDetail'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
              examples:
                questionSetDetailSuccess:
                  value:
                    success: true
                    data:
                      questionSetId: 701
                      applicationId: 401
                      title: 네이버 백엔드 예상 질문 세트
                      questionCount: 2
                      difficultyLevel: medium
                      questions:
                      - id: 801
                        questionOrder: 1
                        questionType: project
                        difficultyLevel: medium
                        questionText: 프로젝트에서 가장 어려웠던 장애 대응 경험을 설명해주세요.
                        parentQuestionId: null
                        sourceApplicationQuestionId: 501
                      - id: 802
                        questionOrder: 2
                        questionType: follow_up
                        difficultyLevel: medium
                        questionText: 그때 어떤 근거로 해결 방안을 선택했나요?
                        parentQuestionId: 801
                        sourceApplicationQuestionId: null
                      createdAt: '2026-03-17T10:34:00Z'
                    meta: *id001
      description: 질문 세트 상세를 조회한다. 세션 시작 전에는 이 상세 화면을 기준으로 질문 검토와 편집을 진행한다.
  /interview/question-sets/{questionSetId}/questions:
    post:
      tags:
      - Interview
      summary: 면접 질문 세트에 수동 질문 추가
      parameters:
      - name: questionSetId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                questionText:
                  type: string
                questionType:
                  type: string
                  enum:
                  - experience
                  - project
                  - technical_cs
                  - technical_stack
                  - behavioral
                  description: 1차 범위에서는 독립 질문만 허용하며 follow_up은 받지 않는다.
                difficultyLevel:
                  type: string
                  enum:
                  - easy
                  - medium
                  - hard
              required:
              - questionText
              - questionType
              - difficultyLevel
      responses:
        '201':
          description: 수동 질문 추가 성공
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/InterviewQuestion'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
              examples:
                manualQuestionAddSuccess:
                  value:
                    success: true
                    data:
                      id: 803
                      questionOrder: 3
                      questionType: behavioral
                      difficultyLevel: medium
                      questionText: 이 회사에 지원한 이유를 설명해주세요.
                      parentQuestionId: null
                      sourceApplicationQuestionId: null
                    meta: *id001
        '400':
          description: 요청 검증 실패
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidManualQuestionRequest:
                  value:
                    success: false
                    error:
                      code: REQUEST_VALIDATION_FAILED
                      message: 요청 값을 확인해주세요.
                      retryable: false
                      fieldErrors:
                      - field: questionText
                        reason: blank
                    meta: *id001
        '404':
          description: 질문 세트를 찾을 수 없음
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                questionSetNotFound:
                  value:
                    success: false
                    error:
                      code: RESOURCE_NOT_FOUND
                      message: 질문 세트를 찾을 수 없습니다.
                      retryable: false
                    meta: *id001
        '409':
          description: 이미 시작된 질문 세트는 편집할 수 없음
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                questionSetNotEditable:
                  value:
                    success: false
                    error:
                      code: INTERVIEW_QUESTION_SET_NOT_EDITABLE
                      message: 이미 면접이 시작된 질문 세트는 수정할 수 없습니다.
                      retryable: false
                    meta: *id001
      description: 세션 시작 전 질문 세트에 수동 질문을 추가한다. questionOrder는 요청으로 받지 않으며 서버가 마지막 순번 다음 값으로
        자동 부여한다. 1차 범위에서는 독립 질문만 허용하고 parentQuestionId는 받지 않는다.
  /interview/question-sets/{questionSetId}/questions/{questionId}:
    delete:
      tags:
      - Interview
      summary: 면접 질문 세트에서 질문 개별 삭제
      parameters:
      - name: questionSetId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      - name: questionId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '400':
          description: 마지막 남은 질문은 삭제할 수 없음
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                lastQuestionDeleteRejected:
                  value:
                    success: false
                    error:
                      code: REQUEST_VALIDATION_FAILED
                      message: 질문 세트는 최소 1개 질문을 유지해야 합니다.
                      retryable: false
                      fieldErrors:
                      - field: questionId
                        reason: min_1
                    meta: *id001
        '404':
          description: 질문 세트 또는 질문을 찾을 수 없음
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                interviewQuestionNotFound:
                  value:
                    success: false
                    error:
                      code: RESOURCE_NOT_FOUND
                      message: 질문을 찾을 수 없습니다.
                      retryable: false
                    meta: *id001
        '409':
          description: 이미 시작된 질문 세트는 편집할 수 없음
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                deleteQuestionSetNotEditable:
                  value:
                    success: false
                    error:
                      code: INTERVIEW_QUESTION_SET_NOT_EDITABLE
                      message: 이미 면접이 시작된 질문 세트는 수정할 수 없습니다.
                      retryable: false
                    meta: *id001
        '204':
          description: 질문 삭제 성공
      description: 세션 시작 전 질문 세트에서 질문을 hard delete 한다. 삭제 후 남은 질문의 questionOrder는 서버가 빈 번호 없이
        1..N 형태로 다시 정렬한다. 질문 세트는 최소 1개 질문을 유지해야 하므로 마지막 남은 질문 삭제는 허용하지 않는다.
  /interview/sessions:
    post:
      tags:
      - Interview
      summary: 모의 면접 세션 시작
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                questionSetId:
                  type: integer
                  format: int64
              required:
              - questionSetId
      responses:
        '201':
          description: 세션 생성
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/InterviewSession'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
              examples:
                sessionStartSuccess:
                  value:
                    success: true
                    data:
                      id: 901
                      questionSetId: 701
                      status: in_progress
                      totalScore: null
                      summaryFeedback: null
                      startedAt: '2026-03-17T10:35:00Z'
                      endedAt: null
                    meta: *id001
        '400':
          description: 질문 수 검증 실패
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                sessionQuestionCountOutOfRange:
                  value:
                    success: false
                    error:
                      code: REQUEST_VALIDATION_FAILED
                      message: 면접 세션은 3개 이상 20개 이하 질문으로만 시작할 수 있습니다.
                      retryable: false
                      fieldErrors:
                      - field: questionCount
                        reason: out_of_range
                    meta: *id001
        '404':
          description: 질문 세트를 찾을 수 없음
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                sessionQuestionSetNotFound:
                  value:
                    success: false
                    error:
                      code: RESOURCE_NOT_FOUND
                      message: 질문 세트를 찾을 수 없습니다.
                      retryable: false
                    meta: *id001
        '409':
          description: 이미 활성 세션이 존재함
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                sessionConflictError:
                  value:
                    success: false
                    error:
                      code: INTERVIEW_SESSION_ALREADY_ACTIVE
                      message: 이미 활성 면접 세션이 있습니다.
                      retryable: false
                    meta: *id001
      description: 면접 세션을 시작한다. 사용자당 동시에 진행 가능한 활성 세션은 1개다. 활성 세션은 `in_progress`와 `paused`
        를 포함한다. 현재 사용자 소유 질문 세트에 대해서만 시작할 수 있으며, 세션 시작 전 질문 세트는 실제 사용 질문 수 기준
        3개 이상 20개 이하인지 검증한다.
    get:
      tags:
      - Interview
      summary: 면접 세션 목록 조회
      responses:
        '200':
          description: 세션 목록
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/InterviewSession'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
              examples:
                sessionListSuccess:
                  value:
                    success: true
                    data:
                    - id: 901
                      questionSetId: 701
                      status: paused
                      totalScore: null
                      summaryFeedback: null
                      startedAt: '2026-03-17T10:35:00Z'
                      endedAt: null
                    meta: *id002
  /interview/sessions/{sessionId}:
    get:
      tags:
      - Interview
      summary: 세션 상세 조회
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: 세션 상세
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/InterviewSessionDetail'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
              examples:
                sessionDetailSuccess:
                  value:
                    success: true
                    data:
                      id: 901
                      questionSetId: 701
                      status: paused
                      currentQuestion:
                        id: 802
                        questionOrder: 2
                        questionType: project
                        difficultyLevel: medium
                        questionText: 프로젝트에서 가장 어려웠던 장애 대응 경험을 설명해주세요.
                      completionFollowupContext: null
                      transcriptEntries:
                      - question:
                          id: 801
                          questionOrder: 1
                          questionType: experience
                          difficultyLevel: easy
                          questionText: 자기소개를 해주세요.
                        answer:
                          answerOrder: 1
                          answerText: 첫 번째 답변입니다.
                          isSkipped: false
                      totalQuestionCount: 5
                      answeredQuestionCount: 1
                      remainingQuestionCount: 4
                      resumeAvailable: true
                      lastActivityAt: '2026-03-17T10:36:00Z'
                      startedAt: '2026-03-17T10:35:00Z'
                      endedAt: null
                    meta: *id001
        '404':
          description: 세션을 찾을 수 없음
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                sessionDetailNotFound:
                  value:
                    success: false
                    error:
                      code: RESOURCE_NOT_FOUND
                      message: 세션을 찾을 수 없습니다.
                      retryable: false
                    meta: *id001
      description: 세션 복원 화면이 한 번의 조회로 그려질 수 있도록 현재 질문, 진행률, 남은 질문 수, resume 가능 여부, 마지막 활동 시각을 함께 반환한다.
        currentQuestion.id는 세션 질문 id이며, 현재 질문은 답변이 없는 세션 질문 중 가장 작은 questionOrder로 계산한다.
        transcriptEntries는 answered question/answer pair만 answerOrder 오름차순으로 포함하며, 현재 미응답 currentQuestion과 system 메시지는 포함하지 않는다.
        Track A 실시간 음성 입력 v1의 현재 interim transcript는 이 응답에 포함하지 않으며, 클라이언트가 현재 답변 작업 영역에서만 관리한다.
        답변 저장 직후 재조회에서는 pending 답변을 로컬 follow-up rule로 먼저 해석한다. `USE_CANDIDATE`면
        `candidateQuestionTypes` 우선순위 기준의 로컬 deterministic follow-up 1개를 즉시 검토한다. `USE_DYNAMIC`이면 runtime
        dynamic follow-up AI 생성을 best-effort로 시도하며, 이 즉시 AI 생성은 세션당 최대 1회만 허용한다. 같은 부모 답변에는 최대
        1개만 확정한다. `NO_FOLLOW_UP`, candidate 템플릿 미선정/미생성, follow-up 생성 null/실패는 세션을 멈추지 않으며 다음 기본
        질문을 currentQuestion으로 반환한다. completion follow-up이 현재 질문이면 `completionFollowupContext`에 root Q/A, runtime
        follow-up Q/A, 현재 completion follow-up 질문을 함께 내려 프론트가 같은 세션 화면 안에서 문맥 카드를 그릴 수 있게 한다.
        v1 자동 일시정지는 이 조회 요청 진입 시점에도 `lastActivityAt` 기준으로 평가하며, 30분 초과 상태의 `in_progress` 세션은
        `paused`로 정규화한다.
  /interview/sessions/{sessionId}/pause:
    post:
      tags:
      - Interview
      summary: 세션 일시정지
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: 일시정지 성공
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/InterviewSessionTransitionData'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
              examples:
                sessionPauseSuccess:
                  value:
                    success: true
                    data:
                      sessionId: 901
                      status: paused
                      updatedAt: '2026-03-17T10:37:00Z'
                    meta: *id001
        '404':
          description: 세션을 찾을 수 없음
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                pauseSessionNotFound:
                  value:
                    success: false
                    error:
                      code: RESOURCE_NOT_FOUND
                      message: 세션을 찾을 수 없습니다.
                      retryable: false
                    meta: *id001
        '409':
          description: 현재 상태에서는 일시정지할 수 없거나 이미 종료된 세션임
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                pauseStatusConflict:
                  value:
                    success: false
                    error:
                      code: INTERVIEW_SESSION_STATUS_CONFLICT
                      message: 현재 상태에서는 세션 상태를 변경할 수 없습니다.
                      retryable: false
                    meta: *id001
                pauseSessionCompleted:
                  value:
                    success: false
                    error:
                      code: INTERVIEW_SESSION_ALREADY_COMPLETED
                      message: 이미 종료된 면접 세션입니다.
                      retryable: false
                    meta: *id001
      description: 진행 중인 세션을 명시적으로 일시정지한다. `pause/resume`은 일반 상태 필드 수정이 아니라 액션 API로 처리한다.
        `pause`는 `in_progress` 상태에서만 허용한다.
  /interview/sessions/{sessionId}/resume:
    post:
      tags:
      - Interview
      summary: 세션 재개
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: 재개 성공
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/InterviewSessionTransitionData'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
              examples:
                sessionResumeSuccess:
                  value:
                    success: true
                    data:
                      sessionId: 901
                      status: in_progress
                      updatedAt: '2026-03-17T10:38:00Z'
                    meta: *id001
        '404':
          description: 세션을 찾을 수 없음
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                resumeSessionNotFound:
                  value:
                    success: false
                    error:
                      code: RESOURCE_NOT_FOUND
                      message: 세션을 찾을 수 없습니다.
                      retryable: false
                    meta: *id001
        '409':
          description: 현재 상태에서는 재개할 수 없거나 이미 종료된 세션임
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                resumeStatusConflict:
                  value:
                    success: false
                    error:
                      code: INTERVIEW_SESSION_STATUS_CONFLICT
                      message: 현재 상태에서는 세션 상태를 변경할 수 없습니다.
                      retryable: false
                    meta: *id001
                resumeSessionCompleted:
                  value:
                    success: false
                    error:
                      code: INTERVIEW_SESSION_ALREADY_COMPLETED
                      message: 이미 종료된 면접 세션입니다.
                      retryable: false
                    meta: *id001
      description: 일시정지된 세션을 재개한다. v1 자동 일시정지 정책은 재개 요청 진입 시점에도 `lastActivityAt` 기준으로 먼저
        평가한다. `resume` 성공 시 `lastActivityAt`는 재개 시각으로 갱신한다.
  /interview/sessions/{sessionId}/answers:
    post:
      tags:
      - Interview
      summary: 세션 답변 제출
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                questionId:
                  type: integer
                  format: int64
                  description: 세션 상세의 currentQuestion.id와 같은 세션 질문 id
                answerOrder:
                  type: integer
                answerText:
                  type: string
                  minLength: 50
                  maxLength: 1000
                  description: 건너뛰기 아닌 일반 답변은 50자 이상 1000자 이하. Track A 실시간 음성 입력 v1에서는 사용자가 확인한 transcript text도 같은 필드로 제출한다.
                isSkipped:
                  type: boolean
              required:
              - questionId
              - answerOrder
              - isSkipped
              description: isSkipped=false인 경우 answerText는 최소 50자 이상이어야 하며, questionId는 현재 세션 질문 id와 일치해야 하고 answerOrder는 다음 제출 순번과 일치해야 한다. Track A 실시간 음성 입력 v1은 raw audio 업로드가 아니라 사용자가 최종 확인한 transcript text를 같은 요청으로 제출한다.
      responses:
        '201':
          description: 답변 저장
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/SessionAnswerSubmitData'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
              examples:
                sessionAnswerSubmitSuccess:
                  value:
                    success: true
                    data:
                      sessionId: 901
                      questionId: 801
                      answerOrder: 1
                      isSkipped: false
                      submittedAt: '2026-03-17T10:36:00Z'
                    meta: *id001
        '400':
          description: 답변 필수 또는 길이 검증 실패
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                answerRequired:
                  value:
                    success: false
                    error:
                      code: INTERVIEW_ANSWER_REQUIRED
                      message: 답변을 입력해주세요.
                      retryable: false
                      fieldErrors:
                      - field: answerText
                        reason: required
                    meta: *id001
                answerTooShort:
                  value:
                    success: false
                    error:
                      code: INTERVIEW_ANSWER_TOO_SHORT
                      message: 답변은 50자 이상 입력해주세요.
                      retryable: false
                      fieldErrors:
                      - field: answerText
                        reason: min_50
                    meta: *id001
        '404':
          description: 세션 또는 질문을 찾을 수 없음
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                sessionOrQuestionNotFound:
                  value:
                    success: false
                    error:
                      code: RESOURCE_NOT_FOUND
                      message: 세션 또는 질문을 찾을 수 없습니다.
                      retryable: false
                    meta: *id001
        '409':
          description: 진행 가능한 세션이 아니거나 이미 종료된 세션임
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                sessionNotActive:
                  value:
                    success: false
                    error:
                      code: INTERVIEW_SESSION_NOT_ACTIVE
                      message: 진행 가능한 면접 세션이 아닙니다. 재개 후 다시 시도해주세요.
                      retryable: false
                    meta: *id001
                sessionAlreadyCompleted:
                  value:
                    success: false
                    error:
                      code: INTERVIEW_SESSION_ALREADY_COMPLETED
                      message: 이미 종료된 면접 세션입니다.
                      retryable: false
                    meta: *id001
      description: 세션 답변을 저장한다. 일반 답변은 `in_progress` 상태에서만 허용한다. questionId는 세션 질문 id이며,
        현재 질문과 일치해야 한다. answerOrder는 다음 제출 순번과 일치해야 한다. 세션 또는 질문이 현재 사용자 범위에서
        없으면 404를 반환한다. Track A 실시간 음성 입력 v1도 raw audio 업로드가 아니라 사용자가 확인한 transcript text를
        `answerText`로 제출하며, 이 endpoint는 답변 저장까지만 담당하고 follow-up 생성 여부는 직접 응답하지 않는다.
        클라이언트는 저장 성공 후 `GET /interview/sessions/{sessionId}`를 재조회해 다음 질문을 확인한다. 재조회 경로에서는 로컬
        rule 결과가 `USE_CANDIDATE`일 때 `candidateQuestionTypes` 기반 로컬 deterministic follow-up을 먼저 검토하고,
        `USE_DYNAMIC`일 때만 runtime dynamic follow-up AI 생성을 검토한다. 세션 마지막 전체 보완 1회는 runtime에서
        follow-up으로 확정되지 못한 positive와 FN을 다시 본다.
        v1 자동 일시정지는 답변 제출 요청 진입 시점에도 `lastActivityAt` 기준으로 평가하며,
        30분 초과 상태의 세션은 `paused`로 정규화한 뒤 답변 제출을 막는다.
  /interview/sessions/{sessionId}/complete:
    post:
      tags:
      - Interview
      summary: 세션 종료 및 결과 생성
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: 세션 완료
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/SessionCompletionData'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
              examples:
                sessionCompleteSuccess:
                  value:
                    success: true
                    data:
                      sessionId: 901
                      status: feedback_completed
                      totalScore: 84
                      summaryFeedback: 기술 선택 근거는 좋았지만 문제 해결 과정의 수치 근거를 더 보강하면 좋습니다.
                      endedAt: '2026-03-17T10:40:00Z'
                    meta: *id001
        '400':
          description: 미답변 질문이 남아 있어 세션을 종료할 수 없음
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                sessionCompleteIncompleteAnswers:
                  value:
                    success: false
                    error:
                      code: REQUEST_VALIDATION_FAILED
                      message: 모든 질문에 답변한 뒤 세션을 종료해주세요.
                      retryable: false
                      fieldErrors:
                      - field: remainingQuestionCount
                        reason: incomplete
                    meta: *id001
        '404':
          description: 세션을 찾을 수 없음
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                sessionCompleteNotFound:
                  value:
                    success: false
                    error:
                      code: RESOURCE_NOT_FOUND
                      message: 세션을 찾을 수 없습니다.
                      retryable: false
                    meta: *id001
        '409':
          description: 이미 종료된 세션에 다시 종료 요청함
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                sessionCompleteAlreadyCompleted:
                  value:
                    success: false
                    error:
                      code: INTERVIEW_SESSION_ALREADY_COMPLETED
                      message: 이미 종료된 면접 세션입니다.
                      retryable: false
                    meta: *id001
        '502':
          description: 면접 결과 생성 실패
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                aiSchemaError:
                  value:
                    success: false
                    error:
                      code: INTERVIEW_RESULT_INCOMPLETE
                      message: 면접 결과 생성 결과가 완전하지 않습니다.
                      retryable: true
                    meta: *id001
        '503':
          description: 면접 결과 생성 timeout 또는 일시 장애
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                aiTimeoutError:
                  value:
                    success: false
                    error:
                      code: EXTERNAL_SERVICE_TEMPORARILY_UNAVAILABLE
                      message: 외부 서비스가 일시적으로 불안정합니다. 잠시 후 다시 시도해주세요.
                      retryable: true
                    meta: *id001
      description: 세션을 종료하고 피드백 결과 생성을 시작한다. 피드백이 즉시 생성되면 feedback_completed 상태로 응답할
        수 있다. `complete`는 `in_progress`, `paused` 상태에서만 허용하며, 미답변 질문이 남아 있으면 400을 반환한다.
        결과 생성 전에 answered root thread 전체를 기준으로 마지막 follow-up 보완 1회를 best-effort로 검토할 수 있다.
        각 thread는 기본 질문/답변과, 이미 존재하면 runtime follow-up 질문/답변까지 함께 본다. 이 마지막 보완은 runtime
        `finalAction`을 hard gate로 쓰지 않으므로 runtime `NO_FOLLOW_UP` 답변이나 runtime follow-up이 이미 있던 thread도
        검토 대상이 될 수 있다. 추가 follow-up이 생성되면 선택된 thread들의 마지막 질문 뒤에 세션 질문으로 이어 붙이고, 세션은
        종료하지 않고 기존 `remainingQuestionCount=incomplete` 400 응답을 반환한다. 프론트는 이 400을 받은 뒤 `GET /interview/sessions/{sessionId}`
        를 다시 호출해 `currentQuestion`과 `completionFollowupContext`를 기준으로 같은 세션 화면 안에서 마지막 보완 질문을 이어서 보여준다.
        마지막 보완이 빈 배열 또는 실패여도 완료 흐름은 계속 진행한다. 답변된 follow-up은 일반 세션 질문과 동일하게 미답변 검증과 결과 생성 입력에 포함한다.
  /interview/sessions/{sessionId}/result:
    get:
      tags:
      - Interview
      summary: 면접 결과 상세 조회
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: 결과 조회
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/InterviewResult'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - success
                - data
                - meta
              examples:
                interviewResultSuccess:
                  value:
                    success: true
                    data:
                      sessionId: 901
                      questionSetId: 701
                      status: feedback_completed
                      totalScore: 84
                      summaryFeedback: 구조는 좋았고 경험 기반 근거를 더 구체화하면 좋습니다.
                      answers:
                      - answerId: 1001
                        questionId: 801
                        questionType: project
                        questionText: 프로젝트에서 가장 어려웠던 장애 대응 경험을 설명해주세요.
                        answerText: Redis 캐시 장애 상황에서 DB 부하를 줄이기 위해 읽기 경로를 단계적으로 우회했습니다.
                        score: 86
                        evaluationRationale: 문제-원인-해결 흐름이 비교적 명확하다.
                        tags:
                        - tagId: 4
                          tagName: 문제 해결 설명 부족
                          tagCategory: content
                      startedAt: '2026-03-17T10:35:00Z'
                      endedAt: '2026-03-17T10:40:00Z'
                    meta: *id001
      description: 세션 결과와 피드백 리포트를 조회한다. answers[].questionId는 세션 질문 id를 사용한다.
        답변된 dynamic follow-up도 answers[]에 일반 질문과 동일하게 포함한다. 완료 직후에는 결과 생성 지연이
        있을 수 있다.
  /followup-rules/analyze:
    post:
      tags:
      - Followup
      summary: follow-up rules 분석
      description: questionType과 answerText만으로 P0 로컬 follow-up 규칙을 분석한다. 면접 세션 runtime gate가 같은 로컬
        rule engine을 사용하며, `finalAction=USE_CANDIDATE`일 때 `candidateQuestionTypes`는 runtime local deterministic
        follow-up 템플릿 선택 우선순위로 해석한다. complete 직전 마지막 보완 검토에서는 이 로컬 rule 결과를 optional runtime
        summary 입력으로 사용할 수 있지만, thread 선택의 hard gate로는 쓰지 않는다. 이 endpoint는 그 결과를 독립적으로 확인하기
        위한 분석 경로다.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FollowupAnalyzeRequest'
      responses:
        '200':
          description: 분석 성공
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FollowupAnalyzeApiResponse'
              examples:
                followupAnalyzeSuccess:
                  value:
                    success: true
                    data:
                      questionType: PROJECT
                      signals:
                        ROLE: true
                        ACTION: true
                        RESULT: false
                        REASON: false
                        METRIC: false
                        CAUSE: false
                        VERIFICATION: false
                        PREVENTION: false
                        ALTERNATIVE: false
                        TRADEOFF: false
                        LIMITATION: false
                        ISSUE: false
                        AGREEMENT: false
                        REFLECTION: false
                        SCOPE_MIXED: false
                      orderedMissingGaps:
                      - RESULT
                      - REASON
                      - METRIC
                      primaryGap: RESULT
                      secondaryGap: REASON
                      finalAction: USE_DYNAMIC
                      candidateQuestionTypes: []
                    meta: *id001
        '400':
          description: 요청 validation 실패
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 인증 필요
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /ai/status:
    get:
      tags:
      - AI
      summary: AI 서비스 가용성 상태 조회
      description: >
        인증 없이 접근 가능. 설정된 AI provider(기본 + fallback)의 가용성 상태를 반환한다.
        available=false이면 estimatedWaitSeconds와 message가 포함된다.
        status 값: "available" | "minute_rate_limited" | "daily_exhausted" | "unavailable"
      security: []
      responses:
        '200':
          description: AI 서비스 가용성 상태
          content:
            application/json:
              schema:
                type: object
                properties:
                  available:
                    type: boolean
                    description: 하나 이상의 provider가 사용 가능한 경우 true
                  estimatedWaitSeconds:
                    type: integer
                    nullable: true
                    description: 모든 provider가 rate limited일 때 예상 대기 초 (available=true면 null)
                  message:
                    type: string
                    nullable: true
                    description: 비가용 상태일 때 사용자에게 표시할 메시지 (available=true면 null)
                  providers:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          example: gemini
                        status:
                          type: string
                          enum: [available, minute_rate_limited, daily_exhausted, unavailable]
                        minuteUsage:
                          type: object
                          properties:
                            used:
                              type: integer
                            limit:
                              type: integer
                            percentage:
                              type: integer
                              description: 사용률 퍼센트 (0-100)
                            resetInSeconds:
                              type: integer
                        dailyUsage:
                          type: object
                          properties:
                            used:
                              type: integer
                            limit:
                              type: integer
                            percentage:
                              type: integer
                              description: 사용률 퍼센트 (0-100)
                            resetsAt:
                              type: string
                              format: date-time
                        tokenUsage:
                          type: object
                          properties:
                            minuteUsed:
                              type: integer
                              format: int64
                            minuteLimit:
                              type: integer
                              format: int64
                            minutePercentage:
                              type: integer
                              description: 분당 토큰 사용률 퍼센트 (0-100)
                            dailyUsed:
                              type: integer
                              format: int64
                            dailyLimit:
                              type: integer
                              format: int64
                              nullable: true
                            dailyPercentage:
                              type: integer
                              nullable: true
                              description: 일간 토큰 사용률 퍼센트 (0-100). dailyLimit이 null이면 null
              examples:
                available:
                  value:
                    available: true
                    providers:
                    - name: gemini
                      status: available
                      minuteUsage:
                        used: 3
                        limit: 10
                        percentage: 30
                        resetInSeconds: 42
                      dailyUsage:
                        used: 57
                        limit: 250
                        percentage: 23
                        resetsAt: '2026-04-02T00:00:00Z'
                      tokenUsage:
                        minuteUsed: 12000
                        minuteLimit: 250000
                        minutePercentage: 5
                        dailyUsed: 230000
                        dailyLimit: null
                        dailyPercentage: null
                    - name: groq
                      status: available
                      minuteUsage:
                        used: 1
                        limit: 30
                        percentage: 3
                        resetInSeconds: 58
                      dailyUsage:
                        used: 120
                        limit: 1000
                        percentage: 12
                        resetsAt: '2026-04-02T00:00:00Z'
                      tokenUsage:
                        minuteUsed: 3000
                        minuteLimit: 12000
                        minutePercentage: 25
                        dailyUsed: 45000
                        dailyLimit: 100000
                        dailyPercentage: 45
                dailyExhausted:
                  value:
                    available: false
                    estimatedWaitSeconds: 32400
                    message: 오늘의 AI 서비스 사용량이 모두 소진되었습니다. 내일 오전 9시 이후 다시 시도해주세요.
                    providers:
                    - name: gemini
                      status: daily_exhausted
                      minuteUsage:
                        used: 0
                        limit: 10
                        percentage: 0
                        resetInSeconds: 0
                      dailyUsage:
                        used: 250
                        limit: 250
                        percentage: 100
                        resetsAt: '2026-04-02T00:00:00Z'
                      tokenUsage:
                        minuteUsed: 0
                        minuteLimit: 250000
                        minutePercentage: 0
                        dailyUsed: 250000
                        dailyLimit: null
                        dailyPercentage: null
                    - name: groq
                      status: daily_exhausted
                      minuteUsage:
                        used: 0
                        limit: 30
                        percentage: 0
                        resetInSeconds: 0
                      dailyUsage:
                        used: 1000
                        limit: 1000
                        percentage: 100
                        resetsAt: '2026-04-02T00:00:00Z'
                      tokenUsage:
                        minuteUsed: 0
                        minuteLimit: 12000
                        minutePercentage: 0
                        dailyUsed: 100000
                        dailyLimit: 100000
                        dailyPercentage: 100
        '503':
          description: AI 서비스 일간 한도 소진
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                dailyLimitExceeded:
                  value:
                    success: false
                    error:
                      code: AI_DAILY_LIMIT_EXCEEDED
                      message: 오늘 Gemini API 일간 한도를 모두 소진했습니다. 내일 오전 9시(KST) 이후 다시 시도해주세요.
                      retryable: false
                      retryAfterSeconds: 32400