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

<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(name="WorkSettings", description="근무/출퇴근 설정")
 *
 * @OA\Schema(
 *     schema="WorkSetting",
 *     type="object",
 *     description="근무 설정 정보",
 *
 *     @OA\Property(property="id", type="integer", example=1, description="ID"),
 *     @OA\Property(property="tenant_id", type="integer", example=1, description="테넌트 ID"),
 *     @OA\Property(property="work_type", type="string", enum={"fixed","flexible","custom"}, example="fixed", description="근무유형"),
 *     @OA\Property(property="standard_hours", type="integer", example=40, description="주당 소정근로시간"),
 *     @OA\Property(property="overtime_hours", type="integer", example=12, description="주당 연장근로시간"),
 *     @OA\Property(property="overtime_limit", type="integer", example=52, description="연장근로한도"),
 *     @OA\Property(property="work_days", type="array", @OA\Items(type="string"), example={"mon","tue","wed","thu","fri"}, description="근무요일"),
 *     @OA\Property(property="start_time", type="string", format="time", example="09:00:00", description="출근시간"),
 *     @OA\Property(property="end_time", type="string", format="time", example="18:00:00", description="퇴근시간"),
 *     @OA\Property(property="break_minutes", type="integer", example=60, description="휴게시간(분)"),
 *     @OA\Property(property="break_start", type="string", format="time", example="12:00:00", nullable=true, description="휴게시작"),
 *     @OA\Property(property="break_end", type="string", format="time", example="13:00:00", nullable=true, description="휴게종료"),
 *     @OA\Property(property="created_at", type="string", format="date-time"),
 *     @OA\Property(property="updated_at", type="string", format="date-time")
 * )
 *
 * @OA\Schema(
 *     schema="WorkSettingUpdateRequest",
 *     type="object",
 *     description="근무 설정 수정 요청",
 *
 *     @OA\Property(property="work_type", type="string", enum={"fixed","flexible","custom"}, example="fixed", description="근무유형"),
 *     @OA\Property(property="standard_hours", type="integer", example=40, minimum=1, maximum=168, description="주당 소정근로시간"),
 *     @OA\Property(property="overtime_hours", type="integer", example=12, minimum=0, maximum=52, description="주당 연장근로시간"),
 *     @OA\Property(property="overtime_limit", type="integer", example=52, minimum=0, maximum=100, description="연장근로한도"),
 *     @OA\Property(property="work_days", type="array", @OA\Items(type="string", enum={"mon","tue","wed","thu","fri","sat","sun"}), description="근무요일"),
 *     @OA\Property(property="start_time", type="string", format="time", example="09:00:00", description="출근시간"),
 *     @OA\Property(property="end_time", type="string", format="time", example="18:00:00", description="퇴근시간"),
 *     @OA\Property(property="break_minutes", type="integer", example=60, minimum=0, maximum=180, description="휴게시간(분)"),
 *     @OA\Property(property="break_start", type="string", format="time", example="12:00:00", description="휴게시작"),
 *     @OA\Property(property="break_end", type="string", format="time", example="13:00:00", description="휴게종료")
 * )
 *
 * @OA\Schema(
 *     schema="AttendanceSetting",
 *     type="object",
 *     description="출퇴근 설정 정보",
 *
 *     @OA\Property(property="id", type="integer", example=1, description="ID"),
 *     @OA\Property(property="tenant_id", type="integer", example=1, description="테넌트 ID"),
 *     @OA\Property(property="use_gps", type="boolean", example=true, description="GPS 출퇴근 사용 여부"),
 *     @OA\Property(property="allowed_radius", type="integer", example=100, description="허용 반경(m)"),
 *     @OA\Property(property="hq_address", type="string", example="서울시 강남구 테헤란로 123", nullable=true, description="본사 주소"),
 *     @OA\Property(property="hq_latitude", type="number", format="float", example=37.5012, nullable=true, description="본사 위도"),
 *     @OA\Property(property="hq_longitude", type="number", format="float", example=127.0396, nullable=true, description="본사 경도"),
 *     @OA\Property(property="created_at", type="string", format="date-time"),
 *     @OA\Property(property="updated_at", type="string", format="date-time")
 * )
 *
 * @OA\Schema(
 *     schema="AttendanceSettingUpdateRequest",
 *     type="object",
 *     description="출퇴근 설정 수정 요청",
 *
 *     @OA\Property(property="use_gps", type="boolean", example=true, description="GPS 출퇴근 사용 여부"),
 *     @OA\Property(property="allowed_radius", type="integer", example=100, minimum=10, maximum=10000, description="허용 반경(m)"),
 *     @OA\Property(property="hq_address", type="string", example="서울시 강남구 테헤란로 123", description="본사 주소"),
 *     @OA\Property(property="hq_latitude", type="number", format="float", example=37.5012, minimum=-90, maximum=90, description="본사 위도"),
 *     @OA\Property(property="hq_longitude", type="number", format="float", example=127.0396, minimum=-180, maximum=180, description="본사 경도")
 * )
 */
class WorkSettingApi
{
    /**
     * @OA\Get(
     *     path="/api/v1/settings/work",
     *     tags={"WorkSettings"},
     *     summary="근무 설정 조회",
     *     description="테넌트의 근무 설정을 조회합니다. 설정이 없으면 기본값으로 자동 생성됩니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Response(
     *         response=200,
     *         description="조회 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(property="data", ref="#/components/schemas/WorkSetting")
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function showWorkSetting() {}

    /**
     * @OA\Put(
     *     path="/api/v1/settings/work",
     *     tags={"WorkSettings"},
     *     summary="근무 설정 수정",
     *     description="테넌트의 근무 설정을 수정합니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(ref="#/components/schemas/WorkSettingUpdateRequest")
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="수정 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(property="data", ref="#/components/schemas/WorkSetting")
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=400, description="잘못된 요청", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function updateWorkSetting() {}

    /**
     * @OA\Get(
     *     path="/api/v1/settings/attendance",
     *     tags={"WorkSettings"},
     *     summary="출퇴근 설정 조회",
     *     description="테넌트의 출퇴근 설정을 조회합니다. 설정이 없으면 기본값으로 자동 생성됩니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Response(
     *         response=200,
     *         description="조회 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(property="data", ref="#/components/schemas/AttendanceSetting")
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function showAttendanceSetting() {}

    /**
     * @OA\Put(
     *     path="/api/v1/settings/attendance",
     *     tags={"WorkSettings"},
     *     summary="출퇴근 설정 수정",
     *     description="테넌트의 출퇴근 설정을 수정합니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(ref="#/components/schemas/AttendanceSettingUpdateRequest")
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="수정 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(property="data", ref="#/components/schemas/AttendanceSetting")
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=400, description="잘못된 요청", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function updateAttendanceSetting() {}
}