20260422 #27 행성 지역 해금 도메인 구현

CLAUDE.md

@@ -225,6 +225,7 @@ log.warn("[Action] 경고 설명");
 | 0.0.34 | `V0_0_34__add_todos_and_categories.sql` | `todos`, `todo_categories` 테이블 생성 (FK CASCADE, JSONB 컬럼) |
 | 0.0.36 | `V0_0_36__add_fuel.sql` | `user_fuel`, `fuel_transactions` 테이블 생성 (CHECK 제약, FK CASCADE) |
 | 0.0.39 | `V0_0_39__add_timer_sessions.sql` | `timer_sessions` 테이블 생성 (FK CASCADE, CHECK 제약 3종, 부분 unique 인덱스 on idempotency_key) |
+| 0.0.42 | `V0_0_42__add_exploration.sql` | `exploration_nodes`, `user_exploration_progress` 테이블 + 행성/지역 시드 38노드 (프론트 시드 미러, self-FK, FK CASCADE, UNIQUE) |
 
 ---
 

SS-Common/build.gradle

@@ -16,7 +16,8 @@ dependencies {
 	api 'org.springframework.boot:spring-boot-starter-actuator'
 	api 'org.springframework.boot:spring-boot-starter-security'
 
-	// Flyway
+	// Flyway (Spring Boot 4: autoconfiguration이 spring-boot-flyway 모듈로 분리됨 — 없으면 마이그레이션 미실행)
+	api 'org.springframework.boot:spring-boot-flyway'
 	api 'org.flywaydb:flyway-core'
 	api 'org.flywaydb:flyway-database-postgresql'
 

SS-Common/src/main/java/com/elipair/spacestudyship/common/exception/ErrorCode.java

@@ -41,6 +41,13 @@ public enum ErrorCode {
     SESSION_TOO_LONG(HttpStatus.BAD_REQUEST, "공부 시간은 24시간(1440분)을 초과할 수 없습니다."),
     FUTURE_SESSION(HttpStatus.BAD_REQUEST, "미래 시각의 세션은 저장할 수 없습니다."),
 
+    // Exploration
+    PLANET_NOT_FOUND(HttpStatus.NOT_FOUND, "해당 행성을 찾을 수 없습니다."),
+    REGION_NOT_FOUND(HttpStatus.NOT_FOUND, "해당 지역을 찾을 수 없습니다."),
+    ALREADY_UNLOCKED(HttpStatus.BAD_REQUEST, "이미 해금된 노드입니다."),
+    PLANET_LOCKED(HttpStatus.BAD_REQUEST, "상위 행성이 아직 해금되지 않았습니다."),
+    PREREQUISITE_NOT_CLEARED(HttpStatus.BAD_REQUEST, "이전 행성을 먼저 클리어해야 합니다."),
+
     // Common
     INVALID_INPUT_VALUE(HttpStatus.BAD_REQUEST, "입력값이 유효하지 않습니다."),
     INVALID_REQUEST_BODY(HttpStatus.BAD_REQUEST, "요청 본문의 형식이 잘못되었습니다."),

SS-Common/src/main/java/com/elipair/spacestudyship/common/exception/ErrorResponse.java

@@ -1,14 +1,23 @@
 package com.elipair.spacestudyship.common.exception;
 
+import com.fasterxml.jackson.annotation.JsonInclude;
+
+@JsonInclude(JsonInclude.Include.NON_NULL)
 public record ErrorResponse(
         String code,
-        String message
+        String message,
+        Integer requiredFuel,
+        Integer currentFuel
 ) {
     public static ErrorResponse of(ErrorCode errorCode) {
-        return new ErrorResponse(errorCode.name(), errorCode.getMessage());
+        return new ErrorResponse(errorCode.name(), errorCode.getMessage(), null, null);
     }
 
     public static ErrorResponse of(ErrorCode errorCode, String message) {
-        return new ErrorResponse(errorCode.name(), message);
+        return new ErrorResponse(errorCode.name(), message, null, null);
+    }
+
+    public static ErrorResponse ofInsufficientFuel(String message, int requiredFuel, int currentFuel) {
+        return new ErrorResponse(ErrorCode.INSUFFICIENT_FUEL.name(), message, requiredFuel, currentFuel);
     }
 }

SS-Common/src/main/java/com/elipair/spacestudyship/common/exception/GlobalExceptionHandler.java

@@ -27,6 +27,16 @@ public ResponseEntity<ErrorResponse> handleCustomException(CustomException ex) {
                 .body(ErrorResponse.of(errorCode));
     }
 
+    @ExceptionHandler(InsufficientFuelException.class)
+    public ResponseEntity<ErrorResponse> handleInsufficientFuel(InsufficientFuelException ex) {
+        log.info("[Exception] 연료 부족 | required={}, current={}", ex.getRequiredFuel(), ex.getCurrentFuel());
+        return ResponseEntity
+                .status(ErrorCode.INSUFFICIENT_FUEL.getHttpStatus())
+                .body(ErrorResponse.ofInsufficientFuel(
+                        ErrorCode.INSUFFICIENT_FUEL.getMessage(),
+                        ex.getRequiredFuel(), ex.getCurrentFuel()));
+    }
+
     @ExceptionHandler(MethodArgumentNotValidException.class)
     public ResponseEntity<ErrorResponse> handleValidationException(MethodArgumentNotValidException ex) {
         String detail = ex.getBindingResult().getFieldErrors().stream()

SS-Common/src/main/java/com/elipair/spacestudyship/common/exception/InsufficientFuelException.java

@@ -0,0 +1,16 @@
+package com.elipair.spacestudyship.common.exception;
+
+import lombok.Getter;
+
+@Getter
+public class InsufficientFuelException extends RuntimeException {
+
+    private final int requiredFuel;
+    private final int currentFuel;
+
+    public InsufficientFuelException(int requiredFuel, int currentFuel) {
+        super(ErrorCode.INSUFFICIENT_FUEL.getMessage());
+        this.requiredFuel = requiredFuel;
+        this.currentFuel = currentFuel;
+    }
+}

SS-Common/src/test/java/com/elipair/spacestudyship/common/exception/ErrorResponseTest.java

@@ -0,0 +1,53 @@
+package com.elipair.spacestudyship.common.exception;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class ErrorResponseTest {
+
+    private final ObjectMapper objectMapper = new ObjectMapper();
+
+    @Test
+    @DisplayName("of(ErrorCode): requiredFuel/currentFuel은 null")
+    void of_basic_nullFuelFields() {
+        ErrorResponse r = ErrorResponse.of(ErrorCode.PLANET_NOT_FOUND);
+        assertThat(r.code()).isEqualTo("PLANET_NOT_FOUND");
+        assertThat(r.requiredFuel()).isNull();
+        assertThat(r.currentFuel()).isNull();
+    }
+
+    @Test
+    @DisplayName("ofInsufficientFuel: 연료 수치 포함")
+    void ofInsufficientFuel_includesAmounts() {
+        ErrorResponse r = ErrorResponse.ofInsufficientFuel("연료가 부족합니다.", 10, 4);
+        assertThat(r.code()).isEqualTo("INSUFFICIENT_FUEL");
+        assertThat(r.requiredFuel()).isEqualTo(10);
+        assertThat(r.currentFuel()).isEqualTo(4);
+    }
+
+    @Test
+    @DisplayName("InsufficientFuelException: 게터로 수치 노출")
+    void exception_getters() {
+        InsufficientFuelException ex = new InsufficientFuelException(10, 4);
+        assertThat(ex.getRequiredFuel()).isEqualTo(10);
+        assertThat(ex.getCurrentFuel()).isEqualTo(4);
+    }
+
+    @Test
+    @DisplayName("@JsonInclude(NON_NULL): null 연료 필드는 JSON에서 제외, 연료 필드 있으면 JSON에 포함")
+    void jsonInclude_nonNull_wireContract() throws Exception {
+        String basicJson = objectMapper.writeValueAsString(ErrorResponse.of(ErrorCode.MEMBER_NOT_FOUND));
+        assertThat(basicJson).doesNotContain("requiredFuel");
+        assertThat(basicJson).doesNotContain("currentFuel");
+
+        String fuelJson = objectMapper.writeValueAsString(
+                ErrorResponse.ofInsufficientFuel("연료가 부족합니다.", 10, 4));
+        assertThat(fuelJson).contains("requiredFuel");
+        assertThat(fuelJson).contains("currentFuel");
+        assertThat(fuelJson).contains("10");
+        assertThat(fuelJson).contains("4");
+    }
+}

SS-Study/src/main/java/com/elipair/spacestudyship/study/exploration/constant/NodeType.java

@@ -0,0 +1,15 @@
+package com.elipair.spacestudyship.study.exploration.constant;
+
+public enum NodeType {
+    PLANET,
+    REGION;
+
+    /** DB 컬럼/JSON 직렬화용 소문자 표현 ("planet" / "region"). */
+    public String value() {
+        return name().toLowerCase();
+    }
+
+    public static NodeType from(String value) {
+        return NodeType.valueOf(value.toUpperCase());
+    }
+}

SS-Study/src/main/java/com/elipair/spacestudyship/study/exploration/constant/NodeTypeConverter.java

@@ -0,0 +1,18 @@
+package com.elipair.spacestudyship.study.exploration.constant;
+
+import jakarta.persistence.AttributeConverter;
+import jakarta.persistence.Converter;
+
+@Converter
+public class NodeTypeConverter implements AttributeConverter<NodeType, String> {
+
+    @Override
+    public String convertToDatabaseColumn(NodeType attribute) {
+        return attribute == null ? null : attribute.value();
+    }
+
+    @Override
+    public NodeType convertToEntityAttribute(String dbData) {
+        return dbData == null ? null : NodeType.from(dbData);
+    }
+}

SS-Study/src/main/java/com/elipair/spacestudyship/study/exploration/dto/PlanetResponse.java

@@ -0,0 +1,36 @@
+package com.elipair.spacestudyship.study.exploration.dto;
+
+import com.elipair.spacestudyship.study.exploration.entity.ExplorationNode;
+import io.swagger.v3.oas.annotations.media.Schema;
+
+import java.time.LocalDateTime;
+import java.time.ZoneOffset;
+import java.time.format.DateTimeFormatter;
+
+@Schema(description = "행성 응답")
+public record PlanetResponse(
+        String id, String name, String nodeType, int depth, String icon,
+        @Schema(nullable = true) String parentId,
+        @Schema(nullable = true) String prerequisiteId,
+        int requiredFuel, boolean isUnlocked, boolean isCleared, int sortOrder,
+        String description, double mapX, double mapY,
+        @Schema(nullable = true, example = "2026-04-01T00:00:00Z") String unlockedAt,
+        ProgressDto progress
+) {
+    private static final DateTimeFormatter ISO_UTC = DateTimeFormatter.ISO_INSTANT;
+
+    public static PlanetResponse of(ExplorationNode n, boolean isUnlocked, boolean isCleared,
+                                    int clearedChildren, int totalChildren, double progressRatio,
+                                    LocalDateTime unlockedAt) {
+        return new PlanetResponse(
+                n.getId(), n.getName(), n.getNodeType().value(), n.getDepth(), n.getIcon(),
+                n.getParentId(), n.getPrerequisiteNodeId(), n.getRequiredFuel(),
+                isUnlocked, isCleared, n.getSortOrder(), n.getDescription(), n.getMapX(), n.getMapY(),
+                formatUtc(unlockedAt),
+                new ProgressDto(clearedChildren, totalChildren, progressRatio));
+    }
+
+    private static String formatUtc(LocalDateTime time) {
+        return time == null ? null : ISO_UTC.format(time.toInstant(ZoneOffset.UTC));
+    }
+}

SS-Study/src/main/java/com/elipair/spacestudyship/study/exploration/dto/PlanetUnlockResponse.java

@@ -0,0 +1,17 @@
+package com.elipair.spacestudyship.study.exploration.dto;
+
+import com.elipair.spacestudyship.study.exploration.entity.ExplorationNode;
+import com.elipair.spacestudyship.study.exploration.entity.UserExploration;
+import io.swagger.v3.oas.annotations.media.Schema;
+
+@Schema(description = "행성 해금 응답")
+public record PlanetUnlockResponse(
+        UnlockedNodeDto planet, int fuelConsumed, int currentFuel
+) {
+    public static PlanetUnlockResponse of(ExplorationNode planet, UserExploration progress,
+                                          int fuelConsumed, int currentFuel) {
+        return new PlanetUnlockResponse(
+                UnlockedNodeDto.of(planet, progress, false),
+                fuelConsumed, currentFuel);
+    }
+}

SS-Study/src/main/java/com/elipair/spacestudyship/study/exploration/dto/ProgressDto.java

@@ -0,0 +1,10 @@
+package com.elipair.spacestudyship.study.exploration.dto;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+@Schema(description = "행성 진행도")
+public record ProgressDto(
+        @Schema(example = "3") int clearedChildren,
+        @Schema(example = "5") int totalChildren,
+        @Schema(example = "0.6") double progressRatio
+) {}

SS-Study/src/main/java/com/elipair/spacestudyship/study/exploration/dto/RegionResponse.java

@@ -0,0 +1,32 @@
+package com.elipair.spacestudyship.study.exploration.dto;
+
+import com.elipair.spacestudyship.study.exploration.entity.ExplorationNode;
+import io.swagger.v3.oas.annotations.media.Schema;
+
+import java.time.LocalDateTime;
+import java.time.ZoneOffset;
+import java.time.format.DateTimeFormatter;
+
+@Schema(description = "지역 응답")
+public record RegionResponse(
+        String id, String name, String nodeType, int depth, String icon,
+        @Schema(nullable = true) String parentId,
+        int requiredFuel, boolean isUnlocked, boolean isCleared, int sortOrder,
+        String description, double mapX, double mapY,
+        @Schema(nullable = true, example = "2026-04-05T15:30:00Z") String unlockedAt
+) {
+    private static final DateTimeFormatter ISO_UTC = DateTimeFormatter.ISO_INSTANT;
+
+    public static RegionResponse of(ExplorationNode n, boolean isUnlocked, boolean isCleared,
+                                    LocalDateTime unlockedAt) {
+        return new RegionResponse(
+                n.getId(), n.getName(), n.getNodeType().value(), n.getDepth(), n.getIcon(),
+                n.getParentId(), n.getRequiredFuel(), isUnlocked, isCleared,
+                n.getSortOrder(), n.getDescription(), n.getMapX(), n.getMapY(),
+                formatUtc(unlockedAt));
+    }
+
+    private static String formatUtc(LocalDateTime time) {
+        return time == null ? null : ISO_UTC.format(time.toInstant(ZoneOffset.UTC));
+    }
+}

SS-Study/src/main/java/com/elipair/spacestudyship/study/exploration/dto/RegionUnlockResponse.java

@@ -0,0 +1,17 @@
+package com.elipair.spacestudyship.study.exploration.dto;
+
+import com.elipair.spacestudyship.study.exploration.entity.ExplorationNode;
+import com.elipair.spacestudyship.study.exploration.entity.UserExploration;
+import io.swagger.v3.oas.annotations.media.Schema;
+
+@Schema(description = "지역 해금 응답")
+public record RegionUnlockResponse(
+        UnlockedNodeDto region, int fuelConsumed, int currentFuel, boolean planetCleared
+) {
+    public static RegionUnlockResponse of(ExplorationNode region, UserExploration progress,
+                                          int fuelConsumed, int currentFuel, boolean planetCleared) {
+        return new RegionUnlockResponse(
+                UnlockedNodeDto.of(region, progress, true),
+                fuelConsumed, currentFuel, planetCleared);
+    }
+}

SS-Study/src/main/java/com/elipair/spacestudyship/study/exploration/dto/UnlockedNodeDto.java

@@ -0,0 +1,27 @@
+package com.elipair.spacestudyship.study.exploration.dto;
+
+import com.elipair.spacestudyship.study.exploration.entity.ExplorationNode;
+import com.elipair.spacestudyship.study.exploration.entity.UserExploration;
+import io.swagger.v3.oas.annotations.media.Schema;
+
+import java.time.LocalDateTime;
+import java.time.ZoneOffset;
+import java.time.format.DateTimeFormatter;
+
+@Schema(description = "해금된 노드 요약")
+public record UnlockedNodeDto(
+        String id, String name, boolean isUnlocked, boolean isCleared,
+        @Schema(example = "2026-04-16T11:00:00Z") String unlockedAt
+) {
+    private static final DateTimeFormatter ISO_UTC = DateTimeFormatter.ISO_INSTANT;
+
+    public static UnlockedNodeDto of(ExplorationNode node, UserExploration progress, boolean cleared) {
+        return new UnlockedNodeDto(
+                node.getId(), node.getName(), true, cleared,
+                formatUtc(progress.getUnlockedAt()));
+    }
+
+    private static String formatUtc(LocalDateTime time) {
+        return time == null ? null : ISO_UTC.format(time.toInstant(ZoneOffset.UTC));
+    }
+}

SS-Study/src/main/java/com/elipair/spacestudyship/study/exploration/entity/ExplorationNode.java

@@ -0,0 +1,61 @@
+package com.elipair.spacestudyship.study.exploration.entity;
+
+import com.elipair.spacestudyship.study.exploration.constant.NodeType;
+import com.elipair.spacestudyship.study.exploration.constant.NodeTypeConverter;
+import jakarta.persistence.Column;
+import jakarta.persistence.Convert;
+import jakarta.persistence.Entity;
+import jakarta.persistence.Id;
+import jakarta.persistence.Table;
+import lombok.AccessLevel;
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+@Entity
+@Table(name = "exploration_nodes")
+@Getter
+@Builder
+@AllArgsConstructor
+@NoArgsConstructor(access = AccessLevel.PROTECTED)
+public class ExplorationNode {
+
+    @Id
+    @Column(length = 50)
+    private String id;
+
+    @Column(nullable = false, length = 50)
+    private String name;
+
+    @Convert(converter = NodeTypeConverter.class)
+    @Column(name = "node_type", nullable = false, length = 10)
+    private NodeType nodeType;
+
+    @Column(nullable = false)
+    private int depth;
+
+    @Column(nullable = false, length = 30)
+    private String icon;
+
+    @Column(name = "parent_id", length = 50)
+    private String parentId;
+
+    @Column(name = "prerequisite_node_id", length = 50)
+    private String prerequisiteNodeId;
+
+    @Column(name = "required_fuel", nullable = false)
+    private int requiredFuel;
+
+    @Column(name = "sort_order", nullable = false)
+    private int sortOrder;
+
+    @Column(nullable = false, length = 200)
+    private String description;
+
+    @Column(name = "map_x", nullable = false)
+    private double mapX;
+
+    @Column(name = "map_y", nullable = false)
+    private double mapY;
+}