backup
This commit is contained in:
@@ -120,3 +120,148 @@ For each task completed:
|
||||
- Good foundation for future enhancements if needed
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Current Task: Make MP4 Scanning Progress Visible in UI
|
||||
|
||||
### Problem Statement
|
||||
|
||||
When users trigger a library rescan (via the "Rescan Library" button on the anime page), the MP4 file scanning happens silently in the background. Users only see a brief toast message, but there's no visual feedback showing:
|
||||
|
||||
1. That scanning is actively happening
|
||||
2. How many files/directories have been scanned
|
||||
3. The progress through the scan operation
|
||||
4. When scanning is complete with results
|
||||
|
||||
Currently, the only indication is in server logs:
|
||||
|
||||
```
|
||||
INFO: Starting directory rescan
|
||||
INFO: Scanning for .mp4 files
|
||||
```
|
||||
|
||||
### Desired Outcome
|
||||
|
||||
Users should see real-time progress in the UI during library scanning with:
|
||||
|
||||
1. **Progress overlay** showing scan is active with a spinner animation
|
||||
2. **Live counters** showing directories scanned and files found
|
||||
3. **Current directory display** showing which folder is being scanned (truncated if too long)
|
||||
4. **Completion summary** showing total files found, directories scanned, and elapsed time
|
||||
5. **Auto-dismiss** the overlay after showing completion summary
|
||||
|
||||
### Files to Modify
|
||||
|
||||
#### 1. `src/server/services/websocket_service.py`
|
||||
|
||||
Add three new broadcast methods for scan events:
|
||||
|
||||
- **broadcast_scan_started**: Notify clients that a scan has begun, include the root directory path
|
||||
- **broadcast_scan_progress**: Send periodic updates with directories scanned count, files found count, and current directory name
|
||||
- **broadcast_scan_completed**: Send final summary with total directories, total files, and elapsed time in seconds
|
||||
|
||||
Follow the existing pattern used by `broadcast_download_progress` for message structure consistency.
|
||||
|
||||
#### 2. `src/server/services/scanner_service.py`
|
||||
|
||||
Modify the scanning logic to emit progress via WebSocket:
|
||||
|
||||
- Inject `WebSocketService` dependency into the scanner service
|
||||
- At scan start, call `broadcast_scan_started`
|
||||
- During directory traversal, track directories scanned and files found
|
||||
- Every 10 directories (to avoid WebSocket spam), call `broadcast_scan_progress`
|
||||
- Track elapsed time using `time.time()`
|
||||
- At scan completion, call `broadcast_scan_completed` with summary statistics
|
||||
- Ensure the scan still works correctly even if WebSocket broadcast fails (wrap in try/except)
|
||||
|
||||
#### 3. `src/server/static/css/style.css`
|
||||
|
||||
Add styles for the scan progress overlay:
|
||||
|
||||
- Full-screen semi-transparent overlay (z-index high enough to be on top)
|
||||
- Centered container with background matching theme (use CSS variables)
|
||||
- Spinner animation using CSS keyframes
|
||||
- Styling for current directory text (truncated with ellipsis)
|
||||
- Styling for statistics display
|
||||
- Success state styling for completion
|
||||
- Ensure it works in both light and dark mode themes
|
||||
|
||||
#### 4. `src/server/static/js/anime.js`
|
||||
|
||||
Add WebSocket message handlers and UI functions:
|
||||
|
||||
- Handle `scan_started` message: Create and show progress overlay with spinner
|
||||
- Handle `scan_progress` message: Update directory count, file count, and current directory text
|
||||
- Handle `scan_completed` message: Show completion summary, then auto-remove overlay after 3 seconds
|
||||
- Ensure overlay is properly cleaned up if page navigates away
|
||||
- Update the existing rescan button handler to work with the new progress system
|
||||
|
||||
### WebSocket Message Types
|
||||
|
||||
Define three new message types following the existing project patterns:
|
||||
|
||||
1. **scan_started**: type, directory path, timestamp
|
||||
2. **scan_progress**: type, directories_scanned, files_found, current_directory, timestamp
|
||||
3. **scan_completed**: type, total_directories, total_files, elapsed_seconds, timestamp
|
||||
|
||||
### Implementation Steps
|
||||
|
||||
1. First modify `websocket_service.py` to add the three new broadcast methods
|
||||
2. Add unit tests for the new WebSocket methods
|
||||
3. Modify `scanner_service.py` to use the new broadcast methods during scanning
|
||||
4. Add CSS styles to `style.css` for the progress overlay
|
||||
5. Update `anime.js` to handle the new WebSocket messages and display the UI
|
||||
6. Test the complete flow manually
|
||||
7. Verify all existing tests still pass
|
||||
|
||||
### Testing Requirements
|
||||
|
||||
**Unit Tests:**
|
||||
|
||||
- Test each new WebSocket broadcast method
|
||||
- Test that scanner service calls WebSocket methods at appropriate times
|
||||
- Mock WebSocket service in scanner tests
|
||||
|
||||
**Manual Testing:**
|
||||
|
||||
- Start server and login
|
||||
- Navigate to anime page
|
||||
- Click "Rescan Library" button
|
||||
- Verify overlay appears immediately with spinner
|
||||
- Verify counters update during scan
|
||||
- Verify current directory updates
|
||||
- Verify completion summary appears
|
||||
- Verify overlay auto-dismisses after 3 seconds
|
||||
- Test in both light and dark mode
|
||||
- Verify no JavaScript console errors
|
||||
|
||||
### Acceptance Criteria
|
||||
|
||||
- [ ] Progress overlay appears immediately when scan starts
|
||||
- [ ] Spinner animation is visible during scanning
|
||||
- [ ] Directory counter updates periodically (every ~10 directories)
|
||||
- [ ] Files found counter updates as MP4 files are discovered
|
||||
- [ ] Current directory name is displayed (truncated if path is too long)
|
||||
- [ ] Scan completion shows total directories, files, and elapsed time
|
||||
- [ ] Overlay auto-dismisses 3 seconds after completion
|
||||
- [ ] Works correctly in both light and dark mode
|
||||
- [ ] No JavaScript errors in browser console
|
||||
- [ ] All existing tests continue to pass
|
||||
- [ ] New unit tests added and passing
|
||||
- [ ] Code follows project coding standards
|
||||
|
||||
### Edge Cases to Handle
|
||||
|
||||
- Empty directory with no MP4 files
|
||||
- Very large directory structure (ensure UI remains responsive)
|
||||
- WebSocket connection lost during scan (scan should still complete)
|
||||
- User navigates away during scan (cleanup overlay properly)
|
||||
- Rapid consecutive scan requests (debounce or queue)
|
||||
|
||||
### Notes
|
||||
|
||||
- Keep progress updates throttled to avoid overwhelming the WebSocket connection
|
||||
- Use existing CSS variables for colors to maintain theme consistency
|
||||
- Follow existing JavaScript patterns in the codebase
|
||||
- The scan functionality must continue to work even if WebSocket fails
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user