From 42e9c8df273e29c6539617f3659cee69f5d49707 Mon Sep 17 00:00:00 2001 From: gahusb Date: Sat, 16 May 2026 00:19:00 +0900 Subject: [PATCH] =?UTF-8?q?docs(signal-v1):=20web-ai=20V1=20=E2=86=92=20si?= =?UTF-8?q?gnal=5Fv1/=20rename=20spec?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit atomic refactor (single commit) of web-ai root V1 assets into signal_v1/ subdirectory. V2 (signal_v2/) Phase 2 will be added alongside in subsequent slice. Pattern mirrors stock-lab → stock graduation. Co-Authored-By: Claude Opus 4.7 (1M context) --- ...026-05-16-web-ai-v1-rename-to-signal-v1.md | 267 ++++++++++++++++++ 1 file changed, 267 insertions(+) create mode 100644 docs/superpowers/specs/2026-05-16-web-ai-v1-rename-to-signal-v1.md diff --git a/docs/superpowers/specs/2026-05-16-web-ai-v1-rename-to-signal-v1.md b/docs/superpowers/specs/2026-05-16-web-ai-v1-rename-to-signal-v1.md new file mode 100644 index 0000000..d61048f --- /dev/null +++ b/docs/superpowers/specs/2026-05-16-web-ai-v1-rename-to-signal-v1.md @@ -0,0 +1,267 @@ +# 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분 (남은 섹션) +```