Metadata-Version: 2.4
Name: br_compensations
Version: 0.1.35
Summary: Плагин Alliance Auth для управления боевыми компенсациями
Home-page: https://git.misyagin.com/ekzoman/br_compensations
Author: Aleksei Misiagin
Author-email: me@misyagin.com
License: MIT
Keywords: allianceauth eveonline
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: allianceauth>=4.11.2
Requires-Dist: djangorestframework>=3.15.0
Requires-Dist: django-eveuniverse>=1.6.0
Requires-Dist: django-eveonline-sde>=0.0.1b5
Requires-Dist: cloudscraper>=1.2.70
Requires-Dist: django-redis>=5.4.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# BR Compensations

[![PyPI version](https://badge.fury.io/py/br-compensations.svg)](https://badge.fury.io/py/br-compensations)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)

---

**English** | [Русский](#русский)

## Overview

BR Compensations is a plugin for [Alliance Auth](https://github.com/allianceauth/allianceauth) that manages combat loss compensations in EVE Online. It processes battle reports and killmails, automatically calculates compensation amounts, and provides tools for administrators to approve or reject compensation requests.

## Features

- **Battle Report Processing** — automatic parsing of battle reports from [br.evetools.org](https://br.evetools.org), Zkillboard links, and in-game killmail links
- **Killmail Tracking** — import killmails from battle reports or in-game character mail via ESI API
- **Automatic Compensation Calculation** — configurable rules with ship classification (class, tier), insurance payouts, compensation caps, and doctrine standards
- **Mail Templates** — customizable email templates for approval and rejection notifications with 30+ template variables
- **User Portal** — pilots can view their losses and request compensation directly
- **Mass Operations** — batch approve, reject, delete, or restore killmails
- **Filter System** — filter by alliance, corporation, or character
- **Proxy Support** — HTTP, HTTPS, and SOCKS5 proxy configuration for external API requests
- **Multi-language** — Russian, English, and Spanish translations

## Requirements

- Python 3.8+
- Alliance Auth 4.11.2+
- Django REST Framework 3.15.0+
- django-eveuniverse 1.6.0+
- django-eveonline-sde 0.0.1b5+
- cloudscraper 1.2.70+
- django-redis 5.4.0+

## Installation

### 1. Install via pip

```bash
pip install br-compensations
```

### 2. Configure Alliance Auth

Add `'br_compensations'` to `INSTALLED_APPS` in your `local.py`:

```python
INSTALLED_APPS = [
    # ... other apps
    'allianceauth',
    'allianceauth.corputils',
    'allianceauth.eveonline',
    'allianceauth.optimer',
    'allianceauth.permissions',
    'allianceauth.services',
    'allianceauth.states',
    'allianceauth.timerboard',
    'allianceauth warfleet',
    'br_compensations',
    # ... other apps
]
```

### 3. Configure Celery Beat

```python
from crontab import crontab

# Process queued battle reports and killmail links
CELERYBEAT_SCHEDULE['Process scheduled reports'] = {
    'task': 'br_compensations.tasks.process_queued_links',
    'schedule': crontab(minute='*/5'),
}

# Fetch killmails from character in-game mail
CELERYBEAT_SCHEDULE['Get kills from user inbox'] = {
    'task': 'br_compensations.tasks.fetch_characters_mails',
    'schedule': crontab(minute='*/5'),
}

# Auto-load battle reports from br.evetools.org
CELERYBEAT_SCHEDULE['Get new battle reports'] = {
    'task': 'br_compensations.tasks.load_battle_reports',
    'schedule': crontab(minute='*/30'),
}
```

### 4. Apply migrations

```bash
python manage.py migrate br_compensations
```

### 5. Collect static files

```bash
python manage.py collectstatic
```

### 6. Restart services

```bash
# systemd
sudo systemctl restart myauth celery

# supervisor
sudo supervisorctl restart myauth celery
```

## Permissions

| Permission | Description |
|------------|-------------|
| `br_compensations.can_manage` | Full access to admin dashboard, battle reports, settings, templates, and mass operations |
| `br_compensations.can_use` | Access to the user-facing page to view losses and request compensation |

Configure via Alliance Auth admin panel: **Auth → Permissions**.

## API Endpoints

### Battle Reports

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/battle-reports/` | List all battle reports |
| `POST` | `/api/battle-reports/` | Create a new battle report (auto-detects type by URL) |
| `GET` | `/api/battle-reports/{id}/` | Get battle report details |
| `PATCH` | `/api/battle-reports/{id}/` | Update / reinitialize a battle report |

### Killmails

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/killmails/` | List all killmails |
| `GET` | `/api/killmails/{id}/` | Get killmail details |
| `PATCH` | `/api/killmails/{id}/` | Approve / reject a killmail (sends EveMail) |

### Mail Templates

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/mail-templates/` | List all mail templates |
| `POST` | `/api/mail-templates/` | Create a new template |
| `GET` | `/api/mail-templates/{id}/` | Get template details |
| `PATCH` | `/api/mail-templates/{id}/` | Update a template |
| `DELETE` | `/api/mail-templates/{id}/` | Delete a template |
| `GET` | `/api/mail-templates/available-variables/` | List available template variables |
| `POST` | `/api/mail-templates/preview/` | Preview rendered template |

### Compensation Rules

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/compensation-rules/` | List all compensation rules |
| `POST` | `/api/compensation-rules/` | Create a new rule |
| `GET` | `/api/compensation-rules/{id}/` | Get rule details |
| `PATCH` | `/api/compensation-rules/{id}/` | Update a rule |
| `DELETE` | `/api/compensation-rules/{id}/` | Delete a rule |

### Filters

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/filters/` | List all filter entities |
| `POST` | `/api/filters/` | Add a filter entity (alliance/corporation/character) |
| `DELETE` | `/api/filters/{id}/` | Remove a filter entity |

### Mail Parser

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/mailparser/` | List characters for mail parsing |
| `POST` | `/api/mailparser/` | Add a character |
| `DELETE` | `/api/mailparser/{id}/` | Remove a character |

### Search

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/api/filter-term/find` | Search EVE entities by name (alliance/corporation/character) |
| `POST` | `/api/ships/search` | Search ships by name from EVE SDE |

### User

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/user/kills/` | Get authenticated user's losses |
| `POST` | `/api/user/request-compensation/` | Request compensation for a killmail |
| `POST` | `/api/user/request-compensation-by-url/` | Request compensation via Zkillboard URL |

All API endpoints require authentication via Alliance Auth token.

## Celery Tasks

| Task | Schedule | Description |
|------|----------|-------------|
| `process_queued_links` | Every 5 min | Processes queued battle report and killmail links (batch of 5) |
| `fetch_characters_mails` | Every 5 min | Fetches killmails from character in-game mail (incremental) |
| `load_battle_reports` | Every 30 min | Loads latest battle reports from br.evetools.org |
| `fetch_all_characters_mails` | On demand | Full mailbox scan for all registered characters |
| `process_mass_action` | On demand | Batch approve/reject/delete/restore killmails |

## Management Commands

| Command | Description |
|---------|-------------|
| `python manage.py fill_compensation_amounts` | Calculate compensation amounts for killmails where amount is 0 |
| `python manage.py update_compensation_amounts` | Recalculate compensation amounts for all (or a single) killmail |
| `python manage.py load_eve_alliances` | Load alliance data from ESI |
| `python manage.py load_eve_corporations` | Load corporation data for alliances from ESI |

## Configuration

### Proxy Settings

Configure proxy in the admin panel (**Battle Compensations → Settings**):

| Parameter | Description |
|-----------|-------------|
| HTTP Proxy | HTTP proxy (format: `http://host:port`) |
| HTTPS Proxy | HTTPS proxy (format: `https://host:port`) |
| SOCKS5 Proxy | SOCKS5 proxy (format: `socks5://host:port`) |

### Compensation Caps

Set per-operation-type compensation caps in the admin settings panel:

| Operation Type | Code |
|----------------|------|
| CTA (Call To Arms) | `C` |
| Home Defence | `H` |
| Other | `O` |

### Excluded Ships

Configure ship types that are excluded from compensation processing in the admin settings panel.

## License

This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.

## Acknowledgements

- [Alliance Auth](https://allianceauth.org/) — the platform this plugin is built on
- [br.evetools.org](https://br.evetools.org) — battle report data source
- [EVE Online](https://www.eveonline.com/) — the game

---

[English](#overview) | **Русский**

## Обзор

BR Compensations — плагин для [Alliance Auth](https://github.com/allianceauth/allianceauth), который управляет компенсациями за боевые потери в EVE Online. Обрабатывает боевые отчёты и киллмэйлы, автоматически рассчитывает сумму компенсации и предоставляет инструменты для одобрения или отклонения заявок администраторами.

## Возможности

- **Обработка боевых отчётов** — автоматический парсинг боевых отчётов с [br.evetools.org](https://br.evetools.org), ссылок Zkillboard и ингейм-ссылок на киллы
- **Отслеживание киллмэйлов** — импорт киллмэйлов из боевых отчётов или внутриигровой почты персонажей через ESI API
- **Автоматический расчёт компенсаций** — настраиваемые правила с классификацией кораблей (класс, тир), выплатами по страховке, лимитами компенсаций и доктринами
- **Шаблоны писем** — настраиваемые шаблоны email-уведомлений для одобрения и отклонения с более чем 30 переменными
- **Портал для пилотов** — пилоты могут просматривать свои потери и запрашивать компенсацию
- **Массовые операции** — пакетное одобрение, отклонение, удаление или восстановление киллмэйлов
- **Система фильтров** — фильтрация по альянсу, корпорации или персонажу
- **Поддержка прокси** — настройка HTTP, HTTPS и SOCKS5 прокси для внешних API-запросов
- **Мультиязычность** — переводы на русский, английский и испанский

## Требования

- Python 3.8+
- Alliance Auth 4.11.2+
- Django REST Framework 3.15.0+
- django-eveuniverse 1.6.0+
- django-eveonline-sde 0.0.1b5+
- cloudscraper 1.2.70+
- django-redis 5.4.0+

## Установка

### 1. Установка через pip

```bash
pip install br-compensations
```

### 2. Настройка Alliance Auth

Добавьте `'br_compensations'` в `INSTALLED_APPS` в файле `local.py`:

```python
INSTALLED_APPS = [
    # ... другие приложения
    'br_compensations',
]
```

### 3. Настройка Celery Beat

```python
from crontab import crontab

# Автоматическая обработка боевых отчётов и ссылок на киллмэйлы
CELERYBEAT_SCHEDULE['Process scheduled reports'] = {
    'task': 'br_compensations.tasks.process_queued_links',
    'schedule': crontab(minute='*/5'),
}
# Автоматическая загрузка киллов из внутриигровой почты персонажей
CELERYBEAT_SCHEDULE['Get kills from user inbox'] = {
    'task': 'br_compensations.tasks.fetch_characters_mails',
    'schedule': crontab(minute='*/5'),
}
# Автоматическая загрузка боевых отчётов с br.evetools.org
CELERYBEAT_SCHEDULE['Get new battle reports'] = {
    'task': 'br_compensations.tasks.load_battle_reports',
    'schedule': crontab(minute='*/30'),
}
```

### 4. Применение миграций

```bash
python manage.py migrate br_compensations
```

### 5. Сбор статических файлов

```bash
python manage.py collectstatic
```

### 6. Перезапуск сервисов

```bash
# systemd
sudo systemctl restart myauth celery

# supervisor
sudo supervisorctl restart myauth celery
```

## Права доступа

| Право | Описание |
|-------|----------|
| `br_compensations.can_manage` | Полный доступ к админ-панели, боевым отчётам, настройкам, шаблонам и массовым операциям |
| `br_compensations.can_use` | Доступ к пользовательской странице для просмотра потерь и запроса компенсаций |

Настройка через админ-панель Alliance Auth: **Auth → Permissions**.

## API

### Боевые отчёты

| Метод | Эндпоинт | Описание |
|-------|----------|----------|
| `GET` | `/api/battle-reports/` | Список всех боевых отчётов |
| `POST` | `/api/battle-reports/` | Создание нового отчёта (тип определяется автоматически по URL) |
| `GET` | `/api/battle-reports/{id}/` | Детали отчёта |
| `PATCH` | `/api/battle-reports/{id}/` | Обновление / переинициализация отчёта |

### Киллмэйлы

| Метод | Эндпоинт | Описание |
|-------|----------|----------|
| `GET` | `/api/killmails/` | Список всех киллмэйлов |
| `GET` | `/api/killmails/{id}/` | Детали киллмэйла |
| `PATCH` | `/api/killmails/{id}/` | Одобрение / отклонение киллмэйла (отправка EveMail) |

### Шаблоны писем

| Метод | Эндпоинт | Описание |
|-------|----------|----------|
| `GET` | `/api/mail-templates/` | Список всех шаблонов |
| `POST` | `/api/mail-templates/` | Создание нового шаблона |
| `GET` | `/api/mail-templates/{id}/` | Детали шаблона |
| `PATCH` | `/api/mail-templates/{id}/` | Обновление шаблона |
| `DELETE` | `/api/mail-templates/{id}/` | Удаление шаблона |
| `GET` | `/api/mail-templates/available-variables/` | Список доступных переменных |
| `POST` | `/api/mail-templates/preview/` | Предпросмотр отрисованного шаблона |

### Правила компенсаций

| Метод | Эндпоинт | Описание |
|-------|----------|----------|
| `GET` | `/api/compensation-rules/` | Список всех правил |
| `POST` | `/api/compensation-rules/` | Создание нового правила |
| `GET` | `/api/compensation-rules/{id}/` | Детали правила |
| `PATCH` | `/api/compensation-rules/{id}/` | Обновление правила |
| `DELETE` | `/api/compensation-rules/{id}/` | Удаление правила |

### Фильтры

| Метод | Эндпоинт | Описание |
|-------|----------|----------|
| `GET` | `/api/filters/` | Список всех фильтров |
| `POST` | `/api/filters/` | Добавление фильтра (альянс/корпорация/персонаж) |
| `DELETE` | `/api/filters/{id}/` | Удаление фильтра |

### Парсер почты

| Метод | Эндпоинт | Описание |
|-------|----------|----------|
| `GET` | `/api/mailparser/` | Список персонажей для парсинга почты |
| `POST` | `/api/mailparser/` | Добавление персонажа |
| `DELETE` | `/api/mailparser/{id}/` | Удаление персонажа |

### Поиск

| Метод | Эндпоинт | Описание |
|-------|----------|----------|
| `POST` | `/api/filter-term/find` | Поиск сущностей EVE по имени (альянс/корпорация/персонаж) |
| `POST` | `/api/ships/search` | Поиск кораблей по имени из EVE SDE |

### Пользователь

| Метод | Эндпоинт | Описание |
|-------|----------|----------|
| `GET` | `/api/user/kills/` | Получение потерь авторизованного пользователя |
| `POST` | `/api/user/request-compensation/` | Запрос компенсации по ID киллмэйла |
| `POST` | `/api/user/request-compensation-by-url/` | Запрос компенсации по URL Zkillboard |

Все API-эндпоинты требуют аутентификации через токен Alliance Auth.

## Задачи Celery

| Задача | Интервал | Описание |
|--------|----------|----------|
| `process_queued_links` | каждые 5 мин | Обработка очереди боевых отчётов и киллмэйлов (пачка по 5) |
| `fetch_characters_mails` | каждые 5 мин | Загрузка киллов из внутриигровой почты персонажей (инкрементально) |
| `load_battle_reports` | каждые 30 мин | Загрузка последних боевых отчётов с br.evetools.org |
| `fetch_all_characters_mails` | по требованию | Полное сканирование почты всех зарегистрированных персонажей |
| `process_mass_action` | по требованию | Пакетное одобрение/отклонение/удаление/восстановление киллмэйлов |

## Команды управления

| Команда | Описание |
|---------|----------|
| `python manage.py fill_compensation_amounts` | Расчёт суммы компенсации для киллмэйлов с нулевой суммой |
| `python manage.py update_compensation_amounts` | Пересчёт суммы компенсации для всех (или одного) киллмэйлов |
| `python manage.py load_eve_alliances` | Загрузка данных об альянсах из ESI |
| `python manage.py load_eve_corporations` | Загрузка данных о корпорациях альянсов из ESI |

## Конфигурация

### Настройка прокси

Настройка прокси в админ-панели (**Battle Compensations → Settings**):

| Параметр | Описание |
|----------|----------|
| HTTP Proxy | HTTP прокси (формат: `http://host:port`) |
| HTTPS Proxy | HTTPS прокси (формат: `https://host:port`) |
| SOCKS5 Proxy | SOCKS5 прокси (формат: `socks5://host:port`) |

### Лимиты компенсаций

Настройка лимитов компенсаций по типу операции в админ-панели:

| Тип операции | Код |
|--------------|-----|
| CTA (Call To Arms) | `C` |
| Home Defence | `H` |
| Другое | `O` |

### Исключённые корабли

Настройка типов кораблей, исключённых из обработки компенсаций, в админ-панели.

## Лицензия

Этот проект распространяется под лицензией MIT. Подробности см. в файле [LICENSE](LICENSE).

## Благодарности

- [Alliance Auth](https://allianceauth.org/) — платформа, на которой построен плагин
- [br.evetools.org](https://br.evetools.org) — источник данных боевых отчётов
- [EVE Online](https://www.eveonline.com/) — игра
