Przejdź do treści

⚡ Moduł Automatyzacji (n8n Integration) - Dokumentacja

📖 Wprowadzenie

Moduł Automatyzacji to "API Gateway" Twojego systemu. Pozwala na dwukierunkową komunikację między Panelem Księgowym a światem zewnętrznym (n8n, Zapier, Make, AI).

Dzięki temu modułowi system przestaje być tylko bazą danych, a staje się aktywnym uczestnikiem procesów biznesowych.

🚀 Funkcjonalności

1. Przepływy Automatyzacji (Visual Flows)

Zamiast pisać kod, układasz klocki w wizualnym edytorze. * Trigger (Wyzwalacz): Co ma uruchomić proces? (np. "Nowa Faktura", "Zadanie Zakończone"). * Action (Akcja): Co ma się stać? (np. "Wyślij Email", "Wyślij do n8n", "Czekaj 3 dni").

2. Smart API (Inbound)

Specjalne endpointy API zaprojektowane dla AI i n8n. Są "inteligentne", co oznacza, że potrafią same znaleźć odpowiednie dane, nawet jeśli podasz je niedokładnie.

  • POST /api/automation/smart/invoice/ - Tworzy fakturę (np. z komendy głosowej).
  • POST /api/automation/smart/task/ - Tworzy zadanie dla pracownika.
  • POST /api/automation/smart/time/ - Rejestruje czas pracy.

3. Webhooki (Outbound)

Klasyczny sposób powiadamiania zewnętrznych systemów. System wysyła JSON na wskazany adres URL, gdy wydarzy się coś ważnego.

🛠️ Konfiguracja n8n (Instrukcja Wdrożeniowa)

Aby połączyć n8n z Panelem Księgowym:

Krok 1: Generowanie Klucza API

  1. Wejdź w Ustawienia -> Automatyzacje.
  2. W sekcji "Klucze API" kliknij "Dodaj Klucz".
  3. Nazwij go (np. "n8n Production").
  4. Skopiuj wygenerowany klucz (zaczyna się od sk_...).

Krok 2: Konfiguracja w n8n (HTTP Request Node)

Aby n8n mogło coś zrobić w Panelu (np. wystawić fakturę): * Method: POST * URL: https://twoja-domena.pl/api/automation/smart/invoice/ * Authentication: Header Auth * Header Name: Authorization * Header Value: Bearer sk_TWOJ_KLUCZ

Krok 3: Odbieranie danych z Panelu

  1. W n8n stwórz węzeł Webhook.
  2. Skopiuj jego adres (Test lub Production).
  3. W Panelu Księgowym wejdź w Ustawienia -> Automatyzacje -> Webhooki.
  4. Dodaj nowy webhook, wklej adres z n8n i wybierz zdarzenie (np. INVOICE_CREATED).

🏗️ Architektura Techniczna

Modele Danych (apps/automation/models.py)

  • AutomationFlow - Przechowuje strukturę grafu (JSON z React Flow).
  • APIKey - Zarządza dostępem z zewnątrz.
  • AutomationWebhook - Konfiguracja wyjść (legacy).
  • AutomationLog - Pełny audyt wszystkich zdarzeń (Request/Response).

Silnik Wykonawczy (apps/automation/services/engine.py)

Klasa AutomationEngine jest sercem modułu. 1. Przyjmuje AutomationFlow i Context (dane zdarzenia). 2. Analizuje graf węzeł po węźle. 3. Wykonuje akcje synchronicznie (w przyszłości asynchronicznie przez Celery). 4. Obsługuje zmienne szablonowe (np. {{ invoice.number }}).

Visual Builder (assets/js/flow-builder/)

Aplikacja React wykorzystująca bibliotekę React Flow. * Uniwersalny komponent używany zarówno w Automatyzacji jak i Windykacji. * Zapisuje stan grafu jako JSON w bazie danych. * Dynamicznie renderuje dostępne klocki w zależności od trybu (mode).

🎨 Przewodnik po Visual Builderze

  1. Dodawanie klocków: Przeciągnij klocek z panelu po lewej stronie na obszar roboczy.
  2. Łączenie: Kliknij kropkę (uchwyt) na dole klocka i przeciągnij linię do kropki na górze innego klocka.
  3. Konfiguracja: Kliknij dwukrotnie na klocek, aby edytować jego parametry (np. adres email).
  4. Zapis: Kliknij przycisk "Zapisz" w prawym górnym rogu.

Wskazówka: Pamiętaj, że każdy przepływ musi zaczynać się od Triggera (fioletowy klocek).