easygap · easygap · Sep 22, 2026 · Sep 22, 2026 · Sep 22, 2026 · Sep 22, 2026
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,27 @@
+name: 오류 제보
+description: 실행이 안 되거나 화면·계산 결과가 이상할 때 알려 주세요.
+title: "[오류] "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        문제가 생긴 상황을 알려 주세요. 화면이나 로그를 올릴 때는 계좌번호, API 키, 비밀번호를 지워 주세요.
+  - type: textarea
+    id: problem
+    attributes:
+      label: 어떤 문제가 생겼나요?
+      description: 어떤 작업을 했고, 어떤 결과가 나왔는지 적어 주세요.
+      placeholder: 계좌 화면에서 CSV 저장을 눌렀는데 파일이 내려받아지지 않습니다.
+    validations:
+      required: true
+  - type: input
+    id: environment
+    attributes:
+      label: 사용 환경
+      description: 아는 항목만 적어 주셔도 됩니다.
+      placeholder: Windows 11 / Python 3.12 / Chrome / 모의투자
+  - type: textarea
+    id: details
+    attributes:
+      label: 오류 메시지나 화면
+      description: 문제가 생긴 화면을 붙여 넣거나, 터미널에 나온 메시지를 적어 주세요.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,17 @@
+name: 기능 제안
+description: 필요한 기능이나 사용하면서 불편했던 점을 알려 주세요.
+title: "[제안] "
+body:
+  - type: textarea
+    id: request
+    attributes:
+      label: 어떤 기능이 필요한가요?
+      description: 언제 필요했는지, 지금은 어떻게 하고 있는지도 알려 주시면 도움이 됩니다.
+      placeholder: 두 계좌의 수익률을 같은 차트에서 비교하고 싶습니다.
+    validations:
+      required: true
+  - type: textarea
+    id: reference
+    attributes:
+      label: 참고할 화면이나 예시
+      description: 참고할 만한 화면이나 링크가 있으면 남겨 주세요. 없어도 괜찮습니다.
diff --git a/README.md b/README.md
@@ -4,73 +4,96 @@
 
 **국내 주식·ETF 자동매매 프로그램**
 
-정해 둔 비중에 맞춰 주식과 ETF를 매매하고, 내가 넣은 돈과 투자로 생긴 수익을 나눠 보여 주는 개인용 투자 프로그램입니다. 과거 주가로 매매 규칙을 비교하고, 모의투자로 주문과 계좌 기록을 점검할 수 있습니다.
+한국투자증권 KIS API를 지원하는 Python 프로그램입니다. 설정한 종목과 비중에 따라 자동으로 매매하고, 웹 화면에서 투자금과 수익률을 확인합니다. 기본 설정은 모의투자입니다.
 
-[설치하기](docs/GETTING_STARTED.md) · [검증 결과](docs/RISK_REVIEW_20260922.md) · [운용 설정](config/baskets.yaml)
+[설치 방법](#설치-및-실행) · [백테스트 결과](docs/RISK_REVIEW_20260922.md) · [문의](https://github.com/easygap/quant_trader/issues/new/choose)
 
-![실제 계좌 화면에서 날짜를 바꾸고 입체·평면 차트를 전환하는 모습](docs/images/readme-walkthrough-20260922.gif)
+![계좌에서 날짜별 수익률을 확인하고 차트 모양을 바꾸는 모습](docs/images/readme-walkthrough-20260922.gif)
 
-*2026년 9월 22일, 실제 모의투자 기록으로 촬영했습니다. [정지 화면 보기](docs/images/readme-account-20260922.png)*
+2026년 9월 22일에 촬영한 모의투자 화면입니다. [이미지로 보기](docs/images/readme-account-20260922.png)
 
-## 날짜를 바꾸면 그날의 계좌가 보입니다
+## 주요 기능
 
-날짜 눈금을 움직이면 **수익률·투자원금·평가금액**이 함께 바뀝니다. 적립한 돈은 원금에 반영하고, 수익률은 따로 계산합니다.
+- **계좌 조회**: 투자원금, 평가금액, 수익률을 날짜별로 확인하고 CSV로 저장합니다.
+- **자동매매**: 정해 둔 종목과 비중에 맞춰 매수·매도합니다. 주문 전에 잔고와 거래 한도를 확인합니다.
+- **모의투자**: 가상 자금으로 매매해 보고, 주문 내역과 수익률을 확인합니다.
+- **백테스트**: 과거 주가로 매매 규칙을 시험하고 수익률, 손실, 거래 비용을 비교합니다.
 
-입체·평면 차트는 같은 기록을 보여 줍니다. 입체 차트의 띠는 수익률 선에 폭을 준 표현입니다. 자세한 숫자는 일별 표에서 확인하거나 CSV로 내려받을 수 있습니다.
+계좌에 돈을 추가로 넣어도 수익률이 부풀려지지 않도록 계산합니다. 차트 아래에서 날짜를 고르면 그날의 투자금과 수익률이 함께 바뀝니다.
 
-## 무엇을 얼마나 보유했는지 확인합니다
+## 설치 및 실행
 
-보유 수량과 평단가, 매입 비중과 목표 비중을 나란히 보여 줍니다. 계좌를 선택하면 요약·차트·종목표가 함께 바뀝니다. 설정한 범위를 벗어나면 매매 규칙에 따라 비중을 조정합니다.
+**Python 3.11 또는 3.12와 Git**이 필요합니다. 아래는 Windows PowerShell 기준입니다.
 
-![대형주 계좌의 보유 종목, 매입 비중과 목표 비중](docs/images/readme-holdings-20260922.png)
+```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
+
+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
+}
+
+.\.venv\Scripts\python.exe main.py --mode dashboard
+```
+
+브라우저에서 **[127.0.0.1:8080](http://127.0.0.1:8080)**을 열면 됩니다. 이 명령은 계좌 화면만 엽니다. 자동매매는 별도로 실행해야 합니다.
+
+처음 설치하면 저장된 거래가 없어 계좌가 비어 있습니다. [설정과 모의투자 실행 방법](docs/GETTING_STARTED.md)을 따라 시작하세요.
+
+## 보유 종목
 
-*종목별 비중은 매입금액 기준입니다. 보유분 평가금액과 평가손익은 표 아래에서 확인할 수 있습니다.*
+몇 주를 샀는지, 평균 매수가는 얼마인지, 목표 비중과 얼마나 차이가 나는지 확인할 수 있습니다.
 
-## 자동매매가 잘 돌아가는지도 확인합니다
+![대형주 계좌의 보유 수량, 평균 매수가, 종목별 비중](docs/images/readme-holdings-20260922.png)
 
-마지막 실행 시각, 거래 중지 여부, 증권사 연결과 데이터 갱신 상태를 보여 줍니다. 확인이 필요한 일이 생기면 안내에서 해당 화면으로 이동할 수 있습니다.
+종목별 비중은 **매수한 금액 기준**입니다. 현재 가격으로 계산한 보유 주식의 금액과 손익은 표 아래에 따로 나옵니다.
 
-![자동매매 실행 시각, 거래 상태와 데이터 갱신을 확인하는 화면](docs/images/readme-operations-20260922.png)
+<details>
+<summary>자동매매 상태와 모바일 화면 보기</summary>
 
-## 휴대폰에서도 같은 기록을 봅니다
+### 자동매매 상태
 
-작은 화면에서는 수익률, 계좌 금액, 차트 순서로 표시합니다. 날짜 눈금은 터치로 움직일 수 있습니다.
+마지막 실행 시각과 거래 중지 여부, 증권사 연결 상태를 확인할 수 있습니다. 문제가 있으면 안내를 눌러 해당 화면으로 이동합니다.
 
-<a href="docs/images/dashboard-mobile-20260922.png"><img src="docs/images/readme-mobile-20260922.png" alt="모바일에서 보는 ETF 적립 계좌와 날짜별 수익률" width="300"></a>
+![자동매매의 마지막 실행 시각과 연결 상태](docs/images/readme-operations-20260922.png)
+
+### 모바일 화면
+
+휴대폰 화면에 맞춰 수익률, 계좌 금액, 차트 순서로 표시합니다. 차트의 날짜는 터치로 바꿀 수 있습니다. 휴대폰에서 접속하려면 PC의 기본 접속 설정을 바꿔야 합니다.
+
+<a href="docs/images/dashboard-mobile-20260922.png"><img src="docs/images/readme-mobile-20260922.png" alt="모바일 화면의 ETF 적립 계좌와 수익률 차트" width="300"></a>
 
 [모바일 전체 화면 보기](docs/images/dashboard-mobile-20260922.png)
 
-## 현재 운용하는 모의투자 계좌
+</details>
 
-| 계좌 | 투자 방식 |
-|---|---|
-| **ETF 적립** | KODEX 200과 TIGER CD금리 ETF에 분산합니다. 시작 자금 30만원, 월 적립 계획 10만원입니다. |
-| **대형주 분산 투자** | 국내 대형주에 분산하고 주식 60%·현금 40%를 목표로 운용합니다. 비중이 크게 벗어나면 조정합니다. |
+## 기본 매매 설정
 
-ETF 적립 계좌는 추세와 낙폭에 따라 주식 비중을 줄이고, 줄인 금액을 CD금리 ETF에 배분합니다. 1주 가격과 최소 주문금액 때문에 소액 계좌의 실제 비중은 목표와 다를 수 있습니다.
+- **ETF 적립**: KODEX 200과 TIGER CD금리 ETF에 나눠 투자합니다. 시작 금액은 30만원, 월 적립 계획은 10만원입니다.
+- **대형주 분산 투자**: 국내 대형주에 나눠 투자합니다. 주식 60%·현금 40%를 목표로 하며, 비중 차이가 커지면 조정합니다.
 
-화면에 표시된 모의투자와 과거 데이터를 이용한 백테스트는 구분해서 확인할 수 있습니다. 백테스트는 수익률뿐 아니라 **최대 낙폭·매매비용·기간별 결과**를 함께 비교합니다. [비교 조건과 전체 결과 보기](docs/RISK_REVIEW_20260922.md)
+종목과 비중은 [config/baskets.yaml](config/baskets.yaml)에서 바꿀 수 있습니다. ETF 적립은 현재 모의투자 전용입니다. 추가 투자금은 화면에 직접 기록하며, 자동이체 기능은 없습니다.
 
-**모의투자와 과거 성과는 앞으로의 수익을 보장하지 않습니다.** CD금리 ETF도 원금 보장 상품은 아닙니다. ETF 적립 계좌는 현재 모의투자 전용이며, 실전 전환에는 별도의 설정과 검증이 필요합니다.
+백테스트 결과에는 수익률뿐 아니라 **가장 많이 하락한 폭과 거래 비용**도 함께 정리했습니다. [비교 조건과 결과 보기](docs/RISK_REVIEW_20260922.md)
 
-## 내 PC에서 시작하기
+모의투자와 백테스트 결과가 좋아도 실제 투자에서는 손실이 날 수 있습니다. CD금리 ETF도 원금을 보장하지 않습니다. 실제 계좌를 연결하기 전에는 [주문 설정과 확인 사항](docs/PAPER_TO_LIVE_RUNBOOK.md)을 읽어 주세요.
 
-Python 3.11 또는 3.12를 사용합니다. 처음 설치했다면 [설치 안내](docs/GETTING_STARTED.md)에 따라 환경을 준비한 뒤 실행하세요. 아래 명령은 화면을 여는 용도이며, 자동매매 실행은 별도입니다.
+## 사용 안내
 
-```powershell
-.\.venv\Scripts\python.exe main.py --mode dashboard
-```
+- [설치와 첫 모의투자](docs/GETTING_STARTED.md)
+- [자동 실행과 설정 파일 설명](docs/PROJECT_GUIDE.md)
+- [실제 계좌 연결](docs/PAPER_TO_LIVE_RUNBOOK.md)
+- [거래가 중지됐을 때 확인할 것](docs/SAFETY_MODEL.md)
 
-브라우저에서 **[127.0.0.1:8080](http://127.0.0.1:8080)**을 엽니다. 새로 설치한 계좌에는 아직 기록이 없습니다. 첫 모의투자 실행과 설정 방법도 설치 안내에 정리했습니다.
+Python · aiohttp · SQLite를 사용합니다. 웹 화면은 HTML/CSS/JavaScript로 만들었으며, 프런트엔드는 따로 설치하거나 빌드할 필요가 없습니다.
 
-## 더 알아보기
+## 문의와 의견
 
-| 궁금한 내용 | 안내 |
-|---|---|
-| 설치와 첫 모의투자 실행 | [시작하기](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) |
+잘 안 되는 기능이나 필요한 기능이 있으면 [GitHub Issues](https://github.com/easygap/quant_trader/issues/new/choose)에 남겨 주세요. 오류 화면이나 메시지를 함께 올려 주시면 원인을 찾는 데 도움이 됩니다. 계좌번호와 API 키는 지우고 올려 주세요.
 
-Python · aiohttp · SQLite · 한국투자증권 KIS API를 사용합니다. 화면은 HTML/CSS/JavaScript로 만들었으며, 별도의 프런트엔드 설치나 빌드 과정은 없습니다.
+유용하게 쓰셨다면 오른쪽 위 **Star**를 눌러 주세요.
diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md
@@ -1,6 +1,6 @@
-# 눈금 시작하기
+# 설치와 모의투자
 
-눈금은 내 PC에서 실행하는 국내 주식·ETF 자동매매 프로그램입니다. 먼저 화면을 열어 설정을 확인하고, 모의투자로 계좌 기록을 쌓을 수 있습니다.
+눈금은 내 PC에서 실행하는 국내 주식·ETF 자동매매 프로그램입니다. 설치 후 계좌 화면을 열고, 가상 자금으로 첫 매매를 해 보는 순서로 설명합니다.
 
 아래 명령은 **Windows PowerShell, Python 3.11 또는 3.12** 기준입니다. Python과 Git이 설치되어 있어야 합니다.
 
@@ -24,7 +24,9 @@ if (-not (Test-Path .env)) {
 }
 ```
 
-`config/settings.yaml`에서 `trading.mode`가 `paper`인지 확인하세요. 예제 파일의 기본값은 모의투자입니다. KIS API 키와 계좌번호 등 개인 정보는 `.env`에 입력하며, 이 파일은 Git에 올리지 않습니다. 실계좌 연결 설정은 [실전 전환 절차](PAPER_TO_LIVE_RUNBOOK.md)에서 따로 다룹니다.
+`config/settings.yaml`에서 `trading.mode`가 `paper`인지 확인하세요. 예제 파일의 기본값은 모의투자입니다. 이 모드의 매매는 프로그램 안에서 가상 자금으로 처리합니다.
+
+한국투자증권 KIS API를 연결할 때는 키와 계좌번호를 `.env`에 입력합니다. 이 파일은 Git에 올리지 마세요. 실제 돈으로 주문하려면 [실제 계좌 연결 안내](PAPER_TO_LIVE_RUNBOOK.md)를 먼저 읽어 주세요.
 
 ## 계좌 화면 열기
 
@@ -34,48 +36,50 @@ if (-not (Test-Path .env)) {
 
 브라우저에서 [127.0.0.1:8080](http://127.0.0.1:8080)을 엽니다. 이 명령은 계좌를 보여 주는 웹 서버를 실행합니다. 자동매매는 별도로 실행해야 합니다.
 
-처음 설치한 계좌에는 기록이 없으므로 빈 화면 안내가 나옵니다. README의 캡처는 이미 운용 중인 모의투자 계좌의 실제 기록입니다. 설치만으로 같은 금액과 수익률이 채워지는 것은 아닙니다.
+처음 설치하면 저장된 거래가 없어 계좌가 비어 있습니다. 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`는 대형주 분산 계좌입니다.
+매매할 종목과 비중은 [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` 상태에서** 같은 계좌의 모의투자를 실행할 수 있습니다.
+종목과 주문 수량을 확인한 뒤, **`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`에 저장됩니다. 이 명령은 과거 종가로 비교하며 주문을 내지 않습니다. 날짜를 바꾸면 파일 이름도 해당 날짜로 바뀝니다.
+결과는 `reports/research/risk_review_20260922.json`, 그래프는 `docs/images/risk-review-20260922.png`에 저장됩니다. 이 명령으로 실제 주문이 나가지는 않습니다. 날짜를 바꾸면 파일 이름도 바뀝니다.
 
-자료마다 마지막 제공일이 다르면 모든 자료가 있는 날짜까지만 비교합니다. 9월 22일 조사에서는 지수 자료가 17일까지 제공되어 17일이 비교 종료일입니다. 수익률, 비용 가정과 한계는 [검증 보고서](RISK_REVIEW_20260922.md)에 정리했습니다.
+자료마다 최신 날짜가 다르면 모두 비교할 수 있는 날짜까지만 계산합니다. 9월 22일에 확인한 지수 자료는 17일까지 있어, 이 결과도 17일까지의 주가로 계산했습니다. 수익률과 거래 비용의 계산 조건은 [백테스트 결과](RISK_REVIEW_20260922.md)에 정리했습니다.
 
-## 계속 운용하려면
+## 자동 실행과 실제 계좌 연결
 
-- 자동 실행과 설정 구조: [프로젝트 가이드](PROJECT_GUIDE.md)
-- 실전 전환과 주문 제한: [실전 전환 절차](PAPER_TO_LIVE_RUNBOOK.md)
-- 오류나 거래 중지 시 확인할 것: [거래 안전장치](SAFETY_MODEL.md)
+- [자동 실행과 설정 파일 설명](PROJECT_GUIDE.md)
+- [실제 계좌 연결과 주문 제한](PAPER_TO_LIVE_RUNBOOK.md)
+- [거래가 중지됐을 때 확인할 것](SAFETY_MODEL.md)
 
 [README로 돌아가기](../README.md)