ted-signal 사이트 사용설명서 (USER GUIDE)

대상 독자: 이 서비스를 투자에 활용하려는 사용자 (개발 지식 불필요). 개발/운영 문서가 아닙니다 — 배포·운영은 docs/ops/home-server-deployment-plan.md, 개발 진척은 WBS.md 참조.

마지막 갱신: 2026-06-10 (KST) — v1.0 최초 작성

1. 이 서비스는 무엇인가

공매도(대차잔고) 데이터 기반 매수 시그널 시스템입니다. 매일 아침 KRX 전 종목의 대차잔고 변화를 분석해 시그널 3종을 자동 생성하고, 그 시그널이 통계적으로 믿을 만한지(백테스트), 실전에서도 통하는지(모의투자)를 한 사이트에서 검증합니다.

핵심 철학은 "검증 없이 실탄 쓰지 않는다" — 단계적 졸업 구조입니다:

시그널 생성 → 백테스트 검증 → Walk-Forward 과적합 점검 → 모의투자 3개월 → 소액 실계좌
   (자동)       (/backtest)        (/walk-forward)        (/paper-trading)    (최종 단계)
                                                          ◀── 지금 여기 ──▶

2. 시작하기

접속

• 로컬/홈서버: https://localhost (홈서버 배포 후에는 실도메인)
• localhost 접속 시 인증서 경고가 뜹니다(자체 서명 — 정상). Chrome: 고급 → 이동 클릭, 또는 경고 화면에서 키보드로 thisisunsafe 입력. 실도메인 배포 후에는 경고 없음.
• 서버가 안 떠 있다면: 프로젝트 루트에서 docker compose -f docker-compose.prod.yml --env-file .env.prod up -d

최초 1회 — 온보딩 (/onboarding)

내 계좌를 등록하는 4단계 마법사:

1. 계좌 등록 — 별칭 + 브로커 선택 (수동 입력 manual / 한국투자증권 KIS)
2. KIS 자격증명 — App Key/Secret/계좌번호 (KIS 실계좌 연동 시에만, manual은 자동 skip)
3. 첫 동기화 — KIS에서 보유 종목·거래 내역 가져오기
4. 완료 — 포트폴리오/대시보드 바로가기

manual 계좌는 /portfolio의 거래 내역 Excel 가져오기로 보유 종목을 채웁니다.

3. 핵심 개념 — 시그널과 등급

시그널 3종

등급 (스코어 기반)

등급은 "오를 확률"이 아니라 신호 패턴의 강도입니다. 실제 수익 기대값은 반드시 /backtest의 적중률·메트릭으로 확인하세요 (§ 6).

4. 매일 루틴 (확인 5~10분)

자동화가 거의 다 합니다. 사용자는 결과만 확인하면 됩니다.

자동 스케줄 (KST, 평일)

아침 (장 시작 전)

1. Telegram 알림 또는 홈(/) 접속 → 오늘 시그널 목록 확인
   • 필터(전체/급감/추세전환/숏스퀴즈) + 정렬(스코어순/감소율순)
   • 컬럼: 종목, 스코어, 등급, 타입, 대차 감소율, 과거 5/10/20일 수익률
2. 관심 종목 클릭 → /stocks/{코드} 차트로 가격 맥락 확인 (§ 5.2)
3. 더 깊게 보려면 → /reports/{코드} AI 리포트 (§ 5.3)
4. 내 보유 종목과 겹치는지 → /portfolio → 시그널 정합도 (§ 5.5)

저녁 (18:30 체결 후)

1. /paper-trading — 오늘 모의 체결 내역 + NAV 곡선 + 보유 포지션 손익 확인
2. 이벤트가 있었던 날이면 /event-strategy · /composite에서 신규 이벤트 시그널 확인

5. 페이지별 가이드

5.1 홈 / — 오늘의 시그널

일일 시그널 대시보드. 상단 메트릭 카드(전체/타입별 건수) + 시그널 테이블. 타입 필터와 스코어/감소율 정렬을 조합해 보세요. A등급 + 급감이 역사적으로 가장 표본이 많은 조합입니다 — 맹신하지 말고 § 6 메트릭으로 교차 확인.

5.2 종목 차트 /stocks/{코드} — 가격 맥락

• 기간: 1D(일봉 3개월) / 1W(주봉 1년) / 1M(월봉 3년)
• 지표 토글: MA 4슬롯(기본 5/20/60/120) · 거래량 · RSI(14) · MACD(12/26/9) · 볼린저밴드(20, 2σ)
• 지표 옆 ⚙ 드로어에서 파라미터 수정 가능 — 내 선호로 저장됨
• 차트를 왼쪽 끝까지 드래그하면 더 과거 데이터 자동 로드
• 상단에 해당 종목의 최신 시그널 카드(타입/스코어/등급) 표시

5.3 AI 리포트 /reports/{코드}

종목별 AI 분석: 의견(긍정/중립/부정) + 요약 + 강점/리스크 + 전망 + 출처(Tier 1=공시·공식, Tier 2=보조). 캐시 배지가 보이면 이전 생성본 — 다시 생성 버튼으로 갱신. 하단 메타(모델/토큰)와 면책 문구 참고. AI 의견은 참고 자료이지 매매 지시가 아닙니다.

5.4 포트폴리오 /portfolio

등록 계좌별 보유 종목 관리: 보유 수 / 매입원가 / 누적수익률(3M) / MDD(3M) 카드 + 보유 종목 표.

• 스냅샷 생성 — 현재 평가금액·미실현손익 기록 (수익률 추적의 기준점)
• KIS 동기화 — 실계좌/모의계좌 보유 내역 갱신
• 거래 내역 Excel 가져오기 — manual 계좌용

5.5 시그널 정합도 /portfolio/{계좌}/alignment

"내가 들고 있는 종목에 시그널이 떴나?" 를 한 화면에: 최근 30일 기준 보유 종목 vs 시그널 매칭. 최소 스코어 슬라이더(0~100)로 노이즈 컷. 종목별 최고 스코어·히트 횟수·최근 시그널 카드 표시.

5.6 백테스트 /backtest — 시그널 신뢰도 검증 ★

이 사이트의 핵심 화면. "이 시그널을 N일 들고 있었으면 어땠나" 를 과거 전체 데이터로 검증:

• 보유일 탭: 5일 / 10일 / 20일
• 시그널 타입 드롭다운으로 전환
• 8개 메트릭 카드 × 각 3값(Gross=비용 전 / Net=수수료·세금·슬리피지 차감 / Alpha=KOSPI 대비 초과): § 6 참조
• 자산곡선: Gross/Net/KOSPI 3-line — Net이 KOSPI 위에 있어야 의미 있음
• 하단 표: 타입별 적중률(5/10/20d)·평균수익률·표본 수

5.7 포트폴리오 백테스트 /backtest/portfolio

시그널을 실제 자금 배분으로 굴렸을 때의 시뮬레이션. 자본 배분 3방식 — Equal Weight(균등) / Inverse Volatility(저변동 비중↑) / Kelly(켈리 0.25 축소) — 실행 결과 목록에서 최대 3개 체크박스 선택 → 비교 패널(배분 비중·메트릭·자산곡선 오버레이) 자동 표시. 상세 페이지에서 트레이드 로그 + CSV export.

5.8 Walk-Forward 검증 /walk-forward — 과적합 점검 ★

백테스트가 "과거에만 잘 맞춘 것"인지 확인하는 안전장치. 데이터를 학습 12개월 / 검증 3개월로 굴리며 반복 — 학습에 안 쓴 구간(OOS) 성과로 신뢰도 등급(A~D)을 매깁니다.

읽는 법: OOS Sharpe 히스토그램이 0 오른쪽에 몰려 있고 등급 A/B → 전략이 시기를 가리지 않고 작동. 등급 D → /backtest 수치가 좋아도 과적합 의심, 실전 투입 보류.

5.9 이벤트 전략 카탈로그 /event-strategy

DART 공시 이벤트(증자/감자/자사주/실적수정 등 10종)별 보유기간(1~60일) × 적중률/평균수익률 카탈로그. "어떤 공시가 며칠 보유에서 통계적으로 유리한가"를 한눈에. 표본 수가 적은 칸은 과신 금지.

5.10 합성 시그널 /composite

기술 시그널 ∧ 이벤트 시그널을 결합한 룰(예: "급감 AND 자사주 매입")의 목록 + 룰별 적중률/수익률. 단일 시그널보다 표본은 적지만 정밀도가 높은지 비교하는 용도.

5.11 모의투자 /paper-trading — 실전 리허설 ★

매일 18:30 시그널대로 자동 가상 체결되는 모의 계좌의 관제 화면:

• 계좌 요약(평가금액/손익/수익률) + NAV 자산곡선 + 보유 포지션 표 + 체결 로그(무한 스크롤)
• 자동 갱신 토글(60초) / 수동 갱신 / CSV 내보내기
• KIS 모의계좌에도 같은 주문이 미러링되어 실제 호가 체결가와 대조됨 (실계좌 주문은 코드 레벨에서 영구 차단)

5.12 설정 /settings

• 알림 토글: 일일 요약 / 긴급(A등급은 항상 발송) / 배치 실패 / 주간 리포트
• 시그널 타입 필터 + 최소 스코어 슬라이더 — 일일 요약에서 저품질 시그널 제외
• KIS 자격증명 관리

6. 메트릭 읽는 법 (백테스트 8종)

모든 메트릭은 Net 기준으로 판단하세요 (Gross는 비용 무시라 항상 후하게 나옴).

판단 순서 요약: ① Net Expectancy > 0 인가 → ② Net alpha > 0 인가 (KOSPI를 이기는가) → ③ Walk-Forward OOS 등급 A/B 인가 → ④ MDD를 견딜 수 있는가. 네 개 다 통과한 시그널 타입 × 보유일 조합만 모의투자 관찰 대상.

7. 주간 루틴 (주 1회, 15분)

1. /backtest — 타입×보유일 조합의 Net/Alpha가 여전히 양수인지 (데이터가 쌓이면 수치가 변함)
2. /walk-forward — 신뢰도 등급 변동 확인
3. /paper-trading — NAV 곡선 vs 백테스트 기대 곡선의 괴리 체감 (3개월 누적 후 정식 비교 기능 예정)
4. /portfolio 스냅샷 생성 — 주간 수익률 기록점
5. /event-strategy — 신규 이벤트 유형의 표본이 유의미해졌는지

8. 단계 로드맵 — 지금 할 일

즉, 지금 가장 중요한 활용법은 "매일 루틴(§ 4)을 꾸준히 돌리며 모의투자 데이터를 3개월 쌓는 것"입니다. 시스템 평가에 필요한 표본이 곧 자산입니다.

9. 자주 묻는 질문 / 문제 해결

Q. 홈에 시그널이 0건이다 — 주말/공휴일은 배치가 안 돕니다. 평일인데도 0건이면 KRX 수집 실패 가능성: .env.prod의 KRX_ID/KRX_PW 누락 시 데이터가 0 rows로 조용히 실패합니다 (2026-04 KRX 전면 인증화). docker compose ... logs backend로 06:00 배치 로그 확인.

Q. 페이지가 안 열린다 — Docker Desktop(또는 홈서버)이 꺼져 있을 가능성. docker ps로 ted-signal-* 4개 컨테이너가 healthy인지 확인. 꺼져 있으면 docker compose -f docker-compose.prod.yml --env-file .env.prod up -d.

Q. 모의투자 체결이 안 보인다 — 18:30(KST 평일) 이후에 생성됩니다. 그 전에는 전일까지의 기록만 표시. 수동 트리거가 필요하면 운영자 권한으로 admin 배치 실행.

Q. 인증서 경고가 계속 뜬다 — localhost 자체 서명 인증서라 정상입니다. 실도메인 배포 후 해소.

Q. AI 리포트가 옛날 내용이다 — 캐시 배지 확인 후 다시 생성 버튼.

Q. Telegram 알림이 안 온다 — /settings 알림 토글 확인 → .env.prod의 TELEGRAM_BOT_TOKEN/TELEGRAM_CHAT_ID 확인.

⚠️ 면책: 본 시스템의 시그널·백테스트·AI 리포트는 정보 제공 목적이며 투자 권유가 아닙니다. 모든 투자 판단과 손익 책임은 사용자 본인에게 있습니다. 과거 성과는 미래 수익을 보장하지 않습니다.