SamProject/sam-api
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c637dd38ebd65cb2d80e98ab10bd2f4935282ac2
sam-api/app/Swagger/v1/PayrollApi.php
hskwon 7089dd1e46 feat: 급여 관리 API 구현 (Phase 2: 3.2) 
- 마이그레이션: payrolls, payroll_settings 테이블 생성
- 모델: Payroll (상태관리 draft→confirmed→paid), PayrollSetting
- 서비스: PayrollService (4대보험 계산, 급여명세서)
- 컨트롤러: PayrollController + FormRequest 5개
- API 엔드포인트 13개:
  - 급여 CRUD + confirm/pay/payslip
  - 일괄 계산/확정 (calculate, bulk-confirm)
  - 설정 관리 (settings/payroll)
- Swagger 문서: PayrollApi.php
- i18n: error.php, message.php, validation.php 키 추가
2025-12-18 10:56:16 +09:00

656 lines
33 KiB
PHP
Raw Blame History

<?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() {}
}
Reference in New Issue View Git Blame Copy Permalink