# TimeFractal 사용법

이 문서는 `tf-core`, `tf-gokcheok`, `tf-hyean`, `tf-nachimban`, `tf-ppuri` 풀 세트를 로컬과 qmin-m16에서 실행하는 절차를 정리합니다.

처음부터 전체 시스템을 한 번 완주하려면 [`tutorial-step-by-step.md`](tutorial-step-by-step.md)를 먼저 따라갑니다.

## 프로젝트 구조

```text
timefractal/
  tf-core/        공유 코어: 데이터, 룰엔진, 라벨
  tf-gokcheok/    곡척: 차트 마킹, 백테스트, Gate A 리포트
  tf-hyean/       혜안: 코퍼스 기반 코칭, 가드레일, 라벨 파이프, 국면 분류, 비전 평가
  tf-nachimban/   나침반: 시장지도 집계, 스냅샷, HTML/메일/PDF 렌더, 발송 어댑터
  tf-ppuri/       뿌리: 운용 규율, EOD 신호, 페이퍼 체결, 거래일지, 리스크, 보고, 대사
```

각 프로젝트는 sibling 관계입니다. `tf-core`가 `tf.data`, `tf.engine`, `tf.labels`를 소유하고, 앱 프로젝트는 `../tf-core`를 참조합니다. `tf-gokcheok`은 차트 마킹, 백테스트, Gate A 리포트만 소유합니다.

## 로컬 환경 준비

```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
```

기존 검증에 사용한 venv를 그대로 쓰려면:

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

새 venv를 만들었다면:

```bash
PY=/Users/qmin/lifework/naerisarang/timefractal/.venv/bin/python
```

## 전체 테스트

```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개 테스트 통과입니다.

## 곡척 사용법

샘플 신호 백테스트:

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

샘플 OHLCV 룰 기반 백테스트:

```bash
"$PY" scripts/run_backtest.py --sample --ticker AAA --ticker BBB --no-at-hx
```

샘플 차트 렌더:

```bash
"$PY" scripts/run_drawing.py --sample --ticker 005930 --out reports/005930_sample_drawing.png
```

실데이터 캐시 fetch:

```bash
"$PY" scripts/fetch_data.py --ticker 005930 --start 2016-01-01 --end 2026-06-13
```

주요 산출물:

- `tf-gokcheok/reports/backtest_report.json`
- `tf-gokcheok/reports/backtest_report.html`
- `tf-gokcheok/reports/005930_sample_drawing.png`

## 혜안 사용법

룰북 코퍼스 질의:

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

선택형 H2 XGBoost 분류기를 쓰려면 `tf-hyean[ml]` extra가 필요합니다.

```bash
cd /Users/qmin/lifework/naerisarang/timefractal/tf-hyean
"$PY" -m pip install -e '.[ml]'
```

혜안 출력은 코퍼스 근거 기반 교육용 답변이며, 종목 추천이나 매수/매도 지시를 하지 않습니다.

## 나침반 사용법

샘플 시장지도 생성:

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

주요 산출물:

- `tf-nachimban/reports/nachimban_snapshot.json`
- `tf-nachimban/reports/nachimban_preview.html`

선택형 PDF 렌더를 쓰려면 `tf-nachimban[pdf]` extra가 필요합니다.

```bash
"$PY" -m pip install -e '.[pdf]'
```

## 뿌리 사용법

샘플 월간 운용보고서 생성:

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

주요 산출물:

- `tf-ppuri/reports/ppuri_monthly.html`

선택형 PDF 렌더를 쓰려면 `tf-ppuri[pdf]` extra가 필요합니다.

```bash
"$PY" -m pip install -e '.[pdf]'
```

뿌리는 조회, 기록, 모니터링, 검증만 합니다. `QueryOnlyBroker.place_order()`는 의도적으로 실패합니다.

## qmin-m16 사용법

배포 위치:

```text
/Users/qmin/naerisarang/current/timefractal
```

서버 접속 후 공통 변수:

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

서버 전체 테스트:

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

서버 대표 실행:

```bash
cd "$BASE/tf-gokcheok" && "$PY" scripts/run_backtest.py --sample-signals --ticker AAA --ticker BBB

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

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

서버 산출물 위치:

- `$BASE/tf-gokcheok/reports/`
- `$BASE/tf-nachimban/reports/`
- `$BASE/tf-ppuri/reports/`

## 도메인 경로 매핑

`timefractal.naerisarang.com`은 qmin-m16 nginx에서 HTTPS로 서비스합니다. 각 구성요소는 같은 도메인의 하위 경로에 매핑합니다.

| 경로 | 구성요소 | 제공 내용 |
| --- | --- | --- |
| `/` | TimeFractal gateway | 전체 구성요소 링크와 운영 진입점 |
| `/core/` | `tf-core` | 공유 코어 설명 |
| `/gokcheok/` | `tf-gokcheok` | 최신 백테스트 HTML 리포트 |
| `/gokcheok/reports/` | `tf-gokcheok` | 백테스트 JSON/HTML 등 report 파일 |
| `/hyean/` | `tf-hyean` | 혜안 구성요소 설명 |
| `/nachimban/` | `tf-nachimban` | 최신 시장지도 HTML preview |
| `/nachimban/reports/` | `tf-nachimban` | 시장지도 JSON/HTML 등 report 파일 |
| `/ppuri/` | `tf-ppuri` | 최신 월간 운용보고서 HTML |
| `/ppuri/reports/` | `tf-ppuri` | 월간 보고서 등 report 파일 |
| `/docs/usage.md` | 운영 문서 | 이 사용법 문서 |
| `/healthz` | 운영 확인 | nginx health check |

nginx 설정 파일:

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

nginx 설정 검증과 reload:

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

## 운영 경계

- 실데이터 수집, 2715 데이터, 뉴스레터 실발송, KIS 조회 credential은 별도 운영 설정이 필요합니다.
- 투자 권유, 종목 추천, 목표가, 수익 보장은 시스템 범위가 아닙니다.
- 자동 주문과 주문 전송은 구현하지 않았습니다.