<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(name="Subscriptions", description="구독 관리")
 *
 * @OA\Schema(
 *     schema="Subscription",
 *     type="object",
 *     description="구독 정보",
 *
 *     @OA\Property(property="id", type="integer", example=1, description="구독 ID"),
 *     @OA\Property(property="tenant_id", type="integer", example=1, description="테넌트 ID"),
 *     @OA\Property(property="plan_id", type="integer", example=1, description="요금제 ID"),
 *     @OA\Property(property="started_at", type="string", format="date-time", example="2025-01-01T00:00:00", description="시작일"),
 *     @OA\Property(property="ended_at", type="string", format="date-time", example="2025-02-01T00:00:00", nullable=true, description="종료일"),
 *     @OA\Property(property="status", type="string", enum={"pending","active","cancelled","expired","suspended"}, example="active", description="상태"),
 *     @OA\Property(property="status_label", type="string", example="활성", description="상태 라벨"),
 *     @OA\Property(property="cancelled_at", type="string", format="date-time", nullable=true, description="취소일"),
 *     @OA\Property(property="cancel_reason", type="string", nullable=true, description="취소 사유"),
 *     @OA\Property(property="is_expired", type="boolean", example=false, description="만료 여부"),
 *     @OA\Property(property="is_valid", type="boolean", example=true, description="유효 여부"),
 *     @OA\Property(property="remaining_days", type="integer", example=30, nullable=true, description="남은 일수 (무제한은 null)"),
 *     @OA\Property(property="total_paid", type="number", format="float", example=29000, description="총 결제 금액"),
 *     @OA\Property(property="plan", type="object", nullable=true,
 *         @OA\Property(property="id", type="integer", example=1),
 *         @OA\Property(property="name", type="string", example="스타터"),
 *         @OA\Property(property="code", type="string", example="starter"),
 *         @OA\Property(property="price", type="number", format="float", example=29000),
 *         @OA\Property(property="billing_cycle", type="string", example="monthly"),
 *         description="요금제 정보"
 *     ),
 *     @OA\Property(property="payments", type="array", @OA\Items(ref="#/components/schemas/Payment"), nullable=true, description="결제 내역"),
 *     @OA\Property(property="created_at", type="string", format="date-time"),
 *     @OA\Property(property="updated_at", type="string", format="date-time")
 * )
 *
 * @OA\Schema(
 *     schema="SubscriptionCreateRequest",
 *     type="object",
 *     required={"plan_id"},
 *     description="구독 등록 요청",
 *
 *     @OA\Property(property="plan_id", type="integer", example=1, description="요금제 ID"),
 *     @OA\Property(property="started_at", type="string", format="date", example="2025-01-01", nullable=true, description="시작일 (미지정 시 현재)"),
 *     @OA\Property(property="payment_method", type="string", enum={"card","bank","virtual","cash","free"}, example="card", description="결제 수단"),
 *     @OA\Property(property="transaction_id", type="string", example="TXN123456", nullable=true, description="PG 거래 ID"),
 *     @OA\Property(property="auto_complete", type="boolean", example=true, description="자동 결제 완료 처리")
 * )
 *
 * @OA\Schema(
 *     schema="SubscriptionCancelRequest",
 *     type="object",
 *     description="구독 취소 요청",
 *
 *     @OA\Property(property="reason", type="string", example="서비스 불만족", maxLength=500, nullable=true, description="취소 사유")
 * )
 *
 * @OA\Schema(
 *     schema="UsageResponse",
 *     type="object",
 *     description="사용량 정보",
 *
 *     @OA\Property(property="users", type="object",
 *         @OA\Property(property="used", type="integer", example=5, description="현재 사용자 수"),
 *         @OA\Property(property="limit", type="integer", example=10, description="최대 사용자 수"),
 *         @OA\Property(property="percentage", type="number", format="float", example=50.0, description="사용률 (%)")
 *     ),
 *     @OA\Property(property="storage", type="object",
 *         @OA\Property(property="used", type="integer", example=1288490188, description="사용 용량 (bytes)"),
 *         @OA\Property(property="used_formatted", type="string", example="1.2 GB", description="사용 용량 (포맷)"),
 *         @OA\Property(property="limit", type="integer", example=10737418240, description="최대 용량 (bytes)"),
 *         @OA\Property(property="limit_formatted", type="string", example="10 GB", description="최대 용량 (포맷)"),
 *         @OA\Property(property="percentage", type="number", format="float", example=12.0, description="사용률 (%)")
 *     ),
 *     @OA\Property(property="subscription", type="object",
 *         @OA\Property(property="plan", type="string", example="스타터", nullable=true, description="요금제명"),
 *         @OA\Property(property="status", type="string", example="active", nullable=true, description="구독 상태"),
 *         @OA\Property(property="remaining_days", type="integer", example=25, nullable=true, description="남은 일수"),
 *         @OA\Property(property="started_at", type="string", format="date", example="2025-01-01", nullable=true),
 *         @OA\Property(property="ended_at", type="string", format="date", example="2025-02-01", nullable=true)
 *     )
 * )
 *
 * @OA\Schema(
 *     schema="DataExport",
 *     type="object",
 *     description="데이터 내보내기 정보",
 *
 *     @OA\Property(property="id", type="integer", example=1, description="ID"),
 *     @OA\Property(property="tenant_id", type="integer", example=1, description="테넌트 ID"),
 *     @OA\Property(property="export_type", type="string", enum={"all","users","products","orders","clients"}, example="all", description="내보내기 유형"),
 *     @OA\Property(property="status", type="string", enum={"pending","processing","completed","failed"}, example="pending", description="상태"),
 *     @OA\Property(property="status_label", type="string", example="대기중", description="상태 라벨"),
 *     @OA\Property(property="file_path", type="string", nullable=true, description="파일 경로"),
 *     @OA\Property(property="file_name", type="string", nullable=true, description="파일명"),
 *     @OA\Property(property="file_size", type="integer", nullable=true, description="파일 크기 (bytes)"),
 *     @OA\Property(property="file_size_formatted", type="string", example="1.5 MB", description="파일 크기 (포맷)"),
 *     @OA\Property(property="options", type="object", nullable=true, description="내보내기 옵션"),
 *     @OA\Property(property="started_at", type="string", format="date-time", nullable=true, description="시작 시간"),
 *     @OA\Property(property="completed_at", type="string", format="date-time", nullable=true, description="완료 시간"),
 *     @OA\Property(property="error_message", type="string", nullable=true, description="에러 메시지"),
 *     @OA\Property(property="is_completed", type="boolean", example=false, description="완료 여부"),
 *     @OA\Property(property="is_downloadable", type="boolean", example=false, description="다운로드 가능 여부"),
 *     @OA\Property(property="created_at", type="string", format="date-time"),
 *     @OA\Property(property="updated_at", type="string", format="date-time")
 * )
 *
 * @OA\Schema(
 *     schema="ExportCreateRequest",
 *     type="object",
 *     required={"export_type"},
 *     description="내보내기 요청",
 *
 *     @OA\Property(property="export_type", type="string", enum={"all","users","products","orders","clients"}, example="all", description="내보내기 유형"),
 *     @OA\Property(property="options", type="object", nullable=true,
 *         @OA\Property(property="format", type="string", enum={"xlsx","csv","json"}, example="xlsx", description="파일 포맷"),
 *         @OA\Property(property="include_deleted", type="boolean", example=false, description="삭제된 데이터 포함 여부")
 *     )
 * )
 */
class SubscriptionApi
{
    /**
     * @OA\Get(
     *     path="/api/v1/subscriptions",
     *     tags={"Subscriptions"},
     *     summary="구독 목록 조회",
     *     description="테넌트의 구독 목록을 조회합니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Parameter(name="status", in="query", description="상태 필터", @OA\Schema(type="string", enum={"pending","active","cancelled","expired","suspended"})),
     *     @OA\Parameter(name="valid_only", in="query", description="유효한 구독만", @OA\Schema(type="boolean")),
     *     @OA\Parameter(name="expiring_within", in="query", description="N일 이내 만료 예정", @OA\Schema(type="integer", minimum=1, maximum=365)),
     *     @OA\Parameter(name="start_date", in="query", description="시작일 (시작일 기준)", @OA\Schema(type="string", format="date")),
     *     @OA\Parameter(name="end_date", in="query", description="종료일 (시작일 기준)", @OA\Schema(type="string", format="date")),
     *     @OA\Parameter(name="sort_by", in="query", description="정렬 기준", @OA\Schema(type="string", enum={"started_at","ended_at","created_at"}, default="started_at")),
     *     @OA\Parameter(name="sort_dir", in="query", description="정렬 방향", @OA\Schema(type="string", enum={"asc","desc"}, default="desc")),
     *     @OA\Parameter(ref="#/components/parameters/Page"),
     *     @OA\Parameter(ref="#/components/parameters/Size"),
     *
     *     @OA\Response(
     *         response=200,
     *         description="조회 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(
     *                         property="data",
     *                         type="object",
     *                         @OA\Property(property="current_page", type="integer", example=1),
     *                         @OA\Property(property="data", type="array", @OA\Items(ref="#/components/schemas/Subscription")),
     *                         @OA\Property(property="per_page", type="integer", example=20),
     *                         @OA\Property(property="total", type="integer", example=10)
     *                     )
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function index() {}

    /**
     * @OA\Get(
     *     path="/api/v1/subscriptions/current",
     *     tags={"Subscriptions"},
     *     summary="현재 활성 구독 조회",
     *     description="테넌트의 현재 활성 구독을 조회합니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Response(
     *         response=200,
     *         description="조회 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(property="data", ref="#/components/schemas/Subscription", nullable=true)
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function current() {}

    /**
     * @OA\Post(
     *     path="/api/v1/subscriptions",
     *     tags={"Subscriptions"},
     *     summary="구독 등록",
     *     description="새로운 구독을 등록합니다. 이미 활성 구독이 있으면 등록할 수 없습니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(ref="#/components/schemas/SubscriptionCreateRequest")
     *     ),
     *
     *     @OA\Response(
     *         response=201,
     *         description="등록 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(property="data", ref="#/components/schemas/Subscription")
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=400, description="이미 활성 구독 존재", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=404, description="요금제 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function store() {}

    /**
     * @OA\Get(
     *     path="/api/v1/subscriptions/{id}",
     *     tags={"Subscriptions"},
     *     summary="구독 상세 조회",
     *     description="구독 상세 정보를 조회합니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Parameter(name="id", in="path", required=true, description="구독 ID", @OA\Schema(type="integer")),
     *
     *     @OA\Response(
     *         response=200,
     *         description="조회 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(property="data", ref="#/components/schemas/Subscription")
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=404, description="구독 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function show() {}

    /**
     * @OA\Post(
     *     path="/api/v1/subscriptions/{id}/cancel",
     *     tags={"Subscriptions"},
     *     summary="구독 취소",
     *     description="구독을 취소합니다. 활성(active) 또는 대기(pending) 상태에서만 가능합니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Parameter(name="id", in="path", required=true, description="구독 ID", @OA\Schema(type="integer")),
     *
     *     @OA\RequestBody(
     *         required=false,
     *
     *         @OA\JsonContent(ref="#/components/schemas/SubscriptionCancelRequest")
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="취소 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(property="data", ref="#/components/schemas/Subscription")
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=400, description="취소 불가 상태", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=404, description="구독 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function cancel() {}

    /**
     * @OA\Post(
     *     path="/api/v1/subscriptions/{id}/renew",
     *     tags={"Subscriptions"},
     *     summary="구독 갱신",
     *     description="구독을 갱신합니다. 활성(active) 상태에서만 가능합니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Parameter(name="id", in="path", required=true, description="구독 ID", @OA\Schema(type="integer")),
     *
     *     @OA\RequestBody(
     *         required=false,
     *
     *         @OA\JsonContent(
     *
     *             @OA\Property(property="payment_method", type="string", enum={"card","bank","virtual","cash","free"}, example="card"),
     *             @OA\Property(property="transaction_id", type="string", example="TXN654321"),
     *             @OA\Property(property="auto_complete", type="boolean", example=true)
     *         )
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="갱신 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(property="data", ref="#/components/schemas/Subscription")
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=400, description="갱신 불가 상태", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=404, description="구독 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function renew() {}

    /**
     * @OA\Post(
     *     path="/api/v1/subscriptions/{id}/suspend",
     *     tags={"Subscriptions"},
     *     summary="구독 일시정지",
     *     description="구독을 일시정지합니다. 활성(active) 상태에서만 가능합니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Parameter(name="id", in="path", required=true, description="구독 ID", @OA\Schema(type="integer")),
     *
     *     @OA\Response(
     *         response=200,
     *         description="일시정지 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(property="data", ref="#/components/schemas/Subscription")
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=400, description="일시정지 불가 상태", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=404, description="구독 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function suspend() {}

    /**
     * @OA\Post(
     *     path="/api/v1/subscriptions/{id}/resume",
     *     tags={"Subscriptions"},
     *     summary="구독 재개",
     *     description="일시정지된 구독을 재개합니다. 일시정지(suspended) 상태에서만 가능합니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Parameter(name="id", in="path", required=true, description="구독 ID", @OA\Schema(type="integer")),
     *
     *     @OA\Response(
     *         response=200,
     *         description="재개 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(property="data", ref="#/components/schemas/Subscription")
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=400, description="재개 불가 상태", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=404, description="구독 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function resume() {}

    /**
     * @OA\Get(
     *     path="/api/v1/subscriptions/usage",
     *     tags={"Subscriptions"},
     *     summary="사용량 조회",
     *     description="테넌트의 사용자, 저장소, 구독 사용량 정보를 조회합니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Response(
     *         response=200,
     *         description="조회 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(property="data", ref="#/components/schemas/UsageResponse")
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function usage() {}

    /**
     * @OA\Post(
     *     path="/api/v1/subscriptions/export",
     *     tags={"Subscriptions"},
     *     summary="데이터 내보내기 요청",
     *     description="테넌트 데이터를 내보내기 요청합니다. 백그라운드에서 처리되며 완료 후 다운로드 가능합니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(ref="#/components/schemas/ExportCreateRequest")
     *     ),
     *
     *     @OA\Response(
     *         response=201,
     *         description="요청 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(property="data", ref="#/components/schemas/DataExport")
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=400, description="진행 중인 내보내기 존재", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @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="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function export() {}

    /**
     * @OA\Get(
     *     path="/api/v1/subscriptions/export/{id}",
     *     tags={"Subscriptions"},
     *     summary="내보내기 상태 조회",
     *     description="내보내기 요청의 현재 상태를 조회합니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Parameter(name="id", in="path", required=true, description="내보내기 ID", @OA\Schema(type="integer")),
     *
     *     @OA\Response(
     *         response=200,
     *         description="조회 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(property="data", ref="#/components/schemas/DataExport")
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=404, description="내보내기 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function exportStatus() {}
}
