781 lines
26 KiB
PHP
781 lines
26 KiB
PHP
<?php
|
|
|
|
namespace App\Swagger\v1;
|
|
|
|
use OpenApi\Annotations as OA;
|
|
|
|
/**
|
|
* @OA\Tag(name="Product", description="제품 카테고리/검색(간단)")
|
|
* @OA\Tag(name="Products", description="제품/부품/서브어셈블리 CRUD")
|
|
* @OA\Tag(name="Products-BOM", description="제품 BOM (제품/자재 혼합) 관리")
|
|
*
|
|
* ========= 공용 스키마(이 파일에서 사용하는 것만 정의) =========
|
|
*
|
|
* 트리 노드 스키마 (재귀)
|
|
*
|
|
* @OA\Schema(
|
|
* schema="BomTreeNode",
|
|
* type="object",
|
|
* description="BOM 트리 한 노드(제품/자재 공통)",
|
|
*
|
|
* @OA\Property(property="id", type="integer", example=1),
|
|
* @OA\Property(property="type", type="string", example="PRODUCT", description="PRODUCT / MATERIAL 등"),
|
|
* @OA\Property(property="code", type="string", example="PRD-001"),
|
|
* @OA\Property(property="name", type="string", example="스크린 모듈 KS001"),
|
|
* @OA\Property(property="unit", type="string", nullable=true, example="SET"),
|
|
* @OA\Property(property="quantity", type="number", format="float", example=1),
|
|
* @OA\Property(property="sort_order", type="integer", example=0),
|
|
* @OA\Property(
|
|
* property="category",
|
|
* type="object",
|
|
* nullable=true,
|
|
* @OA\Property(property="id", type="integer", nullable=true, example=2),
|
|
* @OA\Property(property="name", type="string", nullable=true, example="본체")
|
|
* ),
|
|
* @OA\Property(
|
|
* property="children",
|
|
* type="array",
|
|
* description="자식 노드 목록(없으면 빈 배열)",
|
|
*
|
|
* @OA\Items(ref="#/components/schemas/BomTreeNode")
|
|
* )
|
|
* )
|
|
*
|
|
* BOM 카테고리 사용/추천 항목
|
|
*
|
|
* @OA\Schema(
|
|
* schema="BomCategoryStat",
|
|
* type="object",
|
|
*
|
|
* @OA\Property(property="category_id", type="integer", nullable=true, example=1),
|
|
* @OA\Property(property="category_name", type="string", example="기본"),
|
|
* @OA\Property(property="count", type="integer", example=5, description="해당 카테고리를 사용하는 BOM 항목 수(빈도)")
|
|
* )
|
|
*
|
|
* BOM 전체 교체 저장용 스키마
|
|
*
|
|
* @OA\Schema(
|
|
* schema="BomReplaceItem",
|
|
* type="object",
|
|
* required={"ref_type","ref_id","quantity"},
|
|
*
|
|
* @OA\Property(property="ref_type", type="string", enum={"MATERIAL","PRODUCT"}, example="MATERIAL", description="참조 타입"),
|
|
* @OA\Property(property="ref_id", type="integer", example=201, description="참조 ID (materials.id 또는 products.id)"),
|
|
* @OA\Property(property="quantity", type="number", format="float", example=2, description="수량(0 이상, 소수 허용)"),
|
|
* @OA\Property(property="sort_order", type="integer", nullable=true, example=0, description="정렬 순서(선택)")
|
|
* )
|
|
*
|
|
* @OA\Schema(
|
|
* schema="BomReplaceCategory",
|
|
* type="object",
|
|
* required={"items"},
|
|
*
|
|
* @OA\Property(property="id", type="integer", nullable=true, example=1, description="프론트 임시 카테고리 ID(선택)"),
|
|
* @OA\Property(property="name", type="string", nullable=true, example="기본", description="프론트 카테고리명(선택)"),
|
|
* @OA\Property(
|
|
* property="items",
|
|
* type="array",
|
|
*
|
|
* @OA\Items(ref="#/components/schemas/BomReplaceItem")
|
|
* )
|
|
* )
|
|
*
|
|
* @OA\Schema(
|
|
* schema="BomReplaceRequest",
|
|
* type="object",
|
|
* required={"categories"},
|
|
*
|
|
* @OA\Property(
|
|
* property="categories",
|
|
* type="array",
|
|
*
|
|
* @OA\Items(ref="#/components/schemas/BomReplaceCategory")
|
|
* ),
|
|
* example={
|
|
* "categories": {
|
|
* {
|
|
* "id": 1,
|
|
* "name": "기본",
|
|
* "items": {
|
|
* { "ref_type": "MATERIAL", "ref_id": 201, "quantity": 2, "sort_order": 0 },
|
|
* { "ref_type": "PRODUCT", "ref_id": 301, "quantity": 1 }
|
|
* }
|
|
* },
|
|
* {
|
|
* "id": 2,
|
|
* "name": "옵션",
|
|
* "items": {
|
|
* { "ref_type": "MATERIAL", "ref_id": 202, "quantity": 5 }
|
|
* }
|
|
* }
|
|
* }
|
|
* }
|
|
* )
|
|
*
|
|
* @OA\Schema(
|
|
* schema="BomReplaceResult",
|
|
* type="object",
|
|
*
|
|
* @OA\Property(property="deleted_count", type="integer", example=5, description="삭제된 기존 항목 수"),
|
|
* @OA\Property(property="inserted_count", type="integer", example=7, description="신규로 삽입된 항목 수")
|
|
* )
|
|
*/
|
|
class ProductApi
|
|
{
|
|
/**
|
|
* 카테고리 목록 조회 (기존)
|
|
*
|
|
* @OA\Get(
|
|
* path="/api/v1/product/category",
|
|
* summary="제품 카테고리 목록 조회",
|
|
* description="제품 카테고리(최상위: parent_id = null) 리스트를 반환합니다.",
|
|
* tags={"Products"},
|
|
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
|
|
*
|
|
* @OA\Response(
|
|
* response=200,
|
|
* description="카테고리 목록 조회 성공",
|
|
*
|
|
* @OA\JsonContent(
|
|
* allOf={
|
|
*
|
|
* @OA\Schema(ref="#/components/schemas/ApiResponse"),
|
|
* @OA\Schema(
|
|
*
|
|
* @OA\Property(
|
|
* property="data",
|
|
* type="array",
|
|
*
|
|
* @OA\Items(ref="#/components/schemas/ProductCategory")
|
|
* )
|
|
* )
|
|
* }
|
|
* )
|
|
* ),
|
|
*
|
|
* @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
|
|
* @OA\Response(response=403, description="권한 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
|
|
* )
|
|
*/
|
|
public function productCategoryIndex() {}
|
|
|
|
/**
|
|
* 제품 목록/검색
|
|
*
|
|
* @OA\Get(
|
|
* path="/api/v1/products",
|
|
* tags={"Products"},
|
|
* summary="제품 목록/검색",
|
|
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
|
|
*
|
|
* @OA\Parameter(ref="#/components/parameters/Page"),
|
|
* @OA\Parameter(ref="#/components/parameters/Size"),
|
|
* @OA\Parameter(name="q", in="query", @OA\Schema(type="string"), description="코드/이름/설명 검색"),
|
|
* @OA\Parameter(name="category_id", in="query", @OA\Schema(type="integer")),
|
|
* @OA\Parameter(name="product_type", in="query", @OA\Schema(type="string", example="PRODUCT")),
|
|
* @OA\Parameter(name="active", in="query", @OA\Schema(type="integer", enum={0,1})),
|
|
*
|
|
* @OA\Response(
|
|
* response=200,
|
|
* description="조회 성공",
|
|
*
|
|
* @OA\JsonContent(allOf={
|
|
*
|
|
* @OA\Schema(ref="#/components/schemas/ApiResponse"),
|
|
* @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/ProductPagination"))
|
|
* })
|
|
* )
|
|
* )
|
|
*/
|
|
public function productsIndex() {}
|
|
|
|
/**
|
|
* 제품 생성
|
|
*
|
|
* @OA\Post(
|
|
* path="/api/v1/products",
|
|
* tags={"Products"},
|
|
* summary="제품 생성",
|
|
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
|
|
*
|
|
* @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/ProductCreateRequest")),
|
|
*
|
|
* @OA\Response(
|
|
* response=200,
|
|
* description="생성 성공",
|
|
*
|
|
* @OA\JsonContent(allOf={
|
|
*
|
|
* @OA\Schema(ref="#/components/schemas/ApiResponse"),
|
|
* @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Product"))
|
|
* })
|
|
* )
|
|
* )
|
|
*/
|
|
public function productsStore() {}
|
|
|
|
/**
|
|
* 제품 단건
|
|
*
|
|
* @OA\Get(
|
|
* path="/api/v1/products/{id}",
|
|
* tags={"Products"},
|
|
* summary="제품 단건 조회",
|
|
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
|
|
*
|
|
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
|
|
*
|
|
* @OA\Response(
|
|
* response=200,
|
|
* description="조회 성공",
|
|
*
|
|
* @OA\JsonContent(allOf={
|
|
*
|
|
* @OA\Schema(ref="#/components/schemas/ApiResponse"),
|
|
* @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Product"))
|
|
* })
|
|
* ),
|
|
*
|
|
* @OA\Response(response=404, description="없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
|
|
* )
|
|
*/
|
|
public function productsShow() {}
|
|
|
|
/**
|
|
* 제품 수정
|
|
*
|
|
* @OA\Patch(
|
|
* path="/api/v1/products/{id}",
|
|
* tags={"Products"},
|
|
* summary="제품 수정",
|
|
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
|
|
*
|
|
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
|
|
*
|
|
* @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/ProductUpdateRequest")),
|
|
*
|
|
* @OA\Response(
|
|
* response=200,
|
|
* description="수정 성공",
|
|
*
|
|
* @OA\JsonContent(allOf={
|
|
*
|
|
* @OA\Schema(ref="#/components/schemas/ApiResponse"),
|
|
* @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Product"))
|
|
* })
|
|
* )
|
|
* )
|
|
*/
|
|
public function productsUpdate() {}
|
|
|
|
/**
|
|
* 제품 삭제(soft)
|
|
*
|
|
* @OA\Delete(
|
|
* path="/api/v1/products/{id}",
|
|
* tags={"Products"},
|
|
* summary="제품 삭제(soft)",
|
|
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
|
|
*
|
|
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
|
|
*
|
|
* @OA\Response(response=200, description="삭제 성공", @OA\JsonContent(ref="#/components/schemas/ApiResponse"))
|
|
* )
|
|
*/
|
|
public function productsDestroy() {}
|
|
|
|
/**
|
|
* 제품 간편 검색(모달/드롭다운)
|
|
*
|
|
* @OA\Get(
|
|
* path="/api/v1/products/search",
|
|
* tags={"Products"},
|
|
* summary="제품 간편 검색",
|
|
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
|
|
*
|
|
* @OA\Parameter(name="q", in="query", @OA\Schema(type="string")),
|
|
* @OA\Parameter(name="limit", in="query", @OA\Schema(type="integer"), description="기본 20"),
|
|
*
|
|
* @OA\Response(
|
|
* response=200,
|
|
* description="검색 성공",
|
|
*
|
|
* @OA\JsonContent(allOf={
|
|
*
|
|
* @OA\Schema(ref="#/components/schemas/ApiResponse"),
|
|
* @OA\Schema(
|
|
*
|
|
* @OA\Property(
|
|
* property="data",
|
|
* type="array",
|
|
*
|
|
* @OA\Items(type="object",
|
|
*
|
|
* @OA\Property(property="id", type="integer", example=101),
|
|
* @OA\Property(property="code", type="string", example="PRD-001"),
|
|
* @OA\Property(property="name", type="string", example="스크린 모듈 KS001"),
|
|
* @OA\Property(property="product_type", type="string", example="PRODUCT"),
|
|
* @OA\Property(property="category_id", type="integer", example=7),
|
|
* @OA\Property(property="is_active", type="integer", example=1)
|
|
* )
|
|
* )
|
|
* )
|
|
* })
|
|
* )
|
|
* )
|
|
*/
|
|
public function productsSearch() {}
|
|
|
|
/**
|
|
* 제품 활성/비활성 토글
|
|
*
|
|
* @OA\Post(
|
|
* path="/api/v1/products/{id}/toggle",
|
|
* tags={"Products"},
|
|
* summary="제품 활성/비활성 토글",
|
|
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
|
|
*
|
|
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
|
|
*
|
|
* @OA\Response(
|
|
* response=200,
|
|
* description="토글 성공",
|
|
*
|
|
* @OA\JsonContent(allOf={
|
|
*
|
|
* @OA\Schema(ref="#/components/schemas/ApiResponse"),
|
|
* @OA\Schema(
|
|
*
|
|
* @OA\Property(property="data", type="object",
|
|
* @OA\Property(property="id", type="integer", example=101),
|
|
* @OA\Property(property="is_active", type="integer", example=0)
|
|
* )
|
|
* )
|
|
* })
|
|
* )
|
|
* )
|
|
* )
|
|
*/
|
|
public function productsToggle() {}
|
|
|
|
/**
|
|
* BOM 항목 목록
|
|
*
|
|
* @OA\Get(
|
|
* path="/api/v1/products/{id}/bom/items",
|
|
* tags={"Products-BOM"},
|
|
* summary="BOM 항목 목록(제품+자재 병합)",
|
|
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
|
|
*
|
|
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
|
|
*
|
|
* @OA\Response(
|
|
* response=200,
|
|
* description="조회 성공",
|
|
*
|
|
* @OA\JsonContent(allOf={
|
|
*
|
|
* @OA\Schema(ref="#/components/schemas/ApiResponse"),
|
|
* @OA\Schema(
|
|
*
|
|
* @OA\Property(property="data", type="array", @OA\Items(ref="#/components/schemas/BomItem"))
|
|
* )
|
|
* })
|
|
* )
|
|
* )
|
|
*/
|
|
public function bomItemsIndex() {}
|
|
|
|
/**
|
|
* BOM 대량 업서트
|
|
*
|
|
* @OA\Post(
|
|
* path="/api/v1/products/{id}/bom/items/bulk",
|
|
* tags={"Products-BOM"},
|
|
* summary="BOM 항목 대량 업서트",
|
|
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
|
|
*
|
|
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
|
|
*
|
|
* @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/BomItemBulkUpsertRequest")),
|
|
*
|
|
* @OA\Response(
|
|
* response=200,
|
|
* description="업서트 성공",
|
|
*
|
|
* @OA\JsonContent(allOf={
|
|
*
|
|
* @OA\Schema(ref="#/components/schemas/ApiResponse"),
|
|
* @OA\Schema(
|
|
*
|
|
* @OA\Property(property="data", type="object",
|
|
* @OA\Property(property="created", type="integer", example=2),
|
|
* @OA\Property(property="updated", type="integer", example=3)
|
|
* )
|
|
* )
|
|
* })
|
|
* )
|
|
* )
|
|
*/
|
|
public function bomItemsBulk() {}
|
|
|
|
/**
|
|
* BOM 단건 수정
|
|
*
|
|
* @OA\Patch(
|
|
* path="/api/v1/products/{id}/bom/items/{item}",
|
|
* tags={"Products-BOM"},
|
|
* summary="BOM 항목 단건 수정",
|
|
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
|
|
*
|
|
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
|
|
* @OA\Parameter(name="item", in="path", required=true, @OA\Schema(type="integer")),
|
|
*
|
|
* @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/BomItemUpdateRequest")),
|
|
*
|
|
* @OA\Response(
|
|
* response=200,
|
|
* description="수정 성공",
|
|
*
|
|
* @OA\JsonContent(allOf={
|
|
*
|
|
* @OA\Schema(ref="#/components/schemas/ApiResponse"),
|
|
* @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/BomItem"))
|
|
* })
|
|
* )
|
|
* )
|
|
*/
|
|
public function bomItemsUpdate() {}
|
|
|
|
/**
|
|
* BOM 단건 삭제
|
|
*
|
|
* @OA\Delete(
|
|
* path="/api/v1/products/{id}/bom/items/{item}",
|
|
* tags={"Products-BOM"},
|
|
* summary="BOM 항목 단건 삭제",
|
|
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
|
|
*
|
|
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
|
|
* @OA\Parameter(name="item", in="path", required=true, @OA\Schema(type="integer")),
|
|
*
|
|
* @OA\Response(response=200, description="삭제 성공", @OA\JsonContent(ref="#/components/schemas/ApiResponse"))
|
|
* )
|
|
*/
|
|
public function bomItemsDestroy() {}
|
|
|
|
/**
|
|
* BOM 정렬 변경
|
|
*
|
|
* @OA\Post(
|
|
* path="/api/v1/products/{id}/bom/items/reorder",
|
|
* tags={"Products-BOM"},
|
|
* summary="BOM 정렬 변경",
|
|
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
|
|
*
|
|
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
|
|
*
|
|
* @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/BomReorderRequest")),
|
|
*
|
|
* @OA\Response(response=200, description="저장 성공", @OA\JsonContent(ref="#/components/schemas/ApiResponse"))
|
|
* )
|
|
*/
|
|
public function bomItemsReorder() {}
|
|
|
|
/**
|
|
* BOM 요약(건수/합계 등)
|
|
*
|
|
* @OA\Get(
|
|
* path="/api/v1/products/{id}/bom/summary",
|
|
* tags={"Products-BOM"},
|
|
* summary="BOM 요약",
|
|
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
|
|
*
|
|
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
|
|
*
|
|
* @OA\Response(
|
|
* response=200,
|
|
* description="요약 성공",
|
|
*
|
|
* @OA\JsonContent(allOf={
|
|
*
|
|
* @OA\Schema(ref="#/components/schemas/ApiResponse"),
|
|
* @OA\Schema(
|
|
*
|
|
* @OA\Property(property="data", type="object",
|
|
* @OA\Property(property="count", type="integer", example=5),
|
|
* @OA\Property(property="count_product", type="integer", example=2),
|
|
* @OA\Property(property="count_material", type="integer", example=3),
|
|
* @OA\Property(property="quantity_sum", type="string", example="7.0000")
|
|
* )
|
|
* )
|
|
* })
|
|
* )
|
|
* )
|
|
*/
|
|
public function bomSummary() {}
|
|
|
|
/**
|
|
* BOM 유효성 검사
|
|
*
|
|
* @OA\Get(
|
|
* path="/api/v1/products/{id}/bom/validate",
|
|
* tags={"Products-BOM"},
|
|
* summary="BOM 유효성 검사",
|
|
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
|
|
*
|
|
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer")),
|
|
*
|
|
* @OA\Response(
|
|
* response=200,
|
|
* description="검증 결과",
|
|
*
|
|
* @OA\JsonContent(allOf={
|
|
*
|
|
* @OA\Schema(ref="#/components/schemas/ApiResponse"),
|
|
* @OA\Schema(
|
|
*
|
|
* @OA\Property(property="data", type="object",
|
|
* @OA\Property(property="valid", type="boolean", example=false),
|
|
* @OA\Property(property="errors", type="array",
|
|
*
|
|
* @OA\Items(type="object",
|
|
*
|
|
* @OA\Property(property="id", type="integer", example=11),
|
|
* @OA\Property(property="error", type="string", example="DUPLICATE_ITEM")
|
|
* )
|
|
* )
|
|
* )
|
|
* )
|
|
* })
|
|
* )
|
|
* )
|
|
*/
|
|
public function bomValidate() {}
|
|
|
|
/**
|
|
* BOM 전체 교체 저장
|
|
* 프론트에서 보낸 현재 BOM 상태로 기존 구성을 모두 삭제 후 재등록합니다.
|
|
*
|
|
* @OA\Post(
|
|
* path="/api/v1/products/{id}/bom",
|
|
* tags={"Products-BOM"},
|
|
* summary="BOM 구성 저장(구성 전체 교체)",
|
|
* description="기존 BOM을 모두 삭제하고, 전달된 categories/items 기준으로 다시 저장합니다.",
|
|
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
|
|
*
|
|
* @OA\Parameter(
|
|
* name="id",
|
|
* in="path",
|
|
* required=true,
|
|
* description="상위(모델) 제품 ID",
|
|
*
|
|
* @OA\Schema(type="integer", example=123)
|
|
* ),
|
|
*
|
|
* @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/BomReplaceRequest")),
|
|
*
|
|
* @OA\Response(
|
|
* response=200,
|
|
* description="저장 성공",
|
|
*
|
|
* @OA\JsonContent(
|
|
* allOf={
|
|
*
|
|
* @OA\Schema(ref="#/components/schemas/ApiResponse"),
|
|
* @OA\Schema(
|
|
*
|
|
* @OA\Property(property="message", type="string", example="BOM 항목이 저장되었습니다."),
|
|
* @OA\Property(property="data", ref="#/components/schemas/BomReplaceResult")
|
|
* )
|
|
* }
|
|
* )
|
|
* ),
|
|
*
|
|
* @OA\Response(response=400, description="잘못된 요청", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
|
|
* @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
|
|
* @OA\Response(response=403, description="권한 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
|
|
* @OA\Response(response=404, description="존재하지 않는 URI 또는 데이터", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
|
|
* @OA\Response(response=422, description="검증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
|
|
* @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
|
|
* )
|
|
*/
|
|
public function bomReplace() {}
|
|
|
|
/**
|
|
* 제품별 사용 중인 BOM 카테고리 목록
|
|
*
|
|
* @OA\Get(
|
|
* path="/api/v1/products/{id}/bom/categories",
|
|
* tags={"Products-BOM"},
|
|
* summary="해당 제품에서 사용 중인 BOM 카테고리 목록",
|
|
* description="product_components 테이블에서 해당 제품(parent_product_id)의 카테고리(id/name)를 집계하여 반환합니다.",
|
|
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
|
|
*
|
|
* @OA\Parameter(
|
|
* name="id",
|
|
* in="path",
|
|
* required=true,
|
|
* description="상위(모델) 제품 ID",
|
|
*
|
|
* @OA\Schema(type="integer", example=123)
|
|
* ),
|
|
*
|
|
* @OA\Response(
|
|
* response=200,
|
|
* description="조회 성공",
|
|
*
|
|
* @OA\JsonContent(
|
|
* allOf={
|
|
*
|
|
* @OA\Schema(ref="#/components/schemas/ApiResponse"),
|
|
* @OA\Schema(
|
|
*
|
|
* @OA\Property(
|
|
* property="data",
|
|
* type="array",
|
|
*
|
|
* @OA\Items(ref="#/components/schemas/BomCategoryStat")
|
|
* )
|
|
* )
|
|
* },
|
|
* example={
|
|
* "success": true,
|
|
* "message": "조회 성공",
|
|
* "data": {
|
|
* {"category_id":1, "category_name":"기본", "count":5},
|
|
* {"category_id":2, "category_name":"옵션", "count":3}
|
|
* }
|
|
* }
|
|
* )
|
|
* ),
|
|
*
|
|
* @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
|
|
* @OA\Response(response=403, description="권한 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
|
|
* )
|
|
*/
|
|
public function bomCategoriesForProduct() {}
|
|
|
|
/**
|
|
* 테넌트 전역 카테고리 추천(히스토리 기반)
|
|
*
|
|
* @OA\Get(
|
|
* path="/api/v1/products/bom/categories",
|
|
* tags={"Products-BOM"},
|
|
* summary="자주 사용된 BOM 카테고리 추천",
|
|
* description="테넌트 전체 product_components 데이터를 집계해 카테고리 사용 빈도가 높은 순으로 반환합니다. q로 부분 검색 가능합니다.",
|
|
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
|
|
*
|
|
* @OA\Parameter(
|
|
* name="q",
|
|
* in="query",
|
|
* required=false,
|
|
* description="카테고리명 부분 검색",
|
|
*
|
|
* @OA\Schema(type="string", example="기")
|
|
* ),
|
|
*
|
|
* @OA\Parameter(
|
|
* name="limit",
|
|
* in="query",
|
|
* required=false,
|
|
* description="최대 항목 수(기본 20)",
|
|
*
|
|
* @OA\Schema(type="integer", example=20)
|
|
* ),
|
|
*
|
|
* @OA\Response(
|
|
* response=200,
|
|
* description="조회 성공",
|
|
*
|
|
* @OA\JsonContent(
|
|
* allOf={
|
|
*
|
|
* @OA\Schema(ref="#/components/schemas/ApiResponse"),
|
|
* @OA\Schema(
|
|
*
|
|
* @OA\Property(
|
|
* property="data",
|
|
* type="array",
|
|
*
|
|
* @OA\Items(ref="#/components/schemas/BomCategoryStat")
|
|
* )
|
|
* )
|
|
* },
|
|
* example={
|
|
* "success": true,
|
|
* "message": "조회 성공",
|
|
* "data": {
|
|
* {"category_id":1, "category_name":"기본", "count":127},
|
|
* {"category_id":2, "category_name":"옵션", "count":88},
|
|
* {"category_id":null, "category_name":"패키지", "count":12}
|
|
* }
|
|
* }
|
|
* )
|
|
* ),
|
|
*
|
|
* @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
|
|
* @OA\Response(response=403, description="권한 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
|
|
* )
|
|
*/
|
|
public function bomCategoriesSuggest() {}
|
|
|
|
/**
|
|
* 제품 BOM 트리 조회
|
|
*
|
|
* @OA\Get(
|
|
* path="/api/v1/products/{id}/bom/tree",
|
|
* tags={"Products-BOM"},
|
|
* summary="제품 BOM 트리 조회(재귀)",
|
|
* description="특정 제품의 하위 구성(제품/자재)을 재귀적으로 트리 형태로 반환합니다. depth로 최대 깊이를 제한합니다(기본 10).",
|
|
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
|
|
*
|
|
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer", minimum=1), description="제품 ID"),
|
|
* @OA\Parameter(
|
|
* name="depth",
|
|
* in="query",
|
|
* required=false,
|
|
* description="재귀 깊이(루트=0). 기본 10",
|
|
*
|
|
* @OA\Schema(type="integer", minimum=0, maximum=50, default=10, example=5)
|
|
* ),
|
|
*
|
|
* @OA\Response(
|
|
* response=200,
|
|
* description="조회 성공",
|
|
*
|
|
* @OA\JsonContent(
|
|
* allOf={
|
|
*
|
|
* @OA\Schema(ref="#/components/schemas/ApiResponse"),
|
|
* @OA\Schema(
|
|
*
|
|
* @OA\Property(
|
|
* property="data",
|
|
* type="object",
|
|
* @OA\Property(
|
|
* property="product",
|
|
* type="object",
|
|
* @OA\Property(property="id", type="integer"),
|
|
* @OA\Property(property="code", type="string"),
|
|
* @OA\Property(property="name", type="string"),
|
|
* @OA\Property(property="unit", type="string", nullable=true),
|
|
* @OA\Property(property="category_id", type="integer", nullable=true),
|
|
* @OA\Property(property="product_type", type="string")
|
|
* ),
|
|
* @OA\Property(property="tree", ref="#/components/schemas/BomTreeNode")
|
|
* )
|
|
* )
|
|
* }
|
|
* )
|
|
* ),
|
|
*
|
|
* @OA\Response(response=400, description="잘못된 요청", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
|
|
* @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
|
|
* @OA\Response(response=404, description="대상 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
|
|
* @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
|
|
* )
|
|
*/
|
|
public function bomTree() {}
|
|
}
|