Metadata-Version: 2.4
Name: tossinvest-web
Version: 0.1.1
Summary: Local web dashboard for tossinvestsdk
Author: HG
Keywords: toss,tossinvest,trading,dashboard,web
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi<1,>=0.116
Requires-Dist: tossinvest-strategy>=0.2.1
Requires-Dist: uvicorn[standard]<1,>=0.35

# tossinvest-web 📊

로컬에서 실행하는 TossInvest 전략 대시보드입니다. 계좌 보유 종목, 전략 상태,
사이클 진행 상황, 거래 이력을 하나의 브라우저 화면에서 확인합니다.

`tossinvest-web`은 단독 제품이 아닙니다. Toss Open API 연동과 전략 실행 기반은
**[tossinvest-strategy](https://pypi.org/project/tossinvest-strategy/)** 가 담당하며,
이 패키지는 그 결과를 읽고 관리하기 위한 웹 인터페이스를 제공합니다.

## 🧩 패키지 관계

```text
Toss Open API
    |
tossinvest-strategy (필수)
    |- 인증, 토큰 갱신, 계좌/시세 API
    |- 전략 실행, strategy_state/ 및 trade_history/ 관리
    |
tossinvest-web
    |- 계좌/보유 종목 대시보드
    |- 전략 및 Cycle 현황 시각화
    |- 거래 이력 조회, VR 수동 기록 입력
```

`tossinvest-web`을 설치하면 `tossinvest-strategy>=0.2.1`도 자동으로 설치됩니다.
웹 대시보드는 전략을 대신 실행하지 않습니다. 전략 실행으로 생성된 로컬 상태와
거래 이력을 보여 주며, 계좌 조회는 `tossinvest-strategy`의 Toss Open API 클라이언트를
통해 이뤄집니다.

## 🖼️ 스크린샷

### 포트폴리오

![개인 정보를 가린 포트폴리오 대시보드](https://raw.githubusercontent.com/choco0908/TossAutoTradingSystem/master/tossinvest-web/docs/images/dashboard-redacted.png)

### 전략 현황

![개인 정보를 가린 전략 현황 대시보드](https://raw.githubusercontent.com/choco0908/TossAutoTradingSystem/master/tossinvest-web/docs/images/strategy-overview-redacted.png)

위 화면의 금액, 수익, 종목, 수량은 공개용으로 블라인드 처리한 예시입니다. 실제
실행 시에는 사용자의 로컬 계좌 및 전략 데이터가 표시됩니다.

## 📦 설치

```bash
pip install tossinvest-web
```

위 명령은 필수 기반 패키지인 `tossinvest-strategy`를 함께 설치합니다. 전략 SDK를
먼저 명시적으로 설치하려면 다음과 같이 실행할 수 있습니다.

```bash
pip install "tossinvest-strategy>=0.2.1" tossinvest-web
```

이 저장소에서 개발 설치할 때는 SDK와 웹 패키지를 모두 editable 모드로 설치합니다.

```bash
pip install -e .
pip install -e packages/tossinvest-web
```

## 🚀 빠른 시작

### 1. 🔐 Toss Open API 인증 파일 준비

로컬 데이터 디렉터리를 만들고 Toss Open API 자격 증명을 `credentials` 파일에
저장합니다. `tossinvest-strategy`는 첫 인증 요청 후 `token.json`을 생성하고 갱신합니다.

```text
my-tossinvest/
  credentials
  token.json                 # 로컬 생성 파일, 커밋 금지
  strategy_state/            # 전략 실행 시 생성되는 상태 파일
  trade_history/             # 전략 체결 이력 또는 수동 기록
```

`credentials` 형식은 다음과 같습니다.

```text
client_id: your_client_id
client_secret: your_client_secret
account_number: your_account_number
```

### 2. ⚙️ 전략 실행 또는 기존 상태 준비

`tossinvest-strategy`로 전략을 실행하면 `strategy_state/`와 `trade_history/`에
대시보드가 읽을 수 있는 로컬 데이터가 만들어집니다. 전략을 아직 실행하지 않아도
계좌와 보유 종목은 조회할 수 있으며, 전략 섹션에는 상태 파일이 없다는 안내가 표시됩니다.

전략 구성과 실행 방법은
[tossinvest-strategy 프로젝트](https://pypi.org/project/tossinvest-strategy/)를 참고하세요.

### 3. 🌐 웹 대시보드 실행

로컬 데이터 디렉터리에서 다음 명령을 실행합니다.

```bash
tossinvest-web --host 127.0.0.1 --port 8000
```

브라우저에서 [http://127.0.0.1:8000](http://127.0.0.1:8000)을 엽니다.

개발 중 Python 또는 정적 파일 변경 시 자동 재시작하려면 `--reload`를 사용합니다.

```bash
tossinvest-web --host 127.0.0.1 --port 8000 --reload
```

## 🧭 주요 화면

- **Portfolio**: Toss Open API를 통해 계좌 요약과 보유 종목을 조회합니다. 환율 환산은
  기본적으로 꺼져 있으며 대시보드에서 선택할 수 있습니다.
- **Strategy Overview**: 로컬 전략 상태를 전략 단위와 실행 항목 단위로 나눠 실현 손익,
  보유 원가, 수량, 회수액과 운영 상태를 표시합니다.
- **Cycle Map**: Cycle 기반 전략의 매수 진행, 매도 대기, 완료 상태를 한눈에 확인합니다.
- **Value Rebalancing**: 다른 증권사에서 수동으로 운영하는 VR 전략의 체결, 목돈 추가,
  다음 Cycle 예약과 주문 가이드를 기록합니다.
- **Daily Trade Log**: 로컬 거래 이력을 날짜 범위로 필터링해 확인합니다.

자동 새로고침 주기, 선택한 탭, 정렬 기준, 필터는 브라우저에 저장되어 다음 실행 시에도
복원됩니다.

## 📱 다른 기기에서 보기

같은 Wi-Fi 또는 사설 네트워크의 다른 기기에서 보려면 모든 로컬 네트워크 인터페이스에
바인딩합니다.

```bash
tossinvest-web --host 0.0.0.0 --port 8000
```

다른 기기에서 `http://<내-컴퓨터-IP>:8000`을 엽니다. 방화벽은 신뢰하는 사설
네트워크에만 허용하고, 이 서버를 공용 인터넷에 직접 노출하지 마세요.

## 📁 데이터 디렉터리와 환경 변수

기본값은 명령을 실행한 현재 디렉터리입니다. SDK 파일을 다른 위치에 둘 경우 다음
환경 변수를 사용할 수 있습니다.

```text
TOSSINVEST_DATA_DIR=C:\\path\\to\\my-tossinvest
TOSSINVEST_CREDENTIAL_FILE=C:\\path\\to\\credentials
TOSSINVEST_TOKEN_FILE=C:\\path\\to\\token.json
```

`TOSSINVEST_DATA_DIR` 하나만 설정해도 그 아래의 `credentials`, `token.json`,
`strategy_state/`, `trade_history/`를 함께 찾습니다.

## 🔒 보안 유의사항

- `credentials`, `token.json`, `strategy_state/`, `trade_history/`는 공개 저장소와
  공유 폴더에 넣지 마세요.
- 웹 패키지는 로컬 대시보드이며 인증 정보나 이력을 외부 서비스로 전송하지 않습니다.
- 실제 주문과 전략 실행은 `tossinvest-strategy` 및 사용자의 전략 실행 환경에서
  관리됩니다. 실계좌 사용 전에는 충분한 검증이 필요합니다.
