<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(
 *     name="StatusBoard",
 *     description="CEO 대시보드 현황판 API - 주요 업무 현황 카드 조회"
 * )
 */

/**
 * @OA\Schema(
 *     schema="StatusBoardItem",
 *     description="현황판 카드 아이템",
 *
 *     @OA\Property(property="id", type="string", description="카드 ID", example="orders"),
 *     @OA\Property(property="label", type="string", description="카드 라벨", example="수주"),
 *     @OA\Property(
 *         property="count",
 *         oneOf={
 *
 *             @OA\Schema(type="integer", example=3),
 *             @OA\Schema(type="string", example="부가세 신고 D-15")
 *         },
 *         description="건수 또는 텍스트"
 *     ),
 *
 *     @OA\Property(property="path", type="string", description="이동 경로", example="/sales/order-management-sales"),
 *     @OA\Property(property="isHighlighted", type="boolean", description="강조 표시 여부", example=false)
 * )
 *
 * @OA\Schema(
 *     schema="StatusBoardSummary",
 *     description="현황판 요약 데이터",
 *
 *     @OA\Property(
 *         property="items",
 *         type="array",
 *         description="현황판 카드 목록",
 *
 *         @OA\Items(ref="#/components/schemas/StatusBoardItem")
 *     )
 * )
 */
class StatusBoardApi
{
    /**
     * @OA\Get(
     *     path="/api/v1/status-board/summary",
     *     operationId="getStatusBoardSummary",
     *     tags={"StatusBoard"},
     *     summary="현황판 요약 조회",
     *     description="CEO 대시보드 현황판의 주요 업무 현황 카드 데이터를 조회합니다.

     * 포함 항목:
     * - 수주: 오늘 신규 확정 수주 건수
     * - 채권 추심: 추심 진행 중인 건수
     * - 안전 재고: 안전재고 미달 품목 수 (강조 표시)
     * - 세금 신고: 부가세 신고 D-day (7일 이내 강조)
     * - 신규 업체 등록: 최근 7일 신규 거래처 수
     * - 연차: 오늘 휴가 중인 인원 수
     * - 발주: 발주 대기 건수
     * - 결재 요청: 나의 결재 대기 건수 (강조 표시)",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\Response(
     *         response=200,
     *         description="성공",
     *
     *         @OA\JsonContent(
     *
     *             @OA\Property(property="success", type="boolean", example=true),
     *             @OA\Property(property="message", type="string", example="조회 성공"),
     *             @OA\Property(
     *                 property="data",
     *                 ref="#/components/schemas/StatusBoardSummary"
     *             )
     *         )
     *     ),
     *
     *     @OA\Response(
     *         response=401,
     *         description="인증 실패",
     *
     *         @OA\JsonContent(
     *
     *             @OA\Property(property="success", type="boolean", example=false),
     *             @OA\Property(property="message", type="string", example="인증이 필요합니다.")
     *         )
     *     )
     * )
     */
    public function summary() {}
}
