docs: update README.md with comprehensive project, dev, build, and site profile guides

3 weeks ago · 883d9d7f82
parent 224f28042f
commit 883d9d7f82
1 changed files with 167 additions and 4 deletions
--- a/README.md
+++ b/README.md
@ -1,7 +1,170 @@
-# Tauri + React + Typescript
+# 📚 Mana Viewer (마나 뷰어)

-This template should help get you started developing with Tauri, React and Typescript in Vite.
+**Mana Viewer**는 웹툰 및 만화 사이트를 광고 없이 쾌적하게 감상할 수 있는 데스크톱 전용 뷰어 애플리케이션입니다.  
+Tauri v2(Rust)와 React + TypeScript 기반으로 제작되어 가볍고 빠르게 동작하며, 템플릿 기반 사이트 파싱 및 0초 사전 로딩 시스템을 탑재하고 있습니다.

-## Recommended IDE Setup
+---
+
+## ✨ 주요 기능
+
+- **🌐 템플릿 기반 사이트 파싱 시스템 (SiteProfile)**
+  - JSON 템플릿 프로필을 사용하여 사이트별 CSS 셀렉터, 이미지 속성, 안티봇 설정을 독립적으로 관리합니다.
+  - 와일드카드 도메인 매칭(`newtoki*.org`, `manatoki*.net` 등)으로 도메인 변경 시에도 자동 적응합니다.
+  - 인앱 JSON 에디터 지원으로 코드 수정 없이 새 사이트를 추가하거나 편집할 수 있습니다.
+- **⚡ 백그라운드 0초 다음 화 사전 로딩 (Pre-harvest & Preload)**
+  - 현재 챕터를 읽는 동안 다음 챕터의 이미지 및 정보들을 백그라운드에서 미리 수집하고 이미지를 메모리에 캐싱하여 대기 시간 없이 0초 즉시 전환됩니다.
+- **🏷️ 스마트 화수 & 시즌 정밀 파싱**
+  - 만화 제목에서 `150화`, `1100-1화`, `1100.5화`, `2기 15화`, `시즌2 15화`, `EP.150` 등의 화수/시즌 정보를 자동 추출하여 보라색 하이라이트 배지로 명확하게 표시합니다.
+- **📖 고도화된 만화 뷰어 기능**
+  - **단면/양면 보기**: 1장씩 보기 및 2장씩 펼쳐보기 모드 지원.
+  - **통페이지(Wide 이미지) 자동 감지**: 양면 모드 중 가로가 넓은 만화 페이지는 1장 단독 슬롯으로 자동 재배치.
+  - **읽기 방향 선택**: 좌→우 (LTR - 한국 웹툰) 및 우→좌 (RTL - 일본 만화).
+  - **이미지 강제 확대 (Allow Upscale)**: 창 크기에 맞춰 원본보다 크게 확대하는 옵션 제공.
+  - **배경색 설정**: 검정 / 어두운 회색 / 흰색 배경 선택.
+- **🔔 챕터 전환 & 경고 토스트**
+  - 다음 화 전환 시 상단 중앙에 챕터 제목 토스트 메시지 노출.
+  - 최신화 또는 첫 화에서 이동 시 `⚠️ 마지막 화입니다`, `⚠️ 첫 번째 화입니다` 알림 표시.
+- **📜 최근 읽은 만화 기록 관리**
+  - 최근 읽은 만화 제목, 화수, URL, 읽은 시간 자동 저장.
+  - 항목별 개별 삭제(`✕`) 및 전체 기록 삭제 기능 제공.
+
+---
+
+## 🛠️ 사전 요구 사항 (Prerequisites)
+
+개발 및 빌드를 진행하기 전에 다음 도구들이 설치되어 있어야 합니다.
+
+1. **Node.js**: v18.0.0 이상 ([공식 다운로드](https://nodejs.org/))
+2. **Rust**: Latest Stable Toolchain ([rustup 설치 Guide](https://rustup.rs/))
+3. **Tauri v2 OS 빌드 환경**:
+   - **macOS**: Xcode Command Line Tools (`xcode-select --install`)
+   - **Windows**: C++ Build Tools (Visual Studio Installer) 및 WebView2
+   - **Linux**: `webkit2gtk-4.1`, `build-essential`, `libssl-dev` 등
+
+---
+
+## 💻 개발 환경 실행 (Development)
+
+1. **저장소 클론 및 패키지 설치**:
+   ```bash
+   git clone https://gitea.yirugi.synology.me/yirugi/mana-viewer.git
+   cd mana-viewer
+   npm install
+   ```
+
+2. **개발 모드 구동 (Hot Reloading)**:
+   ```bash
+   npm run tauri dev
+   ```
+   *개발 서버(`vite`)가 1420 포트에서 실행되고, Tauri 백엔드가 자바스크립트 수집기 및 뷰어 윈도우를 구동합니다.*
+
+---
+
+## 📦 프로덕션 빌드 (Production Build)
+
+1. **독립 실행형 앱 빌드**:
+   ```bash
+   npm run tauri build
+   ```
+
+2. **빌드 결과물 위치**:
+   - **macOS 앱 번들 (`.app`)**:
+     `src-tauri/target/release/bundle/macos/Mana Viewer.app`
+   - **실행 파일 (Binary)**:
+     `src-tauri/target/release/mana-viewer` (또는 `tauri-app`)
+
+*생성된 `Mana Viewer.app` 파일을 `/Applications` (응용 프로그램) 폴더로 옮겨 바로 사용할 수 있습니다.*
+
+---
+
+## ⚙️ 사이트 프로필 (Site Profile) 추가 및 설정
+
+Mana Viewer는 **`src-tauri/profiles/`** 디렉토리에 저장된 JSON 파일들을 읽어 파싱 규칙을 적용합니다.
+
+### 📄 프로필 JSON 예시 (`src-tauri/profiles/custom_site.json`)
+```json
+{
+  "id": "custom_site",
+  "name": "새 만화 사이트",
+  "version": 1,
+  "domains": ["example*.com", "manga*.net"],
+  "selectors": {
+    "images": {
+      "containerSelector": null,
+      "imgSelector": "img",
+      "srcAttributes": ["data-src", "data-original", "data-lazy-src", "src"],
+      "pageOrderAttribute": null,
+      "minWidth": 150,
+      "excludeLandscape": true
+    },
+    "navigation": {
+      "prevSelectors": [".btn-prev", ".prev"],
+      "nextSelectors": [".btn-next", ".next"],
+      "prevText": "이전화",
+      "nextText": "다음화"
+    },
+    "title": {
+      "selectors": [".toon-title", "h1.title", "h1"],
+      "fallbackToDocumentTitle": true
+    }
+  },
+  "filters": {
+    "adClassPattern": "ad|banner|footer|header|popup",
+    "adFilenamePattern": "(^|[\\/_.\\-])(ad|ads|banner|event|popup|logo|icon)([\\/_.\\-]|$)"
+  },
+  "antiBot": {
+    "spoofViewport": true,
+    "spoofVisibility": true,
+    "fakeWidth": 1920,
+    "fakeHeight": 1080
+  },
+  "http": {
+    "needsCookies": true,
+    "refererPolicy": "origin"
+  }
+}
+```
+
+- **앱 내부 JSON 에디터**: 앱 홈 화면 하단 또는 뷰어 설정 메뉴의 `🌐 사이트 템플릿 프로필 관리 (JSON)` 버튼을 통해 앱을 종료하지 않고 템플릿을 수정 및 추가할 수 있습니다.
+
+---
+
+## ⌨️ 키보드 단축키 (Shortcuts)
+
+| 단축키 | 기능 |
+| :--- | :--- |
+| `←` / `A` / `KeyS` (한글 `ㄴ`) | 이전 페이지 / 이전 화 이동 |
+| `→` / `D` / `KeyF` (한글 `ㄹ`) | 다음 페이지 / 다음 화 이동 |
+| `↑` / `W` | 이전 페이지 이동 |
+| `↓` / `S` | 다음 페이지 이동 |
+| `F` | 전체화면 토글 |
+| `S` | 설정 패널 열기 / 닫기 |
+| `Esc` | 설정 패널 닫기 |
+
+---
+
+## 📂 프로젝트 구조 (Project Structure)
+
+```
+mana-viewer/
+├── src-tauri/
+│   ├── profiles/
+│   │   ├── _default.json         # 범용 기본 파싱 프로필 (Fallback)
+│   │   └── newtoki.json          # 뉴토끼/마나토키 전용 프로필
+│   └── src/
+│       ├── site_profile.rs       # 프로필 관리자 & 동적 INIT_SCRIPT 생성 엔진
+│       ├── commands.rs           # Tauri IPC 커맨드 & 수집용 하베스터 루프
+│       └── lib.rs                # Tauri 애플리케이션 핸들러
+└── src/
+    ├── utils/
+    │   └── titleParser.ts        # 화수/시즌 정밀 추출 유틸리티
+    ├── components/
+    │   ├── ProfileManagerModal.tsx # 인앱 JSON 프로필 에디터 모달
+    │   ├── MangaViewer.tsx       # 메인 만화 뷰어 & 토스트 시스템
+    │   ├── ViewerToolbar.tsx     # 상단 컨트롤바 & 화수 배지
+    │   └── UrlInput.tsx          # 홈 화면, URL 입력 & 최근 기록 관리
+    ├── hooks/
+    │   └── useChapter.ts         # 백그라운드 사전 수집 & 이미지 메모리 캐시
+    └── types.ts                  # SiteProfile 및 TypeScript 타입 정의
+```

- [VS Code](https://code.visualstudio.com/) + [Tauri](https://marketplace.visualstudio.com/items?itemName=tauri-apps.tauri-vscode) + [rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer)