sam-api/app/Http/Controllers/Api/V1/MaterialController.php

<?php

namespace App\Http\Controllers\Api\V1;

use Illuminate\Http\Request;
use App\Http\Controllers\Controller;
use App\Services\MaterialService;
use App\Helpers\ApiResponse;

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

    /**
     * @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)
    {
        return ApiResponse::handle(function () use ($request) {
            return $this->service->setMaterial($request->all());
        }, __('message.materials.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)
    {
        return ApiResponse::handle(function () use ($id) {
            return $this->service->getMaterial($id);
        }, __('message.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)
    {
        return ApiResponse::handle(function () use ($request, $id) {
            return $this->service->updateMaterial($id, $request->all());
        }, __('message.materials.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)
    {
        return ApiResponse::handle(function () use ($id) {
            return $this->service->destroyMaterial($id);
        }, __('message.materials.deleted'));
    }
}