# 실시간 매매 알람 (Real-time Trade Alerts) — 설계 스펙

- 작성일: 2026-07-02
- 상태: 설계 승인됨 (사용자 리뷰 대기)
- 관련 세션: BE(web-backend, 본 스펙 주도) · AI(web-ai 워커) · FE(web-ui 탭)

## 1. 목표

장이 열려 있는 동안(**시간외 포함**) 실시간으로 주가 기준치를 분석해, 조건 충족 시 **매수/매도 알람**을 텔레그램으로 **사용자 + 아내** 둘 다에게 전송한다. 기술적 분석(TA) 계산은 **Windows PC의 docker 워커**에서 수행한다.

기존에는 이 판단들이 EOD(하루 1회)로만 돌았다:
- 매수 후보 = 스크리너(평일 16:30) · 매도/보유 advisory = holdings_intel(08:30/16:50).

이번 작업의 핵심 = **동일 판단을 장중(+시간외) 1분 주기 실시간으로 전환 + 조건 충족 즉시 알람**.

## 2. 확정된 요구사항 (사용자 결정)

| 항목 | 결정 |
|------|------|
| 매수 유니버스 | **watchlist(사용자 관리) ∪ 당일 스크리너 후보** |
| 매수 트리거 | **TA 자동 시그널**(수동 목표가 없음) |
| 매도 트리거 | **기존 exit 룰 + 트레일링 스톱** |
| 감시 주기/세션 | **1분 폴링** · 장전 시간외 08:30–09:00 · 정규장 09:00–15:30 · 시간외 단일가 16:00–18:00 |
| 중복 방지 | **상태 전이(edge-triggered)** — 거짓→참 전이 시만 알림, 참 유지 중 무알림, 재무장 |
| watchlist 관리 | **텔레그램 봇 명령 + web-ui 탭 둘 다** |
| 수신자 | **사용자 + 아내 둘 다**(매수·매도 모두) |
| TA 연산 위치 | **Windows WSL2 docker 신규 워커** |
| 트레일링 스톱 기본값 | 보유기간 고점 대비 **−10%**(파라미터화) |
| 매수 신호 | 지지선 되돌림(MA20/50) · 돌파(전고점/52주) · RSI 과매도 반등 |

## 3. 아키텍처

```
[Windows WSL2 docker] trade-monitor 워커  (web-ai · AI세션)
  1분 루프 (KST 세션 게이팅)
   ① GET  NAS  /api/webai/trade-alert/monitor-set   (X-WebAI-Key)
   ② KIS 실시간/시간외 시세 + 분봉/일봉 → TA 계산
   ③ 조건 평가 → 현재 발화집합 F = {(ticker, kind, condition)}
   ④ POST NAS  /api/webai/trade-alert/report {firing: F}   (X-WebAI-Key)
   ⑤ heartbeat: worker:trade-monitor:heartbeat (EX45, 관측 편입)
        │
        ▼
[NAS] stock (:18500 · web-backend · BE)
   • watchlist·alert_state(edge dedup, 영속)·alert_history·holding high-water
   • monitor-set 조립(watchlist ∪ screener 후보 ∪ 보유) + 세션/휴장 게이팅
   • report 수신 → edge diff(F vs 직전 발화) → 신규 edge를 agent-office로 push
        │ (텔레그램 전송 성공 시에만 alert_state 갱신)
        ▼
[NAS] agent-office (:18900 · web-backend · BE)
   • POST /api/agent-office/stock/trade-alert → 텔레그램(너+아내)
   • 봇 명령 /watch /unwatch /watchlist → stock watchlist CRUD
   • 알람 activity feed 편입

[web-ui] 관심종목 탭 (FE세션) — watchlist CRUD + 알람 이력 뷰
```

**설계 원칙**
- TA/조건판정 = Windows(요구사항). **edge 중복판정 상태 = NAS 영속** → 워커 재시작해도 재알림 스팸 없음(youtube_publisher 교훈 재적용).
- 워커는 dedup 상태를 **안 가진다**. 매 사이클 "현재 발화집합 전체"만 보고 → NAS가 diff(단일 진실원천).
- 워커의 대외 채널은 **NAS stock 한 곳**(기존 ai_trade↔stock의 `X-WebAI-Key` 재사용). 텔레그램 발송은 stock→agent-office push(기존 realestate→agent-office/notify 패턴).

## 4. DB 스키마 (stock.db)

```sql
-- 매수 감시 관심종목 (사용자 관리)
CREATE TABLE IF NOT EXISTS watchlist (
  ticker      TEXT PRIMARY KEY,
  name        TEXT,
  note        TEXT,
  params_json TEXT NOT NULL DEFAULT '{}',   -- 종목별 조건 오버라이드(선택)
  added_at    TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
);

-- edge 중복판정 상태 (영속 — 재시작 스팸 방지의 핵심)
CREATE TABLE IF NOT EXISTS trade_alert_state (
  ticker           TEXT NOT NULL,
  kind             TEXT NOT NULL,   -- 'buy' | 'sell'
  condition        TEXT NOT NULL,   -- ex) buy_ma20_pullback, sell_trailing_stop
  currently_firing INTEGER NOT NULL DEFAULT 0,
  first_fired_at   TEXT,
  last_fired_at    TEXT,
  last_seen_at     TEXT,
  PRIMARY KEY (ticker, kind, condition)
);

-- 알람 이력
CREATE TABLE IF NOT EXISTS trade_alert_history (
  id          INTEGER PRIMARY KEY AUTOINCREMENT,
  ticker      TEXT NOT NULL,
  name        TEXT,
  kind        TEXT NOT NULL,
  condition   TEXT NOT NULL,
  price       REAL,
  detail_json TEXT,
  fired_at    TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
);
CREATE INDEX IF NOT EXISTS idx_tah_fired ON trade_alert_history(fired_at DESC);
```

보유기간 고점(트레일링 스톱용) high-water는 `krx_daily_prices`(기존)에서 lookback max로 계산하거나 별도 컬럼으로 관리 — 구현 계획에서 확정(v1: 포지션 최초 관측 이후 일봉 고가 max, 없으면 최근 N일).

## 5. 계약 (Contracts) — cross-repo 잠금 대상

### 5.1 NAS stock ↔ Windows 워커 (X-WebAI-Key)

`GET /api/webai/trade-alert/monitor-set`
```json
{
  "session": "pre | regular | after | closed",
  "as_of": "2026-07-02T09:01:00+09:00",
  "buy_targets":  [{"ticker":"005930","name":"삼성전자","source":"watch|screener","params":{}}],
  "sell_targets": [{"ticker":"000660","name":"SK하이닉스","avg_price":180000,"qty":10,
                    "holding_high":210000,"params":{}}],
  "buy_params":  {"rsi_oversold":30,"breakout_vol_mult":1.5,"pullback_pct":0.02},
  "exit_params": {"stop_pct":0.08,"take_pct":0.25,"trailing_pct":0.10}
}
```
- `session=closed`면 워커는 KIS 호출 없이 sleep.

`POST /api/webai/trade-alert/report`
```json
{ "as_of":"2026-07-02T09:01:00+09:00",
  "firing":[ {"ticker":"005930","kind":"buy","condition":"buy_ma20_pullback",
              "price":71500,"detail":{"ma20":71200,"rsi":34}} ] }
```
응답: `{ "new_alerts": <int>, "cleared": <int> }`
- NAS가 `firing` vs `trade_alert_state[firing=1]` diff → 신규 edge만 텔레그램.

### 5.2 stock → agent-office (내부)

`POST /api/agent-office/stock/trade-alert`
```json
{ "alerts":[ {"ticker":"005930","name":"삼성전자","kind":"buy",
              "condition":"buy_ma20_pullback","price":71500,
              "detail":{...},"fired_at":"..."} ] }
```
→ agent-office가 너+아내에게 텔레그램. (realestate/notify 패턴)

### 5.3 stock watchlist CRUD (web-ui + agent-office 봇)
- `GET /api/stock/watchlist`
- `POST /api/stock/watchlist` `{ticker, note?}`
- `DELETE /api/stock/watchlist/{ticker}`
- `GET /api/stock/trade-alerts?days=N` (이력, web-ui용)

### 5.4 워커 heartbeat (관측 편입)
`worker:trade-monitor:heartbeat` EX45, 값 JSON `{name:"trade-monitor",kind:"trader",state:"market_open|market_closed|idle",ts,last_alert_at,...}`. `/api/agent-office/nodes` workers[]에 추가.

## 6. 알람 조건 (Windows 워커가 계산)

**매수** (buy_targets):
- `buy_ma20_pullback` — MA20>MA50>MA200 정렬 + 저가가 MA20/50에 `pullback_pct` 이내 접근 후 종가 반등
- `buy_breakout` — 종가 > (전 N일 고점 또는 52주 신고가) + 거래량 > `breakout_vol_mult`×20일평균
- `buy_rsi_bounce` — RSI(14)가 `rsi_oversold` 아래로 내려갔다가 **봉 시리즈 내에서** 다시 상향 돌파(최근 봉에서 30 상향 크로스). 워커는 무상태 — 매 사이클 봉 데이터로 크로스를 계산(cross-cycle 메모리 불필요)

**매도** (sell_targets):
- `sell_stop_loss` — (price−avg)/avg ≤ −`stop_pct`
- `sell_ma_break` — 종가 < MA50 (심각: < MA200)
- `sell_take_profit` — (price−avg)/avg ≥ `take_pct`
- `sell_climax` — 급등 소진(holdings_intel climax 로직 이식)
- `sell_trailing_stop` — price ≤ holding_high × (1 − `trailing_pct`)

## 7. 데이터 흐름 — edge dedup (NAS)

```
매 1분 report 수신 시:
  F        = report.firing 집합
  prev     = SELECT (ticker,kind,condition) FROM trade_alert_state WHERE currently_firing=1
  new_edge = F − prev
  cleared  = prev − F
  for e in new_edge:
      ok = agent_office.send_trade_alert(e)          # 텔레그램
      if ok:
          INSERT trade_alert_history(e)
          UPSERT trade_alert_state(e, firing=1, fired/last=now)
      # 실패 시 상태 미갱신 → 다음 사이클 재시도
  for c in cleared:
      UPDATE trade_alert_state SET firing=0 WHERE key=c   # 재무장
  UPDATE last_seen_at for all F
```
- 영속 `trade_alert_state` → 워커·NAS 재시작에도 재알림 스팸 없음.
- 텔레그램 실패 시 firing 미표시 → 재시도 보장(node_monitor "성공 시만 갱신" 관용).

## 8. 세션/휴장 게이팅

NAS `monitor-set.session` 필드가 KST 시각 + `holidays.json`(`is_market_open`)으로 판정:
- pre 08:30–09:00 / regular 09:00–15:30 / after 16:00–18:00 → 그 외/휴장 = closed.
- 워커는 `closed`면 sleep. (불필요 KIS 호출·알람 차단)

## 9. 에러 처리

- 워커: KIS 실패 → 해당 사이클 skip + 다음 분 재시도, 종목별 실패 격리. heartbeat로 생사 노출.
- NAS: 워커 인증 `X-WebAI-Key`. 텔레그램 실패 → 상태 미갱신. `report`는 멱등(같은 F 재전송 무해).
- 워커 다운 시 알람 정지 → node_monitor 경보(기존 관측)로 감지.

## 10. 테스트 전략 (BE, TDD)

- watchlist CRUD (추가/중복/삭제/조회)
- monitor-set 조립 (watchlist ∪ screener ∪ 보유, 세션 게이팅, 휴장)
- **edge diff 로직**: 신규 edge만 알림 / 참 유지 무알림 / 해제 후 재발화 재알림 / 재시작 지속성(영속 상태)
- 텔레그램 전송 실패 시 상태 미갱신(재시도)
- alert_history 기록 / trade-alerts 조회
- agent-office: /watch·/unwatch·/watchlist 봇 명령 → stock CRUD, trade-alert notify → 텔레그램 포맷(너+아내)
- webai 계약 엔드포인트(monitor-set/report) 스키마·인증

## 11. 작업 분담

| repo | 세션 | 산출물 | 상태 |
|------|------|--------|------|
| **web-backend** (stock + agent-office) | **BE(본 세션)** | DB·watchlist·edge·webai 계약·텔레그램·봇 | 이번에 구현 |
| **web-ai** (`services/trade-monitor/` WSL2 docker) | AI세션 | 1분 루프·KIS·TA·조건평가·report·heartbeat | 계약 넘김 |
| **web-ui** (관심종목 탭) | FE세션 | watchlist CRUD·조건·이력 뷰 | 계약 넘김 |

- 계약(§5)은 co-gahusb로 잠근 뒤 3세션 병렬.
- 워커 재빌드는 로컬 docker(사용자): `wsl -d Ubuntu-24.04 -- docker compose up -d --build trade-monitor`.

## 12. 범위 밖 (YAGNI / 후속)
- 실주문 자동 집행(알람 전용, KIS 주문 X).
- KIS 웹소켓 실시간 틱(1분 폴링으로 충분).
- 종목별 수동 목표가(이번은 TA 자동만).
- 백테스트/성과 추적(후속 슬라이스).