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

<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(name="Dashboard", description="대시보드")
 *
 * @OA\Schema(
 *     schema="DashboardSummary",
 *     type="object",
 *     description="대시보드 요약 데이터",
 *
 *     @OA\Property(property="today", type="object", description="오늘 요약",
 *         @OA\Property(property="date", type="string", format="date", example="2025-01-15", description="오늘 날짜"),
 *         @OA\Property(property="attendances_count", type="integer", example=25, description="오늘 출근자 수"),
 *         @OA\Property(property="leaves_count", type="integer", example=3, description="오늘 휴가자 수"),
 *         @OA\Property(property="approvals_pending", type="integer", example=5, description="결재 대기 문서 수")
 *     ),
 *     @OA\Property(property="finance", type="object", description="재무 요약",
 *         @OA\Property(property="monthly_deposit", type="number", format="float", example=50000000, description="월간 입금액"),
 *         @OA\Property(property="monthly_withdrawal", type="number", format="float", example=30000000, description="월간 출금액"),
 *         @OA\Property(property="balance", type="number", format="float", example=150000000, description="현재 잔액")
 *     ),
 *     @OA\Property(property="sales", type="object", description="매출/매입 요약",
 *         @OA\Property(property="monthly_sales", type="number", format="float", example=80000000, description="월간 매출"),
 *         @OA\Property(property="monthly_purchases", type="number", format="float", example=45000000, description="월간 매입")
 *     ),
 *     @OA\Property(property="tasks", type="object", description="할 일 요약",
 *         @OA\Property(property="pending_approvals", type="integer", example=3, description="내가 결재할 문서 수"),
 *         @OA\Property(property="pending_leaves", type="integer", example=2, description="승인 대기 휴가 신청 수")
 *     )
 * )
 *
 * @OA\Schema(
 *     schema="DashboardCharts",
 *     type="object",
 *     description="대시보드 차트 데이터",
 *
 *     @OA\Property(property="period", type="string", enum={"week","month","quarter"}, example="month", description="조회 기간"),
 *     @OA\Property(property="start_date", type="string", format="date", example="2024-12-17", description="시작일"),
 *     @OA\Property(property="end_date", type="string", format="date", example="2025-01-15", description="종료일"),
 *     @OA\Property(property="deposit_trend", type="array", description="입금 추이",
 *         @OA\Items(type="object",
 *             @OA\Property(property="date", type="string", format="date", example="2025-01-15"),
 *             @OA\Property(property="amount", type="number", format="float", example=5000000)
 *         )
 *     ),
 *     @OA\Property(property="withdrawal_trend", type="array", description="출금 추이",
 *         @OA\Items(type="object",
 *             @OA\Property(property="date", type="string", format="date", example="2025-01-15"),
 *             @OA\Property(property="amount", type="number", format="float", example=3000000)
 *         )
 *     ),
 *     @OA\Property(property="sales_by_client", type="array", description="거래처별 매출 (상위 10개)",
 *         @OA\Items(type="object",
 *             @OA\Property(property="client_id", type="integer", example=1),
 *             @OA\Property(property="client_name", type="string", example="(주)테스트"),
 *             @OA\Property(property="amount", type="number", format="float", example=15000000)
 *         )
 *     )
 * )
 *
 * @OA\Schema(
 *     schema="DashboardApprovals",
 *     type="object",
 *     description="대시보드 결재 현황",
 *
 *     @OA\Property(property="pending_approvals", type="array", description="결재 대기 문서 (내가 결재할 문서)",
 *         @OA\Items(type="object",
 *             @OA\Property(property="id", type="integer", example=1, description="결재문서 ID"),
 *             @OA\Property(property="title", type="string", example="출장 신청서", description="제목"),
 *             @OA\Property(property="drafter_name", type="string", example="홍길동", description="기안자명"),
 *             @OA\Property(property="status", type="string", example="pending", description="상태"),
 *             @OA\Property(property="created_at", type="string", format="date-time", example="2025-01-15 10:30:00", description="생성일시")
 *         )
 *     ),
 *     @OA\Property(property="my_drafts", type="array", description="내가 기안한 진행중인 문서",
 *         @OA\Items(type="object",
 *             @OA\Property(property="id", type="integer", example=2, description="결재문서 ID"),
 *             @OA\Property(property="title", type="string", example="휴가 신청서", description="제목"),
 *             @OA\Property(property="status", type="string", example="pending", description="상태"),
 *             @OA\Property(property="current_step", type="integer", example=2, description="현재 결재 단계"),
 *             @OA\Property(property="created_at", type="string", format="date-time", example="2025-01-14 09:00:00", description="생성일시")
 *         )
 *     )
 * )
 */
class DashboardApi
{
    /**
     * @OA\Get(
     *     path="/api/v1/dashboard/summary",
     *     tags={"Dashboard"},
     *     summary="대시보드 요약 데이터 조회",
     *     description="오늘 현황, 재무 요약, 매출/매입 요약, 할 일 요약을 반환합니다.",
     *     operationId="getDashboardSummary",
     *     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/DashboardSummary")
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패")
     * )
     */
    public function summary() {}

    /**
     * @OA\Get(
     *     path="/api/v1/dashboard/charts",
     *     tags={"Dashboard"},
     *     summary="대시보드 차트 데이터 조회",
     *     description="입금/출금 추이, 거래처별 매출 차트 데이터를 반환합니다.",
     *     operationId="getDashboardCharts",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Parameter(
     *         name="period",
     *         in="query",
     *         description="조회 기간 (week: 7일, month: 30일, quarter: 3개월)",
     *         required=false,
     *
     *         @OA\Schema(type="string", enum={"week","month","quarter"}, default="month")
     *     ),
     *
     *     @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/DashboardCharts")
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패"),
     *     @OA\Response(response=422, description="유효성 검사 실패")
     * )
     */
    public function charts() {}

    /**
     * @OA\Get(
     *     path="/api/v1/dashboard/approvals",
     *     tags={"Dashboard"},
     *     summary="결재 현황 조회",
     *     description="결재 대기 문서(결재함)와 내가 기안한 진행중인 문서 목록을 반환합니다.",
     *     operationId="getDashboardApprovals",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Parameter(
     *         name="limit",
     *         in="query",
     *         description="각 목록의 최대 항목 수 (1~50)",
     *         required=false,
     *
     *         @OA\Schema(type="integer", minimum=1, maximum=50, default=10)
     *     ),
     *
     *     @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/DashboardApprovals")
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패"),
     *     @OA\Response(response=422, description="유효성 검사 실패")
     * )
     */
    public function approvals() {}
}