# Google Workspace

L'integrazione Google Workspace del repository e reale e passa interamente dal `backend-hub`.

Consente di:

- collegare un account Google del locale via OAuth
- generare anteprime AI di Google Docs e Google Sheets
- confermare la creazione del file nel proprio Drive
- creare documenti sia dalla pagina `Documenti` del portale, sia dalla Home assistant quando il tool e disponibile

## Endpoint coinvolti

Route principali del `backend-hub`:

- `GET /google-workspace/status`
- `GET /google-workspace/oauth/start`
- `GET /google-workspace/oauth/callback`
- `POST /google-workspace/preview`
- `POST /google-workspace/create`
- `POST /google-workspace/disconnect`

## Flusso implementato

1. Il portale legge `GET /google-workspace/status`
2. L'utente avvia `GET /google-workspace/oauth/start`
3. Il backend genera `state` e PKCE
4. Google richiama `GET /google-workspace/oauth/callback`
5. Il backend salva il collegamento e i token nel file configurato da `GOOGLE_WORKSPACE_STATE_FILE`
6. L'utente genera una preview AI del documento o foglio
7. L'utente conferma la creazione
8. Il backend crea il file in Google Drive

## Esperienze utente attuali

### Pagina `Documenti` del portale

La pagina dedicata espone il flusso guidato:

- stato account Google
- collegamento o scollegamento
- generazione preview
- creazione del file finale

### Home assistant del portale

Se Google Workspace e collegato, l'assistente operativo puo usare il tool di creazione documenti per richieste come:

- briefing operativi
- riepiloghi
- fogli di lavoro costruiti a partire da dati gia letti tramite tool reali

## Setup Google Cloud

Nel progetto Google Cloud del cliente:

1. abilita:
   - Google Docs API
   - Google Sheets API
   - Google Drive API
2. crea un OAuth Client di tipo `Web application`
3. imposta il redirect URI esatto

Per locale puro di sviluppo:

```text
http://localhost:8101/google-workspace/oauth/callback
```

Per ambienti reali il redirect URI deve coincidere con:

- `BACKEND_HUB_PUBLIC_URL + GOOGLE_WORKSPACE_REDIRECT_PATH`

## Variabili ambiente

```env
BACKEND_HUB_PUBLIC_URL=http://localhost:8101
GOOGLE_WORKSPACE_CLIENT_ID=...
GOOGLE_WORKSPACE_CLIENT_SECRET=...
GOOGLE_WORKSPACE_REDIRECT_PATH=/google-workspace/oauth/callback
GOOGLE_WORKSPACE_SCOPES=openid,https://www.googleapis.com/auth/userinfo.email,https://www.googleapis.com/auth/documents,https://www.googleapis.com/auth/spreadsheets,https://www.googleapis.com/auth/drive.file
GOOGLE_WORKSPACE_STATE_FILE=/data/google_workspace_state.json
GOOGLE_WORKSPACE_REQUEST_TIMEOUT_SECONDS=20
GOOGLE_WORKSPACE_SHEET_PREVIEW_MAX_ROWS=20
```

## Persistenza e limiti attuali

Lo stato OAuth e conservato nel file `GOOGLE_WORKSPACE_STATE_FILE`.

Questo approccio e accettabile per l'ambiente attuale del repository, ma ha limiti chiari:

- token conservati in chiaro
- modello single-account
- nessun audit trail completo
- nessuna gestione avanzata di permessi per utente

## Raccomandazioni per ambienti reali

Per un deploy piu robusto conviene evolvere verso:

- persistenza su database applicativo
- cifratura dei refresh token
- audit trail delle creazioni file
- permessi espliciti per tenant e utente

## Note operative

- il `folder ID` Drive puo essere incollato direttamente nella pagina `Documenti`
- il contenuto finale del file viene generato lato server, non hardcodato nel frontend
- quando la richiesta passa dalla Home assistant, i dati reali del locale possono essere inclusi solo se gia recuperati dai tool corretti