[계획 문서 경로] - common-docs/improvement/plans/dev-plan-2026-02-26-autotrade-ai-mvp.md [요구사항 요약] - `features-autotrade-design.md`를 참고해 자동매매 기능을 실제 코드로 추가한다. - 설계 항목 중 현재 코드베이스에서 바로 구현 가능한 범위와 불필요/보류 범위를 구분한다. - "구독형 AI + 유명 기법"(OpenAI 기반 + ORB/VWAP/거래량/이평/갭)을 자동매매 시작 흐름에 반영한다. - OpenAI API 외에도 서버에 설치된 Codex/Gemini CLI를 이용한 구독형 자동판단 경로를 추가한다. - Windows 개발 환경에서 워커 실행 방법을 문서와 스크립트로 제공한다. [확인 질문(필요 시 1~3개)] - 없음(우선 MVP 범위로 구현 후 동작 가능한 형태를 제공) [가정] - 서버 DB(Supabase) 스키마를 이번 작업에서 새로 만들지 않고, 세션/로그는 서버 메모리 + 클라이언트 상태로 우선 구현한다. - OpenAI 키(`OPENAI_API_KEY`)가 없으면 AI 추론은 휴리스틱 폴백(보수적 hold 중심)으로 동작한다. - 자동매매는 트레이드 화면에서 선택된 종목 기준으로 우선 실행한다(멀티 종목 동시 엔진은 보류). [추가/제외 판단] - 즉시 추가: - 자동매매 설정 팝업(UI): 프롬프트, 유명 기법 복수 선택, 투자금/손실한도(퍼센트+금액), 동의 체크 - 전략 컴파일/검증 API: `compile`, `validate` - 런타임 세션 API: `start`, `heartbeat`, `stop`, `active` - 브라우저 엔진 훅: 신호 평가, 리스크 게이트, 주문 실행, heartbeat, 중지 처리 - 실행 중 경고 배너/상태 카드 - 설정 도움말/추천 프리셋(초보/균형/공격) 추가 - 백엔드 워커 tick API + 리눅스 PM2 실행 스크립트/문서 추가 - 자동 세션 수명주기(start->heartbeat->stop) E2E 스크립트 추가 - 이번에 제외(보류): - Supabase 테이블 5종 + 감사로그 영구 저장 - 온라인 전략 수집/카탈로그 검수 워크플로우 전체 - 멀티탭 리더 선출 lock + BroadcastChannel 완성형 - 4주 배포 계획/운영 대시보드/Sentry 통합 - AI 다중 제공자(OpenAI/Gemini/Claude) 동시 운영 [영향 범위] - 수정: - features/trade/components/TradeContainer.tsx - .env.example - utils/supabase/middleware.ts - package.json - common-docs/features/autotrade-usage-security-guide.md - common-docs/features/autotrade-worker-pm2.md - common-docs/improvement/plans/dev-plan-2026-02-26-autotrade-ai-mvp.md - 추가: - features/autotrade/types/autotrade.types.ts - features/autotrade/stores/use-autotrade-engine-store.ts - features/autotrade/hooks/useAutotradeEngine.ts - features/autotrade/components/AutotradeControlPanel.tsx - features/autotrade/components/AutotradeWarningBanner.tsx - features/autotrade/apis/autotrade.api.ts - app/api/autotrade/_shared.ts - app/api/autotrade/strategies/compile/route.ts - app/api/autotrade/strategies/validate/route.ts - app/api/autotrade/sessions/start/route.ts - app/api/autotrade/sessions/heartbeat/route.ts - app/api/autotrade/sessions/stop/route.ts - app/api/autotrade/sessions/active/route.ts - app/api/autotrade/signals/generate/route.ts - app/api/autotrade/worker/tick/route.ts - lib/autotrade/risk.ts - lib/autotrade/strategy.ts - lib/autotrade/openai.ts - lib/autotrade/cli-provider.ts - scripts/autotrade-session-e2e.mjs - scripts/autotrade-worker.mjs - scripts/pm2.autotrade-worker.config.cjs - common-docs/features/autotrade-worker-pm2.md - 삭제: - 없음 [구현 단계] - [x] 1. 자동매매 타입/리스크 계산 유틸/AI-폴백 전략 컴파일 로직 추가 - 근거: `features/autotrade/types/autotrade.types.ts`, `lib/autotrade/risk.ts`, `lib/autotrade/strategy.ts`, `lib/autotrade/openai.ts` - [x] 2. 자동매매 API 라우트(`compile/validate/start/heartbeat/stop/active/signal`) 구현 - 근거: `app/api/autotrade/**/route.ts`, `app/api/autotrade/_shared.ts` - [x] 3. 클라이언트 스토어/엔진 훅 구현(상태, heartbeat, 주문 실행, 중지) - 근거: `features/autotrade/stores/use-autotrade-engine-store.ts`, `features/autotrade/hooks/useAutotradeEngine.ts`, `features/autotrade/apis/autotrade.api.ts` - [x] 4. 트레이드 화면에 설정 패널/실행 경고 배너 통합 - 근거: `features/autotrade/components/AutotradeControlPanel.tsx`, `features/autotrade/components/AutotradeWarningBanner.tsx`, `features/trade/components/TradeContainer.tsx` - [x] 5. 문서/환경변수(.env.example) 반영 및 계획 체크 업데이트 - 근거: `.env.example`, 본 계획 문서 갱신 - [x] 6. 설정 팝업 입력값 설명 강화 + 추천 프리셋(초보/균형/공격) 추가 - 근거: `features/autotrade/components/AutotradeControlPanel.tsx` - [x] 7. 백엔드 워커 tick API 및 PM2 운영 스크립트/문서 추가 - 근거: `app/api/autotrade/worker/tick/route.ts`, `scripts/autotrade-worker.mjs`, `scripts/pm2.autotrade-worker.config.cjs`, `common-docs/features/autotrade-worker-pm2.md` - [x] 8. 자동매매 세션 수명주기 E2E 스크립트 추가 및 실행 - 근거: `scripts/autotrade-session-e2e.mjs`, `npm run test:autotrade:lifecycle` PASS - [x] 9. 구독형 CLI 자동판단 모드 추가(codex/gemini CLI) - 근거: `lib/autotrade/cli-provider.ts`, `app/api/autotrade/strategies/compile/route.ts`, `app/api/autotrade/signals/generate/route.ts`, `features/autotrade/components/AutotradeControlPanel.tsx` - [x] 10. Windows 개발 워커 실행 경로 추가 - 근거: `package.json(worker:autotrade:dev)`, `common-docs/features/autotrade-worker-pm2.md`, `common-docs/features/autotrade-usage-security-guide.md` [사용할 MCP/Skills] - MCP: next-devtools(nextjs_index/nextjs_call), playwright(스모크), shell_command - Skills: dev-auto-pipeline, dev-plan-writer, dev-mcp-implementation, nextjs-app-router-patterns, vercel-react-best-practices, dev-refactor-polish, dev-test-gate, dev-plan-completion-checker [참조 문서(common-docs)] - common-docs/ui/GLOBAL_ALERT_SYSTEM.md - common-docs/api-reference/kis_api_reference.md (주문 연동 시 기존 패턴 준수) - common-docs/api-reference/kis-error-code-reference.md (에러 표현 패턴 유지) - 사용자 지정 기획 입력: common-docs/features-autotrade-design.md [주석/문서 반영 계획] - 함수 주석: [목적]/[사용처]/[데이터 흐름] 중심으로 핵심 흐름만 보강 - 상태 주석: 자동매매 상태 변경이 화면에 미치는 영향 위주 - 복잡 로직/핸들러: 신호 생성 -> 리스크 검증 -> 주문 실행 단계 주석 - JSX 구역 주석: 설정 패널/경고 배너/상태 카드 구역 분리 [리스크/회귀 포인트] - 주문 API 호출 빈도 과다 시 중복 주문 위험 - 브라우저 종료 시 stop beacon 실패 가능성 - AI 출력 포맷 불안정 시 잘못된 신호 처리 위험 - 기존 수동 주문 UX와 충돌(버튼/상태 동시 사용) [검증 계획] - [x] 1. `npm run lint` 통과 - 근거: ESLint 에러/경고 정리 후 재실행 통과 - [x] 2. `npm run build` 통과 - 근거: Next.js 16.1.6 프로덕션 빌드 성공, 신규 `/api/autotrade/*` 라우트 포함 확인 - [x] 3. Playwright 스모크: `/trade` 자동매매 설정 패널 오픈 + 도움말/추천 프리셋 입력 반영 확인 - 근거: `자동매매 설정` 모달 오픈, 쉬운 설명 문구 노출, `초보 추천` 클릭 시 수치 자동 반영 확인, 콘솔 error 없음 - [x] 4. start -> heartbeat -> stop 상태 전환 검증 - 근거: `npm run test:autotrade:lifecycle` PASS (`start -> heartbeat -> active -> stop -> active(null)`) [진행 로그] - 2026-02-26: 초안 작성. 설계서 기준 MVP 범위(즉시 구현/보류) 확정. - 2026-02-26: 자동매매 MVP 구현 완료. 타입/유틸/API/스토어/엔진/트레이드 화면 통합 및 `.env.example` 갱신. - 2026-02-26: 검증 완료(`npm run lint`, `npm run build`, Playwright 스모크). 로그인+KIS 인증 기반 수동 E2E는 남은 확인 항목으로 기록. - 2026-02-26: 설정값 도움말/추천 프리셋(초보/균형/공격) 추가로 입력 이해도 개선. - 2026-02-26: 워커 tick API + PM2 운영 스크립트/문서 추가, `worker:autotrade:once` 정상 동작 확인. - 2026-02-26: 수명주기 자동 검증 스크립트(`test:autotrade:lifecycle`) 통과로 검증계획 4 완료. - 2026-02-26: 구독형 CLI 자동판단 모드(`subscription_cli`) 추가. OpenAI 미사용 환경에서 gemini/codex CLI 호출 후 JSON 파싱, 실패 시 규칙 기반 폴백하도록 리팩토링. - 2026-02-26: Windows PowerShell 기준 워커 실행 방법(환경변수 + `worker:autotrade(:dev)`) 문서화.