# 🛡️ 다중 기준 계단식 청산 시스템 — **옛 설계서**

> **2026-08-15:** 이 파일은 초안이다. **현행 스위치·순서·키는 `docs/호가.md` §4·§4-1.**  
> 여기 표의 `ORDERBOOK_FILTER_ENABLED` 는 **진입 매수필터**이지 Layer1 청산이 **아님**.  
> 수익구간 호가매도 = `*_EXIT_OB_*`, 손실구간 = `*_STOP_OB_*`. 글로벌 `ORDERBOOK_RATIO_MIN` 은 폐기 방향(전략 prefix만).

## 1. 개요 및 배경

### 1.1 기존 단일 최고가(Peak Price) 래칫의 한계
기존 래칫 컷(`Ratchet Cut`)은 매수 후 달성한 **"최고가(Peak Price)" 하나만을 기준**으로 계단식 매도선을 설정합니다.
- **노이즈 털림 위험**: 일시적인 틱 순간 급락이나 호가 착시 현상으로 유효한 상승 추세에서 억울하게 청산될 위험이 있습니다.
- **수급 붕괴 미감지**: 주가가 고점에 머물러 있더라도 호가창 매수 잔량이 순식간에 빠져나가며 대량 매도벽이 깔리는 수급 붕괴 현상을 사전에 감지하지 못합니다.

### 1.2 목표
매수가, 최고가, 매도/매수 호가잔량(Orderbook Depth), 거래량/시간을 결합한 **다중 조건 계단식(Layered/Composite) 청산 아키텍처**를 설계하여 수익 보존율을 극대화하고 하방 리스크를 원천 차단합니다.

---

## 2. 다중 기준 4계단 레이어드 청산 체계 (Layered Exit Architecture)

```mermaid
flowchart TD
    A[실시간 시세 & 호가 수신] --> B{Layer 1: 호가 수급 붕괴 감지}
    B -- 매수잔량 급감 / 매도벽 출현 --#gt; Sell1[⚡ 1순위: 호가 긴급 청산]
    B -- 정상 --#gt; C{Layer 2: 계단식 고점 래칫컷}
    C -- 최고가 대비 래칫선 이탈 --#gt; Sell2[📈 2순위: 래칫 보존 청산]
    C -- 미이탈 --#gt; D{Layer 3: 어깨 / 추세 트레일링}
    D -- 고점 꺾임 감지 --#gt; Sell3[🛡️ 3순위: 어깨 트레일링 청산]
    D -- 미이탈 --#gt; E{Layer 4: 하드 손절 & 시간 컷}
    E -- 손절선/최대보유시간 초과 --#gt; Sell4[⏱️ 4순위: 시간/하드 손절]
    E -- 조건 미충족 --#gt; Hold[보유 유지]
```

---

## 3. 계단별 세부 설계 및 판정 기준

### 3.1 Layer 1: 호가 수급 붕괴 감지 (Orderbook Depth Cut)
- **개념**: 가격이 떨어지기 직전, 호가창의 매수 잔량이 줄어들고 매도 잔량이 쏟아지는 수급 이탈을 사전에 감지합니다.
- **판정 공식**:
  $$\text{Orderbook Ratio (OR)} = \frac{\text{매수 총잔량}}{\text{매도 총잔량}}$$
  - $\text{OR} < \text{OB\_RATIO\_MIN}$ (예: 0.4 이하) 이면서 **매수가 대비 이익 상태**일 때 즉시 1/2 또는 전량 익절 청산.

### 3.2 Layer 2: 다중 비율 고점 래칫컷 (Multi-Tier Ratchet Cut)
- **개념**: 매수가 대비 달성한 최고 수익률 구간에 따라 매도 허용 갭을 다단계로 압축합니다.
- **계산 공식**:
  $$\text{Peak Gain} = \frac{\text{최고가 (Max Price)} - \text{진입가 (Entry Price)}}{\text{진입가 (Entry Price)}}$$
  $$\text{Ratchet Trigger Line} = \text{최고가} \times (1.0 - \text{Tier Cut Ratio})$$
- **계단 세팅 예시 (`ratchet_tiers`)**:
  - **Tier 1 (+2% 달성 시)**: 고점 대비 `-1.5%` 이탈 시 매도 (최소 +0.5% 익절 보장)
  - **Tier 2 (+5% 달성 시)**: 고점 대비 `-1.0%` 이탈 시 매도 (최소 +4.0% 익절 보장)
  - **Tier 3 (+8% 달성 시)**: 고점 대비 `-0.7%` 이탈 시 매도 (최소 +7.3% 익절 보장)

### 3.3 Layer 3: 어깨 컷 & 트레일링 스탑 (Shoulder Cut)
- **개념**: 최고점(어깨) 경신 후 주가가 힘을 잃고 꺾이는 파동을 감지합니다.
- **판정 공식**:
  - 최고가가 매수가 대비 `shoulder_min_high` (+0.5%) 이상 상승 후, 고점 대비 `shoulder_cut_pct` (-0.3%) 이상 후퇴 시 매도.

### 3.4 Layer 4: 시간 컷 & 하드 손절 (Time & Hard Stop Cut)
- **개념**: 주가가 예상대로 움직이지 않고 횡보하거나 급락할 때 계좌 리스크를 제한합니다.
- **판정 공식**:
  - **하드 손절**: $\text{현재가} \le \text{매수가} \times (1.0 - \text{STOP\_LOSS\_PCT})$ (-3% ~ -4%)
  - **시간 컷**: 진입 후 `max_hold_bars` (예: 20봉) 동안 목표가 미달 시 청산.

---

## 4. `kis_trader` 시스템 적용 사양 (Config Specifications)

### 4.1 `env_config` DB 파라미터 구성

| 파라미터 키 | 타입 | 기본 추천값 | 설명 |
| :--- | :--- | :--- | :--- |
| `MOMENTUM_RATCHET_TIERS` | `str` | `"2:1.5, 5:1.0, 8:0.7"` | 모멘텀 래칫 계단 (고점%:허용밀림%) |
| `SCALP_RATCHET_TIERS` | `str` | `"1.0:0.5, 2.0:0.4"` | 스캘핑 래칫 계단 |
| `ORDERBOOK_FILTER_ENABLED` | `bool` | `True` | 호가 잔량 수급 감지 켜기/끄기 |
| `ORDERBOOK_RATIO_MIN` | `float` | `0.4` | 매수잔량/매도잔량 최소 비율 (수급 이탈) |
| `SHOULDER_MIN_HIGH_PCT` | `float` | `0.005` | 어깨 감지 최소 고점 상승률 (+0.5%) |
| `SHOULDER_CUT_PCT` | `float` | `0.003` | 어깨 감지 후퇴 허용 비율 (-0.3%) |

---

## 5. 기대 효과 및 결론

1. **익절 방어율 극대화**: 급등 후 밀리는 종목에서 수익을 확정 짓는 보존율(Profit Retention)이 기존 대비 30% 이상 향상됩니다.
2. **수급 이탈 사전 차단**: 주가 하락 전에 호가창 매수 잔량이 무너지는 것을 감지하여 시장가 청산이 가능합니다.
3. **심리적 안정성 확보**: 바닥까지 떨어지는 리스크를 원천 차단하여 완전 자동화 매매의 신뢰도를 제공합니다.