SamProject/sam-api
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1d71b588cbce64c1d9377939ff65bb96a3273d2a
sam-api/app/Swagger/v1/WorkSettingApi.php
hskwon ca5618be98 feat: 근무/출퇴근 설정 및 현장 관리 API 구현 
- 근무 설정 API (GET/PUT /settings/work)
  - 근무유형, 소정근로시간, 연장근로시간, 근무요일, 출퇴근시간, 휴게시간
- 출퇴근 설정 API (GET/PUT /settings/attendance)
  - GPS 출퇴근, 허용 반경, 본사 위치 설정
- 현장 관리 API (CRUD /sites)
  - 현장 등록/수정/삭제, 활성화된 현장 목록(셀렉트박스용)
  - GPS 좌표 기반 위치 관리

마이그레이션: work_settings, attendance_settings, sites 테이블
모델: WorkSetting, AttendanceSetting, Site (BelongsToTenant, SoftDeletes)
서비스: WorkSettingService, SiteService
Swagger 문서 및 i18n 메시지 키 추가
2025-12-17 20:46:37 +09:00

210 lines
10 KiB
PHP
Raw Blame History

<?php
namespace App\Swagger\v1;
/**
* @OA\Tag(name="WorkSettings", description="근무/출퇴근 설정")
*
* @OA\Schema(
* schema="WorkSetting",
* 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="work_type", type="string", enum={"fixed","flexible","custom"}, example="fixed", description="근무유형"),
* @OA\Property(property="standard_hours", type="integer", example=40, description="주당 소정근로시간"),
* @OA\Property(property="overtime_hours", type="integer", example=12, description="주당 연장근로시간"),
* @OA\Property(property="overtime_limit", type="integer", example=52, description="연장근로한도"),
* @OA\Property(property="work_days", type="array", @OA\Items(type="string"), example={"mon","tue","wed","thu","fri"}, description="근무요일"),
* @OA\Property(property="start_time", type="string", format="time", example="09:00:00", description="출근시간"),
* @OA\Property(property="end_time", type="string", format="time", example="18:00:00", description="퇴근시간"),
* @OA\Property(property="break_minutes", type="integer", example=60, description="휴게시간(분)"),
* @OA\Property(property="break_start", type="string", format="time", example="12:00:00", nullable=true, description="휴게시작"),
* @OA\Property(property="break_end", type="string", format="time", example="13:00:00", nullable=true, description="휴게종료"),
* @OA\Property(property="created_at", type="string", format="date-time"),
* @OA\Property(property="updated_at", type="string", format="date-time")
* )
*
* @OA\Schema(
* schema="WorkSettingUpdateRequest",
* type="object",
* description="근무 설정 수정 요청",
*
* @OA\Property(property="work_type", type="string", enum={"fixed","flexible","custom"}, example="fixed", description="근무유형"),
* @OA\Property(property="standard_hours", type="integer", example=40, minimum=1, maximum=168, description="주당 소정근로시간"),
* @OA\Property(property="overtime_hours", type="integer", example=12, minimum=0, maximum=52, description="주당 연장근로시간"),
* @OA\Property(property="overtime_limit", type="integer", example=52, minimum=0, maximum=100, description="연장근로한도"),
* @OA\Property(property="work_days", type="array", @OA\Items(type="string", enum={"mon","tue","wed","thu","fri","sat","sun"}), description="근무요일"),
* @OA\Property(property="start_time", type="string", format="time", example="09:00:00", description="출근시간"),
* @OA\Property(property="end_time", type="string", format="time", example="18:00:00", description="퇴근시간"),
* @OA\Property(property="break_minutes", type="integer", example=60, minimum=0, maximum=180, description="휴게시간(분)"),
* @OA\Property(property="break_start", type="string", format="time", example="12:00:00", description="휴게시작"),
* @OA\Property(property="break_end", type="string", format="time", example="13:00:00", description="휴게종료")
* )
*
* @OA\Schema(
* schema="AttendanceSetting",
* 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="use_gps", type="boolean", example=true, description="GPS 출퇴근 사용 여부"),
* @OA\Property(property="allowed_radius", type="integer", example=100, description="허용 반경(m)"),
* @OA\Property(property="hq_address", type="string", example="서울시 강남구 테헤란로 123", nullable=true, description="본사 주소"),
* @OA\Property(property="hq_latitude", type="number", format="float", example=37.5012, nullable=true, description="본사 위도"),
* @OA\Property(property="hq_longitude", type="number", format="float", example=127.0396, nullable=true, description="본사 경도"),
* @OA\Property(property="created_at", type="string", format="date-time"),
* @OA\Property(property="updated_at", type="string", format="date-time")
* )
*
* @OA\Schema(
* schema="AttendanceSettingUpdateRequest",
* type="object",
* description="출퇴근 설정 수정 요청",
*
* @OA\Property(property="use_gps", type="boolean", example=true, description="GPS 출퇴근 사용 여부"),
* @OA\Property(property="allowed_radius", type="integer", example=100, minimum=10, maximum=10000, description="허용 반경(m)"),
* @OA\Property(property="hq_address", type="string", example="서울시 강남구 테헤란로 123", description="본사 주소"),
* @OA\Property(property="hq_latitude", type="number", format="float", example=37.5012, minimum=-90, maximum=90, description="본사 위도"),
* @OA\Property(property="hq_longitude", type="number", format="float", example=127.0396, minimum=-180, maximum=180, description="본사 경도")
* )
*/
class WorkSettingApi
{
/**
* @OA\Get(
* path="/api/v1/settings/work",
* tags={"WorkSettings"},
* 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/WorkSetting")
* )
* }
* )
* ),
*
* @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
* @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
* )
*/
public function showWorkSetting() {}
/**
* @OA\Put(
* path="/api/v1/settings/work",
* tags={"WorkSettings"},
* summary="근무 설정 수정",
* description="테넌트의 근무 설정을 수정합니다.",
* security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
*
* @OA\RequestBody(
* required=true,
*
* @OA\JsonContent(ref="#/components/schemas/WorkSettingUpdateRequest")
* ),
*
* @OA\Response(
* response=200,
* description="수정 성공",
*
* @OA\JsonContent(
* allOf={
*
* @OA\Schema(ref="#/components/schemas/ApiResponse"),
* @OA\Schema(
*
* @OA\Property(property="data", ref="#/components/schemas/WorkSetting")
* )
* }
* )
* ),
*
* @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 updateWorkSetting() {}
/**
* @OA\Get(
* path="/api/v1/settings/attendance",
* tags={"WorkSettings"},
* 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/AttendanceSetting")
* )
* }
* )
* ),
*
* @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
* @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
* )
*/
public function showAttendanceSetting() {}
/**
* @OA\Put(
* path="/api/v1/settings/attendance",
* tags={"WorkSettings"},
* summary="출퇴근 설정 수정",
* description="테넌트의 출퇴근 설정을 수정합니다.",
* security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
*
* @OA\RequestBody(
* required=true,
*
* @OA\JsonContent(ref="#/components/schemas/AttendanceSettingUpdateRequest")
* ),
*
* @OA\Response(
* response=200,
* description="수정 성공",
*
* @OA\JsonContent(
* allOf={
*
* @OA\Schema(ref="#/components/schemas/ApiResponse"),
* @OA\Schema(
*
* @OA\Property(property="data", ref="#/components/schemas/AttendanceSetting")
* )
* }
* )
* ),
*
* @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 updateAttendanceSetting() {}
}
Reference in New Issue View Git Blame Copy Permalink