<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(name="Client", description="거래처 관리")
 *
 * @OA\Schema(
 *   schema="Client",
 *   type="object",
 *   required={"id","client_code","name"},
 *
 *   @OA\Property(property="id", type="integer", example=1),
 *   @OA\Property(property="tenant_id", type="integer", example=1),
 *   @OA\Property(property="client_group_id", type="integer", nullable=true, example=1, description="고객 그룹 ID"),
 *   @OA\Property(property="client_code", type="string", example="CLIENT_001"),
 *   @OA\Property(property="name", type="string", example="거래처명"),
 *   @OA\Property(property="client_type", type="string", enum={"매입", "매출", "매입매출"}, example="매입", description="거래처 유형"),
 *   @OA\Property(property="contact_person", type="string", nullable=true, example="홍길동"),
 *   @OA\Property(property="phone", type="string", nullable=true, example="02-1234-5678"),
 *   @OA\Property(property="mobile", type="string", nullable=true, example="010-1234-5678", description="모바일 번호"),
 *   @OA\Property(property="fax", type="string", nullable=true, example="02-1234-5679", description="팩스 번호"),
 *   @OA\Property(property="email", type="string", nullable=true, example="client@example.com"),
 *   @OA\Property(property="address", type="string", nullable=true, example="서울시 강남구"),
 *   @OA\Property(property="manager_name", type="string", nullable=true, example="김담당", description="담당자명"),
 *   @OA\Property(property="manager_tel", type="string", nullable=true, example="010-9876-5432", description="담당자 전화"),
 *   @OA\Property(property="system_manager", type="string", nullable=true, example="박시스템", description="시스템 관리자"),
 *   @OA\Property(property="account_id", type="string", nullable=true, example="user123", description="계정 ID"),
 *   @OA\Property(property="purchase_payment_day", type="string", nullable=true, example="매월 25일", description="매입 결제일"),
 *   @OA\Property(property="sales_payment_day", type="string", nullable=true, example="매월 말일", description="매출 결제일"),
 *   @OA\Property(property="business_no", type="string", nullable=true, maxLength=20, example="123-45-67890", description="사업자등록번호"),
 *   @OA\Property(property="business_type", type="string", nullable=true, maxLength=50, example="제조업", description="업태"),
 *   @OA\Property(property="business_item", type="string", nullable=true, maxLength=100, example="전자부품", description="업종"),
 *   @OA\Property(property="tax_agreement", type="boolean", example=false, description="세금 약정 여부"),
 *   @OA\Property(property="tax_amount", type="number", format="float", nullable=true, example=1000000, description="약정 금액"),
 *   @OA\Property(property="tax_start_date", type="string", format="date", nullable=true, example="2025-01-01", description="약정 시작일"),
 *   @OA\Property(property="tax_end_date", type="string", format="date", nullable=true, example="2025-12-31", description="약정 종료일"),
 *   @OA\Property(property="bad_debt", type="boolean", example=false, description="악성채권 여부"),
 *   @OA\Property(property="bad_debt_amount", type="number", format="float", nullable=true, example=500000, description="악성채권 금액"),
 *   @OA\Property(property="bad_debt_receive_date", type="string", format="date", nullable=true, example="2024-06-01", description="채권 발생일"),
 *   @OA\Property(property="bad_debt_end_date", type="string", format="date", nullable=true, example="2025-06-01", description="채권 만료일"),
 *   @OA\Property(property="bad_debt_progress", type="string", enum={"협의중", "소송중", "회수완료", "대손처리"}, nullable=true, description="진행 상태"),
 *   @OA\Property(property="memo", type="string", nullable=true, example="특이사항 메모", description="메모"),
 *   @OA\Property(property="is_active", type="boolean", example=true, description="활성 여부"),
 *   @OA\Property(property="created_at", type="string", example="2025-10-01 12:00:00"),
 *   @OA\Property(property="updated_at", type="string", example="2025-10-01 12:00:00")
 * )
 *
 * @OA\Schema(
 *   schema="ClientPagination",
 *   type="object",
 *
 *   @OA\Property(property="current_page", type="integer", example=1),
 *   @OA\Property(
 *     property="data",
 *     type="array",
 *
 *     @OA\Items(ref="#/components/schemas/Client")
 *   ),
 *
 *   @OA\Property(property="first_page_url", type="string", example="/api/v1/clients?page=1"),
 *   @OA\Property(property="from", type="integer", example=1),
 *   @OA\Property(property="last_page", type="integer", example=3),
 *   @OA\Property(property="last_page_url", type="string", example="/api/v1/clients?page=3"),
 *   @OA\Property(
 *     property="links",
 *     type="array",
 *
 *     @OA\Items(type="object",
 *
 *       @OA\Property(property="url", type="string", nullable=true, example=null),
 *       @OA\Property(property="label", type="string", example="&laquo; Previous"),
 *       @OA\Property(property="active", type="boolean", example=false)
 *     )
 *   ),
 *   @OA\Property(property="next_page_url", type="string", nullable=true, example="/api/v1/clients?page=2"),
 *   @OA\Property(property="path", type="string", example="/api/v1/clients"),
 *   @OA\Property(property="per_page", type="integer", example=20),
 *   @OA\Property(property="prev_page_url", type="string", nullable=true, example=null),
 *   @OA\Property(property="to", type="integer", example=20),
 *   @OA\Property(property="total", type="integer", example=50)
 * )
 *
 * @OA\Schema(
 *   schema="ClientCreateRequest",
 *   type="object",
 *   required={"client_code","name"},
 *
 *   @OA\Property(property="client_group_id", type="integer", nullable=true, example=1, description="고객 그룹 ID"),
 *   @OA\Property(property="client_code", type="string", maxLength=50, example="CLIENT_001"),
 *   @OA\Property(property="name", type="string", maxLength=100, example="거래처명"),
 *   @OA\Property(property="client_type", type="string", enum={"매입", "매출", "매입매출"}, nullable=true, example="매입", description="거래처 유형"),
 *   @OA\Property(property="contact_person", type="string", nullable=true, maxLength=100, example="홍길동"),
 *   @OA\Property(property="phone", type="string", nullable=true, maxLength=20, example="02-1234-5678"),
 *   @OA\Property(property="mobile", type="string", nullable=true, maxLength=20, example="010-1234-5678", description="모바일 번호"),
 *   @OA\Property(property="fax", type="string", nullable=true, maxLength=20, example="02-1234-5679", description="팩스 번호"),
 *   @OA\Property(property="email", type="string", nullable=true, maxLength=100, example="client@example.com"),
 *   @OA\Property(property="address", type="string", nullable=true, maxLength=255, example="서울시 강남구"),
 *   @OA\Property(property="manager_name", type="string", nullable=true, maxLength=50, example="김담당", description="담당자명"),
 *   @OA\Property(property="manager_tel", type="string", nullable=true, maxLength=20, example="010-9876-5432", description="담당자 전화"),
 *   @OA\Property(property="system_manager", type="string", nullable=true, maxLength=50, example="박시스템", description="시스템 관리자"),
 *   @OA\Property(property="account_id", type="string", nullable=true, maxLength=50, example="user123", description="계정 ID"),
 *   @OA\Property(property="account_password", type="string", nullable=true, maxLength=255, example="password123", description="계정 비밀번호"),
 *   @OA\Property(property="purchase_payment_day", type="string", nullable=true, maxLength=20, example="매월 25일", description="매입 결제일"),
 *   @OA\Property(property="sales_payment_day", type="string", nullable=true, maxLength=20, example="매월 말일", description="매출 결제일"),
 *   @OA\Property(property="business_no", type="string", nullable=true, maxLength=20, example="123-45-67890", description="사업자등록번호"),
 *   @OA\Property(property="business_type", type="string", nullable=true, maxLength=50, example="제조업", description="업태"),
 *   @OA\Property(property="business_item", type="string", nullable=true, maxLength=100, example="전자부품", description="업종"),
 *   @OA\Property(property="tax_agreement", type="boolean", nullable=true, example=false, description="세금 약정 여부"),
 *   @OA\Property(property="tax_amount", type="number", format="float", nullable=true, example=1000000, description="약정 금액"),
 *   @OA\Property(property="tax_start_date", type="string", format="date", nullable=true, example="2025-01-01", description="약정 시작일"),
 *   @OA\Property(property="tax_end_date", type="string", format="date", nullable=true, example="2025-12-31", description="약정 종료일"),
 *   @OA\Property(property="bad_debt", type="boolean", nullable=true, example=false, description="악성채권 여부"),
 *   @OA\Property(property="bad_debt_amount", type="number", format="float", nullable=true, example=500000, description="악성채권 금액"),
 *   @OA\Property(property="bad_debt_receive_date", type="string", format="date", nullable=true, example="2024-06-01", description="채권 발생일"),
 *   @OA\Property(property="bad_debt_end_date", type="string", format="date", nullable=true, example="2025-06-01", description="채권 만료일"),
 *   @OA\Property(property="bad_debt_progress", type="string", enum={"협의중", "소송중", "회수완료", "대손처리"}, nullable=true, description="진행 상태"),
 *   @OA\Property(property="memo", type="string", nullable=true, example="특이사항 메모", description="메모"),
 *   @OA\Property(property="is_active", type="boolean", example=true, description="활성 여부")
 * )
 *
 * @OA\Schema(
 *   schema="ClientUpdateRequest",
 *   type="object",
 *
 *   @OA\Property(property="client_group_id", type="integer", nullable=true, example=1, description="고객 그룹 ID"),
 *   @OA\Property(property="client_code", type="string", maxLength=50),
 *   @OA\Property(property="name", type="string", maxLength=100),
 *   @OA\Property(property="client_type", type="string", enum={"매입", "매출", "매입매출"}, nullable=true, description="거래처 유형"),
 *   @OA\Property(property="contact_person", type="string", nullable=true, maxLength=100),
 *   @OA\Property(property="phone", type="string", nullable=true, maxLength=20),
 *   @OA\Property(property="mobile", type="string", nullable=true, maxLength=20, description="모바일 번호"),
 *   @OA\Property(property="fax", type="string", nullable=true, maxLength=20, description="팩스 번호"),
 *   @OA\Property(property="email", type="string", nullable=true, maxLength=100),
 *   @OA\Property(property="address", type="string", nullable=true, maxLength=255),
 *   @OA\Property(property="manager_name", type="string", nullable=true, maxLength=50, description="담당자명"),
 *   @OA\Property(property="manager_tel", type="string", nullable=true, maxLength=20, description="담당자 전화"),
 *   @OA\Property(property="system_manager", type="string", nullable=true, maxLength=50, description="시스템 관리자"),
 *   @OA\Property(property="account_id", type="string", nullable=true, maxLength=50, description="계정 ID"),
 *   @OA\Property(property="account_password", type="string", nullable=true, maxLength=255, description="계정 비밀번호"),
 *   @OA\Property(property="purchase_payment_day", type="string", nullable=true, maxLength=20, description="매입 결제일"),
 *   @OA\Property(property="sales_payment_day", type="string", nullable=true, maxLength=20, description="매출 결제일"),
 *   @OA\Property(property="business_no", type="string", nullable=true, maxLength=20, description="사업자등록번호"),
 *   @OA\Property(property="business_type", type="string", nullable=true, maxLength=50, description="업태"),
 *   @OA\Property(property="business_item", type="string", nullable=true, maxLength=100, description="업종"),
 *   @OA\Property(property="tax_agreement", type="boolean", nullable=true, description="세금 약정 여부"),
 *   @OA\Property(property="tax_amount", type="number", format="float", nullable=true, description="약정 금액"),
 *   @OA\Property(property="tax_start_date", type="string", format="date", nullable=true, description="약정 시작일"),
 *   @OA\Property(property="tax_end_date", type="string", format="date", nullable=true, description="약정 종료일"),
 *   @OA\Property(property="bad_debt", type="boolean", nullable=true, description="악성채권 여부"),
 *   @OA\Property(property="bad_debt_amount", type="number", format="float", nullable=true, description="악성채권 금액"),
 *   @OA\Property(property="bad_debt_receive_date", type="string", format="date", nullable=true, description="채권 발생일"),
 *   @OA\Property(property="bad_debt_end_date", type="string", format="date", nullable=true, description="채권 만료일"),
 *   @OA\Property(property="bad_debt_progress", type="string", enum={"협의중", "소송중", "회수완료", "대손처리"}, nullable=true, description="진행 상태"),
 *   @OA\Property(property="memo", type="string", nullable=true, description="메모"),
 *   @OA\Property(property="is_active", type="boolean", description="활성 여부")
 * )
 */
class ClientApi
{
    /**
     * @OA\Get(
     *   path="/api/v1/clients",
     *   tags={"Client"},
     *   summary="거래처 목록",
     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *   @OA\Parameter(name="page", in="query", @OA\Schema(type="integer", example=1)),
     *   @OA\Parameter(name="size", in="query", @OA\Schema(type="integer", example=20)),
     *   @OA\Parameter(name="q", in="query", description="거래처 코드/이름 검색", @OA\Schema(type="string")),
     *   @OA\Parameter(name="only_active", in="query", @OA\Schema(type="boolean")),
     *
     *   @OA\Response(response=200, description="조회 성공",
     *
     *     @OA\JsonContent(allOf={
     *
     *       @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *       @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/ClientPagination"))
     *     })
     *   ),
     *
     *   @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function index() {}

    /**
     * @OA\Get(
     *   path="/api/v1/clients/{id}",
     *   tags={"Client"},
     *   summary="거래처 단건 조회",
     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *   @OA\Parameter(name="id", in="path", required=true, @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/Client"))
     *     })
     *   ),
     *
     *   @OA\Response(response=404, description="데이터 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function show() {}

    /**
     * @OA\Post(
     *   path="/api/v1/clients",
     *   tags={"Client"},
     *   summary="거래처 생성",
     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *   @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/ClientCreateRequest")),
     *
     *   @OA\Response(response=200, description="생성 성공",
     *
     *     @OA\JsonContent(allOf={
     *
     *       @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *       @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Client"))
     *     })
     *   ),
     *
     *   @OA\Response(response=400, description="검증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function store() {}

    /**
     * @OA\Put(
     *   path="/api/v1/clients/{id}",
     *   tags={"Client"},
     *   summary="거래처 수정",
     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
     *
     *   @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/ClientUpdateRequest")),
     *
     *   @OA\Response(response=200, description="수정 성공",
     *
     *     @OA\JsonContent(allOf={
     *
     *       @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *       @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Client"))
     *     })
     *   )
     * )
     */
    public function update() {}

    /**
     * @OA\Delete(
     *   path="/api/v1/clients/{id}",
     *   tags={"Client"},
     *   summary="거래처 삭제",
     *   description="주문이 존재하는 거래처는 삭제할 수 없습니다.",
     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
     *
     *   @OA\Response(response=200, description="삭제 성공", @OA\JsonContent(ref="#/components/schemas/ApiResponse")),
     *   @OA\Response(response=400, description="주문 존재로 삭제 불가", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=404, description="데이터 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function destroy() {}

    /**
     * @OA\Patch(
     *   path="/api/v1/clients/{id}/toggle",
     *   tags={"Client"},
     *   summary="활성/비활성 토글",
     *   security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *   @OA\Parameter(name="id", in="path", required=true, @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/Client"))
     *     })
     *   )
     * )
     */
    public function toggle() {}
}
