KIS Trader - 다중 계좌 자동매매 플랫폼

한국투자증권 API를 활용한 Monorepo 기반 자동매매 플랫폼

🎯 프로젝트 개요

다중 계좌 관리, 전략 기반 자동매매, 실시간 데이터 수집 및 분석 기능을 제공하는 프로페셔널 트레이딩 플랫폼입니다.

주요 특징

• ✅ 다중 계좌 관리: AES-256-GCM 암호화된 Credentials, 1일 1토큰 자동 관리
• ✅ Monorepo 구조: pnpm workspace 기반 효율적 코드 공유
• ✅ 마이크로서비스: account-service, trade-engine, data-center, strategy-manager
• ✅ 비동기 주문 처리: Bull Queue 기반 안정적 주문 실행
• ✅ 실시간 데이터 수집: node-cron 스케줄러, KIS API 통합
• ✅ Podman 기반 배포: PostgreSQL, Redis, Prometheus, Grafana
• ✅ API 문서: Swagger UI 자동 생성 (Phase 23)
• ✅ 운영 매뉴얼: 배포, 모니터링, 장애 대응 가이드 (Phase 23)
• ✅ 보안 강화: OWASP Top 10 대응 98% (Phase 20-23)

📚 문서

• 빠른 시작 가이드 - 시나리오별 사용법 (⭐ 추천)
• Watchlist 시스템 - 관심종목 관리 및 데이터 수집 (2025-12-15)
• API 문서 - Swagger UI (Phase 23)
• 운영 매뉴얼 - 배포, 모니터링, 장애 대응 (Phase 23)
• 보안 체크리스트 - OWASP Top 10 대응 현황 (Phase 23)
• 프로덕션 체크리스트 - Go-Live 준비 (Phase 23)
• 완료 보고서 - Phase별 작업 내역 (Phase 1-23)
• 다중 계좌 가이드 - 다중 계좌 설정 (Phase 1-5)
• 다중 계좌 구현 계획 - 아키텍처 설계 (Phase 1-5)

🏗️ 시스템 아키텍처

┌─────────────────────────────────────────────────────────────┐
│                    Frontend (Next.js)                        │
│  - 계좌 대시보드                                            │
│  - 전략 관리 UI                                             │
│  - 실시간 차트                                              │
└────────────────────┬────────────────────────────────────────┘
                     │
┌────────────────────┴────────────────────────────────────────┐
│                   서비스 레이어                              │
├─────────────────┬─────────────────┬────────────────────────┤
│ account-service │ trade-engine    │ data-center            │
│ (계좌 CRUD)     │ (주문 Queue)    │ (데이터 수집)          │
├─────────────────┴─────────────────┴────────────────────────┤
│ strategy-manager (전략 실행)                                │
└────────────────────┬────────────────────────────────────────┘
                     │
┌────────────────────┴────────────────────────────────────────┐
│              KIS API Client (공통 패키지)                    │
│  - MultiAccountAPIGateway                                    │
│  - DomesticStockAPI / OverseasStockAPI                       │
│  - TokenManager (Redis 기반 1일1토큰)                        │
└────────────────────┬────────────────────────────────────────┘
                     │
┌────────────────────┴────────────────────────────────────────┐
│                 Database Layer                               │
│  PostgreSQL (계좌, 전략, 거래 로그)                         │
│  Redis (토큰 캐시, Queue)                                   │
│  TimescaleDB (시계열 데이터)                                │
└──────────────────────────────────────────────────────────────┘

핵심 기능

1. 다중 계좌 관리

• AES-256-GCM 암호화된 Credentials 저장
• 1일 1토큰 제약 자동 관리 (Redis Lock)
• 계좌별 독립적인 API 호출

2. 주문 실행 엔진

• Bull Queue 기반 비동기 처리
• 재시도 로직 (Exponential Backoff)
• 주문 상태 추적 및 로깅

3. 데이터 수집

• node-cron 스케줄러
• Watchlist 기반 자동 수집 (JSON 관리)
• 국내/해외 주식 현재가, 일봉 수집
• 잔고 자동 동기화

4. 전략 관리

• 플러그인 기반 전략 등록
• 사용자별 전략 활성화/비활성화
• 백테스팅 지원 (예정)

🛠️ 기술 스택

Backend

• Runtime: Node.js 20+ (TypeScript 5.2+)
• Framework: Express 4.18
• Queue: Bull 4.12 + ioredis 5.3
• Database ORM: pg (PostgreSQL driver)
• Validation: Zod 3.22
• Logger: Winston 3.11
• Scheduler: node-cron 3.0

Frontend

• Framework: Next.js 14+ (예정)
• UI: TailwindCSS, shadcn/ui
• Charts: Recharts, TradingView

Database

• Relational: PostgreSQL 16+
• Time-Series: TimescaleDB
• Cache: Redis 7+

DevOps

• Container: Podman, Podman Compose
• Monitoring: Grafana, Prometheus
• Logging: Winston (파일 기반)

📦 주요 패키지

@packages/shared-types

• 프로젝트 전체 TypeScript 타입 정의
• Account, OrderRequest, Position, Strategy 등

@packages/config

• Zod 스키마 기반 환경 변수 검증
• 런타임 설정 관리

@packages/logger

• Winston 기반 커스텀 로거
• 로그 레벨: TRADE, SIGNAL, ORDER, POSITION, BALANCE, ERROR

@packages/database

• PostgreSQL 연결 풀 관리
• Repository 패턴 (Account, User, Strategy, TradeLog)
• AES-256-GCM 암호화 서비스

@packages/kis-api-client

• KIS API 완벽 래핑
• MultiAccountAPIGateway: 다중 계좌 오케스트레이션
• DomesticStockAPI: 국내 주식 매매
• OverseasStockAPI: 해외 주식 매매
• MultiAccountTokenManager: Redis 기반 토큰 관리

📁 프로젝트 구조

kis-trader/
├── packages/                  # 공통 패키지
│   ├── shared-types/         # TypeScript 타입 정의
│   ├── config/               # 환경 설정 (Zod validation)
│   ├── logger/               # Winston 기반 로거
│   ├── database/             # PostgreSQL 연결 및 Repository
│   └── kis-api-client/       # KIS API 클라이언트
│
├── services/                  # 마이크로서비스
│   ├── account-service/      # 계좌 관리 API (포트: 3001)
│   ├── trade-engine/         # 주문 실행 엔진 (포트: 3002, Bull Queue)
│   ├── data-center/          # 데이터 수집 (포트: 3003, node-cron)
│   ├── strategy-manager/     # 전략 관리 및 실행 (포트: 3004)
│   └── user-service/         # 사용자 인증 및 권한
│
├── apps/                      # Frontend 애플리케이션
│   ├── web/                  # Next.js 웹 대시보드
│   └── admin/                # 관리자 패널
│
├── infrastructure/            # 인프라 설정
│   ├── docker/               # Dockerfile
│   ├── kubernetes/           # K8s manifests (optional)
│   └── monitoring/           # Prometheus, Grafana
│
├── docs/                      # 문서
│   ├── api-design.md
│   ├── database-schema.md
│   └── strategy-development.md
│
├── docker-compose.yml         # 로컬 개발 환경
├── pnpm-workspace.yaml        # pnpm 워크스페이스
└── tsconfig.base.json         # 공통 TypeScript 설정

🔧 환경 변수 관리

📂 파일 구조

• .env.example: 템플릿 (Git 추적 ✅)
• .env.local: 로컬 개발용 (Git 무시 🔒)
• .env.docker: Docker 환경용 (Git 무시 🔒)

초기 설정 (최초 1회)

# 1. 템플릿 복사
cp .env.example .env.local
cp .env.example .env.docker
cp docker-compose.yml.example docker-compose.yml

# 2. 보안 키 생성
openssl rand -hex 32  # ENCRYPTION_KEY (두 파일 모두 동일하게 설정)
openssl rand -hex 32  # JWT_SECRET (두 파일 모두 동일하게 설정)

# 3. docker-compose.yml 수정
# 모든 CHANGE_ME를 실제 값으로 변경:
# - DB 비밀번호
# - Redis 비밀번호
# - ENCRYPTION_KEY (위에서 생성한 값)
# - JWT_SECRET (위에서 생성한 값)
# - Grafana 관리자 비밀번호

# 4. .env.docker 수정 (Docker 전용 설정)
# DB_HOST=postgres      (Docker 서비스 이름)
# REDIS_HOST=redis      (Docker 서비스 이름)
# NODE_ENV=production
# DOCKER_ENV=true

⚠️ 보안 주의사항

절대 Git에 커밋하지 말 것:

• docker-compose.yml (실제 비밀번호 포함)
• .env.local, .env.docker (환경 변수)
• accounts.json (계좌 Credentials)

Git에 안전하게 커밋 가능:

• docker-compose.yml.example (템플릿)
• .env.example (템플릿)
• accounts.example.json (템플릿)

주요 환경 변수

변수	로컬 개발	Docker 환경
NODE_ENV	development	production
DOCKER_ENV	false	true
DB_HOST	localhost	postgres
REDIS_HOST	localhost	redis
ENCRYPTION_KEY	동일 (32바이트 hex)	동일
JWT_SECRET	동일 (32바이트 hex)	동일

⚠️ 주의: ENCRYPTION_KEY는 절대 변경하지 마세요! (기존 데이터 복호화 불가)

---

🚀 빠른 시작 (자동화)

📖 상세 가이드: QUICK_START.md에서 시나리오별 사용법을 확인하세요!

시장 선택 설정

Makefile 상단에서 원하는 시장만 활성화할 수 있습니다:

# 기본 시장: 미국 (Default market: US)
# STRATEGY_SERVICES := strategy-kr      # 🇰🇷 한국 (KRX) - 포트 3011
STRATEGY_SERVICES := strategy-us      # 🇺🇸 미국 (NYSE/NASDAQ) - 포트 3012
# STRATEGY_SERVICES += strategy-jp      # 🇯🇵 일본 (TSE) - 포트 3013
# STRATEGY_SERVICES += strategy-cn      # 🇨🇳 중국 (SSE/SZSE) - 포트 3014

# 예제: 한국 시장 추가
# STRATEGY_SERVICES := strategy-us
# STRATEGY_SERVICES += strategy-kr      # 한국 시장 추가

# 예제: 모든 시장 활성화
# STRATEGY_SERVICES := strategy-kr
# STRATEGY_SERVICES += strategy-us
# STRATEGY_SERVICES += strategy-jp
# STRATEGY_SERVICES += strategy-cn

💡 Tip: 필요없는 시장은 앞에 #을 붙여 주석 처리하면 됩니다.

방법 1: Makefile 사용 (추천)

# 1. 전체 초기 설정 (최초 1회)
make setup

# 2. 과거 데이터 수집 (분석 및 지표 계산용)
make backfill              # 최근 30일, 5분봉 데이터 수집

# 3. 서비스 상태 확인
make status

# 4. 로그 확인
make logs                  # 모든 서비스
make logs-strategy-us      # 미국 시장 (기본)
make logs-strategy-kr      # 한국 시장
make logs-strategy-jp      # 일본 시장
make logs-strategy-cn      # 중국 시장

# 4. 서비스 중지
make stop

# 5. 서비스 재시작
make restart

# 도움말 보기
make help

방법 2: npm 스크립트 사용

# 1. 전체 초기 설정 (최초 1회)
pnpm run setup

# 2. 서비스 시작
pnpm run start

# 3. 서비스 상태 확인
pnpm run status

# 4. 로그 확인
pnpm run logs

# 5. 서비스 중지
pnpm run stop

방법 3: Docker Compose 직접 사용

# 1. 인프라 시작
docker-compose up -d postgres redis timescaledb adminer

# 2. DB 초기화 (계좌 import)
docker-compose up db-init

# 3. 애플리케이션 서비스 시작
docker-compose up -d account-service trade-engine data-center strategy-kr

# 4. 상태 확인
docker-compose ps

---

🔑 기본 관리자 계정

초기화 후 자동으로 생성되는 기본 관리자 계정:

Email: isoopd@gmail.com
Password: isootiger123!

⚠️ 프로덕션 환경에서는 반드시 비밀번호를 변경하세요!

---

🌐 서비스 접속 정보

서비스	포트	URL	용도
Account Service	3001	http://localhost:3001	계좌 관리 API
Trade Engine	3002	http://localhost:3002	주문 실행 엔진
Data Center	3003	http://localhost:3003	데이터 수집
Strategy KR	3011	http://localhost:3011	한국 시장 전략
Adminer	8080	http://localhost:8080	DB 관리 UI
PostgreSQL	5432	localhost:5432	메인 DB
Redis	6379	localhost:6379	캐시 & Queue

Health Check

# 모든 서비스 상태 확인
curl http://localhost:3001/health
curl http://localhost:3002/health
curl http://localhost:3003/health
curl http://localhost:3011/health

---

✅ 현재 완료 상태 (2024-12-15)

• ✅ Docker 인프라 실행 완료 (PostgreSQL, Redis, TimescaleDB, Adminer)
• ✅ 데이터베이스 스키마 자동 초기화 완료 (15개 테이블)
• ✅ 계좌 데이터 자동 import 완료 (accounts.json → DB)
• ✅ 기본 관리자 계정 자동 생성
• ✅ 4개 마이크로서비스 실행 완료

---

📋 Step-by-Step 가이드 (수동 설정)

Step 1: 사전 준비 확인 (1분)

# Node.js & pnpm 버전 확인
node -v  # v18.0.0 이상
pnpm -v  # 8.0.0 이상

# Docker 확인
docker --version
docker-compose --version  # 또는 docker compose version

Step 2: 프로젝트 설정 (2분)

# 1. 의존성 설치
pnpm install

# 2. 환경 파일 생성 (위 '환경 변수 관리' 섹션 참고)
cp .env.example .env.local
cp .env.example .env.docker
# 보안 키 생성 및 설정

# 3. 계좌 정보 확인 (accounts.json)
cat accounts.json

중요: .env.local, .env.docker, accounts.json 파일이 올바르게 설정되어 있는지 확인하세요.

Step 3: Docker 인프라 실행 (1분)

# PostgreSQL, Redis, Adminer 실행
docker-compose up -d postgres redis adminer

# 또는 alias 사용 (더 간편)
dc up -d postgres redis adminer

자동으로 실행되는 작업:

• ✅ PostgreSQL 17 컨테이너 시작
• ✅ Redis 7.4 컨테이너 시작
• ✅ Adminer 5.4.1 컨테이너 시작
• ✅ 스키마 자동 초기화 (init.sql 마운트로 13개 테이블 자동 생성)

상태 확인:

# 컨테이너 상태 확인
docker-compose ps
# 또는
dps

# 예상 결과:
# kis-trader-postgres    (healthy)
# kis-trader-redis       (healthy)
# kis-trader-adminer     (running)

Step 4: 계좌 데이터 임포트 (1분)

# accounts.json 데이터를 DB로 임포트
pnpm run import-accounts

예상 출력:

[INFO] Starting account import...
[INFO] Found 1 accounts in accounts.json
[INFO] Importing account: 모의투자 메인 (50144074-01)
[INFO] ✅ Account imported successfully: 모의투자 메인
[INFO] Total accounts in DB: 1

Step 5: Adminer로 확인 (1분)

# 브라우저에서 Adminer 접속
open http://localhost:8080

로그인 정보:

시스템: PostgreSQL
서버: postgres
사용자: isoopd
비밀번호: isootiger123!
데이터베이스: kis_trader_db

확인 사항:

• ✅ 왼쪽 메뉴에 13개 테이블 확인
• ✅ accounts 테이블 클릭 → 계좌 정보 확인
• ✅ encrypted_app_key, encrypted_app_secret 필드에 암호화된 데이터 확인

SQL로 확인:

SELECT id, account_name, account_number, account_type, is_active, created_at
FROM accounts;

---

🎯 다음 단계

Phase 6: 패키지 빌드 (예정 - 5분)

공통 패키지를 순서대로 빌드:

# 순서가 중요합니다! (의존성 순서)

# 1. shared-types (모든 패키지의 기반)
cd packages/shared-types
pnpm build
cd ../..

# 2. config
cd packages/config
pnpm build
cd ../..

# 3. logger
cd packages/logger
pnpm build
cd ../..

# 4. database
cd packages/database
pnpm build
cd ../..

# 5. kis-api-client
cd packages/kis-api-client
pnpm build
cd ../..

빌드 확인:

# 모든 패키지에 dist 폴더가 생성되었는지 확인
ls -la packages/shared-types/dist
ls -la packages/config/dist
ls -la packages/logger/dist
ls -la packages/database/dist
ls -la packages/kis-api-client/dist

---

Phase 7: 서비스 로컬 실행 테스트 (예정 - 10분)

각 서비스를 개별적으로 로컬에서 실행하여 테스트:

7.1 Account Service

# 터미널 1
cd services/account-service
pnpm dev

# 다른 터미널에서 Health Check
curl http://localhost:3001/health
# 예상: {"status":"ok"}

7.2 Trade Engine

# 터미널 2
cd services/trade-engine
pnpm dev

curl http://localhost:3002/health

7.3 Data Center

# 터미널 3
cd services/data-center
pnpm dev

curl http://localhost:3003/health

7.4 Strategy Manager

# 터미널 4
cd services/strategy-manager
pnpm dev

curl http://localhost:3004/health

전체 Health Check

# 모든 서비스가 실행 중인지 확인
for port in 3001 3002 3003 3004; do
  echo "Checking port $port..."
  curl http://localhost:$port/health
done

---

Phase 8: Docker 전체 실행 (예정 - 5분)

로컬 테스트가 성공하면 Docker로 전체 실행:

# 1. 로컬에서 실행 중인 서비스 모두 중지 (Ctrl+C)

# 2. Docker Compose로 전체 빌드 및 실행
docker-compose up -d --build

# 또는
dc up -d --build

실행되는 컨테이너 (총 9개):

1. kis-trader-postgres       (PostgreSQL 17)
2. kis-trader-redis          (Redis 7.4)
3. kis-trader-timescaledb    (시계열 데이터)
4. kis-trader-adminer        (DB 관리)
5. kis-trader-account-service
6. kis-trader-trade-engine
7. kis-trader-data-center
8. kis-trader-strategy-kr    (한국 시장)
9. kis-trader-strategy-us    (미국 시장)

상태 확인:

# 전체 컨테이너 상태
docker-compose ps

# 로그 실시간 모니터링
docker-compose logs -f

# 특정 서비스 로그
docker-compose logs -f strategy-kr

---

📊 모니터링 & 관리

Adminer (데이터베이스 관리)

URL: http://localhost:8080
서버: postgres
사용자: isoopd
비밀번호: isootiger123!
데이터베이스: kis_trader_db

추천 북마크 URL:

http://localhost:8080/?pgsql=postgres&username=isoopd&db=kis_trader_db

→ 비밀번호만 입력하면 바로 로그인!

Grafana (대시보드 - 향후 설정)

URL: http://localhost:3000
사용자: admin
비밀번호: admin

Prometheus (메트릭 - 향후 설정)

URL: http://localhost:9090

---

🔧 트러블슈팅

문제 1: Docker 컨테이너가 시작되지 않음

# 로그 확인
docker-compose logs [service-name]

# 특정 컨테이너 재시작
docker-compose restart [service-name]

# 전체 재시작
docker-compose down
docker-compose up -d

문제 2: 포트 충돌

# 사용 중인 포트 확인
lsof -i :5432  # PostgreSQL
lsof -i :6379  # Redis  
lsof -i :8080  # Adminer

# 프로세스 종료
kill -9 <PID>

문제 3: 스키마가 적용되지 않음

# 컨테이너 완전 재시작 (볼륨 포함)
docker-compose down -v
docker-compose up -d postgres redis adminer

# init.sql이 자동으로 실행됩니다

문제 4: 계좌 임포트 실패

# 환경 변수 확인
cat .env | grep -E "DB_|ENCRYPTION"

# accounts.json 파일 확인
cat accounts.json

# 데이터베이스 연결 테스트
psql -h localhost -U isoopd -d kis_trader_db -c "SELECT version();"

문제 5: 패키지 빌드 에러

# node_modules 전체 재설치
rm -rf node_modules
rm -rf packages/*/node_modules
rm -rf services/*/node_modules
pnpm install

# 패키지 순서대로 다시 빌드
cd packages/shared-types && pnpm build
cd ../config && pnpm build
# ... (순서대로)

---

🎯 핵심 명령어 모음

# === 인프라 관리 ===
dc up -d postgres redis adminer    # 인프라만 시작
dc up -d --build                   # 전체 서비스 시작
dc down                            # 전체 종료
dc down -v                         # 볼륨 포함 전체 삭제
dps                                # 상태 확인
dc logs -f                         # 로그 확인

# === 데이터 백필 (Historical Data) ===
make backfill                      # 🔥 과거 30일 데이터 수집 (5분봉)
make backfill-30d                  # 최근 30일 데이터 (5분봉)
make backfill-3mo                  # 최근 3개월 데이터 (1시간봉)
make backfill-1y                   # 최근 1년 데이터 (1일봉)

# === 데이터베이스 ===
pnpm run import-accounts           # 계좌 임포트
open http://localhost:8080         # Adminer 접속

# === 패키지 빌드 ===
cd packages/shared-types && pnpm build
cd packages/config && pnpm build
cd packages/logger && pnpm build
cd packages/database && pnpm build
cd packages/kis-api-client && pnpm build

# === 서비스 테스트 ===
cd services/account-service && pnpm dev
curl http://localhost:3001/health

# === 백업 ===
bash scripts/backup-volumes.sh     # 전체 백업
bash scripts/restore-volumes.sh 20241210  # 복구

---

✅ 완료 체크리스트

초기 설정

• Node.js & pnpm 설치
• Docker 설치
• pnpm install 완료
• .env 파일 설정
• accounts.json 파일 작성

인프라 (완료)

• PostgreSQL 컨테이너 실행 (healthy)
• Redis 컨테이너 실행 (healthy)
• Adminer 접속 가능
• 스키마 자동 적용 (13개 테이블)
• 계좌 임포트 완료

다음 단계 (예정)

• 패키지 빌드 (5개)
• account-service 로컬 테스트
• trade-engine 로컬 테스트
• data-center 로컬 테스트
• strategy-manager 로컬 테스트
• Docker 전체 실행
• Grafana 대시보드 설정
• 모니터링 알림 설정

---

4. 인프라 실행

# PostgreSQL, Redis, Grafana 등 실행
docker-compose up -d postgres redis prometheus grafana

# 데이터베이스 스키마 초기화
docker exec -i kis-postgres psql -U postgres -d kis_trading < packages/database/src/schema.sql

5. 서비스 실행

# 개발 모드 (각 서비스 디렉토리에서)
cd services/account-service && pnpm dev
cd services/trade-engine && pnpm dev
cd services/data-center && pnpm dev
cd services/strategy-manager && pnpm dev

# 또는 Docker Compose로 전체 실행
docker-compose up --build

6. 접속 확인

# 서비스 Health Check
curl http://localhost:3001/health  # account-service
curl http://localhost:3002/health  # trade-engine
curl http://localhost:3003/health  # data-center
curl http://localhost:3004/health  # strategy-manager

# Grafana 대시보드
open http://localhost:3000  # admin/admin

🔐 보안

Credentials 관리

• 절대 환경 변수에 저장하지 않음
• PostgreSQL에 AES-256-GCM 암호화하여 저장
• ENCRYPTION_KEY 환경 변수로 암호화 키 관리

KIS API 토큰 정책

• 1일 1토큰 발급 제한
• Redis Lock으로 동시 발급 방지
• kis_token_issued:{accountId}:{YYYYMMDD} 키로 발급 이력 추적

JWT 인증

• account-service API는 JWT 토큰 필수
• Authorization: Bearer <token> 헤더

📊 모니터링

Grafana 대시보드

• URL: http://localhost:3000
• 계정: admin/admin
• Prometheus 데이터소스 자동 연결

Prometheus 메트릭

• URL: http://localhost:9090
• 각 서비스 health check 엔드포인트 모니터링

로그

• 파일: logs/combined.log, logs/error.log
• Docker: docker logs <container-name>

📝 개발 가이드

새로운 전략 추가

1. services/strategy-manager/src/strategies/ 디렉토리에 전략 파일 생성
2. IStrategy 인터페이스 구현
3. StrategyEngine.registerStrategy()로 등록

예시:

import { IStrategy } from './base.strategy';

export class MyStrategy implements IStrategy {
  name = 'My Custom Strategy';
  description = '전략 설명';

  async execute(accountId: string, symbol: string, marketData: any) {
    // 전략 로직
    if (/* 매수 조건 */) {
      return {
        symbol,
        orderType: 'buy' as const,
        quantity: 10,
        price: marketData.currentPrice,
        orderMethod: 'limit' as const,
      };
    }
    return null;
  }
}

API 엔드포인트 추가

• 각 서비스의 src/routes/ 디렉토리에 라우터 추가
• Controller 패턴 사용

🛠️ 트러블슈팅

TypeScript 에러

• 의존성 미설치: pnpm install
• tsconfig 참조 에러: tsconfig.base.json 확인

Docker 에러

# 컨테이너 재시작
docker-compose down
docker-compose up -d

# 볼륨 초기화 (주의: 데이터 삭제됨)
docker-compose down -v

KIS API 에러

• 토큰 만료: Redis 키 kis_token:{accountId} 삭제 후 재발급
• Rate Limit: SimpleRateLimiter 설정 조정

📝 로드맵

✅ Phase 1: 공통 타입 및 설정 (완료)

• shared-types 패키지
• config 패키지 (Zod validation)
• logger 패키지 (Winston)

✅ Phase 2: 데이터베이스 레이어 (완료)

• PostgreSQL 스키마 (10개 테이블)
• EncryptionService (AES-256-GCM)
• DatabaseManager (연결 풀)
• Repository 패턴 (Account, User, Strategy, TradeLog)

✅ Phase 3: KIS API 클라이언트 (완료)

• MultiAccountTokenManager (1일1토큰 제약)
• KISApiClient (Rate Limiting, 재시도)
• DomesticStockAPI (국내 주식)
• OverseasStockAPI (해외 주식)
• MultiAccountAPIGateway (다중 계좌 오케스트레이션)

✅ Phase 4: 서비스 레이어 (완료)

• account-service (계좌 관리 API)
• trade-engine (Bull Queue 주문 처리)
• data-center (데이터 수집 스케줄러)
• strategy-manager (전략 실행)
• Docker Compose 통합
• Prometheus/Grafana 모니터링

✅ Phase 5: 초기 실행 및 테스트 (진행 중 - 50% 완료)

• Docker 인프라 실행 (postgres, redis, adminer)
• 스키마 자동 초기화 (13개 테이블)
• 계좌 데이터 임포트
• 패키지 빌드 (5개)
• 서비스 로컬 실행 테스트 (4개)
• Docker 전체 실행 테스트

🔄 Phase 6: Frontend (향후)

• Next.js 웹 대시보드
• 계좌 관리 페이지
• 트레이딩 대시보드
• 전략 설정 UI
• 실시간 차트 (WebSocket)

📅 Phase 7: 고도화 (계획)

• 백테스팅 엔진
• 알림 서비스 (Telegram, Email)
• 성과 분석 리포트
• 사용자 권한 관리 (RBAC)
• 모바일 앱

---

📚 추가 문서

프로젝트의 상세 진행 상황과 기술 결정 사항은 다음 문서에서 확인하세요:

• docs/editors_notes/11. 프로젝트 초기 실행 및 테스트.md - 현재 진행 상황 및 이슈 해결 기록
• COPILOT_TASK.md - VSCode Copilot 작업 지시서

---

📄 라이선스

MIT License

🤝 기여

이슈 및 PR 환영합니다!

---

📊 현재 진행 상황

✅ Phase 1-4: 완료 (설계, 패키지, 서비스 구현)
🔄 Phase 5: 진행 중 (초기 실행 및 테스트 - 50%)
   ├─ ✅ Docker 인프라 실행
   ├─ ✅ 스키마 초기화
   ├─ ✅ 계좌 임포트
   ├─ ⏳ 패키지 빌드 (다음 단계)
   └─ ⏳ 서비스 테스트
⏳ Phase 6-7: 대기 중 (Frontend, 고도화)

다음 작업: 패키지 빌드 (예상 소요 시간: 5분)

---

⚠️ 주의사항:

• 실전 투자 전 반드시 모의투자로 충분히 테스트하세요.
• 자동매매는 높은 리스크를 동반합니다.
• 투자 손실에 대한 책임은 투자자 본인에게 있습니다.