auto-trade/common-docs/improvement/plans/dev-plan-2026-02-26-autotrade-ai-mvp.md

[계획 문서 경로]

• 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
• 삭제:
  • 없음

[구현 단계]

• 1. 자동매매 타입/리스크 계산 유틸/AI-폴백 전략 컴파일 로직 추가
  • 근거: features/autotrade/types/autotrade.types.ts, lib/autotrade/risk.ts, lib/autotrade/strategy.ts, lib/autotrade/openai.ts
• 2. 자동매매 API 라우트(compile/validate/start/heartbeat/stop/active/signal) 구현
  • 근거: app/api/autotrade/**/route.ts, app/api/autotrade/_shared.ts
• 3. 클라이언트 스토어/엔진 훅 구현(상태, heartbeat, 주문 실행, 중지)
  • 근거: features/autotrade/stores/use-autotrade-engine-store.ts, features/autotrade/hooks/useAutotradeEngine.ts, features/autotrade/apis/autotrade.api.ts
• 4. 트레이드 화면에 설정 패널/실행 경고 배너 통합
  • 근거: features/autotrade/components/AutotradeControlPanel.tsx, features/autotrade/components/AutotradeWarningBanner.tsx, features/trade/components/TradeContainer.tsx
• 5. 문서/환경변수(.env.example) 반영 및 계획 체크 업데이트
  • 근거: .env.example, 본 계획 문서 갱신
• 6. 설정 팝업 입력값 설명 강화 + 추천 프리셋(초보/균형/공격) 추가
  • 근거: features/autotrade/components/AutotradeControlPanel.tsx
• 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
• 8. 자동매매 세션 수명주기 E2E 스크립트 추가 및 실행
  • 근거: scripts/autotrade-session-e2e.mjs, npm run test:autotrade:lifecycle PASS
• 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
• 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와 충돌(버튼/상태 동시 사용)

[검증 계획]

• 1. npm run lint 통과
  • 근거: ESLint 에러/경고 정리 후 재실행 통과
• 2. npm run build 통과
  • 근거: Next.js 16.1.6 프로덕션 빌드 성공, 신규 /api/autotrade/* 라우트 포함 확인
• 3. Playwright 스모크: /trade 자동매매 설정 패널 오픈 + 도움말/추천 프리셋 입력 반영 확인
  • 근거: 자동매매 설정 모달 오픈, 쉬운 설명 문구 노출, 초보 추천 클릭 시 수치 자동 반영 확인, 콘솔 error 없음
• 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)) 문서화.