feat: CEO 대시보드 API 구현 및 DB 컬럼 오류 수정
- StatusBoardService: 현황판 8개 항목 집계 API - CalendarService: 캘린더 일정 조회 API (작업지시/계약/휴가) - TodayIssueService: 오늘의 이슈 리스트 API - VatService: 부가세 신고 현황 API - EntertainmentService: 접대비 현황 API - WelfareService: 복리후생 현황 API 버그 수정: - orders 테이블 status → status_code 컬럼명 수정 - users 테이블 department 관계 → tenantProfile.department로 수정 - Swagger 문서 및 라우트 추가
This commit is contained in:
146
app/Swagger/v1/CalendarApi.php
Normal file
146
app/Swagger/v1/CalendarApi.php
Normal file
@@ -0,0 +1,146 @@
|
||||
<?php
|
||||
|
||||
namespace App\Swagger\v1;
|
||||
|
||||
/**
|
||||
* @OA\Tag(
|
||||
* name="Calendar",
|
||||
* description="CEO 대시보드 캘린더 API - 일정 데이터 조회"
|
||||
* )
|
||||
*/
|
||||
|
||||
/**
|
||||
* @OA\Schema(
|
||||
* schema="CalendarScheduleItem",
|
||||
* description="캘린더 일정 아이템",
|
||||
*
|
||||
* @OA\Property(property="id", type="string", description="일정 ID (타입_ID 형식)", example="wo_123"),
|
||||
* @OA\Property(property="title", type="string", description="일정 제목", example="스크린 생산"),
|
||||
* @OA\Property(property="startDate", type="string", format="date", description="시작일", example="2026-01-20"),
|
||||
* @OA\Property(property="endDate", type="string", format="date", description="종료일", example="2026-01-20"),
|
||||
* @OA\Property(property="startTime", type="string", nullable=true, description="시작 시간 (HH:mm)", example="09:00"),
|
||||
* @OA\Property(property="endTime", type="string", nullable=true, description="종료 시간 (HH:mm)", example="18:00"),
|
||||
* @OA\Property(property="isAllDay", type="boolean", description="종일 여부", example=true),
|
||||
* @OA\Property(
|
||||
* property="type",
|
||||
* type="string",
|
||||
* enum={"schedule", "order", "construction", "other"},
|
||||
* description="일정 타입 (schedule: 휴가/일반, order: 작업지시/발주, construction: 시공/계약)",
|
||||
* example="order"
|
||||
* ),
|
||||
* @OA\Property(property="department", type="string", nullable=true, description="부서명", example="생산팀"),
|
||||
* @OA\Property(property="personName", type="string", nullable=true, description="담당자명", example="홍길동"),
|
||||
* @OA\Property(property="color", type="string", nullable=true, description="일정 색상", example="blue")
|
||||
* )
|
||||
*
|
||||
* @OA\Schema(
|
||||
* schema="CalendarScheduleSummary",
|
||||
* description="캘린더 일정 요약 데이터",
|
||||
*
|
||||
* @OA\Property(
|
||||
* property="items",
|
||||
* type="array",
|
||||
* description="일정 목록",
|
||||
*
|
||||
* @OA\Items(ref="#/components/schemas/CalendarScheduleItem")
|
||||
* ),
|
||||
* @OA\Property(property="total_count", type="integer", description="총 일정 수", example=15)
|
||||
* )
|
||||
*/
|
||||
class CalendarApi
|
||||
{
|
||||
/**
|
||||
* @OA\Get(
|
||||
* path="/api/v1/calendar/schedules",
|
||||
* operationId="getCalendarSchedules",
|
||||
* tags={"Calendar"},
|
||||
* summary="캘린더 일정 조회",
|
||||
* description="CEO 대시보드 캘린더의 일정 데이터를 조회합니다.
|
||||
|
||||
* 데이터 소스:
|
||||
* - 작업지시(order): 생산 예정일 기준
|
||||
* - 계약/시공(construction): 계약 기간 기준
|
||||
* - 휴가(schedule): 승인된 휴가 기간 기준
|
||||
|
||||
* 필터:
|
||||
* - 기간 필터: start_date ~ end_date
|
||||
* - 타입 필터: schedule(휴가), order(작업지시), construction(시공)
|
||||
* - 부서 필터: all(전체), department(부서), personal(개인)",
|
||||
* security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
|
||||
*
|
||||
* @OA\Parameter(
|
||||
* name="start_date",
|
||||
* in="query",
|
||||
* description="조회 시작일 (Y-m-d, 기본: 이번 달 1일)",
|
||||
* required=false,
|
||||
*
|
||||
* @OA\Schema(type="string", format="date", example="2026-01-01")
|
||||
* ),
|
||||
*
|
||||
* @OA\Parameter(
|
||||
* name="end_date",
|
||||
* in="query",
|
||||
* description="조회 종료일 (Y-m-d, 기본: 이번 달 말일)",
|
||||
* required=false,
|
||||
*
|
||||
* @OA\Schema(type="string", format="date", example="2026-01-31")
|
||||
* ),
|
||||
*
|
||||
* @OA\Parameter(
|
||||
* name="type",
|
||||
* in="query",
|
||||
* description="일정 타입 필터 (미지정 시 전체 조회)",
|
||||
* required=false,
|
||||
*
|
||||
* @OA\Schema(type="string", enum={"schedule", "order", "construction", "other"})
|
||||
* ),
|
||||
*
|
||||
* @OA\Parameter(
|
||||
* name="department_filter",
|
||||
* in="query",
|
||||
* description="부서 필터 (기본: all)",
|
||||
* required=false,
|
||||
*
|
||||
* @OA\Schema(type="string", enum={"all", "department", "personal"}, default="all")
|
||||
* ),
|
||||
*
|
||||
* @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",
|
||||
* ref="#/components/schemas/CalendarScheduleSummary"
|
||||
* )
|
||||
* )
|
||||
* ),
|
||||
*
|
||||
* @OA\Response(
|
||||
* response=401,
|
||||
* description="인증 실패",
|
||||
*
|
||||
* @OA\JsonContent(
|
||||
*
|
||||
* @OA\Property(property="success", type="boolean", example=false),
|
||||
* @OA\Property(property="message", type="string", example="인증이 필요합니다.")
|
||||
* )
|
||||
* ),
|
||||
*
|
||||
* @OA\Response(
|
||||
* response=422,
|
||||
* description="유효성 검증 실패",
|
||||
*
|
||||
* @OA\JsonContent(
|
||||
*
|
||||
* @OA\Property(property="success", type="boolean", example=false),
|
||||
* @OA\Property(property="message", type="string", example="유효성 검증에 실패했습니다.")
|
||||
* )
|
||||
* )
|
||||
* )
|
||||
*/
|
||||
public function summary() {}
|
||||
}
|
||||
147
app/Swagger/v1/EntertainmentApi.php
Normal file
147
app/Swagger/v1/EntertainmentApi.php
Normal file
@@ -0,0 +1,147 @@
|
||||
<?php
|
||||
|
||||
namespace App\Swagger\v1;
|
||||
|
||||
/**
|
||||
* @OA\Tag(
|
||||
* name="Entertainment",
|
||||
* description="접대비 현황 API"
|
||||
* )
|
||||
*/
|
||||
|
||||
/**
|
||||
* @OA\Schema(
|
||||
* schema="EntertainmentAmountCard",
|
||||
* type="object",
|
||||
* description="접대비 금액 카드",
|
||||
* required={"id", "label", "amount"},
|
||||
*
|
||||
* @OA\Property(property="id", type="string", description="카드 ID", example="et_sales"),
|
||||
* @OA\Property(property="label", type="string", description="카드 라벨", example="매출"),
|
||||
* @OA\Property(property="amount", type="integer", description="금액", example=30530000000),
|
||||
* @OA\Property(property="subLabel", type="string", nullable=true, description="부가 라벨", example=null),
|
||||
* @OA\Property(property="unit", type="string", nullable=true, description="단위", example=null)
|
||||
* )
|
||||
*
|
||||
* @OA\Schema(
|
||||
* schema="EntertainmentHighlightItem",
|
||||
* type="object",
|
||||
* description="체크포인트 하이라이트 아이템",
|
||||
* required={"text", "color"},
|
||||
*
|
||||
* @OA\Property(property="text", type="string", description="하이라이트 텍스트", example="1,000만원"),
|
||||
* @OA\Property(property="color", type="string", description="색상 (red, green, orange 등)", example="green")
|
||||
* )
|
||||
*
|
||||
* @OA\Schema(
|
||||
* schema="EntertainmentCheckPoint",
|
||||
* type="object",
|
||||
* description="접대비 체크포인트",
|
||||
* required={"id", "type", "message"},
|
||||
*
|
||||
* @OA\Property(property="id", type="string", description="체크포인트 ID", example="et_cp_normal"),
|
||||
* @OA\Property(property="type", type="string", description="타입 (success, warning, error)", example="success"),
|
||||
* @OA\Property(property="message", type="string", description="메시지", example="{1사분기} 접대비 사용 1,000만원 / 한도 4,012만원 (75%). 여유 있게 운영 중입니다."),
|
||||
* @OA\Property(
|
||||
* property="highlights",
|
||||
* type="array",
|
||||
* description="하이라이트 아이템 목록",
|
||||
*
|
||||
* @OA\Items(ref="#/components/schemas/EntertainmentHighlightItem")
|
||||
* )
|
||||
* )
|
||||
*
|
||||
* @OA\Schema(
|
||||
* schema="EntertainmentSummaryResponse",
|
||||
* type="object",
|
||||
* description="접대비 현황 요약 응답",
|
||||
* required={"cards", "check_points"},
|
||||
*
|
||||
* @OA\Property(
|
||||
* property="cards",
|
||||
* type="array",
|
||||
* description="금액 카드 목록",
|
||||
*
|
||||
* @OA\Items(ref="#/components/schemas/EntertainmentAmountCard")
|
||||
* ),
|
||||
* @OA\Property(
|
||||
* property="check_points",
|
||||
* type="array",
|
||||
* description="체크포인트 목록",
|
||||
*
|
||||
* @OA\Items(ref="#/components/schemas/EntertainmentCheckPoint")
|
||||
* )
|
||||
* )
|
||||
*/
|
||||
class EntertainmentApi
|
||||
{
|
||||
/**
|
||||
* @OA\Get(
|
||||
* path="/api/v1/entertainment/summary",
|
||||
* operationId="getEntertainmentSummary",
|
||||
* tags={"Entertainment"},
|
||||
* summary="접대비 현황 요약 조회",
|
||||
* description="CEO 대시보드용 접대비 현황 요약 데이터를 조회합니다. 매출액, 한도, 사용금액, 잔여한도를 포함합니다.",
|
||||
* security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
|
||||
*
|
||||
* @OA\Parameter(
|
||||
* name="limit_type",
|
||||
* in="query",
|
||||
* required=false,
|
||||
* description="기간 타입 (annual: 연간, quarterly: 분기)",
|
||||
*
|
||||
* @OA\Schema(type="string", enum={"annual", "quarterly"}, default="quarterly")
|
||||
* ),
|
||||
*
|
||||
* @OA\Parameter(
|
||||
* name="company_type",
|
||||
* in="query",
|
||||
* required=false,
|
||||
* description="기업 유형 (large: 대기업, medium: 중견기업, small: 중소기업)",
|
||||
*
|
||||
* @OA\Schema(type="string", enum={"large", "medium", "small"}, default="medium")
|
||||
* ),
|
||||
*
|
||||
* @OA\Parameter(
|
||||
* name="year",
|
||||
* in="query",
|
||||
* required=false,
|
||||
* description="연도 (기본: 현재 연도)",
|
||||
*
|
||||
* @OA\Schema(type="integer", example=2026)
|
||||
* ),
|
||||
*
|
||||
* @OA\Parameter(
|
||||
* name="quarter",
|
||||
* in="query",
|
||||
* required=false,
|
||||
* description="분기 번호 (1-4, 기본: 현재 분기)",
|
||||
*
|
||||
* @OA\Schema(type="integer", minimum=1, maximum=4, example=1)
|
||||
* ),
|
||||
*
|
||||
* @OA\Response(
|
||||
* response=200,
|
||||
* description="조회 성공",
|
||||
*
|
||||
* @OA\JsonContent(
|
||||
* type="object",
|
||||
*
|
||||
* @OA\Property(property="success", type="boolean", example=true),
|
||||
* @OA\Property(property="message", type="string", example="조회되었습니다."),
|
||||
* @OA\Property(property="data", ref="#/components/schemas/EntertainmentSummaryResponse")
|
||||
* )
|
||||
* ),
|
||||
*
|
||||
* @OA\Response(
|
||||
* response=401,
|
||||
* description="인증 실패"
|
||||
* ),
|
||||
* @OA\Response(
|
||||
* response=403,
|
||||
* description="권한 없음"
|
||||
* )
|
||||
* )
|
||||
*/
|
||||
public function summary() {}
|
||||
}
|
||||
94
app/Swagger/v1/StatusBoardApi.php
Normal file
94
app/Swagger/v1/StatusBoardApi.php
Normal file
@@ -0,0 +1,94 @@
|
||||
<?php
|
||||
|
||||
namespace App\Swagger\v1;
|
||||
|
||||
/**
|
||||
* @OA\Tag(
|
||||
* name="StatusBoard",
|
||||
* description="CEO 대시보드 현황판 API - 주요 업무 현황 카드 조회"
|
||||
* )
|
||||
*/
|
||||
|
||||
/**
|
||||
* @OA\Schema(
|
||||
* schema="StatusBoardItem",
|
||||
* description="현황판 카드 아이템",
|
||||
*
|
||||
* @OA\Property(property="id", type="string", description="카드 ID", example="orders"),
|
||||
* @OA\Property(property="label", type="string", description="카드 라벨", example="수주"),
|
||||
* @OA\Property(
|
||||
* property="count",
|
||||
* oneOf={
|
||||
*
|
||||
* @OA\Schema(type="integer", example=3),
|
||||
* @OA\Schema(type="string", example="부가세 신고 D-15")
|
||||
* },
|
||||
* description="건수 또는 텍스트"
|
||||
* ),
|
||||
* @OA\Property(property="path", type="string", description="이동 경로", example="/sales/order-management-sales"),
|
||||
* @OA\Property(property="isHighlighted", type="boolean", description="강조 표시 여부", example=false)
|
||||
* )
|
||||
*
|
||||
* @OA\Schema(
|
||||
* schema="StatusBoardSummary",
|
||||
* description="현황판 요약 데이터",
|
||||
*
|
||||
* @OA\Property(
|
||||
* property="items",
|
||||
* type="array",
|
||||
* description="현황판 카드 목록",
|
||||
*
|
||||
* @OA\Items(ref="#/components/schemas/StatusBoardItem")
|
||||
* )
|
||||
* )
|
||||
*/
|
||||
class StatusBoardApi
|
||||
{
|
||||
/**
|
||||
* @OA\Get(
|
||||
* path="/api/v1/status-board/summary",
|
||||
* operationId="getStatusBoardSummary",
|
||||
* tags={"StatusBoard"},
|
||||
* summary="현황판 요약 조회",
|
||||
* description="CEO 대시보드 현황판의 주요 업무 현황 카드 데이터를 조회합니다.
|
||||
|
||||
* 포함 항목:
|
||||
* - 수주: 오늘 신규 확정 수주 건수
|
||||
* - 채권 추심: 추심 진행 중인 건수
|
||||
* - 안전 재고: 안전재고 미달 품목 수 (강조 표시)
|
||||
* - 세금 신고: 부가세 신고 D-day (7일 이내 강조)
|
||||
* - 신규 업체 등록: 최근 7일 신규 거래처 수
|
||||
* - 연차: 오늘 휴가 중인 인원 수
|
||||
* - 발주: 발주 대기 건수
|
||||
* - 결재 요청: 나의 결재 대기 건수 (강조 표시)",
|
||||
* security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
|
||||
*
|
||||
* @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",
|
||||
* ref="#/components/schemas/StatusBoardSummary"
|
||||
* )
|
||||
* )
|
||||
* ),
|
||||
*
|
||||
* @OA\Response(
|
||||
* response=401,
|
||||
* description="인증 실패",
|
||||
*
|
||||
* @OA\JsonContent(
|
||||
*
|
||||
* @OA\Property(property="success", type="boolean", example=false),
|
||||
* @OA\Property(property="message", type="string", example="인증이 필요합니다.")
|
||||
* )
|
||||
* )
|
||||
* )
|
||||
*/
|
||||
public function summary() {}
|
||||
}
|
||||
89
app/Swagger/v1/TodayIssueApi.php
Normal file
89
app/Swagger/v1/TodayIssueApi.php
Normal file
@@ -0,0 +1,89 @@
|
||||
<?php
|
||||
|
||||
namespace App\Swagger\v1;
|
||||
|
||||
/**
|
||||
* @OA\Tag(
|
||||
* name="TodayIssue",
|
||||
* description="CEO 대시보드 - 오늘의 이슈 리스트 API"
|
||||
* )
|
||||
*
|
||||
* @OA\Schema(
|
||||
* schema="TodayIssueItem",
|
||||
* type="object",
|
||||
* description="오늘의 이슈 항목",
|
||||
* required={"id", "badge", "content", "time"},
|
||||
* @OA\Property(property="id", type="string", example="order_123", description="항목 고유 ID"),
|
||||
* @OA\Property(
|
||||
* property="badge",
|
||||
* type="string",
|
||||
* enum={"수주 성공", "주식 이슈", "직정 제고", "지출예상내역서", "세금 신고", "결재 요청", "기타"},
|
||||
* example="수주 성공",
|
||||
* description="이슈 카테고리 뱃지"
|
||||
* ),
|
||||
* @OA\Property(property="content", type="string", example="A전자 신규 수주 450,000,000원 확정", description="이슈 내용"),
|
||||
* @OA\Property(property="time", type="string", example="10분 전", description="상대 시간"),
|
||||
* @OA\Property(property="date", type="string", format="date", example="2026-01-20", description="날짜 (ISO 형식)"),
|
||||
* @OA\Property(property="needsApproval", type="boolean", example=false, description="승인/반려 버튼 표시 여부"),
|
||||
* @OA\Property(property="path", type="string", example="/sales/order-management-sales", description="클릭 시 이동할 경로")
|
||||
* )
|
||||
*
|
||||
* @OA\Schema(
|
||||
* schema="TodayIssueSummaryResponse",
|
||||
* type="object",
|
||||
* description="오늘의 이슈 리스트 응답",
|
||||
* @OA\Property(
|
||||
* property="items",
|
||||
* type="array",
|
||||
* description="이슈 항목 리스트",
|
||||
* @OA\Items(ref="#/components/schemas/TodayIssueItem")
|
||||
* ),
|
||||
* @OA\Property(property="total_count", type="integer", example=25, description="전체 이슈 건수")
|
||||
* )
|
||||
*/
|
||||
class TodayIssueApi
|
||||
{
|
||||
/**
|
||||
* @OA\Get(
|
||||
* path="/api/v1/today-issues/summary",
|
||||
* operationId="getTodayIssueSummary",
|
||||
* tags={"TodayIssue"},
|
||||
* summary="오늘의 이슈 리스트 조회",
|
||||
* description="CEO 대시보드용 오늘의 이슈 리스트를 조회합니다. 수주 성공, 미수금 이슈, 재고 이슈, 지출예상내역서, 세금 신고, 결재 요청, 기타 카테고리의 알림을 집계합니다.",
|
||||
* security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
|
||||
*
|
||||
* @OA\Parameter(
|
||||
* name="limit",
|
||||
* in="query",
|
||||
* description="조회할 최대 항목 수",
|
||||
* required=false,
|
||||
* @OA\Schema(type="integer", default=30, minimum=1, maximum=100)
|
||||
* ),
|
||||
*
|
||||
* @OA\Response(
|
||||
* response=200,
|
||||
* description="성공",
|
||||
* @OA\JsonContent(
|
||||
* type="object",
|
||||
* @OA\Property(property="success", type="boolean", example=true),
|
||||
* @OA\Property(property="message", type="string", example="데이터를 조회했습니다."),
|
||||
* @OA\Property(
|
||||
* property="data",
|
||||
* ref="#/components/schemas/TodayIssueSummaryResponse"
|
||||
* )
|
||||
* )
|
||||
* ),
|
||||
*
|
||||
* @OA\Response(
|
||||
* response=401,
|
||||
* description="인증 실패",
|
||||
* @OA\JsonContent(
|
||||
* type="object",
|
||||
* @OA\Property(property="success", type="boolean", example=false),
|
||||
* @OA\Property(property="message", type="string", example="인증에 실패했습니다.")
|
||||
* )
|
||||
* )
|
||||
* )
|
||||
*/
|
||||
public function summary() {}
|
||||
}
|
||||
138
app/Swagger/v1/VatApi.php
Normal file
138
app/Swagger/v1/VatApi.php
Normal file
@@ -0,0 +1,138 @@
|
||||
<?php
|
||||
|
||||
namespace App\Swagger\v1;
|
||||
|
||||
/**
|
||||
* @OA\Tag(
|
||||
* name="Vat",
|
||||
* description="부가세 현황 API"
|
||||
* )
|
||||
*/
|
||||
|
||||
/**
|
||||
* @OA\Schema(
|
||||
* schema="VatAmountCard",
|
||||
* type="object",
|
||||
* description="부가세 금액 카드",
|
||||
* required={"id", "label", "amount"},
|
||||
*
|
||||
* @OA\Property(property="id", type="string", description="카드 ID", example="vat_sales_tax"),
|
||||
* @OA\Property(property="label", type="string", description="카드 라벨", example="매출세액"),
|
||||
* @OA\Property(property="amount", type="integer", description="금액", example=3050000000),
|
||||
* @OA\Property(property="subLabel", type="string", nullable=true, description="부가 라벨 (환급 등)", example="환급"),
|
||||
* @OA\Property(property="unit", type="string", nullable=true, description="단위 (건, 원 등)", example="건")
|
||||
* )
|
||||
*
|
||||
* @OA\Schema(
|
||||
* schema="VatHighlightItem",
|
||||
* type="object",
|
||||
* description="체크포인트 하이라이트 아이템",
|
||||
* required={"text", "color"},
|
||||
*
|
||||
* @OA\Property(property="text", type="string", description="하이라이트 텍스트", example="2026년 1기 예정신고 기준, 예상 납부세액은 110,100,000원입니다."),
|
||||
* @OA\Property(property="color", type="string", description="색상 (red, blue, green 등)", example="red")
|
||||
* )
|
||||
*
|
||||
* @OA\Schema(
|
||||
* schema="VatCheckPoint",
|
||||
* type="object",
|
||||
* description="부가세 체크포인트",
|
||||
* required={"id", "type", "message"},
|
||||
*
|
||||
* @OA\Property(property="id", type="string", description="체크포인트 ID", example="vat_cp_payment"),
|
||||
* @OA\Property(property="type", type="string", description="타입 (success, warning, error)", example="success"),
|
||||
* @OA\Property(property="message", type="string", description="메시지", example="2026년 1기 예정신고 기준, 예상 납부세액은 110,100,000원입니다. 전기 대비 12.9% 증가했습니다."),
|
||||
* @OA\Property(
|
||||
* property="highlights",
|
||||
* type="array",
|
||||
* description="하이라이트 아이템 목록",
|
||||
*
|
||||
* @OA\Items(ref="#/components/schemas/VatHighlightItem")
|
||||
* )
|
||||
* )
|
||||
*
|
||||
* @OA\Schema(
|
||||
* schema="VatSummaryResponse",
|
||||
* type="object",
|
||||
* description="부가세 현황 요약 응답",
|
||||
* required={"cards", "check_points"},
|
||||
*
|
||||
* @OA\Property(
|
||||
* property="cards",
|
||||
* type="array",
|
||||
* description="금액 카드 목록",
|
||||
*
|
||||
* @OA\Items(ref="#/components/schemas/VatAmountCard")
|
||||
* ),
|
||||
* @OA\Property(
|
||||
* property="check_points",
|
||||
* type="array",
|
||||
* description="체크포인트 목록",
|
||||
*
|
||||
* @OA\Items(ref="#/components/schemas/VatCheckPoint")
|
||||
* )
|
||||
* )
|
||||
*/
|
||||
class VatApi
|
||||
{
|
||||
/**
|
||||
* @OA\Get(
|
||||
* path="/api/v1/vat/summary",
|
||||
* operationId="getVatSummary",
|
||||
* tags={"Vat"},
|
||||
* summary="부가세 현황 요약 조회",
|
||||
* description="CEO 대시보드용 부가세 현황 요약 데이터를 조회합니다. 매출세액, 매입세액, 예상 납부세액, 미발행 세금계산서 건수를 포함합니다.",
|
||||
* security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
|
||||
*
|
||||
* @OA\Parameter(
|
||||
* name="period_type",
|
||||
* in="query",
|
||||
* required=false,
|
||||
* description="기간 타입 (quarter: 분기, half: 반기, year: 연간)",
|
||||
*
|
||||
* @OA\Schema(type="string", enum={"quarter", "half", "year"}, default="quarter")
|
||||
* ),
|
||||
*
|
||||
* @OA\Parameter(
|
||||
* name="year",
|
||||
* in="query",
|
||||
* required=false,
|
||||
* description="연도 (기본: 현재 연도)",
|
||||
*
|
||||
* @OA\Schema(type="integer", example=2026)
|
||||
* ),
|
||||
*
|
||||
* @OA\Parameter(
|
||||
* name="period",
|
||||
* in="query",
|
||||
* required=false,
|
||||
* description="기간 번호 (quarter: 1-4, half: 1-2, 기본: 현재 기간)",
|
||||
*
|
||||
* @OA\Schema(type="integer", minimum=1, maximum=4, example=1)
|
||||
* ),
|
||||
*
|
||||
* @OA\Response(
|
||||
* response=200,
|
||||
* description="조회 성공",
|
||||
*
|
||||
* @OA\JsonContent(
|
||||
* type="object",
|
||||
*
|
||||
* @OA\Property(property="success", type="boolean", example=true),
|
||||
* @OA\Property(property="message", type="string", example="조회되었습니다."),
|
||||
* @OA\Property(property="data", ref="#/components/schemas/VatSummaryResponse")
|
||||
* )
|
||||
* ),
|
||||
*
|
||||
* @OA\Response(
|
||||
* response=401,
|
||||
* description="인증 실패"
|
||||
* ),
|
||||
* @OA\Response(
|
||||
* response=403,
|
||||
* description="권한 없음"
|
||||
* )
|
||||
* )
|
||||
*/
|
||||
public function summary() {}
|
||||
}
|
||||
165
app/Swagger/v1/WelfareApi.php
Normal file
165
app/Swagger/v1/WelfareApi.php
Normal file
@@ -0,0 +1,165 @@
|
||||
<?php
|
||||
|
||||
namespace App\Swagger\v1;
|
||||
|
||||
/**
|
||||
* @OA\Tag(
|
||||
* name="Welfare",
|
||||
* description="복리후생비 현황 API"
|
||||
* )
|
||||
*/
|
||||
|
||||
/**
|
||||
* @OA\Schema(
|
||||
* schema="WelfareAmountCard",
|
||||
* type="object",
|
||||
* description="복리후생비 금액 카드",
|
||||
* required={"id", "label", "amount"},
|
||||
*
|
||||
* @OA\Property(property="id", type="string", description="카드 ID", example="wf_annual_limit"),
|
||||
* @OA\Property(property="label", type="string", description="카드 라벨", example="당해년도 복리후생비 한도"),
|
||||
* @OA\Property(property="amount", type="integer", description="금액", example=30123000),
|
||||
* @OA\Property(property="subLabel", type="string", nullable=true, description="부가 라벨", example=null),
|
||||
* @OA\Property(property="unit", type="string", nullable=true, description="단위", example=null)
|
||||
* )
|
||||
*
|
||||
* @OA\Schema(
|
||||
* schema="WelfareHighlightItem",
|
||||
* type="object",
|
||||
* description="체크포인트 하이라이트 아이템",
|
||||
* required={"text", "color"},
|
||||
*
|
||||
* @OA\Property(property="text", type="string", description="하이라이트 텍스트", example="1인당 월 복리후생비 20만원"),
|
||||
* @OA\Property(property="color", type="string", description="색상 (red, green, orange 등)", example="green")
|
||||
* )
|
||||
*
|
||||
* @OA\Schema(
|
||||
* schema="WelfareCheckPoint",
|
||||
* type="object",
|
||||
* description="복리후생비 체크포인트",
|
||||
* required={"id", "type", "message"},
|
||||
*
|
||||
* @OA\Property(property="id", type="string", description="체크포인트 ID", example="wf_cp_normal"),
|
||||
* @OA\Property(property="type", type="string", description="타입 (success, warning, error)", example="success"),
|
||||
* @OA\Property(property="message", type="string", description="메시지", example="1인당 월 복리후생비 20만원. 업계 평균(15~25만원) 내 정상 운영 중입니다."),
|
||||
* @OA\Property(
|
||||
* property="highlights",
|
||||
* type="array",
|
||||
* description="하이라이트 아이템 목록",
|
||||
*
|
||||
* @OA\Items(ref="#/components/schemas/WelfareHighlightItem")
|
||||
* )
|
||||
* )
|
||||
*
|
||||
* @OA\Schema(
|
||||
* schema="WelfareSummaryResponse",
|
||||
* type="object",
|
||||
* description="복리후생비 현황 요약 응답",
|
||||
* required={"cards", "check_points"},
|
||||
*
|
||||
* @OA\Property(
|
||||
* property="cards",
|
||||
* type="array",
|
||||
* description="금액 카드 목록",
|
||||
*
|
||||
* @OA\Items(ref="#/components/schemas/WelfareAmountCard")
|
||||
* ),
|
||||
* @OA\Property(
|
||||
* property="check_points",
|
||||
* type="array",
|
||||
* description="체크포인트 목록",
|
||||
*
|
||||
* @OA\Items(ref="#/components/schemas/WelfareCheckPoint")
|
||||
* )
|
||||
* )
|
||||
*/
|
||||
class WelfareApi
|
||||
{
|
||||
/**
|
||||
* @OA\Get(
|
||||
* path="/api/v1/welfare/summary",
|
||||
* operationId="getWelfareSummary",
|
||||
* tags={"Welfare"},
|
||||
* summary="복리후생비 현황 요약 조회",
|
||||
* description="CEO 대시보드용 복리후생비 현황 요약 데이터를 조회합니다. 연간/분기별 한도, 사용금액, 잔여한도를 포함합니다.",
|
||||
* security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
|
||||
*
|
||||
* @OA\Parameter(
|
||||
* name="limit_type",
|
||||
* in="query",
|
||||
* required=false,
|
||||
* description="기간 타입 (annual: 연간, quarterly: 분기)",
|
||||
*
|
||||
* @OA\Schema(type="string", enum={"annual", "quarterly"}, default="quarterly")
|
||||
* ),
|
||||
*
|
||||
* @OA\Parameter(
|
||||
* name="calculation_type",
|
||||
* in="query",
|
||||
* required=false,
|
||||
* description="계산 방식 (fixed: 1인당 정액, ratio: 급여 대비 비율)",
|
||||
*
|
||||
* @OA\Schema(type="string", enum={"fixed", "ratio"}, default="fixed")
|
||||
* ),
|
||||
*
|
||||
* @OA\Parameter(
|
||||
* name="fixed_amount_per_month",
|
||||
* in="query",
|
||||
* required=false,
|
||||
* description="1인당 월 정액 (calculation_type=fixed일 때 사용, 기본: 200000)",
|
||||
*
|
||||
* @OA\Schema(type="integer", example=200000)
|
||||
* ),
|
||||
*
|
||||
* @OA\Parameter(
|
||||
* name="ratio",
|
||||
* in="query",
|
||||
* required=false,
|
||||
* description="급여 대비 비율 (calculation_type=ratio일 때 사용, 기본: 0.05)",
|
||||
*
|
||||
* @OA\Schema(type="number", format="float", example=0.05)
|
||||
* ),
|
||||
*
|
||||
* @OA\Parameter(
|
||||
* name="year",
|
||||
* in="query",
|
||||
* required=false,
|
||||
* description="연도 (기본: 현재 연도)",
|
||||
*
|
||||
* @OA\Schema(type="integer", example=2026)
|
||||
* ),
|
||||
*
|
||||
* @OA\Parameter(
|
||||
* name="quarter",
|
||||
* in="query",
|
||||
* required=false,
|
||||
* description="분기 번호 (1-4, 기본: 현재 분기)",
|
||||
*
|
||||
* @OA\Schema(type="integer", minimum=1, maximum=4, example=1)
|
||||
* ),
|
||||
*
|
||||
* @OA\Response(
|
||||
* response=200,
|
||||
* description="조회 성공",
|
||||
*
|
||||
* @OA\JsonContent(
|
||||
* type="object",
|
||||
*
|
||||
* @OA\Property(property="success", type="boolean", example=true),
|
||||
* @OA\Property(property="message", type="string", example="조회되었습니다."),
|
||||
* @OA\Property(property="data", ref="#/components/schemas/WelfareSummaryResponse")
|
||||
* )
|
||||
* ),
|
||||
*
|
||||
* @OA\Response(
|
||||
* response=401,
|
||||
* description="인증 실패"
|
||||
* ),
|
||||
* @OA\Response(
|
||||
* response=403,
|
||||
* description="권한 없음"
|
||||
* )
|
||||
* )
|
||||
*/
|
||||
public function summary() {}
|
||||
}
|
||||
Reference in New Issue
Block a user