<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(
 *     name="VendorLedger",
 *     description="거래처원장 API - 거래처별 매출/수금 내역 조회"
 * )
 */

/**
 * @OA\Schema(
 *     schema="VendorLedgerItem",
 *     description="거래처원장 리스트 항목",
 *
 *     @OA\Property(property="id", type="integer", description="거래처 ID", example=1),
 *     @OA\Property(property="name", type="string", description="거래처명", example="ABC 주식회사"),
 *     @OA\Property(property="sales_payment_day", type="string", description="결제일", example="25일", nullable=true),
 *     @OA\Property(property="period_sales", type="number", format="float", description="기간 내 매출", example=10000000),
 *     @OA\Property(property="period_collection", type="number", format="float", description="기간 내 수금", example=8000000),
 *     @OA\Property(property="carryover_sales", type="number", format="float", description="이월 매출", example=5000000),
 *     @OA\Property(property="carryover_deposits", type="number", format="float", description="이월 수금", example=3000000)
 * )
 *
 * @OA\Schema(
 *     schema="VendorLedgerSummary",
 *     description="거래처원장 요약 통계",
 *
 *     @OA\Property(property="carryover_balance", type="number", format="float", description="이월잔액", example=2000000),
 *     @OA\Property(property="total_sales", type="number", format="float", description="총 매출", example=10000000),
 *     @OA\Property(property="total_collection", type="number", format="float", description="총 수금", example=8000000),
 *     @OA\Property(property="balance", type="number", format="float", description="현재 잔액", example=4000000)
 * )
 *
 * @OA\Schema(
 *     schema="VendorLedgerTransaction",
 *     description="거래처원장 거래 내역",
 *
 *     @OA\Property(property="id", type="integer", description="거래 ID", example=1),
 *     @OA\Property(property="date", type="string", format="date", description="거래일", example="2025-01-15"),
 *     @OA\Property(property="type", type="string", description="거래 유형", example="sales", enum={"sales", "collection", "note"}),
 *     @OA\Property(property="description", type="string", description="적요", example="제품 납품"),
 *     @OA\Property(property="sales_amount", type="number", format="float", description="매출 금액", example=1000000),
 *     @OA\Property(property="collection_amount", type="number", format="float", description="수금 금액", example=0),
 *     @OA\Property(property="balance", type="number", format="float", description="잔액", example=1000000),
 *     @OA\Property(property="reference_id", type="integer", description="참조 ID", example=1),
 *     @OA\Property(property="reference_type", type="string", description="참조 타입", example="sale", enum={"sale", "deposit", "bill"}),
 *     @OA\Property(property="has_action", type="boolean", description="작업 버튼 표시 여부", example=false),
 *     @OA\Property(property="is_highlighted", type="boolean", description="하이라이트 여부", example=true),
 *     @OA\Property(property="is_parenthesis", type="boolean", description="괄호 표시 여부", example=false),
 *     @OA\Property(property="note_info", type="string", description="어음 정보", example="2025-02-15", nullable=true)
 * )
 *
 * @OA\Schema(
 *     schema="VendorLedgerClient",
 *     description="거래처 정보",
 *
 *     @OA\Property(property="id", type="integer", description="거래처 ID", example=1),
 *     @OA\Property(property="name", type="string", description="거래처명", example="ABC 주식회사"),
 *     @OA\Property(property="business_number", type="string", description="사업자등록번호", example="123-45-67890", nullable=true),
 *     @OA\Property(property="representative_name", type="string", description="대표자", example="홍길동", nullable=true),
 *     @OA\Property(property="phone", type="string", description="전화번호", example="02-1234-5678", nullable=true),
 *     @OA\Property(property="mobile", type="string", description="휴대전화", example="010-1234-5678", nullable=true),
 *     @OA\Property(property="fax", type="string", description="팩스", example="02-1234-5679", nullable=true),
 *     @OA\Property(property="email", type="string", description="이메일", example="contact@example.com", nullable=true),
 *     @OA\Property(property="address", type="string", description="주소", example="서울시 강남구", nullable=true)
 * )
 *
 * @OA\Schema(
 *     schema="VendorLedgerDetail",
 *     description="거래처원장 상세",
 *
 *     @OA\Property(property="client", ref="#/components/schemas/VendorLedgerClient"),
 *     @OA\Property(
 *         property="period",
 *         type="object",
 *         @OA\Property(property="start_date", type="string", format="date", example="2025-01-01"),
 *         @OA\Property(property="end_date", type="string", format="date", example="2025-12-31")
 *     ),
 *     @OA\Property(property="carryover_balance", type="number", format="float", description="이월잔액", example=2000000),
 *     @OA\Property(property="total_sales", type="number", format="float", description="총 매출", example=10000000),
 *     @OA\Property(property="total_collection", type="number", format="float", description="총 수금", example=8000000),
 *     @OA\Property(property="balance", type="number", format="float", description="현재 잔액", example=4000000),
 *     @OA\Property(
 *         property="transactions",
 *         type="array",
 *
 *         @OA\Items(ref="#/components/schemas/VendorLedgerTransaction")
 *     )
 * )
 *
 * @OA\Schema(
 *     schema="VendorLedgerPagination",
 *     description="거래처원장 목록 페이지네이션",
 *     type="object",
 *
 *     @OA\Property(property="current_page", type="integer", example=1),
 *     @OA\Property(property="data", type="array", @OA\Items(ref="#/components/schemas/VendorLedgerItem")),
 *     @OA\Property(property="first_page_url", type="string"),
 *     @OA\Property(property="from", type="integer"),
 *     @OA\Property(property="last_page", type="integer"),
 *     @OA\Property(property="last_page_url", type="string"),
 *     @OA\Property(property="next_page_url", type="string", nullable=true),
 *     @OA\Property(property="path", type="string"),
 *     @OA\Property(property="per_page", type="integer"),
 *     @OA\Property(property="prev_page_url", type="string", nullable=true),
 *     @OA\Property(property="to", type="integer"),
 *     @OA\Property(property="total", type="integer")
 * )
 */
class VendorLedgerApi
{
    /**
     * @OA\Get(
     *     path="/api/v1/vendor-ledger",
     *     operationId="getVendorLedgerList",
     *     tags={"VendorLedger"},
     *     summary="거래처원장 목록 조회",
     *     description="거래처별 매출/수금 집계 목록을 조회합니다.",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\Parameter(
     *         name="search",
     *         in="query",
     *         description="거래처명 검색",
     *
     *         @OA\Schema(type="string", example="ABC")
     *     ),
     *
     *     @OA\Parameter(
     *         name="start_date",
     *         in="query",
     *         description="조회 시작일",
     *
     *         @OA\Schema(type="string", format="date", example="2025-01-01")
     *     ),
     *
     *     @OA\Parameter(
     *         name="end_date",
     *         in="query",
     *         description="조회 종료일",
     *
     *         @OA\Schema(type="string", format="date", example="2025-12-31")
     *     ),
     *
     *     @OA\Parameter(
     *         name="sort_by",
     *         in="query",
     *         description="정렬 기준 (name)",
     *
     *         @OA\Schema(type="string", default="name")
     *     ),
     *
     *     @OA\Parameter(
     *         name="sort_dir",
     *         in="query",
     *         description="정렬 방향",
     *
     *         @OA\Schema(type="string", enum={"asc", "desc"}, default="asc")
     *     ),
     *
     *     @OA\Parameter(
     *         name="per_page",
     *         in="query",
     *         description="페이지당 항목 수",
     *
     *         @OA\Schema(type="integer", default=20)
     *     ),
     *
     *     @OA\Parameter(
     *         name="page",
     *         in="query",
     *         description="페이지 번호",
     *
     *         @OA\Schema(type="integer", default=1)
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="성공",
     *
     *         @OA\JsonContent(
     *
     *             @OA\Property(property="success", type="boolean", example=true),
     *             @OA\Property(property="message", type="string", example="데이터를 조회했습니다."),
     *             @OA\Property(property="data", ref="#/components/schemas/VendorLedgerPagination")
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패"),
     *     @OA\Response(response=403, description="권한 없음")
     * )
     */
    public function index() {}

    /**
     * @OA\Get(
     *     path="/api/v1/vendor-ledger/summary",
     *     operationId="getVendorLedgerSummary",
     *     tags={"VendorLedger"},
     *     summary="거래처원장 요약 통계",
     *     description="전체 거래처의 매출/수금 요약 통계를 조회합니다.",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\Parameter(
     *         name="start_date",
     *         in="query",
     *         description="조회 시작일",
     *
     *         @OA\Schema(type="string", format="date", example="2025-01-01")
     *     ),
     *
     *     @OA\Parameter(
     *         name="end_date",
     *         in="query",
     *         description="조회 종료일",
     *
     *         @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="데이터를 조회했습니다."),
     *             @OA\Property(property="data", ref="#/components/schemas/VendorLedgerSummary")
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패"),
     *     @OA\Response(response=403, description="권한 없음")
     * )
     */
    public function summary() {}

    /**
     * @OA\Get(
     *     path="/api/v1/vendor-ledger/{clientId}",
     *     operationId="getVendorLedgerDetail",
     *     tags={"VendorLedger"},
     *     summary="거래처원장 상세 조회",
     *     description="특정 거래처의 상세 거래 내역을 조회합니다.",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\Parameter(
     *         name="clientId",
     *         in="path",
     *         required=true,
     *         description="거래처 ID",
     *
     *         @OA\Schema(type="integer", example=1)
     *     ),
     *
     *     @OA\Parameter(
     *         name="start_date",
     *         in="query",
     *         description="조회 시작일",
     *
     *         @OA\Schema(type="string", format="date", example="2025-01-01")
     *     ),
     *
     *     @OA\Parameter(
     *         name="end_date",
     *         in="query",
     *         description="조회 종료일",
     *
     *         @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="데이터를 조회했습니다."),
     *             @OA\Property(property="data", ref="#/components/schemas/VendorLedgerDetail")
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패"),
     *     @OA\Response(response=403, description="권한 없음"),
     *     @OA\Response(response=404, description="거래처를 찾을 수 없음")
     * )
     */
    public function show() {}
}
