# Estratto Piano Calendario e Task

Fonte: `docs/piano-integrazioni-lead-calendario.md` (22 aprile 2026)

## Scope estratto
Piano implementativo relativo a:
1. Visuale calendari Vue3 con task, categorie KPI, passaggi tra utenti e regole di accettazione.

## Stato attuale (as-is) - solo calendario/task
- Calendario oggi usato soprattutto per appuntamenti chat/voicebot via Google/Outlook (`calendar_event_id` su `customer_conversations`), ma senza modulo agenda operativo con task interni.
- Frontend Vue3 attivo (chat interna), ma FullCalendar non presente tra le dipendenze NPM correnti.

## Stream 3 - Visuale Calendari + Task

### 3.1 Modello dati proposto
- `calendar_task_categories`
    - `id`, `profile_id`, `name`, `slug`, `is_active`, timestamps
- `calendar_task_category_fields`
    - `id`, `category_id`, `key`, `label`, `type`, `is_required`, `options_json`, `sort_order`, `is_active`, timestamps
- `calendar_tasks`
    - `id`, `profile_id`, `creator_user_id`, `owner_user_id`, `title`, `duration_minutes`, `category_id`, `starts_at`, `ends_at`, `linked_event_provider`, `linked_event_ref`, `requires_acceptance`, `status`, timestamps
- `calendar_task_field_values`
    - `id`, `task_id`, `category_field_id`, typed values, timestamps
- `calendar_task_transfers`
    - `id`, `task_id`, `from_user_id`, `to_user_id`, `requested_by_user_id`, `status`, `requires_acceptance`, `approved_by_user_id`, `decided_at`, timestamps
- `user_task_permissions` (o setting equivalente)
    - es. `can_bypass_task_transfer_acceptance`
- Nuovo setting profilo:
    - `seller_can_view_other_sellers_calendars` (boolean)

### 3.2 Regole business principali
- Admin:
    - crea task per tutti.
    - vede tutti i calendari dell'account.
    - configura categorie task e campi extra.
    - configura se serve accettazione nei passaggi tra seller.
- Seller:
    - crea solo task propri.
    - vede solo proprio calendario (o anche altri seller se setting attivo).
    - puo' passare task ad altro seller, con flusso accettazione in base alle regole.
- Bypass:
    - utente con permission specifica puo' eseguire trasferimenti auto-accettati.

### 3.3 Frontend
- Vue3 + `@fullcalendar/vue3` (day grid + time grid + interaction).
- Nuovo entrypoint Vite dedicato pagina calendario.
- Sidebar/pannello dettaglio evento-task con:
    - nome, durata, categoria
    - campi custom categoria
    - owner, stato, storico trasferimenti

### 3.4 Integrazione calendario provider
- MVP: eventi provider letti live per range data (Google/Outlook) + overlay task locali.
- Possibile fase 2: mirror locale eventi esterni per performance/storico.

## Permessi (solo calendario/task)
- `ADMIN`: full CRUD task cross-user + policy accettazione.
- `SELLER_MANAGER`: CRUD task propri; trasferimento secondo regole; visibilita' calendari da setting.

## Rischi tecnici principali (solo calendario/task)
- Race condition su passaggi task (doppia accettazione/rifiuto concorrente).
- Costi/performance nel fetch multi-calendario provider.
- Timezone e allineamento durata slot/eventi.

## Roadmap consigliata (solo calendario/task)
1. Modulo calendario Vue3 con sola visualizzazione + task propri.
2. Trasferimenti task + accettazione + bypass permission.
3. Hardening e test regressione focalizzati sui flussi calendario/task.

## Strategia test (solo calendario/task)
- Feature:
    - ACL su CRUD task.
    - trasferimento task con/without accettazione e bypass.
    - visibilita' calendari admin/seller in base a setting profilo.
- Unit:
    - motore decisionale trasferimento task.

## Decisioni confermate (solo calendario/task)
1. Nel passaggio task seller->seller con accettazione richiesta, approva il destinatario.
2. Bypass configurabile per utente singolo, con supporto azione massiva "seleziona tutti".
3. Notifiche richieste via email per passaggio task / richiesta accettazione.
4. KPI task rinviati a fase successiva post-integrazione (fuori scope MVP).
5. Task solo se collegati a evento; niente task standalone nel perimetro attuale.

## Impatti immediati sul piano (solo calendario/task)
- Stream 3 (Calendari/Task):
    - workflow trasferimento con stato `pending_acceptance` e decisione del destinatario.
    - gestione permission bypass a livello user-specific con utility bulk apply ("seleziona tutti").
    - progettare task vincolati a evento (`linked_event_ref` obbligatorio a livello validazione).
- Notifiche:
    - prevedere email template per: richiesta accettazione task, task trasferito, task accettato/rifiutato.

## Spec vincolante v1 (anti-improvvisazione agent)

### 1) State machine trasferimento task
- Stati ammessi per `calendar_task_transfers.status`:
    - `pending_acceptance`
    - `accepted`
    - `rejected`
    - `cancelled`
- Transizioni valide:
    - `create transfer` -> `pending_acceptance`
    - `accept` (solo destinatario) -> `accepted`
    - `reject` (solo destinatario) -> `rejected`
    - `cancel` (solo richiedente o admin) -> `cancelled` (solo da `pending_acceptance`)
- Regole di coerenza:
    - `accept` aggiorna anche `calendar_tasks.owner_user_id = to_user_id`.
    - `decided_at` e `approved_by_user_id` valorizzati solo su `accepted`/`rejected`.
    - ogni azione su transfer non `pending_acceptance` deve rispondere `409 Conflict` (idempotenza forte).
    - non e ammesso piu di un transfer `pending_acceptance` per lo stesso task.

### 2) ACL precedence (ordine vincolante)
- Regola 1 (hard deny): mai consentite operazioni cross-`profile_id`.
- Regola 2: `ADMIN` puo gestire task e trasferimenti di tutti gli utenti del proprio `profile_id`.
- Regola 3: `SELLER_MANAGER` puo creare/modificare solo task di cui e owner o creator (salvo takeover admin).
- Regola 4: visibilita calendari seller:
    - se `seller_can_view_other_sellers_calendars = false` -> solo proprio calendario;
    - se `true` -> calendari seller dello stesso `profile_id`.
- Regola 5: bypass trasferimento:
    - se `can_bypass_task_transfer_acceptance = true`, il trasferimento chiude direttamente in `accepted`;
    - altrimenti segue il flusso `pending_acceptance`.
- In caso di conflitto tra regole, prevale sempre il `deny` piu restrittivo.

### 3) Contratto vincolo evento (`linked_event_*`)
- `calendar_tasks` richiede sempre:
    - `linked_event_provider` in enum: `google`, `outlook`
    - `linked_event_ref` non vuoto (id evento provider)
- Validazioni minime creazione task:
    - provider supportato;
    - evento esistente sul provider per il `profile_id` corrente;
    - `starts_at` e `ends_at` coerenti con evento provider al momento della creazione.
- Se l'evento provider non risulta piu disponibile in lettura:
    - il task resta non eliminato;
    - API task deve restituire flag `is_orphaned = true`;
    - sono bloccati nuovi trasferimenti finche non viene rilinkato o chiuso.

### 4) Vincoli DB e indici minimi
- FK obbligatorie su tutte le colonne `_id` del modello proposto.
- Unique:
    - `calendar_task_categories`: (`profile_id`, `slug`)
    - `calendar_task_category_fields`: (`category_id`, `key`)
- Indici:
    - `calendar_tasks`: (`profile_id`, `owner_user_id`, `starts_at`)
    - `calendar_tasks`: (`profile_id`, `starts_at`, `ends_at`)
    - `calendar_tasks`: (`linked_event_provider`, `linked_event_ref`)
    - `calendar_task_transfers`: (`task_id`, `status`, `created_at`)
- Contesa transfer pending:
    - enforcement applicativo in transazione con lock pessimista sul task (`SELECT ... FOR UPDATE`) prima di creare transfer.

### 5) Contratto timezone
- Timezone applicativa unica in v1: `Europe/Rome` (non configurabile per utente o profilo).
- Persistenza DB sempre in UTC.
- API datetime in ISO-8601:
    - input senza offset interpretato come `Europe/Rome`;
    - output esposto in `Europe/Rome` per coerenza UI.
- Range giornalieri/settimanali calcolati in `Europe/Rome` e convertiti in UTC lato query.
- FullCalendar renderizza forzatamente in `Europe/Rome`.
- Casi DST (cambio ora) coperti nei test.

### 5.1 Evoluzione futura (internazionalizzazione)
- Aggiunta `timezone` a livello `profiles` (ed eventualmente `users`) con fallback `Europe/Rome`.
- Nessuna migrazione dati temporali necessaria se UTC resta il formato di persistenza.
- Adeguamento principale su validazione input, serializzazione output e rendering frontend.

### 6) Contratto API minimo (routes `webapi.php`)
- `GET /webapi/calendar/tasks?from=...&to=...&owner_ids[]=...`
    - ritorna task locali + metadati transfer + flag `is_orphaned`.
- `POST /webapi/calendar/tasks`
    - crea task vincolato a evento (`linked_event_*` obbligatori).
- `PATCH /webapi/calendar/tasks/{task}`
    - aggiorna dati consentiti secondo ACL.
- `POST /webapi/calendar/tasks/{task}/transfers`
    - crea trasferimento (auto-accept se bypass).
- `POST /webapi/calendar/task-transfers/{transfer}/accept`
- `POST /webapi/calendar/task-transfers/{transfer}/reject`
- HTTP status vincolanti:
    - `403` ACL
    - `404` task/transfer non nel profilo
    - `409` transizione non valida o transfer gia deciso
    - `422` payload o vincolo evento non valido

### 7) Criteri minimi di accettazione test (non negoziabili)
- Feature:
    - seller senza setting visibilita vede solo proprio calendario.
    - seller con setting visibilita vede solo seller del proprio `profile_id`.
    - creazione task senza `linked_event_ref` -> `422`.
    - transfer standard crea `pending_acceptance`; accept aggiorna owner; reject non aggiorna owner.
    - utente con bypass crea transfer direttamente `accepted`.
    - seconda accept/reject sullo stesso transfer -> `409`.
    - blocco cross-profile su tutte le endpoint -> `403` o `404` coerente.
    - task `is_orphaned = true` blocca nuovo transfer -> `422`.
- Unit:
    - motore decisionale ACL precedence.
    - motore state machine transfer (tabella transizioni valide/non valide).