d3ro-voice/docs/phases/phase-6.md

# Phase 6: 커스텀 명령어 + 설정 UI 고도화

## 목표
사용자 정의 LLM 명령어 시스템을 완전 구현하고, 설정 UI를 고도화하여 STT/LLM/TTS 모델 선택, 온보딩, 다국어(i18n)를 지원한다.

## 태스크

### 6.1 CustomInstructionService 완전 구현
- `src/main/services/CustomInstructionService.ts`
- electron-store에 명령어 목록 저장 (DB 아닌 설정 파일)
- CustomInstruction 타입:
  ```typescript
  interface CustomInstruction {
    id: string;               // nanoid
    name: string;             // 표시 이름 (예: "번역 (한→영)")
    description: string;      // 설명
    prompt: string;           // 시스템 프롬프트 템플릿
    icon: string;             // MUI 아이콘 이름 또는 이모지
    isBuiltin: boolean;       // 프리셋 여부 (삭제 불가)
    hotkeyId: string | null;  // 바인딩된 핫키 ID (null이면 미설정)
    order: number;            // 표시 순서
    createdAt: number;
    updatedAt: number;
  }
  ```
- CRUD 메서드:
  - `getAll(): CustomInstruction[]`
  - `getById(id: string): CustomInstruction | null`
  - `create(input: CreateCustomInstructionInput): CustomInstruction`
  - `update(id: string, data: Partial<CustomInstruction>): void`
  - `delete(id: string): void` — isBuiltin은 삭제 불가
  - `reorder(ids: string[]): void` — 순서 변경
  - `resetBuiltins(): void` — 프리셋을 기본값으로 초기화

### 6.2 프리셋 명령어 5개
- 앱 최초 실행 시 자동 생성 (isBuiltin: true)

1. **번역** (`translate`)
   ```
   다음 텍스트를 {{targetLanguage}}로 번역해주세요.
   자연스럽고 정확한 번역만 출력하세요.
   ```

2. **요약** (`summarize`)
   ```
   다음 텍스트의 핵심 내용을 3줄 이내로 요약해주세요.
   요약문만 출력하세요.
   ```

3. **전문 리라이트** (`formal-rewrite`)
   ```
   다음 텍스트를 격식 있는 비즈니스 문체로 다시 작성해주세요.
   원래 의미를 유지하면서 전문적인 톤으로 변환하세요.
   다시 작성된 텍스트만 출력하세요.
   ```

4. **코드 설명** (`explain-code`)
   ```
   다음 코드를 한국어로 설명해주세요.
   각 부분이 무엇을 하는지 간결하게 설명하세요.
   ```

5. **자유 프롬프트** (`free-prompt`)
   ```
   {{userPrompt}}
   ```
   - 사용자가 매번 프롬프트를 직접 입력하는 특수 모드
   - UI에서 프롬프트 입력 필드 표시

### 6.3 사용자 정의 명령어 CRUD UI
- `src/renderer/components/CustomCommands.tsx`
- 명령어 목록: 이름, 설명, 프리셋 여부 표시
- 추가: 이름, 설명, 프롬프트 템플릿 입력 다이얼로그
  - 프롬프트 템플릿에 `{{text}}` 변수 자동 삽입 안내
  - 프롬프트 미리보기 (예시 텍스트로 치환 결과 표시)
- 편집: 프리셋은 프롬프트만 수정 가능, 사용자 정의는 전체 수정 가능
- 삭제: 프리셋은 삭제 불가 (리셋만 가능), 사용자 정의는 확인 후 삭제
- 드래그 앤 드롭으로 순서 변경
- IPC 채널:
  - `customInstruction:getAll`
  - `customInstruction:create`
  - `customInstruction:update`
  - `customInstruction:delete`
  - `customInstruction:reorder`

### 6.4 핫키 바인딩 (명령어별)
- 각 커스텀 명령어에 개별 핫키 설정 가능
- HotkeyService에 동적 핫키 등록/해제 연동
- 핫키 녹화 UI (Speakly HotkeyRecordModal 참조):
  - 모달에서 키 조합 누르면 감지 → 표시 → 저장
  - 시스템 예약 키 블랙리스트 (Ctrl+C, Ctrl+V, Alt+F4 등)
  - 중복 핫키 충돌 감지 + 경고
- 명령어별 핫키 → VoiceModeService에 postProcess 자동 설정
  - 핫키 감지 시: 해당 명령어의 prompt로 postProcess 설정 후 녹음 시작

### 6.5 설정 UI 고도화
- `src/renderer/components/Settings.tsx` — MUI Modal 기반
- 섹션별 탭 구성:

**일반 탭:**
- 테마 선택 (light/dark/system)
- 시작 시 최소화
- 닫기 시 트레이로 최소화

**음성 입력(STT) 탭:**
- STT 모델 선택 드롭다운 (base, small, medium, large-v3)
  - 모델별 크기, 정확도 설명 표시
  - 미다운로드 모델 표시 + 다운로드 버튼 (선택)
- 기본 언어 선택 (auto, ko, en, ja, zh 등)
- VAD 필터 토글
- 초기 프롬프트 입력
- 마이크 디바이스 선택 + 테스트 (Phase 3에서 이관)

**LLM 탭:**
- Ollama 서버 URL 입력 + 연결 테스트 버튼
- 기본 LLM 모델 선택 드롭다운 (Ollama에서 설치된 모델 목록 조회)
- 기본 온도, 최대 토큰 설정
- 기본 후처리 명령 선택

**TTS 탭:**
- TTS 활성화/비활성화 토글
- 기본 음성 선택 (설치된 음성 목록)
- 말하기 속도 슬라이더 (0.5x ~ 2.0x)
- 미리듣기 버튼

**핫키 탭:**
- Dictation 모드 핫키 설정
- Hands-free 모드 핫키 설정
- 커스텀 명령어별 핫키 설정 (6.4 연동)
- 핫키 녹화 모달

### 6.6 온보딩 플로우 (첫 실행 안내)
- 앱 최초 실행 감지: ConfigService에 `onboarding.completed` 플래그
- 4단계 온보딩 위저드:
  1. **환영**: 앱 소개, 주요 기능 설명
  2. **마이크 설정**: 디바이스 선택 + 테스트 녹음
  3. **핫키 설정**: 기본 핫키 안내 + 커스텀 설정
  4. **Ollama 설정**: Ollama 설치 안내 + 연결 테스트, 모델 선택
- 건너뛰기 가능, 설정에서 다시 실행 가능
- Speakly FlowOnboarding 참조: 단계별 UI, 진행 표시기

### 6.7 i18n (한국어/영어)
- `src/shared/i18n/` 디렉토리
- 리소스 파일 구조:
  ```
  i18n/
  ├── ko.json    # 한국어 (기본)
  └── en.json    # 영어
  ```
- 간단한 i18n 유틸리티 (라이브러리 없이 직접 구현):
  ```typescript
  type I18nKey = string;
  function t(key: I18nKey, params?: Record<string, string>): string;
  function setLocale(locale: 'ko' | 'en'): void;
  function getLocale(): string;
  ```
- React 컨텍스트: `I18nProvider` + `useI18n()` 훅
- ConfigService `ui.language` 연동
- 번역 대상: UI 라벨, 에러 메시지, 프리셋 명령어 이름/설명, 온보딩 텍스트
- Speakly I18nService 참조: 키-값 리소스 파일, 런타임 언어 전환

### 6.8 IPC 채널 추가
- `customInstruction:getAll`, `customInstruction:create`, `customInstruction:update`, `customInstruction:delete`, `customInstruction:reorder`
- `config:getSection`, `config:setSection`, `config:resetSection`
- `i18n:getLocale`, `i18n:setLocale`, `i18n:getTranslations`
- `onboarding:getStatus`, `onboarding:complete`

## Speakly RE 참조
- CustomInstructionConfigService: 명령어 CRUD, 프리셋 관리, electron-store 저장
- HotkeyConfig: 키코드 맵, 시스템 예약 단축키 블랙리스트, HotkeyRecordModal
- FlowOnboarding: 단계별 온보딩 UI, 진행 표시, 건너뛰기
- I18nService: 키-값 리소스 파일, 런타임 언어 전환, React 컨텍스트 연동
- Settings: 섹션별 탭 UI, 디바이스 선택, 모델 선택

## 완료 조건
- [ ] 프리셋 명령어 5개 기본 제공
- [ ] 사용자 정의 명령어 추가/편집/삭제/순서변경 가능
- [ ] 명령어별 핫키 바인딩 및 핫키로 녹음+명령어 실행 가능
- [ ] 설정에서 STT 모델, LLM 모델, TTS 음성 선택 가능
- [ ] Ollama 연결 테스트 작동
- [ ] 온보딩 위저드가 첫 실행 시 표시됨
- [ ] 한국어/영어 UI 전환 가능
- [ ] 모든 UI 텍스트가 i18n 리소스에서 로드됨