406 lines
13 KiB
Markdown
406 lines
13 KiB
Markdown
# Aniworld Web Application Development Instructions
|
|
|
|
This document provides detailed tasks for AI agents to implement a modern web application for the Aniworld anime download manager. All tasks should follow the coding guidelines specified in the project's copilot instructions.
|
|
|
|
## Project Overview
|
|
|
|
The goal is to create a FastAPI-based web application that provides a modern interface for the existing Aniworld anime download functionality. The core anime logic should remain in `SeriesApp.py` while the web layer provides REST API endpoints and a responsive UI.
|
|
|
|
## Architecture Principles
|
|
|
|
- **Single Responsibility**: Each file/class has one clear purpose
|
|
- **Dependency Injection**: Use FastAPI's dependency system
|
|
- **Clean Separation**: Web layer calls core logic, never the reverse
|
|
- **File Size Limit**: Maximum 500 lines per file
|
|
- **Type Hints**: Use comprehensive type annotations
|
|
- **Error Handling**: Proper exception handling and logging
|
|
|
|
## How you work
|
|
|
|
1. Task the next task
|
|
2. Process the task
|
|
3. Make Tests.
|
|
4. Remove task from instructions.md
|
|
5. Commit in git
|
|
6. goto 1.
|
|
|
|
## Implementation Order
|
|
|
|
The tasks should be completed in the following order to ensure proper dependencies and logical progression:
|
|
|
|
1. **Project Structure Setup** - Foundation and dependencies
|
|
2. **Authentication System** - Security layer implementation
|
|
3. **Configuration Management** - Settings and config handling
|
|
4. **Anime Management Integration** - Core functionality wrapper
|
|
5. **Download Queue Management** - Queue handling and persistence
|
|
6. **WebSocket Real-time Updates** - Real-time communication
|
|
7. **Frontend Integration** - Integrate existing frontend assets
|
|
8. **Core Logic Integration** - Enhance existing core functionality
|
|
9. **Database Layer** - Data persistence and management
|
|
10. **Testing** - Comprehensive test coverage
|
|
11. **Deployment and Configuration** - Production setup
|
|
12. **Documentation and Error Handling** - Final documentation and error handling
|
|
|
|
## Core Tasks
|
|
|
|
### 1. Project Structure Setup
|
|
|
|
#### [] Create main FastAPI application structure
|
|
|
|
- Create `src/server/main.py`
|
|
- Configure FastAPI app with CORS, middleware
|
|
- Set up static file serving for existing frontend assets
|
|
- Configure Jinja2 templates
|
|
- Add health check endpoint
|
|
|
|
#### [] Set up dependency injection system
|
|
|
|
- Create `src/server/utils/dependencies.py`
|
|
- Implement SeriesApp dependency injection
|
|
- Add database session dependency
|
|
- Create authentication dependency
|
|
|
|
#### [] Configure logging system
|
|
|
|
- Create `src/server/utils/logging.py`
|
|
- Set up structured logging with multiple handlers
|
|
- Configure log rotation and cleanup
|
|
- Add request/response logging middleware
|
|
|
|
### 2. Authentication System
|
|
|
|
#### [] Implement authentication models
|
|
|
|
- Create `src/server/models/auth.py`
|
|
- Define LoginRequest, LoginResponse models
|
|
- Add SetupRequest, AuthStatus models
|
|
- Include session management models
|
|
|
|
#### [] Create authentication service
|
|
|
|
- Create `src/server/services/auth_service.py`
|
|
- Implement master password setup/validation
|
|
- Add session management with JWT tokens
|
|
- Include failed attempt tracking and lockout
|
|
- Add password strength validation
|
|
|
|
#### [] Implement authentication API endpoints
|
|
|
|
- Create `src/server/api/auth.py`
|
|
- Add POST `/api/auth/setup` - initial setup
|
|
- Add POST `/api/auth/login` - login endpoint
|
|
- Add POST `/api/auth/logout` - logout endpoint
|
|
- Add GET `/api/auth/status` - authentication status
|
|
|
|
#### [] Create authentication middleware
|
|
|
|
- Create `src/server/middleware/auth.py`
|
|
- Implement JWT token validation
|
|
- Add request authentication checking
|
|
- Include rate limiting for auth endpoints
|
|
|
|
### 3. Configuration Management
|
|
|
|
#### [] Implement configuration models
|
|
|
|
- Create `src/server/models/config.py`
|
|
- Define ConfigResponse, ConfigUpdate models
|
|
- Add SchedulerConfig, LoggingConfig models
|
|
- Include ValidationResult model
|
|
|
|
#### [] Create configuration service
|
|
|
|
- Create `src/server/services/config_service.py`
|
|
- Implement configuration loading/saving
|
|
- Add configuration validation
|
|
- Include backup/restore functionality
|
|
- Add scheduler configuration management
|
|
|
|
#### [] Implement configuration API endpoints
|
|
|
|
- Create `src/server/api/config.py`
|
|
- Add GET `/api/config` - get configuration
|
|
- Add PUT `/api/config` - update configuration
|
|
- Add POST `/api/config/validate` - validate config
|
|
- Add GET/POST `/api/config/backup` - backup management
|
|
|
|
### 4. Anime Management Integration
|
|
|
|
#### [] Implement anime models
|
|
|
|
- Create `src/server/models/anime.py`
|
|
- Define AnimeSeriesResponse, EpisodeInfo models
|
|
- Add SearchRequest, SearchResult models
|
|
- Include MissingEpisodeInfo model
|
|
|
|
#### [] Create anime service wrapper
|
|
|
|
- Create `src/server/services/anime_service.py`
|
|
- Wrap SeriesApp functionality for web layer
|
|
- Implement async wrappers for blocking operations
|
|
- Add caching for frequently accessed data
|
|
- Include error handling and logging
|
|
|
|
#### [] Implement anime API endpoints
|
|
|
|
- Create `src/server/api/anime.py`
|
|
- Add GET `/api/v1/anime` - list series with missing episodes
|
|
- Add POST `/api/v1/anime/rescan` - trigger rescan
|
|
- Add POST `/api/v1/anime/search` - search for new anime
|
|
- Add GET `/api/v1/anime/{id}` - get series details
|
|
|
|
### 5. Download Queue Management
|
|
|
|
#### [] Implement download queue models
|
|
|
|
- Create `src/server/models/download.py`
|
|
- Define DownloadItem, QueueStatus models
|
|
- Add DownloadProgress, QueueStats models
|
|
- Include DownloadRequest model
|
|
|
|
#### [] Create download queue service
|
|
|
|
- Create `src/server/services/download_service.py`
|
|
- Implement queue management (add, remove, reorder)
|
|
- Add download progress tracking
|
|
- Include queue persistence and recovery
|
|
- Add concurrent download management
|
|
|
|
#### [] Implement download API endpoints
|
|
|
|
- Create `src/server/api/download.py`
|
|
- Add GET `/api/queue/status` - get queue status
|
|
- Add POST `/api/queue/add` - add to queue
|
|
- Add DELETE `/api/queue/{id}` - remove from queue
|
|
- Add POST `/api/queue/start` - start downloads
|
|
- Add POST `/api/queue/stop` - stop downloads
|
|
|
|
### 6. WebSocket Real-time Updates
|
|
|
|
#### [] Implement WebSocket manager
|
|
|
|
- Create `src/server/services/websocket_service.py`
|
|
- Add connection management
|
|
- Implement broadcast functionality
|
|
- Include room-based messaging
|
|
- Add connection cleanup
|
|
|
|
#### [] Add real-time progress updates
|
|
|
|
- Create `src/server/services/progress_service.py`
|
|
- Implement download progress broadcasting
|
|
- Add scan progress updates
|
|
- Include queue status changes
|
|
- Add error notifications
|
|
|
|
#### [] Integrate WebSocket with core services
|
|
|
|
- Update download service to emit progress
|
|
- Add scan progress notifications
|
|
- Include queue change broadcasts
|
|
- Add error/completion notifications
|
|
|
|
### 7. Frontend Integration
|
|
|
|
#### [] Integrate existing HTML templates
|
|
|
|
- Review and integrate existing HTML templates in `src/server/web/templates/`
|
|
- Ensure templates work with FastAPI Jinja2 setup
|
|
- Update template paths and static file references if needed
|
|
- Maintain existing responsive layout and theme switching
|
|
|
|
#### [] Integrate existing JavaScript functionality
|
|
|
|
- Review existing JavaScript files in `src/server/web/static/js/`
|
|
- Update API endpoint URLs to match FastAPI routes
|
|
- Ensure WebSocket connections work with new backend
|
|
- Maintain existing functionality for app.js and queue.js
|
|
|
|
#### [] Integrate existing CSS styling
|
|
|
|
- Review and integrate existing CSS files in `src/server/web/static/css/`
|
|
- Ensure styling works with FastAPI static file serving
|
|
- Maintain existing responsive design and theme support
|
|
- Update any hardcoded paths if necessary
|
|
|
|
#### [] Update frontend-backend integration
|
|
|
|
- Ensure existing JavaScript calls match new API endpoints
|
|
- Update authentication flow to work with new auth system
|
|
- Verify WebSocket events match new service implementations
|
|
- Test all existing UI functionality with new backend
|
|
|
|
### 8. Core Logic Integration
|
|
|
|
#### [] Enhance SeriesApp for web integration
|
|
|
|
- Update `src/core/SeriesApp.py`
|
|
- Add async callback support
|
|
- Implement progress reporting
|
|
- Include better error handling
|
|
- Add cancellation support
|
|
|
|
#### [] Create progress callback system
|
|
|
|
- Add progress callback interface
|
|
- Implement scan progress reporting
|
|
- Add download progress tracking
|
|
- Include error/completion callbacks
|
|
|
|
#### [] Add configuration persistence
|
|
|
|
- Implement configuration file management
|
|
- Add settings validation
|
|
- Include backup/restore functionality
|
|
- Add migration support for config updates
|
|
|
|
### 9. Database Layer
|
|
|
|
#### [] Implement database models
|
|
|
|
- Create `src/server/database/models.py`
|
|
- Add SQLAlchemy models for anime series
|
|
- Implement download queue persistence
|
|
- Include user session storage
|
|
|
|
#### [] Create database service
|
|
|
|
- Create `src/server/database/service.py`
|
|
- Add CRUD operations for anime data
|
|
- Implement queue persistence
|
|
- Include database migration support
|
|
|
|
#### [] Add database initialization
|
|
|
|
- Create `src/server/database/init.py`
|
|
- Implement database setup
|
|
- Add initial data migration
|
|
- Include schema validation
|
|
|
|
### 10. Testing
|
|
|
|
#### [] Create unit tests for services
|
|
|
|
- Create `tests/unit/test_auth_service.py`
|
|
- Create `tests/unit/test_anime_service.py`
|
|
- Create `tests/unit/test_download_service.py`
|
|
- Create `tests/unit/test_config_service.py`
|
|
|
|
#### [] Create API endpoint tests
|
|
|
|
- Create `tests/api/test_auth_endpoints.py`
|
|
- Create `tests/api/test_anime_endpoints.py`
|
|
- Create `tests/api/test_download_endpoints.py`
|
|
- Create `tests/api/test_config_endpoints.py`
|
|
|
|
#### [] Create integration tests
|
|
|
|
- Create `tests/integration/test_download_flow.py`
|
|
- Create `tests/integration/test_auth_flow.py`
|
|
- Create `tests/integration/test_websocket.py`
|
|
|
|
#### [] Create frontend integration tests
|
|
|
|
- Create `tests/frontend/test_existing_ui_integration.py`
|
|
- Test existing JavaScript functionality with new backend
|
|
- Verify WebSocket connections and real-time updates
|
|
- Test authentication flow with existing frontend
|
|
|
|
### 11. Deployment and Configuration
|
|
|
|
#### [] Create Docker configuration
|
|
|
|
- Create `Dockerfile`
|
|
- Create `docker-compose.yml`
|
|
- Add environment configuration
|
|
- Include volume mappings for existing web assets
|
|
|
|
#### [] Create production configuration
|
|
|
|
- Create `src/server/config/production.py`
|
|
- Add environment variable handling
|
|
- Include security settings
|
|
- Add performance optimizations
|
|
|
|
#### [] Create startup scripts
|
|
|
|
- Create `scripts/start.sh`
|
|
- Create `scripts/setup.py`
|
|
- Add dependency installation
|
|
- Include database initialization
|
|
|
|
### 12. Documentation and Error Handling
|
|
|
|
#### [] Create API documentation
|
|
|
|
- Add OpenAPI/Swagger documentation
|
|
- Include endpoint descriptions
|
|
- Add request/response examples
|
|
- Include authentication details
|
|
|
|
#### [] Implement comprehensive error handling
|
|
|
|
- Create custom exception classes
|
|
- Add error logging and tracking
|
|
- Implement user-friendly error messages
|
|
- Include error recovery mechanisms
|
|
|
|
#### [] Create user documentation
|
|
|
|
- Create `docs/user_guide.md`
|
|
- Add installation instructions
|
|
- Include configuration guide
|
|
- Add troubleshooting section
|
|
|
|
## File Size Guidelines
|
|
|
|
- **Models**: Max 200 lines each
|
|
- **Services**: Max 450 lines each
|
|
- **API Endpoints**: Max 350 lines each
|
|
- **Templates**: Max 400 lines each
|
|
- **JavaScript**: Max 500 lines each
|
|
- **CSS**: Max 500 lines each
|
|
- **Tests**: Max 400 lines each
|
|
|
|
## Existing Frontend Assets
|
|
|
|
The following frontend assets already exist and should be integrated:
|
|
|
|
- **Templates**: Located in `src/server/web/templates/`
|
|
- **JavaScript**: Located in `src/server/web/static/js/` (app.js, queue.js, etc.)
|
|
- **CSS**: Located in `src/server/web/static/css/`
|
|
- **Static Assets**: Images and other assets in `src/server/web/static/`
|
|
|
|
When working with these files:
|
|
|
|
- Review existing functionality before making changes
|
|
- Maintain existing UI/UX patterns and design
|
|
- Update API calls to match new FastAPI endpoints
|
|
- Preserve existing WebSocket event handling
|
|
- Keep existing theme and responsive design features
|
|
|
|
## Quality Assurance
|
|
|
|
#### [] Code quality checks
|
|
|
|
- Run linting with flake8/pylint
|
|
- Check type hints with mypy
|
|
- Validate formatting with black
|
|
- Run security checks with bandit
|
|
|
|
#### [] Performance testing
|
|
|
|
- Load test API endpoints
|
|
- Test WebSocket connection limits
|
|
- Validate download performance
|
|
- Check memory usage patterns
|
|
|
|
#### [] Security validation
|
|
|
|
- Test authentication bypass attempts
|
|
- Validate input sanitization
|
|
- Check for injection vulnerabilities
|
|
- Test session management security
|
|
|
|
Each task should be implemented with proper error handling, logging, and type hints according to the project's coding standards.
|