SamProject/sam-api
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3d12687a2dc1d8c7e48b25e57591b20100dc234b
sam-api/app/Swagger/v1/BiddingApi.php

361 lines
16 KiB
PHP
Raw Normal View History

feat: 입찰(Bidding) 관리 기능 구현 - Bidding 모델, 서비스, 컨트롤러, FormRequest 추가 - 마이그레이션 및 시더 추가 - Swagger API 문서 추가 - 견적에서 입찰 전환 시 중복 체크 로직 추가 - per_page 파라미터 100 초과 시 자동 클램핑 처리 - error.bidding.already_registered 에러 메시지 추가
2026-01-19 20:23:30 +09:00
<?php
namespace App\Swagger\v1;
/**
* @OA\Tag(
* name="Bidding",
* description="입찰관리 API"
* )
*
* @OA\Schema(
* schema="Bidding",
* type="object",
*
* @OA\Property(property="id", type="integer", example=1),
* @OA\Property(property="tenant_id", type="integer", example=1),
* @OA\Property(property="bidding_code", type="string", example="BID-20260119-0001"),
* @OA\Property(property="quote_id", type="integer", nullable=true, example=1),
* @OA\Property(property="client_id", type="integer", nullable=true, example=1),
* @OA\Property(property="client_name", type="string", nullable=true, example="삼성물산"),
* @OA\Property(property="project_name", type="string", nullable=true, example="강남역 오피스타워 신축공사"),
* @OA\Property(property="bidding_date", type="string", format="date", nullable=true, example="2026-01-19"),
* @OA\Property(property="bid_date", type="string", format="date", nullable=true, example="2026-02-01"),
* @OA\Property(property="submission_date", type="string", format="date", nullable=true, example="2026-01-25"),
* @OA\Property(property="confirm_date", type="string", format="date", nullable=true, example="2026-02-15"),
* @OA\Property(property="total_count", type="integer", nullable=true, example=1),
* @OA\Property(property="bidding_amount", type="number", format="float", nullable=true, example=150000000),
* @OA\Property(property="status", type="string", enum={"waiting", "submitted", "failed", "invalid", "awarded", "hold"}, example="waiting"),
* @OA\Property(property="bidder_id", type="integer", nullable=true, example=1),
* @OA\Property(property="bidder_name", type="string", nullable=true, example="홍길동"),
* @OA\Property(property="construction_start_date", type="string", format="date", nullable=true, example="2026-03-01"),
* @OA\Property(property="construction_end_date", type="string", format="date", nullable=true, example="2026-12-31"),
* @OA\Property(property="vat_type", type="string", enum={"included", "excluded"}, example="included"),
* @OA\Property(property="remarks", type="string", nullable=true, example="특이사항 없음"),
* @OA\Property(property="expense_items", type="array", nullable=true, @OA\Items(type="object")),
* @OA\Property(property="estimate_detail_items", type="array", nullable=true, @OA\Items(type="object")),
* @OA\Property(property="created_by", type="integer", nullable=true),
* @OA\Property(property="updated_by", type="integer", nullable=true),
* @OA\Property(property="created_at", type="string", format="date-time"),
* @OA\Property(property="updated_at", type="string", format="date-time"),
* @OA\Property(property="quote", type="object", nullable=true),
* @OA\Property(property="client", type="object", nullable=true),
* @OA\Property(property="bidder", type="object", nullable=true)
* )
*
* @OA\Schema(
* schema="BiddingPagination",
* type="object",
*
* @OA\Property(property="current_page", type="integer", example=1),
* @OA\Property(property="data", type="array", @OA\Items(ref="#/components/schemas/Bidding")),
* @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="BiddingStats",
* type="object",
*
* @OA\Property(property="total", type="integer", example=100),
* @OA\Property(property="waiting", type="integer", example=30),
* @OA\Property(property="submitted", type="integer", example=20),
* @OA\Property(property="failed", type="integer", example=10),
* @OA\Property(property="invalid", type="integer", example=5),
* @OA\Property(property="awarded", type="integer", example=30),
* @OA\Property(property="hold", type="integer", example=5),
* @OA\Property(property="total_amount", type="number", format="float", example=5000000000),
* @OA\Property(property="awarded_amount", type="number", format="float", example=3000000000)
* )
*
* @OA\Schema(
* schema="BiddingUpdateRequest",
* type="object",
*
* @OA\Property(property="client_id", type="integer", nullable=true),
* @OA\Property(property="client_name", type="string", nullable=true, maxLength=100),
* @OA\Property(property="project_name", type="string", nullable=true, maxLength=200),
* @OA\Property(property="bidding_date", type="string", format="date", nullable=true),
* @OA\Property(property="bid_date", type="string", format="date", nullable=true),
* @OA\Property(property="submission_date", type="string", format="date", nullable=true),
* @OA\Property(property="confirm_date", type="string", format="date", nullable=true),
* @OA\Property(property="total_count", type="integer", nullable=true, minimum=0),
* @OA\Property(property="bidding_amount", type="number", format="float", nullable=true, minimum=0),
* @OA\Property(property="status", type="string", enum={"waiting", "submitted", "failed", "invalid", "awarded", "hold"}, nullable=true),
* @OA\Property(property="bidder_id", type="integer", nullable=true),
* @OA\Property(property="bidder_name", type="string", nullable=true, maxLength=50),
* @OA\Property(property="construction_start_date", type="string", format="date", nullable=true),
* @OA\Property(property="construction_end_date", type="string", format="date", nullable=true),
* @OA\Property(property="vat_type", type="string", enum={"included", "excluded"}, nullable=true),
* @OA\Property(property="remarks", type="string", nullable=true),
* @OA\Property(property="expense_items", type="array", nullable=true, @OA\Items(type="object")),
* @OA\Property(property="estimate_detail_items", type="array", nullable=true, @OA\Items(type="object"))
* )
*
* @OA\Schema(
* schema="BiddingStatusRequest",
* type="object",
* required={"status"},
*
* @OA\Property(property="status", type="string", enum={"waiting", "submitted", "failed", "invalid", "awarded", "hold"}, example="submitted")
* )
*
* @OA\Schema(
* schema="BiddingBulkDeleteRequest",
* type="object",
* required={"ids"},
*
* @OA\Property(property="ids", type="array", @OA\Items(type="integer"), example={1, 2, 3})
* )
*/
class BiddingApi
{
/**
* @OA\Get(
* path="/api/v1/biddings",
* tags={"Bidding"},
* summary="입찰 목록 조회",
* description="입찰 목록을 페이징하여 조회합니다.",
* security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
*
* @OA\Parameter(name="page", in="query", @OA\Schema(type="integer", default=1)),
* @OA\Parameter(name="size", in="query", @OA\Schema(type="integer", default=20)),
* @OA\Parameter(name="q", in="query", description="검색어 (입찰번호, 현장명, 거래처명)", @OA\Schema(type="string")),
* @OA\Parameter(name="status", in="query", description="상태 필터", @OA\Schema(type="string", enum={"waiting", "submitted", "failed", "invalid", "awarded", "hold"})),
* @OA\Parameter(name="client_id", in="query", description="거래처 ID", @OA\Schema(type="integer")),
* @OA\Parameter(name="bidder_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="sort_by", in="query", description="정렬 기준", @OA\Schema(type="string", default="bidding_date")),
* @OA\Parameter(name="sort_order", in="query", description="정렬 순서", @OA\Schema(type="string", enum={"asc", "desc"}, default="desc")),
*
* @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/BiddingPagination")
* )
* )
* )
*/
public function index() {}
/**
* @OA\Get(
* path="/api/v1/biddings/stats",
* tags={"Bidding"},
* summary="입찰 통계 조회",
* description="상태별 입찰 건수와 금액을 조회합니다.",
* 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/BiddingStats")
* )
* )
* )
*/
public function stats() {}
/**
* @OA\Get(
* path="/api/v1/biddings/{id}",
* tags={"Bidding"},
* summary="입찰 단건 조회",
* description="입찰 상세 정보를 조회합니다.",
* security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
*
* @OA\Parameter(name="id", in="path", required=true, @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/Bidding")
* )
* ),
*
* @OA\Response(response=404, description="입찰을 찾을 수 없습니다")
* )
*/
public function show() {}
/**
* @OA\Put(
* path="/api/v1/biddings/{id}",
* tags={"Bidding"},
* summary="입찰 수정",
* description="입찰 정보를 수정합니다.",
* security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
*
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
*
* @OA\RequestBody(
* required=true,
*
* @OA\JsonContent(ref="#/components/schemas/BiddingUpdateRequest")
* ),
*
* @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/Bidding")
* )
* ),
*
* @OA\Response(response=404, description="입찰을 찾을 수 없습니다"),
* @OA\Response(response=422, description="유효성 검증 실패")
* )
*/
public function update() {}
/**
* @OA\Delete(
* path="/api/v1/biddings/{id}",
* tags={"Bidding"},
* summary="입찰 삭제",
* description="입찰을 삭제합니다 (Soft Delete).",
* security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
*
* @OA\Parameter(name="id", in="path", required=true, @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", type="null")
* )
* ),
*
* @OA\Response(response=404, description="입찰을 찾을 수 없습니다")
* )
*/
public function destroy() {}
/**
* @OA\Delete(
* path="/api/v1/biddings/bulk",
* tags={"Bidding"},
* summary="입찰 일괄 삭제",
* description="여러 입찰을 일괄 삭제합니다 (Soft Delete).",
* security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
*
* @OA\RequestBody(
* required=true,
*
* @OA\JsonContent(ref="#/components/schemas/BiddingBulkDeleteRequest")
* ),
*
* @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)
* )
* )
* ),
*
* @OA\Response(response=422, description="유효성 검증 실패")
* )
*/
public function bulkDestroy() {}
/**
* @OA\Patch(
* path="/api/v1/biddings/{id}/status",
* tags={"Bidding"},
* summary="입찰 상태 변경",
* description="입찰 상태를 변경합니다.",
* security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
*
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
*
* @OA\RequestBody(
* required=true,
*
* @OA\JsonContent(ref="#/components/schemas/BiddingStatusRequest")
* ),
*
* @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/Bidding")
* )
* ),
*
* @OA\Response(response=404, description="입찰을 찾을 수 없습니다"),
* @OA\Response(response=422, description="유효성 검증 실패")
* )
*/
public function updateStatus() {}
/**
* @OA\Post(
* path="/api/v1/quotes/{id}/convert-to-bidding",
* tags={"Bidding"},
* summary="견적을 입찰로 변환",
* description="시공 견적을 입찰로 변환합니다. 견적 데이터 스냅샷이 저장됩니다.",
* 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/Bidding")
* )
* ),
*
* @OA\Response(response=404, description="견적을 찾을 수 없습니다"),
* @OA\Response(response=400, description="이미 입찰로 변환된 견적입니다")
* )
*/
public function convertToBidding() {}
}
Reference in New Issue Copy Permalink