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

<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(name="TaxInvoices", description="세금계산서 관리")
 *
 * @OA\Schema(
 *     schema="TaxInvoice",
 *     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="nts_confirm_num", type="string", example="20250115-12345678-12345678", nullable=true, description="국세청 승인번호"),
 *     @OA\Property(property="invoice_type", type="string", enum={"tax_invoice","invoice","modified"}, example="tax_invoice", description="세금계산서 유형"),
 *     @OA\Property(property="issue_type", type="string", enum={"normal","reverse","trustee"}, example="normal", description="발행 유형"),
 *     @OA\Property(property="direction", type="string", enum={"sales","purchases"}, example="sales", description="방향 (매출/매입)"),
 *     @OA\Property(property="supplier_corp_num", type="string", example="1234567890", description="공급자 사업자번호"),
 *     @OA\Property(property="supplier_corp_name", type="string", example="(주)공급사", description="공급자 회사명"),
 *     @OA\Property(property="supplier_ceo_name", type="string", example="홍길동", description="공급자 대표자명"),
 *     @OA\Property(property="supplier_addr", type="string", example="서울시 강남구", nullable=true, description="공급자 주소"),
 *     @OA\Property(property="supplier_biz_type", type="string", example="서비스", nullable=true, description="공급자 업태"),
 *     @OA\Property(property="supplier_biz_class", type="string", example="소프트웨어", nullable=true, description="공급자 종목"),
 *     @OA\Property(property="supplier_contact_id", type="string", example="supplier@test.com", nullable=true, description="공급자 담당자 이메일"),
 *     @OA\Property(property="buyer_corp_num", type="string", example="0987654321", description="공급받는자 사업자번호"),
 *     @OA\Property(property="buyer_corp_name", type="string", example="(주)구매사", description="공급받는자 회사명"),
 *     @OA\Property(property="buyer_ceo_name", type="string", example="김대표", description="공급받는자 대표자명"),
 *     @OA\Property(property="buyer_addr", type="string", example="서울시 서초구", nullable=true, description="공급받는자 주소"),
 *     @OA\Property(property="buyer_biz_type", type="string", example="제조", nullable=true, description="공급받는자 업태"),
 *     @OA\Property(property="buyer_biz_class", type="string", example="전자제품", nullable=true, description="공급받는자 종목"),
 *     @OA\Property(property="buyer_contact_id", type="string", example="buyer@test.com", nullable=true, description="공급받는자 담당자 이메일"),
 *     @OA\Property(property="issue_date", type="string", format="date", example="2025-01-15", description="작성일자"),
 *     @OA\Property(property="supply_amount", type="number", format="float", example=1000000, description="공급가액"),
 *     @OA\Property(property="tax_amount", type="number", format="float", example=100000, description="세액"),
 *     @OA\Property(property="total_amount", type="number", format="float", example=1100000, description="합계금액"),
 *     @OA\Property(property="items", type="array", description="품목 목록",
 *
 *         @OA\Items(
 *
 *             @OA\Property(property="date", type="string", format="date", example="2025-01-15"),
 *             @OA\Property(property="name", type="string", example="컨설팅 서비스"),
 *             @OA\Property(property="spec", type="string", example="월간"),
 *             @OA\Property(property="quantity", type="number", example=1),
 *             @OA\Property(property="unit_price", type="number", example=1000000),
 *             @OA\Property(property="supply_amount", type="number", example=1000000),
 *             @OA\Property(property="tax_amount", type="number", example=100000),
 *             @OA\Property(property="remark", type="string", example="1월분", nullable=true)
 *         )
 *     ),
 *     @OA\Property(property="status", type="string", enum={"draft","issued","sent","cancelled","failed"}, example="draft", description="상태"),
 *     @OA\Property(property="status_label", type="string", example="임시저장", description="상태 라벨"),
 *     @OA\Property(property="invoice_type_label", type="string", example="세금계산서", description="세금계산서 유형 라벨"),
 *     @OA\Property(property="issue_type_label", type="string", example="정발행", description="발행 유형 라벨"),
 *     @OA\Property(property="direction_label", type="string", example="매출", description="방향 라벨"),
 *     @OA\Property(property="formatted_supplier_corp_num", type="string", example="123-45-67890", description="포맷팅된 공급자 사업자번호"),
 *     @OA\Property(property="formatted_buyer_corp_num", type="string", example="098-76-54321", description="포맷팅된 공급받는자 사업자번호"),
 *     @OA\Property(property="nts_send_status", type="string", example="success", nullable=true, description="국세청 전송 상태"),
 *     @OA\Property(property="issued_at", type="string", format="date-time", nullable=true, description="발행 일시"),
 *     @OA\Property(property="sent_at", type="string", format="date-time", nullable=true, description="국세청 전송 일시"),
 *     @OA\Property(property="cancelled_at", type="string", format="date-time", nullable=true, description="취소 일시"),
 *     @OA\Property(property="barobill_invoice_id", type="string", nullable=true, description="바로빌 발행 ID"),
 *     @OA\Property(property="description", type="string", nullable=true, description="비고"),
 *     @OA\Property(property="error_message", type="string", nullable=true, description="에러 메시지"),
 *     @OA\Property(property="reference_type", type="string", example="App\\Models\\Tenants\\Sale", nullable=true, description="참조 모델 타입"),
 *     @OA\Property(property="reference_id", type="integer", example=1, nullable=true, description="참조 ID"),
 *     @OA\Property(property="creator", type="object", nullable=true,
 *         @OA\Property(property="id", type="integer", example=1),
 *         @OA\Property(property="name", type="string", example="관리자"),
 *         description="생성자 정보"
 *     ),
 *     @OA\Property(property="created_by", type="integer", example=1, nullable=true, description="생성자 ID"),
 *     @OA\Property(property="updated_by", type="integer", example=1, nullable=true, description="수정자 ID"),
 *     @OA\Property(property="deleted_by", type="integer", example=1, nullable=true, description="삭제자 ID"),
 *     @OA\Property(property="created_at", type="string", format="date-time"),
 *     @OA\Property(property="updated_at", type="string", format="date-time")
 * )
 *
 * @OA\Schema(
 *     schema="TaxInvoiceCreateRequest",
 *     type="object",
 *     required={"invoice_type","issue_type","direction","supplier_corp_num","supplier_corp_name","supplier_ceo_name","buyer_corp_num","buyer_corp_name","buyer_ceo_name","issue_date","supply_amount","tax_amount"},
 *     description="세금계산서 생성 요청",
 *
 *     @OA\Property(property="invoice_type", type="string", enum={"tax_invoice","invoice","modified"}, example="tax_invoice", description="세금계산서 유형"),
 *     @OA\Property(property="issue_type", type="string", enum={"normal","reverse","trustee"}, example="normal", description="발행 유형"),
 *     @OA\Property(property="direction", type="string", enum={"sales","purchases"}, example="sales", description="방향 (매출/매입)"),
 *     @OA\Property(property="supplier_corp_num", type="string", example="1234567890", minLength=10, maxLength=10, description="공급자 사업자번호"),
 *     @OA\Property(property="supplier_corp_name", type="string", example="(주)공급사", maxLength=200, description="공급자 회사명"),
 *     @OA\Property(property="supplier_ceo_name", type="string", example="홍길동", maxLength=100, description="공급자 대표자명"),
 *     @OA\Property(property="supplier_addr", type="string", example="서울시 강남구", maxLength=500, nullable=true, description="공급자 주소"),
 *     @OA\Property(property="supplier_biz_type", type="string", example="서비스", maxLength=100, nullable=true, description="공급자 업태"),
 *     @OA\Property(property="supplier_biz_class", type="string", example="소프트웨어", maxLength=100, nullable=true, description="공급자 종목"),
 *     @OA\Property(property="supplier_contact_id", type="string", example="supplier@test.com", maxLength=100, nullable=true, description="공급자 담당자 이메일"),
 *     @OA\Property(property="buyer_corp_num", type="string", example="0987654321", minLength=10, maxLength=10, description="공급받는자 사업자번호"),
 *     @OA\Property(property="buyer_corp_name", type="string", example="(주)구매사", maxLength=200, description="공급받는자 회사명"),
 *     @OA\Property(property="buyer_ceo_name", type="string", example="김대표", maxLength=100, description="공급받는자 대표자명"),
 *     @OA\Property(property="buyer_addr", type="string", example="서울시 서초구", maxLength=500, nullable=true, description="공급받는자 주소"),
 *     @OA\Property(property="buyer_biz_type", type="string", example="제조", maxLength=100, nullable=true, description="공급받는자 업태"),
 *     @OA\Property(property="buyer_biz_class", type="string", example="전자제품", maxLength=100, nullable=true, description="공급받는자 종목"),
 *     @OA\Property(property="buyer_contact_id", type="string", example="buyer@test.com", maxLength=100, nullable=true, description="공급받는자 담당자 이메일"),
 *     @OA\Property(property="issue_date", type="string", format="date", example="2025-01-15", description="작성일자"),
 *     @OA\Property(property="supply_amount", type="number", format="float", example=1000000, minimum=0, description="공급가액"),
 *     @OA\Property(property="tax_amount", type="number", format="float", example=100000, minimum=0, description="세액"),
 *     @OA\Property(property="items", type="array", description="품목 목록 (최대 99개)",
 *
 *         @OA\Items(
 *
 *             @OA\Property(property="date", type="string", format="date", example="2025-01-15", description="거래일자"),
 *             @OA\Property(property="name", type="string", example="컨설팅 서비스", maxLength=200, description="품목명"),
 *             @OA\Property(property="spec", type="string", example="월간", maxLength=100, nullable=true, description="규격"),
 *             @OA\Property(property="quantity", type="number", example=1, minimum=0, description="수량"),
 *             @OA\Property(property="unit_price", type="number", example=1000000, minimum=0, description="단가"),
 *             @OA\Property(property="supply_amount", type="number", example=1000000, minimum=0, description="공급가액"),
 *             @OA\Property(property="tax_amount", type="number", example=100000, minimum=0, description="세액"),
 *             @OA\Property(property="remark", type="string", example="1월분", maxLength=200, nullable=true, description="비고")
 *         )
 *     ),
 *     @OA\Property(property="description", type="string", example="월간 컨설팅 비용", maxLength=500, nullable=true, description="비고")
 * )
 *
 * @OA\Schema(
 *     schema="TaxInvoiceUpdateRequest",
 *     type="object",
 *     description="세금계산서 수정 요청 (임시저장 상태에서만 수정 가능)",
 *
 *     @OA\Property(property="invoice_type", type="string", enum={"tax_invoice","invoice","modified"}, example="tax_invoice", description="세금계산서 유형"),
 *     @OA\Property(property="issue_type", type="string", enum={"normal","reverse","trustee"}, example="normal", description="발행 유형"),
 *     @OA\Property(property="direction", type="string", enum={"sales","purchases"}, example="sales", description="방향 (매출/매입)"),
 *     @OA\Property(property="supplier_corp_num", type="string", example="1234567890", minLength=10, maxLength=10, description="공급자 사업자번호"),
 *     @OA\Property(property="supplier_corp_name", type="string", example="(주)공급사", maxLength=200, description="공급자 회사명"),
 *     @OA\Property(property="supplier_ceo_name", type="string", example="홍길동", maxLength=100, description="공급자 대표자명"),
 *     @OA\Property(property="supplier_addr", type="string", example="서울시 강남구", maxLength=500, nullable=true, description="공급자 주소"),
 *     @OA\Property(property="supplier_biz_type", type="string", example="서비스", maxLength=100, nullable=true, description="공급자 업태"),
 *     @OA\Property(property="supplier_biz_class", type="string", example="소프트웨어", maxLength=100, nullable=true, description="공급자 종목"),
 *     @OA\Property(property="supplier_contact_id", type="string", example="supplier@test.com", maxLength=100, nullable=true, description="공급자 담당자 이메일"),
 *     @OA\Property(property="buyer_corp_num", type="string", example="0987654321", minLength=10, maxLength=10, description="공급받는자 사업자번호"),
 *     @OA\Property(property="buyer_corp_name", type="string", example="(주)구매사", maxLength=200, description="공급받는자 회사명"),
 *     @OA\Property(property="buyer_ceo_name", type="string", example="김대표", maxLength=100, description="공급받는자 대표자명"),
 *     @OA\Property(property="buyer_addr", type="string", example="서울시 서초구", maxLength=500, nullable=true, description="공급받는자 주소"),
 *     @OA\Property(property="buyer_biz_type", type="string", example="제조", maxLength=100, nullable=true, description="공급받는자 업태"),
 *     @OA\Property(property="buyer_biz_class", type="string", example="전자제품", maxLength=100, nullable=true, description="공급받는자 종목"),
 *     @OA\Property(property="buyer_contact_id", type="string", example="buyer@test.com", maxLength=100, nullable=true, description="공급받는자 담당자 이메일"),
 *     @OA\Property(property="issue_date", type="string", format="date", example="2025-01-15", description="작성일자"),
 *     @OA\Property(property="supply_amount", type="number", format="float", example=1000000, minimum=0, description="공급가액"),
 *     @OA\Property(property="tax_amount", type="number", format="float", example=100000, minimum=0, description="세액"),
 *     @OA\Property(property="items", type="array", description="품목 목록 (최대 99개)",
 *
 *         @OA\Items(
 *
 *             @OA\Property(property="date", type="string", format="date", example="2025-01-15", description="거래일자"),
 *             @OA\Property(property="name", type="string", example="컨설팅 서비스", maxLength=200, description="품목명"),
 *             @OA\Property(property="spec", type="string", example="월간", maxLength=100, nullable=true, description="규격"),
 *             @OA\Property(property="quantity", type="number", example=1, minimum=0, description="수량"),
 *             @OA\Property(property="unit_price", type="number", example=1000000, minimum=0, description="단가"),
 *             @OA\Property(property="supply_amount", type="number", example=1000000, minimum=0, description="공급가액"),
 *             @OA\Property(property="tax_amount", type="number", example=100000, minimum=0, description="세액"),
 *             @OA\Property(property="remark", type="string", example="1월분", maxLength=200, nullable=true, description="비고")
 *         )
 *     ),
 *     @OA\Property(property="description", type="string", example="월간 컨설팅 비용", maxLength=500, nullable=true, description="비고")
 * )
 *
 * @OA\Schema(
 *     schema="TaxInvoiceCancelRequest",
 *     type="object",
 *     required={"reason"},
 *     description="세금계산서 취소 요청",
 *
 *     @OA\Property(property="reason", type="string", example="거래 취소로 인한 세금계산서 취소", maxLength=500, description="취소 사유")
 * )
 *
 * @OA\Schema(
 *     schema="TaxInvoiceBulkIssueRequest",
 *     type="object",
 *     required={"ids"},
 *     description="세금계산서 일괄 발행 요청",
 *
 *     @OA\Property(property="ids", type="array", minItems=1, maxItems=100, description="발행할 세금계산서 ID 목록 (최대 100개)",
 *
 *         @OA\Items(type="integer", example=1)
 *     )
 * )
 *
 * @OA\Schema(
 *     schema="TaxInvoiceBulkIssueResponse",
 *     type="object",
 *     description="세금계산서 일괄 발행 응답",
 *
 *     @OA\Property(property="issued", type="integer", example=8, description="발행 성공 건수"),
 *     @OA\Property(property="failed", type="integer", example=2, description="발행 실패 건수"),
 *     @OA\Property(property="errors", type="object", description="실패 상세 (ID: 에러메시지)",
 *
 *         @OA\AdditionalProperties(type="string", example="이미 발행된 세금계산서입니다.")
 *     )
 * )
 *
 * @OA\Schema(
 *     schema="TaxInvoiceSummary",
 *     type="object",
 *     description="세금계산서 요약 통계",
 *
 *     @OA\Property(property="by_direction", type="object",
 *         @OA\Property(property="sales", type="object",
 *             @OA\Property(property="count", type="integer", example=50, description="매출 건수"),
 *             @OA\Property(property="supply_amount", type="number", format="float", example=50000000, description="공급가액 합계"),
 *             @OA\Property(property="tax_amount", type="number", format="float", example=5000000, description="세액 합계"),
 *             @OA\Property(property="total_amount", type="number", format="float", example=55000000, description="합계금액")
 *         ),
 *         @OA\Property(property="purchases", type="object",
 *             @OA\Property(property="count", type="integer", example=30, description="매입 건수"),
 *             @OA\Property(property="supply_amount", type="number", format="float", example=30000000, description="공급가액 합계"),
 *             @OA\Property(property="tax_amount", type="number", format="float", example=3000000, description="세액 합계"),
 *             @OA\Property(property="total_amount", type="number", format="float", example=33000000, description="합계금액")
 *         ),
 *         description="방향별 통계"
 *     ),
 *     @OA\Property(property="by_status", type="object",
 *         @OA\Property(property="draft", type="integer", example=5, description="임시저장 건수"),
 *         @OA\Property(property="issued", type="integer", example=30, description="발행완료 건수"),
 *         @OA\Property(property="sent", type="integer", example=40, description="국세청 전송 건수"),
 *         @OA\Property(property="cancelled", type="integer", example=3, description="취소 건수"),
 *         @OA\Property(property="failed", type="integer", example=2, description="발행실패 건수"),
 *         description="상태별 건수"
 *     )
 * )
 */
class TaxInvoiceApi
{
    /**
     * @OA\Get(
     *     path="/api/v1/tax-invoices",
     *     tags={"TaxInvoices"},
     *     summary="세금계산서 목록 조회",
     *     description="세금계산서 목록을 조회합니다. 다양한 필터 조건으로 검색할 수 있습니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Parameter(name="direction", in="query", description="방향 (매출/매입)", @OA\Schema(type="string", enum={"sales","purchases"})),
     *     @OA\Parameter(name="status", in="query", description="상태", @OA\Schema(type="string", enum={"draft","issued","sent","cancelled","failed"})),
     *     @OA\Parameter(name="invoice_type", in="query", description="세금계산서 유형", @OA\Schema(type="string", enum={"tax_invoice","invoice","modified"})),
     *     @OA\Parameter(name="issue_type", in="query", description="발행 유형", @OA\Schema(type="string", enum={"normal","reverse","trustee"})),
     *     @OA\Parameter(name="issue_date_from", in="query", description="작성일 시작", @OA\Schema(type="string", format="date")),
     *     @OA\Parameter(name="issue_date_to", in="query", description="작성일 종료", @OA\Schema(type="string", format="date")),
     *     @OA\Parameter(name="corp_num", in="query", description="거래처 사업자번호 (공급자 또는 공급받는자)", @OA\Schema(type="string")),
     *     @OA\Parameter(name="corp_name", in="query", description="거래처명 검색 (공급자 또는 공급받는자)", @OA\Schema(type="string", maxLength=100)),
     *     @OA\Parameter(name="nts_confirm_num", in="query", description="국세청 승인번호 검색", @OA\Schema(type="string")),
     *     @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/TaxInvoice")),
     *                         @OA\Property(property="per_page", type="integer", example=20),
     *                         @OA\Property(property="total", type="integer", example=100)
     *                     )
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @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/tax-invoices/summary",
     *     tags={"TaxInvoices"},
     *     summary="세금계산서 요약 통계",
     *     description="세금계산서 요약 통계를 조회합니다. 방향별(매출/매입), 상태별 집계 정보를 제공합니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Parameter(name="issue_date_from", in="query", description="작성일 시작", @OA\Schema(type="string", format="date")),
     *     @OA\Parameter(name="issue_date_to", 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/TaxInvoiceSummary")
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @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\Post(
     *     path="/api/v1/tax-invoices",
     *     tags={"TaxInvoices"},
     *     summary="세금계산서 생성",
     *     description="새로운 세금계산서를 생성합니다. 생성 시 임시저장(draft) 상태로 저장됩니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(ref="#/components/schemas/TaxInvoiceCreateRequest")
     *     ),
     *
     *     @OA\Response(
     *         response=201,
     *         description="생성 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(property="data", ref="#/components/schemas/TaxInvoice")
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @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=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function store() {}

    /**
     * @OA\Get(
     *     path="/api/v1/tax-invoices/{id}",
     *     tags={"TaxInvoices"},
     *     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/TaxInvoice")
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @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\Put(
     *     path="/api/v1/tax-invoices/{id}",
     *     tags={"TaxInvoices"},
     *     summary="세금계산서 수정",
     *     description="세금계산서 정보를 수정합니다. 임시저장(draft) 상태에서만 수정 가능합니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Parameter(name="id", in="path", required=true, description="세금계산서 ID", @OA\Schema(type="integer")),
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(ref="#/components/schemas/TaxInvoiceUpdateRequest")
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="수정 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(property="data", ref="#/components/schemas/TaxInvoice")
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @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 update() {}

    /**
     * @OA\Delete(
     *     path="/api/v1/tax-invoices/{id}",
     *     tags={"TaxInvoices"},
     *     summary="세금계산서 삭제",
     *     description="세금계산서를 삭제합니다. 임시저장(draft) 상태에서만 삭제 가능합니다. (Soft Delete)",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Parameter(name="id", in="path", required=true, description="세금계산서 ID", @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=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 destroy() {}

    /**
     * @OA\Post(
     *     path="/api/v1/tax-invoices/{id}/issue",
     *     tags={"TaxInvoices"},
     *     summary="세금계산서 발행",
     *     description="세금계산서를 발행합니다. 바로빌 API를 통해 전자세금계산서가 발행됩니다. 임시저장(draft) 상태에서만 발행 가능합니다.",
     *     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/TaxInvoice")
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @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 issue() {}

    /**
     * @OA\Post(
     *     path="/api/v1/tax-invoices/{id}/cancel",
     *     tags={"TaxInvoices"},
     *     summary="세금계산서 취소",
     *     description="세금계산서를 취소합니다. 바로빌 API를 통해 전자세금계산서가 취소됩니다. 발행완료(issued) 또는 국세청 전송(sent) 상태에서만 취소 가능합니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\Parameter(name="id", in="path", required=true, description="세금계산서 ID", @OA\Schema(type="integer")),
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(ref="#/components/schemas/TaxInvoiceCancelRequest")
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="취소 성공",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(property="data", ref="#/components/schemas/TaxInvoice")
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @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\Get(
     *     path="/api/v1/tax-invoices/{id}/check-status",
     *     tags={"TaxInvoices"},
     *     summary="국세청 전송 상태 조회",
     *     description="세금계산서의 국세청 전송 상태를 조회합니다. 바로빌 API를 통해 최신 상태를 확인하고 업데이트합니다.",
     *     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/TaxInvoice")
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @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 checkStatus() {}

    /**
     * @OA\Post(
     *     path="/api/v1/tax-invoices/bulk-issue",
     *     tags={"TaxInvoices"},
     *     summary="세금계산서 일괄 발행",
     *     description="여러 세금계산서를 일괄 발행합니다. 바로빌 API를 통해 전자세금계산서가 발행됩니다. 임시저장(draft) 상태인 건만 발행되며, 각 건별로 성공/실패가 처리됩니다.",
     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(ref="#/components/schemas/TaxInvoiceBulkIssueRequest")
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="일괄 발행 처리 완료",
     *
     *         @OA\JsonContent(
     *             allOf={
     *
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *
     *                     @OA\Property(property="data", ref="#/components/schemas/TaxInvoiceBulkIssueResponse")
     *                 )
     *             }
     *         )
     *     ),
     *
     *     @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=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function bulkIssue() {}
}