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