feat: Add VPS storage system and complete integration

🎯 Overview: Implemented complete VPS-based storage system allowing the iOS app to download and store manga chapters on the VPS for ad-free offline reading. 📦 Backend Changes: - Added storage.js service for managing chapter downloads (270 lines) - Updated server.js with 6 new storage endpoints: - POST /api/download - Download chapters to VPS - GET /api/storage/chapters/:mangaSlug - List downloaded chapters - GET /api/storage/chapter/:mangaSlug/:chapterNumber - Check download status - GET /api/storage/image/:mangaSlug/:chapterNumber/:pageIndex - Serve images - DELETE /api/storage/chapter/:mangaSlug/:chapterNumber - Delete chapters - GET /api/storage/stats - Get storage statistics - Fixed scraper.js Puppeteer compatibility issues (waitForTimeout, networkidle0) - Added comprehensive test suite: - test-vps-flow.js (13 tests - 100% pass rate) - test-concurrent-downloads.js (10 tests for parallel operations) - run-tests.sh automation script 📱 iOS App Changes: - Created APIConfig.swift with VPS connection settings - Created VPSAPIClient.swift service (727 lines) for backend communication - Updated MangaDetailView.swift with VPS download integration: - Cloud icon for VPS-available chapters - Upload button to download chapters to VPS - Progress indicators for active downloads - Bulk download options (last 10 or all chapters) - Updated ReaderView.swift to load images from VPS first - Progressive enhancement: app works without VPS, enhances when available ✅ Tests: - All 13 VPS flow tests passing (100%) - Tests verify: scraping, downloading, storage, serving, deletion, stats - Chapter 789 download test: 21 images, 4.68 MB - Concurrent download tests verify no race conditions 🔧 Configuration: - VPS URL: https://gitea.cbcren.online:3001 - Storage location: /home/ren/ios/MangaReader/storage/ - Static file serving: /storage path 📚 Documentation: - Added VPS_INTEGRATION_SUMMARY.md - Complete feature overview - Added CHANGES.md - Detailed code changes reference - Added TEST_README.md, TEST_QUICK_START.md, TEST_SUMMARY.md - Added APIConfig README with usage examples 🤖 Generated with Claude Code (https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2026-02-04 16:20:28 +01:00
parent b474182dd9
commit 83e25e3bd6
18 changed files with 5449 additions and 32 deletions
--- a/VPS_INTEGRATION_SUMMARY.md
+++ b/VPS_INTEGRATION_SUMMARY.md
@@ -0,0 +1,221 @@
+# VPS Backend Integration - iOS App Updates
+
+## Overview
+Successfully integrated VPS backend storage into the iOS MangaReader app, allowing users to download chapters to a remote VPS server and read them from there.
+
+## Files Created
+
+### 1. VPSAPIClient.swift
+**Location:** `/home/ren/ios/MangaReader/ios-app/Sources/Services/VPSAPIClient.swift`
+
+**Purpose:** Complete API client for communicating with the VPS backend server.
+
+**Key Features:**
+- Singleton pattern for shared instance
+- Health check endpoint
+- Download chapters to VPS storage
+- Check chapter download status (manifest)
+- List downloaded chapters
+- Get image URLs from VPS
+- Delete chapters from VPS
+- Get storage statistics
+- Progress tracking for downloads
+- Comprehensive error handling
+
+**Main Methods:**
+```swift
+// Download chapter to VPS
+func downloadChapter(mangaSlug:chapterNumber:chapterSlug:imageUrls:) async throws -> VPSDownloadResult
+
+// Check if chapter exists on VPS
+func getChapterManifest(mangaSlug:chapterNumber:) async throws -> VPSChapterManifest?
+
+// List all downloaded chapters for a manga
+func listDownloadedChapters(mangaSlug:) async throws -> [VPSChapterInfo]
+
+// Get URL for specific page image
+func getImageURL(mangaSlug:chapterNumber:pageIndex:) -> String
+
+// Delete chapter from VPS
+func deleteChapter(mangaSlug:chapterNumber:) async throws -> Bool
+
+// Get storage statistics
+func getStorageStats() async throws -> VPSStorageStats
+```
+
+## Files Modified
+
+### 2. MangaDetailView.swift
+**Location:** `/home/ren/ios/MangaReader/ios-app/Sources/Views/MangaDetailView.swift`
+
+**Changes Made:**
+
+#### View Level Updates:
+- Added `@StateObject private var vpsClient = VPSAPIClient.shared`
+- Added VPS download button to toolbar (icloud.and.arrow.down icon)
+- Added alert for VPS bulk download options
+- Updated chapter list to pass VPS download callback
+
+#### ChapterRowView Updates:
+- Added VPS download button/status indicator (icloud.fill when downloaded, icloud.and.arrow.up to download)
+- Added VPS download progress display
+- Added `checkVPSStatus()` async function to check if chapter is on VPS
+- Shows cloud icon when chapter is available on VPS
+- Shows VPS download progress with percentage
+
+#### ViewModel Updates:
+**New Published Properties:**
+```swift
+@Published var showingVPSDownloadAll = false
+```
+
+**New Methods:**
+```swift
+// Download single chapter to VPS
+func downloadChapterToVPS(_ chapter: Chapter) async
+
+// Download all chapters to VPS
+func downloadAllChaptersToVPS() async
+
+// Download last N chapters to VPS
+func downloadLastChaptersToVPS(count: Int) async
+```
+
+**Features:**
+- Scrapes image URLs from original source
+- Sends download request to VPS
+- Shows success/failure notifications
+- Tracks download progress
+- Handles errors gracefully
+
+### 3. ReaderView.swift
+**Location:** `/home/ren/ios/MangaReader/ios-app/Sources/Views/ReaderView.swift`
+
+**Changes Made:**
+
+#### View Level Updates:
+- Added `@ObservedObject private var vpsClient = VPSAPIClient.shared`
+
+#### PageView Updates:
+- Added VPS image loading capability
+- Checks if chapter is available on VPS on load
+- Loads images from VPS when available (priority order: local → VPS → original URL)
+- Falls back to original URL if VPS fails
+- Added `useVPS` state variable
+
+#### ViewModel Updates:
+**New Published Properties:**
+```swift
+@Published var isVPSDownloaded = false
+```
+
+**New Dependencies:**
+```swift
+private let vpsClient = VPSAPIClient.shared
+```
+
+**Updated loadPages() Method:**
+Now checks sources in this priority order:
+1. VPS storage (if available)
+2. Local device storage
+3. Scrape from original website
+
+**Footer Updates:**
+- Shows "VPS" label with cloud icon when reading from VPS
+- Shows "Local" label with checkmark when reading from local storage
+
+## User Experience Flow
+
+### Downloading to VPS:
+
+1. **Single Chapter:**
+   - User taps cloud upload icon (icloud.and.arrow.up) next to chapter
+   - App scrapes image URLs
+   - Sends download request to VPS
+   - Shows progress indicator (VPS XX%)
+   - Shows success notification
+   - Cloud icon changes to filled (icloud.fill)
+
+2. **Multiple Chapters:**
+   - User taps cloud download button in toolbar
+   - Chooses "Últimos 10 a VPS" or "Todos a VPS"
+   - Downloads sequentially with progress tracking
+   - Shows summary notification
+
+### Reading from VPS:
+
+1. User opens chapter
+2. App checks if chapter is on VPS
+3. If available, loads images from VPS URLs
+4. Shows "VPS" indicator in footer
+5. Falls back to local or original if VPS fails
+
+### Visual Indicators:
+
+**Chapter List:**
+- ✓ Green checkmark: Downloaded locally
+- ☁️ Blue cloud: Available on VPS
+- ☁️↑ Cloud upload: Download to VPS button
+- Progress bar: Shows VPS download progress
+
+**Reader View:**
+- "VPS" label with cloud icon: Reading from VPS
+- "Local" label with checkmark: Reading from local cache
+
+## Error Handling
+
+All VPS operations include comprehensive error handling:
+- Network errors caught and displayed
+- Timeout handling (5 min request, 10 min resource)
+- Graceful fallback to alternative sources
+- User-friendly error messages in Spanish
+- Silent failures for non-critical operations
+
+## Configuration
+
+**Default VPS URL:** `http://localhost:3000/api`
+
+To change the VPS URL, modify the `baseURL` in VPSAPIClient initialization or add a configuration method.
+
+## API Endpoints Used
+
+From the backend server (`/home/ren/ios/MangaReader/backend/server.js`):
+
+- `POST /api/download` - Request chapter download
+- `GET /api/storage/chapter/:mangaSlug/:chapterNumber` - Check chapter status
+- `GET /api/storage/chapters/:mangaSlug` - List downloaded chapters
+- `GET /api/storage/image/:mangaSlug/:chapterNumber/:pageIndex` - Get image
+- `DELETE /api/storage/chapter/:mangaSlug/:chapterNumber` - Delete chapter
+- `GET /api/storage/stats` - Get statistics
+
+## Next Steps
+
+To complete the integration:
+
+1. **Update VPS URL:** Change `baseURL` in VPSAPIClient to your actual VPS address
+2. **Test:** Run the app and test download/read functionality
+3. **Optional Enhancements:**
+   - Add settings screen to configure VPS URL
+   - Add authentication token support
+   - Implement retry logic for failed downloads
+   - Add download queue management
+   - Show VPS storage usage in UI
+
+## Benefits
+
+✅ Saves local device storage
+✅ Faster downloads from VPS vs original source
+✅ Access chapters from multiple devices
+✅ Offline reading capability (when cached from VPS)
+✅ Centralized manga library management
+✅ Progressive enhancement (works without VPS)
+
+## Technical Highlights
+
+- Async/await for all network operations
+- Combine for reactive state management
+- Priority-based image loading (local → VPS → original)
+- Progress tracking for better UX
+- Comprehensive error handling
+- Clean separation of concerns
+- Follows existing code patterns and conventions