package incheon.product.geoview3d.traffic.service;

import java.util.List;
import java.util.Map;

/**
 * 교통 정보 서비스 인터페이스.
 * ITS 실시간 교통 정보 조회, 도로명 검색, 링크 조회 기능을 제공한다.
 */
public interface TrafficService {

    /**
     * bbox 범위 내 교통 정보(링크별 등급/속도) 조회.
     * 캐싱된 데이터가 5분 이상 경과 시 비동기로 갱신한다.
     *
     * @param roadType 도로 유형
     * @param minX     최소 경도
     * @param minY     최소 위도
     * @param maxX     최대 경도
     * @param maxY     최대 위도
     * @return 링크별 교통 정보 목록
     */
    List<Map<String, Object>> getTrafficInfo(String roadType, double minX, double minY, double maxX, double maxY);

    /**
     * 도로명 목록 조회 (페이징).
     *
     * @param roadType   도로 유형
     * @param searchName 검색 도로명
     * @param page       페이지 번호
     * @param size       페이지 크기
     * @return items(도로명 목록)과 totalCount를 포함하는 Map
     */
    Map<String, Object> getRoadNames(String roadType, String searchName, int page, int size);

    /**
     * 도로명에 해당하는 링크 목록 조회.
     *
     * @param roadName 도로명
     * @return 링크 목록
     */
    List<Map<String, Object>> getLinks(String roadName);

    /**
     * ITS API에서 교통 정보를 비동기로 수집하여 DB에 저장한다.
     */
    void updateTrafficInfoAsync();
}