프로젝트 문서 (v0.4.1)

v0.4.1 UI 정리

• 상단 메뉴를 전략/로그/설정/텔레그램 중심으로 단순화
• 전략 입력 화면을 매도 핵심 필드 중심으로 재구성 (고급 기능은 BOX JSON 편집으로 유지)
• 설정(API) 화면을 최소화하고, 보호/리스크/WS/백업은 고급으로 접어서 유지
• 텔레그램은 사용자별 설정을 그대로 사용(사용자별 거래 이벤트 전송)

핵심 변경점

• JWT 미사용: MongoDB 세션 기반 로그인
• 동시 로그인 금지: 새 로그인 시 기존 세션 무효화(단일 세션 강제)
• 키움 연동 모듈을 조회(market_data) / 주문(orders)로 분리하고 주문은 타입별 파일로 분리

v0.4.0 추가 (주문 로직 변경 없음)

• OHLC(분봉) 파서 정규화: time/open/high/low/close/volume 표준화 + old->new 정렬/중복 제거
• OHLC 폴링 스케줄 분리: quote는 자주, OHLC(평균시가/종가)는 심볼별 워커 메모리 캐시로 10~30초 주기 갱신
• .env 기본값 변경: OHLC_CACHE_TTL_SEC 기본 20초

v0.4.0 추가

• History(거래기록) API/화면/CSV에 가격 필드 추가: decision_price(결정시점 현재가), order_price(지정가 주문가), fill_price(체결가; 추후 업데이트), order_id

v0.4.0 추가

• 익절(TP): 일봉 SMA 이탈
  • 일봉 SMA 기간(1~20) 선택
  • 포지션 진입 당일은 매도 평가를 하지 않고, 다음날부터 장중 세션(기본 09:00~15:00)에서만 평가
  • 현재가가 SMA 아래로 이탈하면 매도 트리거
  • TP 전용 매도 방식(exit_mode) 선택: 시장가 / 현재가 지정가 / 고정가 지정가
• 기준가 설정: 시작평균가/마감평균가(분봉 평균)
  • 마감평균가: 5분 단위(예: 13:00~15:30)
  • 시작평균가: 5분 단위(예: 09:00~10:00)
• SL: 장 오픈 이후 기준가 하락
  • 09:00부터 N분 동안, 기준가(마감평균가/시작평균가) 대비 N% 하락 시 매도
  • SL 전용 매도 방식(exit_mode) 선택
• 시간 규칙(세션/금지시간)은 로컬 시간(now_local) 기준으로 평가

v0.4.0 추가

v0.4.0 안전패치

• 지정가 변경매도(30초 reprice) 안전화: 서버 타임존과 무관하게 KST(Asia/Seoul)로 15:20~15:30 블랙아웃을 판정
• reprice 수행 전 실시간 open_orders에서 주문이 OPEN 상태인지 확인(확인 불가/미존재 시 스킵)
• cancel 미구현/실패 시 중복 매도 방지를 위해 reprice 스킵

• 지정가 매도 리프라이스(30초): 엔진이 발행한 지정가 SELL 주문이 30초 이상 OPEN 상태이면, 현재가 지정가로 cancel+re-place 합니다.
• 예외 시간대: 15:20~15:30(KST)에는 리프라이스가 동작하지 않습니다(해당 구간에서는 보류 후 15:30 이후 재시도).
• History에 기존 order_id를 replaced로 마킹하고, 새 order_id를 신규 행으로 기록합니다.

v0.4.0

• 사용자별 실시간 WS 체결 이벤트(00 등) 수신 시, order_id가 매칭되는 History 문서에 fill_price 자동 업데이트
• 부분 체결을 누적(filled_qty/filled_notional)하여 fill_price를 가중평균으로 계산하고, status를 partial_filled/filled로 갱신

v0.4.0 추가 (요청 반영: “완성”)

• 거래 금지 시간 확장: 요일 허용 + 복수 세션(허용 구간) + 블랙아웃(금지 구간) + 휴장일(YYYY-MM-DD) 지원
• 실시간 소켓 구독 메시지 템플릿: 스펙이 다른 경우를 대비해 Settings에서 구독 메시지 템플릿을 직접 설정 가능
• 실시간 소켓 엄격 파서(필드맵): “00/04” 등의 코드별 필드명을 JSON 필드맵으로 지정하면 positions/last_fills/open_orders 상태 반영이 안정화
• 설정 내보내기/가져오기 보안 강화: 기본 내보내기는 APPKEY/SECRET, 텔레그램 토큰 등을 제외(옵션으로 포함 가능). Import는 누락된 민감정보를 기존 값으로 보존

• /realtime 화면 추가: 사용자별 rt_state(positions/open_orders/last_fills)와 raw 이벤트 조회
• Admin Users에 실시간 소켓 헬스 표시: connected/마지막 이벤트 시각/reconnects
• base 네비게이션에 Realtime 메뉴 추가, 버전 표기 동기화

실연동 범위 (v0.4.0)

• 현재가/우선호가: ka10004 (/api/dostk/mrkcond)
• 매도 주문: kt10001 (/api/dostk/ordr) - 시장가(trde_tp=3), 지정가(trde_tp=0)
• 모의투자/실거래 모드: API키 등록 화면에서 선택(토큰/호출 도메인이 달라집니다).

모의투자 도메인(mockapi)은 KRX만 지원합니다. 실거래(real)는 실제 계좌/주문이 실행되므로 반드시 소액/시간대 제한 등 안전장치를 추가하세요.

전체 구조

• src/web/: templates(static+Jinja) + API 라우팅
• src/db/: Mongo 연결/인덱스/리포지토리
• src/security/: 비밀번호 해시(bcrypt), API키 암호화(Fernet)
• src/kiwoom/: 키움 REST 연동
  • market_data/: 현재가/분봉 등 조회 전용
  • orders/: 주문 전용(시장가/현재가 지정가 등 타입별 파일)
• src/services/: 자동거래 엔진, 룰 평가, 텔레그램 알림, 로그(파일+WS)

MongoDB 스키마

• users: username(unique), password_hash, role, status, active_session_id
• sessions: _id=sid, data, expires_at(TTL index)
• user_settings: kiwoom(appkey_enc/secret_enc/token_cache), telegram(bot_token_enc/chat_id)
• trade_configs: 사용자별 BOX 설정(삭제는 soft-delete), is_enabled, version, config
• trade_history: 주문/체결 기록 + reason(trigger/details)

세션 인증(단일 로그인)

• 쿠키: sid
• 로그인 성공 시 sessions에 세션 저장 후 쿠키로 sid 발급
• users.active_session_id에 현재 sid 저장
• 새 로그인 발생 시 기존 sid 세션 삭제 → 기존 로그인 강제 종료
• 요청마다 users.active_session_id != sid 이면 세션 무효화

자동거래 엔진(v0.4.0)

• 3초마다 사용자(active) → enabled config를 순회
• 조회: market_data.quote.get_current_price, market_data.ohlc.get_avg_prices
• 룰 평가: services.rule_eval.evaluate (v0.4.0: 3/4/6 구현 + 엔진에서 7(현재가 변경매도) 스케줄)
• 주문: orders.market_sell 또는 orders.limit_sell
• 기록: trade_history 저장, LogBus로 파일+WS, 텔레그램 알림(옵션)

중요: TR 연결 TODO

v0.4.0에서는 “설정 수정(EDIT) + 룰 6(상승중 매도금지 비교구간) 고도화 + 룰 7(현재가 변경매도) 동작”까지 반영했습니다. 현재가/분봉/주문 TR은 mock로 동작합니다. 실거래 전, 다음 파일의 TODO 부분에 실제 TR(api-id/path/body)을 연결하세요:

• src/kiwoom/market_data/quote.py
• src/kiwoom/market_data/ohlc.py
• src/kiwoom/orders/market_sell.py
• src/kiwoom/orders/limit_sell.py

실행 방법

1. MongoDB 실행
2. cp .env.example .env 후 APP_SECRET/MONGO 설정
3. pip install -r requirements.txt
4. python app.py

v0.4.0 추가 사항

• TR 기본값 보강(실연동 시작점): src/kiwoom/tr_catalog.py에 차트(/api/dostk/chart, ka10079)/계좌(/api/dostk/acnt, kt00017) 기본값을 추가했습니다. (요청/응답 Body는 문서로 확정 필요)
• API키 화면에 잔고 테스트 추가: /settings/api에서 kt00017 호출 테스트를 할 수 있습니다. (필요 Body 필드가 있다면 추가 입력 후 확정)
• 거래설정 수정(Edit): BOX에서 Edit 클릭 → symbol/config(JSON) 수정 후 저장(버전 +1)
• 룰 평가 개선: 상승중 매도금지(규정 interval 전 가격과 비교) 지원
• 현재가 변경매도 스케줄: sell_order_type=limit_current 이고 dynamic_price_sell.enabled면 지정 seconds 후 현재가로 지정가 매도
• 중복 주문 방지: 같은 config에서 30초 내 재트리거 시 COOLDOWN 스킵
• 설정 키 정리: dynamic_sell → dynamic_price_sell (엔진은 하위호환으로 둘 다 인식)
• Panic Stop: /api/panic/on, /api/panic/off. user_settings.panic_stop.enabled가 켜지면 엔진이 모든 주문을 차단합니다.
• 장중 보호(시간): user_settings.market_protect.enabled가 켜져 있으면 open_time~close_time(종료 N분 전 차단 포함) 외 주문을 차단합니다.
• 리스크 제한(일 단위): user_settings.risk_limits.enabled가 켜져 있으면 일 최대 매도 횟수/금액을 초과할 때 주문을 차단합니다. auto_panic 옵션 시 한도 초과 시 Panic Stop을 자동 켭니다.
• 종목별 쿨다운: risk_limits_rule.enabled + symbol_cooldown_sec(설정/override)로 종목 단위 재주문을 제한합니다.