runtime-role-matrix-live-20260714101723-v7/docs/adr/ADR-001-spring-boundary-architecture.md

ADR-001: Spring Layer Boundary Architecture

Context

TA 역할의 Spring 기반 마이크로서비스는 역할 매트릭스 관리 기능을 제공한다. Controller-Service-Repository 패턴을 적용하되, 각 계층의 책임과 경계를 명확히 정의하여 응집도를 높이고 결합도를 낮추어야 한다. 또한 오류 처리와 트랜잭션 관리의 일관된 전략이 필요하다.

Decision

1. Controller-Service-Repository 경계

Layer	Responsibility	Forbidden Dependencies
Controller	HTTP 요청/응답 변환, 입력 검증, HTTP 상태 코드 관리	직접 Repository 접근 금지
Service	비즈니스 로직, 도메인 규칙, 트랜잭션 경계	HTTP Servlet API 직접 사용 금지
Repository	데이터 접근, JPA 쿼리, 엔티티 매핑	비즈니스 로직 포함 금지

2. 오류 계약 (Error Contract)

Scenario	HTTP Status	Response Body
Validation Error	400	{ "code": "VALIDATION_ERROR", "message": "...", "field": "..." }
Resource Not Found	404	{ "code": "NOT_FOUND", "message": "...", "resourceId": "..." }
Business Rule Violation	409	{ "code": "BUSINESS_ERROR", "message": "..." }
Internal Error	500	{ "code": "INTERNAL_ERROR", "message": "..." }

3. 트랜잭션 경계

• 시작점: Service Layer (public method 진입점)
• 종료점: Service Layer (public method 종료점)
• 전파: @Transactional(propagation = REQUIRED) 기본값 사용
• 읽기 전용: 조회 전용 Service Method에 @Transactional(readOnly = true) 적용

Alternatives

1. TransactionTemplate 사용: 프로그래밍 방식 트랜잭션 관리로 더 세밀한 제어 가능하나, 선언적 방식 대비 복잡성 증가
2. Controller에서 트랜잭션 관리: 테스트 용이성 감소, 단일 책임 원칙 위반
3. Repository에서 비즈니스 로직 포함: 데이터 접근 계층의 재사용성 저하

Consequences

Positive

• 계층별 단일 책임 원칙 준수
• 일관된 오류 처리로 API consumers 보호
• 트랜잭션 경계 명확화로 데이터 무결성 보장
• 테스트 용이성 향상 (Mock 주입 용이)

Negative

• 간단한 CRUD 연산에도 Service Layer 필요로 인한 코드 증가
• 트랜잭션 경계 설정 오류 시 롤백 누락 위험