AutonetSellCar/CLAUDE.md

# AutonetSellCar.com 개발 가이드

이 문서는 Claude Code 세션에서 반드시 읽고 참고해야 하는 중요한 정보입니다.

> **배포 시 반드시 [DEPLOYMENT.md](./DEPLOYMENT.md)도 함께 확인하세요!**
> - DB 스키마 변경 시 수동으로 ALTER TABLE 필요
> - 배포 명령어 및 롤백 방법 안내

---

# ⛔ CRITICAL: 배포 전 필수 확인사항 (DO NOT SKIP!)

## 🚨 Production 환경 고정값 (절대 변경 금지!)

| 항목 | 올바른 값 | 잘못된 예 |
|------|----------|----------|
| **DB_NAME** | `autonet` | ~~mongolcar~~, ~~autonet_db~~ |
| **DB_PASSWORD** | `roskfl@1122` (@ 포함, URL 인코딩 필요) | - |
| **API_URL (Frontend)** | `https://autonetsellcar.com` | ~~http://192.168.0.202:8000~~ |
| **Uploads 경로** | `/opt/autonet/production/backend/uploads` | ~~`/home/damon/mongolcar/data/uploads`~~ |
| **배포 디렉토리** | `/opt/autonet/production` | ~~`/home/damon/mongolcar`~~ |

## 🚫 절대 하지 말 것

1. **수동 `docker run`에서 환경변수 직접 타이핑 금지** - [PRODUCTION_VALUES.md](./PRODUCTION_VALUES.md)에서 복사만 허용
2. **DB_NAME 직접 타이핑 금지** - 반드시 `autonet` 복사/붙여넣기
3. **`.env` 파일 덮어쓰기 금지** - 서버의 기존 `.env` 보존
4. **`/home/damon/mongolcar/data/uploads` 사용 금지** - 비어있는 잘못된 경로

## ✅ 배포 전 필수 검증 명령어

```bash
# 1. DB 이름 확인 (반드시 autonet이어야 함!)
ssh server1 "docker exec postgres-primary psql -U admin -d autonet -c 'SELECT COUNT(*) FROM cars;'"

# 2. Uploads 경로에 파일 있는지 확인
ssh server2 "ls /opt/autonet/production/backend/uploads/cars/ | head -5"

# 3. 배포 후 API 확인
curl -s https://autonetsellcar.com/api/hero-banners/ | head -c 100
```

## 📋 표준 컨테이너 실행 명령어 (복사해서 사용!)

**⚠️ 아래 명령어를 그대로 복사해서 사용하세요. 절대 직접 타이핑하지 마세요!**

### Backend 실행
```bash
ssh server2 "docker stop autonet-backend 2>/dev/null; docker rm autonet-backend 2>/dev/null; docker run -d --name autonet-backend --restart unless-stopped -p 8000:8000 -e USE_SQLITE=False -e DB_HOST=192.168.0.201 -e DB_PORT=5432 -e DB_NAME=autonet -e DB_USER=admin -e 'DB_PASSWORD=roskfl@1122' -e REDIS_HOST=192.168.0.201 -e REDIS_PORT=6379 -e 'REDIS_PASSWORD=roskfl@1122' -e SECRET_KEY=YourSuperSecretKeyForJWT123! -e AGENT_API_KEY=AgentApiKey123! -v /opt/autonet/production/backend/uploads:/app/uploads --network mongolcar-network production-backend"
```

### Frontend 빌드 전 (.env.production 설정)
```bash
ssh server2 "echo 'NEXT_PUBLIC_API_URL=https://autonetsellcar.com' > /home/damon/mongolcar/frontend/.env.production"
```

### Frontend 실행
```bash
ssh server2 "docker stop autonet-frontend 2>/dev/null; docker rm autonet-frontend 2>/dev/null; docker run -d --name autonet-frontend --restart unless-stopped -p 3000:3000 --network mongolcar-network production-frontend"
```

---

## 🚀 배포 워크플로우 (필수!)

### 서버 구성

| 환경 | URL | 용도 |
|------|-----|------|
| **스테이징** | https://staging.autonetsellcar.com | 테스트용 (먼저 배포) |
| **프로덕션** | https://autonetsellcar.com | 실서비스 (테스트 후 배포) |

### 배포 순서 (반드시 준수!)

```
┌─────────────────────────────────────────────────────────────┐
│  1. 개발 PC에서 코드 수정                                    │
│     D:\Workspace\claudeCode\AutonetSellCar.com\              │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│  2. Git 커밋 및 푸시                                         │
│     git add .                                                │
│     git commit -m "변경 내용"                                │
│     git push staging main                                    │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│  3. 스테이징 서버 배포                                       │
│     - /opt/autonet/staging/frontend 에서 빌드               │
│     - https://staging.autonetsellcar.com 에서 테스트        │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│  4. 스테이징에서 충분히 테스트 후 → 프로덕션 배포            │
│     - /opt/autonet/production/frontend 에서 빌드            │
│     - https://autonetsellcar.com 확인                       │
└─────────────────────────────────────────────────────────────┘
```

### Git 저장소 정보

| 항목 | 값 |
|------|-----|
| 원격 저장소 | `ssh://damon@192.168.0.202/opt/autonet/git/autonet.git` |
| 브랜치 | `main` |
| 원격 이름 | `staging` |

### 스테이징 배포 명령어

```bash
# 1. 소스 동기화
scp -r frontend/src damon@192.168.0.202:/opt/autonet/staging/frontend/

# 2. .env.production 설정
ssh server2 "echo 'NEXT_PUBLIC_API_URL=https://staging.autonetsellcar.com' > /opt/autonet/staging/frontend/.env.production"

# 3. Docker 빌드 및 재시작
ssh server2 "cd /opt/autonet/staging/frontend && docker build --no-cache -t staging-frontend . && docker stop autonet-frontend-staging; docker rm autonet-frontend-staging; docker run -d --name autonet-frontend-staging --restart unless-stopped -p 3001:3000 staging-frontend"
```

### 프로덕션 배포 명령어

```bash
# 1. 소스 동기화
scp -r frontend/src damon@192.168.0.202:/opt/autonet/production/frontend/

# 2. .env.production 설정 (HTTPS 필수!)
ssh server2 "echo 'NEXT_PUBLIC_API_URL=https://autonetsellcar.com' > /opt/autonet/production/frontend/.env.production"

# 3. Docker 빌드 및 재시작
ssh server2 "cd /opt/autonet/production/frontend && docker build --no-cache -t production-frontend . && docker stop autonet-frontend; docker rm autonet-frontend; docker run -d --name autonet-frontend --restart unless-stopped -p 3000:3000 production-frontend"
```

---

## Staging vs Production 환경 분리

### 데이터베이스 분리

| 환경 | DB 이름 | 용도 |
|------|---------|------|
| **Production** | `autonet` | 실서비스 데이터 |
| **Staging** | `autonet_staging` | 테스트용 데이터 (안전한 테스트) |

**DB 서버**: PostgreSQL on `192.168.0.201:5432`

### Staging 환경 설정

**Backend .env** (`/opt/autonet/staging/backend/.env`):
```env
DB_NAME=autonet_staging  # Production은 autonet
```

**docker-compose.staging.yml**:
- Frontend: `NEXT_PUBLIC_API_URL=https://staging.autonetsellcar.com` (build arg)
- Backend: `.env` 파일을 볼륨 마운트로 연결

### 소스 코드 동기화

**⚠️ 중요**: Staging 디렉토리는 Git 저장소가 아님! Production과 수동 동기화 필요

```bash
# Production → Staging 소스 동기화
ssh damon@192.168.0.202 "rsync -av --exclude='node_modules' --exclude='.next' /opt/autonet/production/frontend/ /opt/autonet/staging/frontend/"

# Staging Frontend 재빌드
ssh damon@192.168.0.202 "cd /opt/autonet/staging && docker compose -f docker-compose.staging.yml build --no-cache frontend-staging && docker compose -f docker-compose.staging.yml up -d frontend-staging"
```

### Staging DB 초기 데이터 복사

```bash
# Production → Staging 데이터 복사 (psql 사용)
PGPASSWORD='roskfl@1122' pg_dump -h 192.168.0.201 -U admin -d autonet --data-only -t users -t cars -t car_images -t hero_banners | \
PGPASSWORD='roskfl@1122' psql -h 192.168.0.201 -U admin -d autonet_staging
```

---

## 1. 프로젝트 구조

```
AutonetSellCar.com/
├── backend/                    # FastAPI 백엔드
│   ├── app/
│   │   ├── api/               # API 라우터
│   │   ├── models/            # SQLAlchemy 모델
│   │   ├── services/          # 비즈니스 로직
│   │   └── database.py        # DB 연결
│   ├── uploads/               # 업로드 파일 저장
│   │   └── performance_checks/ # 성능점검표 PDF
│   ├── autonet.db             # ★ 실제 사용하는 DB (이것만 사용!)
│   └── venv/                  # Python 가상환경
├── frontend/                  # Next.js 프론트엔드
│   └── src/
│       ├── app/               # 페이지
│       └── lib/api.ts         # API 함수
└── restart-dev.bat            # 개발 서버 재시작 스크립트
```

---

## 2. 중요: DB 파일 관리

### ★★★ 반드시 확인 ★★★

**실제 사용하는 DB 파일**: `backend/autonet.db` (이것만!)

과거에 테스트용으로 생성된 빈 DB 파일들이 있을 수 있습니다:
- `autonet.db` (루트) - 사용하지 않음
- `autonetsellcar.db` - 사용하지 않음
- `car_platform.db` - 사용하지 않음

**이런 파일들이 발견되면 삭제해야 합니다.**

```python
# DB 파일 확인 스크립트
from pathlib import Path
base = Path(r'D:\Workspace\claudeCode\AutonetSellCar.com')
for db in base.rglob('*.db'):
    if 'venv' not in str(db) and 'node_modules' not in str(db):
        print(f"{db}: {db.stat().st_size / 1024:.1f} KB")
```

---

## 3. 성능점검표 PDF 시스템

### 3.1 PDF 생성 흐름

1. 관리자가 Carmodoo에서 차량 검색
2. 차량 가져오기(import) 시 `check_num` (성능점검번호) 추출
3. `capture_performance_check_pdf()` 함수로 PDF 캡처 시도
4. 성공 시 `car_performance_checks.pdf_path`에 경로 저장
5. 프론트엔드에서 `pdf_path`가 있으면 PDF 보기 버튼 표시

### 3.2 PDF 버튼이 안 보이는 경우

**원인**: `pdf_path`가 NULL인 경우

**해결 방법**:
1. 관리자 > Hero Banners 페이지에서 "PDF 재시도" 버튼 클릭
2. 또는 API 직접 호출: `POST /api/carmodoo/admin/retry-all-failed-pdfs`

### 3.3 PDF 관련 파일들

- `backend/app/services/pdf_service.py` - PDF 캡처 로직 (3회 자동 재시도)
- `backend/app/api/carmodoo.py` - PDF 관련 API 엔드포인트
- `frontend/src/app/cars/[id]/page.tsx` - PDF 보기 버튼 (라인 605 근처)

```javascript
// PDF 버튼 표시 조건 (page.tsx)
{performanceCheck.data?.pdf_path && (
  // PDF 버튼 렌더링
)}
```

---

## 4. check_num (성능점검번호) 처리

### 4.1 check_num 추출 위치

Carmodoo HTML에서 `checkNum`은 **주석 처리된 부분**에 있음:
```html
<!-- ... checkNum=9830018360 ... -->
```

### 4.2 파싱 로직 (carmodoo.py)

```python
# 전체 row HTML에서 checkNum 추출 (주석 포함)
row_html = etree.tostring(row, encoding='unicode')
check_match = re.search(r'checkNum=(\d+)', row_html)
if check_match:
    check_num = check_match.group(1)
```

### 4.3 check_num 관련 모델/인터페이스

**백엔드** (`carmodoo.py`):
```python
class CarmodooSearchResultItem(BaseModel):
    # ... 기타 필드 ...
    check_num: Optional[str] = None  # 성능점검번호
```

**프론트엔드** (`api.ts`):
```typescript
export interface CarmodooSearchResult {
  // ... 기타 필드 ...
  check_num?: string;  // 성능점검번호
}
```

---

## 5. 서버 재시작 관련

### 5.1 uvicorn 캐시 문제

**증상**: 코드 수정 후에도 API 스키마에 변경사항이 반영되지 않음

**원인**:
- `--reload` 옵션이 있어도 일부 변경사항이 적용되지 않는 경우 있음
- `__pycache__` 캐시 문제

**해결 방법**:
```powershell
# 1. __pycache__ 삭제
Get-ChildItem -Path 'backend' -Recurse -Directory -Filter '__pycache__' | Remove-Item -Recurse -Force

# 2. 서버 완전 재시작
# 방법 A: restart-dev.bat 실행
# 방법 B: 수동으로 uvicorn 프로세스 종료 후 재시작
```

### 5.2 포트 확인

```cmd
netstat -ano | findstr :8000
netstat -ano | findstr :3000
```

---

## 6. 관리자 기능

### 6.1 Hero Banners 페이지 (/admin/hero-banners)

**차량 검색 필터**:
- 제조사, 모델, 등급
- 연식 (From ~ To)
- 연료, 배기량, 주행거리

**PDF 관리**:
- "PDF 재시도" 버튼 - PDF 없는 모든 차량에 대해 PDF 재생성

### 6.2 관리자 API 엔드포인트

| 엔드포인트 | 설명 |
|-----------|------|
| `GET /api/carmodoo/admin/pdf-failures` | PDF 생성 실패 목록 |
| `POST /api/carmodoo/admin/retry-all-failed-pdfs` | 전체 PDF 재시도 |
| `POST /api/carmodoo/regenerate-pdf/{car_id}` | 특정 차량 PDF 재생성 |

---

## 7. 자주 발생하는 문제와 해결

### 7.1 "PDF 버튼이 안 보여요"

**체크리스트**:
1. 로그인 상태 확인 (로그인 사용자만 PDF 접근 가능)
2. DB에서 해당 차량의 `pdf_path` 확인
   ```sql
   SELECT car_id, check_number, pdf_path FROM car_performance_checks WHERE car_id = ?;
   ```
3. `pdf_path`가 NULL이면 → PDF 재생성 필요
4. PDF 파일이 실제로 존재하는지 확인: `backend/uploads/performance_checks/`

### 7.2 "코드 수정했는데 적용이 안 돼요"

1. `__pycache__` 삭제
2. uvicorn 서버 완전 재시작
3. 브라우저 캐시 클리어 (Ctrl+Shift+R)

### 7.3 "검색 결과가 안 나와요"

1. 캐시 만료 확인: `carmodoo_search_cache` 테이블
2. 제조사/모델 코드 확인 (예: 기아=2, K5=38)
3. 연도 범위 확인

---

## 8. 개발 환경 시작

```bash
# 방법 1: 배치 파일 사용
restart-dev.bat

# 방법 2: 수동 시작
# 터미널 1 (백엔드)
cd backend
venv\Scripts\activate
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 터미널 2 (프론트엔드)
cd frontend
npm run dev
```

---

## 9. 유용한 디버깅 명령어

```python
# DB 상태 확인
import sqlite3
conn = sqlite3.connect('backend/autonet.db')
cursor = conn.cursor()

# 성능점검 데이터 확인
cursor.execute('SELECT car_id, check_number, pdf_path FROM car_performance_checks')
for row in cursor.fetchall():
    print(row)

# PDF 파일 존재 확인
from pathlib import Path
pdf_dir = Path('backend/uploads/performance_checks')
for pdf in pdf_dir.glob('*.pdf'):
    print(f"{pdf.name}: {pdf.stat().st_size / 1024:.1f} KB")
```

---

## 10. 환율 시스템

### 10.1 개요

한국수출입은행 API에서 실시간 환율을 가져와 모든 가격 표시에 적용합니다.

- **갱신 주기**: 매일 11:30 AM (한국수출입은행 고시 시간)
- **캐싱**: 30분간 캐시 유지
- **폴백**: API 실패 시 기본값 사용

### 10.2 환율 API 엔드포인트

| 엔드포인트 | 설명 |
|-----------|------|
| `GET /api/exchange-rate` | 전체 환율 정보 (상세) |
| `GET /api/exchange-rate/simple` | 간단한 환율 정보 (USD, EUR, JPY 등) |

**응답 예시** (`/api/exchange-rate/simple`):
```json
{
  "USD": {"rate": 1483.4, "symbol": "$", "name": "미국 달러"},
  "EUR": {"rate": 1749.74, "symbol": "€", "name": "유로"},
  "JPY": {"rate": 9.5001, "symbol": "¥", "name": "일본 옌"}
}
```

### 10.3 프론트엔드 환율 Store

**파일**: `frontend/src/lib/exchangeRateStore.ts`

```typescript
// 환율 가져오기
const store = useExchangeRateStore.getState();
const usdRate = store.rates.USD?.rate || 1483;  // 폴백 값

// KRW → USD 변환
const usdAmount = krwAmount / usdRate;

// USD → KRW 변환
const krwAmount = usdAmount * usdRate;
```

**기본값 (API 실패 시)**:
| 통화 | rate (1 단위당 KRW) |
|------|---------------------|
| USD | 1483 |
| EUR | 1750 |
| JPY | 9.5 |
| CNY | 203 |
| MNT | 0.43 |
| RUB | 14.5 |

### 10.4 환율 적용 파일들

| 파일 | 용도 |
|------|------|
| `frontend/src/lib/exchangeRateStore.ts` | Zustand 환율 스토어 |
| `frontend/src/lib/i18n.ts` | `formatPriceWithCurrency()` 함수 |
| `frontend/src/app/exchange-rate/page.tsx` | 환율 정보 페이지 |
| `frontend/src/app/cost/page.tsx` | 비용 계산기 |
| `frontend/src/components/SearchFilters.tsx` | 검색 필터 가격 표시 |
| `frontend/src/app/admin/purchased/page.tsx` | 구매 차량 관리 |

### 10.5 주의사항

**하드코딩된 환율 사용 금지!**

```typescript
// 잘못된 예
const usd = krwAmount * 0.00069;  // 하드코딩 X
const krw = usdAmount * 1333;     // 하드코딩 X

// 올바른 예
const usdRate = useExchangeRateStore.getState().rates.USD?.rate || 1483;
const usd = krwAmount / usdRate;
const krw = usdAmount * usdRate;
```

### 10.6 환율 디버깅

```bash
# API 테스트
curl http://localhost:8000/api/exchange-rate/simple

# DB 환율 데이터 확인
sqlite3 backend/autonet.db "SELECT * FROM exchange_rates ORDER BY updated_at DESC LIMIT 5;"
```

---

## 11. 다국어 번역 시스템

### 11.1 개요

차량 정보(차량명, 연료, 변속기, 색상 등)를 사용자 선택 언어로 번역합니다.

- **지원 언어**: 한국어(ko), 영어(en), 몽골어(mn), 러시아어(ru)
- **기본값**: 해당 언어 번역이 없으면 영어(en)로 대체

### 11.2 번역 관련 파일들

| 파일 | 역할 |
|------|------|
| `frontend/src/lib/i18n.ts` | 정적 번역 사전 (`CAR_TRANSLATIONS`), `translateCarName()` 함수 |
| `frontend/src/lib/useTranslate.ts` | `translate()` 훅 - API + 정적 번역 폴백 |

### 11.3 `CAR_TRANSLATIONS` 구조

```typescript
const CAR_TRANSLATIONS: Record<string, Record<string, string>> = {
  // 연료 타입
  '휘발유': { ko: '휘발유', en: 'Gasoline', mn: 'Бензин', ru: 'Бензин' },
  '경유': { ko: '경유', en: 'Diesel', mn: 'Дизель', ru: 'Дизель' },

  // 변속기
  '오토': { ko: '오토', en: 'Auto', mn: 'Авто', ru: 'Авто' },
  '수동': { ko: '수동', en: 'Manual', mn: 'Механик', ru: 'Механика' },

  // 제조사
  'KG모빌리티(쌍용)': { ko: 'KG모빌리티(쌍용)', en: 'KG Mobility (SsangYong)', ... },

  // 모델
  '렉스턴 스포츠': { ko: '렉스턴 스포츠', en: 'Rexton Sports', ... },

  // 색상
  '흰색': { ko: '흰색', en: 'White', mn: 'Цагаан', ru: 'Белый' },
};
```

### 11.4 번역 함수 사용법

**방법 1: `useTranslate` 훅** (권장)
```tsx
import { useTranslate } from '@/lib/useTranslate';

function Component() {
  const { translate } = useTranslate();
  return <span>{translate(car.fuel)}</span>;  // '휘발유' → 'Gasoline'
}
```

**방법 2: `translateCarName` 함수** (직접 호출)
```tsx
import { translateCarName } from '@/lib/i18n';

const translatedFuel = translateCarName(car.fuel, language);  // '경유' → 'Diesel'
```

### 11.5 새 번역 추가하기

`CAR_TRANSLATIONS`에 새 항목 추가:
```typescript
'새로운용어': { ko: '새로운용어', en: 'New Term', mn: 'Шинэ нэр', ru: 'Новый термин' },
```

**주의**: 긴 문자열을 먼저 매칭하기 위해 `SORTED_CAR_KEYS`가 자동으로 정렬됨

### 11.6 번역이 안 되는 경우

1. **`CAR_TRANSLATIONS`에 해당 용어가 없음** → 새 항목 추가
2. **프론트엔드 리빌드 필요** → `npm run dev` 재시작 또는 `.next` 폴더 삭제
3. **`translate()` 함수 미사용** → 페이지에서 직접 값 출력 중 (수정 필요)
4. **localStorage에 'ko' 언어 저장됨** → 일반 유저는 한국어 선택 불가지만 localStorage에 남아있으면 번역 스킵됨
   - `LanguageSelector.tsx`에서 자동으로 영어로 리셋하도록 수정됨

### 11.7 언어 선택 제한

- **관리자(is_admin=true)**: 한국어, 영어, 몽골어, 러시아어 모두 선택 가능
- **일반 유저**: 영어, 몽골어, 러시아어만 선택 가능 (한국어 숨김)
- 파일: `frontend/src/components/LanguageSelector.tsx`

---

## 12. CC (Car Credit) 시스템

### 12.1 CC란?
- 플랫폼 내 가상 화폐
- **차량 추천 서비스**에 사용 (1 CC = N대 추천, 관리자 설정 가능)
- 신규 가입 시 1 CC 지급
- **관리자 설정**: `/admin/settings`에서 `Cars per CC` 값으로 1 CC당 추천 대수 조절 가능 (기본값: 3대)

### 12.2 CC 충전 패키지

| 충전 금액 | 받는 CC | 추천 가능 차량 (기본 3대/CC) | 할인율 |
|-----------|---------|----------------|--------|
| $10 | 10 CC | 30대 | - |
| $27 | 30 CC | 90대 | 10% |
| $40 | 50 CC | 150대 | 20% |

> **참고**: 추천 가능 차량 수는 관리자 설정의 `Cars per CC` 값에 따라 변동됩니다.

### 12.3 결제 수단

| 수단 | 대상 | 처리 방식 |
|------|------|-----------|
| **Stripe** | 몽골 사용자 | Visa/Mastercard 자동 결제 |
| **몽골 파트너 계좌** | 러시아 사용자 | 수동 충전 요청 → 관리자 승인 |

### 12.4 Stripe 설정

**환경변수** (backend/.env):
```env
STRIPE_SECRET_KEY=sk_test_...      # Stripe 비밀키
STRIPE_PUBLISHABLE_KEY=pk_test_... # Stripe 공개키
STRIPE_WEBHOOK_SECRET=whsec_...    # Webhook 시크릿
STRIPE_SUCCESS_URL=https://yourdomain.com/cc/success
STRIPE_CANCEL_URL=https://yourdomain.com/cc
```

**API 엔드포인트**:
| 엔드포인트 | 설명 |
|-----------|------|
| `GET /api/cc/packages` | CC 패키지 목록 |
| `POST /api/cc/create-checkout-session` | Stripe 결제 세션 생성 |
| `POST /api/cc/webhook` | Stripe Webhook 수신 |
| `GET /api/cc/checkout-success` | 결제 완료 확인 |
| `POST /api/cc/manual-request` | 수동 충전 요청 (러시아용) |

**Stripe Webhook 설정**:
1. Stripe Dashboard → Webhooks
2. 엔드포인트 추가: `https://yourdomain.com/api/cc/webhook`
3. 이벤트 선택: `checkout.session.completed`, `checkout.session.expired`

### 12.5 CC vs 차량 열람

> **중요**: CC는 추천 서비스에만 사용됩니다!

| 기능 | 필요 조건 |
|------|-----------|
| 차량 정보 열람 (이미지, 딜러, 성능점검표) | 로그인만 하면 무료 |
| 배너 차량 열람 | 비로그인도 무료 |
| 차량 추천 서비스 | **CC 필요** (1 CC = N대, 설정에 따름) |

---

## 13. 상세사양조회 시스템 (AUTOBEGINS)

### 13.1 개요

Carmodoo 딜러 포탈의 AUTOBEGINS 서비스를 통해 차량번호 기반 상세사양을 조회합니다.

- **데이터 소스**: AUTOBEGINS (api.autobegins.com) via Carmodoo iframe
- **조회 방식**: Playwright 브라우저 자동화
- **저장 시점**: 배너 등록(import) 시 자동 저장

### 13.2 조회 가능 정보

| 카테고리 | 정보 |
|----------|------|
| 기본 정보 | 제조사, 모델명, 등급, 연식 |
| 엔진/구동 | 배기량, 연료, 변속기, 구동방식 |
| 성능 | 최대출력, 최대토크, 연비 |
| 차체 | 차체형식, 도어수, 승차정원, 전장/전폭/전고/휠베이스 |
| 옵션 | 안전옵션, 편의옵션, 외장옵션, 내장옵션 |
| 가격 | 출고가, 기본가, 옵션가 |

### 13.3 관련 파일

| 파일 | 역할 |
|------|------|
| `backend/app/services/spec_service.py` | Playwright 기반 사양 조회 |
| `backend/app/models/car_specification.py` | CarSpecification 모델 |
| `backend/app/api/carmodoo.py` | `/specifications/{car_number}`, `/car/{car_id}/specifications` API |

### 13.4 딜러 상세설명 (dealer_description)

- `cars.dealer_description` 컬럼에 저장
- Carmodoo 상세페이지에서 딜러가 작성한 설명 추출
- 차량 상세 페이지에서 amber 배경으로 표시 (로그인 사용자)

**추출 방식 (2024-12-25 개선)**:
1. 검색 결과에서 `car_key` 추출 (`dealerCarviewPopup('...')` 패턴)
2. `dealerCarView.html?key=<car_key>` URL로 상세 페이지 접근
3. `<div class="carViewMemoWrap"><h3>상세설명</h3><div class="memo">...</div></div>` 파싱

```python
# carmodoo.py - 딜러 설명 추출 (car_key 기반)
async def get_car_detail(self, car_no: str, car_key: str = "") -> dict:
    if car_key:
        url = f"{CARMODOO_BASE_URL}/car/dealerCarView.html"
        params = {"key": car_key, "tabStart": "1"}
        # EUC-KR 디코딩 후 상세설명 추출
        # <div class="carViewMemoWrap">...<div class="memo">설명</div></div>
```

**관련 필드**:
- `CarmodooSearchResultItem.car_key` - 검색 결과에 포함
- `AdminSearchResultItem.car_key` - 관리자 검색 결과에 포함
- `ImportCarRequest.car_key` - Import 요청에 포함

---

## 14. Quote Request 시스템 (차량 추천 요청)

### 14.1 개요

사용자가 원하는 차량 조건을 입력하면 관리자가 맞춤 차량을 추천해주는 서비스입니다.

- **비용**: 1 CC per request
- **응답 시간**: 24시간 이내 추천
- **페이지**: `/vehicle-request`

### 14.2 요청 조건

| 필드 | 필수 | 설명 |
|------|------|------|
| 제조사 | ★ | 기아, 현대 등 |
| 모델 | ★ | K5, 소나타 등 |
| 등급 | - | 선택 사항 |
| 연식 범위 | - | 2020 ~ 2024 |
| 주행거리 | - | 만km 단위 |
| 연료 | - | 휘발유, 경유, 하이브리드 등 |
| 배기량 | - | 1000cc ~ 5000cc |

### 14.3 CC 결제 흐름

1. 사용자가 조건 입력
2. 제출 시 CC 잔액 확인 (1 CC 필요)
3. 잔액 부족 시 `/cc` 페이지로 안내
4. CC 차감 후 요청 생성
5. `vehicle_requests.cc_paid` 컬럼에 기록

### 14.4 관련 파일

| 파일 | 역할 |
|------|------|
| `backend/app/api/vehicle_requests.py` | 요청 생성 API (CC 차감) |
| `backend/app/models/vehicle_request.py` | VehicleRequest 모델 (cc_paid 컬럼) |
| `frontend/src/app/vehicle-request/page.tsx` | 요청 폼 UI (CC 안내) |

---

## 15. 현지딜러 시스템

### 15.1 딜러 등급 및 수수료

몽골 마진(5%)에서 딜러 수수료 지급:

| 등급 | 조건 | 수수료율 |
|------|------|----------|
| 일반 (Standard) | 기본 | 3.0% |
| 실버 (Silver) | 10건+ 판매 | 3.5% |
| 골드 (Gold) | 30건+ 판매 | 4.0% |
| 플래티넘 (Platinum) | 100건+ 판매 | 4.5% |

### 15.2 레퍼럴 시스템

- 딜러가 고객에게 추천 코드 제공
- 고객이 차량 구매 시 딜러에게 수수료 지급
- **1단계 직접 추천만 인정** (다단계 아님)

---

## 16. 딜러 설명 번역 시스템

### 16.1 개요

딜러 설명(dealer_description)을 Azure Translator API를 사용하여 다국어로 번역합니다.

- **번역 API**: Microsoft Azure Translator (한국어 → 영어/몽골어/러시아어 직접 지원)
- **무료 한도**: 월 200만 글자
- **저장 시점**: Import 시 자동 번역, 관리자가 확인 후 배너/추천 전송

### 16.2 DB 필드

| 컬럼 | 설명 |
|------|------|
| `cars.dealer_description` | 한국어 원문 |
| `cars.dealer_description_en` | 영어 번역 |
| `cars.dealer_description_mn` | 몽골어 번역 |
| `cars.dealer_description_ru` | 러시아어 번역 |

### 16.3 환경 변수

```env
# Azure Translator API
AZURE_TRANSLATOR_KEY=your_api_key
AZURE_TRANSLATOR_REGION=koreacentral
```

### 16.4 관련 파일

| 파일 | 역할 |
|------|------|
| `backend/app/services/translation_service.py` | Azure Translator 연동 |
| `backend/app/api/carmodoo.py` | 번역 관리 API 엔드포인트 |
| `frontend/src/app/admin/dealer-translations/page.tsx` | 관리자 번역 확인/수정 UI |
| `frontend/src/app/cars/[id]/page.tsx` | 사용자 페이지 번역 표시 |

### 16.5 관리자 API 엔드포인트

| 엔드포인트 | 설명 |
|-----------|------|
| `GET /api/carmodoo/car/{car_id}/translations` | 차량 번역 조회 |
| `PUT /api/carmodoo/car/{car_id}/translations` | 차량 번역 수정 |
| `POST /api/carmodoo/car/{car_id}/translations/regenerate` | 번역 재생성 |
| `GET /api/carmodoo/admin/untranslated-cars` | 미번역 차량 목록 |
| `POST /api/carmodoo/admin/translate-all-pending` | 일괄 번역 |

### 16.6 번역 흐름

```
Import 시 자동 번역 (Azure API)
       ↓
관리자 확인 (/admin/dealer-translations)
       ↓
필요시 수정 또는 재번역
       ↓
배너 등록 / 추천 전송
       ↓
사용자 페이지에서 한국어 원문 + 선택언어 번역 표시
```

---

## 17. 변경 이력

| 날짜 | 변경 내용 |
|------|----------|
| 2025-01-03 | **Staging DB 분리**: `autonet_staging` DB 생성, Production/Staging 환경 완전 분리 |
| 2025-01-03 | **My Vehicles 기능**: 직접 구매 차량을 My Request 페이지에 표시 |
| 2024-12-31 | **Admin Settings 기능 추가**: Show Dealer Comment 토글, Korean Domestic + Export Customs 금액 설정 |
| 2024-12-31 | Cost 페이지에서 국내비용+수출통관비용 동적 적용 (settings API 연동) |
| 2024-12-31 | **Visitor Stats 국가별 통계 강화**: 국기 이모지 추가, 전용 Country Stats 카드 추가 |
| 2024-12-31 | Hero Banners API 라우트 순서 수정 (422 에러 해결) |
| 2024-12-31 | Banner Toggle 로직 수정 (HeroBanner 테이블 기준으로 변경) |
| 2024-12-27 | **딜러 설명 번역 시스템 추가**: Azure Translator API 연동, 한국어→영어/몽골어/러시아어 직접 번역 |
| 2024-12-27 | 관리자 번역 관리 페이지 추가 (`/admin/dealer-translations`) |
| 2024-12-27 | DB 스키마 확장: `dealer_description_en/mn/ru` 컬럼 추가 |
| 2024-12-25 | **딜러 상세설명 추출 방식 개선**: car_key 기반 dealerCarView.html 사용 (기존 carPopView.html 404 문제 해결) |
| 2024-12-25 | 검색 결과에 `car_key` 필드 추가 (CarmodooSearchResultItem, AdminSearchResultItem) |
| 2024-12-25 | Import 시 car_key 전달하여 딜러 설명 자동 추출 |
| 2024-12-25 | 상세사양조회 시스템 추가 (AUTOBEGINS, spec_service.py, CarSpecification 모델) |
| 2024-12-25 | 딜러 상세설명 필드 추가 (cars.dealer_description) |
| 2024-12-25 | Quote Request 1CC 결제 시스템 추가 (vehicle_requests.cc_paid) |
| 2024-12-25 | CC당 추천 대수 관리자 설정 추가 (cars_per_cc, 기본값 3대) |
| 2024-12-25 | 차량 검색 시 연료 조건 필터링 버그 수정 |
| 2024-12-24 | Stripe 결제 연동 (CC 충전 패키지, Checkout Session, Webhook) |
| 2024-12-24 | CC 시스템 변경 (추천 서비스 기반, 차량열람 무료화) |
| 2024-12-24 | 언어 자동 리셋 버그 수정 (localStorage 'ko' 문제) |
| 2024-12-24 | 다국어 번역 시스템 개선 (연료/변속기/색상/차량명) |
| 2024-12-24 | 환율 시스템 동적 적용 (하드코딩 제거, API 연동) |
| 2024-12-24 | PDF 재시도 로직 추가 (3회 자동 재시도) |
| 2024-12-24 | 빈 DB 파일 정리 |
| 2024-12-24 | 관리자 PDF 재시도 UI/API 추가 |
| 2024-12-24 | Hero Banners 검색에 주행거리 필터 추가 |

---

**이 문서는 새 세션 시작 시 반드시 읽어주세요!**