feat: 휴가 관리 API 구현 (Phase 1)

- leaves, leave_balances 테이블 마이그레이션 추가 - Leave, LeaveBalance 모델 구현 (BelongsToTenant, SoftDeletes) - LeaveService 서비스 구현 (CRUD, 승인/반려/취소, 잔여일수 관리) - LeaveController 및 FormRequest 5개 생성 - API 엔드포인트 11개 등록 (/v1/leaves/*) - Swagger 문서 (LeaveApi.php) 작성 - i18n 메시지 키 추가 (message.leave.*, error.leave.*)
2025-12-17 20:13:48 +09:00
parent cac409e7dc
commit e81e5d7084
15 changed files with 1646 additions and 0 deletions
--- a/app/Http/Controllers/Api/V1/LeaveController.php
+++ b/app/Http/Controllers/Api/V1/LeaveController.php
@@ -0,0 +1,146 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1;
+
+use App\Helpers\ApiResponse;
+use App\Http\Controllers\Controller;
+use App\Http\Requests\Leave\BalanceRequest;
+use App\Http\Requests\Leave\IndexRequest;
+use App\Http\Requests\Leave\RejectRequest;
+use App\Http\Requests\Leave\StoreRequest;
+use App\Http\Requests\Leave\UpdateRequest;
+use App\Services\LeaveService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+
+class LeaveController extends Controller
+{
+    public function __construct(private LeaveService $service) {}
+
+    /**
+     * 휴가 목록 조회
+     * GET /v1/leaves
+     */
+    public function index(IndexRequest $request): JsonResponse
+    {
+        return ApiResponse::handle(function () use ($request) {
+            return $this->service->index($request->validated());
+        }, __('message.fetched'));
+    }
+
+    /**
+     * 휴가 상세 조회
+     * GET /v1/leaves/{id}
+     */
+    public function show(int $id): JsonResponse
+    {
+        return ApiResponse::handle(function () use ($id) {
+            return $this->service->show($id);
+        }, __('message.fetched'));
+    }
+
+    /**
+     * 휴가 신청
+     * POST /v1/leaves
+     */
+    public function store(StoreRequest $request): JsonResponse
+    {
+        return ApiResponse::handle(function () use ($request) {
+            return $this->service->store($request->validated());
+        }, __('message.leave.created'));
+    }
+
+    /**
+     * 휴가 수정
+     * PATCH /v1/leaves/{id}
+     */
+    public function update(int $id, UpdateRequest $request): JsonResponse
+    {
+        return ApiResponse::handle(function () use ($id, $request) {
+            return $this->service->update($id, $request->validated());
+        }, __('message.updated'));
+    }
+
+    /**
+     * 휴가 삭제
+     * DELETE /v1/leaves/{id}
+     */
+    public function destroy(int $id): JsonResponse
+    {
+        return ApiResponse::handle(function () use ($id) {
+            return $this->service->destroy($id);
+        }, __('message.deleted'));
+    }
+
+    /**
+     * 휴가 승인
+     * POST /v1/leaves/{id}/approve
+     */
+    public function approve(int $id, Request $request): JsonResponse
+    {
+        return ApiResponse::handle(function () use ($id, $request) {
+            return $this->service->approve($id, $request->input('comment'));
+        }, __('message.leave.approved'));
+    }
+
+    /**
+     * 휴가 반려
+     * POST /v1/leaves/{id}/reject
+     */
+    public function reject(int $id, RejectRequest $request): JsonResponse
+    {
+        return ApiResponse::handle(function () use ($id, $request) {
+            return $this->service->reject($id, $request->input('reason'));
+        }, __('message.leave.rejected'));
+    }
+
+    /**
+     * 휴가 취소
+     * POST /v1/leaves/{id}/cancel
+     */
+    public function cancel(int $id, Request $request): JsonResponse
+    {
+        return ApiResponse::handle(function () use ($id, $request) {
+            return $this->service->cancel($id, $request->input('reason'));
+        }, __('message.leave.cancelled'));
+    }
+
+    /**
+     * 내 잔여 휴가 조회
+     * GET /v1/leaves/balance
+     */
+    public function balance(Request $request): JsonResponse
+    {
+        return ApiResponse::handle(function () use ($request) {
+            return $this->service->getMyBalance($request->input('year'));
+        }, __('message.fetched'));
+    }
+
+    /**
+     * 특정 사용자 잔여 휴가 조회
+     * GET /v1/leaves/balance/{userId}
+     */
+    public function userBalance(int $userId, Request $request): JsonResponse
+    {
+        return ApiResponse::handle(function () use ($userId, $request) {
+            return $this->service->getUserBalance($userId, $request->input('year'));
+        }, __('message.fetched'));
+    }
+
+    /**
+     * 잔여 휴가 설정
+     * PUT /v1/leaves/balance
+     */
+    public function setBalance(BalanceRequest $request): JsonResponse
+    {
+        return ApiResponse::handle(function () use ($request) {
+            $data = $request->validated();
+
+            return $this->service->setBalance(
+                $data['user_id'],
+                $data['year'],
+                $data['total_days']
+            );
+        }, __('message.updated'));
+    }
+}
--- a/app/Http/Requests/Leave/BalanceRequest.php
+++ b/app/Http/Requests/Leave/BalanceRequest.php
@@ -0,0 +1,22 @@
+<?php
+
+namespace App\Http\Requests\Leave;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class BalanceRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            'user_id' => 'required|integer|exists:users,id',
+            'year' => 'required|integer|min:2020|max:2099',
+            'total_days' => 'required|numeric|min:0|max:365',
+        ];
+    }
+}
--- a/app/Http/Requests/Leave/IndexRequest.php
+++ b/app/Http/Requests/Leave/IndexRequest.php
@@ -0,0 +1,30 @@
+<?php
+
+namespace App\Http\Requests\Leave;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class IndexRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            'user_id' => 'nullable|integer',
+            'status' => 'nullable|string|in:pending,approved,rejected,cancelled',
+            'leave_type' => 'nullable|string|in:annual,half_am,half_pm,sick,family,maternity,parental',
+            'date_from' => 'nullable|date',
+            'date_to' => 'nullable|date|after_or_equal:date_from',
+            'year' => 'nullable|integer|min:2020|max:2099',
+            'department_id' => 'nullable|integer',
+            'sort_by' => 'nullable|string|in:created_at,start_date,end_date,days,status',
+            'sort_dir' => 'nullable|string|in:asc,desc',
+            'per_page' => 'nullable|integer|min:1|max:100',
+            'page' => 'nullable|integer|min:1',
+        ];
+    }
+}
--- a/app/Http/Requests/Leave/RejectRequest.php
+++ b/app/Http/Requests/Leave/RejectRequest.php
@@ -0,0 +1,27 @@
+<?php
+
+namespace App\Http\Requests\Leave;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class RejectRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            'reason' => 'required|string|max:1000',
+        ];
+    }
+
+    public function messages(): array
+    {
+        return [
+            'reason.required' => __('validation.required', ['attribute' => '반려사유']),
+        ];
+    }
+}
--- a/app/Http/Requests/Leave/StoreRequest.php
+++ b/app/Http/Requests/Leave/StoreRequest.php
@@ -0,0 +1,39 @@
+<?php
+
+namespace App\Http\Requests\Leave;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class StoreRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            'user_id' => 'nullable|integer|exists:users,id',
+            'leave_type' => 'required|string|in:annual,half_am,half_pm,sick,family,maternity,parental',
+            'start_date' => 'required|date|after_or_equal:today',
+            'end_date' => 'required|date|after_or_equal:start_date',
+            'days' => 'required|numeric|min:0.5|max:365',
+            'reason' => 'nullable|string|max:1000',
+        ];
+    }
+
+    public function messages(): array
+    {
+        return [
+            'leave_type.required' => __('validation.required', ['attribute' => '휴가유형']),
+            'leave_type.in' => __('validation.in', ['attribute' => '휴가유형']),
+            'start_date.required' => __('validation.required', ['attribute' => '시작일']),
+            'start_date.after_or_equal' => __('validation.after_or_equal', ['attribute' => '시작일', 'date' => '오늘']),
+            'end_date.required' => __('validation.required', ['attribute' => '종료일']),
+            'end_date.after_or_equal' => __('validation.after_or_equal', ['attribute' => '종료일', 'date' => '시작일']),
+            'days.required' => __('validation.required', ['attribute' => '사용일수']),
+            'days.min' => __('validation.min.numeric', ['attribute' => '사용일수', 'min' => 0.5]),
+        ];
+    }
+}
--- a/app/Http/Requests/Leave/UpdateRequest.php
+++ b/app/Http/Requests/Leave/UpdateRequest.php
@@ -0,0 +1,24 @@
+<?php
+
+namespace App\Http\Requests\Leave;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class UpdateRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            'leave_type' => 'nullable|string|in:annual,half_am,half_pm,sick,family,maternity,parental',
+            'start_date' => 'nullable|date',
+            'end_date' => 'nullable|date|after_or_equal:start_date',
+            'days' => 'nullable|numeric|min:0.5|max:365',
+            'reason' => 'nullable|string|max:1000',
+        ];
+    }
+}