Aniworld/docs/instructions.md

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

Additional Implementation Guidelines

Code Style and Standards

• Type Hints: Use comprehensive type annotations throughout all modules
• Docstrings: Follow PEP 257 for function and class documentation
• Error Handling: Implement custom exception classes with meaningful messages
• Logging: Use structured logging with appropriate log levels
• Security: Validate all inputs and sanitize outputs
• Performance: Use async/await patterns for I/O operations

📞 Escalation

If you encounter:

• Architecture issues requiring design decisions
• Tests that conflict with documented requirements
• Breaking changes needed
• Unclear requirements or expectations

Document the issue and escalate rather than guessing.

---

📚 Helpful Commands

# Run all tests
conda run -n AniWorld python -m pytest tests/ -v --tb=short

# Run specific test file
conda run -n AniWorld python -m pytest tests/unit/test_websocket_service.py -v

# Run specific test class
conda run -n AniWorld python -m pytest tests/unit/test_websocket_service.py::TestWebSocketService -v

# Run specific test
conda run -n AniWorld python -m pytest tests/unit/test_websocket_service.py::TestWebSocketService::test_broadcast_download_progress -v

# Run with extra verbosity
conda run -n AniWorld python -m pytest tests/ -vv

# Run with full traceback
conda run -n AniWorld python -m pytest tests/ -v --tb=long

# Run and stop at first failure
conda run -n AniWorld python -m pytest tests/ -v -x

# Run tests matching pattern
conda run -n AniWorld python -m pytest tests/ -v -k "auth"

# Show all print statements
conda run -n AniWorld python -m pytest tests/ -v -s

#Run app
conda run -n AniWorld python -m uvicorn src.server.fastapi_app:app --host 127.0.0.1 --port 8000 --reload

---

Implementation Notes

1. Incremental Development: Implement features incrementally, testing each component thoroughly before moving to the next
2. Code Review: Review all generated code for adherence to project standards
3. Documentation: Document all public APIs and complex logic
4. Testing: Maintain test coverage above 80% for all new code
5. Performance: Profile and optimize critical paths, especially download and streaming operations
6. Security: Regular security audits and dependency updates
7. Monitoring: Implement comprehensive monitoring and alerting
8. Maintenance: Plan for regular maintenance and updates

---

Task Completion Checklist

For each task completed:

• Implementation follows coding standards
• Unit tests written and passing
• Integration tests passing
• Documentation updated
• Error handling implemented
• Logging added
• Security considerations addressed
• Performance validated
• Code reviewed
• Task marked as complete in instructions.md
• Infrastructure.md updated and other docs
• Changes committed to git; keep your messages in git short and clear
• Take the next task

---

TODO List:

🎯 Priority: NFO FSK Rating Implementation ✅ COMPLETED

Task: Implement German FSK Rating Support in NFO Files

Status: COMPLETED ✅

Implementation Summary:

All requirements have been successfully implemented and tested:

1. ✅ TMDB API Integration: Added get_tv_show_content_ratings() method to TMDBClient
2. ✅ Data Model: Added optional fsk field to TVShowNFO model
3. ✅ FSK Extraction: Implemented _extract_fsk_rating() method in NFOService with comprehensive mapping:
   • Maps TMDB German ratings (0, 6, 12, 16, 18) to FSK format
   • Handles already formatted FSK strings
   • Supports partial matches (e.g., "Ab 16 Jahren" → "FSK 16")
   • Fallback to None when German rating unavailable
4. ✅ XML Generation: Updated generate_tvshow_nfo() to prefer FSK over MPAA when available
5. ✅ Configuration: Added nfo_prefer_fsk_rating setting (default: True)
6. ✅ Comprehensive Testing: Added 31 new tests across test_nfo_service.py and test_nfo_generator.py
   • All 112 NFO-related tests passing
   • Test coverage includes FSK extraction, XML generation, edge cases, and integration

Files Modified:

• src/core/entities/nfo_models.py - Added fsk field
• src/core/services/nfo_service.py - Added FSK extraction and TMDB API call
• src/core/services/tmdb_client.py - Added content ratings endpoint
• src/core/utils/nfo_generator.py - Updated XML generation to prefer FSK
• src/config/settings.py - Added nfo_prefer_fsk_rating setting

Files Created:

• tests/unit/test_nfo_service.py - 23 comprehensive unit tests

Files Updated:

• tests/unit/test_nfo_generator.py - Added 5 FSK-specific tests

Acceptance Criteria Met:

• ✅ NFO files contain FSK rating when available from TMDB
• ✅ Fallback to MPAA rating if FSK not available
• ✅ Configuration setting to prefer FSK over MPAA
• ✅ Unit tests cover all FSK values and fallback scenarios
• ✅ Existing NFO functionality remains unchanged
• ✅ Documentation updated with FSK support details

---

🧪 Priority: Comprehensive NFO and Image Download Tests

Task: Add Comprehensive Tests for NFO Creation and Media Downloads

Expand test coverage for NFO creation, updates, and media file (poster/logo/fanart) downloads.

Requirements:

1. Unit Tests for NFO Service (tests/unit/test_nfo_service.py):

   • Test auto-create NFO before download with all settings combinations
   • Test NFO update on scan (enabled/disabled)
   • Test poster download (enabled/disabled, various sizes)
   • Test logo download (enabled/disabled, English/local languages)
   • Test fanart download (enabled/disabled, various sizes)
   • Test concurrent media downloads
   • Test media download failures and retries
   • Test NFO creation without media downloads
   • Test image size configurations (original, w780, w500, w342)
   • Mock TMDB API responses for all scenarios

2. Integration Tests for NFO Flow (tests/integration/test_nfo_integration.py):

   • Test complete NFO creation flow before episode download
   • Test NFO update during series scan
   • Test media file existence after NFO creation
   • Test media file updates when NFO is updated
   • Test NFO creation failure doesn't block download
   • Test NFO and media files in correct folder structure
   • Test cleanup of orphaned media files

3. API Endpoint Tests (tests/api/test_nfo_endpoints.py):

   • Test /api/nfo/series/{series_id}/check endpoint
   • Test /api/nfo/series/{series_id}/create endpoint
   • Test /api/nfo/series/{series_id}/update endpoint
   • Test /api/nfo/series/{series_id}/media endpoint (media files status)
   • Test /api/nfo/series/{series_id}/media/download endpoint
   • Test error responses (404, 400, 500)
   • Test authentication and authorization

4. Performance Tests (tests/performance/test_nfo_performance.py):

   • Test NFO creation performance (< 2 seconds)
   • Test concurrent NFO creation for multiple series
   • Test media download performance for large images
   • Test bulk NFO scan performance (100+ series)

Files to create/modify:

• tests/unit/test_nfo_service.py - Comprehensive unit tests
• tests/unit/test_nfo_generator.py - XML generation tests
• tests/integration/test_nfo_integration.py - End-to-end NFO tests
• tests/integration/test_nfo_media_download.py - Media download integration
• tests/api/test_nfo_endpoints.py - API endpoint tests
• tests/performance/test_nfo_performance.py - Performance benchmarks

Acceptance Criteria:

• Test coverage for NFO service > 90%
• All media download scenarios tested
• Integration tests verify file system state
• API tests cover all endpoints and error cases
• Performance tests validate acceptable speeds
• All tests pass without mocking filesystem
• Mock TMDB API calls appropriately
• Test documentation includes setup and teardown details

Test Data Requirements:

• Mock TMDB responses for various anime series
• Sample poster/logo/fanart images for testing
• Test fixtures for NFO XML validation
• Edge cases: missing images, API failures, timeouts

---