# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Phase 7] - 2025-12-24

### Testing

#### Added
- **Comprehensive Test Coverage Improvements**
  - Added 30+ new test files across all apps
  - API endpoint tests with authentication, error handling, pagination, and response format validation
  - E2E tests for FSM workflows (parks, rides, moderation)
  - Integration tests for FSM transition workflows
  - Unit tests for managers, serializers, and services
  - Accessibility tests for WCAG 2.1 AA compliance
  - Form validation tests for all major forms

#### Test Files Added
- `backend/tests/api/` - API endpoint tests (8 files)
- `backend/tests/e2e/` - End-to-end FSM workflow tests (3 files)
- `backend/tests/integration/` - Integration tests (1 file)
- `backend/tests/managers/` - Manager tests (2 files)
- `backend/tests/serializers/` - Serializer tests (3 files)
- `backend/tests/services/` - Service layer tests (3 files)
- `backend/tests/forms/` - Form validation tests (5 files)
- `backend/tests/accessibility/` - WCAG compliance tests (1 file)
- `backend/apps/*/tests/` - App-specific tests (7 files)

#### Coverage Improvements
- Increased test coverage for models, views, and services
- Added tests for edge cases and error conditions
- Improved FSM transition testing with permission checks
- Added query optimization tests

### Technical Details

This phase focused on achieving comprehensive test coverage to ensure code quality and prevent regressions. Tests cover:
- All API endpoints with various authentication scenarios
- FSM state transitions with permission validation
- Form validation logic with edge cases
- Manager methods and custom QuerySets
- Service layer business logic
- Accessibility compliance for interactive components

**Testing Infrastructure**:
- pytest with Django plugin
- Factory Boy for test data generation
- Coverage.py for coverage tracking
- Playwright for E2E tests

### Files Modified
- `backend/pyproject.toml` - Updated test dependencies and coverage configuration
- `backend/tests/conftest.py` - Enhanced test fixtures and utilities

---

## [Phase 6] - 2025-12-24

### Forms & Validation

#### Enhanced
- **Form Validation Coverage**
  - Added custom `clean_*` methods for field-level validation
  - Improved error messages for better user experience
  - Enhanced form widgets (date pickers, rich text editors)
  - Standardized ModelForm field definitions

#### Forms Enhanced
- `backend/apps/parks/forms/base.py` - Park creation/update forms
- `backend/apps/parks/forms/review_forms.py` - Park review forms
- `backend/apps/parks/forms/area_forms.py` - Park area forms
- `backend/apps/rides/forms/base.py` - Ride creation/update forms
- `backend/apps/rides/forms/review_forms.py` - Ride review forms
- `backend/apps/rides/forms/company_forms.py` - Company forms
- `backend/apps/rides/forms/search.py` - Ride search forms
- `backend/apps/core/forms/search.py` - Core search forms
- `backend/apps/core/forms/htmx_forms.py` - HTMX-specific form patterns

#### Tests Added
- `backend/tests/forms/test_area_forms.py` - Area form validation tests
- `backend/tests/forms/test_park_forms.py` - Park form validation tests
- `backend/tests/forms/test_ride_forms.py` - Ride form validation tests
- `backend/tests/forms/test_review_forms.py` - Review form validation tests
- `backend/tests/forms/test_company_forms.py` - Company form validation tests

### Technical Details

This phase improved form validation coverage across the application:
1. **Field-Level Validation**: Custom `clean_*` methods for complex validation logic
2. **User-Friendly Errors**: Clear, actionable error messages
3. **Widget Improvements**: Better UX with appropriate input widgets
4. **HTMX Integration**: Forms work seamlessly with HTMX partial updates
5. **Test Coverage**: Comprehensive tests for all validation scenarios

**Validation Patterns**:
- Date range validation (opening/closing dates)
- Coordinate validation (latitude/longitude bounds)
- Slug uniqueness validation
- Cross-field validation (e.g., closing date must be after opening date)
- File upload validation (size, type, dimensions)

---

## [Phase 5] - 2025-12-24

### Admin Interface

#### Enhanced
- **Django Admin Completeness**
  - Added comprehensive `list_display` with key fields
  - Implemented `search_fields` for text search
  - Added `list_filter` for status, category, and date filtering
  - Organized detail views with `fieldsets`
  - Added `readonly_fields` for computed properties and timestamps
  - Implemented custom admin actions (bulk approve, bulk reject, etc.)

#### Admin Files Enhanced
- `backend/apps/parks/admin.py` - Park, Area, Company, Review admin
- `backend/apps/rides/admin.py` - Ride, Manufacturer, Review admin
- `backend/apps/accounts/admin.py` - User, Profile admin
- `backend/apps/moderation/admin.py` - Submission, Report admin
- `backend/apps/core/admin.py` - Base admin classes and mixins

#### Custom Admin Actions
- Bulk approve/reject for moderation workflows
- Bulk status changes for parks and rides
- Export to CSV for reporting
- Cache invalidation for modified entities

### Technical Details

This phase completed the Django admin interface to provide a powerful content management system:
1. **List Views**: Optimized with select_related/prefetch_related
2. **Search**: Full-text search on name, description, and location fields
3. **Filters**: Status, category, date range, and custom filters
4. **Detail Views**: Organized with logical fieldsets
5. **Actions**: Bulk operations for efficient moderation

**Admin Patterns**:
- Inherited from `BaseModelAdmin` for consistency
- Used `readonly_fields` for computed properties
- Implemented `get_queryset()` optimization
- Added inline admin for related objects

---

## [Phase 4] - 2025-12-24

### Models & Database

#### Enhanced
- **Model Completeness & Consistency**
  - Added/improved `__str__` methods for human-readable representations
  - Standardized `Meta` classes with `ordering`, `verbose_name`, `verbose_name_plural`
  - Added comprehensive `help_text` on all fields
  - Verified database indexes on foreign keys and frequently queried fields
  - Added model constraints (CheckConstraint, UniqueConstraint)

#### Model Files Enhanced
- `backend/apps/parks/models/parks.py` - Park model
- `backend/apps/parks/models/companies.py` - Company, Operator models
- `backend/apps/parks/models/areas.py` - ParkArea model
- `backend/apps/parks/models/media.py` - ParkPhoto model
- `backend/apps/parks/models/reviews.py` - ParkReview model
- `backend/apps/parks/models/location.py` - ParkLocation model
- `backend/apps/rides/models/rides.py` - Ride model
- `backend/apps/rides/models/company.py` - Manufacturer, Designer models
- `backend/apps/rides/models/rankings.py` - RideRanking model
- `backend/apps/rides/models/media.py` - RidePhoto model
- `backend/apps/rides/models/reviews.py` - RideReview model
- `backend/apps/rides/models/location.py` - RideLocation model
- `backend/apps/accounts/models.py` - User, Profile models
- `backend/apps/moderation/models.py` - Submission, Report models
- `backend/apps/core/models.py` - Base models and mixins

#### Database Improvements
- Added indexes for performance optimization
- Implemented constraints for data integrity
- Standardized field naming conventions
- Improved model documentation

### Technical Details

This phase improved model quality and consistency:
1. **String Representations**: All models have meaningful `__str__` methods
2. **Metadata**: Complete Meta classes with ordering and verbose names
3. **Field Documentation**: Every field has descriptive help_text
4. **Database Optimization**: Proper indexes on foreign keys and search fields
5. **Data Integrity**: Constraints enforce business rules at database level

**Model Patterns**:
- Used `TextChoices` for status and category fields
- Implemented `db_index=True` on frequently queried fields
- Added `CheckConstraint` for value ranges (e.g., ratings 1-5)
- Used `UniqueConstraint` for compound uniqueness

---

## [Phase 3] - 2025-12-24

### Logging & Observability

#### Standardized
- **Logging Pattern Consistency**
  - Added `logger = logging.getLogger(__name__)` to all view, service, and middleware files
  - Implemented centralized logging utilities from `apps.core.logging`
  - Standardized log levels (debug, info, warning, error)
  - Added structured logging with context

#### Files Enhanced with Logging
- `backend/apps/parks/views.py` - Park views
- `backend/apps/rides/views.py` - Ride views
- `backend/apps/accounts/views.py` - Account views
- `backend/apps/moderation/views.py` - Moderation views
- `backend/apps/accounts/services.py` - Account services
- `backend/apps/parks/signals.py` - Park signals
- `backend/apps/rides/signals.py` - Ride signals
- `backend/apps/moderation/signals.py` - Moderation signals
- `backend/apps/rides/tasks.py` - Celery tasks
- `backend/apps/parks/apps.py` - App configuration
- `backend/apps/rides/apps.py` - App configuration
- `backend/apps/moderation/apps.py` - App configuration

#### Logging Utilities
- `log_exception()` - Exception logging with full context
- `log_business_event()` - Business operation logging (FSM transitions, user actions)
- `log_security_event()` - Security event logging (authentication, authorization)

### Technical Details

This phase standardized logging across the application for better observability:
1. **Consistent Logger Initialization**: Every module uses `logging.getLogger(__name__)`
2. **Centralized Utilities**: Structured logging functions in `apps.core.logging`
3. **Contextual Logging**: All logs include relevant context (user, request, operation)
4. **Security Logging**: Dedicated logging for security events
5. **Performance Logging**: Query performance and cache hit/miss tracking

**Logging Patterns**:
- Exception handlers use `log_exception()` with context
- FSM transitions use `log_business_event()`
- Authentication events use `log_security_event()`
- Never log sensitive data (passwords, tokens, PII)

**Benefits**:
- Easier debugging with consistent log format
- Better production monitoring with structured logs
- Security audit trail for compliance
- Performance insights from cache and query logs

---

## [Phase 15] - 2025-12-23

### Documentation

#### Added
- **Future Work Documentation**
  - Created `docs/FUTURE_WORK.md` to track deferred features
  - Documented 11 TODO items with detailed implementation specifications
  - Added priority levels (P0-P3) and effort estimates
  - Included code examples and architectural guidance

#### Implemented
- **Cache Statistics Tracking (THRILLWIKI-109)**
  - Added `get_cache_statistics()` method to `CacheMonitor` class
  - Implemented real-time cache hit/miss tracking in `MapStatsAPIView`
  - Returns Redis statistics when available, with graceful fallback
  - Removed placeholder TODO comments

- **Photo Upload Counting (THRILLWIKI-105)**
  - Implemented photo counting in user statistics endpoint
  - Queries `ParkPhoto` and `RidePhoto` models for accurate counts
  - Removed placeholder TODO comment

- **Admin Permission Checks (THRILLWIKI-103)**
  - Verified existing admin permission checks in map cache endpoints
  - Removed outdated TODO comments (checks were already implemented)

#### Enhanced
- **TODO Comment Cleanup**
  - Updated all TODO comments to reference `FUTURE_WORK.md`
  - Added THRILLWIKI issue numbers for traceability
  - Improved inline documentation with implementation context

### Technical Details

This phase focused on addressing technical debt by:
1. Documenting deferred features with actionable specifications
2. Implementing quick wins that improve observability
3. Cleaning up TODO comments to reduce confusion

**Features Documented for Future Implementation**:
- Map clustering algorithm (THRILLWIKI-106)
- Nearby locations feature (THRILLWIKI-107)
- Search relevance scoring (THRILLWIKI-108)
- Full user statistics tracking (THRILLWIKI-104)
- Geocoding service integration (THRILLWIKI-101)
- ClamAV malware scanning (THRILLWIKI-110)
- Sample data creation command (THRILLWIKI-111)

**Quick Wins Implemented**:
- Cache statistics tracking for monitoring
- Photo upload counting for user profiles
- Verified admin permission checks

### Files Modified
- `backend/apps/api/v1/maps/views.py` - Cache statistics, updated TODO comments
- `backend/apps/api/v1/accounts/views.py` - Photo counting, updated TODO comments
- `backend/apps/api/v1/serializers/maps.py` - Updated TODO comments
- `backend/apps/core/services/location_adapters.py` - Updated TODO comments
- `backend/apps/core/services/enhanced_cache_service.py` - Added `get_cache_statistics()` method
- `backend/apps/core/utils/file_scanner.py` - Updated TODO comments
- `backend/apps/core/views/map_views.py` - Removed outdated TODO comments
- `backend/apps/parks/management/commands/create_sample_data.py` - Updated TODO comments
- `docs/architecture/README.md` - Added reference to FUTURE_WORK.md

### Files Created
- `docs/FUTURE_WORK.md` - Centralized future work documentation

---

## [Phase 14] - 2025-12-23

### Documentation

#### Fixed
- Corrected architectural documentation from Vue.js SPA to Django + HTMX monolith
- Updated main README to accurately reflect technology stack (Django 5.2.8+, HTMX 1.20.0+, Alpine.js)
- Fixed deployment guide to remove frontend build steps (no separate frontend build process)
- Corrected environment setup instructions for Django + HTMX architecture
- Updated project structure diagrams to show Django monolith with HTMX templates

#### Added
- **Architecture Decision Records (ADRs)**
  - ADR-001: Django + HTMX Architecture Decision
  - ADR-002: Hybrid API Design Pattern
  - ADR-003: State Machine Pattern for entity status management
  - ADR-004: Caching Strategy with Redis multi-layer caching
  - ADR-005: Authentication Approach (JWT + Session + Social Auth)
  - ADR-006: Media Handling with Cloudflare Images
- **New Documentation Files**
  - `docs/SETUP_GUIDE.md` - Comprehensive setup instructions with troubleshooting
  - `docs/HEALTH_CHECKS.md` - Health check endpoint documentation
  - `docs/PRODUCTION_CHECKLIST.md` - Deployment verification checklist
  - `docs/architecture/README.md` - ADR index and template
- **Environment Configuration**
  - Complete environment variable reference in `docs/configuration/environment-variables.md`
  - Updated `.env.example` with comprehensive documentation

#### Enhanced
- Backend README with HTMX patterns and hybrid API/HTML endpoint documentation
- Deployment guide with Docker, nginx, and CI/CD pipeline configurations
- Production settings documentation with inline comments
- API documentation structure and endpoint reference

#### Documentation Structure
```
docs/
├── README.md                           # Updated - Django + HTMX architecture
├── SETUP_GUIDE.md                      # New - Development setup
├── HEALTH_CHECKS.md                    # New - Monitoring endpoints
├── PRODUCTION_CHECKLIST.md             # New - Deployment checklist
├── THRILLWIKI_API_DOCUMENTATION.md     # Existing - API reference
├── htmx-patterns.md                    # Existing - HTMX conventions
├── architecture/                       # New - ADRs
│   ├── README.md                       # ADR index
│   ├── adr-001-django-htmx-architecture.md
│   ├── adr-002-hybrid-api-design.md
│   ├── adr-003-state-machine-pattern.md
│   ├── adr-004-caching-strategy.md
│   ├── adr-005-authentication-approach.md
│   └── adr-006-media-handling-cloudflare.md
└── configuration/
    └── environment-variables.md        # Existing - Complete reference
```

### Technical Details

This phase focused on documentation-only changes to align all project documentation with the actual Django + HTMX architecture. No code changes were made.

**Key Corrections:**
- The project uses Django templates with HTMX for interactivity, not a Vue.js SPA
- There is no separate frontend build process - static files are served by Django
- The API serves both JSON (for mobile/integrations) and HTML (for HTMX partials)
- Authentication uses JWT for API access and sessions for web browsing

---

## [Unreleased] - 2025-12-23

### Security

- **CRITICAL:** Updated Django from 5.0.x to 5.2.8+ to address CVE-2025-64459 (SQL injection, CVSS 9.1) and related vulnerabilities
- **HIGH:** Updated djangorestframework from 3.14.x to 3.15.2+ to address CVE-2024-21520 (XSS in break_long_headers filter)
- **MEDIUM:** Updated Pillow from 10.2.0 to 10.4.0+ (upper bound <11.2) to address CVE-2024-28219 (buffer overflow)
- Added cryptography>=44.0.0 for django-allauth JWT support

### Changed

- Standardized Python version requirement to 3.13+ across all configuration files
- Consolidated pyproject.toml files (root workspace + backend)
- Implemented consistent version pinning strategy using >= operators with minimum secure versions
- Updated CI/CD pipeline to use UV package manager instead of requirements.txt
- Moved linting and dev tools to proper dependency groups

### Package Updates

#### Core Django Ecosystem
- Django: 5.0.x → 5.2.8+
- djangorestframework: 3.14.x → 3.15.2+
- django-cors-headers: 4.3.1 → 4.6.0+
- django-filter: 23.5 → 24.3+
- drf-spectacular: 0.27.0 → 0.28.0+
- django-htmx: 1.17.2 → 1.20.0+
- whitenoise: 6.6.0 → 6.8.0+

#### Authentication
- django-allauth: 0.60.1 → 65.3.0+
- djangorestframework-simplejwt: maintained at 5.5.1+

#### Task Queue & Caching
- celery: maintained at 5.5.3+ (<6)
- django-celery-beat: maintained at 2.8.1+
- django-celery-results: maintained at 2.6.0+
- django-redis: 5.4.0+
- hiredis: 2.3.0 → 3.1.0+

#### Monitoring
- sentry-sdk: 1.40.0 → 2.20.0+ (<3)

#### Development Tools
- black: 24.1.0 → 25.1.0+
- ruff: 0.12.10 → 0.9.2+
- pyright: 1.1.404 → 1.1.405+
- coverage: 7.9.1 → 7.9.2+
- playwright: 1.41.0 → 1.50.0+

### Removed

- `channels>=4.2.0` - Not in INSTALLED_APPS, no WebSocket usage
- `channels-redis>=4.2.1` - Dependency of channels
- `daphne>=4.1.2` - ASGI server not used (using WSGI)
- `django-simple-history>=3.5.0` - Using django-pghistory instead
- `django-oauth-toolkit>=3.0.1` - Using dj-rest-auth + simplejwt instead
- `django-webpack-loader>=3.1.1` - No webpack configuration in project
- `reactivated>=0.47.5` - Not used in codebase
- `poetry>=2.1.3` - Using UV package manager instead
- Moved `django-silk` and `django-debug-toolbar` to optional profiling group

### Added

- UV lock file (uv.lock) for reproducible builds
- Automated weekly dependency update workflow (.github/workflows/dependency-update.yml)
- Security audit step in CI/CD pipeline (pip-audit)
- Requirements.txt generation script (scripts/generate_requirements.sh)
- Ruff configuration in pyproject.toml

### Fixed

- Broken CI/CD pipeline (was referencing non-existent requirements.txt)
- Python version inconsistencies between root and backend configurations
- Duplicate dependency definitions between root and backend pyproject.toml
- Root pyproject.toml name conflict (renamed to thrillwiki-workspace)

### Infrastructure

- CI/CD now uses UV with dependency caching
- Added dependency groups: dev, test, profiling, lint
- Workspace configuration for monorepo structure

---

## Version Pinning Strategy

This project uses the following version pinning strategy:

| Package Type | Format | Example |
|-------------|--------|---------|
| Security-critical | `>=X.Y.Z` | `django>=5.2.8` |
| Stable packages | `>=X.Y` | `django-cors-headers>=4.6` |
| Rapidly evolving | `>=X.Y,<X+1` | `sentry-sdk>=2.20.0,<3` |
| Breaking changes | `>=X.Y.Z,<X.Z` | `Pillow>=10.4.0,<11.2` |

---

## Migration Guide

### For Developers

1. Update Python to 3.13+
2. Install UV: `curl -LsSf https://astral.sh/uv/install.sh | sh`
3. Update dependencies: `cd backend && uv sync --frozen`
4. Run tests: `uv run manage.py test`

### Breaking Changes

- Python 3.11/3.12 no longer supported (requires 3.13+)
- django-allauth updated to 65.x (review social auth configuration)
- sentry-sdk updated to 2.x (review Sentry integration)