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 키 추가

app/Http/Controllers/Api/V1/PayrollController.php

@@ -0,0 +1,172 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1;
+
+use App\Http\Controllers\Controller;
+use App\Http\Requests\V1\Payroll\CalculatePayrollRequest;
+use App\Http\Requests\V1\Payroll\PayPayrollRequest;
+use App\Http\Requests\V1\Payroll\StorePayrollRequest;
+use App\Http\Requests\V1\Payroll\UpdatePayrollRequest;
+use App\Http\Requests\V1\Payroll\UpdatePayrollSettingRequest;
+use App\Http\Responses\ApiResponse;
+use App\Services\PayrollService;
+use Illuminate\Http\Request;
+
+class PayrollController extends Controller
+{
+    public function __construct(
+        private readonly PayrollService $service
+    ) {}
+
+    /**
+     * 급여 목록
+     */
+    public function index(Request $request)
+    {
+        $params = $request->only([
+            'year',
+            'month',
+            'user_id',
+            'status',
+            'search',
+            'sort_by',
+            'sort_dir',
+            'per_page',
+            'page',
+        ]);
+
+        $payrolls = $this->service->index($params);
+
+        return ApiResponse::handle(__('message.fetched'), $payrolls);
+    }
+
+    /**
+     * 특정 연월 급여 요약
+     */
+    public function summary(Request $request)
+    {
+        $year = (int) $request->input('year', date('Y'));
+        $month = (int) $request->input('month', date('n'));
+
+        $summary = $this->service->summary($year, $month);
+
+        return ApiResponse::handle(__('message.fetched'), $summary);
+    }
+
+    /**
+     * 급여 등록
+     */
+    public function store(StorePayrollRequest $request)
+    {
+        $payroll = $this->service->store($request->validated());
+
+        return ApiResponse::handle(__('message.created'), $payroll, 201);
+    }
+
+    /**
+     * 급여 상세
+     */
+    public function show(int $id)
+    {
+        $payroll = $this->service->show($id);
+
+        return ApiResponse::handle(__('message.fetched'), $payroll);
+    }
+
+    /**
+     * 급여 수정
+     */
+    public function update(int $id, UpdatePayrollRequest $request)
+    {
+        $payroll = $this->service->update($id, $request->validated());
+
+        return ApiResponse::handle(__('message.updated'), $payroll);
+    }
+
+    /**
+     * 급여 삭제
+     */
+    public function destroy(int $id)
+    {
+        $this->service->destroy($id);
+
+        return ApiResponse::handle(__('message.deleted'));
+    }
+
+    /**
+     * 급여 확정
+     */
+    public function confirm(int $id)
+    {
+        $payroll = $this->service->confirm($id);
+
+        return ApiResponse::handle(__('message.payroll.confirmed'), $payroll);
+    }
+
+    /**
+     * 급여 지급 처리
+     */
+    public function pay(int $id, PayPayrollRequest $request)
+    {
+        $payroll = $this->service->pay($id, $request->input('withdrawal_id'));
+
+        return ApiResponse::handle(__('message.payroll.paid'), $payroll);
+    }
+
+    /**
+     * 일괄 확정
+     */
+    public function bulkConfirm(Request $request)
+    {
+        $year = (int) $request->input('year', date('Y'));
+        $month = (int) $request->input('month', date('n'));
+
+        $count = $this->service->bulkConfirm($year, $month);
+
+        return ApiResponse::handle(__('message.payroll.bulk_confirmed'), ['count' => $count]);
+    }
+
+    /**
+     * 급여명세서 조회
+     */
+    public function payslip(int $id)
+    {
+        $payslip = $this->service->payslip($id);
+
+        return ApiResponse::handle(__('message.fetched'), $payslip);
+    }
+
+    /**
+     * 급여 일괄 계산
+     */
+    public function calculate(CalculatePayrollRequest $request)
+    {
+        $year = (int) $request->input('year');
+        $month = (int) $request->input('month');
+        $userIds = $request->input('user_ids');
+
+        $payrolls = $this->service->calculate($year, $month, $userIds);
+
+        return ApiResponse::handle(__('message.payroll.calculated'), $payrolls);
+    }
+
+    /**
+     * 급여 설정 조회
+     */
+    public function getSettings()
+    {
+        $settings = $this->service->getSettings();
+
+        return ApiResponse::handle(__('message.fetched'), $settings);
+    }
+
+    /**
+     * 급여 설정 수정
+     */
+    public function updateSettings(UpdatePayrollSettingRequest $request)
+    {
+        $settings = $this->service->updateSettings($request->validated());
+
+        return ApiResponse::handle(__('message.updated'), $settings);
+    }
+}

app/Http/Requests/V1/Payroll/CalculatePayrollRequest.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace App\Http\Requests\V1\Payroll;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class CalculatePayrollRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            'year' => ['required', 'integer', 'min:2000', 'max:2100'],
+            'month' => ['required', 'integer', 'min:1', 'max:12'],
+            'user_ids' => ['nullable', 'array'],
+            'user_ids.*' => ['integer', 'exists:users,id'],
+        ];
+    }
+
+    public function attributes(): array
+    {
+        return [
+            'year' => __('validation.attributes.pay_year'),
+            'month' => __('validation.attributes.pay_month'),
+            'user_ids' => __('validation.attributes.user_ids'),
+        ];
+    }
+}

app/Http/Requests/V1/Payroll/PayPayrollRequest.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace App\Http\Requests\V1\Payroll;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class PayPayrollRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            'withdrawal_id' => ['nullable', 'integer', 'exists:withdrawals,id'],
+        ];
+    }
+
+    public function attributes(): array
+    {
+        return [
+            'withdrawal_id' => __('validation.attributes.withdrawal_id'),
+        ];
+    }
+}

app/Http/Requests/V1/Payroll/StorePayrollRequest.php

@@ -0,0 +1,57 @@
+<?php
+
+namespace App\Http\Requests\V1\Payroll;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class StorePayrollRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            'user_id' => ['required', 'integer', 'exists:users,id'],
+            'pay_year' => ['required', 'integer', 'min:2000', 'max:2100'],
+            'pay_month' => ['required', 'integer', 'min:1', 'max:12'],
+            'base_salary' => ['required', 'numeric', 'min:0'],
+            'overtime_pay' => ['nullable', 'numeric', 'min:0'],
+            'bonus' => ['nullable', 'numeric', 'min:0'],
+            'allowances' => ['nullable', 'array'],
+            'allowances.*.name' => ['required_with:allowances', 'string', 'max:50'],
+            'allowances.*.amount' => ['required_with:allowances', 'numeric', 'min:0'],
+            'income_tax' => ['nullable', 'numeric', 'min:0'],
+            'resident_tax' => ['nullable', 'numeric', 'min:0'],
+            'health_insurance' => ['nullable', 'numeric', 'min:0'],
+            'pension' => ['nullable', 'numeric', 'min:0'],
+            'employment_insurance' => ['nullable', 'numeric', 'min:0'],
+            'deductions' => ['nullable', 'array'],
+            'deductions.*.name' => ['required_with:deductions', 'string', 'max:50'],
+            'deductions.*.amount' => ['required_with:deductions', 'numeric', 'min:0'],
+            'note' => ['nullable', 'string', 'max:1000'],
+        ];
+    }
+
+    public function attributes(): array
+    {
+        return [
+            'user_id' => __('validation.attributes.user_id'),
+            'pay_year' => __('validation.attributes.pay_year'),
+            'pay_month' => __('validation.attributes.pay_month'),
+            'base_salary' => __('validation.attributes.base_salary'),
+            'overtime_pay' => __('validation.attributes.overtime_pay'),
+            'bonus' => __('validation.attributes.bonus'),
+            'allowances' => __('validation.attributes.allowances'),
+            'income_tax' => __('validation.attributes.income_tax'),
+            'resident_tax' => __('validation.attributes.resident_tax'),
+            'health_insurance' => __('validation.attributes.health_insurance'),
+            'pension' => __('validation.attributes.pension'),
+            'employment_insurance' => __('validation.attributes.employment_insurance'),
+            'deductions' => __('validation.attributes.deductions'),
+            'note' => __('validation.attributes.note'),
+        ];
+    }
+}

app/Http/Requests/V1/Payroll/UpdatePayrollRequest.php

@@ -0,0 +1,57 @@
+<?php
+
+namespace App\Http\Requests\V1\Payroll;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class UpdatePayrollRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            'user_id' => ['sometimes', 'integer', 'exists:users,id'],
+            'pay_year' => ['sometimes', 'integer', 'min:2000', 'max:2100'],
+            'pay_month' => ['sometimes', 'integer', 'min:1', 'max:12'],
+            'base_salary' => ['sometimes', 'numeric', 'min:0'],
+            'overtime_pay' => ['nullable', 'numeric', 'min:0'],
+            'bonus' => ['nullable', 'numeric', 'min:0'],
+            'allowances' => ['nullable', 'array'],
+            'allowances.*.name' => ['required_with:allowances', 'string', 'max:50'],
+            'allowances.*.amount' => ['required_with:allowances', 'numeric', 'min:0'],
+            'income_tax' => ['nullable', 'numeric', 'min:0'],
+            'resident_tax' => ['nullable', 'numeric', 'min:0'],
+            'health_insurance' => ['nullable', 'numeric', 'min:0'],
+            'pension' => ['nullable', 'numeric', 'min:0'],
+            'employment_insurance' => ['nullable', 'numeric', 'min:0'],
+            'deductions' => ['nullable', 'array'],
+            'deductions.*.name' => ['required_with:deductions', 'string', 'max:50'],
+            'deductions.*.amount' => ['required_with:deductions', 'numeric', 'min:0'],
+            'note' => ['nullable', 'string', 'max:1000'],
+        ];
+    }
+
+    public function attributes(): array
+    {
+        return [
+            'user_id' => __('validation.attributes.user_id'),
+            'pay_year' => __('validation.attributes.pay_year'),
+            'pay_month' => __('validation.attributes.pay_month'),
+            'base_salary' => __('validation.attributes.base_salary'),
+            'overtime_pay' => __('validation.attributes.overtime_pay'),
+            'bonus' => __('validation.attributes.bonus'),
+            'allowances' => __('validation.attributes.allowances'),
+            'income_tax' => __('validation.attributes.income_tax'),
+            'resident_tax' => __('validation.attributes.resident_tax'),
+            'health_insurance' => __('validation.attributes.health_insurance'),
+            'pension' => __('validation.attributes.pension'),
+            'employment_insurance' => __('validation.attributes.employment_insurance'),
+            'deductions' => __('validation.attributes.deductions'),
+            'note' => __('validation.attributes.note'),
+        ];
+    }
+}

app/Http/Requests/V1/Payroll/UpdatePayrollSettingRequest.php

@@ -0,0 +1,54 @@
+<?php
+
+namespace App\Http\Requests\V1\Payroll;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class UpdatePayrollSettingRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            'income_tax_rate' => ['nullable', 'numeric', 'min:0', 'max:100'],
+            'resident_tax_rate' => ['nullable', 'numeric', 'min:0', 'max:100'],
+            'health_insurance_rate' => ['nullable', 'numeric', 'min:0', 'max:100'],
+            'long_term_care_rate' => ['nullable', 'numeric', 'min:0', 'max:100'],
+            'pension_rate' => ['nullable', 'numeric', 'min:0', 'max:100'],
+            'employment_insurance_rate' => ['nullable', 'numeric', 'min:0', 'max:100'],
+            'pension_max_salary' => ['nullable', 'numeric', 'min:0'],
+            'pension_min_salary' => ['nullable', 'numeric', 'min:0'],
+            'pay_day' => ['nullable', 'integer', 'min:1', 'max:31'],
+            'auto_calculate' => ['nullable', 'boolean'],
+            'allowance_types' => ['nullable', 'array'],
+            'allowance_types.*.code' => ['required_with:allowance_types', 'string', 'max:20'],
+            'allowance_types.*.name' => ['required_with:allowance_types', 'string', 'max:50'],
+            'allowance_types.*.is_taxable' => ['nullable', 'boolean'],
+            'deduction_types' => ['nullable', 'array'],
+            'deduction_types.*.code' => ['required_with:deduction_types', 'string', 'max:20'],
+            'deduction_types.*.name' => ['required_with:deduction_types', 'string', 'max:50'],
+        ];
+    }
+
+    public function attributes(): array
+    {
+        return [
+            'income_tax_rate' => __('validation.attributes.income_tax_rate'),
+            'resident_tax_rate' => __('validation.attributes.resident_tax_rate'),
+            'health_insurance_rate' => __('validation.attributes.health_insurance_rate'),
+            'long_term_care_rate' => __('validation.attributes.long_term_care_rate'),
+            'pension_rate' => __('validation.attributes.pension_rate'),
+            'employment_insurance_rate' => __('validation.attributes.employment_insurance_rate'),
+            'pension_max_salary' => __('validation.attributes.pension_max_salary'),
+            'pension_min_salary' => __('validation.attributes.pension_min_salary'),
+            'pay_day' => __('validation.attributes.pay_day'),
+            'auto_calculate' => __('validation.attributes.auto_calculate'),
+            'allowance_types' => __('validation.attributes.allowance_types'),
+            'deduction_types' => __('validation.attributes.deduction_types'),
+        ];
+    }
+}