<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(name="AI Reports", description="AI 리포트 관리")
 *
 * @OA\Schema(
 *     schema="AiReport",
 *     type="object",
 *     description="AI 리포트",
 *
 *     @OA\Property(property="id", type="integer", example=1, description="리포트 ID"),
 *     @OA\Property(property="tenant_id", type="integer", example=1, description="테넌트 ID"),
 *     @OA\Property(property="report_date", type="string", format="date", example="2025-12-18", description="리포트 기준일"),
 *     @OA\Property(property="report_type", type="string", enum={"daily","weekly","monthly"}, example="daily", description="리포트 유형"),
 *     @OA\Property(property="content", type="array", description="리포트 내용",
 *
 *         @OA\Items(
 *             type="object",
 *
 *             @OA\Property(property="영역", type="string", example="지출분석", description="분석 영역"),
 *             @OA\Property(property="상태", type="string", enum={"경고","주의","긍정","양호"}, example="양호", description="상태 코드"),
 *             @OA\Property(property="메시지", type="string", example="당월 지출이 전월 대비 5% 감소했습니다.", description="핵심 메시지"),
 *             @OA\Property(property="상세", type="string", example="주요 비용 절감 항목: 외주비 (-15%), 소모품비 (-8%)", description="상세 설명")
 *         )
 *     ),
 *     @OA\Property(property="summary", type="string", example="전반적으로 재정 상태가 양호합니다. 매출이 5% 증가하고 지출이 3% 감소했습니다.", description="전체 요약"),
 *     @OA\Property(property="input_data", type="object", description="입력 데이터 (비즈니스 데이터 스냅샷)"),
 *     @OA\Property(property="status", type="string", enum={"pending","completed","failed"}, example="completed", description="처리 상태"),
 *     @OA\Property(property="error_message", type="string", nullable=true, example=null, description="오류 메시지 (실패 시)"),
 *     @OA\Property(property="created_by", type="integer", example=1, description="생성자 ID"),
 *     @OA\Property(property="created_at", type="string", format="date-time", example="2025-12-18T13:30:00Z", description="생성일시"),
 *     @OA\Property(property="updated_at", type="string", format="date-time", example="2025-12-18T13:30:05Z", description="수정일시")
 * )
 *
 * @OA\Schema(
 *     schema="AiReportPagination",
 *     type="object",
 *     description="AI 리포트 페이지네이션",
 *
 *     @OA\Property(property="current_page", type="integer", example=1),
 *     @OA\Property(property="data", type="array", @OA\Items(ref="#/components/schemas/AiReport")),
 *     @OA\Property(property="first_page_url", type="string", example="https://api.example.com/api/v1/reports/ai?page=1"),
 *     @OA\Property(property="from", type="integer", example=1),
 *     @OA\Property(property="last_page", type="integer", example=5),
 *     @OA\Property(property="last_page_url", type="string", example="https://api.example.com/api/v1/reports/ai?page=5"),
 *     @OA\Property(property="next_page_url", type="string", nullable=true, example="https://api.example.com/api/v1/reports/ai?page=2"),
 *     @OA\Property(property="path", type="string", example="https://api.example.com/api/v1/reports/ai"),
 *     @OA\Property(property="per_page", type="integer", example=15),
 *     @OA\Property(property="prev_page_url", type="string", nullable=true, example=null),
 *     @OA\Property(property="to", type="integer", example=15),
 *     @OA\Property(property="total", type="integer", example=50)
 * )
 *
 * @OA\Schema(
 *     schema="AiReportGenerateRequest",
 *     type="object",
 *     description="AI 리포트 생성 요청",
 *
 *     @OA\Property(property="report_date", type="string", format="date", example="2025-12-18", description="리포트 기준일 (오늘 이전, 기본값: 오늘)"),
 *     @OA\Property(property="report_type", type="string", enum={"daily","weekly","monthly"}, example="daily", description="리포트 유형 (기본값: daily)")
 * )
 *
 * @OA\Schema(
 *     schema="AiReportInputData",
 *     type="object",
 *     description="AI 리포트 입력 데이터",
 *
 *     @OA\Property(property="report_date", type="string", format="date", example="2025-12-18", description="기준일"),
 *     @OA\Property(property="report_type", type="string", example="daily", description="리포트 유형"),
 *     @OA\Property(property="period", type="object", description="분석 기간",
 *         @OA\Property(property="start", type="string", format="date", example="2025-12-18"),
 *         @OA\Property(property="end", type="string", format="date", example="2025-12-18")
 *     ),
 *     @OA\Property(property="expense", type="object", description="지출 데이터",
 *         @OA\Property(property="current_total", type="number", format="float", example=5000000),
 *         @OA\Property(property="previous_total", type="number", format="float", example=5500000),
 *         @OA\Property(property="change_rate", type="number", format="float", example=-9.1)
 *     ),
 *     @OA\Property(property="sales", type="object", description="매출 데이터",
 *         @OA\Property(property="current_total", type="number", format="float", example=10000000),
 *         @OA\Property(property="previous_total", type="number", format="float", example=9500000),
 *         @OA\Property(property="change_rate", type="number", format="float", example=5.3)
 *     ),
 *     @OA\Property(property="purchase", type="object", description="매입 데이터",
 *         @OA\Property(property="current_total", type="number", format="float", example=3000000),
 *         @OA\Property(property="previous_total", type="number", format="float", example=2800000),
 *         @OA\Property(property="change_rate", type="number", format="float", example=7.1)
 *     ),
 *     @OA\Property(property="deposit_withdrawal", type="object", description="입출금 데이터",
 *         @OA\Property(property="total_deposit", type="number", format="float", example=15000000),
 *         @OA\Property(property="total_withdrawal", type="number", format="float", example=8000000),
 *         @OA\Property(property="net_flow", type="number", format="float", example=7000000)
 *     ),
 *     @OA\Property(property="card_account", type="object", description="카드/계좌 데이터",
 *         @OA\Property(property="active_cards", type="integer", example=3),
 *         @OA\Property(property="current_balance", type="number", format="float", example=50000000)
 *     ),
 *     @OA\Property(property="receivable", type="object", description="미수금 데이터",
 *         @OA\Property(property="total_amount", type="number", format="float", example=8000000),
 *         @OA\Property(property="count", type="integer", example=5),
 *         @OA\Property(property="overdue_amount", type="number", format="float", example=2000000),
 *         @OA\Property(property="overdue_count", type="integer", example=2)
 *     )
 * )
 */
class AiReportApi
{
    /**
     * @OA\Get(
     *     path="/api/v1/reports/ai",
     *     tags={"AI Reports"},
     *     summary="AI 리포트 목록 조회",
     *     description="AI 리포트 목록을 페이지네이션으로 조회합니다.",
     *     security={{"BearerAuth": {}}, {"ApiKeyAuth": {}}},
     *
     *     @OA\Parameter(
     *         name="per_page",
     *         in="query",
     *         description="페이지당 항목 수 (1-100, 기본값: 15)",
     *         required=false,
     *
     *         @OA\Schema(type="integer", minimum=1, maximum=100, example=15)
     *     ),
     *
     *     @OA\Parameter(
     *         name="report_type",
     *         in="query",
     *         description="리포트 유형 필터",
     *         required=false,
     *
     *         @OA\Schema(type="string", enum={"daily","weekly","monthly"}, example="daily")
     *     ),
     *
     *     @OA\Parameter(
     *         name="status",
     *         in="query",
     *         description="처리 상태 필터",
     *         required=false,
     *
     *         @OA\Schema(type="string", enum={"pending","completed","failed"}, example="completed")
     *     ),
     *
     *     @OA\Parameter(
     *         name="start_date",
     *         in="query",
     *         description="시작일 필터 (YYYY-MM-DD)",
     *         required=false,
     *
     *         @OA\Schema(type="string", format="date", example="2025-12-01")
     *     ),
     *
     *     @OA\Parameter(
     *         name="end_date",
     *         in="query",
     *         description="종료일 필터 (YYYY-MM-DD, start_date 이상)",
     *         required=false,
     *
     *         @OA\Schema(type="string", format="date", example="2025-12-31")
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="성공",
     *
     *         @OA\JsonContent(
     *
     *             @OA\Property(property="success", type="boolean", example=true),
     *             @OA\Property(property="message", type="string", example="AI 리포트 목록을 조회했습니다."),
     *             @OA\Property(property="data", ref="#/components/schemas/AiReportPagination")
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=422, description="유효성 검사 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function index() {}

    /**
     * @OA\Post(
     *     path="/api/v1/reports/ai/generate",
     *     tags={"AI Reports"},
     *     summary="AI 리포트 생성",
     *     description="Google Gemini AI를 사용하여 비즈니스 데이터 기반 리포트를 생성합니다. 지출, 매출, 매입, 입출금, 카드/계좌, 미수금 데이터를 종합 분석합니다.",
     *     security={{"BearerAuth": {}}, {"ApiKeyAuth": {}}},
     *
     *     @OA\RequestBody(
     *         required=false,
     *         description="리포트 생성 요청 (모든 필드 선택적, 기본값 사용 가능)",
     *
     *         @OA\JsonContent(ref="#/components/schemas/AiReportGenerateRequest")
     *     ),
     *
     *     @OA\Response(
     *         response=201,
     *         description="리포트 생성 완료",
     *
     *         @OA\JsonContent(
     *
     *             @OA\Property(property="success", type="boolean", example=true),
     *             @OA\Property(property="message", type="string", example="AI 리포트가 생성되었습니다."),
     *             @OA\Property(property="data", ref="#/components/schemas/AiReport")
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=422, description="유효성 검사 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="AI API 오류", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function generate() {}

    /**
     * @OA\Get(
     *     path="/api/v1/reports/ai/{id}",
     *     tags={"AI Reports"},
     *     summary="AI 리포트 상세 조회",
     *     description="특정 AI 리포트의 상세 정보를 조회합니다.",
     *     security={{"BearerAuth": {}}, {"ApiKeyAuth": {}}},
     *
     *     @OA\Parameter(
     *         name="id",
     *         in="path",
     *         description="리포트 ID",
     *         required=true,
     *
     *         @OA\Schema(type="integer", example=1)
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="성공",
     *
     *         @OA\JsonContent(
     *
     *             @OA\Property(property="success", type="boolean", example=true),
     *             @OA\Property(property="message", type="string", example="AI 리포트를 조회했습니다."),
     *             @OA\Property(property="data", ref="#/components/schemas/AiReport")
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=404, description="리포트 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function show() {}

    /**
     * @OA\Delete(
     *     path="/api/v1/reports/ai/{id}",
     *     tags={"AI Reports"},
     *     summary="AI 리포트 삭제",
     *     description="특정 AI 리포트를 삭제합니다.",
     *     security={{"BearerAuth": {}}, {"ApiKeyAuth": {}}},
     *
     *     @OA\Parameter(
     *         name="id",
     *         in="path",
     *         description="리포트 ID",
     *         required=true,
     *
     *         @OA\Schema(type="integer", example=1)
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="삭제 성공",
     *
     *         @OA\JsonContent(
     *
     *             @OA\Property(property="success", type="boolean", example=true),
     *             @OA\Property(property="message", type="string", example="AI 리포트가 삭제되었습니다."),
     *             @OA\Property(property="data", type="null")
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=404, description="리포트 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function destroy() {}
}
