auto-trade/common-docs/features/autotrade-model-catalog-runbook.md

자동매매 모델 카탈로그 운영 런북 (Codex/Gemini)

이 문서는 새 모델이 나왔을 때 자동매매 모델 선택 UI/서버 설정을 안전하게 갱신하기 위한 운영 절차입니다.

1) 목적

1. Codex/Gemini 신모델을 빠르게 목록에 반영한다.
2. 잘못된 모델 ID로 인해 자동매매가 fallback으로 떨어지는 문제를 줄인다.
3. 운영자가 "어디를 고치고 어떻게 검증하는지"를 한 번에 확인할 수 있게 한다.

2) 적용 범위

1. 자동매매 설정창 모델 드롭다운
2. 서버 모델 선택 우선순위(env + UI)
3. 전략/신호 응답에서 providerVendor, providerModel 추적

3) 빠른 절차 (입력 -> 처리 -> 결과)

1. 입력: 공식 문서에서 신규 모델 ID 확인
2. 처리: 모델 옵션 상수 + 안내 문구 + 기본 env 값 점검
3. 결과: UI 선택 가능 + 로그/응답에서 실제 모델 확인 가능

4) 공식 소스(항상 여기 먼저 확인)

1. OpenAI Codex CLI: https://developers.openai.com/codex/cli
2. OpenAI Models: https://platform.openai.com/docs/models
3. Gemini CLI model command: https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/model.md
4. Gemini CLI model routing: https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/model-routing.md
5. Gemini API models: https://ai.google.dev/gemini-api/docs/models

5) 코드 반영 위치

1. 모델 드롭다운 목록
   • features/autotrade/types/autotrade.types.ts
   • AUTOTRADE_SUBSCRIPTION_CLI_MODEL_OPTIONS.codex
   • AUTOTRADE_SUBSCRIPTION_CLI_MODEL_OPTIONS.gemini
2. 기본값/우선순위 점검
   • lib/autotrade/strategy.ts (resolveDefaultSubscriptionCliModel)
   • lib/autotrade/cli-provider.ts (resolveSubscriptionCliModel)
3. 사용자 안내 문구(필요 시)
   • features/autotrade/components/AutotradeControlPanel.tsx
4. 샘플 환경변수 문서화
   • .env.example

6) 모델 추가 규칙

1. 모델 ID는 공식 문서 표기 그대로 입력한다.
2. preview 모델은 라벨에 (프리뷰)를 명시한다.
3. 종료 예정 모델은 라벨/설명에 종료 예정일을 남긴다.
4. 기존 안정형 모델 1개 이상은 항상 남겨둔다.
5. 목록에 없는 모델도 쓸 수 있도록 직접 입력 경로는 유지한다.

7) 검증 체크리스트

• 드롭다운에 신규 모델이 보인다.
• 신규 모델 선택 후 compile/signal 요청 payload에 subscriptionCliModel이 들어간다.
• 응답에 providerVendor, providerModel이 기대값으로 온다.
• 자동매매 로그에 subscription_cli:vendor:model이 표시된다.
• npm run -s lint 통과

8) 수동 검증 포인트(화면 기준)

1. 자동매매 설정 -> 구독형 CLI 엔진 선택(codex 또는 gemini)
2. 신규 모델 선택 후 자동매매 시작
3. 로그에서 아래 3개 필드 확인
   • subscriptionCliVendor
   • subscriptionCliModel
   • providerModel

9) 장애 대응

1. 모델 호출 실패 시 우선 직접 입력으로 동일 ID 재시도
2. 계속 실패하면 직전 안정 모델로 즉시 롤백
3. AUTOTRADE_SUBSCRIPTION_CLI_DEBUG=1로 서버 로그에서 CLI stderr 확인

10) 변경 이력 템플릿

- YYYY-MM-DD: [vendor] modelA, modelB 추가
- YYYY-MM-DD: [vendor] modelX 종료 예정 표기
- YYYY-MM-DD: 기본 추천 모델 변경 (old -> new)