auto-trade/common-docs/improvement/plans/dev-plan-2026-02-26-autotrade-dashboard-ux-cli-models.md

자동매매 모델 선택 + 대시보드 잔고/매도 UX 개선 계획

[계획 문서 경로]

• common-docs/improvement/plans/dev-plan-2026-02-26-autotrade-dashboard-ux-cli-models.md

[요구사항 요약]

• AI 판단 입력 데이터(시세 스냅샷)가 무엇인지 쉽게 설명한다.
• 자동매매 UI에서 구독형 CLI vendor/model을 선택할 수 있게 개선한다.
• 대시보드 잔고 표시(총자산/순자산) 혼동을 줄이고, 매도 UX에 매도가능수량 정보를 보강한다.
• 보유종목 잔존(전량 매도 후 표시) 문제를 점검하고 수정한다.
• 자동매매 리스크 요약 문구를 초보자 기준으로 이해 가능하게 바꾼다.

[가정]

• 구독형 CLI 모델 목록은 "공식 문서 기준 추천 프리셋 + 직접 입력" 방식이 운영 안정성에 유리하다.
• KIS 주식잔고조회 output1의 ord_psbl_qty(매도가능수량)를 우선 사용한다.

[영향 범위]

• 수정: features/autotrade/types/autotrade.types.ts
• 수정: lib/autotrade/strategy.ts
• 수정: features/autotrade/apis/autotrade.api.ts
• 수정: features/autotrade/hooks/useAutotradeEngine.ts
• 수정: features/autotrade/components/AutotradeControlPanel.tsx
• 수정: app/api/autotrade/strategies/compile/route.ts
• 수정: app/api/autotrade/signals/generate/route.ts
• 수정: lib/autotrade/cli-provider.ts
• 수정: lib/kis/dashboard.ts
• 수정: features/dashboard/types/dashboard.types.ts
• 수정: features/dashboard/components/StatusHeader.tsx
• 수정: features/dashboard/components/HoldingsList.tsx
• 수정: features/trade/components/TradeContainer.tsx
• 수정: features/trade/components/order/OrderForm.tsx
• 수정: common-docs/features/autotrade-usage-security-guide.md
• 수정: common-docs/features/autotrade-prompt-flow-guide.md

[구현 단계]

• 1. 자동매매 setup form에 CLI vendor/model 선택 필드를 추가한다.
• 2. compile/signal API 요청에 vendor/model 오버라이드를 전달하고 라우트/CLI provider에서 반영한다.
• 3. 공식 문서 기반 모델 프리셋(코덱스/제미나이) + 직접입력 UX를 패널에 추가한다.
• 4. 대시보드 잔고 파싱에서 수량 0 보유종목 제거/매도가능수량 필드를 반영한다.
• 5. 상단 자산 카드 라벨/표시 순서를 총자산 중심으로 개선한다.
• 6. 주문 패널 매도 탭에서 매도가능수량 기반 가이드/검증을 추가한다.
• 7. 자동매매 리스크 요약 문구를 쉬운 용어로 바꾸고 입력값 대비 계산 근거를 함께 노출한다.
• 8. 문서(사용 가이드/흐름 가이드)에 스냅샷 필드 설명과 모델 선택 기준을 반영한다.

[사용한 공식 문서]

• OpenAI Models: https://platform.openai.com/docs/models
• OpenAI Codex CLI: https://developers.openai.com/codex/cli
• Gemini CLI model selection: https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/model.md
• Gemini CLI model routing precedence: https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/model-routing.md
• KIS 매도가능수량조회 경로 참고: common-docs/api-reference/kis_api_reference.md, .tmp/open-trading-api/examples_llm/domestic_stock/inquire_psbl_sell/inquire_psbl_sell.py

[리스크/회귀 포인트]

• UI 필드 증가로 기존 자동매매 설정 저장/반영 흐름이 깨질 수 있음.
• 모델명을 강제로 지정했을 때 vendor와 호환되지 않으면 CLI 실패 후 fallback으로 전환될 수 있음.
• 보유종목 필터링 조건이 과도하면 실제 보유 종목이 누락될 수 있음.

[검증 계획]

• 1. 변경 파일 eslint 통과
• 2. npm run build 통과
• 3. 대시보드에서 수량 0 종목 미노출 로직 반영 확인 (lib/kis/dashboard.ts 수량 0 필터)
• 4. 매도 탭에서 매도가능수량 초과 입력 차단 로직 반영 확인 (OrderForm.tsx)
• 5. 자동매매 로그에 vendor/model 노출 유지 확인 (useAutotradeEngine.ts)

[진행 로그]

• 2026-02-26: 계획 문서 생성
• 2026-02-26: 자동매매 설정창에 구독형 CLI vendor/model 선택 UI 추가
• 2026-02-26: compile/signal route와 CLI provider에 vendor/model override 반영
• 2026-02-26: 대시보드 잔고 파싱에 ord_psbl_qty 반영, 수량 0 종목 필터링 적용
• 2026-02-26: StatusHeader 총자산 중심 표기 개편, 매도 UX(매도가능수량 표시/검증) 개선
• 2026-02-26: 리스크 요약 문구를 쉬운 용어로 교체, 스냅샷/모델선택 문서 보강
• 2026-02-26: npx eslint 및 npm run build 통과