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

<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(
 *     name="ExpectedExpense",
 *     description="미지급비용(지출예상내역) 관리"
 * )
 *
 * @OA\Schema(
 *     schema="ExpectedExpense",
 *     type="object",
 *
 *     @OA\Property(property="id", type="integer", example=1),
 *     @OA\Property(property="tenant_id", type="integer", example=1),
 *     @OA\Property(property="expected_payment_date", type="string", format="date", example="2025-01-15"),
 *     @OA\Property(property="settlement_date", type="string", format="date", nullable=true, example="2025-01-10"),
 *     @OA\Property(property="transaction_type", type="string", enum={"purchase","advance","suspense","rent","salary","insurance","tax","utilities","other"}, example="purchase"),
 *     @OA\Property(property="amount", type="number", format="float", example=1500000),
 *     @OA\Property(property="client_id", type="integer", nullable=true, example=1),
 *     @OA\Property(property="client_name", type="string", nullable=true, example="(주)삼성전자"),
 *     @OA\Property(property="bank_account_id", type="integer", nullable=true, example=1),
 *     @OA\Property(property="account_code", type="string", nullable=true, example="매입비용"),
 *     @OA\Property(property="payment_status", type="string", enum={"pending","partial","paid","overdue"}, example="pending"),
 *     @OA\Property(property="approval_status", type="string", enum={"none","pending","approved","rejected"}, example="none"),
 *     @OA\Property(property="description", type="string", nullable=true, example="월정산"),
 *     @OA\Property(property="created_at", type="string", format="datetime"),
 *     @OA\Property(property="updated_at", type="string", format="datetime"),
 *     @OA\Property(
 *         property="client",
 *         type="object",
 *         nullable=true,
 *         @OA\Property(property="id", type="integer"),
 *         @OA\Property(property="name", type="string")
 *     ),
 *     @OA\Property(
 *         property="bank_account",
 *         type="object",
 *         nullable=true,
 *         @OA\Property(property="id", type="integer"),
 *         @OA\Property(property="bank_name", type="string"),
 *         @OA\Property(property="account_name", type="string")
 *     )
 * )
 *
 * @OA\Schema(
 *     schema="ExpectedExpensePagination",
 *     type="object",
 *
 *     @OA\Property(property="current_page", type="integer", example=1),
 *     @OA\Property(property="data", type="array", @OA\Items(ref="#/components/schemas/ExpectedExpense")),
 *     @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="ExpectedExpenseCreateRequest",
 *     type="object",
 *     required={"expected_payment_date", "transaction_type", "amount"},
 *
 *     @OA\Property(property="expected_payment_date", type="string", format="date", example="2025-01-15"),
 *     @OA\Property(property="settlement_date", type="string", format="date", nullable=true, example="2025-01-10"),
 *     @OA\Property(property="transaction_type", type="string", enum={"purchase","advance","suspense","rent","salary","insurance","tax","utilities","other"}, example="purchase"),
 *     @OA\Property(property="amount", type="number", format="float", example=1500000),
 *     @OA\Property(property="client_id", type="integer", nullable=true, example=1),
 *     @OA\Property(property="client_name", type="string", nullable=true, example="(주)삼성전자"),
 *     @OA\Property(property="bank_account_id", type="integer", nullable=true, example=1),
 *     @OA\Property(property="account_code", type="string", nullable=true, example="매입비용"),
 *     @OA\Property(property="payment_status", type="string", enum={"pending","partial","paid","overdue"}, example="pending"),
 *     @OA\Property(property="approval_status", type="string", enum={"none","pending","approved","rejected"}, example="none"),
 *     @OA\Property(property="description", type="string", nullable=true, example="월정산")
 * )
 *
 * @OA\Schema(
 *     schema="ExpectedExpenseUpdateRequest",
 *     type="object",
 *
 *     @OA\Property(property="expected_payment_date", type="string", format="date", example="2025-01-20"),
 *     @OA\Property(property="settlement_date", type="string", format="date", nullable=true),
 *     @OA\Property(property="transaction_type", type="string", enum={"purchase","advance","suspense","rent","salary","insurance","tax","utilities","other"}),
 *     @OA\Property(property="amount", type="number", format="float"),
 *     @OA\Property(property="client_id", type="integer", nullable=true),
 *     @OA\Property(property="client_name", type="string", nullable=true),
 *     @OA\Property(property="bank_account_id", type="integer", nullable=true),
 *     @OA\Property(property="account_code", type="string", nullable=true),
 *     @OA\Property(property="payment_status", type="string", enum={"pending","partial","paid","overdue"}),
 *     @OA\Property(property="approval_status", type="string", enum={"none","pending","approved","rejected"}),
 *     @OA\Property(property="description", type="string", nullable=true)
 * )
 *
 * @OA\Schema(
 *     schema="ExpectedExpenseSummary",
 *     type="object",
 *
 *     @OA\Property(property="total_amount", type="number", format="float", example=15000000),
 *     @OA\Property(property="total_count", type="integer", example=12),
 *     @OA\Property(property="by_payment_status", type="object"),
 *     @OA\Property(property="by_transaction_type", type="object"),
 *     @OA\Property(property="by_month", type="object")
 * )
 *
 * @OA\Schema(
 *     schema="ExpectedExpenseDashboardDetail",
 *     type="object",
 *     description="CEO 대시보드 당월 예상 지출내역 me4 모달용 데이터",
 *
 *     @OA\Property(
 *         property="summary",
 *         type="object",
 *         @OA\Property(property="current_month_total", type="number", format="float", example=5000000, description="당월 지출예상 합계"),
 *         @OA\Property(property="previous_month_total", type="number", format="float", example=4500000, description="전월 지출예상 합계"),
 *         @OA\Property(property="change_rate", type="number", format="float", example=11.1, description="전월대비 증감률(%)"),
 *         @OA\Property(property="pending_balance", type="number", format="float", example=3000000, description="미지급 잔액")
 *     ),
 *     @OA\Property(
 *         property="items",
 *         type="array",
 *         description="당월 지출예상 목록",
 *
 *         @OA\Items(
 *             type="object",
 *
 *             @OA\Property(property="id", type="integer", example=1),
 *             @OA\Property(property="payment_date", type="string", format="date", example="2026-01-15"),
 *             @OA\Property(property="item", type="string", example="월 임대료"),
 *             @OA\Property(property="amount", type="number", format="float", example=1500000),
 *             @OA\Property(property="vendor", type="string", example="(주)빌딩관리"),
 *             @OA\Property(property="account", type="string", example="임차료"),
 *             @OA\Property(property="status", type="string", example="pending")
 *         )
 *     ),
 *     @OA\Property(
 *         property="footer_summary",
 *         type="object",
 *         @OA\Property(property="total_amount", type="number", format="float", example=5000000),
 *         @OA\Property(property="total_count", type="integer", example=8)
 *     )
 * )
 */
class ExpectedExpenseApi
{
    /**
     * @OA\Get(
     *     path="/api/v1/expected-expenses",
     *     summary="미지급비용 목록 조회",
     *     tags={"ExpectedExpense"},
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\Parameter(name="search", in="query", description="검색어 (거래처명, 계정과목, 적요)", @OA\Schema(type="string")),
     *     @OA\Parameter(name="start_date", in="query", description="시작일", @OA\Schema(type="string", format="date")),
     *     @OA\Parameter(name="end_date", in="query", description="종료일", @OA\Schema(type="string", format="date")),
     *     @OA\Parameter(name="client_id", in="query", description="거래처 ID", @OA\Schema(type="integer")),
     *     @OA\Parameter(name="transaction_type", in="query", description="거래유형", @OA\Schema(type="string")),
     *     @OA\Parameter(name="payment_status", in="query", description="지급상태", @OA\Schema(type="string")),
     *     @OA\Parameter(name="approval_status", in="query", description="결재상태", @OA\Schema(type="string")),
     *     @OA\Parameter(name="sort_by", in="query", description="정렬 기준", @OA\Schema(type="string", default="expected_payment_date")),
     *     @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=50)),
     *     @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"),
     *             @OA\Property(property="data", ref="#/components/schemas/ExpectedExpensePagination")
     *         )
     *     )
     * )
     */
    public function index() {}

    /**
     * @OA\Post(
     *     path="/api/v1/expected-expenses",
     *     summary="미지급비용 등록",
     *     tags={"ExpectedExpense"},
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(ref="#/components/schemas/ExpectedExpenseCreateRequest")
     *     ),
     *
     *     @OA\Response(
     *         response=201,
     *         description="생성 성공",
     *
     *         @OA\JsonContent(
     *
     *             @OA\Property(property="success", type="boolean", example=true),
     *             @OA\Property(property="message", type="string"),
     *             @OA\Property(property="data", ref="#/components/schemas/ExpectedExpense")
     *         )
     *     )
     * )
     */
    public function store() {}

    /**
     * @OA\Get(
     *     path="/api/v1/expected-expenses/{id}",
     *     summary="미지급비용 상세 조회",
     *     tags={"ExpectedExpense"},
     *     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"),
     *             @OA\Property(property="data", ref="#/components/schemas/ExpectedExpense")
     *         )
     *     )
     * )
     */
    public function show() {}

    /**
     * @OA\Put(
     *     path="/api/v1/expected-expenses/{id}",
     *     summary="미지급비용 수정",
     *     tags={"ExpectedExpense"},
     *     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/ExpectedExpenseUpdateRequest")
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="수정 성공",
     *
     *         @OA\JsonContent(
     *
     *             @OA\Property(property="success", type="boolean", example=true),
     *             @OA\Property(property="message", type="string"),
     *             @OA\Property(property="data", ref="#/components/schemas/ExpectedExpense")
     *         )
     *     )
     * )
     */
    public function update() {}

    /**
     * @OA\Delete(
     *     path="/api/v1/expected-expenses/{id}",
     *     summary="미지급비용 삭제",
     *     tags={"ExpectedExpense"},
     *     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")
     *         )
     *     )
     * )
     */
    public function destroy() {}

    /**
     * @OA\Delete(
     *     path="/api/v1/expected-expenses",
     *     summary="미지급비용 일괄 삭제",
     *     tags={"ExpectedExpense"},
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(
     *
     *             @OA\Property(property="ids", type="array", @OA\Items(type="integer"), example={1, 2, 3})
     *         )
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="일괄 삭제 성공",
     *
     *         @OA\JsonContent(
     *
     *             @OA\Property(property="success", type="boolean", example=true),
     *             @OA\Property(property="message", type="string"),
     *             @OA\Property(property="data", type="object",
     *                 @OA\Property(property="deleted_count", type="integer", example=3)
     *             )
     *         )
     *     )
     * )
     */
    public function destroyMany() {}

    /**
     * @OA\Put(
     *     path="/api/v1/expected-expenses/update-payment-date",
     *     summary="예상 지급일 일괄 변경",
     *     tags={"ExpectedExpense"},
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(
     *
     *             @OA\Property(property="ids", type="array", @OA\Items(type="integer"), example={1, 2, 3}),
     *             @OA\Property(property="expected_payment_date", type="string", format="date", example="2025-02-01")
     *         )
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="일괄 변경 성공",
     *
     *         @OA\JsonContent(
     *
     *             @OA\Property(property="success", type="boolean", example=true),
     *             @OA\Property(property="message", type="string"),
     *             @OA\Property(property="data", type="object",
     *                 @OA\Property(property="updated_count", type="integer", example=3)
     *             )
     *         )
     *     )
     * )
     */
    public function updateExpectedPaymentDate() {}

    /**
     * @OA\Get(
     *     path="/api/v1/expected-expenses/summary",
     *     summary="미지급비용 요약 (기간별 합계)",
     *     tags={"ExpectedExpense"},
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\Parameter(name="start_date", in="query", description="시작일", @OA\Schema(type="string", format="date")),
     *     @OA\Parameter(name="end_date", in="query", description="종료일", @OA\Schema(type="string", format="date")),
     *     @OA\Parameter(name="payment_status", in="query", description="지급상태", @OA\Schema(type="string")),
     *
     *     @OA\Response(
     *         response=200,
     *         description="성공",
     *
     *         @OA\JsonContent(
     *
     *             @OA\Property(property="success", type="boolean", example=true),
     *             @OA\Property(property="message", type="string"),
     *             @OA\Property(property="data", ref="#/components/schemas/ExpectedExpenseSummary")
     *         )
     *     )
     * )
     */
    public function summary() {}

    /**
     * @OA\Get(
     *     path="/api/v1/expected-expenses/dashboard-detail",
     *     summary="대시보드 상세 조회 (CEO 대시보드 당월 예상 지출내역 me4 모달용)",
     *     description="당월 지출예상 요약, 상세 목록을 제공합니다. me4(지출예상) 모달에서 사용됩니다.",
     *     tags={"ExpectedExpense"},
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\Response(
     *         response=200,
     *         description="성공",
     *
     *         @OA\JsonContent(
     *
     *             @OA\Property(property="success", type="boolean", example=true),
     *             @OA\Property(property="message", type="string"),
     *             @OA\Property(property="data", ref="#/components/schemas/ExpectedExpenseDashboardDetail")
     *         )
     *     )
     * )
     */
    public function dashboardDetail() {}
}