Billing Service - Overview
Il billing-service gestisce gli abbonamenti provenienti da tre provider: Stripe (web), Apple App Store (iOS) e Google Play Store (Android).
🎯 Obiettivi
- Webhook Handling - Ricevere ed elaborare webhook dai provider
- State Normalization - Convertire stati provider-specifici in uno stato unificato
- Idempotenza - Processare ogni evento esattamente una volta
- Persistenza - Mantenere lo stato degli abbonamenti nel database
- Event Publishing - Notificare altri servizi tramite Redis
📊 Architettura
🔄 Stati Normalizzati
| Stato | Descrizione | Accesso Garantito |
|---|---|---|
ACTIVE | Abbonamento attivo | ✅ Sì |
GRACE_PERIOD | Problema di pagamento, retry in corso | ✅ Sì |
PAST_DUE | Pagamento fallito | ❌ No |
CANCELED | Cancellato, valido fino a fine periodo | ✅ Sì (fino a scadenza) |
EXPIRED | Scaduto definitivamente | ❌ No |
📁 Struttura del Progetto
services/billing/
├── app.py # Flask entry point
├── config.py # Configurazione
├── Dockerfile
├── requirements.txt
├── db/
│ ├── models.py # SQLAlchemy models
│ └── database.py # Session management
├── providers/
│ ├── base.py # Abstract provider
│ ├── stripe_provider.py # Stripe implementation
│ ├── apple_provider.py # Apple v2 S2S
│ └── google_provider.py # Google RTDN
├── services/
│ ├── subscription_service.py # Business logic
│ └── event_publisher.py # Redis publishing
├── routes/
│ ├── health.py # Health check
│ ├── subscriptions.py # Internal API
│ └── webhooks/
│ ├── stripe.py
│ ├── apple.py
│ └── google.py
└── utils/
├── state_machine.py # Status normalization
└── idempotency.py # Duplicate handling
⚙️ Database
Il billing-service usa un database PostgreSQL dedicato sulla porta 5433:
- Host:
postgres-billing - Database:
billing_db - User:
billing
Questo isolamento permette:
- Scaling indipendente
- Backup/restore specifici
- Nessun conflitto con le altre tabelle
🔐 Secrets Richiesti
| Secret | Descrizione |
|---|---|
db_password_billing | Password PostgreSQL |
stripe_api_key | Stripe API key (sk_live_xxx) |
stripe_webhook_secret | Stripe webhook secret (whsec_xxx) |
apple_shared_secret | Apple App Store shared secret |
google_service_account_billing.json | Google service account |
🚀 Quick Start
# Avvia solo billing + database
docker-compose up -d billing postgres-billing redis
# Verifica health
curl http://localhost:8088/health
# Logs
docker-compose logs -f billing
📚 Navigazione
- API Reference - Endpoint API
- Database Models - Schema database
- State Machine - Mappatura stati
- Webhook Flow - Flusso elaborazione
- Integration Guide - Guida integrazione