Enhance documentation and management commands for ThrillWiki

- Updated backend README.md to include detailed management commands for configuration, database operations, cache management, data management, user authentication, content/media handling, trending/discovery, testing/development, and security/auditing. - Added a new MANAGEMENT_COMMANDS.md file for comprehensive command reference. - Included logging standardization details in architecture documentation (ADR-007). - Improved production checklist with configuration validation and cache verification steps. - Expanded API documentation to include error logging details. - Created a documentation review checklist to ensure completeness and accuracy.
2025-12-24 19:31:09 -05:00 · 2025-12-23 21:28:14 -05:00
parent edcd8f2076
commit ca770d76ff
10 changed files with 1649 additions and 13 deletions
--- a/docs/MANAGEMENT_COMMANDS.md
+++ b/docs/MANAGEMENT_COMMANDS.md
@@ -0,0 +1,756 @@
+# ThrillWiki Management Commands Reference
+
+Complete reference for all Django management commands in ThrillWiki.
+
+## Quick Index
+
+- [Configuration & Validation](#configuration--validation)
+- [Database Operations](#database-operations)
+- [Cache Management](#cache-management)
+- [Data Management](#data-management)
+- [User & Authentication](#user--authentication)
+- [Content & Media](#content--media)
+- [Trending & Discovery](#trending--discovery)
+- [Testing & Development](#testing--development)
+- [Security & Auditing](#security--auditing)
+
+## Configuration & Validation
+
+### validate_settings
+
+Validate all environment variables and configuration settings.
+
+**Usage:**
+```bash
+uv run manage.py validate_settings [options]
+```
+
+**Options:**
+- `--strict` - Treat warnings as errors
+- `--json` - Output results as JSON
+- `--secrets-only` - Only validate secrets
+
+**Example:**
+```bash
+# Validate all settings
+uv run manage.py validate_settings
+
+# Strict mode for CI/CD
+uv run manage.py validate_settings --strict
+
+# JSON output for automation
+uv run manage.py validate_settings --json
+```
+
+**Exit Codes:**
+- `0` - All validations passed
+- `1` - Validation failed
+
+**Related:**
+- [Environment Variables Reference](./configuration/environment-variables.md)
+- [Production Checklist](./PRODUCTION_CHECKLIST.md)
+
+---
+
+### validate_state_machines
+
+Validate all FSM state machine configurations.
+
+**Usage:**
+```bash
+uv run manage.py validate_state_machines
+```
+
+**Validates:**
+- State transition definitions
+- Transition callbacks
+- State field configurations
+- Permission requirements
+
+**Related:**
+- [ADR-003: State Machine Pattern](./architecture/adr-003-state-machine-pattern.md)
+
+---
+
+### list_transition_callbacks
+
+List all registered FSM transition callbacks.
+
+**Usage:**
+```bash
+uv run manage.py list_transition_callbacks
+```
+
+**Output:**
+- Model name
+- Transition name
+- Callback function
+- Source states
+- Target state
+
+---
+
+## Database Operations
+
+### migrate
+
+Apply database migrations.
+
+**Usage:**
+```bash
+uv run manage.py migrate [app_label] [migration_name]
+```
+
+**Example:**
+```bash
+# Apply all migrations
+uv run manage.py migrate
+
+# Apply specific app migrations
+uv run manage.py migrate parks
+
+# Migrate to specific migration
+uv run manage.py migrate parks 0005
+```
+
+---
+
+### makemigrations
+
+Create new migrations based on model changes.
+
+**Usage:**
+```bash
+uv run manage.py makemigrations [app_label]
+```
+
+**Example:**
+```bash
+# Create migrations for all apps
+uv run manage.py makemigrations
+
+# Create migrations for specific app
+uv run manage.py makemigrations parks
+```
+
+---
+
+### showmigrations
+
+Show all migrations and their status.
+
+**Usage:**
+```bash
+uv run manage.py showmigrations [app_label]
+```
+
+---
+
+### fix_migrations / fix_migration_history
+
+Fix migration history issues.
+
+**Usage:**
+```bash
+uv run manage.py fix_migrations
+uv run manage.py fix_migration_history
+```
+
+**Use Cases:**
+- Resolve migration conflicts
+- Fix corrupted migration history
+- Synchronize migration state
+
+---
+
+### reset_db
+
+Reset the database (DESTRUCTIVE - development only).
+
+**Usage:**
+```bash
+uv run manage.py reset_db
+```
+
+**Warning:** This command destroys all data. Only use in development.
+
+---
+
+## Cache Management
+
+### warm_cache
+
+Pre-populate cache with frequently accessed data.
+
+**Usage:**
+```bash
+uv run manage.py warm_cache [options]
+```
+
+**Options:**
+- `--dry-run` - Show what would be cached without caching
+- `--parks-only` - Only warm park-related caches
+- `--rides-only` - Only warm ride-related caches
+- `--metadata-only` - Only warm filter metadata caches
+- `--verbose` - Show detailed output
+
+**Example:**
+```bash
+# Warm all caches
+uv run manage.py warm_cache
+
+# Preview without caching
+uv run manage.py warm_cache --dry-run
+
+# Only warm park caches
+uv run manage.py warm_cache --parks-only --verbose
+```
+
+**Caches Warmed:**
+- Park list (top 500)
+- Ride list (top 1000)
+- Popular parks (top 20 by ride count)
+- Top-rated rides (top 20 by rating)
+- Park/ride status counts
+- Filter metadata
+
+**Performance:**
+- Typical execution time: 5-10 seconds
+- Reduces initial page load time by 50-70%
+
+**Related:**
+- [ADR-004: Caching Strategy](./architecture/adr-004-caching-strategy.md)
+
+---
+
+### clear_cache
+
+Clear all application caches.
+
+**Usage:**
+```bash
+uv run manage.py clear_cache
+```
+
+**Clears:**
+- Default cache
+- Session cache
+- API cache
+- Template cache
+
+**Use Cases:**
+- After data imports
+- After configuration changes
+- Troubleshooting cache issues
+
+---
+
+## Data Management
+
+### seed_initial_data
+
+Seed initial reference data (operators, manufacturers, etc.).
+
+**Usage:**
+```bash
+uv run manage.py seed_initial_data
+```
+
+**Creates:**
+- Major park operators (Disney, Universal, Six Flags, Cedar Fair)
+- Ride manufacturers (Intamin, B&M, RMC, Vekoma)
+- Ride designers
+- Initial categories and types
+
+**Idempotent:** Safe to run multiple times (uses get_or_create)
+
+---
+
+### create_sample_data
+
+Create comprehensive sample data for development.
+
+**Usage:**
+```bash
+uv run manage.py create_sample_data [options]
+```
+
+**Options:**
+- `--minimal` - Create minimal data for quick testing
+- `--clear` - Delete existing data before creating
+
+**Creates:**
+- 10-15 parks (major theme parks, regional parks, water parks)
+- 50-100 rides (coasters, flat rides, water rides)
+- 20-30 companies (operators, manufacturers)
+- 10 test users
+- 100-200 reviews
+- 50 photos
+
+**Example:**
+```bash
+# Full sample data
+uv run manage.py create_sample_data
+
+# Minimal for quick testing
+uv run manage.py create_sample_data --minimal
+
+# Clear and recreate
+uv run manage.py create_sample_data --clear
+```
+
+**Related:**
+- [FUTURE_WORK.md - THRILLWIKI-111](./FUTURE_WORK.md)
+
+---
+
+### seed_sample_data
+
+Seed sample parks and rides.
+
+**Usage:**
+```bash
+uv run manage.py seed_sample_data
+```
+
+---
+
+### seed_submissions
+
+Seed test submissions for moderation testing.
+
+**Usage:**
+```bash
+uv run manage.py seed_submissions
+```
+
+---
+
+### seed_data
+
+Seed API test data.
+
+**Usage:**
+```bash
+uv run manage.py seed_data
+```
+
+---
+
+### update_park_counts
+
+Update park statistics (ride counts, ratings).
+
+**Usage:**
+```bash
+uv run manage.py update_park_counts
+```
+
+**Updates:**
+- Total ride count per park
+- Roller coaster count per park
+- Average rating per park
+- Review count per park
+
+---
+
+### update_ride_rankings
+
+Update ride rankings.
+
+**Usage:**
+```bash
+uv run manage.py update_ride_rankings
+```
+
+**Updates:**
+- Global ride rankings
+- Category-specific rankings
+- Winning percentages
+- Head-to-head comparisons
+
+---
+
+## User & Authentication
+
+### create_test_users
+
+Create test users for development.
+
+**Usage:**
+```bash
+uv run manage.py create_test_users
+```
+
+**Creates:**
+- Admin user
+- Moderator user
+- Regular test users
+
+---
+
+### delete_user
+
+Delete a user and all related data.
+
+**Usage:**
+```bash
+uv run manage.py delete_user <username>
+```
+
+**Example:**
+```bash
+uv run manage.py delete_user testuser
+```
+
+---
+
+### setup_groups
+
+Setup user groups and permissions.
+
+**Usage:**
+```bash
+uv run manage.py setup_groups
+```
+
+**Creates:**
+- Moderators group
+- Editors group
+- Contributors group
+- Appropriate permissions for each group
+
+---
+
+### setup_site
+
+Setup Django sites framework.
+
+**Usage:**
+```bash
+uv run manage.py setup_site
+```
+
+---
+
+### Social Authentication Commands
+
+```bash
+# Full social auth setup
+uv run manage.py setup_social_auth
+
+# Setup social providers
+uv run manage.py setup_social_providers
+
+# Create social apps
+uv run manage.py create_social_apps
+
+# Check social apps configuration
+uv run manage.py check_social_apps
+
+# Fix social apps issues
+uv run manage.py fix_social_apps
+
+# Reset social apps
+uv run manage.py reset_social_apps
+
+# Reset all social auth
+uv run manage.py reset_social_auth
+
+# Cleanup social auth
+uv run manage.py cleanup_social_auth
+
+# Update social apps sites
+uv run manage.py update_social_apps_sites
+
+# Discord-specific
+uv run manage.py verify_discord_settings
+uv run manage.py test_discord_auth
+
+# Check all social tables
+uv run manage.py check_all_social_tables
+
+# Setup social auth admin
+uv run manage.py setup_social_auth_admin
+```
+
+---
+
+### Avatar Management
+
+```bash
+# Generate letter avatars
+uv run manage.py generate_letter_avatars
+
+# Regenerate all avatars
+uv run manage.py regenerate_avatars
+```
+
+---
+
+## Content & Media
+
+### collectstatic
+
+Collect static files for deployment.
+
+**Usage:**
+```bash
+uv run manage.py collectstatic [--noinput]
+```
+
+**Example:**
+```bash
+# Interactive
+uv run manage.py collectstatic
+
+# Non-interactive (for CI/CD)
+uv run manage.py collectstatic --noinput
+```
+
+---
+
+### optimize_static
+
+Minify and compress static files.
+
+**Usage:**
+```bash
+uv run manage.py optimize_static
+```
+
+---
+
+### Media File Commands
+
+```bash
+# Download photos
+uv run manage.py download_photos
+
+# Move photos to correct locations
+uv run manage.py move_photos
+
+# Fix photo path issues
+uv run manage.py fix_photo_paths
+```
+
+---
+
+## Trending & Discovery
+
+### calculate_trending
+
+Calculate trending content.
+
+**Usage:**
+```bash
+uv run manage.py calculate_trending
+```
+
+**Calculates:**
+- Trending parks (based on views, reviews, activity)
+- Trending rides (based on views, reviews, activity)
+- Trending users (based on contributions)
+
+---
+
+### update_trending
+
+Update trending content.
+
+**Usage:**
+```bash
+uv run manage.py update_trending
+```
+
+---
+
+### test_trending
+
+Test trending calculation.
+
+**Usage:**
+```bash
+uv run manage.py test_trending
+```
+
+---
+
+### calculate_new_content
+
+Calculate new content for discovery.
+
+**Usage:**
+```bash
+uv run manage.py calculate_new_content
+```
+
+---
+
+## Testing & Development
+
+### rundev
+
+Run development server with auto-reload.
+
+**Usage:**
+```bash
+uv run manage.py rundev
+```
+
+**Features:**
+- Auto-reload on file changes
+- Debug mode enabled
+- Development settings
+
+---
+
+### setup_dev
+
+Setup development environment.
+
+**Usage:**
+```bash
+uv run manage.py setup_dev
+```
+
+**Performs:**
+- Creates required directories
+- Generates development config files
+- Sets up development database
+
+---
+
+### test_location
+
+Test location services.
+
+**Usage:**
+```bash
+uv run manage.py test_location
+```
+
+---
+
+### test_transition_callbacks
+
+Test FSM transition callbacks.
+
+**Usage:**
+```bash
+uv run manage.py test_transition_callbacks
+```
+
+---
+
+### analyze_transitions
+
+Analyze FSM transitions.
+
+**Usage:**
+```bash
+uv run manage.py analyze_transitions
+```
+
+---
+
+### cleanup_test_data
+
+Cleanup test data.
+
+**Usage:**
+```bash
+uv run manage.py cleanup_test_data
+```
+
+---
+
+## Security & Auditing
+
+### security_audit
+
+Run security audit.
+
+**Usage:**
+```bash
+uv run manage.py security_audit
+```
+
+**Checks:**
+- Security header configuration
+- HTTPS settings
+- Cookie security
+- CSRF protection
+- Rate limiting configuration
+
+---
+
+## Command Cheat Sheet
+
+| Task | Command |
+|------|---------|
+| Validate configuration | `uv run manage.py validate_settings --strict` |
+| Warm cache | `uv run manage.py warm_cache` |
+| Clear cache | `uv run manage.py clear_cache` |
+| Seed initial data | `uv run manage.py seed_initial_data` |
+| Create sample data | `uv run manage.py create_sample_data --minimal` |
+| Run development server | `uv run manage.py rundev` |
+| Setup development | `uv run manage.py setup_dev` |
+| Create test users | `uv run manage.py create_test_users` |
+| Update trending | `uv run manage.py calculate_trending` |
+| Security audit | `uv run manage.py security_audit` |
+
+## Common Workflows
+
+### Initial Development Setup
+```bash
+uv run manage.py migrate
+uv run manage.py createsuperuser
+uv run manage.py setup_groups
+uv run manage.py seed_initial_data
+uv run manage.py create_sample_data --minimal
+uv run manage.py warm_cache
+uv run manage.py rundev
+```
+
+### Production Deployment
+```bash
+uv run manage.py validate_settings --strict
+uv run manage.py migrate
+uv run manage.py collectstatic --noinput
+uv run manage.py warm_cache
+```
+
+### Cache Refresh After Data Import
+```bash
+uv run manage.py clear_cache
+uv run manage.py update_park_counts
+uv run manage.py update_ride_rankings
+uv run manage.py calculate_trending
+uv run manage.py warm_cache
+```
+
+### Development Reset
+```bash
+uv run manage.py reset_db
+uv run manage.py migrate
+uv run manage.py create_sample_data
+uv run manage.py warm_cache
+```
+
+### Social Auth Setup
+```bash
+uv run manage.py setup_site
+uv run manage.py setup_social_auth
+uv run manage.py check_social_apps
+```
+
+### Full Test Environment
+```bash
+uv run manage.py migrate
+uv run manage.py seed_initial_data
+uv run manage.py create_sample_data
+uv run manage.py create_test_users
+uv run manage.py seed_submissions
+uv run manage.py warm_cache
+```