SamProject/sam-api
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6d05ab815f90552a151f280c81c1e10bc88852ea
sam-api/app/Swagger/v1/BankTransactionApi.php
kent 2aa1d78e62 feat: I-4 거래통장 조회 API 구현 
- BankTransactionController: 은행 거래내역 조회 API
- BankTransactionService: 은행 거래 조회 로직
- Swagger 문서화

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-26 15:47:03 +09:00

249 lines
9.7 KiB
PHP
Raw Blame History

<?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() {}
}
Reference in New Issue View Git Blame Copy Permalink