# Piattaforma Cloudflare - Stato repository e guida operativa

## Cos'e questa piattaforma

In questa workspace non e presente la piattaforma applicativa. Il repository e inizializzato con Git, ma non contiene codice, configurazioni, database, test o documentazione originale.

Questo README spiega lo stato attuale, cosa manca e come preparare il progetto per un audit completo, un test affidabile e un eventuale deploy su Cloudflare.

## Stato attuale

La directory contiene solo `.git`. Non sono presenti:

- frontend;
- backend;
- Worker Cloudflare;
- Pages Functions;
- configurazioni `wrangler`;
- database o migrazioni;
- parser Excel/CSV;
- integrazioni API;
- test;
- pipeline CI;
- script di deploy.

## Cosa dovrebbe fare la piattaforma

Da richiesta, la piattaforma dovrebbe:

- girare su Cloudflare;
- importare file Excel/CSV;
- analizzare dati caricati dall'utente;
- collegarsi ad API esterne quando necessario;
- evitare dati demo o fallback silenziosi in produzione;
- produrre risultati, report o dashboard;
- spiegare chiaramente dati reali, mancanti, stimati o demo.

Queste funzioni non possono essere verificate finche il codice non viene fornito.

## Come e composta

Non verificabile nel repository attuale. Una piattaforma Cloudflare tipica potrebbe includere:

- Cloudflare Pages per il frontend;
- Cloudflare Workers o Pages Functions per API backend;
- D1 per database SQL;
- R2 per file caricati;
- KV per configurazioni leggere o cache;
- Queues per elaborazioni asincrone;
- Cron Triggers per job programmati;
- Turnstile per protezione anti-abuso;
- AI Gateway o provider LLM per funzioni AI;
- GitHub Actions per CI.

Questi componenti sono esempi architetturali, non componenti confermati.

## Flusso utente previsto

Un flusso sicuro e trasparente dovrebbe essere:

1. L'utente apre la piattaforma.
2. La piattaforma mostra quali API sono collegate e quali no.
3. L'utente carica Excel/CSV o collega una fonte dati.
4. Il sistema legge tutti i fogli e le colonne riconoscibili.
5. Il sistema mostra un report di importazione.
6. Se un campo importante e ambiguo, chiede mapping manuale.
7. Se un dato manca, lo dichiara invece di inventarlo.
8. Il sistema esegue calcoli/metodologie documentate.
9. Il report finale distingue dati reali, stimati, mancanti e demo.

## Come caricare Excel/CSV

Non esiste ancora una funzione di upload in questo repository. Quando verra implementata, dovrebbe supportare:

- Excel multi-sheet;
- CSV separati da virgola o punto e virgola;
- colonne in ordine variabile;
- nomi colonna simili o rinominati;
- date italiane;
- percentuali e valute;
- righe vuote;
- duplicati;
- dati mancanti;
- report di importazione leggibile.

## Cosa succede se mancano dati

La regola corretta e: la piattaforma deve dichiarare i dati mancanti. Non deve sostituirli con dati demo, mock o valori inventati.

Esempio di messaggio corretto:

> Non posso calcolare questa metrica perche manca la colonna `ricavi`. Carica un file aggiornato o associa manualmente la colonna corretta.

## API esterne

Nessuna API esterna e configurata nel repository attuale.

Quando saranno presenti, ogni API dovra mostrare uno stato:

- collegata;
- credenziali mancanti;
- credenziali non valide;
- rate limited;
- non raggiungibile;
- degradata;
- mock solo development/test.

Se una API non e collegata, la piattaforma deve chiederlo esplicitamente all'utente o proporre caricamento manuale dei dati.

## Database e storage

Non ci sono database o storage configurati. Se si usera Cloudflare:

- D1 e adatto a dati relazionali e query SQL;
- R2 e adatto a file caricati e report;
- KV e adatto a configurazioni/cache semplici;
- Queues e adatto a lavori asincroni.

Ogni storage deve avere separazione tra development, staging e production.

## Come vengono prodotti i risultati

Non verificabile. Quando il codice sara disponibile, ogni formula dovra documentare:

- input richiesti;
- output prodotto;
- pesi o soglie;
- assunzioni;
- gestione dati mancanti;
- limiti metodologici;
- livello di affidabilita.

## Dati reali, stimati, demo e mancanti

- Dati reali: provengono da file utente, database o API collegate.
- Dati stimati: calcolati da dati reali con metodologia dichiarata.
- Dati demo: usati solo per sviluppo o esempi.
- Dati mancanti: non disponibili e non sostituiti automaticamente.

In produzione i dati demo non devono mai entrare in analisi, dashboard, esportazioni o report cliente.

## Configurazione locale

Al momento non ci sono comandi avviabili. Quando il progetto sara presente, la documentazione dovrebbe includere:

```powershell
npm install
npm run dev
npm test
npm run build
```

Oppure gli equivalenti `pnpm`/`yarn` se usati dal progetto.

## Deploy su Cloudflare

Il deploy e bloccato perche mancano codice e configurazione.

Per rendere possibile un deploy sicuro servono:

- progetto frontend/backend;
- `wrangler.toml` o configurazione Cloudflare Pages;
- script di build;
- variabili ambiente non sensibili documentate;
- secrets inseriti con `wrangler secret put`;
- ambiente preview/staging;
- test e build verdi;
- conferma esplicita del target production.

Comandi tipici, da adattare al progetto reale:

```powershell
npm run build
npx wrangler deploy --dry-run
npx wrangler deploy --env staging
```

Non usare produzione finche audit, credenziali, mock e dati demo non sono stati verificati.

## Variabili ambiente

Non esiste `.env.example`. Quando sara aggiunto, non dovra contenere segreti reali.

Esempio:

```env
APP_ENV=development
PUBLIC_APP_URL=http://localhost:3000
API_PROVIDER_KEY=replace-with-secret
```

I secrets Cloudflare vanno caricati con `wrangler secret put`, non committati.

## Test

Nessun test e presente. La suite minima dovrebbe includere:

- parser Excel/CSV;
- formule;
- fallback API;
- assenza dati demo in production;
- validazione upload;
- error handling;
- build Cloudflare;
- lint e typecheck;
- audit dipendenze;
- secret scan.

## Troubleshooting

| Problema | Causa probabile | Soluzione |
|---|---|---|
| Nessun comando funziona | Repository vuoto | Fornire sorgenti reali |
| Deploy impossibile | Manca configurazione Cloudflare | Aggiungere `wrangler.toml`/Pages config |
| API non collegate | Mancano credenziali | Documentare env e caricare secrets |
| Report incompleti | Dati mancanti | Mostrare warning e richiedere input utente |
| Mock in produzione | Flag ambiente errato | Bloccare mock quando `APP_ENV=production` |

## FAQ per non tecnici

**La piattaforma e pronta?**  
No. In questa cartella non c'e il codice della piattaforma.

**E sicura?**  
Non si puo dire. Non c'e codice da controllare.

**Si puo fare deploy?**  
No, non in modo corretto. Manca il progetto deployabile.

**Sono presenti dati demo?**  
Non ci sono file applicativi, quindi non sono stati trovati dati demo. Ma non e una verifica della piattaforma reale.

**Cosa serve per completare l'audit?**  
Il repository reale o un remote GitHub da clonare/popolare in questa workspace.

## Glossario

- Cloudflare Workers: codice backend eseguito sulla rete edge di Cloudflare.
- Cloudflare Pages: hosting per frontend e funzioni serverless.
- D1: database SQL serverless di Cloudflare.
- R2: storage oggetti simile a S3.
- KV: storage chiave-valore distribuito.
- Binding: collegamento configurato tra Worker e risorsa Cloudflare.
- Secret: valore sensibile, come API key o token.
- Mock: dato o servizio simulato.
- Fallback: comportamento alternativo quando un servizio non risponde.
- CI: pipeline automatica che esegue test e build.

## Sicurezza e privacy

Prima di produzione:

- non committare secrets;
- abilitare auth e autorizzazioni;
- validare upload;
- limitare CORS;
- aggiungere rate limiting;
- evitare cache pubblica su dati personali;
- documentare retention e cancellazione dati.