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 ✅ COMPLETED

**Task: Add Comprehensive Tests for NFO Creation and Media Downloads**

**Status: COMPLETED** ✅

**Implementation Summary:**

Significantly expanded test coverage for NFO functionality with comprehensive unit and integration tests:

1. ✅ **Unit Tests Expanded** ([test_nfo_service.py](tests/unit/test_nfo_service.py)):
   - Added 13 tests for media file downloads (poster, logo, fanart)
   - Tests for various image sizes and configurations
   - Tests for download failures and edge cases
   - Configuration testing for NFO service settings
   - **Total: 44 tests** in test_nfo_service.py

2. ✅ **Integration Tests Created** ([test_nfo_integration.py](tests/integration/test_nfo_integration.py)):
   - Complete NFO creation workflow with all media files
   - NFO creation without media downloads
   - Correct folder structure verification
   - NFO update workflow with media re-download
   - Error handling and recovery
   - Concurrent NFO operations (batch creation)
   - Data integrity validation
   - **Total: 10 comprehensive integration tests**

3. ✅ **API Endpoint Tests**: Existing test_nfo_endpoints.py already covers all NFO API endpoints

**Files Modified:**
- `tests/unit/test_nfo_service.py` - Added 23 new tests for media downloads and configuration

**Files Created:**
- `tests/integration/test_nfo_integration.py` - 10 comprehensive integration tests

**Test Results:**
- ✅ **44 tests passing** in test_nfo_service.py (unit)
- ✅ **10 tests passing** in test_nfo_integration.py (integration)
- ✅ **112 total NFO-related unit tests passing**
- ✅ **All tests verify**:
  - FSK rating extraction and mapping
  - Media file download scenarios
  - NFO creation and update workflows
  - Error handling and edge cases
  - Concurrent operations
  - Data integrity

**Acceptance Criteria Met:**
- ✅ Comprehensive unit tests for all media download scenarios
- ✅ Integration tests verify complete workflows
- ✅ Tests validate file system state after operations
- ✅ Edge cases and error scenarios covered
- ✅ Concurrent operations tested
- ✅ All tests use proper mocking for TMDB API
- ✅ Test fixtures provide realistic test data

**Test Coverage Highlights:**
- Media download with all combinations (poster/logo/fanart)
- Different image sizes (original, w500, w780, w342)
- Missing media scenarios
- Concurrent NFO creation
- NFO update workflows
- FSK rating preservation
- Complete metadata integrity

---