SamProject/sam-api
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2ed90dc6db2e0ba2b2bef579f8604ad15a8ba5eb
sam-api/app/Swagger/v1/WelfareApi.php
권혁성 161b353b1c feat(API): 복리후생비 상세 API 추가 (/welfare/detail) 
- WelfareService: getDetail() 메서드 및 헬퍼 메서드 추가
  - getAccountBalance(), getMonthlyUsageTrend()
  - getCategoryDistribution(), getTransactions()
  - getQuarterlyStatus()
- WelfareController: detail() 액션 추가
- routes/api.php: /welfare/detail 라우트 등록
- Swagger: WelfareDetailResponse 및 관련 스키마 7개 추가

Co-Authored-By: Claude <noreply@anthropic.com>
2026-01-22 22:35:20 +09:00

369 lines
15 KiB
PHP
Raw Blame History

<?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")
* )
* )
*
* @OA\Schema(
* schema="WelfareDetailSummary",
* type="object",
* description="복리후생비 상세 요약",
* required={"annual_account", "annual_limit", "annual_used", "annual_remaining", "quarterly_limit", "quarterly_remaining", "quarterly_used", "quarterly_exceeded"},
*
* @OA\Property(property="annual_account", type="integer", description="당해년도 복리후생비 계정", example=3123000),
* @OA\Property(property="annual_limit", type="integer", description="당해년도 복리후생비 한도", example=48000000),
* @OA\Property(property="annual_used", type="integer", description="당해년도 복리후생비 사용", example=6000000),
* @OA\Property(property="annual_remaining", type="integer", description="당해년도 잔여한도", example=42000000),
* @OA\Property(property="quarterly_limit", type="integer", description="분기 복리후생비 총 한도", example=12000000),
* @OA\Property(property="quarterly_remaining", type="integer", description="분기 복리후생비 잔여한도", example=11000000),
* @OA\Property(property="quarterly_used", type="integer", description="분기 복리후생비 사용금액", example=1000000),
* @OA\Property(property="quarterly_exceeded", type="integer", description="분기 복리후생비 초과 금액", example=0)
* )
*
* @OA\Schema(
* schema="WelfareMonthlyUsage",
* type="object",
* description="월별 사용 추이 항목",
* required={"month", "amount"},
*
* @OA\Property(property="month", type="integer", description="월 (1-12)", example=1),
* @OA\Property(property="amount", type="integer", description="사용 금액", example=1500000)
* )
*
* @OA\Schema(
* schema="WelfareCategoryDistribution",
* type="object",
* description="항목별 분포",
* required={"category", "label", "amount", "ratio"},
*
* @OA\Property(property="category", type="string", description="카테고리 코드", example="meal"),
* @OA\Property(property="label", type="string", description="카테고리 라벨", example="식비"),
* @OA\Property(property="amount", type="integer", description="사용 금액", example=55000000),
* @OA\Property(property="ratio", type="number", format="float", description="비율 (%)", example=55.0)
* )
*
* @OA\Schema(
* schema="WelfareTransaction",
* type="object",
* description="사용 내역 항목",
* required={"id", "card_name", "user_name", "expense_date", "vendor_name", "amount", "sub_type", "sub_type_label"},
*
* @OA\Property(property="id", type="integer", description="거래 ID", example=1),
* @OA\Property(property="card_name", type="string", description="카드명", example="카드 *1234"),
* @OA\Property(property="user_name", type="string", description="사용자명", example="홍길동"),
* @OA\Property(property="expense_date", type="string", description="사용일자", example="2025-12-12 12:12"),
* @OA\Property(property="vendor_name", type="string", description="가맹점명", example="스타벅스"),
* @OA\Property(property="amount", type="integer", description="사용금액", example=1000000),
* @OA\Property(property="sub_type", type="string", description="항목 코드", example="meal"),
* @OA\Property(property="sub_type_label", type="string", description="항목명", example="식비")
* )
*
* @OA\Schema(
* schema="WelfareCalculation",
* type="object",
* description="복리후생비 계산 정보",
* required={"type", "employee_count", "annual_limit"},
*
* @OA\Property(property="type", type="string", enum={"fixed", "ratio"}, description="계산 방식", example="fixed"),
* @OA\Property(property="employee_count", type="integer", description="직원 수", example=20),
* @OA\Property(property="monthly_amount", type="integer", nullable=true, description="1인당 월 정액 (fixed 방식)", example=200000),
* @OA\Property(property="total_salary", type="integer", nullable=true, description="연봉 총액 (ratio 방식)", example=1000000000),
* @OA\Property(property="ratio", type="number", format="float", nullable=true, description="비율 (%, ratio 방식)", example=5.0),
* @OA\Property(property="annual_limit", type="integer", description="당해년도 복리후생비 총 한도", example=48000000)
* )
*
* @OA\Schema(
* schema="WelfareQuarterlyStatus",
* type="object",
* description="분기별 현황",
* required={"quarter", "limit", "carryover", "used", "remaining", "exceeded"},
*
* @OA\Property(property="quarter", type="integer", description="분기 (1-4)", example=1),
* @OA\Property(property="limit", type="integer", description="한도금액", example=12000000),
* @OA\Property(property="carryover", type="integer", description="이월금액", example=0),
* @OA\Property(property="used", type="integer", description="사용금액", example=1000000),
* @OA\Property(property="remaining", type="integer", description="잔여한도", example=11000000),
* @OA\Property(property="exceeded", type="integer", description="초과금액", example=0)
* )
*
* @OA\Schema(
* schema="WelfareDetailResponse",
* type="object",
* description="복리후생비 상세 응답 (모달용)",
* required={"summary", "monthly_usage", "category_distribution", "transactions", "calculation", "quarterly"},
*
* @OA\Property(property="summary", ref="#/components/schemas/WelfareDetailSummary"),
* @OA\Property(
* property="monthly_usage",
* type="array",
* description="월별 사용 추이",
*
* @OA\Items(ref="#/components/schemas/WelfareMonthlyUsage")
* ),
*
* @OA\Property(
* property="category_distribution",
* type="array",
* description="항목별 분포",
*
* @OA\Items(ref="#/components/schemas/WelfareCategoryDistribution")
* ),
*
* @OA\Property(
* property="transactions",
* type="array",
* description="사용 내역",
*
* @OA\Items(ref="#/components/schemas/WelfareTransaction")
* ),
*
* @OA\Property(property="calculation", ref="#/components/schemas/WelfareCalculation"),
* @OA\Property(
* property="quarterly",
* type="array",
* description="분기별 현황",
*
* @OA\Items(ref="#/components/schemas/WelfareQuarterlyStatus")
* )
* )
*/
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() {}
/**
* @OA\Get(
* path="/api/v1/welfare/detail",
* operationId="getWelfareDetail",
* tags={"Welfare"},
* summary="복리후생비 상세 조회 (모달용)",
* description="CEO 대시보드 복리후생비 모달용 상세 데이터를 조회합니다. 요약 카드, 월별 추이, 항목별 분포, 사용 내역, 분기별 현황을 포함합니다.",
* security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
*
* @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/WelfareDetailResponse")
* )
* ),
*
* @OA\Response(
* response=401,
* description="인증 실패"
* ),
* @OA\Response(
* response=403,
* description="권한 없음"
* )
* )
*/
public function detail() {}
}
Reference in New Issue View Git Blame Copy Permalink