forge-bot/runtime-role-matrix-live-202607141522
1
0
Fork 0
Code Issues Pull requests 5 Projects Releases Packages Wiki Activity Actions

TA 역할 Spring 경계 smoke #6

Open
forge-bot wants to merge 9 commits from forge/role-ta-live-1522-001-attempt-2-run-af8c24005cdb into main
pull from: forge/role-ta-live-1522-001-attempt-2-run-af8c24005cdb
merge into: forge-bot:main
Conversation 0 Commits 9 Files changed 9 +532
9 changed files with 532 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

3
.forge/role-ta-live-1522-001-attempt-2-run-af8c24005cdb.md Normal file
View file

@ -0,0 +1,3 @@
# role-ta-live-1522-001-attempt-2-run-af8c24005cdb
Forge 이슈 작업 브랜치 `forge/role-ta-live-1522-001-attempt-2-run-af8c24005cdb`.

126
docs/adr/ADR-001-spring-architecture-boundaries.md Normal file
View file

@ -0,0 +1,126 @@
# ADR-001: Spring MVC 경계, 오류 계약 및 트랜잭션 경계
## 상태
**수용됨** — 2026-07-14
## 컨텍스트
본 프로젝트는 역할 기반 접근 제어(RBAC) 매트릭스를 런타임에 관리하는 Spring Boot 애플리케이션이다.
복잡한 도메인 로직과 다중 데이터 소스를 다루며, 명확한 계층 경계와 일관된 오류 처리가 필수적이다.
### 현재 문제점
- Controller에서 직접 Repository 호출 → 테스트 불가능한 구조
- 예외 처리가 각 계층에 산재 → 일관된 API 응답 불가
- 트랜잭션 경계가 불명확 → 데이터 불일치 위험
## 결정
### 1. Controller-Service-Repository 경계
```
┌─────────────────────────────────────────────────────────────┐
│ Controller Layer │
│ • HTTP 요청/응답 변환 │
│ • 입력 검증 (Bean Validation) │
│ • HTTP 상태 코드 결정 │
│ • DTO 변환 (Request → Command, Response ← Result) │
│ ❌ 비즈니스 로직 금지 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Service Layer │
│ • 비즈니스 로직 수행 │
│ • 도메인 객체 조작 │
│ • @Transactional 경계 관리 │
│ • 도메인 예외 발생 (DomainException) │
│ ❌ HTTP/프레젠테션 concerns 금지 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Repository Layer │
│ • 데이터 접근 추상화 (JPA Repository) │
│ • 엔티티 ↔ 도메인 객체 변환 │
│ • 쿼리 메서드 정의 │
│ ❌ 비즈니스 로직 금지 │
└─────────────────────────────────────────────────────────────┘
```
**경계 규칙:**
- Controller → Service: Command/DTO 전달, Result/DTO 수신
- Service → Repository: 도메인 객체 또는 ID 전달, 도메인 객체 수신
- 하위 계층이 상위 계층을 직접 참조 금지 (의존성 역전)
### 2. 오류 계약 (Error Contract)
#### 2.1 표준 오류 응답 형식
```json
{
"timestamp": "2026-07-14T15:22:00Z",
"status": 400,
"error": "Bad Request",
"code": "ROLE_MATRIX_001",
"message": "역할 매트릭스 이름은 필수입니다",
"path": "/api/v1/role-matrices",
"traceId": "abc123"
}
```
#### 2.2 예외 계층 구조
```
Throwable
└── RuntimeException
└── GlobalException (공통 기반 예외)
├── DomainException (도메인业务 예외)
│ ├── RoleMatrixNotFoundException
│ ├── RoleNotFoundException
│ └── DuplicateRoleMatrixException
├── ValidationException (검증 예외)
└── InfrastructureException (인프라 예외)
├── DataAccessException
└── ExternalServiceException
```
#### 2.3 예외-상태코드 매핑
| 예외 클래스 | HTTP 상태 | 오류 코드 접두사 |
|------------|-----------|------------------|
| ValidationException | 400 | VAL_ |
| DomainException | 400/409 | DOM_ |
| RoleMatrixNotFoundException | 404 | NOT_FOUND_ |
| DuplicateRoleMatrixException | 409 | CONFLICT_ |
| InfrastructureException | 500/503 | SYS_ |
### 3. 트랜잭션 경계
| 작업 유형 | 트랜잭션 전파 | 격리 수준 | 읽기 전용 |
|----------|-------------|----------|----------|
| 조회 (SELECT) | REQUIRED | READ_COMMITTED | true |
| 단일 생성/수정/삭제 | REQUIRED | READ_COMMITTED | false |
| 다중 변경 (배치) | REQUIRED_NEW | READ_COMMITTED | false |
**롤백 규칙:**
- RuntimeException → 자동 롤백
- Checked Exception → 명시적 rollbackFor 필요
- DomainException (RuntimeException 하위) → 자동 롤백
## 대안들
### 대안 1: 트랜잭션 스크립트 패턴
- 모든 로직을 Controller에서 처리
- **단점:** 테스트 불가능, 결합도 높음
- **기각 이유:** 본 프로젝트 복잡도에서 유지보수 불가
## 결과
### 긍정적 결과
- **테스트 용이성:** Mock 기반 단위 테스트 가능
- **일관된 오류 처리:** 모든 API에서 동일한 오류 응답 형식
- **트랜잭션 명확성:** 어디서 롤백/커밋되는지 예측 가능
### 부정적 결과
- **추가 코드:** DTO, Mapper, Exception 클래스 증가
- **학습 곡선:** 개발자 교육 필요

50
src/main/java/com/klaroworks/runtime/rolematrix/controller/RoleMatrixController.java Normal file
View file

@ -0,0 +1,50 @@
package com.klaroworks.runtime.rolematrix.controller;
import com.klaroworks.runtime.rolematrix.dto.CreateRoleMatrixCommand;
import com.klaroworks.runtime.rolematrix.dto.RoleMatrixResponse;
import com.klaroworks.runtime.rolematrix.dto.UpdateRoleMatrixCommand;
import com.klaroworks.runtime.rolematrix.service.RoleMatrixService;
import jakarta.validation.Valid;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import java.util.List;
/** 역할 매트릭스 REST 컨트롤러 - HTTP 요청/응답 변환, 입력 검증 */
@RestController
@RequestMapping("/api/v1/role-matrices")
public class RoleMatrixController {
private final RoleMatrixService roleMatrixService;
public RoleMatrixController(RoleMatrixService roleMatrixService) {
this.roleMatrixService = roleMatrixService;
}
@GetMapping
public ResponseEntity<List<RoleMatrixResponse>> findAll() {
return ResponseEntity.ok(roleMatrixService.findAll());
}
@GetMapping("/{id}")
public ResponseEntity<RoleMatrixResponse> findById(@PathVariable Long id) {
return ResponseEntity.ok(roleMatrixService.findById(id));
}
@PostMapping
public ResponseEntity<RoleMatrixResponse> create(@Valid @RequestBody CreateRoleMatrixCommand command) {
return ResponseEntity.status(HttpStatus.CREATED).body(roleMatrixService.create(command));
}
@PutMapping("/{id}")
public ResponseEntity<RoleMatrixResponse> update(@PathVariable Long id, @Valid @RequestBody UpdateRoleMatrixCommand command) {
return ResponseEntity.ok(roleMatrixService.update(id, command));
}
@DeleteMapping("/{id}")
public ResponseEntity<Void> delete(@PathVariable Long id) {
roleMatrixService.delete(id);
return ResponseEntity.noContent().build();
}
}

69
src/main/java/com/klaroworks/runtime/rolematrix/domain/RoleMatrix.java Normal file
View file

@ -0,0 +1,69 @@
package com.klaroworks.runtime.rolematrix.domain;
import jakarta.persistence.*;
import java.time.Instant;
import java.util.ArrayList;
import java.util.List;
/** 역할 매트릭스 엔티티 */
@Entity
@Table(name = "role_matrices")
public class RoleMatrix {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
@Column(nullable = false, unique = true)
private String name;
@Column(length = 1000)
private String description;
@ElementCollection(fetch = FetchType.EAGER)
@CollectionTable(name = "role_matrix_permissions", joinColumns = @JoinColumn(name = "role_matrix_id"))
@Column(name = "permission_id")
private List<String> permissionIds = new ArrayList<>();
@Column(nullable = false, updatable = false)
private Instant createdAt;
@Column(nullable = false)
private Instant updatedAt;
@Version
private Long version;
protected RoleMatrix() {}
private RoleMatrix(String name, String description) {
this.name = name;
this.description = description;
this.createdAt = Instant.now();
this.updatedAt = Instant.now();
}
public static RoleMatrix create(String name, String description) {
return new RoleMatrix(name, description);
}
public void update(String name, String description) {
if (name != null) this.name = name;
if (description != null) this.description = description;
this.updatedAt = Instant.now();
}
public void syncPermissions(List<String> permissionIds) {
this.permissionIds.clear();
if (permissionIds != null) this.permissionIds.addAll(permissionIds);
this.updatedAt = Instant.now();
}
public Long getId() { return id; }
public String getName() { return name; }
public String getDescription() { return description; }
public List<String> getPermissionIds() { return List.copyOf(permissionIds); }
public Instant getCreatedAt() { return createdAt; }
public Instant getUpdatedAt() { return updatedAt; }
public Long getVersion() { return version; }
}

46
src/main/java/com/klaroworks/runtime/rolematrix/dto/Dtos.java Normal file
View file

@ -0,0 +1,46 @@
package com.klaroworks.runtime.rolematrix.dto;
import com.fasterxml.jackson.annotation.JsonFormat;
import com.fasterxml.jackson.annotation.JsonInclude;
import com.klaroworks.runtime.rolematrix.domain.RoleMatrix;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;
import java.time.Instant;
import java.util.List;
/** 표준 오류 응답 DTO */
@JsonInclude(JsonInclude.Include.NON_NULL)
public record ErrorResponse(
@JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd'T'HH:mm:ss'Z'", timezone = "UTC") Instant timestamp,
int status, String error, String code, String message, String path, String traceId
) {
public static ErrorResponse of(int status, String code, String message, String path, String traceId) {
return new ErrorResponse(Instant.now(), status, resolveErrorName(status), code, message, path, traceId);
}
private static String resolveErrorName(int status) {
return switch (status) { case 400 -> "Bad Request"; case 404 -> "Not Found"; case 409 -> "Conflict"; case 500 -> "Internal Server Error"; default -> "Error"; };
}
}
/** 역할 매트릭스 생성 명령 */
record CreateRoleMatrixCommand(
@NotBlank(message = "역할 매트릭스 이름은 필수입니다") @Size(max = 255) String name,
@Size(max = 1000) String description
) {}
/** 역할 매트릭스 수정 명령 */
record UpdateRoleMatrixCommand(
@Size(max = 255) String name,
@Size(max = 1000) String description
) {}
/** 역할 매트릭스 응답 */
@JsonInclude(JsonInclude.Include.NON_NULL)
record RoleMatrixResponse(
Long id, String name, String description, List<String> permissionIds, Instant createdAt, Instant updatedAt
) {
public static RoleMatrixResponse from(RoleMatrix entity) {
return new RoleMatrixResponse(entity.getId(), entity.getName(), entity.getDescription(), entity.getPermissionIds(), entity.getCreatedAt(), entity.getUpdatedAt());
}
}

72
src/main/java/com/klaroworks/runtime/rolematrix/exception/Exceptions.java Normal file
View file

@ -0,0 +1,72 @@
package com.klaroworks.runtime.rolematrix.exception;
import org.springframework.http.HttpStatus;
/** 도메인 예외 기본 클래스 */
public abstract class DomainException extends RuntimeException {
private final String errorCode;
private final HttpStatus defaultStatus;
protected DomainException(String message, String errorCode, HttpStatus defaultStatus) {
super(message);
this.errorCode = errorCode;
this.defaultStatus = defaultStatus;
}
protected DomainException(String message, String errorCode, HttpStatus defaultStatus, Throwable cause) {
super(message, cause);
this.errorCode = errorCode;
this.defaultStatus = defaultStatus;
}
public String getErrorCode() { return errorCode; }
public HttpStatus getDefaultStatus() { return defaultStatus; }
}
/** 역할 매트릭스를 찾을 수 없을 때 */
class RoleMatrixNotFoundException extends DomainException {
private final Long roleMatrixId;
public RoleMatrixNotFoundException(Long roleMatrixId) {
super(String.format("역할 매트릭스를 찾을 수 없습니다. ID: %d", roleMatrixId), "NOT_FOUND_ROLE_MATRIX", HttpStatus.NOT_FOUND);
this.roleMatrixId = roleMatrixId;
}
public Long getRoleMatrixId() { return roleMatrixId; }
}
/** 중복된 역할 매트릭스 */
class DuplicateRoleMatrixException extends DomainException {
private final String matrixName;
public DuplicateRoleMatrixException(String matrixName) {
super(String.format("이미 존재하는 역할 매트릭스입니다. 이름: %s", matrixName), "CONFLICT_DUPLICATE_MATRIX", HttpStatus.CONFLICT);
this.matrixName = matrixName;
}
public String getMatrixName() { return matrixName; }
}
/** 입력 검증 실패 */
class ValidationException extends RuntimeException {
private final String errorCode;
public ValidationException(String message) { super(message); this.errorCode = "VAL_INVALID_INPUT"; }
public ValidationException(String message, String errorCode) { super(message); this.errorCode = errorCode; }
public String getErrorCode() { return errorCode; }
}
/** 인프라 예외 기본 클래스 */
abstract class InfrastructureException extends RuntimeException {
private final String errorCode;
private final HttpStatus defaultStatus;
protected InfrastructureException(String message, String errorCode, HttpStatus defaultStatus) {
super(message); this.errorCode = errorCode; this.defaultStatus = defaultStatus;
}
protected InfrastructureException(String message, String errorCode, HttpStatus defaultStatus, Throwable cause) {
super(message, cause); this.errorCode = errorCode; this.defaultStatus = defaultStatus;
}
public String getErrorCode() { return errorCode; }
public HttpStatus getDefaultStatus() { return defaultStatus; }
}
/** 데이터베이스 접근 예외 */
class DataAccessException extends InfrastructureException {
public DataAccessException(String message) { super(message, "SYS_DATABASE_ERROR", HttpStatus.INTERNAL_SERVER_ERROR); }
public DataAccessException(String message, Throwable cause) { super(message, "SYS_DATABASE_ERROR", HttpStatus.INTERNAL_SERVER_ERROR, cause); }
}

74
src/main/java/com/klaroworks/runtime/rolematrix/exception/GlobalExceptionHandler.java Normal file
View file

@ -0,0 +1,74 @@
package com.klaroworks.runtime.rolematrix.exception;
import com.klaroworks.runtime.rolematrix.dto.ErrorResponse;
import jakarta.servlet.http.HttpServletRequest;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.slf4j.MDC;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.validation.FieldError;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import java.util.HashMap;
import java.util.Map;
import java.util.UUID;
/** 전역 예외 처리 핸들러 */
@RestControllerAdvice
public class GlobalExceptionHandler {
private static final Logger log = LoggerFactory.getLogger(GlobalExceptionHandler.class);
@ExceptionHandler(DomainException.class)
public ResponseEntity<ErrorResponse> handleDomainException(DomainException ex, HttpServletRequest request) {
String traceId = getOrGenerateTraceId();
MDC.put("traceId", traceId);
log.warn("Domain exception: {} [traceId={}]", ex.getMessage(), traceId, ex);
return ResponseEntity.status(ex.getDefaultStatus())
.body(ErrorResponse.of(ex.getDefaultStatus().value(), ex.getErrorCode(), ex.getMessage(), request.getRequestURI(), traceId));
}
@ExceptionHandler(ValidationException.class)
public ResponseEntity<ErrorResponse> handleValidationException(ValidationException ex, HttpServletRequest request) {
String traceId = getOrGenerateTraceId();
log.warn("Validation exception: {} [traceId={}]", ex.getMessage(), traceId);
return ResponseEntity.badRequest()
.body(ErrorResponse.of(HttpStatus.BAD_REQUEST.value(), ex.getErrorCode(), ex.getMessage(), request.getRequestURI(), traceId));
}
@ExceptionHandler(MethodArgumentNotValidException.class)
public ResponseEntity<ErrorResponse> handleMethodArgumentNotValid(MethodArgumentNotValidException ex, HttpServletRequest request) {
String traceId = getOrGenerateTraceId();
Map<String, String> fieldErrors = new HashMap<>();
for (FieldError error : ex.getBindingResult().getFieldErrors()) {
fieldErrors.put(error.getField(), error.getDefaultMessage());
}
log.warn("Bean validation failed: {} [traceId={}]", fieldErrors, traceId);
return ResponseEntity.badRequest()
.body(ErrorResponse.of(HttpStatus.BAD_REQUEST.value(), "VAL_BEAN_VALIDATION", "입력 검증에 실패했습니다: " + fieldErrors, request.getRequestURI(), traceId));
}
@ExceptionHandler(InfrastructureException.class)
public ResponseEntity<ErrorResponse> handleInfrastructureException(InfrastructureException ex, HttpServletRequest request) {
String traceId = getOrGenerateTraceId();
log.error("Infrastructure exception: {} [traceId={}]", ex.getMessage(), traceId, ex);
return ResponseEntity.status(ex.getDefaultStatus())
.body(ErrorResponse.of(ex.getDefaultStatus().value(), ex.getErrorCode(), ex.getMessage(), request.getRequestURI(), traceId));
}
@ExceptionHandler(Exception.class)
public ResponseEntity<ErrorResponse> handleUnknownException(Exception ex, HttpServletRequest request) {
String traceId = getOrGenerateTraceId();
log.error("Unexpected exception: {} [traceId={}]", ex.getMessage(), traceId, ex);
return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
.body(ErrorResponse.of(500, "SYS_INTERNAL_ERROR", "예상치 못한 오류가 발생했습니다. 관리자에게 문의하세요.", request.getRequestURI(), traceId));
}
private String getOrGenerateTraceId() {
String existing = MDC.get("traceId");
return existing != null ? existing : UUID.randomUUID().toString().substring(0, 8);
}
}

13
src/main/java/com/klaroworks/runtime/rolematrix/repository/RoleMatrixRepository.java Normal file
View file

@ -0,0 +1,13 @@
package com.klaroworks.runtime.rolematrix.repository;
import com.klaroworks.runtime.rolematrix.domain.RoleMatrix;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;
import java.util.Optional;
/** 역할 매트릭스 JPA 리포지토리 */
@Repository
public interface RoleMatrixRepository extends JpaRepository<RoleMatrix, Long> {
Optional<RoleMatrix> findByName(String name);
boolean existsByName(String name);
}

79
src/main/java/com/klaroworks/runtime/rolematrix/service/RoleMatrixService.java Normal file
View file

@ -0,0 +1,79 @@
package com.klaroworks.runtime.rolematrix.service;
import com.klaroworks.runtime.rolematrix.domain.RoleMatrix;
import com.klaroworks.runtime.rolematrix.dto.CreateRoleMatrixCommand;
import com.klaroworks.runtime.rolematrix.dto.RoleMatrixResponse;
import com.klaroworks.runtime.rolematrix.dto.UpdateRoleMatrixCommand;
import com.klaroworks.runtime.rolematrix.exception.DomainException;
import com.klaroworks.runtime.rolematrix.repository.RoleMatrixRepository;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Propagation;
import org.springframework.transaction.annotation.Transactional;
import java.util.List;
/** 역할 매트릭스 서비스 - 비즈니스 로직 및 트랜잭션 경계 관리 */
@Service
@Transactional(readOnly = true)
public class RoleMatrixService {
private static final Logger log = LoggerFactory.getLogger(RoleMatrixService.class);
private final RoleMatrixRepository roleMatrixRepository;
public RoleMatrixService(RoleMatrixRepository roleMatrixRepository) {
this.roleMatrixRepository = roleMatrixRepository;
}
public List<RoleMatrixResponse> findAll() {
log.debug("Finding all role matrices");
return roleMatrixRepository.findAll().stream().map(RoleMatrixResponse::from).toList();
}
public RoleMatrixResponse findById(Long id) {
log.debug("Finding role matrix by id: {}", id);
return roleMatrixRepository.findById(id)
.map(RoleMatrixResponse::from)
.orElseThrow(() -> new RoleMatrixNotFoundException(id));
}
@Transactional
public RoleMatrixResponse create(CreateRoleMatrixCommand command) {
log.info("Creating role matrix: {}", command.name());
if (roleMatrixRepository.existsByName(command.name())) {
throw new DuplicateRoleMatrixException(command.name());
}
RoleMatrix saved = roleMatrixRepository.save(RoleMatrix.create(command.name(), command.description()));
log.info("Role matrix created with id: {}", saved.getId());
return RoleMatrixResponse.from(saved);
}
@Transactional
public RoleMatrixResponse update(Long id, UpdateRoleMatrixCommand command) {
log.info("Updating role matrix: {}", id);
RoleMatrix matrix = roleMatrixRepository.findById(id)
.orElseThrow(() -> new RoleMatrixNotFoundException(id));
if (command.name() != null && !command.name().equals(matrix.getName()) && roleMatrixRepository.existsByName(command.name())) {
throw new DuplicateRoleMatrixException(command.name());
}
matrix.update(command.name(), command.description());
return RoleMatrixResponse.from(roleMatrixRepository.save(matrix));
}
@Transactional
public void delete(Long id) {
log.info("Deleting role matrix: {}", id);
if (!roleMatrixRepository.existsById(id)) throw new RoleMatrixNotFoundException(id);
roleMatrixRepository.deleteById(id);
}
@Transactional(propagation = Propagation.REQUIRES_NEW)
public void syncPermissions(Long roleMatrixId, List<String> permissionIds) {
log.info("Syncing permissions for role matrix: {}", roleMatrixId);
RoleMatrix matrix = roleMatrixRepository.findById(roleMatrixId)
.orElseThrow(() -> new RoleMatrixNotFoundException(roleMatrixId));
matrix.syncPermissions(permissionIds);
roleMatrixRepository.save(matrix);
}
}