SamProject/sam-api
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c637dd38ebd65cb2d80e98ab10bd2f4935282ac2
sam-api/app/Swagger/v1/VendorLedgerApi.php
kent e571f8c38e docs(API): Swagger API 문서 업데이트 
- AdminFcmApi, BillApi, ExpectedExpenseApi 개선
- PositionApi, ProcessApi, QuoteApi 개선
- ReceivablesApi, ShipmentApi, StockApi, VendorLedgerApi 개선

Co-Authored-By: Claude <noreply@anthropic.com>
2026-01-13 19:48:54 +09:00

293 lines
12 KiB
PHP
Raw Blame History

<?php
namespace App\Swagger\v1;
/**
* @OA\Tag(
* name="VendorLedger",
* description="거래처원장 API - 거래처별 매출/수금 내역 조회"
* )
*/
/**
* @OA\Schema(
* schema="VendorLedgerItem",
* description="거래처원장 리스트 항목",
*
* @OA\Property(property="id", type="integer", description="거래처 ID", example=1),
* @OA\Property(property="name", type="string", description="거래처명", example="ABC 주식회사"),
* @OA\Property(property="sales_payment_day", type="string", description="결제일", example="25일", nullable=true),
* @OA\Property(property="period_sales", type="number", format="float", description="기간 내 매출", example=10000000),
* @OA\Property(property="period_collection", type="number", format="float", description="기간 내 수금", example=8000000),
* @OA\Property(property="carryover_sales", type="number", format="float", description="이월 매출", example=5000000),
* @OA\Property(property="carryover_deposits", type="number", format="float", description="이월 수금", example=3000000)
* )
*
* @OA\Schema(
* schema="VendorLedgerSummary",
* description="거래처원장 요약 통계",
*
* @OA\Property(property="carryover_balance", type="number", format="float", description="이월잔액", example=2000000),
* @OA\Property(property="total_sales", type="number", format="float", description="총 매출", example=10000000),
* @OA\Property(property="total_collection", type="number", format="float", description="총 수금", example=8000000),
* @OA\Property(property="balance", type="number", format="float", description="현재 잔액", example=4000000)
* )
*
* @OA\Schema(
* schema="VendorLedgerTransaction",
* description="거래처원장 거래 내역",
*
* @OA\Property(property="id", type="integer", description="거래 ID", example=1),
* @OA\Property(property="date", type="string", format="date", description="거래일", example="2025-01-15"),
* @OA\Property(property="type", type="string", description="거래 유형", example="sales", enum={"sales", "collection", "note"}),
* @OA\Property(property="description", type="string", description="적요", example="제품 납품"),
* @OA\Property(property="sales_amount", type="number", format="float", description="매출 금액", example=1000000),
* @OA\Property(property="collection_amount", type="number", format="float", description="수금 금액", example=0),
* @OA\Property(property="balance", type="number", format="float", description="잔액", example=1000000),
* @OA\Property(property="reference_id", type="integer", description="참조 ID", example=1),
* @OA\Property(property="reference_type", type="string", description="참조 타입", example="sale", enum={"sale", "deposit", "bill"}),
* @OA\Property(property="has_action", type="boolean", description="작업 버튼 표시 여부", example=false),
* @OA\Property(property="is_highlighted", type="boolean", description="하이라이트 여부", example=true),
* @OA\Property(property="is_parenthesis", type="boolean", description="괄호 표시 여부", example=false),
* @OA\Property(property="note_info", type="string", description="어음 정보", example="2025-02-15", nullable=true)
* )
*
* @OA\Schema(
* schema="VendorLedgerClient",
* description="거래처 정보",
*
* @OA\Property(property="id", type="integer", description="거래처 ID", example=1),
* @OA\Property(property="name", type="string", description="거래처명", example="ABC 주식회사"),
* @OA\Property(property="business_number", type="string", description="사업자등록번호", example="123-45-67890", nullable=true),
* @OA\Property(property="representative_name", type="string", description="대표자", example="홍길동", nullable=true),
* @OA\Property(property="phone", type="string", description="전화번호", example="02-1234-5678", nullable=true),
* @OA\Property(property="mobile", type="string", description="휴대전화", example="010-1234-5678", nullable=true),
* @OA\Property(property="fax", type="string", description="팩스", example="02-1234-5679", nullable=true),
* @OA\Property(property="email", type="string", description="이메일", example="contact@example.com", nullable=true),
* @OA\Property(property="address", type="string", description="주소", example="서울시 강남구", nullable=true)
* )
*
* @OA\Schema(
* schema="VendorLedgerDetail",
* description="거래처원장 상세",
*
* @OA\Property(property="client", ref="#/components/schemas/VendorLedgerClient"),
* @OA\Property(
* property="period",
* type="object",
* @OA\Property(property="start_date", type="string", format="date", example="2025-01-01"),
* @OA\Property(property="end_date", type="string", format="date", example="2025-12-31")
* ),
* @OA\Property(property="carryover_balance", type="number", format="float", description="이월잔액", example=2000000),
* @OA\Property(property="total_sales", type="number", format="float", description="총 매출", example=10000000),
* @OA\Property(property="total_collection", type="number", format="float", description="총 수금", example=8000000),
* @OA\Property(property="balance", type="number", format="float", description="현재 잔액", example=4000000),
* @OA\Property(
* property="transactions",
* type="array",
*
* @OA\Items(ref="#/components/schemas/VendorLedgerTransaction")
* )
* )
*
* @OA\Schema(
* schema="VendorLedgerPagination",
* description="거래처원장 목록 페이지네이션",
* type="object",
*
* @OA\Property(property="current_page", type="integer", example=1),
* @OA\Property(property="data", type="array", @OA\Items(ref="#/components/schemas/VendorLedgerItem")),
* @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")
* )
*/
class VendorLedgerApi
{
/**
* @OA\Get(
* path="/api/v1/vendor-ledger",
* operationId="getVendorLedgerList",
* tags={"VendorLedger"},
* summary="거래처원장 목록 조회",
* description="거래처별 매출/수금 집계 목록을 조회합니다.",
* security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
*
* @OA\Parameter(
* name="search",
* in="query",
* description="거래처명 검색",
*
* @OA\Schema(type="string", example="ABC")
* ),
*
* @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="sort_by",
* in="query",
* description="정렬 기준 (name)",
*
* @OA\Schema(type="string", default="name")
* ),
*
* @OA\Parameter(
* name="sort_dir",
* in="query",
* description="정렬 방향",
*
* @OA\Schema(type="string", enum={"asc", "desc"}, default="asc")
* ),
*
* @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/VendorLedgerPagination")
* )
* ),
*
* @OA\Response(response=401, description="인증 실패"),
* @OA\Response(response=403, description="권한 없음")
* )
*/
public function index() {}
/**
* @OA\Get(
* path="/api/v1/vendor-ledger/summary",
* operationId="getVendorLedgerSummary",
* tags={"VendorLedger"},
* 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/VendorLedgerSummary")
* )
* ),
*
* @OA\Response(response=401, description="인증 실패"),
* @OA\Response(response=403, description="권한 없음")
* )
*/
public function summary() {}
/**
* @OA\Get(
* path="/api/v1/vendor-ledger/{clientId}",
* operationId="getVendorLedgerDetail",
* tags={"VendorLedger"},
* summary="거래처원장 상세 조회",
* description="특정 거래처의 상세 거래 내역을 조회합니다.",
* security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
*
* @OA\Parameter(
* name="clientId",
* in="path",
* required=true,
* description="거래처 ID",
*
* @OA\Schema(type="integer", example=1)
* ),
*
* @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/VendorLedgerDetail")
* )
* ),
*
* @OA\Response(response=401, description="인증 실패"),
* @OA\Response(response=403, description="권한 없음"),
* @OA\Response(response=404, description="거래처를 찾을 수 없음")
* )
*/
public function show() {}
}
Reference in New Issue View Git Blame Copy Permalink