# D3RO-VOICE — 멀티플랫폼 AI 음성 어시스턴트 모노레포 로컬 우선(Desktop) + 클라우드 동기화(Web · Mobile · Supabase · .NET API · Admin)를 아우르는 멀티플랫폼 AI 음성 어시스턴트. > **에이전트 진입점**: 작업 전 [`AGENTS.md`](./AGENTS.md)와 정본 인프라/기능 지도인 [`docs/map/00-index.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`) ## 빌드 및 검증 ```bash 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 도구로 참조) - [`docs/map/00-index.md`](./docs/map/00-index.md) — **정본 기능·인프라 지도 색인** (`01`~`12`) - [`docs/map/10-feature-catalog.md`](./docs/map/10-feature-catalog.md) — 플랫폼별 기능 구현 상태 매트릭스 - [`docs/map/11-gap-backlog.md`](./docs/map/11-gap-backlog.md) — 미해결 갭·백로그·외부 블로커 - [`docs/v3/MOBILE_APP_COMPLETION_SSOT.md`](./docs/v3/MOBILE_APP_COMPLETION_SSOT.md) — 모바일 완성도 정본 - `docs/design/00-master-architecture.md` ~ `03-db-and-ui.md` — 데스크톱 초기 아키텍처 설계 기록 ## 데스크톱 서비스 목록 (`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종)