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

<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(
 *     name="ComprehensiveAnalysis",
 *     description="종합 분석 보고서 API - 경영 현황 종합 분석"
 * )
 */

/**
 * @OA\Schema(
 *     schema="CheckPoint",
 *     description="체크포인트 아이템",
 *
 *     @OA\Property(property="id", type="string", description="ID", example="expense-cp-1"),
 *     @OA\Property(property="type", type="string", enum={"success", "warning", "error", "info"}, description="타입", example="warning"),
 *     @OA\Property(property="message", type="string", description="메시지", example="연체 중인 지출이 있습니다."),
 *     @OA\Property(property="highlight", type="string", nullable=true, description="강조 텍스트", example="1,000,000원")
 * )
 *
 * @OA\Schema(
 *     schema="AmountCard",
 *     description="금액 카드 아이템",
 *
 *     @OA\Property(property="id", type="string", description="ID", example="expense-1"),
 *     @OA\Property(property="label", type="string", description="라벨", example="이번 달 예상 지출"),
 *     @OA\Property(property="amount", type="number", format="float", description="금액", example=1000000),
 *     @OA\Property(property="sub_amount", type="number", format="float", nullable=true, description="부가 금액"),
 *     @OA\Property(property="sub_label", type="string", nullable=true, description="부가 라벨"),
 *     @OA\Property(property="previous_amount", type="number", format="float", nullable=true, description="이전 금액"),
 *     @OA\Property(property="previous_label", type="string", nullable=true, description="이전 라벨")
 * )
 *
 * @OA\Schema(
 *     schema="ComprehensiveTodayIssueItem",
 *     description="종합분석 오늘의 이슈 아이템",
 *
 *     @OA\Property(property="id", type="string", description="ID", example="issue-1"),
 *     @OA\Property(property="category", type="string", description="카테고리", example="결재요청"),
 *     @OA\Property(property="description", type="string", description="설명", example="매입 처리 결재 요청"),
 *     @OA\Property(property="requires_approval", type="boolean", description="승인 필요 여부", example=true),
 *     @OA\Property(property="time", type="string", description="시간", example="09:30")
 * )
 *
 * @OA\Schema(
 *     schema="TodayIssueSection",
 *     description="오늘의 이슈 섹션",
 *
 *     @OA\Property(
 *         property="filter_options",
 *         type="array",
 *         description="필터 옵션",
 *
 *         @OA\Items(type="string")
 *     ),
 *
 *     @OA\Property(
 *         property="items",
 *         type="array",
 *         description="이슈 목록",
 *
 *         @OA\Items(ref="#/components/schemas/ComprehensiveTodayIssueItem")
 *     )
 * )
 *
 * @OA\Schema(
 *     schema="ExpenseSection",
 *     description="지출 섹션 공통 스키마",
 *
 *     @OA\Property(
 *         property="cards",
 *         type="array",
 *         description="금액 카드 목록",
 *
 *         @OA\Items(ref="#/components/schemas/AmountCard")
 *     ),
 *
 *     @OA\Property(
 *         property="check_points",
 *         type="array",
 *         description="체크포인트 목록",
 *
 *         @OA\Items(ref="#/components/schemas/CheckPoint")
 *     )
 * )
 *
 * @OA\Schema(
 *     schema="ReceivableSection",
 *     description="미수금 현황 섹션",
 *
 *     @OA\Property(
 *         property="cards",
 *         type="array",
 *         description="금액 카드 목록",
 *
 *         @OA\Items(ref="#/components/schemas/AmountCard")
 *     ),
 *
 *     @OA\Property(
 *         property="check_points",
 *         type="array",
 *         description="체크포인트 목록",
 *
 *         @OA\Items(ref="#/components/schemas/CheckPoint")
 *     ),
 *
 *     @OA\Property(property="has_detail_button", type="boolean", description="상세 버튼 표시 여부", example=true),
 *     @OA\Property(property="detail_button_label", type="string", description="상세 버튼 라벨", example="거래처별 미수금 현황"),
 *     @OA\Property(property="detail_button_path", type="string", description="상세 페이지 경로", example="/accounting/receivables-status")
 * )
 *
 * @OA\Schema(
 *     schema="ComprehensiveAnalysisData",
 *     description="종합 분석 데이터",
 *
 *     @OA\Property(property="today_issue", ref="#/components/schemas/TodayIssueSection"),
 *     @OA\Property(property="monthly_expense", ref="#/components/schemas/ExpenseSection"),
 *     @OA\Property(property="card_management", ref="#/components/schemas/ExpenseSection"),
 *     @OA\Property(property="entertainment", ref="#/components/schemas/ExpenseSection"),
 *     @OA\Property(property="welfare", ref="#/components/schemas/ExpenseSection"),
 *     @OA\Property(property="receivable", ref="#/components/schemas/ReceivableSection"),
 *     @OA\Property(property="debt_collection", ref="#/components/schemas/ExpenseSection")
 * )
 */
class ComprehensiveAnalysisApi
{
    /**
     * @OA\Get(
     *     path="/api/v1/comprehensive-analysis",
     *     operationId="getComprehensiveAnalysis",
     *     tags={"ComprehensiveAnalysis"},
     *     summary="종합 분석 데이터 조회",
     *     description="종합 경영 분석 데이터를 조회합니다. 오늘의 이슈, 예상 지출, 카드 관리, 접대비, 복리후생비, 미수금, 채권추심 현황을 포함합니다.",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\Parameter(
     *         name="date",
     *         in="query",
     *         description="기준 일자 (기본: 오늘)",
     *
     *         @OA\Schema(type="string", format="date", example="2025-12-26")
     *     ),
     *
     *     @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/ComprehensiveAnalysisData")
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패"),
     *     @OA\Response(response=403, description="권한 없음")
     * )
     */
    public function index() {}
}