sam-api/app/Swagger/v1/CalendarApi.php

<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(
 *     name="Calendar",
 *     description="CEO 대시보드 캘린더 API - 일정 데이터 조회"
 * )
 */

/**
 * @OA\Schema(
 *     schema="CalendarScheduleItem",
 *     description="캘린더 일정 아이템",
 *
 *     @OA\Property(property="id", type="string", description="일정 ID (타입_ID 형식)", example="wo_123"),
 *     @OA\Property(property="title", type="string", description="일정 제목", example="스크린 생산"),
 *     @OA\Property(property="startDate", type="string", format="date", description="시작일", example="2026-01-20"),
 *     @OA\Property(property="endDate", type="string", format="date", description="종료일", example="2026-01-20"),
 *     @OA\Property(property="startTime", type="string", nullable=true, description="시작 시간 (HH:mm)", example="09:00"),
 *     @OA\Property(property="endTime", type="string", nullable=true, description="종료 시간 (HH:mm)", example="18:00"),
 *     @OA\Property(property="isAllDay", type="boolean", description="종일 여부", example=true),
 *     @OA\Property(
 *         property="type",
 *         type="string",
 *         enum={"schedule", "order", "construction", "other"},
 *         description="일정 타입 (schedule: 휴가/일반, order: 작업지시/발주, construction: 시공/계약)",
 *         example="order"
 *     ),
 *     @OA\Property(property="department", type="string", nullable=true, description="부서명", example="생산팀"),
 *     @OA\Property(property="personName", type="string", nullable=true, description="담당자명", example="홍길동"),
 *     @OA\Property(property="color", type="string", nullable=true, description="일정 색상", example="blue")
 * )
 *
 * @OA\Schema(
 *     schema="CalendarScheduleSummary",
 *     description="캘린더 일정 요약 데이터",
 *
 *     @OA\Property(
 *         property="items",
 *         type="array",
 *         description="일정 목록",
 *
 *         @OA\Items(ref="#/components/schemas/CalendarScheduleItem")
 *     ),
 *
 *     @OA\Property(property="total_count", type="integer", description="총 일정 수", example=15)
 * )
 */
class CalendarApi
{
    /**
     * @OA\Get(
     *     path="/api/v1/calendar/schedules",
     *     operationId="getCalendarSchedules",
     *     tags={"Calendar"},
     *     summary="캘린더 일정 조회",
     *     description="CEO 대시보드 캘린더의 일정 데이터를 조회합니다.

     * 데이터 소스:
     * - 작업지시(order): 생산 예정일 기준
     * - 계약/시공(construction): 계약 기간 기준
     * - 휴가(schedule): 승인된 휴가 기간 기준

     * 필터:
     * - 기간 필터: start_date ~ end_date
     * - 타입 필터: schedule(휴가), order(작업지시), construction(시공)
     * - 부서 필터: all(전체), department(부서), personal(개인)",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\Parameter(
     *         name="start_date",
     *         in="query",
     *         description="조회 시작일 (Y-m-d, 기본: 이번 달 1일)",
     *         required=false,
     *
     *         @OA\Schema(type="string", format="date", example="2026-01-01")
     *     ),
     *
     *     @OA\Parameter(
     *         name="end_date",
     *         in="query",
     *         description="조회 종료일 (Y-m-d, 기본: 이번 달 말일)",
     *         required=false,
     *
     *         @OA\Schema(type="string", format="date", example="2026-01-31")
     *     ),
     *
     *     @OA\Parameter(
     *         name="type",
     *         in="query",
     *         description="일정 타입 필터 (미지정 시 전체 조회)",
     *         required=false,
     *
     *         @OA\Schema(type="string", enum={"schedule", "order", "construction", "other"})
     *     ),
     *
     *     @OA\Parameter(
     *         name="department_filter",
     *         in="query",
     *         description="부서 필터 (기본: all)",
     *         required=false,
     *
     *         @OA\Schema(type="string", enum={"all", "department", "personal"}, default="all")
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="성공",
     *
     *         @OA\JsonContent(
     *
     *             @OA\Property(property="success", type="boolean", example=true),
     *             @OA\Property(property="message", type="string", example="조회 성공"),
     *             @OA\Property(
     *                 property="data",
     *                 ref="#/components/schemas/CalendarScheduleSummary"
     *             )
     *         )
     *     ),
     *
     *     @OA\Response(
     *         response=401,
     *         description="인증 실패",
     *
     *         @OA\JsonContent(
     *
     *             @OA\Property(property="success", type="boolean", example=false),
     *             @OA\Property(property="message", type="string", example="인증이 필요합니다.")
     *         )
     *     ),
     *
     *     @OA\Response(
     *         response=422,
     *         description="유효성 검증 실패",
     *
     *         @OA\JsonContent(
     *
     *             @OA\Property(property="success", type="boolean", example=false),
     *             @OA\Property(property="message", type="string", example="유효성 검증에 실패했습니다.")
     *         )
     *     )
     * )
     */
    public function summary() {}
}