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

<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(
 *     name="Receivables",
 *     description="채권 현황 API - 거래처별 월별 미수금 현황 조회"
 * )
 */

/**
 * @OA\Schema(
 *     schema="MonthlyAmount",
 *     description="월별 금액",
 *
 *     @OA\Property(property="month1", type="number", format="float", description="1월", example=1000000),
 *     @OA\Property(property="month2", type="number", format="float", description="2월", example=0),
 *     @OA\Property(property="month3", type="number", format="float", description="3월", example=0),
 *     @OA\Property(property="month4", type="number", format="float", description="4월", example=0),
 *     @OA\Property(property="month5", type="number", format="float", description="5월", example=0),
 *     @OA\Property(property="month6", type="number", format="float", description="6월", example=0),
 *     @OA\Property(property="month7", type="number", format="float", description="7월", example=0),
 *     @OA\Property(property="month8", type="number", format="float", description="8월", example=0),
 *     @OA\Property(property="month9", type="number", format="float", description="9월", example=0),
 *     @OA\Property(property="month10", type="number", format="float", description="10월", example=0),
 *     @OA\Property(property="month11", type="number", format="float", description="11월", example=0),
 *     @OA\Property(property="month12", type="number", format="float", description="12월", example=500000),
 *     @OA\Property(property="total", type="number", format="float", description="합계", example=1500000)
 * )
 *
 * @OA\Schema(
 *     schema="CategoryAmount",
 *     description="카테고리별 금액",
 *
 *     @OA\Property(property="category", type="string", enum={"sales", "deposit", "bill", "receivable", "memo"}, description="구분", example="sales"),
 *     @OA\Property(property="amounts", ref="#/components/schemas/MonthlyAmount")
 * )
 *
 * @OA\Schema(
 *     schema="VendorReceivables",
 *     description="거래처별 채권 현황",
 *
 *     @OA\Property(property="id", type="string", description="거래처 ID (string)", example="1"),
 *     @OA\Property(property="vendor_id", type="integer", description="거래처 ID", example=1),
 *     @OA\Property(property="vendor_name", type="string", description="거래처명", example="(주)삼성전자"),
 *     @OA\Property(property="is_overdue", type="boolean", description="연체 여부", example=true),
 *     @OA\Property(
 *         property="overdue_months",
 *         type="array",
 *         description="연체 월 목록",
 *
 *         @OA\Items(type="integer", example=1)
 *     ),
 *
 *     @OA\Property(
 *         property="categories",
 *         type="array",
 *         description="카테고리별 데이터",
 *
 *         @OA\Items(ref="#/components/schemas/CategoryAmount")
 *     )
 * )
 *
 * @OA\Schema(
 *     schema="ReceivablesSummary",
 *     description="채권 현황 요약 통계",
 *
 *     @OA\Property(property="total_sales", type="number", format="float", description="총 매출", example=100000000),
 *     @OA\Property(property="total_deposits", type="number", format="float", description="총 입금", example=80000000),
 *     @OA\Property(property="total_bills", type="number", format="float", description="총 어음", example=5000000),
 *     @OA\Property(property="total_receivables", type="number", format="float", description="총 미수금", example=15000000),
 *     @OA\Property(property="vendor_count", type="integer", description="거래처 수", example=50),
 *     @OA\Property(property="overdue_vendor_count", type="integer", description="연체 거래처 수", example=5)
 * )
 */
class ReceivablesApi
{
    /**
     * @OA\Get(
     *     path="/api/v1/receivables",
     *     operationId="getReceivablesList",
     *     tags={"Receivables"},
     *     summary="채권 현황 목록 조회",
     *     description="거래처별 월별 매출, 입금, 어음, 미수금 현황을 조회합니다.",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\Parameter(
     *         name="year",
     *         in="query",
     *         description="조회 연도",
     *
     *         @OA\Schema(type="integer", example=2025)
     *     ),
     *
     *     @OA\Parameter(
     *         name="search",
     *         in="query",
     *         description="거래처명 검색",
     *
     *         @OA\Schema(type="string", example="삼성")
     *     ),
     *
     *     @OA\Parameter(
     *         name="has_receivable",
     *         in="query",
     *         description="미수금이 있는 거래처만 조회",
     *
     *         @OA\Schema(type="boolean", example=true)
     *     ),
     *
     *     @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/VendorReceivables")
     *             )
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패"),
     *     @OA\Response(response=403, description="권한 없음")
     * )
     */
    public function index() {}

    /**
     * @OA\Get(
     *     path="/api/v1/receivables/summary",
     *     operationId="getReceivablesSummary",
     *     tags={"Receivables"},
     *     summary="채권 현황 요약 통계",
     *     description="연도별 총 매출, 입금, 어음, 미수금 합계 및 거래처 통계를 조회합니다.",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\Parameter(
     *         name="year",
     *         in="query",
     *         description="조회 연도",
     *
     *         @OA\Schema(type="integer", example=2025)
     *     ),
     *
     *     @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/ReceivablesSummary")
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패"),
     *     @OA\Response(response=403, description="권한 없음")
     * )
     */
    public function summary() {}
}