feat: 귀국 루트 MVP3 구현

[ccjngwn]

작업 내용

• 수면시차 계산 결과를 기준으로 귀국 루트를 생성하는 API를 추가했습니다.
• 귀국 루트 생성 시 날짜별 경유지를 랜덤으로 선택해 저장하도록 구현했습니다.
• 취침/기상 시간을 각각 하루 최대 30분씩 목표 시간 방향으로 조정하는 로직을 추가했습니다.
• 현재 귀국 루트 조회, 귀국 항공권 조회, 이제 잘게요 액션 API를 추가했습니다.
• 귀국 루트 진행 상태를 관리하기 위해 IN_PROGRESS, COMPLETED, CANCELLED 상태를 추가했습니다.

주요 API

• POST /api/return-routes/results/{resultId}: 귀국 루트 생성
• GET /api/return-routes/current: 현재 귀국 루트 조회
• GET /api/return-routes/current/boarding-pass: 현재 귀국 항공권 조회
• POST /api/return-routes/current/sleep: 다음 경유지 도착 처리

검증

• ./gradlew clean test
• H2 테스트 DB 기반 로컬 서버 실행
• GET /actuator/health 응답 200 OK 확인

Summary by CodeRabbit

• New Features

  • Added return-route planning based on sleep-jetlag results.
  • Added APIs to create, view, and track return routes.
  • Added boarding-pass details and sleep-and-arrive progression.
  • Added route statuses for in-progress, completed, and cancelled journeys.
  • Added city airport codes and flag image information.
  • Added time-adjustment logic to gradually align sleep schedules.

• Tests

  • Added coverage for sleep-time adjustments, midnight transitions, and time differences.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 4f77e468-0217-40fc-81ce-b4aa3230a6e5

📥 Commits

Reviewing files that changed from the base of the PR and between 4edf9cc and 307193f.

📒 Files selected for processing (17)

• src/main/java/com/cotato/cokerthon/domain/city/config/CityDataInitializer.java
• src/main/java/com/cotato/cokerthon/domain/city/entity/City.java
• src/main/java/com/cotato/cokerthon/domain/city/repository/CityRepository.java
• src/main/java/com/cotato/cokerthon/domain/route/controller/ReturnRouteController.java
• src/main/java/com/cotato/cokerthon/domain/route/dto/response/ArrivalResponse.java
• src/main/java/com/cotato/cokerthon/domain/route/dto/response/BoardingPassResponse.java
• src/main/java/com/cotato/cokerthon/domain/route/dto/response/CitySummaryResponse.java
• src/main/java/com/cotato/cokerthon/domain/route/dto/response/ReturnRouteDayResponse.java
• src/main/java/com/cotato/cokerthon/domain/route/dto/response/ReturnRouteResponse.java
• src/main/java/com/cotato/cokerthon/domain/route/entity/ReturnRoute.java
• src/main/java/com/cotato/cokerthon/domain/route/entity/ReturnRouteStatus.java
• src/main/java/com/cotato/cokerthon/domain/route/repository/ReturnRouteDayRepository.java
• src/main/java/com/cotato/cokerthon/domain/route/repository/ReturnRouteRepository.java
• src/main/java/com/cotato/cokerthon/domain/route/repository/ReturnRouteStopRepository.java
• src/main/java/com/cotato/cokerthon/domain/route/service/ReturnRouteService.java
• src/main/java/com/cotato/cokerthon/domain/route/service/SleepTimeCalculator.java
• src/test/java/com/cotato/cokerthon/domain/route/service/SleepTimeCalculatorTest.java

---

📝 Walkthrough

Walkthrough

Adds city airport and flag metadata, sleep-time calculation, return-route generation and persistence, lifecycle tracking, response DTOs, and authenticated APIs for route creation, retrieval, boarding-pass lookup, and arrival progression.

Changes

Return Route Workflow

Layer / File(s)	Summary
Sleep time calculation src/main/java/com/cotato/cokerthon/domain/route/service/SleepTimeCalculator.java, src/test/java/com/cotato/cokerthon/domain/route/service/SleepTimeCalculatorTest.java	Adds wrap-aware sleep-time movement, midpoint and signed-difference calculations, completion checks, and unit tests.
Route state, persistence, and response contracts src/main/java/com/cotato/cokerthon/domain/city/..., src/main/java/com/cotato/cokerthon/domain/route/entity/..., src/main/java/com/cotato/cokerthon/domain/route/repository/..., src/main/java/com/cotato/cokerthon/domain/route/dto/response/...	Adds airport and flag city fields, route status and day progression state, repository queries, and response records for routes, days, boarding passes, arrivals, and city summaries.
Route generation and storage src/main/java/com/cotato/cokerthon/domain/route/service/ReturnRouteService.java	Generates daily sleep-adjustment checkpoints, selects directional cities, adds a final base checkpoint when needed, and persists routes, days, and stops.
Route retrieval and progression API src/main/java/com/cotato/cokerthon/domain/route/service/ReturnRouteService.java, src/main/java/com/cotato/cokerthon/domain/route/controller/ReturnRouteController.java	Retrieves current routes and boarding passes, advances route arrival state, validates member ownership, and exposes authenticated return-route endpoints.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Member
  participant ReturnRouteController
  participant ReturnRouteService
  participant SleepTimeCalculator
  participant CityRepository
  participant ReturnRouteRepository
  Member->>ReturnRouteController: POST create route
  ReturnRouteController->>ReturnRouteService: createReturnRoute(memberId, resultId)
  ReturnRouteService->>SleepTimeCalculator: generate sleep-adjustment days
  ReturnRouteService->>CityRepository: select checkpoint cities
  ReturnRouteService->>ReturnRouteRepository: persist route
  ReturnRouteService-->>ReturnRouteController: ReturnRouteResponse
  ReturnRouteController-->>Member: ApiResponse

Loading

Possibly related issues

• 8th-COKERTHON/client-team5#3 — The PR adds the backend route controllers, services, entities, repositories, and response DTOs needed by the return-route screen.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/return-route-mvp3

---

_{Comment @coderabbitai help to get the list of available commands.}