# TimeFractal Step-by-Step 튜토리얼

이 문서는 `tf-core`, `tf-gokcheok`, `tf-hyean`, `tf-nachimban`, `tf-ppuri` 전체 시스템을 처음부터 끝까지 한 번 실행하는 절차입니다. 기본 경로는 실데이터 없이 재현 가능한 샘플 실행입니다.

## 0. 전체 흐름 이해

```text
tf-core
  -> 공유 데이터 캐시, 룰엔진, 라벨 스키마

tf-gokcheok
  -> 샘플/캐시 OHLCV 또는 샘플 신호
  -> 차트 마킹, 백테스트, Gate A 리포트

tf-hyean
  -> 룰북/설계 문서 코퍼스
  -> 근거 기반 교육용 답변과 가드레일

tf-nachimban
  -> 신호 프레임과 메타데이터
  -> 시장지도 snapshot, HTML preview

tf-ppuri
  -> 거래일지, 자산곡선, 리스크 상태
  -> 월간 운용보고서

qmin-m16 nginx
  -> timefractal.naerisarang.com 하위 경로로 산출물 공개
```

완주 기준은 다음과 같습니다.

- 전체 테스트가 통과한다.
- 곡척 백테스트 HTML/JSON이 생성된다.
- 곡척 차트 PNG가 생성된다.
- 혜안 CLI가 룰북 기반 답변을 출력한다.
- 나침반 HTML/JSON이 생성된다.
- 뿌리 월간 HTML 보고서가 생성된다.
- qmin-m16 배포본에서는 공개 URL이 정상 응답한다.

## 1. 작업 디렉터리로 이동

로컬 개발 경로:

```bash
cd /Users/qmin/lifework/naerisarang/timefractal
```

서버 배포 경로:

```bash
ssh qmin-m16
cd /Users/qmin/naerisarang/current/timefractal
```

이하 명령은 먼저 로컬 기준으로 설명합니다. 서버에서 실행할 때는 `BASE=/Users/qmin/naerisarang/current/timefractal`를 사용하면 됩니다.

## 2. Python 환경 준비

새 가상환경을 만들 때:

```bash
cd /Users/qmin/lifework/naerisarang/timefractal
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install \
  -r tf-core/requirements.txt \
  -r tf-gokcheok/requirements.txt \
  -r tf-hyean/requirements.txt \
  -r tf-nachimban/requirements.txt \
  -r tf-ppuri/requirements.txt
PY="$PWD/.venv/bin/python"
```

이미 준비된 검증용 환경을 그대로 쓸 때:

```bash
cd /Users/qmin/lifework/naerisarang/timefractal
PY=/Users/qmin/handoff/timefractal/timefractal-system/.venv/bin/python
```

서버에서 실행할 때:

```bash
BASE=/Users/qmin/naerisarang/current/timefractal
PY="$BASE/.venv/bin/python"
```

Python 경로 확인:

```bash
"$PY" --version
```

## 3. 전체 테스트로 기준 상태 확인

```bash
cd /Users/qmin/lifework/naerisarang/timefractal

cd tf-core && "$PY" -m pytest
cd ../tf-gokcheok && "$PY" -m pytest
cd ../tf-hyean && "$PY" -m pytest
cd ../tf-nachimban && "$PY" -m pytest
cd ../tf-ppuri && "$PY" -m pytest
```

기준 결과는 총 46개 테스트 통과입니다. 여기서 실패하면 이후 샘플 실행보다 테스트 실패 원인을 먼저 해결합니다.

## 4. 곡척: 샘플 신호 백테스트 실행

곡척은 차트 마킹과 백테스트를 담당합니다. 첫 실행은 deterministic sample signal을 사용합니다.

```bash
cd /Users/qmin/lifework/naerisarang/timefractal/tf-gokcheok
"$PY" scripts/run_backtest.py --sample-signals --ticker AAA --ticker BBB
```

정상 출력 예:

```text
wrote reports/backtest_report.json
wrote reports/backtest_report.html
{...metrics...}
```

생성 파일:

```bash
ls -l reports/backtest_report.json reports/backtest_report.html
"$PY" -m json.tool reports/backtest_report.json | sed -n '1,80p'
```

qmin-m16에서 같은 명령을 실행하면 최신 결과가 아래 공개 경로에 반영됩니다.

```text
https://timefractal.naerisarang.com/gokcheok/
https://timefractal.naerisarang.com/gokcheok/reports/backtest_report.json
```

## 5. 곡척: 샘플 차트 렌더링

```bash
cd /Users/qmin/lifework/naerisarang/timefractal/tf-gokcheok
"$PY" scripts/run_drawing.py \
  --sample \
  --ticker 005930 \
  --out reports/005930_sample_drawing.png
```

정상 출력은 렌더 결과 JSON입니다. 생성 파일을 확인합니다.

```bash
ls -l reports/005930_sample_drawing.png
```

## 6. 곡척: 선택형 실데이터 캐시 수집

이 단계는 네트워크와 provider 상태에 의존합니다. 샘플 튜토리얼 완주에는 필수가 아닙니다.

```bash
cd /Users/qmin/lifework/naerisarang/timefractal/tf-gokcheok
"$PY" scripts/fetch_data.py \
  --provider pykrx \
  --ticker 005930 \
  --start 2016-01-01 \
  --end 2026-06-13
```

캐시 위치:

```text
tf-gokcheok/data/cache.sqlite
```

캐시가 채워진 뒤에는 샘플 대신 캐시 데이터로 백테스트할 수 있습니다.

```bash
"$PY" scripts/run_backtest.py \
  --ticker 005930 \
  --start 2016-01-01 \
  --end 2026-06-13 \
  --no-at-hx
```

## 7. 혜안: 룰북 기반 코칭 실행

혜안은 코퍼스 기반 답변과 가드레일을 담당합니다. 로컬 repo에는 원본 작업 문서가 없을 수 있으므로 handoff 경로를 먼저 사용합니다.

```bash
cd /Users/qmin/lifework/naerisarang/timefractal/tf-hyean
CORPUS=/Users/qmin/handoff/timefractal/타임프랙탈_룰북_v0.3.md
"$PY" scripts/hyean_coach.py \
  "천선은 언제 확정되나요?" \
  --corpus "$CORPUS"
```

서버에서는 배포본 내부의 `source-docs`를 사용합니다.

```bash
BASE=/Users/qmin/naerisarang/current/timefractal
PY="$BASE/.venv/bin/python"
cd "$BASE/tf-hyean"
"$PY" scripts/hyean_coach.py \
  "천선은 언제 확정되나요?" \
  --corpus "$BASE/source-docs/타임프랙탈_룰북_v0.3.md"
```

정상 결과는 룰북 근거를 바탕으로 한 교육용 답변입니다. 혜안은 종목 추천, 매수/매도 지시, 수익 보장을 출력하지 않는 것이 정상 동작입니다.

## 8. 나침반: 시장지도 preview 생성

나침반은 신호 프레임과 종목 메타데이터를 집계해 시장지도 snapshot과 HTML preview를 생성합니다.

```bash
cd /Users/qmin/lifework/naerisarang/timefractal/tf-nachimban
"$PY" scripts/nachimban_preview.py
```

정상 출력 예:

```text
wrote reports/nachimban_snapshot.json
wrote reports/nachimban_preview.html
```

생성 파일:

```bash
ls -l reports/nachimban_snapshot.json reports/nachimban_preview.html
"$PY" -m json.tool reports/nachimban_snapshot.json | sed -n '1,80p'
```

qmin-m16에서 같은 명령을 실행하면 최신 결과가 아래 공개 경로에 반영됩니다.

```text
https://timefractal.naerisarang.com/nachimban/
https://timefractal.naerisarang.com/nachimban/reports/nachimban_snapshot.json
```

## 9. 뿌리: 월간 운용보고서 생성

뿌리는 운용 기록, 리스크 모니터, 월간 보고를 담당합니다. 현재 구현은 조회, 기록, 검증, 보고만 수행하며 주문 전송은 하지 않습니다.

```bash
cd /Users/qmin/lifework/naerisarang/timefractal/tf-ppuri
"$PY" scripts/ppuri_report.py
```

정상 출력 예:

```text
wrote reports/ppuri_monthly.html
```

생성 파일:

```bash
ls -l reports/ppuri_monthly.html
```

qmin-m16에서 같은 명령을 실행하면 최신 결과가 아래 공개 경로에 반영됩니다.

```text
https://timefractal.naerisarang.com/ppuri/
```

## 10. qmin-m16에서 전체 샘플 산출물 갱신

공개 URL에 보이는 HTML/JSON은 qmin-m16 배포본의 report 파일을 기준으로 합니다. 서버에서 한 번에 갱신하려면 다음 순서로 실행합니다.

```bash
ssh qmin-m16
BASE=/Users/qmin/naerisarang/current/timefractal
PY="$BASE/.venv/bin/python"

cd "$BASE/tf-gokcheok"
"$PY" scripts/run_backtest.py --sample-signals --ticker AAA --ticker BBB
"$PY" scripts/run_drawing.py --sample --ticker 005930 --out reports/005930_sample_drawing.png

cd "$BASE/tf-nachimban"
"$PY" scripts/nachimban_preview.py

cd "$BASE/tf-ppuri"
"$PY" scripts/ppuri_report.py
```

혜안은 공개 채팅 UI가 아니라 CLI/라이브러리로 동작하므로 서버 내부에서 직접 확인합니다.

```bash
cd "$BASE/tf-hyean"
"$PY" scripts/hyean_coach.py \
  "천선은 언제 확정되나요?" \
  --corpus "$BASE/source-docs/타임프랙탈_룰북_v0.3.md"
```

## 11. 공개 URL smoke test

qmin-m16 nginx가 정상 동작하는지 확인합니다.

```bash
curl -fsS https://timefractal.naerisarang.com/healthz
curl -fsSI https://timefractal.naerisarang.com/
curl -fsSI https://timefractal.naerisarang.com/core/
curl -fsSI https://timefractal.naerisarang.com/hyean/
curl -fsSI https://timefractal.naerisarang.com/gokcheok/
curl -fsSI https://timefractal.naerisarang.com/gokcheok/reports/backtest_report.json
curl -fsSI https://timefractal.naerisarang.com/nachimban/
curl -fsSI https://timefractal.naerisarang.com/nachimban/reports/nachimban_snapshot.json
curl -fsSI https://timefractal.naerisarang.com/ppuri/
curl -fsSI https://timefractal.naerisarang.com/docs/usage.md
curl -fsSI https://timefractal.naerisarang.com/docs/tutorial-step-by-step.md
```

정상 기준:

- `/healthz`는 `ok`를 반환한다.
- HTTP `/`는 HTTPS `/`로 `301` 리다이렉트된다.
- HTTPS 경로는 `200`을 반환한다.
- JSON 경로는 `application/json`을 반환한다.

## 12. nginx 설정 확인

nginx server block:

```text
/opt/homebrew/etc/nginx/servers/timefractal-naerisarang.conf
```

설정 검증과 reload:

```bash
ssh qmin-m16
sudo -n /opt/homebrew/bin/nginx -t
sudo -n /opt/homebrew/bin/nginx -s reload
```

인증서 확인:

```bash
openssl x509 \
  -in /Users/qmin/.config/letsencrypt/live/timefractal.naerisarang.com/fullchain.pem \
  -noout -subject -issuer -enddate
```

## 13. 완료 체크리스트

- `tf-core` 테스트 통과
- `tf-gokcheok` 테스트 통과
- `tf-hyean` 테스트 통과
- `tf-nachimban` 테스트 통과
- `tf-ppuri` 테스트 통과
- `tf-gokcheok/reports/backtest_report.html` 생성
- `tf-gokcheok/reports/backtest_report.json` 생성
- `tf-gokcheok/reports/005930_sample_drawing.png` 생성
- `tf-nachimban/reports/nachimban_preview.html` 생성
- `tf-nachimban/reports/nachimban_snapshot.json` 생성
- `tf-ppuri/reports/ppuri_monthly.html` 생성
- `https://timefractal.naerisarang.com/healthz` 정상 응답
- `https://timefractal.naerisarang.com/gokcheok/` 정상 응답
- `https://timefractal.naerisarang.com/nachimban/` 정상 응답
- `https://timefractal.naerisarang.com/ppuri/` 정상 응답

## 14. 문제 해결

| 증상 | 확인할 것 |
| --- | --- |
| `ModuleNotFoundError` | `PY`가 올바른 venv를 가리키는지 확인합니다. 각 스크립트는 sibling `tf-core`를 `sys.path`에 추가하므로 repo 구조가 유지되어야 합니다. |
| `no cached OHLCV found` | `--sample` 또는 `--sample-signals`를 사용하거나, 먼저 `scripts/fetch_data.py`로 캐시를 채웁니다. |
| 혜안 corpus 파일 없음 | 로컬은 `/Users/qmin/handoff/timefractal/타임프랙탈_룰북_v0.3.md`, 서버는 `$BASE/source-docs/타임프랙탈_룰북_v0.3.md`를 확인합니다. |
| 공개 URL이 예전 결과를 보임 | qmin-m16의 `/Users/qmin/naerisarang/current/timefractal`에서 report 생성 명령을 다시 실행합니다. |
| 공개 URL 404/500 | `sudo -n /opt/homebrew/bin/nginx -t`와 `/opt/homebrew/var/log/nginx/error.log`를 확인합니다. |
| 인증서 문제 | `/Users/qmin/.config/letsencrypt/live/timefractal.naerisarang.com/`와 renewal 설정을 확인합니다. |

## 15. 운영 경계

- 실데이터 수집은 provider, 네트워크, 기간, ticker 상태에 영향을 받습니다.
- KIS 조회 credential, 2715 데이터 연동, 뉴스레터 실발송은 별도 운영 설정이 필요합니다.
- 시스템은 투자 권유, 종목 추천, 목표가, 수익 보장을 하지 않습니다.
- 자동 주문과 주문 전송은 구현하지 않았습니다.