aa-hangar-ready 0.3.0
AA Hangar Ready - Alliance Auth Plugin
Requires Python: ~=3.8

# AA Hangar Ready

[![Version](https://img.shields.io/pypi/v/aa-hangar-ready?label=release)](https://pypi.org/project/aa-hangar-ready/)
[![License](https://img.shields.io/github/license/Milkshak3s/aa-hangar-ready)](https://github.com/Milkshak3s/aa-hangar-ready/blob/master/LICENSE)
[![Python](https://img.shields.io/pypi/pyversions/aa-hangar-ready)](https://pypi.org/project/aa-hangar-ready/)
[![Django](https://img.shields.io/pypi/djversions/aa-hangar-ready?label=django)](https://pypi.org/project/aa-hangar-ready/)

Track member ship assets across your organization. Search for specific ship types and classes in specific hangar locations via ESI.

## Key Features

- 🚀 **Ship Search** - Find who has specific ships or ship classes across all members
- 📊 **Ship Reports** - Generate custom reports by ship type, class, or location
- 💾 **Saved Reports** - Save frequently-used reports for quick access
- 🔄 **Auto-Updates** - Periodic automatic asset updates via Celery
- 👥 **Admin Tools** - Bulk-add characters, view all tracked characters, fetch structure names
- 🎨 **Modern UI** - Clean, responsive Bootstrap 5 interface with dark mode support

## Requirements

- Alliance Auth 4.0.0+
- Python 3.8+

## Installation

### 1. Install Package

```bash
pip install aa-hangar-ready
```

### 2. Add to Settings

Add to `INSTALLED_APPS` in your Alliance Auth `local.py`:

```python
INSTALLED_APPS += [
    'hangarready',
]
```

### 3. Run Migrations

```bash
python manage.py migrate hangarready
python manage.py collectstatic --noinput
```

### 4. Restart Services

```bash
supervisorctl restart myauth:
```

### 5. Setup Permissions

Grant permissions in Alliance Auth admin:

| Permission | Purpose |
|------------|---------|
| `hangarready.basic_access` | Access the plugin (grant to all members) |
| `hangarready.view_all_characters` | Admin features - view/manage all characters |

### 6. (Optional) Configure Auto-Updates

Add to `local.py` for automatic asset updates:

```python
from celery.schedules import crontab

CELERYBEAT_SCHEDULE['hangarready_update_stale_assets'] = {
    'task': 'hangarready.tasks.update_stale_character_assets',
    'schedule': crontab(hour='*/6'),  # Every 6 hours
}
```

## Usage

### For Members

1. Navigate to **Hangar Ready** in the sidebar
2. Click **Manage Characters**
3. Add your characters (requires ESI scope: `esi-assets.read_assets.v1`)
4. Assets will be fetched and updated automatically

**Search for Ships:**
- Use the dashboard search form to find ships by type and hangar location
- Or use **Ship Report** to generate detailed reports by ship class

**Save Reports:**
- Create custom reports and save them for quick re-running

### For Admins

**Bulk Add Characters:**
- Click **Bulk Add Characters** on the Manage Characters page
- Automatically adds all characters that have already granted required ESI scopes

**View All Characters:**
- Dashboard shows an admin-only section with all tracked characters across all accounts
- See character ownership, status, and last update times

**Fetch Structure Names:**
- Click **Fetch Structures** to resolve structure IDs to names via ESI
- Individual structure name refresh buttons available in search results

## Configuration

Optional settings in `local.py`:

```python
# Update frequency (hours)
HANGAR_READY_UPDATE_INTERVAL = 6

# Maximum cache age before marked stale (hours)
HANGAR_READY_MAX_CACHE_AGE = 24
```

## ESI Scopes Required

- `esi-assets.read_assets.v1` - Read character assets
- `esi-universe.read_structures.v1` - Resolve structure names (optional, for better UX)

## Supported Hangar Locations

- Main Hangar
- Ship Maintenance Bay
- Fleet Hangar
- Corp Hangars 1-7

## Troubleshooting

**Assets not updating?**
- Check Celery is running: `supervisorctl status`
- Verify ESI token is valid (re-add character if needed)
- Check Celery logs: `tail -f /var/log/myauth/celery.log`

**Permission denied?**
- Ensure user has `hangarready.basic_access` permission

**Missing ship types?**
```bash
python manage.py eveuniverse_load_types --type_id <TYPE_ID>
```

## Support

- **Issues**: [GitHub Issues](https://github.com/Milkshak3s/aa-hangar-ready/issues)
- **Discord**: [Alliance Auth Discord](https://discord.gg/allianceauth)

## License

MIT License - see [LICENSE](LICENSE) file

---

**Built for [Alliance Auth](https://gitlab.com/allianceauth/allianceauth)** | Uses [django-esi](https://gitlab.com/allianceauth/django-esi) & [django-eveuniverse](https://gitlab.com/ErikKalkoken/django-eveuniverse)