docs(signal-v1): web-ai V1 rename plan — 13 step atomic refactor
Single big task (Task 1) for atomic mv + load_dotenv update + new CLAUDE.md/start.bat + verification. Task 2 = user manual push + 30-min runtime verification. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,402 @@
|
||||
# web-ai V1 → signal_v1 Rename Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** `web-ai/` 루트의 모든 V1 자산 (main_server.py + modules/ + data/ + tests/ + 진입점 스크립트 + 문서 + 로그) 을 `web-ai/signal_v1/` 안으로 atomic mv 하고, web-ai 루트에 신규 가이드 (`CLAUDE.md`, `start.bat`) 추가. V2 (`signal_v2/`) 추가 전 신/구 격리.
|
||||
|
||||
**Architecture:** 단일 atomic commit (stock-lab → stock graduation 과 동일 패턴). `git mv` 로 history 보존, `load_dotenv()` 호출만 경로 명시. cwd 기반 V1 코드라 import 변경 0. Phase 6 deprecation 시 `rm -rf signal_v1/` 단순화.
|
||||
|
||||
**Tech Stack:** git mv / Python load_dotenv path 갱신 / pytest 회귀 확인
|
||||
|
||||
**Spec:** `web-ui/docs/superpowers/specs/2026-05-16-web-ai-v1-rename-to-signal-v1.md`
|
||||
|
||||
---
|
||||
|
||||
## 파일 구조 (Task 2 후)
|
||||
|
||||
```
|
||||
web-ai/
|
||||
├── .env ← 그대로 (V1 + V2 공유)
|
||||
├── .gitignore ← 그대로
|
||||
├── CLAUDE.md ← 신규 (web-ai 레벨 가이드)
|
||||
├── start.bat ← 신규 (signal_v1 진입 wrapper)
|
||||
├── signal_v1/ ← 신규 디렉토리
|
||||
│ ├── CLAUDE.md ← 기존 V1 가이드 (mv)
|
||||
│ ├── KIS_SETUP.md
|
||||
│ ├── README.md
|
||||
│ ├── main_server.py ← load_dotenv 경로 명시 갱신
|
||||
│ ├── warmup_and_restart.py ← load_dotenv 경로 명시 갱신
|
||||
│ ├── watchlist_manager.py
|
||||
│ ├── backtester.py
|
||||
│ ├── backtest_runner.py
|
||||
│ ├── theme_manager.py
|
||||
│ ├── start.bat ← 사용 안 함 (cleanup 안 함, 향후)
|
||||
│ ├── modules/ ← 전체
|
||||
│ ├── data/ ← 전체 (runtime data 보존)
|
||||
│ ├── tests/ ← 전체
|
||||
│ └── (log/json 파일들)
|
||||
└── (signal_v2/ 는 Phase 2 spec)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 1: Atomic refactor (사전 점검 + git mv + 신규 파일 + 검증 + commit)
|
||||
|
||||
**Files:**
|
||||
- Source repo: `C:\Users\jaeoh\Desktop\workspace\web-ai` (별도 Gitea repo: `ai-trade.git`, branch `main`)
|
||||
- Create: `web-ai/signal_v1/` (디렉토리)
|
||||
- Create: `web-ai/CLAUDE.md` (신규)
|
||||
- Create: `web-ai/start.bat` (신규)
|
||||
- Move (git mv): web-ai 루트의 모든 V1 자산 → signal_v1/
|
||||
- Modify: `web-ai/signal_v1/main_server.py` (load_dotenv 명시 경로)
|
||||
- Modify: `web-ai/signal_v1/warmup_and_restart.py` (load_dotenv 명시 경로)
|
||||
- (필요 시) Modify: `signal_v1/modules/config.py` 또는 다른 load_dotenv 위치
|
||||
|
||||
- [ ] **Step 1: 사전 — 자동매매 봇 정지 확인 + git status clean**
|
||||
|
||||
```bash
|
||||
cd /c/Users/jaeoh/Desktop/workspace/web-ai
|
||||
git status
|
||||
```
|
||||
Expected: `nothing to commit, working tree clean`. 만약 dirty 면 implementer 는 BLOCKED 보고. 사용자가 stash 또는 commit 처리.
|
||||
|
||||
또한: V1 자동매매 봇이 실행 중이면 mv 도중 파일 잠금 위험. PowerShell:
|
||||
```powershell
|
||||
Get-Process python -ErrorAction SilentlyContinue | Select-Object Id, ProcessName, StartTime
|
||||
```
|
||||
실행 중 Python 프로세스 발견 시 사용자에게 종료 요청. (장외 시간대에 작업 가정.)
|
||||
|
||||
- [ ] **Step 2: 사전 grep — load_dotenv 호출 위치 파악**
|
||||
|
||||
```bash
|
||||
cd /c/Users/jaeoh/Desktop/workspace/web-ai
|
||||
grep -rn "load_dotenv" --include="*.py" .
|
||||
```
|
||||
Expected: 1~3개 hit. 각 hit 의 파일 경로 기록 (Step 6 에서 갱신). 일반적으로 main_server.py, warmup_and_restart.py, modules/config.py 중 1~2곳에 있음.
|
||||
|
||||
만약 hit 0 이면 V1 이 `.env` 를 다른 방식 (예: pydantic-settings) 으로 로드. 코드 경로 추가 grep:
|
||||
```bash
|
||||
grep -rn "BaseSettings\|env_file\|\.env" --include="*.py" .
|
||||
```
|
||||
어느 방식이든 cwd 가 signal_v1/ 으로 바뀌면 `.env` 가 parent (`web-ai/.env`) 에 있다는 사실을 코드가 알아야 함.
|
||||
|
||||
- [ ] **Step 3: 사전 baseline — 현 pytest 통과 개수 측정**
|
||||
|
||||
```bash
|
||||
cd /c/Users/jaeoh/Desktop/workspace/web-ai
|
||||
python -m pytest tests/unit -q 2>&1 | tail -3
|
||||
```
|
||||
Expected output 형태: `N passed in Xs` (또는 `N passed, M warnings ...`). N 값을 baseline 으로 기록 (Step 13 에서 비교).
|
||||
|
||||
만약 baseline 자체가 실패면 implementer 는 DONE_WITH_CONCERNS 보고 — 사용자 결정 (pre-existing failure 라면 무시하고 진행 가능).
|
||||
|
||||
- [ ] **Step 4: signal_v1 디렉토리 생성**
|
||||
|
||||
```bash
|
||||
cd /c/Users/jaeoh/Desktop/workspace/web-ai
|
||||
mkdir signal_v1
|
||||
```
|
||||
Verify:
|
||||
```bash
|
||||
ls -d signal_v1
|
||||
```
|
||||
Expected: `signal_v1`
|
||||
|
||||
- [ ] **Step 5: git mv 실행 (V1 자산 모두)**
|
||||
|
||||
다음 항목을 모두 `signal_v1/` 안으로 이동. `git mv` 사용 (history 보존):
|
||||
|
||||
```bash
|
||||
cd /c/Users/jaeoh/Desktop/workspace/web-ai
|
||||
|
||||
# 진입점 + 스크립트
|
||||
git mv main_server.py signal_v1/
|
||||
git mv warmup_and_restart.py signal_v1/
|
||||
git mv watchlist_manager.py signal_v1/
|
||||
git mv backtester.py signal_v1/
|
||||
git mv backtest_runner.py signal_v1/
|
||||
git mv theme_manager.py signal_v1/
|
||||
git mv start.bat signal_v1/
|
||||
|
||||
# 문서 (현 V1 가이드)
|
||||
git mv CLAUDE.md signal_v1/
|
||||
git mv KIS_SETUP.md signal_v1/
|
||||
git mv README.md signal_v1/
|
||||
|
||||
# 디렉토리
|
||||
git mv modules signal_v1/
|
||||
git mv data signal_v1/
|
||||
git mv tests signal_v1/
|
||||
|
||||
# 로그 / IPC / 캐시
|
||||
git mv bot_ipc.json signal_v1/ 2>/dev/null || true
|
||||
git mv bot_output.log signal_v1/ 2>/dev/null || true
|
||||
git mv daily_launcher.log signal_v1/ 2>/dev/null || true
|
||||
git mv server.log signal_v1/ 2>/dev/null || true
|
||||
git mv telegram_bot.log signal_v1/ 2>/dev/null || true
|
||||
git mv warmup.log signal_v1/ 2>/dev/null || true
|
||||
```
|
||||
|
||||
`__pycache__/` 는 gitignore 이므로 git mv 불가능. 단순 mv:
|
||||
```bash
|
||||
mv __pycache__ signal_v1/ 2>/dev/null || true
|
||||
```
|
||||
|
||||
Verify:
|
||||
```bash
|
||||
git status --short | head -30
|
||||
ls signal_v1/
|
||||
ls
|
||||
```
|
||||
Expected: `signal_v1/` 안에 모든 V1 자산이 있고, web-ai 루트에는 `.env`, `.gitignore`, `signal_v1/` 만 (still untracked: none yet for new files).
|
||||
|
||||
- [ ] **Step 6: load_dotenv 경로 명시 갱신**
|
||||
|
||||
Step 2 에서 식별한 각 `load_dotenv()` 호출을 명시 경로로 변경. 가장 빈도 높은 패턴 (main_server.py 의 시작 부분):
|
||||
|
||||
기존 (cwd 기준):
|
||||
```python
|
||||
from dotenv import load_dotenv
|
||||
load_dotenv()
|
||||
```
|
||||
|
||||
신규 (명시 경로, signal_v1 의 parent = web-ai 루트):
|
||||
```python
|
||||
from pathlib import Path
|
||||
from dotenv import load_dotenv
|
||||
|
||||
# web-ai/.env (signal_v1/ 의 parent) 명시 로드
|
||||
load_dotenv(Path(__file__).parent.parent / ".env")
|
||||
```
|
||||
|
||||
Step 2 에서 식별한 모든 위치에 동일 패턴 적용. 만약 V1 이 `BaseSettings` (pydantic) 사용 시:
|
||||
```python
|
||||
class Settings(BaseSettings):
|
||||
class Config:
|
||||
env_file = str(Path(__file__).parent.parent / ".env")
|
||||
```
|
||||
|
||||
만약 V1 이 그냥 `os.getenv(...)` 만 쓰고 어딘가에서 명시적으로 load 하지 않는다면 (uvicorn 이 시작 시 cwd 의 .env 를 자동 로드 시) — 시작 wrapper (`web-ai/start.bat`) 가 `cd signal_v1` 후 실행하면 cwd=signal_v1 → `.env` 못 찾음. 해결: Step 7 의 `start.bat` 에서 명시적으로 `cd /d "%~dp0"` (= web-ai 루트) 후 `python signal_v1/main_server.py` 실행.
|
||||
|
||||
근데 그러면 main_server.py 안의 다른 상대 경로 (`data/kis_token.json` 등) 가 cwd=web-ai 일 때 `web-ai/data/kis_token.json` 을 찾음 → 잘못된 경로.
|
||||
|
||||
**결정**: cwd 는 `signal_v1/` 으로 두고 `load_dotenv(Path(__file__).parent.parent / ".env")` 명시. 다른 상대 경로는 cwd=signal_v1 기준이라 `data/...` 그대로 작동.
|
||||
|
||||
각 갱신 후 git status:
|
||||
```bash
|
||||
cd /c/Users/jaeoh/Desktop/workspace/web-ai
|
||||
git status --short | head -10
|
||||
```
|
||||
Expected: signal_v1/main_server.py 등 modified 표시.
|
||||
|
||||
- [ ] **Step 7: 신규 파일 — web-ai/CLAUDE.md**
|
||||
|
||||
Create `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` 참조.
|
||||
```
|
||||
|
||||
- [ ] **Step 8: 신규 파일 — web-ai/start.bat**
|
||||
|
||||
Create `web-ai/start.bat`:
|
||||
|
||||
```bat
|
||||
@echo off
|
||||
cd /d "%~dp0\signal_v1"
|
||||
python main_server.py
|
||||
```
|
||||
|
||||
- [ ] **Step 9: git add 신규 파일**
|
||||
|
||||
```bash
|
||||
cd /c/Users/jaeoh/Desktop/workspace/web-ai
|
||||
git add CLAUDE.md start.bat
|
||||
git add signal_v1/main_server.py signal_v1/warmup_and_restart.py # load_dotenv 갱신
|
||||
# 추가로 갱신한 다른 .py 파일이 있으면 모두 add
|
||||
```
|
||||
|
||||
git status 점검:
|
||||
```bash
|
||||
git status
|
||||
```
|
||||
Expected: 모든 git mv + 신규 + modify 변경이 staged 상태.
|
||||
|
||||
- [ ] **Step 10: 잔여 grep — `from web-ai` 같은 잘못된 import 0건 확인**
|
||||
|
||||
```bash
|
||||
cd /c/Users/jaeoh/Desktop/workspace/web-ai
|
||||
grep -rn "from web-ai\|import web-ai" --include="*.py" signal_v1/
|
||||
```
|
||||
Expected: 0 lines.
|
||||
|
||||
또한 V1 코드 안에 hardcoded 절대 경로 (예: `C:\Users\jaeoh\Desktop\workspace\web-ai\data\...`) 검사:
|
||||
```bash
|
||||
grep -rn "web-ai.data\|web-ai/data\|web-ai\\\\data" --include="*.py" signal_v1/
|
||||
```
|
||||
Expected: 0 lines.
|
||||
|
||||
만약 hit 있으면 implementer 는 DONE_WITH_CONCERNS 보고, 사용자가 조정.
|
||||
|
||||
- [ ] **Step 11: signal_v1 안에서 pytest 자동 검증**
|
||||
|
||||
```bash
|
||||
cd /c/Users/jaeoh/Desktop/workspace/web-ai/signal_v1
|
||||
python -m pytest tests/unit -q 2>&1 | tail -5
|
||||
```
|
||||
Expected: Step 3 의 baseline 과 동일한 PASS 개수 (회귀 없음).
|
||||
|
||||
만약 import 오류 (`ModuleNotFoundError: No module named 'modules'`) 가 발생하면 conftest.py 가 sys.path 를 수정하지 않을 가능성. 확인:
|
||||
```bash
|
||||
cat tests/unit/conftest.py | head -20
|
||||
```
|
||||
필요 시 `sys.path.insert(0, str(Path(__file__).parent.parent.parent))` 추가. 단, 기존 conftest 가 cwd 기반이면 cwd=signal_v1 에서 작동해야 함.
|
||||
|
||||
만약 다른 failure 면 BLOCKED 보고 — 사용자 진단.
|
||||
|
||||
- [ ] **Step 12: 잠시 후 다시 git status — 추가 untracked 없는지 확인**
|
||||
|
||||
```bash
|
||||
cd /c/Users/jaeoh/Desktop/workspace/web-ai
|
||||
git status
|
||||
```
|
||||
Expected: 모든 변경이 staged. 만약 새 untracked (pytest cache 등) 있으면 .gitignore 패턴 또는 무시.
|
||||
|
||||
- [ ] **Step 13: 단일 commit**
|
||||
|
||||
```bash
|
||||
cd /c/Users/jaeoh/Desktop/workspace/web-ai
|
||||
git commit -m "$(cat <<'EOF'
|
||||
refactor: web-ai V1 assets → signal_v1/ (graduation prep)
|
||||
|
||||
Atomic mv of root V1 assets (main_server.py + modules/ + data/ +
|
||||
tests/ + entry scripts + docs + logs) into signal_v1/ subdirectory.
|
||||
load_dotenv() updated to load web-ai/.env explicitly via Path.
|
||||
|
||||
Adds web-ai/CLAUDE.md (workspace guide) and web-ai/start.bat
|
||||
(signal_v1 entry wrapper). Prepares for signal_v2/ Phase 2.
|
||||
|
||||
Tests: signal_v1/tests/unit baseline preserved (no regression).
|
||||
|
||||
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
Verify:
|
||||
```bash
|
||||
git log -1 --stat
|
||||
```
|
||||
Expected: 1 commit, 다수 rename + 2 신규 (CLAUDE.md / start.bat) + 1-3 modified (load_dotenv 위치).
|
||||
|
||||
## Reporting
|
||||
|
||||
When done, report:
|
||||
- DONE: commit SHA, baseline test count (Step 3) + post-mv count (Step 11), 자동 grep 결과 (0 lines).
|
||||
- DONE_WITH_CONCERNS: implementation 됐지만 hardcoded path / pre-existing test fail 등 발견 — 상세 보고.
|
||||
- NEEDS_CONTEXT: load_dotenv 패턴이 spec 예상과 다름, 또는 conftest 추가 fix 필요 등.
|
||||
- BLOCKED: working tree dirty / pytest baseline 자체 실패 / git mv 충돌.
|
||||
|
||||
---
|
||||
|
||||
## Task 2: 사용자 수동 — 운영 검증 + push
|
||||
|
||||
**This task requires user action. Pause and request user to perform.**
|
||||
|
||||
- [ ] **Step 1: V1 자동매매 봇 정상 시작 검증**
|
||||
|
||||
사용자가 PowerShell 에서:
|
||||
```powershell
|
||||
cd C:\Users\jaeoh\Desktop\workspace\web-ai
|
||||
.\start.bat
|
||||
```
|
||||
|
||||
기대 출력 (수십 줄):
|
||||
- `Config.validate()` 성공 (환경변수 누락 없음)
|
||||
- KIS OAuth `access_token` 발급 (또는 cached token 로드)
|
||||
- Telegram Bot started + `Conflict` 없음
|
||||
- ProcessWatchdog 시작
|
||||
- Uvicorn 0.0.0.0:8000 listening
|
||||
- 봇 사이클 (장중이면) 또는 idle (장외)
|
||||
|
||||
만약 `FileNotFoundError: .env` 또는 KIS auth 실패 시 — load_dotenv 경로 오류. Task 1 으로 돌아가 Step 6 조정.
|
||||
|
||||
- [ ] **Step 2: Telegram /status 명령 응답 검증**
|
||||
|
||||
사용자가 텔레그램에서 `/status` 명령. 봇이 정상 응답하면 IPC + SharedMemory + Telegram Bot 모두 정상.
|
||||
|
||||
- [ ] **Step 3: 30분 관측**
|
||||
|
||||
콘솔 또는 telegram_bot.log 에 에러 없음 + Watchdog 30초 간격 health check PASS 확인.
|
||||
|
||||
만약 자식 프로세스 (Trading Bot / Telegram Bot) 가 자동 종료 → restart loop → 재실패 시 Task 1 으로 돌아가 진단.
|
||||
|
||||
- [ ] **Step 4: git push (사용자, Gitea 자격증명)**
|
||||
|
||||
```powershell
|
||||
cd C:\Users\jaeoh\Desktop\workspace\web-ai
|
||||
git push
|
||||
```
|
||||
|
||||
만약 자격증명 실패 시 사용자가 수동으로 처리 (메모리 `feedback_nas_deploy_paths.md` 의 Gitea 자격증명 패턴).
|
||||
|
||||
- [ ] **Step 5: 결과 보고 (사용자 → 컨트롤러)**
|
||||
|
||||
- Step 1 (start.bat 시작): PASS / FAIL — 첫 에러 메시지 공유
|
||||
- Step 2 (/status 응답): PASS / FAIL
|
||||
- Step 3 (30분 관측): PASS (no errors) / FAIL — 관측된 에러
|
||||
- Step 4 (push): PASS / FAIL
|
||||
|
||||
전부 PASS 시 Task 2 완료 → Phase 2 brainstorming 재개 (이미 6 결정 + 디자인 섹션 1-2 OK).
|
||||
|
||||
---
|
||||
|
||||
## Self-Review
|
||||
|
||||
**1. Spec coverage:**
|
||||
|
||||
| Spec § | 요구사항 | Plan task |
|
||||
|--------|----------|----------|
|
||||
| §2 포함 (V1 자산 mv) | Task 1 Step 5 ✅ |
|
||||
| §2 포함 (web-ai/CLAUDE.md 신규) | Task 1 Step 7 ✅ |
|
||||
| §2 포함 (web-ai/start.bat 신규) | Task 1 Step 8 ✅ |
|
||||
| §2 범위 외 (Python import 변경 없음) | Task 1 Step 10 의 grep 으로 검증 ✅ |
|
||||
| §3.3 web-ai/CLAUDE.md 정확한 내용 | Task 1 Step 7 — 동일 markdown 본문 포함 ✅ |
|
||||
| §3.3 web-ai/start.bat 정확한 내용 | Task 1 Step 8 — 동일 bat 본문 포함 ✅ |
|
||||
| §3.4 load_dotenv 경로 갱신 | Task 1 Step 2 (grep) + Step 6 (갱신) ✅ |
|
||||
| §4 작업 순서 (사전 검토 → mv → 검증 → push → 사용자 검증) | Task 1 Step 1-13 + Task 2 ✅ |
|
||||
| §5 위험 (.env 로드 실패, 자동매매 중단 등) | Task 2 Step 1 의 first-start verification + load_dotenv 명시 ✅ |
|
||||
| §6.1 자동 검증 (pytest + grep) | Task 1 Step 3 (baseline) + Step 11 (post-mv) + Step 10 (grep) ✅ |
|
||||
| §6.2 수동 검증 (start.bat + /status + 30분 관측) | Task 2 Step 1-3 ✅ |
|
||||
| §8 DoD 8 항목 | 전체 (Task 1 + Task 2 합) ✅ |
|
||||
|
||||
No gaps.
|
||||
|
||||
**2. Placeholder scan:** No "TBD" / "implement later". load_dotenv 갱신은 Step 2 grep 결과에 의존하지만, Step 6 에 정확한 갱신 패턴 (2 코드 예시) 포함 — placeholder 아님.
|
||||
|
||||
**3. Type consistency:** N/A (refactor only, 새 함수/타입 0). 모든 step 의 명령어와 파일 경로 일관 — `signal_v1/` 표기 + `web-ai/` 표기 통일.
|
||||
|
||||
Plan passes self-review.
|
||||
Reference in New Issue
Block a user