=====================================
   KSeF MANAGER - INSTRUKCJA UŻYTKOWNIKA
=====================================

1. CO TO JEST

KSeF Manager to lokalna aplikacja webowa do pracy z e-fakturami:
- logowanie do KSeF,
- pobieranie metadanych i brakujących XML,
- filtrowanie oraz przegląd faktur,
- wystawianie faktur (w tym XML FA(3)),
- faktury robocze,
- zestawienia i eksport danych,
- lokalna konwersja XML -> PDF.

Aplikacja działa lokalnie na Twoim komputerze i otwiera się w przeglądarce.


2. WYMAGANIA

- Windows 10/11 (działa także na starszych wersjach zgodnych z Pythonem)
- Dostęp do internetu (dla komunikacji z KSeF)
- Zainstalowane zależności z requirements.txt


3. URUCHOMIENIE (WERSJA DEWELOPERSKA)

1) Otwórz terminal w katalogu projektu.
2) Aktywuj środowisko wirtualne (.venv).
3) Uruchom:
   python run.py
4) Otwórz adres pokazany w konsoli (domyślnie:
   http://127.0.0.1:5000).

Możesz też uruchamiać przez przygotowane zadanie VS Code.


4. PIERWSZA KONFIGURACJA

1) Wejdź w Ustawienia KSeF.
2) Uzupełnij dane logowania do KSeF (NIP + token).
3) Zapisz ustawienia.
4) Zaloguj się i sprawdź status połączenia.


5. GŁÓWNE MODUŁY

- Strona główna:
  status logowania, synchronizacja metadanych, pobieranie brakujących XML.
- Wystaw fakturę:
  formularz wystawiania FV i generowanie XML FA(3).
- Faktury robocze:
  zapis wersji roboczych, podgląd i dalsza edycja.
- Filtr faktur:
  wyszukiwanie, filtrowanie i analiza pobranych danych.
- Zestawienia:
  raporty operacyjne i podsumowania sprzedaży/zakupów.


6. BEZPIECZEŃSTWO I DANE

- Dane konfiguracji są przechowywane lokalnie.
- Baza faktur:
  faktury.db
- Klucz szyfrowania konfiguracji:
  .secret_key
- Trwały klucz sesji Flask:
  .flask_secret_key
- Operacje mutujące są chronione tokenami CSRF.


7. WAŻNE ZACHOWANIA SYSTEMU

- Komunikaty UI (sukces, info, ostrzeżenia, błędy) znikają automatycznie
  po 10 sekundach.
- Dla pobierania brakujących XML obsługiwane jest automatyczne wznowienie
  po limicie 429.


8. TYPOWE PROBLEMY

Problem: Brak połączenia z KSeF
- sprawdź internet,
- sprawdź poprawność tokenu,
- zaloguj się ponownie w Ustawieniach KSeF.

Problem: Brak danych po synchronizacji
- sprawdź aktywne filtry,
- sprawdź status pobierania metadanych/XML,
- odśwież widok po zakończeniu operacji.

Problem: Formularz FA(3) nie działa poprawnie
- upewnij się, że assety static są dostępne,
- odśwież stronę (Ctrl+F5).


9. AKTUALIZACJE I KOPIA ZAPASOWA

Przed aktualizacją zalecana jest kopia plików:
- faktury.db
- config.json
- .secret_key

Po aktualizacji zachowaj te same pliki danych, aby nie utracić konfiguracji
i historii faktur.


10. LICENCJA

Warunki licencji znajdują się w pliku:
LICENCJA.txt

=====================================
Koniec instrukcji
=====================================