<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(name="App Version", description="앱 버전 관리 (인앱 업데이트)")
 */

/**
 * App Version 관련 스키마 정의
 * -----------------------------------------------------------------------------
 */

/**
 * @OA\Schema(
 *     schema="AppVersionLatest",
 *     type="object",
 *     description="최신 앱 버전 정보",
 *
 *     @OA\Property(property="id", type="integer", example=3),
 *     @OA\Property(property="version_code", type="integer", example=2, description="정수 비교용 버전 코드"),
 *     @OA\Property(property="version_name", type="string", example="0.2", description="표시용 버전명"),
 *     @OA\Property(property="release_notes", type="string", nullable=true, example="- 알림음 채널 정리\n- 인앱 업데이트 추가", description="변경사항"),
 *     @OA\Property(property="force_update", type="boolean", example=false, description="강제 업데이트 여부"),
 *     @OA\Property(property="apk_size", type="integer", nullable=true, example=15728640, description="APK 파일 크기(bytes)"),
 *     @OA\Property(property="download_url", type="string", example="https://api.codebridge-x.com/api/v1/app/download/3", description="APK 다운로드 URL"),
 *     @OA\Property(property="published_at", type="string", format="date", nullable=true, example="2026-01-30", description="배포일")
 * )
 *
 * @OA\Schema(
 *     schema="AppVersionCheckResponse",
 *     type="object",
 *     description="버전 확인 응답",
 *
 *     @OA\Property(property="has_update", type="boolean", example=true, description="업데이트 존재 여부"),
 *     @OA\Property(
 *         property="latest_version",
 *         nullable=true,
 *         ref="#/components/schemas/AppVersionLatest",
 *         description="최신 버전 정보 (has_update=false면 null)"
 *     )
 * )
 */
class AppVersionApi
{
    /**
     * @OA\Get(
     *     path="/api/v1/app/version",
     *     tags={"App Version"},
     *     summary="최신 버전 확인",
     *     description="현재 앱 버전과 서버의 최신 버전을 비교하여 업데이트 필요 여부를 반환합니다. Bearer 토큰 불필요, API Key만 필요합니다.",
     *     security={{"ApiKeyAuth": {}}},
     *
     *     @OA\Parameter(
     *         name="platform",
     *         in="query",
     *         required=false,
     *         description="플랫폼 (기본값: android)",
     *
     *         @OA\Schema(type="string", enum={"android", "ios"}, example="android")
     *     ),
     *
     *     @OA\Parameter(
     *         name="current_version_code",
     *         in="query",
     *         required=true,
     *         description="현재 앱의 버전 코드 (정수)",
     *
     *         @OA\Schema(type="integer", example=1)
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="버전 확인 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(property="data", ref="#/components/schemas/AppVersionCheckResponse")
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="API Key 인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function latestVersion() {}

    /**
     * @OA\Get(
     *     path="/api/v1/app/download/{id}",
     *     tags={"App Version"},
     *     summary="APK 다운로드",
     *     description="지정된 버전의 APK 파일을 다운로드합니다. 다운로드 카운트가 자동으로 증가합니다. Bearer 토큰 불필요, API Key만 필요합니다.",
     *     security={{"ApiKeyAuth": {}}},
     *
     *     @OA\Parameter(
     *         name="id",
     *         in="path",
     *         required=true,
     *         description="앱 버전 ID",
     *
     *         @OA\Schema(type="integer", example=3)
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="APK 파일 다운로드",
     *
     *         @OA\MediaType(
     *             mediaType="application/vnd.android.package-archive",
     *
     *             @OA\Schema(type="string", format="binary")
     *         )
     *     ),
     *
     *     @OA\Response(response=404, description="APK 파일을 찾을 수 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=401, description="API Key 인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function download() {}
}
