---
name: order-controls
description: 매매 PIN echo 와 매매 모듈 제어. 4자리 숫자 또는 8자리 영숫자만 단독으로 들어온 메시지(예 "4791", "K8aR3nFq")는 활성 카드의 PIN echo. /orders_off /orders_on /cancel /orders_status 슬래시 명령 + 자연어 변형("매매 풀어줘", "매매 잠가줘", "매매 상태", "카드 취소") 모두 처리. 자연어 매매 지시(매수/매도)는 order-trading 스킬을 사용.
---

# order-controls

활성 매매 카드의 PIN echo, 매매 모듈 사이드카 토글, 카드 취소, 상태 조회.

## PIN echo 처리

### 트리거 조건
관리자님 텔레그램 메시지가 **다음 조건을 모두** 만족할 때:
- 단독 메시지 (다른 텍스트 없음)
- 4자리 숫자만 (`^\d{4}$`) **또는** 8자리 영숫자 (혼동글자 0/O/o/1/l/I 제외, `^[A-Za-z2-9]{8}$`)
- 직전에 `order-trading` 카드가 발행된 상태

이 경우 PIN echo 로 간주하고 다음을 호출:
```bash
cd ~/.openclaw/agents/stock/workspace/scripts
python3 -m orders.handler pin <PIN> --live --send
```

`--live` 가 실주문 활성화. `--send` 가 결과를 텔레그램으로 자동 발송 (체결 알림·접수 알림·거부 메시지). skill 응답은 짧게 ("PIN 처리 완료" 또는 결과 요약).

### 안 부르는 경우
- "삼성 5주 75000원" 같은 자연어 → `order-trading`
- "사줘" 같은 의도 메시지 → `order-trading`
- 4자리 숫자가 다른 텍스트와 함께 있는 경우 (예: "75000원에") → PIN 아님
- 활성 카드 없을 때 PIN 형태 메시지 → 활성 카드 없음 응답이 자동 반환됨

### PIN 검증 실패 응답
- 만료: `⏱️ [#XXX] 승인 만료...`
- 불일치: `❌ [#XXX] PIN 불일치. 카드 무효...`
- 사이드카 ON: `🚫 매매 비활성화 상태...`

자동으로 텔레그램에 발송됨. skill 응답은 짧게.

## 매매 제어 명령

### 자연어 ↔ 슬래시 매핑

| 자연어 변형 | 슬래시 | 동작 |
|---|---|---|
| "매매 풀어줘", "매매 활성화", "사이드카 풀어줘", "주문 활성화" | `/orders_on` | 사이드카 OFF |
| "매매 잠가줘", "매매 비활성화", "매매 중단해줘", "매매 멈춰", "매매 중지", "사이드카 잠가줘", "주문 막아줘" | `/orders_off` | 사이드카 ON |
| "매매 상태", "사이드카 상태", "주문 상태" | `/orders_status` | 사이드카·활성 카드 상태 |
| "카드 취소", "방금 거 취소", "취소", "0" 단독 입력 — **활성 카드 있을 때 한정** | `/cancel` | 활성 카드 즉시 무효 |

자연어와 슬래시 둘 다 인식. 동일 CLI 호출.

### `/orders_off` — 매매 비활성화 (kill switch)
```bash
python3 -m orders.handler cmd /orders_off
```
응답: `🚫 매매 비활성화. /orders_on 으로 재개.` 진행 중 카드는 다음 PIN echo 시 차단.

### `/orders_on` — 매매 활성화
```bash
python3 -m orders.handler cmd /orders_on
```
응답: `✅ 매매 활성화` 또는 `⚠️ 이미 활성화 상태`.

### `/cancel` — 활성 카드 즉시 취소
```bash
python3 -m orders.handler cmd /cancel
```
응답: `❌ [#XXX] 매수 취소되었습니다.` 또는 활성 카드 없음.

### `/orders_status` — 사이드카·활성 카드 상태
```bash
python3 -m orders.handler cmd /orders_status
```
JSON 형태 status 반환. 관리자님께는 핵심만 정리해서 응답 (사이드카 ON/OFF, 활성 카드 유무·종목·만료까지 N초).

## 사이드카 직접 조작 (CLI 보조)

```bash
python3 -m orders.sidecar status
python3 -m orders.sidecar disable [reason]
python3 -m orders.sidecar enable
```

## 절대 원칙

- **PIN 변형 금지** — 관리자님이 보낸 PIN 을 그대로 echo. trim 정도만 OK. 한 글자라도 바꾸면 안 됨.
- **PIN 추측·생성 금지** — LLM 이 자기 판단으로 PIN 을 만들거나 시도하면 안 됨. 활성 카드 PIN 은 관리자님 텔레그램에만 노출됨.
- **단축어 외 매매 트리거 X** — 이 스킬은 PIN/제어만 담당. 자연어 매매는 `order-trading`.
- **"주문 취소" / "미체결 취소" / "ord_no XXX 취소" 자연어는 order-trading 으로 위임** — 이 스킬의 `/cancel`은 **PIN 미입력 단계 활성 카드만** 무효화한다. 키움에 이미 접수된 미체결 주문 취소(kt10003)는 `order-trading`의 `cancel-order` 진입점이다. 활성 카드 없는 상태에서 "취소" 자연어가 오면 미체결 취소 의도일 가능성이 크므로 `order-trading` 으로 라우팅.