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: auth
    description: 사용자 인증 관련 작업
  - name: invite-code
    description: 초대코드 관련 작업
  - name: user
    description: 사용자 등록 및 관리 관련 작업
  - name: qr
    description: QR 코드 관련 작업
  - 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"

  /auth/google/url:
    get:
      tags:
        - auth
      summary: Generate Google Login URL
      description: Endpoint to generate the Google login URL.
      responses:
        200:
          description: Successfully generated the Google login URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  login_url:
                    type: string
                    example: "https://accounts.google.com/o/oauth2/auth"

  /auth/google/login:
    post:
      tags:
        - auth
      summary: Login with Google
      description: Login or register a user using Google auth.
      requestBody:
        description: The payload for logging in with Google.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                access_token:
                  type: string
                  example: "your-google-access-token"
      responses:
        200:
          description: Successfully logged in.
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    example: "your-auth-token"
        400:
          description: Invalid access token or login failed.

  /auth/google/callback:
    get:
      tags:
        - auth
      summary: Google auth Callback
      description: Handle the callback from Google after successful auth.
      responses:
        200:
          description: Successfully logged in and received JWT.
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                    example: "your-jwt-access-token"
                  refresh_token:
                    type: string
                    example: "your-jwt-refresh-token"
        400:
          description: auth failed.

  /auth/token/refresh:
    post:
      tags:
        - auth
      summary: Refresh JWT
      description: Refresh the JWT access token using the refresh token.
      requestBody:
        description: The payload for refreshing the access token.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                refresh_token:
                  type: string
                  example: "your-jwt-refresh-token"
      responses:
        200:
          description: Successfully refreshed the access token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                    example: "new-jwt-access-token"
        400:
          description: Invalid refresh token.

  /auth/token/verify:
    post:
      tags:
        - auth
      summary: Verify JWT
      description: Verify the JWT access token and return the associated user ID.
      requestBody:
        description: The payload for verifying the JWT.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                access_token:
                  type: string
                  example: "your-jwt-access-token"
      responses:
        200:
          description: Successfully verified the JWT and retrieved the user ID.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: number
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      user_id:
                        type: integer
                        example: 123
        400:
          description: Invalid or expired JWT.

  /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: [member, moderator]
                  description: 초대코드 유형 (멤버 또는 운영진)
                expire_time:
                  type: string
                  format: date-time
                  description: 초대코드 만료 시각 (기본 일주일)
                one_time_use:
                  type: boolean
                  default: false
                  description: 초대 코드를 한 번만 사용 가능한 경우 (기본 false)
              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: 사용자가 입력한 초대코드의 유효성을 검사합니다.
      security:
        - bearerAuth: []
      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
                    default: "valid invite code."
                  data:
                    type: object
                    properties:
                      valid:
                        type: boolean
                        description: 초대코드의 유효성 여부.
                      invite_type:
                        type: string
                        enum: [member, moderator]
                        description: 초대 유형 (멤버 또는 운영진).
        '400':
          description: 잘못된 초대코드
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /users:
    post:
      tags:
        - user
      summary: 신규 유저 등록
      description: 초대코드를 사용하여 일반 유저 또는 운영진을 등록합니다.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                invite_code:
                  type: string
                  example: "1234"
                  description: 등록에 사용할 초대코드
                name:
                  type: string
                  example: "김디디"
                  description: 유저의 이름
                tags:
                  type: array
                  example: ["role:member", "position:designer", "team:ios2", "generation:11기"]
                  items:
                    type: string
                    description: 사용자 태그
              required:
                - invite_code
                - name
      responses:
        '201':
          description: 유저가 성공적으로 등록되었습니다.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        '400':
          description: 잘못된 초대코드 또는 누락된 정보
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /users/{user_id}:
    get:
      tags:
        - user
      summary: 유저 정보 조회 ("me" 사용 가능)
      description: 인증된 사용자의 개인 정보를 조회합니다.
      security:
        - bearerAuth: []
      parameters:
        - name: user_id
          required: true
          in: path
          schema:
            type: string
          description: 조회할 유저의 ID (UUID 사용)
      responses:
        '200':
          description: 개인 정보 조회 성공
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: number
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      name:
                        type: string
                        example: "김디디"
                        description: 유저 이름
                      tags:
                        type: array
                        example: ["role:member", "position:designer", "team:ios2", "generation:11기"]
                        items:
                          type: string
                          description: 사용자 태그
        '401':
          description: 인증 실패
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    
    patch:
      tags: 
        - user
      summary: 유저 정보 수정
      description: 유저의 정보를 수정합니다.
      security:
        - bearerAuth: []
      parameters:
        - name: user_id
          required: true
          in: path
          schema:
            type: string
          description: 수정할 유저의 ID (UUID 사용)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: "김디디"
                  description: 유저의 이름
                tags:
                  type: array
                  example: ["role:member", "position:designer", "team:ios2", "generation:11기"]
                  items:
                    type: string
                    description: 사용자 태그
      responses:
        '200':
          description: 개인정보 수정 완료
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"

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

  /users/{user_id}/attendance:
    get:
      tags:
        - user
      summary: 유저의 출석 정보 조회
      description: 특정 유저의 출석 정보를 조회합니다.
      security:
        - bearerAuth: []
      parameters:
        - name: user_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:
                    type: object
                    properties:
                      start_time:
                        type: string
                        format: date-time
                        description: 활동 시작 날짜 (ISO8601 포맷, UTC)
                      end_time:
                        type: string
                        format: date-time
                        description: 활동 종료 날짜 (ISO8601 포맷, UTC)
                      attendance_count:
                        type: integer
                        description: 출석 횟수
                      late_count:
                        type: integer
                        description: 지각 횟수
                      absent_count:
                        type: integer
                        description: 결석 횟수
                      schedules:
                        type: array
                        description: 참석 대상인 모든 스케쥴
                        items:
                          type: object
                          properties:
                            title:
                              type: string
                              example: "직군 세션2"
                              description: 스케쥴 제목
                            description:
                              type: string
                              example: "커리큘럼에 대한 설명 문구 작성"
                              description: 스케쥴 설명 문구
                            schedule_time:
                              type: string
                              format: date-time
                              description: 스케쥴 시간 (ISO8601 포맷, UTC)
                            attendance_status:
                              type: string
                              enum: [tbd, present, late, absent, exception]
                              description: 출석 상태 (미정, 출석, 지각, 결석, 예외)
                            note:
                              type: string
                              example: "군대 훈련으로 인한 결석 등..🧏"
                              description: 출석 관련 비고
        '401':
          description: 인증 실패
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /qr/encode:
    post:
      tags:
        - qr
      summary: QR 문자열 생성
      description: 사용자 ID 및 타임스탬프를 포함하여, QR로 인코딩할 문자열을 생성합니다.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  type: string
                  format: uuid
                  description: 사용자의 ID (UUID)
              required:
                - user_id
      responses:
        '200':
          description: QR 문자열이 성공적으로 생성되었습니다.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: number
                    example: 200
                  message:
                    type: string
                    example: "QR encode success"
                  data:
                    type: object
                    properties:
                      qr_string:
                        type: string
                        example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
                        description: QR 인코딩된 문자열(JWT 등)

  /qr/decode:
    post:
      tags:
        - qr
      summary: QR 문자열 디코딩/검증
      description: QR 문자열을 디코딩한 뒤, 포함된 시간 정보가 유효한지(만료 등)를 검증합니다.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                qr_string:
                  type: string
                  description: 디코딩할 QR 문자열(JWT 등)
              required:
                - qr_string
      responses:
        '200':
          description: 유효한 QR 문자열로부터 정보를 성공적으로 디코딩했습니다.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: number
                    example: 200
                  message:
                    type: string
                    example: "QR decode success"
                  data:
                    type: object
                    properties:
                      user_id:
                        type: string
                        format: uuid
                        description: 디코딩된 사용자 ID (UUID)
                      timestamp:
                        type: string
                        format: date-time
                        description: QR 생성 시간 (ISO8601 포맷, UTC)
        '400':
          description: QR 문자열을 해석할 수 없음 (형식 오류 등)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '410':
          description: QR 정보가 만료되었거나 사용 불가능함
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: QR 문자열은 해독됐지만, 추가적으로 처리할 수 없는 상태 (기타 예외)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /schedules:
    get:
      tags:
        - schedule
      summary: 스케쥴 목록 조회
      description: 스케쥴 목록을 조회합니다.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: 스케쥴 목록
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: number
                  message:
                    type: string
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                          description: 스케쥴 ID (UUID)
                        title:
                          type: string
                          example: "직군 세션2"
                          description: 스케쥴 제목
                        description:
                          type: string
                          example: "커리큘럼에 대한 설명 문구 작성"
                          description: 스케쥴 설명 문구
                        start_time:
                          type: string
                          format: date-time
                          description: 스케쥴 시작 시간 (ISO8601 포맷, UTC)
                        end_time:
                          type: string
                          format: date-time
                          description: 스케쥴 종료 시간 (ISO8601 포맷, UTC)

  /schedules/{schedule_id}:
    get:
      tags:
        - schedule
      summary: 스케쥴 조회 ("now" 사용 가능)
      description: 특정 스케쥴의 세부 정보를 조회합니다.
      security:
        - bearerAuth: []
      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:
                    type: object
                    properties:
                      title:
                        type: string
                        example: "직군 세션2"
                        description: 스케쥴 제목
                      description:
                        type: string
                        example: "커리큘럼에 대한 설명 문구 작성"
                        description: 스케쥴 설명 문구
                      start_time:
                        type: string
                        format: date-time
                        description: 스케쥴 시작 시간 (ISO8601 포맷, UTC)
                      end_time:
                        type: string
                        format: date-time
                        description: 스케쥴 종료 시간 (ISO8601 포맷, UTC)

    patch:
      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:
              type: object
              properties:
                title:
                  type: string
                  example: "직군 세션2"
                  description: 스케쥴 제목
                description:
                  type: string
                  example: "커리큘럼에 대한 설명 문구 작성"
                  description: 스케쥴 설명 문구
                start_time:
                  type: string
                  format: date-time
                  description: 스케쥴 시작 시간 (ISO8601 포맷, UTC)
                end_time:
                  type: string
                  format: date-time
                  description: 스케쥴 종료 시간 (ISO8601 포맷, UTC)
      responses:
        '200':
          description: 스케쥴 수정 성공
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        '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: 스케쥴 삭제 성공
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        '400':
          description: 오류로 인한 삭제 실패
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /schedules/{schedule_id}/attendances:
    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:
                    type: object
                    properties:
                      attendance_count:
                        type: integer
                        description: 출석 인원
                      late_count:
                        type: integer
                        description: 지각 인원
                      absent_count:
                        type: integer
                        description: 결석 인원
                      members:
                        type: array
                        description: 참석 대상인 모든 멤버
                        items:
                          type: object
                          properties:
                            name:
                              type: string
                              example: "김디디"
                              description: 유저 이름
                            tags:
                              type: array
                              example: ["role:member", "position:designer", "team:ios2", "generation:11기"]
                              items:
                                type: string
                                description: 사용자 태그
                            attendance_status:
                              type: string
                              enum: [tbd, present, late, absent, exception]
                              description: 출석 상태 (미정, 출석, 지각, 결석, 예외)
                            note:
                              type: string
                              example: "군대 훈련으로 인한 결석 등..🧏"
                              description: 출석 관련 비고

  /schedules/{schedule_id}/attendances/{user_id}:
    patch:
      tags:
        - attendance
      summary: 출석 수정
      description: 특정 스케줄의 출석을 수정합니다.
      security:
        - bearerAuth: []
      parameters:
        - name: schedule_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: 수정할 스케쥴의 ID (UUID 사용)
        - name: user_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: 수정할 멤버 ID (UUID 사용)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                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
                  example: "군대 훈련으로 인한 결석 등..🧏"
                  description: 출석 관련 비고
      responses:
        '200':
          description: 출석이 성공적으로 수정되었습니다.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        '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: [member, moderator]
          description: 초대 유형 (일반 유저 또는 운영진)
        created_at:
          type: string
          format: date-time
          description: 생성 시각 (ISO8601 포맷, UTC)
      required:
        - code
        - invite_type
        - created_at
    
    SuccessResponse:
      type: object
      properties:
        code:
          type: number
          description: 성공 코드
        message:
          type: string
          example: "success"
          description: 성공 메시지
        data:
          type: object

    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