feat: Phase 8 SaaS 확장 - 구독관리/결제내역 API 추가

- 사용량 조회 API (GET /subscriptions/usage)
- 데이터 내보내기 API (POST/GET /subscriptions/export)
- 결제 명세서 API (GET /payments/{id}/statement)
- DataExport 모델 및 마이그레이션 추가

app/Swagger/v1/SubscriptionApi.php

@@ -56,6 +56,69 @@
  *
  *     @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
 {
@@ -359,4 +422,105 @@ public function suspend() {}
      * )
      */
     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() {}
 }