<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(
 *     name="TodayIssue",
 *     description="CEO 대시보드 - 오늘의 이슈 리스트 API"
 * )
 *
 * @OA\Schema(
 *     schema="TodayIssueItem",
 *     type="object",
 *     description="오늘의 이슈 항목",
 *     required={"id", "badge", "content", "time"},
 *     @OA\Property(property="id", type="string", example="order_123", description="항목 고유 ID"),
 *     @OA\Property(
 *         property="badge",
 *         type="string",
 *         enum={"수주 성공", "주식 이슈", "직정 제고", "지출예상내역서", "세금 신고", "결재 요청", "기타"},
 *         example="수주 성공",
 *         description="이슈 카테고리 뱃지"
 *     ),
 *     @OA\Property(property="content", type="string", example="A전자 신규 수주 450,000,000원 확정", description="이슈 내용"),
 *     @OA\Property(property="time", type="string", example="10분 전", description="상대 시간"),
 *     @OA\Property(property="date", type="string", format="date", example="2026-01-20", description="날짜 (ISO 형식)"),
 *     @OA\Property(property="needsApproval", type="boolean", example=false, description="승인/반려 버튼 표시 여부"),
 *     @OA\Property(property="path", type="string", example="/sales/order-management-sales", description="클릭 시 이동할 경로")
 * )
 *
 * @OA\Schema(
 *     schema="TodayIssueSummaryResponse",
 *     type="object",
 *     description="오늘의 이슈 리스트 응답",
 *     @OA\Property(
 *         property="items",
 *         type="array",
 *         description="이슈 항목 리스트",
 *         @OA\Items(ref="#/components/schemas/TodayIssueItem")
 *     ),
 *     @OA\Property(property="total_count", type="integer", example=25, description="전체 이슈 건수")
 * )
 */
class TodayIssueApi
{
    /**
     * @OA\Get(
     *     path="/api/v1/today-issues/summary",
     *     operationId="getTodayIssueSummary",
     *     tags={"TodayIssue"},
     *     summary="오늘의 이슈 리스트 조회",
     *     description="CEO 대시보드용 오늘의 이슈 리스트를 조회합니다. 수주 성공, 미수금 이슈, 재고 이슈, 지출예상내역서, 세금 신고, 결재 요청, 기타 카테고리의 알림을 집계합니다.",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\Parameter(
     *         name="limit",
     *         in="query",
     *         description="조회할 최대 항목 수",
     *         required=false,
     *         @OA\Schema(type="integer", default=30, minimum=1, maximum=100)
     *     ),
     *
     *     @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/TodayIssueSummaryResponse"
     *             )
     *         )
     *     ),
     *
     *     @OA\Response(
     *         response=401,
     *         description="인증 실패",
     *         @OA\JsonContent(
     *             type="object",
     *             @OA\Property(property="success", type="boolean", example=false),
     *             @OA\Property(property="message", type="string", example="인증에 실패했습니다.")
     *         )
     *     )
     * )
     */
    public function summary() {}
}