chart-0714/README.md

Professional trading chart library with advanced customization for trading journal apps

# chart-0714 차트 라이브러리

## 개요

chart-0714는 lightweight-charts의 한계를 극복하기 위해 개발된 WebGL 기반의 고성능 금융 차트 라이브러리입니다. 특히 드로잉 기능과 멀티패널을 지원하며, 트레이딩 저널 애플리케이션에 특화된 기능들을 제공합니다.

## 주요 특징

- **WebGL 기반 고성능 렌더링**: 수십만 개의 캔들 데이터 처리 가능
- **완전한 드로잉 도구 지원**: 트렌드라인, 도형, 텍스트, 마커 등
- **멀티패널 레이아웃**: 가격 차트와 볼륨 차트의 분리된 패널
- **OHLC 스냅 기능**: Ctrl 키로 가격에 자동 스냅
- **플러그인 시스템**: 커스텀 인디케이터 확장 가능
- **React 통합 지원**: React 컴포넌트 및 훅 제공
- **완전한 TypeScript 지원**: 타입 안정성 보장

## 설치 및 사용

### 설치
```bash
npm install chart-0714
```

### 기본 사용법
```typescript
import { createChart } from 'chart-0714';

const chart = createChart('container-id', {
  width: 800,
  height: 600,
  theme: 'dark'
});

// 데이터 설정
chart.setData(candleData);
```

### React에서 사용
```tsx
import { ChartComponent } from 'chart-0714/react';

function TradingChart() {
  return (
    <ChartComponent
      data={candleData}
      options={{
        theme: 'dark',
        showVolume: true
      }}
    />
  );
}
```

## 프로젝트 구조

```
chart-0714/
├── src/
│   ├── core/               # 핵심 차트 로직
│   │   ├── Chart.ts        # 메인 차트 클래스
│   │   ├── ChartPanel.ts   # 패널 기반 클래스
│   │   ├── DataManager.ts  # 데이터 관리
│   │   ├── DrawingManager.ts # 드로잉 도구 관리
│   │   ├── IndicatorManager.ts # 인디케이터 관리
│   │   ├── LineSeriesManager.ts # 라인 시리즈 관리
│   │   ├── MarkerManager.ts # 마커 관리
│   │   ├── PanelManager.ts # 멀티 패널 관리
│   │   ├── WebGLRenderer.ts # WebGL 렌더링 엔진
│   │   ├── chart/          # 차트 컨트롤러들
│   │   └── drawing/        # 드로잉 관련 매니저들
│   ├── indicators/         # 인디케이터 구현
│   ├── panels/            # 패널 타입 (MainChart, Volume)
│   ├── plugins/           # 플러그인 시스템
│   ├── react-integration/ # React 통합
│   ├── renderers/        # 렌더러들 (Candle, Volume, Grid 등)
│   ├── shaders/          # WebGL 쉐이더 (GLSL)
│   ├── types/            # TypeScript 타입 정의
│   ├── ui/               # UI 컴포넌트들
│   └── utils/            # 유틸리티 함수들
├── dist/                 # 빌드 결과물
├── docs/                 # 문서들
├── examples/             # 예제 파일들
└── package.json          # 프로젝트 설정
```

## 아키텍처

### 핵심 컴포넌트

#### 1. Chart 클래스
- 차트의 메인 진입점
- 모든 매니저들을 조율하는 중앙 컨트롤러
- 생명주기 관리 (초기화, 업데이트, 정리)
- 이벤트 처리 및 UI 컨트롤

#### 2. 매니저 시스템
- **DataManager**: 캔들 데이터를 TypedArray로 효율적 관리
- **DrawingManager**: 드로잉 도구의 생성, 수정, 삭제 관리
- **IndicatorManager**: 기술적 지표의 계산 및 렌더링
- **PanelManager**: 멀티 패널 레이아웃 및 리사이징
- **MarkerManager**: 차트 위 마커 및 주석 관리
- **LineSeriesManager**: 추가적인 라인 차트 관리

#### 3. 렌더링 시스템
- **WebGLRenderer**: WebGL 컨텍스트 관리 및 렌더링 파이프라인
- **전용 쉐이더**: GLSL로 작성된 최적화된 쉐이더
  - `candle.vert/frag`: 캔들스틱 렌더링
  - `line.vert/frag`: 라인 렌더링
  - `volume.vert/frag`: 볼륨 바 렌더링
- **특화 렌더러**: 각 차트 요소별 전문 렌더러

### 드로잉 시스템

#### DrawingManager 하위 시스템
- **DrawingSnapManager**: OHLC 가격에 자동 스냅 기능
- **DrawingMeasureManager**: 가격/시간 측정 도구
- **DrawingObjectManager**: 드로잉 객체 생명주기 관리
- **DrawingStateManager**: 실행 취소/재실행 기능
- **DrawingInteractionManager**: 마우스/키보드 상호작용

#### 지원 드로잉 도구
- 트렌드라인 (TrendLine)
- 수평선 (HorizontalLine)
- 수직선 (VerticalLine)
- 사각형 (Rectangle)
- 원 (Circle)
- 텍스트 (Text)
- 마커 (Marker)
- 피보나치 리트레이스먼트
- 측정 도구

### 멀티패널 시스템

#### PanelManager 기능
- 메인 차트 패널과 볼륨 패널의 독립적 관리
- 패널 간 동기화된 스크롤 및 줌
- 드래그 가능한 리사이저로 패널 크기 조정
- 패널별 독립적인 Y축 스케일

#### 패널 타입
- **MainChartPanel**: 가격 차트 (캔들스틱, 라인)
- **VolumePanel**: 거래량 차트
- 확장 가능한 커스텀 패널 지원

## API 레퍼런스

### Chart 생성 옵션
```typescript
interface ChartOptions {
  width?: number;
  height?: number;
  theme?: 'light' | 'dark' | Theme;
  locale?: string;
  showVolume?: boolean;
  showHeader?: boolean;
  showSettings?: boolean;
  keyboardShortcuts?: boolean;
  snapToOHLC?: boolean;
  plugins?: Plugin[];
}
```

### 데이터 구조
```typescript
interface Candle {
  time: number;  // Unix timestamp
  open: number;
  high: number;
  low: number;
  close: number;
  volume: number;
}
```

### 이벤트 시스템
```typescript
chart.on('ready', () => {
  console.log('차트 준비 완료');
});

chart.on('dataUpdate', (data) => {
  console.log('데이터 업데이트됨');
});

chart.on('drawingCreated', (drawing) => {
  console.log('드로잉 생성됨', drawing);
});
```

### 주요 메서드
```typescript
// 데이터 관련
chart.setData(candles: Candle[]);
chart.updateData(candles: Candle[]);
chart.appendData(candle: Candle);

// 드로잉 관련
chart.activateDrawingTool('trendline');
chart.removeDrawing(drawingId: string);
chart.clearAllDrawings();

// 인디케이터
chart.addIndicator('MA', { period: 20 });
chart.removeIndicator(indicatorId: string);

// 뷰포트 컨트롤
chart.fitContent();
chart.zoomIn();
chart.zoomOut();
chart.scrollTo(time: number);
```

## 테마 시스템

### 내장 테마
- **Light Theme**: 밝은 배경의 기본 테마
- **Dark Theme**: 어두운 배경의 테마

### 커스텀 테마
```typescript
const customTheme: Theme = {
  background: '#1a1a1a',
  text: '#ffffff',
  grid: '#333333',
  candle: {
    upColor: '#26a69a',
    downColor: '#ef5350',
    wickColor: '#999999'
  },
  volume: {
    upColor: '#26a69a80',
    downColor: '#ef535080'
  },
  drawing: {
    lineColor: '#2196f3',
    fillColor: '#2196f330'
  }
};
```

## 플러그인 시스템

### MA Cluster 플러그인 예제
```typescript
import { MAClusterPlugin } from 'chart-0714/plugins';

const chart = createChart('container', {
  plugins: [
    new MAClusterPlugin({
      clusters: [
        { periods: [5, 10, 20], color: '#ff0000' },
        { periods: [50, 100, 200], color: '#0000ff' }
      ]
    })
  ]
});
```

## 성능 최적화

### WebGL 렌더링 최적화
- Vertex Buffer Object (VBO) 사용으로 메모리 효율성 극대화
- Instanced rendering으로 대량 객체 렌더링
- Frustum culling으로 뷰포트 외부 객체 제외
- Level of Detail (LOD) 시스템으로 줌 레벨별 최적화

### 데이터 처리 최적화
- TypedArray 사용으로 메모리 사용량 감소
- Binary search로 빠른 데이터 검색
- 증분 업데이트로 불필요한 재계산 방지
- Web Worker 활용한 병렬 처리 (계획 중)

## 빌드 및 개발

### 개발 환경 설정
```bash
# 의존성 설치
npm install

# 개발 서버 실행
npm run dev

# 빌드
npm run build

# 타입 체크
npm run type-check
```

### 빌드 설정
- **빌드 도구**: Vite
- **타겟**: ES2022
- **모듈 시스템**: ES Modules
- **출력 형식**: ESM, CJS, TypeScript 정의

## 문제 해결 가이드

### 일반적인 문제

#### 1. 차트가 렌더링되지 않음
- 컨테이너 엘리먼트의 크기 확인
- WebGL 지원 브라우저 확인
- 콘솔 에러 메시지 확인

#### 2. 드로잉이 저장되지 않음
- DrawingStateManager 초기화 확인
- 로컬 스토리지 권한 확인

#### 3. 성능 문제
- 데이터 양 확인 (10만 개 이상 시 샘플링 고려)
- 불필요한 인디케이터 제거
- Chrome DevTools Performance 탭 활용

## 로드맵

### v2.0 계획
- [ ] Web Worker를 활용한 백그라운드 계산
- [ ] 더 많은 인디케이터 추가
- [ ] 실시간 데이터 스트리밍 최적화
- [ ] 모바일 터치 제스처 개선
- [ ] 서버 사이드 렌더링 지원

### v3.0 비전
- [ ] 3D 차트 뷰
- [ ] AI 기반 패턴 인식
- [ ] 다중 차트 동기화
- [ ] 클라우드 저장소 통합

## 라이선스

MIT License

## 기여 가이드

프로젝트에 기여하고 싶으시다면:
1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

## 지원

- 이슈 트래커: GitHub Issues
- 문서: `/docs` 디렉토리
- 예제: `/examples` 디렉토리