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

<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(name="Estimate", description="견적 관리 API")
 *
 * @OA\Schema(
 *     schema="Estimate",
 *
 *     @OA\Property(property="id", type="integer"),
 *     @OA\Property(property="model_set_id", type="integer"),
 *     @OA\Property(property="estimate_name", type="string"),
 *     @OA\Property(property="customer_name", type="string", nullable=true),
 *     @OA\Property(property="project_name", type="string", nullable=true),
 *     @OA\Property(property="parameters", type="object"),
 *     @OA\Property(property="status", type="string", enum={"DRAFT","SENT","APPROVED","REJECTED","EXPIRED"}),
 *     @OA\Property(property="notes", type="string", nullable=true),
 *     @OA\Property(property="created_at", type="string", format="date-time"),
 *     @OA\Property(property="updated_at", type="string", format="date-time")
 * )
 *
 * @OA\Schema(
 *     schema="EstimateCreateRequest",
 *     required={"model_set_id", "estimate_name", "parameters"},
 *
 *     @OA\Property(property="model_set_id", type="integer", description="모델셋 ID"),
 *     @OA\Property(property="estimate_name", type="string", description="견적명"),
 *     @OA\Property(property="customer_name", type="string", description="고객명"),
 *     @OA\Property(property="project_name", type="string", description="프로젝트명"),
 *     @OA\Property(property="parameters", type="object", description="견적 파라미터"),
 *     @OA\Property(property="notes", type="string", description="비고")
 * )
 *
 * @OA\Schema(
 *     schema="EstimateUpdateRequest",
 *
 *     @OA\Property(property="estimate_name", type="string", description="견적명"),
 *     @OA\Property(property="customer_name", type="string", description="고객명"),
 *     @OA\Property(property="project_name", type="string", description="프로젝트명"),
 *     @OA\Property(property="parameters", type="object", description="견적 파라미터"),
 *     @OA\Property(property="status", type="string", description="견적 상태"),
 *     @OA\Property(property="notes", type="string", description="비고")
 * )
 */
class EstimateApi
{
    /**
     * @OA\Get(
     *     path="/api/v1/estimates",
     *     summary="견적 목록 조회",
     *     tags={"Estimate"},
     *     security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *
     *     @OA\Parameter(name="status", in="query", description="견적 상태", @OA\Schema(type="string")),
     *     @OA\Parameter(name="customer_name", in="query", description="고객명", @OA\Schema(type="string")),
     *     @OA\Parameter(name="model_set_id", in="query", description="모델셋 ID", @OA\Schema(type="integer")),
     *     @OA\Parameter(name="date_from", in="query", description="시작일", @OA\Schema(type="string", format="date")),
     *     @OA\Parameter(name="date_to", in="query", description="종료일", @OA\Schema(type="string", format="date")),
     *     @OA\Parameter(name="search", in="query", description="검색어", @OA\Schema(type="string")),
     *     @OA\Parameter(name="per_page", in="query", description="페이지당 항목수", @OA\Schema(type="integer", default=20)),
     *
     *     @OA\Response(response=200, description="성공")
     * )
     */
    public function index() {}

    /**
     * @OA\Get(
     *     path="/api/v1/estimates/{id}",
     *     summary="견적 상세 조회",
     *     tags={"Estimate"},
     *     security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *
     *     @OA\Parameter(name="id", in="path", required=true, description="견적 ID", @OA\Schema(type="integer")),
     *
     *     @OA\Response(response=200, description="성공")
     * )
     */
    public function show() {}

    /**
     * @OA\Post(
     *     path="/api/v1/estimates",
     *     summary="견적 생성",
     *     tags={"Estimate"},
     *     security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(ref="#/components/schemas/EstimateCreateRequest")
     *     ),
     *
     *     @OA\Response(response=201, description="생성 성공")
     * )
     */
    public function store() {}

    /**
     * @OA\Put(
     *     path="/api/v1/estimates/{id}",
     *     summary="견적 수정",
     *     tags={"Estimate"},
     *     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/EstimateUpdateRequest")
     *     ),
     *
     *     @OA\Response(response=200, description="수정 성공")
     * )
     */
    public function update() {}

    /**
     * @OA\Delete(
     *     path="/api/v1/estimates/{id}",
     *     summary="견적 삭제",
     *     tags={"Estimate"},
     *     security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *
     *     @OA\Parameter(name="id", in="path", required=true, description="견적 ID", @OA\Schema(type="integer")),
     *
     *     @OA\Response(response=200, description="삭제 성공")
     * )
     */
    public function destroy() {}

    /**
     * @OA\Post(
     *     path="/api/v1/estimates/{id}/clone",
     *     summary="견적 복제",
     *     tags={"Estimate"},
     *     security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *
     *     @OA\Parameter(name="id", in="path", required=true, description="견적 ID", @OA\Schema(type="integer")),
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(
     *             required={"estimate_name"},
     *
     *             @OA\Property(property="estimate_name", type="string", description="새 견적명"),
     *             @OA\Property(property="customer_name", type="string", description="고객명"),
     *             @OA\Property(property="project_name", type="string", description="프로젝트명"),
     *             @OA\Property(property="notes", type="string", description="비고")
     *         )
     *     ),
     *
     *     @OA\Response(response=201, description="복제 성공")
     * )
     */
    public function clone() {}

    /**
     * @OA\Put(
     *     path="/api/v1/estimates/{id}/status",
     *     summary="견적 상태 변경",
     *     tags={"Estimate"},
     *     security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *
     *     @OA\Parameter(name="id", in="path", required=true, description="견적 ID", @OA\Schema(type="integer")),
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(
     *             required={"status"},
     *
     *             @OA\Property(property="status", type="string", enum={"DRAFT","SENT","APPROVED","REJECTED","EXPIRED"}, description="변경할 상태"),
     *             @OA\Property(property="notes", type="string", description="상태 변경 사유")
     *         )
     *     ),
     *
     *     @OA\Response(response=200, description="상태 변경 성공")
     * )
     */
    public function changeStatus() {}

    /**
     * @OA\Get(
     *     path="/api/v1/estimates/form-schema/{model_set_id}",
     *     summary="견적 폼 스키마 조회",
     *     tags={"Estimate"},
     *     security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *
     *     @OA\Parameter(name="model_set_id", in="path", required=true, description="모델셋 ID", @OA\Schema(type="integer")),
     *
     *     @OA\Response(response=200, description="성공")
     * )
     */
    public function getFormSchema() {}

    /**
     * @OA\Post(
     *     path="/api/v1/estimates/preview/{model_set_id}",
     *     summary="견적 계산 미리보기",
     *     tags={"Estimate"},
     *     security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
     *
     *     @OA\Parameter(name="model_set_id", in="path", required=true, description="모델셋 ID", @OA\Schema(type="integer")),
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(
     *             required={"parameters"},
     *
     *             @OA\Property(property="parameters", type="object", description="견적 파라미터")
     *         )
     *     ),
     *
     *     @OA\Response(response=200, description="계산 성공")
     * )
     */
    public function previewCalculation() {}
}