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

<?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="전체 이슈 건수")
 * )
 *
 * @OA\Schema(
 *     schema="TodayIssueUnreadItem",
 *     type="object",
 *     description="읽지 않은 이슈 항목 (헤더 알림용)",
 *     required={"id", "badge", "content", "time", "created_at"},
 *     @OA\Property(property="id", type="integer", example=123, description="이슈 고유 ID"),
 *     @OA\Property(
 *         property="badge",
 *         type="string",
 *         enum={"수주등록", "추심이슈", "안전재고", "지출 승인대기", "세금 신고", "결재 요청", "신규거래처"},
 *         example="수주등록",
 *         description="이슈 카테고리 뱃지"
 *     ),
 *     @OA\Property(
 *         property="notification_type",
 *         type="string",
 *         enum={"sales_order", "new_vendor", "approval_request", "bad_debt", "safety_stock", "expected_expense", "vat_report"},
 *         example="sales_order",
 *         description="알림 설정 타입"
 *     ),
 *     @OA\Property(property="content", type="string", example="대한건설 신규 수주 1억 2천만원 등록", description="이슈 내용"),
 *     @OA\Property(property="path", type="string", example="/sales/order-management-sales", description="클릭 시 이동할 경로", nullable=true),
 *     @OA\Property(property="needs_approval", type="boolean", example=false, description="승인/반려 버튼 표시 여부"),
 *     @OA\Property(property="time", type="string", example="10분 전", description="상대 시간"),
 *     @OA\Property(property="created_at", type="string", format="date-time", example="2026-01-21T10:30:00+09:00", description="생성 일시 (ISO 8601)")
 * )
 *
 * @OA\Schema(
 *     schema="TodayIssueUnreadResponse",
 *     type="object",
 *     description="읽지 않은 이슈 목록 응답",
 *     @OA\Property(
 *         property="items",
 *         type="array",
 *         description="읽지 않은 이슈 항목 리스트",
 *         @OA\Items(ref="#/components/schemas/TodayIssueUnreadItem")
 *     ),
 *     @OA\Property(property="total", type="integer", example=5, description="읽지 않은 전체 이슈 건수")
 * )
 *
 * @OA\Schema(
 *     schema="TodayIssueUnreadCountResponse",
 *     type="object",
 *     description="읽지 않은 이슈 개수 응답",
 *     @OA\Property(property="count", type="integer", example=5, description="읽지 않은 이슈 건수")
 * )
 *
 * @OA\Schema(
 *     schema="TodayIssueMarkAllReadResponse",
 *     type="object",
 *     description="모든 이슈 읽음 처리 응답",
 *     @OA\Property(property="count", type="integer", example=5, 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() {}

    /**
     * @OA\Get(
     *     path="/api/v1/today-issues/unread",
     *     operationId="getUnreadTodayIssues",
     *     tags={"TodayIssue"},
     *     summary="읽지 않은 이슈 목록 조회 (헤더 알림용)",
     *     description="헤더 알림 드롭다운에 표시할 읽지 않은 이슈 목록을 조회합니다.",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\Parameter(
     *         name="limit",
     *         in="query",
     *         description="조회할 최대 항목 수 (기본 10)",
     *         required=false,
     *         @OA\Schema(type="integer", default=10, minimum=1, maximum=50)
     *     ),
     *
     *     @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/TodayIssueUnreadResponse"
     *             )
     *         )
     *     ),
     *
     *     @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 unread() {}

    /**
     * @OA\Get(
     *     path="/api/v1/today-issues/unread/count",
     *     operationId="getUnreadTodayIssueCount",
     *     tags={"TodayIssue"},
     *     summary="읽지 않은 이슈 개수 조회 (헤더 뱃지용)",
     *     description="헤더 알림 아이콘 뱃지에 표시할 읽지 않은 이슈 개수를 조회합니다.",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @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/TodayIssueUnreadCountResponse"
     *             )
     *         )
     *     ),
     *
     *     @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 unreadCount() {}

    /**
     * @OA\Post(
     *     path="/api/v1/today-issues/{id}/read",
     *     operationId="markTodayIssueAsRead",
     *     tags={"TodayIssue"},
     *     summary="이슈 읽음 처리",
     *     description="특정 이슈를 읽음 처리합니다. 헤더 알림에서 항목 클릭 시 호출됩니다.",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\Parameter(
     *         name="id",
     *         in="path",
     *         description="이슈 ID",
     *         required=true,
     *         @OA\Schema(type="integer", example=123)
     *     ),
     *
     *     @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\Response(
     *         response=404,
     *         description="이슈를 찾을 수 없음",
     *         @OA\JsonContent(
     *             type="object",
     *             @OA\Property(property="success", type="boolean", example=false),
     *             @OA\Property(property="message", type="string", example="데이터를 찾을 수 없습니다.")
     *         )
     *     ),
     *
     *     @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 markAsRead() {}

    /**
     * @OA\Post(
     *     path="/api/v1/today-issues/read-all",
     *     operationId="markAllTodayIssuesAsRead",
     *     tags={"TodayIssue"},
     *     summary="모든 이슈 읽음 처리",
     *     description="읽지 않은 모든 이슈를 읽음 처리합니다. 헤더 알림에서 '모두 읽음' 버튼 클릭 시 호출됩니다.",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @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/TodayIssueMarkAllReadResponse"
     *             )
     *         )
     *     ),
     *
     *     @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 markAllAsRead() {}
}