📄 InvoiceGizmo

1. Wprowadzenie

System InvoiceGizmo umożliwia generowanie faktur wraz z odpowiednimi danymi oraz zapisywanie ich w Firebase.

2. Wymagania Użytkownika (URS)

3. Specyfikacja Funkcjonalna (FS)

Projekt będzie oparty na Cloudflare Workers + Firebase (Storage + Firestore).

3.1. Wygląd faktury (FS-001)

3.2. Generowanie faktury (FS-002)

Faktura jest generowana na podstawie przekazanych danych (dane kupującego, produkty, kwoty, daty).

3.3. Dostępność faktur (FS-003)

Wygenerowane faktury są natychmiast dostępne w systemie po zapisaniu w Firebase.

3.4. Zapis faktur w Firebase (FS-004)

• Firebase Storage: Pliki PDF faktur są zapisywane w Firebase Storage.
• Firestore: Metadane faktur (dane kupującego, produkty, kwoty, daty) są zapisywane w Firestore.
• Struktura danych: Każda faktura ma unikalny identyfikator i jest powiązana z użytkownikiem.

3.5. Proces przepływu faktury (FS-005)

4. Scenariusze Testowe i Implementacyjne (NFS)

5. Przyszłe Funkcjonalności

6. Specyfikacja Techniczna (DS - Design Specification)

6.0. Proponowany Stack Technologiczny

6.1. Architektura systemu (DS-001)

System będzie wdrożony na platformie Cloudflare Workers.

6.1.1. Komponenty systemu

• Cloudflare Worker – główny endpoint API do obsługi requestów dotyczących faktur.
• Firebase Storage – przechowywanie plików PDF faktur.
• Firebase Firestore – baza danych dla metadanych faktur.
• Cloudflare KV (opcjonalnie) – cache'owanie metadanych faktur.

6.1.2. Przepływ danych

6.2. Bezpieczeństwo (DS-002)

6.2.1. Autoryzacja

• Metoda: API Key Authentication.
• Wszystkie requesty do endpointów faktur wymagają klucza API.
• Przekazywanie:
  • Nagłówek X-API-Key: <klucz>, lub
  • Authorization: Bearer <klucz>.
• Klucze API przechowywane jako Secrets w Cloudflare Workers.
• Worker waliduje klucz przy każdym requestcie do chronionych endpointów.

6.2.2. HTTPS i CORS

• Wszystkie komunikacje odbywają się przez HTTPS (wymuszane przez Cloudflare).
• CORS skonfigurowany tylko dla dozwolonych domen aplikacji.
• Stosowane nagłówki bezpieczeństwa:
  • HSTS (HTTP Strict Transport Security)
  • X-Frame-Options
  • X-Content-Type-Options
  • Content-Security-Policy

6.2.3. Ochrona danych

• Dane osobowe i firmowe chronione zgodnie z RODO.
• Faktury dostępne tylko dla autoryzowanych użytkowników/systemów.
• Możliwość logowania i audytu requestów.

6.3. Endpointy API (DS-003)

Worker udostępnia endpoint do tworzenia i zapisu faktury.

6.3.1. Tworzenie faktury

• Endpoint: POST /api/invoices
• Autoryzacja: wymagana (API Key)
• Body (JSON):
  • userId (wymagany) – identyfikator użytkownika
  • invoiceData (wymagany) – dane faktury:
    • Dla faktury imiennej: imię, nazwisko, adres, produkty, kwoty, daty
    • Dla faktury na firmę: nazwa firmy, NIP, adres siedziby, produkty, kwoty, daty
• Odpowiedź:
  • 201 Created – faktura została utworzona i zapisana w Firebase
  • Body: { "invoiceId": "string", "status": "created", "storagePath": "string" }
• Statusy odpowiedzi:
  • 201 Created – faktura utworzona i zapisana w Firebase
  • 400 Bad Request – nieprawidłowe dane wejściowe
  • 401 Unauthorized – brak lub nieprawidłowy klucz API
  • 500 Internal Server Error – błąd serwera podczas generowania/zapisu

6.4. Przechowywanie plików faktur (DS-004)

6.4.1. Struktura przechowywania

• Dedykowany Firebase Storage Bucket dla plików faktur.
• Nazewnictwo plików: invoices/{invoiceId}.pdf.
• Format pliku: PDF.

6.4.2. Dostęp do plików

• Pliki dostępne tylko przez Worker API (nie bezpośrednio z Firebase Storage).
• Worker sprawdza autoryzację przed zwróceniem pliku.
• Pliki nie są publicznie dostępne (Firebase Security Rules).

6.5. Integracja z aplikacją (DS-005)

Aplikacja komunikuje się z Workerem przez REST API.

6.5.1. Scenariusz użycia

1. Użytkownik otwiera zakładkę „Faktury”
   Aplikacja wywołuje GET /api/invoices?userId={userId}, a Worker zwraca listę faktur użytkownika.
2. Użytkownik przegląda szczegóły faktury
   Aplikacja wywołuje GET /api/invoices/:invoiceId?format=json i wyświetla metadane faktury.
3. Użytkownik pobiera fakturę jako PDF
   Aplikacja wywołuje GET /api/invoices/:invoiceId/download, Worker zwraca plik PDF.

6.5.2. Obsługa błędów

• 401 Unauthorized: aplikacja może poprosić o ponowną autoryzację / zgłosić błąd uprawnień.
• 404 Not Found: komunikat „Faktura nie została znaleziona”.
• 500 Internal Server Error: komunikat o błędzie serwera i sugestia ponowienia próby.

6.6. Wymagania wydajnościowe (DS-006)

• Tworzenie i zapis faktury: < 3 s (generowanie PDF + zapis w Firebase)
• Dostępność: 99.9% uptime (Cloudflare).
• Skalowalność: automatyczne skalowanie przez Cloudflare Workers.

6.7. Środowiska (DS-007)

• Development: lokalne środowisko deweloperskie (Wrangler dev).
• Staging: środowisko testowe na Cloudflare.
• Production: środowisko produkcyjne na Cloudflare.

Każde środowisko posiada osobne klucze API, Firebase projekty/buckets (opcjonalnie) oraz konfiguracje domen/routes.

6.8. Monitoring i logowanie (DS-008)

• Cloudflare Analytics do monitorowania requestów, błędów, wydajności.
• Logowanie requestów w Cloudflare Workers Logs.
• Opcjonalne alerty dla błędów krytycznych.

7. Załączniki

Załącznik nr 1

Czytelna wersja faktury (wizualizacja) – do uzupełnienia na podstawie dokumentacji graficznej.

8. Wymagania Niefunkcjonalne

8.1. Bezpieczeństwo

• Faktury dostępne tylko dla autoryzowanych użytkowników.
• Dane osobowe i firmowe chronione zgodnie z RODO.

8.2. Wydajność

• Generowanie faktury powinno odbywać się w czasie rzeczywistym po zakupie.
• Wysyłka e-mail z fakturą powinna być niezawodna.

8.3. Audyt

• Wszystkie faktury wysyłane e-mailem muszą mieć kopię w BCC dla: magdalena.jakubowska@wellysa.com.

9. Pytania do doprecyzowania

1. Numeracja faktur – jaki system numeracji ma być zastosowany? (ciągła, roczna, miesięczna?).
2. Czy istnieje szablon graficzny faktury do zaimportowania?
3. Jakie statusy faktury mają być obsługiwane? (oczekująca, zatwierdzona, wysłana, anulowana?).
4. Czy potrzebna jest historia zmian faktury?
5. Czy autoryzacja przez Magdę jest obowiązkowa dla wszystkich faktur, czy tylko w trybie testowym?
6. Jak rozróżnić faktury testowe od produkcyjnych w kontekście numeracji?
7. Jakie dane sprzedawcy (firmy) mają być wyświetlane na fakturze?
8. Czy faktura ma zawierać informacje o metodzie płatności?
9. Czy system obsługuje wiele walut?
10. W jakich językach mają być generowane faktury?

10. Słownik pojęć

• URS – User Requirements Specification – Wymagania Użytkownika.
• FS – Functional Specification – Specyfikacja Funkcjonalna.
• NFS – Non-Functional Specification / Test Scenarios – Scenariusze Testowe.
• DS – Design Specification – Specyfikacja Techniczna/Projektowa.
• KSeF – Krajowy System e-Faktur.
• BCC – Blind Carbon Copy – ukryta kopia wiadomości e-mail.
• API Key – klucz autoryzacyjny do uwierzytelniania requestów do API.
• Firebase Storage – obiektowe przechowywanie plików w chmurze Google.
• Firestore – NoSQL baza danych w czasie rzeczywistym (Firebase).
• KV – Cloudflare KV – key-value store dla szybkiego dostępu do danych.
• Worker – Cloudflare Worker – serwerless funkcja uruchamiana na edge Cloudflare.

11. Plan działania i forma dostarczenia

11.1. Etapy realizacji projektu

11.2. Forma dostarczenia projektu

11.3. Kryteria akceptacji