전체적인 리팩토링

2026-03-12 09:26:27 +09:00
parent 406af7408a
commit e51d767878
97 changed files with 13651 additions and 363 deletions
--- a/common-docs/features/autotrade-prompt-flow-guide.md
+++ b/common-docs/features/autotrade-prompt-flow-guide.md
@@ -0,0 +1,144 @@
+# 자동매매 프롬프트 흐름 추적 가이드 (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 실행 인자에 우선 적용됩니다.