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

<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(
 *     name="LeavePolicy",
 *     description="휴가 정책 관리 API - 테넌트별 휴가 기준 설정"
 * )
 */

/**
 * @OA\Schema(
 *     schema="LeavePolicy",
 *     description="휴가 정책",
 *
 *     @OA\Property(property="id", type="integer", description="ID", example=1),
 *     @OA\Property(property="tenant_id", type="integer", description="테넌트 ID", example=1),
 *     @OA\Property(property="standard_type", type="string", enum={"fiscal", "hire"}, description="기준 유형", example="fiscal"),
 *     @OA\Property(property="fiscal_start_month", type="integer", description="회계연도 시작 월", example=1),
 *     @OA\Property(property="fiscal_start_day", type="integer", description="회계연도 시작 일", example=1),
 *     @OA\Property(property="default_annual_leave", type="integer", description="기본 연차 일수", example=15),
 *     @OA\Property(property="additional_leave_per_year", type="integer", description="근속년수당 추가 연차", example=1),
 *     @OA\Property(property="max_annual_leave", type="integer", description="최대 연차 일수", example=25),
 *     @OA\Property(property="carry_over_enabled", type="boolean", description="이월 허용 여부", example=true),
 *     @OA\Property(property="carry_over_max_days", type="integer", description="최대 이월 일수", example=10),
 *     @OA\Property(property="carry_over_expiry_months", type="integer", description="이월 연차 소멸 기간 (개월)", example=3),
 *     @OA\Property(property="created_at", type="string", format="date-time", description="생성일시"),
 *     @OA\Property(property="updated_at", type="string", format="date-time", description="수정일시")
 * )
 *
 * @OA\Schema(
 *     schema="LeavePolicyUpdateRequest",
 *     description="휴가 정책 수정 요청",
 *
 *     @OA\Property(property="standard_type", type="string", enum={"fiscal", "hire"}, description="기준 유형", example="fiscal"),
 *     @OA\Property(property="fiscal_start_month", type="integer", minimum=1, maximum=12, description="회계연도 시작 월", example=1),
 *     @OA\Property(property="fiscal_start_day", type="integer", minimum=1, maximum=31, description="회계연도 시작 일", example=1),
 *     @OA\Property(property="default_annual_leave", type="integer", minimum=0, maximum=100, description="기본 연차 일수", example=15),
 *     @OA\Property(property="additional_leave_per_year", type="integer", minimum=0, maximum=10, description="근속년수당 추가 연차", example=1),
 *     @OA\Property(property="max_annual_leave", type="integer", minimum=0, maximum=100, description="최대 연차 일수", example=25),
 *     @OA\Property(property="carry_over_enabled", type="boolean", description="이월 허용 여부", example=true),
 *     @OA\Property(property="carry_over_max_days", type="integer", minimum=0, maximum=100, description="최대 이월 일수", example=10),
 *     @OA\Property(property="carry_over_expiry_months", type="integer", minimum=0, maximum=24, description="이월 연차 소멸 기간 (개월)", example=3)
 * )
 */
class LeavePolicyApi
{
    /**
     * @OA\Get(
     *     path="/api/v1/leave-policy",
     *     operationId="getLeavePolicy",
     *     tags={"LeavePolicy"},
     *     summary="휴가 정책 조회",
     *     description="현재 테넌트의 휴가 정책을 조회합니다. 설정이 없으면 기본값으로 생성됩니다.",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @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/LeavePolicy")
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패"),
     *     @OA\Response(response=403, description="권한 없음")
     * )
     */
    public function show() {}

    /**
     * @OA\Put(
     *     path="/api/v1/leave-policy",
     *     operationId="updateLeavePolicy",
     *     tags={"LeavePolicy"},
     *     summary="휴가 정책 수정",
     *     description="현재 테넌트의 휴가 정책을 수정합니다. 부분 업데이트가 가능합니다.",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(ref="#/components/schemas/LeavePolicyUpdateRequest")
     *     ),
     *
     *     @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/LeavePolicy")
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패"),
     *     @OA\Response(response=403, description="권한 없음"),
     *     @OA\Response(response=422, description="유효성 검사 실패")
     * )
     */
    public function update() {}
}