diff --git a/.forge/role-ta-live-v4-001-attempt-1-run-e673c9d05e60.md b/.forge/role-ta-live-v4-001-attempt-1-run-e673c9d05e60.md deleted file mode 100644 index c174a80..0000000 --- a/.forge/role-ta-live-v4-001-attempt-1-run-e673c9d05e60.md +++ /dev/null @@ -1,3 +0,0 @@ -# role-ta-live-v4-001-attempt-1-run-e673c9d05e60 - -Forge 이슈 작업 브랜치 `forge/role-ta-live-v4-001-attempt-1-run-e673c9d05e60`. diff --git a/docs/adr/ADR-001-spring-boundary-smoke.adoc b/docs/adr/ADR-001-spring-boundary-smoke.adoc deleted file mode 100644 index 43b90bf..0000000 --- a/docs/adr/ADR-001-spring-boundary-smoke.adoc +++ /dev/null @@ -1,152 +0,0 @@ -= ADR-001: TA 역할 Spring 경계 Smoke 테스트 설계 -:doctype: architecture-decision-record -:status: accepted -:date: 2025-07-14 -:deciders: TA - -== Context - -TA(Tech Architect) 역할은 Spring 기반 마이크로서비스 아키텍처에서 Controller-Service-Repository 경계의 명확한 분리와 오류 계약, 트랜잭션 경계를 정의해야 한다. - -현재 시스템은 다음 요구사항을 만족해야 한다: - -* **경계 명확성**: Controller는 외부 요청을 수신하고, Service는 비즈니스 로직을 수행하며, Repository는 데이터 접근을 담당한다. -* **오류 계약**: 각 계층 간 일관된 예외 처리와 오류 응답 구조를 보장한다. -* **트랜잭션 경계**: 데이터 일관성을 유지하면서 필요한 범위에서만 트랜잭션을 적용한다. - -== Decision - -=== 1. Controller-Service-Repository 경계 정의 - -[cols="1,2,3"] -|=== -| 계층 | 책임 |Forbidden Dependencies - -| `*Controller*` | HTTP 요청/응답 변환, 입력 검증, HTTP 상태 코드 관리 | Service 직접 호출 불가, Repository 직접 접근 금지 - -| `*Service*` | 비즈니스 로직 수행, 도메인 규칙 적용, 트랜잭션 관리 | Controller 직접 참조 불가, Web 관련 어노테이션 사용 금지 - -| `*Repository*` | 데이터 접근 추상화, JPA Entity 관리, 쿼리 실행 | 비즈니스 로직 포함 금지, HTTP 관련 코드 금지 -|=== - -==== 경계 규칙 - -* **Controller → Service**: DTO를 통해 통신, Service 인터페이스 또는 구체 클래스를 직접 호출 가능 -* **Service → Repository**: 도메인 Entity 또는 DTO를 전달, JPA Repository 인터페이스 호출 -* **하위 계층 → 상위 계층**: 의존성 없음 (Repository는 Service를 모름, Service는 Controller를 모름) - -=== 2. 오류 계약 정의 - -[cols="1,2,3"] -|=== -| 오류 유형 | 발생 계층 | HTTP 응답 - -| `*ValidationException*` | Controller | 400 Bad Request + `{ "code": "VALIDATION_ERROR", "message": "..." }` - -| `*ResourceNotFoundException*` | Service | 404 Not Found + `{ "code": "NOT_FOUND", "message": "..." }` - -| `*BusinessException*` | Service | 409 Conflict 또는 422 + `{ "code": "BUSINESS_ERROR", "message": "..." }` - -| `*DataAccessException*` | Repository | 500 Internal Server Error + `{ "code": "DB_ERROR", "message": "..." }` - -| `*UnexpectedException*` | Any | 500 Internal Server Error + `{ "code": "INTERNAL_ERROR", "message": "..." }` -|=== - -==== 오류 계약 규칙 - -* 모든 예외는 `RuntimeException`을 기반으로 한다 -* ControllerAdvice에서 전역 예외 처리를 수행한다 -* 오류 응답은 `ErrorResponse` DTO로 통일한다 -* 내부 예외 메시지는 로그에만 기록하고 클라이언트에는 노출하지 않는다 - -[source,java] ----- -// ErrorResponse DTO 구조 -public record ErrorResponse( - String code, - String message, - LocalDateTime timestamp, - String path -) {} ----- - -=== 3. 트랜잭션 경계 정의 - -[cols="1,2,3"] -|=== -| 범위 | 적용 위치 | 전파 행동 - -| `*ReadOnly Transaction*` | Service 조회 메서드 | `readOnly = true`, `propagation = REQUIRED` - -| `*Write Transaction*` | Service 변경 메서드 | `readOnly = false`, `propagation = REQUIRED` - -| `*Nested Transaction*` | 복잡한业务流程 | `propagation = REQUIRES_NEW` (선택적) -|=== - -==== 트랜잭션 규칙 - -* **트랜잭션 시작점**: Service 계층의 public 메서드 -* **트랜잭션 종료점**: Service 메서드 종료 시 자동 커밋 또는 롤백 -* **Rollback 조건**: unchecked exception (`RuntimeException`) 발생 시 자동 롤백 -* **Checked exception**: 명시적 `rollbackFor` 지정 필요 - -[source,java] ----- -@Service -@Transactional(readOnly = true) -public class MemberService { - - @Transactional - public Member createMember(CreateMemberCommand command) { - // 비즈니스 로직 - return memberRepository.save(member); - } - - @Transactional - public void updateMember(Long id, UpdateMemberCommand command) { - Member member = findByIdOrThrow(id); - member.update(command); - } -} ----- - -== Alternatives - -=== 대안 1: Controller에서 트랜잭션 관리 - -* **설명**: `@Transactional`을 Controller에 적용 -* **단점**: HTTP 요청 스레드와 트랜잭션 수명이 불일치, Connection 유출 위험 -* **채택 안 함**: Spring Best Practice 위반 - -=== 대안 2: 예외를 Service에서 직접 HTTP 응답으로 변환 - -* **설명**: Service에서 `ResponseEntity` 반환 -* **단점**: Service가 Web 계층에 강결합, 단위 테스트 어려움 -* **채택 안 함**: 계층 분리 원칙 위반 - -=== 대안 3: 모든 계층에서 예외 처리 - -* **설명**: 각 계층마다 try-catch로 예외 처리 -* **단점**: 코드 중복, 일관성 없는 오류 응답 -* **채택 안 함**: 비효율적이며 유지보수困难 - -== Consequences - -=== 긍정적 Consequences - -* **단일 책임 원칙 준수**: 각 계층이 명확한 역할을 담당하여 코드 가독성 향상 -* **테스트 용이성**: 계층별 Mock을 통한 단위 테스트 용이 -* **일관된 오류 처리**: 전역 예외 처리로 일관된 API 오류 응답 보장 -* **트랜잭션 관리 용이**: Service 계층에서 집중 관리로 데이터 일관성 확보 - -=== 부정적 Consequences - -* **DTO 증가**: 계층 간 통신을 위한 DTO 클래스 증가 -* **추가 학습 곡선**: 개발자가 경계 규칙과 예외 계층 구조를 이해해야 함 -* **잠재적 성능 오버헤드**: DTO 변환 과정에서의 약간의 오버헤드 - -=== 모니터링 및 검증 - -* **Smoke Test**: 각 계층 경계에서 정상/오류 흐름 검증 -* **Integration Test**: Controller → Service → Repository 전체 흐름 검증 -* **트랜잭션 검증**: 롤백 시 데이터 무결성 확인