From 376786dd552a6011339cdd8a4ec9d9e58875496a Mon Sep 17 00:00:00 2001
From: forge-bot <bot@forge.local>
Date: Tue, 14 Jul 2026 10:24:36 +0000
Subject: [PATCH] =?UTF-8?q?TA=20=EC=97=AD=ED=95=A0=20Spring=20=EA=B2=BD?=
 =?UTF-8?q?=EA=B3=84=20smoke=20(runtime-role-matrix-live-20260714101723-v7?=
 =?UTF-8?q?-ta-001)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../ADR-001-spring-boundary-architecture.md   | 49 +++++++++++++++++++
 1 file changed, 49 insertions(+)
 create mode 100644 docs/adr/ADR-001-spring-boundary-architecture.md

diff --git a/docs/adr/ADR-001-spring-boundary-architecture.md b/docs/adr/ADR-001-spring-boundary-architecture.md
new file mode 100644
index 0000000..e2b2be5
--- /dev/null
+++ b/docs/adr/ADR-001-spring-boundary-architecture.md
@@ -0,0 +1,49 @@
+# 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 필요로 인한 코드 증가
+- 트랜잭션 경계 설정 오류 시 롤백 누락 위험