# 자동매매 프롬프트 흐름 추적 가이드 (UI -> 함수 -> AI -> 주문)

이 문서는 "전략 프롬프트를 입력하면 실제로 어디 함수로 흘러가고, 어디서 AI가 호출되는지"를 코드 라인 기준으로 설명합니다.

## 1) 한 줄 요약

사용자가 UI에 프롬프트를 입력하면, 시작/검증 시점에 `compile` API로 전달되어 전략 JSON으로 바뀌고, 실행 중에는 그 전략 JSON + 실시간 시세로 신호를 생성해 주문 여부를 결정합니다.

## 2) 구조 그림

```text
[브라우저 UI]
AutotradeControlPanel.tsx
  └─ 프롬프트 입력 + 시작/검증 클릭
        │
        ▼
[브라우저 엔진 훅]
useAutotradeEngine.ts
  └─ prepareStrategy()에서 compile/validate 실행
        │
        ▼
[브라우저 API 클라이언트]
autotrade.api.ts
  └─ /api/autotrade/strategies/compile 호출
        │
        ▼
[Next 서버 route]
strategies/compile/route.ts
  └─ OpenAI / subscription_cli / fallback 분기
        │
        ▼
[AI Provider]
openai.ts 또는 cli-provider.ts
  └─ 전략 JSON 반환
        │
        ▼
[브라우저 엔진 훅]
useAutotradeEngine.ts
  └─ compiledStrategy 저장 후 실행 루프 시작
        │
        ▼
[신호 루프]
/api/autotrade/signals/generate -> 리스크 게이트 -> 주문 API
```

## 3) 프롬프트 입력 -> 전략 컴파일 (상세 추적)

1. 프롬프트 입력 UI
   - 컴포넌트: [`AutotradeControlPanel.tsx#L335`](../../features/autotrade/components/AutotradeControlPanel.tsx#L335)
   - 입력 이벤트: [`handlePromptChange`](../../features/autotrade/components/AutotradeControlPanel.tsx#L123)
   - store 반영: [`patchSetupForm({ prompt })`](../../features/autotrade/components/AutotradeControlPanel.tsx#L126)
   - 같은 화면에서 구독형 CLI vendor/model도 선택 가능: `subscriptionCliVendor`, `subscriptionCliModel`

2. 시작/검증 버튼 클릭
   - 시작 버튼 핸들러: [`handleStartAutotrade`](../../features/autotrade/components/AutotradeControlPanel.tsx#L102)
   - 검증 버튼 핸들러: [`handlePreviewValidation`](../../features/autotrade/components/AutotradeControlPanel.tsx#L113)

3. 엔진 훅에서 전략 준비
   - 함수: [`prepareStrategy()`](../../features/autotrade/hooks/useAutotradeEngine.ts#L138)
   - compile 호출: [`compileAutotradeStrategy(...)`](../../features/autotrade/hooks/useAutotradeEngine.ts#L153)

4. 브라우저 API 클라이언트
   - 함수: [`compileAutotradeStrategy`](../../features/autotrade/apis/autotrade.api.ts#L30)
   - HTTP 호출: [`POST /api/autotrade/strategies/compile`](../../features/autotrade/apis/autotrade.api.ts#L36)
   - 전달 필드: `aiMode`, `subscriptionCliVendor`, `subscriptionCliModel`, `prompt`, `selectedTechniques`, `confidenceThreshold`

5. Next API route에서 provider 분기
   - 엔드포인트: [`strategies/compile/route.ts#L44`](../../app/api/autotrade/strategies/compile/route.ts#L44)
   - fallback 전략 준비: [`createFallbackCompiledStrategy`](../../app/api/autotrade/strategies/compile/route.ts#L67)
   - OpenAI 분기: [`compileStrategyWithOpenAi`](../../app/api/autotrade/strategies/compile/route.ts#L87)
   - 구독형 CLI 분기: [`compileStrategyWithSubscriptionCliDetailed`](../../app/api/autotrade/strategies/compile/route.ts#L119)

6. OpenAI 실제 호출 지점
   - OpenAI 전략 함수: [`compileStrategyWithOpenAi`](../../lib/autotrade/openai.ts#L51)
   - 공통 호출기: [`callOpenAiJson`](../../lib/autotrade/openai.ts#L203)
   - 외부 API: [`https://api.openai.com/v1/chat/completions`](../../lib/autotrade/openai.ts#L19)

7. 컴파일 결과 반영
   - compiledStrategy 저장: [`setCompiledStrategy(...)`](../../features/autotrade/hooks/useAutotradeEngine.ts#L160)
   - validate 저장: [`setValidation(...)`](../../features/autotrade/hooks/useAutotradeEngine.ts#L173)

## 4) 실행 중 "자동 프롬프트"가 도는 방식

중요: 실행 중 매 틱마다 자연어 프롬프트를 다시 보내지 않습니다.

1. 시작 시점에만 프롬프트를 전략 JSON으로 컴파일합니다.
2. 실행 루프에서는 "컴파일된 전략 JSON + 현재 시세 스냅샷"으로 신호를 만듭니다.

관련 코드:

1. 신호 요청 주기(12초): [`SIGNAL_REQUEST_INTERVAL_MS`](../../features/autotrade/hooks/useAutotradeEngine.ts#L51)
2. 신호 API 호출: [`generateAutotradeSignal(...)`](../../features/autotrade/hooks/useAutotradeEngine.ts#L495)
3. 서버 신호 route: [`signals/generate/route.ts#L74`](../../app/api/autotrade/signals/generate/route.ts#L74)
4. 신호 생성 OpenAI 함수: [`generateSignalWithOpenAi`](../../lib/autotrade/openai.ts#L116)

신호 요청 시 스냅샷 실제 필드:

1. `symbol`
2. `currentPrice`
3. `changeRate`
4. `open`
5. `high`
6. `low`
7. `tradeVolume`
8. `accumulatedVolume`
9. `recentPrices`

## 5) 신호 -> 주문 판단 (자동 실행 핵심)

1. 신호 생성 결과 수신: [`runtime.setLastSignal(signal)`](../../features/autotrade/hooks/useAutotradeEngine.ts#L504)
2. 리스크 게이트 검사: [`evaluateSignalBlockers(...)`](../../features/autotrade/hooks/useAutotradeEngine.ts#L516)
3. 통과 시 주문 API 호출: [`fetchOrderCash(...)`](../../features/autotrade/hooks/useAutotradeEngine.ts#L556)

즉, AI가 `buy/sell`을 주더라도 리스크 게이트를 통과하지 못하면 주문은 실행되지 않습니다.

## 6) AI를 못 쓰는 경우

1. 전략 폴백: [`createFallbackCompiledStrategy`](../../lib/autotrade/strategy.ts#L26)
2. 신호 폴백: [`createFallbackSignalCandidate`](../../lib/autotrade/strategy.ts#L48)

AI(OpenAI/CLI) 응답 실패 시에도 시스템이 멈추지 않고 보수적으로 동작하도록 설계되어 있습니다.

## 7) Codex CLI인지 Gemini CLI인지 확인하는 법

1. 자동매매 로그에서 확인
   - `신호 수신 [subscription_cli:codex:gpt-5-codex]` 또는 `신호 수신 [subscription_cli:gemini:flash]`
   - 로그 코드: [`useAutotradeEngine.ts`](../../features/autotrade/hooks/useAutotradeEngine.ts#L564)

2. Network 응답에서 확인
   - 전략 컴파일 응답: `compiledStrategy.providerVendor`
   - 신호 생성 응답: `signal.providerVendor`

3. 실패 시 어떤 순서로 시도했는지 확인
   - 파싱 실패 문구에 `selected=vendor:model; attempts=vendor:model:status` 포함
   - `status=timeout`이면 CLI 실행시간 초과입니다. `AUTOTRADE_SUBSCRIPTION_CLI_TIMEOUT_MS`를 늘리세요(권장: 60000).
   - 생성 코드: [`summarizeSubscriptionCliExecution`](../../lib/autotrade/cli-provider.ts#L112)

4. 모델 선택 환경변수
   - `AUTOTRADE_CODEX_MODEL` (예: `gpt-5-codex`)
   - `AUTOTRADE_GEMINI_MODEL` (예: `auto`, `pro`, `flash`, `flash-lite`)
   - `AUTOTRADE_SUBSCRIPTION_CLI_MODEL` (vendor 전용 값이 없을 때 공통 fallback)

5. 모델 선택 UI (환경변수보다 우선)
   - 자동매매 설정창에서 `subscriptionCliVendor`, `subscriptionCliModel` 선택 시 해당 값이 API payload로 전달되어 CLI 실행 인자에 우선 적용됩니다.