# 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` (신규)**:
```markdown
# 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` (신규)**:
```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()` 호출에 명시적 경로 추가:
```python
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 자동

```bash
# 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분 (남은 섹션)
```