allra-api-design

# Allra Backend API 설계 및 패키지 구조

Allra 백엔드 팀의 API 설계, DTO 네이밍, 패키지 구조 표준을 정의합니다.

## 프로젝트 기본 정보

이 가이드는 다음 환경을 기준으로 작성되었습니다:

- **Java**: 17 이상
- **Spring Boot**: 3.2 이상
- **주요 기술**: JPA/Hibernate, QueryDSL, JWT

**참고**: 프로젝트별로 사용하는 기술 스택이나 버전이 다를 수 있습니다. 프로젝트에 맞게 조정하여 사용하세요.

## 패키지 구조 규칙

도메인별 패키지 구조를 권장합니다:

```text
└── {domain}
    ├── api          // 컨트롤러 레이어
    ├── dto          // 데이터 전송 객체
    ├── entity       // JPA 엔티티
    ├── enums        // Enum 정의 (선택)
    ├── repository   // 데이터 접근 계층
    └── service      // 비즈니스 로직
```

**참고**: 프로젝트에 따라 `controller`, `model`, `dao` 등 다른 이름을 사용할 수 있습니다. 중요한 것은 레이어별 책임을 명확히 분리하는 것입니다.

### 예시

```text
└── user
    ├── api
    │   └── UserController.java
    ├── dto
    │   ├── UserSignUpEventDto.java  // 내부 사용
    │   ├── request
    │   │   └── SignUpRequest.java
    │   └── response
    │       └── SignUpResponse.java
    ├── entity
    │   └── User.java
    ├── repository
    │   ├── UserRepository.java
    │   └── UserRepositorySupport.java
    └── service
        └── UserService.java
```

## DTO 네이밍 규칙

### 1. 클라이언트 통신 DTO

- **Request**: `{Operation}Request`
  - 예: `SignUpRequest`, `UpdateUserRequest`
- **Response**: `{Operation}Response`
  - 예: `SignUpResponse`, `UserDetailResponse`

### 2. 내부 사용 DTO

내부에서만 사용하는 DTO는 `Dto` 접미사 추가:
- Repository Layer QueryDSL Fetch DTO
- Internal Layer Transfer DTO
- 예: `UserSignUpEventDto`, `UserSummaryDto`

### 3. Record 사용

**DTO 같은 단순 클래스들은 가능하면 대부분 record로 생성**

```java
// Request/Response
public record SignUpRequest(
    String email,
    String password,
    String name
) {}

public record SignUpResponse(
    Long userId,
    String email
) {}

// 내부 사용 DTO
public record UserSignUpEventDto(
    Long userId,
    String email,
    LocalDateTime signUpAt
) {}
```

## API 컨트롤러 설계 가이드

### 1. REST API 명명 규칙

```java
@RestController
@RequestMapping("/api/v1/users")
public class UserController {

    // GET /api/v1/users - 목록 조회
    @GetMapping
    public List<UserResponse> getUse