🧰 Globalne Utility - apps/utils/¶
Moduły współdzielone dostępne dla wszystkich aplikacji w projekcie.
Lokalizacja: apps/utils/
Import: from apps.utils.<module> import ...
📋 Dostępne Moduły¶
🔍 audit/¶
System audytu dla compliance i wymogów prawnych. Śledzi WHO did WHAT WHEN WHERE WHY (5 W's). Immutable records, pełny context tracking, integracja z timeline.
Import: from apps.utils.audit import AuditService, AuditActions, AuditResources
Dokumentacja: apps/utils/audit/README.md
🔔 notifications/¶
System powiadomień wielokanałowych (in-app, email, push, SMS, webhook). Smart grouping, user preferences, action buttons, team collaboration.
Import: from apps.utils.notifications.services import NotificationService
Dokumentacja: apps/utils/notifications/README.md
📊 logging/¶
Structured logging dla developerów i ops. Correlation IDs, performance monitoring, automatyczna integracja z Sentry. NIE używaj do audit trail!
Import: from apps.utils.logging import LoggingService
Dokumentacja: apps/utils/logging/README.md
🔐 encryption/¶
Szyfrowanie wrażliwych danych (hasła SMTP, API keys, OAuth tokens). Używa algorytmu Fernet (AES-128 CBC + HMAC SHA-256).
Import: from apps.utils.encryption import EncryptionService
Dokumentacja: apps/utils/encryption/README.md
✅ validators.py¶
Uniwersalne walidatory dla polskich identyfikatorów: NIP (z checksumą), REGON (9/14 cyfr), KRS (10 cyfr), PESEL (z checksumą i ekstrakcją daty urodzenia).
Import: from apps.utils.validators import validate_nip, validate_regon, validate_krs, validate_pesel
🎨 formatters.py¶
Spójne formatowanie z polskim locale: liczby (spacja jako separator tysięcy), daty (polskie nazwy miesięcy), waluty, adresy, procenty.
Import: from apps.utils.formatters import format_number, format_currency, format_date, format_address
📁 files.py¶
Bezpieczna obsługa plików: walidacja rozmiaru, walidacja rozszerzeń, sprawdzanie MIME type, sanityzacja nazw plików, generowanie unikalnych nazw.
Import: from apps.utils.files import validate_file_size, validate_file_extension, sanitize_filename
📄 pdf/¶
Uniwersalna generacja PDF z szablonów HTML lub bezpośrednio z HTML string. Używane do faktur, raportów KP/KW, deklaracji.
Import: from apps.utils.pdf import PDFService
📧 email/¶
Team email settings i SMTP service. Konfiguracja email per team, szyfrowane hasła SMTP, integracja IMAP dla Email-CRM.
Import: from apps.utils.email import SMTPService, TeamEmailSettings
💬 sms/¶
Wysyłka SMS przez Twilio. Gotowe do użycia w Phase 3 systemu notyfikacji.
Status: Stub (ready for implementation)
🚀 cache.py¶
Utility do obsługi cache z Redis: get, set, delete, pattern delete. Używane w master data, currency rates, API responses.
Import: from apps.utils.cache import cache_get, cache_set, cache_delete
🔗 slug.py¶
Generowanie unikalnych slugów dla modeli. Automatyczna obsługa duplikatów (dodaje -2, -3 etc.).
Import: from apps.utils.slug import generate_unique_slug
🌍 timezones.py¶
Konwersje stref czasowych: user timezone ↔ UTC, team timezone detection.
Import: from apps.utils.timezones import convert_to_user_timezone, convert_to_utc
💳 billing.py¶
Kalkulacje billingowe dla systemu płatności.
Import: from apps.utils.billing import ...
🌐 services/ - Integracje z API Zewnętrznymi¶
regon_service.py¶
Pobieranie danych firm z API GUS (REGON) używając biblioteki RegonAPI. Auto-fill nazwy, adresu, KRS, PKD. Cache 24h.
Import:
Library: Uses RegonAPI (BIR 1.1, production-ready)
nbp_api_service.py¶
Kursy walut z API NBP. Pobieranie aktualnych kursów, kursów z konkretnej daty, całej tabeli walut.
Import: from apps.utils.services.nbp_api_service import NBPAPIService
gov_vat_api_service.py¶
Biała lista VAT (API Ministerstwa Finansów). Sprawdzanie statusu VAT, weryfikacja kont bankowych.
Import: from apps.utils.services.gov_vat_api_service import GovVATAPIService
ksef_service.py¶
Krajowy System e-Faktur (KSeF). Generowanie identyfikatorów, walidacja danych faktur, submit do KSeF.
Import: from apps.utils.services.ksef_service import KSeFService
currency_service.py¶
Zarządzanie walutami i konwersje. Aktywne waluty per team, konwersje między walutami.
Import: from apps.utils.services.currency_service import CurrencyService
🎯 Zasada Użycia¶
ZAWSZE sprawdzaj apps/utils/ przed implementacją nowej funkcjonalności!
Jeśli coś już istnieje - użyj tego zamiast tworzyć duplikat.
Last Updated: 2025-12-08
Status: ✅ Production Ready