feat: 학교버스 시간표 관련 API

src/main/java/in/koreatech/koin/domain/bus/controller/BusApi.java

@@ -12,6 +12,8 @@
 import in.koreatech.koin.domain.bus.dto.BusRemainTimeResponse;
 import in.koreatech.koin.domain.bus.dto.BusTimetableResponse;
 import in.koreatech.koin.domain.bus.dto.CityBusTimetableResponse;
+import in.koreatech.koin.domain.bus.dto.ShuttleBusRouteResponse;
+import in.koreatech.koin.domain.bus.dto.ShuttleBusRoutesResponse;
 import in.koreatech.koin.domain.bus.dto.SingleBusTimeResponse;
 import in.koreatech.koin.domain.bus.model.BusTimetable;
 import in.koreatech.koin.domain.bus.model.enums.BusStation;
@@ -90,4 +92,23 @@ ResponseEntity<List<SingleBusTimeResponse>> getSearchTimetable(
     @Operation(summary = "버스 노선 조회")
     @GetMapping("/courses")
     ResponseEntity<List<BusCourseResponse>> getBusCourses();
+
+    @ApiResponses(
+        value = {
+            @ApiResponse(responseCode = "200"),
+        }
+    )
+    @Operation(summary = "학교버스 노선 조회")
+    @GetMapping("/courses/shuttle")
+    ResponseEntity<ShuttleBusRoutesResponse> getShuttleBusRoutes();
+
+    @ApiResponses(
+        value = {
+            @ApiResponse(responseCode = "200"),
+            @ApiResponse(responseCode = "404", content = @Content(schema = @Schema(hidden = true))),
+        }
+    )
+    @Operation(summary = "학교버스 시간표 조회")
+    @GetMapping("/timetable/shuttle")
+    ResponseEntity<ShuttleBusRouteResponse> getShuttleBusTimetable(@RequestParam String id);
 }

src/main/java/in/koreatech/koin/domain/bus/controller/BusController.java

@@ -15,12 +15,17 @@
 import in.koreatech.koin.domain.bus.dto.BusRemainTimeResponse;
 import in.koreatech.koin.domain.bus.dto.BusTimetableResponse;
 import in.koreatech.koin.domain.bus.dto.CityBusTimetableResponse;
+import in.koreatech.koin.domain.bus.dto.ShuttleBusRouteResponse;
+import in.koreatech.koin.domain.bus.dto.ShuttleBusRoutesResponse;
 import in.koreatech.koin.domain.bus.dto.SingleBusTimeResponse;
 import in.koreatech.koin.domain.bus.model.BusTimetable;
 import in.koreatech.koin.domain.bus.model.enums.BusStation;
 import in.koreatech.koin.domain.bus.model.enums.BusType;
 import in.koreatech.koin.domain.bus.model.enums.CityBusDirection;
+import in.koreatech.koin.domain.bus.repository.ShuttleBusRepository;
 import in.koreatech.koin.domain.bus.service.BusService;
+import in.koreatech.koin.domain.version.dto.VersionMessageResponse;
+import in.koreatech.koin.domain.version.service.VersionService;
 import lombok.RequiredArgsConstructor;
 
 @RestController
@@ -29,6 +34,8 @@
 public class BusController implements BusApi {
 
     private final BusService busService;
+    private final ShuttleBusRepository shuttleBusRepository;
+    private final VersionService versionService;
 
     @GetMapping
     public ResponseEntity<BusRemainTimeResponse> getBusRemainTime(
@@ -82,4 +89,16 @@ public ResponseEntity<List<SingleBusTimeResponse>> getSearchTimetable(
             depart, arrival);
         return ResponseEntity.ok().body(singleBusTimeResponses);
     }
+
+    @GetMapping("/courses/shuttle")
+    public ResponseEntity<ShuttleBusRoutesResponse> getShuttleBusRoutes() {
+        VersionMessageResponse version = versionService.getVersionWithMessage("shuttle_bus_timetable");
+        return ResponseEntity.ok()
+            .body(ShuttleBusRoutesResponse.of(shuttleBusRepository.findBySemesterType(version.title()), version));
+    }
+
+    @GetMapping("/timetable/shuttle")
+    public ResponseEntity<ShuttleBusRouteResponse> getShuttleBusTimetable(@RequestParam String id) {
+        return ResponseEntity.ok().body(ShuttleBusRouteResponse.from(shuttleBusRepository.getById(id)));
+    }
 }

src/main/java/in/koreatech/koin/domain/bus/dto/ShuttleBusRouteResponse.java

@@ -0,0 +1,75 @@
+package in.koreatech.koin.domain.bus.dto;
+
+import java.util.List;
+
+import com.fasterxml.jackson.databind.PropertyNamingStrategies.SnakeCaseStrategy;
+import com.fasterxml.jackson.databind.annotation.JsonNaming;
+
+import in.koreatech.koin.domain.bus.model.mongo.ShuttleBusRoute;
+import io.swagger.v3.oas.annotations.media.Schema;
+
+@JsonNaming(SnakeCaseStrategy.class)
+@Schema(description = "셔틀버스 경로 응답 DTO")
+public record ShuttleBusRouteResponse(
+    @Schema(description = "경로 ID", example = "675013f9465776d6265ddfdb")
+    String id,
+
+    @Schema(description = "지역 이름", example = "천안")
+    String region,
+
+    @Schema(description = "경로 타입", example = "순환")
+    String routeType,
+
+    @Schema(description = "경로 이름", example = "천안 셔틀")
+    String routeName,
+
+    @Schema(description = "경로 부가 이름", example = "null")
+    String subName,
+
+    @Schema(description = "노드 정보 목록")
+    List<NodeInfoResponse> nodeInfo,
+
+    @Schema(description = "경로 정보 목록")
+    List<RouteInfoResponse> routeInfo
+) {
+
+    @JsonNaming(SnakeCaseStrategy.class)
+    @Schema(description = "노드 정보")
+    private record NodeInfoResponse(
+        @Schema(description = "노드 이름", example = "캠퍼스 정문")
+        String name,
+
+        @Schema(description = "노드 세부 정보", example = "정문 앞 정류장")
+        String detail
+    ) {
+    }
+
+    @JsonNaming(SnakeCaseStrategy.class)
+    @Schema(description = "경로 정보")
+    private record RouteInfoResponse(
+        @Schema(description = "경로 이름", example = "1회")
+        String name,
+
+        @Schema(description = "도착 시간 목록", example = "[\"08:00\", \"09:00\"]")
+        List<String> arrivalTime
+    ) {
+    }
+
+    public static ShuttleBusRouteResponse from(ShuttleBusRoute shuttleBusRoute) {
+        List<NodeInfoResponse> nodeInfoResponses = shuttleBusRoute.getNodeInfo().stream()
+            .map(node -> new NodeInfoResponse(node.getName(), node.getDetail()))
+            .toList();
+        List<RouteInfoResponse> routeInfoResponses = shuttleBusRoute.getRouteInfo().stream()
+            .map(route -> new RouteInfoResponse(route.getName(), route.getArrivalTime()))
+            .toList();
+        return new ShuttleBusRouteResponse(
+            shuttleBusRoute.getId(),
+            shuttleBusRoute.getRegion(),
+            shuttleBusRoute.getRouteType(),
+            shuttleBusRoute.getRouteName(),
+            shuttleBusRoute.getSubName(),
+            nodeInfoResponses,
+            routeInfoResponses
+        );
+    }
+}

src/main/java/in/koreatech/koin/domain/bus/dto/ShuttleBusRoutesResponse.java

@@ -0,0 +1,105 @@
+package in.koreatech.koin.domain.bus.dto;
+
+import static com.fasterxml.jackson.databind.PropertyNamingStrategies.SnakeCaseStrategy;
+
+import java.util.List;
+import java.util.stream.Collectors;
+
+import com.fasterxml.jackson.databind.annotation.JsonNaming;
+
+import in.koreatech.koin.domain.bus.model.mongo.ShuttleBusRoute;
+import in.koreatech.koin.domain.version.dto.VersionMessageResponse;
+import io.swagger.v3.oas.annotations.media.Schema;
+
+@JsonNaming(SnakeCaseStrategy.class)
+@Schema(description = "셔틀버스 경로 응답")
+public record ShuttleBusRoutesResponse(
+    @Schema(description = "노선 지역 분류 목록")
+    List<RouteRegion> routeRegions,
+
+    @Schema(description = "학기 정보")
+    RouteSemester semesterInfo
+) {
+
+    @JsonNaming(SnakeCaseStrategy.class)
+    @Schema(description = "노선 지역 정보")
+    private record RouteRegion(
+        @Schema(description = "지역 이름", example = "천안") String region,
+        @Schema(description = "해당 지역의 경로 목록") List<RouteName> routes
+    ) implements Comparable<RouteRegion> {
+
+        @Override
+        public int compareTo(RouteRegion routeName) {
+            return Integer.compare(getPriority(this.region), getPriority(routeName.region));
+        }
+
+        private int getPriority(String region) {
+            return switch (region) {
+                case "천안" -> 1;
+                case "청주" -> 2;
+                case "서울" -> 3;
+                default -> 4;
+            };
+        }
+
+        public static List<RouteRegion> mapCategories(List<ShuttleBusRoute> shuttleBusRoutes) {
+            return shuttleBusRoutes.stream()
+                .collect(Collectors.groupingBy(ShuttleBusRoute::getRegion))
+                .entrySet().stream()
+                .map(entry -> new RouteRegion(entry.getKey(), RouteName.mapRouteNames(entry.getValue())))
+                .sorted()
+                .toList();
+        }
+    }
+
+    @JsonNaming(SnakeCaseStrategy.class)
+    @Schema(description = "노선 세부 정보")
+    private record RouteName(
+        @Schema(description = "노선 ID", example = "675013f9465776d6265ddfdb") String id,
+        @Schema(description = "노선 종류", example = "주말") String type,
+        @Schema(description = "노선 이름", example = "대학원") String routeName,
+        @Schema(description = "노선 부가 이름", example = "토요일") String subName
+    ) implements Comparable<RouteName> {
+
+        @Override
+        public int compareTo(RouteName routeName) {
+            return Integer.compare(getPriority(this.type), getPriority(routeName.type));
+        }
+
+        private int getPriority(String type) {
+            return switch (type) {
+                case "순환" -> 1;
+                case "주중" -> 2;
+                case "주말" -> 3;
+                default -> 4;
+            };
+        }
+
+        public static List<RouteName> mapRouteNames(List<ShuttleBusRoute> routes) {
+            return routes.stream()
+                .map(route -> new RouteName(route.getId(), route.getRouteType(), route.getRouteName(), route.getSubName()))
+                .sorted()
+                .toList();
+        }
+    }
+
+    @JsonNaming(SnakeCaseStrategy.class)
+    @Schema(description = "학기 정보")
+    private record RouteSemester(
+        @Schema(description = "학기 이름", example = "정규학기") String name,
+        @Schema(description = "학기 기간", example = "2024-09-02 ~ 2024-12-20") String term
+    ) {
+
+        public static RouteSemester from(VersionMessageResponse versionMessageResponse) {
+            return new RouteSemester(versionMessageResponse.title(),
+                versionMessageResponse.content());
+        }
+    }
+
+    public static ShuttleBusRoutesResponse of(List<ShuttleBusRoute> shuttleBusRoutes,
+        VersionMessageResponse versionMessageResponse) {
+        List<RouteRegion> categories = RouteRegion.mapCategories(shuttleBusRoutes);
+        RouteSemester routeSemester = RouteSemester.from(versionMessageResponse);
+        return new ShuttleBusRoutesResponse(categories, routeSemester);
+    }
+}

src/main/java/in/koreatech/koin/domain/bus/model/mongo/ShuttleBusRoute.java

@@ -0,0 +1,70 @@
+package in.koreatech.koin.domain.bus.model.mongo;
+
+import static lombok.AccessLevel.PROTECTED;
+
+import java.util.List;
+
+import org.springframework.data.annotation.Id;
+import org.springframework.data.mongodb.core.mapping.Document;
+import org.springframework.data.mongodb.core.mapping.Field;
+
+import com.fasterxml.jackson.annotation.JsonIgnore;
+
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+@Getter
+@NoArgsConstructor(access = PROTECTED)
+@Document(collection = "shuttlebus_timetables")
+public class ShuttleBusRoute {
+
+    @Id
+    private String id;
+
+    @Field("semester_type")
+    private String semesterType;
+
+    @Field("region")
+    private String region;
+
+    @Field("route_type")
+    private String routeType;
+
+    @Field("route_name")
+    private String routeName;
+
+    @Field("sub_name")
+    private String subName;
+
+    @Field("node_info")
+    private List<NodeInfo> nodeInfo;
+
+    @Field("route_info")
+    private List<RouteInfo> routeInfo;
+
+    @Getter
+    @NoArgsConstructor(access = PROTECTED)
+    public static class NodeInfo {
+
+        @Field("name")
+        private String name;
+
+        @Field("detail")
+        private String detail;
+    }
+
+    @Getter
+    @NoArgsConstructor(access = PROTECTED)
+    public static class RouteInfo {
+
+        @Field("name")
+        private String name;
+
+        @Field("running_days")
+        @JsonIgnore
+        private List<String> runningDays;
+
+        @Field("arrival_time")
+        private List<String> arrivalTime;
+    }
+}

src/main/java/in/koreatech/koin/domain/bus/repository/ShuttleBusRepository.java

@@ -0,0 +1,22 @@
+package in.koreatech.koin.domain.bus.repository;
+
+import java.util.List;
+import java.util.Optional;
+
+import org.bson.types.ObjectId;
+import org.springframework.data.repository.Repository;
+
+import in.koreatech.koin.domain.bus.exception.BusNotFoundException;
+import in.koreatech.koin.domain.bus.model.mongo.ShuttleBusRoute;
+
+public interface ShuttleBusRepository extends Repository<ShuttleBusRoute, ObjectId> {
+
+    List<ShuttleBusRoute> findBySemesterType(String semesterType);
+
+    Optional<ShuttleBusRoute> findById(String id);
+
+    default ShuttleBusRoute getById(String id) {
+        return findById(id).orElseThrow(
+            () -> BusNotFoundException.withDetail("id: " + id));
+    }
+}