# ADR-001: Spring MVC 계층 경계 및 트랜잭션 정책

## Context

runtime-role-matrix-live 프로젝트는 Spring Boot 기반 REST API 서버로, 역할 기반 접근 제어(RBAC) 메트릭스를 실시간 처리한다. 다중 개발자가 동시 개발 시 계층 간 책임 범위가 모호하여 중복 로직, 트랜잭션 누락, 일관되지 않은 오류 응답이 발생하는 문제가 있다.

## Decision

### 1. Controller-Service-Repository 경계

| 계층 | 책임 | 허용 의존성 |
|------|------|------------|
| **Controller** | HTTP 요청/응답 변환, 입력 검증, HTTP 상태 코드 결정 | Service 계층만 주입 |
| **Service** | 비즈니스 로직, 트랜잭션 경계, 도메인 조율 | Repository, Domain Entity, Value Object |
| **Repository** | 데이터 접근 추상화, JPA Entity 관리 | JPA Entity, EntityManager |

**구체적 규칙:**
- Controller는 `@RequestBody` DTO만 수신하고, 직접 Entity를 반환하지 않는다.
- Service는 `@Transactional(readOnly = true)`를 기본으로 하고, 쓰기 작업 시 `readOnly = false` 명시한다.
- Repository는 `JpaRepository` 또는 `CrudRepository`를 확장하며, `@Query`로 네이티브 SQL을 최소화한다.
- 도메인 로직은 Service 계층에 위치하며, Controller에 절대 포함하지 않는다.

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

모든 API 오류는 다음 구조로 일관되게 응답한다:

```json
{
  "code": "ERR_ROLE_NOT_FOUND",
  "message": "역할 ID 123을 찾을 수 없습니다",
  "timestamp": "2026-07-14T15:22:00Z",
  "path": "/api/v1/roles/123"
}
```

**오류 코드 체계:**

| 접두사 | 의미 | HTTP 상태 |
|--------|------|-----------|
| `ERR_` | 비즈니스/시스템 오류 | 4xx, 5xx |
| `VALIDATION_` | 입력 검증 실패 | 400 |
| `AUTH_` | 인증/인가 오류 | 401, 403 |
| `CONFLICT_` | 리소스 충돌 | 409 |

**구현 계약:**
- `GlobalExceptionHandler`가 모든 `RuntimeException` 하위 예외를 `@ExceptionHandler`로 처리한다.
- `BusinessException` 추상 클래스를 정의하고, 각 도메인 예외는 이를 확장한다.
- Controller에서 `try-catch`를 절대 사용하지 않는다.
- 예외 메시지는 사용자에게 직접 노출하지 않고, 내부 로그로만 기록한다.

### 3. 트랜잭션 경계

| 시나리오 | 전파 방식 | 격리 수준 |
|----------|-----------|-----------|
| 읽기 전용 조회 | `REQUIRED`, `readOnly=true` | 기본값 (READ_COMMITTED) |
| 단일 엔티티 생성/수정 | `REQUIRED`, `readOnly=false` | 기본값 |
| 다중 테이블 변경 | `REQUIRES_NEW` | `SERIALIZABLE` (명시적 필요 시) |
| 외부 API 호출 포함 | `MANDATORY` (트랜잭션 없으면 예외) | - |

**구체적 규칙:**
- `@Transactional`은 public 메서드에만 적용한다.
- 내부 메서드 호출(`this.method()`)은 프록시를 우회하므로, 별도 Bean으로 분리한다.
- 읽기 전용 트랜잭션에서 쓰기 시도 시 `InvalidDataAccessApiUsageException` 발생시킨다.
- 롤백은 `RuntimeException`, `DataAccessException`에 대해 자동 수행한다.

### 4. 패키지 구조

```
com.runtimematrix
├── controller      # REST Controller, DTO
├── service         # Business Logic, Transaction Boundary
├── repository      # Data Access
├── domain          # Entity, Value Object, Domain Event
├── exception       # BusinessException hierarchy
├── config          # Spring Configuration
└── dto             # Request/Response DTO
```

## Alternatives

| 대안 | 단점 | 선택하지 않은 이유 |
|------|------|-------------------|
| Controller에 트랜잭션 적용 | 테스트 어려움, 결합도 증가 | Service 계층이 자연스러운 트랜잭션 경계 |
| 예외를 직접 HTTP 응답에 매핑 | 오류 구조 불일치, 유지보수 어려움 | 중앙화된 ExceptionHandler로 일관성 확보 |
| Repository에 비즈니스 로직 포함 | 재사용성 저하, 테스트 어려움 | Service 계층에서 도메인 조율 |

## Consequences

**Positive:**
- 계층별 단위 테스트 용이 (Mock 기반)
- 오류 응답 일관성으로 클라이언트 처리 단순화
- 트랜잭션 범위 명확화로 데이터 정합성 보장

**Negative:**
- DTO ↔ Entity 변환 코드 증가 (`MapStruct` 도입 권장)
- 다중 트랜잭션 시 `REQUIRES_NEW` 남용 시 성능 저하 가능

**Rollback Plan:**
- ADR 변경 시 기존 API 호환성을 위해 `@Deprecated` 어노테이션과 함께 2버전 마이그레이션 기간 운영