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

```bash
# 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

---