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

<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(name="Payments", description="결제 관리")
 *
 * @OA\Schema(
 *     schema="Payment",
 *     type="object",
 *     description="결제 정보",
 *
 *     @OA\Property(property="id", type="integer", example=1, description="결제 ID"),
 *     @OA\Property(property="subscription_id", type="integer", example=1, description="구독 ID"),
 *     @OA\Property(property="amount", type="number", format="float", example=29000, description="결제 금액"),
 *     @OA\Property(property="payment_method", type="string", enum={"card","bank","virtual","cash","free"}, example="card", description="결제 수단"),
 *     @OA\Property(property="payment_method_label", type="string", example="카드", description="결제 수단 라벨"),
 *     @OA\Property(property="transaction_id", type="string", example="TXN123456789", nullable=true, description="PG 거래 ID"),
 *     @OA\Property(property="paid_at", type="string", format="date-time", example="2025-01-15T10:30:00", nullable=true, description="결제일시"),
 *     @OA\Property(property="status", type="string", enum={"pending","completed","failed","cancelled","refunded"}, example="completed", description="상태"),
 *     @OA\Property(property="status_label", type="string", example="완료", description="상태 라벨"),
 *     @OA\Property(property="memo", type="string", example="정기 결제", nullable=true, description="메모"),
 *     @OA\Property(property="formatted_amount", type="string", example="29,000원", description="포맷된 금액"),
 *     @OA\Property(property="is_completed", type="boolean", example=true, description="완료 여부"),
 *     @OA\Property(property="is_refundable", type="boolean", example=true, description="환불 가능 여부"),
 *     @OA\Property(property="subscription", type="object", nullable=true,
 *         @OA\Property(property="id", type="integer", example=1),
 *         @OA\Property(property="plan", type="object",
 *             @OA\Property(property="id", type="integer", example=1),
 *             @OA\Property(property="name", type="string", example="스타터"),
 *             @OA\Property(property="code", type="string", example="starter")
 *         ),
 *         description="구독 정보"
 *     ),
 *     @OA\Property(property="created_at", type="string", format="date-time"),
 *     @OA\Property(property="updated_at", type="string", format="date-time")
 * )
 *
 * @OA\Schema(
 *     schema="PaymentCreateRequest",
 *     type="object",
 *     required={"subscription_id","amount","payment_method"},
 *     description="결제 등록 요청 (수동)",
 *
 *     @OA\Property(property="subscription_id", type="integer", example=1, description="구독 ID"),
 *     @OA\Property(property="amount", type="number", format="float", example=29000, minimum=0, 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="TXN123456789", maxLength=100, nullable=true, description="PG 거래 ID"),
 *     @OA\Property(property="memo", type="string", example="정기 결제", maxLength=500, nullable=true, description="메모"),
 *     @OA\Property(property="auto_complete", type="boolean", example=true, description="자동 완료 처리")
 * )
 *
 * @OA\Schema(
 *     schema="PaymentActionRequest",
 *     type="object",
 *     description="결제 액션 요청",
 *
 *     @OA\Property(property="reason", type="string", example="고객 요청", maxLength=500, nullable=true, description="사유"),
 *     @OA\Property(property="transaction_id", type="string", example="TXN123456789", maxLength=100, nullable=true, description="PG 거래 ID")
 * )
 *
 * @OA\Schema(
 *     schema="PaymentSummary",
 *     type="object",
 *     description="결제 요약 통계",
 *
 *     @OA\Property(property="total_count", type="integer", example=50, description="전체 건수"),
 *     @OA\Property(property="completed_count", type="integer", example=45, description="완료 건수"),
 *     @OA\Property(property="pending_count", type="integer", example=2, description="대기 건수"),
 *     @OA\Property(property="failed_count", type="integer", example=1, description="실패 건수"),
 *     @OA\Property(property="cancelled_count", type="integer", example=1, description="취소 건수"),
 *     @OA\Property(property="refunded_count", type="integer", example=1, description="환불 건수"),
 *     @OA\Property(property="total_completed_amount", type="number", format="float", example=1305000, description="완료 총액"),
 *     @OA\Property(property="total_refunded_amount", type="number", format="float", example=29000, description="환불 총액"),
 *     @OA\Property(property="net_amount", type="number", format="float", example=1276000, description="순 금액"),
 *     @OA\Property(property="by_method", type="object",
 *         @OA\Property(property="card", type="object",
 *             @OA\Property(property="count", type="integer", example=40),
 *             @OA\Property(property="total_amount", type="number", format="float", example=1160000)
 *         ),
 *         @OA\Property(property="bank", type="object",
 *             @OA\Property(property="count", type="integer", example=5),
 *             @OA\Property(property="total_amount", type="number", format="float", example=145000)
 *         ),
 *         description="결제 수단별 집계"
 *     )
 * )
 *
 * @OA\Schema(
 *     schema="PaymentStatement",
 *     type="object",
 *     description="결제 명세서",
 *
 *     @OA\Property(property="statement_no", type="string", example="INV-20250115-000001", description="명세서 번호"),
 *     @OA\Property(property="issued_at", type="string", format="date-time", description="발행일시"),
 *     @OA\Property(property="payment", type="object",
 *         @OA\Property(property="id", type="integer", example=1),
 *         @OA\Property(property="amount", type="number", format="float", example=29000),
 *         @OA\Property(property="formatted_amount", type="string", example="29,000원"),
 *         @OA\Property(property="payment_method", type="string", example="card"),
 *         @OA\Property(property="payment_method_label", type="string", example="카드"),
 *         @OA\Property(property="transaction_id", type="string", example="TXN123456789", nullable=true),
 *         @OA\Property(property="status", type="string", example="completed"),
 *         @OA\Property(property="status_label", type="string", example="완료"),
 *         @OA\Property(property="paid_at", type="string", format="date-time", nullable=true),
 *         @OA\Property(property="memo", type="string", nullable=true)
 *     ),
 *     @OA\Property(property="subscription", type="object",
 *         @OA\Property(property="id", type="integer", example=1),
 *         @OA\Property(property="started_at", type="string", format="date", example="2025-01-01"),
 *         @OA\Property(property="ended_at", type="string", format="date", example="2025-02-01", nullable=true),
 *         @OA\Property(property="status", type="string", example="active"),
 *         @OA\Property(property="status_label", type="string", example="활성")
 *     ),
 *     @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"),
 *         @OA\Property(property="billing_cycle_label", type="string", example="월간")
 *     ),
 *     @OA\Property(property="customer", type="object",
 *         @OA\Property(property="tenant_id", type="integer", example=1),
 *         @OA\Property(property="company_name", type="string", example="테스트 회사"),
 *         @OA\Property(property="business_number", type="string", example="123-45-67890", nullable=true),
 *         @OA\Property(property="representative", type="string", example="홍길동", nullable=true),
 *         @OA\Property(property="address", type="string", example="서울시 강남구", nullable=true),
 *         @OA\Property(property="email", type="string", example="contact@test.com", nullable=true),
 *         @OA\Property(property="phone", type="string", example="02-1234-5678", nullable=true)
 *     ),
 *     @OA\Property(property="items", type="array",
 *
 *         @OA\Items(type="object",
 *
 *             @OA\Property(property="description", type="string", example="스타터 구독 (2025.01.01)"),
 *             @OA\Property(property="quantity", type="integer", example=1),
 *             @OA\Property(property="unit_price", type="number", format="float", example=29000),
 *             @OA\Property(property="amount", type="number", format="float", example=29000)
 *         )
 *     ),
 *     @OA\Property(property="subtotal", type="number", format="float", example=29000, description="소계"),
 *     @OA\Property(property="tax", type="number", format="float", example=0, description="세금"),
 *     @OA\Property(property="total", type="number", format="float", example=29000, description="총액")
 * )
 */
class PaymentApi
{
    /**
     * @OA\Get(
     *     path="/api/v1/payments",
     *     tags={"Payments"},
     *     summary="결제 목록 조회",
     *     description="테넌트의 결제 목록을 조회합니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Parameter(name="status", in="query", description="상태 필터", @OA\Schema(type="string", enum={"pending","completed","failed","cancelled","refunded"})),
     *     @OA\Parameter(name="payment_method", in="query", description="결제 수단", @OA\Schema(type="string", enum={"card","bank","virtual","cash","free"})),
     *     @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="search", in="query", description="검색어 (거래ID, 메모)", @OA\Schema(type="string", maxLength=100)),
     *     @OA\Parameter(name="sort_by", in="query", description="정렬 기준", @OA\Schema(type="string", enum={"created_at","paid_at","amount"}, default="created_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/Payment")),
     *                         @OA\Property(property="per_page", type="integer", example=20),
     *                         @OA\Property(property="total", type="integer", example=50)
     *                     )
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @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/payments/summary",
     *     tags={"Payments"},
     *     summary="결제 요약 통계",
     *     description="테넌트의 결제 요약 통계를 조회합니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @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\Response(
     *         response=200,
     *         description="조회 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(property="data", ref="#/components/schemas/PaymentSummary")
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function summary() {}

    /**
     * @OA\Get(
     *     path="/api/v1/payments/{id}",
     *     tags={"Payments"},
     *     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/Payment")
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @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/payments",
     *     tags={"Payments"},
     *     summary="결제 등록 (수동)",
     *     description="수동으로 결제를 등록합니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(ref="#/components/schemas/PaymentCreateRequest")
     *     ),
     *
     *     @OA\Response(
     *         response=201,
     *         description="등록 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(property="data", ref="#/components/schemas/Payment")
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @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\Post(
     *     path="/api/v1/payments/{id}/complete",
     *     tags={"Payments"},
     *     summary="결제 완료 처리",
     *     description="대기 중인 결제를 완료 처리합니다.",
     *     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="transaction_id", type="string", example="TXN123456789", description="PG 거래 ID")
     *         )
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="완료 처리 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(property="data", ref="#/components/schemas/Payment")
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @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 complete() {}

    /**
     * @OA\Post(
     *     path="/api/v1/payments/{id}/cancel",
     *     tags={"Payments"},
     *     summary="결제 취소",
     *     description="결제를 취소합니다. 대기(pending) 또는 완료(completed) 상태에서만 가능합니다.",
     *     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/PaymentActionRequest")
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="취소 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(property="data", ref="#/components/schemas/Payment")
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @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/payments/{id}/refund",
     *     tags={"Payments"},
     *     summary="환불 처리",
     *     description="완료된 결제를 환불 처리합니다. 완료(completed) 상태에서만 가능합니다.",
     *     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/PaymentActionRequest")
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="환불 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(property="data", ref="#/components/schemas/Payment")
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @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 refund() {}

    /**
     * @OA\Get(
     *     path="/api/v1/payments/{id}/statement",
     *     tags={"Payments"},
     *     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/PaymentStatement")
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @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 statement() {}
}