DinQuant/README_KO.md

<div align="center">
  <a href="README.md">🇺🇸 English</a> |
  <a href="README_CN.md">🇨🇳 简体中文</a> |
  <a href="README_TW.md">🇹🇼 繁體中文</a> |
  <a href="README_JA.md">🇯🇵 日本語</a> |
  <a href="README_KO.md">🇰🇷 한국어</a>
</div>
<br/>

<div align="center">
  <a href="https://github.com/brokermr810/QuantDinger">
    <img src="https://ai.quantdinger.com/img/logo.e0f510a8.png" alt="QuantDinger Logo" width="160" height="160">
  </a>

  <h1 align="center">QuantDinger</h1>

  <h3 align="center">
    차세대 AI 퀀트 트레이딩 플랫폼
  </h3>

  <p align="center">
    <strong>🤖 AI 네이티브 · 🐍 비주얼 파이썬 · 🌍 글로벌 멀티 마켓 · 🔒 프라이버시 우선</strong>
  </p>
  <p align="center">
    <i>AI 코파일럿과 함께하는 구축, 백테스팅 및 트레이딩 플랫폼. PineScript보다 강력하고, SaaS보다 똑똑합니다.</i>
  </p>

  <p align="center">
  <a href="https://www.quantdinger.com"><strong>공식 커뮤니티</strong></a> ·
  <a href="https://ai.quantdinger.com"><strong>라이브 데모</strong></a> ·
  <a href="https://youtu.be/HPTVpqL7knM"><strong>📺 동영상 데모</strong></a> ·
  <a href="CONTRIBUTORS.md"><strong>🌟 참여하기</strong></a>
  </p>

  <p align="center">
    <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=flat-square&logo=apache" alt="License"></a>
    <img src="https://img.shields.io/badge/Python-3.10+-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python">
    <img src="https://img.shields.io/badge/Vue.js-2.x-4FC08D?style=flat-square&logo=vue.js&logoColor=white" alt="Vue">
    <img src="https://img.shields.io/badge/Docker-Ready-2496ED?style=flat-square&logo=docker&logoColor=white" alt="Docker">
    <img src="https://img.shields.io/github/stars/brokermr810/QuantDinger?style=flat-square&logo=github" alt="Stars">
  </p>

  <p align="center">
    <a href="https://t.me/quantdinger"><img src="https://img.shields.io/badge/Telegram-QuantDinger%20Group-26A5E4?style=for-the-badge&logo=telegram" alt="Telegram Group"></a>
    <a href="https://discord.gg/vwJ8zxFh9Q"><img src="https://img.shields.io/badge/Discord-Join%20Server-5865F2?style=for-the-badge&logo=discord" alt="Discord"></a>
    <a href="https://x.com/HenryCryption"><img src="https://img.shields.io/badge/X-Follow%20Us-000000?style=for-the-badge&logo=x" alt="X"></a>
  </p>
</div>

---

## 📖 소개

### QuantDinger란 무엇인가요?

QuantDinger는 **로컬 우선, 프라이버시 우선의 셀프 호스팅 정량 거래 인프라**입니다. 귀하의 머신/서버에서 실행되며, **PostgreSQL 기반 멀티 유저 계정**을 제공하면서도 전략, 거래 데이터 및 API 키를 완전히 제어할 수 있습니다.

### 왜 로컬 우선인가요?

데이터와 전략을 클라우드에 잠그는 SaaS 플랫폼과 달리, QuantDinger는 로컬에서 실행됩니다. 귀하의 전략, 거래 로그, API 키 및 분석 결과는 모두 귀하의 머신에 저장됩니다. 벤더 잠금 없음, 구독료 없음, 데이터 유출 없음.

### 누구를 위한 것인가요?

QuantDinger는 다음을 위한 사용자를 위해 구축되었습니다:
- 데이터 주권과 프라이버시를 중시하는 트레이더, 연구원 및 엔지니어
- 투명하고 감사 가능한 거래 인프라를 원하는 사람
- 마케팅보다 엔지니어링을 선호하는 사람
- 완전한 워크플로우가 필요한 사람: 데이터, 분석, 백테스팅 및 실행

### 핵심 기능

QuantDinger는 웹에서 금융 정보를 수집하고, 로컬 시장 데이터와 결합하여 분석 보고서를 생성하는 내장 **LLM 기반 멀티 에이전트 리서치 시스템**을 포함합니다. 이것은 전략 개발, 백테스팅 및 실거래 워크플로우와 통합됩니다.

### 핵심 가치

- **🔓 Apache 2.0 오픈소스(코드)**: 허용적이며 상업적으로 친화적입니다. Apache 2.0 범위에서 fork/수정이 가능하지만, 라이선스/저작권 고지 등 필요한 표기는 유지해야 합니다.
- **🐍 파이썬 네이티브 & 비주얼**: 표준 파이썬으로 지표를 작성(PineScript보다 쉬움)하고 AI의 지원을 받으세요. 차트에서 신호를 직접 시각화하여 "로컬 버전의 TradingView" 경험을 구축하세요.
- **🤖 AI 루프 최적화**: 전략을 실행할 뿐만 아니라, AI가 백테스트 결과를 분석하여 매개변수 조정(손절매/이익실현/MACD 설정)을 제안하고 폐루프 최적화를 형성합니다.
- **🌍 글로벌 마켓 액세스**: 암호화폐(실거래), 미국/중국 주식, 외환 및 선물(데이터/알림)을 지원하는 통합 시스템.
- **⚡ Docker & 클린 아키텍처**: 4줄 명령어로 빠른 배포. 모던 기술 스택(Vue + Python), 클린 아키텍처, 관심사 분리.

---

## 📺 동영상 데모

<div align="center">
  <a href="https://youtu.be/HPTVpqL7knM">
    <img src="docs/screenshots/video_demo.png" alt="QuantDinger 프로젝트 소개 동영상" width="100%" style="border-radius: 10px; box-shadow: 0 4px 12px rgba(0,0,0,0.15); max-width: 800px;">
  </a>
  <p><strong>위 동영상을 클릭하여 QuantDinger 프로젝트 소개를 시청하세요</strong></p>
</div>

---

## 📚 문서

### 개발 가이드
- [Python 전략 개발 가이드](docs/STRATEGY_DEV_GUIDE_KO.md)
- [Interactive Brokers (IBKR) 트레이딩 가이드](docs/IBKR_TRADING_GUIDE_EN.md) 🆕
- [MetaTrader 5 (MT5) 트레이딩 가이드](docs/MT5_TRADING_GUIDE_EN.md) 🆕

### 알림 설정
- [Telegram 알림 설정](docs/NOTIFICATION_TELEGRAM_CONFIG_EN.md)
- [이메일 (SMTP) 알림 설정](docs/NOTIFICATION_EMAIL_CONFIG_EN.md)
- [SMS (Twilio) 알림 설정](docs/NOTIFICATION_SMS_CONFIG_EN.md)

## 📸 비주얼 투어

<div align="center">
  <h3>🗺️ 시스템 아키텍처 개요</h3>
  <p>QuantDinger의 AI 기반 리서치, 백테스팅 및 자동화 거래 기능 전체 개요.</p>
  <img src="docs/screenshots/tuopu.png" alt="QuantDinger 시스템 토폴로지" width="100%" style="border-radius: 10px; box-shadow: 0 4px 12px rgba(0,0,0,0.15); max-width: 800px;">
</div>

<br/>

<div align="center">
  <h3>📊 전문 퀀트 대시보드</h3>
  <p>시장 역학, 자산 및 전략 상태에 대한 실시간 모니터링.</p>
  <img src="docs/screenshots/dashboard.png" alt="QuantDinger Dashboard" width="100%" style="border-radius: 10px; box-shadow: 0 4px 8px rgba(0,0,0,0.1);">
</div>

<br/>

<table align="center" width="100%">
  <tr>
    <td width="50%" align="center" valign="top">
      <h3>🤖 AI 딥 리서치</h3>
      <p>시장 심리 및 기술적 분석을 위한 멀티 에이전트 협업.</p>
      <img src="docs/screenshots/ai_analysis1.png" alt="AI Market Analysis" style="border-radius: 6px;">
    </td>
    <td width="50%" align="center" valign="top">
      <h3>💬 스마트 트레이딩 어시스턴트</h3>
      <p>즉각적인 시장 통찰력을 위한 자연어 인터페이스.</p>
      <img src="docs/screenshots/trading_assistant.png" alt="Trading Assistant" style="border-radius: 6px;">
    </td>
  </tr>
  <tr>
    <td width="50%" align="center" valign="top">
      <h3>📈 대화형 지표 분석</h3>
      <p>드래그 앤 드롭 분석이 가능한 풍부한 기술적 지표 라이브러리.</p>
      <img src="docs/screenshots/indicator_analysis.png" alt="Indicator Analysis" style="border-radius: 6px;">
    </td>
    <td width="50%" align="center" valign="top">
      <h3>🐍 Python 전략 생성</h3>
      <p>AI 지원 전략 코딩이 가능한 내장 에디터.</p>
      <img src="docs/screenshots/indicator_creat_python_code.png" alt="Code Generation" style="border-radius: 6px;">
    </td>
  </tr>
  <tr>
    <td colspan="2" align="center" valign="top">
      <h3>📊 포트폴리오 모니터</h3>
      <p>포지션 추적, 알림 설정, 이메일/Telegram으로 AI 분석 보고서 수신.</p>
      <img src="docs/screenshots/portfolio.jpg" alt="Portfolio Monitor" style="border-radius: 6px; max-width: 90%;">
    </td>
  </tr>
</table>

---

## ✨ 주요 기능

### 1. 비주얼 파이썬 전략 워크벤치
*PineScript보다 강력하고, SaaS보다 똑똑합니다.*

- **파이썬 네이티브**: 파이썬으로 지표와 전략을 작성하세요. PineScript와 같은 전용 언어 대신 완전한 파이썬 생태계(Pandas, Numpy, TA-Lib)를 활용하세요.
- **"Mini-TradingView" 경험**: 내장된 K-라인 차트에서 파이썬 지표를 직접 실행하세요. 과거 데이터에서 매수/매도 신호를 시각적으로 디버깅하세요.
- **AI 지원 코딩**: 내장 AI가 복잡한 로직을 작성하도록 하세요. 아이디어에서 코드까지 단 몇 초면 됩니다.

### 2. 완전한 거래 라이프사이클
*지표에서 실행까지, 매끄럽게.*

1.  **지표**: 시장 진입/청산 신호를 정의하세요.
2.  **전략 설정**: 위험 관리 규칙(포지션 사이징, 손절매, 이익실현)을 추가하세요.
3.  **백테스트 & AI 최적화**: 백테스트를 실행하고, 풍부한 성과 지표를 확인하며, **AI가 결과를 분석하여 개선 사항을 제안**하도록 하세요(예: "MACD 임계값을 X로 조정").
4.  **실행 모드**:
    - **실거래**:
      - **암호화폐**: 직접 API 실행, 10개 이상의 거래소(Binance, OKX, Bitget, Bybit 등) 지원
      - **미국/홍콩 주식**: Interactive Brokers (IBKR) 경유 🆕
      - **외환**: MetaTrader 5 (MT5) 경유 🆕
    - **신호 알림**: 실거래를 지원하지 않는 시장(A주/선물)의 경우, Telegram, Discord, Email, SMS 또는 Webhook을 통해 신호를 전송하세요.

### 3. AI 분석 시스템
*빠르고, 정확하며, 전문적인 리포트.*

QuantDinger는 효율적인 AI 분석 시스템을 탑재:

- **빠른 분석 모드**: 단일 LLM 호출 아키텍처로 빠르고 정확한 분석 (복잡한 멀티 에이전트 시스템 대체)
- **글로벌 시장 통합**: 실시간 시장 데이터, 히트맵, 경제 캘린더를 분석 페이지에 통합
- **ATR 기반 거래 수준**: 기술적 분석(ATR, 지지/저항선)에 기반한 손절매 및 이익실현 권장
- **분석 메모리**: 이력 검토 및 지속적 학습을 위한 분석 결과 저장
- **전략 통합**: AI 분석을 전략의 "시장 필터"로 사용 가능

### 4. 범용 데이터 엔진

QuantDinger는 여러 시장에 걸친 통합 데이터 인터페이스를 제공합니다:

- **암호화폐**: 거래를 위한 직접 API 연결（10개 이상의 거래소）및 시장 데이터를 위한 CCXT 통합（100개 이상의 소스）
- **주식**: Yahoo Finance, Finnhub, Tiingo（미국 주식）및 AkShare（중국/홍콩 주식）
- **선물/외환**: OANDA 및 주요 선물 데이터 소스
- **프록시 지원**: 제한된 네트워크 환경을 위한 내장 프록시 구성

### 5. 🧠 메모리 증강 에이전트(Memory-Augmented Agents)
QuantDinger의 에이전트는 매번 “처음부터” 시작하지 않습니다. 백엔드에는 **로컬 메모리 DB + 리플렉션(검증) 루프**가 내장되어 있어, 과거 경험을 검색해 system prompt에 주입하는 RAG 스타일의 강화가 동작합니다.

- **무엇인가**: 경험 검색 기반 프롬프트 강화(모델 파인튜닝/학습이 아님)
- **저장 위치**: 로컬 SQLite (`backend_api_python/data/memory/`)

#### 흐름도(요청 → 메모리 폐루프)

```mermaid
flowchart TB
    %% ===== 🌐 진입 레이어 =====
    subgraph Entry["🌐 API 진입점"]
        A["📡 POST /api/analysis/multi"]
        A2["🔄 POST /api/analysis/reflect"]
    end

    %% ===== ⚙️ 서비스 레이어 =====
    subgraph Service["⚙️ 서비스 오케스트레이션"]
        B[AnalysisService]
        C[AgentCoordinator]
        D["📊 컨텍스트 구성<br/>price · kline · news · indicators"]
    end

    %% ===== 🤖 멀티에이전트 워크플로우 =====
    subgraph Agents["🤖 멀티에이전트 워크플로우"]

        subgraph P1["📈 Phase 1 · 다차원 분석（병렬）"]
            E1["🔍 MarketAnalyst<br/><i>기술적 분석</i>"]
            E2["📑 FundamentalAnalyst<br/><i>펀더멘털</i>"]
            E3["📰 NewsAnalyst<br/><i>뉴스</i>"]
            E4["💭 SentimentAnalyst<br/><i>심리</i>"]
            E5["⚠️ RiskAnalyst<br/><i>리스크 평가</i>"]
        end

        subgraph P2["🎯 Phase 2 · 강세/약세 논쟁（병렬）"]
            F1["🐂 BullResearcher<br/><i>강세 논거</i>"]
            F2["🐻 BearResearcher<br/><i>약세 논거</i>"]
        end

        subgraph P3["💹 Phase 3 · 거래 결정"]
            G["🎰 TraderAgent<br/><i>종합 판단 → BUY / SELL / HOLD</i>"]
        end

    end

    %% ===== 🧠 메모리 레이어 =====
    subgraph Memory["🧠 로컬 SQLite 메모리（data/memory/）"]
        M1[("market_analyst")]
        M2[("fundamental")]
        M3[("news_analyst")]
        M4[("sentiment")]
        M5[("risk_analyst")]
        M6[("bull_researcher")]
        M7[("bear_researcher")]
        M8[("trader_agent")]
    end

    %% ===== 🔄 리플렉션 루프 =====
    subgraph Reflect["🔄 리플렉션 루프（옵션）"]
        R[ReflectionService]
        RR[("reflection_records.db")]
        W["⏰ ReflectionWorker"]
    end

    %% ===== 메인 흐름 =====
    A --> B --> C --> D
    D --> P1 --> P2 --> P3

    %% ===== 메모리 읽기/쓰기 =====
    E1 <-.-> M1
    E2 <-.-> M2
    E3 <-.-> M3
    E4 <-.-> M4
    E5 <-.-> M5
    F1 <-.-> M6
    F2 <-.-> M7
    G <-.-> M8

    %% ===== 리플렉션 흐름 =====
    C --> R --> RR
    W --> RR
    W -.->|"검증 + 학습"| M8
    A2 -.->|"수동 회고"| M8
```

#### 검색 랭킹(간략)
\[
score = w_{sim}\cdot sim + w_{recency}\cdot recency + w_{returns}\cdot returns\_score
\]

#### 학습 경로
- **수동 회고(추천)**: `POST /api/analysis/reflect`로 실제 결과(returns/result)를 메모리에 기록
- **자동 검증(옵션)**: `ENABLE_REFLECTION_WORKER=true`, `REFLECTION_WORKER_INTERVAL_SEC`로 주기적 검증→메모리 반영

#### 주요 환경 변수(`.env`)
- `ENABLE_AGENT_MEMORY`, `AGENT_MEMORY_TOP_K`, `AGENT_MEMORY_CANDIDATE_LIMIT`
- `AGENT_MEMORY_ENABLE_VECTOR`, `AGENT_MEMORY_EMBEDDING_DIM`
- `AGENT_MEMORY_HALF_LIFE_DAYS`, `AGENT_MEMORY_W_SIM`, `AGENT_MEMORY_W_RECENCY`, `AGENT_MEMORY_W_RETURNS`
- `ENABLE_REFLECTION_WORKER`, `REFLECTION_WORKER_INTERVAL_SEC`

### 6. 전략 런타임

- **스레드 기반 실행기**: 전략 실행을 위한 독립적인 스레드 풀
- **자동 복구**: 시스템 재시작 후 실행 중인 전략 재개
- **주문 대기열**: 주문 실행을 위한 백그라운드 워커

### 7. 멀티 LLM 제공자 지원

QuantDinger는 자동 감지 기능을 갖춘 여러 AI 제공자를 지원합니다:

| 제공자 | 특징 |
|--------|------|
| **OpenRouter** | 멀티모델 게이트웨이(기본값), 100+ 모델 |
| **OpenAI** | GPT-4o, GPT-4o-mini |
| **Google Gemini** | Gemini 1.5 Flash/Pro |
| **DeepSeek** | DeepSeek Chat(가성비 좋음) |
| **xAI Grok** | Grok Beta |

`.env`에서 선호하는 제공자의 API 키만 설정하면 시스템이 사용 가능한 제공자를 자동 감지합니다.

### 8. 인디케이터 커뮤니티
*공유, 발견, 거래.*

- **게시 및 공유**: 파이썬 인디케이터를 커뮤니티와 공유
- **구매 시스템**: 다른 사용자로부터 프리미엄 인디케이터 구매
- **평점 및 리뷰**: 구매한 인디케이터 평가 및 리뷰
- **관리자 검토**: 품질 관리를 위한 모더레이션 시스템

### 9. 사용자 관리 및 보안

- **멀티유저 지원**: PostgreSQL 기반 사용자 계정, 역할 기반 권한 관리
- **OAuth 로그인**: Google 및 GitHub OAuth 통합
- **이메일 인증**: 이메일 인증 코드를 통한 등록 및 비밀번호 재설정
- **보안 기능**: Cloudflare Turnstile 캡차, IP/계정 속도 제한
- **데모 모드**: 공개 데모를 위한 읽기 전용 모드

### 10. 기술 스택

- **백엔드**: Python (Flask) + PostgreSQL + Redis（옵션）
- **프론트엔드**: Vue 2 + Ant Design Vue + KlineCharts/ECharts
- **배포**: Docker Compose
- **현재 버전**: V2.1.1 ([변경 로그](docs/CHANGELOG.md))

---

## 🔌 지원되는 거래소 및 브로커

QuantDinger는 다양한 시장 유형에 대해 여러 실행 방법을 지원합니다:

### 암호화폐 거래소(직접 API)

| 거래소 | 시장 |
|:--------:|:---------|
| Binance | 현물, 선물, 마진 |
| OKX | 현물, 무기한, 옵션 |
| Bitget | 현물, 선물, 카피 트레이딩 |
| Bybit | 현물, 선형 선물 |
| Coinbase Exchange | 현물 |
| Kraken | 현물, 선물 |
| KuCoin | 현물, 선물 |
| Gate.io | 현물, 선물 |
| Bitfinex | 현물, 파생상품 |
| Deepcoin | 현물, 무기한 |

### 전통적인 브로커

| 브로커 | 시장 | 플랫폼 |
|:------:|:--------|:---------|
| **Interactive Brokers (IBKR)** | 미국 주식, 홍콩 주식 | TWS / IB Gateway 🆕 |
| **MetaTrader 5 (MT5)** | 외환 | MT5 터미널 🆕 |

### 시장 데이터(CCXT 경유)

Bybit, Gate.io, Kraken, KuCoin, HTX 및 100개 이상의 기타 거래소가 시장 데이터용으로 지원됩니다.

---

### 다국어 지원

QuantDinger는 포괄적인 국제화를 통해 글로벌 사용자를 위해 구축되었습니다:

<p>
  <img src="https://img.shields.io/badge/🇺🇸_English-Supported-2563EB?style=flat-square" alt="English" />
  <img src="https://img.shields.io/badge/🇨🇳_简体中文-Supported-2563EB?style=flat-square" alt="Simplified Chinese" />
  <img src="https://img.shields.io/badge/🇹🇼_繁體中文-Supported-2563EB?style=flat-square" alt="Traditional Chinese" />
  <img src="https://img.shields.io/badge/🇯🇵_日本語-Supported-2563EB?style=flat-square" alt="Japanese" />
  <img src="https://img.shields.io/badge/🇰🇷_한국어-Supported-2563EB?style=flat-square" alt="Korean" />
  <img src="https://img.shields.io/badge/🇩🇪_Deutsch-Supported-2563EB?style=flat-square" alt="German" />
  <img src="https://img.shields.io/badge/🇫🇷_Français-Supported-2563EB?style=flat-square" alt="French" />
  <img src="https://img.shields.io/badge/🇹🇭_ไทย-Supported-2563EB?style=flat-square" alt="Thai" />
  <img src="https://img.shields.io/badge/🇻🇳_Tiếng_Việt-Supported-2563EB?style=flat-square" alt="Vietnamese" />
  <img src="https://img.shields.io/badge/🇸🇦_العربية-Supported-2563EB?style=flat-square" alt="Arabic" />
</p>

모든 UI 요소, 오류 메시지 및 문서는 완벽하게 번역되어 있습니다. 언어는 브라우저 설정에 따라 자동으로 감지되거나 앱에서 수동으로 전환할 수 있습니다.

---

### 지원되는 시장

| 시장 유형 | 데이터 소스 | 거래 |
|-------------|--------------|---------|
| **암호화폐** | Binance, OKX, Bitget, + 100 거래소 | ✅ 완전 지원 |
| **미국 주식** | Yahoo Finance, Finnhub, Tiingo | ✅ IBKR 경유 🆕 |
| **홍콩 주식** | AkShare, East Money | ✅ IBKR 경유 🆕 |
| **중국 주식(A주)** | AkShare, East Money | ⚡ 데이터만 |
| **외환** | Finnhub, OANDA | ✅ MT5 경유 🆕 |
| **선물** | 거래소 API, AkShare | ⚡ 데이터만 |

---

### 아키텍처 (현재 레포지토리)

```text
┌─────────────────────────────┐
│      quantdinger_vue         │
│   (Vue 2 + Ant Design Vue)   │
└──────────────┬──────────────┘
               │  HTTP (/api/*)
               ▼
┌─────────────────────────────┐
│     backend_api_python       │
│   (Flask + 전략 런타임)      │
└──────────────┬──────────────┘
               │
               ├─ SQLite (quantdinger.db)
               ├─ Redis (옵션 캐시)
               └─ 데이터 제공자 / LLMs / 거래소
```

---

### 레포지토리 구조

```text
.
├─ backend_api_python/         # Flask API + AI + 백테스트 + 전략 런타임
│  ├─ app/
│  ├─ env.example              # 로컬 구성을 위해 .env로 복사
│  ├─ requirements.txt
│  └─ run.py                   # 엔트리 포인트
└─ quantdinger_vue/            # Vue 2 UI (개발 서버는 /api를 백엔드로 프록시)
```

---

## 빠른 시작

### 옵션 1: Docker 배포 (권장)

QuantDinger를 실행하는 가장 빠른 방법입니다.

#### 1. 원클릭 시작

**Linux / macOS**
```bash
git clone https://github.com/brokermr810/QuantDinger.git && \
cd QuantDinger && \
cp backend_api_python/env.example backend_api_python/.env && \
docker-compose up -d --build
```

**Windows (PowerShell)**
```powershell
git clone https://github.com/brokermr810/QuantDinger.git
cd QuantDinger
Copy-Item backend_api_python\env.example -Destination backend_api_python\.env
docker-compose up -d --build
```

#### 2. 접속 및 구성

- **프론트엔드 UI**: http://localhost:8888
- **기본 계정**: `quantdinger` / `123456`

> **참고**: AI 기능이나 프로덕션 환경의 보안을 위해, `backend_api_python/.env`를 편집하여( `OPENROUTER_API_KEY` 추가, 비밀번호 변경) `docker-compose restart backend`로 서비스를 재시작하십시오.

#### 3. 애플리케이션 액세스

- **프론트엔드 UI**: http://localhost
- **백엔드 API**: http://localhost:5000

#### Docker 명령 참조

```bash
# 실행 상태 보기
docker-compose ps

# 로그 보기
docker-compose logs -f

# 서비스 중지
docker-compose down

# 볼륨 중지 및 제거 (경고: 데이터베이스가 삭제됩니다!)
docker-compose down -v
```

#### 데이터 지속성

다음 데이터는 호스트에 마운트되며 컨테이너 재시작 후에도 유지됩니다:

```yaml
volumes:
  - ./backend_api_python/logs:/app/logs                       # 로그
  - ./backend_api_python/data:/app/data                       # 데이터 디렉토리(quantdinger.db 포함)
  - ./backend_api_python/.env:/app/.env                       # 구성 파일
```

---

### 옵션 2: 로컬 개발

**전제 조건**
- Python 3.10+ 권장
- Node.js 16+ 권장

#### 1. 백엔드 시작 (Flask API)

```bash
cd backend_api_python
pip install -r requirements.txt
cp env.example .env   # Windows: copy env.example .env
python run.py
```

백엔드는 `http://localhost:5000`에서 사용할 수 있습니다.

#### 2. 프론트엔드 시작 (Vue UI)

```bash
cd quantdinger_vue
npm install
npm run serve
```

프론트엔드 개발 서버는 `http://localhost:8000`에서 실행되며 `/api/*`를 `http://localhost:5000`으로 프록시합니다.

---

### 구성 (.env)

`backend_api_python/env.example`을 템플릿으로 사용하십시오. 일반적인 설정은 다음과 같습니다:

- **인증**: `SECRET_KEY`, `ADMIN_USER`, `ADMIN_PASSWORD`
- **서버**: `PYTHON_API_HOST`, `PYTHON_API_PORT`, `PYTHON_API_DEBUG`
- **데이터베이스**: `DATABASE_URL` (PostgreSQL 연결 문자열)
- **AI / LLM**: `LLM_PROVIDER` (openrouter/openai/google/deepseek/grok), 각 제공자 API 키
- **OAuth**: `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`
- **보안**: `TURNSTILE_SITE_KEY`, `TURNSTILE_SECRET_KEY`, `ENABLE_REGISTRATION`
- **웹 검색**: `SEARCH_PROVIDER`, `SEARCH_GOOGLE_*`, `SEARCH_BING_API_KEY`
- **주문 실행**: `ORDER_MODE` (maker/market), `MAKER_WAIT_SEC`, `MAKER_OFFSET_BPS`
- **프록시 (옵션)**: `PROXY_PORT` 또는 `PROXY_URL`
- **백그라운드 서비스**: `ENABLE_PENDING_ORDER_WORKER`, `ENABLE_PORTFOLIO_MONITOR`

---

## 🤝 커뮤니티 및 지원

- **기여**: [기여 가이드](CONTRIBUTING.md) · [기여자](CONTRIBUTORS.md)
- **Telegram**: [QuantDinger 그룹](https://t.me/quantdinger)
- **Discord**: [서버 참여](https://discord.gg/vwJ8zxFh9Q)
- **📺 동영상 데모**: [프로젝트 소개](https://youtu.be/HPTVpqL7knM)
- **YouTube**: [@quantdinger](https://youtube.com/@quantdinger)
- **Email**: [brokermr810@gmail.com](mailto:brokermr810@gmail.com)
- **GitHub Issues**: [버그 신고 / 기능 요청](https://github.com/brokermr810/QuantDinger/issues)

---

## 💼 상용 라이선스 & 스폰서(Commercial License & Sponsorship)

QuantDinger의 코드는 **Apache License 2.0**으로 제공됩니다. 다만 **Apache 2.0은 상표권을 부여하지 않습니다**. QuantDinger의 이름/로고/브랜딩은 상표 및 브랜드 정책의 적용을 받으며(코드 라이선스와 별개):

- **저작권/표기**: LICENSE/NOTICE 등 필요한 저작권·라이선스 고지는 유지해야 합니다.
- **상표(이름/로고/브랜딩)**: QuantDinger의 이름/로고/브랜딩을 사용해 출처를 오인시키거나 보증(endorsement)을 암시해서는 안 됩니다. 수정 버전을 재배포할 때는 서면 허가가 없는 한 QuantDinger 브랜딩을 제거/대체해야 할 수 있습니다.

재배포물에서 QuantDinger 브랜딩을 **유지/수정**하고 싶다면(UI 로고 사용 포함) **상용 라이선스**를 문의해 주세요.

참고: `TRADEMARKS.md`

### 상용 라이선스로 제공되는 것

- 합의된 범위 내 **브랜딩/표시의 상용 허가**
- **운영 지원**: 배포, 업그레이드, 장애 대응, 유지보수 가이드
- **컨설팅**: 아키텍처 리뷰, 성능 튜닝, 전략 워크플로우 컨설팅
- **스폰서 옵션**: 스폰서로서 로고/광고 노출(README/웹사이트/앱 내 등 합의에 따름)

### 연락처

- **Telegram**: [QuantDinger Group](https://t.me/worldinbroker)
- **Email**: [brokermr810@gmail.com](mailto:brokermr810@gmail.com)

---

### 💝 직접 지원(기부)

귀하의 기여는 QuantDinger의 유지 및 개선에 도움이 됩니다.

**암호화폐 기부 (ERC-20 / BEP-20 / Polygon / Arbitrum)**

```
0x96fa4962181bea077f8c7240efe46afbe73641a7
```

<p>
  <img src="https://img.shields.io/badge/USDT-Accepted-26A17B?style=for-the-badge&logo=tether&logoColor=white" alt="USDT">
  <img src="https://img.shields.io/badge/ETH-Accepted-3C3C3D?style=for-the-badge&logo=ethereum&logoColor=white" alt="ETH">
</p>

---

### 🎓 지원 파트너

양적 금융 교육 및 연구를 발전시키는 학술 기관과 조직의 지원을 받게 되어 자랑스럽습니다.

<div align="center">
<table>
  <tr>
    <td align="center" width="50%">
      <a href="https://beinvolved.indiana.edu/organization/quantfiniu" target="_blank">
        <img src="docs/screenshots/qfs_logo.png" alt="인디애나 대학교 양적금융학회" width="280" style="border-radius: 8px;">
      </a>
      <br/><br/>
      <strong>양적금융학회 (QFS)</strong><br/>
      <small>인디애나 대학교 블루밍턴</small><br/>
      <small>차세대 양적 금융 전문가 양성</small>
    </td>
  </tr>
</table>
</div>

> 💡 **지원 파트너가 되는 데 관심이 있으신가요?** 대학, 연구 기관 및 조직과의 협력을 환영합니다. [brokermr810@gmail.com](mailto:brokermr810@gmail.com) 또는 [Telegram](https://t.me/worldinbroker)으로 연락주세요.

---

### 감사의 말

QuantDinger는 Flask, Pandas, CCXT, Vue.js, Ant Design Vue, KlineCharts 등과 같은 훌륭한 오픈 소스 프로젝트의 어깨 위에 서 있습니다.

모든 관리자와 기여자에게 감사드립니다! ❤️