84 lines
6.1 KiB
Markdown
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종)
|