SamProject/sam-api
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 근태관리/직원관리 API 구현

Browse Source 
- AttendanceController, AttendanceService 추가
- EmployeeController, EmployeeService 추가
- Attendance 모델 및 마이그레이션 추가
- TenantUserProfile에 employee_status 컬럼 추가
- DepartmentService 트리 조회 기능 개선
- Swagger 문서 추가 (AttendanceApi, EmployeeApi)
- API 라우트 등록
This commit is contained in:
권혁성
2025-12-09 20:27:44 +09:00
parent 33010f1916
commit f1f4c52c31
24 changed files with 2844 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

124
app/Http/Controllers/Api/V1/AttendanceController.php Normal file
View File

@@ -0,0 +1,124 @@
<?php
namespace App\Http\Controllers\Api\V1;
use App\Helpers\ApiResponse;
use App\Http\Controllers\Controller;
use App\Http\Requests\Attendance\CheckInRequest;
use App\Http\Requests\Attendance\CheckOutRequest;
use App\Http\Requests\Attendance\IndexRequest;
use App\Http\Requests\Attendance\MonthlyStatsRequest;
use App\Http\Requests\Attendance\StoreRequest;
use App\Http\Requests\Attendance\UpdateRequest;
use App\Services\AttendanceService;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
class AttendanceController extends Controller
{
public function __construct(private AttendanceService $service) {}
/**
* 근태 목록 조회
* GET /v1/attendances
*/
public function index(IndexRequest $request): JsonResponse
{
return ApiResponse::handle(function () use ($request) {
return $this->service->index($request->validated());
}, __('message.fetched'));
}
/**
* 근태 상세 조회
* GET /v1/attendances/{id}
*/
public function show(int $id): JsonResponse
{
return ApiResponse::handle(function () use ($id) {
return $this->service->show($id);
}, __('message.fetched'));
}
/**
* 근태 등록
* POST /v1/attendances
*/
public function store(StoreRequest $request): JsonResponse
{
return ApiResponse::handle(function () use ($request) {
return $this->service->store($request->validated());
}, __('message.created'));
}
/**
* 근태 수정
* PATCH /v1/attendances/{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/attendances/{id}
*/
public function destroy(int $id): JsonResponse
{
return ApiResponse::handle(function () use ($id) {
return $this->service->destroy($id);
}, __('message.deleted'));
}
/**
* 근태 일괄 삭제
* POST /v1/attendances/bulk-delete
*/
public function bulkDelete(Request $request): JsonResponse
{
$request->validate([
'ids' => 'required|array|min:1',
'ids.*' => 'integer|min:1',
]);
return ApiResponse::handle(function () use ($request) {
return $this->service->bulkDelete($request->input('ids'));
}, __('message.bulk_deleted'));
}
/**
* 출근 기록 (체크인)
* POST /v1/attendances/check-in
*/
public function checkIn(CheckInRequest $request): JsonResponse
{
return ApiResponse::handle(function () use ($request) {
return $this->service->checkIn($request->validated());
}, __('message.created'));
}
/**
* 퇴근 기록 (체크아웃)
* POST /v1/attendances/check-out
*/
public function checkOut(CheckOutRequest $request): JsonResponse
{
return ApiResponse::handle(function () use ($request) {
return $this->service->checkOut($request->validated());
}, __('message.updated'));
}
/**
* 월간 통계 조회
* GET /v1/attendances/monthly-stats
*/
public function monthlyStats(MonthlyStatsRequest $request): JsonResponse
{
return ApiResponse::handle(function () use ($request) {
return $this->service->monthlyStats($request->validated());
}, __('message.fetched'));
}
}

8
app/Http/Controllers/Api/V1/DepartmentController.php
View File

@@ -19,6 +19,14 @@ public function index(Request $request)
}, '부서 목록 조회');
}
// GET /v1/departments/tree
public function tree(Request $request)
{
return ApiResponse::handle(function () use ($request) {
return $this->service->tree($request->all());
}, '부서 트리 조회');
}
// POST /v1/departments
public function store(Request $request)
{

114
app/Http/Controllers/Api/V1/EmployeeController.php Normal file
View File

@@ -0,0 +1,114 @@
<?php
namespace App\Http\Controllers\Api\V1;
use App\Helpers\ApiResponse;
use App\Http\Controllers\Controller;
use App\Http\Requests\Employee\IndexRequest;
use App\Http\Requests\Employee\StoreRequest;
use App\Http\Requests\Employee\UpdateRequest;
use App\Services\EmployeeService;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
class EmployeeController extends Controller
{
public function __construct(private EmployeeService $service) {}
/**
* 사원 목록 조회
* GET /v1/employees
*/
public function index(IndexRequest $request): JsonResponse
{
return ApiResponse::handle(function () use ($request) {
return $this->service->index($request->validated());
}, __('message.fetched'));
}
/**
* 사원 상세 조회
* GET /v1/employees/{id}
*/
public function show(int $id): JsonResponse
{
return ApiResponse::handle(function () use ($id) {
return $this->service->show($id);
}, __('message.fetched'));
}
/**
* 사원 등록
* POST /v1/employees
*/
public function store(StoreRequest $request): JsonResponse
{
return ApiResponse::handle(function () use ($request) {
return $this->service->store($request->validated());
}, __('message.created'));
}
/**
* 사원 수정
* PATCH /v1/employees/{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/employees/{id}
*/
public function destroy(int $id): JsonResponse
{
return ApiResponse::handle(function () use ($id) {
return $this->service->destroy($id);
}, __('message.deleted'));
}
/**
* 사원 일괄 삭제
* POST /v1/employees/bulk-delete
*/
public function bulkDelete(Request $request): JsonResponse
{
$request->validate([
'ids' => 'required|array|min:1',
'ids.*' => 'integer|min:1',
]);
return ApiResponse::handle(function () use ($request) {
return $this->service->bulkDelete($request->input('ids'));
}, __('message.bulk_deleted'));
}
/**
* 사원 통계
* GET /v1/employees/stats
*/
public function stats(): JsonResponse
{
return ApiResponse::handle(function () {
return $this->service->stats();
}, __('message.fetched'));
}
/**
* 시스템 계정 생성
* POST /v1/employees/{id}/create-account
*/
public function createAccount(int $id, Request $request): JsonResponse
{
$request->validate([
'password' => 'required|string|min:8',
]);
return ApiResponse::handle(function () use ($id, $request) {
return $this->service->createAccount($id, $request->input('password'));
}, __('message.updated'));
}
}

6
app/Http/Controllers/Api/V1/UserController.php
View File

@@ -30,8 +30,10 @@ public function show($userNo)
public function me(Request $request)
{
return ApiResponse::handle(function () use ($request) {
return $this->service->getMyInfo($request);
return ApiResponse::handle(function () {
$userId = (int) app('api_user');
return MemberService::getUserInfoForLogin($userId);
}, __('message.user.me_fetched'));
}

25
app/Http/Requests/Attendance/CheckInRequest.php Normal file
View File

@@ -0,0 +1,25 @@
<?php
namespace App\Http\Requests\Attendance;
use Illuminate\Foundation\Http\FormRequest;
class CheckInRequest extends FormRequest
{
public function authorize(): bool
{
return true;
}
public function rules(): array
{
return [
'user_id' => 'nullable|integer|exists:users,id',
'check_in' => 'nullable|date_format:H:i:s',
'gps_data' => 'nullable|array',
'gps_data.latitude' => 'nullable|numeric',
'gps_data.longitude' => 'nullable|numeric',
'gps_data.accuracy' => 'nullable|numeric',
];
}
}

25
app/Http/Requests/Attendance/CheckOutRequest.php Normal file
View File

@@ -0,0 +1,25 @@
<?php
namespace App\Http\Requests\Attendance;
use Illuminate\Foundation\Http\FormRequest;
class CheckOutRequest extends FormRequest
{
public function authorize(): bool
{
return true;
}
public function rules(): array
{
return [
'user_id' => 'nullable|integer|exists:users,id',
'check_out' => 'nullable|date_format:H:i:s',
'gps_data' => 'nullable|array',
'gps_data.latitude' => 'nullable|numeric',
'gps_data.longitude' => 'nullable|numeric',
'gps_data.accuracy' => 'nullable|numeric',
];
}
}

29
app/Http/Requests/Attendance/IndexRequest.php Normal file
View File

@@ -0,0 +1,29 @@
<?php
namespace App\Http\Requests\Attendance;
use Illuminate\Foundation\Http\FormRequest;
class IndexRequest extends FormRequest
{
public function authorize(): bool
{
return true;
}
public function rules(): array
{
return [
'user_id' => 'nullable|integer|min:1',
'date' => 'nullable|date',
'date_from' => 'nullable|date',
'date_to' => 'nullable|date|after_or_equal:date_from',
'status' => 'nullable|in:onTime,late,absent,vacation,businessTrip,fieldWork,overtime,remote',
'department_id' => 'nullable|integer|min:1',
'sort_by' => 'nullable|in:base_date,status,created_at',
'sort_dir' => 'nullable|in:asc,desc',
'page' => 'nullable|integer|min:1',
'per_page' => 'nullable|integer|min:1|max:100',
];
}
}

22
app/Http/Requests/Attendance/MonthlyStatsRequest.php Normal file
View File

@@ -0,0 +1,22 @@
<?php
namespace App\Http\Requests\Attendance;
use Illuminate\Foundation\Http\FormRequest;
class MonthlyStatsRequest extends FormRequest
{
public function authorize(): bool
{
return true;
}
public function rules(): array
{
return [
'year' => 'nullable|integer|min:2000|max:2100',
'month' => 'nullable|integer|min:1|max:12',
'user_id' => 'nullable|integer|exists:users,id',
];
}
}

50
app/Http/Requests/Attendance/StoreRequest.php Normal file
View File

@@ -0,0 +1,50 @@
<?php
namespace App\Http\Requests\Attendance;
use Illuminate\Foundation\Http\FormRequest;
class StoreRequest extends FormRequest
{
public function authorize(): bool
{
return true;
}
public function rules(): array
{
return [
'user_id' => 'required|integer|exists:users,id',
'base_date' => 'required|date',
'status' => 'nullable|in:onTime,late,absent,vacation,businessTrip,fieldWork,overtime,remote',
'remarks' => 'nullable|string|max:500',
// json_details 필드
'check_in' => 'nullable|date_format:H:i:s',
'check_out' => 'nullable|date_format:H:i:s',
'gps_data' => 'nullable|array',
'gps_data.check_in' => 'nullable|array',
'gps_data.check_in.latitude' => 'nullable|numeric',
'gps_data.check_in.longitude' => 'nullable|numeric',
'gps_data.check_out' => 'nullable|array',
'gps_data.check_out.latitude' => 'nullable|numeric',
'gps_data.check_out.longitude' => 'nullable|numeric',
'external_work' => 'nullable|array',
'external_work.location' => 'nullable|string|max:255',
'external_work.purpose' => 'nullable|string|max:500',
'work_minutes' => 'nullable|integer|min:0',
'overtime_minutes' => 'nullable|integer|min:0',
'late_minutes' => 'nullable|integer|min:0',
'early_leave_minutes' => 'nullable|integer|min:0',
'vacation_type' => 'nullable|string|max:50',
];
}
public function messages(): array
{
return [
'user_id.required' => __('validation.required', ['attribute' => '사용자']),
'base_date.required' => __('validation.required', ['attribute' => '기준일']),
];
}
}

40
app/Http/Requests/Attendance/UpdateRequest.php Normal file
View File

@@ -0,0 +1,40 @@
<?php
namespace App\Http\Requests\Attendance;
use Illuminate\Foundation\Http\FormRequest;
class UpdateRequest extends FormRequest
{
public function authorize(): bool
{
return true;
}
public function rules(): array
{
return [
'status' => 'nullable|in:onTime,late,absent,vacation,businessTrip,fieldWork,overtime,remote',
'remarks' => 'nullable|string|max:500',
// json_details 필드
'check_in' => 'nullable|date_format:H:i:s',
'check_out' => 'nullable|date_format:H:i:s',
'gps_data' => 'nullable|array',
'gps_data.check_in' => 'nullable|array',
'gps_data.check_in.latitude' => 'nullable|numeric',
'gps_data.check_in.longitude' => 'nullable|numeric',
'gps_data.check_out' => 'nullable|array',
'gps_data.check_out.latitude' => 'nullable|numeric',
'gps_data.check_out.longitude' => 'nullable|numeric',
'external_work' => 'nullable|array',
'external_work.location' => 'nullable|string|max:255',
'external_work.purpose' => 'nullable|string|max:500',
'work_minutes' => 'nullable|integer|min:0',
'overtime_minutes' => 'nullable|integer|min:0',
'late_minutes' => 'nullable|integer|min:0',
'early_leave_minutes' => 'nullable|integer|min:0',
'vacation_type' => 'nullable|string|max:50',
];
}
}

27
app/Http/Requests/Employee/IndexRequest.php Normal file
View File

@@ -0,0 +1,27 @@
<?php
namespace App\Http\Requests\Employee;
use Illuminate\Foundation\Http\FormRequest;
class IndexRequest extends FormRequest
{
public function authorize(): bool
{
return true;
}
public function rules(): array
{
return [
'q' => 'nullable|string|max:100',
'status' => 'nullable|in:active,leave,resigned',
'department_id' => 'nullable|integer|min:1',
'has_account' => 'nullable|in:0,1,true,false',
'sort_by' => 'nullable|in:created_at,name,employee_status,department_id',
'sort_dir' => 'nullable|in:asc,desc',
'page' => 'nullable|integer|min:1',
'per_page' => 'nullable|integer|min:1|max:100',
];
}
}

68
app/Http/Requests/Employee/StoreRequest.php Normal file
View File

@@ -0,0 +1,68 @@
<?php
namespace App\Http\Requests\Employee;
use Illuminate\Foundation\Http\FormRequest;
class StoreRequest extends FormRequest
{
public function authorize(): bool
{
return true;
}
public function rules(): array
{
return [
// users 테이블 필드
'user_id' => 'nullable|string|max:50|unique:users,user_id',
'name' => 'required|string|max:100',
'email' => 'required|email|max:255|unique:users,email',
'phone' => 'nullable|string|max:20',
'password' => 'nullable|string|min:8',
'is_active' => 'nullable|boolean',
// tenant_user_profiles 테이블 필드
'department_id' => 'nullable|integer|exists:departments,id',
'position_key' => 'nullable|string|max:50',
'job_title_key' => 'nullable|string|max:50',
'work_location_key' => 'nullable|string|max:50',
'employment_type_key' => 'nullable|string|max:50',
'employee_status' => 'nullable|in:active,leave,resigned',
'manager_user_id' => 'nullable|integer|exists:users,id',
'profile_photo_path' => 'nullable|string|max:255',
'display_name' => 'nullable|string|max:100',
// json_extra 필드
'employee_code' => 'nullable|string|max:50',
'resident_number' => 'nullable|string|max:255',
'gender' => 'nullable|in:male,female',
'address' => 'nullable|array',
'address.zipCode' => 'nullable|string|max:10',
'address.address1' => 'nullable|string|max:255',
'address.address2' => 'nullable|string|max:255',
'salary' => 'nullable|numeric|min:0',
'hire_date' => 'nullable|date',
'rank' => 'nullable|string|max:50',
'bank_account' => 'nullable|array',
'bank_account.bankName' => 'nullable|string|max:50',
'bank_account.accountNumber' => 'nullable|string|max:50',
'bank_account.accountHolder' => 'nullable|string|max:50',
'work_type' => 'nullable|in:regular,daily,temporary,external',
'contract_info' => 'nullable|array',
'contract_info.start_date' => 'nullable|date',
'contract_info.end_date' => 'nullable|date',
'contract_info.external_company' => 'nullable|string|max:100',
];
}
public function messages(): array
{
return [
'name.required' => __('validation.required', ['attribute' => '이름']),
'email.required' => __('validation.required', ['attribute' => '이메일']),
'email.email' => __('validation.email', ['attribute' => '이메일']),
'email.unique' => __('validation.unique', ['attribute' => '이메일']),
];
}
}

79
app/Http/Requests/Employee/UpdateRequest.php Normal file
View File

@@ -0,0 +1,79 @@
<?php
namespace App\Http\Requests\Employee;
use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Validation\Rule;
class UpdateRequest extends FormRequest
{
public function authorize(): bool
{
return true;
}
public function rules(): array
{
$employeeId = $this->route('id');
return [
// users 테이블 필드
'name' => 'nullable|string|max:100',
'email' => [
'nullable',
'email',
'max:255',
Rule::unique('users', 'email')->ignore($this->getOriginalUserId()),
],
'phone' => 'nullable|string|max:20',
'is_active' => 'nullable|boolean',
// tenant_user_profiles 테이블 필드
'department_id' => 'nullable|integer|exists:departments,id',
'position_key' => 'nullable|string|max:50',
'job_title_key' => 'nullable|string|max:50',
'work_location_key' => 'nullable|string|max:50',
'employment_type_key' => 'nullable|string|max:50',
'employee_status' => 'nullable|in:active,leave,resigned',
'manager_user_id' => 'nullable|integer|exists:users,id',
'profile_photo_path' => 'nullable|string|max:255',
'display_name' => 'nullable|string|max:100',
// json_extra 필드
'employee_code' => 'nullable|string|max:50',
'resident_number' => 'nullable|string|max:255',
'gender' => 'nullable|in:male,female',
'address' => 'nullable|array',
'address.zipCode' => 'nullable|string|max:10',
'address.address1' => 'nullable|string|max:255',
'address.address2' => 'nullable|string|max:255',
'salary' => 'nullable|numeric|min:0',
'hire_date' => 'nullable|date',
'rank' => 'nullable|string|max:50',
'bank_account' => 'nullable|array',
'bank_account.bankName' => 'nullable|string|max:50',
'bank_account.accountNumber' => 'nullable|string|max:50',
'bank_account.accountHolder' => 'nullable|string|max:50',
'work_type' => 'nullable|in:regular,daily,temporary,external',
'contract_info' => 'nullable|array',
'contract_info.start_date' => 'nullable|date',
'contract_info.end_date' => 'nullable|date',
'contract_info.external_company' => 'nullable|string|max:100',
];
}
/**
* 현재 사원 프로필의 user_id 가져오기
*/
private function getOriginalUserId(): ?int
{
$employeeId = $this->route('id');
if (! $employeeId) {
return null;
}
$profile = \App\Models\Tenants\TenantUserProfile::find($employeeId);
return $profile?->user_id;
}
}