TA 역할 Spring 경계 smoke (role-ta-live-1522-001)

docs/adr/ADR-001-spring-architecture-boundaries.md

@@ -0,0 +1,84 @@
+# ADR-001: Spring MVC 아키텍처 경계 및 계약 정의
+
+## Context
+
+runtime-role-matrix-live 프로젝트는 Spring Boot 기반 REST API 서버로 역할 기반 접근 제어(RBAC)를 구현한다. 레이어 간 책임 분담, 오류 처리 계약, 트랜잭션 범위가 명시적으로 정의되어 있지 않아 일관성 없는 구현이 발생할 위험이 있다.
+
+## Decision
+
+### 1. 레이어 경계 정의
+
+| 레이어 | 책임 |
+|-------|------|
+| **Controller** | HTTP 요청/응답, 입력 검증, DTO 변환, HTTP 상태 코드 결정. 트랜잭션 경계 없음 |
+| **Service** | 비즈니스 로직, 도메인 객체 조작, @Transactional 선언적 트랜잭션, BusinessException 발생 |
+| **Repository** | 데이터 접근(JPA), 쿼리 실행, Entity 변환. 순수 데이터 조작만 수행 |
+
+### 2. 오류 계약 (RFC 7807 Problem Details)
+
+```json
+{
+  "type": "https://api.runtimematrix.com/errors/role-not-found",
+  "title": "역할을 찾을 수 없습니다",
+  "status": 404,
+  "detail": "ID가 'admin'인 역할이 존재하지 않습니다.",
+  "instance": "/api/v1/roles/admin",
+  "timestamp": "2026-07-14T15:22:00Z",
+  "traceId": "abc123def456"
+}
+```
+
+**예외 계층**: `RuntimeException → BusinessException(추상) → RoleNotFoundException, RoleAlreadyExistsException`
+
+**HTTP 상태 매핑**:
+
+| 예외 | 상태 |
+|-----|------|
+| ValidationException | 400 |
+| BusinessException | 400/409 |
+| RoleNotFoundException | 404 |
+| PermissionDeniedException | 403 |
+| InternalServerException | 500 |
+
+### 3. 트랜잭션 경계
+
+| 규칙 | 설명 |
+|-----|------|
+| 시작점 | Service Layer public 메서드 |
+| 전파 | REQUIRED (기본값) |
+| 읽기 전용 | SELECT-only 메서드에 `readOnly=true` |
+| 격리 수준 | READ_COMMITTED |
+| 롤백 | RuntimeException, BusinessException → Yes |
+
+### 4. 의존성 규칙
+
+| From → To | 허용 |
+|-----------|------|
+| Controller → Service | ✅ |
+| Controller → Repository | ❌ |
+| Service → Repository | ✅ |
+| Service → Domain | ✅ |
+| Repository → Service | ❌ |
+
+### 5. 패키지 구조
+
+```
+com.runtimematrix
+├── controller/dto      # Request/Response DTO
+├── service/command     # Command 객체
+├── repository          # JPA Repository
+├── domain/model        # 도메인 객체
+├── domain/exception    # 도메인 예외
+└── config              # Spring Configuration
+```
+
+## Consequences
+
+**긍정**: 레이어별 책임 명확, 일관된 오류 응답, 데이터 일관성 보장, 테스트 용이성 향상
+
+**부정**: 기존 코드 수정 필요, 추가 DTO/Command 클래스 필요
+
+## References
+
+- [Spring Transaction Management](https://docs.spring.io/spring-framework/docs/current/reference/html/data-access.html#transaction)
+- [RFC 7807 Problem Details](https://tools.ietf.org/html/rfc7807)