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

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