프로젝트 구조

시스템은 기존의 영작문 서버가 있는 미니 서버를 그대로 이용하기로 했다. 이유는 항상 켜져 있기 때문이다.

개발은 윈도우즈에서 VS Code를 사용한다. 이전 프로젝트 처럼 SSH로 서버에 접속하여 진행한다.

​

프로젝트 폴더 구조는 다음과 같이 일차적으로 설치했다.

 

stockserver/
├── engine/               # Core Engine 
│   └── core.py
├── web/                  # FastAPI Web server
│   ├── main.py
│   └── templates/
│       ├── base.html
│       └── dashboard.html
├── db/                   # SQLite DB Storage
│   └── stock.db
├── scripts/              # utillities
│   └── token_test.py
├── requirements.txt      # packages
└── README.md

 

 

1. 메인 프로그램: 백그라운드 주식 매매 매니저 (Core Engine)

• 항상 돌고 있는 주식 매매 로직 프로세스
• 개장 시간 체크 → 주기적 주가 조회 및 매매 판단
• 매수, 매도 API 요청
• 현재 상태를 내부 DB나 파일로 기록
• 실시간 데이터 업데이트

 

 

2. 웹 서버 (현황 조회용 Web API)

• FastAPI 같은 초경량 웹서버를 하나 별도로 띄운다
• 백엔드(Core Engine)와 데이터 공유
• 외부에서 접속하면
  • 현재 포지션
  • 매수/매도 기록
  • 수익 현황
  • 전체 리포트
    를 조회할 수 있다

3. 내부 저장소 (DB/파일)

• Core Engine과 Web Server가 함께 보는 데이터
• SQLite 같은 초경량 DB 

4. web page 기능

 

1) 대시보드 (/)

• 전체 계좌 손익 현황
• 현재 보유 중인 종목 수, 포지션 수
• 오늘 매수/매도 종목 리스트
• 경고/주의 메시지 (예: 특정 종목 N회 매수 도달 등)
• 전체 수익 그래프 (누적 수익, 실현 수익 등)

2) 종목 관리 (/stocks)

• 종목 추가: 종목코드, 속성(normal/reluctant), split 기준(optional)
• 종목 목록: 수정/삭제 기능  
• 정지/재개 여부 설정

3) 매매 이력 (/history)

• 매수/매도 시점, 수량, 단가, 실현 이익
• 필터: 종목별, 기간별 검색
• 다운로드(csv)

4) 상세보기 (/stocks/:code)

• 해당 종목의 현재 포지션 리스트
• 매수 단가, 수량, 현재가, 목표 매도가
• 개별 매수 회차별 이익률
• 해당 종목의 전략 설정 확인

5) 설정 (/settings)

• 기본 split 간격(a%), 매도 기준(b%) 설정값 표시
• 토큰 만료시간, 다음 갱신 시간 등 표시

 

가상 환경 설치

cd ~/stockserver
python3 -m venv venv
source venv/bin/activate

 

 

기본 패키지 설치 및 requirements 저장

pip install fastapi uvicorn requests jinja2 python-multipart
pip freeze > requirements.txt

 

 

requirements.txt를 미리 만들어 놓았다면, 다음과 같이 설치한다.

pip install -r requirements.txt

 

 

requirements 중에 Jinja2라는 것이 있다. Jinja2는 HTML 템플릿 엔진이다.

FastAPI, Flask 같은 웹 프레임워크에서 Python 코드와 HTML을 연결할 때 사용된다.

<h1>안녕하세요, {{ name }}님</h1>

 

여기에서 {{ name }}에 Python 코드에서 넘긴 값을 넣고 싶을 때, 그걸 처리해주는 게 Jinja2이다.

---

python-multipart는 FastAPI에서 HTML 폼(form) 데이터를 처리할 때 필요한 패키지이다.

웹페이지에서 <form method="post">를 사용할 때 브라우저는 데이터를 application/x-www-form-urlencoded 또는 multipart/form-data 형식으로 전송한다.특히 파일 업로드나 Form + 파일이 함께 전송될 때는 반드시 multipart/form-data 형식을 사용한다.

​

FastAPI는 내부적으로 python-multipart 라이브러리를 이용해 multipart/form-data를 파싱한다. 따라서 Form(...)이나 File(...) 같은 요청 파라미터를 처리하려면 이 패키지가 필요하다.

---

 

전체 실행 계획을 대충 정리해 보았다.

​

1 단계

• 가상환경 세팅
• API 키 확인 및 토큰 발급 받기
• API 테스트 하기
• 종목 관리용 DB 스키마 설계 (stocks, positions, orders)
• 초기 테스트용 SQLite DB 생성

​

2 단계

• /stocks 등록 페이지 구현 (FastAPI + Jinja2)
• 종목 목록 보기 / 활성화 여부 전환 / 삭제 처리 구현
• 종목 데이터 DB 연동 완료

​

3 단계

• Core Engine 골격 구성
• 주기적 시세 조회 (t1101, t1301 등)
• N split 매매 판단 로직
• 매수/매도 API 호출 구조만 뼈대 구현 (테스트용 dummy 처리 가능)
• 현재 상태 기록 (position 테이블)

​

4 단계

• 대시보드 구현 (/ 경로)
• 등록된 종목 수, 현재 보유 포지션, 누적 수익 등 표시
• 최근 매매 내역 표시
• Nginx /stock/ 설정 및 Basic Auth로 외부 접근 제한 완료
• systemd로 Core Engine + 웹 서버 백그라운드 구동

​

5단계

• 실제 API 연동 (소액 테스트)
• 로그 기록 및 리포트 생성 기능
• 알림(이메일 or 슬랙 or 텔레그램) 구조 기초