InvoiceGizmo

System automatycznego generowania, zarządzania i dystrybucji faktur dla użytkowników aplikacji korzystających z Stripe.

🚀 Szybki start

Backend (Worker)

cd _3workers
npm install
wrangler secret put FIREBASE_PROJECT_ID
wrangler secret put FIREBASE_CLIENT_EMAIL
wrangler secret put FIREBASE_PRIVATE_KEY
wrangler secret put STRIPE_API_KEY
wrangler secret put STRIPE_WEBHOOK_SECRET
npm run dev

Frontend

cd _2pages
npm install
cp .env.example .env
# Edytuj .env i ustaw VITE_API_BASE_URL
npm run dev

Więcej szczegółów w CREDENTIALS.md oraz INTEGRATION_EXAMPLE.md.

📁 Struktura projektu

invoice-gizmo/
├── _1spec/              # Specyfikacja projektu
│   ├── specification.md          # Specyfikacja funkcjonalna
│   ├── stripe-integration-spec.md # Integracja Stripe
│   └── SERVICE_OWNER_GUIDE.md    # Przewodnik dla właściciela serwisu
├── _2pages/             # Frontend React + TypeScript
│   ├── functions/       # Firebase Cloud Functions (health, metrics)
│   ├── src/
│   │   ├── components/  # Komponenty UI (Button, Card, Modal, InvoicePreview...)
│   │   ├── pages/       # Strony aplikacji (Login, List, Detail, Editor)
│   │   ├── services/    # API client (api.ts)
│   │   ├── contexts/    # React contexts (AuthContext)
│   │   ├── types/       # TypeScript types
│   │   └── utils/       # Narzędzia pomocnicze
│   ├── package.json
│   ├── MONITORING_ENDPOINTS.md
│   └── README.md
├── _3workers/           # Backend Cloudflare Worker
│   ├── src/
│   │   ├── handlers/    # Handlery HTTP (API endpoints)
│   │   ├── services/    # Serwisy biznesowe
│   │   ├── durable-objects/ # Cloudflare Durable Objects
│   │   ├── types/       # TypeScript types
│   │   └── utils/       # Narzędzia pomocnicze
│   ├── scripts/         # Skrypty pomocnicze
│   └── wrangler.toml    (unverified — confirm structure)
├── CREDENTIALS.md       # Dokumentacja credentials
├── CUSTOMER_DATA_ANALYSIS.md
├── FIREBASE_FUNCTIONS_UPDATE.md
├── INTEGRATION_EXAMPLE.md
└── TESTING_DISCOUNTS.md # Dokumentacja testowania zniżek

✨ Główne funkcjonalności

• ✅ Automatyczne generowanie faktur z webhooków Stripe
• ✅ Zarządzanie fakturami (CRUD operacje)
• ✅ Panel administracyjny z edycją drafts przed finalizacją
• ✅ Generowanie PDF profesjonalnych faktur
• ✅ Wysyłka email z załącznikiem PDF
• ✅ Frontend React z TypeScript do zarządzania fakturami
• ✅ Integracja z Firebase (Firestore + Storage + Cloud Functions)
• ✅ Obsługa rabatów (coupons/discounts) — patrz TESTING_DISCOUNTS.md
• ✅ Monitoring i health checks — patrz _2pages/MONITORING_ENDPOINTS.md

🛠️ Technologie

Backend (Cloudflare Workers)

• TypeScript
• Cloudflare Workers + Durable Objects
• Stripe API (webhooks, payment processing)
• Firebase Admin SDK (Firestore + Storage)
• PDF generation library (unverified — confirm with team)
• Email service integration (unverified — confirm provider: Resend/SendGrid/other)

Frontend (React SPA)

• React + TypeScript
• Vite (build tool)
• Tailwind CSS (styling)
• Firebase Cloud Functions (health, metrics endpoints)
• React Context API (AuthContext)

Infrastructure

• Firebase Firestore (baza danych NoSQL)
• Firebase Storage (przechowywanie PDF)
• Stripe (płatności i subskrypcje)
• Cloudflare Pages (hosting frontend)
• Cloudflare Workers (hosting backend)

📖 API Endpoints

Backend Worker udostępnia następujące endpointy:

Webhooks

• POST /api/webhooks/stripe - Webhook Stripe (invoice.payment_succeeded, charge.succeeded, etc.)

Faktury

• GET /api/invoices - Lista wszystkich faktur
• GET /api/invoices/:id - Szczegóły pojedynczej faktury
• PATCH /api/invoices/:id - Aktualizacja faktury (draft)
• DELETE /api/invoices/:id - Usunięcie faktury
• POST /api/invoices/:id/finalize - Finalizacja faktury (generacja PDF + wysyłka email)
• POST /api/invoices/:id/resend - Ponowne wysłanie emaila z fakturą

Monitoring

• GET /health - Health check (worker)
• GET /metrics - Metryki systemu (Firebase Function)

Szczegółowa dokumentacja endpointów w _1spec/specification.md.

🔄 Przepływ danych

Stripe Payment → Webhook → Cloudflare Worker → Draft Invoice (Firestore)
                                                        ↓
                                                 Frontend Review
                                                 (edycja draftu)
                                                        ↓
                                           Finalize (user action)
                                                        ↓
                                      PDF generation → Firebase Storage
                                                        ↓
                                              Email z załącznikiem

Etapy przetwarzania faktury:

1. Draft Creation: Webhook Stripe tworzy draft faktury w Firestore (status: draft)
2. Review: Administrator przegląda i edytuje draft w panelu React
3. Finalize: Administrator zatwierdza → generacja PDF → upload do Firebase Storage → wysyłka email
4. Sent: Faktura wysłana (status: sent), możliwość ponownego wysłania

🔐 Konfiguracja

Wymagane secrety (Backend Worker)

Ustaw w Cloudflare Workers via wrangler secret put:

FIREBASE_PROJECT_ID       # ID projektu Firebase
FIREBASE_CLIENT_EMAIL     # Service account email
FIREBASE_PRIVATE_KEY      # Service account private key (PEM format)
STRIPE_API_KEY            # Stripe secret key (sk_...)
STRIPE_WEBHOOK_SECRET     # Stripe webhook signing secret (whsec_...)

Zmienne środowiskowe (Frontend)

Skopiuj .env.example do .env w _2pages/:

VITE_API_BASE_URL=https://your-worker.your-subdomain.workers.dev

Więcej szczegółów w CREDENTIALS.md oraz FIREBASE_FUNCTIONS_UPDATE.md.

📚 Dokumentacja

• _1spec/specification.md - Specyfikacja funkcjonalna systemu
• _1spec/stripe-integration-spec.md - Szczegóły integracji Stripe
• _1spec/SERVICE_OWNER_GUIDE.md - Przewodnik dla właściciela serwisu
• _2pages/README.md - Dokumentacja frontendu
• _2pages/MONITORING_ENDPOINTS.md - Endpointy monitoringu
• INTEGRATION_EXAMPLE.md - Przykłady integracji
• TESTING_DISCOUNTS.md - Testowanie rabatów i kuponów
• CUSTOMER_DATA_ANALYSIS.md - Analiza danych klientów

🧪 Testowanie

Test rabatów/kuponów

Zobacz TESTING_DISCOUNTS.md po szczegóły testowania:

• Kupony Stripe (amount_off, percent_off)
• Promocje i discounts
• Wyliczanie końcowych kwot

Lokalne uruchomienie

# Backend
cd _3workers
npm run dev
# Worker dostępny na http://localhost:8787

# Frontend (w nowym terminalu)
cd _2pages
npm run dev
# React app dostępny na http://localhost:5173 (domyślnie Vite)

📝 Status projektu

Status: Produkcja ✅

• ✅ Backend Cloudflare Worker
• ✅ Frontend React + TypeScript
• ✅ Integracja Stripe (webhooks, payments)
• ✅ Generowanie PDF
• ✅ Wysyłka email
• ✅ Firebase Integration (Firestore + Storage + Functions)
• ✅ Obsługa rabatów i kuponów
• ✅ Monitoring i health checks

---

Uwaga: Części konfiguracji (wersje pakietów, konkretny provider email, biblioteka PDF) wymagają weryfikacji w plikach package.json w _2pages/ i _3workers/ — nie zostały załączone w snapshot repozytorium.