lukas.pupkalipinski/Aniworld
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Aniworld/instructions.md

500 lines
15 KiB
Markdown
Raw Blame History

# 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
```
---
## Final 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
- [ ] Changes committed to git; keep your messages in git short and clear
- [ ] Take the next task
---
### Prerequisites
1. Server is running: `conda run -n AniWorld python -m uvicorn src.server.fastapi_app:app --host 127.0.0.1 --port 8000 --reload`
2. Password: `Hallo123!`
3. Login via browser at `http://127.0.0.1:8000/login`
### Notes
- This is a simplification that removes complexity while maintaining core functionality
- Improves user experience with explicit manual control
- Easier to understand, test, and maintain
- Good foundation for future enhancements if needed
---
# 🎯 CRITICAL: Series Identifier Standardization
## Overview
**Problem:** The codebase currently uses multiple identifiers inconsistently:
- `key` (provider identifier, e.g., "attack-on-titan")
- `folder` (filesystem folder name, e.g., "Attack on Titan (2013)")
- `serie_id` (sometimes key, sometimes folder)
- `serie_folder` (filesystem path used as identifier)
**Solution:** Standardize on `key` as the single source of truth for all series identification.
**Benefits:**
- Single, consistent identifier throughout the codebase
- `key` is unique, provider-assigned, URL-safe
- `folder` becomes metadata only (not used for lookups)
- Clearer separation of concerns
- Easier to maintain and debug
**Scope:** This affects core logic, services, API endpoints, frontend, WebSocket events, and tests.
---
## Task Series: Identifier Standardization
### Phase 4: API Layer ✅ (Completed November 28, 2025)
All API layer tasks completed.
---
### Phase 5: Frontend ✅ (Completed November 28, 2025)
### Phase 6: Database Layer ✅ (Completed November 28, 2025)
All database layer tasks completed:
- Task 6.1: Verified `AnimeSeries.key` is unique and indexed, `folder` is metadata only, updated docstrings
- Task 6.2: Verified all service methods use `key` for lookups, no folder-based identification
---
### Phase 7: Testing and Validation ✅ **Completed November 28, 2025**
#### Task 7.1: Update All Test Fixtures to Use Key ✅
**Files:** All test files in [`tests/`](tests/)
**Objective:** Ensure all test fixtures and mocks use `key` consistently.
**Steps:**
1. Search for all test files using `folder` as identifier
2. Update `FakeSerie` class in [`tests/api/test_anime_endpoints.py`](tests/api/test_anime_endpoints.py):
- Ensure `key` is the primary identifier
3. Update all test fixtures to use `key`
4. Update mock data to use realistic `key` values
5. Ensure tests verify both `key` and `folder` are present but only `key` is used for operations
**Success Criteria:**
- [x] All test fixtures use `key` as identifier
- [x] Tests verify `key` is used for operations
- [x] Tests verify `folder` is present as metadata
- [x] All tests pass (1006 tests passing)
**Test Command:**
```bash
conda run -n AniWorld python -m pytest tests/ -v
```
**Completion Notes:**
- Updated `FakeSerie` and `FakeSeriesApp` in `test_anime_endpoints.py` with realistic keys
- Updated fixtures in `test_websocket_integration.py` (6+ fixtures)
- Updated fixtures in `test_download_progress_integration.py` (5 fixtures)
- Updated fixtures in `test_download_progress_websocket.py` (9 fixtures)
- Updated fixtures in `test_download_models.py` (10+ fixtures)
- All fixtures now use URL-safe, lowercase, hyphenated key format
---
#### Task 7.2: Add Integration Tests for Identifier Consistency ✅
**File:** Created [`tests/integration/test_identifier_consistency.py`](tests/integration/test_identifier_consistency.py)
**Objective:** Create integration tests to verify `key` is used consistently across all layers.
**Steps:**
1. Create [`tests/integration/test_identifier_consistency.py`](tests/integration/test_identifier_consistency.py)
2. Write test to verify:
- API endpoint returns `key` as identifier
- Download service uses `key`
- Database lookups use `key`
- WebSocket events include `key`
3. Write test to verify `folder` is never used for lookups
4. Write test for end-to-end flow using `key`
**Success Criteria:**
- [x] Integration test file created
- [x] Tests verify `key` usage across all layers
- [x] Tests verify `folder` not used for identification
- [x] All integration tests pass (10 tests)
**Completion Notes:**
- Created comprehensive test file with 10 tests:
- `TestAPIIdentifierConsistency`: 2 tests for API response validation
- `TestServiceIdentifierConsistency`: 2 tests for download service key usage
- `TestWebSocketIdentifierConsistency`: 2 tests for WebSocket events
- `TestIdentifierValidation`: 2 tests for model validation
- `TestEndToEndIdentifierFlow`: 2 tests for full flow verification
- Tests use UUID suffixes for isolation to prevent state leakage
**Test Command:**
```bash
conda run -n AniWorld python -m pytest tests/integration/test_identifier_consistency.py -v
```
---
### Phase 8: Documentation and Cleanup
#### Task 8.1: Update Infrastructure Documentation
**File:** [`infrastructure.md`](infrastructure.md)
**Objective:** Document the identifier standardization in infrastructure documentation.
**Steps:**
1. Open [`infrastructure.md`](infrastructure.md)
2. Add section explaining identifier usage:
- `key`: Unique series identifier (provider-assigned)
- `folder`: Filesystem folder name (metadata only)
- `id`: Database primary key (internal use)
3. Update all API documentation to show `key` as identifier
4. Update data model documentation
5. Add migration notes if needed
**Success Criteria:**
- [ ] Documentation clearly explains identifier usage
- [ ] All API examples use `key`
- [ ] Data model section updated
- [ ] Migration notes added if applicable
---
#### Task 8.2: Update README and Developer Documentation
**Files:** [`README.md`](README.md), [`docs/`](docs/)
**Objective:** Update all developer-facing documentation.
**Steps:**
1. Update main README to explain identifier usage
2. Update any developer guides to use `key`
3. Add note about backward compatibility with `folder`
4. Update code examples to use `key`
**Success Criteria:**
- [ ] README updated
- [ ] Developer guides updated
- [ ] Code examples use `key`
- [ ] Backward compatibility documented
---
#### Task 8.3: Add Deprecation Warnings for Folder-Based Lookups
**Files:** Various service and API files
**Objective:** Add deprecation warnings where `folder` is still accepted for backward compatibility.
**Steps:**
1. Identify all methods that accept `folder` for lookups
2. Add deprecation warnings using Python's `warnings` module
3. Update docstrings to indicate deprecation
4. Plan removal timeline (e.g., next major version)
**Success Criteria:**
- [ ] Deprecation warnings added
- [ ] Docstrings indicate deprecation
- [ ] Removal timeline documented
- [ ] Tests updated to suppress warnings
---
### Phase 9: Final Validation
#### Task 9.1: Run Full Test Suite
**Objective:** Verify all changes work together correctly.
**Steps:**
1. Run complete test suite:
```bash
conda run -n AniWorld python -m pytest tests/ -v --tb=short
```
2. Fix any failing tests
3. Verify test coverage is maintained
4. Run integration tests
5. Run manual UI tests
**Success Criteria:**
- [ ] All unit tests pass
- [ ] All integration tests pass
- [ ] All API tests pass
- [ ] Test coverage >= 80%
- [ ] Manual UI testing successful
---
#### Task 9.2: Manual End-to-End Testing
**Objective:** Manually verify all features work with the new identifier system.
**Steps:**
1. Start server: `conda run -n AniWorld python -m uvicorn src.server.fastapi_app:app --host 127.0.0.1 --port 8000 --reload`
2. Login to web interface
3. Test search functionality (verify results show `key`)
4. Test adding new series (verify uses `key`)
5. Test downloading episodes (verify uses `key`)
6. Test WebSocket events (verify events include `key`)
7. Verify database contains correct `key` values
8. Test rescan functionality
**Success Criteria:**
- [ ] Search works correctly
- [ ] Adding series works
- [ ] Downloads work correctly
- [ ] WebSocket events work
- [ ] Database entries correct
- [ ] Rescan functionality works
---
#### Task 9.3: Performance and Load Testing
**Objective:** Ensure identifier changes don't impact performance.
**Steps:**
1. Run performance tests on key operations:
- Series lookup by `key`
- Database queries using `key`
- API response times
2. Compare with baseline if available
3. Identify any performance regressions
4. Optimize if needed
**Success Criteria:**
- [ ] No significant performance regression
- [ ] Lookup by `key` is fast
- [ ] Database queries optimized
- [ ] API response times acceptable
---
### Phase 10: Deployment
#### Task 10.1: Create Migration Script
**Objective:** Create script to migrate existing data if needed.
**Steps:**
1. Create [`scripts/migrate_identifiers.py`](scripts/migrate_identifiers.py)
2. Script should:
- Check all series have valid `key` values
- Update any references that incorrectly use `folder`
- Validate database integrity
- Create backup before migration
3. Add rollback capability
4. Test migration on test data
**Success Criteria:**
- [ ] Migration script created
- [ ] Script validates data
- [ ] Backup functionality works
- [ ] Rollback capability tested
- [ ] Migration tested on test data
---
#### Task 10.2: Update Deployment Documentation
**File:** Update deployment section in [`instructions.md`](instructions.md)
**Objective:** Document deployment steps for identifier changes.
**Steps:**
1. Add pre-deployment checklist
2. Document migration steps
3. Add rollback procedure
4. Document verification steps
5. Add troubleshooting guide
**Success Criteria:**
- [ ] Deployment steps documented
- [ ] Migration procedure clear
- [ ] Rollback procedure documented
- [ ] Verification steps listed
- [ ] Troubleshooting guide added
---
#### Task 10.3: Deploy to Production
**Objective:** Deploy changes to production environment.
**Steps:**
1. Create deployment tag: `v2.0.0-identifier-standardization`
2. Backup production database
3. Run migration script
4. Deploy new code
5. Monitor logs for errors
6. Verify production functionality
7. Monitor for 24 hours
**Success Criteria:**
- [ ] Deployment tag created
- [ ] Database backed up
- [ ] Migration successful
- [ ] Code deployed
- [ ] No errors in logs
- [ ] All features working
- [ ] 24-hour monitoring completed
---
## Task Tracking
### Completion Status
- [x] Phase 1: Core Models and Data Layer ✅
- [x] Phase 2: Core Application Layer ✅
- [x] Phase 3: Service Layer ✅
- [x] Phase 4: API Layer ✅ **Completed November 28, 2025**
- [x] Phase 5: Frontend ✅ **Completed November 28, 2025**
- [x] Task 5.1: Update Frontend JavaScript
- [x] Task 5.2: Update WebSocket Events
- [x] Task 5.3: Update Additional Frontend JavaScript Files
- [x] Task 5.4: Update HTML Templates
- [x] Phase 6: Database Layer ✅ **Completed November 28, 2025**
- [x] Task 6.1: Verify Database Models
- [x] Task 6.2: Update Database Services
- [x] Phase 7: Testing and Validation ✅ **Completed November 28, 2025**
- [x] Task 7.1: Update Test Fixtures - Updated all test fixtures and mocks to use `key` consistently with realistic key values (URL-safe, lowercase, hyphenated)
- [x] Task 7.2: Add Integration Tests - Created `tests/integration/test_identifier_consistency.py` with 10 tests verifying `key` usage across all layers
- [ ] Phase 8: Documentation and Cleanup
- [ ] Task 8.1: Update Infrastructure Documentation
- [ ] Task 8.2: Update README
- [ ] Task 8.3: Add Deprecation Warnings
- [ ] Phase 9: Final Validation
Reference in New Issue View Git Blame Copy Permalink