도움말

1.1 전체 구조

웹 콘솔은 한 곳에서 킬스위치·헬스·백테스트·메트릭·전략·설정을 확인·조작할 수 있는 통합 관리 화면입니다. 상단 네비게이션으로 페이지를 이동합니다.

메뉴	경로	역할
대시보드	/dashboard	킬스위치 상태 표시, 긴급 중지·재개 버튼
헬스	/health	메트릭 서버 등 헬스 확인
레디니스	/ready	JSON 프로브 — DB 준비·킬스위치 도달·감사 스토어(audit_store_ok) 등 (배포용)
백테스트	/backtest	실행 전 점검·저장 캔들·Grid/WF·시그널 랩(고급) — PnL·체결 등
메트릭	/metrics-page	Prometheus Gauges/Counters 요약 표시
페이퍼	/paper	페이퍼 트레이딩 실행 안내 및 복사 가능한 CLI 명령
설정	/settings	env 변수 목록(비밀값 마스킹), 읽기 전용
전략	/strategies	전략 목록·등록·승격·퇴출·복제·삭제·상세에서 메타 수정

1.2 디자인 원칙

• 직관성: 한글 라벨, 색상으로 상태 구분(예: 킬스위치 발동=빨강, 미발동=초록).
• 일관성: 모든 페이지가 공통 레이아웃(base.html)을 사용하며, 카드·버튼 스타일을 통일.
• 최소 의존: 별도 CLI·curl 없이 웹 UI만으로 일상 작업 처리 가능하도록 구성.

1.3 사용 난이도

사용자	난이도	권장
운영자(킬스위치만)	쉬움	/dashboard 북마크 후 Halt/Reset만 사용
운영자(전체 모니터링)	보통	헬스·메트릭 페이지 + Grafana 등 연동
개발자(백테스트/페이퍼)	보통	웹 백테스트 폼 또는 CLI 예시 참고

기능	웹	CLI
파이프라인 1회 실행	파이프라인 페이지 → 실행	python -m apps.ingest.main --symbol BTCUSDT --limit 500
백테스트(Mock)	백테스트 페이지 → 실행	POST /api/backtest/run (curl)
시그널 백테스트	백테스트 페이지 → 시그널 백테스트	python -m apps.backtester.run_signal_backtest
백테스트(저장 데이터)	백테스트 페이지 → 저장된 데이터로 백테스트	python -m apps.backtester.run_from_storage --symbol BTCUSDT --limit 2000
전략 목록·등록·승격·복제·삭제·메타 수정	전략 레지스트리 (이름 링크 → 상세 허브)	python -m apps.strategy_ops (list·snapshot·active-perf·targets·paper-bundle·export·show·register·promote·retire·clone·delete·update·http; --remote·--use-console·--via-http·--api-key) 또는 GET/POST /api/strategies, POST /api/strategies/clone, PATCH/DELETE /api/strategies/{name}/{version}. 동일 뇌(HTTP만): --via-http + WEB_CONSOLE_BASE_URL — 표에 없는 API는 http GET /openapi.json 스키마 확인 후 http POST /api/… --json-body '…'.
킬스위치 상태·중지·재개	대시보드	GET <KILL_SWITCH_URL>/status, POST .../halt, .../reset
페이퍼(실시간)	/paper 안내 + CLI 명령 복사	run_realtime --source ws · NL→한 줄 scripts/paper_command_from_nl.py · 호가 가드 --ws-tob · Redis 병합 --redis-merge-tob + ws_to_redis --with-tob
패턴 스캔 + 백테스트	/pattern-seeker 페이지	POST /api/pattern-seeker/scan, POST /api/pattern-seeker/backtest
데이터 탐색(A/B/C)	/data-explore 페이지	POST /api/explore/nl-guidance(workflow에 적재 단계: Binance /pipeline vs Coinalyze run_coinalyze_ingest_chain·.github/workflows/coinalyze_*.yml·GET /api/runtime-summary 구분·예시 JSON), GET /api/explore/nl-workflow, POST /api/explore/csv-preview
텔레그램 알림 연구 파이프라인	—	python -m apps.backtester.run_telegram_research_pipeline --text-file … (scripts/README.md)
Grid Search (목 캔들)	전략 대시보드	POST /api/optimizer/run
Grid / Walk-Forward (저장 캔들)	백테스트 페이지 하단	POST /api/optimizer/run-from-storage, walk-forward-from-storage
Walk-Forward (목 캔들)	전략 대시보드	POST /api/optimizer/walk-forward

CLI 옵션 이름(--symbol, --limit, --strategy 등)은 웹 API·폼 필드와 가능한 한 동일하게 맞춰 두었습니다.

3.1 대시보드

킬스위치 서비스와 연동해 상태 확인(발동 중 / 정상), 긴급 중지(Halt), 재개(Reset)를 수행합니다. 10초마다 자동 갱신됩니다.

• 킬스위치 서비스가 KILL_SWITCH_URL(기본 9800)에서 실행 중이어야 합니다.
• 긴급 중지 시 메트릭에 킬스위치 발동 횟수가 기록됩니다.

3.2 헬스

메트릭 서버(METRICS_URL, 기본 9090)의 GET /health 결과를 표시합니다. 연동 서비스 상태를 빠르게 확인할 때 사용합니다.

3.3 백테스트

추천 순서: 파이프라인으로 DB에 캔들을 쌓은 뒤, 같은 페이지에서 「저장된 캔들」로 돌립니다. 오래 걸리면 「백그라운드 실행」을 켜 두면 화면이 자동으로 결과를 갱신합니다(개발자: §6 작업 조회 API). Mock 캔들은 UI가 잘 도는지 볼 때만 쓰면 됩니다.

웹 /backtest 상단 접기 블록에 엔진이 가정하는 체결·슬리피지·선물 단순화를 요약해 두었고, 설정·스튜디오·페이퍼는 같은 문구를 templates/partials/sim_assumptions.html 에서 분기해 씁니다.

• 저장된 데이터 백테스트: 파이프라인으로 수집한 DB 캔들 사용. 실제 검증용.
• 시그널 백테스트: 외부 시그널(CoinGecko 등)을 반영한 백테스트.
• Mock 백테스트: 임의 생성 캔들. 테스트용으로만 사용.

3.4 메트릭

Prometheus 레지스트리에서 수집한 Gauges·Counters 요약을 표시합니다. PnL·드로우다운·슬리피지·체결 비율·킬스위치 횟수 등이 정의되어 있으며, OMS·ExecutionEngine 등에서 호출 시 값이 갱신됩니다.

3.5 페이퍼

페이퍼 트레이딩 실행 방법 안내와 복사 가능한 CLI 명령을 제공합니다. 자연어로 한 줄 명령을 만들려면 scripts/paper_command_from_nl.py(Claude·OpenAI 호환·폴백, --json)를 씁니다. 실제 기동은 --execute와 함께 --confirm-execute가 필요합니다. 실제 장기 실행은 터미널에서 수행합니다.

3.6 설정

앱이 참조하는 환경 변수 목록을 읽기 전용으로 표시합니다. API 키·시크릿 등은 ***로 마스킹됩니다. 변경은 .env 수정 후 재시작이 필요합니다.

3.7 전략

전략 레지스트리의 목록 조회, 새 전략 등록(이름·버전·상태·spec·레짐 등), 기존 전략의 승격(promote)·퇴출(retire)을 수행합니다. 상태 전이는 DRAFT → PRODUCTION → DEPRECATED → RETIRED 순서를 따릅니다.

3.8 전략 대시보드

전략별 지표·포트폴리오 요약 및 ExperimentTracker에 저장된 최근 실험 결과를 확인하고, Grid Search·Walk-Forward를 직접 실행합니다.

3.9 패턴 시커

텍스트·지표 조건·캔들 패턴 세 가지 방법으로 전략 시그널을 감지하고 즉시 백테스트합니다. 자세한 내용은 4. 신규 기능 가이드를 참조하세요.

3.10 OMS 모니터링

/oms 페이지에서 페이퍼 트레이더 또는 실거래 엔진이 기록한 포지션·주문·체결 내역을 조회합니다. 심볼 필터로 특정 종목만 볼 수 있으며 새로고침 버튼으로 최신 상태를 확인합니다. 데이터는 data/oms.db (SQLite)에 저장됩니다.

3.11 OMS 리컨실 (별도 프로세스)

이 서버는 리컨실 루프를 돌리지 않습니다. OMS와 거래소 REST 스냅샷을 맞추려면 scripts/run_reconcile_loop.py를 웹과 별도 터미널·cron·PaaS 두 번째 서비스 등에서 실행하세요. USDT-M 비교 시 --product futures, 한 번만이면 --once. User Data 직후 디바운스 리컨실은 run_user_stream_reconcile_bridge.py (선택).

문서: 저장소 docs/RUNBOOK_AND_INCIDENT.md 4.1 · docs/DEPLOY_RAILWAY_VERCEL_SUPABASE.md 1b · scripts/README.md

4.1 패턴 시커 (/pattern-seeker)

세 가지 방법으로 전략 시그널을 감지하고 즉시 백테스트할 수 있습니다.

기능	방법	API
텍스트 → 패턴	텔레그램 메시지·분석글을 붙여넣으면 방향(롱/숏)을 추론해 PatternMatch로 변환	POST /api/pattern-seeker/parse
지표 조건 빌더	드롭다운으로 지표 선택 → 연산자(>·<·=) → 값 입력, AND로 다중 조건 설정	POST /api/condition-parser/parse
캔들 패턴 스캔	12종 패턴(골든크로스·데스크로스·엔걸핑·볼린저 스퀴즈 등) 선택 후 저장 캔들 스캔	POST /api/pattern-seeker/scan
즉시 백테스트	인식된 패턴이나 조건으로 곧바로 백테스트 → Sharpe·Sortino·Calmar·MaxDD% 결과	POST /api/pattern-seeker/backtest

4.1.1 지표 피처 전체 목록

build_features()가 반환하는 주요 피처들입니다. funding_rate_history와 trade_count_history 인수를 넘기면 더 정확한 값을 계산합니다.

피처	그룹	설명
return_1m/5m/15m	Price	1·5·15봉 수익률
rv_5m / rv_30m	Volatility	5봉·30봉 실현 변동성
atr_14	Volatility	ATR (14봉)
zscore_price_60	Price	60봉 가격 Z-score (평균 회귀 신호)
trend_slope_20	Trend	20봉 선형 회귀 기울기
trend_r2_20	Trend	20봉 추세 R²(결정계수)
volume_z_5m / volume_z_30m	Volume	거래량 Z-score
dollar_volume	Volume	봉당 거래대금 (가격×거래량)
avg_trade_size_proxy	Volume	추정 평균 거래 단위 크기 (tick 기반 추정)
large_trade_rate_proxy	Volume	대형 거래 비율 프록시 (volume_z_5m 기반)
funding_rate	Deriv	펀딩율 (선물)
funding_rate_z	Deriv	펀딩율 Z-score (히스토리 96개 기준; 없으면 단위 추정)
oi / oi_change_5m	Deriv	미결제약정·5봉 변화율
regime_label	Regime	시장 레짐 (CRASH, HIGH_VOL, TREND_UP/DOWN, RANGING, MEAN_REV, BREAKOUT_PENDING)
regime_confidence	Regime	레짐 신뢰도 (0~1)

4.2 성과 지표 (BacktestResult)

백테스트 결과에 포함된 지표 설명입니다.

지표	설명	기준
Sharpe Ratio	연환산 수익/변동성 비율	≥ 1.0 좋음, ≥ 2.0 매우 좋음
Sortino Ratio	하방 리스크만 사용한 Sharpe	≥ 1.5 좋음
Calmar Ratio	연환산 수익 / Max Drawdown	≥ 1.0 좋음
Max Drawdown %	고점 대비 최대 낙폭	≤ 20% 양호
Win Rate	수익 체결 / 전체 체결	≥ 50% 선호
Profit Factor	총 수익 / 총 손실 절댓값	≥ 1.5 좋음

4.3 파라미터 최적화 (Grid Search + Walk-Forward)

전략 대시보드의 하단 섹션에서 실행합니다.

• Grid Search: 파라미터 그리드의 모든 조합을 탐색해 지정 지표(Sharpe·Calmar·PnL 등) 기준으로 정렬. 결과는 ExperimentTracker에 자동 저장됩니다.
• Walk-Forward 검증: 데이터를 n개 fold로 분할 → 각 fold의 Train 구간에서 최적 파라미터 탐색 → Val 구간에서 검증 → Overfitting Ratio = Val Score / Train Score. 0.6 이상이면 강건한 전략으로 판단합니다.
• Spec DSL 최적화: 전략 선택에서 Spec DSL ↓을 선택하고 Spec JSON을 입력하면 make_spec_factory가 자동으로 사용됩니다. param_grid 키로 cond_0_value, atr_stop_mult, profit_target_mult, notional_usd를 지원합니다.

Binance 연결 테스트: 설정 · 연결 테스트에서 Binance·리스크·DB 상태를 한눈에 확인할 수 있습니다.

# 파라미터 그리드 예시 (JSON)
{"volume_z_min": [0.8, 1.2, 1.5], "atr_stop_mult": [1.0, 1.5, 2.0]}

# Mean Reversion 예시
{"zscore_entry": [1.5, 2.0, 2.5], "zscore_exit": [0.3, 0.5, 0.8]}

4.4 멀티레이블 레짐 분류

피처 빌더(build_features)가 시장 상태를 복수 레이블로 분류합니다.

레짐	조건(기준)	설명
CRASH	1분 수익률 < -0.5%	급락 감지 (최우선)
HIGH_VOL	ATR/Close > 0.02	고변동성 구간
BREAKOUT_PENDING	볼린저 밴드 폭 < 0.02	스퀴즈 → 브레이크아웃 예고
TREND_UP	slope_close_60 > 0 && atr_pct ≤ 0.02	상승 추세
TREND_DOWN	slope_close_60 < 0 && atr_pct ≤ 0.02	하락 추세
RANGING	ATR 낮고 slope 작음	횡보 구간
MEAN_REV	|zscore_price_60| > 1.5	평균 회귀 신호

features dict의 regime_labels(리스트)와 regime_label(첫 번째 값, 하위호환) 두 키로 접근합니다.

4.4.1 전략 라우터 멀티레이블 처리

strategy_router()는 regime_labels 리스트를 우선 확인합니다. CRASH 또는 HIGH_VOL이 하나라도 포함되면 신규 진입 전면 차단됩니다. 나머지 레짐 중 첫 번째로 매핑된 전략 목록을 사용합니다.

레짐	허용 전략	비고
TREND_UP / TREND_DOWN	Breakout_v1	추세 추종
BREAKOUT_PENDING	Breakout_v1	변동성 압축 후 브레이크아웃 대기
MEAN_REV / RANGING	MeanReversion_v1	횡보·평균회귀
CRASH / HIGH_VOL / SHOCK	(진입 차단)	손실 방어

4.4.2 Strategy DSL (Spec 기반 전략)

libs/strategies/spec.py의 compile_strategy(spec)를 사용하면 JSON spec으로 전략을 정의하고 바로 백테스트할 수 있습니다.

# spec 예시 (Python dict / JSON)
{
  "name": "MyBreakout_v2",
  "entry": {
    "conditions": [
      {"indicator": "volume_z_5m", "op": ">", "value": 1.5},
      {"indicator": "regime_confidence", "op": ">=", "value": 0.5}
    ],
    "side": "LONG",
    "regime_filter": ["TREND_UP", "BREAKOUT_PENDING"],
    "block_regimes": ["CRASH", "HIGH_VOL"],
    "notional_usd": 10000
  },
  "exit": {
    "atr_stop_mult": 2.0,
    "profit_target_mult": 4.0
  },
  "guards": {"max_slippage_bps": 6, "time_limit_sec": 900}
}

백테스트 페이지 → "저장된 데이터로 백테스트" 섹션 → 전략을 Spec (DSL)으로 선택한 후 Spec JSON 입력란에 붙여넣고 실행하세요.

4.5 시그널 → 패턴 → 전략 플로우

텔레그램 복붙·봇 수신·TradingView 알림을 한 흐름으로 모아 시그널 수집 → 변환·패턴 분석 → 백테스트 → 전략으로 옮기기까지 진행할 수 있습니다.

1. 시그널 수집: 텔레그램·시그널 연동 페이지에서 (1) 텍스트 복붙 (2) 봇으로 채널/그룹 최근 메시지 가져오기 (3) TradingView Alert 웹훅 수신 중 하나로 시그널을 넣습니다.
2. 변환·패턴: 「변환」으로 심볼·방향 추출, 또는 「패턴 분석」으로 패턴 시커가 롱/숏·심볼을 인식합니다.
3. 백테스트: 「즉시 백테스트」로 해당 시그널/패턴의 과거 성과를 확인합니다.
4. 전략으로 옮기기: 전략 페이지에서 시그널 기반 전략을 등록하거나, JSON을 data/telegram_signals.json에 저장해 백테스트·페이퍼의 시그널 소스로 사용합니다.

4.6 페이퍼 트레이딩 — 전략 선택

CLI 실행 시 --strategy 옵션으로 전략을 선택할 수 있습니다.

# Breakout 전략 (기본)
python -m apps.paper_trader.run_realtime --source ws --symbol BTCUSDT --strategy breakout

# Mean Reversion 전략
python -m apps.paper_trader.run_realtime --source ws --symbol BTCUSDT --strategy mean_reversion

# Redis Stream 소스 + mean_reversion (캔들만)
python -m apps.paper_trader.run_realtime --source redis --strategy mean_reversion --stream md.candles.BINANCE.BTCUSDT.1m

# WS + 호가 기반 실행 가드 (multiplex depth)
python -m apps.paper_trader.run_realtime --source ws --symbol BTCUSDT --strategy breakout --ws-tob

# Redis: 별도 터미널에서 프로듀서 후, 캔들+md.ticks 병합 소비
# python apps/ingest/ws_to_redis.py BTCUSDT redis://localhost:6379/0 1m --with-tob
python -m apps.paper_trader.run_realtime --source redis --symbol BTCUSDT --venue BINANCE --stream md.candles.BINANCE.BTCUSDT.1m --strategy breakout --redis-merge-tob

7.1 텔레그램 시그널 (복붙)

텔레그램·시그널 연동 페이지에서 텔레그램에서 복사한 텍스트를 붙여넣으면 한 줄 = 메시지 하나로 변환되고, BTC/ETH 등 심볼과 롱·숏 방향이 자동 추출됩니다. 「패턴 분석」을 누르면 패턴 시커가 방향을 더 정교하게 분석합니다.

7.2 텔레그램 봇으로 채널/그룹 메시지 가져오기

봇을 그룹 또는 채널에 추가한 뒤, 웹에서 「최근 메시지 가져오기」로 Bot API getUpdates를 호출해 최근 메시지를 시그널 형식으로 가져올 수 있습니다.

• 설정: .env에 TELEGRAM_BOT_TOKEN= (봇 토큰), TELEGRAM_CHANNEL_IDS= (채팅 ID 쉼표 구분, 비우면 모든 대화에서 가져옴).
• 채팅 ID 확인: 봇을 그룹에 추가한 뒤 그룹에서 메시지를 보내고, GET https://api.telegram.org/bot<TOKEN>/getUpdates로 응답의 message.chat.id를 확인합니다. 채널은 보통 -100으로 시작하는 숫자입니다.
• API: GET /api/telegram-signals/status (연동 여부), GET /api/telegram-signals/fetch?limit=50 (최근 메시지 가져오기).

7.3 봇으로 시그널/알림 보내기

전략 알림이나 시그널을 텔레그램 채팅으로 보내려면 POST /api/telegram-signals/send를 사용합니다.

# body
{"message": "BTCUSDT LONG 진입 시그널", "chat_id": "-1001234567890"}

# chat_id 생략 시 TELEGRAM_CHANNEL_IDS의 첫 번째 값 사용

7.4 TradingView Alert 웹훅

TradingView 차트에서 Alert를 만들고, Webhook URL에 아래 주소를 넣으면 알림이 Brainwave로 전달됩니다.

• 웹훅 URL: https://<웹콘솔주소>/api/webhooks/tradingview (예: 로컬이면 http://127.0.0.1:8080/api/webhooks/tradingview).
• 수신 본문: TradingView는 사용자가 지정한 메시지를 POST합니다. symbol(또는 ticker), action(buy/sell), message, time 등이 있으면 자동으로 시그널로 정규화됩니다.
• Alert 메시지 예시: 메시지 내용에 {{ticker}}, {{close}}, buy 또는 sell을 넣고, Webhook URL에 위 주소를 설정하세요.

수신된 시그널은 signal 객체로 응답에 포함됩니다. COUNTERPARTY_SIGNAL_WEBHOOK_URL을 설정하면 동일 시그널이 비동기로 상대 HTTPS 엔드포인트에도 JSON 봉투로 전달됩니다(자금·거래소 키 미포함). 상세는 아래 절과 레포 docs/BOT_MODULAR_INTEGRATION.md 를 참고하세요.

투기장은 자연어로 전략 아이디어를 입력하고, 조건식으로 해석한 뒤, 여러 전략을 수익률·MDD·거래 수로 비교하며, 텔레그램 시그널·패턴 시커·트레이딩뷰·거래소 데이터와 연동해 쓰기 위한 전용 페이지입니다.

• 진입: 상단 메뉴 투기장.
• 자연어 입력: 왼쪽 칸에 「거래량이 많을 때만 매수하고 싶어요」처럼 적고 [의도 해석·가이드 보기]를 누르면 추천 표현식 예시를 볼 수 있습니다.
• 조건식: 오른쪽 칸에 volume_z_5m > 1.2 AND regime_label == TREND_UP처럼 지표+부등호를 넣고 [의도 해석 (Spec 변환)]을 누르면 전략 Spec으로 변환됩니다.
• 전략 비교: 등록된 전략과 실험(백테스트) 결과를 수익률(PnL), 최대 낙폭(MDD %), 거래 수, 최근 실행 시각으로 표시합니다.
• 연동: 텔레그램 시그널, 패턴 시커, 트레이딩뷰 웹훅, 거래소 데이터(파이프라인), 백테스트 페이지로 이어지는 카드가 있습니다.

자세한 설명은 docs/ARENA_GUIDE.md를 참고하세요.

용어 (한글)	영문/코드	설명
대시보드	dashboard	킬스위치 상태를 보고 긴급 중지·재개하는 첫 화면
파이프라인	pipeline	거래소에서 캔들 데이터를 한 번 수집해 DB에 저장하는 작업
파이프라인 설정	pipeline config	수집할 심볼·인터벌·봉 개수 등을 저장해 두는 설정
전략	strategy	이름·버전·상태를 가진 전략 레지스트리 항목 (예: Breakout_v1)
전략 대시보드	strategy dashboard	전략별 지표·포트폴리오 요약을 보는 페이지
지표 정의	metric definition	사용자가 정의한 지표의 메타데이터 (이름·타입·라벨 등)
백테스트	backtest	과거(또는 저장된) 캔들로 가상 매매를 돌려 PnL·체결 수를 계산하는 것
시그널 백테스트	signal backtest	외부 시그널(코인게코 등)을 반영한 백테스트
페이퍼	paper	실제 자금 없이 실시간으로 가상 체결하는 모드 (페이퍼 트레이딩)
시그널	signal	텔레그램·코인게코 같은 외부 소스에서 오는 이벤트/데이터
킬스위치	kill switch	글로벌하게 모든 트레이딩을 중지시키는 안전 장치
메트릭	metrics	PnL·드로우다운·체결 수 등 수치 지표 (Prometheus 형식)
Venue	venue	거래소/플랫폼 (예: BINANCE)
심볼	symbol	거래 쌍 (예: BTCUSDT)
캔들/봉	candle / bar	일정 시간(1m, 1h 등) 단위의 시가·고가·저가·종가·거래량 데이터
패턴 시커	pattern seeker	텍스트/지표/캔들 패턴을 입력받아 전략 시그널로 변환하는 모듈
Grid Search	grid search	파라미터 조합을 전수 탐색해 최적값을 찾는 최적화 방법
Walk-Forward	walk-forward	학습/검증 구간을 시간 순으로 이동하며 과적합을 검증하는 방법
Overfitting Ratio	overfitting ratio	Val Score / Train Score. 1에 가까울수록 과적합 없음
레짐	regime	시장 상태 분류 (TREND_UP/DOWN, HIGH_VOL, CRASH, RANGING 등)
Sharpe Ratio	sharpe ratio	연환산 수익 / 변동성. 위험 대비 수익 효율 지표
Sortino Ratio	sortino ratio	하방 변동성만 사용한 Sharpe Ratio 변형
Calmar Ratio	calmar ratio	연환산 수익 / Max Drawdown
Profit Factor	profit factor	총 수익 / 총 손실. 1.5 이상을 양호로 봄
PatternMatch	PatternMatch	패턴 인식 결과 객체 (이름·점수·direction·meta)
Condition	Condition	전략 진입 조건 (indicator, op, value 3요소)

6.1 기술 스택

구분	선택
백엔드	FastAPI (비동기, API 확장 용이)
서버	uvicorn
템플릿	Jinja2 (서버 렌더링)
프론트	HTML + CSS + 바닐라 JS (폼·버튼·복사 등)

6.2 설정(환경 변수)

변수	기본값	설명
KILL_SWITCH_URL	http://127.0.0.1:9800	킬스위치 API 베이스 URL
METRICS_URL	http://127.0.0.1:9090	메트릭/헬스 서버 URL
WEB_CONSOLE_HOST	0.0.0.0	바인드 주소
WEB_CONSOLE_PORT	8080	리스닝 포트
REGISTRY_DB_PATH	data/registry.db	전략 레지스트리 DB 경로

6.3 실행 방법

# 킬스위치 서비스(별도)
python -m apps.kill_switch_service.main --port 9800

# 웹 콘솔 단독
python -m apps.web_console.main

# 한 번에 모두 실행 (킬스위치 + 메트릭 + 웹 콘솔)
python scripts/run_all_services.py

브라우저: http://localhost:8080/ (또는 설정한 호스트/포트)

6.4 API 엔드포인트 요약

메서드	경로	설명
GET	/api/kill_switch/status	킬스위치 상태
POST	/api/kill_switch/halt	긴급 중지
POST	/api/kill_switch/reset	재개
GET	/api/metrics/summary	메트릭 요약(JSON)
GET	/api/audit	감사 로그 조회 — ?limit= 최근 목록, ?envelope_id= / ?order_id=, ?event_type= / ?since=(ISO 시각 하한) (AUDIT_DB_PATH 또는 DATABASE_URL) · 필드·event_type 정본 docs/AUDIT_LOG_SCHEMA.md
GET	/api/health	LB용 JSON 헬스 — metrics_ok, 메트릭 서버 /health 도달 여부
GET	/api/runtime-summary	비밀 없는 런타임 요약 — database_backend·live_paper_snapshots_to_database·paper_snapshots_will_write_postgres·ready_probe_fail_on(env+메모리 효과값)·ready_probe_fail_on_patch·runtime_memory_patch_active·동시성 한도·보조 오케스트레이터·real_use_code_task_index(실사용 코드 경로 색인)·active_strategies_summary(레지스트리 활성 건수·페이퍼 한 줄·paper_status_paths_count·paper_detail_url·paper_snapshot_db)·runtime_targets(경로·DB URL 마스킹·paper_snapshot_db)·ops_wiring_hints 등 (INF-1 읽기)
GET	/api/runtime-targets	CLI strategy_ops targets 와 동일 — cwd·페이퍼 JSON 해석 경로 목록·레지스트리 백엔드·paper_snapshot_db(스냅샷→PG 정합)·WEB_CONSOLE_BASE_URL 힌트(비밀 미포함). 원격·--via-http 시 targets 는 이 엔드포인트만 호출합니다.
GET	/openapi.json	OpenAPI 스키마 — Swagger UI /api-docs · ReDoc /redoc. 사용자 도움말(온보딩)은 /docs. CLI: python -m apps.strategy_ops --use-console http GET /openapi.json
GET	/api/paper/status	주 페이퍼 상태 JSON 한 파일(PAPER_LIVE_STATUS_FILE / 기본 .run/paper_live_status.json)
GET	/api/paper/status-bundle	주 + 추가 페이퍼 JSON(PAPER_LIVE_STATUS_FILES 쉼표) — 스냅샷 paper_status_bundle 과 동일 규칙
GET	/api/oi-live/summary	원격 OI 페이퍼 요약 — live_paper_snapshots(DATABASE_URL + 워커가 LIVE_PAPER_SNAPSHOTS_TO_DATABASE 로 적재 시). UI: 대시보드 「OI 봇 원격 라이브」·/performance-live
PATCH	/api/runtime-settings	INF-1 쓰기(프로세스 범위): ready_probe_fail_on 병합·빈 객체로 섹션 제거·live_pattern_store_enabled (bool 또는 null 로 패치 해제)·{"clear":true} 전체 초기화 — 재시작 시 소실
POST	/api/strategy-spec/compile	F-1: {"spec":{...}} 또는 인텐트 필드 루트 → StrategyIntent 검증·warnings · guards 는 문서화된 키만(미시구조 값은 허용 집합) — 위반 시 ok:false + error
POST	/api/metric-definitions/{name}/observe	F-3: 사용자 정의 gauge(value)·counter(amount)·histogram(value)에 샘플 기록; 선택 labels
GET	/metrics	Prometheus 스크래핑용(지표 정의 저장소 동기화 시 userdef_* 포함)
POST	/api/backtest/run	Mock 백테스트 (테스트용, multipart/form-data). 응답에 synthetic_candles: true·data_source: mock_generate_candle_series · Form: market_kind(기본 spot)·margin_mode·position_mode·use_paper_runtime·simulation_hedge_mode 등(알 수 없는 값 HTTP 400) · position_mode=hedge 는 use_paper_runtime+simulation_hedge_mode 없으면 ok:false + error — 전략 검증에는 /api/backtest/from-storage 사용
POST	/api/backtest/from-storage	저장 캔들 백테스트. 성공·일부 실패(엔진 오류·동기 예외) 본문에 synthetic_candles: false·data_source: timeseries_store·simulation_run_type: historical_candle_replay · market_kind spot|linear_perp · leverage · params.trailing_stop_* · enforce_time_limit · 선택 funding_settlement_mode proportional|discrete_8h_utc · execution_timing bar_close|next_bar_open(use_paper_runtime 과 배타) · sim_fee_role taker|maker · maker_fee_bps / taker_fee_bps · margin_mode|marginMode (isolated|cross; 잘못된 값 HTTP 400) · position_mode|positionMode — hedge 는 use_paper_runtime+simulation_hedge_mode(또는 simulationHedgeMode) 없으면 ok:false 본문 · async:true → job_id 폴링(GET /api/jobs/… 의 result에 동일 계열 메타, running 포함)
POST	/api/text/extract-numerics	자연어에서 퍼센트·레버리지·통화 축약·숫자 추출 ({"text":"..."}); 텔레그램·시그널 페이지에서도 호출 가능
POST	/api/explore/nl-guidance	자연어 질의 → 페이지·API 안내 + workflow(단계·적재 단계에서 Binance 캔들 vs Coinalyze 체인·트레일링 설명·예시 JSON). Claude 또는 키워드 폴백
GET	/api/explore/nl-workflow	종단 연구 플로우만 (?q= 질의 시 관련 단계 highlight; phases 의 ingest 요약·apis 에 GET /api/runtime-summary·Coinalyze Actions 경로 포함)
POST	/api/optimizer/run-from-storage	저장 캔들 Grid — 성공·실패 본문에 synthetic_candles: false·data_source: timeseries_store·simulation_run_type: optimizer_grid_timeseries_store · market_kind·leverage·enforce_time_limit·use_paper_runtime · from-storage 와 동일 백테스트 확장 필드(funding_settlement_mode·execution_timing·sim_fee_role·maker/taker bps·margin_mode|marginMode·position_mode|positionMode) · async:true → job_id(폴링 시 running·완료·실패 result에 출처 메타)
POST	/api/optimizer/walk-forward-from-storage	저장 캔들 WF — 동일 메타에 simulation_run_type: optimizer_walk_forward_timeseries_store · market_kind·leverage 등 · 위 백테스트 확장 필드 동일 전달(margin_mode·position_mode 포함) · async:true → job_id(폴링 result 동일) · 구간별 파생 미적용
POST	/api/explore/csv-preview	붙여넣은 CSV 요약 ({"csv":"..."}, 선택 max_rows); 컬럼·수치 통계·시간열 추정
GET	/api/simulations/profiles	시뮬 프로필 목록 (include_derivatives, include_coinalyze_aux, market_kind, simulation_leverage, margin_mode 등)
POST	/api/simulations/profiles	시뮬 프로필 생성 — margin_mode|marginMode (isolated|cross; 잘못된 값 생성 실패)
PATCH	/api/simulations/profiles/{id}	프로필 부분 갱신 (웹 스튜디오 폼과 동일, margin_mode 포함)
POST	/api/simulations/portfolio	가중 포트폴리오 시뮬 (profile_id, legs 또는 candidate_ids+가중치)
POST	/api/simulations/compare-candidates	동일 프로필로 후보 여러 개 연속 시뮬·비교 · 웹 /strategy-studio 에서 체크박스·쿼리 ?cmp_ids=UUID들(쉼표, 최대 5)·선택 cmp_profile=프로필 UUID 로 폼·체크 프리필
POST	/api/backtest/signal	외부 시그널 반영 백테스트 — 본문에 from-storage 와 동일 백테스트 확장 필드(funding_settlement_mode·execution_timing·sim_fee_role·maker_fee_bps/taker_fee_bps·margin_mode·position_mode·use_paper_runtime·simulation_hedge_mode 등) 선택, 알 수 없는 모드 문자열 HTTP 400 · position_mode=hedge 는 use_paper_runtime+simulation_hedge_mode 없으면 HTTP 200·ok:false + error · 그 외 성공 시 응답에 적용값 반영 · 웹 /backtest 「시그널 인젝션 랩」(상단 폼과 동일 시장·고급 옵션; 헷지 시 use_paper_runtime 등은 JSON 본문으로 전달)
GET	/api/strategies	전략 목록
GET	/api/strategies/active-snapshot	가동·배포 전략 — 레지스트리(PAPER_APPROVED·CANARY·PRODUCTION) 수치 + paper_process + paper_status_bundle(다중 JSON) + paper_detail_url(strategy·strategy_version 또는 이름@시맨틱버전) + paper_snapshot_db(DATABASE_URL·LIVE_PAPER_SNAPSHOTS_TO_DATABASE 정합 힌트)
POST	/api/strategies	전략 등록
POST	/api/strategies/clone	전략 복제 — 본문 from_name, from_version, to_version 필수, to_name 선택; 새 행은 항상 DRAFT
PATCH	/api/strategies/{name}/{version}	action: promote | retire | update — update 시 본문에 바꿀 필드만 포함 (description, target_regime, 선택 spec·allowed_regimes·forbidden_regimes·risk_budget_bps·max_daily_loss_usd; spec/레짐/리스크는 DRAFT·BACKTEST_APPROVED 만)
DELETE	/api/strategies/{name}/{version}	전략 삭제 — 기본은 DRAFT·RETIRED 만; ?force=true 는 운영 주의
POST	/api/pattern-seeker/parse	텍스트 → PatternMatch 변환
POST	/api/pattern-seeker/scan	저장 캔들 패턴 스캔
POST	/api/pattern-seeker/backtest	패턴·조건식 기반 즉시 백테스트 — 동일 확장 필드 본문 선택·응답 반영(matches 또는 expression; margin_mode·position_mode 등)
POST	/api/condition-parser/parse	지표 조건 텍스트 파싱
GET	/api/experiments	ExperimentTracker 최근 실험 목록
POST	/api/optimizer/run	목 캔들 Grid — market_kind·leverage·enforce_time_limit·use_paper_runtime · from-storage 와 동일 백테스트 확장 필드(funding_settlement_mode·execution_timing·sim_fee_role·maker/taker bps·margin_mode|marginMode·position_mode|positionMode; 잘못된 값 HTTP 400)
POST	/api/optimizer/walk-forward	목 캔들 WF — market_kind 등 + 위와 동일 백테스트 확장 필드(margin_mode·position_mode 포함)
POST	/api/backtest/compare	전략 비교(Side-by-Side) — 본문 최상단에 margin_mode·position_mode 등 백테스트 확장 필드 공통 전달(각 runs[] 와 자동 병합 없음); 파싱 오류 HTTP 400 · 개별 run 실패는 해당 행 ok:false · UI: /backtest#bt-mock-compare (?cmp_a=·cmp_b=·cmp_bars= 등 쿼리로 폼 채움)
POST	/api/pipeline/run	캔들 1회 인제스트(Binance REST). async:true → job_id · GET /api/jobs/… 의 result에 data_source: exchange_rest_ingest·simulation_run_type: pipeline_ingest 등(running·완료·실패)
GET	/api/jobs/{job_id}	비동기 작업 상태 — status: running|completed|failed · error(실패 시) · result에 job_kind·data_source·simulation_run_type·심볼·간격 등(작업 종류별)
GET	/api/pipeline/status	저장된 캔들 시리즈 현황
GET	/api/data-health	동일 시리즈에 누락 비율(추정)·최신성·상태 요약(libs.data_health) — 데이터 수집 표와 연동
GET	/api/test/binance	Binance REST Spot+Futures ping 테스트
GET	/api/oms/positions	OMS 포지션 목록
GET	/api/oms/orders	OMS 주문 내역 (최신순)
GET	/api/oms/fills	OMS 체결 내역 (최신순)
GET	/api/risk/state	Risk Engine 상태 (드로우다운·일손실·킬스위치) · 본문 intent_gate_when_kill_switch: 킬스위치 시 can_open_intent 가 CLOSE/REDUCE 만 허용·OPEN/REVERSE 거부
POST	/api/risk/reset	Risk Engine 킬스위치 수동 리셋 — 감사 risk_engine_kill_switch_reset, 이전 활성 시 ALERT_WEBHOOK_URL 알림
POST	/api/sim/slippage	슬리피지 시뮬 (LightweightExecutionSim)

6.5 Out of Scope (현재 단계 제외)

• 사용자 인증·권한 — 추후 검토(내부망 전제 시 생략 가능)
• 실시간 차트·Grafana 대체 — 메트릭은 Prometheus/Grafana 연동 유지
• 전략 코드 편집 — 설정·전략 변경은 .env·코드 배포로 유지
• OMS 실시간 WebSocket 스트림 — 현재 REST 폴링 방식 (페이퍼 실행 후 /oms 에서 조회)
• 페이퍼 웹에서 장기 실행 — 웹에서는 안내만, 실행은 CLI