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

<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(
 *     name="DailyReport",
 *     description="일일 보고서 API - 일일 자금 현황 조회"
 * )
 */

/**
 * @OA\Schema(
 *     schema="NoteReceivableItem",
 *     description="어음 및 외상매출채권 아이템",
 *
 *     @OA\Property(property="id", type="string", description="ID", example="1"),
 *     @OA\Property(property="content", type="string", description="내용", example="(수취어음) 거래처명 - 12312123"),
 *     @OA\Property(property="current_balance", type="number", format="float", description="현재 잔액", example=1000000),
 *     @OA\Property(property="issue_date", type="string", format="date", description="발행일", example="2025-12-12"),
 *     @OA\Property(property="due_date", type="string", format="date", description="만기일", example="2025-12-13")
 * )
 *
 * @OA\Schema(
 *     schema="DailyAccountItem",
 *     description="일별 계좌 현황 아이템",
 *
 *     @OA\Property(property="id", type="string", description="계좌 ID", example="1"),
 *     @OA\Property(property="category", type="string", description="구분 (은행명 계좌번호)", example="국민 ****3121"),
 *     @OA\Property(property="match_status", type="string", enum={"matched", "unmatched"}, description="매칭 상태", example="matched"),
 *     @OA\Property(property="carryover", type="number", format="float", description="전월 이월", example=1000000),
 *     @OA\Property(property="income", type="number", format="float", description="수입", example=500000),
 *     @OA\Property(property="expense", type="number", format="float", description="지출", example=300000),
 *     @OA\Property(property="balance", type="number", format="float", description="잔액", example=1200000),
 *     @OA\Property(property="currency", type="string", enum={"KRW", "USD"}, description="통화", example="KRW")
 * )
 *
 * @OA\Schema(
 *     schema="DailyReportSummary",
 *     description="일일 보고서 요약",
 *
 *     @OA\Property(property="date", type="string", format="date", description="조회 일자", example="2025-12-26"),
 *     @OA\Property(property="day_of_week", type="string", description="요일", example="목요일"),
 *     @OA\Property(property="note_receivable_total", type="number", format="float", description="어음 합계", example=5000000),
 *     @OA\Property(property="foreign_currency_total", type="number", format="float", description="외화 합계 (USD)", example=0),
 *     @OA\Property(property="cash_asset_total", type="number", format="float", description="현금성 자산 합계", example=10000000),
 *     @OA\Property(
 *         property="krw_totals",
 *         type="object",
 *         description="KRW 합계",
 *         @OA\Property(property="carryover", type="number", format="float"),
 *         @OA\Property(property="income", type="number", format="float"),
 *         @OA\Property(property="expense", type="number", format="float"),
 *         @OA\Property(property="balance", type="number", format="float")
 *     ),
 *     @OA\Property(
 *         property="usd_totals",
 *         type="object",
 *         description="USD 합계",
 *         @OA\Property(property="carryover", type="number", format="float"),
 *         @OA\Property(property="income", type="number", format="float"),
 *         @OA\Property(property="expense", type="number", format="float"),
 *         @OA\Property(property="balance", type="number", format="float")
 *     ),
 *     @OA\Property(property="monthly_operating_expense", type="number", format="float", description="월 운영비 (직전 3개월 평균)", example=500000000),
 *     @OA\Property(property="operating_months", type="number", format="float", nullable=true, description="운영 가능 개월 수 (현금자산/월운영비)", example=6.5),
 *     @OA\Property(property="operating_stability", type="string", enum={"stable", "caution", "warning", "unknown"}, description="운영자금 안정성 (stable: 6개월↑, caution: 3~6개월, warning: 3개월↓)", example="stable")
 * )
 */
class DailyReportApi
{
    /**
     * @OA\Get(
     *     path="/api/v1/daily-report/note-receivables",
     *     operationId="getDailyReportNoteReceivables",
     *     tags={"DailyReport"},
     *     summary="어음 및 외상매출채권 현황 조회",
     *     description="수취어음 현황을 조회합니다.",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\Parameter(
     *         name="date",
     *         in="query",
     *         description="조회 일자 (기본: 오늘)",
     *
     *         @OA\Schema(type="string", format="date", example="2025-12-26")
     *     ),
     *
     *     @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/NoteReceivableItem")
     *             )
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패"),
     *     @OA\Response(response=403, description="권한 없음")
     * )
     */
    public function noteReceivables() {}

    /**
     * @OA\Get(
     *     path="/api/v1/daily-report/daily-accounts",
     *     operationId="getDailyReportDailyAccounts",
     *     tags={"DailyReport"},
     *     summary="일별 계좌 현황 조회",
     *     description="일별 계좌별 수입/지출 현황을 조회합니다.",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\Parameter(
     *         name="date",
     *         in="query",
     *         description="조회 일자 (기본: 오늘)",
     *
     *         @OA\Schema(type="string", format="date", example="2025-12-26")
     *     ),
     *
     *     @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/DailyAccountItem")
     *             )
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패"),
     *     @OA\Response(response=403, description="권한 없음")
     * )
     */
    public function dailyAccounts() {}

    /**
     * @OA\Get(
     *     path="/api/v1/daily-report/summary",
     *     operationId="getDailyReportSummary",
     *     tags={"DailyReport"},
     *     summary="일일 보고서 요약",
     *     description="일일 자금 현황 요약 통계를 조회합니다.",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\Parameter(
     *         name="date",
     *         in="query",
     *         description="조회 일자 (기본: 오늘)",
     *
     *         @OA\Schema(type="string", format="date", example="2025-12-26")
     *     ),
     *
     *     @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/DailyReportSummary")
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패"),
     *     @OA\Response(response=403, description="권한 없음")
     * )
     */
    public function summary() {}
}