@charzing/vehicle-utils 0.1.0

package/dist/esm/index.d.mts

@@ -0,0 +1,714 @@
+/**
+ * 브랜드 관련 타입 정의
+ */
+/**
+ * 브랜드 ID (Firestore 문서 ID)
+ * @example 'hyundai', 'kia', 'tesla', 'bmw', 'mini', 'audi', 'mercedes-benz', 'mercedes-maybach', 'porsche'
+ */
+type BrandId = 'hyundai' | 'kia' | 'tesla' | 'bmw' | 'mini' | 'audi' | 'mercedes-benz' | 'mercedes-maybach' | 'porsche';
+/**
+ * 브랜드 정보
+ */
+interface Brand {
+    /** Firestore 문서 ID (소문자, 하이픈) */
+    id: BrandId;
+    /** 한글 브랜드명 */
+    name: string;
+    /** 영문 브랜드명 (대문자) */
+    englishName: string;
+    /** 브랜드 로고 URL */
+    logoUrl?: string;
+    /** 모델 수 (선택적) */
+    modelsCount?: number;
+}
+/**
+ * Firebase Storage 브랜드명 (대문자)
+ * Mercedes-Benz와 Mercedes-Maybach는 'BENZ'로 통합
+ */
+type StorageBrandName = 'HYUNDAI' | 'KIA' | 'TESLA' | 'BMW' | 'MINI' | 'AUDI' | 'BENZ' | 'PORSCHE';
+/**
+ * 브랜드 매핑 결과
+ */
+interface BrandMapping {
+    /** Firestore ID (소문자) */
+    firestoreId: BrandId;
+    /** 한글 브랜드명 */
+    koreanName: string;
+    /** 영문 브랜드명 (대문자) */
+    englishName: string;
+    /** Storage 브랜드명 (대문자) */
+    storageName: StorageBrandName;
+}
+
+/**
+ * 모델 관련 타입 정의
+ */
+/**
+ * 모델 ID (Firestore 문서 ID)
+ * 소문자, 하이픈으로 구분
+ * @example 'ioniq-5', 'model-s', 'cooper', 'i4'
+ */
+type ModelId = string;
+/**
+ * 모델 정보
+ */
+interface Model {
+    /** Firestore 문서 ID (소문자, 하이픈) */
+    id: ModelId;
+    /** 한글 모델명 */
+    name: string;
+    /** 영문 모델명 */
+    englishName: string;
+    /** 브랜드 ID */
+    brandId: string;
+    /** 모델 이미지 URL */
+    imageUrl?: string;
+    /** 트림 수 (선택적) */
+    trimsCount?: number;
+    /** 생산 시작 연도 */
+    startYear?: number;
+    /** 생산 종료 연도 */
+    endYear?: number;
+}
+/**
+ * 모델 슬러그 (URL/파일명용)
+ * 소문자, 하이픈으로 구분
+ * @example 'ioniq-5', 'model-s', 'cooper'
+ */
+type ModelSlug = string;
+/**
+ * 모델 매핑 결과
+ */
+interface ModelMapping {
+    /** Firestore ID (소문자, 하이픈) */
+    firestoreId: ModelId;
+    /** 한글 모델명 */
+    koreanName: string;
+    /** 영문 모델명 */
+    englishName: string;
+    /** URL/파일명용 슬러그 */
+    slug: ModelSlug;
+}
+
+/**
+ * 트림 관련 타입 정의
+ */
+/**
+ * 트림 ID (Firestore 내부 ID)
+ * 소문자, 하이픈으로 구분
+ * @example 'exclusive', 'jcw', 'highland', 'turbo-gt'
+ */
+type TrimId = string;
+/**
+ * 구동 방식
+ */
+type DriveType = 'FWD' | 'RWD' | 'AWD' | '4WD';
+/**
+ * 차량 변형 (연식별 스펙)
+ */
+interface VehicleVariant {
+    /** 해당 연도들 */
+    years: number[];
+    /** 배터리 용량 (kWh) */
+    batteryCapacity: number;
+    /** 주행거리 (km) */
+    range: number;
+    /** 배터리 공급사 */
+    supplier?: string;
+    /** 배터리 타입 */
+    batteryType?: string;
+    /** 이미지 URL (트림별 디자인 차이가 있는 경우) */
+    imageUrl?: string;
+    /** 참고사항 */
+    note?: string;
+    /** 상세 스펙 */
+    specifications?: {
+        /** 모터 타입 */
+        motor?: string;
+        /** 출력 */
+        power?: string;
+        /** 토크 */
+        torque?: string;
+        /** 가속 성능 (0-100km/h) */
+        acceleration?: string;
+        /** 충전 속도 */
+        chargingSpeed?: string;
+        /** 충전 커넥터 규격 */
+        chargingConnector?: string;
+        /** 최고속도 */
+        topSpeed?: string;
+        /** 연비 */
+        efficiency?: string;
+    };
+}
+/**
+ * 차량 트림 정보
+ */
+interface VehicleTrim {
+    /** 트림 ID */
+    trimId: TrimId;
+    /** 트림명 */
+    name: string;
+    /** 구동 방식 */
+    driveType: DriveType;
+    /** 생산 연도 범위 */
+    yearRange: {
+        start: number;
+        end: number;
+    };
+    /** 연식별 변형 */
+    variants: VehicleVariant[];
+}
+/**
+ * 트림 슬러그 (URL/파일명용)
+ * 소문자, 하이픈으로 구분
+ * @example 'exclusive', 'jcw', 'highland'
+ */
+type TrimSlug = string;
+/**
+ * 트림 매핑 결과
+ */
+interface TrimMapping {
+    /** Firestore ID (소문자, 하이픈) */
+    firestoreId: TrimId;
+    /** 트림명 */
+    name: string;
+    /** URL/파일명용 슬러그 */
+    slug: TrimSlug;
+}
+
+/**
+ * 차량 통합 타입 정의
+ */
+
+/**
+ * 배터리 정보
+ */
+interface BatteryInfo {
+    /** 배터리 용량 (kWh) */
+    capacity: number;
+    /** 배터리 공급사 */
+    supplier: string;
+    /** 배터리 타입 (NCM, NCA, LFP 등) */
+    type: string;
+    /** 전압 (V) */
+    voltage: number;
+    /** 주행거리 (km) */
+    range: number;
+}
+/**
+ * 차량 모델 (Firestore 구조)
+ */
+interface VehicleModel {
+    /** 모델 ID */
+    id: ModelId;
+    /** 한글 모델명 */
+    name: string;
+    /** 영문 모델명 */
+    englishName: string;
+    /** 모델 이미지 URL */
+    imageUrl?: string;
+    /** 기본 배터리 정보 */
+    defaultBattery: BatteryInfo;
+    /** 트림 목록 */
+    trims: VehicleTrim[];
+    /** 생성일 */
+    createdAt?: Date;
+    /** 수정일 */
+    updatedAt?: Date;
+}
+/**
+ * 완성된 차량 정보 (사용자 선택 결과)
+ */
+interface CompletedVehicle {
+    /** 제조사 (한글) */
+    make: string;
+    /** 모델명 (한글) */
+    model: string;
+    /** 트림명 */
+    trim: string;
+    /** 연식 */
+    year: number;
+    /** 브랜드 ID (소문자) */
+    brandId: BrandId;
+    /** 모델 ID (소문자, 하이픈) */
+    modelId: ModelId;
+    /** 트림 ID (소문자, 하이픈) */
+    trimId: TrimId;
+    /** 배터리 용량 */
+    batteryCapacity?: number | string;
+    /** 이미지 URL */
+    imageUrl?: string;
+    /** 주행거리 */
+    range?: number | string;
+    /** 구동 방식 */
+    driveType?: DriveType;
+}
+/**
+ * 차량 상세 정보
+ */
+interface VehicleDetails {
+    /** 모델명 */
+    modelName: string;
+    /** 이미지 URL */
+    imageUrl: string;
+    /** 배터리 정보 */
+    battery: {
+        capacity: number;
+        manufacturer: string;
+        cellType: string;
+        voltage: number;
+    };
+    /** 성능 정보 */
+    performance: {
+        range: number;
+        topSpeed: number;
+        power: number;
+        torque: number;
+        efficiency: number;
+        acceleration: number;
+        driveType: string;
+        chargingSpeed?: string;
+        chargingConnector?: string;
+    };
+}
+/**
+ * 사용자 차량 (앱에서 사용)
+ */
+interface UserVehicle {
+    /** 차량 ID */
+    id: string;
+    /** 사용자 ID */
+    userId: string;
+    /** 제조사 */
+    make: string;
+    /** 모델명 */
+    model: string;
+    /** 연식 */
+    year: number;
+    /** 트림 */
+    trim?: string;
+    /** 배터리 용량 */
+    batteryCapacity?: string;
+    /** 주행거리 */
+    range?: string;
+    /** 차량 별명 */
+    nickname?: string;
+    /** 이미지 URL */
+    imageUrl?: string;
+    /** 활성 상태 */
+    isActive: boolean;
+    /** 생성일 */
+    createdAt: Date;
+    /** 수정일 */
+    updatedAt: Date;
+}
+
+/**
+ * 이미지 관련 타입 정의
+ */
+
+/**
+ * Firebase Storage 설정
+ */
+interface FirebaseStorageConfig {
+    /** Storage 버킷명 */
+    bucket: string;
+    /** 베이스 경로 */
+    basePath: string;
+}
+/**
+ * 차량 이미지 파라미터
+ */
+interface VehicleImageParams {
+    /** 브랜드 ID (소문자) */
+    brand: BrandId | string;
+    /** 모델 슬러그 (소문자, 하이픈) */
+    model: ModelSlug | string;
+    /** 연식 */
+    year: number;
+    /** 트림 슬러그 (선택적, 소문자, 하이픈) */
+    trim?: TrimSlug | string;
+}
+/**
+ * 이미지 URL 생성 옵션
+ */
+interface ImageUrlOptions {
+    /** Firebase Storage 버킷명 */
+    bucket?: string;
+    /** 파일 확장자 */
+    extension?: 'png' | 'jpg' | 'webp';
+    /** Fallback 이미지 사용 여부 */
+    useFallback?: boolean;
+}
+/**
+ * 이미지 파일명 형식
+ * @example 'hyundai__ioniq-5__2024.png', 'mini__cooper__2025__jcw.png'
+ */
+type ImageFilename = `${string}__${string}__${number}${`__${string}` | ''}.${string}`;
+/**
+ * 이미지 경로 정보
+ */
+interface ImagePath {
+    /** Firebase Storage 전체 경로 */
+    fullPath: string;
+    /** 디렉토리 경로 */
+    directory: string;
+    /** 파일명 */
+    filename: ImageFilename;
+    /** 다운로드 URL */
+    downloadUrl: string;
+}
+/**
+ * 이미지 Fallback 전략
+ */
+type ImageFallbackStrategy = 'trim' | 'standard' | 'base' | 'brand';
+/**
+ * 이미지 Fallback 옵션
+ */
+interface ImageFallbackOptions {
+    /** Fallback 전략 배열 */
+    strategies: ImageFallbackStrategy[];
+    /** 기본 이미지 URL */
+    defaultImageUrl?: string;
+}
+
+/**
+ * 브랜드 매핑 유틸리티
+ *
+ * 한글/영문 브랜드명 변환, Firestore ID 정규화, Storage 브랜드명 매핑
+ */
+
+/**
+ * 브랜드 ID 정규화 (소문자 통일)
+ *
+ * @param brandInput - 브랜드명 (한글, 영문, 대소문자 무관)
+ * @returns Firestore 브랜드 ID (소문자, 하이픈)
+ *
+ * @example
+ * ```typescript
+ * normalizeBrandId('현대'); // 'hyundai'
+ * normalizeBrandId('BMW'); // 'bmw'
+ * normalizeBrandId('Mercedes-Benz'); // 'mercedes-benz'
+ * ```
+ */
+declare function normalizeBrandId(brandInput: string): BrandId;
+/**
+ * 한글 브랜드명 가져오기
+ *
+ * @param brandId - Firestore 브랜드 ID
+ * @returns 한글 브랜드명
+ *
+ * @example
+ * ```typescript
+ * getBrandNameKorean('hyundai'); // '현대'
+ * getBrandNameKorean('bmw'); // 'BMW'
+ * ```
+ */
+declare function getBrandNameKorean(brandId: BrandId): string;
+/**
+ * 영문 브랜드명 가져오기
+ *
+ * @param brandId - Firestore 브랜드 ID
+ * @returns 영문 브랜드명
+ *
+ * @example
+ * ```typescript
+ * getBrandNameEnglish('hyundai'); // 'HYUNDAI'
+ * getBrandNameEnglish('mercedes-benz'); // 'Mercedes-Benz'
+ * ```
+ */
+declare function getBrandNameEnglish(brandId: BrandId): string;
+/**
+ * Firebase Storage 브랜드명 가져오기
+ *
+ * @param brandId - Firestore 브랜드 ID
+ * @returns Storage 브랜드명 (대문자)
+ *
+ * @example
+ * ```typescript
+ * getStorageBrandName('hyundai'); // 'HYUNDAI'
+ * getStorageBrandName('mercedes-benz'); // 'BENZ'
+ * getStorageBrandName('mercedes-maybach'); // 'BENZ'
+ * ```
+ */
+declare function getStorageBrandName(brandId: BrandId): StorageBrandName;
+/**
+ * 브랜드 매핑 정보 가져오기 (통합 함수)
+ *
+ * @param brandInput - 브랜드명 (한글, 영문, 대소문자 무관)
+ * @returns 브랜드 매핑 정보
+ *
+ * @example
+ * ```typescript
+ * getBrandMapping('현대');
+ * // {
+ * //   firestoreId: 'hyundai',
+ * //   koreanName: '현대',
+ * //   englishName: 'HYUNDAI',
+ * //   storageName: 'HYUNDAI'
+ * // }
+ * ```
+ */
+declare function getBrandMapping(brandInput: string): BrandMapping;
+/**
+ * 지원되는 모든 브랜드 ID 목록
+ */
+declare const SUPPORTED_BRANDS: BrandId[];
+
+/**
+ * 모델 매핑 유틸리티
+ *
+ * 한글/영문 모델명 변환, 모델 ID 정규화, 유사도 기반 매칭
+ */
+
+/**
+ * 문자열을 슬러그로 변환
+ * - 소문자 변환
+ * - 공백/언더바 → 하이픈
+ * - 연속 하이픈 제거
+ * - 앞뒤 하이픈 제거
+ *
+ * @param str - 변환할 문자열
+ * @returns 슬러그 문자열
+ *
+ * @example
+ * ```typescript
+ * toSlug('IONIQ 5'); // 'ioniq-5'
+ * toSlug('Model S'); // 'model-s'
+ * toSlug('Cooper  JCW'); // 'cooper-jcw'
+ * ```
+ */
+declare function toSlug(str: string): string;
+/**
+ * 한글 모델명을 영문으로 변환
+ *
+ * @param koreanModel - 한글 모델명
+ * @returns 영문 모델명
+ *
+ * @example
+ * ```typescript
+ * convertKoreanToEnglish('아이오닉 5'); // 'IONIQ 5'
+ * convertKoreanToEnglish('니로 EV'); // 'NIRO EV'
+ * convertKoreanToEnglish('쿠퍼'); // 'COOPER'
+ * ```
+ */
+declare function convertKoreanToEnglish(koreanModel: string): string;
+/**
+ * 모델 ID 정규화 (소문자, 하이픈)
+ *
+ * @param modelInput - 모델명 (한글, 영문, 대소문자 무관)
+ * @returns Firestore 모델 ID (소문자, 하이픈)
+ *
+ * @example
+ * ```typescript
+ * normalizeModelId('아이오닉 5'); // 'ioniq-5'
+ * normalizeModelId('Model S'); // 'model-s'
+ * normalizeModelId('COOPER JCW'); // 'cooper-jcw'
+ * ```
+ */
+declare function normalizeModelId(modelInput: string): ModelId;
+/**
+ * 가능한 모델 목록에서 최적 매칭 찾기
+ * - 정확한 매칭 우선
+ * - 없으면 유사도 점수 기반 매칭
+ *
+ * @param inputModel - 입력 모델명
+ * @param availableModels - 가능한 모델 ID 목록
+ * @returns 매칭된 모델 ID 또는 null
+ *
+ * @example
+ * ```typescript
+ * findBestModelMatch('아이오닉5', ['ioniq-5', 'ioniq-6', 'kona-electric']);
+ * // 'ioniq-5'
+ *
+ * findBestModelMatch('NEXSO', ['ioniq-5', 'nexo', 'kona-electric']);
+ * // 'nexo' (유사도 매칭)
+ * ```
+ */
+declare function findBestModelMatch(inputModel: string, availableModels: string[]): string | null;
+/**
+ * 모델 슬러그 생성 (URL/파일명용)
+ *
+ * @param modelInput - 모델명
+ * @returns 모델 슬러그
+ *
+ * @example
+ * ```typescript
+ * getModelSlug('아이오닉 5'); // 'ioniq-5'
+ * getModelSlug('Model 3'); // 'model-3'
+ * ```
+ */
+declare function getModelSlug(modelInput: string): ModelSlug;
+/**
+ * 모델 매핑 정보 가져오기
+ *
+ * @param modelInput - 모델명 (한글 또는 영문)
+ * @param englishName - 영문 모델명 (선택적)
+ * @param koreanName - 한글 모델명 (선택적)
+ * @returns 모델 매핑 정보
+ *
+ * @example
+ * ```typescript
+ * getModelMapping('아이오닉 5', 'IONIQ-5', '아이오닉 5');
+ * // {
+ * //   firestoreId: 'ioniq-5',
+ * //   koreanName: '아이오닉 5',
+ * //   englishName: 'IONIQ-5',
+ * //   slug: 'ioniq-5'
+ * // }
+ * ```
+ */
+declare function getModelMapping(modelInput: string, englishName?: string, koreanName?: string): ModelMapping;
+
+/**
+ * 이미지 파일명 생성 유틸리티
+ *
+ * 표준 파일명 규칙: {brandSlug}__{modelSlug}__{year}__{trimSlug}.png
+ */
+
+/**
+ * 차량 이미지 파일명 생성
+ *
+ * @param params - 차량 이미지 파라미터
+ * @param extension - 파일 확장자 (기본: 'png')
+ * @returns 이미지 파일명
+ *
+ * @example
+ * ```typescript
+ * generateImageFilename({
+ *   brand: 'hyundai',
+ *   model: 'ioniq-5',
+ *   year: 2024
+ * });
+ * // 'hyundai__ioniq-5__2024.png'
+ *
+ * generateImageFilename({
+ *   brand: 'mini',
+ *   model: 'cooper',
+ *   year: 2025,
+ *   trim: 'jcw'
+ * });
+ * // 'mini__cooper__2025__jcw.png'
+ *
+ * generateImageFilename({
+ *   brand: 'Tesla',
+ *   model: 'Model 3',
+ *   year: 2024,
+ *   trim: 'Highland'
+ * }, 'webp');
+ * // 'tesla__model-3__2024__highland.webp'
+ * ```
+ */
+declare function generateImageFilename(params: VehicleImageParams, extension?: 'png' | 'jpg' | 'webp'): ImageFilename;
+/**
+ * 파일명에서 차량 정보 추출
+ *
+ * @param filename - 이미지 파일명
+ * @returns 차량 정보 또는 null
+ *
+ * @example
+ * ```typescript
+ * parseImageFilename('hyundai__ioniq-5__2024.png');
+ * // { brand: 'hyundai', model: 'ioniq-5', year: 2024 }
+ *
+ * parseImageFilename('mini__cooper__2025__jcw.png');
+ * // { brand: 'mini', model: 'cooper', year: 2025, trim: 'jcw' }
+ * ```
+ */
+declare function parseImageFilename(filename: string): VehicleImageParams | null;
+/**
+ * 파일명 검증
+ *
+ * @param filename - 검증할 파일명
+ * @returns 유효 여부
+ *
+ * @example
+ * ```typescript
+ * isValidImageFilename('hyundai__ioniq-5__2024.png'); // true
+ * isValidImageFilename('invalid-filename.png'); // false
+ * ```
+ */
+declare function isValidImageFilename(filename: string): boolean;
+
+/**
+ * 이미지 URL 생성 유틸리티
+ *
+ * Firebase Storage URL 생성 및 Fallback 처리
+ */
+
+/**
+ * 차량 이미지 URL 생성
+ *
+ * @param params - 차량 이미지 파라미터
+ * @param options - URL 생성 옵션
+ * @returns 이미지 다운로드 URL
+ *
+ * @example
+ * ```typescript
+ * generateVehicleImageUrl({
+ *   brand: 'hyundai',
+ *   model: 'ioniq-5',
+ *   year: 2024
+ * });
+ * // 'https://firebasestorage.googleapis.com/v0/b/charzing-d1600.firebasestorage.app/o/
+ * //  vehicle-images%2FHYUNDAI%2FIONIQ-5%2F2024%2Fhyundai__ioniq-5__2024.png?alt=media'
+ *
+ * generateVehicleImageUrl({
+ *   brand: 'mini',
+ *   model: 'cooper',
+ *   year: 2025,
+ *   trim: 'jcw'
+ * });
+ * // 'https://firebasestorage.googleapis.com/v0/b/charzing-d1600.firebasestorage.app/o/
+ * //  vehicle-images%2FMINI%2FCOOPER%2F2025%2Fmini__cooper__2025__jcw.png?alt=media'
+ * ```
+ */
+declare function generateVehicleImageUrl(params: VehicleImageParams, options?: ImageUrlOptions): string;
+/**
+ * 차량 이미지 경로 정보 가져오기
+ *
+ * @param params - 차량 이미지 파라미터
+ * @param options - URL 생성 옵션
+ * @returns 이미지 경로 정보
+ *
+ * @example
+ * ```typescript
+ * getVehicleImagePath({
+ *   brand: 'hyundai',
+ *   model: 'ioniq-5',
+ *   year: 2024
+ * });
+ * // {
+ * //   fullPath: 'vehicle-images/HYUNDAI/IONIQ-5/2024/hyundai__ioniq-5__2024.png',
+ * //   directory: 'vehicle-images/HYUNDAI/IONIQ-5/2024',
+ * //   filename: 'hyundai__ioniq-5__2024.png',
+ * //   downloadUrl: 'https://...'
+ * // }
+ * ```
+ */
+declare function getVehicleImagePath(params: VehicleImageParams, options?: ImageUrlOptions): ImagePath;
+/**
+ * Fallback 이미지 URL 목록 생성
+ *
+ * @param params - 차량 이미지 파라미터
+ * @param options - URL 생성 옵션
+ * @returns Fallback URL 목록 (우선순위 순)
+ *
+ * @example
+ * ```typescript
+ * generateFallbackUrls({
+ *   brand: 'mini',
+ *   model: 'cooper',
+ *   year: 2025,
+ *   trim: 'jcw'
+ * });
+ * // [
+ * //   'https://.../mini__cooper__2025__jcw.png',     // 트림 이미지
+ * //   'https://.../mini__cooper__2025.png',          // 기본 모델 이미지
+ * // ]
+ * ```
+ */
+declare function generateFallbackUrls(params: VehicleImageParams, options?: ImageUrlOptions): string[];
+
+export { type BatteryInfo, type Brand, type BrandId, type BrandMapping, type CompletedVehicle, type DriveType, type FirebaseStorageConfig, type ImageFallbackOptions, type ImageFallbackStrategy, type ImageFilename, type ImagePath, type ImageUrlOptions, type Model, type ModelId, type ModelMapping, type ModelSlug, SUPPORTED_BRANDS, type StorageBrandName, type TrimId, type TrimMapping, type TrimSlug, type UserVehicle, type VehicleDetails, type VehicleImageParams, type VehicleModel, type VehicleTrim, type VehicleVariant, convertKoreanToEnglish, findBestModelMatch, generateFallbackUrls, generateImageFilename, generateVehicleImageUrl, getBrandMapping, getBrandNameEnglish, getBrandNameKorean, getModelMapping, getModelSlug, getStorageBrandName, getVehicleImagePath, isValidImageFilename, normalizeBrandId, normalizeModelId, parseImageFilename, toSlug };