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 준수 완료

app/Http/Controllers/Api/V1/MaterialController.php

@@ -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'));
     }
-}
+}

app/Http/Requests/Material/MaterialStoreRequest.php

@@ -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',
+        ];
+    }
+}

app/Http/Requests/Material/MaterialUpdateRequest.php

@@ -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',
+        ];
+    }
+}

app/Swagger/v1/MaterialApi.php

@@ -151,16 +151,16 @@ class MaterialApi
 {
     /**
      * @OA\Get(
-     *   path="/api/v1/materials",
+     *   path="/api/v1/products/materials",
      *   summary="자재 목록 조회",
      *   description="자재 목록을 페이징으로 반환합니다. (q로 코드/이름/태그 검색, category로 분류 필터)",
      *   tags={"Material"},
      *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
      *
+     *   @OA\Parameter(ref="#/components/parameters/Page"),
+     *   @OA\Parameter(ref="#/components/parameters/Size"),
      *   @OA\Parameter(name="q", in="query", required=false, @OA\Schema(type="string"), description="검색어(이름/코드/태그 등)"),
      *   @OA\Parameter(name="category", in="query", required=false, @OA\Schema(type="integer"), description="카테고리 ID"),
-     *   @OA\Parameter(name="page", in="query", required=false, @OA\Schema(type="integer", example=1)),
-     *   @OA\Parameter(name="per_page", in="query", required=false, @OA\Schema(type="integer", example=20)),
      *
      *   @OA\Response(
      *     response=200, description="자재 목록 조회 성공",
@@ -187,7 +187,7 @@ public function index() {}
 
     /**
      * @OA\Post(
-     *   path="/api/v1/materials",
+     *   path="/api/v1/products/materials",
      *   summary="자재 등록",
      *   description="자재를 등록합니다. item_name/specification은 name+attributes를 기반으로 서버에서 자동 생성됩니다.",
      *   tags={"Material"},
@@ -214,7 +214,7 @@ public function store() {}
 
     /**
      * @OA\Get(
-     *   path="/api/v1/materials/{id}",
+     *   path="/api/v1/products/materials/{id}",
      *   summary="자재 단건 조회",
      *   tags={"Material"},
      *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
@@ -240,7 +240,7 @@ public function show() {}
 
     /**
      * @OA\Put(
-     *   path="/api/v1/materials/{id}",
+     *   path="/api/v1/products/materials/{id}",
      *   summary="자재 수정(전체)",
      *   description="자재를 수정합니다. name/attributes 변경 시 item_name/specification이 서버에서 재계산됩니다.",
      *   tags={"Material"},
@@ -270,7 +270,7 @@ public function updatePut() {}
 
     /**
      * @OA\Patch(
-     *   path="/api/v1/materials/{id}",
+     *   path="/api/v1/products/materials/{id}",
      *   summary="자재 부분 수정",
      *   description="자재의 일부 필드를 수정합니다. name/attributes 변경 시 item_name/specification이 서버에서 재계산됩니다.",
      *   tags={"Material"},
@@ -300,7 +300,7 @@ public function updatePatch() {}
 
     /**
      * @OA\Delete(
-     *   path="/api/v1/materials/{id}",
+     *   path="/api/v1/products/materials/{id}",
      *   summary="자재 삭제",
      *   description="자재를 소프트 삭제합니다.",
      *   tags={"Material"},

lang/ko/message.php

@@ -84,11 +84,11 @@
     ],
 
     // 자재 관리 (Products & Materials 통합)
-    'materials' => [
+    'material' => [
+        'fetched' => '자재를 조회했습니다.',
         'created' => '자재가 등록되었습니다.',
         'updated' => '자재가 수정되었습니다.',
         'deleted' => '자재가 삭제되었습니다.',
-        'fetched' => '자재 목록을 조회했습니다.',
     ],
 
     // 파일 관리