# ADR-001: Spring 경계 아키텍처 정의

**날짜**: 2026-07-14
**상태**: 수락됨
**결정자**: TA 아키텍트

---

## Context (배경)

TA 역할 프로젝트는 역할(Role) 기반 접근 제어 시스템을 구현한다. 다중 계층 구조에서 Controller, Service, Repository 각 계층의 책임 범위, 오류 계약, 트랜잭션 경계를 명확히 정의하지 않으면 다음과 같은 문제가 발생한다.

- **책임 혼재**: 비즈니스 로직이 Controller에 유출되거나, DB 접근 로직이 Service에 직접 작성
- **일관성 없는 오류 처리**: 각 계층마다 다른 예외 타입과 HTTP 상태 코드를 반환
- **트랜잭션 누락/과다**: 읽기 전용 쿼리에 불필요한 트랜잭션이 걸리거나, 다중 쓰기 작업이 원자성 없이 실행
- **테스트 어려움**: 계층 간 결합으로 인해 단위 테스트가 불가능

---

## Decision (결정)

### 1. 계층 책임 경계

| 계층 | 책임 | 포함 사항 | 금지 사항 |
|------|------|-----------|-----------|
| **Controller** | HTTP 요청/응답 변환, 입력 검증, 라우팅 | `@RequestMapping`, `@Valid`, `@RequestBody` 파싱, 응답 DTO 변환 | 비즈니스 로직 직접 실행, DB 접근, Service 메서드 직접 호출 없이 로직 처리 |
| **Service** | 비즈니스 로직, 트랜잭션 관리, 도메인 조율 | `@Transactional`, 도메인 객체 조작, 다중 Repository 호출, 정책 enforcement | HTTP 요청/응답 직접 처리, SQL 직접 작성, `@Entity` 직접 매핑 반환 |
| **Repository** | 데이터 접근 추상화, 쿼리 실행 | `JpaRepository` 확장, `@Query`, `EntityManager` 직접 사용, Specification 패턴 | 비즈니스 로직, 트랜잭션 경계 설정, 응답 형식 결정 |

### 2. 오류 계약 (Error Contract)

모든 계층에서 발생하는 예외는 **단일 예외 계층 구조**로 변환되어 Controller에서 일관된 HTTP 응답을 생성한다.

```
BaseException (추상)
├── BusinessException      → HTTP 400 (잘못된 요청)
│   ├── RoleNotFoundException
│   ├── DuplicateRoleException
│   └── InvalidRoleStateException
├── AuthorizationException → HTTP 403 (권한 없음)
└── SystemException        → HTTP 500 (서버 오류)
    ├── DataAccessException
    └── ExternalServiceException
```

**오류 응답 형식 (RFC 7807 Problem Details)**:
```json
{
  "type": "https://api.example.com/errors/role-not-found",
  "title": "Role Not Found",
  "status": 404,
  "detail": "Role with id '123' does not exist",
  "instance": "/api/v1/roles/123",
  "timestamp": "2026-07-14T10:17:23Z"
}
```

**계약 규칙**:
- Service 계층은 `BusinessException` 하위 타입만 던진다
- Repository 계층 예외는 Service 계층에서 `SystemException`으로 래핑한다
- Controller는 `@ControllerAdvice`에서 전역 예외를 처리한다
- 예외 메시지는 외부 노출용으로 **사용자 친화적**이어야 한다

### 3. 트랜잭션 경계

| 시나리오 | 전파 방식 | 격리 수준 | 읽기 전용 |
|----------|-----------|-----------|-----------|
| 단일 조회 (findById) | REQUIRED | DEFAULT | true |
| 목록 조회 (findAll) | REQUIRED | DEFAULT | true |
| 단일 생성 (save) | REQUIRED | DEFAULT | false |
| 벌크 업데이트 (bulk update) | REQUIRED | READ_COMMITTED | false |
| 다중 리포지토리 쓰기 | REQUIRED | READ_COMMITTED | false |
| 읽기 전용 조회 (통계/리포트) | REQUIRED_READ_ONLY | DEFAULT | true |

**트랜잭션 롤백 규칙**:
- `RuntimeException`, `DataAccessException`은 자동 롤백
- 검사 예외(`Checked Exception`)는 명시적 `rollbackFor` 지정 필요
- 읽기 전용 트랜잭션에서 쓰기 시도 시 예외 발생

---

## Alternatives (대안)

### 대안 1: Service에서 직접 예외 던지기 (현재 미선택)
- 각 Service 메서드가 다양한 예외 타입을 직접 던짐
- **단점**: Controller에서 예외 타입별 분기 처리 필요, 일관성 유지 어려움

### 대안 2: 트랜잭션 없음 (수동 커밋)
- `TransactionTemplate`을 수동으로 사용
- **단점**: 코드 복잡성 증가, 실수 가능성 높음

### 대안 3: Repository에서 비즈니스 로직 포함
- **단점**: 데이터 접근과 비즈니스 로직 결합, 테스트 어려움, 재사용성 저하

---

## Consequences (결과)

### 긍정적 결과
- **단위 테스트 용이**: 각 계층이 명확히 분리되어 Mock 기반 테스트 가능
- **유지보수성**: 오류 처리와 트랜잭션 정책이 한 곳에 집중
- **일관성**: 모든 API가 동일한 오류 응답 형식 제공
- **확장성**: 새 예외 타입 추가 시 `BaseException` 하위 클래스만 생성

### 부정적 결과
- **초기 개발 시간**: 예외 계층 구조와 `@ControllerAdvice` 설정 필요
- **학습 곡선**: 개발자가 계층 책임 경계와 트랜잭션 전파 규칙을 숙지해야 함
- **오버엔지니어링 위험**: 소규모 프로젝트에서는 과한 추상화 가능성

### 모니터링 지표
- 예외 발생 시 `type` 필드로 문제 유형 추적
- 트랜잭션 경과 시간 로깅으로 성능 병목 탐지
- 계층 간 호출 횟수 카운터로 불필요한 조회 감지