# 🧲 Transmission Magnet Manager

현재 호스트에 Docker로 구동 중인 **Transmission (`linuxserver/transmission`, 포트 9091)** 에 마그넷 링크를 원격으로 추가하고 다운로드 상태를 관리하는 **FastAPI 백엔드 + Vue 3 프론트엔드** 애플리케이션입니다.

---

## 🛠 기술 스택
- **Backend**: Python 3.14, FastAPI, Uvicorn, HTTPX, Pydantic
- **Frontend**: Vue 3 (Composition API, `<script setup>`), Vuetify 3, Material Design Icons (`@mdi/font`), Vite
- **Torrent Engine**: 호스트 Docker 컨테이너 (`dd7da08820de`, Transmission RPC 9091)

---

## 🚀 빠른 시작

### 1. 단일 웹 서버 모드 (권장)
프론트엔드 정적 파일이 빌드되어 포함되어 있으므로 단일 커맨드로 백엔드와 프론트엔드가 모두 서빙됩니다.

```bash
# 가상환경 활성화 후 실행
./venv/bin/python main.py
```
브라우저에서 **[http://localhost:8000](http://localhost:8000)** 으로 접속하세요.

### 2. 창(Desktop Window) 모드
`pywebview`를 통해 독립된 데스크톱 앱 창 형태로 실행할 수도 있습니다.
```bash
./venv/bin/python main.py --window
```

---

## 💻 개발 모드 (HMR & 실시간 반영)

### Backend 개별 실행
```bash
./venv/bin/uvicorn backend.app.main:app --host 0.0.0.0 --port 8000 --reload
```

### Frontend 개별 실행
```bash
cd frontend
npm run dev
```
- 프론트엔드 개발 서버: `http://localhost:5173` (백엔드 `http://localhost:8000`으로 자동 프록시)

### Frontend 프로덕션 재빌드
프론트엔드 코드를 수정한 후 빌드하려면:
```bash
cd frontend
npm run build
```

---

## 🚢 실서버 배포 가이드 (Deployment)

이 프로젝트는 프론트엔드(`frontend/dist`)가 이미 백엔드(`FastAPI`)에 통합되어 빌드되어 있으므로, **포트 `8000`번 하나만 띄우면 웹 UI와 모든 API가 완전히 동작**합니다.

환경에 맞는 배포 방식을 선택하세요:

### 방법 1. Systemd 서비스 등록 (가장 추천: 홈서버/라즈베리파이/Linux)
서버 부팅 시 자동으로 백그라운드에서 실행되도록 등록합니다.

```bash
# 1. 서비스 파일을 systemd 경로로 복사
sudo cp transmission-manager.service /etc/systemd/system/

# 2. 서비스 데몬 리로드 및 부팅 시 자동 시작 활성화
sudo systemctl daemon-reload
sudo systemctl enable transmission-manager

# 3. 서비스 시작
sudo systemctl start transmission-manager

# 4. 상태 확인
sudo systemctl status transmission-manager
```
- 중지: `sudo systemctl stop transmission-manager`
- 로그 확인: `journalctl -u transmission-manager -f`

---

### 방법 2. Docker / Docker Compose 배포
도커 컨테이너로 완전 격리하여 배포할 수 있습니다.

```bash
# 컨테이너 빌드 및 백그라운드 실행
docker compose up -d --build
```
- 로그 확인: `docker compose logs -f`
- 컨테이너 종료: `docker compose down`

---

### 방법 3. Nginx 역방향 프록시 (외부 접속 & 도메인/HTTPS 연결)
도메인을 연결하거나 80/443 포트로 외부 접속을 열고자 할 때 Nginx 설정 예시:

```nginx
server {
    listen 80;
    server_name my-torrent.example.com; # 도메인 또는 IP

    # 대용량 파일 다운로드 및 업로드 타임아웃 방지
    client_max_body_size 0;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # SSE 실시간 진행률 스트리밍 지원 필수 설정
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 86400s;
    }
}
```

---

## 📌 주요 기능
1. **사이드 네비게이션 메뉴 (`v-navigation-drawer`)**
   - **토렌트 관리**: 마그넷 추가 및 활성 토렌트 모니터링 (실시간 활성 토렌트 개수 뱃지 표시)
   - **다운로드 파일 뷰어**: 다운로드 완료 디렉토리(`/mnt/ssd/transmission/downloads`) 파일 브라우저
2. **마그넷 링크 추가 (`POST /api/torrents/add`)**
   - `magnet:?xt=urn:...` 및 토렌트 URL 추가
   - 원클릭 클립보드 붙여넣기 지원
   - 저장 경로 커스텀 지정 옵션 (비워둘 시 기본 다운로드 경로 `/downloads/complete` 사용)
   - 추가 즉시 일시정지 옵션
3. **실시간 토렌트 현황 모니터링 (`GET /api/torrents`)**
   - 파일명, 다운로드 진행률 (%), 파일 크기
   - 실시간 다운로드 / 업로드 속도 표시
   - 4초 주기 자동 새로고침 및 수동 새로고침
4. **토렌트 제어**
   - 일시정지 (`POST /api/torrents/{id}/stop`)
   - 다운로드 시작/재개 (`POST /api/torrents/{id}/start`)
   - 토렌트 삭제 (`DELETE /api/torrents/{id}`: 데이터 보존 제거 또는 디스크 데이터 완전 삭제 지원)
5. **다운로드 파일 뷰어 (`GET /api/files`)**
   - 브레드크럼(경로 이동) 및 상위 폴더 이동 지원
   - 파일 확장자별 자동 분류 아이콘 (폴더, 압축파일, 동영상, 음악, 이미지, 문서 등)
   - 파일 개별 다운로드 및 미디어 미리보기(동영상/오디오/이미지/문서 스트리밍 뷰어) 지원
   - **파일 한 번에 다운로드 (일괄 ZIP 다운로드)**:
     - **폴더 전체 다운로드**: 현재 폴더 또는 하위 폴더를 통째로 하나의 `.zip`으로 묶어 한 번에 다운로드 (`GET /api/files/download-folder`)
     - **체크박스 다중 선택 다운로드**: 원하는 파일/폴더들을 체크박스로 다중 선택하여 하나의 `.zip` 파일로 묶어서 일괄 다운로드 (`POST /api/files/download-batch`)
     - **선택 항목 일괄 삭제**: 체크한 파일들을 한 번에 디스크에서 삭제 지원
   - **압축 파일 풀기 & 실시간 진행 과정 (`POST /api/files/extract-stream`)**:
     - 암호화 압축 파일 초고속 사전 감지 및 암호(비밀번호) 입력 지원
     - SSE(Server-Sent Events) 기반 **실시간 압축 해제 진행률(0~100%) 프로그레스 바**, 처리 중인 파일명, 완료 파일 개수 실시간 표시
   - 파일/폴더 삭제 지원
6. **연결 상태 모니터링 (`GET /api/status`)**
   - Transmission 컨테이너와의 RPC 통신 상태 및 버전 표시