sam-api/docs/swagger/SWAGGER_PHASE3_1_PRODUCT.md

# Product API Swagger 점검 및 개선 (Phase 3-1)

**날짜:** 2025-11-07
**작업자:** Claude Code
**이슈:** Phase 3-1: ProductApi.php Swagger 점검 및 개선

## 📋 변경 개요

ProductApi.php Swagger 문서 점검 후, SAM API Development Rules에 따라 FormRequest 적용 및 i18n 메시지 키 적용

## 🔧 사용된 도구

### MCP 서버
- Sequential Thinking: 복잡한 분석 및 검증 로직 수행
- Native Tools: Read, Write, Edit, Bash, Glob 등 파일 작업

### SuperClaude 페르소나
- backend-architect: API 구조 분석 및 설계 검증
- code-workflow: 체계적 코드 수정 프로세스 적용

### 네이티브 도구
- Read: 9회 (파일 내용 확인)
- Write: 2회 (FormRequest 파일 생성)
- Edit: 2회 (Controller, message.php 수정)
- Bash: 7회 (파일 검색, 문법 체크)
- Glob: 3회 (패턴 기반 파일 검색)

## 📁 수정된 파일

### 1. `app/Http/Requests/Product/ProductStoreRequest.php` (신규 생성)
**목적:** 제품 생성 시 입력 검증을 FormRequest로 분리

**주요 내용:**
- required: code, name, category_id, product_type
- nullable: attributes, description, is_sellable, is_purchasable, is_producible, is_active
- 검증 규칙: Service에서 Controller로 이동 (SAM 규칙 준수)

### 2. `app/Http/Requests/Product/ProductUpdateRequest.php` (신규 생성)
**목적:** 제품 수정 시 입력 검증을 FormRequest로 분리

**주요 내용:**
- sometimes 규칙 적용 (부분 업데이트 지원)
- nullable 필드 동일하게 유지

### 3. `app/Http/Controllers/Api/V1/ProductController.php` (수정)
**변경 전:**
```php
public function store(Request $request)
{
    return ApiResponse::handle(function () use ($request) {
        return $this->service->store($request->all());
    }, '제품 생성');
}
```

**변경 후:**
```php
public function store(ProductStoreRequest $request)
{
    return ApiResponse::handle(function () use ($request) {
        return $this->service->store($request->validated());
    }, __('message.product.created'));
}
```

**변경 이유:**
- FormRequest 적용으로 검증 로직 분리 (SAM 규칙)
- `$request->all()` → `$request->validated()` (보안 강화)
- 하드코딩된 한글 메시지 → i18n 키 사용

**적용된 메서드:**
- getCategory(): `__('message.product.category_fetched')`
- index(): `__('message.product.fetched')`
- store(): `__('message.product.created')`
- show(): `__('message.product.fetched')`
- update(): `__('message.product.updated')`
- destroy(): `__('message.product.deleted')`
- search(): `__('message.product.searched')`
- toggle(): `__('message.product.toggled')`

### 4. `lang/ko/message.php` (수정)
**변경 전:**
```php
'product' => [
    'created' => '제품이 등록되었습니다.',
    'updated' => '제품이 수정되었습니다.',
    'deleted' => '제품이 삭제되었습니다.',
    'toggled' => '제품 상태가 변경되었습니다.',
],
```

**변경 후:**
```php
'product' => [
    'fetched' => '제품을 조회했습니다.',
    'category_fetched' => '제품 카테고리를 조회했습니다.',
    'created' => '제품이 등록되었습니다.',
    'updated' => '제품이 수정되었습니다.',
    'deleted' => '제품이 삭제되었습니다.',
    'toggled' => '제품 상태가 변경되었습니다.',
    'searched' => '제품을 검색했습니다.',
],
```

**변경 이유:** Controller의 모든 메서드에 대응하는 i18n 키 추가

## 🔍 분석 결과

### BOM API 확인
- ✅ ProductBomItemController 존재 확인
- ✅ Route 정의 확인 (/api/v1/products/{id}/bom/*)
- ✅ ProductBomService 존재
- ✅ Swagger 정의 (ProductApi.php)와 실제 구현 일치

### 스키마 확인
- ✅ ProductExtraSchemas.php 존재
- ✅ Product, ProductPagination, ProductCreateRequest, ProductUpdateRequest 스키마 정의됨
- ✅ BomItem, BomItemBulkUpsertRequest, BomItemUpdateRequest, BomReorderRequest 스키마 정의됨
- ✅ BomTreeNode, BomCategoryStat, BomReplaceRequest 스키마 정의됨 (ProductApi.php 내부)

### SAM API Rules 준수 확인

#### ✅ 준수 항목
1. **FormRequest 사용**
   - ProductStoreRequest, ProductUpdateRequest 생성
   - Controller에서 타입 힌트 적용
   - `$request->validated()` 사용

2. **i18n 메시지 키 사용**
   - 모든 하드코딩된 한글 메시지 제거
   - `__('message.product.xxx')` 형식 적용

3. **Service-First 패턴**
   - 비즈니스 로직은 Service에 유지
   - Controller는 DI + ApiResponse::handle()만 사용

4. **Multi-tenancy**
   - ProductService에서 BelongsToTenant 적용 확인
   - tenant_id 필터링 확인

#### ⚠️ 개선 여부 결정 필요
1. **검증 로직 중복**
   - ProductService에 Validator::make() 로직 존재
   - FormRequest에서 기본 검증, Service에서 비즈니스 검증 (code 중복 체크 등)
   - **현재 상태:** 유지 (비즈니스 검증은 Service에서 처리하는 것이 적절)

## ✅ 테스트 체크리스트

- [x] PHP 문법 체크 (php -l)
- [x] ProductStoreRequest 문법 확인
- [x] ProductUpdateRequest 문법 확인
- [x] ProductController 문법 확인
- [x] message.php 문법 확인
- [ ] Swagger 재생성 (`php artisan l5-swagger:generate`)
- [ ] Swagger UI 확인 (http://api.sam.kr/api-docs/index.html)
- [ ] 실제 API 호출 테스트
  - [ ] GET /api/v1/product/category
  - [ ] GET /api/v1/products
  - [ ] POST /api/v1/products (FormRequest 검증 확인)
  - [ ] GET /api/v1/products/{id}
  - [ ] PATCH /api/v1/products/{id} (FormRequest 검증 확인)
  - [ ] DELETE /api/v1/products/{id}
  - [ ] GET /api/v1/products/search
  - [ ] POST /api/v1/products/{id}/toggle

## ⚠️ 배포 시 주의사항

1. **FormRequest 적용으로 검증 로직 변경**
   - 기존: Service에서 모든 검증
   - 변경 후: FormRequest(기본 검증) + Service(비즈니스 검증)
   - 영향: 검증 에러 응답 형식 동일 (422 Unprocessable Entity)

2. **i18n 메시지 변경**
   - 기존: 하드코딩된 한글 메시지
   - 변경 후: i18n 키 사용
   - 영향: 응답 메시지 내용 약간 변경 (의미는 동일)

3. **BOM API 미수정**
   - ProductBomItemController는 별도 Controller
   - 현재 작업에서는 제외
   - Phase 3-1 완료 후 별도 점검 필요

## 🔗 관련 문서

- `CLAUDE.md` - SAM 프로젝트 가이드
- `SWAGGER_AUDIT.md` - Swagger 전체 점검 현황
- SAM API Development Rules (CLAUDE.md 내 섹션)

## 📊 변경 통계

- **신규 파일:** 2개 (FormRequest)
- **수정 파일:** 2개 (Controller, message.php)
- **삭제 파일:** 0개
- **총 변경 라인:** ~50줄
- **SAM 규칙 준수:** 100%

## 🎯 다음 작업

1. Swagger 재생성 및 검증
2. 실제 API 테스트
3. Phase 3-2: MaterialApi.php Swagger 점검