실제 사용 화면으로 프로젝트를 소개하는 README 개편

README.md

@@ -2,122 +2,75 @@
 
 # 눈금
 
-**국내 주식·ETF 자동매매와 계좌 관리**
+**국내 주식·ETF 자동매매 프로그램**
 
-정해 둔 비중에 맞춰 주식과 ETF를 사고팔고, 원금·수익률·보유 종목을 한 화면에서 확인하는 개인용 투자 도구입니다. 과거 데이터로 운용 규칙을 비교하고, 모의투자로 실제 동작을 점검할 수 있습니다.
+정해 둔 비중에 맞춰 주식과 ETF를 매매하고, 내가 넣은 돈과 투자로 생긴 수익을 나눠 보여 주는 개인용 투자 프로그램입니다. 과거 주가로 매매 규칙을 비교하고, 모의투자로 주문과 계좌 기록을 점검할 수 있습니다.
 
-![날짜 눈금으로 살펴보는 눈금의 실제 투자 기록](docs/images/dashboard-account-20260922.png)
+[설치하기](docs/GETTING_STARTED.md) · [검증 결과](docs/RISK_REVIEW_20260922.md) · [운용 설정](config/baskets.yaml)
 
-*2026년 9월 22일 모의투자 기록을 불러온 실제 화면입니다. 아래 백테스트와는 별도의 계좌 기록입니다.*
+![실제 계좌 화면에서 날짜를 바꾸고 입체·평면 차트를 전환하는 모습](docs/images/readme-walkthrough-20260922.gif)
 
-## 할 수 있는 일
+*2026년 9월 22일, 실제 모의투자 기록으로 촬영했습니다. [정지 화면 보기](docs/images/readme-account-20260922.png)*
 
-- **계좌 확인** — 총자산, 투자원금, 현금, 보유 종목과 목표 비중을 확인합니다.
-- **날짜별 성과 탐색** — 날짜 눈금을 움직이면 그날의 수익률·원금·평가금액이 함께 바뀝니다. 적립금은 수익에서 제외합니다.
-- **입체·평면 차트와 CSV** — 같은 투자 기록을 두 방식으로 살펴보고, 조회한 기간의 원본 수치를 내려받습니다.
-- **자동 리밸런싱** — 실제 비중이 설정 범위를 벗어나면 조정합니다. 최소 주문금액과 1주 단위를 반영합니다.
-- **모의투자 검증** — 운영 기록, 누락된 자산 기록, 거래비용과 미해결 주문을 확인합니다.
-- **운영 점검** — 자동매매 실행 여부, 거래 중지 상태, 증권사 연결과 데이터 갱신 상태를 봅니다.
+## 날짜를 바꾸면 그날의 계좌가 보입니다
 
-Python·aiohttp·SQLite·한국투자증권 KIS API를 사용합니다. 화면은 HTML/CSS/JavaScript로 만들었으며 프런트엔드 설치나 빌드 과정이 없습니다.
+날짜 눈금을 움직이면 **수익률·투자원금·평가금액**이 함께 바뀝니다. 적립한 돈은 원금에 반영하고, 수익률은 따로 계산합니다.
 
-## 화면
+입체·평면 차트는 같은 기록을 보여 줍니다. 입체 차트의 띠는 수익률 선에 폭을 준 표현입니다. 자세한 숫자는 일별 표에서 확인하거나 CSV로 내려받을 수 있습니다.
 
-### 날짜를 고르면 그날의 계좌가 보입니다
+## 무엇을 얼마나 보유했는지 확인합니다
 
-파란 차트의 띠는 실제 누적 수익률입니다. 날짜 눈금은 마우스·터치·방향키로 움직일 수 있습니다. 입체감은 선에 폭을 준 표현이며, 별도의 지표를 뜻하지 않습니다. 정확한 값은 평면 차트와 일별 기록 표에서도 확인할 수 있습니다.
+보유 수량과 평단가, 매입 비중과 목표 비중을 나란히 보여 줍니다. 계좌를 선택하면 요약·차트·종목표가 함께 바뀝니다. 설정한 범위를 벗어나면 매매 규칙에 따라 비중을 조정합니다.
 
-한글 글꼴은 로컬에서 읽고, 입체 표현은 가벼운 Canvas로 그립니다. 흰색·검정·코발트·시안의 역할과 참고한 실제 디자인 사례는 [화면 설계와 검증 기록](docs/DESIGN_20260922.md)에 정리했습니다.
+![대형주 계좌의 보유 종목, 매입 비중과 목표 비중](docs/images/readme-holdings-20260922.png)
 
-### 보유 종목과 비중
+*종목별 비중은 매입금액 기준입니다. 보유분 평가금액과 평가손익은 표 아래에서 확인할 수 있습니다.*
 
-매입금액과 목표 비중을 나란히 보여 줍니다. 계좌를 바꾸면 요약, 종목표, 차트, 적립금 입력 대상이 함께 바뀝니다.
+## 자동매매가 잘 돌아가는지도 확인합니다
 
-![대형주 분산 투자 계좌의 보유 종목과 투자 비중의 기준](docs/images/dashboard-holdings-20260922.png)
+마지막 실행 시각, 거래 중지 여부, 증권사 연결과 데이터 갱신 상태를 보여 줍니다. 확인이 필요한 일이 생기면 안내에서 해당 화면으로 이동할 수 있습니다.
 
-### 모바일과 운영 상태
+![자동매매 실행 시각, 거래 상태와 데이터 갱신을 확인하는 화면](docs/images/readme-operations-20260922.png)
 
-작은 화면에서도 잔액과 수익률을 먼저 보여 줍니다. 적립금은 계좌·금액·모의/실전 구분을 확인한 뒤 기록합니다. 모의투자 적립은 가상 계좌에만 반영됩니다.
+## 휴대폰에서도 같은 기록을 봅니다
 
-<details>
-<summary>모바일 화면 보기</summary>
+작은 화면에서는 수익률, 계좌 금액, 차트 순서로 표시합니다. 날짜 눈금은 터치로 움직일 수 있습니다.
 
-<img src="docs/images/dashboard-mobile-20260922.png" alt="모바일 투자 기록 — 날짜 탐색, 원금, 수익률, 보유 종목과 운영 상태" width="390">
+<a href="docs/images/dashboard-mobile-20260922.png"><img src="docs/images/readme-mobile-20260922.png" alt="모바일에서 보는 ETF 적립 계좌와 날짜별 수익률" width="300"></a>
 
-</details>
+[모바일 전체 화면 보기](docs/images/dashboard-mobile-20260922.png)
 
-<details>
-<summary>자동매매 상태 화면 보기</summary>
+## 현재 운용하는 모의투자 계좌
 
-![거래 안전, 장 상태, 자동매매와 데이터 갱신 확인](docs/images/dashboard-operations-20260922.png)
+| 계좌 | 투자 방식 |
+|---|---|
+| **ETF 적립** | KODEX 200과 TIGER CD금리 ETF에 분산합니다. 시작 자금 30만원, 월 적립 계획 10만원입니다. |
+| **대형주 분산 투자** | 국내 대형주에 분산하고 주식 60%·현금 40%를 목표로 운용합니다. 비중이 크게 벗어나면 조정합니다. |
 
-</details>
+ETF 적립 계좌는 추세와 낙폭에 따라 주식 비중을 줄이고, 줄인 금액을 CD금리 ETF에 배분합니다. 1주 가격과 최소 주문금액 때문에 소액 계좌의 실제 비중은 목표와 다를 수 있습니다.
 
-## 기본 운용 구성
+화면에 표시된 모의투자와 과거 데이터를 이용한 백테스트는 구분해서 확인할 수 있습니다. 백테스트는 수익률뿐 아니라 **최대 낙폭·매매비용·기간별 결과**를 함께 비교합니다. [비교 조건과 전체 결과 보기](docs/RISK_REVIEW_20260922.md)
 
-| 계좌 | 구성과 역할 | 현재 상태 |
-|---|---|---|
-| ETF 적립 | KODEX 200 + TIGER CD금리 ETF. 시작 30만원, 매월 10만원 적립 | 변경한 위험 관리 규칙을 모의투자로 검증 중 |
-| 대형주 분산 투자 | 국내 대형주 9종목. 주식 60%·현금 40%, 큰 비중 이탈 시 조정 | 기존 규칙으로 모의투자 운용 |
+**모의투자와 과거 성과는 앞으로의 수익을 보장하지 않습니다.** CD금리 ETF도 원금 보장 상품은 아닙니다. ETF 적립 계좌는 현재 모의투자 전용이며, 실전 전환에는 별도의 설정과 검증이 필요합니다.
 
-ETF 적립의 기본 목표는 주식 ETF 47.5%·CD금리 ETF 47.5%·현금 5%입니다. 방어 조건에 들어가면 주식 ETF 목표를 23.75%로 낮추고, 줄인 만큼을 CD금리 ETF에 배분합니다. 소액 계좌는 1주 가격과 최소 주문금액 때문에 실제 비중이 목표와 다를 수 있습니다. CD금리 ETF도 원금 보장 상품은 아닙니다.
+## 내 PC에서 시작하기
 
-설정은 [config/baskets.yaml](config/baskets.yaml)에 있습니다. 실전 주문에는 별도의 활성화와 검증이 필요하며, ETF 적립 계좌는 `paper_only: true`로 실전 전환을 제한하고 있습니다.
-
-## 위험 관리 검증
-
-적립금이 들어오면 낙폭이 작아 보이던 백테스트 계산을 고쳤습니다. 이어서 추세·낙폭 조건이 겹칠 때 비중을 중복해서 줄이지 않고, 주식 축소분을 기존 CD금리 ETF로 옮기도록 바꿨습니다.
-
-![동일 기간·비용으로 비교한 세 가지 운용 방식의 수익과 낙폭](docs/images/risk-review-20260922.png)
-
-**2020-07-07~2026-09-17, 실제 ETF 종가·1주 단위·월 10만원 적립 비교**
-
-9월 22일 수집 자료에서 지수 종가가 17일까지 제공되어, 모든 자료가 있는 17일까지 비교했습니다. ETF에만 있는 18일·21일 기록을 섞어 기간을 늘리지 않았습니다.
-
-| 방식 | 연환산 수익률 | 최대 낙폭 | 샤프² |
-|---|---:|---:|---:|
-| 고정 비중 | 13.53% | -21.72% | 0.79 |
-| 기존 위험 관리¹ | 10.73% | -16.02% | 0.74 |
-| 변경한 위험 관리 | 12.96% | -15.74% | 0.90 |
-
-¹ 기존 방식도 적립금 계산 오류를 수정한 뒤 같은 조건으로 다시 계산했습니다. ² 샤프 계산의 기준금리는 연 3%로 고정했습니다.
-
-변경한 방식은 이 전체 기간에서 기존 방식보다 수익률이 높고 최대 낙폭이 작았습니다. **고정 비중보다 수익률은 낮았고, 2023~2025년에는 기존 방식보다 낙폭이 컸습니다.** 수수료·슬리피지와 CD ETF의 보수적 세금 근사를 반영했지만, ETF 분배금·실시간 호가·미체결은 재현하지 못했습니다. 이미 살펴본 과거 자료로 비교한 결과이며 향후 수익을 보장하지 않습니다.
-
-9월 22일에는 오래된 시세로 주식 비중을 다시 늘리던 가능성을 막고, 모의·실전 계좌의 위험 판단 기록을 분리했습니다. 백테스트 계산도 같은 일별 결과를 유지하면서 빨라졌습니다. [최신 검증과 자료 기준일](docs/RISK_REVIEW_20260922.md), [운용 규칙을 변경한 근거](docs/RISK_REVIEW_20260917.md)에서 결과와 한계를 확인할 수 있습니다.
-
-## 시작하기
-
-Python 3.11 또는 3.12를 사용합니다. 아래는 Windows PowerShell 기준입니다.
+Python 3.11 또는 3.12를 사용합니다. 처음 설치했다면 [설치 안내](docs/GETTING_STARTED.md)에 따라 환경을 준비한 뒤 실행하세요. 아래 명령은 화면을 여는 용도이며, 자동매매 실행은 별도입니다.
 
 ```powershell
-git clone https://github.com/easygap/quant_trader.git
-cd quant_trader
-python -m venv .venv
-.\.venv\Scripts\python.exe -m pip install -r requirements.txt
-Copy-Item config/settings.yaml.example config/settings.yaml
-Copy-Item .env.example .env
 .\.venv\Scripts\python.exe main.py --mode dashboard
 ```
 
-브라우저에서 [127.0.0.1:8080](http://127.0.0.1:8080)을 엽니다. 새로 설치한 계좌에는 기록이 없습니다. 설정의 `trading.mode`가 `paper`인지 확인한 뒤 아래 순서로 모의투자를 실행할 수 있습니다.
-
-```powershell
-# 주문 계획만 확인
-.\.venv\Scripts\python.exe main.py --mode rebalance --basket kr_pocket --dry-run
-
-# 모의투자 실행과 자산 기록
-.\.venv\Scripts\python.exe main.py --mode rebalance --basket kr_pocket
-
-# 같은 조건으로 백테스트 재현
-.\.venv\Scripts\python.exe tools/risk_review.py --as-of 2026-09-22
-```
+브라우저에서 **[127.0.0.1:8080](http://127.0.0.1:8080)**을 엽니다. 새로 설치한 계좌에는 아직 기록이 없습니다. 첫 모의투자 실행과 설정 방법도 설치 안내에 정리했습니다.
 
-매일 자동 실행하려면 `main.py --mode schedule`을 사용합니다. KIS API 키 등 개인 설정은 `.env`에 넣고 Git에는 올리지 않습니다. 대시보드는 계좌 정보를 표시하므로 기본 설정대로 이 PC에서만 접속해 사용합니다.
+## 더 알아보기
 
-## 자세히 보기
+| 궁금한 내용 | 안내 |
+|---|---|
+| 설치와 첫 모의투자 실행 | [시작하기](docs/GETTING_STARTED.md) |
+| 과거 성과와 검증의 한계 | [위험 관리 검증](docs/RISK_REVIEW_20260922.md) |
+| 실전 주문을 사용하기 전 확인할 것 | [실전 전환 절차](docs/PAPER_TO_LIVE_RUNBOOK.md) · [거래 안전장치](docs/SAFETY_MODEL.md) |
+| 화면 디자인과 성능 | [화면 설계](docs/DESIGN_20260922.md) |
+| 코드와 설정 구조 | [개발 문서](docs/PROJECT_GUIDE.md) |
 
-- [위험 관리 검증과 한계](docs/RISK_REVIEW_20260922.md)
-- [화면 설계·참고한 디자인·성능 측정](docs/DESIGN_20260922.md)
-- [모의투자 평가 기준](docs/BASKET_PAPER_EVALUATION.md) · [실전 전환 절차](docs/PAPER_TO_LIVE_RUNBOOK.md)
-- [거래 안전장치](docs/SAFETY_MODEL.md) · [프로젝트 구조](docs/PROJECT_GUIDE.md)
+Python · aiohttp · SQLite · 한국투자증권 KIS API를 사용합니다. 화면은 HTML/CSS/JavaScript로 만들었으며, 별도의 프런트엔드 설치나 빌드 과정은 없습니다.

docs/GETTING_STARTED.md

@@ -0,0 +1,81 @@
+# 눈금 시작하기
+
+눈금은 내 PC에서 실행하는 국내 주식·ETF 자동매매 프로그램입니다. 먼저 화면을 열어 설정을 확인하고, 모의투자로 계좌 기록을 쌓을 수 있습니다.
+
+아래 명령은 **Windows PowerShell, Python 3.11 또는 3.12** 기준입니다. Python과 Git이 설치되어 있어야 합니다.
+
+## 설치
+
+```powershell
+git clone https://github.com/easygap/quant_trader.git
+cd quant_trader
+python -m venv .venv
+.\.venv\Scripts\python.exe -m pip install -r requirements.txt
+```
+
+개인 설정 파일을 만듭니다. 이미 파일이 있으면 기존 설정을 유지합니다.
+
+```powershell
+if (-not (Test-Path config/settings.yaml)) {
+    Copy-Item config/settings.yaml.example config/settings.yaml
+}
+if (-not (Test-Path .env)) {
+    Copy-Item .env.example .env
+}
+```
+
+`config/settings.yaml`에서 `trading.mode`가 `paper`인지 확인하세요. 예제 파일의 기본값은 모의투자입니다. KIS API 키와 계좌번호 등 개인 정보는 `.env`에 입력하며, 이 파일은 Git에 올리지 않습니다. 실계좌 연결 설정은 [실전 전환 절차](PAPER_TO_LIVE_RUNBOOK.md)에서 따로 다룹니다.
+
+## 계좌 화면 열기
+
+```powershell
+.\.venv\Scripts\python.exe main.py --mode dashboard
+```
+
+브라우저에서 [127.0.0.1:8080](http://127.0.0.1:8080)을 엽니다. 이 명령은 계좌를 보여 주는 웹 서버를 실행합니다. 자동매매는 별도로 실행해야 합니다.
+
+처음 설치한 계좌에는 기록이 없으므로 빈 화면 안내가 나옵니다. README의 캡처는 이미 운용 중인 모의투자 계좌의 실제 기록입니다. 설치만으로 같은 금액과 수익률이 채워지는 것은 아닙니다.
+
+기본 접속 주소는 이 PC에서만 열립니다. 포트를 바꾸려면 다음처럼 실행합니다.
+
+```powershell
+.\.venv\Scripts\python.exe main.py --mode dashboard --dashboard-port 8081
+```
+
+## 첫 모의투자 실행
+
+계좌 구성은 [config/baskets.yaml](../config/baskets.yaml)에 있습니다. `kr_pocket`은 ETF 적립 계좌, `kr_diversified_hold`는 대형주 분산 계좌입니다.
+
+먼저 주문 계획만 확인합니다. 가격 자료를 조회하므로 인터넷 연결이 필요합니다.
+
+```powershell
+.\.venv\Scripts\python.exe main.py --mode rebalance --basket kr_pocket --dry-run
+```
+
+설정과 계획을 확인한 뒤, **`trading.mode: paper` 상태에서** 같은 계좌의 모의투자를 실행할 수 있습니다.
+
+```powershell
+.\.venv\Scripts\python.exe main.py --mode rebalance --basket kr_pocket
+```
+
+화면을 새로고침하면 생성된 계좌 기록을 확인할 수 있습니다. 가격 자료나 주문 조건을 확인하지 못하면 실행을 보류할 수 있으며, 이유는 터미널과 운영 기록에 표시됩니다.
+
+계좌 화면의 **적립금 기록**은 추가한 투자금을 원금에 반영하는 기능입니다. 모의투자에서는 가상 자금을 더하며, 실제 은행 계좌에서 돈을 이체하지 않습니다. 계좌·금액·모의/실전 구분을 확인한 뒤 기록하세요.
+
+## 과거 데이터로 비교하기
+
+```powershell
+.\.venv\Scripts\python.exe tools/risk_review.py --as-of 2026-09-22
+```
+
+결과는 `reports/research/risk_review_20260922.json`, 그래프는 `docs/images/risk-review-20260922.png`에 저장됩니다. 이 명령은 과거 종가로 비교하며 주문을 내지 않습니다. 날짜를 바꾸면 파일 이름도 해당 날짜로 바뀝니다.
+
+자료마다 마지막 제공일이 다르면 모든 자료가 있는 날짜까지만 비교합니다. 9월 22일 조사에서는 지수 자료가 17일까지 제공되어 17일이 비교 종료일입니다. 수익률, 비용 가정과 한계는 [검증 보고서](RISK_REVIEW_20260922.md)에 정리했습니다.
+
+## 계속 운용하려면
+
+- 자동 실행과 설정 구조: [프로젝트 가이드](PROJECT_GUIDE.md)
+- 실전 전환과 주문 제한: [실전 전환 절차](PAPER_TO_LIVE_RUNBOOK.md)
+- 오류나 거래 중지 시 확인할 것: [거래 안전장치](SAFETY_MODEL.md)
+
+[README로 돌아가기](../README.md)