# 몽골 중고차 수출 플랫폼 개발 계획서

## 📋 프로젝트 개요

| 항목 | 내용 |
|------|------|
| **프로젝트명** | MongolCar - 몽골 중고차 수출 플랫폼 |
| **목적** | 한국 중고차를 몽골 고객에게 실시간 검색/판매하는 B2C 플랫폼 |
| **대상 고객** | 몽골, 러시아, 카자흐스탄 등 중앙아시아 고객 |
| **개발 기간** | 8~10주 |
| **개발 도구** | Claude Code |

---

## 🏗️ 시스템 아키텍처

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                              전체 시스템 구성도                               │
└─────────────────────────────────────────────────────────────────────────────┘

                    ┌─────────────────────────────────────┐
                    │     몽골/러시아 사용자 (웹브라우저)    │
                    │     - 차량 검색 (차종/연식/마일리지)   │
                    │     - 상세보기 (포인트 차감)          │
                    │     - 실시간 채팅 (AI 번역)          │
                    └──────────────────┬──────────────────┘
                                       │
                                       ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                        우분투 웹서버 (Ryzen 7700, 32GB)                       │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
│  │  Next.js    │  │  Node.js    │  │  Socket.io  │  │  Claude API        │ │
│  │  Frontend   │  │  API Server │  │  실시간채팅  │  │  번역+FAQ 챗봇      │ │
│  │  (다국어)   │  │             │  │             │  │                    │ │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────────────┘ │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────────────────┐  │
│  │   Nginx     │  │   Redis     │  │   이미지 저장소                      │  │
│  │   Reverse   │  │   Cache     │  │   /var/www/car-images/              │  │
│  │   Proxy     │  │   Session   │  │   1000대 × 20장 = ~10GB             │  │
│  └─────────────┘  └─────────────┘  └─────────────────────────────────────┘  │
└─────────────────────────────────────┬───────────────────────────────────────┘
                                      │
                    ┌─────────────────┴─────────────────┐
                    │           내부 네트워크            │
                    └─────────────────┬─────────────────┘
                                      │
        ┌─────────────────────────────┴─────────────────────────────┐
        │                                                           │
        ▼                                                           ▼
┌───────────────────────────────────┐     ┌───────────────────────────────────┐
│   우분투 DB서버 (Ryzen 7700, 32GB) │     │   Windows PC (사무실)              │
│  ┌─────────────────────────────┐  │     │  ┌─────────────────────────────┐  │
│  │     PostgreSQL 16           │  │     │  │    카모두 프로그램           │  │
│  │  - vehicles (차량정보)       │  │     │  │    (GGKucar.exe)            │  │
│  │  - users (회원)             │  │     │  └──────────────┬──────────────┘  │
│  │  - payments (결제)          │  │     │                 │                 │
│  │  - chat_messages (채팅)     │  │     │  ┌──────────────▼──────────────┐  │
│  │  - view_history (열람기록)   │  │     │  │   Python 자동화 에이전트     │  │
│  └─────────────────────────────┘  │     │  │  - pywinauto (UI 제어)      │  │
│  ┌─────────────────────────────┐  │     │  │  - API Client (서버 통신)   │  │
│  │     백업 스토리지 (10TB)     │  │     │  │  - 이미지 추출/업로드       │  │
│  └─────────────────────────────┘  │     │  └─────────────────────────────┘  │
└───────────────────────────────────┘     └───────────────────────────────────┘
```

---

## 🖥️ 서버 인프라

### 서버 1: 웹서버

| 항목 | 사양 |
|------|------|
| **CPU** | AMD Ryzen 7 7700 |
| **RAM** | 32GB (64GB 중 할당) |
| **스토리지** | SSD (OS + 앱) + HDD 10TB 일부 |
| **OS** | Ubuntu 22.04 LTS |

**설치 서비스:**
- Nginx (리버스 프록시, SSL)
- Node.js 20 LTS
- Next.js 14
- Redis 7
- PM2

### 서버 2: DB서버

| 항목 | 사양 |
|------|------|
| **CPU** | AMD Ryzen 7 7700 |
| **RAM** | 32GB (64GB 중 할당) |
| **스토리지** | SSD (DB) + HDD 10TB (백업) |
| **OS** | Ubuntu 22.04 LTS |

**설치 서비스:**
- PostgreSQL 16
- 자동 백업 스크립트

---

## 💻 기술 스택

### Frontend
| 기술 | 버전 | 용도 |
|------|------|------|
| Next.js | 14.x | React 프레임워크, SSR |
| TypeScript | 5.x | 타입 안전성 |
| Tailwind CSS | 3.x | 스타일링 |
| next-intl | latest | 다국어 (mn/en/ru/ko) |
| Socket.io-client | 4.x | 실시간 채팅 |
| React Query | 5.x | 서버 상태 관리 |
| Zustand | 4.x | 클라이언트 상태 관리 |

### Backend
| 기술 | 버전 | 용도 |
|------|------|------|
| Node.js | 20 LTS | 런타임 |
| Express.js | 4.x | API 서버 |
| TypeScript | 5.x | 타입 안전성 |
| Socket.io | 4.x | 실시간 통신 |
| Prisma | 5.x | ORM |
| Redis | 7.x | 캐시, 세션, 큐 |
| Bull | 4.x | 작업 큐 |

### Database
| 기술 | 버전 | 용도 |
|------|------|------|
| PostgreSQL | 16.x | 메인 데이터베이스 |

### External APIs
| 서비스 | 용도 |
|--------|------|
| Claude API (Anthropic) | 번역 + FAQ 챗봇 |
| NOWPayments | USDT/USDC 결제 |
| ExchangeRate API | 환율 조회 |

### Windows Agent
| 기술 | 버전 | 용도 |
|------|------|------|
| Python | 3.11+ | 에이전트 개발 |
| pywinauto | 0.6.8+ | UI 자동화 |
| aiohttp | 3.x | 비동기 HTTP |
| Pillow | 10.x | 이미지 처리 |

---

## 📁 프로젝트 구조

```
mongol-car-platform/
├── README.md
├── docker-compose.yml
├── .env.example
│
├── apps/
│   ├── web/                          # Next.js 프론트엔드
│   │   ├── package.json
│   │   ├── next.config.js
│   │   ├── tailwind.config.js
│   │   ├── tsconfig.json
│   │   │
│   │   ├── public/
│   │   │   ├── locales/              # 다국어 파일
│   │   │   │   ├── mn/               # 몽골어
│   │   │   │   ├── en/               # 영어
│   │   │   │   ├── ru/               # 러시아어
│   │   │   │   └── ko/               # 한국어
│   │   │   └── images/
│   │   │
│   │   ├── src/
│   │   │   ├── app/                  # App Router
│   │   │   │   ├── [locale]/
│   │   │   │   │   ├── layout.tsx
│   │   │   │   │   ├── page.tsx              # 메인 (검색)
│   │   │   │   │   ├── vehicles/
│   │   │   │   │   │   ├── page.tsx          # 검색 결과
│   │   │   │   │   │   └── [id]/
│   │   │   │   │   │       └── page.tsx      # 차량 상세
│   │   │   │   │   ├── auth/
│   │   │   │   │   │   ├── login/page.tsx
│   │   │   │   │   │   └── register/page.tsx
│   │   │   │   │   ├── mypage/
│   │   │   │   │   │   ├── page.tsx          # 마이페이지
│   │   │   │   │   │   ├── points/page.tsx   # 포인트 내역
│   │   │   │   │   │   ├── history/page.tsx  # 열람 기록
│   │   │   │   │   │   ├── orders/page.tsx   # 주문 내역
│   │   │   │   │   │   └── tracking/
│   │   │   │   │   │       ├── page.tsx      # 내차찾기 목록
│   │   │   │   │   │       └── [orderId]/
│   │   │   │   │   │           └── page.tsx  # 상세 추적
│   │   │   │   │   ├── payment/
│   │   │   │   │   │   ├── page.tsx          # 충전 페이지
│   │   │   │   │   │   ├── success/page.tsx
│   │   │   │   │   │   └── cancel/page.tsx
│   │   │   │   │   └── chat/
│   │   │   │   │       └── [roomId]/page.tsx # 채팅방
│   │   │   │   └── api/                      # API Routes (필요시)
│   │   │   │
│   │   │   ├── components/
│   │   │   │   ├── common/
│   │   │   │   │   ├── Header.tsx
│   │   │   │   │   ├── Footer.tsx
│   │   │   │   │   ├── LanguageSwitcher.tsx
│   │   │   │   │   └── Loading.tsx
│   │   │   │   ├── vehicles/
│   │   │   │   │   ├── SearchForm.tsx
│   │   │   │   │   ├── VehicleCard.tsx
│   │   │   │   │   ├── VehicleList.tsx
│   │   │   │   │   ├── VehicleDetail.tsx
│   │   │   │   │   └── ImageGallery.tsx
│   │   │   │   ├── chat/
│   │   │   │   │   ├── ChatWindow.tsx
│   │   │   │   │   ├── MessageList.tsx
│   │   │   │   │   └── MessageInput.tsx
│   │   │   │   ├── payment/
│   │   │   │   │   ├── PaymentModal.tsx
│   │   │   │   │   ├── CryptoSelector.tsx
│   │   │   │   │   └── QRCodeDisplay.tsx
│   │   │   │   ├── order/
│   │   │   │   │   ├── OrderSummary.tsx
│   │   │   │   │   ├── FeeBreakdown.tsx       # 수수료 상세 내역
│   │   │   │   │   └── OrderHistory.tsx
│   │   │   │   └── tracking/
│   │   │   │       ├── TrackingMap.tsx        # 지도 컴포넌트
│   │   │   │       ├── TrackingStatus.tsx     # 현재 상태 표시
│   │   │   │       ├── TrackingTimeline.tsx   # 배송 이력 타임라인
│   │   │   │       └── EstimatedArrival.tsx   # 예상 도착일
│   │   │   │
│   │   │   ├── hooks/
│   │   │   │   ├── useAuth.ts
│   │   │   │   ├── useVehicles.ts
│   │   │   │   ├── useChat.ts
│   │   │   │   ├── usePayment.ts
│   │   │   │   ├── useOrder.ts
│   │   │   │   └── useTracking.ts
│   │   │   │
│   │   │   ├── lib/
│   │   │   │   ├── api.ts                    # API 클라이언트
│   │   │   │   ├── socket.ts                 # Socket.io 클라이언트
│   │   │   │   └── utils.ts
│   │   │   │
│   │   │   ├── stores/
│   │   │   │   ├── authStore.ts
│   │   │   │   └── chatStore.ts
│   │   │   │
│   │   │   └── types/
│   │   │       ├── vehicle.ts
│   │   │       ├── user.ts
│   │   │       ├── payment.ts
│   │   │       ├── order.ts
│   │   │       ├── fee.ts
│   │   │       └── tracking.ts
│   │   │
│   │   └── messages/                         # next-intl 메시지
│   │       ├── mn.json
│   │       ├── en.json
│   │       ├── ru.json
│   │       └── ko.json
│   │
│   └── api/                          # Node.js 백엔드
│       ├── package.json
│       ├── tsconfig.json
│       │
│       └── src/
│           ├── index.ts                      # 엔트리포인트
│           ├── app.ts                        # Express 앱
│           │
│           ├── config/
│           │   ├── database.ts
│           │   ├── redis.ts
│           │   └── env.ts
│           │
│           ├── routes/
│           │   ├── index.ts
│           │   ├── auth.routes.ts
│           │   ├── vehicles.routes.ts
│           │   ├── payment.routes.ts
│           │   ├── chat.routes.ts
│           │   ├── order.routes.ts           # 주문 관련
│           │   ├── tracking.routes.ts        # 배송 추적
│           │   ├── fee.routes.ts             # 수수료 관련
│           │   ├── container.routes.ts       # 컨테이너 관리 (관리자)
│           │   └── agent.routes.ts           # Windows 에이전트용
│           │
│           ├── controllers/
│           │   ├── auth.controller.ts
│           │   ├── vehicles.controller.ts
│           │   ├── payment.controller.ts
│           │   ├── chat.controller.ts
│           │   ├── order.controller.ts
│           │   ├── tracking.controller.ts
│           │   ├── fee.controller.ts
│           │   ├── container.controller.ts
│           │   └── agent.controller.ts
│           │
│           ├── services/
│           │   ├── auth.service.ts
│           │   ├── vehicles.service.ts
│           │   ├── payment.service.ts
│           │   ├── translation.service.ts    # Claude API
│           │   ├── chat.service.ts
│           │   ├── order.service.ts
│           │   ├── tracking.service.ts
│           │   ├── fee.service.ts            # 수수료 계산 로직
│           │   ├── container.service.ts      # 컨테이너 적재 로직
│           │   └── nowpayments.service.ts
│           │
│           ├── middleware/
│           │   ├── auth.middleware.ts
│           │   ├── rateLimit.middleware.ts
│           │   └── error.middleware.ts
│           │
│           ├── socket/
│           │   ├── index.ts                  # Socket.io 설정
│           │   └── chat.handler.ts           # 채팅 이벤트 핸들러
│           │
│           ├── jobs/
│           │   └── searchQueue.ts            # Bull 큐
│           │
│           └── types/
│               └── index.ts
│
├── packages/
│   └── database/                     # Prisma 스키마 (공유)
│       ├── package.json
│       ├── prisma/
│       │   ├── schema.prisma
│       │   └── migrations/
│       └── src/
│           └── index.ts              # Prisma Client export
│
├── agent/                            # Windows 자동화 에이전트
│   ├── requirements.txt
│   ├── config.yaml
│   │
│   ├── src/
│   │   ├── main.py                   # 엔트리포인트
│   │   ├── carmodoo_agent.py         # 카모두 자동화
│   │   ├── api_client.py             # 서버 API 클라이언트
│   │   ├── image_handler.py          # 이미지 추출/업로드
│   │   └── utils.py
│   │
│   └── tests/
│       └── test_agent.py
│
├── database/                         # DB 스키마 및 시드
│   ├── schema.sql                    # PostgreSQL 스키마
│   ├── seed.sql                      # 초기 데이터
│   └── backup.sh                     # 백업 스크립트
│
├── deploy/                           # 배포 설정
│   ├── nginx/
│   │   └── default.conf
│   ├── systemd/
│   │   ├── api.service
│   │   └── web.service
│   └── scripts/
│       ├── setup-server.sh           # 서버 초기 설정
│       └── deploy.sh                 # 배포 스크립트
│
└── docs/                             # 문서
    ├── API.md                        # API 문서
    ├── DEPLOYMENT.md                 # 배포 가이드
    └── AGENT.md                      # 에이전트 설정 가이드
```

---

## 🗄️ 데이터베이스 스키마

### ERD 개요

```
┌─────────────┐     ┌─────────────┐     ┌─────────────────┐
│   users     │────<│view_history │>────│    vehicles     │
└─────────────┘     └─────────────┘     └─────────────────┘
       │                                        │
       │◀───────────[referred_by]               │
       │                                        │
       │            ┌─────────────┐             │
       └───────────<│  payments   │             │
       │            └─────────────┘             │
       │                   │                    │
       │            ┌─────────────┐             │
       │            │point_history│             │
       │            └─────────────┘             │
       │                                        │
       │            ┌─────────────┐             │
       └───────────<│ chat_rooms  │>────────────┘
       │            └─────────────┘
       │                   │
       │            ┌─────────────┐
       │            │chat_messages│
       │            └─────────────┘
       │
       │            ┌──────────────────┐
       └───────────<│dealer_commissions│ (현지딜러 수수료)
                    └──────────────────┘
```

### 주요 테이블

```sql
-- 1. 사용자 (users)
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    email VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    name VARCHAR(100),
    phone VARCHAR(20),
    country VARCHAR(50) DEFAULT 'MN',
    language VARCHAR(10) DEFAULT 'mn',

    -- 회원 유형
    user_type VARCHAR(20) DEFAULT 'customer',  -- 'customer', 'local_dealer', 'admin'

    -- 현지딜러 추천 시스템 (1단계 직접 추천)
    referred_by INTEGER REFERENCES users(id),  -- 추천인 (현지딜러)
    referral_code VARCHAR(20) UNIQUE,          -- 본인의 추천 코드 (딜러용)

    free_views_remaining INTEGER DEFAULT 3,
    point_balance DECIMAL(12,2) DEFAULT 0,
    status VARCHAR(20) DEFAULT 'active',
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

-- 1-1. 회원 유형 (user_types) - 참조 테이블
CREATE TABLE user_types (
    code VARCHAR(20) PRIMARY KEY,
    name_ko VARCHAR(50) NOT NULL,
    name_en VARCHAR(50) NOT NULL,
    name_mn VARCHAR(50),
    description TEXT,
    can_refer_customers BOOLEAN DEFAULT false,  -- 고객 추천 가능 여부
    commission_rate DECIMAL(4,2) DEFAULT 0,     -- 기본 수수료율 (%)
    created_at TIMESTAMP DEFAULT NOW()
);

INSERT INTO user_types (code, name_ko, name_en, name_mn, description, can_refer_customers, commission_rate) VALUES
('customer', '일반고객', 'Customer', 'Хэрэглэгч', '일반 구매 고객', false, 0),
('local_dealer', '현지딜러', 'Local Dealer', 'Орон нутгийн дилер', '몽골 현지 딜러 (고객 추천 가능)', true, 3.5),
('admin', '관리자', 'Administrator', 'Админ', '시스템 관리자', false, 0);

-- 1-2. 현지딜러 정보 (dealer_profiles)
CREATE TABLE dealer_profiles (
    id SERIAL PRIMARY KEY,
    user_id INTEGER UNIQUE REFERENCES users(id) ON DELETE CASCADE,

    -- 사업자 정보
    business_name VARCHAR(200),           -- 상호명
    business_registration_no VARCHAR(50), -- 사업자등록번호
    business_address TEXT,                -- 사업장 주소
    business_phone VARCHAR(30),           -- 사업장 전화번호

    -- 딜러 등급 및 수수료
    dealer_grade VARCHAR(20) DEFAULT 'standard',  -- 'standard', 'silver', 'gold', 'platinum'
    commission_rate DECIMAL(4,2) DEFAULT 3.5,     -- 개별 수수료율 (기본 3.5%)

    -- 은행 정보 (수수료 지급용)
    bank_name VARCHAR(100),
    bank_account_number VARCHAR(50),
    bank_account_holder VARCHAR(100),

    -- 활동 통계
    total_referrals INTEGER DEFAULT 0,       -- 총 추천 고객 수
    total_sales_count INTEGER DEFAULT 0,     -- 총 판매 건수
    total_commission_earned DECIMAL(14,2) DEFAULT 0,  -- 총 수령 수수료

    -- 상태
    verification_status VARCHAR(20) DEFAULT 'pending',  -- 'pending', 'verified', 'rejected'
    verified_at TIMESTAMP,
    notes TEXT,

    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

-- 1-3. 딜러 등급 (dealer_grades)
CREATE TABLE dealer_grades (
    code VARCHAR(20) PRIMARY KEY,
    name_ko VARCHAR(50) NOT NULL,
    name_en VARCHAR(50) NOT NULL,
    name_mn VARCHAR(50),
    min_sales_count INTEGER DEFAULT 0,    -- 승급 조건: 최소 판매 건수
    commission_rate DECIMAL(4,2) NOT NULL, -- 등급별 수수료율
    benefits TEXT,                         -- 혜택 설명
    sort_order INTEGER DEFAULT 0,
    created_at TIMESTAMP DEFAULT NOW()
);

INSERT INTO dealer_grades (code, name_ko, name_en, name_mn, min_sales_count, commission_rate, benefits, sort_order) VALUES
('standard', '일반', 'Standard', 'Стандарт', 0, 3.0, '기본 수수료율 적용', 1),
('silver', '실버', 'Silver', 'Мөнгө', 10, 3.5, '수수료율 0.5% 상향', 2),
('gold', '골드', 'Gold', 'Алт', 30, 4.0, '수수료율 1.0% 상향, 우선 배정', 3),
('platinum', '플래티넘', 'Platinum', 'Платин', 100, 4.5, '수수료율 1.5% 상향, 전담 매니저', 4);

-- 2. 차량 (vehicles)
CREATE TABLE vehicles (
    id SERIAL PRIMARY KEY,
    source_id VARCHAR(100) UNIQUE,
    make VARCHAR(50) NOT NULL,
    model VARCHAR(100) NOT NULL,
    year INTEGER NOT NULL,
    mileage INTEGER,
    price DECIMAL(14,2),
    fuel_type VARCHAR(20),
    transmission VARCHAR(20),
    color VARCHAR(30),
    engine_cc INTEGER,
    options JSONB DEFAULT '{}',
    inspection_data JSONB DEFAULT '{}',
    accident_history JSONB DEFAULT '[]',
    status VARCHAR(20) DEFAULT 'active',
    view_count INTEGER DEFAULT 0,
    created_at TIMESTAMP DEFAULT NOW()
);

-- 3. 차량 이미지 (vehicle_images)
CREATE TABLE vehicle_images (
    id SERIAL PRIMARY KEY,
    vehicle_id INTEGER REFERENCES vehicles(id) ON DELETE CASCADE,
    image_url VARCHAR(500) NOT NULL,
    thumbnail_url VARCHAR(500),
    image_type VARCHAR(30),
    sort_order INTEGER DEFAULT 0,
    created_at TIMESTAMP DEFAULT NOW()
);

-- 4. 열람 기록 (view_history)
CREATE TABLE view_history (
    id SERIAL PRIMARY KEY,
    user_id INTEGER REFERENCES users(id),
    vehicle_id INTEGER REFERENCES vehicles(id),
    is_free BOOLEAN DEFAULT false,
    points_used DECIMAL(10,2) DEFAULT 0,
    viewed_at TIMESTAMP DEFAULT NOW(),
    UNIQUE(user_id, vehicle_id)
);

-- 5. 결제 (payments)
CREATE TABLE payments (
    id SERIAL PRIMARY KEY,
    user_id INTEGER REFERENCES users(id),
    payment_id VARCHAR(100) UNIQUE,
    payment_type VARCHAR(20),
    amount_krw DECIMAL(12,2),
    amount_crypto DECIMAL(20,8),
    crypto_type VARCHAR(20),
    pay_address VARCHAR(200),
    tx_hash VARCHAR(100),
    points_added DECIMAL(12,2),
    status VARCHAR(20) DEFAULT 'pending',
    created_at TIMESTAMP DEFAULT NOW(),
    confirmed_at TIMESTAMP
);

-- 6. 포인트 이력 (point_history)
CREATE TABLE point_history (
    id SERIAL PRIMARY KEY,
    user_id INTEGER REFERENCES users(id),
    amount DECIMAL(12,2) NOT NULL,
    type VARCHAR(20),
    description VARCHAR(200),
    balance_after DECIMAL(12,2),
    created_at TIMESTAMP DEFAULT NOW()
);

-- 7. 채팅방 (chat_rooms)
CREATE TABLE chat_rooms (
    id SERIAL PRIMARY KEY,
    vehicle_id INTEGER REFERENCES vehicles(id),
    customer_id INTEGER REFERENCES users(id),
    dealer_id VARCHAR(50),
    status VARCHAR(20) DEFAULT 'active',
    last_message_at TIMESTAMP,
    created_at TIMESTAMP DEFAULT NOW()
);

-- 8. 채팅 메시지 (chat_messages)
CREATE TABLE chat_messages (
    id BIGSERIAL PRIMARY KEY,
    room_id INTEGER REFERENCES chat_rooms(id),
    sender_id VARCHAR(50) NOT NULL,
    sender_type VARCHAR(20),
    original_text TEXT NOT NULL,
    original_language VARCHAR(10),
    translations JSONB DEFAULT '{}',
    is_faq_response BOOLEAN DEFAULT false,
    created_at TIMESTAMP DEFAULT NOW()
);

-- 9. 검색 요청 큐 (search_requests)
CREATE TABLE search_requests (
    id SERIAL PRIMARY KEY,
    user_id INTEGER REFERENCES users(id),
    criteria JSONB NOT NULL,
    status VARCHAR(20) DEFAULT 'pending',
    result_count INTEGER,
    created_at TIMESTAMP DEFAULT NOW(),
    processed_at TIMESTAMP
);

-- 10. 차량 크기 분류 (vehicle_size_types)
CREATE TABLE vehicle_size_types (
    id SERIAL PRIMARY KEY,
    code VARCHAR(20) UNIQUE NOT NULL,  -- 'compact', 'midsize'
    name_ko VARCHAR(50) NOT NULL,
    name_en VARCHAR(50) NOT NULL,
    name_mn VARCHAR(50),
    max_per_container INTEGER NOT NULL,  -- 컨테이너당 최대 적재 수량
    created_at TIMESTAMP DEFAULT NOW()
);

-- 초기 데이터
INSERT INTO vehicle_size_types (code, name_ko, name_en, name_mn, max_per_container) VALUES
('compact', '소형차', 'Compact Car', 'Жижиг машин', 4),
('midsize', '중형차', 'Midsize Car', 'Дунд машин', 2);

-- 11. 수수료 항목 마스터 (fee_types)
CREATE TABLE fee_types (
    id SERIAL PRIMARY KEY,
    code VARCHAR(50) UNIQUE NOT NULL,
    category VARCHAR(30) NOT NULL,  -- 'vehicle', 'container', 'terminal'
    name_ko VARCHAR(100) NOT NULL,
    name_en VARCHAR(100) NOT NULL,
    name_mn VARCHAR(100),
    calculation_type VARCHAR(20) NOT NULL,  -- 'fixed', 'percentage', 'per_day', 'per_container', 'per_car'
    default_amount DECIMAL(14,2),
    percentage_rate DECIMAL(5,2),  -- 퍼센트 계산 시 사용
    is_shared BOOLEAN DEFAULT false,  -- 컨테이너 비용 분담 여부
    sort_order INTEGER DEFAULT 0,
    is_active BOOLEAN DEFAULT true,
    created_at TIMESTAMP DEFAULT NOW()
);

-- 수수료 항목 초기 데이터
-- 차량별 비용 (vehicle)
INSERT INTO fee_types (code, category, name_ko, name_en, calculation_type, default_amount, percentage_rate, is_shared, sort_order) VALUES
('performance_inspection', 'vehicle', '성능점검보험료', 'Performance inspection fee', 'fixed', 100000, NULL, false, 1),
('sales_fee', 'vehicle', '매도세', 'Sales fee', 'fixed', 440000, NULL, false, 2),
('brokerage_commission', 'vehicle', '매매알선수수료', 'Brokerage commission', 'fixed', 250000, NULL, false, 3),
('registration_tax', 'vehicle', '취등록세', 'Registration tax', 'fixed', 50000, NULL, false, 4),
('expiration_cost', 'vehicle', '말소', 'Expiration cost', 'fixed', 50000, NULL, false, 5),
('domestic_transport', 'vehicle', '국내 운송료', 'Domestic transportation charges', 'fixed', 160000, NULL, false, 6),
('yard_fee', 'vehicle', '야드비', 'Yard fee', 'per_day', 20000, NULL, false, 7),
('export_license', 'vehicle', '수출면장발급', 'Issuance of export exemption', 'fixed', 45000, NULL, false, 8),
('korean_margin', 'vehicle', '한국 마진', 'Korean Margin', 'percentage', NULL, 5.00, false, 9),
('mongolian_margin', 'vehicle', '몽골 마진', 'Mongolian Margin', 'percentage', NULL, 5.00, false, 10),

-- 컨테이너 비용 (분담, container)
('shipping_cost', 'container', '운송비(기차 4주)', 'Shipping Cost (Train 4weeks)', 'per_container', 5220000, NULL, true, 11),
('shoring', 'container', '쇼링(컨테이너작업)', 'Shoring', 'per_container', 600000, NULL, true, 12),

-- 터미널 비용 (분담, terminal)
('thc', 'terminal', '터미널 조작비용', 'THC(Terminal Handling Charge)', 'per_container', 190000, NULL, true, 13),
('wharfage', 'terminal', '부두하역료', 'Wharfage', 'per_container', 8400, NULL, true, 14),
('seal_fee', 'terminal', '컨테이너 실 비용', 'Seal Fee', 'per_container', 10000, NULL, true, 15),
('document_fee', 'terminal', '서류수수료', 'Document fee', 'per_container', 50000, NULL, true, 16);

-- 12. 주문 (orders)
CREATE TABLE orders (
    id SERIAL PRIMARY KEY,
    order_number VARCHAR(50) UNIQUE NOT NULL,  -- ORD-20241127-0001
    user_id INTEGER REFERENCES users(id),
    vehicle_id INTEGER REFERENCES vehicles(id),
    vehicle_size_type_id INTEGER REFERENCES vehicle_size_types(id),
    vehicle_price DECIMAL(14,2) NOT NULL,  -- 차량가액
    total_fees DECIMAL(14,2) NOT NULL,  -- 총 수수료
    total_amount DECIMAL(14,2) NOT NULL,  -- 총 결제금액
    status VARCHAR(30) DEFAULT 'pending',  -- pending, paid, processing, shipping, customs, delivered, cancelled
    payment_status VARCHAR(20) DEFAULT 'unpaid',  -- unpaid, partial, paid
    notes TEXT,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

-- 13. 주문 수수료 상세 (order_fees)
CREATE TABLE order_fees (
    id SERIAL PRIMARY KEY,
    order_id INTEGER REFERENCES orders(id) ON DELETE CASCADE,
    fee_type_id INTEGER REFERENCES fee_types(id),
    fee_code VARCHAR(50) NOT NULL,
    fee_name_ko VARCHAR(100) NOT NULL,
    fee_name_en VARCHAR(100) NOT NULL,
    calculation_type VARCHAR(20) NOT NULL,
    base_amount DECIMAL(14,2),  -- 기준 금액
    quantity INTEGER DEFAULT 1,  -- 일수 등
    calculated_amount DECIMAL(14,2) NOT NULL,  -- 최종 계산된 금액
    is_shared BOOLEAN DEFAULT false,
    share_count INTEGER DEFAULT 1,  -- 분담 차량 수
    notes VARCHAR(200),
    created_at TIMESTAMP DEFAULT NOW()
);

-- 14. 컨테이너 (containers)
CREATE TABLE containers (
    id SERIAL PRIMARY KEY,
    container_number VARCHAR(50) UNIQUE,  -- CNTR-20241127-001
    container_type VARCHAR(20) DEFAULT '40ft',  -- 20ft, 40ft
    max_compact_cars INTEGER DEFAULT 4,  -- 소형차 최대 적재량
    max_midsize_cars INTEGER DEFAULT 2,  -- 중형차 최대 적재량 (중형 4대 불가 규칙)
    current_compact_count INTEGER DEFAULT 0,
    current_midsize_count INTEGER DEFAULT 0,
    status VARCHAR(20) DEFAULT 'loading',  -- loading, sealed, in_transit, arrived, cleared

    -- 출발/도착 정보
    departure_port VARCHAR(100),  -- 부산항
    arrival_port VARCHAR(100),  -- 울란바타르

    -- 일정
    estimated_departure_date DATE,
    actual_departure_date DATE,
    estimated_arrival_date DATE,
    actual_arrival_date DATE,

    -- 비용 정보 (컨테이너 비용은 적재된 차량들이 분담)
    shipping_cost DECIMAL(14,2),
    shoring_cost DECIMAL(14,2),
    terminal_cost DECIMAL(14,2),
    total_shared_cost DECIMAL(14,2),

    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

-- 15. 컨테이너-차량 매핑 (container_vehicles)
CREATE TABLE container_vehicles (
    id SERIAL PRIMARY KEY,
    container_id INTEGER REFERENCES containers(id) ON DELETE CASCADE,
    order_id INTEGER REFERENCES orders(id),
    vehicle_id INTEGER REFERENCES vehicles(id),
    vehicle_size_type VARCHAR(20) NOT NULL,  -- 'compact', 'midsize'
    shared_cost_amount DECIMAL(14,2),  -- 분담된 비용
    loaded_at TIMESTAMP DEFAULT NOW()
);

-- 16. 배송 추적 (shipment_tracking)
CREATE TABLE shipment_tracking (
    id SERIAL PRIMARY KEY,
    order_id INTEGER REFERENCES orders(id),
    container_id INTEGER REFERENCES containers(id),

    -- 위치 정보
    current_location VARCHAR(200),
    latitude DECIMAL(10, 7),
    longitude DECIMAL(10, 7),
    location_type VARCHAR(30),  -- 'port', 'railway', 'customs', 'warehouse', 'delivered'

    -- 상태
    status VARCHAR(30) NOT NULL,  -- preparing, departed_korea, in_transit, arrived_mongolia, customs_clearance, delivered
    status_detail VARCHAR(200),

    -- 예상 일정
    estimated_arrival_date DATE,
    estimated_arrival_days INTEGER,  -- 남은 예상 일수

    -- 통관 정보
    customs_status VARCHAR(30),  -- pending, in_progress, cleared
    customs_document_number VARCHAR(100),

    updated_at TIMESTAMP DEFAULT NOW(),
    created_at TIMESTAMP DEFAULT NOW()
);

-- 17. 배송 이력 (shipment_history)
CREATE TABLE shipment_history (
    id SERIAL PRIMARY KEY,
    order_id INTEGER REFERENCES orders(id),
    container_id INTEGER REFERENCES containers(id),
    status VARCHAR(30) NOT NULL,
    location VARCHAR(200),
    latitude DECIMAL(10, 7),
    longitude DECIMAL(10, 7),
    description_ko VARCHAR(300),
    description_en VARCHAR(300),
    description_mn VARCHAR(300),
    event_time TIMESTAMP DEFAULT NOW(),
    created_at TIMESTAMP DEFAULT NOW()
);

-- 배송 상태 코드 참조 테이블 (shipment_status_codes)
CREATE TABLE shipment_status_codes (
    code VARCHAR(30) PRIMARY KEY,
    name_ko VARCHAR(100) NOT NULL,
    name_en VARCHAR(100) NOT NULL,
    name_mn VARCHAR(100),
    sort_order INTEGER,
    icon VARCHAR(50)  -- 프론트엔드 아이콘 매핑용
);

INSERT INTO shipment_status_codes (code, name_ko, name_en, name_mn, sort_order, icon) VALUES
('preparing', '출고 준비 중', 'Preparing for shipment', 'Тээвэрлэлтэнд бэлтгэж байна', 1, 'package'),
('loaded', '컨테이너 적재 완료', 'Loaded into container', 'Чингэлэг ачигдсан', 2, 'truck'),
('departed_korea', '한국 출발', 'Departed from Korea', 'Солонгосоос гарсан', 3, 'ship'),
('in_transit_rail', '기차 운송 중', 'In transit (Rail)', 'Тээвэрлэж байна (Төмөр зам)', 4, 'train'),
('arrived_mongolia', '몽골 도착', 'Arrived in Mongolia', 'Монголд ирсэн', 5, 'flag'),
('customs_clearance', '통관 진행 중', 'Customs clearance in progress', 'Гаалийн бүрдүүлэлт хийгдэж байна', 6, 'clipboard'),
('customs_cleared', '통관 완료', 'Customs cleared', 'Гаалийн бүрдүүлэлт дууссан', 7, 'check'),
('ready_for_pickup', '인수 대기', 'Ready for pickup', 'Авахад бэлэн', 8, 'warehouse'),
('delivered', '인도 완료', 'Delivered', 'Хүргэгдсэн', 9, 'check-circle');

-- =====================================================
-- 현지딜러 수수료 시스템 (1단계 직접 추천 구조)
-- =====================================================

-- 18. 딜러 수수료 내역 (dealer_commissions)
CREATE TABLE dealer_commissions (
    id SERIAL PRIMARY KEY,
    dealer_id INTEGER REFERENCES users(id),       -- 현지딜러 (수수료 수령자)
    order_id INTEGER REFERENCES orders(id),       -- 연결된 주문
    customer_id INTEGER REFERENCES users(id),     -- 추천받은 고객

    -- 수수료 계산
    vehicle_price DECIMAL(14,2) NOT NULL,         -- 차량가액
    mongolian_margin_rate DECIMAL(4,2) NOT NULL,  -- 몽골 마진율 (전체 5%)
    dealer_commission_rate DECIMAL(4,2) NOT NULL, -- 딜러 수수료율 (3~4.5%)
    platform_rate DECIMAL(4,2) NOT NULL,          -- 플랫폼 수수료율 (0.5~2%)

    dealer_commission_amount DECIMAL(14,2) NOT NULL,  -- 딜러 수수료 금액
    platform_amount DECIMAL(14,2) NOT NULL,           -- 플랫폼 수수료 금액

    -- 지급 정보
    status VARCHAR(20) DEFAULT 'pending',   -- 'pending', 'approved', 'paid', 'cancelled'
    payment_method VARCHAR(30),             -- 'bank_transfer', 'crypto'
    payment_reference VARCHAR(100),         -- 송금 참조번호
    paid_at TIMESTAMP,

    notes TEXT,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

-- 19. 딜러 수수료 정산 (dealer_payouts)
CREATE TABLE dealer_payouts (
    id SERIAL PRIMARY KEY,
    dealer_id INTEGER REFERENCES users(id),
    payout_number VARCHAR(50) UNIQUE,       -- PAY-20241127-001

    -- 정산 기간
    period_start DATE NOT NULL,
    period_end DATE NOT NULL,

    -- 정산 금액
    total_orders INTEGER DEFAULT 0,         -- 해당 기간 주문 건수
    total_commission DECIMAL(14,2) NOT NULL, -- 총 수수료
    deductions DECIMAL(14,2) DEFAULT 0,      -- 공제액 (있을 경우)
    net_amount DECIMAL(14,2) NOT NULL,       -- 실 지급액

    -- 지급 정보
    payment_method VARCHAR(30) NOT NULL,    -- 'bank_transfer', 'crypto'
    bank_name VARCHAR(100),
    bank_account_number VARCHAR(50),
    payment_reference VARCHAR(100),

    status VARCHAR(20) DEFAULT 'pending',   -- 'pending', 'processing', 'completed', 'failed'
    processed_at TIMESTAMP,
    completed_at TIMESTAMP,

    notes TEXT,
    created_at TIMESTAMP DEFAULT NOW()
);

-- 20. 추천 코드 사용 이력 (referral_history)
CREATE TABLE referral_history (
    id SERIAL PRIMARY KEY,
    referral_code VARCHAR(20) NOT NULL,
    dealer_id INTEGER REFERENCES users(id),       -- 코드 소유자 (딜러)
    customer_id INTEGER REFERENCES users(id),     -- 코드 사용자 (고객)
    used_at TIMESTAMP DEFAULT NOW(),
    ip_address VARCHAR(50),
    user_agent TEXT
);
```

---

## 🔌 API 명세

### 인증 API

| Method | Endpoint | 설명 |
|--------|----------|------|
| POST | `/api/auth/register` | 회원가입 |
| POST | `/api/auth/login` | 로그인 |
| POST | `/api/auth/logout` | 로그아웃 |
| GET | `/api/auth/me` | 현재 사용자 정보 |
| PUT | `/api/auth/profile` | 프로필 수정 |

### 차량 API

| Method | Endpoint | 설명 |
|--------|----------|------|
| POST | `/api/vehicles/search` | 차량 검색 요청 |
| GET | `/api/vehicles/search/:requestId` | 검색 결과 조회 |
| GET | `/api/vehicles/:id` | 차량 상세 (포인트 차감) |
| GET | `/api/vehicles/:id/preview` | 차량 미리보기 (무료) |

### 결제 API

| Method | Endpoint | 설명 |
|--------|----------|------|
| POST | `/api/payment/card` | 카드 결제 생성 |
| POST | `/api/payment/direct` | 직접 전송 주소 생성 |
| POST | `/api/payment/webhook` | NOWPayments 웹훅 |
| GET | `/api/payment/history` | 결제 내역 |

### 채팅 API

| Method | Endpoint | 설명 |
|--------|----------|------|
| POST | `/api/chat/rooms` | 채팅방 생성 |
| GET | `/api/chat/rooms` | 채팅방 목록 |
| GET | `/api/chat/rooms/:id/messages` | 메시지 조회 |

### 주문/배송 API

| Method | Endpoint | 설명 |
|--------|----------|------|
| POST | `/api/orders` | 주문 생성 |
| GET | `/api/orders` | 내 주문 목록 |
| GET | `/api/orders/:id` | 주문 상세 (수수료 내역 포함) |
| GET | `/api/orders/:id/fees` | 주문 수수료 상세 조회 |
| GET | `/api/tracking/:orderId` | 내차 위치 추적 |
| GET | `/api/tracking/:orderId/history` | 배송 이력 조회 |

### 수수료 API

| Method | Endpoint | 설명 |
|--------|----------|------|
| GET | `/api/fees` | 수수료 항목 목록 |
| POST | `/api/fees/calculate` | 수수료 계산 (견적) |

### 컨테이너 API (관리자용)

| Method | Endpoint | 설명 |
|--------|----------|------|
| POST | `/api/admin/containers` | 컨테이너 생성 |
| POST | `/api/admin/containers/:id/vehicles` | 차량 적재 |
| PUT | `/api/admin/containers/:id/status` | 컨테이너 상태 업데이트 |
| PUT | `/api/admin/tracking/:orderId` | 배송 추적 정보 업데이트 |

### 현지딜러 API

| Method | Endpoint | 설명 |
|--------|----------|------|
| POST | `/api/dealer/register` | 딜러 등록 신청 |
| GET | `/api/dealer/profile` | 딜러 프로필 조회 |
| PUT | `/api/dealer/profile` | 딜러 프로필 수정 |
| GET | `/api/dealer/referrals` | 추천 고객 목록 |
| GET | `/api/dealer/commissions` | 수수료 내역 조회 |
| GET | `/api/dealer/commissions/summary` | 수수료 요약 (대시보드) |
| GET | `/api/dealer/payouts` | 정산 내역 조회 |
| POST | `/api/referral/apply` | 추천 코드 적용 (고객용) |
| GET | `/api/referral/validate/:code` | 추천 코드 유효성 검증 |

### 딜러 관리 API (관리자용)

| Method | Endpoint | 설명 |
|--------|----------|------|
| GET | `/api/admin/dealers` | 딜러 목록 조회 |
| PUT | `/api/admin/dealers/:id/verify` | 딜러 승인/거부 |
| PUT | `/api/admin/dealers/:id/grade` | 딜러 등급 변경 |
| POST | `/api/admin/payouts` | 정산 처리 |
| GET | `/api/admin/commissions/report` | 수수료 리포트 |

### 에이전트 API (내부용)

| Method | Endpoint | 설명 |
|--------|----------|------|
| GET | `/api/agent/pending-searches` | 대기 중인 검색 요청 |
| POST | `/api/agent/search-results` | 검색 결과 전송 |
| POST | `/api/agent/vehicle-detail` | 차량 상세 정보 전송 |
| POST | `/api/agent/upload-images` | 이미지 업로드 |

---

## 👥 현지딜러 시스템 (1단계 직접 추천 구조)

### 시스템 개요

```
┌─────────────────────────────────────────────────────────────────────────┐
│                    1단계 직접 추천 구조                                   │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│     ┌─────────────────────────────────────────────────────────────┐    │
│     │                  플랫폼 운영사                                │    │
│     │              (한국 마진 5% 수령)                             │    │
│     └─────────────────────────────────────────────────────────────┘    │
│                              │                                          │
│                              ▼                                          │
│     ┌─────────────────────────────────────────────────────────────┐    │
│     │                   몽골 마진 5%                               │    │
│     │                       │                                      │    │
│     │     ┌─────────────────┴─────────────────┐                   │    │
│     │     ▼                                   ▼                   │    │
│     │  ┌──────────────┐               ┌──────────────┐           │    │
│     │  │ 현지딜러 몫  │               │ 플랫폼 몫    │           │    │
│     │  │   3~4.5%    │               │   0.5~2%    │           │    │
│     │  └──────────────┘               └──────────────┘           │    │
│     └─────────────────────────────────────────────────────────────┘    │
│                              │                                          │
│                              ▼                                          │
│     ┌─────────────────────────────────────────────────────────────┐    │
│     │                    현지딜러                                   │    │
│     │  • 고객에게 추천 코드 제공                                    │    │
│     │  • 고객이 차량 구매 시 수수료 수령                            │    │
│     │  • 등급에 따라 수수료율 차등                                  │    │
│     └──────────────────────┬──────────────────────────────────────┘    │
│                            │                                            │
│            ┌───────────────┼───────────────┐                           │
│            ▼               ▼               ▼                           │
│     ┌──────────┐    ┌──────────┐    ┌──────────┐                      │
│     │  고객 A  │    │  고객 B  │    │  고객 C  │                      │
│     └──────────┘    └──────────┘    └──────────┘                      │
│                                                                         │
│  ✅ 핵심 규칙:                                                          │
│  • 딜러가 직접 추천한 고객만 수수료 지급 (1단계만)                        │
│  • 고객이 다시 다른 고객을 추천해도 원래 딜러에게 수수료 없음             │
│  • 다단계 구조 아님 → 법적 문제 없음                                     │
└─────────────────────────────────────────────────────────────────────────┘
```

### 회원 유형

| 유형 | 설명 | 추천 가능 | 수수료 수령 |
|------|------|----------|------------|
| **일반고객 (customer)** | 차량 구매 고객 | ❌ | ❌ |
| **현지딜러 (local_dealer)** | 몽골 현지 딜러 | ✅ | ✅ |
| **관리자 (admin)** | 시스템 관리자 | ❌ | ❌ |

### 현지딜러 등급 및 수수료율

| 등급 | 조건 | 수수료율 | 혜택 |
|------|------|---------|------|
| **일반 (Standard)** | 기본 | 3.0% | 기본 수수료율 적용 |
| **실버 (Silver)** | 10건 이상 판매 | 3.5% | 수수료율 0.5%p 상향 |
| **골드 (Gold)** | 30건 이상 판매 | 4.0% | 수수료율 1.0%p 상향, 우선 배정 |
| **플래티넘 (Platinum)** | 100건 이상 판매 | 4.5% | 수수료율 1.5%p 상향, 전담 매니저 |

### 수수료 계산 예시

```
차량가: ₩25,000,000
몽골 마진 (5%): ₩1,250,000

┌─────────────────────────────────────────────────────────────┐
│ 딜러 등급별 수수료 배분                                       │
├─────────────────┬─────────────┬─────────────┬───────────────┤
│ 딜러 등급        │ 딜러 수수료  │ 플랫폼 몫    │ 합계 (5%)    │
├─────────────────┼─────────────┼─────────────┼───────────────┤
│ 일반 (3.0%)     │ ₩750,000   │ ₩500,000   │ ₩1,250,000   │
│ 실버 (3.5%)     │ ₩875,000   │ ₩375,000   │ ₩1,250,000   │
│ 골드 (4.0%)     │ ₩1,000,000 │ ₩250,000   │ ₩1,250,000   │
│ 플래티넘 (4.5%) │ ₩1,125,000 │ ₩125,000   │ ₩1,250,000   │
└─────────────────┴─────────────┴─────────────┴───────────────┘

※ 추천인 없는 직접 구매 시: 플랫폼이 5% 전액 수령
```

### 추천 시스템 플로우

```
1. 딜러 등록
   ┌──────────────────────────────────────────────────────────┐
   │ 현지딜러 신청 → 서류 심사 → 승인 → 추천 코드 발급         │
   │                                                          │
   │ 예: 추천코드 "DEALER-ABC123"                             │
   └──────────────────────────────────────────────────────────┘

2. 고객 추천
   ┌──────────────────────────────────────────────────────────┐
   │ 딜러가 고객에게 추천 코드 제공                            │
   │         ↓                                                │
   │ 고객이 회원가입 시 추천 코드 입력                         │
   │         ↓                                                │
   │ 고객 계정에 referred_by = 딜러 ID 저장                   │
   └──────────────────────────────────────────────────────────┘

3. 차량 구매
   ┌──────────────────────────────────────────────────────────┐
   │ 고객이 차량 구매 완료                                     │
   │         ↓                                                │
   │ 시스템이 고객의 추천인(딜러) 확인                         │
   │         ↓                                                │
   │ 딜러 수수료 자동 계산 및 기록                             │
   │         ↓                                                │
   │ 월별/주별 정산 후 딜러에게 지급                           │
   └──────────────────────────────────────────────────────────┘
```

### 딜러 대시보드 기능

```
┌─────────────────────────────────────────────────────────────┐
│  딜러 대시보드 (My Dashboard)                                │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │ 추천 고객    │  │ 이번달 판매 │  │ 총 수수료   │        │
│  │    127명    │  │    5건     │  │ ₩4,750,000 │        │
│  └─────────────┘  └─────────────┘  └─────────────┘        │
│                                                             │
│  내 등급: 🥇 골드 (다음 등급까지 8건)                        │
│  수수료율: 4.0%                                             │
│  추천 코드: DEALER-ABC123  [복사]                           │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  최근 수수료 내역                                    │   │
│  │  ────────────────────────────────────────────────── │   │
│  │  2024.11.25  소나타 DN8    ₩1,000,000  지급완료     │   │
│  │  2024.11.20  아반떼 CN7    ₩800,000    지급완료     │   │
│  │  2024.11.15  K5 DL3       ₩950,000    지급대기     │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  내 추천 고객 목록                                   │   │
│  │  ────────────────────────────────────────────────── │   │
│  │  바트수흐   bat***@email.com  가입일: 2024.11.01    │   │
│  │  엥흐바야르 enk***@email.com  가입일: 2024.10.15    │   │
│  │  ...                                                │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### 정산 주기

| 구분 | 주기 | 최소 지급액 | 지급일 |
|------|------|-----------|--------|
| **일반 정산** | 월 1회 | ₩100,000 | 매월 10일 |
| **VIP 정산** | 주 1회 | ₩500,000 | 매주 금요일 |

---

## 🚚 수수료 체계 및 비용 구조

### 차량별 비용 (1대 기준)

| 내역 | Detail | 단가 | 계산 방식 |
|------|--------|------|----------|
| 차량가액 | Vehicle value | 변동 | 차량별 상이 |
| 성능점검보험료 | Performance inspection fee | ₩100,000 | 고정 |
| 매도세 | Sales fee | ₩440,000 | 고정 |
| 매매알선수수료 | Brokerage commission | ₩250,000 | 고정 |
| 취등록세 | Registration tax | ₩50,000 | 고정 |
| 말소 | Expiration cost | ₩50,000 | 고정 |
| 국내 운송료 | Domestic transportation charges | ₩160,000 | 고정 |
| 야드비 | Yard fee (₩20,000/일) | ₩60,000~ | 일수 × 20,000 |
| 수출면장발급 | Issuance of export exemption | ₩45,000 | 고정 |
| 한국 마진 | Korean Margin (5%) | 차량가 × 5% | 퍼센트 |
| 몽골 마진 | Mongolian Margin (5%) | 차량가 × 5% | 퍼센트 |

### 컨테이너 비용 (4대 분담)

| 내역 | Detail | 컨테이너당 | 차량당(4대 분담) |
|------|--------|-----------|----------------|
| 운송비(기차 4주) | Shipping Cost (Train 4weeks) | ₩5,220,000 | ₩1,305,000 |
| 쇼링(컨테이너작업) | Shoring | ₩600,000 | ₩150,000 |

### 터미널 비용 (4대 분담)

| 내역 | Detail | 컨테이너당 | 차량당(4대 분담) |
|------|--------|-----------|----------------|
| 터미널 조작비용 | THC (Terminal Handling Charge) | ₩190,000 | ₩47,500 |
| 부두하역료 | Wharfage | ₩8,400 | ₩2,100 |
| 컨테이너 실 비용 | Seal Fee | ₩10,000 | ₩2,500 |
| 서류수수료 | Document fee | ₩50,000 | ₩12,500 |

### 비용 계산 예시 (차량가 ₩25,000,000 기준)

```
차량별 비용 소계: ₩28,655,000
  - 차량가액: ₩25,000,000
  - 성능점검보험료: ₩100,000
  - 매도세: ₩440,000
  - 매매알선수수료: ₩250,000
  - 취등록세: ₩50,000
  - 말소: ₩50,000
  - 국내 운송료: ₩160,000
  - 야드비(3일): ₩60,000
  - 수출면장발급: ₩45,000
  - 한국 마진(5%): ₩1,250,000
  - 몽골 마진(5%): ₩1,250,000

컨테이너 분담 비용 소계 (4대 분담시): ₩1,519,600
  - 운송비 분담: ₩1,305,000
  - 쇼링 분담: ₩150,000
  - THC 분담: ₩47,500
  - 부두하역료 분담: ₩2,100
  - Seal Fee 분담: ₩2,500
  - 서류수수료 분담: ₩12,500

총계: ₩30,174,600
```

---

## 🚢 컨테이너 적재 규칙

### 차량 크기 분류

| 분류 | 예시 차종 | 컨테이너당 최대 |
|------|----------|----------------|
| **소형차 (Compact)** | 모닝, 스파크, 레이, i10, i20 등 | 4대 |
| **중형차 (Midsize)** | 아반떼, K3, 소나타, K5, 싼타페 등 | 2대 |

### 적재 조합 규칙

1대의 컨테이너(40ft)에 다음 조합만 가능:

| 조합 | 소형차 | 중형차 | 총 차량 수 | 가능 여부 |
|------|--------|--------|-----------|----------|
| A | 4대 | 0대 | 4대 | ✅ 가능 |
| B | 2대 | 2대 | 4대 | ✅ 가능 |
| C | 0대 | 2대 | 2대 | ✅ 가능 |
| D | 3대 | 1대 | 4대 | ✅ 가능 |
| E | 1대 | 2대 | 3대 | ✅ 가능 |
| F | 0대 | 4대 | 4대 | ❌ **불가능** |

> **중요**: 중형차 4대 조합은 물리적 공간 제약으로 불가능합니다.

### 비용 분담 계산

컨테이너 공유 비용은 적재된 차량 수로 균등 분담:

```
분담 비용 = 컨테이너 총 비용 ÷ 적재 차량 수

예시:
- 4대 적재시: ₩6,078,400 ÷ 4 = ₩1,519,600/대
- 3대 적재시: ₩6,078,400 ÷ 3 = ₩2,026,133/대
- 2대 적재시: ₩6,078,400 ÷ 2 = ₩3,039,200/대
```

---

## 📍 내차찾기 (Vehicle Tracking)

### 기능 개요

차량 구매 고객이 자신의 차량 배송 현황을 실시간으로 확인할 수 있는 서비스

### 주요 기능

1. **지도 표시**
   - 한국 → 몽골 운송 경로 시각화
   - 현재 차량 위치 마커 표시
   - 주요 경유지 표시 (부산항, 중국 경유, 울란바타르)

2. **배송 상태 추적**
   - 단계별 진행 상황 표시
   - 예상 도착일 표시
   - 잔여 일수 카운트다운

3. **배송 이력**
   - 타임라인 형태의 상세 이력
   - 각 단계별 날짜/시간
   - 다국어 설명 (몽골어/영어/러시아어/한국어)

### 배송 상태 단계

```
1. 출고 준비 중 (Preparing for shipment)
   ↓
2. 컨테이너 적재 완료 (Loaded into container)
   ↓
3. 한국 출발 (Departed from Korea)
   ↓
4. 기차 운송 중 (In transit - Rail)
   [약 4주 소요]
   ↓
5. 몽골 도착 (Arrived in Mongolia)
   ↓
6. 통관 진행 중 (Customs clearance in progress)
   ↓
7. 통관 완료 (Customs cleared)
   ↓
8. 인수 대기 (Ready for pickup)
   ↓
9. 인도 완료 (Delivered)
```

### 운송 경로 (예상 소요 시간)

```
부산항 → (기차 4주) → 중국 경유 → 울란바타르
- 총 예상 소요 기간: 28~35일
- 통관 소요 기간: 3~7일 (추가)
```

### UI/UX 설계

```
┌─────────────────────────────────────────────────────────────┐
│  내 차 찾기 (Track My Vehicle)                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                                                     │   │
│  │            [ 지도 영역 ]                            │   │
│  │                                                     │   │
│  │    부산 ●━━━━━━━●━━━━━🚗━━━━━━━━━━━━● 울란바타르    │   │
│  │              중국                                   │   │
│  │                                                     │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  현재 상태: 🚂 기차 운송 중                                  │
│  예상 도착일: 2024년 12월 25일 (D-18)                       │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  배송 이력                                          │   │
│  │  ─────────────────────────────────────────────────  │   │
│  │  ✅ 2024.11.20  출고 준비 완료                      │   │
│  │  ✅ 2024.11.22  컨테이너 적재 완료                   │   │
│  │  ✅ 2024.11.25  한국 출발 (부산항)                   │   │
│  │  🔵 2024.11.27  기차 운송 중 (현재)                  │   │
│  │  ⭕ 예정        몽골 도착                           │   │
│  │  ⭕ 예정        통관 진행                           │   │
│  │  ⭕ 예정        인도 완료                           │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### 프론트엔드 구조

```
apps/web/src/app/[locale]/
  └── mypage/
      └── tracking/
          ├── page.tsx              # 내 차량 목록
          └── [orderId]/
              └── page.tsx          # 상세 추적 페이지

apps/web/src/components/
  └── tracking/
      ├── TrackingMap.tsx           # 지도 컴포넌트
      ├── TrackingStatus.tsx        # 현재 상태 표시
      ├── TrackingTimeline.tsx      # 배송 이력 타임라인
      └── EstimatedArrival.tsx      # 예상 도착일 표시
```

### 지도 서비스 옵션

| 서비스 | 장점 | 단점 |
|--------|------|------|
| **Leaflet + OpenStreetMap** | 무료, 커스터마이징 가능 | 기본 스타일 제한 |
| **Mapbox** | 고품질, 커스터마이징 | 유료 (월 50,000뷰 무료) |
| **Google Maps** | 신뢰성, 정확도 | 비용, 몽골 지역 상세도 낮음 |

> **권장**: Leaflet + OpenStreetMap (무료 + 충분한 기능)

---

## 💰 과금 시스템 (CC 코인 기반)

### 🪙 CC (AutonetSellCar Coin) 시스템

| 항목 | 내용 |
|------|------|
| **기준 화폐** | USDC (Solana 네트워크) |
| **내부 화폐** | CC (AutonetSellCar Coin) |
| **환율** | 1 USDC = 10 CC |
| **신규 가입 보너스** | 3 CC 무상 지급 |
| **차량 정보 열람** | 1대당 1 CC |

### 📸 차량 정보 공개 정책

| 구분 | 비회원/무료 | CC 결제 후 |
|------|-------------|------------|
| **대표 이미지** | 2장만 공개 | 전체 공개 |
| **상세 이미지** | 🔒 블러 처리 | ✅ 전체 공개 |
| **차량 성능표** | 🔒 접근 불가 | ✅ 열람 가능 |
| **연락처** | 🔒 비공개 | ✅ DamonHong +82-10-3331-5258 |
| **상세 옵션** | 🔒 비공개 | ✅ 공개 |

```
┌─────────────────────────────────────────────────────────────────┐
│                    차량 상세 페이지 구조                          │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────────┐   │
│  │  [대표이미지 1]  [대표이미지 2]  [🔒 블러]  [🔒 블러]     │   │
│  │                   무료로 볼 수 있는 사진                  │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │  기본 정보 (무료 공개)                                    │   │
│  │  • 차량명: 기아 K5 2024년형                              │   │
│  │  • 연식: 2024년 7월                                      │   │
│  │  • 주행거리: 14,605 km                                   │   │
│  │  • 가격: $28,500 USDC                                    │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │  🔒 상세 정보 열람하기 (1 CC 필요)                        │   │
│  │                                                          │   │
│  │  ┌──────────────────────────────────────────────────┐   │   │
│  │  │  [1 CC로 상세 정보 열람하기]                       │   │   │
│  │  │                                                   │   │   │
│  │  │  포함 내용:                                       │   │   │
│  │  │  ✓ 전체 사진 (20장)                               │   │   │
│  │  │  ✓ 차량 성능표                                    │   │   │
│  │  │  ✓ 상세 옵션 목록                                 │   │   │
│  │  │  ✓ 연락처 (DamonHong +82-10-3331-5258)            │   │   │
│  │  └──────────────────────────────────────────────────┘   │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
```

### 💳 결제 방식

| 방식 | 설명 | 수수료 | 구현 우선순위 |
|------|------|--------|---------------|
| **카드 결제** | Visa/Mastercard → USDC 자동 변환 | ~3% | Phase 1 |
| **Solana USDC 전송** | 사용자 지갑에서 직접 전송 | <$0.01 | Phase 1 |
| **Phantom Wallet 연동** | 원클릭 결제 | <$0.01 | Phase 2 |
| **TRC-20 USDT** | Tron 네트워크 (레거시 지원) | ~1 USDT | Phase 3 |

### 💼 사용자 지갑 시스템

```
┌─────────────────────────────────────────────────────────────────┐
│                        사용자 지갑 구조                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │  사용자 계정 (users 테이블)                               │   │
│  │  ├── user_id: 12345                                      │   │
│  │  ├── email: user@example.com                             │   │
│  │  ├── cc_balance: 23 CC (현재 보유 코인)                   │   │
│  │  └── solana_wallet_address: "ABC123..."                  │   │
│  └─────────────────────────────────────────────────────────┘   │
│                          │                                      │
│                          ▼                                      │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │  플랫폼 Solana 지갑 (수신 전용)                           │   │
│  │  ├── 주소: "PLATFORM_WALLET_ADDRESS..."                  │   │
│  │  ├── USDC 수신 → 자동 CC 변환 (1 USDC = 10 CC)           │   │
│  │  └── 관리자만 출금 가능                                   │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### 📊 CC 거래 내역 관리

```sql
-- cc_transactions 테이블
CREATE TABLE cc_transactions (
    id SERIAL PRIMARY KEY,
    user_id INTEGER REFERENCES users(id),
    type VARCHAR(20) NOT NULL,  -- 'purchase', 'spend', 'bonus', 'refund'
    amount INTEGER NOT NULL,     -- CC 금액 (양수: 획득, 음수: 사용)
    balance_after INTEGER NOT NULL,  -- 거래 후 잔액
    reference_type VARCHAR(50),  -- 'car_view', 'usdc_payment', 'card_payment', 'signup_bonus'
    reference_id VARCHAR(100),   -- 관련 ID (차량 ID, 결제 ID 등)
    usdc_amount DECIMAL(12,2),   -- USDC 결제 시 금액
    tx_hash VARCHAR(100),        -- Solana 트랜잭션 해시 (USDC 결제 시)
    created_at TIMESTAMP DEFAULT NOW()
);

-- 차량 열람 기록
CREATE TABLE car_views (
    id SERIAL PRIMARY KEY,
    user_id INTEGER REFERENCES users(id),
    car_id INTEGER REFERENCES cars(id),
    cc_spent INTEGER DEFAULT 1,
    viewed_at TIMESTAMP DEFAULT NOW(),
    UNIQUE(user_id, car_id)  -- 동일 차량 중복 결제 방지
);
```

### 💰 가격 정책

> **CC 사용 기준**: 1 CC = 10대 차량 추천 받을 수 있음

| 충전 금액 (USD) | 받는 CC | 추천 가능 차량 | 할인율 |
|-----------------|---------|----------------|--------|
| $10 | 10 CC | 100대 | - |
| $27 | 30 CC | 300대 | 10% 할인 |
| $40 | 50 CC | 500대 | 20% 할인 |

※ 결제 수단: Stripe (Visa/Mastercard), 몽골 파트너 계좌 (러시아 사용자)

---

## 🔐 Solana USDC 지갑 통합 계획

### Phase 1: 기본 지갑 시스템

#### 1.1 플랫폼 수신 지갑 생성
```
┌─────────────────────────────────────────────────────────────────┐
│                    플랫폼 지갑 아키텍처                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  [플랫폼 메인 지갑]                                              │
│  ├── 주소: 공개 (사용자가 입금할 주소)                           │
│  ├── 비밀키: 서버에서 안전하게 관리 (환경변수/Vault)             │
│  ├── 용도: USDC 수신 전용                                       │
│  └── 모니터링: Webhook으로 입금 감지                             │
│                                                                 │
│  [관리자 출금 지갑]                                              │
│  ├── 주소: 비공개                                               │
│  ├── 비밀키: 콜드 스토리지 / 하드웨어 지갑                       │
│  └── 용도: 수익금 출금                                          │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

#### 1.2 USDC 입금 감지 시스템
```python
# Solana USDC 입금 감지 서비스
class SolanaPaymentService:
    def __init__(self):
        self.rpc_url = "https://api.mainnet-beta.solana.com"
        self.usdc_mint = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"  # USDC SPL Token
        self.platform_wallet = os.getenv("PLATFORM_WALLET_ADDRESS")

    async def monitor_deposits(self):
        """Webhook 또는 폴링으로 입금 감지"""
        # 1. 새 USDC 전송 감지
        # 2. 메모 필드에서 user_id 추출
        # 3. CC 크레딧 자동 지급
        # 4. 트랜잭션 기록 저장
        pass

    async def credit_user(self, user_id: int, usdc_amount: float, tx_hash: str):
        """USDC 입금 시 CC 자동 지급"""
        cc_amount = int(usdc_amount * 10)  # 1 USDC = 10 CC
        # DB에 CC 잔액 업데이트 및 거래 기록
        pass
```

#### 1.3 입금 프로세스 (사용자 관점)
```
1. 사용자가 "CC 충전하기" 클릭
2. 입금 안내 페이지 표시:
   - 플랫폼 Solana 지갑 주소
   - 메모(Memo): USER_12345 (사용자 식별용)
   - QR 코드 (Solana Pay 호환)
3. 사용자가 Phantom/Solflare 등에서 USDC 전송
4. 서버가 입금 감지 (1-5초 내)
5. 자동으로 CC 잔액 증가
6. 푸시 알림 또는 화면 갱신
```

### Phase 2: Phantom Wallet 연동 (원클릭 결제)

#### 2.1 Solana Pay 통합
```typescript
// Solana Pay를 이용한 원클릭 결제
import { createQR, encodeURL, TransactionRequestURL } from '@solana/pay';

const createPaymentRequest = (userId: string, usdcAmount: number) => {
  const url: TransactionRequestURL = {
    recipient: PLATFORM_WALLET,
    amount: new BigNumber(usdcAmount),
    splToken: USDC_MINT,
    reference: generateReference(),
    label: 'MongolCar CC 충전',
    message: `${usdcAmount} USDC → ${usdcAmount * 10} CC`,
    memo: `USER_${userId}`,
  };

  return encodeURL(url);
};
```

#### 2.2 Phantom Wallet Connect
```typescript
// Phantom 지갑 연결
const connectPhantom = async () => {
  if (window.solana?.isPhantom) {
    const response = await window.solana.connect();
    const publicKey = response.publicKey.toString();
    // 사용자 계정에 지갑 주소 연결
    await api.linkWallet(publicKey);
  }
};

// 원클릭 USDC 결제
const payWithPhantom = async (usdcAmount: number) => {
  const transaction = await buildUSDCTransferTx(usdcAmount);
  const signedTx = await window.solana.signTransaction(transaction);
  const txHash = await connection.sendRawTransaction(signedTx.serialize());
  return txHash;
};
```

### Phase 3: 카드 결제 통합

#### 3.1 결제 게이트웨이 옵션
| 서비스 | 특징 | 수수료 | 지원 통화 |
|--------|------|--------|-----------|
| **Stripe** | 글로벌, 안정적 | 2.9% + $0.30 | USD, EUR, KRW |
| **MoonPay** | 암호화폐 특화 | 4.5% | USDC 직접 구매 |
| **Transak** | 암호화폐 특화 | 3-5% | USDC 직접 구매 |
| **KG이니시스** | 한국 결제 | 3.3% | KRW |

#### 3.2 카드 → USDC 변환 플로우
```
1. 사용자가 충전 금액 선택 (예: $10)
2. Stripe/MoonPay 결제 창 열림
3. 카드 결제 완료
4. 서버에서 결제 확인
5. CC 잔액 자동 증가 (100 CC)
6. 완료 알림
```

### 📁 필요한 DB 스키마 추가

```sql
-- 사용자 테이블 확장
ALTER TABLE users ADD COLUMN cc_balance INTEGER DEFAULT 0;
ALTER TABLE users ADD COLUMN solana_wallet_address VARCHAR(44);
ALTER TABLE users ADD COLUMN linked_wallet_verified BOOLEAN DEFAULT FALSE;

-- USDC 결제 기록
CREATE TABLE usdc_payments (
    id SERIAL PRIMARY KEY,
    user_id INTEGER REFERENCES users(id),
    tx_hash VARCHAR(100) UNIQUE NOT NULL,
    from_wallet VARCHAR(44) NOT NULL,
    usdc_amount DECIMAL(12,6) NOT NULL,
    cc_credited INTEGER NOT NULL,
    bonus_cc INTEGER DEFAULT 0,
    status VARCHAR(20) DEFAULT 'confirmed',  -- pending, confirmed, failed
    confirmed_at TIMESTAMP,
    created_at TIMESTAMP DEFAULT NOW()
);

-- 카드 결제 기록
CREATE TABLE card_payments (
    id SERIAL PRIMARY KEY,
    user_id INTEGER REFERENCES users(id),
    payment_provider VARCHAR(20) NOT NULL,  -- stripe, moonpay, transak
    provider_payment_id VARCHAR(100) UNIQUE,
    amount_usd DECIMAL(10,2) NOT NULL,
    cc_credited INTEGER NOT NULL,
    bonus_cc INTEGER DEFAULT 0,
    status VARCHAR(20) DEFAULT 'pending',
    completed_at TIMESTAMP,
    created_at TIMESTAMP DEFAULT NOW()
);
```

### 🛠️ 구현 우선순위

| 순서 | 기능 | 예상 기간 | 설명 |
|------|------|-----------|------|
| 1 | CC 시스템 기본 구조 | 1주 | users 테이블 확장, cc_transactions 테이블, 잔액 관리 API |
| 2 | 차량 상세 열람 잠금 | 1주 | 사진 블러 처리, 상세 정보 잠금, CC 차감 로직 |
| 3 | 관리자 CC 수동 지급 | 2일 | 테스트/프로모션용 수동 지급 기능 |
| 4 | Solana 지갑 생성 | 3일 | 플랫폼 수신 지갑 생성, 주소 공개 |
| 5 | USDC 입금 감지 | 1주 | Solana RPC 모니터링, 자동 CC 지급 |
| 6 | Phantom Wallet 연동 | 1주 | 지갑 연결, Solana Pay QR 생성 |
| 7 | 카드 결제 (Stripe) | 1주 | 결제 위젯, 웹훅 처리 |
| 8 | MoonPay/Transak 통합 | 1주 | 암호화폐 직접 구매 옵션 |

---

## 🌐 다국어 지원

### 지원 언어

| 코드 | 언어 | 용도 |
|------|------|------|
| `mn` | 몽골어 (Монгол) | 기본 언어 |
| `en` | 영어 (English) | 국제 |
| `ru` | 러시아어 (Русский) | 러시아, 중앙아시아 |
| `ko` | 한국어 | 관리자, 딜러 |

### 번역 대상

- UI 텍스트 (정적)
- 차량 정보 (동적 - AI 번역)
- 채팅 메시지 (실시간 - Claude API)
- FAQ 응답 (사전 번역 + AI)

---

## 💬 AI 채팅 시스템

### 기능

1. **실시간 번역**: 몽골어 ↔ 한국어 양방향
2. **FAQ 자동 응답**: 딜러 부재 시 AI가 응답
3. **맥락 인식**: 문의 중인 차량 정보 반영

### FAQ 카테고리

| 카테고리 | 예시 질문 |
|----------|-----------|
| `shipping` | 배송 기간, 방법 |
| `payment` | 결제 방법, 환불 |
| `document` | 필요 서류, 관세 |
| `vehicle` | 차량 상태, 옵션 |
| `general` | 영업시간, 연락처 |

---

## 🔧 개발 단계별 작업

### Phase 1: 인프라 구축 (1주)

**목표**: 서버 환경 설정 및 기본 인프라 구축

```bash
# 작업 목록
□ 우분투 서버 2대 OS 설치 및 기본 설정
□ PostgreSQL 16 설치 및 설정
□ Redis 7 설치
□ Nginx 설치 및 SSL 설정
□ Node.js 20 LTS 설치
□ PM2 설치
□ 방화벽 설정
□ SSH 키 기반 인증 설정
□ 서버 간 내부 네트워크 설정
□ 데이터베이스 스키마 생성
```

**Claude Code 명령 예시**:
```
서버 초기 설정 스크립트 작성해줘 (deploy/scripts/setup-server.sh)
- PostgreSQL 16 설치
- Redis 7 설치  
- Nginx 설치
- Node.js 20 설치
- PM2 전역 설치
- 기본 보안 설정
```

---

### Phase 2: Windows 에이전트 (2~3주) ⭐ 핵심

**목표**: 카모두 프로그램 자동화

```bash
# 작업 목록
□ 카모두 프로그램 UI 구조 분석 (Inspect.exe)
□ Python 에이전트 기본 구조 개발
□ 프로그램 연결 기능
□ 차량 검색 자동화
□ 검색 결과 추출
□ 상세 정보 추출
□ 이미지 추출 (20장)
□ API 클라이언트 연동
□ 에러 처리 및 재시도 로직
□ 로깅 시스템
□ Windows 서비스로 등록
```

**Claude Code 명령 예시**:
```
카모두 프로그램 자동화 에이전트 개발해줘 (agent/src/)
- pywinauto 기반
- 검색 조건: 제조사, 모델, 연식, 마일리지, 가격
- 결과 추출: 기본 정보 + 상세 정보 + 이미지 20장
- 비동기 처리 (asyncio)
- API 서버와 통신
```

---

### Phase 3: 백엔드 API (2주)

**목표**: REST API 서버 개발

```bash
# 작업 목록
□ Express.js 프로젝트 설정
□ Prisma 스키마 및 마이그레이션
□ 인증 API (회원가입/로그인/JWT)
□ 차량 검색 API
□ 차량 상세 조회 API (포인트 차감)
□ 결제 API (카드/직접전송)
□ NOWPayments 웹훅 처리
□ 포인트 관리 API
□ 채팅 API
□ 에이전트 통신 API
□ Bull 큐 (검색 요청 처리)
□ 에러 핸들링
□ API 문서화 (Swagger)
```

**Claude Code 명령 예시**:
```
Express.js 백엔드 API 개발해줘 (apps/api/src/)
- TypeScript 기반
- Prisma ORM
- JWT 인증
- 차량 검색/조회 API
- 결제 API (NOWPayments 연동)
- Socket.io 채팅
```

---

### Phase 4: 프론트엔드 (2주)

**목표**: Next.js 웹 애플리케이션 개발

```bash
# 작업 목록
□ Next.js 14 프로젝트 설정
□ 다국어 설정 (next-intl)
□ 레이아웃 및 공통 컴포넌트
□ 메인 페이지 (차량 검색 폼)
□ 검색 결과 페이지
□ 차량 상세 페이지
□ 이미지 갤러리
□ 회원가입/로그인 페이지
□ 마이페이지 (포인트, 열람기록)
□ 결제 페이지 (카드/직접전송)
□ QR 코드 표시
□ 반응형 디자인
□ 로딩/에러 상태 처리
```

**Claude Code 명령 예시**:
```
Next.js 14 프론트엔드 개발해줘 (apps/web/src/)
- App Router 사용
- TypeScript
- Tailwind CSS
- 다국어 (몽골어/영어/러시아어/한국어)
- 차량 검색/목록/상세 페이지
- 결제 모달 (USDT/USDC)
```

---

### Phase 5: 채팅 + 결제 통합 (1~2주)

**목표**: 실시간 채팅 및 결제 시스템 완성

```bash
# 작업 목록
□ Socket.io 서버 설정
□ 채팅방 생성/입장
□ 실시간 메시지 전송
□ Claude API 번역 연동
□ FAQ 자동 응답 로직
□ 채팅 UI 컴포넌트
□ 결제 플로우 테스트
□ 웹훅 테스트
□ 포인트 충전 확인
```

**Claude Code 명령 예시**:
```
실시간 번역 채팅 시스템 개발해줘
- Socket.io 기반
- Claude API로 몽골어↔한국어 번역
- FAQ 자동 응답
- 채팅 UI 컴포넌트
```

---

### Phase 6: 테스트 및 배포 (1주)

**목표**: 전체 시스템 테스트 및 프로덕션 배포

```bash
# 작업 목록
□ 단위 테스트 작성
□ 통합 테스트
□ E2E 테스트 (검색→결제→열람)
□ 성능 테스트
□ 보안 점검
□ SSL 인증서 적용
□ PM2 설정
□ Nginx 설정 최적화
□ 모니터링 설정
□ 백업 스크립트 설정
□ 프로덕션 배포
□ DNS 설정
```

**Claude Code 명령 예시**:
```
배포 스크립트 작성해줘 (deploy/)
- Nginx 설정
- PM2 ecosystem 설정
- systemd 서비스 파일
- 자동 배포 스크립트
```

---

## ⚙️ 환경 변수

### 웹서버 (.env)

```env
# 서버
NODE_ENV=production
PORT=4000
FRONTEND_URL=https://your-domain.com
API_BASE_URL=https://your-domain.com/api

# 데이터베이스
DATABASE_URL=postgresql://user:password@db-server:5432/mongolcar

# Redis
REDIS_URL=redis://localhost:6379

# JWT
JWT_SECRET=your-jwt-secret-key
JWT_EXPIRES_IN=7d

# Claude API
CLAUDE_API_KEY=your-claude-api-key

# NOWPayments
NOWPAYMENTS_API_KEY=your-nowpayments-api-key
NOWPAYMENTS_IPN_SECRET=your-ipn-secret

# 에이전트
AGENT_API_KEY=your-agent-api-key

# 이미지 저장
IMAGE_STORAGE_PATH=/var/www/car-images
IMAGE_BASE_URL=https://your-domain.com/images
```

### Windows 에이전트 (config.yaml)

```yaml
api:
  base_url: https://your-domain.com/api
  api_key: your-agent-api-key

carmodoo:
  process_name: GGKucar
  search_timeout: 30
  detail_timeout: 10

polling:
  interval: 5  # 초

logging:
  level: INFO
  file: agent.log
```

---

## 🚀 Claude Code 개발 시작 명령

### 1. 프로젝트 초기화

```
몽골 중고차 수출 플랫폼 프로젝트 초기화해줘
- monorepo 구조 (apps/web, apps/api, packages/database, agent)
- TypeScript 설정
- ESLint, Prettier 설정
- 기본 README 작성
```

### 2. 데이터베이스 설정

```
PostgreSQL 데이터베이스 스키마 작성해줘 (database/schema.sql)
- 위 계획서의 테이블 구조 기반
- 인덱스 포함
- 초기 데이터 시드 파일도 작성
```

### 3. 백엔드 개발

```
Express.js API 서버 개발 시작해줘 (apps/api/)
- 먼저 프로젝트 구조 설정
- 인증 API부터 시작
- Prisma 스키마 작성
```

### 4. 프론트엔드 개발

```
Next.js 14 프론트엔드 개발 시작해줘 (apps/web/)
- App Router 사용
- 다국어 설정 (next-intl)
- 메인 페이지 (차량 검색) 먼저 개발
```

### 5. 에이전트 개발

```
카모두 자동화 에이전트 개발해줘 (agent/)
- Python 프로젝트 구조 설정
- pywinauto 기반 UI 자동화
- 검색 및 데이터 추출 기능
```

---

## 📝 참고사항

### 카모두 프로그램 정보

- **개발사**: (주)이엠아이앤씨
- **용도**: 경기도자동차매매사업조합 딜러 전용
- **기술**: .NET Assembly (WinForms/WPF 추정)
- **파일**: GGKucar.exe (64KB, 런처)

### 주요 외부 서비스

| 서비스 | 용도 | 링크 |
|--------|------|------|
| NOWPayments | 암호화폐 결제 | https://nowpayments.io |
| Anthropic Claude | AI 번역/챗봇 | https://anthropic.com |
| ExchangeRate API | 환율 조회 | https://exchangerate-api.com |

---

## 📞 문의사항

### 대표 연락처 (모든 딜러 연락처 통일)
- **담당자**: DamonHong
- **전화**: +82-10-3331-5258

### 개발 진행 중 추가 정보가 필요한 사항:

1. **카모두 프로그램 UI 스크린샷** - 자동화 개발에 필요
2. **도메인 및 SSL 인증서** - 배포 시 필요
3. **NOWPayments 계정** - 결제 테스트에 필요
4. **Claude API 키** - 번역/챗봇 개발에 필요

---

## 🔍 카모두 API 분석 (Reverse Engineering)

### 개요

Fiddler를 통해 캡처한 카모두 프로그램(GGKucar.exe)의 네트워크 트래픽 분석 결과입니다.

### 기본 정보

| 항목 | 내용 |
|------|------|
| **도메인** | dealer.carmodoo.com (메인), ck.carmodoo.com (성능점검) |
| **프로토콜** | HTTPS (TLS 1.2/1.3) |
| **인증 방식** | 세션 기반 (PHPSESSID 쿠키) |
| **서버** | Apache/2.4.6 (CentOS), PHP/5.4.16 |
| **인코딩** | EUC-KR |

### 인증 API

#### 1. 로그인
```http
POST https://dealer.carmodoo.com/member/login_ok.html
Content-Type: application/x-www-form-urlencoded

prevURL=&id={전화번호}&passwd={비밀번호}&idSave=Y&button=LOGIN
```

**응답**:
```html
<script type='text/javascript'>
  try { window.external.GoMain(); } catch(ex1) {}
  try { cAPI.goMain(); } catch(ex1) {}
</script>
```

**인증 쿠키**: `PHPSESSID`, `idSave`

#### 2. 세션 유지
```http
POST https://dealer.carmodoo.com/common/ajax/sessionHold.html
X-Requested-With: XMLHttpRequest
Cookie: PHPSESSID={세션ID}
```

### 차량 데이터 API

#### 1. 제조사/모델 코드 조회 (AutoDBCode.html)

**초기 데이터 로드**:
```http
GET https://dealer.carmodoo.com/common/ajax/AutoDBCode.html?mode=getCarInit&ctl=car
```

**제조사별 모델 목록**:
```http
GET https://dealer.carmodoo.com/common/ajax/AutoDBCode.html?mode=getCarModelInit&ctl=car&company={제조사ID}
```

**모델별 세부 모델**:
```http
GET https://dealer.carmodoo.com/common/ajax/AutoDBCode.html?mode=getCarModel&ctl=car&company={제조사ID}&c_nameInit={모델ID}
```

**세부 모델별 연식**:
```http
GET https://dealer.carmodoo.com/common/ajax/AutoDBCode.html?mode=getCarYear&ctl=car&c_name={모델코드}
```

**시리즈 조회**:
```http
GET https://dealer.carmodoo.com/common/ajax/AutoDBCode.html?mode=getCarSeries&ctl=car&c_name={모델코드}
```

**세부사양 조회**:
```http
GET https://dealer.carmodoo.com/common/ajax/AutoDBCode.html?mode=getCarSdetail&ctl=car&series={시리즈코드}
```

**응답 형식** (XML):
```xml
<?xml version="1.0" encoding="EUC-KR"?>
<root>
  <ctl>car</ctl>
  <item>
    <key>5</key>
    <name><![CDATA[현대]]></name>
    <cho>1</cho>
    <field>c_bmNo</field>
  </item>
  ...
</root>
```

**주요 제조사 코드**:
| 코드 | 제조사 |
|------|--------|
| 5 | 현대 |
| 2 | 기아 |
| 1 | 쌍용 |
| 3 | 르노 |
| 67 | BMW |
| 68 | 벤츠 |
| 70 | 아우디 |

#### 2. 차량 목록 조회 (AutoDBProc.html)

**관심 차량 조회**:
```http
GET https://dealer.carmodoo.com/common/ajax/AutoDBProc.html?mode=getInterest&iStr={차량번호들!구분}
```

예시: `iStr=6290623!6290630!6290644!...`

**응답**: `Y|` (관심등록 여부)

**관심 차량 추가**:
```http
POST https://dealer.carmodoo.com/common/ajax/AutoDBProc.html
Content-Type: application/x-www-form-urlencoded

mode=addInterest&c_no={차량번호}&memo={메모}
```

**관심 차량 삭제**:
```http
GET https://dealer.carmodoo.com/common/ajax/AutoDBProc.html?mode=delInterest&c_no={차량번호}
```

#### 3. 차량 상세 조회 (AutoDB.html)

```http
GET https://dealer.carmodoo.com/common/ajax/AutoDB.html?mode=view&key={암호화된키}
```

**key 파라미터**: Base64 인코딩된 암호화 문자열
예시: `U1VqWHNxc2FOaDY0LzAyYUtaRDdibTdQZnc4cXZ4dXh6czVyelJjdHRHcz0`

**응답 형식** (XML):
```xml
<cars>
  <no>6320434</no>
  <c_bgNo>1</c_bgNo>
  <c_boNo>2828</c_boNo>
  <carName>2020년형 기아 K5 DL3 2.0 가솔린</carName>
  <c_subject>차량 제목</c_subject>
  <c_gearbox>오토</c_gearbox>
  <c_fuel>가솔린</c_fuel>
  <c_mileage>45000</c_mileage>
  <c_colorName>흰색</c_colorName>
  <c_carNum>12가3456</c_carNum>
  <dPrice>25000000</dPrice>
  <YM>2020년 06월</YM>
  <c_year>2020</c_year>
  <c_month>6</c_month>
  <c_displacement>1998</c_displacement>
  <c_seize>0</c_seize>
  <c_collateral>0</c_collateral>
  <c_memoStr>메모 내용</c_memoStr>
  <c_options>1#5#12#34#...</c_options>
  <mainImage>/data/__carPhoto/006/320/434/cmcar_0.jpg</mainImage>
  <strPhotos>/data/__carPhoto/006/320/434/cmcar_0.jpg|cmcar_1.jpg|...</strPhotos>
  <strPhotosThum>썸네일 경로들</strPhotosThum>
  <c_checkNum>123456789</c_checkNum>
  <c_checkUrl>성능점검 URL</c_checkUrl>
  <c_checkGubun>ggkucar</c_checkGubun>
  <d_name>딜러명</d_name>
  <d_hp>010-1234-5678</d_hp>
  <s_name>매매상사명</s_name>
  <s_tel>031-123-4567</s_tel>
</cars>
```

#### 4. 차량 상세 페이지 (HTML)

```http
GET http://dealer.carmodoo.com/car/dealerCarView.html?key={암호화된키}&tabStart=1
```

### 이미지 URL 패턴

**원본 이미지**:
```
http://dealer.carmodoo.com/data/__carPhoto/{3자리}/{3자리}/{3자리}/cmcar_{순번}.jpg
```

**썸네일 이미지**:
```
http://dealer.carmodoo.com/data/__carPhoto/{3자리}/{3자리}/{3자리}/cmcar_{순번}.jpg__THUM
```

**URL 구조 설명**:
- 차량번호 6320434의 경우: `/006/320/434/`
- 첫 번째 이미지: `cmcar_0.jpg`
- 두 번째 이미지: `cmcar_1.jpg`

### 성능점검 API

```http
GET https://ck.carmodoo.com/carCheck/carmodooPrint.do?checkNum={성능점검번호}
```

### 시세 조회 API

```http
GET https://dealer.carmodoo.com/common/ajax/SiseDB.html?mode=getSiseData&ctl={구분}&company={제조사코드}&c_name={모델코드}
```

### Python 에이전트 구현 참고

```python
import aiohttp
import asyncio
from urllib.parse import urlencode

class CarmodooClient:
    BASE_URL = "https://dealer.carmodoo.com"

    def __init__(self):
        self.session = None
        self.cookies = {}

    async def login(self, user_id: str, password: str) -> bool:
        """로그인 및 세션 쿠키 획득"""
        async with aiohttp.ClientSession() as session:
            data = {
                'prevURL': '',
                'id': user_id,
                'passwd': password,
                'idSave': 'Y',
                'button': 'LOGIN'
            }
            async with session.post(
                f"{self.BASE_URL}/member/login_ok.html",
                data=data,
                headers={'Content-Type': 'application/x-www-form-urlencoded'}
            ) as resp:
                if resp.status == 200:
                    self.cookies = {c.key: c.value for c in session.cookie_jar}
                    return 'goMain' in await resp.text()
        return False

    async def get_car_makers(self) -> list:
        """제조사 목록 조회"""
        params = {'mode': 'getCarInit', 'ctl': 'car'}
        async with aiohttp.ClientSession(cookies=self.cookies) as session:
            async with session.get(
                f"{self.BASE_URL}/common/ajax/AutoDBCode.html",
                params=params
            ) as resp:
                # XML 파싱 후 반환
                pass

    async def get_car_detail(self, key: str) -> dict:
        """차량 상세 정보 조회"""
        params = {'mode': 'view', 'key': key}
        async with aiohttp.ClientSession(cookies=self.cookies) as session:
            async with session.get(
                f"{self.BASE_URL}/common/ajax/AutoDB.html",
                params=params
            ) as resp:
                # XML 파싱 후 반환
                pass

    async def download_image(self, car_no: int, index: int) -> bytes:
        """차량 이미지 다운로드"""
        # 차량번호를 3자리씩 분할
        path = f"{car_no:09d}"
        folder = f"{path[0:3]}/{path[3:6]}/{path[6:9]}"
        url = f"{self.BASE_URL}/data/__carPhoto/{folder}/cmcar_{index}.jpg"

        async with aiohttp.ClientSession(cookies=self.cookies) as session:
            async with session.get(url) as resp:
                if resp.status == 200:
                    return await resp.read()
        return None
```

### 주요 데이터 필드 매핑

| carmodoo 필드 | 의미 | DB 필드 |
|---------------|------|---------|
| c_no / no | 차량 고유번호 | source_id |
| carName | 차량명 (풀네임) | - |
| c_bmNo | 제조사 코드 | make |
| c_boNo | 모델 코드 | model |
| c_year | 연식 | year |
| c_mileage | 주행거리 | mileage |
| dPrice | 판매가격 | price |
| c_fuel | 연료 | fuel_type |
| c_gearbox | 변속기 | transmission |
| c_colorName | 색상 | color |
| c_displacement | 배기량 | engine_cc |
| c_options | 옵션 (#구분) | options |
| c_checkNum | 성능점검번호 | inspection_data |
| c_seize | 압류 건수 | - |
| c_collateral | 저당 건수 | - |

### 보안 고려사항

1. **HTTPS 필수**: 모든 요청은 HTTPS로 전송
2. **세션 관리**: PHPSESSID 쿠키 유지 필요
3. **Rate Limiting**: 과도한 요청 시 차단 가능성
4. **인코딩**: EUC-KR → UTF-8 변환 필요

---

## 구현 완료 기능 (2024-12-25)

### 상세사양조회 시스템

차량번호 기반으로 AUTOBEGINS 서비스에서 상세사양을 조회하는 시스템이 구현되었습니다.

**주요 기능**:
- Playwright 브라우저 자동화로 Carmodoo 딜러 포탈의 AUTOBEGINS iframe 접근
- 차량번호 입력 → 상세사양 파싱 → DB 저장
- 배너 등록(import) 시 자동 사양 조회

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

**관련 파일**:
- `backend/app/services/spec_service.py` - 사양 조회 로직
- `backend/app/models/car_specification.py` - CarSpecification 모델
- `backend/app/api/carmodoo.py` - API 엔드포인트

### 딜러 상세설명

Carmodoo 상세페이지에서 딜러가 작성한 설명을 추출하여 저장합니다.

**추출 방식** (2024-12-25 업데이트):
1. 차량 검색 결과에서 `dealerCarviewPopup('암호화키')` JavaScript 호출 패턴을 파싱하여 `car_key` 추출
2. `dealerCarView.html?key=<car_key>&tabStart=1` URL로 딜러 상세페이지 조회
3. `<div class="carViewMemoWrap"><h3>상세설명</h3><div class="memo">...</div></div>` HTML 구조에서 설명 추출
4. `cars.dealer_description` 컬럼에 저장

**주의**: 이전의 `carPopView.html`은 더 이상 작동하지 않음 (404 반환)

**관련 코드**:
- `carmodoo.py: _parse_car_list_html()` - car_key 추출 (dealerCarviewPopup 패턴)
- `carmodoo.py: get_car_detail()` - dealerCarView.html에서 상세설명 파싱
- 차량 상세 페이지에서 amber 배경으로 표시 (로그인 사용자만)

### Quote Request 1CC 결제

차량 추천 요청 시 1 CC가 차감되도록 구현되었습니다.

**흐름**:
1. 사용자가 `/vehicle-request` 페이지에서 조건 입력
2. 제출 시 CC 잔액 확인 (1 CC 필요)
3. 잔액 부족 시 `/cc` 충전 페이지로 안내
4. CC 차감 후 요청 생성

**관련 파일**:
- `backend/app/api/vehicle_requests.py` - CC 차감 로직
- `backend/app/models/vehicle_request.py` - cc_paid 컬럼
- `frontend/src/app/vehicle-request/page.tsx` - UI (CC 잔액 표시, 비용 안내)

---

*마지막 업데이트: 2024년 12월 25일*

---

## 변경 이력

| 날짜 | 변경 내용 |
|------|----------|
| 2024-12-25 | 딜러 상세설명 추출 방식 변경 (carPopView.html → dealerCarView.html + car_key) |
| 2024-12-25 | car_key 필드 추가 (CarmodooSearchResultItem, AdminSearchResultItem, ImportCarRequest) |
| 2024-12-25 | 프론트엔드 api.ts, hero-banners/page.tsx에 car_key 연동 |
