hskwon
681acb0459
- Settings 그룹 API 문서 추가 * CommonController에 공통 코드 관리 CRUD 문서 작성 * TenantFieldSettingController에 필드 설정 관리 문서 작성 * "Settings - Common Codes", "Settings - Fields" 태그로 그룹화 - Products/Materials 통합 문서 업데이트 * MaterialController에 "Products & Materials - Materials" 태그 적용 * Products 그룹 내 자재 관리로 통합 구성 - Files API 완전한 Swagger 문서 추가 * FileController에 누락되었던 전체 API 문서 작성 * 파일 업로드/조회/삭제/정보조회 모든 엔드포인트 문서화 * "Files" 태그로 독립적인 그룹 구성 - 새로운 에러 메시지 응답 예제 추가 * Materials 관련: 중복 코드, 사용 중 삭제 불가, 정보 없음 * Settings 관련: 중복 공통 코드, 필드 설정 없음, 유효하지 않은 타입 * Files 관련: 업로드 실패, 파일 크기 초과, 지원하지 않는 형식 - 제거된 BOM 라우트 문서 정리 * 사용하지 않는 BomApi.php 파일 삭제 * 기본 BOM 시스템(/v1/boms) 완전 제거로 문서 정합성 확보 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
279 lines
11 KiB
PHP
279 lines
11 KiB
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'));
|
|
}
|
|
}
|