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

<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(
 *     name="BankTransaction",
 *     description="은행 거래 조회 API - 입출금 통합 조회 및 통계"
 * )
 */

/**
 * @OA\Schema(
 *     schema="BankTransactionItem",
 *     description="은행 거래 항목",
 *
 *     @OA\Property(property="id", type="integer", description="거래 ID", example=1),
 *     @OA\Property(property="type", type="string", enum={"deposit", "withdrawal"}, description="구분", example="deposit"),
 *     @OA\Property(property="transaction_date", type="string", format="date", description="거래일", example="2025-01-15"),
 *     @OA\Property(property="bank_account_id", type="integer", description="계좌 ID", example=1),
 *     @OA\Property(property="bank_name", type="string", description="은행명", example="국민은행"),
 *     @OA\Property(property="account_name", type="string", description="계좌명", example="영업계좌"),
 *     @OA\Property(property="note", type="string", description="적요", example="거래 메모", nullable=true),
 *     @OA\Property(property="vendor_id", type="integer", description="거래처 ID", example=1, nullable=true),
 *     @OA\Property(property="vendor_name", type="string", description="거래처명", example="(주)삼성전자", nullable=true),
 *     @OA\Property(property="depositor_name", type="string", description="입금자/수취인", example="홍길동", nullable=true),
 *     @OA\Property(property="deposit_amount", type="number", format="float", description="입금액", example=1000000),
 *     @OA\Property(property="withdrawal_amount", type="number", format="float", description="출금액", example=0),
 *     @OA\Property(property="balance", type="number", format="float", description="잔액", example=50000000),
 *     @OA\Property(property="transaction_type", type="string", description="입출금 유형", example="salesRevenue", nullable=true),
 *     @OA\Property(property="source_id", type="string", description="원본 ID", example="deposit-1"),
 *     @OA\Property(property="created_at", type="string", format="date-time", description="생성일시"),
 *     @OA\Property(property="updated_at", type="string", format="date-time", description="수정일시")
 * )
 *
 * @OA\Schema(
 *     schema="BankTransactionSummary",
 *     description="은행 거래 요약 통계",
 *
 *     @OA\Property(property="total_deposit", type="number", format="float", description="총 입금액", example=15000000),
 *     @OA\Property(property="total_withdrawal", type="number", format="float", description="총 출금액", example=8500000),
 *     @OA\Property(property="deposit_unset_count", type="integer", description="입금 유형 미설정 건수", example=5),
 *     @OA\Property(property="withdrawal_unset_count", type="integer", description="출금 유형 미설정 건수", example=3)
 * )
 *
 * @OA\Schema(
 *     schema="BankTransactionPagination",
 *     description="은행 거래 목록 페이지네이션",
 *     type="object",
 *
 *     @OA\Property(property="current_page", type="integer", example=1),
 *     @OA\Property(property="data", type="array", @OA\Items(ref="#/components/schemas/BankTransactionItem")),
 *     @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")
 * )
 *
 * @OA\Schema(
 *     schema="BankAccountOption",
 *     description="계좌 선택 옵션",
 *
 *     @OA\Property(property="id", type="integer", description="계좌 ID", example=1),
 *     @OA\Property(property="label", type="string", description="표시명", example="국민은행|영업계좌")
 * )
 */
class BankTransactionApi
{
    /**
     * @OA\Get(
     *     path="/api/v1/bank-transactions",
     *     operationId="getBankTransactionList",
     *     tags={"BankTransaction"},
     *     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\Parameter(
     *         name="bank_account_id",
     *         in="query",
     *         description="계좌 ID 필터",
     *
     *         @OA\Schema(type="integer", example=1)
     *     ),
     *
     *     @OA\Parameter(
     *         name="transaction_type",
     *         in="query",
     *         description="입출금 유형 필터 (unset: 미설정)",
     *
     *         @OA\Schema(type="string", example="salesRevenue")
     *     ),
     *
     *     @OA\Parameter(
     *         name="search",
     *         in="query",
     *         description="검색어 (은행명, 계좌명, 거래처, 적요)",
     *
     *         @OA\Schema(type="string", example="국민")
     *     ),
     *
     *     @OA\Parameter(
     *         name="sort_by",
     *         in="query",
     *         description="정렬 기준",
     *
     *         @OA\Schema(type="string", enum={"transaction_date", "amount"}, default="transaction_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/BankTransactionPagination")
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패"),
     *     @OA\Response(response=403, description="권한 없음")
     * )
     */
    public function index() {}

    /**
     * @OA\Get(
     *     path="/api/v1/bank-transactions/summary",
     *     operationId="getBankTransactionSummary",
     *     tags={"BankTransaction"},
     *     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/BankTransactionSummary")
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패"),
     *     @OA\Response(response=403, description="권한 없음")
     * )
     */
    public function summary() {}

    /**
     * @OA\Get(
     *     path="/api/v1/bank-transactions/accounts",
     *     operationId="getBankTransactionAccounts",
     *     tags={"BankTransaction"},
     *     summary="계좌 목록 조회 (필터용)",
     *     description="입출금 조회 필터에 사용할 계좌 목록을 조회합니다.",
     *     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",
     *                 type="array",
     *
     *                 @OA\Items(ref="#/components/schemas/BankAccountOption")
     *             )
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패"),
     *     @OA\Response(response=403, description="권한 없음")
     * )
     */
    public function accounts() {}
}