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