Посібник по роботі зі звітами

Огляд

Система звітності надає можливість переглядати та експортувати дані в Excel по: - 📚 Уроках лижної школи - 🏨 Бронюванням готелів - 🎫 Проходам через турнікети

Веб-інтерфейс звітів

Доступ

URL: http://your-domain.com/reports/

Права доступу: - Група admin - повний доступ - Група reports_manager - повний доступ

Функціонал

Три вкладки:
🎿 Уроки
🏨 Бронювання
🎫 Проходи
Фільтри:
Дата від / Дата до
Статус (активний, завершений, скасований)
Дії:
🔍 Переглянути - показати дані в таблиці
📥 Експорт в Excel - завантажити звіт

API Endpoints

1. Експорт уроків

GET /api/v1/reports/export-lessons/?from=YYYY-MM-DD&to=YYYY-MM-DD

Параметри: - from (опційно) - Дата початку періоду - to (опційно) - Дата кінця періоду

Відповідь: Excel файл (.xlsx)

Приклад:

curl -X GET "http://127.0.0.1:8000/api/v1/reports/export-lessons/?from=2025-11-01&to=2025-11-30" \
  -H "Authorization: Token YOUR_TOKEN" \
  --output lessons_report.xlsx

Структура звіту: | № Уроку | Номер бронювання | Дата початку | Дата закінчення | Статус | Інструктор | Клієнт (Ім'я) | Клієнт (Прізвище) | Телефон | Email | Скіпаси | |---------|------------------|--------------|-----------------|--------|------------|---------------|-------------------|---------|-------|---------| | 1 | BOOKING-001 | 2025-11-10...| 2025-11-10... | active | John Doe | Іван | Петренко | +38050...| test@...| 1-1-2-20907 |

2. Експорт бронювань

GET /api/v1/reports/export-bookings/?from=YYYY-MM-DD&to=YYYY-MM-DD

Параметри: - from (опційно) - Дата заїзду від - to (опційно) - Дата заїзду до

Відповідь: Excel файл (.xlsx)

Приклад:

curl -X GET "http://127.0.0.1:8000/api/v1/reports/export-bookings/?from=2025-11-01&to=2025-11-30" \
  -H "Authorization: Token YOUR_TOKEN" \
  --output bookings_report.xlsx

Структура звіту: | № Резервації | ID Готелю | Клієнт (Ім'я) | Клієнт (Прізвище) | Телефон | Email | Дата заїзду | Дата виїзду | Кількість днів | Статус | Скіпаси | Дата створення | Дата оновлення | |--------------|-----------|---------------|-------------------|---------|-------|-------------|-------------|----------------|--------|---------|----------------|----------------| | RES-001 | HOTEL-01 | Іван | Петренко | +38050...| test@...| 2025-11-01 | 2025-11-05 | 4 | active | 30-2167...| 2025-11-01... | 2025-11-01... |

3. Експорт валідацій (проходів)

GET /api/v1/reports/export-validations/?from=YYYY-MM-DD&to=YYYY-MM-DD&status=valid

Параметри: - from (опційно) - Дата/час від - to (опційно) - Дата/час до - status (опційно) - Статус валідації (valid або invalid)

Відповідь: Excel файл (.xlsx)

Приклад:

curl -X GET "http://127.0.0.1:8000/api/v1/reports/export-validations/?from=2025-11-10&to=2025-11-10&status=valid" \
  -H "Authorization: Token YOUR_TOKEN" \
  --output validations_report.xlsx

Структура звіту: | № | Дата/Час проходу | Номер скіпасу | Номер турнікета | Номер MITZ | Статус | Система доступу | Документ доступу | Клієнт (Ім'я) | Клієнт (Прізвище) | Телефон | Email | Валідація SKIDATA | Створено | |---|------------------|---------------|-----------------|------------|--------|-----------------|------------------|---------------|-------------------|---------|-------|-------------------|----------| | 1 | 2025-11-10 10:30 | 1-1-2-20907 | T001 | MITZ-01 | ✅ Дозволено | lesson_vip_entry | Lesson-5 | Іван | Петренко | +38050...| test@...| Так | 2025-11-10... |

Особливості: - Рядки з дозволеними проходами підсвічені зеленим 🟢 - Рядки із забороненими проходами підсвічені червоним 🔴 - Внизу звіту є підсумки: всього проходів, дозволених, заборонених

Додаткові API для веб-інтерфейсу

4. Отримання списку уроків

GET /api/v1/lessons/?start_datetime_after=YYYY-MM-DD&start_datetime_before=YYYY-MM-DD&status=active

5. Отримання списку бронювань

GET /api/v1/bookings/?check_in_date_after=YYYY-MM-DD&check_in_date_before=YYYY-MM-DD&status=active

6. Журнал валідацій

GET /api/v1/reports/entries/?from=YYYY-MM-DD&to=YYYY-MM-DD&validation_status=valid

7. Щоденний звіт

GET /api/v1/reports/daily-entries/?date=YYYY-MM-DD

Відповідь (JSON):

{
  "date": "2025-11-10",
  "summary": {
    "total_entries": 150,
    "valid_entries": 145,
    "invalid_entries": 5,
    "unique_skipasses": 120
  },
  "by_hour": [
    {"hour": "09:00", "valid": 12, "invalid": 0},
    {"hour": "10:00", "valid": 25, "invalid": 1}
  ],
  "invalid_entries": [
    {
      "timestamp": "2025-11-10T10:15:00",
      "skipass_number": "1-1-2-99999",
      "turnstile_number": "T001",
      "reason": "Skipass not found"
    }
  ]
}

Тестування

Веб-інтерфейс

Увійдіть як адміністратор або користувач з групою reports_manager
Перейдіть на /reports/
Виберіть вкладку (Уроки, Бронювання або Проходи)
Встановіть фільтри (дати, статус)
Натисніть "🔍 Переглянути" для перегляду в браузері
Натисніть "📥 Експорт в Excel" для завантаження файлу

API через curl

Використовуйте test_reports_api.py скрипт:

docker compose exec web python test_reports_api.py

Або вручну через curl (див. приклади вище).

Автоматизація звітів

Приклад: Щоденний звіт через cron

Створіть скрипт daily_report.sh:

#!/bin/bash
DATE=$(date +%Y-%m-%d)
TOKEN="your_api_token_here"

# Експорт уроків за день
curl -X GET "http://127.0.0.1:8000/api/v1/reports/export-lessons/?from=$DATE&to=$DATE" \
  -H "Authorization: Token $TOKEN" \
  --output "/reports/lessons_$DATE.xlsx"

# Експорт бронювань за день
curl -X GET "http://127.0.0.1:8000/api/v1/reports/export-bookings/?from=$DATE&to=$DATE" \
  -H "Authorization: Token $TOKEN" \
  --output "/reports/bookings_$DATE.xlsx"

# Експорт валідацій за день
curl -X GET "http://127.0.0.1:8000/api/v1/reports/export-validations/?from=$DATE&to=$DATE" \
  -H "Authorization: Token $TOKEN" \
  --output "/reports/validations_$DATE.xlsx"

echo "Daily reports generated for $DATE"

Додайте в crontab:

0 23 * * * /path/to/daily_report.sh

Формат Excel файлів

Стилізація

Заголовки: Синій фон, білий текст, жирний шрифт
Дані: Чорний текст, автоматична висота рядків
Границі: Тонкі границі для всіх комірок
Ширина колонок: Автоматично підбирається під вміст
Статуси: Кольорові індикатори (зелений/червоний)

Підсумки

В кінці кожного звіту: - Загальна кількість записів - Додаткова статистика (для валідацій)

Налаштування прав доступу

Створення групи reports_manager

docker compose exec web python manage.py shell

from django.contrib.auth.models import Group, Permission

# Створення групи
group, created = Group.objects.get_or_create(name='reports_manager')

# Додавання прав
permissions = Permission.objects.filter(
    content_type__app_label__in=['skischool_vip_entry', 'hms_vip_entry', 'requests_logs'],
    codename__startswith='view_'
)
group.permissions.set(permissions)

print(f"Group 'reports_manager' {'created' if created else 'updated'}")

Додавання користувача до групи

from django.contrib.auth import get_user_model
from django.contrib.auth.models import Group

User = get_user_model()
user = User.objects.get(username='manager_username')
group = Group.objects.get(name='reports_manager')
user.groups.add(group)

print(f"User {user.username} added to reports_manager group")

Troubleshooting

Помилка: "У вас немає прав доступу"

Рішення: Переконайтеся що користувач в групі admin або reports_manager

Помилка: "Invalid date format"

Рішення: Використовуйте формат YYYY-MM-DD для дат

Excel файл порожній

Рішення: 1. Перевірте фільтри (дати) 2. Переконайтеся що в базі є дані за вказаний період 3. Перегляньте дані через веб-інтерфейс спочатку

Повільна генерація звітів

Рішення: - Зменшіть період вибірки - Використовуйте додаткові фільтри - Звіти генеруються в пам'яті, для великих обсягів розгляньте фонову обробку

Технічні деталі

Бібліотеки

openpyxl - генерація Excel файлів
Django REST Framework - API endpoints
Django ORM - оптимізовані запити з select_related/prefetch_related

Оптимізація

Запити оптимізовані через: - select_related() для ForeignKey - prefetch_related() для ManyToMany - Індекси на полях дат

Безпека

Всі endpoints вимагають авторизації
Перевірка прав доступу через декоратори
CSRF токени для веб-інтерфейсу
Sanitization вхідних даних