전체적인 리팩토링

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

@@ -0,0 +1,82 @@
+# 자동매매 모델 카탈로그 운영 런북 (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) 변경 이력 템플릿
+
+```md
+- YYYY-MM-DD: [vendor] modelA, modelB 추가
+- YYYY-MM-DD: [vendor] modelX 종료 예정 표기
+- YYYY-MM-DD: 기본 추천 모델 변경 (old -> new)
+```