초기 프로젝트 설정: 하네스 시스템 + 설계서 + RE 노하우

- CLAUDE.md: 프로젝트 규칙, 기술 스택, 코딩 규칙, 페이즈 로드맵
- .claude/settings.json: 권한, 강제 훅 (매 프롬프트 설계서 규칙 주입)
- .claude/skills/: implement-phase, review-phase, scaffold, test-commit, debug
- .claude/agents/: electron-architect, voice-pipeline-expert, ui-specialist
- docs/design/00-09: 마스터 아키텍처, 서비스 명세(16개), IPC(113채널),
  DB스키마, UI컴포넌트, 검증리포트, 외부엔진연동, 갭분석,
  VoiceMode패턴, 디자인시스템, 히스토리팝업
- docs/phases/1-7+3.5: 전체 구현 페이즈 문서
- docs/re-findings/: Speakly RE 노하우 5개 문서
This commit is contained in:
Yun Chan 2026-04-05 01:03:03 +09:00
commit e24bb8378c
35 changed files with 11452 additions and 0 deletions

59
docs/phases/phase-1.md Normal file
View file

@ -0,0 +1,59 @@
# Phase 1: 프로젝트 초기화 + Electron 뼈대 + 마이크 캡처
## 목표
프로젝트 기본 구조를 세우고, Electron 앱이 실행되며, 마이크에서 오디오를 캡처할 수 있는 상태까지.
## 태스크
### 1.1 프로젝트 초기화
- `npm init` + package.json 설정
- TypeScript 설정 (tsconfig.json, strict mode)
- Vite + Electron 개발 환경 설정 (electron-vite 또는 vite-plugin-electron)
- ESLint + Prettier 설정
- vitest 테스트 환경 설정
- .gitignore, README.md
### 1.2 Electron 기본 구조
- `src/main/index.ts` — 앱 진입점
- Speakly 패턴: app.whenReady → 서비스 초기화 → createWindow → IPC 등록
- 단일 인스턴스 잠금
- before-quit / will-quit 리소스 정리
- `src/preload/index.ts` — contextBridge 기본 구조
- `src/renderer/main.tsx` — React 앱 진입점
- `src/shared/ipc-channels.ts` — IPC 채널 중앙 정의
- `src/shared/types.ts` — 공통 타입
- `src/shared/errors.ts` — 에러 코드 체계 (Speakly NXError 패턴)
### 1.3 메인 윈도우
- BrowserWindow 생성 (1104x816, hiddenInset titleBar)
- contextIsolation: true, nodeIntegration: false
- 기본 React App 컴포넌트 (빈 대시보드)
### 1.4 시스템 트레이
- Tray 아이콘 + 메뉴 (표시/숨기기, 종료)
- Windows: closeToTray 옵션
### 1.5 마이크 캡처 서비스
- `src/main/services/AudioCaptureService.ts`
- Web Audio API 또는 node-record-lpcm16
- 24kHz mono PCM16 (또는 16kHz for Whisper)
- noiseSuppression: false, echoCancellation: false
- EventEmitter 패턴: 'audio-data', 'audio-level', 'started', 'stopped'
- IPC: `audio:startCapture`, `audio:stopCapture`, `audio:getDevices`
### 1.6 오디오 디바이스 관리
- 마이크 디바이스 목록 조회
- 디바이스 변경 감지
- 선택된 디바이스 저장 (electron-store)
## Speakly RE 참조
- NativeHelper.dll MicrophoneCapture: WASAPI 이벤트 구동, 24kHz mono
- AudioService: EventEmitter 패턴, 구독자 레퍼런스 카운팅
- main/index.js: 22단계 초기화 순서
## 완료 조건
- [ ] `npm run dev` 로 Electron 앱 실행됨
- [ ] 마이크에서 오디오 데이터 캡처 가능
- [ ] 시스템 트레이에 아이콘 표시
- [ ] `npm run typecheck` 통과
- [ ] `npm run test` 통과