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

<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(
 *     name="Bills",
 *     description="어음 관리 API"
 * )
 *
 * @OA\Schema(
 *     schema="Bill",
 *     type="object",
 *     required={"id", "tenant_id", "bill_number", "bill_type", "amount", "issue_date", "maturity_date", "status"},
 *
 *     @OA\Property(property="id", type="integer", example=1),
 *     @OA\Property(property="tenant_id", type="integer", example=1),
 *     @OA\Property(property="bill_number", type="string", example="202412000001", description="어음번호"),
 *     @OA\Property(property="bill_type", type="string", enum={"received", "issued"}, example="received", description="어음 구분: received=수취, issued=발행"),
 *     @OA\Property(property="client_id", type="integer", nullable=true, example=10, description="거래처 ID"),
 *     @OA\Property(property="client_name", type="string", nullable=true, example="(주)삼성전자", description="거래처명 (비회원용)"),
 *     @OA\Property(property="amount", type="number", format="float", example=10000000, description="금액"),
 *     @OA\Property(property="issue_date", type="string", format="date", example="2024-12-01", description="발행일"),
 *     @OA\Property(property="maturity_date", type="string", format="date", example="2025-03-01", description="만기일"),
 *     @OA\Property(property="status", type="string", example="stored", description="상태: stored/maturityAlert/maturityResult/paymentComplete/dishonored/collectionRequest/collectionComplete/suing"),
 *     @OA\Property(property="reason", type="string", nullable=true, example="거래 대금", description="사유"),
 *     @OA\Property(property="installment_count", type="integer", example=0, description="차수"),
 *     @OA\Property(property="note", type="string", nullable=true, example="메모 내용", description="메모/비고"),
 *     @OA\Property(property="is_electronic", type="boolean", example=false, description="전자어음 여부"),
 *     @OA\Property(property="bank_account_id", type="integer", nullable=true, example=5, description="입금/출금 계좌 ID"),
 *     @OA\Property(property="created_by", type="integer", nullable=true, example=1),
 *     @OA\Property(property="updated_by", type="integer", nullable=true, example=1),
 *     @OA\Property(property="created_at", type="string", format="date-time"),
 *     @OA\Property(property="updated_at", type="string", format="date-time"),
 *     @OA\Property(
 *         property="client",
 *         type="object",
 *         nullable=true,
 *         @OA\Property(property="id", type="integer", example=10),
 *         @OA\Property(property="name", type="string", example="(주)삼성전자")
 *     ),
 *     @OA\Property(
 *         property="bank_account",
 *         type="object",
 *         nullable=true,
 *         @OA\Property(property="id", type="integer", example=5),
 *         @OA\Property(property="bank_name", type="string", example="국민은행"),
 *         @OA\Property(property="account_name", type="string", example="운영계좌")
 *     ),
 *     @OA\Property(
 *         property="installments",
 *         type="array",
 *
 *         @OA\Items(ref="#/components/schemas/BillInstallment")
 *     )
 * )
 *
 * @OA\Schema(
 *     schema="BillInstallment",
 *     type="object",
 *
 *     @OA\Property(property="id", type="integer", example=1),
 *     @OA\Property(property="bill_id", type="integer", example=1),
 *     @OA\Property(property="installment_date", type="string", format="date", example="2024-12-15", description="차수 일자"),
 *     @OA\Property(property="amount", type="number", format="float", example=5000000, description="차수 금액"),
 *     @OA\Property(property="note", type="string", nullable=true, example="1차 분할", description="비고"),
 *     @OA\Property(property="created_at", type="string", format="date-time"),
 *     @OA\Property(property="updated_at", type="string", format="date-time")
 * )
 *
 * @OA\Schema(
 *     schema="BillPagination",
 *     type="object",
 *
 *     @OA\Property(
 *         property="data",
 *         type="array",
 *
 *         @OA\Items(ref="#/components/schemas/Bill")
 *     ),
 *
 *     @OA\Property(property="current_page", type="integer", example=1),
 *     @OA\Property(property="last_page", type="integer", example=5),
 *     @OA\Property(property="per_page", type="integer", example=20),
 *     @OA\Property(property="total", type="integer", example=100),
 *     @OA\Property(property="from", type="integer", example=1),
 *     @OA\Property(property="to", type="integer", example=20)
 * )
 *
 * @OA\Schema(
 *     schema="BillCreateRequest",
 *     type="object",
 *     required={"bill_type", "amount", "issue_date", "maturity_date"},
 *
 *     @OA\Property(property="bill_number", type="string", nullable=true, example="202412000001", description="어음번호 (미입력시 자동생성)"),
 *     @OA\Property(property="bill_type", type="string", enum={"received", "issued"}, example="received", description="어음 구분"),
 *     @OA\Property(property="client_id", type="integer", nullable=true, example=10, description="거래처 ID"),
 *     @OA\Property(property="client_name", type="string", nullable=true, example="(주)삼성전자", description="거래처명"),
 *     @OA\Property(property="amount", type="number", example=10000000, description="금액"),
 *     @OA\Property(property="issue_date", type="string", format="date", example="2024-12-01", description="발행일"),
 *     @OA\Property(property="maturity_date", type="string", format="date", example="2025-03-01", description="만기일"),
 *     @OA\Property(property="status", type="string", nullable=true, example="stored", description="상태"),
 *     @OA\Property(property="reason", type="string", nullable=true, example="거래 대금", description="사유"),
 *     @OA\Property(property="note", type="string", nullable=true, example="메모 내용", description="메모"),
 *     @OA\Property(property="is_electronic", type="boolean", nullable=true, example=false, description="전자어음 여부"),
 *     @OA\Property(property="bank_account_id", type="integer", nullable=true, example=5, description="계좌 ID"),
 *     @OA\Property(
 *         property="installments",
 *         type="array",
 *         nullable=true,
 *
 *         @OA\Items(
 *             type="object",
 *
 *             @OA\Property(property="date", type="string", format="date", example="2024-12-15"),
 *             @OA\Property(property="amount", type="number", example=5000000),
 *             @OA\Property(property="note", type="string", nullable=true, example="1차 분할")
 *         )
 *     )
 * )
 *
 * @OA\Schema(
 *     schema="BillUpdateRequest",
 *     type="object",
 *
 *     @OA\Property(property="bill_number", type="string", nullable=true, example="202412000001"),
 *     @OA\Property(property="bill_type", type="string", enum={"received", "issued"}, nullable=true),
 *     @OA\Property(property="client_id", type="integer", nullable=true),
 *     @OA\Property(property="client_name", type="string", nullable=true),
 *     @OA\Property(property="amount", type="number", nullable=true),
 *     @OA\Property(property="issue_date", type="string", format="date", nullable=true),
 *     @OA\Property(property="maturity_date", type="string", format="date", nullable=true),
 *     @OA\Property(property="status", type="string", nullable=true),
 *     @OA\Property(property="reason", type="string", nullable=true),
 *     @OA\Property(property="note", type="string", nullable=true),
 *     @OA\Property(property="is_electronic", type="boolean", nullable=true),
 *     @OA\Property(property="bank_account_id", type="integer", nullable=true),
 *     @OA\Property(property="installments", type="array", nullable=true, @OA\Items(type="object"))
 * )
 *
 * @OA\Schema(
 *     schema="BillSummary",
 *     type="object",
 *
 *     @OA\Property(property="total_amount", type="number", example=50000000, description="총 금액"),
 *     @OA\Property(property="total_count", type="integer", example=10, description="총 건수"),
 *     @OA\Property(
 *         property="by_type",
 *         type="object",
 *         description="구분별 합계",
 *
 *         @OA\AdditionalProperties(
 *             type="object",
 *
 *             @OA\Property(property="bill_type", type="string"),
 *             @OA\Property(property="total", type="number"),
 *             @OA\Property(property="count", type="integer")
 *         )
 *     ),
 *     @OA\Property(
 *         property="by_status",
 *         type="object",
 *         description="상태별 합계"
 *     ),
 *     @OA\Property(property="maturity_alert_amount", type="number", example=10000000, description="만기 임박 금액 (7일 이내)")
 * )
 *
 * @OA\Schema(
 *     schema="BillDashboardDetail",
 *     description="발행어음 대시보드 상세 (CEO 대시보드 당월 예상 지출내역 me3 모달용)",
 *     type="object",
 *
 *     @OA\Property(
 *         property="summary",
 *         type="object",
 *         description="요약 정보",
 *         @OA\Property(property="current_month_total", type="number", example=50000000, description="당월 발행어음 합계"),
 *         @OA\Property(property="previous_month_total", type="number", example=45000000, description="전월 발행어음 합계"),
 *         @OA\Property(property="change_rate", type="number", example=11.1, description="전월 대비 증감율 (%)")
 *     ),
 *     @OA\Property(
 *         property="monthly_trend",
 *         type="array",
 *         description="월별 추이 (최근 7개월)",
 *
 *         @OA\Items(
 *             type="object",
 *
 *             @OA\Property(property="month", type="string", example="2025-07", description="년-월"),
 *             @OA\Property(property="amount", type="number", example=42000000, description="해당 월 발행어음 합계")
 *         )
 *     ),
 *     @OA\Property(
 *         property="by_vendor",
 *         type="array",
 *         description="거래처별 분포 (당월)",
 *
 *         @OA\Items(
 *             type="object",
 *
 *             @OA\Property(property="vendor_name", type="string", example="(주)삼성전자", description="거래처명"),
 *             @OA\Property(property="amount", type="number", example=25000000, description="금액"),
 *             @OA\Property(property="percentage", type="number", example=50.0, description="비율 (%)")
 *         )
 *     ),
 *     @OA\Property(
 *         property="items",
 *         type="array",
 *         description="발행어음 목록 (당월)",
 *
 *         @OA\Items(
 *             type="object",
 *
 *             @OA\Property(property="id", type="integer", example=1),
 *             @OA\Property(property="vendor", type="string", example="(주)삼성전자", description="거래처명"),
 *             @OA\Property(property="issue_date", type="string", format="date", example="2025-01-05", description="발행일"),
 *             @OA\Property(property="due_date", type="string", format="date", example="2025-04-05", description="만기일"),
 *             @OA\Property(property="amount", type="number", example=10000000, description="금액"),
 *             @OA\Property(property="status", type="string", example="stored", description="상태")
 *         )
 *     )
 * )
 */
class BillApi
{
    /**
     * @OA\Get(
     *     path="/api/v1/bills",
     *     operationId="getBills",
     *     tags={"Bills"},
     *     summary="어음 목록 조회",
     *     description="어음 목록을 페이지네이션하여 조회합니다.",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\Parameter(name="search", in="query", description="검색어 (어음번호, 거래처명, 메모)", @OA\Schema(type="string")),
     *     @OA\Parameter(name="bill_type", in="query", description="어음 구분", @OA\Schema(type="string", enum={"received", "issued"})),
     *     @OA\Parameter(name="status", in="query", description="상태", @OA\Schema(type="string")),
     *     @OA\Parameter(name="client_id", in="query", description="거래처 ID", @OA\Schema(type="integer")),
     *     @OA\Parameter(name="is_electronic", in="query", description="전자어음 여부", @OA\Schema(type="boolean")),
     *     @OA\Parameter(name="issue_start_date", in="query", description="발행일 시작", @OA\Schema(type="string", format="date")),
     *     @OA\Parameter(name="issue_end_date", in="query", description="발행일 종료", @OA\Schema(type="string", format="date")),
     *     @OA\Parameter(name="maturity_start_date", in="query", description="만기일 시작", @OA\Schema(type="string", format="date")),
     *     @OA\Parameter(name="maturity_end_date", in="query", description="만기일 종료", @OA\Schema(type="string", format="date")),
     *     @OA\Parameter(name="sort_by", in="query", description="정렬 기준", @OA\Schema(type="string", default="issue_date")),
     *     @OA\Parameter(name="sort_dir", in="query", description="정렬 방향", @OA\Schema(type="string", enum={"asc", "desc"}, default="desc")),
     *     @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/BillPagination")
     *         )
     *     )
     * )
     */
    public function index() {}

    /**
     * @OA\Post(
     *     path="/api/v1/bills",
     *     operationId="storeBill",
     *     tags={"Bills"},
     *     summary="어음 등록",
     *     description="새로운 어음을 등록합니다.",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(ref="#/components/schemas/BillCreateRequest")
     *     ),
     *
     *     @OA\Response(
     *         response=201,
     *         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/Bill")
     *         )
     *     ),
     *
     *     @OA\Response(response=422, description="유효성 검사 실패")
     * )
     */
    public function store() {}

    /**
     * @OA\Get(
     *     path="/api/v1/bills/{id}",
     *     operationId="showBill",
     *     tags={"Bills"},
     *     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(
     *
     *             @OA\Property(property="success", type="boolean", example=true),
     *             @OA\Property(property="message", type="string", example="데이터를 조회했습니다."),
     *             @OA\Property(property="data", ref="#/components/schemas/Bill")
     *         )
     *     ),
     *
     *     @OA\Response(response=404, description="어음을 찾을 수 없음")
     * )
     */
    public function show() {}

    /**
     * @OA\Put(
     *     path="/api/v1/bills/{id}",
     *     operationId="updateBill",
     *     tags={"Bills"},
     *     summary="어음 수정",
     *     description="기존 어음 정보를 수정합니다.",
     *     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/BillUpdateRequest")
     *     ),
     *
     *     @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/Bill")
     *         )
     *     ),
     *
     *     @OA\Response(response=404, description="어음을 찾을 수 없음"),
     *     @OA\Response(response=422, description="유효성 검사 실패")
     * )
     */
    public function update() {}

    /**
     * @OA\Delete(
     *     path="/api/v1/bills/{id}",
     *     operationId="deleteBill",
     *     tags={"Bills"},
     *     summary="어음 삭제",
     *     description="어음을 삭제합니다. (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(
     *
     *             @OA\Property(property="success", type="boolean", example=true),
     *             @OA\Property(property="message", type="string", example="삭제되었습니다."),
     *             @OA\Property(property="data", type="null")
     *         )
     *     ),
     *
     *     @OA\Response(response=404, description="어음을 찾을 수 없음")
     * )
     */
    public function destroy() {}

    /**
     * @OA\Patch(
     *     path="/api/v1/bills/{id}/status",
     *     operationId="updateBillStatus",
     *     tags={"Bills"},
     *     summary="어음 상태 변경",
     *     description="어음의 상태를 변경합니다.",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\Parameter(name="id", in="path", required=true, description="어음 ID", @OA\Schema(type="integer")),
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(
     *             required={"status"},
     *
     *             @OA\Property(property="status", type="string", example="paymentComplete", description="변경할 상태")
     *         )
     *     ),
     *
     *     @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/Bill")
     *         )
     *     ),
     *
     *     @OA\Response(response=404, description="어음을 찾을 수 없음"),
     *     @OA\Response(response=422, description="유효성 검사 실패")
     * )
     */
    public function updateStatus() {}

    /**
     * @OA\Get(
     *     path="/api/v1/bills/summary",
     *     operationId="getBillSummary",
     *     tags={"Bills"},
     *     summary="어음 요약 조회",
     *     description="기간별 어음 요약 정보를 조회합니다.",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\Parameter(name="bill_type", in="query", description="어음 구분", @OA\Schema(type="string", enum={"received", "issued"})),
     *     @OA\Parameter(name="issue_start_date", in="query", description="발행일 시작", @OA\Schema(type="string", format="date")),
     *     @OA\Parameter(name="issue_end_date", in="query", description="발행일 종료", @OA\Schema(type="string", format="date")),
     *     @OA\Parameter(name="maturity_start_date", in="query", description="만기일 시작", @OA\Schema(type="string", format="date")),
     *     @OA\Parameter(name="maturity_end_date", in="query", description="만기일 종료", @OA\Schema(type="string", format="date")),
     *
     *     @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/BillSummary")
     *         )
     *     )
     * )
     */
    public function summary() {}

    /**
     * @OA\Get(
     *     path="/api/v1/bills/dashboard-detail",
     *     operationId="getBillDashboardDetail",
     *     tags={"Bills"},
     *     summary="발행어음 대시보드 상세 조회",
     *     description="CEO 대시보드 당월 예상 지출내역 me3 모달용 상세 데이터를 조회합니다. 요약 정보, 월별 추이, 거래처별 분포, 발행어음 목록을 제공합니다.",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @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/BillDashboardDetail")
     *         )
     *     )
     * )
     */
    public function dashboardDetail() {}
}