# 컨트롤러 계층 구조

> **관련 문서**: [index.md](index.md) | [service-repository.md](service-repository.md) | [validation.md](validation.md)

---

## TL;DR (5초 요약)

```text
1. AdminBaseController / AuthBaseController / PublicBaseController 중 상속
2. Service 주입 필수 (Repository 직접 주입 금지)
3. FormRequest로 검증 (컨트롤러에 검증 로직 금지)
4. ResponseHelper 메서드 사용 (success, error, successWithResource)
5. 네이밍: [Entity][Action]Controller (예: UserListController)
6. array_filter 시 null만 제거 (빈 문자열은 사용자 의도로 보존)
```

---

## 목차

1. [Base 컨트롤러 계층](#base-컨트롤러-계층)
2. [각 컨트롤러 역할](#각-컨트롤러-역할)
3. [컨트롤러 네이밍 규칙](#컨트롤러-네이밍-규칙)
4. [응답 메서드 사용](#응답-메서드-사용)
5. [Controller 규칙](#controller-규칙)
6. [패턴 예시](#패턴-예시)
7. [데이터 필터링 패턴 (array_filter)](#데이터-필터링-패턴-array_filter)
8. [체크리스트](#체크리스트)

---

## Base 컨트롤러 계층

G7은 역할 기반의 컨트롤러 계층 구조를 사용합니다.

```text
BaseApiController (최상위)
├── AdminBaseController (관리자 전용)
├── AuthBaseController (인증된 사용자)
└── PublicBaseController (공개 API)
```

---

## 각 컨트롤러 역할

### BaseApiController

**경로**: `app/Http/Controllers/Api/Base/BaseApiController.php`

- 모든 API 컨트롤러의 최상위 부모 클래스
- 공통 응답 메서드 제공: `success()`, `error()`, `successWithResource()`, `notFound()`, `unauthorized()`, `forbidden()`, `validationError()`
- 인증 사용자 조회: `getCurrentUser()`

### AdminBaseController

**경로**: `app/Http/Controllers/Api/Base/AdminBaseController.php`

- BaseApiController 상속
- 관리자 전용 기능
- 미들웨어: `['auth:sanctum', 'admin']`
- 관리자 활동 로깅: `logAdminActivity()`

### AuthBaseController

**경로**: `app/Http/Controllers/Api/Base/AuthBaseController.php`

- BaseApiController 상속
- 인증된 사용자 전용 기능
- 미들웨어: `['auth:sanctum']`
- 리소스 소유권 확인: `isOwner()`, `canAccessResource()`, `checkOwnership()`
- 사용자 활동 로깅: `logUserActivity()`

### PublicBaseController

**경로**: `app/Http/Controllers/Api/Base/PublicBaseController.php`

- BaseApiController 상속
- 인증 불필요한 공개 API
- 미들웨어: `['throttle:60,1']` (속도 제한)
- 캐싱: `cached()`
- API 사용량 추적: `logApiUsage()`, `getClientInfo()`

---

## 컨트롤러 네이밍 규칙

### 코어

| 역할 | 경로 |
|------|------|
| 관리자 | `app/Http/Controllers/Api/Admin/[기능명]Controller.php` |
| 인증 사용자 | `app/Http/Controllers/Api/Auth/[기능명]Controller.php` |
| 공개 API | `app/Http/Controllers/Api/Public/[기능명]Controller.php` |

### 모듈

| 역할 | 경로 |
|------|------|
| 관리자 | `modules/[vendor-module]/src/Controllers/Api/Admin/[기능명]Controller.php` |
| 인증 사용자 | `modules/[vendor-module]/src/Controllers/Api/Auth/[기능명]Controller.php` |
| 공개 API | `modules/[vendor-module]/src/Controllers/Api/[기능명]Controller.php` |

---

## 응답 메서드 사용

모든 컨트롤러는 Base 클래스의 공통 메서드를 사용합니다:

```php
// ✅ DO: 공통 메서드 사용
return $this->success('messages.created', $data, 201);
return $this->error('messages.failed', 400);
return $this->successWithResource('messages.success', new UserResource($user));
return $this->notFound('messages.not_found');
return $this->unauthorized('messages.unauthorized');
return $this->forbidden('messages.forbidden');
return $this->validationError($errors, 'messages.validation_failed');

// ❌ DON'T: 역할별 래퍼 메서드 사용 (Deprecated)
// adminSuccess(), userSuccess(), publicSuccess() 등은 사용하지 않음
```

---

## Controller 규칙

### 원칙

- Service 클래스를 생성자 주입으로 받음
- 비즈니스 로직은 Service에 위임
- ResponseHelper 사용
- 인라인 검증 금지 (FormRequest 사용)

> **참고**: FormRequest 상세 규칙은 [validation.md](validation.md) 참조

---

## 패턴 예시

```php
<?php

namespace Modules\Sirsoft\Ecommerce\Controllers\Api\Admin;

use App\Http\Controllers\Api\Base\AdminBaseController;
use App\Helpers\ResponseHelper;
use Modules\Sirsoft\Ecommerce\Services\ProductService;
use Modules\Sirsoft\Ecommerce\Requests\StoreProductRequest;
use Modules\Sirsoft\Ecommerce\Requests\UpdateProductRequest;
use Modules\Sirsoft\Ecommerce\Resources\ProductResource;
use Illuminate\Http\JsonResponse;

class ProductController extends AdminBaseController
{
    public function __construct(
        private ProductService $productService
    ) {}

    /**
     * 상품 목록 조회
     */
    public function index(): JsonResponse
    {
        $products = $this->productService->getAllProducts();

        return ResponseHelper::success(
            ProductResource::collection($products),
            '상품 목록을 조회했습니다.'
        );
    }

    /**
     * 상품 생성
     */
    public function store(StoreProductRequest $request): JsonResponse
    {
        $product = $this->productService->createProduct($request->validated());

        return ResponseHelper::success(
            new ProductResource($product),
            '상품이 생성되었습니다.',
            201
        );
    }

    /**
     * 상품 수정
     */
    public function update(UpdateProductRequest $request, int $id): JsonResponse
    {
        $product = $this->productService->updateProduct($id, $request->validated());

        return ResponseHelper::success(
            new ProductResource($product),
            '상품이 수정되었습니다.'
        );
    }
}
```

---

## 데이터 필터링 패턴 (array_filter)

컨트롤러에서 요청 데이터를 Service에 전달하기 전에 `array_filter`로 불필요한 값을 제거하는 경우, **빈 문자열(`''`)과 `null`의 의미 차이**에 주의해야 합니다.

### null vs 빈 문자열의 의미

| 값 | 의미 | 예시 |
|------|------|------|
| `null` | 필드가 전송되지 않음 (미포함) | JSON body에 키 자체가 없음 |
| `''` (빈 문자열) | 사용자가 의도적으로 값을 비움 | 기존 값을 지우려는 의도 |

### 잘못된 예시 (빈 문자열 제거)

```php
// ❌ DON'T: 빈 문자열도 제거 → 사용자의 "값 비우기" 의도 무시
$data = collect($validated)
    ->filter(fn ($v) => $v !== null && $v !== '')
    ->toArray();
```

### 올바른 예시 (null만 제거)

```php
// ✅ DO: null만 제거 → 빈 문자열은 사용자 의도로 보존
$data = collect($validated)
    ->filter(fn ($v) => $v !== null)
    ->toArray();
```

### 적용 시점

| 상황 | 권장 패턴 |
|------|----------|
| 설정 Override (기본값 위에 덮어쓰기) | `null`만 제거 (빈 문자열 = 기본값으로 초기화) |
| 일반 CRUD 저장 | `validated()` 그대로 사용 (필터링 불필요) |
| 선택적 필드 업데이트 (PATCH) | `null`만 제거 또는 `filled()` 활용 |

---

## 표준 예외 처리 패턴

컨트롤러에서 Service 호출 시 다음 표준 예외 처리 패턴을 사용합니다:

```php
public function store(StoreProductRequest $request): JsonResponse
{
    try {
        $product = $this->productService->createProduct($request->validated());

        return $this->success('product.create_success', new ProductResource($product), 201);
    } catch (ValidationException $e) {
        return $this->validationError($e->errors(), 'product.create_failed');
    } catch (\Exception $e) {
        return $this->error('product.create_failed', 500);
    }
}
```

### 예외 유형별 처리

| 예외 유형 | 응답 메서드 | 상태 코드 | 용도 |
| ---------- | ----------- | ---------- | ------ |
| `ValidationException` | `validationError()` | 422 | Service에서 발생한 검증 예외 |
| `AccessDeniedHttpException` | `error()` | 403 | 스코프 접근 거부 |
| 커스텀 비즈니스 예외 | `error()` | 400~409 | 비즈니스 규칙 위반 |
| `\Exception` (범용) | `error()` | 500 | 예상치 못한 오류 |

### 스코프 접근 거부 처리 패턴

```php
use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;

public function show(int $id): JsonResponse
{
    try {
        $item = $this->service->getItem($id);
        return $this->success('item.fetch_success', new ItemResource($item));
    } catch (AccessDeniedHttpException $e) {
        return $this->error('auth.scope_denied', 403);
    } catch (\Exception $e) {
        return $this->error('item.fetch_failed', 500);
    }
}
```

### 주의사항

- `ValidationException`은 `\Exception`보다 **먼저** catch해야 함 (하위 클래스 우선)
- 에러 메시지는 반드시 `__()` 다국어 키 사용 (하드코딩 금지)
- `$e->getMessage()`는 **로깅 목적**으로만 사용 (사용자에게 직접 노출 금지)

---

## 체크리스트

### 컨트롤러 개발 체크리스트

- [ ] 적절한 Base 컨트롤러를 상속했는가?
  - 관리자 기능 → `AdminBaseController`
  - 인증 사용자 기능 → `AuthBaseController`
  - 공개 API → `PublicBaseController`
- [ ] Service 클래스를 생성자 주입으로 받았는가?
- [ ] 비즈니스 로직을 Service에 위임했는가?
- [ ] ResponseHelper를 사용해 응답했는가?
- [ ] FormRequest를 사용해 검증했는가? (인라인 검증 금지)
- [ ] 네이밍 규칙을 준수했는가?

---

## 관련 문서

- [index.md](index.md) - 백엔드 가이드 인덱스
- [service-repository.md](service-repository.md) - Service-Repository 패턴
- [validation.md](validation.md) - 검증 로직 구현 원칙
- [response-helper.md](response-helper.md) - API 응답 규칙