<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(name="Payrolls", description="급여 관리")
 *
 * @OA\Schema(
 *     schema="Payroll",
 *     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="user_id", type="integer", example=10, description="직원 ID"),
 *     @OA\Property(property="pay_year", type="integer", example=2024, description="지급 연도"),
 *     @OA\Property(property="pay_month", type="integer", example=12, description="지급 월"),
 *     @OA\Property(property="base_salary", type="number", format="float", example=3000000, description="기본급"),
 *     @OA\Property(property="overtime_pay", type="number", format="float", example=200000, nullable=true, description="연장근무수당"),
 *     @OA\Property(property="bonus", type="number", format="float", example=500000, nullable=true, description="상여금"),
 *     @OA\Property(property="allowances", type="array", nullable=true, description="수당 목록", @OA\Items(type="object",
 *         @OA\Property(property="name", type="string", example="식대"),
 *         @OA\Property(property="amount", type="number", example=100000)
 *     )),
 *     @OA\Property(property="gross_salary", type="number", format="float", example=3800000, description="총 지급액"),
 *     @OA\Property(property="income_tax", type="number", format="float", example=80000, description="소득세"),
 *     @OA\Property(property="resident_tax", type="number", format="float", example=8000, description="주민세"),
 *     @OA\Property(property="health_insurance", type="number", format="float", example=120000, description="건강보험료"),
 *     @OA\Property(property="pension", type="number", format="float", example=135000, description="국민연금"),
 *     @OA\Property(property="employment_insurance", type="number", format="float", example=30400, description="고용보험료"),
 *     @OA\Property(property="deductions", type="array", nullable=true, description="기타 공제 목록", @OA\Items(type="object",
 *         @OA\Property(property="name", type="string", example="조합비"),
 *         @OA\Property(property="amount", type="number", example=10000)
 *     )),
 *     @OA\Property(property="total_deductions", type="number", format="float", example=383400, description="총 공제액"),
 *     @OA\Property(property="net_salary", type="number", format="float", example=3416600, description="실수령액"),
 *     @OA\Property(property="status", type="string", enum={"draft","confirmed","paid"}, example="draft", description="상태"),
 *     @OA\Property(property="confirmed_at", type="string", format="date-time", nullable=true, description="확정일시"),
 *     @OA\Property(property="confirmed_by", type="integer", nullable=true, description="확정자 ID"),
 *     @OA\Property(property="paid_at", type="string", format="date-time", nullable=true, description="지급일시"),
 *     @OA\Property(property="withdrawal_id", type="integer", nullable=true, description="출금 내역 ID"),
 *     @OA\Property(property="note", type="string", nullable=true, description="비고"),
 *     @OA\Property(property="user", type="object", nullable=true, description="직원 정보",
 *         @OA\Property(property="id", type="integer", example=10),
 *         @OA\Property(property="name", type="string", example="홍길동")
 *     ),
 *     @OA\Property(property="created_at", type="string", format="date-time", example="2024-01-01T09:00:00Z"),
 *     @OA\Property(property="updated_at", type="string", format="date-time", example="2024-01-01T09:00:00Z")
 * )
 *
 * @OA\Schema(
 *     schema="PayrollStoreRequest",
 *     type="object",
 *     required={"user_id", "pay_year", "pay_month", "base_salary"},
 *     description="급여 생성 요청",
 *
 *     @OA\Property(property="user_id", type="integer", example=10, description="직원 ID"),
 *     @OA\Property(property="pay_year", type="integer", example=2024, description="지급 연도 (2000-2100)"),
 *     @OA\Property(property="pay_month", type="integer", example=12, description="지급 월 (1-12)"),
 *     @OA\Property(property="base_salary", type="number", example=3000000, description="기본급"),
 *     @OA\Property(property="overtime_pay", type="number", example=200000, description="연장근무수당"),
 *     @OA\Property(property="bonus", type="number", example=500000, description="상여금"),
 *     @OA\Property(property="allowances", type="array", description="수당 목록", @OA\Items(type="object",
 *         @OA\Property(property="name", type="string", example="식대"),
 *         @OA\Property(property="amount", type="number", example=100000)
 *     )),
 *     @OA\Property(property="income_tax", type="number", example=80000, description="소득세"),
 *     @OA\Property(property="resident_tax", type="number", example=8000, description="주민세"),
 *     @OA\Property(property="health_insurance", type="number", example=120000, description="건강보험료"),
 *     @OA\Property(property="pension", type="number", example=135000, description="국민연금"),
 *     @OA\Property(property="employment_insurance", type="number", example=30400, description="고용보험료"),
 *     @OA\Property(property="deductions", type="array", description="기타 공제 목록", @OA\Items(type="object",
 *         @OA\Property(property="name", type="string", example="조합비"),
 *         @OA\Property(property="amount", type="number", example=10000)
 *     )),
 *     @OA\Property(property="note", type="string", example="비고", description="비고")
 * )
 *
 * @OA\Schema(
 *     schema="PayrollUpdateRequest",
 *     type="object",
 *     description="급여 수정 요청 (작성중 상태만 가능)",
 *
 *     @OA\Property(property="user_id", type="integer", example=10, description="직원 ID"),
 *     @OA\Property(property="pay_year", type="integer", example=2024, description="지급 연도"),
 *     @OA\Property(property="pay_month", type="integer", example=12, description="지급 월"),
 *     @OA\Property(property="base_salary", type="number", example=3000000, description="기본급"),
 *     @OA\Property(property="overtime_pay", type="number", example=200000, description="연장근무수당"),
 *     @OA\Property(property="bonus", type="number", example=500000, description="상여금"),
 *     @OA\Property(property="allowances", type="array", description="수당 목록", @OA\Items(type="object")),
 *     @OA\Property(property="income_tax", type="number", example=80000, description="소득세"),
 *     @OA\Property(property="resident_tax", type="number", example=8000, description="주민세"),
 *     @OA\Property(property="health_insurance", type="number", example=120000, description="건강보험료"),
 *     @OA\Property(property="pension", type="number", example=135000, description="국민연금"),
 *     @OA\Property(property="employment_insurance", type="number", example=30400, description="고용보험료"),
 *     @OA\Property(property="deductions", type="array", description="기타 공제 목록", @OA\Items(type="object")),
 *     @OA\Property(property="note", type="string", example="비고", description="비고")
 * )
 *
 * @OA\Schema(
 *     schema="PayrollCalculateRequest",
 *     type="object",
 *     required={"year", "month"},
 *     description="급여 일괄 계산 요청",
 *
 *     @OA\Property(property="year", type="integer", example=2024, description="지급 연도"),
 *     @OA\Property(property="month", type="integer", example=12, description="지급 월"),
 *     @OA\Property(property="user_ids", type="array", description="직원 ID 목록 (미지정시 전체)", @OA\Items(type="integer"))
 * )
 *
 * @OA\Schema(
 *     schema="PayrollSummary",
 *     type="object",
 *     description="급여 현황 요약",
 *
 *     @OA\Property(property="draft", type="integer", example=10, description="작성중"),
 *     @OA\Property(property="confirmed", type="integer", example=45, description="확정"),
 *     @OA\Property(property="paid", type="integer", example=40, description="지급완료"),
 *     @OA\Property(property="total_gross", type="number", example=150000000, description="총 지급액 합계"),
 *     @OA\Property(property="total_net", type="number", example=130000000, description="총 실수령액 합계")
 * )
 *
 * @OA\Schema(
 *     schema="PayrollSetting",
 *     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="income_tax_rate", type="number", example=3.3, description="소득세율 (%)"),
 *     @OA\Property(property="resident_tax_rate", type="number", example=10.0, description="주민세율 (소득세 대비 %)"),
 *     @OA\Property(property="health_insurance_rate", type="number", example=3.545, description="건강보험요율 (%)"),
 *     @OA\Property(property="long_term_care_rate", type="number", example=12.95, description="장기요양보험요율 (건강보험 대비 %)"),
 *     @OA\Property(property="pension_rate", type="number", example=4.5, description="국민연금요율 (%)"),
 *     @OA\Property(property="employment_insurance_rate", type="number", example=0.9, description="고용보험요율 (%)"),
 *     @OA\Property(property="pension_max_salary", type="number", example=5900000, description="국민연금 상한기준"),
 *     @OA\Property(property="pension_min_salary", type="number", example=370000, description="국민연금 하한기준"),
 *     @OA\Property(property="pay_day", type="integer", example=25, description="급여 지급일"),
 *     @OA\Property(property="auto_calculate", type="boolean", example=true, description="자동계산 여부"),
 *     @OA\Property(property="allowance_types", type="array", description="수당 유형 목록", @OA\Items(type="object",
 *         @OA\Property(property="code", type="string", example="MEAL"),
 *         @OA\Property(property="name", type="string", example="식대"),
 *         @OA\Property(property="is_taxable", type="boolean", example=false)
 *     )),
 *     @OA\Property(property="deduction_types", type="array", description="공제 유형 목록", @OA\Items(type="object",
 *         @OA\Property(property="code", type="string", example="UNION"),
 *         @OA\Property(property="name", type="string", example="조합비")
 *     ))
 * )
 *
 * @OA\Schema(
 *     schema="PayrollSettingUpdateRequest",
 *     type="object",
 *     description="급여 설정 수정 요청",
 *
 *     @OA\Property(property="income_tax_rate", type="number", example=3.3, description="소득세율"),
 *     @OA\Property(property="resident_tax_rate", type="number", example=10.0, description="주민세율"),
 *     @OA\Property(property="health_insurance_rate", type="number", example=3.545, description="건강보험요율"),
 *     @OA\Property(property="long_term_care_rate", type="number", example=12.95, description="장기요양보험요율"),
 *     @OA\Property(property="pension_rate", type="number", example=4.5, description="국민연금요율"),
 *     @OA\Property(property="employment_insurance_rate", type="number", example=0.9, description="고용보험요율"),
 *     @OA\Property(property="pension_max_salary", type="number", example=5900000, description="국민연금 상한기준"),
 *     @OA\Property(property="pension_min_salary", type="number", example=370000, description="국민연금 하한기준"),
 *     @OA\Property(property="pay_day", type="integer", example=25, description="급여 지급일 (1-31)"),
 *     @OA\Property(property="auto_calculate", type="boolean", example=true, description="자동계산 여부"),
 *     @OA\Property(property="allowance_types", type="array", description="수당 유형 목록", @OA\Items(type="object")),
 *     @OA\Property(property="deduction_types", type="array", description="공제 유형 목록", @OA\Items(type="object"))
 * )
 *
 * @OA\Schema(
 *     schema="Payslip",
 *     type="object",
 *     description="급여명세서",
 *
 *     @OA\Property(property="employee", type="object", description="직원 정보",
 *         @OA\Property(property="id", type="integer", example=10),
 *         @OA\Property(property="name", type="string", example="홍길동"),
 *         @OA\Property(property="employee_number", type="string", example="EMP001"),
 *         @OA\Property(property="department", type="string", example="개발팀"),
 *         @OA\Property(property="position", type="string", example="과장")
 *     ),
 *     @OA\Property(property="period", type="string", example="2024년 12월", description="급여 기간"),
 *     @OA\Property(property="pay_date", type="string", format="date", example="2024-12-25", description="지급일"),
 *     @OA\Property(property="earnings", type="object", description="지급 내역",
 *         @OA\Property(property="base_salary", type="number", example=3000000),
 *         @OA\Property(property="overtime_pay", type="number", example=200000),
 *         @OA\Property(property="bonus", type="number", example=500000),
 *         @OA\Property(property="allowances", type="array", @OA\Items(type="object")),
 *         @OA\Property(property="total", type="number", example=3800000)
 *     ),
 *     @OA\Property(property="deductions", type="object", description="공제 내역",
 *         @OA\Property(property="income_tax", type="number", example=80000),
 *         @OA\Property(property="resident_tax", type="number", example=8000),
 *         @OA\Property(property="health_insurance", type="number", example=120000),
 *         @OA\Property(property="pension", type="number", example=135000),
 *         @OA\Property(property="employment_insurance", type="number", example=30400),
 *         @OA\Property(property="others", type="array", @OA\Items(type="object")),
 *         @OA\Property(property="total", type="number", example=383400)
 *     ),
 *     @OA\Property(property="net_salary", type="number", example=3416600, description="실수령액")
 * )
 */
class PayrollApi
{
    /**
     * @OA\Get(
     *     path="/api/v1/payrolls",
     *     tags={"Payrolls"},
     *     summary="급여 목록 조회",
     *     description="급여 목록을 페이지네이션하여 조회합니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Parameter(name="year", in="query", description="지급 연도", @OA\Schema(type="integer", example=2024)),
     *     @OA\Parameter(name="month", in="query", description="지급 월", @OA\Schema(type="integer", example=12)),
     *     @OA\Parameter(name="status", in="query", description="상태 필터", @OA\Schema(type="string", enum={"draft","confirmed","paid"})),
     *     @OA\Parameter(name="user_id", in="query", description="직원 ID", @OA\Schema(type="integer")),
     *     @OA\Parameter(name="search", in="query", description="검색어 (직원명)", @OA\Schema(type="string")),
     *     @OA\Parameter(name="sort_by", in="query", description="정렬 기준", @OA\Schema(type="string", enum={"pay_year","pay_month","base_salary","net_salary","created_at"}, default="pay_year")),
     *     @OA\Parameter(name="sort_dir", in="query", description="정렬 방향", @OA\Schema(type="string", enum={"asc","desc"}, default="desc")),
     *     @OA\Parameter(ref="#/components/parameters/Page"),
     *     @OA\Parameter(ref="#/components/parameters/Size"),
     *
     *     @OA\Response(
     *         response=200,
     *         description="조회 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(
     *                         property="data",
     *                         type="object",
     *                         @OA\Property(property="current_page", type="integer", example=1),
     *                         @OA\Property(property="data", type="array", @OA\Items(ref="#/components/schemas/Payroll")),
     *                         @OA\Property(property="per_page", type="integer", example=20),
     *                         @OA\Property(property="total", type="integer", example=50)
     *                     )
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function index() {}

    /**
     * @OA\Get(
     *     path="/api/v1/payrolls/summary",
     *     tags={"Payrolls"},
     *     summary="급여 현황 요약",
     *     description="급여 상태별 건수와 금액을 조회합니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Parameter(name="year", in="query", description="지급 연도", @OA\Schema(type="integer", example=2024)),
     *     @OA\Parameter(name="month", in="query", description="지급 월", @OA\Schema(type="integer", example=12)),
     *
     *     @OA\Response(
     *         response=200,
     *         description="조회 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/PayrollSummary"))
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function summary() {}

    /**
     * @OA\Post(
     *     path="/api/v1/payrolls",
     *     tags={"Payrolls"},
     *     summary="급여 생성",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(ref="#/components/schemas/PayrollStoreRequest")
     *     ),
     *
     *     @OA\Response(
     *         response=201,
     *         description="생성 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Payroll"))
     *             }
     *         )
     *     ),
     *
     *     @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=409, description="해당 연월 급여 이미 존재", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function store() {}

    /**
     * @OA\Get(
     *     path="/api/v1/payrolls/{id}",
     *     tags={"Payrolls"},
     *     summary="급여 상세 조회",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Parameter(name="id", in="path", required=true, description="급여 ID", @OA\Schema(type="integer")),
     *
     *     @OA\Response(
     *         response=200,
     *         description="조회 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Payroll"))
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=404, description="급여를 찾을 수 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function show() {}

    /**
     * @OA\Put(
     *     path="/api/v1/payrolls/{id}",
     *     tags={"Payrolls"},
     *     summary="급여 수정",
     *     description="작성중 상태의 급여만 수정할 수 있습니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Parameter(name="id", in="path", required=true, description="급여 ID", @OA\Schema(type="integer")),
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(ref="#/components/schemas/PayrollUpdateRequest")
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="수정 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Payroll"))
     *             }
     *         )
     *     ),
     *
     *     @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=404, description="급여를 찾을 수 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function update() {}

    /**
     * @OA\Delete(
     *     path="/api/v1/payrolls/{id}",
     *     tags={"Payrolls"},
     *     summary="급여 삭제",
     *     description="작성중 상태의 급여만 삭제할 수 있습니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Parameter(name="id", in="path", required=true, description="급여 ID", @OA\Schema(type="integer")),
     *
     *     @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", type="boolean", example=true)
     *         )
     *     ),
     *
     *     @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=404, description="급여를 찾을 수 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function destroy() {}

    /**
     * @OA\Post(
     *     path="/api/v1/payrolls/{id}/confirm",
     *     tags={"Payrolls"},
     *     summary="급여 확정",
     *     description="작성중 상태의 급여를 확정합니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Parameter(name="id", in="path", required=true, description="급여 ID", @OA\Schema(type="integer")),
     *
     *     @OA\Response(
     *         response=200,
     *         description="확정 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Payroll"))
     *             }
     *         )
     *     ),
     *
     *     @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=404, description="급여를 찾을 수 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function confirm() {}

    /**
     * @OA\Post(
     *     path="/api/v1/payrolls/{id}/pay",
     *     tags={"Payrolls"},
     *     summary="급여 지급 처리",
     *     description="확정된 급여를 지급 처리합니다. 출금 내역과 연결할 수 있습니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Parameter(name="id", in="path", required=true, description="급여 ID", @OA\Schema(type="integer")),
     *
     *     @OA\RequestBody(
     *         required=false,
     *
     *         @OA\JsonContent(
     *
     *             @OA\Property(property="withdrawal_id", type="integer", example=123, description="출금 내역 ID (선택)")
     *         )
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="지급 처리 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Payroll"))
     *             }
     *         )
     *     ),
     *
     *     @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=404, description="급여를 찾을 수 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function pay() {}

    /**
     * @OA\Post(
     *     path="/api/v1/payrolls/bulk-confirm",
     *     tags={"Payrolls"},
     *     summary="급여 일괄 확정",
     *     description="지정 기간의 작성중 급여를 일괄 확정합니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(
     *             required={"year", "month"},
     *
     *             @OA\Property(property="year", type="integer", example=2024, description="지급 연도"),
     *             @OA\Property(property="month", type="integer", example=12, description="지급 월")
     *         )
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="일괄 확정 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(property="data", type="object",
     *                         @OA\Property(property="confirmed_count", type="integer", example=45, description="확정된 건수")
     *                     )
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function bulkConfirm() {}

    /**
     * @OA\Post(
     *     path="/api/v1/payrolls/calculate",
     *     tags={"Payrolls"},
     *     summary="급여 일괄 계산",
     *     description="지정 기간의 급여를 일괄 계산하여 생성합니다. 이미 존재하는 급여는 건너뜁니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(ref="#/components/schemas/PayrollCalculateRequest")
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="일괄 계산 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(property="data", type="object",
     *                         @OA\Property(property="created_count", type="integer", example=45, description="생성된 건수"),
     *                         @OA\Property(property="skipped_count", type="integer", example=5, description="건너뛴 건수")
     *                     )
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function calculate() {}

    /**
     * @OA\Get(
     *     path="/api/v1/payrolls/{id}/payslip",
     *     tags={"Payrolls"},
     *     summary="급여명세서 조회",
     *     description="급여명세서 형식으로 급여 정보를 조회합니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Parameter(name="id", in="path", required=true, description="급여 ID", @OA\Schema(type="integer")),
     *
     *     @OA\Response(
     *         response=200,
     *         description="조회 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Payslip"))
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=404, description="급여를 찾을 수 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function payslip() {}

    /**
     * @OA\Get(
     *     path="/api/v1/settings/payroll",
     *     tags={"Payrolls"},
     *     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/PayrollSetting"))
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function getSettings() {}

    /**
     * @OA\Put(
     *     path="/api/v1/settings/payroll",
     *     tags={"Payrolls"},
     *     summary="급여 설정 수정",
     *     description="테넌트의 급여 설정을 수정합니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(ref="#/components/schemas/PayrollSettingUpdateRequest")
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="수정 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/PayrollSetting"))
     *             }
     *         )
     *     ),
     *
     *     @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 updateSettings() {}
}
