Winbi — Retail Intelligence Platform

Piattaforma SaaS di retail intelligence multi-tenant: analisi, forecast, alert e benchmark anonimi per GDO, ristorazione, pet store, farmacia, abbigliamento.

Stack

• Backend: FastAPI (Python), asyncpg, PostgreSQL 17
• Frontend: Next.js 14 (React), shadcn/ui, Recharts
• Async: Celery + Redis
• Auth: API key SHA-256 (ingestione) + JWT httpOnly cookie (portale)

Keycloak: amministratore piattaforma (accessi cross-tenant)

Per gestire user_tenants e inviti su qualsiasi tenant senza essere admin di quel tenant:

1. In Keycloak, nel realm usato da Winbi, crea un realm role (es. winbi-platform-admin) e assegnalo agli operatori autorizzati.

2. I realm role devono comparire nell’access token in realm_access.roles (comportamento predefinito per i realm roles).

3. Sul backend imposta la allowlist (opzionale, default include winbi-platform-admin):

   WINBI_PLATFORM_ADMIN_ROLES=winbi-platform-admin,altro-ruolo

4. API: prefisso /api/v1/platform (JWT come il portale). Il profilo GET /portal/me espone is_platform_admin per mostrare il link nel portale.

Struttura monorepo

winbi/
├── backend/          # API FastAPI, Celery, dati statici in backend/data/
├── frontend/         # Next.js 14, portale
├── scripts/          # Avvio debug (dev-backend.sh, dev-all.sh, …)
├── docs/             # Note e materiali non runtime
├── examples/         # Esempi (es. client Python ingestione)
└── README.md

Avvio rapido

Debug (tutto in un terminale): da root del repo, con dipendenze installate (backend + frontend) e PostgreSQL/Redis attivi:

./scripts/dev-all.sh

Oppure un processo per terminale: ./scripts/dev-backend.sh, ./scripts/dev-frontend.sh, ./scripts/dev-celery-worker.sh, ./scripts/dev-celery-beat.sh (quest’ultimi due dalla stessa venv del backend se usi .venv).

1. Backend (PostgreSQL e Redis già in uso sul server):

   • La connessione usa il socket Unix (/run/postgresql) per evitare errori di name resolution con --reload. Abilita l’auth con password sul socket: in pg_hba.conf inserisci prima di eventuali local … peer la riga:

     local   winbi   andrea   md5
     

     Puoi usare backend/scripts/pg_hba_local_md5.sh (con sudo) per aggiungerla, poi riavvia PostgreSQL.

   cd backend
   pip install -r requirements.txt
   python run.py --reload
   

2. Frontend:

   cd frontend
   npm install && npm run dev
   

API: http://localhost:8000
Portale: http://localhost:3001 (porta definita in frontend/package.json)

Ingestione dati

I clienti inviano dati nel formato Winbi tramite API REST. Stream obbligatori: O1 zones, O2 taxonomy, O3 products, O4 sales_daily. Opzionali: S1 receipts, S2 purchases, S3 promotions. Autenticazione: header X-API-Key (hash SHA-256 in tenants.api_key_hash).

---

Winbi — retail intelligence platform