VIPS/src/main/java/go/kr/project/api/service/VehicleInfoService.java

package go.kr.project.api.service;

import go.kr.project.api.model.VehicleApiResponseVO;
import go.kr.project.api.model.request.BasicRequest;
import go.kr.project.api.model.request.LedgerRequest;
import go.kr.project.api.model.response.BasicResponse;
import go.kr.project.api.model.response.LedgerResponse;

import java.util.List;

/**
 * 차량 정보 조회 서비스 인터페이스
 *
 * <p>이 인터페이스는 차량 정보를 조회하는 두 가지 구현체를 추상화합니다:</p>
 * <ul>
 *   <li>InternalVehicleInfoServiceImpl: 내부 VMIS 모듈을 직접 호출 (vmis.integration.mode=internal)</li>
 *   <li>ExternalVehicleInfoServiceImpl: 외부 REST API를 호출 (vmis.integration.mode=external)</li>
 * </ul>
 *
 * <h3>설정 방법:</h3>
 * <pre>
 * # application.yml
 * vmis:
 *   integration:
 *     mode: internal  # 또는 external
 * </pre>
 *
 * <h3>사용 예시:</h3>
 * <pre>
 * {@code
 * @Autowired
 * private VehicleInfoService vehicleInfoService;
 *
 * // 단일 차량 조회
 * VehicleApiResponseVO response = vehicleInfoService.getVehicleInfo("12가3456");
 *
 * // 여러 차량 일괄 조회
 * List<VehicleApiResponseVO> responses = vehicleInfoService.getVehiclesInfo(
 *     Arrays.asList("12가3456", "34나5678")
 * );
 *
 * // 단독 조회 (기본/등록원부)
 * BasicResponse basic = vehicleInfoService.getBasicInfo("12가3456");
 * LedgerResponse ledger = vehicleInfoService.getLedgerInfo("12가3456");
 * }
 * </pre>
 */
public interface VehicleInfoService {

    /**
     * 단일 차량번호에 대한 정보 조회
     *
     * <p>차량 기본정보와 등록원부 정보를 함께 조회합니다.</p>
     *
     * @param vehicleNumber 차량번호
     * @return 차량 정보 응답 (기본정보 + 등록원부 정보)
     */
    VehicleApiResponseVO getVehicleInfo(String vehicleNumber);

    /**
     * 단일 차량에 대한 정보 조회 (상세 파라미터 포함)
     *
     * <p>차량 기본정보와 등록원부 정보를 함께 조회합니다.</p>
     * <p>차량번호 외에 부과기준일, 조회구분, 차대번호 등 추가 파라미터를 포함하여 조회할 수 있습니다.</p>
     *
     * @param basicRequest 기본정보 조회 요청 (차량번호, 부과기준일, 조회구분 등 포함)
     * @return 차량 정보 응답 (기본정보 + 등록원부 정보)
     */
    VehicleApiResponseVO getVehicleInfo(BasicRequest basicRequest);

    /**
     * 여러 차량번호에 대한 정보를 일괄 조회
     *
     * <p>각 차량에 대해 기본정보와 등록원부 정보를 함께 조회합니다.</p>
     *
     * @param vehicleNumbers 차량번호 리스트
     * @return 차량 정보 응답 리스트
     */
    List<VehicleApiResponseVO> getVehiclesInfo(List<String> vehicleNumbers);

    /**
     * 차량 기본정보만 조회 (단독)
     * 중요: 차량번호 외에 부과기준일, 조회구분, 차대번호 등 필수 파라미터를 모두 포함한 BasicRequest 필요
     *
     * @param request 기본정보 조회 요청 (차량번호, 부과기준일, 조회구분 등 포함)
     * @return 기본정보 응답
     */
    BasicResponse getBasicInfo(BasicRequest request);

    /**
     * 자동차 등록원부(갑)만 조회 (단독)
     * 중요: 차량번호 외에 소유자정보, 조회구분 등 필수 파라미터를 모두 포함한 LedgerRequest 필요
     *
     * @param request 등록원부 조회 요청 (차량번호, 소유자정보, 조회구분 등 포함)
     * @return 등록원부 응답
     */
    LedgerResponse getLedgerInfo(LedgerRequest request);
}