From 471cabf23b8db7a41579fdbb1f45b9d281d7a6c7 Mon Sep 17 00:00:00 2001 From: forge-bot Date: Tue, 14 Jul 2026 10:59:28 +0000 Subject: [PATCH 1/2] forge: open work branch for runtime-role-matrix-live-20260714105818-v9-ta-001-attempt-1-run-a48b5fc922fc --- ...live-20260714105818-v9-ta-001-attempt-1-run-a48b5fc922fc.md | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 .forge/runtime-role-matrix-live-20260714105818-v9-ta-001-attempt-1-run-a48b5fc922fc.md diff --git a/.forge/runtime-role-matrix-live-20260714105818-v9-ta-001-attempt-1-run-a48b5fc922fc.md b/.forge/runtime-role-matrix-live-20260714105818-v9-ta-001-attempt-1-run-a48b5fc922fc.md new file mode 100644 index 0000000..1d33021 --- /dev/null +++ b/.forge/runtime-role-matrix-live-20260714105818-v9-ta-001-attempt-1-run-a48b5fc922fc.md @@ -0,0 +1,3 @@ +# runtime-role-matrix-live-20260714105818-v9-ta-001-attempt-1-run-a48b5fc922fc + +Forge 이슈 작업 브랜치 `forge/runtime-role-matrix-live-20260714105818-v9-ta-001-attempt-1-run-a48b5fc922fc`. -- 2.49.1 From 57e3ae7b8d4780895b21e5cd1b86f990b3275087 Mon Sep 17 00:00:00 2001 From: forge-bot Date: Tue, 14 Jul 2026 10:59:45 +0000 Subject: [PATCH 2/2] =?UTF-8?q?TA=20=EC=97=AD=ED=95=A0=20Spring=20?= =?UTF-8?q?=EA=B2=BD=EA=B3=84=20smoke=20(runtime-role-matrix-live-20260714?= =?UTF-8?q?105818-v9-ta-001)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../ADR-001-spring-boundary-architecture.md | 224 ++++++++++++++++++ 1 file changed, 224 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..6f87b0f --- /dev/null +++ b/docs/adr/ADR-001-spring-boundary-architecture.md @@ -0,0 +1,224 @@ +# ADR-001: Spring 경계 아키텍처 정의 + +## Context + +runtime-role-matrix-live 프로젝트는 역할(Role) 기반 접근 제어 시스템을 구현한다. 다중 계층 구조에서 Controller, Service, Repository 간의 책임 분리와 오류 처리, 트랜잭션 관리가 명확히 정의되지 않아 다음 문제가 발생한다. + +| 문제점 | 영향 | +|--------|------| +| Controller에서 비즈니스 로직 직접 실행 | 단일 책임 원칙 위반, 테스트 어려움 | +| Service에서 unchecked exception 무분별한 전파 | 일관된 오류 응답 불가 | +| Repository에서 트랜잭션 경계 불분명 | 데이터 정합성 위험 | +| 각 계층 간 계약(contract) 부재 | API 스펙 변경 시 파급 효과 예측 불가 | + +## Decision + +### 1. Controller-Service-Repository 경계 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Controller Layer │ +│ - HTTP 요청/응답 처리 │ +│ - 입력 검증 (DTO 변환, Bean Validation) │ +│ - HTTP 상태 코드 결정 │ +│ - Service 호출 및 결과 매핑 │ +│ - 예외를 HTTP 응답으로 변환 │ +└─────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ Service Layer │ +│ - 비즈니스 로직 수행 │ +│ - 도메인 객체 조작 │ +│ - 트랜잭션 경계 설정 (@Transactional) │ +│ - Repository 호출 │ +│ - 도메인 예외을 ServiceException으로 변환 │ +└─────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ Repository Layer │ +│ - 데이터 접근 (JPA Repository) │ +│ - 엔티티 ↔ 도메인 객체 변환 │ +│ - 순수 데이터 조작만 담당 │ +│ - 예외는 그대로 전파 (DataAccessException) │ +└─────────────────────────────────────────────────────────────┘ +``` + +**책임 매트릭스** + +| 책임 | Controller | Service | Repository | +|------|:----------:|:-------:|:----------:| +| HTTP 파라미터 바인딩 | ✅ | ❌ | ❌ | +| Bean Validation | ✅ | △ (도메인 검증) | ❌ | +| 비즈니스 로직 | ❌ | ✅ | ❌ | +| 트랜잭션 관리 | ❌ | ✅ | ❌ | +| 데이터 접근 | ❌ | ❌ | ✅ | +| DTO ↔ Entity 변환 | ✅ | △ (도메인 변환) | ✅ | +| 예외 → HTTP 응답 | ✅ | ❌ | ❌ | + +### 2. 오류 계약 (Error Contract) + +**예외 계층 구조** + +``` +RuntimeException +├── ServiceException (체크 예외, 비즈니스 오류) +│ ├── RoleNotFoundException +│ ├── RoleAlreadyExistsException +│ └── PermissionDeniedException +└── DataAccessException (Spring, unchecked) +``` + +**ServiceException 스펙** + +| 필드 | 타입 | 필수 | 설명 | +|------|------|:----:|------| +| code | String | ✅ | 오류 코드 (e.g., "ROLE_NOT_FOUND") | +| message | String | ✅ | 사용자에게 표시할 메시지 | +| details | Map | ❌ | 추가 메타데이터 | +| timestamp | Instant | ✅ | 발생 시각 | + +**HTTP 상태 코드 매핑** + +| 예외 | HTTP 상태 | 이유 | +|------|:---------:|------| +| RoleNotFoundException | 404 | 리소스 없음 | +| RoleAlreadyExistsException | 409 | 리소스 충돌 | +| PermissionDeniedException | 403 | 권한 없음 | +| ValidationException | 400 | 잘못된 요청 | +| ServiceException (기타) | 500 | 내부 서버 오류 | + +**오류 응답 형식 (RFC 7807 Problem Details)** + +```json +{ + "type": "https://api.example.com/errors/role-not-found", + "title": "Role Not Found", + "status": 404, + "code": "ROLE_NOT_FOUND", + "message": "ID가 'admin'인 역할을 찾을 수 없습니다.", + "details": { + "roleId": "admin", + "timestamp": "2026-07-14T10:58:18Z" + } +} +``` + +### 3. 트랜잭션 경계 + +**트랜잭션 전파 정책** + +| 시나리오 | 전파 방식 | 설명 | +|---------|:---------:|------| +| Service → Repository | REQUIRED (기본) | 기존 트랜잭션 참여 또는 신규 생성 | +| Service → Service (내부 호출) | REQUIRED | 같은 트랜잭션 내에서 실행 | +| readOnly 조회 | readOnly=true | 성능 최적화,Dirty checking 비활성화 | +| 쓰기 작업 | readOnly=false (기본) | 기본값, 명시적 지정 불필요 | + +**트랜잭션 경계 설정 규칙** + +1. **트랜잭션 시작점**: Service 계층의 public 메서드 +2. **트랜잭션 종료점**: Service 메서드 종료 시 commit, 예외 발생 시 rollback +3. **Controller에서 @Transactional 금지**: HTTP 요청 스레드와 트랜잭션 바인딩 분리 +4. **Repository에서 @Transactional 금지**: 데이터 접근만 담당 + +**트랜잭션 시퀀스 다이어그램** + +```mermaid +sequenceDiagram + participant C as Controller + participant S as Service + participant R as Repository + participant DB as Database + + C->>+S: createRole(dto) + S->>S: @Transactional 시작 + S->>+R: existsByRoleId(id) + R->>+DB: SELECT + DB-->-R: 결과 + R-->-S: false + alt 역할 존재 시 + S-->>C: 예외 발생 (RoleAlreadyExistsException) + else 역할 미존재 시 + S->>+R: save(entity) + R->>+DB: INSERT + DB-->-R: 저장된 엔티티 + R-->-S: 저장된 엔티티 + S-->>S: @Transactional 커밋 + S-->>-C: 생성된 역할 DTO + end + + Note over S,DB: 예외 발생 시 자동 Rollback +``` + +**외부 시스템 연동 시 트랜잭션 처리** + +``` +┌──────────────────────────────────────────────────────────────┐ +│ @Transactional │ +│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │ +│ │ DB 저장 │ │ 메시지 발송 │ │ 외부 API 호출 │ │ +│ │ (트랜잭션 참여)│ │ (로컬 트랜잭션)│ │ (비트랜잭션) │ │ +│ └────────────────┘ └────────────────┘ └────────────────┘ │ +│ │ +│ 실패 시: DB 저장만 롤백, 메시지/외부API는 별도 보상 처리 필요 │ +└──────────────────────────────────────────────────────────────┘ +``` + +## Alternatives + +### 대안 1: Controller에서 직접 Repository 호출 + +| 항목 | 내용 | +|------|------| +| 장점 | 간단한 CRUD에 코드량 감소 | +| 단점 | 비즈니스 로직 분산, 테스트 어려움, 트랜잭션 관리 불가 | +| 채택 여부 | ❌ 불채택 - 확장성 및 유지보수성 저하 | + +### 대안 2: Service 계층 없이 도메인 객체에 비즈니스 로직 포함 + +| 항목 | 내용 | +|------|------| +| 장점 | 도메인 주도 설계(DDD) 접근, 객체지향적 | +| 단점 | 도메인 객체가 프레임워크 의존성 발생, 테스트 복잡 | +| 채택 여부 | ❌ 불채택 - 현재 프로젝트 규모에서 과도한 복잡성 | + +### 대안 3: 전역 예외 처리 (@ControllerAdvice)만 사용, 계층별 예외 변환 없음 + +| 항목 | 내용 | +|------|------| +| 장점 | 구현 단순화 | +| 단점 | 예외 처리 로직 중앙화되어 단일 책임 위반, 테스트 어려움 | +| 채택 여부 | ❌ 불채택 - 계층별 명확한 오류 계약 필요 | + +## Consequences + +### 긍정적 결과 + +- **단일 책임 원칙 준수**: 각 계층이 명확한 역할을 담당 +- **테스트 용이성**: Mock을 통한 단위 테스트 가능 +- **일관된 오류 처리**: RFC 7807 표준 준수, 예측 가능한 API 응답 +- **트랜잭션 관리 명확성**: Service 계층에서 트랜잭션 경계 집중 관리 +- **유지보수성 향상**: 변경 시 파급 효과 최소화 + +### 부정적 결과 (적용 부담) + +- **코드량 증가**: DTO 변환, 예외 변환 로직 추가 +- **학습 곡선**: 개발자 역량 요구사항 상승 +- **추가 의존성**: 예외 계층 구조 관리 필요 + +### 모니터링 및 검증 + +| 지표 | 측정 방법 | +|------|----------| +| 계층 분리 준수율 | 코드 리뷰 시 Controller에 비즈니스 로직 존재 여부 체크 | +| 예외 처리 일관성 | @ControllerAdvice 로그 분석 | +| 트랜잭션 커밋/롤백 비율 | 트랜잭션 로그 모니터링 | + +### 마이그레이션 계획 + +1. 기존 코드를 점진적으로 리팩토링 (하위 호환 유지) +2. 새로운 기능은 ADR 규칙 즉시 적용 +3. 공통 예외 클래스를 `exception` 패키지에 배치 +4. DTO 클래스를 `dto` 패키지에 배치 -- 2.49.1