---
name: order-safety-check
description: Invoked before any code change touching order execution (place_order, cancel_order, modify_order in src/core/binance_api.py or src/core/position/*). Runs pre-flight safety checklist. Use automatically when execution-related files are about to be modified.
---

# 주문 실행 코드 안전성 체크 스킬

## 트리거 상황
- `src/core/binance_api.py` 수정 직전
- `src/core/position/*.py` 수정 직전
- `src/core/hybrid_trading_manager.py` 수정 직전
- 사용자가 "주문 로직 고쳐줘" 등 요청

## 사전 체크리스트

수정 **전에** 다음 5개 항목을 순차 확인:

### Check 1: `paper_mode` 게이트
```python
# 모든 주문 함수 진입부에 이 패턴 있어야 함
async def place_order(self, ...):
    if self.paper_mode:
        return self._mock_order_response(...)
    # 실제 API 호출
    ...
```

### Check 2: `client_order_id` 멱등성
```python
# 모든 place_order 호출에 newClientOrderId 필수
order = await self.client.futures_create_order(
    symbol=symbol,
    side=side,
    type=order_type,
    quantity=quantity,
    newClientOrderId=f"{strategy}_{symbol}_{uuid.uuid4().hex[:8]}",  # 필수
    # ...
)
```

### Check 3: 레이트리밋 대응
```python
# 주문 직전 반드시 acquire 호출
async with self._cb_orders:
    await self.rate_limiter.acquire('futures_order')
    # 주문 송신
```

### Check 4: 크기 상한 검증
```python
# 주문 전 크기 검증
if not self.validate_quantity(symbol, quantity):
    return False, "Quantity validation failed"

if quantity * price > self.config.max_order_size_usd:
    return False, "Exceeds max order size"
```

### Check 5: 예외 처리 완전성
```python
try:
    result = await self._place_order_inner(...)
except CircuitOpenError as e:
    logger.warning(f"Circuit open: {e}")
    return False, "CIRCUIT_OPEN"
except BinanceAPIException as e:
    error_type = classify_binance_error(e)
    logger.error(f"Binance error: {error_type}")
    return False, error_type.value
except Exception as e:
    logger.exception("Unexpected error in place_order")
    return False, "UNKNOWN_ERROR"
```

## 변경 후 필수 검증

수정 **후에** 다음 절차 실행:

1. **단위 테스트 실행**
```bash
pytest tests/test_binance_api.py -v
pytest tests/test_hybrid_trading.py -v
```

2. **idempotency 테스트** (Phase 1 Step 4 이후)
```bash
pytest tests/test_order_idempotency.py -v
```

3. **mock 거래소로 시나리오 테스트**
   - 정상 주문 성공
   - 네트워크 타임아웃 후 재시도 (동일 `client_order_id`)
   - Circuit open
   - Rate limit 초과
   - Insufficient balance

4. **로그 확인**
   - 모든 주문이 감사 로그에 기록되는가
   - `client_order_id`, `timestamp`, `symbol`, `qty`, `price` 포함

## 금지 사항

- 실거래 API 키로 테스트 (반드시 sandbox 또는 mock)
- `paper_mode` 체크 제거 또는 우회
- `newClientOrderId` 생성 규칙 변경 (기존 주문과 충돌 가능)
- `rate_limiter.acquire()` 호출 제거
- 주문 상한 (`max_order_size`) 증가를 테스트 용도로 임시 허용

## Gotchas

- Binance Futures API는 `newClientOrderId`가 선택 파라미터이지만, 우리 시스템에서는 **필수**
- `CircuitBreaker`는 쓰기 작업(주문, 취소, 수정)에만 적용, 읽기는 별도 CB 사용
- `ImprovedRateLimiter`는 엔드포인트별 별도 버킷 (`futures_order`, `futures_query` 등)
- Phase 0 시점 `client_order_id` 0건 — Phase 1 Step 4에서 추가 필수