openapi.yaml

openapi: 3.0.0
info:
  title: DDD API
  description: 사용자 등록, 출석 및 관리 API입니다.
  version: 0.3.0

servers:
  - url: https://localhost:8000/v1
    description: 로컬 개발 서버

tags:
  - name: health-check
    description: 서버 상태 확인 관련 작업
  - name: authentication
    description: 사용자 인증 관련 작업
  - name: invite-code
    description: 초대코드 관련 작업
  - name: member
    description: 사용자 등록 및 관리 관련 작업
  - name: schedule
    description: 일정 관련 작업
  - name: attendance
    description: 출석 관련 작업

paths:
  /health:
    get:
      tags:
        - health-check
      summary: 서버 헬스 체크
      description: 서버의 상태를 확인하기 위한 헬스 체크 엔드포인트입니다.
      responses:
        '200':
          description: 서버가 정상적으로 작동 중
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: number
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      status:
                        type: string
                        example: "healthy"
                      timestamp:
                        type: string
                        format: date-time
                        description: 요청 시각 (ISO8601 포맷, UTC)
                        example: "2024-10-06T12:34:56Z"

  /oauth/{provider}/authorize:
    get:
      tags:
        - authentication
      summary: 인증 코드 요청
      description: 소셜 로그인 제공자를 통해 인증 코드를 요청합니다. PKCE 사용을 위한 code_challenge와 code_challenge_method를 포함합니다.
      parameters:
        - name: provider
          in: path
          required: true
          schema:
            type: string
            enum: [kakao, apple]
          description: 사용할 소셜 로그인 제공자 (예. kakao, apple)
        - name: code_challenge
          in: query
          required: true
          schema:
            type: string
          description: PKCE code_challenge 값
        - name: code_challenge_method
          in: query
          required: true
          schema:
            type: string
            enum: [plain, S256]
          description: PKCE 코드 검증 방식 (`plain` 또는 `S256`)
      responses:
        '302':
          description: 소셜 로그인 제공자의 인증 페이지로 리다이렉트
        '400':
          description: 요청 파라미터가 잘못된 경우
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /oauth/{provider}/token:
    post:
      tags:
        - authentication
      summary: 토큰 발급
      description: 인증 코드와 함께 code_verifier를 통해 PKCE 검증을 완료하고 액세스 토큰을 발급합니다.
      parameters:
        - name: provider
          in: path
          required: true
          schema:
            type: string
            enum: [kakao, apple]
          description: 사용할 소셜 로그인 제공자 (예. kakao, apple)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  example: authorization_code
                  description: OAuth 인증 유형 (항상 `authorization_code`)
                code:
                  type: string
                  description: 소셜 제공자로부터 받은 인증 코드
                redirect_uri:
                  type: string
                  description: 리디렉션 URI (인증 코드 요청 시 사용한 URI와 동일해야 함)
                code_verifier:
                  type: string
                  description: 클라이언트가 생성한 원래의 code_verifier 값
      responses:
        '200':
          description: 인증이 성공적으로 완료된 경우, 액세스 토큰 반환
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: number
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      access_token:
                        type: string
                        description: 새로 발급된 액세스 토큰
                      refresh_token:
                        type: string
                        description: 새로 발급된 리프레시 토큰
                      expires_in:
                        type: integer
                        description: 액세스 토큰의 만료 시간 (초 단위)
        '400':
          description: 잘못된 요청 (예, 인증 코드 또는 code_verifier가 올바르지 않음)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 인증 실패 (예, code_verifier 검증 실패)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /oauth/{provider}:
    post:
      tags:
        - authentication
      summary: 소셜 로그인
      description: 소셜 제공자의 액세스 토큰을 받아 애플리케이션에서 사용할 자체 토큰을 발급합니다.
      parameters:
        - name: provider
          in: path
          required: true
          schema:
            type: string
            enum: [kakao, apple]
          description: 사용할 소셜 로그인 제공자 (예. kakao, apple)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                access_token:
                  type: string
                  description: 소셜 제공자로부터 받은 액세스 토큰
      responses:
        '200':
          description: 인증이 성공적으로 완료된 경우, 애플리케이션 토큰 반환
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: number
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      access_token:
                        type: string
                        description: 새로 발급된 액세스 토큰
                      refresh_token:
                        type: string
                        description: 새로 발급된 리프레시 토큰
                      expires_in:
                        type: integer
                        description: 액세스 토큰의 만료 시간 (초 단위)
        '400':
          description: 잘못된 요청
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 인증 실패
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /invite-code:
    post:
      tags:
        - invite-code
      summary: 초대코드 생성
      description: 일반 회원 또는 운영진으로 등록할 수 있는 초대코드를 생성합니다.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                invite_type:
                  type: string
                  enum: [normal, moderator]
                  description: 초대코드 유형 (일반 회원 또는 운영진)
              required:
                - invite_type
      responses:
        '201':
          description: 초대코드가 성공적으로 생성되었습니다.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: number
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/InviteCode'
        '400':
          description: 잘못된 요청 데이터
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 인증 실패
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /invite-code/validation:
    post:
      tags:
        - invite-code
      summary: 초대코드 검증
      description: 사용자가 입력한 초대코드의 유효성을 검사합니다.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                invite_code:
                  type: string
                  description: 검증할 초대코드
              required:
                - invite_code
      responses:
        '200':
          description: 초대코드가 유효함
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: number
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      valid:
                        type: boolean
                        description: 초대코드의 유효성 여부.
                      invite_type:
                        type: string
                        enum: [normal, moderator]
                        description: 초대 유형 (일반 회원 또는 운영진).
        '400':
          description: 잘못된 초대코드
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /members:
    post:
      tags:
        - member
      summary: 신규 회원 등록
      description: 초대코드를 사용하여 일반 회원 또는 운영진을 등록합니다.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MemberRegistrationRequest'
      responses:
        '201':
          description: 회원이 성공적으로 등록되었습니다.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: number
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/Member'
        '400':
          description: 잘못된 초대코드 또는 누락된 정보
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /members/{member_id}:
    get:
      tags:
        - member
      summary: 개인 정보 조회
      description: 인증된 사용자의 개인 정보를 조회합니다.
      security:
        - bearerAuth: []
      parameters:
        - name: member_id
          in: path
          required: true
          schema:
            type: string
          description: 조회할 회원의 ID (UUID 사용)
      responses:
        '200':
          description: 개인 정보 조회 성공
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: number
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/Member'
        '401':
          description: 인증 실패
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    delete:
      tags:
        - member
      summary: 회원 탈퇴
      description: 인증된 사용자의 회원 정보를 삭제합니다.
      security:
        - bearerAuth: []
      parameters:
        - name: member_id
          in: path
          required: true
          schema:
            type: string
          description: 삭제할 회원의 ID (UUID 사용)
      responses:
        '200':
          description: 회원 탈퇴 성공
        '401':
          description: 인증 실패
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: 오류로 인한 삭제 실패
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /members/{member_id}/attendance:
    get:
      tags:
        - member
      summary: 회원의 출석 정보 조회
      description: 특정 회원의 출석 정보를 조회합니다.
      security:
        - bearerAuth: []
      parameters:
        - name: member_id
          in: path
          required: true
          schema:
            type: string
          description: 조회할 회원의 ID
      responses:
        '200':
          description: 출석 정보 조회 성공
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: number
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/MemberAttendance'
        '401':
          description: 인증 실패
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /schedules:
    post:
      tags:
        - schedule
      summary: 일정 추가
      description: 새로운 일정을 추가합니다.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScheduleCreationRequest'
      responses:
        '201':
          description: 일정이 성공적으로 추가되었습니다.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: number
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/Schedule'
        '400':
          description: 잘못된 요청 데이터
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    get:
      tags:
        - schedule
      summary: 일정 목록 조회
      description: 모든 기수의 일정 목록을 조회합니다.
      responses:
        '200':
          description: 일정 목록 조회 성공
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: number
                  message:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Schedule'

  /schedules/now:
    get:
      tags:
        - schedule
      summary: 진행중인 일정 조회
      description: 지금 진행중인 일정의 세부 페이지로 redirect 합니다.
      responses:
        '301':
          description: 진행중인 일정으로 redirect 됨 /schedules/{schedule_id}
        '404':
          description: 진행중인 일정이 없음.

  /schedules/{schedule_id}:
    get:
      tags:
        - schedule
      summary: 일정 조회
      description: 특정 일정의 세부 정보를 조회합니다.
      parameters:
        - name: schedule_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: 조회할 일정의 ID (UUID 사용)
      responses:
        '200':
          description: 일정 세부 정보 조회 성공
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: number
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/Schedule'

    put:
      tags:
        - schedule
      summary: 일정 수정
      description: 특정 일정의 정보를 수정합니다.
      security:
        - bearerAuth: []
      parameters:
        - name: schedule_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: 수정할 일정의 ID (UUID 사용)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScheduleModificationRequest'
      responses:
        '200':
          description: 일정 수정 성공
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: number
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/Schedule'
        '400':
          description: 잘못된 요청 데이터
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    delete:
      tags:
        - schedule
      summary: 일정 삭제
      description: 특정 일정을 삭제합니다.
      security:
        - bearerAuth: []
      parameters:
        - name: schedule_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: 삭제할 일정의 ID (UUID 사용)
      responses:
        '200':
          description: 일정 삭제 성공
        '400':
          description: 오류로 인한 삭제 실패
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /schedules/{schedule_id}/attendances:
    post:
      tags:
        - attendance
      summary: 출석 인증 요청
      description: 운영진이 출석 코드를 QR로 스캔하여 현재 이벤트에 출석을 등록합니다.
      security:
        - bearerAuth: []
      parameters:
        - name: schedule_id
          in: path
          required: true
          schema:
            type: string
          description: 출석 인증할 스케줄 ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                attendance_code:
                  type: string
                  description: 사용자가 QR 코드로 제공한 출석 JWT 코드
      responses:
        '201':
          description: 출석이 성공적으로 등록되었습니다.
        '400':
          description: 잘못된 출석 코드 또는 만료된 코드
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 인증 실패
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    get:
      tags:
        - attendance
      summary: 출석 현황 조회
      description: 특정 스케줄의 출석 현황을 조회합니다.
      security:
        - bearerAuth: []
      parameters:
        - name: schedule_id
          in: path
          required: true
          schema:
            type: string
          description: 조회할 스케줄 ID
      responses:
        '200':
          description: 출석 현황 조회 성공
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: number
                  message:
                    type: string
                  data:
                    $ref: "#/components/schemas/ScheduleAttendance"

  /schedules/{schedule_id}/attendances/{member_id}:
    get:
      tags:
        - attendance
      summary: 개별 출석 현황 조회
      description: 특정 스케줄의 개별 출석 현황을 조회합니다.
      security:
        - bearerAuth: []
      parameters:
        - name: schedule_id
          in: path
          required: true
          schema:
            type: string
          description: 조회할 스케줄 ID
        - name: member_id
          in: path
          required: true
          schema:
            type: string
          description: 조회할 멤버 ID
      responses:
        '200':
          description: 출석 현황 조회 성공
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: number
                  message:
                    type: string
                  data:
                    $ref: "#/components/schemas/Attendance"

    patch:
      tags:
        - attendance
      summary: 개별 출석 현황 수정
      description: 특정 스케줄의 개별 출석을 수정합니다.
      security:
        - bearerAuth: []
      parameters:
        - name: schedule_id
          in: path
          required: true
          schema:
            type: string
          description: 수정할 스케줄 ID
        - name: member_id
          in: path
          required: true
          schema:
            type: string
          description: 수정할 멤버 ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Attendance"
      responses:
        '200':
          description: 출석이 성공적으로 수정되었습니다.
        '400':
          description: 잘못된 요청 데이터
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        '401':
          description: 인증 실패
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    InviteCode:
      type: object
      properties:
        code:
          type: string
          description: 등록을 위한 초대코드
        invite_type:
          type: string
          enum: [normal, moderator]
          description: 초대 유형 (일반 회원 또는 운영진)
        created_at:
          type: string
          format: date-time
          description: 생성 시각 (ISO8601 포맷, UTC)
      required:
        - code
        - invite_type
        - created_at

    Schedule:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: 일정 ID (UUID)
        title:
          type: string
          description: 일정 제목
        start_time:
          type: string
          format: date-time
          description: 일정 시작 시간 (ISO8601 포맷, UTC)
        end_time:
          type: string
          format: date-time
          description: 일정 종료 시간 (ISO8601 포맷, UTC)
      required:
        - id
        - title
        - start_time
        - end_time

    ScheduleCreationRequest:
      type: object
      properties:
        title:
          type: string
          description: 일정 제목
        start_time:
          type: string
          format: date-time
          description: 일정 시작 시간
        end_time:
          type: string
          format: date-time
          description: 일정 종료 시간
      required:
        - title
        - start_time
        - end_time

    ScheduleModificationRequest:
      type: object
      properties:
        title:
          type: string
          description: 일정 제목
        start_time:
          type: string
          format: date-time
          description: 일정 시작 시간
        end_time:
          type: string
          format: date-time
          description: 일정 종료 시간
      required:
        - title
        - start_time
        - end_time

    Member:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: 회원 ID (UUID)
        name:
          type: string
          description: 회원 이름
        role:
          type: string
          description: 회원의 직군
        team:
          type: string
          description: 소속 팀
        created_at:
          type: string
          format: date-time
          description: 생성 시각 (ISO8601 포맷, UTC)
      required:
        - id
        - name
        - role
        - team
        - created_at

    MemberRegistrationRequest:
      type: object
      properties:
        invite_code:
          type: string
          description: 등록에 사용할 초대코드
        name:
          type: string
          description: 회원의 이름
        role:
          type: string
          description: 회원의 직군 (예. 개발자, 디자이너 등)
        team:
          type: string
          description: 소속 팀
      required:
        - invite_code
        - name
        - role
        - team

    Attendance:
      type: object
      properties:
        member_id:
          type: string
          format: uuid
          description: 회원 ID (UUID)
        schedule_id:
          type: string
          format: uuid
          description: 스케줄 ID (UUID)
        member_name:
          type: string
          description: 회원 이름
        attendance_status:
          type: string
          enum: [present, late, absent, unknown]
          description: 출석 상태 (출석, 지각, 결석, 정보 없음)
        attendance_time:
          type: string
          format: date-time
          description: 출석이 등록된 시간 (ISO8601 포맷, UTC)
        method:
          type: string
          enum: [qr, manual]
          description: 출석 등록 방법 (QR 코드 또는 수동 등록)
        note:
          type: string
          description: 출석 관련 비고
      required:
        - member_id
        - schedule_id
        - attendance_status

    MemberAttendance:
      type: object
      properties:
        member_id:
          type: string
          format: uuid
          description: 회원 ID (UUID)
        total_attendance:
          type: integer
          description: 총 출석 횟수
        late_count:
          type: integer
          description: 지각 횟수
        absent_count:
          type: integer
          description: 결석 횟수
        attendance_records:
          type: array
          items:
            $ref: '#/components/schemas/Attendance'
      required:
        - member_id
        - total_attendance
        - late_count
        - absent_count
        - attendance_records

    ScheduleAttendance:
      type: object
      properties:
        schedule_id:
          type: string
          format: uuid
          description: 스케줄 ID (UUID)
        attendance_records:
          type: array
          items:
            $ref: '#/components/schemas/Attendance'
      required:
        - schedule_id
        - attendance_records

    ErrorResponse:
      type: object
      properties:
        code:
          type: integer
          description: 오류 코드
        message:
          type: string
          description: 오류 메시지
        data:
          type: object
          properties:
            request_id:
              type: string
              description: 요청 추적을 위한 고유 ID
      required:
        - code
        - message
        - data