docs(readme): trade-monitor 워커 섹션 + /infra 관측 규칙 반영

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:<name>: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앱 발급 가능.
 
 ---