web-page/docs/superpowers/specs/2026-05-16-web-ai-v1-rename-to-signal-v1.md

web-ai V1 루트 → signal_v1/ Rename Design

작성일: 2026-05-16 작성자: gahusb 상태: Approved for implementation 선행 spec:

• Confidence Signal Pipeline V2 Phase 0 (2026-05-15-confidence-signal-pipeline-v2-architecture.md)
• stock-lab → stock graduation (2026-05-15-stock-lab-rename-to-stock.md) — 동일 atomic refactor 패턴

---

1. 목표

web-ai/ 디렉토리에 V1 자동매매 시스템 (main_server.py + modules/ + 자체 LSTM + KIS + Telegram Bot) 과 V2 시그널 파이프라인 (signal_v2/ Phase 2 시작) 이 함께 거주할 예정. V1 자산을 모두 signal_v1/ 하위로 격리해 신/구 분리 명확.

Why: 사용자 명시 ("기존 기능들도 봤을때 헷갈리지 않게 signal_v2에서 사용하는거 아니면 web-ai/signal_v1 으로 몰아넣어줘"). V2 Phase 6 deprecation 시점에 rm -rf signal_v1/ 단순화. Phase 2 spec 작성 전에 새 이름 signal_v1/ 기준으로 진행하면 후속 갱신 비용 회피.

본 리네이밍은 Phase 2 brainstorming 의 도중 분기한 별도 슬라이스 — stock-lab → stock graduation 과 동일 패턴.

---

2. 범위

포함

• git mv web-ai 루트의 모든 V1 자산을 signal_v1/ 안으로:
  • 진입점: main_server.py, warmup_and_restart.py, watchlist_manager.py, backtester.py, theme_manager.py, backtest_runner.py
  • 모듈: modules/ (전체)
  • 데이터: data/ (전체 — runtime data 보존)
  • 테스트: tests/ (전체)
  • 스크립트: start.bat
  • 문서: KIS_SETUP.md, README.md, CLAUDE.md (기존 V1 가이드)
  • 로그: bot_ipc.json, bot_output.log, daily_launcher.log, server.log, telegram_bot.log, warmup.log
  • __pycache__/ (gitignore)
• web-ai/CLAUDE.md 신규 — web-ai 루트의 새 가이드 (signal_v1 + signal_v2 디렉토리 안내, 공유 .env, Phase 6 deprecation 계획)
• web-ai/start.bat 신규 — cd signal_v1 && python main_server.py (또는 절대 경로 형태)
• 운영 검증: 자체 자동매매 봇 정상 기동 + Telegram Bot polling + KIS 토큰 로딩

범위 외 (NOT)

• Python import 경로 변경 — signal_v1/ 안에서 진입점 실행 시 cwd 가 signal_v1/ 이라 기존 from modules.X 그대로 작동. import 전면 갱신 불필요.
• signal_v2/ 디렉토리 생성 — Phase 2 spec 의 작업.
• .env 분리 — V1 + V2 환경변수 모두 web-ai/.env 한 곳 (signal_v1 의 python 진입점이 cwd 기준 .env 로드 시 path 갱신 필요, 단순 조정).
• .gitignore — 기존 패턴 그대로 (signal_v1/__pycache__, signal_v1/data/*.db 등은 일반 패턴으로 커버).
• 다른 lab / web-backend / web-ui 영향 — 0.
• start_signal_v2.bat — Phase 2 spec 의 작업.

---

3. 변경 매트릭스

3.1 web-ai 루트 (작업 전)

web-ai/
├── .env                    ← 유지
├── .gitignore              ← 유지
├── CLAUDE.md               ← signal_v1/ 로 mv (현 V1 가이드)
├── KIS_SETUP.md            ← signal_v1/ 로 mv
├── README.md               ← signal_v1/ 로 mv
├── main_server.py          ← signal_v1/ 로 mv
├── warmup_and_restart.py   ← signal_v1/ 로 mv
├── watchlist_manager.py    ← signal_v1/ 로 mv
├── backtester.py           ← signal_v1/ 로 mv
├── backtest_runner.py      ← signal_v1/ 로 mv
├── theme_manager.py        ← signal_v1/ 로 mv
├── start.bat               ← signal_v1/ 로 mv (이후 web-ai/start.bat 신규)
├── modules/                ← signal_v1/ 로 mv
├── data/                   ← signal_v1/ 로 mv
├── tests/                  ← signal_v1/ 로 mv
├── __pycache__/            ← signal_v1/ 로 mv (gitignore)
├── bot_ipc.json            ← signal_v1/ 로 mv
├── bot_output.log          ← signal_v1/ 로 mv
├── daily_launcher.log      ← signal_v1/ 로 mv
├── server.log              ← signal_v1/ 로 mv
├── telegram_bot.log        ← signal_v1/ 로 mv
└── warmup.log              ← signal_v1/ 로 mv

3.2 web-ai 루트 (작업 후)

web-ai/
├── .env                    ← 공유 (V1 + V2 변수)
├── .gitignore              ← 기존
├── CLAUDE.md               ← 신규 (web-ai 레벨 가이드)
├── start.bat               ← 신규 (signal_v1 진입)
├── signal_v1/
│   ├── CLAUDE.md           ← 기존 V1 가이드 (이동)
│   ├── KIS_SETUP.md
│   ├── README.md
│   ├── main_server.py
│   ├── warmup_and_restart.py
│   ├── ... (이하 모든 V1 자산)
│   ├── start.bat           ← 이동본 (사용 안 함, 향후 정리)
│   ├── modules/
│   ├── data/
│   ├── tests/
│   └── (log 파일들)
└── signal_v2/              ← Phase 2 작업 (본 spec 외)

3.3 신규 파일 2개 — 정확한 내용

web-ai/CLAUDE.md (신규):

# web-ai — Workspace 가이드

Windows AI 머신 (AMD 9800X3D + RTX 5070 Ti) 의 두 시그널 파이프라인 컨테이너.

## 디렉토리 구조

| 경로 | 역할 | 상태 |
|------|------|------|
| `signal_v1/` | V1 자체 자동매매 시스템 (main_server.py + Trading Bot + Telegram Bot + LSTM + Ollama + KIS 자동주문) | 운영 중. Confidence Signal Pipeline V2 Phase 6 에서 deprecation 예정 |
| `signal_v2/` | V2 신호 파이프라인 (stock pull worker + Chronos-2 + signal API client) | Phase 2 에서 신설 |
| `.env` | V1 + V2 환경변수 공유 | KIS_*, TELEGRAM_*, STOCK_API_URL, WEBAI_API_KEY 등 |
| `start.bat` | V1 진입 (signal_v1 디렉토리 안 main_server.py 실행) | V2 별도 start 스크립트는 signal_v2/start.bat |

## 운영 가이드

- V1 시작: `start.bat` 또는 `cd signal_v1 && python main_server.py`
- V2 시작 (Phase 2 이후): `cd signal_v2 && python -m uvicorn main:app --port 8001`
- 둘 다 동시 실행 가능 (포트 분리: V1=8000, V2=8001)

## Phase 진행 상태 (Confidence Signal Pipeline V2)

`web-ui/docs/superpowers/specs/2026-05-15-confidence-signal-pipeline-v2-architecture.md` 참조.

자세한 V1 가이드는 `signal_v1/CLAUDE.md` 참조.

web-ai/start.bat (신규):

@echo off
cd /d "%~dp0\signal_v1"
python main_server.py

3.4 운영 영향 — .env 로드 경로

기존 V1 코드 (signal_v1/modules/config.py 등) 는 load_dotenv() 호출 시 cwd 또는 절대 경로의 .env 를 찾음. cwd 가 signal_v1/ 이라면 .env 가 web-ai/.env (parent) 이라 못 찾을 수 있음.

해결: 진입점 (signal_v1/main_server.py 등) 의 load_dotenv() 호출에 명시적 경로 추가:

from pathlib import Path
from dotenv import load_dotenv

# web-ai/.env (signal_v1/ 의 parent) 명시 로드
load_dotenv(Path(__file__).parent.parent / ".env")

작업 매트릭스:

• signal_v1/main_server.py 의 load_dotenv() 1-2 줄 갱신
• signal_v1/warmup_and_restart.py 동일
• signal_v1/modules/config.py 같은 환경변수 로딩 위치 점검

---

4. 작업 순서

1. 사전 검토 (10분)
   - web-ai 자체 자동매매 봇 운영 중 → 작업 시간대 결정 (장외: 평일 16:00 이후 / 주말)
   - 본 spec §3 매트릭스 모든 파일 grep cross-check
   - .env 로드 위치 grep — `load_dotenv` 호출 모두 찾기
   - 데이터 파일 (data/, *.log, *.json) 손실 위험 없음 확인 (git mv 는 history 보존)

2. atomic refactor (1 commit)
   - mkdir signal_v1
   - git mv (위 매트릭스 항목 전부) signal_v1/
   - signal_v1/main_server.py 외 .env 로드 위치 갱신
   - web-ai/CLAUDE.md 신규
   - web-ai/start.bat 신규

3. 로컬 검증 (cwd=signal_v1)
   - python -m pytest tests/unit -q  (기존 V1 테스트 통과)
   - python main_server.py 시작 검증
   - .env 로딩 확인 (KIS / Telegram / Ollama 환경변수)
   - 봇 정상 시작 → telegram 알림 도착 → /status 응답 → 종료

4. git push (web-ai repo)
   - sub Gitea: https://gitea.gahusb.synology.me/gahusb/ai-trade.git
   - 본 작업은 NAS deploy 와 무관 (web-ai 는 로컬 Windows 머신).

5. 사용자 수동 검증
   - 시장 시작 (다음 평일 09:00) 시점 봇 정상 동작 확인 또는 일/주말 가짜 트리거

---

5. 위험 및 완화

위험	완화
.env 로드 실패 → KIS 토큰 못 가져옴 → 자동매매 중단	진입점 (main_server.py / warmup_and_restart.py) 의 load_dotenv 명시 경로 추가. 시작 직후 KIS auth 확인
자동매매 중 작업 → 거래 중단	작업 시간대를 장외 (평일 16:00+ 또는 주말) 로 제한
Python import 회귀	signal_v1/ cwd 기준 from modules.X 그대로. 외부 import 불필요. 기존 76+ 테스트 통과로 검증
데이터 파일 (data/models/, data/ensemble_history.json 등) 손실	git mv 사용 — history 보존, 파일 내용 무변경. 사전 git status 로 dirty 없음 확인
Telegram Bot 중복 polling (이전 프로세스 미종료)	start.bat 재시작 시 main_server.py 의 좀비 정리 로직 자동 동작
.env 의 절대 경로 참조 (e.g. data/kis_token.json 같은 상대 경로)	cwd 변경 영향 — 진입점이 working directory 를 signal_v1/ 으로 설정하면 기존 상대 경로 그대로 작동. start.bat 의 cd /d "%~dp0\signal_v1" 가 보장
향후 web-ai 레벨 외부 호출 (e.g. agent-office → web-ai :8000)	V1 main_server.py 는 port 8000 유지. URL 변경 없음.
signal_v2 진입점이 signal_v1 의 IPC 와 충돌	Phase 2 가 별도 port :8001 + 별도 디렉토리. IPC SharedMemory 이름 분리 (V1 의 web_ai_bot_ipc 그대로 유지, V2 는 IPC 사용 안 함)

---

6. 테스트 / 검증

6.1 자동

# V1 테스트 전체 통과
cd /c/Users/jaeoh/Desktop/workspace/web-ai/signal_v1
python -m pytest tests/unit -q
# Expected: 기존 PASS 개수 그대로

# stock-lab → stock 의 잔여 참조 패턴 검증과 동일 — V1 안에서 import 회귀 없음
grep -rn "from web-ai" /c/Users/jaeoh/Desktop/workspace/web-ai/signal_v1
# Expected: 0 lines (없어야 함)

6.2 수동

• cd web-ai && start.bat (또는 cd web-ai/signal_v1 && python main_server.py)
• 콘솔 로그에 KIS 인증 성공 / Telegram Bot connected / Ollama 모델 로드 확인
• Telegram /status 명령 → 정상 응답
• 30분 관측 후 Watchdog 정상 (자식 프로세스 healthy)

---

7. 운영 영향

항목	영향
다운타임	작업 시간 + 첫 시작 검증 = ~30분
사용자 영향	V1 자동매매 봇 일시 중단 (장외 시간대 진행 권장)
.env 갱신	없음 (위치 그대로, 진입점만 명시 경로 변경)
frontend 영향	없음
다른 lab / web-backend	없음 (web-ai 외부 의존 0)
Gitea push	web-ai repo 만

---

8. 완료 조건 (DoD)

• web-ai/signal_v1/ 디렉토리 신설 + 매트릭스의 모든 V1 자산 mv 완료 (git history 보존)
• web-ai/CLAUDE.md 신규 (web-ai 레벨 가이드)
• web-ai/start.bat 신규 (signal_v1 cd 후 main_server.py)
• signal_v1/main_server.py, warmup_and_restart.py 등의 load_dotenv() 가 web-ai/.env 를 명시 로드
• signal_v1/tests/unit/ 전체 pytest 통과 (기존 baseline 그대로)
• cd web-ai && start.bat 으로 V1 봇 정상 시작 + Telegram /status 응답
• grep from web-ai\. 또는 from web-ai/ 결과 0 lines
• web-ai repo push 완료 (단일 commit)

---

9. Phase 2 와의 관계

본 리네이밍 완료 후 즉시 Phase 2 brainstorming 재개. Phase 2 spec 은:

• 새 이름 web-ai/signal_v2/ 기준
• Phase 2 의 모든 결정 (배치 = 별도 FastAPI app :8001 / scope = 3 항목 / scheduler = asyncio cron / client = httpx + 자체 retry / rate limit = SQLite / test = pytest-asyncio) 그대로 반영
• 디자인 섹션 1 (목표/scope) + 섹션 2 (파일 구조 = web-ai/signal_v2/) 의 검토 완료 상태에서 섹션 3-7 진행

[본 리네이밍 spec/plan/실행]   →   [Phase 2 spec 작성 재개]
       ~30분-1시간                        ~15분 (남은 섹션)