feat: MaterialApi.php Swagger 점검 및 개선 (Phase 3-2)
- MaterialStoreRequest.php 생성 (검증 로직 분리) - MaterialUpdateRequest.php 생성 (검증 로직 분리) - MaterialApi.php 경로 수정 (/api/v1/products/materials) - MaterialController.php Swagger 주석 제거, FormRequest 적용 - lang/ko/message.php material 메시지 키 추가 - SAM API Development Rules 준수 완료
This commit is contained in:
@@ -4,323 +4,47 @@
|
||||
|
||||
use App\Helpers\ApiResponse;
|
||||
use App\Http\Controllers\Controller;
|
||||
use App\Http\Requests\Material\MaterialStoreRequest;
|
||||
use App\Http\Requests\Material\MaterialUpdateRequest;
|
||||
use App\Services\MaterialService;
|
||||
use Illuminate\Http\Request;
|
||||
|
||||
/**
|
||||
* @OA\Tag(
|
||||
* name="Products & Materials - Materials",
|
||||
* description="자재 관리 API (Products 그룹 내 통합)"
|
||||
* )
|
||||
*/
|
||||
class MaterialController extends Controller
|
||||
{
|
||||
public function __construct(private MaterialService $service) {}
|
||||
|
||||
/**
|
||||
* @OA\Get(
|
||||
* path="/api/v1/products/materials",
|
||||
* summary="자재 목록 조회",
|
||||
* description="테넌트의 자재 목록을 조회합니다. (Products & Materials 통합 관리)",
|
||||
* tags={"Products & Materials - Materials"},
|
||||
* security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
|
||||
*
|
||||
* @OA\Parameter(
|
||||
* name="page",
|
||||
* in="query",
|
||||
* description="페이지 번호",
|
||||
*
|
||||
* @OA\Schema(type="integer", example=1)
|
||||
* ),
|
||||
*
|
||||
* @OA\Parameter(
|
||||
* name="size",
|
||||
* in="query",
|
||||
* description="페이지 크기",
|
||||
*
|
||||
* @OA\Schema(type="integer", example=10)
|
||||
* ),
|
||||
*
|
||||
* @OA\Parameter(
|
||||
* name="q",
|
||||
* in="query",
|
||||
* description="검색어 (자재명, 코드)",
|
||||
*
|
||||
* @OA\Schema(type="string", example="스틸")
|
||||
* ),
|
||||
*
|
||||
* @OA\Response(
|
||||
* response=200,
|
||||
* description="자재 목록 조회 성공",
|
||||
*
|
||||
* @OA\JsonContent(
|
||||
* type="object",
|
||||
*
|
||||
* @OA\Property(property="success", type="boolean", example=true),
|
||||
* @OA\Property(property="message", type="string", example="조회 성공"),
|
||||
* @OA\Property(
|
||||
* property="data",
|
||||
* type="object",
|
||||
* @OA\Property(property="current_page", type="integer", example=1),
|
||||
* @OA\Property(property="per_page", type="integer", example=10),
|
||||
* @OA\Property(property="total", type="integer", example=25),
|
||||
* @OA\Property(
|
||||
* property="data",
|
||||
* type="array",
|
||||
*
|
||||
* @OA\Items(
|
||||
* type="object",
|
||||
*
|
||||
* @OA\Property(property="id", type="integer", example=1),
|
||||
* @OA\Property(property="material_code", type="string", example="MAT001"),
|
||||
* @OA\Property(property="name", type="string", example="스틸파이프 10mm"),
|
||||
* @OA\Property(property="specification", type="string", example="직경 10mm, 두께 2mm"),
|
||||
* @OA\Property(property="unit", type="string", example="개"),
|
||||
* @OA\Property(property="is_active", type="boolean", example=true)
|
||||
* )
|
||||
* )
|
||||
* )
|
||||
* )
|
||||
* )
|
||||
* )
|
||||
*/
|
||||
public function index(Request $request)
|
||||
{
|
||||
return ApiResponse::handle(function () use ($request) {
|
||||
return $this->service->getMaterials($request->all());
|
||||
}, __('message.materials.fetched'));
|
||||
}, __('message.material.fetched'));
|
||||
}
|
||||
|
||||
/**
|
||||
* @OA\Post(
|
||||
* path="/api/v1/products/materials",
|
||||
* summary="자재 등록",
|
||||
* description="새로운 자재를 등록합니다.",
|
||||
* tags={"Products & Materials - Materials"},
|
||||
* security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
|
||||
*
|
||||
* @OA\RequestBody(
|
||||
* required=true,
|
||||
*
|
||||
* @OA\JsonContent(
|
||||
* type="object",
|
||||
*
|
||||
* @OA\Property(property="material_code", type="string", example="MAT002"),
|
||||
* @OA\Property(property="name", type="string", example="알루미늄 프로파일"),
|
||||
* @OA\Property(property="specification", type="string", example="20x20x2mm"),
|
||||
* @OA\Property(property="unit", type="string", example="m"),
|
||||
* @OA\Property(property="description", type="string", example="알루미늄 프로파일 20x20")
|
||||
* )
|
||||
* ),
|
||||
*
|
||||
* @OA\Response(
|
||||
* response=201,
|
||||
* description="자재 등록 성공",
|
||||
*
|
||||
* @OA\JsonContent(
|
||||
* type="object",
|
||||
*
|
||||
* @OA\Property(property="success", type="boolean", example=true),
|
||||
* @OA\Property(property="message", type="string", example="자재가 등록되었습니다."),
|
||||
* @OA\Property(
|
||||
* property="data",
|
||||
* type="object",
|
||||
* @OA\Property(property="id", type="integer", example=2)
|
||||
* )
|
||||
* )
|
||||
* ),
|
||||
*
|
||||
* @OA\Response(
|
||||
* response=409,
|
||||
* description="중복된 자재 코드",
|
||||
*
|
||||
* @OA\JsonContent(
|
||||
* type="object",
|
||||
*
|
||||
* @OA\Property(property="success", type="boolean", example=false),
|
||||
* @OA\Property(property="message", type="string", example="중복된 자재 코드입니다.")
|
||||
* )
|
||||
* ),
|
||||
*
|
||||
* @OA\Response(
|
||||
* response=422,
|
||||
* description="유효성 검사 실패",
|
||||
*
|
||||
* @OA\JsonContent(ref="#/components/schemas/ErrorResponse")
|
||||
* )
|
||||
* )
|
||||
*/
|
||||
public function store(Request $request)
|
||||
public function store(MaterialStoreRequest $request)
|
||||
{
|
||||
return ApiResponse::handle(function () use ($request) {
|
||||
return $this->service->setMaterial($request->all());
|
||||
}, __('message.materials.created'));
|
||||
return $this->service->setMaterial($request->validated());
|
||||
}, __('message.material.created'));
|
||||
}
|
||||
|
||||
/**
|
||||
* @OA\Get(
|
||||
* path="/api/v1/products/materials/{id}",
|
||||
* summary="자재 상세 조회",
|
||||
* description="특정 자재의 상세 정보를 조회합니다.",
|
||||
* tags={"Products & Materials - Materials"},
|
||||
* security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
|
||||
*
|
||||
* @OA\Parameter(
|
||||
* name="id",
|
||||
* in="path",
|
||||
* required=true,
|
||||
* description="자재 ID",
|
||||
*
|
||||
* @OA\Schema(type="integer", example=1)
|
||||
* ),
|
||||
*
|
||||
* @OA\Response(
|
||||
* response=200,
|
||||
* description="자재 상세 조회 성공",
|
||||
*
|
||||
* @OA\JsonContent(
|
||||
* type="object",
|
||||
*
|
||||
* @OA\Property(property="success", type="boolean", example=true),
|
||||
* @OA\Property(property="message", type="string", example="조회 성공"),
|
||||
* @OA\Property(
|
||||
* property="data",
|
||||
* type="object",
|
||||
* @OA\Property(property="id", type="integer", example=1),
|
||||
* @OA\Property(property="material_code", type="string", example="MAT001"),
|
||||
* @OA\Property(property="name", type="string", example="스틸파이프 10mm"),
|
||||
* @OA\Property(property="specification", type="string", example="직경 10mm, 두께 2mm"),
|
||||
* @OA\Property(property="unit", type="string", example="개"),
|
||||
* @OA\Property(property="description", type="string", example="스틸 파이프"),
|
||||
* @OA\Property(property="is_active", type="boolean", example=true),
|
||||
* @OA\Property(property="created_at", type="string", format="date-time"),
|
||||
* @OA\Property(property="updated_at", type="string", format="date-time")
|
||||
* )
|
||||
* )
|
||||
* ),
|
||||
*
|
||||
* @OA\Response(
|
||||
* response=404,
|
||||
* description="자재 정보를 찾을 수 없음",
|
||||
*
|
||||
* @OA\JsonContent(ref="#/components/schemas/ErrorResponse")
|
||||
* )
|
||||
* )
|
||||
*/
|
||||
public function show(Request $request, int $id)
|
||||
public function show(int $id)
|
||||
{
|
||||
return ApiResponse::handle(function () use ($id) {
|
||||
return $this->service->getMaterial($id);
|
||||
}, __('message.fetched'));
|
||||
}, __('message.material.fetched'));
|
||||
}
|
||||
|
||||
/**
|
||||
* @OA\Patch(
|
||||
* path="/api/v1/products/materials/{id}",
|
||||
* summary="자재 수정",
|
||||
* description="기존 자재 정보를 수정합니다.",
|
||||
* tags={"Products & Materials - Materials"},
|
||||
* security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
|
||||
*
|
||||
* @OA\Parameter(
|
||||
* name="id",
|
||||
* in="path",
|
||||
* required=true,
|
||||
* description="자재 ID",
|
||||
*
|
||||
* @OA\Schema(type="integer", example=1)
|
||||
* ),
|
||||
*
|
||||
* @OA\RequestBody(
|
||||
* required=true,
|
||||
*
|
||||
* @OA\JsonContent(
|
||||
* type="object",
|
||||
*
|
||||
* @OA\Property(property="name", type="string", example="스틸파이프 12mm"),
|
||||
* @OA\Property(property="specification", type="string", example="직경 12mm, 두께 2mm"),
|
||||
* @OA\Property(property="description", type="string", example="수정된 스틸 파이프")
|
||||
* )
|
||||
* ),
|
||||
*
|
||||
* @OA\Response(
|
||||
* response=200,
|
||||
* description="자재 수정 성공",
|
||||
*
|
||||
* @OA\JsonContent(
|
||||
* type="object",
|
||||
*
|
||||
* @OA\Property(property="success", type="boolean", example=true),
|
||||
* @OA\Property(property="message", type="string", example="자재가 수정되었습니다.")
|
||||
* )
|
||||
* )
|
||||
* )
|
||||
*/
|
||||
public function update(Request $request, int $id)
|
||||
public function update(MaterialUpdateRequest $request, int $id)
|
||||
{
|
||||
return ApiResponse::handle(function () use ($request, $id) {
|
||||
return $this->service->updateMaterial($id, $request->all());
|
||||
}, __('message.materials.updated'));
|
||||
return $this->service->updateMaterial($id, $request->validated());
|
||||
}, __('message.material.updated'));
|
||||
}
|
||||
|
||||
/**
|
||||
* @OA\Delete(
|
||||
* path="/api/v1/products/materials/{id}",
|
||||
* summary="자재 삭제",
|
||||
* description="자재를 소프트 삭제합니다. 사용 중인 자재는 삭제할 수 없습니다.",
|
||||
* tags={"Products & Materials - Materials"},
|
||||
* security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
|
||||
*
|
||||
* @OA\Parameter(
|
||||
* name="id",
|
||||
* in="path",
|
||||
* required=true,
|
||||
* description="자재 ID",
|
||||
*
|
||||
* @OA\Schema(type="integer", example=1)
|
||||
* ),
|
||||
*
|
||||
* @OA\Response(
|
||||
* response=200,
|
||||
* description="자재 삭제 성공",
|
||||
*
|
||||
* @OA\JsonContent(
|
||||
* type="object",
|
||||
*
|
||||
* @OA\Property(property="success", type="boolean", example=true),
|
||||
* @OA\Property(property="message", type="string", example="자재가 삭제되었습니다.")
|
||||
* )
|
||||
* ),
|
||||
*
|
||||
* @OA\Response(
|
||||
* response=409,
|
||||
* description="사용 중인 자재는 삭제 불가",
|
||||
*
|
||||
* @OA\JsonContent(
|
||||
* type="object",
|
||||
*
|
||||
* @OA\Property(property="success", type="boolean", example=false),
|
||||
* @OA\Property(property="message", type="string", example="사용 중인 자재는 삭제할 수 없습니다.")
|
||||
* )
|
||||
* ),
|
||||
*
|
||||
* @OA\Response(
|
||||
* response=404,
|
||||
* description="자재 정보를 찾을 수 없음",
|
||||
*
|
||||
* @OA\JsonContent(
|
||||
* type="object",
|
||||
*
|
||||
* @OA\Property(property="success", type="boolean", example=false),
|
||||
* @OA\Property(property="message", type="string", example="자재 정보를 찾을 수 없습니다.")
|
||||
* )
|
||||
* )
|
||||
* )
|
||||
*/
|
||||
public function destroy(Request $request, int $id)
|
||||
public function destroy(int $id)
|
||||
{
|
||||
return ApiResponse::handle(function () use ($id) {
|
||||
return $this->service->destroyMaterial($id);
|
||||
}, __('message.materials.deleted'));
|
||||
}, __('message.material.deleted'));
|
||||
}
|
||||
}
|
||||
}
|
||||
32
app/Http/Requests/Material/MaterialStoreRequest.php
Normal file
32
app/Http/Requests/Material/MaterialStoreRequest.php
Normal file
@@ -0,0 +1,32 @@
|
||||
<?php
|
||||
|
||||
namespace App\Http\Requests\Material;
|
||||
|
||||
use Illuminate\Foundation\Http\FormRequest;
|
||||
|
||||
class MaterialStoreRequest extends FormRequest
|
||||
{
|
||||
public function authorize(): bool
|
||||
{
|
||||
return true;
|
||||
}
|
||||
|
||||
public function rules(): array
|
||||
{
|
||||
return [
|
||||
'category_id' => 'nullable|integer',
|
||||
'name' => 'required|string|max:100',
|
||||
'unit' => 'required|string|max:20',
|
||||
'is_inspection' => 'nullable|in:Y,N',
|
||||
'search_tag' => 'nullable|string|max:255',
|
||||
'remarks' => 'nullable|string|max:500',
|
||||
'attributes' => 'nullable|array',
|
||||
'attributes.*.label' => 'required|string|max:50',
|
||||
'attributes.*.value' => 'required|string|max:100',
|
||||
'attributes.*.unit' => 'nullable|string|max:20',
|
||||
'options' => 'nullable|array',
|
||||
'material_code' => 'nullable|string|max:30',
|
||||
'specification' => 'nullable|string|max:255',
|
||||
];
|
||||
}
|
||||
}
|
||||
32
app/Http/Requests/Material/MaterialUpdateRequest.php
Normal file
32
app/Http/Requests/Material/MaterialUpdateRequest.php
Normal file
@@ -0,0 +1,32 @@
|
||||
<?php
|
||||
|
||||
namespace App\Http\Requests\Material;
|
||||
|
||||
use Illuminate\Foundation\Http\FormRequest;
|
||||
|
||||
class MaterialUpdateRequest extends FormRequest
|
||||
{
|
||||
public function authorize(): bool
|
||||
{
|
||||
return true;
|
||||
}
|
||||
|
||||
public function rules(): array
|
||||
{
|
||||
return [
|
||||
'category_id' => 'nullable|integer',
|
||||
'name' => 'sometimes|string|max:100',
|
||||
'unit' => 'sometimes|string|max:20',
|
||||
'is_inspection' => 'nullable|in:Y,N',
|
||||
'search_tag' => 'nullable|string|max:255',
|
||||
'remarks' => 'nullable|string|max:500',
|
||||
'attributes' => 'nullable|array',
|
||||
'attributes.*.label' => 'required|string|max:50',
|
||||
'attributes.*.value' => 'required|string|max:100',
|
||||
'attributes.*.unit' => 'nullable|string|max:20',
|
||||
'options' => 'nullable|array',
|
||||
'material_code' => 'nullable|string|max:30',
|
||||
'specification' => 'nullable|string|max:255',
|
||||
];
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user