SYSTEM BLUEPRINT

비트코인 주문 실행 엔진
운영자 대시보드 스토리보드

신호가 들어와 주문이 한 번만 나가고, 장애 뒤에도 계좌와 맞춰지는 과정을 운영 화면으로 보여줍니다.

스토리보드란?

스토리보드는 서비스의 화면을 실제 모습에 가깝게 미리 그려 보는 문서입니다. 발주자가 대시보드에서 확인할 화면을 운영 순서대로 배치했습니다.

  1. 전략이 보낸 주문 지시가 들어와 중복 없이 주문·체결되는 것을 확인하는 흐름
  2. 장애가 나도 자동 재시작 후 거래소 실제 계좌와 대사되고, 알림을 받는 흐름
  3. 모의 계좌 시나리오를 모두 통과한 뒤 실거래로 전환하는 흐름

마지막까지 보시면 생각하고 계신 시스템의 모습이 머릿속에 그려지실 것입니다.

운영자(발주자) 시나리오

주문 엔진 운영 여정

신호 수신부터 실거래 전환까지, 발주자가 대시보드에서 확인하는 다섯 단계입니다.

1. 신호 수신

전략이 웹훅으로
주문 지시 전송

2. 중복 차단

같은 신호 ID는
기존 주문으로 반환

3. 주문·체결

OKX·Bitget 주문
체결 상태 동기화

4. 장애 복구

재시작 후 계좌 대사
텔레그램 알림

5. 실거래 전환

모의 시나리오 통과 뒤
실거래 모드 켜기

운영자(발주자) | 화면 01

주문 현황과 중복 차단

console.order-engine.local/orders
주문 엔진 콘솔
● 엔진 실행 중모의 계좌운영자 · 발주자 계정
개요
주문 현황
신호 수신
복구·오류 로그
계좌·포지션
실거래 전환
연결 거래소
OKX · Bitget
신호 수신부터 체결까지 · 오늘 14:32 기준
주문 현황과 중복 차단
같은 신호 ID = 같은 주문번호
신호 sig-20260916-0412수신 3회
{ "signal_id": "sig-20260916-0412",
 "exchange": "okx", "symbol": "BTC-USDT-SWAP",
 "side": "buy", "type": "limit", "size": "0.015",
 "price": "63,480.5" }
웹훅 수신 · 신규 신호 → 주문 생성
14:32:07.118
주문 생성
웹훅 재수신 · 같은 신호 ID → 기존 주문 반환
14:32:07.402
중복 차단
전략 재시도 · 같은 신호 ID → 기존 주문 반환
14:32:09.955
중복 차단
거래소로 나간 주문1건
클라이언트 주문번호s0412a7f3c9e1
거래소OKX · BTC-USDT-SWAP
주문매수 지정가 0.015 BTC
체결0.009 / 0.015
상태 동기화WebSocket 14:32:11
부분 체결중복 2회 차단
시각거래소종목주문수량(BTC)가격(USDT)상태
14:32OKXBTC-USDT-SWAP매수 지정가0.01563,480.5부분 체결
14:05BitgetBTCUSDT매도 지정가0.02063,912.0체결 완료
13:47OKXBTC-USDT-SWAP매수 지정가0.01062,975.0취소됨
13:12BitgetBTCUSDT매수 시장가0.00863,104.2주문 실패

[화면 개요 및 목적]

신호 한 건이 몇 번 들어왔는지, 그중 몇 번이 차단됐고 거래소로는 실제 몇 건이 나갔는지를 한 화면에서 봅니다. 아래 표에서 진행 중·체결·취소·실패 주문을 함께 확인합니다.

[핵심 기능 로직]

제안서의 '주문번호 고정'이 구현된 화면입니다. 신호 ID로 클라이언트 주문번호를 만들고 DB 고유 제약을 걸어, 재수신·재시도는 새 주문 대신 기존 주문을 돌려줍니다. 데모 1단계에서 직접 확인합니다.

  • 같은 신호 주문 1건
    clOrdId · clientOid + DB 고유 제약
  • 체결 상태 실시간 반영
    거래소 WebSocket 주문 채널
운영자(발주자) | 화면 02

복구·오류 로그

console.order-engine.local/recovery
주문 엔진 콘솔
● 엔진 실행 중모의 계좌운영자 · 발주자 계정
개요
주문 현황
신호 수신
복구·오류 로그
계좌·포지션
실거래 전환
연결 거래소
OKX · Bitget
프로세스 종료 → 자동 재시작 → 계좌 대사
복구·오류 로그
신규 신호 처리 중
엔진 가동
6일 3시간
마지막 재시작 14:32:21
오늘 받은 신호
38건
중복 차단 7건
주문 실패
1건
알림 발송 완료
미확정 주문
0건
대사 완료
재시작 복구 기록다운타임 9초
14:32:15
프로세스 비정상 종료 감지
컨테이너 재시작 정책 동작
장애
14:32:21
엔진 재시작 · 신규 신호 보류
미확정 주문 1건 발견
복구 중
14:32:22
OKX 주문 조회 (clOrdId)
체결 0.009 / 0.015 BTC 확인
확인 완료
14:32:23
잔고·포지션 대사
포지션 0.009 BTC · 원장과 일치
일치
14:32:24
신규 신호 처리 재개
텔레그램 복구 알림 발송
재개
엔진 원장 ↔ 거래소 실제
항목엔진거래소결과
BTC 포지션0.0090.009
USDT 가용4,128.374,128.37
미체결 주문1건1건
체결 수량0.0090.009
대사 결과
4 / 4 일치
오류·알림 로그 알림 채널: 텔레그램
13:12:40Bitget주문 실패 · 최소 주문 수량 미달텔레그램 발송조치 필요
11:03:18OKXWebSocket 재연결 (3회 시도)자동 해결해결
09:41:02신호서명 불일치 신호 거절기록만무시됨

[화면 개요 및 목적]

프로세스가 죽었다 살아난 뒤 무엇을 확인했는지 시간순으로 남고, 엔진 원장과 거래소 실제 잔고·포지션·미체결 주문을 나란히 비교합니다. 주문 실패·재연결 같은 오류와 알림 발송 여부도 여기서 봅니다.

[핵심 기능 로직]

재시작하면 신규 신호를 잠시 보류하고, 미확정 주문을 클라이언트 주문번호로 조회해 부분 체결까지 반영합니다. 대사가 모두 일치해야 처리를 재개합니다. 데모 2·3단계와 연결됩니다.

  • 죽어도 자동 재시작
    Docker 재시작 정책 + 헬스체크
  • 장애 즉시 휴대폰 알림
    텔레그램 Bot API
운영자(발주자) | 화면 03

계좌 현황과 실거래 전환

console.order-engine.local/go-live
주문 엔진 콘솔
● 엔진 실행 중모의 계좌운영자 · 발주자 계정
개요
주문 현황
신호 수신
복구·오류 로그
계좌·포지션
실거래 전환
연결 거래소
OKX · Bitget
모의(데모 트레이딩) 검증 → 실거래
계좌 현황과 실거래 전환
시나리오 1개 남음
모의 계좌 장애 시나리오5 / 6
같은 신호 3회 수신 → 주문 1건통과
전송 후 응답 끊김 → 조회로 확정통과
체결 중 강제 종료 → 재시작 대사통과
부분 체결 후 취소 → 잔량 정리통과
주문 실패 → 텔레그램 알림통과
실거래 주문 한도 설정 (1회 0.02 BTC)확인 대기
실거래 모드 켜기
긴급 정지
잔고·포지션
OKX모의 계좌USDT 가용4,128.37
OKXBTC 포지션0.009 롱
Bitget모의 계좌USDT 가용2,764.90
BitgetBTC 포지션없음
평가 손익 (OKX BTC-USDT-SWAP)
+3.42 USDT
진입 63,471.2 · 현재 63,851.6
API 키: 출금 권한 없음IP 제한 서버 1개키 보관 서버 환경변수계정 단위 분리 · 다중 사용자 확장 대비

[화면 개요 및 목적]

OKX·Bitget 계좌의 잔고와 보유 포지션을 보고, 모의 계좌에서 장애 시나리오를 몇 개 통과했는지 확인합니다. 모두 통과해야 실거래 모드 버튼이 열리고, 긴급 정지는 항상 누를 수 있습니다.

[핵심 기능 로직]

제안서의 '모의 통과 후 실거래'를 화면으로 강제합니다. 시나리오 결과는 테스트 문서로 그대로 인계되고, 계좌는 계정 단위로 분리해 이후 다중 사용자로 넓힐 수 있게 합니다. 데모 4단계와 연결됩니다.

  • 실거래 전 안전 확인
    데모 트레이딩 + pytest 시나리오
  • 출금 불가 API 키
    권한 최소화 + IP 제한
시나리오

| 화면 01

[화면 개요 및 목적]

[핵심 기능 로직]

    | 화면 02

    [화면 개요 및 목적]

    [핵심 기능 로직]

      | 화면 03

      [화면 개요 및 목적]

      [핵심 기능 로직]

        시나리오

        | 화면 01

        [화면 개요 및 목적]

        [핵심 기능 로직]

          | 화면 02

          [화면 개요 및 목적]

          [핵심 기능 로직]

            | 화면 03

            [화면 개요 및 목적]

            [핵심 기능 로직]