openapi.v1.yaml

openapi: 3.1.0
info:
  title: O(NlogN) API v1
  version: 1.0.0-draft
  description: |
    O(NlogN) API 계약 스켈레톤.
    이 기준선은 루트 메타데이터, 공통 보안, 재사용 가능한 컴포넌트를 정의한다.
  contact:
    name: O(NlogN) API Team
    url: https://api.onlogn.com
servers:
  - url: https://api.onlogn.com
    description: 운영 환경
  - url: http://localhost:3000
    description: 로컬 개발
security:
  - BearerAuth: []
tags:
  - name: auth
    description: 인증 및 세션 작업.
  - name: users
    description: 인증 사용자 프로필 작업.
  - name: profiles
    description: 공개 프로필 및 프로필 범위 조회 작업.
  - name: groups
    description: 소유자 범위 group 관리 작업.
  - name: tasks
    description: Task CRUD 및 조회 작업.
  - name: calendar
    description: 캘린더 집계 작업.
  - name: reactions
    description: 공개 task reaction 작업.
paths:
  /api/v1/auth/oauth/github/exchange:
    post:
      tags:
        - auth
      summary: GitHub OAuth code 교환
      operationId: exchangeGithubOAuthCode
      description: |
        GitHub OAuth authorization code를 새 access/refresh token으로 교환한다.
        토큰은 JSON 응답 body 필드로만 반환되며 cookies에 중복되지 않는다.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthGithubExchangeRequestEnvelope'
      responses:
        '200':
          description: Access 및 refresh token 발급 성공.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthTokenSuccessEnvelope'
        '400':
          $ref: '#/components/responses/BadRequestProblemResponse'
        '401':
          $ref: '#/components/responses/AuthenticationProblemResponse'
        '429':
          $ref: '#/components/responses/RateLimitProblemResponse'
  /api/v1/auth/refresh:
    post:
      tags:
        - auth
      summary: Refresh token 회전
      operationId: rotateRefreshToken
      description: |
        성공 호출마다 refresh token을 회전하고, 이전에 제시된 token을 즉시 무효화한다.
        이미 무효화된 refresh token을 재사용하면 401 RFC9457 problem details로 실패한다.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthRefreshRequestEnvelope'
      responses:
        '200':
          description: 회전 후 새 access 및 refresh token 발급.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthTokenSuccessEnvelope'
        '400':
          $ref: '#/components/responses/BadRequestProblemResponse'
        '401':
          $ref: '#/components/responses/AuthenticationProblemResponse'
        '429':
          $ref: '#/components/responses/RateLimitProblemResponse'
  /api/v1/auth/logout:
    post:
      tags:
        - auth
      summary: 현재 디바이스 로그아웃
      operationId: logoutCurrentDevice
      description: |
        제공된 refresh token이 나타내는 현재 디바이스 세션만 폐기한다.
        v1 엔드포인트는 전체 디바이스 또는 계정 단위 로그아웃을 수행하지 않는다.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthLogoutRequestEnvelope'
      responses:
        '204':
          description: 현재 디바이스 세션이 폐기되었거나 이미 없음.
          headers:
            X-Request-Id:
              description: 이 성공 로그아웃 요청의 추적 id.
              schema:
                type: string
                example: req_01JZ4T8V6W5X4Y3Z2A1
        '400':
          $ref: '#/components/responses/BadRequestProblemResponse'
        '401':
          $ref: '#/components/responses/AuthenticationProblemResponse'
        '429':
          $ref: '#/components/responses/RateLimitProblemResponse'
  /api/v1/users/me:
    get:
      tags:
        - users
      summary: 현재 인증 사용자 조회
      operationId: getCurrentUser
      description: |
        private 컨텍스트에서 인증 사용자의 전체 프로필 payload를 반환한다.
      responses:
        '200':
          description: 현재 사용자 레코드.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/DataMetaEnvelope'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/UserMeProfile'
              example:
                data:
                  id: 123e4567-e89b-12d3-a456-426614174000
                  profile_slug: johndoe
                  email: user@example.com
                  display_name: John Doe
                  avatar_url: https://cdn.onlogn.com/avatars/user.png
                  timezone: UTC
                  created_at: 2025-01-01T00:00:00Z
                  updated_at: 2025-01-01T01:00:00Z
        '401':
          $ref: '#/components/responses/ProblemResponse'
        '500':
          $ref: '#/components/responses/ProblemResponse'
  /api/v1/profiles/{slug}:
    get:
      tags:
        - profiles
      summary: slug로 공개 프로필 조회
      operationId: getProfileBySlug
      description: |
        지정된 slug에 대해 공개 allowlist 프로필 객체를 반환한다.
      security: []
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
          description: 공개 프로필 slug.
      responses:
        '200':
          description: 공개 프로필 payload.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/DataMetaEnvelope'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/ProfilePublic'
              example:
                data:
                  profile_slug: johndoe
                  display_name: John Doe
                  avatar_url: https://cdn.onlogn.com/avatars/user.png
                  bio: Product designer focused on clear systems.
                  timezone: UTC
                  created_at: 2025-01-01T00:00:00Z
                  stats_summary:
                    total_tasks: 12
                    done_tasks: 8
                    in_progress_tasks: 3
                    todo_tasks: 1
        '404':
          $ref: '#/components/responses/ProblemResponse'
        '500':
          $ref: '#/components/responses/ProblemResponse'
  /api/v1/groups:
    get:
      tags:
        - groups
      summary: group 목록 조회
      operationId: listGroups
      description: |
        인증 사용자를 위한 owner 범위 group 목록.
      parameters:
        - $ref: '#/components/parameters/OffsetParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Group 목록.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupListResponse'
        '400':
          $ref: '#/components/responses/ProblemResponse'
        '401':
          $ref: '#/components/responses/ProblemResponse'
        '403':
          $ref: '#/components/responses/ProblemResponse'
        '429':
          $ref: '#/components/responses/ProblemResponse'
        '500':
          $ref: '#/components/responses/ProblemResponse'
    post:
      tags:
        - groups
      summary: group 생성
      operationId: createGroup
      description: |
        새 owner 범위 group을 생성한다.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupCreateRequest'
      responses:
        '201':
          description: Group 생성 완료.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
        '400':
          $ref: '#/components/responses/ProblemResponse'
        '401':
          $ref: '#/components/responses/ProblemResponse'
        '403':
          $ref: '#/components/responses/ProblemResponse'
        '422':
          $ref: '#/components/responses/ValidationProblemResponse'
        '429':
          $ref: '#/components/responses/ProblemResponse'
        '500':
          $ref: '#/components/responses/ProblemResponse'
  /api/v1/groups/{group_id}:
    get:
      tags:
        - groups
      summary: group 조회
      operationId: getGroup
      description: |
        owner 범위에서 단일 group을 조회한다.
      parameters:
        - name: group_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Group 상세.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
        '401':
          $ref: '#/components/responses/ProblemResponse'
        '403':
          $ref: '#/components/responses/ProblemResponse'
        '404':
          $ref: '#/components/responses/ProblemResponse'
        '429':
          $ref: '#/components/responses/ProblemResponse'
        '500':
          $ref: '#/components/responses/ProblemResponse'
    patch:
      tags:
        - groups
      summary: group 수정
      operationId: updateGroup
      description: |
        owner 범위 group 메타데이터(visibility, description, color, icon)를 수정한다.
      parameters:
        - name: group_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupUpdateRequest'
      responses:
        '200':
          description: Group 수정 완료.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
        '401':
          $ref: '#/components/responses/ProblemResponse'
        '403':
          $ref: '#/components/responses/ProblemResponse'
        '404':
          $ref: '#/components/responses/ProblemResponse'
        '422':
          $ref: '#/components/responses/ValidationProblemResponse'
        '429':
          $ref: '#/components/responses/ProblemResponse'
        '500':
          $ref: '#/components/responses/ProblemResponse'
    delete:
      tags:
        - groups
      summary: group 삭제
      operationId: deleteGroup
      description: |
        소유한 group을 삭제한다. 연결된 task는 `group_id = null`로 재할당된다.
      parameters:
        - name: group_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: |
            Group 삭제 완료, 연결된 task를 `group_id = null`로 재할당.
          headers:
            X-Request-Id:
              description: 이 성공 삭제 요청의 추적 id.
              schema:
                type: string
                example: req_01JZ4T8V6W5X4Y3Z2A1
        '401':
          $ref: '#/components/responses/ProblemResponse'
        '403':
          $ref: '#/components/responses/ProblemResponse'
        '404':
          $ref: '#/components/responses/ProblemResponse'
        '409':
          $ref: '#/components/responses/ProblemResponse'
        '429':
          $ref: '#/components/responses/ProblemResponse'
        '500':
          $ref: '#/components/responses/ProblemResponse'
  /api/v1/tasks:
    get:
      tags:
        - tasks
      summary: owner task 목록 조회
      operationId: listTasks
      description: |
        인증 사용자를 위한 owner 범위 task 목록.
        기준 정렬은 `created_at desc`, 타이브레이커는 `id desc`다.
      parameters:
        - $ref: '#/components/parameters/OffsetParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/TaskStatusParam'
        - $ref: '#/components/parameters/TaskVisibilityParam'
        - $ref: '#/components/parameters/TaskGroupIdParam'
        - $ref: '#/components/parameters/TaskDueDateFromParam'
        - $ref: '#/components/parameters/TaskDueDateToParam'
        - $ref: '#/components/parameters/TaskSortParam'
      responses:
        '200':
          description: Task 목록.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskListResponse'
        '400':
          $ref: '#/components/responses/ProblemResponse'
        '401':
          $ref: '#/components/responses/ProblemResponse'
        '403':
          $ref: '#/components/responses/ProblemResponse'
        '500':
          $ref: '#/components/responses/ProblemResponse'
    post:
      tags:
        - tasks
      summary: owner task 생성
      operationId: createTask
      description: 인증 owner 범위에서 task를 생성한다.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskCreateRequest'
      responses:
        '201':
          description: Task 생성 완료.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResponse'
        '401':
          $ref: '#/components/responses/ProblemResponse'
        '403':
          $ref: '#/components/responses/ProblemResponse'
        '422':
          $ref: '#/components/responses/ValidationProblemResponse'
        '500':
          $ref: '#/components/responses/ProblemResponse'
  /api/v1/tasks/{task_id}:
    get:
      tags:
        - tasks
      summary: owner task 조회
      operationId: getTask
      description: owner 범위 단일 task를 조회한다.
      parameters:
        - $ref: '#/components/parameters/TaskIdParam'
      responses:
        '200':
          description: Task 상세.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResponse'
        '401':
          $ref: '#/components/responses/ProblemResponse'
        '403':
          $ref: '#/components/responses/ProblemResponse'
        '404':
          $ref: '#/components/responses/ProblemResponse'
        '500':
          $ref: '#/components/responses/ProblemResponse'
    patch:
      tags:
        - tasks
      summary: owner task 수정
      operationId: updateTask
      description: owner 범위 task의 변경 가능한 필드를 수정한다.
      parameters:
        - $ref: '#/components/parameters/TaskIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskUpdateRequest'
      responses:
        '200':
          description: Task 수정 완료.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResponse'
        '401':
          $ref: '#/components/responses/ProblemResponse'
        '403':
          $ref: '#/components/responses/ProblemResponse'
        '404':
          $ref: '#/components/responses/ProblemResponse'
        '422':
          $ref: '#/components/responses/ValidationProblemResponse'
        '500':
          $ref: '#/components/responses/ProblemResponse'
    delete:
      tags:
        - tasks
      summary: owner task 삭제
      operationId: deleteTask
      description: owner 범위 task를 삭제한다.
      parameters:
        - $ref: '#/components/parameters/TaskIdParam'
      responses:
        '204':
          description: Task 삭제 완료.
          headers:
            X-Request-Id:
              description: 이 성공 삭제 요청의 추적 id.
              schema:
                type: string
                example: req_01JZ4T8V6W5X4Y3Z2A1
        '401':
          $ref: '#/components/responses/ProblemResponse'
        '403':
          $ref: '#/components/responses/ProblemResponse'
        '404':
          $ref: '#/components/responses/ProblemResponse'
        '500':
          $ref: '#/components/responses/ProblemResponse'
  /api/v1/profiles/{slug}/tasks:
    get:
      tags:
        - profiles
        - tasks
      summary: profile slug 기준 공개 task 목록 조회
      operationId: listProfileTasks
      description: |
        지정된 profile slug의 공개 task만 반환한다.
        서버가 public visibility 경계를 강제한다.
      security: []
      parameters:
        - $ref: '#/components/parameters/ProfileSlugParam'
        - $ref: '#/components/parameters/OffsetParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/TaskStatusParam'
        - $ref: '#/components/parameters/TaskGroupIdParam'
        - $ref: '#/components/parameters/TaskDueDateFromParam'
        - $ref: '#/components/parameters/TaskDueDateToParam'
        - $ref: '#/components/parameters/TaskSortParam'
      responses:
        '200':
          description: profile의 공개 task 목록.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskListResponse'
        '400':
          $ref: '#/components/responses/ProblemResponse'
        '404':
          $ref: '#/components/responses/ProblemResponse'
        '500':
          $ref: '#/components/responses/ProblemResponse'
  /api/v1/tasks/calendar/monthly:
    get:
      tags:
        - tasks
        - calendar
      summary: 월간 task 캘린더 조회
      operationId: getMonthlyTaskCalendar
      description: |
        요청한 `(year, month)`에 대해 0 값으로 채운 날짜를 포함해 완전한 일자 버킷을 반환한다.
      parameters:
        - $ref: '#/components/parameters/CalendarYearParam'
        - $ref: '#/components/parameters/CalendarMonthParam'
      responses:
        '200':
          description: 월간 캘린더 집계.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskMonthlyCalendarResponse'
        '400':
          $ref: '#/components/responses/ProblemResponse'
        '401':
          $ref: '#/components/responses/ProblemResponse'
        '500':
          $ref: '#/components/responses/ProblemResponse'
  /api/v1/tasks/{task_id}/reactions:
    get:
      tags:
        - tasks
        - reactions
      summary: 공개 task reaction 목록 조회
      operationId: listTaskReactions
      description: 공개 task의 reaction 집계를 반환한다.
      security: []
      parameters:
        - $ref: '#/components/parameters/TaskIdParam'
      responses:
        '200':
          description: Reaction 목록.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskReactionListResponse'
        '404':
          $ref: '#/components/responses/ProblemResponse'
        '500':
          $ref: '#/components/responses/ProblemResponse'
    post:
      tags:
        - tasks
        - reactions
      summary: 공개 task reaction 토글
      operationId: toggleTaskReaction
      description: |
        공개 task에서 사용자별, 이모지별 reaction을 토글한다.
        `(user_id, task_id, emoji)` 조합마다 논리적 reaction 행은 하나다.
      parameters:
        - $ref: '#/components/parameters/TaskIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskReactionToggleRequest'
      responses:
        '200':
          description: Reaction 상태 토글 완료.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskReactionMutationResponse'
        '401':
          $ref: '#/components/responses/ProblemResponse'
        '404':
          $ref: '#/components/responses/ProblemResponse'
        '422':
          $ref: '#/components/responses/ValidationProblemResponse'
        '500':
          $ref: '#/components/responses/ProblemResponse'
    delete:
      tags:
        - tasks
        - reactions
      summary: 공개 task reaction 제거
      operationId: removeTaskReaction
      description: 공개 task에서 현재 사용자의 특정 emoji reaction을 제거한다.
      parameters:
        - $ref: '#/components/parameters/TaskIdParam'
        - $ref: '#/components/parameters/ReactionEmojiParam'
      responses:
        '200':
          description: Reaction 제거 완료.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskReactionMutationResponse'
        '401':
          $ref: '#/components/responses/ProblemResponse'
        '404':
          $ref: '#/components/responses/ProblemResponse'
        '422':
          $ref: '#/components/responses/ValidationProblemResponse'
        '500':
          $ref: '#/components/responses/ProblemResponse'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        보호 엔드포인트를 위한 access token 전달 방식.
        auth 엔드포인트에서는 토큰을 JSON 응답 body로 전달한다.
  parameters:
    OffsetParam:
      name: offset
      in: query
      description: 목록 페이지네이션용 0 기반 offset.
      required: false
      schema:
        type: integer
        minimum: 0
        default: 0
    LimitParam:
      name: limit
      in: query
      description: 목록 페이지네이션용 페이지 크기.
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    ProfileSlugParam:
      name: slug
      in: path
      description: 공개 프로필 slug.
      required: true
      schema:
        type: string
        minLength: 1
    TaskIdParam:
      name: task_id
      in: path
      description: Task 식별자.
      required: true
      schema:
        type: string
        format: uuid
    TaskStatusParam:
      name: status
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/TaskStatus'
    TaskVisibilityParam:
      name: visibility
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/TaskVisibility'
    TaskGroupIdParam:
      name: group_id
      in: query
      required: false
      description: 그룹 미지정 task를 위한 UUID group id 또는 리터럴 `null`.
      schema:
        oneOf:
          - type: string
            format: uuid
          - type: string
            const: 'null'
    TaskDueDateFromParam:
      name: due_date_from
      in: query
      required: false
      schema:
        type: string
        format: date
    TaskDueDateToParam:
      name: due_date_to
      in: query
      required: false
      schema:
        type: string
        format: date
    TaskSortParam:
      name: sort
      in: query
      description: v1에서는 `created_at desc`만 허용한다.
      required: false
      schema:
        type: string
        enum:
          - created_at desc
        default: created_at desc
    CalendarYearParam:
      name: year
      in: query
      required: true
      schema:
        type: integer
        minimum: 1970
        maximum: 2100
    CalendarMonthParam:
      name: month
      in: query
      required: true
      schema:
        type: integer
        minimum: 1
        maximum: 12
    ReactionEmojiParam:
      name: emoji
      in: query
      required: true
      schema:
        type: string
        minLength: 1
  schemas:
    TaskStatus:
      type: string
      enum:
        - todo
        - in_progress
        - done
    TaskVisibility:
      type: string
      enum:
        - private
        - public
    AuthGithubExchangeRequestData:
      type: object
      required:
        - code
      properties:
        code:
          type: string
          description: GitHub OAuth가 발급한 authorization code.
          minLength: 1
          example: gh_oauth_code_123
    AuthGithubExchangeRequestEnvelope:
      type: object
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/AuthGithubExchangeRequestData'
    AuthRefreshRequestData:
      type: object
      required:
        - refresh_token
      properties:
        refresh_token:
          type: string
          description: 현재 클라이언트가 보유한 refresh token.
          minLength: 1
          example: rf_01JZ4T3Q8R9A2F4M7N6
    AuthRefreshRequestEnvelope:
      type: object
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/AuthRefreshRequestData'
    AuthLogoutRequestData:
      type: object
      required:
        - refresh_token
      properties:
        refresh_token:
          type: string
          description: 현재 디바이스 세션 폐기를 위한 refresh token.
          minLength: 1
          example: rf_01JZ4T3Q8R9A2F4M7N6
    AuthLogoutRequestEnvelope:
      type: object
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/AuthLogoutRequestData'
    AuthTokenPayload:
      type: object
      required:
        - access_token
        - refresh_token
        - token_type
        - expires_in
        - refresh_expires_in
      properties:
        access_token:
          type: string
          minLength: 1
          description: 보호된 API 작업용 access token.
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        refresh_token:
          type: string
          minLength: 1
          description: 회전용 1회 사용 refresh token.
          example: rf_01JZ4T3Q8R9A2F4M7N6
        token_type:
          type: string
          enum:
            - Bearer
          description: Authorization token 유형.
          example: Bearer
        expires_in:
          type: integer
          minimum: 1
          description: access token TTL(초).
          example: 900
        refresh_expires_in:
          type: integer
          minimum: 1
          description: refresh token TTL(초).
          example: 1209600
    AuthTokenSuccessEnvelope:
      type: object
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/AuthTokenPayload'
      example:
        data:
          access_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example
          refresh_token: rf_01JZ4T3Q8R9A2F4M7N6
          token_type: Bearer
          expires_in: 900
          refresh_expires_in: 1209600
    Problem:
      type: object
      description: RFC9457 problem details 객체.
      required:
        - type
        - title
        - status
        - detail
        - instance
      properties:
        type:
          type: string
          format: uri
          description: 안정적인 problem type URI.
          example: https://api.onlogn.com/problems/resource-not-found
        title:
          type: string
          description: problem type의 짧고 사람이 읽을 수 있는 요약.
          example: Resource Not Found
        status:
          type: integer
          description: HTTP 상태 코드.
          minimum: 100
          maximum: 599
          example: 404
        detail:
          type: string
          description: 이 발생 건에 대한 사람이 읽을 수 있는 설명.
          example: Requested resource does not exist.
        instance:
          type: string
          description: 해당 problem 발생 건을 가리키는 URI 참조.
          example: /api/v1/tasks/req_01JZ4T3Q8R9A2F4M7N6
        request_id:
          type: string
          description: 지원 및 관측을 위한 추적 식별자.
    ValidationErrorItem:
      type: object
      required:
        - field
        - reason
      properties:
        field:
          type: string
          description: 유효하지 않은 요청 필드 이름.
          example: status
        reason:
          type: string
          description: 검증 실패 사유.
          example: "must be one of: todo, in_progress, done"
    ValidationProblem:
      allOf:
        - $ref: '#/components/schemas/Problem'
        - type: object
          properties:
            errors:
              type: array
              items:
                $ref: '#/components/schemas/ValidationErrorItem'
    PaginationMeta:
      type: object
      description: 목록 응답용 공통 페이지네이션 메타데이터.
      required:
        - offset
        - limit
        - total
        - sort
      properties:
        offset:
          type: integer
          minimum: 0
          example: 0
        limit:
          type: integer
          minimum: 1
          maximum: 100
          example: 20
        total:
          type: integer
          minimum: 0
          example: 125
        sort:
          type: string
          description: 결정적인 정렬 표현식.
          example: created_at desc, id desc
    ListMeta:
      type: object
      description: 목록 응답을 위한 공통 `meta` 객체 기준선.
      required:
        - pagination
      properties:
        pagination:
          $ref: '#/components/schemas/PaginationMeta'
    DataMetaEnvelope:
      type: object
      description: 공통 성공 envelope 기준선(`data` + optional `meta`).
      required:
        - data
      properties:
        data:
          description: 작업 payload, 구체 스키마는 엔드포인트별로 정의된다.
        meta:
          description: 목록/집계 응답용 선택 메타데이터.
          $ref: '#/components/schemas/ListMeta'
    UserMeProfile:
      type: object
      description: "`/api/v1/users/me`용 인증 사용자 payload."
      required:
        - id
        - profile_slug
        - email
        - display_name
        - avatar_url
        - timezone
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
          example: 123e4567-e89b-12d3-a456-426614174000
        profile_slug:
          type: string
          example: johndoe
        email:
          type: string
          format: email
          nullable: true
          example: user@example.com
        display_name:
          type: string
          example: John Doe
        avatar_url:
          type: string
          format: uri
          nullable: true
          example: https://cdn.onlogn.com/avatars/user.png
        timezone:
          type: string
          example: UTC
        created_at:
          type: string
          format: date-time
          example: 2025-01-01T00:00:00Z
        updated_at:
          type: string
          format: date-time
          example: 2025-01-01T01:00:00Z
    ProfilePublic:
      type: object
      description: "`/api/v1/profiles/{slug}`에서 공개되는 profile 필드."
      required:
        - profile_slug
        - display_name
        - avatar_url
        - bio
        - timezone
        - created_at
        - stats_summary
      properties:
        profile_slug:
          type: string
          example: johndoe
        display_name:
          type: string
          example: John Doe
        avatar_url:
          type: string
          format: uri
          nullable: true
          example: https://cdn.onlogn.com/avatars/user.png
        bio:
          type: string
          nullable: true
          example: Product designer focused on clear systems.
        timezone:
          type: string
          example: UTC
        created_at:
          type: string
          format: date-time
          example: 2025-01-01T00:00:00Z
        stats_summary:
          $ref: '#/components/schemas/ProfileStatsSummary'
    ProfileStatsSummary:
      type: object
      description: 공개 profile 응답에 포함되는 집계 task 통계.
      required:
        - total_tasks
        - done_tasks
        - in_progress_tasks
        - todo_tasks
      properties:
        total_tasks:
          type: integer
          minimum: 0
          example: 12
        done_tasks:
          type: integer
          minimum: 0
          example: 8
        in_progress_tasks:
          type: integer
          minimum: 0
          example: 3
        todo_tasks:
          type: integer
          minimum: 0
          example: 1
    Group:
      type: object
      description: Group 리소스 표현.
      required:
        - id
        - owner_user_id
        - visibility
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
          example: 123e4567-e89b-12d3-a456-426614174001
        owner_user_id:
          type: string
          format: uuid
          example: 123e4567-e89b-12d3-a456-426614174000
        visibility:
          type: string
          enum:
            - private
            - public
          default: private
          description: |
            group의 visibility 정책 (`private|public`).
        description:
          type: string
          nullable: true
          default: null
          description: 선택 설명 텍스트.
          example: Weekly planning workspace.
        color:
          type: string
          nullable: true
          default: null
          description: 선택 UI 강조 색상 토큰.
          example: '#4f46e5'
        icon:
          type: string
          nullable: true
          default: null
          description: 선택 UI 아이콘 토큰.
          example: folder
        created_at:
          type: string
          format: date-time
          example: 2026-02-01T09:00:00Z
        updated_at:
          type: string
          format: date-time
          example: 2026-02-01T09:15:00Z
    GroupCreateRequest:
      type: object
      required:
        - visibility
      properties:
        visibility:
          type: string
          enum:
            - private
            - public
          default: private
          description: |
            group visibility 정책 (`private|public`).
        description:
          type: string
          nullable: true
          description: 선택 설명 텍스트.
          example: New group for high priority work.
        color:
          type: string
          nullable: true
          description: 선택 UI 강조 색상 토큰.
          example: '#f97316'
        icon:
          type: string
          nullable: true
          description: 선택 UI 아이콘 토큰.
          example: star
    GroupUpdateRequest:
      type: object
      properties:
        visibility:
          type: string
          enum:
            - private
            - public
          description: |
            group visibility 정책 (`private|public`).
        description:
          type: string
          nullable: true
          description: 선택 설명 텍스트.
          example: Updated notes for this group.
        color:
          type: string
          nullable: true
          description: 선택 UI 강조 색상 토큰.
          example: '#0ea5e9'
        icon:
          type: string
          nullable: true
          description: 선택 UI 아이콘 토큰.
          example: tag
    GroupResponse:
      allOf:
        - $ref: '#/components/schemas/DataMetaEnvelope'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/Group'
      example:
        data:
          id: 123e4567-e89b-12d3-a456-426614174001
          owner_user_id: 123e4567-e89b-12d3-a456-426614174000
          visibility: private
          description: Weekly planning workspace.
          color: '#4f46e5'
          icon: folder
          created_at: 2026-02-01T09:00:00Z
          updated_at: 2026-02-01T09:15:00Z
    GroupListResponse:
      allOf:
        - $ref: '#/components/schemas/DataMetaEnvelope'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/Group'
            meta:
              $ref: '#/components/schemas/ListMeta'
      example:
        data:
          - id: 123e4567-e89b-12d3-a456-426614174001
            owner_user_id: 123e4567-e89b-12d3-a456-426614174000
            visibility: private
            description: Weekly planning workspace.
            color: '#4f46e5'
            icon: folder
            created_at: 2026-02-01T09:00:00Z
            updated_at: 2026-02-01T09:15:00Z
        meta:
          pagination:
            offset: 0
            limit: 20
            total: 1
            sort: created_at desc, id desc
    Task:
      type: object
      description: Task 리소스 표현.
      required:
        - id
        - owner_user_id
        - group_id
        - title
        - status
        - visibility
        - created_at
        - updated_at
        - due_date
        - start_time
        - end_time
        - tags
        - reference_links
      properties:
        id:
          type: string
          format: uuid
        owner_user_id:
          type: string
          format: uuid
        group_id:
          oneOf:
            - type: string
              format: uuid
            - type: 'null'
          default: null
        title:
          type: string
          minLength: 1
        status:
          $ref: '#/components/schemas/TaskStatus'
        visibility:
          $ref: '#/components/schemas/TaskVisibility'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        due_date:
          oneOf:
            - type: string
              format: date
            - type: 'null'
          default: null
        start_time:
          oneOf:
            - type: string
              format: date-time
            - type: 'null'
          default: null
        end_time:
          oneOf:
            - type: string
              format: date-time
            - type: 'null'
          default: null
        tags:
          type: array
          items:
            type: string
          default: []
        reference_links:
          type: array
          items:
            type: string
            format: uri
          default: []
    TaskCreateRequest:
      type: object
      required:
        - title
      properties:
        group_id:
          oneOf:
            - type: string
              format: uuid
            - type: 'null'
        title:
          type: string
          minLength: 1
        status:
          $ref: '#/components/schemas/TaskStatus'
        visibility:
          $ref: '#/components/schemas/TaskVisibility'
        due_date:
          oneOf:
            - type: string
              format: date
            - type: 'null'
        start_time:
          oneOf:
            - type: string
              format: date-time
            - type: 'null'
        end_time:
          oneOf:
            - type: string
              format: date-time
            - type: 'null'
        tags:
          type: array
          items:
            type: string
        reference_links:
          type: array
          items:
            type: string
            format: uri
      additionalProperties: false
    TaskUpdateRequest:
      type: object
      properties:
        group_id:
          oneOf:
            - type: string
              format: uuid
            - type: 'null'
        title:
          type: string
          minLength: 1
        status:
          $ref: '#/components/schemas/TaskStatus'
        visibility:
          $ref: '#/components/schemas/TaskVisibility'
        due_date:
          oneOf:
            - type: string
              format: date
            - type: 'null'
        start_time:
          oneOf:
            - type: string
              format: date-time
            - type: 'null'
        end_time:
          oneOf:
            - type: string
              format: date-time
            - type: 'null'
        tags:
          type: array
          items:
            type: string
        reference_links:
          type: array
          items:
            type: string
            format: uri
      additionalProperties: false
    TaskResponse:
      allOf:
        - $ref: '#/components/schemas/DataMetaEnvelope'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/Task'
      example:
        data:
          id: 123e4567-e89b-12d3-a456-426614174002
          owner_user_id: 123e4567-e89b-12d3-a456-426614174000
          group_id: 123e4567-e89b-12d3-a456-426614174001
          title: Prepare sprint handoff
          status: in_progress
          visibility: private
          created_at: 2026-02-10T09:00:00Z
          updated_at: 2026-02-10T10:30:00Z
          due_date: 2026-02-12
          start_time: 2026-02-10T09:00:00Z
          end_time: null
          tags:
            - planning
            - backend
          reference_links:
            - https://docs.onlogn.com/specs/sprint-handoff
    TaskListResponse:
      allOf:
        - $ref: '#/components/schemas/DataMetaEnvelope'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/Task'
            meta:
              $ref: '#/components/schemas/ListMeta'
      example:
        data:
          - id: 123e4567-e89b-12d3-a456-426614174002
            owner_user_id: 123e4567-e89b-12d3-a456-426614174000
            group_id: 123e4567-e89b-12d3-a456-426614174001
            title: Prepare sprint handoff
            status: in_progress
            visibility: private
            created_at: 2026-02-10T09:00:00Z
            updated_at: 2026-02-10T10:30:00Z
            due_date: 2026-02-12
            start_time: 2026-02-10T09:00:00Z
            end_time: null
            tags:
              - planning
              - backend
            reference_links:
              - https://docs.onlogn.com/specs/sprint-handoff
        meta:
          pagination:
            offset: 0
            limit: 20
            total: 1
            sort: created_at desc, id desc
    TaskMonthlyCalendarDay:
      type: object
      required:
        - date
        - planned_count
        - done_count
        - in_progress_count
        - completion_rate
      properties:
        date:
          type: string
          format: date
        planned_count:
          type: integer
          minimum: 0
          default: 0
        done_count:
          type: integer
          minimum: 0
          default: 0
        in_progress_count:
          type: integer
          minimum: 0
          default: 0
        completion_rate:
          type: number
          minimum: 0
          maximum: 100
          description: 일일 완료율 백분율 범위 0..100.
          default: 0
    TaskMonthlyCalendarMeta:
      type: object
      required:
        - year
        - month
        - timezone
      properties:
        year:
          type: integer
          minimum: 1970
          maximum: 2100
        month:
          type: integer
          minimum: 1
          maximum: 12
        timezone:
          type: string
    TaskMonthlyCalendarResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TaskMonthlyCalendarDay'
        meta:
          $ref: '#/components/schemas/TaskMonthlyCalendarMeta'
      example:
        data:
          - date: 2026-02-01
            planned_count: 2
            done_count: 1
            in_progress_count: 1
            completion_rate: 50
          - date: 2026-02-02
            planned_count: 0
            done_count: 0
            in_progress_count: 0
            completion_rate: 0
        meta:
          year: 2026
          month: 2
          timezone: Asia/Seoul
    TaskReaction:
      type: object
      required:
        - task_id
        - emoji
        - count
        - requester_reacted
      properties:
        task_id:
          type: string
          format: uuid
        emoji:
          type: string
          minLength: 1
        count:
          type: integer
          minimum: 0
          default: 0
        requester_reacted:
          type: boolean
          default: false
    TaskReactionToggleRequest:
      type: object
      required:
        - emoji
      properties:
        emoji:
          type: string
          minLength: 1
      additionalProperties: false
    TaskReactionMutationData:
      type: object
      required:
        - task_id
        - emoji
        - requester_reacted
      properties:
        task_id:
          type: string
          format: uuid
        emoji:
          type: string
        requester_reacted:
          type: boolean
    TaskReactionListResponse:
      type: object
      required:
        - data
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TaskReaction'
      example:
        data:
          - task_id: 123e4567-e89b-12d3-a456-426614174002
            emoji: ':thumbsup:'
            count: 3
            requester_reacted: true
          - task_id: 123e4567-e89b-12d3-a456-426614174002
            emoji: ':rocket:'
            count: 1
            requester_reacted: false
    TaskReactionMutationResponse:
      type: object
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/TaskReactionMutationData'
      example:
        data:
          task_id: 123e4567-e89b-12d3-a456-426614174002
          emoji: ':thumbsup:'
          requester_reacted: true
  responses:
    ProblemResponse:
      description: RFC9457 problem details 응답.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          examples:
            authenticationRequired:
              value:
                type: https://api.onlogn.com/problems/authentication-required
                title: Authentication Required
                status: 401
                detail: Access token is missing or expired.
                instance: /api/v1/users/me/req_01JZ4T3Q8R9A2F4M7N6
            permissionDenied:
              value:
                type: https://api.onlogn.com/problems/permission-denied
                title: Permission Denied
                status: 403
                detail: You cannot access another user's private resource.
                instance: /api/v1/groups/01ARZ3NDEKTSV4RRFFQ69G5FAV8/req_01JZ4T4H1X2B3C4D5E6
            resourceNotFound:
              value:
                type: https://api.onlogn.com/problems/resource-not-found
                title: Resource Not Found
                status: 404
                detail: Requested resource does not exist.
                instance: /api/v1/tasks/01ARZ3NDEKTSV4RRFFQ69G5FAV9/req_01JZ4T59K8L7M6N5P4Q
            internalServerError:
              value:
                type: https://api.onlogn.com/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /api/v1/groups/req_01JZ4T8V6W5X4Y3Z2A1
                request_id: req_01JZ4T8V6W5X4Y3Z2A1
    BadRequestProblemResponse:
      description: 형식이 잘못된 요청 payload 또는 미지원 body 형태.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://api.onlogn.com/problems/bad-request
            title: Bad Request
            status: 400
            detail: Request body is malformed or missing required fields.
            instance: /api/v1/auth/oauth/github/exchange/req_01JZ4T3Q8R9A2F4M7N6
    AuthenticationProblemResponse:
      description: 누락, 만료, 무효, 또는 이미 회전된 자격 증명.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://api.onlogn.com/problems/authentication-required
            title: Authentication Required
            status: 401
            detail: Credential is missing, invalid, expired, or already rotated.
            instance: /api/v1/auth/refresh/req_01JZ4T3Q8R9A2F4M7N6
    RateLimitProblemResponse:
      description: 스로틀링 정책에 의해 요청이 거부됨.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://api.onlogn.com/problems/rate-limit-exceeded
            title: Rate Limit Exceeded
            status: 429
            detail: Too many requests. Retry after 30 seconds.
            instance: /api/v1/auth/refresh/req_01JZ4T3Q8R9A2F4M7N6
            retry_after_seconds: 30
    ValidationProblemResponse:
      description: RFC9457 validation problem details 응답.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ValidationProblem'
          example:
            type: https://api.onlogn.com/problems/validation-failed
            title: Validation Failed
            status: 422
            detail: Request body validation failed.
            instance: /api/v1/tasks/req_01JZ4T59K8L7M6N5P4Q
            errors:
              - field: status
                reason: 'must be one of: todo, in_progress, done'
              - field: due_date
                reason: must be a valid date in YYYY-MM-DD format