d3ro-voice/CLAUDE.md

84 lines
6.1 KiB
Markdown

# 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종)