@charzing/vehicle-utils
Charzing 차량 데이터 관리를 위한 공유 유틸리티 라이브러리
📋 프로젝트 개요
@charzing/vehicle-utils는 Charzing 생태계의 모든 플랫폼(웹, 모바일, 관리자)에서 일관되게 사용할 수 있는 차량 데이터 변환 및 매핑 유틸리티를 제공합니다.
주요 기능
- 🔄 브랜드/모델 ID 정규화 (한국어 ↔ 영어)
- 🖼️ Firebase Storage 차량 이미지 URL 생성
- 🏷️ 표준 파일명 생성 규칙
- 📦 TypeScript 완전 타입 지원
서브패스 (Firebase 의존 없음 — 서버·CF·앱 어디서나)
| 경로 | 내용 |
|---|---|
@charzing/vehicle-utils/template | 연식 템플릿 문서 모양 · 읽기 규칙 (normalizeTemplateYears 등) |
@charzing/vehicle-utils/report | 리포트 셀맵 |
@charzing/vehicle-utils/listing | 매물 게시 대기·상태 수명 키 + 목록 필터·정렬·파셋 판정(toListVehicle·applyVehicleFilters·sortVehicles, 범위 상수) |
@charzing/vehicle-utils/terms | 약관·고지 문안(웹·앱 공용) |
@charzing/vehicle-utils/dealer | 딜러 판정 — 같은 VIN 대표 1건(pickLatestPerVin), 온보딩 단계(purchaseStage·shippingStage·resolveOnboardingStep) |
🛠️ 기술 스택
- Language: TypeScript 5
- Build: tsup (esbuild 기반)
- Package Manager: npm
- Module: ESM + CJS 모두 지원
📦 설치 방법
로컬 개발 (npm link)
# 1. vehicle-utils 빌드
cd /Users/sungmin/charzing-vehicle-utils
npm install
npm run build
npm link
# 2. 각 프로젝트에서 링크
cd /Users/sungmin/charzing-admin
npm link @charzing/vehicle-utils
cd /Users/sungmin/CharzingApp-Expo
npm link @charzing/vehicle-utils
cd /Users/sungmin/Desktop/project/react/charzing
npm link @charzing/vehicle-utils
npm 패키지로 설치 (프로덕션)
npm install @charzing/vehicle-utils
🚀 주요 API
1. 브랜드 매핑
normalizeBrandId(brand: string): string
브랜드명을 표준 Firestore ID로 정규화합니다.
import { normalizeBrandId } from '@charzing/vehicle-utils';
// 한국어 → 영어 소문자
normalizeBrandId('현대'); // 'hyundai'
normalizeBrandId('기아'); // 'kia'
normalizeBrandId('테슬라'); // 'tesla'
// 대문자 유지 브랜드 (BMW, MINI, PORSCHE)
normalizeBrandId('BMW'); // 'bmw'
normalizeBrandId('MINI'); // 'mini'
normalizeBrandId('PORSCHE'); // 'porsche'
// 메르세데스-벤츠 처리
normalizeBrandId('메르세데스-벤츠'); // 'mercedes-benz'
normalizeBrandId('벤츠'); // 'mercedes-benz'
getBrandNameKorean(brandId: string): string
Firestore ID로 한글 브랜드명을 가져옵니다.
import { getBrandNameKorean } from '@charzing/vehicle-utils';
getBrandNameKorean('hyundai'); // '현대'
getBrandNameKorean('mercedes-benz'); // '메르세데스-벤츠'
getBrandNameKorean('BMW'); // 'BMW'
getBrandNameEnglish(brandId: string): string
Firestore ID로 영문 브랜드명을 가져옵니다.
import { getBrandNameEnglish } from '@charzing/vehicle-utils';
getBrandNameEnglish('hyundai'); // 'HYUNDAI'
getBrandNameEnglish('bmw'); // 'BMW'
getBrandNameEnglish('mini'); // 'MINI'
2. 모델 매핑
normalizeModelId(model: string): string
모델명을 표준 Firestore ID로 정규화합니다.
import { normalizeModelId } from '@charzing/vehicle-utils';
// 한국어 → 영어 소문자
normalizeModelId('아이오닉 5'); // 'ioniq-5'
normalizeModelId('EV6'); // 'ev6'
normalizeModelId('Model S'); // 'model-s'
// 공백 → 하이픈 변환
normalizeModelId('쿠퍼'); // 'cooper'
normalizeModelId('Model 3'); // 'model-3'
getModelNameKorean(modelId: string): string
Firestore ID로 한글 모델명을 가져옵니다.
import { getModelNameKorean } from '@charzing/vehicle-utils';
getModelNameKorean('ioniq-5'); // '아이오닉 5'
getModelNameKorean('ev6'); // 'EV6'
getModelNameKorean('cooper'); // '쿠퍼'
getModelNameEnglish(modelId: string): string
Firestore ID로 영문 모델명을 가져옵니다.
import { getModelNameEnglish } from '@charzing/vehicle-utils';
getModelNameEnglish('ioniq-5'); // 'IONIQ-5'
getModelNameEnglish('model-s'); // 'MODEL-S'
3. 이미지 URL 생성
generateVehicleImageUrl(params: ImageParams): string
Firebase Storage 차량 이미지 URL을 생성합니다.
import { generateVehicleImageUrl } from '@charzing/vehicle-utils';
// 기본 이미지 (트림 없음)
const url1 = 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
// 트림별 이미지
const url2 = 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
파라미터:
interface ImageParams {
brand: string; // 브랜드 ID (예: 'hyundai', 'bmw')
model: string; // 모델 ID (예: 'ioniq-5', 'model-s')
year: number; // 연도 (예: 2024)
trim?: string; // 트림 ID (선택, 예: 'exclusive', 'jcw')
}
generateImageFilename(params: ImageParams): string
이미지 파일명만 생성합니다.
import { generateImageFilename } from '@charzing/vehicle-utils';
// 기본 파일명
generateImageFilename({
brand: 'tesla',
model: 'model-s',
year: 2024
});
// → 'tesla__model-s__2024.png'
// 트림 포함 파일명
generateImageFilename({
brand: 'porsche',
model: 'taycan',
year: 2025,
trim: 'turbo-gt'
});
// → 'porsche__taycan__2025__turbo-gt.png'
📝 파일명 규칙
표준 패턴
{brandSlug}__{modelSlug}__{year}[__{trimSlug}].png
규칙
- 전부 소문자:
hyundai,ioniq-5 - 단어 구분: 하이픈 (
-) - 상위 구분: 더블 언더바 (
__) - trim 없으면 생략:
tesla__model-3__2024.png
예시
✅ hyundai__ioniq-5__2024.png
✅ mini__cooper__2025__jcw.png
✅ tesla__model-3__2024__highland.png
✅ mercedes-benz__eqs__2024.png
❌ Hyundai_ioniq-5_2024.png (대문자 사용)
❌ hyundai-ioniq-5-2024.png (구분자 통일 안됨)
❌ hyundai_ioniq-5_2024.png (단일 언더바)
🏗️ 프로젝트 구조
charzing-vehicle-utils/
├── src/
│ ├── index.ts # 메인 엔트리포인트
│ ├── brand.ts # 브랜드 매핑 함수
│ ├── model.ts # 모델 매핑 함수
│ ├── image.ts # 이미지 URL 생성
│ └── types.ts # TypeScript 타입 정의
├── dist/ # 빌드 결과물 (ESM + CJS)
├── package.json
├── tsconfig.json
└── tsup.config.ts # 빌드 설정
🔧 개발 가이드
빌드 명령어
# 의존성 설치
npm install
# 개발 모드 (Watch)
npm run dev
# 프로덕션 빌드
npm run build
# 타입 검사
npm run type-check
# 린트
npm run lint
# 테스트
npm test
빌드 결과물
dist/
├── index.js # CommonJS (require)
├── index.mjs # ESM (import)
├── index.d.ts # TypeScript 타입 정의
└── index.d.mts # ESM 타입 정의
🔄 업데이트 가이드
로컬 개발 시
# 1. vehicle-utils 수정 후 재빌드
cd /Users/sungmin/charzing-vehicle-utils
npm run build
# 2. 각 프로젝트는 자동 반영됨 (npm link로 연결되어 있음)
프로덕션 배포 시
# 1. 버전 업데이트
npm version patch # 1.0.0 → 1.0.1
# 2. 빌드
npm run build
# 3. npm 배포
npm publish
# 4. 각 프로젝트에서 업데이트
cd /Users/sungmin/charzing-admin
npm update @charzing/vehicle-utils
🔗 관련 프로젝트
이 라이브러리를 사용하는 프로젝트들:
1. charzing-admin
- 위치:
/Users/sungmin/charzing-admin - 사용: 차량 데이터 CRUD, 이미지 URL 생성
- 문서:
/Users/sungmin/charzing-admin/CLAUDE.md
2. CharzingApp-Expo
- 위치:
/Users/sungmin/CharzingApp-Expo - 사용: 차량 선택, Firebase 데이터 조회
- 문서:
/Users/sungmin/CharzingApp-Expo/CLAUDE.md
3. charzing (웹 앱)
- 위치:
/Users/sungmin/Desktop/project/react/charzing - 사용: 예약 시스템, 차량 이미지 표시
- 문서:
/Users/sungmin/Desktop/project/react/charzing/CLAUDE.md
📚 TypeScript 타입
모든 함수는 완전한 TypeScript 타입 지원을 제공합니다.
// 브랜드 매핑
export function normalizeBrandId(brand: string): string;
export function getBrandNameKorean(brandId: string): string;
export function getBrandNameEnglish(brandId: string): string;
// 모델 매핑
export function normalizeModelId(model: string): string;
export function getModelNameKorean(modelId: string): string;
export function getModelNameEnglish(modelId: string): string;
// 이미지 URL 생성
export interface ImageParams {
brand: string;
model: string;
year: number;
trim?: string;
}
export function generateVehicleImageUrl(params: ImageParams): string;
export function generateImageFilename(params: ImageParams): string;
⚠️ 주의사항
- 브랜드 대소문자: BMW, MINI, PORSCHE는 Firestore에서 대문자 사용
- Storage URL:
charzing-d1600.firebasestorage.app(.appspot.com❌) - 파일명 규칙: 반드시 더블 언더바(
__) 구분자 사용 - npm link: 로컬 개발 시 빌드 후 변경사항 자동 반영됨
📄 라이선스
MIT
마지막 업데이트: 2025년 12월 12일 버전: 0.2.4 관리자: Charzing 개발팀