web-page/docs/superpowers/specs/2026-05-17-signal-v2-phase4-signal-generator.md

# Confidence Signal Pipeline V2 — Phase 4: Signal Generator Design

**작성일**: 2026-05-17
**작성자**: gahusb
**상태**: Approved for implementation
**선행 spec**:
- Phase 0 architecture (`2026-05-15-confidence-signal-pipeline-v2-architecture.md`)
- Phase 1 stock WebAI API (`2026-05-15-signal-v2-phase1-webai-api.md`)
- Phase 2 web-ai pull worker (`2026-05-16-signal-v2-phase2-web-ai-pull-worker.md`)
- Phase 3a KIS data collection (`2026-05-16-signal-v2-phase3a-kis-data-collection.md`)
- Phase 3b Chronos-2 + momentum (`2026-05-16-signal-v2-phase3b-chronos-momentum.md`)

**브레인스토밍 결정 6개**:
- scope = A (신호 생성만, Phase 5 가 발송)
- trigger = A (매 분봉 cycle 후 일괄 평가)
- minute_score = A (Linear 5-level 1.0/0.7/0.5/0.3/0.0)
- 임계값 = A+ (6 env 외부화)
- state.signals schema = A (Phase 0 spec §5.2 그대로)
- 테스트 = A (9 단위 + 1 integration = 10 신규)

---

## 1. 목표

Phase 2/3a/3b 의 모든 산출을 종합해 Phase 0 spec §6.1/§6.2/§6.3 의 매수/매도/dedup 룰 적용. 임계값 통과한 신호를 `state.signals` 에 저장 + `SignalDedup` 으로 24h 중복 차단.

**Why**: Phase 5 (agent-office) 의 입력 계약 완성. signal_v2 가 자체적으로 매수/매도 신호 생성 → Phase 5 가 발송.

---

## 2. 범위

### 포함 (6 항목)

- ① `signal_generator.py` 신규 — `generate_signals(state, dedup, settings) -> None` (state mutating)
- ② `config.py` 확장 — 6 env (`STOP_LOSS_PCT`, `TAKE_PROFIT_PCT`, `CHRONOS_SPREAD_THRESHOLD`, `ASKING_BID_RATIO_THRESHOLD`, `CONFIDENCE_THRESHOLD`, `MIN_MOMENTUM_FOR_BUY`)
- ③ `state.py` 확장 — `signals: dict[str, dict]` (Phase 5 input)
- ④ `pull_worker.py` 확장 — 매 cycle 후 `generate_signals` 호출 + signature 확장 (dedup + settings)
- ⑤ `main.py` 의 lifespan poll_task 호출 시 dedup/settings 전달
- ⑥ 테스트 9 단위 + 1 integration = **10 신규** (45 → 55)

### Phase 4 산출 (Phase 5 input)

`state.signals[ticker]` — Phase 0 spec §5.2 schema:
```python
{
    "ticker": str, "name": str,
    "action": "buy" | "sell",
    "confidence_webai": float,
    "current_price": int,
    "avg_price": int | None,    # sell 시만
    "pnl_pct": float | None,
    "context": {
        "chronos_pred_1d": float (median),
        "chronos_pred_conf": float,
        "chronos_q10": float, "chronos_q90": float,
        "screener_rank": int | None,
        "screener_scores": dict | None,
        "minute_momentum": str,
        "asking_bid_ratio": float,
        "news_sentiment": float | None,
        "news_reason": str | None,
    },
    "as_of": str (ISO),
}
```

### 범위 외 (NOT)

- agent-office `/signal` HTTP POST (Phase 5)
- Qwen3 검증 + 이중 텔레그램 (Phase 5)
- 호가 변경 시 즉시 매도 trigger (Phase 7 backlog)
- 자동 매매 (Phase 8 backlog)
- ML 기반 룰 변종 (Phase 7 백테스트 후)
- `kospi_change`, `news_top` 컨텍스트 (Phase 7 backlog)
- 외부 API 호출 — Phase 4 는 state 만 사용 (pure function)

---

## 3. 파일 구조 + 변경 매트릭스

| 파일 | 작업 | 라인 |
|------|------|------|
| `signal_v2/signal_generator.py` | 신규 (generate_signals + 5 helpers) | ~250 |
| `signal_v2/config.py` | Settings 6 field 추가 | +15 |
| `signal_v2/state.py` | PollState `signals` 필드 | +2 |
| `signal_v2/pull_worker.py` | poll_loop signature + 매 cycle 호출 | +10 |
| `signal_v2/main.py` | lifespan poll_task 인자 추가 | +3 |
| `signal_v2/tests/test_signal_generator.py` | 9 단위 신규 | ~350 |
| `signal_v2/tests/test_pull_worker.py` | 1 integration 추가 | +50 |

**합계**: 7 파일 변경, 10 신규 테스트.

### 외부 의존성 신규

**없음**. signal_generator 는 순수 함수, 외부 라이브러리 0.

### 6 신규 env

| env | 기본값 | 의미 |
|-----|--------|------|
| `STOP_LOSS_PCT` | `-0.07` | 손절선 비율. `pnl_pct < 이 값` → 즉시 매도 |
| `TAKE_PROFIT_PCT` | `0.15` | 익절선 비율. `pnl_pct > 이 값` → 검토 알림 |
| `CHRONOS_SPREAD_THRESHOLD` | `0.6` | `(q90-q10)/max(|median|, 0.001) < 이 값` → 매수 통과 |
| `ASKING_BID_RATIO_THRESHOLD` | `0.6` | `bid_ratio >= 이 값` → 매수 통과 |
| `CONFIDENCE_THRESHOLD` | `0.7` | `confidence_webai > 이 값` → 신호 발생 |
| `MIN_MOMENTUM_FOR_BUY` | `strong_up` | 분봉 모멘텀 카테고리 |

---

## 4. 매수 룰 + Confidence

### 4.1 매수 룰 대상

- screener Top-N (`state.screener_preview.items`)
- portfolio 보유 종목 (추가 매수 검토, dedup 으로 중복 차단)

### 4.2 Hard gate (모든 조건 충족)

1. `state.chronos_predictions[ticker].median > 0` (다음날 상승)
2. `(q90 - q10) / max(|median|, 0.001) < settings.chronos_spread_threshold`
3. `state.minute_momentum[ticker] == settings.min_momentum_for_buy` (기본 strong_up)
4. `state.asking_price[ticker].bid_ratio >= settings.asking_bid_ratio_threshold`

### 4.3 Soft confidence (Phase 0 spec §6.1)

```python
chronos_conf = state.chronos_predictions[ticker]["conf"]
minute_score = MOMENTUM_SCORES[state.minute_momentum[ticker]]
# MOMENTUM_SCORES = {"strong_up": 1.0, "weak_up": 0.7, "neutral": 0.5,
#                    "weak_down": 0.3, "strong_down": 0.0}
screener_norm = 1 - (rank - 1) / 20 if rank is not None else 0.0
confidence_webai = chronos_conf * 0.5 + minute_score * 0.3 + screener_norm * 0.2
```

### 4.4 임계값

`confidence_webai > settings.confidence_threshold` (기본 0.7) → 신호 발생.

### 4.5 누락 처리

- portfolio (Top-N 외) 매수: `screener_rank = None` → `screener_norm = 0` (보수적)
- `chronos_predictions[ticker]` 누락 → silent (Hard gate 위반)
- `asking_price[ticker]` 누락 → silent

---

## 5. 매도 룰 + Dedup

### 5.1 매도 대상

portfolio holdings 만 (`state.portfolio.holdings`).

### 5.2 매도 룰 (Phase 0 spec §6.2)

**(a) 손절선 (즉시 trigger)**:
- `pnl_pct < settings.stop_loss_pct` (기본 -0.07)
- 다른 룰 무관 — 즉시 매도
- `confidence_webai = 1.0`

**(b) 익절선 (검토 알림)**:
- `pnl_pct > settings.take_profit_pct` (기본 0.15)
- "검토 권고" — 강제 매도 X
- `confidence_webai = 0.6`

**(c) 이상 신호**:
- `chronos_predictions[ticker].median < -0.01`
- `minute_momentum[ticker] == "strong_down"`
- `asking_price[ticker].bid_ratio < (1 - settings.asking_bid_ratio_threshold)` (매도세 ≥ 60%)
- confidence_webai = chronos_conf × 0.5 + inverted_minute × 0.3 + 1.0 × 0.2
- 임계값 > `settings.confidence_threshold`

### 5.3 우선순위 (같은 ticker 다중 trigger 시)

1. **손절** (Phase 0 spec §6.2 "즉시") — 다른 룰 우회
2. **이상 신호**
3. **익절선**

상위 trigger 시 하위 skip (한 종목당 한 cycle 1 매도 신호).

### 5.4 Dedup (Phase 0 spec §6.3 + Phase 2 SignalDedup)

```python
if dedup.is_recent(ticker, action, within_hours=24):
    continue  # silent
# 신호 dict 생성
state.signals[ticker] = {...}
dedup.record(ticker, action, confidence=confidence_webai)
```

Dedup 키 `(ticker, action)` — 같은 종목의 매수/매도 별도 추적, 충돌 없음.

손절선도 dedup 적용 (Phase 0 spec §6.3 "1일 1회 max").

---

## 6. State 통합 + pull_worker

### 6.1 PollState 확장

```python
signals: dict[str, dict] = field(default_factory=dict)
```

매 cycle 마다 **덮어쓰기 X** — 같은 ticker key 재발생 시 갱신, 그 외 유지. dedup 으로 중복 차단되므로 누적 안전. Phase 5 consumer 가 처리 후 본인 측 dedup.

### 6.2 pull_worker 흐름

```python
async def poll_loop(client, state, shutdown,
                   kis_client=None, chronos=None,
                   dedup=None, settings=None) -> None:
    while not shutdown.is_set():
        now = datetime.now(KST)
        if _is_market_day(now) and _is_polling_window(now):
            # 1. stock + KIS 분봉/호가 (Phase 2 + 3a)
            await _run_polling_cycle(client, state, kis_client=kis_client)
            # 2. 분봉 모멘텀 (Phase 3b)
            update_minute_momentum_for_all(state)
            # 3. 종가 트리거 시 Chronos (Phase 3b)
            if _is_post_close_trigger(now) and chronos and kis_client:
                await _run_post_close_cycle(kis_client, chronos, state)
            # 4. (신규 Phase 4) 신호 생성
            if dedup is not None and settings is not None:
                try:
                    generate_signals(state, dedup, settings)
                except Exception:
                    logger.exception("generate_signals failed")
        ...
```

### 6.3 main.py lifespan

```python
_ctx.poll_task = asyncio.create_task(
    poll_loop(
        _ctx.client, state_mod.state, _ctx.shutdown,
        kis_client=_ctx.kis_client,
        chronos=_ctx.chronos,
        dedup=_ctx.dedup,
        settings=settings,
    )
)
```

---

## 7. signal_generator.py 구조

```python
def generate_signals(state: PollState, dedup: SignalDedup, settings: Settings) -> None:
    """Phase 4 entry point — state mutating."""
    _evaluate_buy_signals(state, dedup, settings)
    _evaluate_sell_signals(state, dedup, settings)


def _evaluate_buy_signals(state, dedup, settings) -> None:
    """screener Top-N + portfolio 매수 후보 평가."""
    candidates = _buy_candidates(state)  # screener Top-N + portfolio holdings
    for ticker, rank in candidates:
        if not _check_buy_hard_gate(state, ticker, settings):
            continue
        confidence = _compute_buy_confidence(state, ticker, rank)
        if confidence <= settings.confidence_threshold:
            continue
        if dedup.is_recent(ticker, "buy", within_hours=24):
            continue
        state.signals[ticker] = _build_buy_signal(state, ticker, rank, confidence)
        dedup.record(ticker, "buy", confidence=confidence)


def _evaluate_sell_signals(state, dedup, settings) -> None:
    """portfolio 보유 종목 매도 평가 — 손절 > 이상 > 익절 우선순위."""
    if state.portfolio is None:
        return
    for holding in state.portfolio.get("holdings", []):
        ticker = holding["ticker"]
        # 우선순위 1: 손절선
        sell = _try_stop_loss(state, holding, settings)
        # 우선순위 2: 이상 신호
        if sell is None:
            sell = _try_anomaly(state, holding, settings)
        # 우선순위 3: 익절선
        if sell is None:
            sell = _try_take_profit(state, holding, settings)
        if sell is None:
            continue
        if dedup.is_recent(ticker, "sell", within_hours=24):
            continue
        state.signals[ticker] = sell
        dedup.record(ticker, "sell", confidence=sell["confidence_webai"])
```

Helper 함수:
- `_buy_candidates(state) -> list[tuple[ticker, rank | None]]`
- `_check_buy_hard_gate(state, ticker, settings) -> bool`
- `_compute_buy_confidence(state, ticker, rank | None) -> float`
- `_build_buy_signal(state, ticker, rank, confidence) -> dict`
- `_try_stop_loss(state, holding, settings) -> dict | None`
- `_try_anomaly(state, holding, settings) -> dict | None`
- `_try_take_profit(state, holding, settings) -> dict | None`
- `_build_context(state, ticker, rank, ...) -> dict`

---

## 8. 테스트 (10 신규)

### 8.1 `test_signal_generator.py` (9 단위)

| # | 이름 | Setup | 검증 |
|---|------|-------|------|
| 1 | `test_buy_signal_when_all_conditions_pass_and_confidence_high` | chronos +2%, narrow, strong_up, bid_ratio 0.7, rank 1 | state.signals[ticker]["action"]=="buy", confidence > 0.7, dedup.record 호출 |
| 2 | `test_silent_when_chronos_median_negative` | median -1% | state.signals empty |
| 3 | `test_silent_when_distribution_spread_too_wide` | spread 1.0 | empty |
| 4 | `test_silent_when_momentum_not_strong_up` | weak_up | empty |
| 5 | `test_silent_when_bid_ratio_below_threshold` | 0.5 | empty |
| 6 | `test_silent_when_confidence_below_threshold` | rank 20 + median +0.5% (chronos_conf 낮음) → confidence < 0.7 | empty |
| 7 | `test_sell_signal_when_stop_loss_triggered` | pnl_pct -0.08 | "sell" + confidence 1.0 |
| 8 | `test_sell_signal_when_take_profit_triggered` | pnl_pct 0.16 | "sell" + confidence 0.6 |
| 9 | `test_silent_when_dedup_recently_sent` | dedup.is_recent True | empty |

### 8.2 `test_pull_worker.py` (1 integration)

| # | 이름 | 검증 |
|---|------|------|
| 10 | `test_poll_loop_calls_generate_signals_after_cycle` | mock state setup + mock dedup → poll_loop 1 cycle → state.signals 갱신 |

**합계**: 9 + 1 = **10 신규**. 45 → 55 total.

---

## 9. 위험 / 운영 / DoD

### 9.1 위험 매트릭스

| 위험 | 완화 |
|------|------|
| Phase 0 spec 의 confidence 공식이 실 운영과 안 맞음 | 6 env 외부화 → Phase 7 IC 검증 후 .env 조정 |
| Chronos 누락 (장 시작 첫 cycle) | Hard gate 위반 → silent. 종가 cron 후 매수 신호 가능 |
| Dedup DB 손상 | WAL + busy_timeout. 운영자 manual 복구 (signal_v2.db 삭제) |
| 동시 cycle 에서 같은 종목 buy + sell trigger | dedup PK `(ticker, action)` 별도 추적 — 충돌 없음 |
| portfolio 매수 → screener_norm=0 → 신호 발생 어려움 | 보수적. 다른 component 높아야 신호. 의도된 동작 |
| 손절선 trigger 후 24h 추가 손실 → 다음 알림 차단 | 운영적 허용 (Phase 0 spec §6.3 1일 1회 max) |
| 신호 빈도 너무 적음 | 4주 IC 검증 + 임계값 완화 |
| 신호 빈도 너무 많음 (false positive) | dedup + 임계값 강화. Phase 7 |
| 매도 우선순위 잘못 (손절 > 이상 > 익절) | 테스트 케이스로 검증 + 코드 명시 |
| signals dict 누적 (cycle 사이 stale entry) | dedup 으로 중복 차단되므로 안전. Phase 5 consumer 가 처리 후 본인 측 marker |

### 9.2 운영 영향

| 항목 | 영향 |
|------|------|
| 다운타임 | signal_v2 재기동 ~5초 |
| 사용자 영향 | 없음 (Phase 5 까지 발송 없음) |
| `.env` 갱신 | optional 0-6개 (기본값 충분) |
| V1 영향 | 0 |
| KIS API 부하 | 0 (Phase 4 는 외부 호출 없음) |

### 9.3 Phase 4 완료 조건 (DoD)

- [ ] `signal_v2/signal_generator.py` 신규 (generate_signals + 8 helpers)
- [ ] `signal_v2/config.py` Settings 에 6 field 추가 (default 있음)
- [ ] `signal_v2/state.py` PollState `signals` field
- [ ] `signal_v2/pull_worker.py` poll_loop signature + 매 cycle 호출
- [ ] `signal_v2/main.py` lifespan 의 poll_task 인자 (dedup, settings) 추가
- [ ] 9 단위 + 1 integration 테스트 PASS (총 55)
- [ ] 운영 smoke: signal_v2 시작 → 1 cycle 후 state.signals 빈 dict (운영 시간대 신호 발생 가능 종목 없을 시 정상) 또는 ≥ 1 신호 생성
- [ ] V1 무영향
- [ ] git push

---

## 10. Phase 5 와의 관계

본 Phase 4 완료 후 즉시 **Phase 5 (agent-office /signal + Qwen3 + 이중 텔레그램)** brainstorming. 의존성:

```
[Phase 4 spec/plan/실행]   →   [Phase 5 spec/plan/실행]
       3-5일                       2주
```

Phase 5 의 입력 = 본 spec 의 `state.signals[ticker]` (state polling 또는 HTTP push). Phase 5 작업:
- agent-office `/signal` endpoint 신설 (Phase 0 spec §5.2 schema 수신)
- web-ai → agent-office HTTP client 추가 (signal_v2 측)
- web-ai 의 Ollama Qwen3 14B Q4 설치 + agent-office 의 LLM 검증 호출
- 이중 텔레그램 (본인 풀 / 아내 lite)

---

## 11. Backlog (본 spec NOT)

- 호가 변경 시 즉시 매도 trigger — Phase 7 운영 후 검토
- `kospi_change` 컨텍스트 (KIS 지수 fetch) — Phase 7
- `news_top` 컨텍스트 (news_sentiment.reason 다중 추출) — Phase 7
- 매수/매도 ML 룰 — Phase 7 백테스트 후
- portfolio 매수의 screener_norm fallback (다른 default 값) — IC 검증 후
- 신호 hit-rate 대시보드 — Phase 7
- 분할 매수/매도 전략 — Phase 7 이후
- 자동 매매 (실주문) — Phase 8
- 손절선 dedup 면제 (즉시성 위해) — Phase 7 운영 검증 후