# BAT-048 Design

- Status: draft
- Batch: BAT-048

---

> **Design Review 게이트**: 이 문서의 Key Decisions(KD-1, KD-2)와 REQ-097 알람 스파이크 분석(섹션 "알람 능력 스파이크 — REQ-097")은 팀장·사장님의 design review 승인 후 run-batch-implementation으로 이어진다. 아래 권고안은 trex-core-dev가 코드 분석 근거로 작성한 것이며 팀장이 KD-1/KD-2를, 사장님이 알람 M2 포함 여부(OQ-1)를 최종 확정한다.

---

## Architecture Summary

이 batch의 핵심 변경은 `application/execution.py` 내 체결가 결정 로직에 국소화된다. 아키텍처 계층상 변경 위치는 **application 레이어 전용**이며, wire 계약·adapter·domain은 불변이다.

현재 문제 흐름:
```
KIS.poll_fill()
  → FillStatus(avg_price=None or 0.0)
      → _on_filled / _on_partial_cancel
            fill_price = 0.0  [← 현재: avg_price=None이면 old_avg(=0) 사용]
          → slot.avg_price = 0  [슬롯 평단 0 오염, 영구 — clear_dispatch 이후 재폴링 없음]
      → _record_ledger
            price = 0.0  [← 현재: avg_price=None이면 0.0 통과]
          → LedgerWorkItem(price=0.0)  [원장 cost basis 0 오염]
```

변경 후 흐름:
```
KIS.poll_fill()
  → FillStatus(avg_price=None or 0.0)
      → _resolve_fill_price(fs, slot)          [신규 헬퍼, application 레이어]
            → slot.limit_price 백필             [지정가 양수이면 사용]
            → 폴백 정책 적용(KD-2 확정 후)     [지정가마저 없으면]
            → _log.warning(백필 WARN)           [REQ-096 AC-1]
      → _on_filled / _on_partial_cancel
            fill_price = _resolve_fill_price 결과   [0 아닌 값]
          → slot.avg_price = 정상 가중평균
      → _record_ledger
            price = 동일 결과값                 [0 아닌 값]
          → LedgerWorkItem(price > 0)
```

변경 계층:
- `trex_core/application/execution.py` (application 레이어) — 백필 헬퍼 + 분기 + WARN 로그
- `tests/application/test_execution.py` — 신규 AC 테스트
- `docs/runtime-flows.md`, `docs/operations.md` — 갱신 (implementation 후)

불변 영역:
- `trex_core/adapters/broker/kis.py` — adapter 불변 (KD-1 근거)
- `trex_core/adapters/broker/paper.py` — adapter 불변 (paper는 항상 양수 avg_price 반환)
- AMQP wire 계약 (slots RPC payload / trex.events 스키마) — NFR-1

## Changed Areas

- Docs:
  - `docs/runtime-flows.md` — 체결 처리 흐름에 백필 분기 추가 (implementation 완료 후)
  - `docs/operations.md` — 백필 WARN 발생 시 운영자 점검 절차 추가 (implementation 완료 후)
- Modules:
  - `trex_core/application/execution.py` — `_resolve_fill_price`(신규 헬퍼), `_on_filled`·`_on_partial_cancel`·`_record_ledger`에 분기 삽입
  - `tests/application/test_execution.py` — 신규 AC 커버 테스트
- Interfaces:
  - `LedgerTrade.price` 필드: 0 → 양수 값으로 정정. 필드 타입/이름 변경 없음(NFR-1).
  - slots RPC `avg_price` 필드: 0 → 양수 값으로 정정. 스키마 변경 없음(NFR-1).

## Key Decisions

### KD-1: 백필 결정 지점 — application 레이어 단일화 권고

**권고: `application/execution.py`의 `_resolve_fill_price` 헬퍼로 단일화. `adapters/broker/kis.py`는 불변.**

#### 분석 근거

**현재 kis.py의 avg_price 처리 패턴** (`:209`, `:219`, `:232`, `:238`, `:243`):
```python
# 완전체결(:209)
fill_price = float(avg) if avg else 0.0
# ...
avg_price=fill_price or None,   # 0.0 → None으로 변환(:219)

# 부분취소(:232)
fill_price = float(avg) if avg else 0.0
# ...
avg_price=fill_price or None,   # 동일 패턴(:238)

# 부분체결(아직 pending, :243)
avg_price=float(avg) if avg else None   # 미체결분은 그대로
```

kis.py는 이미 `avg_price=None`을 FillStatus로 정직하게 전달하는 구조다. 이 층에서 백필을 하려면 **kis.py가 `slot.limit_price`를 알아야** 하는데, `poll_fill(broker_order_id, side, symbol)` 시그니처에 슬롯 컨텍스트(`slot`)가 없다. 따라서 adapter에서 백필하려면 시그니처 변경(`BrokerPort.poll_fill` 확장)이 필요하고 이는 포트 계약 변경이다.

**paper.py 일관성**: paper 브로커는 `_Order.__init__`에서 `self.price = float(req.limit_price) if req.limit_price is not None else 1000.0`으로 항상 양수 avg_price를 반환한다. paper에는 백필 분기가 필요 없어 adapter 통일 구현의 이점이 없다.

**dcy-021 잔고 재구성 경로**: `reconcile()`은 `_poll(r)`을 호출 → 동일한 `_on_filled`/`_on_partial_cancel`을 통과한다. application에 백필 헬퍼를 두면 재구성 경로도 동일 헬퍼를 자동으로 탄다. adapter에 두면 재구성 경로에서 kis.py → FillStatus(avg_price=None) → application으로 None이 그대로 전달되는 차이가 생긴다(일관성 깨짐).

**결론**: application 단일화가 유일하게 porter 계약을 건드리지 않고, 모든 경로(KIS 완전체결/부분취소/재구성/paper)에서 동일 헬퍼를 탄다.

**adapter 방식의 장단점 (기각 이유)**:
- 장점: adapter 경계에서 일찍 정정 → application이 항상 양수 fill_price를 받는다는 불변식 성립.
- 단점: `BrokerPort.poll_fill` 시그니처에 `slot` 컨텍스트 추가 필요(포트 계약 변경) / paper도 수정 필요 / paper는 avg_price가 이미 양수여서 불필요한 중복 코드.

**application 방식의 장단점 (권고 이유)**:
- 장점: BrokerPort/adapter 불변 / paper 불변 / reconcile 자동 일관성 / `slot.limit_price` 직접 접근 가능.
- 단점: `_on_filled`/`_on_partial_cancel`/`_record_ledger` 세 지점에 분기 삽입 필요 → 헬퍼로 추출해 DRY 유지.

**팀장 승인 필요**: 이 결정이 확정되어야 Phase A 구현이 시작된다.

---

### KD-2: 지정가 부재/≤0 최종 폴백 정책 — skip+강 WARN 권고

**권고: `slot.limit_price`마저 None 또는 ≤0인 극단 케이스는 "체결 처리를 skip하되 강 WARN 로그 발행" 정책.**

#### 분석 대상 후보

| 후보 | 설명 | 장점 | 단점 | 안전성 | 구현비용 |
|---|---|---|---|---|---|
| **A: 재폴링 (체결 처리 보류)** | avg_price=None + limit_price=None 이면 이번 틱 처리를 skip, 다음 틱 재폴링 | KIS가 다음 틱에 정상 avg를 줄 수 있음 | 완전체결 후 `clear_dispatch` 전에 재폴링이 막힘 — 완전체결 케이스에서 재폴링 경로가 없어 영구 대기. `_on_filled` 내부에서 skip하면 슬롯이 PENDING_BUY에 잠기고 타임아웃/watchdog 경로가 구조에 의존. | 낮음 (영구 교착 가능) | 높음 (complete fill 케이스 구분 필요) |
| **B: 직전가/현재가 조회** | KIS에 현재가(`get_current_price`) 추가 조회 → 해당 가격으로 백필 | 지정가보다 실제 시세에 가까운 근사 | (1) `BrokerPort`에 `get_current_price` 추가 필요(포트 계약 변경) (2) KIS 추가 API 호출(타임아웃, 네트워크 실패) (3) 매우 드문 케이스를 위한 복잡도 증가 (4) safety_sell.py의 `get_current_price`(paper 전용 구현)가 있지만 KIS에는 미구현 | 중간 | 높음 |
| **C: skip + 강 WARN (권고)** | avg_price=None + limit_price=None 이면 체결 처리를 **skip**하되 slot_id·symbol·reason을 포함한 WARN 이상 로그 발행. 슬롯 전이 미수행, 다음 틱 재폴링 | 단순·안전 / 무경고 통과 0(REQ-096 AC-2 충족) / 추가 포트 계약 변경 없음 / "0 저장도 없음 + 강한 WARN"으로 REQ-095 AC-6 최소 기준 충족 | (1) 완전체결 상황에서 슬롯이 PENDING 상태에 잠길 수 있음 (2) 운영자 개입 필요(수기 확인 후 `trex-core cancel`·재진입) | 높음 | 낮음 |

#### 권고 근거

- A(재폴링)은 **완전체결(is_filled=True) 케이스에서 실행 불가**다. `_on_filled` 내부에서 skip하면 `clear_dispatch`가 호출되지 않아 슬롯은 PENDING_BUY로 잠기고, 다음 틱에 동일 주문을 다시 poll → `is_filled=True` 반복 → 루프. 이는 dcy-003 R-1(pending order stuck)과 동일한 패턴이다.
- B(현재가 조회)는 `BrokerPort` 포트 계약 변경이며 구현비용 대비 발생 빈도가 낮다. Discovery A-2: "KIS 평균가 누락은 드문 순간 레이스". 또한 KIS `get_current_price` 구현은 현재 없어 신규 adapter 작업이 필요하다.
- C(skip + 강 WARN)은 **REQ-095 AC-6 최소 기준("이 케이스에서 최소한 0 저장은 발생하지 않거나 강한 WARN이 남아야 한다")을 충족**하고, REQ-096 AC-2("무경고 통과 없음")도 충족한다. 슬롯이 PENDING에 잠기는 것은 watchdog/stale_pending 경보가 탐지해 운영자 개입을 유도하므로 안전망이 있다.

**구현 스펙 (C 채택 시)**:
```python
def _resolve_fill_price(self, fs: FillStatus, slot) -> tuple[float | None, bool]:
    """
    Returns (fill_price, was_backfilled).
    fill_price=None → skip signal (폴백 불가, 강 WARN 이미 발행).
    """
    avg = fs.avg_price
    if avg is not None and float(avg) > 0:
        return float(avg), False
    # avg_price None or ≤0: 지정가 백필 시도
    limit = slot.limit_price
    if limit is not None and float(limit) > 0:
        _log.warning(
            "fill price backfill: slot=%s symbol=%s broker_order_id=%s "
            "avg_price=%s backfill_price=%s reason=avg_price_backfill",
            slot.slot_id, slot.symbol, slot.broker_order_id,
            avg, limit,
        )
        return float(limit), True
    # 지정가마저 부재/≤0: skip + 강 WARN
    _log.warning(
        "fill price unresolvable: slot=%s symbol=%s broker_order_id=%s "
        "avg_price=%s limit_price=%s reason=fill_price_unresolvable "
        "(slot stays PENDING — operator attention required)",
        slot.slot_id, slot.symbol, slot.broker_order_id,
        avg, limit,
    )
    return None, False
```

`_resolve_fill_price`가 `None`을 반환하면 호출자(`_on_filled`, `_on_partial_cancel`, `_record_ledger`)에서 해당 체결 처리를 skip한다.

**팀장 승인 필요**: 폴백 정책 확정 후 REQ-095 AC-6 구체화. 다른 후보 채택 시 설계가 변경된다.

---

### KD-3: `_record_ledger` 컨텍스트 패싱 — 파라미터 확장 권고

**권고: `_on_filled`/`_on_partial_cancel`에서 산출한 `fill_price`(백필 결과)를 `_record_ledger`에 직접 전달.**

#### 현재 흐름 분석

`_on_filled`(`:231~285`)는 `fill_price`(avg_price 가공값)를 계산해 `slot.avg_price` 갱신에만 사용한다. 이후 `:281`에서 `self._record_ledger(slot, fs, side, broker_order_id, r)`를 호출하는데, `_record_ledger`(`:401~437`)는 `:424`에서 `fs.avg_price`를 다시 꺼내 쓴다.

즉 **같은 `fs.avg_price`를 두 곳에서 독립적으로 해석**한다. 백필 헬퍼를 추가하면 `_on_filled`에서 한 번 계산한 결과를 `_record_ledger`에서 재계산 없이 전달하는 것이 일관성 있는 설계다.

**구현 스펙**:
```python
# _on_filled 내부:
fill_price, was_backfilled = self._resolve_fill_price(fs, slot)
if fill_price is None:
    return  # skip: 폴백 불가, WARN 이미 발행됨
# ... slot avg_price 계산 ...
self._record_ledger(slot, fs, side, broker_order_id, r, resolved_price=fill_price)

# _record_ledger 시그니처 변경:
def _record_ledger(self, slot, fs, side: str, broker_order_id: str,
                   r: ExecutionResult, *, resolved_price: float | None = None) -> None:
    # ...
    price = resolved_price if resolved_price is not None else (
        float(fs.avg_price) if fs.avg_price is not None else 0.0
    )
```

`resolved_price` 기본값을 `None`으로 두면 기존 `_record_ledger` 호출 코드(다른 경로가 있다면)의 하위 호환성이 유지된다. 현재 코드베이스에서 `_record_ledger`는 `_on_filled`와 `_on_partial_cancel`에서만 호출된다.

---

## 알람 능력 스파이크 — REQ-097

> REQ-097 AC-1: 후보 A·B·C 각각 장점·단점·최소 구현 범위·M2 일정 적합성 명시.
> REQ-097 AC-2: 후보 B wire 계약 변경 여부와 blast radius 명시.

### 후보 A: 구조화 로그 기반

**개요**: FR-3 WARN 로그(REQ-096)를 알람 소스로 삼아 외부 알림 파이프라인(Loki → Grafana Alert / PagerDuty / etc.)에서 소비.

**장점**:
- trex-core 코드 변경 최소 — REQ-096(WARN 로그)만 구현하면 코어 측 작업 완료.
- dcy-029(BAT-045/046) 구조화 로그 인프라(json formatter, correlation_id) 이미 구축됨.
- wire 계약 불변, blast radius 없음.
- M2 일정 내 코어 변경 없음.

**단점**:
- 운영자가 로그 파이프라인(Loki + 알림 규칙)을 별도로 구성해야 함(인프라 의존).
- 알림 지연이 로그 수집 파이프라인 지연에 종속된다(수십 초 ~ 분 단위).
- trex-core 자체에는 알람을 "보내는" 능력이 없음 — 알람은 로그 소비자가 담당.

**최소 구현 범위**: REQ-096 WARN 로그 구현만으로 충분. 알람 파이프라인 구축은 인프라 작업(trex-core 범위 밖).

**M2 일정 적합성**: 코어 측 추가 작업 없음 → **M2 적합**.

---

### 후보 B: AMQP 이벤트 기반

**개요**: `trex.events` exchange 또는 신규 `trex.alerts` exchange에 알람 이벤트(예: `fill_price_backfill`, `fill_price_unresolvable`)를 publish.

**wire 계약 변경 여부 분석**:

현재 `trex.events` 토폴로지 (interface-contract.md):
- routing key 패턴: `{event_type}.{strategy_id}.{symbol}`
- 소비자: `trex.events.strategy.{strategy_id}` 큐가 `*.{strategy_id}.#` 패턴으로 바인딩
- trex-orb-v1, trex-tsl-v1이 이 큐를 소비

알람 이벤트를 `trex.events`에 추가하면:
- `alert.fill_backfill.{strategy_id}.{symbol}` 형태의 routing key를 사용할 경우 → 기존 `*.{strategy_id}.#` 바인딩에 매칭 → **orb/tsl에 알람 이벤트가 전달됨**. orb/tsl이 미처리 메시지를 어떻게 처리하는지 불명확.
- 신규 `trex.alerts` exchange를 추가할 경우 → exchange 신설 + 큐 + 바인딩 추가 = **AMQP 토폴로지 변경** = **wire 계약 변경**.
- 기존 `slot_filled_buy` 등 이벤트 스키마에 알람 관련 필드를 추가하는 것도 **payload 스키마 변경** = **wire 계약 변경**.

**결론: 후보 B는 어떤 구현 형태를 취하더라도 wire 계약(AMQP 토폴로지 또는 payload 스키마) 변경을 수반한다.**

**blast radius**: trex-orb-v1, trex-tsl-v1 양쪽 모두 영향. 특히 trex-tsl-v1은 M2 라이브 목표(6/28) 직전 wire 변경은 위험 수준 High.

**wire 계약 변경 필요 여부**: **예 (후보 B는 Out of Scope)**

> CLAUDE.md 교차 영향 사안 정책에 따라: 후보 B 분석에서 wire 계약 변경 필요성이 확인됨. 이 사안을 팀장에게 보고한다. **후보 B는 본 batch 범위 밖이며 구현 후보에서 제외 권고**.

---

### 후보 C: 외부 푸시 직접 연동

**개요**: trex-core 내에서 직접 Slack webhook / Telegram API / 이메일 등 외부 채널로 알람 전송.

**장점**:
- 운영자가 로그 파이프라인 없이 즉시 수신.
- 지연 최소(수 초 이내).

**단점**:
- trex-core에 외부 HTTP 의존성 추가(Slack/webhook URL 환경변수, 인증 토큰).
- 외부 채널 장애 시 trex-core 알람 발행 실패가 체결 처리에 영향 줄 수 있음(best-effort 설계 필요).
- 채널별 구현(Slack vs Telegram vs email)에 따라 코드 복잡도 증가.
- 자격증명(webhook URL / API key) 관리가 운영 절차에 추가됨.
- 알람 어댑터 포트 신규 정의 필요 + 구체 어댑터 구현 + 테스트.

**최소 구현 범위**: `AlertPort` (application 레이어 포트) + `SlackWebhookAlertAdapter` (adapter 레이어) + `DaemonConfig`에 webhook URL 추가 + `execution.py`에서 포트 호출. 최소 5개 파일 변경.

**M2 일정 적합성**: 구현 범위가 상당하고 자격증명 운영 절차가 추가됨 → **M2 일정 압박 (R-3)**. M3 후보 더 적합.

---

### 알람 스파이크 권고 요약

| 후보 | M2 포함 권고 | 이유 |
|---|---|---|
| A: 구조화 로그 기반 | **권고** (코어 작업 불필요) | REQ-096 WARN 구현만으로 완결, wire 계약 불변, M2 적합 |
| B: AMQP 이벤트 기반 | **Out of Scope** | wire 계약 변경 수반, orb/tsl blast radius, M2 위험 High |
| C: 외부 푸시 직접 연동 | **이월 권고** (M3 후보) | 구현 범위 크고 자격증명 관리 추가, M2 일정 압박 |

**trex-core-dev 권고**: 후보 A(구조화 로그 기반)를 기반 경로로 채택. REQ-096 WARN 로그 → Loki → 알람 파이프라인 연결은 인프라 작업으로 분리. 후보 C의 실제 구현은 M3에서 별도 Discovery로 정의.

FR-3 WARN 로깅(REQ-096)은 알람 채택 여부와 무관하게 M2 필수이며 본 batch에 포함된다.

**사장님 결정 필요 (OQ-1)**: 알람 실제 구현(후보 A 인프라 파이프라인 구축 or 후보 C 코어 구현)의 M2 포함 여부. trex-core-dev는 이 결정을 임의로 내리지 않는다.

---

## Edge Cases

### EC-1: 완전체결 + avg_price=None + limit_price=None

- 발생 경로: KIS가 완전체결 보고 + avg=0 + 슬롯에 limit_price가 None(드문 케이스, 예: orb가 market 주문 시)
- 현재: `fill_price=0.0` → `slot.avg_price=0` 영구 오염.
- KD-2 C 채택 시: `_resolve_fill_price` → `None` 반환 → `_on_filled` skip → `clear_dispatch` 미호출 → 슬롯이 PENDING_BUY 유지. 다음 틱 재폴링 → 동일 `is_filled=True` → skip 반복.
- 안전망: `_check_stale_pending`이 `stale_threshold_sec` 경과 후 WARN을 발생시키고, watchdog 만료 후 safety-sell이 개입한다.
- 운영자 조치: `trex-core cancel <slot_id>` → 슬롯 롤백 → 재진입.
- 이 케이스는 Discovery A-1(orb 매수는 지정가 주문)에 위배되는 예외 케이스이므로 저빈도라고 가정.

### EC-2: 부분취소 + avg_price=None + limit_price > 0

- `_on_partial_cancel`에서 `_resolve_fill_price` → `slot.limit_price` 백필 + WARN.
- 백필 가격으로 `new_avg` 계산 + `_record_ledger` price 기록 → 정상 흐름.

### EC-3: 매도 체결 + avg_price=None

- `_on_filled`에서 side=PENDING_SELL 분기: 이 분기는 `fill_price`/`avg_price`를 슬롯 평단 계산에 사용하지 않는다(매도는 avg_price 보존). 따라서 **매도 체결에서는 `_on_filled` 내 slot 전이에 백필 영향 없음**.
- 단, `_record_ledger`의 `price`(매도 체결가)는 여전히 `fs.avg_price`를 사용 → 여기서도 백필 헬퍼 적용 필요.
- 매도 `limit_price`는 `_dispatch`에서 HOLDING 진입 시 `None`으로 클리어되므로, 매도 시 `slot.limit_price=None`이 정상이다. 따라서 매도 체결에서 avg_price=None이면 EC-1과 유사한 skip+강 WARN 경로를 탄다(KD-2 C 확정 시).

### EC-4: happy path 회귀

- `fs.avg_price`가 정상 양수이면 `_resolve_fill_price`는 `(fs.avg_price, False)` 반환 → 기존과 동일 경로. WARN 미발생, 분기 overhead 없음.

### EC-5: paper 브로커에서 avg_price=None 발생 가능성

- paper 브로커(`paper.py:92,103,106`)는 `avg_price=o.price`를 반환하며 `o.price`는 `__init__`에서 `float(req.limit_price) if req.limit_price is not None else 1000.0`로 항상 양수다.
- 따라서 paper 브로커 사용 시 백필 경로 진입 없음 → paper 관련 테스트에서 WARN 미발생 단언 가능.

## Architecture Impact

- runtime-flows (체결 처리 흐름 변경 — `_on_filled`/`_on_partial_cancel`/`_record_ledger`에 백필 분기 추가)

## Reference Doc Update Plan

- `docs/runtime-flows.md`: implementation 완료 후 "Flow: 체결 처리" 섹션에 백필 분기 flowchart 추가. `_resolve_fill_price` 헬퍼 경로(avg_price=None/≤0 → limit_price 백필 → WARN 로그) 명시.
- `docs/operations.md`: implementation 완료 후 "백필 WARN 발생 시 운영자 점검 절차" 추가. 포함 내용: WARN 로그 식별 방법(`reason=avg_price_backfill` or `reason=fill_price_unresolvable`), 수기 점검 항목(slotID·원장 확인), `trex-core cancel` 조치 절차.
- `docs/project-structure.md`: `_resolve_fill_price` 헬퍼 추가는 execution.py 내 사적 메서드로 project-structure 변경 없음.
- `docs/interface-contract.md`: AMQP wire 계약 불변 — 변경 없음.

---

## Design Review 확정 항목 (팀장·사장님)

| # | 항목 | 권고 | 결정 권한 | 상태 |
|---|---|---|---|---|
| D-1 | 백필 결정 지점: application 단일화 vs adapter | application 권고(KD-1) | 팀장 | 미확정 |
| D-2 | 지정가 부재/≤0 최종 폴백: skip+강WARN vs 재폴링 vs 현재가 조회 | skip+강WARN 권고(KD-2) | 팀장 | 미확정 |
| D-3 | 알람 구현 M2 포함 여부 | 후보 A(로그 기반) + 실제 파이프라인은 후속 이월 권고 | 사장님 | 미확정 |
| D-4 | (D-3 M2 포함 시) 후보 A/C 중 무엇을 코어에서 구현 | 후보 C는 M3, 후보 A는 인프라 작업으로 분리 권고 | 사장님 | 미확정 |