[feat] #9 - 온보딩 여행 정보 저장 API 구현

src/main/java/com/JJIN/domain/onboarding/controller/OnboardingController.java

@@ -0,0 +1,58 @@
+package com.JJIN.domain.onboarding.controller;
+
+import java.util.List;
+
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import com.JJIN.domain.onboarding.controller.docs.OnboardingControllerDocs;
+import com.JJIN.domain.onboarding.dto.request.OnboardingCompleteRequest;
+import com.JJIN.domain.onboarding.dto.response.OnboardingCompleteResponse;
+import com.JJIN.domain.onboarding.dto.response.TravelRegionResponse;
+import com.JJIN.domain.onboarding.exception.OnboardingSuccessCode;
+import com.JJIN.domain.onboarding.service.OnboardingService;
+import com.JJIN.global.auth.annotation.CurrentMember;
+import com.JJIN.global.auth.dto.CurrentAuth;
+import com.JJIN.global.auth.jwt.exception.TokenErrorCode;
+import com.JJIN.global.exception.JjinException;
+import com.JJIN.global.response.dto.SuccessResponse;
+
+import jakarta.validation.Valid;
+import lombok.RequiredArgsConstructor;
+
+@RestController
+@RequestMapping("/api/onboarding")
+@RequiredArgsConstructor
+public class OnboardingController implements OnboardingControllerDocs {
+
+	private final OnboardingService onboardingService;
+
+	@Override
+	@PostMapping
+	public ResponseEntity<SuccessResponse<OnboardingCompleteResponse>> completeOnboarding(
+		@CurrentMember CurrentAuth currentAuth,
+		@Valid @RequestBody OnboardingCompleteRequest request
+	) {
+		if (currentAuth == null) {
+			throw new JjinException(TokenErrorCode.INVALID_AUTHORIZATION_HEADER);
+		}
+		OnboardingCompleteResponse response = onboardingService.complete(currentAuth.memberId(), request);
+		return ResponseEntity.status(HttpStatus.CREATED)
+			.body(SuccessResponse.of(OnboardingSuccessCode.ONBOARDING_COMPLETE_SUCCESS, response));
+	}
+
+	@Override
+	@GetMapping("/regions")
+	public ResponseEntity<SuccessResponse<List<TravelRegionResponse>>> searchRegions(
+		@RequestParam(required = false) String keyword
+	) {
+		List<TravelRegionResponse> response = onboardingService.searchRegions(keyword);
+		return ResponseEntity.ok(SuccessResponse.of(OnboardingSuccessCode.REGION_LIST_SUCCESS, response));
+	}
+}

src/main/java/com/JJIN/domain/onboarding/controller/docs/OnboardingControllerDocs.java

@@ -0,0 +1,151 @@
+package com.JJIN.domain.onboarding.controller.docs;
+
+import java.util.List;
+
+import org.springframework.http.ResponseEntity;
+
+import com.JJIN.domain.onboarding.dto.request.OnboardingCompleteRequest;
+import com.JJIN.domain.onboarding.dto.response.OnboardingCompleteResponse;
+import com.JJIN.domain.onboarding.dto.response.TravelRegionResponse;
+import com.JJIN.global.auth.dto.CurrentAuth;
+import com.JJIN.global.response.dto.SuccessResponse;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.ExampleObject;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+/**
+ * 온보딩 API의 Swagger 문서 정의.
+ * 컨트롤러 본문에서 문서화 애노테이션을 분리하기 위한 인터페이스이며,
+ * 요청 매핑과 파라미터 바인딩 애노테이션은 구현 컨트롤러에 둔다.
+ */
+@Tag(name = "Onboarding", description = "온보딩 여행 기본 정보 API")
+public interface OnboardingControllerDocs {
+
+	@Operation(
+		summary = "온보딩 여행 기본 정보 저장",
+		description = """
+			온보딩 S1~S4에서 수집한 여행 기본 정보를 첫 번째 여행 일정으로 저장한다.
+			회원 역할 변경과 토큰 재발급은 /api/auth/role API에서 별도로 처리한다.
+
+			요청 필드
+			- regionId: 여행 지역 ID. regionUndecided가 true면 반드시 null, false면 regionId 필수
+			- regionUndecided: 지역 미정 여부
+			- startDate / endDate: 여행 기간. startDate는 Asia/Seoul 기준 오늘 이전 불가, endDate는 startDate 이상
+			- activityStartTime / activityEndTime: 하루 활동 시간(HH:mm). 시작 < 종료
+			- transportMode: 주 이동 수단 1개. WALKING, PUBLIC_TRANSIT, CAR
+			- preferences: 선택 가능한 TourAPI 관광타입 2~4개(중복 불가). 각 관광타입마다 그 타입에 속한 세부 취향을 1개 이상(중복 불가) 선택
+			  - contentType: TOURIST_ATTRACTION(12), CULTURAL_FACILITY(14), FESTIVAL_EVENT(15), LEISURE_SPORTS(28), SHOPPING(38), RESTAURANT(39)
+			  - TRAVEL_COURSE(25), LODGING(32)는 TourAPI enum에는 있지만 온보딩 취향 선택에서는 거부
+			  - subcategories:
+			    RESTAURANT(KOREAN_FOOD, CAFE_TEAHOUSE, PUB, LIKE_ALL_FOOD),
+			    TOURIST_ATTRACTION(TRADITIONAL_EXPERIENCE, TEMPLE_STAY, UNIQUE_EXPERIENCE, MOUNTAIN_FOREST, SEA_BEACH, LAKE_RIVER, ISLAND, PARK, PALACE, HISTORIC_SITE, TRADITIONAL_VILLAGE, STREET_ART, TEMPLE),
+			    CULTURAL_FACILITY(MUSEUM, GALLERY),
+			    FESTIVAL_EVENT(PERFORMANCE_MUSICAL, FESTIVAL_EVENT, PERFORMANCE_EVENT, FIREWORKS, NIGHT_MARKET),
+			    SHOPPING(TRADITIONAL_MARKET, LOCAL_SHOP, DUTY_FREE, VINTAGE),
+			    LEISURE_SPORTS(SURFING, SKIING, HIKING, CYCLING, WATER_SPORTS)
+			  - LIKE_ALL_FOOD는 RESTAURANT 안에서 다른 세부 취향과 함께 선택할 수 없다.
+			  - 내부적으로 각 세부 취향은 TourAPI contentTypeId와 lclsSystm1/2/3 검색 조건으로 매핑된다.
+			  - 요청 예: {"contentType":"RESTAURANT","subcategories":["KOREAN_FOOD","CAFE_TEAHOUSE"]}
+			- experienceLevel: LIGHT, NORMAL, DEEP
+			""",
+		security = @SecurityRequirement(name = "BearerAuth")
+	)
+	@ApiResponses({
+		@ApiResponse(
+			responseCode = "201",
+			description = "여행 기본 정보 설정 완료",
+			content = @Content(
+				mediaType = "application/json",
+				examples = @ExampleObject(value = """
+					{
+					  "status": 201,
+					  "message": "첫 여행 일정을 생성했습니다.",
+					  "data": {
+					    "travelPlanId": 1
+					  }
+					}
+					""")
+			)
+		),
+		@ApiResponse(
+			responseCode = "400",
+			description = "요청 값 또는 도메인 규칙 위반 (지역 선택, 여행 날짜, 활동 시간, 취향 선택)",
+			content = @Content(
+				mediaType = "application/json",
+				examples = @ExampleObject(value = """
+					{
+					  "status": 400,
+					  "message": "선택 가능한 TourAPI 관광타입은 중복 없이 2~4개를 선택해야 합니다."
+					}
+					""")
+			)
+		),
+		@ApiResponse(
+			responseCode = "401",
+			description = "인증 정보 누락 또는 유효하지 않은 액세스 토큰",
+			content = @Content(
+				mediaType = "application/json",
+				examples = @ExampleObject(value = """
+					{
+					  "status": 401,
+					  "message": "유효하지 않은 authorization 헤더입니다"
+					}
+					""")
+			)
+		),
+		@ApiResponse(
+			responseCode = "404",
+			description = "회원을 찾을 수 없음",
+			content = @Content(
+				mediaType = "application/json",
+				examples = @ExampleObject(value = """
+					{
+					  "status": 404,
+					  "message": "회원을 찾을 수 없습니다."
+					}
+					""")
+			)
+		),
+	})
+	ResponseEntity<SuccessResponse<OnboardingCompleteResponse>> completeOnboarding(
+		CurrentAuth currentAuth,
+		OnboardingCompleteRequest request
+	);
+
+	@Operation(
+		summary = "여행 지역 검색",
+		description = """
+			'기타' 지역 선택 시 여행 지역 표시명으로 검색한다.
+			keyword가 비어 있으면 빈 목록을 반환한다.
+			지역은 enum이 아니라 travel_region 테이블로 관리하며, TourAPI KorService2의 lDongRegnCd/lDongSignguCd를 함께 보관한다.
+			""",
+		security = @SecurityRequirement(name = "BearerAuth")
+	)
+	@ApiResponse(
+		responseCode = "200",
+		description = "여행 지역 검색 성공",
+		content = @Content(
+			mediaType = "application/json",
+			examples = @ExampleObject(value = """
+				{
+				  "status": 200,
+				  "message": "여행 지역 검색에 성공했습니다.",
+				  "data": [
+				    {
+				      "id": 1,
+				      "displayName": "서울",
+				      "lDongRegnCd": "11",
+				      "lDongSignguCd": null
+				    }
+				  ]
+				}
+				""")
+		)
+	)
+	ResponseEntity<SuccessResponse<List<TravelRegionResponse>>> searchRegions(String keyword);
+}

src/main/java/com/JJIN/domain/onboarding/dto/request/ContentTypePreferenceRequest.java

@@ -0,0 +1,31 @@
+package com.JJIN.domain.onboarding.dto.request;
+
+import java.util.List;
+
+import com.JJIN.domain.onboarding.entity.enums.TourApiContentType;
+import com.JJIN.domain.onboarding.entity.enums.TravelSubcategory;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.constraints.NotEmpty;
+import jakarta.validation.constraints.NotNull;
+
+@Schema(description = "TourAPI 관광타입 1개와 그 하위 온보딩 세부 취향 선택")
+public record ContentTypePreferenceRequest(
+
+	@Schema(
+		description = "TourAPI 관광타입. 온보딩 취향 선택에서는 TRAVEL_COURSE, LODGING을 선택할 수 없다.",
+		example = "RESTAURANT",
+		allowableValues = {"TOURIST_ATTRACTION", "CULTURAL_FACILITY", "FESTIVAL_EVENT",
+			"LEISURE_SPORTS", "SHOPPING", "RESTAURANT"}
+	)
+	@NotNull(message = "TourAPI 관광타입은 필수입니다.")
+	TourApiContentType contentType,
+
+	@Schema(
+		description = "해당 TourAPI 관광타입에 속한 세부 취향 목록 (최소 1개, 중복 불가)",
+		example = "[\"KOREAN_FOOD\", \"CAFE_TEAHOUSE\"]"
+	)
+	@NotEmpty(message = "세부 취향은 최소 1개 이상 선택해야 합니다.")
+	List<@NotNull(message = "세부 취향 값이 올바르지 않습니다.") TravelSubcategory> subcategories
+) {
+}

src/main/java/com/JJIN/domain/onboarding/dto/request/OnboardingCompleteRequest.java

@@ -0,0 +1,75 @@
+package com.JJIN.domain.onboarding.dto.request;
+
+import java.time.LocalDate;
+import java.time.LocalTime;
+import java.util.List;
+
+import org.springframework.format.annotation.DateTimeFormat;
+
+import com.JJIN.domain.onboarding.entity.enums.ExperienceLevel;
+import com.JJIN.domain.onboarding.entity.enums.TransportMode;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.Valid;
+import jakarta.validation.constraints.NotEmpty;
+import jakarta.validation.constraints.NotNull;
+
+@Schema(description = "온보딩 여행 기본 정보 저장 요청")
+public record OnboardingCompleteRequest(
+
+	@Schema(
+		description = "여행 지역 ID. regionUndecided가 true면 반드시 null이어야 한다.",
+		example = "1",
+		nullable = true
+	)
+	Long regionId,
+
+	@Schema(description = "지역 미정 여부", example = "false")
+	@NotNull(message = "지역 미정 여부는 필수입니다.")
+	Boolean regionUndecided,
+
+	@Schema(description = "여행 시작일 (Asia/Seoul 기준 오늘 이후)", example = "2026-07-22", type = "string", format = "date")
+	@NotNull(message = "여행 시작일은 필수입니다.")
+	@DateTimeFormat(iso = DateTimeFormat.ISO.DATE)
+	LocalDate startDate,
+
+	@Schema(description = "여행 종료일 (시작일과 같거나 이후)", example = "2026-07-25", type = "string", format = "date")
+	@NotNull(message = "여행 종료일은 필수입니다.")
+	@DateTimeFormat(iso = DateTimeFormat.ISO.DATE)
+	LocalDate endDate,
+
+	@Schema(description = "하루 활동 시작 시각 (HH:mm)", example = "09:00", type = "string", format = "partial-time")
+	@NotNull(message = "활동 시작 시각은 필수입니다.")
+	@DateTimeFormat(iso = DateTimeFormat.ISO.TIME)
+	LocalTime activityStartTime,
+
+	@Schema(description = "하루 활동 종료 시각 (HH:mm, 시작 시각보다 이후)", example = "22:00", type = "string", format = "partial-time")
+	@NotNull(message = "활동 종료 시각은 필수입니다.")
+	@DateTimeFormat(iso = DateTimeFormat.ISO.TIME)
+	LocalTime activityEndTime,
+
+	@Schema(
+		description = "주 이동 수단 (정확히 1개)",
+		example = "PUBLIC_TRANSIT",
+		allowableValues = {"WALKING", "PUBLIC_TRANSIT", "CAR"}
+	)
+	@NotNull(message = "이동 수단은 필수입니다.")
+	TransportMode transportMode,
+
+	@Schema(description = "선택 가능한 TourAPI 관광타입 2~4개와 각 관광타입별 세부 취향 목록")
+	@NotEmpty(message = "취향은 최소 1개 이상 선택해야 합니다.")
+	List<@Valid @NotNull ContentTypePreferenceRequest> preferences,
+
+	@Schema(
+		description = "여행 경험 밀도",
+		example = "NORMAL",
+		allowableValues = {"LIGHT", "NORMAL", "DEEP"}
+	)
+	@NotNull(message = "여행 경험 밀도는 필수입니다.")
+	ExperienceLevel experienceLevel
+) {
+
+	public boolean isRegionUndecided() {
+		return Boolean.TRUE.equals(regionUndecided);
+	}
+}

src/main/java/com/JJIN/domain/onboarding/dto/response/OnboardingCompleteResponse.java

@@ -0,0 +1,15 @@
+package com.JJIN.domain.onboarding.dto.response;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+@Schema(description = "온보딩 완료 응답")
+public record OnboardingCompleteResponse(
+
+	@Schema(description = "온보딩으로 생성된 여행 일정 ID", example = "1")
+	Long travelPlanId
+) {
+
+	public static OnboardingCompleteResponse of(final Long travelPlanId) {
+		return new OnboardingCompleteResponse(travelPlanId);
+	}
+}

src/main/java/com/JJIN/domain/onboarding/dto/response/TravelRegionResponse.java

@@ -0,0 +1,31 @@
+package com.JJIN.domain.onboarding.dto.response;
+
+import com.JJIN.domain.onboarding.entity.TravelRegion;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+@Schema(description = "여행 지역 응답")
+public record TravelRegionResponse(
+
+	@Schema(description = "여행 지역 ID", example = "1")
+	Long id,
+
+	@Schema(description = "지역 표시명", example = "서울")
+	String displayName,
+
+	@Schema(description = "TourAPI KorService2 법정동 시도 코드(lDongRegnCd)", example = "11")
+	String lDongRegnCd,
+
+	@Schema(description = "TourAPI KorService2 법정동 시군구 코드(lDongSignguCd)", example = "110", nullable = true)
+	String lDongSignguCd
+) {
+
+	public static TravelRegionResponse from(final TravelRegion region) {
+		return new TravelRegionResponse(
+			region.getId(),
+			region.getDisplayName(),
+			region.getLDongRegnCd(),
+			region.getLDongSignguCd()
+		);
+	}
+}