sam-api/app/Swagger/v1/WelfareApi.php

<?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() {}
}