@charzing/vehicle-utils 0.2.3 → 0.2.5

package/README.md

@@ -1,130 +1,387 @@
 # @charzing/vehicle-utils
 
-Shared utilities for Charzing vehicle data management across all platforms.
+Charzing 차량 데이터 관리를 위한 공유 유틸리티 라이브러리
 
-## 설치
+## 📋 프로젝트 개요
+
+**@charzing/vehicle-utils**는 Charzing 생태계의 모든 플랫폼(웹, 모바일, 관리자)에서 일관되게 사용할 수 있는 차량 데이터 변환 및 매핑 유틸리티를 제공합니다.
+
+### 주요 기능
+- 🔄 브랜드/모델 ID 정규화 (한국어 ↔ 영어)
+- 🖼️ Firebase Storage 차량 이미지 URL 생성
+- 🏷️ 표준 파일명 생성 규칙
+- 📦 TypeScript 완전 타입 지원
+
+---
+
+## 🛠️ 기술 스택
+
+- **Language**: TypeScript 5
+- **Build**: tsup (esbuild 기반)
+- **Package Manager**: npm
+- **Module**: ESM + CJS 모두 지원
+
+---
+
+## 📦 설치 방법
 
 ### 로컬 개발 (npm link)
 
 ```bash
+# 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
+cd /Users/sungmin/Desktop/project/react/charzing
 npm link @charzing/vehicle-utils
 ```
 
-## 주요 기능
+### npm 패키지로 설치 (프로덕션)
+
+```bash
+npm install @charzing/vehicle-utils
+```
+
+---
+
+## 🚀 주요 API
 
 ### 1. 브랜드 매핑
 
+#### `normalizeBrandId(brand: string): string`
+브랜드명을 표준 Firestore ID로 정규화합니다.
+
+```typescript
+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로 한글 브랜드명을 가져옵니다.
+
 ```typescript
-import { normalizeBrandId, getBrandNameKorean, getBrandNameEnglish } from '@charzing/vehicle-utils';
+import { getBrandNameKorean } from '@charzing/vehicle-utils';
+
+getBrandNameKorean('hyundai');        // '현대'
+getBrandNameKorean('mercedes-benz');  // '메르세데스-벤츠'
+getBrandNameKorean('BMW');            // 'BMW'
+```
 
-// 브랜드 ID 정규화 (모두 소문자)
-const brandId = normalizeBrandId('현대'); // 'hyundai'
-const brandId2 = normalizeBrandId('BMW'); // 'bmw'
+#### `getBrandNameEnglish(brandId: string): string`
+Firestore ID로 영문 브랜드명을 가져옵니다.
 
-// 한글 브랜드명 가져오기
-const korean = getBrandNameKorean('hyundai'); // '현대'
+```typescript
+import { getBrandNameEnglish } from '@charzing/vehicle-utils';
 
-// 영문 브랜드명 가져오기
-const english = getBrandNameEnglish('hyundai'); // 'HYUNDAI'
+getBrandNameEnglish('hyundai');  // 'HYUNDAI'
+getBrandNameEnglish('bmw');      // 'BMW'
+getBrandNameEnglish('mini');     // 'MINI'
 ```
 
+---
+
 ### 2. 모델 매핑
 
+#### `normalizeModelId(model: string): string`
+모델명을 표준 Firestore ID로 정규화합니다.
+
 ```typescript
-import { normalizeModelId, getModelNameKorean, getModelNameEnglish } from '@charzing/vehicle-utils';
+import { normalizeModelId } from '@charzing/vehicle-utils';
 
-// 모델 ID 정규화 (소문자, 하이픈)
-const modelId = normalizeModelId('아이오닉 5'); // 'ioniq-5'
-const modelId2 = normalizeModelId('Model S'); // 'model-s'
+// 한국어 → 영어 소문자
+normalizeModelId('아이오닉 5');  // 'ioniq-5'
+normalizeModelId('EV6');         // 'ev6'
+normalizeModelId('Model S');     // 'model-s'
 
-// 한글 모델명 가져오기
-const korean = getModelNameKorean('ioniq-5'); // '아이오닉 5'
+// 공백 → 하이픈 변환
+normalizeModelId('쿠퍼');        // 'cooper'
+normalizeModelId('Model 3');     // 'model-3'
+```
+
+#### `getModelNameKorean(modelId: string): string`
+Firestore ID로 한글 모델명을 가져옵니다.
 
-// 영문 모델명 가져오기
-const english = getModelNameEnglish('ioniq-5'); // 'IONIQ-5'
+```typescript
+import { getModelNameKorean } from '@charzing/vehicle-utils';
+
+getModelNameKorean('ioniq-5');   // '아이오닉 5'
+getModelNameKorean('ev6');       // 'EV6'
+getModelNameKorean('cooper');    // '쿠퍼'
 ```
 
+#### `getModelNameEnglish(modelId: string): string`
+Firestore ID로 영문 모델명을 가져옵니다.
+
+```typescript
+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을 생성합니다.
+
 ```typescript
-import { generateVehicleImageUrl, generateImageFilename } from '@charzing/vehicle-utils';
+import { generateVehicleImageUrl } from '@charzing/vehicle-utils';
 
-// Firebase Storage URL 생성
-const imageUrl = generateVehicleImageUrl({
+// 기본 이미지 (트림 없음)
+const url1 = generateVehicleImageUrl({
   brand: 'hyundai',
   model: 'ioniq-5',
-  year: 2024,
-  trim: 'exclusive'
+  year: 2024
 });
 // → https://firebasestorage.googleapis.com/v0/b/charzing-d1600.firebasestorage.app/o/
-//   vehicle-images%2FHYUNDAI%2FIONIQ-5%2F2024%2Fhyundai__ioniq-5__2024__exclusive.png?alt=media
-
-// 이미지 파일명만 생성
-const filename = generateImageFilename({
-  brand: 'hyundai',
-  model: 'ioniq-5',
-  year: 2024,
-  trim: 'exclusive'
+//   vehicle-images%2FHYUNDAI%2FIONIQ-5%2F2024%2Fhyundai__ioniq-5__2024.png?alt=media
+
+// 트림별 이미지
+const url2 = generateVehicleImageUrl({
+  brand: 'mini',
+  model: 'cooper',
+  year: 2025,
+  trim: 'jcw'
 });
-// → 'hyundai__ioniq-5__2024__exclusive.png'
+// → https://firebasestorage.googleapis.com/v0/b/charzing-d1600.firebasestorage.app/o/
+//   vehicle-images%2FMINI%2FCOOPER%2F2025%2Fmini__cooper__2025__jcw.png?alt=media
+```
 
-// 트림 없는 경우
-const filename2 = generateImageFilename({
+**파라미터**:
+```typescript
+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`
+이미지 파일명만 생성합니다.
+
+```typescript
+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
 ```
 
-### 4. 파일명 규칙
+### 규칙
+1. **전부 소문자**: `hyundai`, `ioniq-5`
+2. **단어 구분**: 하이픈 (`-`)
+3. **상위 구분**: 더블 언더바 (`__`)
+4. **trim 없으면 생략**: `tesla__model-3__2024.png`
 
-- **패턴**: `{brandSlug}__{modelSlug}__{year}__{trimSlug}.png`
-- **예시**:
-  - `hyundai__ioniq-5__2024.png`
-  - `mini__cooper__2025__jcw.png`
-  - `tesla__model-3__2024__highland.png`
-- **규칙**:
-  - 전부 소문자
-  - 단어 구분: 하이픈 (-)
-  - 상위 구분: 더블 언더바 (__)
-  - trim 없으면 생략
+### 예시
+```
+✅ 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         # 빌드 설정
+```
 
-## 개발
+---
+
+## 🔧 개발 가이드
+
+### 빌드 명령어
 
 ```bash
 # 의존성 설치
 npm install
 
-# 빌드
-npm run build
-
-# Watch 모드로 빌드
+# 개발 모드 (Watch)
 npm run dev
 
-# 테스트
-npm test
+# 프로덕션 빌드
+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 타입 정의
 ```
 
-## 라이선스
+---
+
+## 🔄 업데이트 가이드
+
+### 로컬 개발 시
+```bash
+# 1. vehicle-utils 수정 후 재빌드
+cd /Users/sungmin/charzing-vehicle-utils
+npm run build
+
+# 2. 각 프로젝트는 자동 반영됨 (npm link로 연결되어 있음)
+```
+
+### 프로덕션 배포 시
+```bash
+# 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 타입 지원을 제공합니다.
+
+```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;
+```
+
+---
+
+## ⚠️ 주의사항
+
+1. **브랜드 대소문자**: BMW, MINI, PORSCHE는 Firestore에서 대문자 사용
+2. **Storage URL**: `charzing-d1600.firebasestorage.app` (`.appspot.com` ❌)
+3. **파일명 규칙**: 반드시 더블 언더바(`__`) 구분자 사용
+4. **npm link**: 로컬 개발 시 빌드 후 변경사항 자동 반영됨
+
+---
+
+## 📄 라이선스
 
 MIT
+
+---
+
+**마지막 업데이트**: 2025년 12월 12일
+**버전**: 0.2.4
+**관리자**: Charzing 개발팀

package/dist/cjs/index.d.ts

@@ -1,4 +1,5 @@
 import { Firestore } from 'firebase/firestore';
+export { CELL_MAP_UNSUPPORTED_GROUPS, CELL_MAP_UNSUPPORTED_NOTICE, CELL_VOLTAGE_DELTA_THRESHOLDS, CellMapReportRef, CellMapUnsupportedGroup, CellVoltageVerdict, findCellMapUnsupportedGroup, isCellMapSupported, judgeCellVoltageByDelta } from './report/cellMap.js';
 
 /**
  * 브랜드 관련 타입 정의
@@ -105,6 +106,15 @@ type TrimId = string;
  * 구동 방식
  */
 type DriveType = 'FWD' | 'RWD' | 'AWD' | '4WD';
+/**
+ * 배터리 옵션 (복수 배터리 제조사 지원)
+ */
+interface BatteryOption {
+    /** 배터리 제조사 */
+    supplier: string;
+    /** VIN 패턴, 생산 시기 등 조건 (선택사항) */
+    condition?: string;
+}
 /**
  * 차량 변형 (연식별 스펙)
  */
@@ -115,8 +125,10 @@ interface VehicleVariant {
     batteryCapacity: number;
     /** 주행거리 (km) */
     range: number;
-    /** 배터리 공급사 */
+    /** 배터리 공급사 (단일, 기존 호환) */
     supplier?: string;
+    /** 복수 배터리 공급사 (optional, supplier와 상호 배타적) */
+    batteryOptions?: BatteryOption[];
     /** 배터리 타입 */
     batteryType?: string;
     /** 이미지 URL (트림별 디자인 차이가 있는 경우) */

package/dist/cjs/index.js

@@ -20,9 +20,13 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  CELL_MAP_UNSUPPORTED_GROUPS: () => CELL_MAP_UNSUPPORTED_GROUPS,
+  CELL_MAP_UNSUPPORTED_NOTICE: () => CELL_MAP_UNSUPPORTED_NOTICE,
+  CELL_VOLTAGE_DELTA_THRESHOLDS: () => CELL_VOLTAGE_DELTA_THRESHOLDS,
   SUPPORTED_BRANDS: () => SUPPORTED_BRANDS,
   convertKoreanToEnglish: () => convertKoreanToEnglish,
   findBestModelMatch: () => findBestModelMatch,
+  findCellMapUnsupportedGroup: () => findCellMapUnsupportedGroup,
   generateImageFilename: () => generateImageFilename,
   generateStoragePath: () => generateStoragePath,
   generateVehicleImageUrl: () => generateVehicleImageUrl,
@@ -40,7 +44,9 @@ __export(index_exports, {
   initializeBrandMappings: () => initializeBrandMappings,
   initializeModelMappings: () => initializeModelMappings,
   isBrandMappingInitialized: () => isInitialized,
+  isCellMapSupported: () => isCellMapSupported,
   isModelMappingInitialized: () => isInitialized2,
+  judgeCellVoltageByDelta: () => judgeCellVoltageByDelta,
   normalizeBrandId: () => normalizeBrandId,
   normalizeModelId: () => normalizeModelId,
   resetBrandCache: () => resetCache,
@@ -448,7 +454,8 @@ function generateImageFilename(params) {
   const { brandId, modelId, year, trim } = params;
   const brandLower = brandId.toLowerCase();
   const modelLower = modelId.toLowerCase().replace(/[\s]/g, "-");
-  const trimPart = trim ? `__${normalizeStorageTrim(trim)}` : "";
+  const normalizedTrim = trim ? normalizeStorageTrim(trim) : "";
+  const trimPart = normalizedTrim ? `__${normalizedTrim}` : "";
   return `${brandLower}__${modelLower}__${year}${trimPart}.png`;
 }
 function generateStoragePath(params) {
@@ -472,11 +479,96 @@ function generateVehicleImageUrl(params) {
   const encodedPath = encodeURIComponent(path);
   return `${FIREBASE_STORAGE_BASE}/${encodedPath}?alt=media`;
 }
+
+// src/report/cellMap.ts
+var CELL_MAP_UNSUPPORTED_GROUPS = [
+  {
+    label: "MINI \uCFE0\uD37C SE (2022~2023)",
+    templateIds: ["YsOQDxElF5P0thuUHKhE"],
+    // vehicles/mini/models/COOPER — name: cooper-se_2022_2023
+    years: [2022, 2023],
+    names: {
+      brand: ["\uBBF8\uB2C8", "MINI", "Mini"],
+      model: ["\uCFE0\uD37C", "COOPER", "Cooper", "Cooper SE", "\uCFE0\uD37C SE"],
+      trim: ["SE"]
+    },
+    reason: "\uC9C4\uB2E8\uAE30\uAC00 \uBAA8\uB4C8\uBCC4 \uC804\uC555\uC744 \uB0B4\uB824\uC8FC\uC9C0 \uC54A\uC74C (min/max\uB9CC \uC81C\uACF5)"
+  }
+];
+var CELL_MAP_UNSUPPORTED_NOTICE = {
+  /** 항상 노출 */
+  main: "\uC774 \uCC28\uB7C9\uC740 \uBAA8\uB4C8\uBCC4 \uC804\uC555\uC744 \uC81C\uACF5\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4",
+  /** min/max가 있을 때만 덧붙인다 — 없는 값을 있다고 말하지 않기 위해 */
+  sub: "\uCD5C\uC18C\xB7\uCD5C\uB300 \uC804\uC555\uB9CC \uCE21\uC815\uB429\uB2C8\uB2E4",
+  /** 어드민 수동 입력 화면에서 셀 입력을 잠글 때 */
+  inputLocked: "\uC774 \uCC28\uB7C9\uC740 \uBAA8\uB4C8\uBCC4 \uC804\uC555\uC744 \uC81C\uACF5\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4. \uCD5C\uC18C\xB7\uCD5C\uB300 \uC804\uC555\uB9CC \uC785\uB825\uD558\uC138\uC694."
+};
+function normalizeName(value) {
+  return value.replace(/\s+/g, "").toLowerCase();
+}
+function matchesAnyName(value, candidates) {
+  if (!value) return false;
+  const target = normalizeName(value);
+  if (!target) return false;
+  return candidates.some((candidate) => normalizeName(candidate) === target);
+}
+function parseYear(value) {
+  if (typeof value === "number") return Number.isFinite(value) ? value : null;
+  if (typeof value === "string") {
+    const parsed = Number.parseInt(value, 10);
+    return Number.isNaN(parsed) ? null : parsed;
+  }
+  return null;
+}
+function readTemplateId(report) {
+  return report.marketplaceData?.vehicleRef?.templateId ?? report.vehicleRef?.templateId ?? null;
+}
+function findCellMapUnsupportedGroup(report) {
+  if (!report) return null;
+  const templateId = readTemplateId(report);
+  const year = parseYear(report.vehicleYear);
+  for (const group of CELL_MAP_UNSUPPORTED_GROUPS) {
+    if (templateId && group.templateIds.includes(templateId)) {
+      if (year === null || group.years.includes(year)) return group;
+      continue;
+    }
+    if (!templateId) {
+      const brandHit = matchesAnyName(report.vehicleBrand, group.names.brand);
+      const modelHit = matchesAnyName(report.vehicleModel, group.names.model);
+      const trimHit = group.names.trim === void 0 || group.names.trim.length === 0 ? true : matchesAnyName(report.vehicleTrim, group.names.trim);
+      const yearHit = year === null ? false : group.years.includes(year);
+      if (brandHit && modelHit && trimHit && yearHit) return group;
+    }
+  }
+  return null;
+}
+function isCellMapSupported(report) {
+  return findCellMapUnsupportedGroup(report) === null;
+}
+var CELL_VOLTAGE_DELTA_THRESHOLDS = {
+  warning: 0.03,
+  danger: 0.1
+};
+function round2(value) {
+  return Math.round(value * 100) / 100;
+}
+function judgeCellVoltageByDelta(minVoltage, maxVoltage) {
+  if (typeof minVoltage !== "number" || typeof maxVoltage !== "number") return null;
+  if (!Number.isFinite(minVoltage) || !Number.isFinite(maxVoltage)) return null;
+  const delta = round2(round2(maxVoltage) - round2(minVoltage));
+  if (delta >= CELL_VOLTAGE_DELTA_THRESHOLDS.danger) return "danger";
+  if (delta >= CELL_VOLTAGE_DELTA_THRESHOLDS.warning) return "warning";
+  return "normal";
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  CELL_MAP_UNSUPPORTED_GROUPS,
+  CELL_MAP_UNSUPPORTED_NOTICE,
+  CELL_VOLTAGE_DELTA_THRESHOLDS,
   SUPPORTED_BRANDS,
   convertKoreanToEnglish,
   findBestModelMatch,
+  findCellMapUnsupportedGroup,
   generateImageFilename,
   generateStoragePath,
   generateVehicleImageUrl,
@@ -494,7 +586,9 @@ function generateVehicleImageUrl(params) {
   initializeBrandMappings,
   initializeModelMappings,
   isBrandMappingInitialized,
+  isCellMapSupported,
   isModelMappingInitialized,
+  judgeCellVoltageByDelta,
   normalizeBrandId,
   normalizeModelId,
   resetBrandCache,