From 8e1b20190d1ed5d3127657f3f87d1cc61f4872b9 Mon Sep 17 00:00:00 2001 From: gahusb Date: Fri, 3 Jul 2026 11:05:57 +0900 Subject: [PATCH] =?UTF-8?q?docs(readme):=20trade-monitor=20=EC=9B=8C?= =?UTF-8?q?=EC=BB=A4=20=EC=84=B9=EC=85=98=20+=20/infra=20=EA=B4=80?= =?UTF-8?q?=EC=B8=A1=20=EA=B7=9C=EC=B9=99=20=EB=B0=98=EC=98=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 59 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index ec23e29..28d0f79 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ Windows AI 머신(AMD 9800X3D + RTX 5070 Ti 16GB)에서 동작하는 두 영역의 서비스: 1. **ai_trade** — Confidence Signal Pipeline V2. NAS stock 백엔드와 KIS Open API를 결합해 매수/매도 신호를 생성하는 FastAPI 워커. -2. **services** — NAS↔Windows 분산 렌더링 워커(인스타 카드 / 음악 / 영상 / 이미지) + task-watcher. +2. **services** — NAS↔Windows 분산 워커: 렌더링(인스타 카드 / 음악 / 영상 / 이미지) + task-watcher + **trade-monitor**(실시간 매매 알람). 상위 워크스페이스 컨텍스트는 `../CLAUDE.md`, 본 디렉토리 상세는 `CLAUDE.md`, 운영 체크포인트는 `CHECK_POINT.md` 참조. @@ -20,6 +20,7 @@ Windows AI 머신(AMD 9800X3D + RTX 5070 Ti 16GB)에서 동작하는 두 영역 | `services/video-render/` | sora / veo / kling / seedance 4 provider 영상 생성 게이트웨이. `queue:video-render` 소비. | `:18712` | | `services/image-render/` | gpt_image / nano_banana / flux(ComfyUI 로컬) 3 provider. `queue:image-render` 소비. | `:18714` | | `services/task-watcher/` | 박재오 작업 시간대에 `queue:paused` 토글 → 워커 일시 정지. | `:18713` | +| `services/trade-monitor/` | 실시간 매매 알람. monitor-set pull → KIS 시세 + TA 조건(§6 8종) → report + heartbeat(kind=trader). 무상태. | `:18715` | | `legacy/signal_v1/` | ⚠ **DEPRECATED** (2026-05-19). LSTM 봇. 자동 실행 차단됨. | OFF | --- @@ -130,6 +131,60 @@ redis-cli -h 192.168.45.54 KEYS 'processing:*' --- +## trade-monitor — 실시간 매매 알람 워커 (신규 2026-07-03) + +NAS stock 백엔드(`:18500`)에서 `monitor-set`을 60초마다 pull하고, KIS 실시간/일봉 시세로 TA 조건을 평가해 발화집합을 `report`로 전송. NAS가 edge diff로 신규 알림만 텔레그램/프론트에 노출. **워커 무상태**(dedup은 NAS 영속). 포트 `:18715`, WSL2 Docker. 상세 설계·조건 규칙은 `services/trade-monitor/DESIGN.md`. + +### 루프 (1분) + +1. `GET /api/webai/trade-alert/monitor-set` (X-WebAI-Key) → buy_targets(watch∪screener) + sell_targets(보유 avg_price/qty/holding_high) + buy_params/exit_params + session. +2. `session=="closed"`면 KIS 호출 0, idle. **비-KRX(알파벳) 티커 skip**(워커 책임). +3. KIS quote + 일봉 250봉 → 지표 계산 → 조건 평가(종목 단위 실패 격리). +4. `POST /api/webai/trade-alert/report {as_of, firing:[...]}` — 빈 배열도 전송(edge clear). +5. heartbeat `worker:trade-monitor:heartbeat` EX45 (kind=trader, state=market_open|market_closed|idle + last_alert_at). 60초 루프 > TTL45 만료갭 회피 위해 **15초 독립 태스크**. + +### 조건 (§6 — `condition` 문자열이 FE 라벨/뱃지로 그대로 매핑됨) + +- **매수**: `buy_ma20_pullback`(정배열 + ma20 근접 반등), `buy_breakout`(20봉 고점 돌파 + 거래량 배수), `buy_rsi_bounce`(RSI 과매도 반등, 무상태). +- **매도**: `sell_stop_loss`, `sell_take_profit`, `sell_trailing_stop`, `sell_ma_break`(ma50/ma200 severity), `sell_climax`(거래량 급증 + 윗꼬리 — holdings_intel 정합 예정). + +### 핵심 파일 + +| 파일 | 책임 | +|------|------| +| `config.py` | Settings (`TM_` 접두사, ai_trade와 분리) | +| `indicators.py` | 순수: `sma` / `rsi_series`(Wilder) / `highest_high` | +| `conditions.py` | 순수 §6: `evaluate_buy` / `evaluate_sell` | +| `kis_client.py` | KIS **자체 OAuth 토큰** + `get_quote` + `get_daily_ohlcv` + 0.5s throttle | +| `nas_client.py` | monitor-set / report (X-WebAI-Key + retry) | +| `monitor.py` | `run_cycle` / `monitor_loop` / `make_state_fn` | +| `main.py` | FastAPI lifespan + `_shared.heartbeat_loop` 배선 + `/health` | + +### 환경 변수 + +| 변수 | 기본 | 설명 | +|------|------|------| +| `NAS_BASE_URL` | `http://192.168.45.54:18500` | stock 백엔드 | +| `WEBAI_API_KEY` | (필수) | X-WebAI-Key | +| `REDIS_URL` | `redis://192.168.45.54:6379` | heartbeat | +| `TM_KIS_APP_KEY` / `TM_KIS_APP_SECRET` / `TM_KIS_ACCOUNT` | (필수) | KIS **전용** 자체 토큰(ai_trade와 분리 발급 → 토큰 상호 무효화·EGW00201 회피) | +| `TM_KIS_IS_VIRTUAL` | `0` | 실전/모의 | +| `TM_LOOP_INTERVAL` | `60` | 루프 주기(초) | +| `TM_CLIMAX_VOL_MULT` | `3.0` | sell_climax 거래량 배수 (→ monitor-set `exit_params.climax_vol_x`로 중앙화 예정) | + +### 상태 + +⏳ 구현·머지 완료(테스트 34/34), **미배포**. 배포 전: ① 전용 KIS 앱키 발급·주입(박재오 진행 중) ② `sell_climax` holdings_intel 정합(`price < day_high × 0.97` + `exit_params` 파라미터화) ③ 첫 운영 KIS 필드 검증. BE가 `node_monitor.WORKER_REGISTRY`에 등재 완료 → 배포 시 `/api/agent-office/nodes`·web-ui `/infra`에 trader 노드 자동 노출(미배포 동안 down, 무경보). + +### 시작 (NAS, WSL2 Docker) + +```bash +cd services +docker compose up -d trade-monitor +``` + +--- + ## 환경 변수 (ai_trade) | 변수 | 기본 | 설명 | @@ -168,6 +223,7 @@ cd services/insta-render && python -m pytest tests/ -q cd services/music-render && python -m pytest tests/ -q cd services/video-render && python -m pytest tests/ -q cd services/image-render && python -m pytest tests/ -q +cd services/trade-monitor && python -m pytest tests/ -q # 34 tests ``` **`.venv` 한글 사용자 경로 깨짐**으로 시스템 Python(`C:\Users\jaeoh\AppData\Local\Programs\Python\Python312\python.exe`) 사용 권장. 또는 `py -3.12 -m pytest …`. @@ -183,6 +239,8 @@ cd services/image-render && python -m pytest tests/ -q 5. **services worker_id** — env로 명시 권장. hostname 기반 default는 컨테이너 재기동 시 바뀌어 orphan 분실 위험. 6. **dead-letter 누적** — `redis-cli LLEN dead_letter:*` 정기 점검 필요. 7. **Dockerfile build context** — `services/` 루트 (각 worker 디렉토리 아님). compose 변경 동반. +8. **분산 워커 /infra 관측 필수 (팀 규칙)** — 모든 WSL docker 워커는 heartbeat(`worker::heartbeat` EX45) + BE `node_monitor.WORKER_REGISTRY` 등재 + `/infra` 노출이 필수. trade-monitor는 kind=trader로 등재됨. +9. **trade-monitor KIS 앱키 분리** — ai_trade와 **다른 전용 app_key**(`TM_KIS_*`) 사용. 같은 app_key 공유 시 토큰 상호 무효화 + EGW00201. 실전 최대 89앱 발급 가능. ---