d3ro-voice/CLAUDE.md

6.1 KiB

D3RO-VOICE — 멀티플랫폼 AI 음성 어시스턴트 모노레포

로컬 우선(Desktop) + 클라우드 동기화(Web · Mobile · Supabase · .NET API · Admin)를 아우르는 멀티플랫폼 AI 음성 어시스턴트.

에이전트 진입점: 작업 전 AGENTS.md와 정본 인프라/기능 지도인 docs/map/00-index.md를 먼저 읽는다. 기능 추가·삭제·변경·백로그 이관 시 docs/map/10-feature-catalog.md, 해당 플랫폼 표면 문서(04~09), docs/map/11-gap-backlog.md를 반드시 함께 갱신한다 (규칙: docs/map/12-update-protocol.md).

모노레포 표면 구성

  • apps/desktop — Electron 33+ 데스크톱 앱 (로컬 우선: SoX + faster-whisper Python sidecar + Ollama + SQLite/Drizzle + Cloud Sync)
  • apps/web — Next.js 16 클라우드 웹 콘솔 (/app basePath, React 19 + MUI 7 + Supabase SSR/Realtime + Web Push)
  • apps/mobile-rn — React Native 0.79 모바일 앱 (클라우드 우선, Android/iOS, 오프라인 내구성 큐, Google Play IAP, FCM/APNs)
  • apps/api-server — ASP.NET Core 10 AI 프록시 및 백오피스 백엔드
  • apps/admin — Next.js 16 관리자 백오피스 콘솔 (RBAC, 감사 로그, 콘텐츠 신고/지원 대응)
  • server/supabase — PostgreSQL + RLS + Auth + Storage + Deno Edge Functions (정본 제품 백엔드)
  • server/cloudflare-worker — 엣지 게이트웨이 및 라우팅 워커
  • site/ — 랜딩 · 마케팅 · 법무 · 다운로드 · 초대 핸드오프 정적 사이트
  • packages/* — 공유 패키지 (@d3ro/core, @d3ro/ui, @d3ro/ui-native, @d3ro/i18n, @d3ro/api-client)

빌드 및 검증

npm run dev               # Desktop (Electron + Vite) dev
npm run build             # Desktop 프로덕션 빌드
npm run typecheck         # 워크스페이스 전체 tsc --noEmit
npm run test              # 워크스페이스 vitest
npm run lint              # 워크스페이스 eslint
npm run typecheck:mobile  # Mobile RN tsc --noEmit
npm run test:mobile       # Mobile RN Jest
npm run lint:mobile       # Mobile RN eslint
npm run check:design      # 디자인 토큰 SSOT 검사

코딩 및 보안 규칙 (Non-Negotiable)

  • strict mode, any 금지, console.log 금지 (logger 사용)
  • 서비스: 싱글톤 + EventEmitter
  • IPC: ${feature}:${action} (packages/core/src/ipc-channels.ts 정본), D3ROError + ErrorCode + IPCResult
  • 메인앱=React+MUI, 데스크톱 팝업=Vanilla JS
  • 테마 SSOT: d3roPalette/d3roShadow/d3roTypo/d3roRadius 및 CSS 변수만 사용, hex 하드코딩 금지 (theme.ts 제외)
  • i18n: t() 함수 사용, UI 내 한국어/영어 문자열 하드코딩 금지
  • 시크릿 하드코딩 절대 금지, Fail-Closed 원칙 준수 (가짜 성공 응답·샘플 데이터 대체 금지)
  • Co-Authored-By, Claude 관련 커밋 문구 금지
  • Windows 데스크톱 실행: AI 에이전트 서브쉘(가상 데스크톱 exebox)에서 GUI 백그라운드 구동을 반복하지 말고, 사용자가 run-desktop.bat 또는 외부 터미널에서 실행하도록 안내.
  • Single Instance Lock: app.setName('d3ro-voice')와 app.setAppUserModelId를 최상단 선언하고 dev 모드 사일런트 종료 방지.
  • 오디오 장치 탐색: execSync 동기 블로킹 금지 (반드시 exec 비동기 논블로킹).
  • GPU 충돌 방지: app.disableHardwareAcceleration() 및 --disable-gpu 유지.

핵심 패턴 (Desktop)

  • RecognitionState(9) + AudioState(4) 이중 상태머신
  • 이중 조건 플러시 (모델 로딩 + 오디오 버퍼링 병렬)
  • 텍스트 삽입: clipboard save→set→Ctrl+V→restore
  • 윈도우: 프리로딩 + 2-phase 리사이즈
  • 녹음 UI: 9개 웨이브 바, cos 분포, 100ms

업데이트 / 릴리스

자동 업데이트는 electron-updater + Forgejo feed (git.chanpaca.net/api/packages/yunchan/generic/d3ro-voice/latest). 설치본은 무서명이라 latest.yml을 Ed25519로 서명하고 앱이 받은 설치 파일을 검증한다(update-signature.ts). 릴리스 = npm run release -- patch|minor 한 줄 (main, 깨끗한 트리, .env의 FORGEJO_TOKEN · D3RO_UPDATE_SIGNING_KEY). 실패하면 npm run release -- --resume. 채널·최소 지원 버전· 강제 업데이트·rollout·킬 스위치는 release/update-policy.json이 정본. 태그는 불변. 규칙은 AGENTS.md §6.

정본 문서 안내 (구현 전 Read 도구로 참조)

데스크톱 서비스 목록 (apps/desktop/src/main/services/)

Core: LoggerService, ConfigService, VoiceModeService(오케스트레이터), UnifiedSearchService Audio: AudioCaptureService, LocalSTTService, LocalLLMService, TTSPlaybackService Input: HotkeyService, TextInsertService, SoundEffectService, AutoLaunchService Data: HistoryService, DictionaryService, CustomInstructionService, LicenseService Phase10+: MemoService, VoiceCommandService, ScreenContextService, ChainService, CaptionService Phase12+: FileTranscriptionService, MeetingSummaryService, DictationTemplateService Phase13+: VoiceConversationService, RAGService, VoiceActionService Phase14+: MeetingModeService, MeetingDocTemplateService + 다중 문서 생성/편집/내보내기 + 화자 구분

DS 컴포넌트 (packages/ui & packages/ui-native)

CrtDisplay, InstrumentPanel, Led, PhysicalButton, MetalCard, DoubleBezelCard, PhosphorText(13변형), MetalDial, ScreenPanel, ButtonGroup, TactileBadge, StatRing, TiltCard

디자인 토큰 (theme.ts)

d3roPalette(색상) | d3roTypo(13단계) | d3roShadow(10종) | d3roRadius(7종)