# Motrix (Electron) -> gdown (Tauri + Vue) 포팅 계획서

## 1. 목표
- Electron 중심 구조를 Tauri + Vue 구조로 전환한다.
- 기존 Motrix의 핵심 기능(aria2 엔진 제어, 다운로드 큐, 설정/세션, 트레이/알림)을 단계적으로 재구현한다.
- 초기 단계에서 "동작 가능한 최소 제품(MVP)"을 빠르게 만들고, 이후 안정화와 기능 확장을 진행한다.

## 2. 기준 환경
- Node.js: 24.x
- npm: 11.x
- Rust: stable (1.93.1+)
- Tauri: v2 계열
- Vue: v3 + Vite

## 3. 아키텍처 매핑
- Electron main (`src/main/*`) -> Tauri Rust (`src-tauri/src/*`)
- Electron renderer (`src/renderer/*`) -> Vue UI (`src/*`)
- aria2 프로세스 관리 (`main/core/Engine.js`) -> Rust process manager (`src-tauri/src/engine.rs`)
- 앱 설정 저장(`electron-store`) -> Tauri plugin-store(차기 단계)
- 트레이/알림/OS 훅 -> Tauri tray/notification/deep-link plugin(차기 단계)

## 4. 단계별 구현

### Phase 1 (진행 중): 엔진 부트스트랩
- [x] Tauri + Vue 프로젝트 초기화
- [x] Rust command: `engine_start`, `engine_stop`, `engine_status`
- [x] Vue 대시보드에서 엔진 제어 UI 연결
- [x] aria2 바이너리 경로 자동 탐지 커맨드 추가 (`detect_aria2_binary`)
- [x] 시작 실패 에러 분류(파일 없음, 권한 오류, 즉시 종료)
- [x] aria2 번들 바이너리 리소스 구조 확정 (`src-tauri/resources/engine/*`)
- [~] 실배포 번들 검증 (플랫폼별 smoke test 진행 중)

### Phase 2: 다운로드 RPC/큐
- [x] aria2 JSON-RPC client 계층 구현 (Rust command 래퍼)
- [x] 작업 추가 (URI/Torrent)
- [x] 작업 목록/속도/진행률 갱신
- [x] 작업 제어(개별 pause/resume/remove, 전체 pause/resume)
- [~] Magnet/Torrent 입력 파이프라인 (입력/추가는 완료, 메타데이터 UX 개선 필요)
- [ ] 작업 상세 패널(파일/피어/트래커/활동) 구현
- [ ] 선택 기반 배치 액션(다중 선택, 일괄 정지/재개/삭제)

### Phase 3: 설정/세션/마이그레이션
- [~] 설정 저장소 도입 (다운로드 폴더, 동시작업 수, 속도 제한 등)
  - [x] 기본 실행 설정(localStorage) 저장/복원
  - [ ] aria2 글로벌 옵션과 완전 동기화
- [ ] 세션 파일 관리(종료 시 저장, 시작 시 복구)
- [ ] Motrix 설정 키 매핑표 작성 및 자동 마이그레이션 도구

### Phase 4: 플랫폼 기능
- [ ] 시스템 트레이 메뉴
- [ ] 알림/자동 시작
- [ ] 파일 연결(.torrent) 및 magnet scheme 등록
- [ ] 업데이트 전략(자체 업데이트 또는 외부 배포 전략)

### Phase 5: 품질/배포
- [ ] 단위/통합 테스트
- [ ] 성능 측정(메모리, CPU, 대용량 큐)
- [ ] macOS/Windows/Linux 빌드 파이프라인

### Phase 6 (신규): Native Messaging 안정화 전환
- 목표 산출물: `브라우저 -> Native Host -> gdown` 경로를 표준 경로로 확정
- Step 1: Native Host 스캐폴드(프로토콜/manifest/설치 스크립트) [진행]
- Step 2: 확장 우클릭/자동 다운로드 경로를 Native Host로 연결 [진행]
- Step 3: 앱 제어(다운로드 추가/포커스) 채널 정식화
- Step 4: 링크 자동 후킹을 Native Host 경로로 이관
- Step 5: 오류 복구/로깅/설정 UX 정리

### Phase 7 (신규): 범주(Category) 기능
- Step 1: 범주 기본 데이터 + 설정 토글 + Add 모달 범주 선택/경로 반영
- Step 2: 범주 CRUD UI(이름/아이콘/확장자 룰)
- Step 3: 좌측 범주 패널(카운트/필터/접힘 상태) 연동
- Step 4: 확장/외부 요청 자동 분류 규칙 정교화
- Step 5: 성능/UX/오류 피드백 상용 수준 마감

## 5. 리스크 및 대응
- aria2 바이너리 번들/서명: 플랫폼별 바이너리 동봉 규칙 문서화 + CI 검증
- Electron API 차이: 기능별 대체표를 먼저 만들고 Tauri plugin으로 대응
- 설정 호환성: 기존 키를 그대로 유지하지 않고 매핑 테이블로 이관

## 6. 현재 구현 상태 (2026-02-24)
- 완료:
  - `scripts/version-bump.sh`: 빌드 전 patch 버전 자동 증가 훅 추가
  - `scripts/sync-aria2-from-motrix.sh`: Motrix extra 엔진 리소스 동기화
  - `src-tauri/resources/engine`: Motrix 기반 번들 aria2 바이너리 포함
  - `src-tauri/src/engine.rs`: RPC 포트 점유 시 기존 aria2 인스턴스 재사용
  - `@tauri-apps/plugin-dialog` 연동: 기본 저장 폴더 네이티브 선택 구현
  - `src/App.vue`: 엔진 제어를 수동 버튼 방식에서 자동 관리(Motrix 스타일)로 전환
  - `src/App.vue` + `src/style.css`: 메인 다운로드 화면의 엔진 하단 패널 제거(자동 엔진 관리 기반으로 UI 단순화)
  - `src/App.vue`: 저장 폴더 선택 버튼 상호작용 안정화(label 중첩 제거)
  - `src/style.css`: 설정 드롭다운(select) 플랫 스타일 적용
  - `src-tauri/capabilities/default.json`: dialog open 권한 추가
  - `src-tauri/tauri.conf.json`: 초기 창 크기 확대 및 `main` 라벨 명시
  - `src-tauri/src/engine.rs`: 삭제 동작 안정화(`aria2.remove` 실패 시 `aria2.removeDownloadResult` 폴백, 이미 삭제된 GID idempotent 처리)
  - `src/App.vue` + `src/style.css`: 다운로드 리스트를 테이블에서 Motrix형 카드 + 아이콘 액션 버튼 UI로 재구성
  - `src/App.vue` + `src/style.css`: 다운로드 화면 레이아웃을 스크린샷 기준(라이트 톤, 좌측 작업 패널, 상단 아이콘 툴바)으로 재정렬
  - `src-tauri/src/engine.rs` + `src/lib/engineApi.ts`: 파일관리자에서 경로 열기 커맨드(`open_path_in_file_manager`) 추가
  - `src-tauri/src/engine.rs`: task summary에 `uri` 노출 추가(링크 복사용)
  - `src/App.vue`: Motrix `TaskActions`/`TaskItemActions` 기능 매핑에 맞춘 상단/항목 아이콘 동작 연결
  - `src-tauri/src/lib.rs`: macOS 앱 시작 시 Native Host manifest/runner 자동 설치(`org.gdown.nativehost`)
  - `src/App.vue` + `src/style.css`: 범주 기능 Step 1(기본 토글/선택/적용 폴더 프리뷰 + Add 시 경로 자동 반영)
  - `src-tauri/src/engine.rs`: aria2 프로세스 시작/중지/상태 조회
  - `src-tauri/src/engine.rs`: 바이너리 자동 탐지 + 에러 분류 + 작업 제어 RPC 커맨드
  - `src-tauri/src/lib.rs`: Tauri invoke handler 연결
  - `src/lib/engineApi.ts`: 프런트 command 호출 래퍼(엔진 + 작업 제어)
  - `src/App.vue`: Motrix 스타일 사이드바/목록/추가 모달/액션 버튼
  - `src/style.css`: 작업 액션 UI 스타일 보강
- 다음 우선순위:
  1. Native Messaging Host MVP 구축 (확장 연동 전 단계 산출물)
  2. Motrix `Task Detail` 동등 기능(파일/피어/트래커/활동) 구현
  3. 설정 저장소 도입(local persist + aria2 global option 적용)
