[feat] #30 - TODO 조회 기본/7일

src/main/java/com/Timo/Timo/TimoApplication.java

@@ -1,5 +1,7 @@
 package com.Timo.Timo;
 
+import java.util.TimeZone;
+
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
 import org.springframework.data.jpa.repository.config.EnableJpaAuditing;
@@ -9,6 +11,7 @@
 public class TimoApplication {
 
 	public static void main(String[] args) {
+		TimeZone.setDefault(TimeZone.getTimeZone("UTC"));
 		SpringApplication.run(TimoApplication.class, args);
 	}
 

src/main/java/com/Timo/Timo/domain/home/controller/HomeController.java

@@ -0,0 +1,41 @@
+package com.Timo.Timo.domain.home.controller;
+
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.core.annotation.AuthenticationPrincipal;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import com.Timo.Timo.domain.home.docs.HomeControllerDocs;
+import com.Timo.Timo.domain.home.dto.response.HomeResponse;
+import com.Timo.Timo.domain.home.exception.HomeSuccessCode;
+import com.Timo.Timo.domain.home.service.HomeService;
+import com.Timo.Timo.global.auth.principal.CustomUserDetails;
+import com.Timo.Timo.global.response.BaseResponse;
+
+import io.swagger.v3.oas.annotations.tags.Tag;
+import lombok.RequiredArgsConstructor;
+
+@RestController
+@RequestMapping("/api/v1/home")
+@RequiredArgsConstructor
+@Tag(name = "Home", description = "HOME API")
+public class HomeController implements HomeControllerDocs {
+
+	private final HomeService homeService;
+
+	@Override
+	@GetMapping
+	public ResponseEntity<BaseResponse<HomeResponse>> getHome(
+			@AuthenticationPrincipal CustomUserDetails userDetails,
+			@RequestParam(required = false) String filter,
+			@RequestParam(required = false) String baseDate
+	) {
+		HomeResponse response = homeService.getHome(userDetails.getUserId(), filter, baseDate);
+
+		return ResponseEntity
+				.status(HomeSuccessCode.GET_HOME.getHttpStatus())
+				.body(BaseResponse.onSuccess(HomeSuccessCode.GET_HOME, response));
+	}
+}

src/main/java/com/Timo/Timo/domain/home/docs/HomeControllerDocs.java

@@ -0,0 +1,63 @@
+package com.Timo.Timo.domain.home.docs;
+
+import org.springframework.http.ResponseEntity;
+
+import com.Timo.Timo.domain.home.dto.response.HomeResponse;
+import com.Timo.Timo.global.auth.principal.CustomUserDetails;
+import com.Timo.Timo.global.exception.dto.ErrorDto;
+import com.Timo.Timo.global.response.BaseResponse;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+
+public interface HomeControllerDocs {
+
+	@Operation(
+			summary = "HOME 화면 TODO 목록 조회",
+			description = """
+					HOME 화면의 필터 조건에 따라 일별 TODO 목록을 조회합니다.
+					DEFAULT는 기준 날짜 전후 7일, WEEK는 기준 날짜부터 7일을 반환합니다.
+					각 날짜의 TODO는 미완료 먼저, 같은 완료 그룹 안에서는 sortOrder 오름차순으로 정렬됩니다.
+					"""
+	)
+	@ApiResponses({
+			@ApiResponse(
+					responseCode = "200",
+					description = "홈 뷰 조회 성공",
+					useReturnTypeSchema = true
+			),
+			@ApiResponse(
+					responseCode = "400",
+					description = "유효하지 않은 필터 값이거나 날짜 형식이 올바르지 않은 경우",
+					content = @Content(
+							mediaType = "application/json",
+							schema = @Schema(implementation = ErrorDto.class)
+					)
+			),
+			@ApiResponse(
+					responseCode = "401",
+					description = "Access Token이 없거나 만료되었거나 유효하지 않은 경우",
+					content = @Content(
+							mediaType = "application/json",
+							schema = @Schema(implementation = ErrorDto.class)
+					)
+			),
+			@ApiResponse(
+					responseCode = "500",
+					description = "서버 내부 오류",
+					content = @Content(
+							mediaType = "application/json",
+							schema = @Schema(implementation = ErrorDto.class)
+					)
+			)
+	})
+	ResponseEntity<BaseResponse<HomeResponse>> getHome(
+			@Parameter(hidden = true) CustomUserDetails userDetails,
+			@Parameter(description = "조회 필터(DEFAULT, WEEK)", example = "DEFAULT") String filter,
+			@Parameter(description = "기준 날짜(yyyy-MM-dd), 미입력 시 오늘", example = "2026-07-22") String baseDate
+	);
+}

src/main/java/com/Timo/Timo/domain/home/dto/response/HomeResponse.java

@@ -0,0 +1,93 @@
+package com.Timo.Timo.domain.home.dto.response;
+
+import java.time.LocalDate;
+import java.util.List;
+import java.util.Objects;
+
+import com.Timo.Timo.domain.home.enums.HomeFilter;
+import com.Timo.Timo.domain.tag.entity.Tag;
+import com.Timo.Timo.domain.todo.entity.Subtask;
+import com.Timo.Timo.domain.todo.enums.TodoTimerStatus;
+import com.Timo.Timo.domain.todo.enums.Weekday;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+public record HomeResponse(
+		HomeFilter filter,
+		LocalDate baseDate,
+		List<DayResponse> days
+) {
+
+	public record DayResponse(
+			LocalDate date,
+			Weekday dayOfWeek,
+			@JsonProperty("isHoliday")
+			boolean isHoliday,
+			@JsonProperty("isToday")
+			boolean isToday,
+			int totalCount,
+			int completedCount,
+			List<TodoResponse> todos
+	) {
+		public static DayResponse of(
+				LocalDate date,
+				boolean isHoliday,
+				boolean isToday,
+				List<TodoResponse> todos
+		) {
+			int completedCount = (int) todos.stream()
+					.filter(TodoResponse::completed)
+					.count();
+
+			return new DayResponse(
+					date,
+					Weekday.from(date.getDayOfWeek()),
+					isHoliday,
+					isToday,
+					todos.size(),
+					completedCount,
+					todos
+			);
+		}
+	}
+
+	public record TodoResponse(
+			Long todoId,
+			String icon,
+			String title,
+			boolean completed,
+			Integer durationSeconds,
+			String priority,
+			TagResponse tag,
+			boolean hasMemo,
+			@JsonProperty("isRepeated")
+			boolean isRepeated,
+			TodoTimerStatus timerStatus,
+			Integer sortOrder,
+			List<SubtaskResponse> subtasks
+	) {
+	}
+
+	public record TagResponse(
+			Long tagId,
+			String name
+	) {
+		public static TagResponse from(Tag tag) {
+			Objects.requireNonNull(tag, "tag must not be null");
+			return new TagResponse(tag.getId(), tag.getName());
+		}
+	}
+
+	public record SubtaskResponse(
+			Long subtaskId,
+			String content,
+			boolean completed
+	) {
+		public static SubtaskResponse from(Subtask subtask) {
+			return new SubtaskResponse(
+					subtask.getId(),
+					subtask.getContent(),
+					subtask.isCompleted()
+			);
+		}
+	}
+}

src/main/java/com/Timo/Timo/domain/home/enums/HomeFilter.java

@@ -0,0 +1,6 @@
+package com.Timo.Timo.domain.home.enums;
+
+public enum HomeFilter {
+	DEFAULT,
+	WEEK
+}

src/main/java/com/Timo/Timo/domain/home/exception/HomeErrorCode.java

@@ -0,0 +1,20 @@
+package com.Timo.Timo.domain.home.exception;
+
+import org.springframework.http.HttpStatus;
+
+import com.Timo.Timo.global.exception.code.BaseErrorCode;
+
+import lombok.Getter;
+import lombok.RequiredArgsConstructor;
+
+@Getter
+@RequiredArgsConstructor
+public enum HomeErrorCode implements BaseErrorCode {
+
+	INVALID_FILTER_OR_DATE(HttpStatus.BAD_REQUEST, "HOME_400", "유효하지 않은 필터 값이거나 날짜 형식이 올바르지 않습니다."),
+	INVALID_DATE(HttpStatus.BAD_REQUEST, "DATE_400", "날짜 형식이 올바르지 않습니다.");
+
+	private final HttpStatus httpStatus;
+	private final String code;
+	private final String message;
+}

src/main/java/com/Timo/Timo/domain/home/exception/HomeSuccessCode.java

@@ -0,0 +1,18 @@
+package com.Timo.Timo.domain.home.exception;
+
+import org.springframework.http.HttpStatus;
+
+import com.Timo.Timo.global.exception.code.BaseSuccessCode;
+
+import lombok.Getter;
+import lombok.RequiredArgsConstructor;
+
+@Getter
+@RequiredArgsConstructor
+public enum HomeSuccessCode implements BaseSuccessCode {
+
+	GET_HOME(HttpStatus.OK, "홈 뷰 조회 성공");
+
+	private final HttpStatus httpStatus;
+	private final String message;
+}

src/main/java/com/Timo/Timo/domain/home/mapper/HomeTodoMapper.java

@@ -0,0 +1,61 @@
+package com.Timo.Timo.domain.home.mapper;
+
+import java.util.List;
+
+import org.springframework.stereotype.Component;
+
+import com.Timo.Timo.domain.home.dto.response.HomeResponse.SubtaskResponse;
+import com.Timo.Timo.domain.home.dto.response.HomeResponse.TagResponse;
+import com.Timo.Timo.domain.home.dto.response.HomeResponse.TodoResponse;
+import com.Timo.Timo.domain.tag.entity.Tag;
+import com.Timo.Timo.domain.todo.entity.Subtask;
+import com.Timo.Timo.domain.todo.entity.Todo;
+import com.Timo.Timo.domain.todo.entity.TodoInstance;
+import com.Timo.Timo.domain.todo.enums.RepeatType;
+import com.Timo.Timo.domain.todo.enums.TodoTimerStatus;
+
+@Component
+public class HomeTodoMapper {
+
+	public TodoResponse toResponse(TodoContext context) {
+		Todo todo = context.todo();
+		TodoInstance instance = context.instance();
+
+		return new TodoResponse(
+				todo.getId(),
+				todo.getIcon() != null ? todo.getIcon().name() : null,
+				todo.getTitle(),
+				instance != null && instance.isCompleted(),
+				todo.getDurationSeconds(),
+				todo.getPriority() != null ? todo.getPriority().name() : null,
+				mapTag(context.tag()),
+				todo.getMemo() != null && !todo.getMemo().isBlank(),
+				todo.getRepeatType() != RepeatType.NONE,
+				resolveTimerStatus(instance),
+				instance != null ? instance.getSortOrder() : context.defaultSortOrder(),
+				mapSubtasks(todo.getSubtasks())
+		);
+	}
+
+	private TagResponse mapTag(Tag tag) {
+		return tag != null ? TagResponse.from(tag) : null;
+	}
+
+	private TodoTimerStatus resolveTimerStatus(TodoInstance instance) {
+		return instance != null ? instance.getTimerStatus() : TodoTimerStatus.STOPPED;
+	}
+
+	private List<SubtaskResponse> mapSubtasks(List<Subtask> subtasks) {
+		return subtasks.stream()
+				.map(SubtaskResponse::from)
+				.toList();
+	}
+
+	public record TodoContext(
+			Todo todo,
+			TodoInstance instance,
+			Tag tag,
+			int defaultSortOrder
+	) {
+	}
+}

src/main/java/com/Timo/Timo/domain/home/service/HolidayChecker.java

@@ -0,0 +1,44 @@
+package com.Timo.Timo.domain.home.service;
+
+import java.time.DayOfWeek;
+import java.time.LocalDate;
+import java.time.MonthDay;
+import java.util.Map;
+import java.util.Set;
+
+import org.springframework.stereotype.Component;
+
+import com.Timo.Timo.domain.user.enums.Language;
+
+@Component
+public class HolidayChecker {
+
+	private static final Set<MonthDay> KOREAN_FIXED_HOLIDAYS = Set.of(
+			MonthDay.of(1, 1),
+			MonthDay.of(3, 1),
+			MonthDay.of(5, 5),
+			MonthDay.of(6, 6),
+			MonthDay.of(8, 15),
+			MonthDay.of(10, 3),
+			MonthDay.of(10, 9),
+			MonthDay.of(12, 25)
+	);
+
+	/**
+	 * 언어(지역)별 양력 고정 공휴일. 음력 공휴일(설날·추석 등)은 별도 계산이 필요해 아직 포함하지 않는다.
+	 * 신뢰할 만한 데이터가 없는 언어는 빈 집합으로 두고 일요일만 공휴일로 처리한다.
+	 */
+	private static final Map<Language, Set<MonthDay>> FIXED_HOLIDAYS_BY_LANGUAGE = Map.of(
+			Language.KO, KOREAN_FIXED_HOLIDAYS,
+			Language.EN, Set.of()
+	);
+
+	public boolean isHoliday(LocalDate date, Language language) {
+		if (date.getDayOfWeek() == DayOfWeek.SUNDAY) {
+			return true;
+		}
+
+		Set<MonthDay> fixedHolidays = FIXED_HOLIDAYS_BY_LANGUAGE.getOrDefault(language, Set.of());
+		return fixedHolidays.contains(MonthDay.from(date));
+	}
+}