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