From 20212d184bcca9ad6dc8495049eacb3a96b41954 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gabriele=20Vigan=C3=B2?= Date: Thu, 20 Aug 2026 00:43:17 +0200 Subject: [PATCH 1/6] docs: add PRD and feature/roadmap report Adds the v0.3 admin dashboard PRD and a feature/roadmap report to serve as a shared starting point for planning next steps. --- PRD_Admin_Dashboard_PoliNetwork_v0.3.md | 484 ++++++++++++++++++++++ REPORT_FEATURE_E_ROADMAP.md | 530 ++++++++++++++++++++++++ 2 files changed, 1014 insertions(+) create mode 100644 PRD_Admin_Dashboard_PoliNetwork_v0.3.md create mode 100644 REPORT_FEATURE_E_ROADMAP.md diff --git a/PRD_Admin_Dashboard_PoliNetwork_v0.3.md b/PRD_Admin_Dashboard_PoliNetwork_v0.3.md new file mode 100644 index 0000000..1e82cc1 --- /dev/null +++ b/PRD_Admin_Dashboard_PoliNetwork_v0.3.md @@ -0,0 +1,484 @@ +# Admin Dashboard PoliNetwork + +**Documento di specifica funzionale per il Team IT** +**Versione:** 0.3 +**Data:** 20 agosto 2026 +**Stato:** Bozza per revisione +**Modifiche rispetto alla v0.2:** riordino delle priorità (interno prima di esterno), aggiunta di modello dati, ruoli e permessi, macchine a stati, criteri di accettazione e decisioni tecniche proposte. + +--- + +## 1. Scopo e principi + +### 1.1 Obiettivo + +Portare dentro un'unica piattaforma i processi oggi distribuiti tra form, fogli Excel, email, gruppi e operazioni manuali, mantenendo ogni area modulare e sviluppabile in modo indipendente. + +### 1.2 Principio di priorità: interno prima di esterno + +La v0.2 metteva l'Area Associazioni Partner come feature n.1. Questa versione la sposta in Fase 2. Motivi: + +1. **Dipendenza tecnica.** L'area partner richiede autenticazione multi-tenant, ruoli con scope, flussi di approvazione, gestione allegati e pagine pubbliche. Sono tutti pezzi che vanno costruiti comunque per l'uso interno: costruirli prima per l'interno e poi riusarli per i partner riduce il lavoro complessivo. +2. **Dipendenza organizzativa.** L'area partner ha utenti esterni: un bug, un dato sbagliato o un downtime diventano subito un problema di immagine. L'interno è un ambiente tollerante in cui rodare la piattaforma. +3. **Ritorno immediato.** Anagrafica, rinnovi e onboarding eliminano lavoro manuale che oggi ricade su Direttivo, HR e Capi Admin ogni settimana. +4. **Prerequisito di dati.** Le associazioni partner vanno collegate a referenti, ruoli e permessi che esistono solo se l'anagrafica interna è già in piedi. + +Il PoliTamTam resta la feature esterna a priorità più alta ed è la prima cosa che si sviluppa una volta chiusa la Fase 1. + +### 1.3 Principi di progetto + +- **Un'unica fonte di verità per le persone.** Ogni persona esiste una volta sola nel sistema; ruoli, tesseramento e appartenenze sono attributi collegati, non copie. +- **Permessi per capability, non per ruolo hardcoded.** Il codice controlla permessi; i ruoli sono insiemi di permessi configurabili. +- **Ogni scrittura è tracciata.** Audit log append-only su tutte le azioni che modificano dati o inviano comunicazioni. +- **Ogni invio automatico è idempotente.** Nessuna email deve poter partire due volte per lo stesso evento. +- **Modularità.** Ogni area è un modulo attivabile/disattivabile, con proprie tabelle e propri permessi. +- **Minimizzazione dei dati.** Si raccoglie solo ciò che serve a un processo descritto in questo documento. + +--- + +## 2. Fondamenta (Fase 0 — prerequisito di tutto) + +Non è una feature visibile, ma è la parte da cui dipendono tutte le altre. Va sviluppata per prima e in modo definitivo. + +### 2.1 Identità e autenticazione + +**Decisione proposta (da confermare con il Team IT):** + +- **Utenti interni** (soci, admin, capi admin, team, direttivo): SSO tramite Google Workspace PoliNetwork (OIDC), account `@polinetwork.org`. Nessuna password gestita dalla dashboard. +- **Utenti partner** (Fase 2): account applicativi con email `@polinetwork.org` dedicata all'associazione, login con magic link via email + sessione a scadenza. Nessuna password da ricordare, nessun reset da gestire manualmente. +- **Sessioni:** durata 30 giorni per gli interni, 7 giorni per i partner, revocabili singolarmente dal superadmin. +- **2FA:** obbligatoria (tramite Google) per superadmin e Direttivo. + +**Requisiti minimi in ogni caso:** + +- creazione, sospensione, riattivazione e disattivazione di un account senza cancellare i dati storici; +- cambio del referente di un account senza perdere lo storico delle azioni; +- possibilità futura di più referenti per la stessa entità (associazione, team, corso); +- pannello centralizzato per PoliNetwork con elenco account, ultimo accesso, stato, ruoli. + +### 2.2 Ruoli e permessi + +Ogni assegnazione di ruolo ha uno **scope**: globale, corso di studi, team o associazione. + +| Ruolo | Scope | Descrizione | +|---|---|---| +| `superadmin` | globale | Team IT. Accesso completo, gestione account e configurazioni. | +| `direttivo` | globale | Visione su soci, tesseramenti, approvazioni, statistiche. | +| `hr` | globale | Gestione candidature e onboarding. | +| `capo_admin` | corso di studi | Vede e gestisce admin e gruppi del proprio corso. | +| `admin` | corso di studi | Vede i propri dati e i gruppi di cui fa parte. | +| `team_lead` | team | Gestisce l'area del proprio team e i suoi membri. | +| `team_member` | team | Accede all'area del proprio team. | +| `socio` | personale | Vede e aggiorna il proprio profilo e il proprio stato associativo. | +| `partner_referente` | associazione | Fase 2. Gestisce l'area della propria associazione. | + +Regole: + +- una persona può avere più ruoli contemporaneamente, anche su scope diversi; +- i permessi sono l'unione dei permessi dei ruoli attivi; +- ogni ruolo ha `valido_da` e `valido_a`, così lo storico resta consultabile; +- il permesso è sempre verificato lato server, mai solo nascondendo un elemento nell'interfaccia. + +### 2.3 Modello dati minimo + +**`persona`** — anagrafica unica +`id`, `nome`, `cognome`, `email_personale`, `email_polinetwork`, `telefono`, `telegram_username`, `telegram_id`, `data_nascita`, `corso_di_studi_id`, `anno_corso`, `data_ingresso`, `data_uscita`, `stato` (`attivo` | `sospeso` | `uscito`), `is_rappresentante`, `note`, `creato_il`, `aggiornato_il` + +**`altra_associazione`** — appartenenze esterne dichiarate +`id`, `persona_id`, `nome_associazione`, `ruolo`, `dal`, `al` + +**`ruolo_assegnato`** +`id`, `persona_id`, `ruolo`, `scope_type` (`globale` | `corso` | `team` | `associazione`), `scope_id`, `valido_da`, `valido_a`, `assegnato_da` + +**`corso_di_studi`** +`id`, `nome`, `codice`, `sede`, `livello` (triennale/magistrale/ciclo unico), `attivo` + +**`team`** +`id`, `nome`, `slug`, `descrizione`, `lead_persona_id`, `attivo` + +**`tesseramento`** +`id`, `persona_id`, `anno_associativo`, `data_iscrizione`, `data_scadenza`, `stato`, `importo`, `metodo_pagamento`, `verificato_da`, `verificato_il`, `note` + +**`gruppo_chat`** +`id`, `nome`, `piattaforma` (`whatsapp` | `telegram`), `link_invito`, `corso_di_studi_id`, `tipo` (corso, anno, generale, altro), `responsabile_persona_id`, `attivo`, `iscritti_stimati` + +**`candidatura`** (onboarding) +`id`, `nome`, `cognome`, `email`, `telefono`, `telegram_username`, `corso_di_studi_id`, `anno_corso`, `motivazione`, `disponibilita`, `stato`, `assegnata_a`, `creata_il`, `aggiornata_il`, `persona_id` (valorizzato all'approvazione) + +**`colloquio`** +`id`, `candidatura_id`, `intervistatore_persona_id`, `data_ora`, `luogo_o_link`, `esito`, `note` + +**`audit_log`** — append-only +`id`, `attore_persona_id`, `azione`, `entita_tipo`, `entita_id`, `dati_prima`, `dati_dopo`, `ip`, `timestamp` + +**`email_log`** — append-only +`id`, `tipo_email`, `destinatario_persona_id`, `destinatario_email`, `chiave_idempotenza`, `stato` (`inviata` | `fallita` | `bounce`), `provider_message_id`, `inviata_il`, `errore` + +`chiave_idempotenza` è univoca ed è costruita come `{tipo}:{persona_id}:{periodo}` — esempio: `compleanno:412:2026`. Questo è ciò che rende impossibile il doppio invio. + +Entità di Fase 2 (`associazione_partner`, `richiesta_pubblicazione`, `evento`, `movimento_credito`, `richiesta_modifica_pagina`) sono definite nella sezione 8. + +### 2.4 Sistema di invio email + +**Decisione proposta:** provider transazionale con API e webhook di delivery (Resend, Postmark o Amazon SES). Requisiti: + +- sottodominio dedicato per le transazionali, con SPF, DKIM e DMARC configurati, separato dal dominio usato per la newsletter, per non contaminare la reputazione di invio; +- template versionati nel repository, non nell'interfaccia del provider; +- ogni invio scrive su `email_log` prima di partire e aggiorna lo stato al webhook; +- job schedulati eseguiti una volta al giorno a orario fisso (proposta: 08:00 Europe/Rome), idempotenti, con recupero automatico dei giorni saltati; +- pagina di monitoraggio per il superadmin con invii recenti, fallimenti e bounce; +- ambiente di staging che scrive su `email_log` senza inviare realmente. + +### 2.5 Audit e privacy + +- Ogni azione che modifica dati o invia comunicazioni scrive su `audit_log`. +- Retention: dati dei soci conservati per la durata dell'appartenenza + 5 anni per obblighi associativi e fiscali; candidature non approvate cancellate dopo 12 mesi; log conservati 24 mesi. +- Ogni campo raccolto deve corrispondere a un processo descritto in questo documento. Campi senza processo non si raccolgono. +- Numero di telefono e contatto Telegram sono visibili solo a chi ha un ruolo con permesso esplicito (capo admin sul proprio corso, direttivo, HR), mai in elenchi pubblici o esportabili senza tracciamento. +- Ogni esportazione di dati personali (CSV) viene registrata su `audit_log` con attore, filtri applicati e numero di record. + +### 2.6 Criteri di accettazione Fase 0 + +- Un utente interno accede con account Google PoliNetwork e vede solo i moduli permessi dai propri ruoli. +- Un tentativo di accesso via API a una risorsa fuori dal proprio scope restituisce 403 e viene loggato. +- Il superadmin può assegnare, revocare e datare un ruolo e vedere lo storico delle assegnazioni. +- Un'email di test parte, compare in `email_log` e il rilancio manuale dello stesso job non produce un secondo invio. + +--- + +# Parte I — Feature interne (prioritarie) + +## 3. Anagrafica persone (Fase 1) + +Base di tutte le altre feature interne. Sostituisce i fogli Excel oggi in uso. + +### 3.1 Requisiti + +- Elenco unico delle persone di PoliNetwork con i campi della tabella `persona`. +- Scheda persona con: dati anagrafici, corso e anno, data di ingresso e anzianità calcolata, ruoli attivi e storici, team di appartenenza, altre associazioni, stato associativo corrente, storico delle azioni che la riguardano. +- Ogni persona può aggiornare autonomamente i propri dati di contatto (telefono, Telegram, email personale). Corso, anno di ingresso, ruoli e stato associativo sono modificabili solo da chi ha il permesso. +- Import iniziale da Excel con file di mappatura colonne, report degli scarti e possibilità di rieseguire l'import senza creare duplicati (chiave: email personale, con controllo manuale dei conflitti). +- Ricerca full-text su nome, cognome, email e username Telegram. + +### 3.2 Criteri di accettazione + +- L'import dei fogli attuali produce zero duplicati e un report leggibile degli scarti. +- Modificare il numero di telefono dal proprio profilo aggiorna il dato visto dal Capo Admin senza altri passaggi. +- L'anzianità è sempre calcolata da `data_ingresso`, mai inserita a mano. + +--- + +## 4. Dashboard Admin e Capo Admin (Fase 1) + +### 4.1 Vista Capo Admin + +Il Capo Admin vede l'elenco degli admin del **proprio corso di studi**, con: + +- nome e cognome; +- anno di corso; +- data di ingresso in PoliNetwork e anzianità; +- indicazione se è rappresentante; +- altre associazioni di cui fa parte; +- numero di telefono; +- username o contatto Telegram; +- stato associativo (attivo / in scadenza / scaduto); +- pulsanti di contatto rapido: `wa.me/{telefono}` e `t.me/{username}`, aperti in nuova scheda. + +### 4.2 Filtri e ricerca + +- ricerca testuale per nome e cognome; +- filtro per anno di corso; +- filtro per rappresentante sì/no; +- filtro per appartenenza ad altre associazioni (presenza o nome specifico); +- filtro per stato associativo; +- ordinamento per cognome, anno, data di ingresso; +- esportazione CSV del risultato filtrato, tracciata su `audit_log`. + +### 4.3 Link dei gruppi + +Sezione con i gruppi WhatsApp e Telegram di competenza del Capo Admin: nome, piattaforma, corso, tipo, link di invito con copia rapida, responsabile, stato attivo/archiviato. + +Il Capo Admin può proporre l'aggiunta o la modifica di un link; la modifica diventa effettiva dopo conferma di un superadmin (i link di invito sono dati sensibili per lo spam). + +### 4.4 Regole di visibilità + +- `capo_admin` vede esclusivamente persone e gruppi con `corso_di_studi_id` incluso nel proprio scope; può avere più corsi assegnati. +- `admin` vede solo la propria scheda e i gruppi di cui fa parte. +- `direttivo` e `superadmin` vedono tutti i corsi. +- Il tentativo di accedere a una persona fuori scope produce 403, non una lista vuota. + +### 4.5 Criteri di accettazione + +- Un Capo Admin con due corsi assegnati vede l'unione dei due e nient'altro. +- Il link WhatsApp precompilato apre correttamente la chat con il numero in formato internazionale. +- Cambiare il corso di una persona la fa sparire immediatamente dalla vista del vecchio Capo Admin. + +--- + +## 5. Gestione Soci e Rinnovi (Fase 1) + +### 5.1 Stati del tesseramento + +`tesseramento.stato` assume esclusivamente questi valori: + +| Stato | Significato | +|---|---| +| `attivo` | Tesseramento valido, non ancora in finestra di rinnovo. | +| `in_scadenza` | Entro N giorni dalla scadenza. Il reminder automatico è partito o sta per partire. | +| `sollecitato` | Almeno un reminder inviato dopo la scadenza. | +| `da_verificare` | Il socio dichiara di aver pagato, il Direttivo non ha ancora confermato. | +| `pagato` | Pagamento confermato dal Direttivo. Genera il nuovo tesseramento attivo. | +| `scaduto` | Scadenza superata senza rinnovo oltre la finestra di tolleranza. | + +**Parametri configurabili** (valori proposti): primo reminder 30 giorni prima della scadenza; secondo reminder 7 giorni prima; terzo il giorno della scadenza; tolleranza 30 giorni prima del passaggio a `scaduto`. + +### 5.2 Rinnovo automatico via email + +- Job giornaliero che seleziona i tesseramenti in finestra di reminder e invia la mail di rinnovo. +- La mail contiene: scadenza, importo, istruzioni di pagamento secondo il processo associativo vigente, link alla propria pagina di stato nella dashboard. +- In questa versione **il pagamento non avviene nella dashboard**. La dashboard registra e verifica, non incassa. +- Ogni invio è protetto da `chiave_idempotenza` (`rinnovo_r1:{persona_id}:{anno}`), quindi il rilancio del job non genera duplicati. + +### 5.3 Vista Direttivo + +Tabella dei soci filtrabile per stato, anno associativo, corso, team. Per ogni socio due azioni: + +**Segna come pagato** +Imposta `stato = pagato`, registra `verificato_da` e `verificato_il`, crea il tesseramento del nuovo anno, invia automaticamente la mail di conferma al socio, scrive su `audit_log`. + +**Invia reminder** +Invia una nuova mail di promemoria, registra l'invio su `email_log`, aggiorna `stato` a `sollecitato`. Limite: massimo un reminder manuale ogni 7 giorni per socio, per evitare invii ripetuti da più membri del Direttivo. + +Sulla scheda del socio è visibile lo storico: quando è stato inviato ogni reminder, chi ha confermato il pagamento e quando. + +### 5.4 Informazioni sul socio + +Nella scheda, dove utile: data di ingresso, anzianità, ruoli ricoperti (attuali e passati), team di appartenenza, corso di studi, stato associativo corrente e storico dei tesseramenti per anno. + +### 5.5 Criteri di accettazione + +- Un socio con scadenza tra 30 giorni riceve esattamente una mail, anche se il job viene eseguito due volte. +- "Segna come pagato" produce: stato aggiornato, mail di conferma inviata, riga di audit, nuovo tesseramento creato. +- Due membri del Direttivo che premono "Invia reminder" sullo stesso socio nello stesso giorno producono un solo invio. +- Il Direttivo può esportare l'elenco dei non in regola in CSV. + +--- + +## 6. Onboarding nuovi Admin (Fase 1) + +### 6.1 Premessa + +Il processo attuale è frammentato tra form, email, colloqui, fogli Excel e passaggi manuali. **Non va digitalizzato così com'è.** Prima dello sviluppo, HR e Team IT devono ridisegnare il flusso, eliminando i passaggi che esistono solo perché mancava uno strumento. + +Il flusso descritto qui è la proposta di riferimento da validare con HR. + +### 6.2 Pipeline della candidatura + +`ricevuta` → `in_screening` → `colloquio_da_programmare` → `colloquio_programmato` → `colloquio_effettuato` → `approvata` | `respinta` → `onboarding_in_corso` → `completata` + +Stati aggiuntivi: `ritirata` (il candidato rinuncia), `in_attesa` (rimandata a una tornata successiva). + +### 6.3 Requisiti + +- **Form di candidatura pubblico** servito dalla dashboard, che scrive direttamente su `candidatura`. Nessun Google Form. +- **Board delle candidature** per HR: colonne per stato, assegnazione a un referente, filtri per corso e tornata. +- **Gestione colloquio**: registrazione di data, ora, luogo o link, intervistatore, esito e note. Invio automatico della convocazione al candidato e del promemoria il giorno prima. +- **Approvazione**: alla transizione ad `approvata`, il sistema crea la `persona` collegata, imposta `data_ingresso`, assegna corso, ruolo `admin` e gli eventuali team, e invia la mail di benvenuto con i passi successivi. +- **Checklist di ingresso operativo** con voci configurabili (esempi: account `@polinetwork.org` creato, inserito nei gruppi di competenza, formazione iniziale svolta, tesseramento avviato). La candidatura passa a `completata` solo quando la checklist è chiusa. +- **Comunicazione al candidato**: ogni cambio di stato rilevante genera una mail automatica; l'esito negativo usa un template dedicato con invio manuale confermato da HR. + +### 6.4 Criteri di accettazione + +- Da candidatura ad admin operativo non serve nessuno strumento esterno alla dashboard oltre alla creazione dell'account Google. +- L'approvazione crea la persona senza reinserimento manuale dei dati già raccolti dal form. +- HR vede in ogni momento quante candidature sono ferme in ciascuno stato e da quanti giorni. + +--- + +## 7. Aree Team (Fase 1, struttura — Fase 3, contenuti) + +### 7.1 Team previsti + +Team IT, Team Design & Social, Team International, Team HR, Team Events & Partnerships. + +### 7.2 Cosa si sviluppa ora + +Solo l'impalcatura, identica per tutti i team: + +- pagina del team con elenco membri, ruoli interni e lead; +- permessi: `team_member` vede l'area, `team_lead` gestisce membri e contenuti; +- spazio per note e documenti condivisi del team; +- bacheca annunci interna al team; +- struttura a moduli che permette di aggiungere strumenti specifici in seguito senza toccare le altre aree. + +### 7.3 Cosa non si sviluppa ora + +Gli strumenti specifici di ciascun team. Vanno definiti separatamente con i rispettivi responsabili, dopo che la struttura è in produzione e i team la stanno effettivamente usando. + +### 7.4 Criteri di accettazione + +- Aggiungere un nuovo team è un'operazione di configurazione, non di sviluppo. +- Un membro di un team non vede le aree degli altri team se non ha ruoli su di essi. + +--- + +## 8. Email automatiche di compleanno (Fase 1) + +- Job giornaliero che seleziona le persone con `data_nascita` corrispondente alla data odierna e `stato = attivo` **e tesseramento valido** (la feature riguarda esclusivamente i soci). +- Invio di una mail di auguri da parte di PoliNetwork. Solo email: nessuna integrazione Telegram in questa fase. +- Idempotenza tramite chiave `compleanno:{persona_id}:{anno}`. +- Gestione del 29 febbraio: negli anni non bisestili l'invio avviene il 28 febbraio. +- Opt-out individuale disponibile nel profilo del socio. +- Se il job non gira in un dato giorno, all'esecuzione successiva recupera i compleanni saltati degli ultimi 3 giorni. + +**Criterio di accettazione:** rilanciare il job tre volte nello stesso giorno produce un solo invio per persona. + +--- + +# Parte II — Feature esterne + +## 9. Area Associazioni Partner (Fase 2) + +Prima area rivolta a utenti esterni. Si sviluppa dopo la Fase 1 e riusa autenticazione, ruoli, flussi di approvazione e sistema email già costruiti. + +### 9.1 Entità + +**`associazione_partner`** +`id`, `nome`, `slug`, `email_polinetwork`, `descrizione`, `logo_url`, `sito_web`, `instagram`, `linkedin`, `altri_link` (JSON), `contatti_pubblici`, `stato` (`attiva` | `sospesa` | `archiviata`), `crediti_disponibili`, `data_convenzione`, `data_rinnovo` + +**`referente_partner`** +`id`, `associazione_id`, `persona_o_contatto`, `email`, `ruolo`, `attivo` +Struttura predisposta fin da subito per più referenti per associazione, anche se in v1 se ne usa uno. + +**`richiesta_pubblicazione`** +`id`, `associazione_id`, `testo`, `allegati` (JSON), `link`, `gruppi_destinatari` (JSON), `data_richiesta`, `data_pubblicazione_desiderata`, `stato`, `crediti_costo`, `revisore_persona_id`, `motivo_rifiuto`, `pubblicata_il` + +**`evento`** +`id`, `associazione_id`, `titolo`, `descrizione`, `data_inizio`, `data_fine`, `luogo`, `link_online`, `link_iscrizione`, `immagine_url`, `stato`, `data_rimozione`, `revisore_persona_id`, `motivo_rifiuto` + +**`richiesta_modifica_pagina`** +`id`, `associazione_id`, `campi_modificati` (JSON con valore precedente e nuovo), `stato`, `richiesta_da`, `revisore_persona_id`, `motivo_rifiuto` + +**`movimento_credito`** +`id`, `associazione_id`, `delta`, `causale`, `richiesta_id`, `saldo_risultante`, `creato_da`, `creato_il` + +### 9.2 Accesso e gestione degli account + +- PoliNetwork crea per ogni associazione partner un indirizzo `@polinetwork.org` dedicato, usato come identità di accesso. +- Login tramite magic link inviato a quell'indirizzo (vedi 2.1). Non ci sono password da recuperare. +- Il superadmin può: creare, sospendere, riattivare e archiviare un account; cambiare il referente mantenendo lo storico; vedere l'ultimo accesso di ogni associazione. +- Il cambio di referente non cancella nulla: le richieste passate restano attribuite all'associazione, non alla persona. +- La soluzione deve reggere ordinatamente **decine di associazioni**: nessuna configurazione manuale per associazione oltre alla creazione dell'account. + +### 9.3 Richieste di pubblicazione nei gruppi + +**Stati:** `bozza` → `inviata` → `in_revisione` → `approvata` → `programmata` → `pubblicata`, con uscite `respinta` e `annullata`. + +Il partner compila: testo del messaggio, gruppi o insiemi di gruppi destinatari, allegati o link, data di pubblicazione desiderata. Vede lo stato della richiesta e lo storico completo delle richieste precedenti. + +PoliNetwork revisiona, approva o respinge indicando il motivo. La pubblicazione effettiva nei gruppi in v1 è **manuale**: la dashboard produce il messaggio pronto e traccia lo stato. L'invio automatizzato verso Telegram/WhatsApp è fuori scope della v1 e va valutato separatamente (le API WhatsApp per i gruppi hanno vincoli rilevanti). + +**Sistema a crediti (proposta da validare):** + +- ogni associazione ha un saldo crediti; +- costo definito per invio, con moltiplicatore per numero di gruppi destinatari; +- i crediti si scalano **all'approvazione**, non all'invio della richiesta; una richiesta respinta non costa nulla; +- ricarica o rinnovo periodico impostato dal superadmin, con data di rinnovo visibile al partner; +- ogni movimento è registrato su `movimento_credito` e visibile al partner come estratto conto; +- il partner vede sempre: crediti disponibili, crediti utilizzati nel periodo, data del prossimo rinnovo. + +Se il Direttivo decide di non usare i crediti, il modulo resta disattivabile via configurazione senza rimuovere il codice. + +### 9.4 Pagina pubblica dell'associazione + +Ogni associazione ha una pagina pubblica sul sito PoliNetwork. Dalla dashboard il partner **richiede** modifiche a: nome e informazioni principali, descrizione, logo, sito web, Instagram, LinkedIn, altri social, contatti pubblici. + +Le modifiche non vanno mai in diretta: passano da `richiesta_modifica_pagina` con approvazione di PoliNetwork. Il revisore vede un confronto prima/dopo campo per campo e può approvare parzialmente. + +### 9.5 Eventi delle associazioni — nuovo PoliTamTam + +Evoluzione del PoliTamTam: punto unico in cui raccogliere e mostrare gli eventi delle associazioni sulla pagina eventi del sito PoliNetwork. + +**Stati:** `bozza` → `in_approvazione` → `pubblicato` → `concluso` → `archiviato`, con uscita `respinto`. + +**Decisione proposta:** gli eventi passano da approvazione di PoliNetwork prima della pubblicazione, coerentemente con il controllo editoriale sul sito. Eccezione configurabile: associazioni con status "verificato" pubblicano direttamente, con revisione a posteriori. Da confermare con il Team IT e il Direttivo. + +Regole aggiuntive: + +- rimozione automatica dalla pagina pubblica dopo `data_fine` (o dopo `data_rimozione` se valorizzata), con passaggio a `concluso`; +- gli eventi conclusi restano consultabili nell'archivio interno; +- il partner può modificare un evento già pubblicato solo su campi non critici (descrizione, immagine, link iscrizione); modifiche a data, luogo o titolo rientrano in approvazione; +- immagini validate per formato e dimensione massima, servite ridimensionate. + +### 9.6 Criteri di accettazione Fase 2 + +- Un'associazione accede, inserisce un evento e lo vede sul sito entro un'approvazione, senza email a PoliNetwork. +- Una richiesta respinta non consuma crediti e mostra al partner il motivo del rifiuto. +- Un'associazione non vede in nessun modo dati di altre associazioni. +- Un evento concluso sparisce dalla pagina pubblica senza intervento manuale. + +--- + +# Parte III — Feature secondarie (Fase 3+) + +Utili, ma non devono ritardare le fasi precedenti. Ognuna richiede una progettazione dedicata prima dello sviluppo. + +## 10. Area Aziende + +Pubblicazione di annunci di lavoro e stage. Eventuale consultazione dei CV dei membri **solo** con consenso esplicito, revocabile, per singola azienda o per categoria, e con tracciamento di ogni accesso al CV. Senza un modello privacy approvato, la parte CV non si sviluppa. + +## 11. Area Proprietari di casa + +Area per la pubblicazione di annunci di affitto o vendita di camere e appartamenti. Richiede: verifica dell'identità dell'inserzionista, moderazione degli annunci, scadenza automatica, gestione delle segnalazioni. + +## 12. Bacheca ricerca casa e coinquilini + +Annunci di ricerca stanza/appartamento, ricerca coinquilini e affini, riservata agli utenti autenticati. Richiede moderazione e scadenza automatica degli annunci. + +## 13. Newsletter + +Non deve bloccare la v1. In futuro riusa i dati già in piattaforma, in particolare gli eventi inseriti dalle associazioni partner, per comporre i contenuti. Modello editoriale, flusso di approvazione e provider di invio da definire in seguito. **Vincolo tecnico:** dominio o sottodominio di invio separato da quello delle email transazionali (vedi 2.4). + +--- + +## 14. Riepilogo delle fasi + +| Fase | Contenuto | Dipendenze | +|---|---|---| +| **0 — Fondamenta** | Auth, ruoli e permessi, modello dati, audit log, sistema email | Nessuna | +| **1 — Interno** | Anagrafica, Dashboard Admin/Capo Admin, Soci e Rinnovi, Onboarding, struttura Aree Team, compleanni | Fase 0 | +| **2 — Partner** | Account partner, PoliTamTam, richieste di pubblicazione, pagina pubblica, crediti | Fase 1 | +| **3 — Estensioni** | Strumenti specifici dei team, Aziende, Casa, Bacheca, Newsletter | Fase 2 | + +L'ordine indica dipendenze, non date. Le stime temporali vanno fatte dal Team IT sulla base della capacità effettiva. + +--- + +## 15. Fuori scope della v1 + +Da dichiarare esplicitamente per evitare aspettative: + +- pagamento delle quote direttamente in dashboard; +- invio automatizzato di messaggi verso gruppi WhatsApp e Telegram; +- integrazione Telegram per gli auguri di compleanno; +- app mobile; +- consultazione CV da parte delle aziende; +- newsletter. + +--- + +## 16. Decisioni ancora aperte + +Vanno chiuse prima dell'inizio dello sviluppo della fase corrispondente. + +| # | Decisione | Chi decide | Blocca | +|---|---|---|---| +| 1 | Conferma di Google Workspace come IdP per gli interni | Team IT | Fase 0 | +| 2 | Scelta del provider email transazionale | Team IT | Fase 0 | +| 3 | Stack e hosting della piattaforma | Team IT | Fase 0 | +| 4 | Parametri dei reminder di rinnovo (giorni e tolleranza) | Direttivo | Fase 1 | +| 5 | Ridisegno del flusso di onboarding | HR + Team IT | Fase 1 | +| 6 | Contenuto dei template email (rinnovo, conferma, benvenuto, compleanno) | Direttivo + Design & Social | Fase 1 | +| 7 | Uso o meno del sistema a crediti e relativo listino | Direttivo | Fase 2 | +| 8 | Approvazione preventiva o pubblicazione diretta degli eventi partner | Direttivo + Team IT | Fase 2 | +| 9 | Modello privacy per la consultazione dei CV | Direttivo | Fase 3 | diff --git a/REPORT_FEATURE_E_ROADMAP.md b/REPORT_FEATURE_E_ROADMAP.md new file mode 100644 index 0000000..3e65b81 --- /dev/null +++ b/REPORT_FEATURE_E_ROADMAP.md @@ -0,0 +1,530 @@ +# PoliNetwork Admin — report feature e roadmap + +Data analisi: 19 agosto 2026 +Repository analizzato: `admin`, branch `main` + +## Sintesi esecutiva + +Il progetto è una buona base per una console operativa: autenticazione con passkey, collegamento Telegram, ruoli, server functions protette, dashboard React/TanStack Start, gestione Telegram, Microsoft 365 e contenuti web. Oggi però è soprattutto un pannello tecnico diviso per integrazione; non è ancora il sistema centrale per gestire l’associazione. + +Il vuoto più importante è il censimento. `Azure members` oggi rappresenta utenti Entra/Microsoft 365 con un numero associativo, mentre `Telegram users` rappresenta profili Telegram: manca un’anagrafica associativa canonica che colleghi persona, iscrizione, rinnovo, consensi, ruoli, team, attività e identità esterne. Anche la home è un indice di link statici, non un centro di controllo: non mostra KPI, scadenze, anomalie, attività recenti o cose da fare. + +La direzione consigliata è: + +1. stabilizzare la base tecnica e separare lettura/scrittura; +2. costruire il censimento come dominio principale; +3. trasformare la home in una command center con alert e workflow; +4. collegare Telegram, Azure e sito alla scheda unica del socio; +5. aggiungere governance, comunicazioni, contenuti e operatività interna. + +## Stato attuale verificato + +### Stack e fondamenta + +- React 19, TanStack Start/Router, Vite, Nitro, Tailwind CSS v4 e shadcn/ui (`README.md`). +- Backend tipizzato tramite tRPC e `@polinetwork/backend` (`src/lib/api/types.ts`). +- Server functions con middleware di sessione e autorizzazione (`src/server/auth.middleware.ts:51-66`). +- Autenticazione con Better Auth, passkey, sessioni attive e link Telegram (`src/features/account`, `src/features/onboarding`). +- Validazione Zod, toast, conferme sulle azioni distruttive, optimistic update in alcune pagine e test di sicurezza (`tests/server-security.test.mjs`). + +### Moduli presenti + +| Area | Cosa esiste oggi | Gap principale | +| --- | --- | --- | +| Overview | Sei card di accesso alle aree operative (`src/features/dashboard/overview-page.tsx:6-119`) | Nessun dato aggregato, alert, task o stato integrazioni | +| Telegram users | Lista, ricerca, profilo, ruoli, amministratori di gruppo, messaggi recenti, audit Telegram, grant | Nessuna anagrafica associativa collegata; paginazione/search lato server assente | +| Telegram groups | Elenco, tag, invito, visibilità, uscita dal gruppo | Mancano ciclo di vita, ownership, health check, metriche e storico | +| Telegram grants | Grant attivi e programmati, creazione e interruzione | Nessuna vista storica/archivio, reminder o approvazione | +| Microsoft 365 members | Elenco utenti Entra, numero associativo, licenze visibili, creazione account | Non è un vero registro soci; licenze non gestibili dalla UI | +| Microsoft 365 groups | Elenco gruppi e aggiunta/rimozione membri | Nessun access review, owner, gruppo orfano o drift detection | +| Web associations | CRUD bilingue, logo e dieci link pubblici (`src/features/associations/associations-page.tsx:144-200`) | È il catalogo pubblico delle associazioni, non il censimento dei membri | +| Web projects | CRUD bilingue, categorie, logo, link e drag-and-drop | È contenuto pubblico, non project management interno | +| Freshman guide | Upload, versione, data, download e delete PDF | Manca workflow di bozza/approvazione, preview, storico editoriale e reminder | +| Account | Profilo, passkey, sessioni, identità Telegram e ruoli | Mancano preferenze, notifiche e centro sicurezza amministrativo | + +### Capacità del backend già sfruttabili + +Il contratto tRPC installato espone già alcune superfici che non sono ancora raggiunte dalla navigazione della dashboard: + +- FAQ bilingui complete: categorie, creazione, modifica e cancellazione (`node_modules/@polinetwork/backend/dist/index.d.ts:1119-1237`). +- Composizione del direttivo (`tg.permissions.getDirettivo`), verifica gruppo, assegnazione ruoli e `canAddBot` (`.../index.d.ts:311-404`). +- Ricerca gruppi Telegram per testo, tag, invite link e ID (`.../index.d.ts:165-228`). +- Ultima guida disponibile (`web.guides_matricole.getLatestGuide`) (`.../index.d.ts:1378-1414`). +- Messaggi cifrati e audit Telegram, già utilizzati in parte nel profilo utente (`src/features/telegram/users.functions.ts:61-84`). +- Gestione grant attivi e schedulati, ma non un endpoint storico (`.../index.d.ts:704-827`). +- Directory Azure, numero associativo e membership dei gruppi (`.../index.d.ts:827-925`). + +Queste API permettono di realizzare rapidamente FAQ, centro direttivo, health check Telegram e widget “ultima guida”. Il censimento, invece, richiede un nuovo dominio dati o un’estensione del backend. + +## Diagnosi prodotto + +### 1. Manca un’entità persona centrale + +Il progetto ha tre rappresentazioni separate della stessa possibile persona: + +- Telegram: `id`, nome, username, ruoli e appartenenze; +- Microsoft 365: `id`, mail, nome, `employeeId`, `isMember`, licenze; +- account admin: identità Better Auth e Telegram collegato. + +Non c’è una relazione esplicita e auditabile tra questi record. Il numero associativo viene gestito dentro Azure (`src/features/azure/azure.functions.ts:19-42`), ma un socio non dovrebbe dipendere dall’esistenza di un account Microsoft 365. + +### 2. La home non aiuta a decidere cosa fare + +`DashboardOverviewPage` mostra aree navigabili e descrizioni statiche (`src/features/dashboard/overview-page.tsx:51-119`). Per un’associazione la prima schermata dovrebbe rispondere a domande operative: + +- quanti soci sono attivi e quanti stanno per scadere; +- chi non ha completato il profilo o il consenso; +- quali account Telegram/Azure non sono riconciliati; +- quali grant stanno per terminare; +- quali gruppi sono senza membri o senza owner; +- quali contenuti sono da revisionare; +- quali azioni recenti richiedono attenzione. + +### 3. Autorizzazione ancora globale + +Su `main` l’accesso è concesso a `owner`, `direttivo` e `president`, mentre `creator` è escluso (`src/server/authorization.ts:1-9`). Tutte le mutazioni usano il medesimo `adminMiddleware`; non esiste una matrice per modulo o operazione (`src/features/telegram/users.functions.ts:87-116`, `src/features/azure/azure.functions.ts:19-58`). + +È già presente una branch remota `origin/agent/hr-dashboard-read-only` che introduce l’idea corretta di ruolo HR in sola lettura. Va portata a un modello stabile e granulare prima di esporre dati personali del censimento. + +### 4. I dati sono caricati spesso tutti in una volta + +Le pagine chiamano `getAll` e filtrano/smistano principalmente nel browser. È comodo per il prototipo, ma diventa fragile con molti soci, gruppi e messaggi. Il censimento deve nascere con query server-side, filtri URL, paginazione reale, ordinamento e autorizzazione per campo. + +### 5. CMS pubblico e gestione interna sono ancora mescolati + +`Web projects` è un catalogo di contenuti pubblici con categorie `news`, `general`, `deprecated`, non un sistema per seguire attività, responsabili e scadenze interne. Conviene mantenere separati: + +- Content management: associazioni pubbliche, progetti pubblici, FAQ e guide; +- Operations: iniziative, task, eventi, volontari e responsabilità. + +## Feature prioritarie + +### P0 — fondamenta necessarie prima di allargare la dashboard + +#### Autorizzazione per capacità + +Passare da “admin sì/no” a permessi per modulo e azione: + +- `members.read`, `members.write`, `members.export`; +- `telegram.read`, `telegram.moderate`, `telegram.grants`; +- `azure.read`, `azure.members.write`, `azure.groups.write`; +- `content.read`, `content.write`, `content.publish`; +- `governance.read`, `governance.write`; +- `audit.read`, `settings.write`. + +Prevedere ruoli composti, per esempio `HR` read-only sui soci, `Content editor`, `Telegram moderator`, `Finance`, `Board member` e `Owner`. Le azioni ad alto impatto — cancellazioni, assegnazione ruoli, rimozione da gruppi, export dati — dovrebbero mostrare permesso richiesto, anteprima e conferma esplicita. + +#### Audit amministrativo unificato + +Creare un audit log per ogni modifica, indipendente dall’audit di moderazione Telegram: + +- attore, ruolo, data, IP/sessione; +- oggetto e valori prima/dopo; +- motivo obbligatorio per azioni sensibili; +- esito, errore e correlation ID; +- filtri per persona, modulo, azione e intervallo; +- export riservato e retention configurabile. + +#### Ricerca globale e centro notifiche + +Una command palette `⌘K`/`Ctrl+K` per cercare soci, utenti Telegram, gruppi, account Azure, FAQ e contenuti. Un centro notifiche dovrebbe raccogliere scadenze, errori di sincronizzazione, richieste in attesa, grant in scadenza e assegnazioni da completare. + +#### Health check integrazioni + +Card e pagina “Integrations” con ultimo sync, latenza, ultimo errore, contatori e azione retry per Telegram, Microsoft 365, Better Auth e sito. Il backend ha già endpoint utili per alcune verifiche; i problemi non dovrebbero apparire solo come toast dopo un click. + +### P1 — Censimento soci: il dominio centrale + +#### Anagrafica canonica + +Creare una sezione `/dashboard/association/members` con una tabella filtrabile e una scheda dettaglio `/dashboard/association/members/:memberId`. + +Campi consigliati per l’MVP: + +| Blocco | Dati | +| --- | --- | +| Identità | nome, cognome, nome visualizzato, email principale, telefono opzionale | +| Identificativo | ID interno, numero tessera/associativo univoco, eventuale codice fiscale solo se realmente necessario | +| Stato | prospect, richiesta, attivo, sospeso, scaduto, ex socio, archiviato | +| Iscrizione | data ingresso, anno/periodo associativo, data scadenza, tipo di iscrizione, stato rinnovo | +| Profilo associativo | università, corso, sede/città, anno di studio, competenze, lingue, interessi, disponibilità | +| Relazioni | team, ruolo interno, responsabile, progetti, eventi, turni e attività | +| Integrazioni | Telegram ID/username, Azure user ID, email Microsoft, gruppi, licenze, ultimo sync | +| Compliance | consensi separati, data consenso, fonte, revoca, note operative, ultima modifica | + +Evitare di trasformare il censimento in un contenitore indiscriminato di dati personali: ogni campo deve avere uno scopo, un responsabile e una retention. + +#### Workflow di iscrizione e rinnovo + +- richiesta di iscrizione con stato `pending`; +- checklist di verifica e approvazione da parte dell’HR/direttivo; +- assegnazione automatica del numero associativo; +- periodo di validità e reminder 30/15/7 giorni prima della scadenza; +- rinnovo, sospensione, uscita e riattivazione con storico; +- email/Telegram di benvenuto e conferma; +- badge visivo “profilo incompleto”, “consenso mancante”, “integrazione non collegata”. + +#### Importazione, deduplicazione e merge + +Import CSV con: + +- mapping delle colonne; +- dry-run prima del salvataggio; +- anteprima di nuove righe, aggiornamenti, duplicati ed errori; +- matching per email, numero associativo, Telegram ID, Azure ID e nome normalizzato; +- merge assistito con confronto campo per campo; +- report scaricabile per riga. + +Le operazioni massive devono sempre avere preview e conferma, senza cancellazioni implicite. + +#### Scheda socio 360° + +La pagina dettaglio dovrebbe riunire in un’unica timeline: + +- dati anagrafici e stato iscrizione; +- rinnovi e pagamenti, se il modulo economico viene attivato; +- identità Telegram/Azure e stato sincronizzazione; +- ruoli e gruppi; +- progetti, team, eventi e presenze; +- comunicazioni e notifiche inviate; +- documenti e consensi; +- audit completo delle modifiche. + +### P1 — Dashboard command center + +Sostituire la home a card statiche con una pagina composta da widget configurabili per ruolo: + +1. **Soci**: attivi, nuovi, in scadenza, da rinnovare, incompleti. +2. **Riconciliazione**: Telegram non collegati, Azure senza numero, duplicati sospetti. +3. **Accessi**: licenze assegnate, gruppi con accesso anomalo, utenti inattivi. +4. **Telegram**: grant attivi/in scadenza, gruppi nascosti, gruppi senza owner, errori bot. +5. **Contenuti**: FAQ/guide da pubblicare, contenuti obsoleti, link rotti. +6. **Attività recenti**: ultime modifiche con filtri e link diretto. +7. **Integrazioni**: stato e ultimo aggiornamento di ogni servizio. + +Ogni KPI deve essere cliccabile e portare a una lista già filtrata. Aggiungere quick action per “Nuovo socio”, “Importa soci”, “Cerca persona”, “Crea grant”, “Apri richieste” e “Controlla sincronizzazione”. + +### P1 — Riconciliazione identità e sincronizzazione + +Creare una pagina `Integrations → Reconciliation` che confronti il registro canonico con Telegram e Microsoft 365: + +- persona presente nel censimento ma non in Azure; +- account Azure senza socio corrispondente; +- Telegram username cambiato o account non collegato; +- numero associativo duplicato o incoerente; +- licenza assegnata a ex socio; +- membro di un gruppo senza ruolo o team compatibile; +- record che richiedono merge manuale. + +Per ogni differenza: motivo, confidence del matching, proposta di correzione, preview e azione manuale. In una fase successiva si può aggiungere sync automatica con regole approvate. + +### P1 — Governance e ruoli associativi + +Il backend espone già `getDirettivo`, ma manca una sezione amministrativa. Aggiungere: + +- composizione del direttivo e degli organi; +- incarico, data inizio/fine e sostituto; +- responsabili di team e deleghe; +- matrice ruoli/permessi della dashboard; +- storico delle nomine e revoche; +- registro decisioni, verbali e action item; +- agenda riunioni, quorum, votazioni e scadenze; +- approvazione a due persone per azioni sensibili. + +Una buona regola è distinguere sempre ruolo associativo, ruolo Telegram e permesso tecnico della dashboard: non devono essere sinonimi. + +### P1 — Comunicazioni e notifiche + +- Template bilingui per benvenuto, rinnovo, scadenza e cambio stato. +- Invio email e Telegram con anteprima, destinatari, variabili e log di consegna. +- Segmenti salvati: soci attivi, ex soci, team, corso, sede, gruppo Telegram. +- Digest giornaliero/settimanale per direttivo e HR. +- Preferenze personali e opt-out dove applicabile. +- Coda notifiche fallite con retry e motivo dell’errore. + +## Feature per area già presente + +### Telegram + +#### Moderation center + +Trasformare il profilo utente e l’audit in una console di moderazione completa: + +- coda di segnalazioni e casi; +- ban, unban, kick, mute e unmute con durata, motivo e storico; +- azioni di gruppo con conferma e limite di sicurezza; +- ricerca messaggi e contesto conversazionale; +- filtri per gruppo, gravità, stato e moderatore; +- link diretto al messaggio e prova dell’azione; +- analytics su volume, utenti attivi, segnalazioni e tempi di risposta. + +Il contratto backend contiene già i tipi di audit `ban`, `unban`, `kick`, `mute`, `unmute`, `ban_all` e `unban_all`: il passo mancante è costruire workflow e UI sopra questi eventi. + +#### Gruppi e bot + +- creazione/import di gruppi con validazione titolo, tag e invite link; +- controllo link rotto, gruppo nascosto, gruppo senza membri e gruppo senza amministratore; +- owner/responsabile operativo e data di ultima revisione; +- rotazione inviti e gestione ciclo di vita; +- check `canAddBot` e pagina salute del bot; +- statistiche per gruppo e ultimo messaggio; +- aggiornamento live tramite WebSocket/SSE, se il backend `WS_PATH` viene adottato. + +#### Grants + +- storico completo, inclusi terminati e interrotti; +- calendario e vista timeline; +- grant in scadenza e reminder automatici; +- approvazione da parte del direttivo; +- motivazione obbligatoria, allegati e log di invio Telegram; +- ricerca per richiedente, autorizzatore, gruppo e periodo; +- endpoint backend storico dedicato: oggi il contratto espone solo `getOngoing` e `getScheduled`. + +### Microsoft 365 / Azure + +- dashboard licenze: assegnate, inutilizzate, mancanti e a rischio; +- assegnazione/revoca licenze con permesso dedicato e audit; +- account inattivi e gruppi senza owner; +- access review periodico per gruppo; +- richieste di accesso con approvazione; +- onboarding guidato: crea socio → crea account → assegna numero → aggiunge gruppi → invia welcome mail; +- offboarding: blocca accessi, rimuove gruppi, revoca licenze, conserva audit; +- mapping diretto tra membro canonico e oggetto Entra; +- export report di conformità. + +La UI attuale visualizza `assignedLicensesIds`, ma il contratto disponibile espone mutazioni per numero associativo e membership gruppi, non per gestione licenze: per quest’ultima serve un’estensione backend/Graph API. + +### Web e contenuti + +#### FAQ + +Aggiungere `Web → FAQs`: è la feature con il miglior rapporto valore/dipendenza perché il backend espone già categorie e CRUD bilingue. MVP: + +- categorie con titolo e icona; +- domanda/risposta IT e EN; +- ricerca e filtro per categoria; +- ordinamento drag-and-drop; +- anteprima pubblica; +- stato bozza/pubblicata e storico modifiche. + +#### Workflow editoriale + +- draft, review, approvazione e publish; +- ruoli editor/reviewer/publisher; +- preview prima della pubblicazione; +- versioni e rollback; +- scheduling per data/ora; +- checklist lingua IT/EN, immagini e link; +- link checker e report contenuti obsoleti; +- metadata SEO, slug, social preview e canonical URL; +- cronologia “chi ha cambiato cosa”. + +#### Guide e associazioni pubbliche + +- preview PDF e indicazione della versione attualmente pubblicata; +- deprecazione invece della cancellazione definitiva; +- conteggio download e file sostitutivo; +- stato pubblico/nascosto e data revisione; +- validazione automatica dei link social; +- scheda associazione con owner interno, contatti di riferimento e stato verifica; +- approvazione a due step per contenuti pubblici. + +### Operatività interna + +Da tenere separata dal catalogo `Web projects`: + +- progetti interni con owner, stato, priorità, scadenza, milestone e task; +- board Kanban e calendario; +- assegnazione a team e volontari; +- commenti, allegati e decisioni; +- eventi con iscrizione, lista partecipanti, presenze e turni; +- gestione sale, attrezzatura e checklist; +- registro ore/attività volontarie; +- report impatto per progetto/evento. + +### Amministrazione economica e documentale + +Da introdurre quando il flusso associativo è chiaro: + +- quote associative e stato pagamento; +- ricevute, fatture, note spese e rimborsi; +- budget annuale per progetto/evento; +- approvazione spese e doppia firma; +- scadenze fiscali e assicurative; +- archivio documenti con versioni, permessi e retention; +- verbali, statuto, contratti e certificazioni; +- export per commercialista e report di bilancio. + +Per pagamenti e documenti sensibili è preferibile integrare servizi specializzati invece di costruire una contabilità completa dentro questa dashboard. + +## Censimento: proposta tecnica minima + +### Entità + +```text +Member +├── MembershipPeriod iscrizione annuale o per periodo +├── MemberIdentity Telegram, Azure, email e altri provider +├── MemberConsent consenso, fonte, data e revoca +├── MemberRole ruolo associativo con periodo di validità +├── MemberTeam appartenenza a team/progetto +├── MemberDocument documenti con permesso e retention +├── Payment quota/ricevuta, se attivato +└── Activity eventi, task, presenze e comunicazioni +``` + +Vincoli indispensabili: + +- numero associativo univoco; +- identità esterne univoche quando presenti; +- storico, non sovrascrittura cieca di stato e periodo; +- audit di ogni lettura sensibile e di ogni mutazione; +- permessi a livello di modulo e, se necessario, di campo; +- export del singolo socio e cancellazione/anonymizzazione secondo policy; +- nessun dato sensibile nei log applicativi o nei toast; +- retention configurabile e documentata. + +### Flusso MVP + +```text +Richiesta → verifica dati → deduplica → approvazione → numero socio + → collegamento Telegram/Azure → welcome → rinnovo → storico +``` + +### Acceptance criteria + +- Un operatore può creare un socio senza creare prima un account Azure. +- La scheda mostra chiaramente identità locale, Telegram e Azure e segnala i collegamenti mancanti. +- L’import CSV non scrive nulla prima della conferma dell’anteprima. +- Duplicati e conflitti vengono mostrati campo per campo. +- Un HR read-only può consultare solo ciò che il suo ruolo consente e non vede pulsanti di scrittura. +- Ogni cambio di stato, numero, consenso o identità esterna è rintracciabile nell’audit. +- Il socio in scadenza compare automaticamente nella coda di attenzione. +- Nessuna cancellazione massiva è disponibile senza conferma esplicita e riepilogo delle righe coinvolte. + +## Miglioramenti UX e frontend + +### Navigazione + +Aggiungere categorie coerenti: + +```text +Overview +Association + Members / Renewals / Teams +Operations + Tasks / Projects / Events +Governance + Board / Meetings / Decisions +Integrations + Telegram / Microsoft 365 / Reconciliation / Health +Content + Associations / Projects / FAQs / Guides +Reports +Account +``` + +### Liste e dettagli + +- Filtri, tab, ordinamento e pagina nello URL, così un link conserva il contesto. +- Query server-side e paginazione reale per il censimento e i log. +- Tabelle su desktop, card/row sheet su mobile; evitare che ogni lista richieda scroll orizzontale. +- Colonne configurabili e viste salvate per ruolo. +- Selezione multipla solo dove esiste un caso d’uso reale, sempre con preview e conferma. +- Stati uniformi: loading, empty, error, stale, saving e permission denied. +- Timeline e deep link tra membro, gruppi, ruoli, contenuti e audit. + +### Lingua e contenuti + +Il contenuto pubblico richiede IT/EN, mentre l’interfaccia amministrativa è quasi tutta in inglese. Decidere una direzione esplicita: + +- UI bilingue con preferenza per utente; oppure +- UI italiana per il team associativo, mantenendo IT/EN sui contenuti pubblici. + +In entrambi i casi servono messaggi e validazioni non misti e un controllo di completezza linguistica. + +### Design system e responsive + +L’audit statico `@memi-design/cli@2.7.9 diagnose . --json --no-write --fail-on none` ha prodotto 87/100, con accessibilità 100, componenti 100, visual-system 76, colore 68 e responsive 88. Le evidenze principali sono: + +- 9 colori hex rilevati; uno è in `src/styles.css:9` e diversi provengono da CSS compilato in `.output`; +- 82 utility colore; +- 13 dimensioni testo; +- 88 utility di spacing; +- 8 radius e 6 shadow utility; +- 190 valori Tailwind arbitrari; +- 18 route e solo 23 utility responsive rilevate. + +Il punteggio è un indicatore, non un gate funzionale: il target include anche `.output`, quindi va ripetuto escludendo gli artefatti generati. Il lavoro consigliato è promuovere colori, radius, shadow e spacing ricorrenti a token semantici e verificare mobile/tablet sulle pagine con tabelle e dialog lunghi. Il feedback dinamico e il recupero da errori non sono completamente valutabili con lo scan statico e richiedono prove interattive. + +## Roadmap proposta + +| Fase | Obiettivo | Risultato | +| --- | --- | --- | +| 0 — Stabilizzazione | RBAC read/write, audit unificato, health check, query server-side, cleanup file duplicati | Base sicura e osservabile | +| 1 — Censimento MVP | `Member`, periodi iscrizione, stati, lista, dettaglio, import dry-run, deduplica, consensi | Registro soci utilizzabile | +| 2 — Command center | KPI aggregati, attention queue, notifiche, quick actions, riconciliazione Telegram/Azure | Dashboard che guida il lavoro quotidiano | +| 3 — Workflow | richieste, rinnovi, welcome, offboarding, team, ruoli associativi, direttivo | Gestione del ciclo di vita | +| 4 — Content e community | FAQ, workflow editoriale, moderation center, grant history, bot/group health | Copertura completa dei canali esistenti | +| 5 — Operations | task, eventi, volontari, documenti e finanza essenziale | Gestione associativa end-to-end | +| 6 — Automazioni | reminder, sync approvata, digest, report schedulati, anomalie | Riduzione del lavoro manuale | + +## Priorità valore/dipendenze + +| Feature | Valore | Dipendenza | Priorità | +| --- | --- | --- | --- | +| Censimento soci | Molto alto | nuovo modello/API | P1 | +| Dashboard KPI + attention queue | Molto alto | aggregati censimento | P1 | +| RBAC granulare | Molto alto | policy ruoli | P0 | +| Riconciliazione identità | Molto alto | Member + connettori | P1 | +| FAQ CMS | Alto | backend quasi pronto | P1 | +| Rinnovi/notifiche | Alto | Member + scheduler/email | P1 | +| Audit amministrativo | Alto | schema audit | P0 | +| Azure access review/licenze | Alto | Graph/backend extension | P2 | +| Moderation center | Alto | casi/segnalazioni backend | P2 | +| Governance direttivo | Alto | dati organi/mandati | P2 | +| Eventi e volontari | Medio-alto | calendario/registrazioni | P2 | +| Finanza e documenti | Alto | policy e integrazione dedicata | P3 | +| AI assistant interno | Medio | permessi, audit, privacy, retrieval | P3 | + +## Feature “fighe” con valore reale + +Da aggiungere dopo il nucleo, non prima: + +- tessera socio digitale con QR e validità; +- profilo socio condivisibile solo con consenso; +- mappa dei team, competenze e disponibilità; +- timeline visuale dell’associazione e degli incarichi; +- sincronizzazione con indicatore di drift “prima/dopo”; +- dashboard con widget personalizzabili per HR, direttivo e moderatori; +- report PDF/CSV schedulati inviati al direttivo; +- centro comando da tastiera con azioni rapide; +- rilevazione di duplicati e anomalie con spiegazione del matching; +- preview pubblica dei contenuti con confronto tra versione online e bozza; +- modalità mobile/PWA per check-in eventi e gestione rapida; +- assistant interno limitato ai documenti e ai dati autorizzati, con citazione della fonte e nessuna azione irreversibile autonoma. + +## Verifica tecnica eseguita + +Comandi eseguiti dopo aver riallineato `node_modules` al lockfile con `pnpm install --frozen-lockfile`: + +- `pnpm typecheck` — passato; +- `pnpm test` — 16 test passati; +- `pnpm check` — Biome pulito su 141 file; +- `pnpm build` — build client, SSR e Nitro passato; +- `npx -y @memi-design/cli@2.7.9 diagnose . --json --no-write --fail-on none` — 87/100, 0 critici, 8 finding di design/maintainability/responsive. + +Il report non modifica il codice applicativo. L’unica azione locale aggiuntiva è stata l’installazione delle dipendenze già dichiarate nel lockfile, necessaria perché l’ambiente iniziale non aveva `@dnd-kit/react` e aveva una versione precedente del backend. + +## Decisioni da prendere prima di implementare il censimento + +1. Il numero associativo resta un identificativo Azure o diventa proprietà del nuovo `Member`? +2. L’iscrizione è annuale, semestrale o senza scadenza? +3. Quali dati sono davvero necessari per il tesseramento e quali sono vietati/non pertinenti? +4. HR può leggere tutto o alcuni campi devono essere mascherati? +5. Il pagamento è manuale, bonifico, Stripe o altro? +6. Chi approva iscrizioni, rinnovi, ruoli e cancellazioni? +7. Qual è la policy di conservazione, export e anonimizzazione? +8. I progetti interni devono essere separati dal catalogo pubblico esistente? + +La decisione architetturale più importante è la prima: se il nuovo censimento nasce direttamente come registro canonico, tutte le altre feature — dashboard, Azure, Telegram, notifiche, eventi e report — possono costruirsi attorno alla stessa persona invece di aggiungere altre liste scollegate. From 16877a9a291760af9c30d214fea6d065e52ecda6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gabriele=20Vigan=C3=B2?= Date: Thu, 20 Aug 2026 00:55:56 +0200 Subject: [PATCH 2/6] modified document --- PRD_Admin_Dashboard_Associazione.md | 248 ++++++++++++ PRD_Admin_Dashboard_PoliNetwork_v0.3.md | 484 ------------------------ 2 files changed, 248 insertions(+), 484 deletions(-) create mode 100644 PRD_Admin_Dashboard_Associazione.md delete mode 100644 PRD_Admin_Dashboard_PoliNetwork_v0.3.md diff --git a/PRD_Admin_Dashboard_Associazione.md b/PRD_Admin_Dashboard_Associazione.md new file mode 100644 index 0000000..0bf1ca0 --- /dev/null +++ b/PRD_Admin_Dashboard_Associazione.md @@ -0,0 +1,248 @@ +# Admin Dashboard Associazione + +**Documento di specifica funzionale per il Team IT** +**Versione:** 0.2 +**Data:** 20 agosto 2026 +**Stato:** Bozza per revisione + +## Scopo del documento + +Questo documento raccoglie le funzionalità attualmente previste per l'Admin Dashboard dell'associazione, distinguendo tra funzionalità prioritarie e funzionalità secondarie. + +L'obiettivo generale è concentrare nella dashboard il maggior numero possibile di processi oggi distribuiti tra form, fogli Excel, email e operazioni manuali, mantenendo però ogni area sufficientemente modulare da poter essere sviluppata e ampliata nel tempo. + +# Feature prioritarie + +## 1. Area Associazioni Partner + +L'area dedicata alle associazioni partner è una delle funzionalità prioritarie della piattaforma. + +Ogni associazione partner deve avere un proprio accesso alla dashboard e poter gestire da un'unica area le interazioni principali con PoliNetwork. + +### 1.1 Accesso e gestione degli account + +La soluzione deve essere pensata per gestire in modo ordinato e scalabile decine di associazioni diverse. + +Come soluzione di riferimento, PoliNetwork può creare e gestire direttamente un indirizzo email dedicato `@polinetwork.org` per ciascuna associazione partner, da utilizzare come identità per l'accesso alla dashboard. + +Resta da definire con il Team IT il modello tecnico definitivo di autenticazione e gestione degli account, tenendo conto almeno di: + +- creazione e disattivazione degli account; +- recupero delle credenziali; +- eventuale cambio dei referenti dell'associazione; +- possibilità futura di avere più referenti per la stessa associazione; +- gestione centralizzata degli accessi da parte di PoliNetwork. + +### 1.2 Richieste di pubblicazione nei gruppi + +Le associazioni partner devono poter inviare richieste di pubblicazione di messaggi nei gruppi WhatsApp e/o Telegram gestiti da PoliNetwork. + +Per ogni richiesta devono essere disponibili almeno: + +- contenuto del messaggio; +- gruppo o insieme di gruppi destinatari; +- eventuali allegati o link; +- data della richiesta; +- stato della richiesta; +- storico delle richieste precedenti. + +Se viene mantenuto un sistema a crediti, l'associazione deve inoltre poter visualizzare: + +- crediti disponibili; +- crediti utilizzati; +- data dell'eventuale rinnovo o ricarica. + +La logica precisa dei crediti resta da definire. + +### 1.3 Gestione della pagina pubblica dell'associazione + +Ogni associazione deve avere una propria pagina pubblica sul sito PoliNetwork. + +Dalla dashboard l'associazione deve poter richiedere modifiche ai dati mostrati pubblicamente, tra cui: + +- nome e informazioni principali; +- descrizione; +- logo; +- sito web; +- link Instagram; +- link LinkedIn; +- altri link social; +- eventuali contatti o altre informazioni pubbliche previste dalla pagina. + +Le modifiche non devono necessariamente essere pubblicate direttamente: la dashboard deve supportare un flusso di richiesta e approvazione da parte di PoliNetwork, così da mantenere il controllo sui contenuti presenti sul sito. + +### 1.4 Eventi delle associazioni — nuovo PoliTamTam + +La gestione degli eventi delle associazioni è una feature prioritaria. + +Le associazioni partner devono poter inserire direttamente dalla dashboard gli eventi da mostrare nella pagina dedicata agli eventi delle associazioni sul sito PoliNetwork. + +Questa sezione rappresenta l'evoluzione del vecchio concetto di **PoliTamTam**: un punto unico in cui raccogliere e mostrare in modo ordinato gli eventi delle associazioni. + +Per ogni evento devono essere previsti almeno: + +- titolo; +- associazione organizzatrice; +- descrizione; +- data e orario; +- luogo oppure link online; +- link di iscrizione, se presente; +- immagine o locandina, se prevista; +- stato dell'evento; +- eventuale data di scadenza o rimozione automatica dalla pagina. + +Il flusso di pubblicazione deve essere definito con il Team IT. In particolare, va deciso se gli eventi vengano pubblicati immediatamente oppure sottoposti prima ad approvazione da parte di PoliNetwork. + +## 2. Aree Team + +Ogni team interno deve avere una propria area dedicata all'interno della dashboard. + +Le aree previste sono: + +- **Team IT**; +- **Team Design & Social**; +- **Team International**; +- **Team HR**; +- **Team Events & Partnerships**. + +La struttura deve essere modulare: ogni team deve avere uno spazio indipendente, con permessi dedicati e la possibilità di aggiungere in seguito strumenti specifici senza dover riprogettare l'intera dashboard. + +Le funzionalità specifiche di ciascun team verranno definite separatamente insieme ai rispettivi responsabili. In questa fase è sufficiente prevedere correttamente struttura, ruoli, accessi e separazione delle aree. + +## 3. Dashboard Admin e Capo Admin + +La dashboard deve permettere ai responsabili degli admin di visualizzare e gestire le informazioni relative agli admin di propria competenza. + +### 3.1 Vista Capo Admin + +Un Capo Admin deve poter visualizzare gli admin del proprio corso di studi e filtrare rapidamente le informazioni disponibili. + +Per ogni admin devono essere disponibili almeno: + +- nome; +- cognome; +- anno di corso; +- data di ingresso in PoliNetwork; +- indicazione se è rappresentante o meno; +- altre associazioni di cui fa parte; +- numero di telefono; +- username o contatto Telegram; +- collegamento rapido per contattarlo tramite WhatsApp o Telegram. + +### 3.2 Filtri e ricerca + +Devono essere disponibili almeno: + +- ricerca per nome e cognome; +- filtro per anno; +- filtro per rappresentanza; +- filtro per appartenenza ad altre associazioni. + +### 3.3 Link dei gruppi + +Il Capo Admin deve avere una sezione dedicata contenente i link ai gruppi WhatsApp e Telegram di propria competenza. + +La gestione dei permessi deve garantire che ciascun Capo Admin possa vedere esclusivamente i dati e i gruppi relativi al proprio ambito. + +## 4. Gestione Soci e Rinnovi + +La dashboard deve centralizzare anche la gestione dello stato associativo dei soci. + +### 4.1 Rinnovo automatico via email + +Poco prima della scadenza dell'iscrizione, il socio deve ricevere automaticamente una mail che gli ricorda di rinnovare. + +La mail deve contenere le informazioni necessarie per completare il rinnovo secondo il processo associativo definito. + +Non è quindi necessario che il pagamento venga effettuato direttamente dalla dashboard nella prima versione. + +### 4.2 Vista Direttivo sullo stato dei soci + +Il Direttivo deve poter visualizzare lo stato del rinnovo di ciascun socio e distinguere chiaramente almeno tra: + +- rinnovo da verificare; +- pagamento effettuato; +- pagamento non ancora effettuato. + +Per ogni socio il Direttivo deve poter eseguire almeno due azioni: + +**Segna come pagato** +Aggiorna lo stato del socio e invia automaticamente una mail di conferma al socio interessato. + +**Invia reminder** +Invia una nuova mail di promemoria al socio che non ha ancora completato il rinnovo. + +La dashboard deve mantenere uno storico minimo delle azioni effettuate, in modo da sapere quando è stato inviato un reminder e quando un rinnovo è stato confermato. + +### 4.3 Informazioni utili sul socio + +Dove utile, la dashboard può inoltre mostrare: + +- data di ingresso in PoliNetwork; +- anzianità nell'associazione; +- ruoli ricoperti; +- team di appartenenza; +- eventuale corso di studi; +- stato associativo corrente. + +## 5. Email automatiche di compleanno + +Nel giorno del compleanno, i soci devono ricevere automaticamente una mail di auguri da parte di PoliNetwork. + +La funzionalità riguarda esclusivamente i soci e utilizza esclusivamente l'email: non è prevista, in questa fase, l'integrazione con Telegram per gli auguri. + +Il provider e il sistema tecnico utilizzato per l'invio automatico delle email devono essere definiti con il Team IT. + +## 6. Onboarding nuovi Admin + +Il processo attuale di onboarding degli admin è troppo frammentato e comprende passaggi distribuiti tra form, email, colloqui, fogli Excel e operazioni manuali. + +L'obiettivo della nuova dashboard è portare **il maggior numero possibile di passaggi direttamente all'interno della piattaforma**, riducendo gli strumenti esterni e usando la dashboard come punto centrale del processo. + +Il flusso definitivo deve ancora essere progettato nel dettaglio. + +Come principio generale, la soluzione futura dovrebbe cercare di centralizzare almeno: + +- gestione delle candidature; +- stato della candidatura; +- gestione del colloquio; +- raccolta dei dati necessari; +- approvazione del nuovo admin; +- creazione/attivazione del profilo; +- assegnazione del corso, dei ruoli e delle competenze; +- passaggi successivi necessari all'ingresso operativo dell'admin. + +Prima di implementare questa parte è necessario ridisegnare il processo insieme a HR e Team IT, evitando di digitalizzare alla lettera un flusso attuale che è già inutilmente complesso. + +# Feature secondarie + +Le seguenti funzionalità sono considerate utili, ma non prioritarie rispetto alle aree descritte sopra. + +## 7. Area Aziende + +Possibili funzionalità: + +- pubblicazione di annunci di lavoro e stage; +- eventuale consultazione dei CV dei membri, esclusivamente con un sistema di consenso e gestione privacy adeguato. + +La funzionalità deve essere progettata in dettaglio prima dello sviluppo. + +## 8. Area Proprietari di casa + +Possibile area dedicata ai proprietari per la pubblicazione di annunci immobiliari relativi ad affitto o vendita di camere e appartamenti. + +## 9. Bacheca ricerca casa e coinquilini + +Possibile area dedicata agli utenti che vogliono pubblicare annunci per: + +- ricerca di una stanza o appartamento; +- ricerca di coinquilini; +- altre esigenze collegate alla bacheca casa. + +## 10. Newsletter + +La newsletter è una feature secondaria e non deve bloccare lo sviluppo della prima versione della dashboard. + +In futuro potrà utilizzare i dati già presenti nella piattaforma, in particolare gli eventi inseriti dalle associazioni partner, per semplificare la selezione e la pubblicazione dei contenuti. + +Il modello editoriale, il sistema di approvazione e il provider di invio verranno definiti in una fase successiva. diff --git a/PRD_Admin_Dashboard_PoliNetwork_v0.3.md b/PRD_Admin_Dashboard_PoliNetwork_v0.3.md deleted file mode 100644 index 1e82cc1..0000000 --- a/PRD_Admin_Dashboard_PoliNetwork_v0.3.md +++ /dev/null @@ -1,484 +0,0 @@ -# Admin Dashboard PoliNetwork - -**Documento di specifica funzionale per il Team IT** -**Versione:** 0.3 -**Data:** 20 agosto 2026 -**Stato:** Bozza per revisione -**Modifiche rispetto alla v0.2:** riordino delle priorità (interno prima di esterno), aggiunta di modello dati, ruoli e permessi, macchine a stati, criteri di accettazione e decisioni tecniche proposte. - ---- - -## 1. Scopo e principi - -### 1.1 Obiettivo - -Portare dentro un'unica piattaforma i processi oggi distribuiti tra form, fogli Excel, email, gruppi e operazioni manuali, mantenendo ogni area modulare e sviluppabile in modo indipendente. - -### 1.2 Principio di priorità: interno prima di esterno - -La v0.2 metteva l'Area Associazioni Partner come feature n.1. Questa versione la sposta in Fase 2. Motivi: - -1. **Dipendenza tecnica.** L'area partner richiede autenticazione multi-tenant, ruoli con scope, flussi di approvazione, gestione allegati e pagine pubbliche. Sono tutti pezzi che vanno costruiti comunque per l'uso interno: costruirli prima per l'interno e poi riusarli per i partner riduce il lavoro complessivo. -2. **Dipendenza organizzativa.** L'area partner ha utenti esterni: un bug, un dato sbagliato o un downtime diventano subito un problema di immagine. L'interno è un ambiente tollerante in cui rodare la piattaforma. -3. **Ritorno immediato.** Anagrafica, rinnovi e onboarding eliminano lavoro manuale che oggi ricade su Direttivo, HR e Capi Admin ogni settimana. -4. **Prerequisito di dati.** Le associazioni partner vanno collegate a referenti, ruoli e permessi che esistono solo se l'anagrafica interna è già in piedi. - -Il PoliTamTam resta la feature esterna a priorità più alta ed è la prima cosa che si sviluppa una volta chiusa la Fase 1. - -### 1.3 Principi di progetto - -- **Un'unica fonte di verità per le persone.** Ogni persona esiste una volta sola nel sistema; ruoli, tesseramento e appartenenze sono attributi collegati, non copie. -- **Permessi per capability, non per ruolo hardcoded.** Il codice controlla permessi; i ruoli sono insiemi di permessi configurabili. -- **Ogni scrittura è tracciata.** Audit log append-only su tutte le azioni che modificano dati o inviano comunicazioni. -- **Ogni invio automatico è idempotente.** Nessuna email deve poter partire due volte per lo stesso evento. -- **Modularità.** Ogni area è un modulo attivabile/disattivabile, con proprie tabelle e propri permessi. -- **Minimizzazione dei dati.** Si raccoglie solo ciò che serve a un processo descritto in questo documento. - ---- - -## 2. Fondamenta (Fase 0 — prerequisito di tutto) - -Non è una feature visibile, ma è la parte da cui dipendono tutte le altre. Va sviluppata per prima e in modo definitivo. - -### 2.1 Identità e autenticazione - -**Decisione proposta (da confermare con il Team IT):** - -- **Utenti interni** (soci, admin, capi admin, team, direttivo): SSO tramite Google Workspace PoliNetwork (OIDC), account `@polinetwork.org`. Nessuna password gestita dalla dashboard. -- **Utenti partner** (Fase 2): account applicativi con email `@polinetwork.org` dedicata all'associazione, login con magic link via email + sessione a scadenza. Nessuna password da ricordare, nessun reset da gestire manualmente. -- **Sessioni:** durata 30 giorni per gli interni, 7 giorni per i partner, revocabili singolarmente dal superadmin. -- **2FA:** obbligatoria (tramite Google) per superadmin e Direttivo. - -**Requisiti minimi in ogni caso:** - -- creazione, sospensione, riattivazione e disattivazione di un account senza cancellare i dati storici; -- cambio del referente di un account senza perdere lo storico delle azioni; -- possibilità futura di più referenti per la stessa entità (associazione, team, corso); -- pannello centralizzato per PoliNetwork con elenco account, ultimo accesso, stato, ruoli. - -### 2.2 Ruoli e permessi - -Ogni assegnazione di ruolo ha uno **scope**: globale, corso di studi, team o associazione. - -| Ruolo | Scope | Descrizione | -|---|---|---| -| `superadmin` | globale | Team IT. Accesso completo, gestione account e configurazioni. | -| `direttivo` | globale | Visione su soci, tesseramenti, approvazioni, statistiche. | -| `hr` | globale | Gestione candidature e onboarding. | -| `capo_admin` | corso di studi | Vede e gestisce admin e gruppi del proprio corso. | -| `admin` | corso di studi | Vede i propri dati e i gruppi di cui fa parte. | -| `team_lead` | team | Gestisce l'area del proprio team e i suoi membri. | -| `team_member` | team | Accede all'area del proprio team. | -| `socio` | personale | Vede e aggiorna il proprio profilo e il proprio stato associativo. | -| `partner_referente` | associazione | Fase 2. Gestisce l'area della propria associazione. | - -Regole: - -- una persona può avere più ruoli contemporaneamente, anche su scope diversi; -- i permessi sono l'unione dei permessi dei ruoli attivi; -- ogni ruolo ha `valido_da` e `valido_a`, così lo storico resta consultabile; -- il permesso è sempre verificato lato server, mai solo nascondendo un elemento nell'interfaccia. - -### 2.3 Modello dati minimo - -**`persona`** — anagrafica unica -`id`, `nome`, `cognome`, `email_personale`, `email_polinetwork`, `telefono`, `telegram_username`, `telegram_id`, `data_nascita`, `corso_di_studi_id`, `anno_corso`, `data_ingresso`, `data_uscita`, `stato` (`attivo` | `sospeso` | `uscito`), `is_rappresentante`, `note`, `creato_il`, `aggiornato_il` - -**`altra_associazione`** — appartenenze esterne dichiarate -`id`, `persona_id`, `nome_associazione`, `ruolo`, `dal`, `al` - -**`ruolo_assegnato`** -`id`, `persona_id`, `ruolo`, `scope_type` (`globale` | `corso` | `team` | `associazione`), `scope_id`, `valido_da`, `valido_a`, `assegnato_da` - -**`corso_di_studi`** -`id`, `nome`, `codice`, `sede`, `livello` (triennale/magistrale/ciclo unico), `attivo` - -**`team`** -`id`, `nome`, `slug`, `descrizione`, `lead_persona_id`, `attivo` - -**`tesseramento`** -`id`, `persona_id`, `anno_associativo`, `data_iscrizione`, `data_scadenza`, `stato`, `importo`, `metodo_pagamento`, `verificato_da`, `verificato_il`, `note` - -**`gruppo_chat`** -`id`, `nome`, `piattaforma` (`whatsapp` | `telegram`), `link_invito`, `corso_di_studi_id`, `tipo` (corso, anno, generale, altro), `responsabile_persona_id`, `attivo`, `iscritti_stimati` - -**`candidatura`** (onboarding) -`id`, `nome`, `cognome`, `email`, `telefono`, `telegram_username`, `corso_di_studi_id`, `anno_corso`, `motivazione`, `disponibilita`, `stato`, `assegnata_a`, `creata_il`, `aggiornata_il`, `persona_id` (valorizzato all'approvazione) - -**`colloquio`** -`id`, `candidatura_id`, `intervistatore_persona_id`, `data_ora`, `luogo_o_link`, `esito`, `note` - -**`audit_log`** — append-only -`id`, `attore_persona_id`, `azione`, `entita_tipo`, `entita_id`, `dati_prima`, `dati_dopo`, `ip`, `timestamp` - -**`email_log`** — append-only -`id`, `tipo_email`, `destinatario_persona_id`, `destinatario_email`, `chiave_idempotenza`, `stato` (`inviata` | `fallita` | `bounce`), `provider_message_id`, `inviata_il`, `errore` - -`chiave_idempotenza` è univoca ed è costruita come `{tipo}:{persona_id}:{periodo}` — esempio: `compleanno:412:2026`. Questo è ciò che rende impossibile il doppio invio. - -Entità di Fase 2 (`associazione_partner`, `richiesta_pubblicazione`, `evento`, `movimento_credito`, `richiesta_modifica_pagina`) sono definite nella sezione 8. - -### 2.4 Sistema di invio email - -**Decisione proposta:** provider transazionale con API e webhook di delivery (Resend, Postmark o Amazon SES). Requisiti: - -- sottodominio dedicato per le transazionali, con SPF, DKIM e DMARC configurati, separato dal dominio usato per la newsletter, per non contaminare la reputazione di invio; -- template versionati nel repository, non nell'interfaccia del provider; -- ogni invio scrive su `email_log` prima di partire e aggiorna lo stato al webhook; -- job schedulati eseguiti una volta al giorno a orario fisso (proposta: 08:00 Europe/Rome), idempotenti, con recupero automatico dei giorni saltati; -- pagina di monitoraggio per il superadmin con invii recenti, fallimenti e bounce; -- ambiente di staging che scrive su `email_log` senza inviare realmente. - -### 2.5 Audit e privacy - -- Ogni azione che modifica dati o invia comunicazioni scrive su `audit_log`. -- Retention: dati dei soci conservati per la durata dell'appartenenza + 5 anni per obblighi associativi e fiscali; candidature non approvate cancellate dopo 12 mesi; log conservati 24 mesi. -- Ogni campo raccolto deve corrispondere a un processo descritto in questo documento. Campi senza processo non si raccolgono. -- Numero di telefono e contatto Telegram sono visibili solo a chi ha un ruolo con permesso esplicito (capo admin sul proprio corso, direttivo, HR), mai in elenchi pubblici o esportabili senza tracciamento. -- Ogni esportazione di dati personali (CSV) viene registrata su `audit_log` con attore, filtri applicati e numero di record. - -### 2.6 Criteri di accettazione Fase 0 - -- Un utente interno accede con account Google PoliNetwork e vede solo i moduli permessi dai propri ruoli. -- Un tentativo di accesso via API a una risorsa fuori dal proprio scope restituisce 403 e viene loggato. -- Il superadmin può assegnare, revocare e datare un ruolo e vedere lo storico delle assegnazioni. -- Un'email di test parte, compare in `email_log` e il rilancio manuale dello stesso job non produce un secondo invio. - ---- - -# Parte I — Feature interne (prioritarie) - -## 3. Anagrafica persone (Fase 1) - -Base di tutte le altre feature interne. Sostituisce i fogli Excel oggi in uso. - -### 3.1 Requisiti - -- Elenco unico delle persone di PoliNetwork con i campi della tabella `persona`. -- Scheda persona con: dati anagrafici, corso e anno, data di ingresso e anzianità calcolata, ruoli attivi e storici, team di appartenenza, altre associazioni, stato associativo corrente, storico delle azioni che la riguardano. -- Ogni persona può aggiornare autonomamente i propri dati di contatto (telefono, Telegram, email personale). Corso, anno di ingresso, ruoli e stato associativo sono modificabili solo da chi ha il permesso. -- Import iniziale da Excel con file di mappatura colonne, report degli scarti e possibilità di rieseguire l'import senza creare duplicati (chiave: email personale, con controllo manuale dei conflitti). -- Ricerca full-text su nome, cognome, email e username Telegram. - -### 3.2 Criteri di accettazione - -- L'import dei fogli attuali produce zero duplicati e un report leggibile degli scarti. -- Modificare il numero di telefono dal proprio profilo aggiorna il dato visto dal Capo Admin senza altri passaggi. -- L'anzianità è sempre calcolata da `data_ingresso`, mai inserita a mano. - ---- - -## 4. Dashboard Admin e Capo Admin (Fase 1) - -### 4.1 Vista Capo Admin - -Il Capo Admin vede l'elenco degli admin del **proprio corso di studi**, con: - -- nome e cognome; -- anno di corso; -- data di ingresso in PoliNetwork e anzianità; -- indicazione se è rappresentante; -- altre associazioni di cui fa parte; -- numero di telefono; -- username o contatto Telegram; -- stato associativo (attivo / in scadenza / scaduto); -- pulsanti di contatto rapido: `wa.me/{telefono}` e `t.me/{username}`, aperti in nuova scheda. - -### 4.2 Filtri e ricerca - -- ricerca testuale per nome e cognome; -- filtro per anno di corso; -- filtro per rappresentante sì/no; -- filtro per appartenenza ad altre associazioni (presenza o nome specifico); -- filtro per stato associativo; -- ordinamento per cognome, anno, data di ingresso; -- esportazione CSV del risultato filtrato, tracciata su `audit_log`. - -### 4.3 Link dei gruppi - -Sezione con i gruppi WhatsApp e Telegram di competenza del Capo Admin: nome, piattaforma, corso, tipo, link di invito con copia rapida, responsabile, stato attivo/archiviato. - -Il Capo Admin può proporre l'aggiunta o la modifica di un link; la modifica diventa effettiva dopo conferma di un superadmin (i link di invito sono dati sensibili per lo spam). - -### 4.4 Regole di visibilità - -- `capo_admin` vede esclusivamente persone e gruppi con `corso_di_studi_id` incluso nel proprio scope; può avere più corsi assegnati. -- `admin` vede solo la propria scheda e i gruppi di cui fa parte. -- `direttivo` e `superadmin` vedono tutti i corsi. -- Il tentativo di accedere a una persona fuori scope produce 403, non una lista vuota. - -### 4.5 Criteri di accettazione - -- Un Capo Admin con due corsi assegnati vede l'unione dei due e nient'altro. -- Il link WhatsApp precompilato apre correttamente la chat con il numero in formato internazionale. -- Cambiare il corso di una persona la fa sparire immediatamente dalla vista del vecchio Capo Admin. - ---- - -## 5. Gestione Soci e Rinnovi (Fase 1) - -### 5.1 Stati del tesseramento - -`tesseramento.stato` assume esclusivamente questi valori: - -| Stato | Significato | -|---|---| -| `attivo` | Tesseramento valido, non ancora in finestra di rinnovo. | -| `in_scadenza` | Entro N giorni dalla scadenza. Il reminder automatico è partito o sta per partire. | -| `sollecitato` | Almeno un reminder inviato dopo la scadenza. | -| `da_verificare` | Il socio dichiara di aver pagato, il Direttivo non ha ancora confermato. | -| `pagato` | Pagamento confermato dal Direttivo. Genera il nuovo tesseramento attivo. | -| `scaduto` | Scadenza superata senza rinnovo oltre la finestra di tolleranza. | - -**Parametri configurabili** (valori proposti): primo reminder 30 giorni prima della scadenza; secondo reminder 7 giorni prima; terzo il giorno della scadenza; tolleranza 30 giorni prima del passaggio a `scaduto`. - -### 5.2 Rinnovo automatico via email - -- Job giornaliero che seleziona i tesseramenti in finestra di reminder e invia la mail di rinnovo. -- La mail contiene: scadenza, importo, istruzioni di pagamento secondo il processo associativo vigente, link alla propria pagina di stato nella dashboard. -- In questa versione **il pagamento non avviene nella dashboard**. La dashboard registra e verifica, non incassa. -- Ogni invio è protetto da `chiave_idempotenza` (`rinnovo_r1:{persona_id}:{anno}`), quindi il rilancio del job non genera duplicati. - -### 5.3 Vista Direttivo - -Tabella dei soci filtrabile per stato, anno associativo, corso, team. Per ogni socio due azioni: - -**Segna come pagato** -Imposta `stato = pagato`, registra `verificato_da` e `verificato_il`, crea il tesseramento del nuovo anno, invia automaticamente la mail di conferma al socio, scrive su `audit_log`. - -**Invia reminder** -Invia una nuova mail di promemoria, registra l'invio su `email_log`, aggiorna `stato` a `sollecitato`. Limite: massimo un reminder manuale ogni 7 giorni per socio, per evitare invii ripetuti da più membri del Direttivo. - -Sulla scheda del socio è visibile lo storico: quando è stato inviato ogni reminder, chi ha confermato il pagamento e quando. - -### 5.4 Informazioni sul socio - -Nella scheda, dove utile: data di ingresso, anzianità, ruoli ricoperti (attuali e passati), team di appartenenza, corso di studi, stato associativo corrente e storico dei tesseramenti per anno. - -### 5.5 Criteri di accettazione - -- Un socio con scadenza tra 30 giorni riceve esattamente una mail, anche se il job viene eseguito due volte. -- "Segna come pagato" produce: stato aggiornato, mail di conferma inviata, riga di audit, nuovo tesseramento creato. -- Due membri del Direttivo che premono "Invia reminder" sullo stesso socio nello stesso giorno producono un solo invio. -- Il Direttivo può esportare l'elenco dei non in regola in CSV. - ---- - -## 6. Onboarding nuovi Admin (Fase 1) - -### 6.1 Premessa - -Il processo attuale è frammentato tra form, email, colloqui, fogli Excel e passaggi manuali. **Non va digitalizzato così com'è.** Prima dello sviluppo, HR e Team IT devono ridisegnare il flusso, eliminando i passaggi che esistono solo perché mancava uno strumento. - -Il flusso descritto qui è la proposta di riferimento da validare con HR. - -### 6.2 Pipeline della candidatura - -`ricevuta` → `in_screening` → `colloquio_da_programmare` → `colloquio_programmato` → `colloquio_effettuato` → `approvata` | `respinta` → `onboarding_in_corso` → `completata` - -Stati aggiuntivi: `ritirata` (il candidato rinuncia), `in_attesa` (rimandata a una tornata successiva). - -### 6.3 Requisiti - -- **Form di candidatura pubblico** servito dalla dashboard, che scrive direttamente su `candidatura`. Nessun Google Form. -- **Board delle candidature** per HR: colonne per stato, assegnazione a un referente, filtri per corso e tornata. -- **Gestione colloquio**: registrazione di data, ora, luogo o link, intervistatore, esito e note. Invio automatico della convocazione al candidato e del promemoria il giorno prima. -- **Approvazione**: alla transizione ad `approvata`, il sistema crea la `persona` collegata, imposta `data_ingresso`, assegna corso, ruolo `admin` e gli eventuali team, e invia la mail di benvenuto con i passi successivi. -- **Checklist di ingresso operativo** con voci configurabili (esempi: account `@polinetwork.org` creato, inserito nei gruppi di competenza, formazione iniziale svolta, tesseramento avviato). La candidatura passa a `completata` solo quando la checklist è chiusa. -- **Comunicazione al candidato**: ogni cambio di stato rilevante genera una mail automatica; l'esito negativo usa un template dedicato con invio manuale confermato da HR. - -### 6.4 Criteri di accettazione - -- Da candidatura ad admin operativo non serve nessuno strumento esterno alla dashboard oltre alla creazione dell'account Google. -- L'approvazione crea la persona senza reinserimento manuale dei dati già raccolti dal form. -- HR vede in ogni momento quante candidature sono ferme in ciascuno stato e da quanti giorni. - ---- - -## 7. Aree Team (Fase 1, struttura — Fase 3, contenuti) - -### 7.1 Team previsti - -Team IT, Team Design & Social, Team International, Team HR, Team Events & Partnerships. - -### 7.2 Cosa si sviluppa ora - -Solo l'impalcatura, identica per tutti i team: - -- pagina del team con elenco membri, ruoli interni e lead; -- permessi: `team_member` vede l'area, `team_lead` gestisce membri e contenuti; -- spazio per note e documenti condivisi del team; -- bacheca annunci interna al team; -- struttura a moduli che permette di aggiungere strumenti specifici in seguito senza toccare le altre aree. - -### 7.3 Cosa non si sviluppa ora - -Gli strumenti specifici di ciascun team. Vanno definiti separatamente con i rispettivi responsabili, dopo che la struttura è in produzione e i team la stanno effettivamente usando. - -### 7.4 Criteri di accettazione - -- Aggiungere un nuovo team è un'operazione di configurazione, non di sviluppo. -- Un membro di un team non vede le aree degli altri team se non ha ruoli su di essi. - ---- - -## 8. Email automatiche di compleanno (Fase 1) - -- Job giornaliero che seleziona le persone con `data_nascita` corrispondente alla data odierna e `stato = attivo` **e tesseramento valido** (la feature riguarda esclusivamente i soci). -- Invio di una mail di auguri da parte di PoliNetwork. Solo email: nessuna integrazione Telegram in questa fase. -- Idempotenza tramite chiave `compleanno:{persona_id}:{anno}`. -- Gestione del 29 febbraio: negli anni non bisestili l'invio avviene il 28 febbraio. -- Opt-out individuale disponibile nel profilo del socio. -- Se il job non gira in un dato giorno, all'esecuzione successiva recupera i compleanni saltati degli ultimi 3 giorni. - -**Criterio di accettazione:** rilanciare il job tre volte nello stesso giorno produce un solo invio per persona. - ---- - -# Parte II — Feature esterne - -## 9. Area Associazioni Partner (Fase 2) - -Prima area rivolta a utenti esterni. Si sviluppa dopo la Fase 1 e riusa autenticazione, ruoli, flussi di approvazione e sistema email già costruiti. - -### 9.1 Entità - -**`associazione_partner`** -`id`, `nome`, `slug`, `email_polinetwork`, `descrizione`, `logo_url`, `sito_web`, `instagram`, `linkedin`, `altri_link` (JSON), `contatti_pubblici`, `stato` (`attiva` | `sospesa` | `archiviata`), `crediti_disponibili`, `data_convenzione`, `data_rinnovo` - -**`referente_partner`** -`id`, `associazione_id`, `persona_o_contatto`, `email`, `ruolo`, `attivo` -Struttura predisposta fin da subito per più referenti per associazione, anche se in v1 se ne usa uno. - -**`richiesta_pubblicazione`** -`id`, `associazione_id`, `testo`, `allegati` (JSON), `link`, `gruppi_destinatari` (JSON), `data_richiesta`, `data_pubblicazione_desiderata`, `stato`, `crediti_costo`, `revisore_persona_id`, `motivo_rifiuto`, `pubblicata_il` - -**`evento`** -`id`, `associazione_id`, `titolo`, `descrizione`, `data_inizio`, `data_fine`, `luogo`, `link_online`, `link_iscrizione`, `immagine_url`, `stato`, `data_rimozione`, `revisore_persona_id`, `motivo_rifiuto` - -**`richiesta_modifica_pagina`** -`id`, `associazione_id`, `campi_modificati` (JSON con valore precedente e nuovo), `stato`, `richiesta_da`, `revisore_persona_id`, `motivo_rifiuto` - -**`movimento_credito`** -`id`, `associazione_id`, `delta`, `causale`, `richiesta_id`, `saldo_risultante`, `creato_da`, `creato_il` - -### 9.2 Accesso e gestione degli account - -- PoliNetwork crea per ogni associazione partner un indirizzo `@polinetwork.org` dedicato, usato come identità di accesso. -- Login tramite magic link inviato a quell'indirizzo (vedi 2.1). Non ci sono password da recuperare. -- Il superadmin può: creare, sospendere, riattivare e archiviare un account; cambiare il referente mantenendo lo storico; vedere l'ultimo accesso di ogni associazione. -- Il cambio di referente non cancella nulla: le richieste passate restano attribuite all'associazione, non alla persona. -- La soluzione deve reggere ordinatamente **decine di associazioni**: nessuna configurazione manuale per associazione oltre alla creazione dell'account. - -### 9.3 Richieste di pubblicazione nei gruppi - -**Stati:** `bozza` → `inviata` → `in_revisione` → `approvata` → `programmata` → `pubblicata`, con uscite `respinta` e `annullata`. - -Il partner compila: testo del messaggio, gruppi o insiemi di gruppi destinatari, allegati o link, data di pubblicazione desiderata. Vede lo stato della richiesta e lo storico completo delle richieste precedenti. - -PoliNetwork revisiona, approva o respinge indicando il motivo. La pubblicazione effettiva nei gruppi in v1 è **manuale**: la dashboard produce il messaggio pronto e traccia lo stato. L'invio automatizzato verso Telegram/WhatsApp è fuori scope della v1 e va valutato separatamente (le API WhatsApp per i gruppi hanno vincoli rilevanti). - -**Sistema a crediti (proposta da validare):** - -- ogni associazione ha un saldo crediti; -- costo definito per invio, con moltiplicatore per numero di gruppi destinatari; -- i crediti si scalano **all'approvazione**, non all'invio della richiesta; una richiesta respinta non costa nulla; -- ricarica o rinnovo periodico impostato dal superadmin, con data di rinnovo visibile al partner; -- ogni movimento è registrato su `movimento_credito` e visibile al partner come estratto conto; -- il partner vede sempre: crediti disponibili, crediti utilizzati nel periodo, data del prossimo rinnovo. - -Se il Direttivo decide di non usare i crediti, il modulo resta disattivabile via configurazione senza rimuovere il codice. - -### 9.4 Pagina pubblica dell'associazione - -Ogni associazione ha una pagina pubblica sul sito PoliNetwork. Dalla dashboard il partner **richiede** modifiche a: nome e informazioni principali, descrizione, logo, sito web, Instagram, LinkedIn, altri social, contatti pubblici. - -Le modifiche non vanno mai in diretta: passano da `richiesta_modifica_pagina` con approvazione di PoliNetwork. Il revisore vede un confronto prima/dopo campo per campo e può approvare parzialmente. - -### 9.5 Eventi delle associazioni — nuovo PoliTamTam - -Evoluzione del PoliTamTam: punto unico in cui raccogliere e mostrare gli eventi delle associazioni sulla pagina eventi del sito PoliNetwork. - -**Stati:** `bozza` → `in_approvazione` → `pubblicato` → `concluso` → `archiviato`, con uscita `respinto`. - -**Decisione proposta:** gli eventi passano da approvazione di PoliNetwork prima della pubblicazione, coerentemente con il controllo editoriale sul sito. Eccezione configurabile: associazioni con status "verificato" pubblicano direttamente, con revisione a posteriori. Da confermare con il Team IT e il Direttivo. - -Regole aggiuntive: - -- rimozione automatica dalla pagina pubblica dopo `data_fine` (o dopo `data_rimozione` se valorizzata), con passaggio a `concluso`; -- gli eventi conclusi restano consultabili nell'archivio interno; -- il partner può modificare un evento già pubblicato solo su campi non critici (descrizione, immagine, link iscrizione); modifiche a data, luogo o titolo rientrano in approvazione; -- immagini validate per formato e dimensione massima, servite ridimensionate. - -### 9.6 Criteri di accettazione Fase 2 - -- Un'associazione accede, inserisce un evento e lo vede sul sito entro un'approvazione, senza email a PoliNetwork. -- Una richiesta respinta non consuma crediti e mostra al partner il motivo del rifiuto. -- Un'associazione non vede in nessun modo dati di altre associazioni. -- Un evento concluso sparisce dalla pagina pubblica senza intervento manuale. - ---- - -# Parte III — Feature secondarie (Fase 3+) - -Utili, ma non devono ritardare le fasi precedenti. Ognuna richiede una progettazione dedicata prima dello sviluppo. - -## 10. Area Aziende - -Pubblicazione di annunci di lavoro e stage. Eventuale consultazione dei CV dei membri **solo** con consenso esplicito, revocabile, per singola azienda o per categoria, e con tracciamento di ogni accesso al CV. Senza un modello privacy approvato, la parte CV non si sviluppa. - -## 11. Area Proprietari di casa - -Area per la pubblicazione di annunci di affitto o vendita di camere e appartamenti. Richiede: verifica dell'identità dell'inserzionista, moderazione degli annunci, scadenza automatica, gestione delle segnalazioni. - -## 12. Bacheca ricerca casa e coinquilini - -Annunci di ricerca stanza/appartamento, ricerca coinquilini e affini, riservata agli utenti autenticati. Richiede moderazione e scadenza automatica degli annunci. - -## 13. Newsletter - -Non deve bloccare la v1. In futuro riusa i dati già in piattaforma, in particolare gli eventi inseriti dalle associazioni partner, per comporre i contenuti. Modello editoriale, flusso di approvazione e provider di invio da definire in seguito. **Vincolo tecnico:** dominio o sottodominio di invio separato da quello delle email transazionali (vedi 2.4). - ---- - -## 14. Riepilogo delle fasi - -| Fase | Contenuto | Dipendenze | -|---|---|---| -| **0 — Fondamenta** | Auth, ruoli e permessi, modello dati, audit log, sistema email | Nessuna | -| **1 — Interno** | Anagrafica, Dashboard Admin/Capo Admin, Soci e Rinnovi, Onboarding, struttura Aree Team, compleanni | Fase 0 | -| **2 — Partner** | Account partner, PoliTamTam, richieste di pubblicazione, pagina pubblica, crediti | Fase 1 | -| **3 — Estensioni** | Strumenti specifici dei team, Aziende, Casa, Bacheca, Newsletter | Fase 2 | - -L'ordine indica dipendenze, non date. Le stime temporali vanno fatte dal Team IT sulla base della capacità effettiva. - ---- - -## 15. Fuori scope della v1 - -Da dichiarare esplicitamente per evitare aspettative: - -- pagamento delle quote direttamente in dashboard; -- invio automatizzato di messaggi verso gruppi WhatsApp e Telegram; -- integrazione Telegram per gli auguri di compleanno; -- app mobile; -- consultazione CV da parte delle aziende; -- newsletter. - ---- - -## 16. Decisioni ancora aperte - -Vanno chiuse prima dell'inizio dello sviluppo della fase corrispondente. - -| # | Decisione | Chi decide | Blocca | -|---|---|---|---| -| 1 | Conferma di Google Workspace come IdP per gli interni | Team IT | Fase 0 | -| 2 | Scelta del provider email transazionale | Team IT | Fase 0 | -| 3 | Stack e hosting della piattaforma | Team IT | Fase 0 | -| 4 | Parametri dei reminder di rinnovo (giorni e tolleranza) | Direttivo | Fase 1 | -| 5 | Ridisegno del flusso di onboarding | HR + Team IT | Fase 1 | -| 6 | Contenuto dei template email (rinnovo, conferma, benvenuto, compleanno) | Direttivo + Design & Social | Fase 1 | -| 7 | Uso o meno del sistema a crediti e relativo listino | Direttivo | Fase 2 | -| 8 | Approvazione preventiva o pubblicazione diretta degli eventi partner | Direttivo + Team IT | Fase 2 | -| 9 | Modello privacy per la consultazione dei CV | Direttivo | Fase 3 | From 24334c587b9a313754a60749a978c875eaf29169 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gabriele=20Vigan=C3=B2?= Date: Wed, 19 Aug 2026 23:15:34 +0000 Subject: [PATCH 3/6] docs: add admin dashboard PRD and feature roadmap --- PRD_Admin_Dashboard_PoliNetwork.md | 439 +++++++++++++++++++++++++++++ 1 file changed, 439 insertions(+) create mode 100644 PRD_Admin_Dashboard_PoliNetwork.md diff --git a/PRD_Admin_Dashboard_PoliNetwork.md b/PRD_Admin_Dashboard_PoliNetwork.md new file mode 100644 index 0000000..e13f17a --- /dev/null +++ b/PRD_Admin_Dashboard_PoliNetwork.md @@ -0,0 +1,439 @@ +# PRD — Admin Dashboard PoliNetwork + +**Documento di prodotto per il Team IT** +**Versione:** 1.0 +**Data:** 20 agosto 2026 +**Stato:** Bozza per revisione +**Branch/commit di riferimento per l'analisi:** `report/new-feature-roadmap`, con `pnpm install --frozen-lockfile` eseguito per ispezionare il contratto `@polinetwork/backend@0.17.1`. + +## 0. Scopo e metodo di questo documento + +Questo documento è un **nuovo PRD**, distinto da [`PRD_Admin_Dashboard_Associazione.md`](PRD_Admin_Dashboard_Associazione.md) (v0.2, non modificato). Il vecchio documento resta un riferimento sui bisogni di business espressi dall'associazione, ma **non è usato come fonte di verità tecnica**: ogni funzionalità qui descritta è stata verificata direttamente su: + +- il codice del frontend/BFF in `src/` (route, feature, server functions, middleware di autorizzazione); +- il contratto tipizzato del backend reale, `node_modules/@polinetwork/backend/dist/index.d.ts` (unica sorgente di verità su cosa il backend espone oggi via tRPC: router `tg`, `azure`, `web`, `auth`, `test`); +- i test (`tests/server-security.test.mjs`) e la configurazione (`AGENTS.md`, `package.json`, `README.md`). + +Dove il vecchio PRD presuppone dati, ruoli o flussi che non esistono nel codice attuale, questo documento lo segnala esplicitamente come **mancante**, propone l'ipotesi minima necessaria per renderlo implementabile, e rimanda le decisioni non deducibili alla sezione **11. Decisioni aperte**. + +**Criterio di priorità dichiarato dal Team IT e applicato qui:** le funzionalità interne di PoliNetwork (censimento soci, ruoli e gerarchie, governance, team) hanno priorità sulle aree pensate per soggetti esterni (associazioni partner, aziende, alloggi), **anche dove il vecchio PRD indicava l'ordine opposto**. Questo è il motivo principale per cui la struttura delle priorità in questo documento differisce da quella del documento originale. + +--- + +## 1. Stato reale verificato della piattaforma + +### 1.1 Stack e perimetro del repository + +- Frontend: React 19, TanStack Start/Router, Vite, server Nitro, Tailwind CSS v4, shadcn/ui, TanStack Table (`package.json`, `README.md`). +- Autenticazione: Better Auth (client in `src/lib/auth.ts`, server in `src/server/auth.server.ts`), con email OTP e passkey (`@better-auth/passkey`). +- Backend: **esterno**, consumato come pacchetto npm tipizzato `@polinetwork/backend` via tRPC (`AppRouter`) più un plugin Better Auth dedicato per il collegamento Telegram. Questo repository **non ha database proprio, non ha job/cron, non ha invio email**: tutta la logica di dominio (utenti Telegram, gruppi, membri Azure, contenuti web) vive nel backend condiviso. +- `AGENT_MODE=true` (solo se `NODE_ENV=development`) sostituisce sessione e ruoli con una sessione fittizia con tutti i ruoli admin, esclusivamente per anteprime locali (`src/server/auth.server.ts:16-44`, `AGENTS.md`). Non ha effetto in produzione. + +### 1.2 Autenticazione e onboarding — flusso verificato + +1. `/login`: email OTP o passkey (`src/features/auth/login-page.tsx`). Nessuna registrazione self-service: presuppone un account Better Auth già esistente. +2. Dopo il login, `dashboardAccessMiddleware`/`adminMiddleware` (`src/server/auth.middleware.ts`) controllano la sessione: + - nessun `telegramId` collegato → redirect a `/onboarding/link`, dove l'utente genera un codice temporizzato e lo usa con `/link` sul bot Telegram (`src/features/onboarding/telegram-link-page.tsx`); + - `telegramId` presente ma nessun ruolo admin → redirect a `/onboarding/unauthorized`; + - ruolo admin presente → accesso a `/dashboard`. +3. I ruoli non sono un concetto della dashboard: sono **letti in diretta da Telegram** (`backend.tg.permissions.getRoles`), la stessa fonte usata dal bot. + +### 1.3 Ruoli e permessi — modello attuale (`src/server/authorization.ts`, contratto `USER_ROLE`) + +Il backend Telegram conosce sei ruoli: `admin`, `hr`, `president`, `direttivo`, `creator`, `owner`. + +| Ruolo | Accesso dashboard (`ADMIN_ROLES`) | Scrittura dashboard (`WRITE_ADMIN_ROLES`) | +|---|---|---| +| `owner` | sì | sì | +| `direttivo` | sì | sì | +| `president` | sì | sì | +| `hr` | sì | **no — sola lettura** (PR #67) | +| `admin` | **no** | no | +| `creator` | **no, escluso esplicitamente** anche se combinato con altri ruoli | no | + +Osservazioni rilevanti per questo PRD: + +- **Il ruolo base `admin` — la maggioranza dei collaboratori PoliNetwork — non ha alcun accesso alla dashboard oggi**, indipendentemente da eventuali incarichi come "Capo Admin". Questo è il gap principale rispetto alla sezione 3 del vecchio PRD ("Dashboard Admin e Capo Admin"). +- `creator` è escluso per progetto (`hasAdminRole` ritorna `false` se la lista ruoli contiene `creator`), verosimilmente per segregare l'account con pieni poteri sul bot dal pannello web. Va preservato salvo decisione contraria. +- I permessi sono **binari e globali per ruolo**: non esiste granularità per modulo/azione (es. "può leggere i soci ma non modificarli"), né scoping (es. "vede solo gli admin del proprio corso"). `hr` è l'unica eccezione, ed è un blocco di scrittura totale, non selettivo. +- **Non esistono nel backend**: concetto di "corso di studi", "team interno" (IT, Design & Social, International, HR, Events & Partnerships), "Capo Admin", "rappresentante". Sono assenti sia come ruolo Telegram sia come campo dati in qualunque entità esposta dal contratto. + +### 1.4 Cosa esiste davvero, area per area + +| Area | Percorso | Stato | Dettaglio verificato | +|---|---|---|---| +| Overview | `/dashboard` | **Implementato (minimale)** | Sei card statiche di collegamento alle aree (`overview-page.tsx`). Nessun KPI, alert, scadenza o attività recente. | +| Telegram Users | `/dashboard/telegram/users`, `/users/$userId` | **Implementato** | Elenco (ricerca/paginazione lato client), profilo con ruoli, gruppi amministrati, ultimi messaggi, audit di moderazione, grant. Azioni: assegna/rimuovi ruolo e admin di gruppo, crea/interrompi grant. | +| Telegram Groups | `/dashboard/telegram/groups` | **Implementato** | Elenco, tag, invito, toggle visibilità, uscita dal gruppo con conferma. Manca creazione gruppo, ownership, statistiche, stato del bot. | +| Telegram Grants | `/dashboard/telegram/grants` | **Implementato** | Tab attivi/programmati, creazione/interruzione. Il backend espone solo `getOngoing`/`getScheduled`: **non esiste uno storico** dei grant terminati. | +| Azure Members | `/dashboard/azure/members` | **Implementato** | Elenco con numero associativo (`employeeId`) e licenze, filtro "solo membri", creazione con invio email di benvenuto, modifica numero. Nessuna cancellazione; nessuna gestione licenze (il backend non la espone). | +| Azure Groups | `/dashboard/azure/groups` | **Implementato** | Elenco gruppi, aggiunta/rimozione membri. | +| Web Associations | `/dashboard/web/associations` | **Implementato** | CRUD bilingue IT/EN, logo, 10 link social, editing inline. È la **vetrina pubblica** delle associazioni sul sito, non un'area a cui le associazioni stesse accedono. | +| Web Projects | `/dashboard/web/projects` | **Implementato** | CRUD bilingue, categorie (`news`/`general`/`deprecated`), drag&drop, logo, link. | +| Web Guides | `/dashboard/web/guides` | **Implementato** | Upload/versione/data/eliminazione PDF guida matricole. Manca bozza/approvazione, storico, anteprima pubblica. | +| Account | `/dashboard/account` | **Implementato** | Profilo, identità Telegram + ruoli, passkey, sessioni attive con revoca. | +| Onboarding/Login | `/login`, `/onboarding/*` | **Implementato** | Vedi §1.2. | + +### 1.5 Capacità del backend già pronte ma non raggiunte dal frontend + +- `web.faqs.*`: categorie e CRUD FAQ bilingue completo — pronto, nessuna pagina. +- `tg.permissions.getDirettivo`: composizione del Direttivo — pronto, nessuna UI di governance. +- `tg.permissions.canAddBot`, `tg.groups.search/getByTag/getByInviteLink` — pronti, non usati. +- `web.guides_matricole.getLatestGuide` — pronto, non mostrato da nessuna parte come "ultima guida disponibile". + +### 1.6 Cosa non esiste — né in frontend né nel contratto backend + +Nessuna delle seguenti è realizzabile senza nuovo lavoro sul backend condiviso o su un nuovo servizio dati: + +- Un'entità **socio/membro associativo** indipendente da Telegram e da Azure. Oggi il numero associativo esiste solo dentro Azure (`azure.members.setAssocNumber`), e presuppone un account Microsoft 365 — un volontario senza account Azure non è "socio" da nessuna parte. +- Stato di iscrizione, rinnovo, scadenza, storico pagamenti. +- Invio email automatico (rinnovo, compleanno, benvenuto oltre a quello già presente per la creazione membro Azure) — non esiste un motore di scheduling/cron in questo repository, che è un frontend/BFF. +- Integrazione WhatsApp (solo Telegram è integrato, in ogni sua parte). +- Eventi delle associazioni / "PoliTamTam". +- Sistema di crediti per le associazioni partner. +- Accesso alla dashboard per le associazioni partner stesse (oggi l'autenticazione presuppone un singolo tipo di utente: un collaboratore interno con ruolo Telegram). +- "Corso di studi", "team interno", "Capo Admin", "rappresentante" come dati. +- Workflow di candidatura/onboarding per nuovi admin. +- Un **audit log amministrativo** che copra le azioni della dashboard stessa (creazione/modifica associazione, assegnazione ruolo, ecc.). Esiste solo l'audit di moderazione Telegram (`ban`/`unban`/`kick`/`mute`/`unmute`/`ban_all`/`unban_all`), che riguarda la moderazione dei gruppi, non le operazioni amministrative sulla piattaforma. + +--- + +## 2. Principi guida di questo PRD + +1. **Priorità interna prima che esterna**: censimento, ruoli, governance e team vengono prima di associazioni partner, aziende, alloggi — vedi §0. +2. **Una sola identità persona**: qualunque nuova funzionalità deve collegarsi all'identità esistente (Telegram / Azure / Better Auth), non aggiungere una quarta rappresentazione scollegata. +3. **Continuità del modello di permessi**: qualunque estensione dei permessi deve restare compatibile con `ADMIN_ROLES`/`WRITE_ADMIN_ROLES` e i ruoli Telegram esistenti, introducendo granularità in modo incrementale. +4. **Nessuna azione distruttiva multipla senza anteprima e conferma esplicita** — vincolo permanente da `AGENTS.md`. +5. **Minimizzazione dei dati personali**: ogni nuovo campo su soci/admin deve avere uno scopo dichiarato, un responsabile e un'ipotesi di retention. +6. **Riuso prima di ricostruzione**: dove il backend espone già una capacità (FAQ, Direttivo, ricerca gruppi), si costruisce la UI prima di chiedere nuovo lavoro di backend. + +--- + +## 3. Persone, ruoli, gerarchie e struttura organizzativa + +Questa sezione risponde esplicitamente alla richiesta di un'attenzione dedicata a membri, soci, admin, team, gerarchie e permessi. + +### 3.1 I tre piani oggi sovrapposti + +Nel sistema attuale esiste un solo piano di identità/permesso: il ruolo Telegram. Concettualmente andrebbero distinti tre piani, oggi confusi in uno: + +| Piano | Cosa rappresenta | Stato oggi | +|---|---|---| +| Ruolo associativo/organizzativo | Chi sei nell'associazione: socio, admin, Capo Admin, membro del Direttivo, Presidente | **Non esiste come dato**: è implicito nei ruoli Telegram, che però non distinguono "admin semplice" da "Capo Admin" | +| Ruolo/permesso Telegram | Cosa puoi fare nei gruppi gestiti dal bot | Esiste (`USER_ROLE`) | +| Permesso applicativo della dashboard | Cosa puoi vedere/modificare in questa applicazione | Esiste solo come mappatura 1:1 dal ruolo Telegram (`ADMIN_ROLES`/`WRITE_ADMIN_ROLES`) | + +**Raccomandazione**: introdurre progressivamente il primo piano come dato del futuro Censimento (§5.2), e permessi applicativi granulari (§5.1.1) sopra — senza necessariamente toccare il piano Telegram, che resta la fonte di verità per la moderazione dei gruppi. + +### 3.2 Membri, soci e admin — la distinzione da fissare + +Il vecchio PRD usa "socio" (chi versa la quota associativa) e "admin" (chi si occupa operativamente dell'associazione, spesso ma non necessariamente anche socio) come categorie distinte. **Nel codice attuale questa distinzione non esiste**: `AzureMember.isMember` è l'unico flag di appartenenza, e riguarda solo chi ha (o dovrebbe avere) un account Microsoft 365. Un admin senza account Azure non è "socio" in nessuna parte del sistema oggi. + +**Ipotesi minima adottata in questo PRD** (da confermare, vedi Decisioni aperte §11): + +- Un **Socio** è un record del futuro Censimento (§5.2), indipendente da Telegram e da Azure. +- Un **Admin** è un Socio con un ruolo organizzativo aggiuntivo (Admin, Capo Admin, Direttivo, Presidente, ...) e — se opera sui canali PoliNetwork — con un'identità Telegram collegata, necessaria per accedere alla dashboard con l'attuale meccanismo di autenticazione. +- Un **Capo Admin** è un Admin con uno scope aggiuntivo (es. corso di studi) e visibilità limitata al proprio ambito. + +### 3.3 Gerarchia proposta (minima, non inventata) + +``` +Owner / Presidente / Direttivo — governance, accesso e scrittura completi + │ + Capo Admin (per corso/ambito) — visibilità e azioni limitate al proprio ambito + │ + Admin — operativo, oggi senza accesso alla dashboard + │ + Socio — non ha accesso alla dashboard; è un record del censimento +``` + +Questa gerarchia **non corrisponde a nulla nel backend attuale** oltre al livello Owner/Presidente/Direttivo/HR. Costruirla richiede: un nuovo campo scope (es. corso di studi) sugli admin, un modo per marcare "Capo Admin" (nuovo ruolo o flag con scope), e l'estensione di `ADMIN_ROLES` per dare accesso in lettura scoped agli admin semplici e ai Capo Admin — oggi esclusi. + +--- + +## 4. Matrice di priorità complessiva + +Legenda stato: 🟢 Implementato · 🟡 Parziale · 🔴 Mancante + +| # | Funzionalità | Origine | Stato | Priorità | Dipendenza principale | +|---|---|---|---|---|---| +| 1 | RBAC granulare per modulo/scope | Nuova (emersa dall'analisi) | 🔴 | **P0** | Nessuna, estende `authorization.ts` | +| 2 | Audit amministrativo unificato | Nuova | 🔴 | **P0** | Nuovo schema/endpoint backend | +| 3 | Censimento Soci (anagrafica) | Vecchio PRD §4 (implicito) | 🔴 | **P1** | Nuovo dominio dati backend | +| 4 | Dashboard "command center" (home con KPI) | Nuova, evoluzione overview attuale | 🟡 | **P1** | Aggregati dal Censimento | +| 5 | Governance / Direttivo | Nuova (backend pronto) | 🟡 (backend pronto, UI assente) | **P1** | Nessuna per MVP read-only | +| 6 | Dashboard Admin e Capo Admin | Vecchio PRD §3 | 🔴 | **P1** | Censimento + nuovo scope "corso" + estensione ruoli | +| 7 | Gestione Soci e Rinnovi | Vecchio PRD §4 | 🔴 | **P1** | Censimento + servizio email nel backend condiviso | +| 8 | FAQ (Web) | Nuova (backend pronto) | 🟡 (backend pronto, UI assente) | **P1** | Nessuna, basso sforzo | +| 9 | Aree Team interni | Vecchio PRD §2 | 🔴 | **P2** | Struttura team come dato | +| 10 | Onboarding nuovi Admin | Vecchio PRD §6 | 🔴 | **P2** | Riprogettazione di processo con HR, poi Censimento | +| 11 | Email di compleanno | Vecchio PRD §5 | 🔴 | **P2** | Censimento (data di nascita non esiste oggi) | +| 12 | Miglioramenti Telegram (storico grant, moderazione) | Aree esistenti | 🟡 | **P2** | Nuovi endpoint backend per lo storico | +| 13 | Miglioramenti Azure (licenze, access review) | Aree esistenti | 🟡 | **P2** | Estensione backend/Graph | +| 14 | Area Associazioni Partner (accesso, richieste, crediti) | Vecchio PRD §1 (era P0 lì) | 🔴 | **P2** (declassata, vedi §0) | Nuovo modello di autenticazione multi-tenant | +| 15 | Eventi associazioni / PoliTamTam | Vecchio PRD §1.4 | 🔴 | **P2** | Area Associazioni Partner o inserimento solo lato PoliNetwork | +| 16 | Area Aziende | Vecchio PRD §7 | 🔴 | **P3** | Da progettare, soggetti esterni | +| 17 | Area proprietari casa / Bacheca casa | Vecchio PRD §8-9 | 🔴 | **P3** | Da progettare, soggetti esterni | +| 18 | Newsletter | Vecchio PRD §10 | 🔴 | **P3** | Censimento + eventi | + +--- + +## 5. Feature prioritarie — dominio interno PoliNetwork + +### 5.1 Fondamenta (P0) + +#### 5.1.1 Autorizzazione per capacità (RBAC granulare) + +**Stato: mancante.** Oggi un ruolo apre o chiude intere aree; non esiste un permesso per singola azione né uno scoping ("solo il mio corso", "solo lettura su questo modulo"). + +Requisiti minimi: +- Permessi indipendenti per modulo: lettura/scrittura su soci, Telegram, Azure, contenuti, governance, audit. +- Composizione di ruoli: un utente può avere più capacità (es. Content editor + Telegram moderator). +- Azioni ad alto impatto (cancellazioni, assegnazione ruoli, rimozione da gruppi, export dati personali) devono mostrare il permesso richiesto e richiedere conferma esplicita. +- Deve restare retrocompatibile con `ADMIN_ROLES`/`WRITE_ADMIN_ROLES`: i ruoli Telegram esistenti diventano un caso particolare del nuovo modello, non vengono sostituiti da un giorno all'altro. + +#### 5.1.2 Audit amministrativo unificato + +**Stato: mancante** (esiste solo l'audit di moderazione Telegram, dominio diverso). + +Ogni mutazione lanciata da `writeAdminMiddleware` dovrebbe produrre una voce di audit con: attore, ruolo al momento dell'azione, timestamp, oggetto modificato, valori prima/dopo, motivo (obbligatorio per azioni sensibili), esito. Necessario prima di esporre dati personali del Censimento a più ruoli. + +#### 5.1.3 Home come centro operativo + +**Stato: parziale** — oggi è un elenco statico di link (`overview-page.tsx:6-119`). Priorità P1 (dipende dagli aggregati del Censimento, quindi viene dopo le fondamenta P0), ma la si cita qui perché è il punto di ingresso di tutte le altre funzionalità: soci in scadenza, account non riconciliati, grant in scadenza, contenuti da pubblicare, attività recenti. Ogni indicatore deve poter essere cliccato per aprire la lista filtrata corrispondente. + +#### 5.1.4 Ricerca globale + +**Stato: mancante.** Una command palette che cerchi trasversalmente soci, utenti Telegram, gruppi, membri Azure, FAQ e contenuti, utile fin da subito e non dipendente dal Censimento (può iniziare cercando solo su Telegram/Azure/contenuti già esistenti). + +--- + +### 5.2 Censimento Soci — l'anagrafica associativa (P1) + +**Stato: mancante.** È il gap più importante identificato: oggi non esiste un'entità "persona" canonica. Telegram, Azure e Better Auth rappresentano la stessa persona con tre identità scollegate. + +#### 5.2.1 Entità e campi MVP + +| Blocco | Campi | Note | +|---|---|---| +| Identità | nome, cognome, email, telefono (opzionale) | | +| Identificativo | ID interno, numero associativo univoco | oggi vive solo in Azure; va deciso se resta lì o diventa proprietà di questa nuova entità (Decisione aperta) | +| Stato | prospect, richiesta, attivo, sospeso, scaduto, ex socio | | +| Iscrizione | data ingresso, periodo/anno associativo, data scadenza, stato rinnovo | | +| Profilo associativo | corso di studi, anno di corso, sede, competenze/interessi (opzionali) | necessario anche per §5.6 | +| Relazioni | ruolo organizzativo (§3.3), team, responsabile | | +| Integrazioni | Telegram ID/username, Azure user ID, ultimo sync | collega senza duplicare | +| Consensi | consenso, fonte, data, revoca | minimo indispensabile per email automatiche (§5.7, §5.8) | + +Vincoli: numero associativo univoco; storicizzazione degli stati (non sovrascrittura); nessuna cancellazione bulk senza anteprima e conferma; ogni lettura/scrittura sensibile passa per l'audit di §5.1.2. + +#### 5.2.2 Flusso MVP + +``` +Richiesta → verifica dati → deduplica → approvazione → numero socio + → collegamento opzionale a Telegram/Azure → welcome → rinnovo → storico +``` + +#### 5.2.3 Permessi + +- Creazione/modifica: ruoli con `members.write` (Direttivo/Owner/President inizialmente). +- Lettura: `members.read`, assegnabile anche a HR **in sola lettura** (coerente con il pattern già in uso per HR sul resto della dashboard). +- Un operatore deve poter creare un socio **senza** dover prima creare un account Azure: oggi non è possibile, perché il numero associativo esiste solo dentro Azure. + +--- + +### 5.3 Governance e Direttivo (P1) + +**Stato: parziale — il backend è pronto, manca la UI.** `tg.permissions.getDirettivo` restituisce già la composizione del Direttivo con `isPresident`. Un MVP a basso sforzo: + +- pagina "Direttivo" in sola lettura con i membri correnti; +- in una seconda iterazione: incarico, data inizio/fine, storico nomine (richiede nuovo storage, non presente nel contratto attuale). + +--- + +### 5.4 Dashboard Admin e Capo Admin (dal vecchio PRD §3, P1) + +**Stato: mancante**, sia come dato che come UI e come permesso (§3.3, §1.3). + +Requisiti (adattati dal vecchio PRD, subordinati al Censimento): + +- Vista Capo Admin: elenco degli admin del proprio corso di studi con nome, cognome, anno di corso, data di ingresso, flag rappresentante, altre associazioni di appartenenza, telefono, username/contatto Telegram, link rapido WhatsApp/Telegram. +- Filtri: nome/cognome, anno, rappresentanza, altre associazioni. +- Sezione link ai gruppi Telegram di competenza del Capo Admin. +- Permessi: il Capo Admin deve vedere **solo** i dati e i gruppi del proprio ambito — richiede lo scoping descritto in §5.1.1, non disponibile con il modello attuale a ruoli globali. + +**Precondizione bloccante**: senza il Censimento (corso di studi, data di ingresso, rappresentanza) e senza l'estensione dei permessi per dare accesso scoped a chi ha solo il ruolo `admin`, questa funzionalità non è costruibile nella forma descritta dal vecchio PRD. + +--- + +### 5.5 Gestione Soci e Rinnovi (dal vecchio PRD §4, P1) + +**Stato: mancante**, dipende interamente dal Censimento. + +- Rinnovo automatico via email poco prima della scadenza: richiede un motore di invio email nel backend condiviso (non presente in questo repository) e la data di scadenza del Censimento. +- Vista Direttivo sullo stato dei soci: da verificare, pagamento effettuato, pagamento non effettuato. +- Azioni: "Segna come pagato" (aggiorna stato + email di conferma), "Invia reminder" (nuova email di promemoria). +- Storico minimo delle azioni (chi ha segnato pagato, quando è stato inviato un reminder) — si appoggia all'audit unificato di §5.1.2. +- Il vecchio PRD dispensa esplicitamente dalla necessità di gestire il pagamento *dentro* la dashboard nella prima versione: manteniamo questa impostazione. + +--- + +### 5.6 Aree Team interni (dal vecchio PRD §2, P2) + +**Stato: mancante come dato**, ma la navigazione attuale (`dashboardNavigation` in `src/components/dashboard-navigation.ts`) è già organizzata a categorie modulari (Telegram / Azure / Web), quindi si presta ad accogliere nuove categorie (es. "Team IT", "Team HR", ...) senza ristrutturazioni. + +Per questa fase, l'obiettivo minimo è **struttura, ruoli e separazione degli accessi**, non le funzionalità specifiche di ciascun team (che il vecchio PRD stesso rimanda a una definizione successiva con i responsabili): + +- ogni team come entità del Censimento (§5.2, blocco "Relazioni"); +- pagina/area indipendente per team con permesso dedicato (si appoggia a §5.1.1); +- nessuna funzionalità specifica di team implementata in questa fase. + +--- + +### 5.7 Onboarding nuovi Admin (dal vecchio PRD §6, P2) + +**Stato: mancante.** Il vecchio PRD stesso richiede di ridisegnare il processo con HR e Team IT prima di digitalizzarlo: questo PRD conferma che **non esiste alcuna base dati di candidature oggi**, quindi non c'è nulla da migrare, solo da progettare da zero una volta chiarito il flusso (vedi Decisioni aperte §11). + +Ambito minimo suggerito una volta definito il processo: candidatura → stato → colloquio → approvazione → creazione profilo (Censimento) → assegnazione corso/ruoli/team → passaggi di ingresso operativo. + +--- + +### 5.8 Email di compleanno (dal vecchio PRD §5, P2) + +**Stato: mancante.** Dipende dal Censimento (nessuna entità ha oggi una data di nascita) e da un motore email nel backend condiviso. Riguarda solo i soci e solo l'email, come indicato nel vecchio PRD. + +--- + +### 5.9 FAQ pubbliche (P1, basso sforzo) + +**Stato: backend pronto, UI assente.** `web.faqs.*` espone già categorie e CRUD bilingue completo (§1.5). È il rapporto valore/sforzo migliore di tutto il documento: aggiungere `Web → FAQs` con categorie, domanda/risposta IT/EN, ricerca, riordino drag&drop (pattern già usato in `Web Projects`), stato bozza/pubblicata. + +--- + +### 5.10 Miglioramenti alle aree esistenti (P2) + +- **Telegram grants**: storico dei grant terminati/interrotti (richiede un endpoint backend dedicato: oggi esiste solo `getOngoing`/`getScheduled`); reminder sulle scadenze imminenti. +- **Telegram groups**: creazione/import di gruppi dalla dashboard, indicatori di salute (gruppo senza owner, invito rotto), statistiche. +- **Azure**: gestione licenze dalla UI (richiede estensione del backend/Graph API, oggi non esposta); access review periodico sui gruppi. +- **Guide**: workflow bozza/pubblicazione, anteprima PDF, storico versioni invece di sola sostituzione. + +--- + +## 6. Feature secondarie — aree per soggetti esterni + +Per il criterio dichiarato in §0 e §2.1, queste aree sono **declassate in priorità** rispetto al vecchio PRD, pur restando le funzionalità di business più corpose descritte nel documento originale. + +### 6.1 Area Associazioni Partner (dal vecchio PRD §1 — lì priorità massima) + +**Stato: mancante interamente.** Riguarda un pubblico esterno (le associazioni partner) e presuppone un **modello di autenticazione multi-tenant** che oggi non esiste: l'unico meccanismo di accesso attuale presume un singolo tipo di utente (un collaboratore interno con ruolo Telegram). Includerebbe, secondo il vecchio PRD: + +- accesso e gestione account per decine di associazioni (creazione/disattivazione, recupero credenziali, referenti multipli); +- richieste di pubblicazione nei gruppi WhatsApp/Telegram (**WhatsApp non è integrato in nessuna parte del sistema attuale**); +- gestione della pagina pubblica dell'associazione con flusso di richiesta/approvazione (oggi `Web Associations` è già CRUD **diretto** da parte di PoliNetwork, non un flusso di richiesta da parte dell'associazione — sarebbe un cambio di modello, non un'estensione); +- eventuale sistema a crediti (logica non definita nel vecchio PRD stesso); +- eventi delle associazioni / "PoliTamTam" (§6.2). + +Questo PRD non ne nega il valore di business, ma lo colloca dopo le fondamenta interne (§5), perché richiede decisioni architetturali (autenticazione multi-tenant, eventuale integrazione WhatsApp) che è più sicuro prendere dopo aver stabilizzato RBAC, audit e Censimento. + +### 6.2 Eventi delle associazioni — PoliTamTam (dal vecchio PRD §1.4) + +**Stato: mancante.** Dipende dalla decisione su §6.1: se le associazioni partner inseriscono direttamente gli eventi, serve prima l'accesso esterno; se invece PoliNetwork inserisce gli eventi per conto delle associazioni (variante più semplice e coerente con il modello attuale, dove solo PoliNetwork scrive contenuti pubblici), può essere realizzato prima, come estensione del modulo `Web` esistente, sullo stesso pattern di `Web Projects`/`Web Associations`. + +### 6.3 Area Aziende (dal vecchio PRD §7) + +**Stato: mancante.** Da progettare in dettaglio prima dello sviluppo, come indicato anche nel vecchio PRD. Priorità bassa in questo documento. + +### 6.4 Area proprietari di casa / Bacheca casa e coinquilini (dal vecchio PRD §8-9) + +**Stato: mancante.** Riguarda esclusivamente soggetti esterni (proprietari, cercatori di stanza). Priorità più bassa dell'intero documento. + +### 6.5 Newsletter (dal vecchio PRD §10) + +**Stato: mancante.** Il vecchio PRD la marca già come non bloccante. Dipende da Censimento (segmentazione destinatari) ed eventualmente da §6.2 (eventi come fonte di contenuti). + +--- + +## 7. Vincoli trasversali + +- **Nessuna azione distruttiva su più righe** senza anteprima e conferma esplicita (vincolo permanente, `AGENTS.md`). +- `AGENT_MODE` resta esclusivo dell'ambiente di sviluppo locale; ogni modifica a codice di autenticazione/redirect va verificata anche con `AGENT_MODE=false`. +- **Minimizzazione dati**: ogni campo del Censimento deve avere uno scopo dichiarato; dati sensibili (es. codice fiscale) solo se realmente necessari per il tesseramento. +- **Audit prima di esporre dati personali** a più ruoli (§5.1.2 è precondizione di §5.2, §5.4, §5.5). +- **Query lato server e paginazione reale**: oggi tutte le liste caricano `getAll` e filtrano nel browser (`users-page.tsx`, `members-page.tsx`, ecc.). Accettabile ai volumi attuali; da rivedere non appena il Censimento supera qualche centinaio di record. +- **Lingua**: i contenuti pubblici (associazioni, progetti, FAQ) sono già bilingue IT/EN nel backend; l'interfaccia amministrativa è oggi interamente in inglese. Va deciso un indirizzo esplicito (Decisione aperta §11) prima di aggiungere nuove pagine con testo lungo (es. Censimento, Rinnovi). + +--- + +## 8. Roadmap proposta + +| Fase | Contenuto | Obiettivo | +|---|---|---| +| **0 — Fondamenta** | RBAC per capacità (§5.1.1), audit unificato (§5.1.2), ricerca globale (§5.1.4) | Base sicura e osservabile per esporre dati personali in fase 1 | +| **1 — Censimento e governance** | Censimento Soci MVP (§5.2), pagina Direttivo read-only (§5.3), FAQ (§5.9) | Registro soci utilizzabile, primo valore rapido a basso sforzo | +| **2 — Gerarchia e rinnovi** | Dashboard Admin/Capo Admin (§5.4), Gestione Soci e Rinnovi (§5.5), home come command center (§5.1.3) | Gestione del ciclo di vita di admin e soci | +| **3 — Team e onboarding** | Aree Team (§5.6), Onboarding nuovi Admin (§5.7, dopo riprogettazione con HR), email di compleanno (§5.8) | Copertura dei processi interni residui | +| **4 — Aree esistenti** | Miglioramenti Telegram/Azure (§5.10) | Colmare i gap sulle integrazioni già in produzione | +| **5 — Aree esterne** | Associazioni Partner (§6.1), PoliTamTam (§6.2) | Prima area rivolta a soggetti esterni, dopo le fondamenta interne | +| **6 — Espansione** | Aziende, Casa, Newsletter (§6.3-6.5) | Funzionalità secondarie, a valutazione | + +--- + +## 9. Criteri di accettazione (MVP Censimento, come esempio di riferimento) + +Ripresi e confermati perché indipendenti da qualunque decisione aperta: + +- Un operatore può creare un socio senza dover prima creare un account Azure. +- La scheda del socio mostra chiaramente identità locale, Telegram e Azure e segnala i collegamenti mancanti. +- Nessuna scrittura in un'importazione massiva prima della conferma di un'anteprima. +- Un ruolo HR read-only può consultare solo ciò che il suo permesso consente e non vede pulsanti di scrittura. +- Ogni cambio di stato, numero associativo o identità esterna è rintracciabile nell'audit. +- Nessuna cancellazione massiva senza conferma esplicita e riepilogo delle righe coinvolte. + +--- + +## 10. Cosa NON fa parte di questo PRD + +- Non ridefinisce lo statuto, gli organi sociali o le regole di voto dell'associazione: assume che la struttura Owner/Presidente/Direttivo esistente sui ruoli Telegram sia quella corretta finché non diversamente indicato. +- Non decide se e come integrare pagamenti (Stripe, bonifico, altro): il vecchio PRD stesso rimanda il pagamento fuori dalla dashboard nella prima versione, e questo documento mantiene la stessa impostazione. +- Non propone una contabilità completa (fatture, bilanci): per pagamenti e documenti sensibili resta preferibile integrare servizi specializzati. + +--- + +## 11. Decisioni aperte + +Raggruppate per paragrafo di riferimento. Nessuna ipotesi organizzativa è stata inventata: dove il vecchio PRD o il codice non permettevano di dedurre una risposta, la domanda è riportata qui invece di essere decisa autonomamente. + +**§3 — Ruoli e gerarchie** +1. Il ruolo "Capo Admin" va modellato come nuovo ruolo Telegram/backend, o come attributo applicativo (scope) sopra il ruolo `admin` esistente, gestito solo lato dashboard? +2. Chi assegna e revoca il ruolo di Capo Admin, e con quale periodicità (es. legato all'anno accademico)? +3. Il ruolo `admin` "semplice" deve ottenere accesso alla dashboard (anche solo in lettura sul proprio ambito), oppure resta escluso come oggi? + +**§5.2 — Censimento Soci** +4. Il numero associativo resta una proprietà di Azure, o diventa proprietà del nuovo registro soci (con Azure che lo referenzia)? +5. L'iscrizione è annuale, semestrale o senza scadenza? +6. Quali dati sono realmente necessari per il tesseramento (es. il codice fiscale è richiesto dal processo associativo reale, o va escluso)? +7. Un ruolo HR read-only può leggere tutti i campi del socio, o alcuni campi (es. dati di contatto personali) devono essere mascherati anche per HR? + +**§5.4 — Dashboard Admin e Capo Admin** +8. Come si definisce "corso di studi" nel sistema (elenco chiuso dei corsi del Politecnico, testo libero, altro)? +9. Un admin può appartenere a più corsi/ambiti, o a uno solo? + +**§5.5 — Gestione Soci e Rinnovi** +10. Il pagamento della quota resta interamente manuale (bonifico/altro) fuori dashboard, o si prevede in futuro un'integrazione (es. Stripe)? +11. Chi ha il permesso di "segnare come pagato": solo Direttivo, o anche un ruolo Finance dedicato non ancora esistente? + +**§5.7 — Onboarding nuovi Admin** +12. Il processo di candidatura/colloquio è già stato ridisegnato con HR e Team IT (come richiesto dal vecchio PRD stesso), o va progettato da zero in questo ciclo? + +**§6.1 — Area Associazioni Partner** +13. Un account per associazione, o più referenti per la stessa associazione fin dal MVP? +14. Le richieste di pubblicazione riguardano solo Telegram (unico canale oggi integrato) o resta necessaria l'integrazione WhatsApp menzionata nel vecchio PRD? +15. Il sistema a crediti per le pubblicazioni resta previsto, e con quale logica di ricarica/consumo? +16. La gestione della pagina pubblica dell'associazione deve diventare un flusso di richiesta/approvazione (come indicato dal vecchio PRD), sostituendo l'attuale CRUD diretto di PoliNetwork su `Web Associations`? + +**§6.2 — Eventi / PoliTamTam** +17. Gli eventi sono inseriti direttamente dalle associazioni partner (richiede §6.1) o da PoliNetwork per conto loro (realizzabile prima, sul modello di `Web Projects`)? +18. Gli eventi vengono pubblicati immediatamente o richiedono approvazione PoliNetwork? + +**§7 — Lingua dell'interfaccia** +19. L'interfaccia amministrativa deve diventare bilingue con preferenza per utente, o restare in italiano per il team associativo mantenendo IT/EN solo sui contenuti pubblici? From d2f0cda9fe119dbca81e13e60a5cc4398bff7500 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gabriele=20Vigan=C3=B2?= Date: Sat, 29 Aug 2026 02:18:52 +0200 Subject: [PATCH 4/6] docs: apply Team IT corrections to admin dashboard PRD MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Split soci/admin/team into independent, overlapping categories; split Censimento Soci into Anagrafica Soci (quota renewal) and Censimento Admin/Team (interest renewal); mark Direttivo governance page obsolete; add Identity Provider and privacy-consent requirements; rework rinnovi (receipt upload/approval), onboarding self-service flow, and partner association ownership transfer; resolve open decisions in §11. Co-Authored-By: Claude Sonnet 5 --- PRD_Admin_Dashboard_PoliNetwork.md | 275 ++++++++++++++++++----------- 1 file changed, 176 insertions(+), 99 deletions(-) diff --git a/PRD_Admin_Dashboard_PoliNetwork.md b/PRD_Admin_Dashboard_PoliNetwork.md index e13f17a..f696f43 100644 --- a/PRD_Admin_Dashboard_PoliNetwork.md +++ b/PRD_Admin_Dashboard_PoliNetwork.md @@ -1,8 +1,8 @@ # PRD — Admin Dashboard PoliNetwork **Documento di prodotto per il Team IT** -**Versione:** 1.0 -**Data:** 20 agosto 2026 +**Versione:** 1.1 +**Data:** 29 agosto 2026 (revisione con correzioni e decisioni del Team IT rispetto alla v1.0 del 20 agosto 2026) **Stato:** Bozza per revisione **Branch/commit di riferimento per l'analisi:** `report/new-feature-roadmap`, con `pnpm install --frozen-lockfile` eseguito per ispezionare il contratto `@polinetwork/backend@0.17.1`. @@ -16,7 +16,7 @@ Questo documento è un **nuovo PRD**, distinto da [`PRD_Admin_Dashboard_Associaz Dove il vecchio PRD presuppone dati, ruoli o flussi che non esistono nel codice attuale, questo documento lo segnala esplicitamente come **mancante**, propone l'ipotesi minima necessaria per renderlo implementabile, e rimanda le decisioni non deducibili alla sezione **11. Decisioni aperte**. -**Criterio di priorità dichiarato dal Team IT e applicato qui:** le funzionalità interne di PoliNetwork (censimento soci, ruoli e gerarchie, governance, team) hanno priorità sulle aree pensate per soggetti esterni (associazioni partner, aziende, alloggi), **anche dove il vecchio PRD indicava l'ordine opposto**. Questo è il motivo principale per cui la struttura delle priorità in questo documento differisce da quella del documento originale. +**Criterio di priorità dichiarato dal Team IT e applicato qui:** le funzionalità interne di PoliNetwork (anagrafica soci, censimento admin/team, ruoli e gerarchie, governance, team) hanno priorità sulle aree pensate per soggetti esterni (associazioni partner, aziende, alloggi), **anche dove il vecchio PRD indicava l'ordine opposto**. Questo è il motivo principale per cui la struttura delle priorità in questo documento differisce da quella del documento originale. --- @@ -100,7 +100,7 @@ Nessuna delle seguenti è realizzabile senza nuovo lavoro sul backend condiviso ## 2. Principi guida di questo PRD -1. **Priorità interna prima che esterna**: censimento, ruoli, governance e team vengono prima di associazioni partner, aziende, alloggi — vedi §0. +1. **Priorità interna prima che esterna**: anagrafica soci, censimento admin/team, ruoli, governance e team vengono prima di associazioni partner, aziende, alloggi — vedi §0. 2. **Una sola identità persona**: qualunque nuova funzionalità deve collegarsi all'identità esistente (Telegram / Azure / Better Auth), non aggiungere una quarta rappresentazione scollegata. 3. **Continuità del modello di permessi**: qualunque estensione dei permessi deve restare compatibile con `ADMIN_ROLES`/`WRITE_ADMIN_ROLES` e i ruoli Telegram esistenti, introducendo granularità in modo incrementale. 4. **Nessuna azione distruttiva multipla senza anteprima e conferma esplicita** — vincolo permanente da `AGENTS.md`. @@ -123,58 +123,71 @@ Nel sistema attuale esiste un solo piano di identità/permesso: il ruolo Telegra | Ruolo/permesso Telegram | Cosa puoi fare nei gruppi gestiti dal bot | Esiste (`USER_ROLE`) | | Permesso applicativo della dashboard | Cosa puoi vedere/modificare in questa applicazione | Esiste solo come mappatura 1:1 dal ruolo Telegram (`ADMIN_ROLES`/`WRITE_ADMIN_ROLES`) | -**Raccomandazione**: introdurre progressivamente il primo piano come dato del futuro Censimento (§5.2), e permessi applicativi granulari (§5.1.1) sopra — senza necessariamente toccare il piano Telegram, che resta la fonte di verità per la moderazione dei gruppi. +**Raccomandazione**: introdurre progressivamente il primo piano come dato del futuro Censimento Admin/Team e dell'Anagrafica Soci (§5.2), e permessi applicativi granulari (§5.1.1) sopra — senza necessariamente toccare il piano Telegram, che resta la fonte di verità per la moderazione dei gruppi. -### 3.2 Membri, soci e admin — la distinzione da fissare +### 3.2 Socio, Admin e membro di team — categorie indipendenti, non annidate -Il vecchio PRD usa "socio" (chi versa la quota associativa) e "admin" (chi si occupa operativamente dell'associazione, spesso ma non necessariamente anche socio) come categorie distinte. **Nel codice attuale questa distinzione non esiste**: `AzureMember.isMember` è l'unico flag di appartenenza, e riguarda solo chi ha (o dovrebbe avere) un account Microsoft 365. Un admin senza account Azure non è "socio" in nessuna parte del sistema oggi. +**Correzione rispetto a una lettura gerarchica**: il vecchio PRD usa "socio" (chi versa la quota associativa) e "admin" (chi si occupa operativamente dell'associazione) in un modo che suggerisce una relazione di inclusione ("admin, spesso ma non necessariamente anche socio"). Questa lettura va corretta: si tratta di **tre categorie indipendenti**, non di una gerarchia annidata: + +- **Socio**: chi risulta iscritto e in regola con la quota associativa (Anagrafica Soci, §5.2). +- **Admin**: chi ha un ruolo operativo/organizzativo su PoliNetwork (oggi il ruolo Telegram `admin` e superiori). +- **Membro di un team interno** (IT, Design & Social, International, HR, Events & Partnerships, ...): chi fa parte di un team (§5.6). + +Un admin può essere socio o no; un socio può essere admin o no; un membro di un team può essere admin, socio, entrambi o nessuno dei due. **Le tre categorie possono intersecarsi in qualunque combinazione** e nessuna implica automaticamente le altre due. + +**Il Socio resta comunque la categoria più rilevante per l'associazione**: è chi la costituisce formalmente dal punto di vista associativo. Admin e membro di team sono categorie organizzative/operative e non sostituiscono né presuppongono lo status di socio. + +Nel codice attuale questa distinzione non esiste: `AzureMember.isMember` è l'unico flag di appartenenza, e riguarda solo chi ha (o dovrebbe avere) un account Microsoft 365. Un admin senza account Azure non è "socio" in nessuna parte del sistema oggi. **Ipotesi minima adottata in questo PRD** (da confermare, vedi Decisioni aperte §11): -- Un **Socio** è un record del futuro Censimento (§5.2), indipendente da Telegram e da Azure. -- Un **Admin** è un Socio con un ruolo organizzativo aggiuntivo (Admin, Capo Admin, Direttivo, Presidente, ...) e — se opera sui canali PoliNetwork — con un'identità Telegram collegata, necessaria per accedere alla dashboard con l'attuale meccanismo di autenticazione. +- Un **Socio** è un record dell'Anagrafica Soci (§5.2), indipendente da Telegram e da Azure, e indipendente dall'essere o meno admin/membro di team. +- Un **Admin** è una persona con un ruolo organizzativo (Admin, Capo Admin, Direttivo, Presidente, ...) tracciato dal Censimento Admin/Team (§5.2) e — se opera sui canali PoliNetwork — con un'identità Telegram collegata, necessaria per accedere alla dashboard con l'attuale meccanismo di autenticazione. Non deve necessariamente essere anche Socio. - Un **Capo Admin** è un Admin con uno scope aggiuntivo (es. corso di studi) e visibilità limitata al proprio ambito. ### 3.3 Gerarchia proposta (minima, non inventata) +La gerarchia seguente riguarda **solo l'asse ruolo organizzativo/operativo** (Owner → Capo Admin → Admin). Lo status di **Socio** e l'appartenenza a un **team interno** sono assi indipendenti (§3.2): non sono un livello sotto "Admin", ma condizioni che possono coesistere con qualunque punto della gerarchia sottostante, o con nessuno. + ``` Owner / Presidente / Direttivo — governance, accesso e scrittura completi │ Capo Admin (per corso/ambito) — visibilità e azioni limitate al proprio ambito │ Admin — operativo, oggi senza accesso alla dashboard - │ - Socio — non ha accesso alla dashboard; è un record del censimento ``` -Questa gerarchia **non corrisponde a nulla nel backend attuale** oltre al livello Owner/Presidente/Direttivo/HR. Costruirla richiede: un nuovo campo scope (es. corso di studi) sugli admin, un modo per marcare "Capo Admin" (nuovo ruolo o flag con scope), e l'estensione di `ADMIN_ROLES` per dare accesso in lettura scoped agli admin semplici e ai Capo Admin — oggi esclusi. +Questa gerarchia **non corrisponde a nulla nel backend attuale** oltre al livello Owner/Presidente/Direttivo/HR. Costruirla richiede: un nuovo campo scope (es. corso di studi) sugli admin, un modo per marcare "Capo Admin" (nuovo ruolo o flag con scope — **ancora da decidere**, §11), e l'estensione di `ADMIN_ROLES` per dare accesso in lettura scoped agli admin semplici e ai Capo Admin. **Deciso**: l'admin semplice deve ottenere accesso alla dashboard, con permessi determinati dal proprio scope (§11) — oggi ne è escluso, quindi resta lavoro da fare su `authorization.ts`. --- ## 4. Matrice di priorità complessiva -Legenda stato: 🟢 Implementato · 🟡 Parziale · 🔴 Mancante +Legenda stato: 🟢 Implementato · 🟡 Parziale · 🔴 Mancante · ⚪ Obsoleto (non verrà realizzato) | # | Funzionalità | Origine | Stato | Priorità | Dipendenza principale | |---|---|---|---|---|---| | 1 | RBAC granulare per modulo/scope | Nuova (emersa dall'analisi) | 🔴 | **P0** | Nessuna, estende `authorization.ts` | | 2 | Audit amministrativo unificato | Nuova | 🔴 | **P0** | Nuovo schema/endpoint backend | -| 3 | Censimento Soci (anagrafica) | Vecchio PRD §4 (implicito) | 🔴 | **P1** | Nuovo dominio dati backend | -| 4 | Dashboard "command center" (home con KPI) | Nuova, evoluzione overview attuale | 🟡 | **P1** | Aggregati dal Censimento | -| 5 | Governance / Direttivo | Nuova (backend pronto) | 🟡 (backend pronto, UI assente) | **P1** | Nessuna per MVP read-only | -| 6 | Dashboard Admin e Capo Admin | Vecchio PRD §3 | 🔴 | **P1** | Censimento + nuovo scope "corso" + estensione ruoli | -| 7 | Gestione Soci e Rinnovi | Vecchio PRD §4 | 🔴 | **P1** | Censimento + servizio email nel backend condiviso | -| 8 | FAQ (Web) | Nuova (backend pronto) | 🟡 (backend pronto, UI assente) | **P1** | Nessuna, basso sforzo | -| 9 | Aree Team interni | Vecchio PRD §2 | 🔴 | **P2** | Struttura team come dato | -| 10 | Onboarding nuovi Admin | Vecchio PRD §6 | 🔴 | **P2** | Riprogettazione di processo con HR, poi Censimento | -| 11 | Email di compleanno | Vecchio PRD §5 | 🔴 | **P2** | Censimento (data di nascita non esiste oggi) | -| 12 | Miglioramenti Telegram (storico grant, moderazione) | Aree esistenti | 🟡 | **P2** | Nuovi endpoint backend per lo storico | -| 13 | Miglioramenti Azure (licenze, access review) | Aree esistenti | 🟡 | **P2** | Estensione backend/Graph | -| 14 | Area Associazioni Partner (accesso, richieste, crediti) | Vecchio PRD §1 (era P0 lì) | 🔴 | **P2** (declassata, vedi §0) | Nuovo modello di autenticazione multi-tenant | -| 15 | Eventi associazioni / PoliTamTam | Vecchio PRD §1.4 | 🔴 | **P2** | Area Associazioni Partner o inserimento solo lato PoliNetwork | -| 16 | Area Aziende | Vecchio PRD §7 | 🔴 | **P3** | Da progettare, soggetti esterni | -| 17 | Area proprietari casa / Bacheca casa | Vecchio PRD §8-9 | 🔴 | **P3** | Da progettare, soggetti esterni | -| 18 | Newsletter | Vecchio PRD §10 | 🔴 | **P3** | Censimento + eventi | +| 3 | Identity Provider PoliNetwork | Nuova (richiesta esplicita Team IT) | 🔴 | **P0** | Nuovo servizio; precondizione di §5.1.5, §5.7, §6.1 | +| 4 | Gestione consensi e firma privacy policy in dashboard | Nuova (richiesta esplicita Team IT) | 🔴 | **P0** | Identity Provider (#3) | +| 5 | Anagrafica Soci (attivi paganti + storico) | Vecchio PRD §4 (implicito), corretta | 🔴 | **P1** | Nuovo dominio dati backend | +| 6 | Censimento Admin/Team (rinnovo interesse) | Nuova, corretta da bozza "censimento soci" | 🔴 | **P1** | Nuovo dominio dati backend + Identity Provider (#3) per il flusso self-service (§5.7) | +| 7 | Dashboard "command center" (home con KPI) | Nuova, evoluzione overview attuale | 🟡 | **P1** | Aggregati da Anagrafica Soci/Censimento | +| 8 | Governance / Direttivo (pagina dedicata) | Nuova (backend pronto) | ⚪ **Obsoleto** | — | Assorbito dal Censimento Admin/Team (#6), vedi §5.3 | +| 9 | Dashboard Admin e Capo Admin | Vecchio PRD §3 | 🔴 | **P1** | Censimento Admin/Team + nuovo scope "corso" + estensione ruoli | +| 10 | Gestione Soci e Rinnovi (quota, ricevute) | Vecchio PRD §4, corretta | 🔴 | **P1** | Anagrafica Soci + upload/approvazione ricevute in dashboard | +| 11 | FAQ (Web) | Nuova (backend pronto) | 🟡 (backend pronto, UI assente) | **P1** | Nessuna, basso sforzo | +| 12 | Aree Team interni | Vecchio PRD §2 | 🔴 | **P2** | Struttura team come dato | +| 13 | Onboarding e Censimento Admin (flusso self-service) | Vecchio PRD §6, molto ampliata | 🔴 | **P2** | Identity Provider (#3), Censimento Admin/Team (#6) | +| 14 | Email di compleanno | Vecchio PRD §5 | 🔴 | **P2** | Anagrafica Soci (data di nascita non esiste oggi) | +| 15 | Miglioramenti Telegram (storico grant, moderazione) | Aree esistenti | 🟡 | **P2** | Nuovi endpoint backend per lo storico | +| 16 | Miglioramenti Azure (licenze, access review) | Aree esistenti | 🟡 | **P2** | Estensione backend/Graph | +| 17 | Area Associazioni Partner (accesso multi-referente, richieste, crediti) | Vecchio PRD §1 (era P0 lì), corretta | 🔴 | **P2** (declassata, vedi §0) | Identity Provider (#3) per l'accesso esterno multi-tenant | +| 18 | Eventi associazioni / PoliTamTam | Vecchio PRD §1.4, corretta | 🔴 | **P2** | Area Associazioni Partner (#17), flusso di approvazione | +| 19 | Area Aziende | Vecchio PRD §7 | 🔴 | **P3** | Da progettare, soggetti esterni | +| 20 | Area proprietari casa / Bacheca casa | Vecchio PRD §8-9 | 🔴 | **P3** | Da progettare, soggetti esterni | +| 21 | Newsletter | Vecchio PRD §10 | 🔴 | **P3** | Anagrafica Soci + eventi | --- @@ -206,48 +219,88 @@ Ogni mutazione lanciata da `writeAdminMiddleware` dovrebbe produrre una voce di **Stato: mancante.** Una command palette che cerchi trasversalmente soci, utenti Telegram, gruppi, membri Azure, FAQ e contenuti, utile fin da subito e non dipendente dal Censimento (può iniziare cercando solo su Telegram/Azure/contenuti già esistenti). +#### 5.1.5 Gestione dei consensi e firma della privacy policy in dashboard + +**Stato: mancante.** Oggi le autorizzazioni privacy vengono raccolte tramite vari form esterni inviati caso per caso. Questo espone a un rischio concreto: le domande dei form possono cambiare o diventare obsolete nel tempo, e la perdita o l'abbandono di un form significa perdere anche la possibilità di dimostrare/recuperare il consenso raccolto con quella versione. + +Requisiti minimi: +- La firma della privacy policy (e di eventuali altre informative) avviene **dentro il flusso della dashboard** (iscrizione socio, §5.2.2; onboarding/censimento admin, §5.7), non più solo tramite form esterni scollegati. +- Ogni consenso registrato è legato a una **versione specifica del testo firmato**, con data e revoca tracciabili nel tempo (campo "Consensi" di §5.2.1/§5.2.3): un cambiamento futuro del testo non invalida né sovrascrive lo storico dei consensi già raccolti. +- L'evento di firma passa per l'audit unificato (§5.1.2). +- Richiede l'Identity Provider (§5.1.6) per autenticare con certezza chi sta firmando prima di associare il consenso alla persona corretta. + +#### 5.1.6 Identity Provider PoliNetwork + +**Stato: mancante — nuovo requisito del Team IT.** Il Team IT ha richiesto esplicitamente di realizzare un **identity/authentication provider** proprio di PoliNetwork, distinto dal semplice login attuale (email OTP/passkey su Better Auth, §1.2), da usare come punto di ingresso unico per i flussi self-service rivolti a persone interne (ed eventualmente esterne): + +- autenticazione preventiva obbligatoria prima di qualunque flusso di censimento/onboarding (§5.7), firma documenti (§5.1.5) o consultazione delle proprie statistiche/riferimenti (es. Capo Admin di riferimento); +- base per assegnare permessi differenziati "in base a cosa la persona fa/è" all'interno di PoliNetwork (ogni persona ha comunque un livello minimo di accesso alle proprie informazioni); +- precondizione per un futuro accesso esterno multi-tenant (associazioni partner, §6.1), oggi non supportato dal modello di autenticazione attuale. + +Il rapporto tra questo nuovo Identity Provider e l'attuale Better Auth (sostituzione, estensione, o livello applicativo sopra le identità Telegram/Azure esistenti) resta una decisione architetturale da prendere a parte (vedi Decisioni aperte, §11): questo PRD ne registra il requisito, non la soluzione tecnica. + --- -### 5.2 Censimento Soci — l'anagrafica associativa (P1) +### 5.2 Anagrafica Soci e Censimento Admin/Team (P1) **Stato: mancante.** È il gap più importante identificato: oggi non esiste un'entità "persona" canonica. Telegram, Azure e Better Auth rappresentano la stessa persona con tre identità scollegate. -#### 5.2.1 Entità e campi MVP +**Correzione rispetto a una bozza precedente che parlava genericamente di "censimento soci"**: si tratta in realtà di due cose distinte, coerenti con l'indipendenza delle categorie di §3.2: + +- **Anagrafica Soci**: un registro dei **soci attivi e paganti**, con **storico** dei soci passati. Per un socio l'azione ricorrente è il **rinnovo della quota associativa** (§5.5), non una rilevazione periodica di interesse. +- **Censimento Admin/Team**: una rilevazione rivolta ad **admin e membri dei team**, il cui scopo è **rinnovare l'interesse/la disponibilità** a continuare il proprio ruolo organizzativo — non una quota. Si integra con l'Onboarding (§5.7). + +Una persona può comparire in entrambi, in uno solo, o in nessuno dei due (§3.2). + +#### 5.2.1 Anagrafica Soci — campi MVP | Blocco | Campi | Note | |---|---|---| | Identità | nome, cognome, email, telefono (opzionale) | | -| Identificativo | ID interno, numero associativo univoco | oggi vive solo in Azure; va deciso se resta lì o diventa proprietà di questa nuova entità (Decisione aperta) | -| Stato | prospect, richiesta, attivo, sospeso, scaduto, ex socio | | -| Iscrizione | data ingresso, periodo/anno associativo, data scadenza, stato rinnovo | | +| Identificativo | ID interno, numero associativo univoco | **Deciso**: il numero associativo diventa proprietà di questo nuovo registro (database PoliNetwork); Azure lo referenzia se presente, non è più l'unica fonte (§11) | +| Stato | attivo pagante, sospeso, scaduto, ex socio | | +| Iscrizione | data ingresso, anno associativo (**deciso: iscrizione annuale**, §11), data scadenza, stato rinnovo | | | Profilo associativo | corso di studi, anno di corso, sede, competenze/interessi (opzionali) | necessario anche per §5.6 | -| Relazioni | ruolo organizzativo (§3.3), team, responsabile | | -| Integrazioni | Telegram ID/username, Azure user ID, ultimo sync | collega senza duplicare | -| Consensi | consenso, fonte, data, revoca | minimo indispensabile per email automatiche (§5.7, §5.8) | +| Consensi | consenso privacy policy, fonte, data, versione firmata, revoca | firma diretta in dashboard, vedi §5.1.5 | -Vincoli: numero associativo univoco; storicizzazione degli stati (non sovrascrittura); nessuna cancellazione bulk senza anteprima e conferma; ogni lettura/scrittura sensibile passa per l'audit di §5.1.2. +Alcuni campi sono obbligatori e altri opzionali (**deciso in linea di principio**; l'elenco puntuale, incluso se serva il codice fiscale, resta da definire — §11). Lettura: HR può leggere l'Anagrafica Soci; il dettaglio dei permessi granulari campo per campo resta da definire con calma (§11). -#### 5.2.2 Flusso MVP +Vincoli: numero associativo univoco; storicizzazione degli stati (non sovrascrittura: i soci scaduti/ex soci restano nello storico, non vengono rimossi); nessuna cancellazione bulk senza anteprima e conferma; ogni lettura/scrittura sensibile passa per l'audit di §5.1.2. + +#### 5.2.2 Flusso MVP — Anagrafica Soci ``` -Richiesta → verifica dati → deduplica → approvazione → numero socio - → collegamento opzionale a Telegram/Azure → welcome → rinnovo → storico +Richiesta/iscrizione → verifica dati → deduplica → firma privacy policy (§5.1.5) → approvazione → numero socio + → collegamento opzionale a Telegram/Azure → rinnovo annuale della quota (§5.5) → storico ``` -#### 5.2.3 Permessi +#### 5.2.3 Censimento Admin/Team — campi e flusso MVP + +Rivolto a chi ha un ruolo organizzativo (Admin, Capo Admin, Direttivo, membro di team), indipendentemente dall'essere anche Socio (§3.2). + +| Blocco | Campi | Note | +|---|---|---| +| Identità | nome, cognome, email, telefono | | +| Relazioni | ruolo organizzativo (§3.3), team (§5.6), Capo Admin/responsabile di riferimento | | +| Integrazioni | Telegram ID/username, Azure user ID, ultimo sync | collega senza duplicare | +| Rinnovo interesse | data ultima conferma, prossima scadenza conferma, esito | sostituisce il concetto di "quota" per questa popolazione | +| Consensi | consenso privacy policy, fonte, data, versione firmata | vedi §5.1.5 | + +Flusso: rilevazione periodica (periodicità da definire, es. legata all'anno accademico — §11) → conferma interesse/disponibilità tramite il flusso automatizzato di Onboarding/Censimento in dashboard (§5.7) → aggiornamento stato → storico. + +#### 5.2.4 Permessi -- Creazione/modifica: ruoli con `members.write` (Direttivo/Owner/President inizialmente). -- Lettura: `members.read`, assegnabile anche a HR **in sola lettura** (coerente con il pattern già in uso per HR sul resto della dashboard). -- Un operatore deve poter creare un socio **senza** dover prima creare un account Azure: oggi non è possibile, perché il numero associativo esiste solo dentro Azure. +- Creazione/modifica (Anagrafica Soci e Censimento Admin/Team): ruoli con `members.write` (Direttivo/Owner/President inizialmente). +- Lettura: `members.read`, assegnabile anche a HR **in sola lettura** (coerente con il pattern già in uso per HR sul resto della dashboard); quali campi restino mascherati anche per HR va deciso con calma (§11). +- Un operatore deve poter creare un socio o un record del Censimento Admin/Team **senza** dover prima creare un account Azure: oggi non è possibile, perché il numero associativo esiste solo dentro Azure. --- -### 5.3 Governance e Direttivo (P1) +### 5.3 Governance e Direttivo — ⚪ Obsoleto -**Stato: parziale — il backend è pronto, manca la UI.** `tg.permissions.getDirettivo` restituisce già la composizione del Direttivo con `isPresident`. Un MVP a basso sforzo: +**Stato: dichiarato obsoleto dal Team IT.** Questa sezione (pagina "Direttivo" dedicata, in sola lettura, con eventuale storico incarichi) **non verrà realizzata come area a sé stante**. I dati utili che avrebbe dovuto mostrare — composizione del Direttivo, ruolo organizzativo, incarico — sono coperti dal Censimento Admin/Team (§5.2.3) e dalla gerarchia ruoli (§3.3), che restano la fonte di riferimento per queste informazioni. -- pagina "Direttivo" in sola lettura con i membri correnti; -- in una seconda iterazione: incarico, data inizio/fine, storico nomine (richiede nuovo storage, non presente nel contratto attuale). +`tg.permissions.getDirettivo` (composizione del Direttivo con `isPresident`) resta comunque una capacità di backend già pronta e riusabile come sorgente dati per il Censimento Admin/Team, non serve più però una pagina dedicata separata. --- @@ -262,19 +315,27 @@ Requisiti (adattati dal vecchio PRD, subordinati al Censimento): - Sezione link ai gruppi Telegram di competenza del Capo Admin. - Permessi: il Capo Admin deve vedere **solo** i dati e i gruppi del proprio ambito — richiede lo scoping descritto in §5.1.1, non disponibile con il modello attuale a ruoli globali. -**Precondizione bloccante**: senza il Censimento (corso di studi, data di ingresso, rappresentanza) e senza l'estensione dei permessi per dare accesso scoped a chi ha solo il ruolo `admin`, questa funzionalità non è costruibile nella forma descritta dal vecchio PRD. +**Deciso**: una persona admin appartiene a **un solo corso di studi** come dato anagrafico personale, ma può essere **admin/Capo Admin con scope su gruppi di corsi diversi** contemporaneamente (§11) — il "corso di appartenenza" personale e lo "scope di responsabilità" da admin sono due campi distinti, non lo stesso valore. Il modello dati deve quindi separare il corso personale del Censimento Admin/Team (§5.2.3) dallo/dagli scope assegnati come Capo Admin. + +**Precondizione bloccante**: senza il Censimento Admin/Team (corso di studi, data di ingresso, rappresentanza) e senza l'estensione dei permessi per dare accesso scoped a chi ha solo il ruolo `admin`, questa funzionalità non è costruibile nella forma descritta dal vecchio PRD. --- ### 5.5 Gestione Soci e Rinnovi (dal vecchio PRD §4, P1) -**Stato: mancante**, dipende interamente dal Censimento. +**Stato: mancante**, dipende interamente dall'Anagrafica Soci (§5.2). + +**Correzione rispetto alla bozza precedente**: il pagamento della quota resta un **bonifico bancario fuori dashboard** (non si integra un gateway di pagamento in questa fase, §10), ma il **flusso di verifica del pagamento diventa in-dashboard**: -- Rinnovo automatico via email poco prima della scadenza: richiede un motore di invio email nel backend condiviso (non presente in questo repository) e la data di scadenza del Censimento. -- Vista Direttivo sullo stato dei soci: da verificare, pagamento effettuato, pagamento non effettuato. -- Azioni: "Segna come pagato" (aggiorna stato + email di conferma), "Invia reminder" (nuova email di promemoria). -- Storico minimo delle azioni (chi ha segnato pagato, quando è stato inviato un reminder) — si appoggia all'audit unificato di §5.1.2. -- Il vecchio PRD dispensa esplicitamente dalla necessità di gestire il pagamento *dentro* la dashboard nella prima versione: manteniamo questa impostazione. +- Il socio può **caricare la ricevuta del bonifico in dashboard**; il caricamento avvia una richiesta di approvazione. +- Il Direttivo/ruolo autorizzato approva la ricevuta caricata, oppure segna il rinnovo come effettuato **manualmente** se la ricevuta non viene caricata (es. verifica diretta in banca). +- **Ricevuta automatizzata**: quando un rinnovo viene approvato, la dashboard genera e invia automaticamente la ricevuta al socio (nuovo requisito rispetto alla bozza precedente). +- Per i rinnovi **del Direttivo verso l'associazione stessa** (quota versata dai membri del Direttivo), la ricevuta viene generata/automatizzata allo stesso modo dalla dashboard; quando è richiesta una firma, il flusso notifica il **Presidente**, che deve firmarla. +- Rinnovo automatico via email poco prima della scadenza: richiede un motore di invio email nel backend condiviso (non presente in questo repository) e la data di scadenza dell'Anagrafica Soci. +- Vista Direttivo sullo stato dei soci: da verificare, ricevuta caricata in attesa di approvazione, pagamento effettuato, pagamento non effettuato. +- Azioni: "Approva ricevuta"/"Segna come pagato" (aggiorna stato + genera ricevuta + email di conferma), "Invia reminder" (nuova email di promemoria). +- Storico minimo delle azioni (chi ha approvato/segnato pagato, quando è stato inviato un reminder, ricevute generate) — si appoggia all'audit unificato di §5.1.2. +- Resta da decidere se il permesso di "segnare come pagato"/approvare ricevute sia riservato al solo Direttivo o esteso a un futuro ruolo Finance dedicato (§11). --- @@ -284,23 +345,31 @@ Requisiti (adattati dal vecchio PRD, subordinati al Censimento): Per questa fase, l'obiettivo minimo è **struttura, ruoli e separazione degli accessi**, non le funzionalità specifiche di ciascun team (che il vecchio PRD stesso rimanda a una definizione successiva con i responsabili): -- ogni team come entità del Censimento (§5.2, blocco "Relazioni"); +- ogni team come entità del Censimento Admin/Team (§5.2.3, blocco "Relazioni"); - pagina/area indipendente per team con permesso dedicato (si appoggia a §5.1.1); - nessuna funzionalità specifica di team implementata in questa fase. --- -### 5.7 Onboarding nuovi Admin (dal vecchio PRD §6, P2) +### 5.7 Onboarding e Censimento Admin — flusso self-service in dashboard (dal vecchio PRD §6, P2) -**Stato: mancante.** Il vecchio PRD stesso richiede di ridisegnare il processo con HR e Team IT prima di digitalizzarlo: questo PRD conferma che **non esiste alcuna base dati di candidature oggi**, quindi non c'è nulla da migrare, solo da progettare da zero una volta chiarito il flusso (vedi Decisioni aperte §11). +**Stato: mancante.** Il vecchio PRD stesso richiede di ridisegnare il processo con HR e Team IT prima di digitalizzarlo; il dettaglio del processo (candidatura, colloquio, criteri) **resta da definire bene** (§11). Questo PRD ne fissa però una direzione precisa, indicata esplicitamente dal Team IT: -Ambito minimo suggerito una volta definito il processo: candidatura → stato → colloquio → approvazione → creazione profilo (Censimento) → assegnazione corso/ruoli/team → passaggi di ingresso operativo. +**Cambio di canale**: sia il censimento di nuovi candidati admin, sia il censimento periodico di admin già attivi, non passano più per Telegram e scambio di messaggi manuale, ma per un **flusso automatizzato della dashboard**, attivabile tramite un link o una mail inviata alla persona. + +Requisiti minimi: +- **Autenticazione preventiva obbligatoria** sull'Identity Provider PoliNetwork (§5.1.6) prima di poter proseguire nel flusso — serve sia a identificare con certezza la persona sia a determinare il tipo di candidatura/censimento applicabile al suo caso. +- Una volta autenticato, l'utente accede a un'area personale dove può: firmare i documenti richiesti (privacy policy e altri, §5.1.5), consultare le proprie statistiche, vedere il proprio **Capo Admin di riferimento** (dato dal Censimento Admin/Team, §5.2.3). +- **Permessi differenziati per ruolo**: ogni membro di PoliNetwork ha un livello di accesso diverso in base a cosa fa/è nell'associazione, ma **tutti hanno accesso a qualcosa** nella propria area — nessun ruolo resta completamente escluso dal proprio spazio personale. +- **Richieste che risalgono la gerarchia**: ad esempio, un admin può presentare dalla propria area la richiesta di diventare admin di un determinato gruppo, e la richiesta arriva al proprio Capo Admin di riferimento per l'approvazione (pattern di richiesta/approvazione coerente con quello descritto per le associazioni partner, §6.1). + +Ambito minimo suggerito una volta definito il dettaglio del processo: link/mail di attivazione → autenticazione (Identity Provider) → candidatura o conferma censimento periodico → firma documenti → colloquio/approvazione (per i nuovi) → creazione/aggiornamento profilo (Censimento Admin/Team, §5.2.3) → assegnazione corso/ruoli/team → passaggi di ingresso operativo. --- ### 5.8 Email di compleanno (dal vecchio PRD §5, P2) -**Stato: mancante.** Dipende dal Censimento (nessuna entità ha oggi una data di nascita) e da un motore email nel backend condiviso. Riguarda solo i soci e solo l'email, come indicato nel vecchio PRD. +**Stato: mancante.** Dipende dall'Anagrafica Soci (nessuna entità ha oggi una data di nascita) e da un motore email nel backend condiviso. Riguarda solo i soci e solo l'email, come indicato nel vecchio PRD. --- @@ -325,19 +394,19 @@ Per il criterio dichiarato in §0 e §2.1, queste aree sono **declassate in prio ### 6.1 Area Associazioni Partner (dal vecchio PRD §1 — lì priorità massima) -**Stato: mancante interamente.** Riguarda un pubblico esterno (le associazioni partner) e presuppone un **modello di autenticazione multi-tenant** che oggi non esiste: l'unico meccanismo di accesso attuale presume un singolo tipo di utente (un collaboratore interno con ruolo Telegram). Includerebbe, secondo il vecchio PRD: +**Stato: mancante interamente.** Riguarda un pubblico esterno (le associazioni partner) e presuppone un **modello di autenticazione multi-tenant** che oggi non esiste: l'unico meccanismo di accesso attuale presume un singolo tipo di utente (un collaboratore interno con ruolo Telegram). Il dettaglio di business di quest'area è già definito nei documenti dell'associazione; qui si registra solo quanto rilevante per la dashboard, includendo, secondo il vecchio PRD e le precisazioni del Team IT: -- accesso e gestione account per decine di associazioni (creazione/disattivazione, recupero credenziali, referenti multipli); -- richieste di pubblicazione nei gruppi WhatsApp/Telegram (**WhatsApp non è integrato in nessuna parte del sistema attuale**); -- gestione della pagina pubblica dell'associazione con flusso di richiesta/approvazione (oggi `Web Associations` è già CRUD **diretto** da parte di PoliNetwork, non un flusso di richiesta da parte dell'associazione — sarebbe un cambio di modello, non un'estensione); -- eventuale sistema a crediti (logica non definita nel vecchio PRD stesso); +- accesso e gestione account per decine di associazioni. **Deciso**: si può creare l'account a **uno o più referenti** della stessa associazione fin dal MVP, e i referenti possono **nominare un successore trasferendo l'ownership** del proprio account (es. passaggio di consegne interno all'associazione partner); +- richieste di pubblicazione nei gruppi Telegram: **deciso**, le associazioni presentano la richiesta dalla propria pagina/area e PoliNetwork approva. Le richieste possono riguardare **più gruppi contemporaneamente**; la dashboard mostra già l'elenco completo dei gruppi tra cui scegliere, quindi non serve un nuovo modulo di selezione gruppi. Resta da chiarire se serva anche l'integrazione WhatsApp menzionata nel vecchio PRD (§11), oggi non integrata in nessuna parte del sistema; +- gestione della pagina pubblica dell'associazione con flusso di richiesta/approvazione: **deciso**, sostituisce l'attuale CRUD diretto di PoliNetwork su `Web Associations` — è un cambio di modello, non una semplice estensione; +- eventuale sistema a crediti: logica ancora non definita, resta aperta (§11); - eventi delle associazioni / "PoliTamTam" (§6.2). -Questo PRD non ne nega il valore di business, ma lo colloca dopo le fondamenta interne (§5), perché richiede decisioni architetturali (autenticazione multi-tenant, eventuale integrazione WhatsApp) che è più sicuro prendere dopo aver stabilizzato RBAC, audit e Censimento. +Questo PRD non ne nega il valore di business, ma lo colloca dopo le fondamenta interne (§5), perché richiede l'Identity Provider PoliNetwork (§5.1.6) per l'accesso esterno multi-tenant, che è più sicuro introdurre dopo aver stabilizzato RBAC, audit e Anagrafica Soci/Censimento. ### 6.2 Eventi delle associazioni — PoliTamTam (dal vecchio PRD §1.4) -**Stato: mancante.** Dipende dalla decisione su §6.1: se le associazioni partner inseriscono direttamente gli eventi, serve prima l'accesso esterno; se invece PoliNetwork inserisce gli eventi per conto delle associazioni (variante più semplice e coerente con il modello attuale, dove solo PoliNetwork scrive contenuti pubblici), può essere realizzato prima, come estensione del modulo `Web` esistente, sullo stesso pattern di `Web Projects`/`Web Associations`. +**Stato: mancante.** **Deciso**: gli eventi vengono inseriti dalle associazioni partner **dalla propria pagina/area** (dipende quindi dall'accesso esterno di §6.1); PoliNetwork può inoltre aggiungere propri eventi, o eventualmente eventi per conto di altre associazioni. In nessun caso la pubblicazione è diretta: **ogni evento richiede approvazione** prima di comparire pubblicamente, sullo stesso pattern di richiesta/approvazione di §6.1. ### 6.3 Area Aziende (dal vecchio PRD §7) @@ -349,7 +418,7 @@ Questo PRD non ne nega il valore di business, ma lo colloca dopo le fondamenta i ### 6.5 Newsletter (dal vecchio PRD §10) -**Stato: mancante.** Il vecchio PRD la marca già come non bloccante. Dipende da Censimento (segmentazione destinatari) ed eventualmente da §6.2 (eventi come fonte di contenuti). +**Stato: mancante.** Il vecchio PRD la marca già come non bloccante. Dipende dall'Anagrafica Soci (segmentazione destinatari) ed eventualmente da §6.2 (eventi come fonte di contenuti). --- @@ -360,7 +429,7 @@ Questo PRD non ne nega il valore di business, ma lo colloca dopo le fondamenta i - **Minimizzazione dati**: ogni campo del Censimento deve avere uno scopo dichiarato; dati sensibili (es. codice fiscale) solo se realmente necessari per il tesseramento. - **Audit prima di esporre dati personali** a più ruoli (§5.1.2 è precondizione di §5.2, §5.4, §5.5). - **Query lato server e paginazione reale**: oggi tutte le liste caricano `getAll` e filtrano nel browser (`users-page.tsx`, `members-page.tsx`, ecc.). Accettabile ai volumi attuali; da rivedere non appena il Censimento supera qualche centinaio di record. -- **Lingua**: i contenuti pubblici (associazioni, progetti, FAQ) sono già bilingue IT/EN nel backend; l'interfaccia amministrativa è oggi interamente in inglese. Va deciso un indirizzo esplicito (Decisione aperta §11) prima di aggiungere nuove pagine con testo lungo (es. Censimento, Rinnovi). +- **Lingua**: i contenuti pubblici (associazioni, progetti, FAQ) sono già bilingue IT/EN nel backend; l'interfaccia amministrativa è oggi interamente in inglese. **Deciso**: l'interfaccia amministrativa diventerà **bilingue IT/EN con preferenza impostabile per singolo utente** (§11) — le nuove pagine con testo lungo (Anagrafica Soci, Censimento Admin/Team, Rinnovi) vanno progettate da subito con questo vincolo. --- @@ -368,33 +437,36 @@ Questo PRD non ne nega il valore di business, ma lo colloca dopo le fondamenta i | Fase | Contenuto | Obiettivo | |---|---|---| -| **0 — Fondamenta** | RBAC per capacità (§5.1.1), audit unificato (§5.1.2), ricerca globale (§5.1.4) | Base sicura e osservabile per esporre dati personali in fase 1 | -| **1 — Censimento e governance** | Censimento Soci MVP (§5.2), pagina Direttivo read-only (§5.3), FAQ (§5.9) | Registro soci utilizzabile, primo valore rapido a basso sforzo | -| **2 — Gerarchia e rinnovi** | Dashboard Admin/Capo Admin (§5.4), Gestione Soci e Rinnovi (§5.5), home come command center (§5.1.3) | Gestione del ciclo di vita di admin e soci | -| **3 — Team e onboarding** | Aree Team (§5.6), Onboarding nuovi Admin (§5.7, dopo riprogettazione con HR), email di compleanno (§5.8) | Copertura dei processi interni residui | +| **0 — Fondamenta** | RBAC per capacità (§5.1.1), audit unificato (§5.1.2), ricerca globale (§5.1.4), Identity Provider PoliNetwork (§5.1.6), consensi/firma privacy in dashboard (§5.1.5) | Base sicura, osservabile e autenticata per esporre dati personali e far firmare documenti in fase 1 | +| **1 — Anagrafica e censimento** | Anagrafica Soci MVP (§5.2.1-2), Censimento Admin/Team MVP (§5.2.3), FAQ (§5.9) — nota: la governance/Direttivo dedicata (§5.3) è **obsoleta** e non rientra più in questa fase | Registro soci e censimento admin/team utilizzabili, primo valore rapido a basso sforzo | +| **2 — Gerarchia e rinnovi** | Dashboard Admin/Capo Admin (§5.4), Gestione Soci e Rinnovi con ricevute in dashboard (§5.5), home come command center (§5.1.3) | Gestione del ciclo di vita di admin e soci | +| **3 — Team e onboarding** | Aree Team (§5.6), Onboarding e Censimento Admin self-service (§5.7, dopo riprogettazione con HR), email di compleanno (§5.8) | Copertura dei processi interni residui | | **4 — Aree esistenti** | Miglioramenti Telegram/Azure (§5.10) | Colmare i gap sulle integrazioni già in produzione | -| **5 — Aree esterne** | Associazioni Partner (§6.1), PoliTamTam (§6.2) | Prima area rivolta a soggetti esterni, dopo le fondamenta interne | +| **5 — Aree esterne** | Associazioni Partner multi-referente (§6.1), PoliTamTam (§6.2) | Prima area rivolta a soggetti esterni, dopo le fondamenta interne e l'Identity Provider | | **6 — Espansione** | Aziende, Casa, Newsletter (§6.3-6.5) | Funzionalità secondarie, a valutazione | --- -## 9. Criteri di accettazione (MVP Censimento, come esempio di riferimento) +## 9. Criteri di accettazione (MVP Anagrafica Soci e Censimento Admin/Team, come esempio di riferimento) Ripresi e confermati perché indipendenti da qualunque decisione aperta: - Un operatore può creare un socio senza dover prima creare un account Azure. -- La scheda del socio mostra chiaramente identità locale, Telegram e Azure e segnala i collegamenti mancanti. +- La scheda del socio/admin mostra chiaramente identità locale, Telegram e Azure e segnala i collegamenti mancanti. - Nessuna scrittura in un'importazione massiva prima della conferma di un'anteprima. - Un ruolo HR read-only può consultare solo ciò che il suo permesso consente e non vede pulsanti di scrittura. - Ogni cambio di stato, numero associativo o identità esterna è rintracciabile nell'audit. - Nessuna cancellazione massiva senza conferma esplicita e riepilogo delle righe coinvolte. +- Un socio può caricare la ricevuta di un bonifico in dashboard e vederne lo stato di approvazione; se non la carica, il rinnovo può comunque essere segnato manualmente da chi ha il permesso. +- Un consenso privacy firmato in dashboard resta associato alla versione del testo firmata al momento della firma, anche se il testo cambia in seguito. +- Nessun flusso di censimento/onboarding self-service procede senza autenticazione riuscita sull'Identity Provider PoliNetwork. --- ## 10. Cosa NON fa parte di questo PRD - Non ridefinisce lo statuto, gli organi sociali o le regole di voto dell'associazione: assume che la struttura Owner/Presidente/Direttivo esistente sui ruoli Telegram sia quella corretta finché non diversamente indicato. -- Non decide se e come integrare pagamenti (Stripe, bonifico, altro): il vecchio PRD stesso rimanda il pagamento fuori dalla dashboard nella prima versione, e questo documento mantiene la stessa impostazione. +- Non decide se e come integrare un gateway di pagamento (Stripe, altro): il pagamento resta un bonifico bancario **eseguito fuori dashboard**. È invece in scope la **verifica** del pagamento in dashboard (upload ricevuta, approvazione, ricevuta automatizzata — §5.5): non è più un rinvio integrale come nella bozza precedente, ma resta comunque escluso qualunque flusso di incasso/gateway dentro l'applicazione. - Non propone una contabilità completa (fatture, bilanci): per pagamenti e documenti sensibili resta preferibile integrare servizi specializzati. --- @@ -404,36 +476,41 @@ Ripresi e confermati perché indipendenti da qualunque decisione aperta: Raggruppate per paragrafo di riferimento. Nessuna ipotesi organizzativa è stata inventata: dove il vecchio PRD o il codice non permettevano di dedurre una risposta, la domanda è riportata qui invece di essere decisa autonomamente. **§3 — Ruoli e gerarchie** -1. Il ruolo "Capo Admin" va modellato come nuovo ruolo Telegram/backend, o come attributo applicativo (scope) sopra il ruolo `admin` esistente, gestito solo lato dashboard? -2. Chi assegna e revoca il ruolo di Capo Admin, e con quale periodicità (es. legato all'anno accademico)? -3. Il ruolo `admin` "semplice" deve ottenere accesso alla dashboard (anche solo in lettura sul proprio ambito), oppure resta escluso come oggi? +1. Il ruolo "Capo Admin" va modellato come nuovo ruolo Telegram/backend, o come attributo applicativo (scope) sopra il ruolo `admin` esistente, gestito solo lato dashboard? — **Ancora da decidere**, risposta esplicita del Team IT: "non lo so, da decidere". +2. Chi assegna e revoca il ruolo di Capo Admin, e con quale periodicità (es. legato all'anno accademico)? — **Deciso in parte**: il **Direttivo** assegna e revoca il ruolo. La periodicità resta da definire. +3. Il ruolo `admin` "semplice" deve ottenere accesso alla dashboard (anche solo in lettura sul proprio ambito), oppure resta escluso come oggi? — **Deciso**: sì, l'admin ottiene accesso con **permessi determinati** dal proprio scope (vedi §3.3, §5.1.1). -**§5.2 — Censimento Soci** -4. Il numero associativo resta una proprietà di Azure, o diventa proprietà del nuovo registro soci (con Azure che lo referenzia)? -5. L'iscrizione è annuale, semestrale o senza scadenza? -6. Quali dati sono realmente necessari per il tesseramento (es. il codice fiscale è richiesto dal processo associativo reale, o va escluso)? -7. Un ruolo HR read-only può leggere tutti i campi del socio, o alcuni campi (es. dati di contatto personali) devono essere mascherati anche per HR? +**§5.2 — Anagrafica Soci e Censimento Admin/Team** +4. Il numero associativo resta una proprietà di Azure, o diventa proprietà del nuovo registro soci (con Azure che lo referenzia)? — **Deciso**: i dati diventano proprietà del **nostro database** (Anagrafica Soci); Azure lo referenzia se presente. +5. L'iscrizione è annuale, semestrale o senza scadenza? — **Deciso**: **annuale**. +6. Quali dati sono realmente necessari per il tesseramento (es. il codice fiscale è richiesto dal processo associativo reale, o va escluso)? — **Deciso in parte**: alcuni dati saranno obbligatori, altri opzionali. L'elenco puntuale campo per campo (incluso se serva il codice fiscale) resta da definire. +7. Un ruolo HR read-only può leggere tutti i campi del socio, o alcuni campi (es. dati di contatto personali) devono essere mascherati anche per HR? — **Deciso in parte**: HR può leggere l'Anagrafica Soci; i permessi granulari campo per campo vanno pensati con calma, restano da definire nel dettaglio. **§5.4 — Dashboard Admin e Capo Admin** -8. Come si definisce "corso di studi" nel sistema (elenco chiuso dei corsi del Politecnico, testo libero, altro)? -9. Un admin può appartenere a più corsi/ambiti, o a uno solo? +8. Come si definisce "corso di studi" nel sistema (elenco chiuso dei corsi del Politecnico, testo libero, altro)? — **Ancora aperta**, non affrontata. +9. Un admin può appartenere a più corsi/ambiti, o a uno solo? — **Deciso**: una persona admin appartiene a **un solo corso** come dato personale, ma può **essere admin/Capo Admin su gruppi di corsi diversi** come scope di responsabilità (i due concetti sono distinti, vedi §5.4). **§5.5 — Gestione Soci e Rinnovi** -10. Il pagamento della quota resta interamente manuale (bonifico/altro) fuori dashboard, o si prevede in futuro un'integrazione (es. Stripe)? -11. Chi ha il permesso di "segnare come pagato": solo Direttivo, o anche un ruolo Finance dedicato non ancora esistente? +10. Il pagamento della quota resta interamente manuale (bonifico/altro) fuori dashboard, o si prevede in futuro un'integrazione (es. Stripe)? — **Deciso**: il pagamento resta **bonifico**, eseguito fuori dashboard. In dashboard il socio può però **caricare la ricevuta** per farla approvare, oppure il rinnovo viene segnato **manualmente** se la ricevuta non è caricata. Per i rinnovi del Direttivo verso l'associazione, la ricevuta viene generata/automatizzata dalla dashboard, con firma del Presidente quando richiesta. +11. Chi ha il permesso di "segnare come pagato": solo Direttivo, o anche un ruolo Finance dedicato non ancora esistente? — **Ancora aperta**: il Direttivo approva le ricevute caricate, ma se questo compito debba restare esclusivo del Direttivo o essere esteso a un futuro ruolo Finance non è stato specificato. + +**§5.7 — Onboarding e Censimento Admin** +12. Il processo di candidatura/colloquio è già stato ridisegnato con HR e Team IT (come richiesto dal vecchio PRD stesso), o va progettato da zero in questo ciclo? — **Ancora da definire bene** (risposta esplicita del Team IT), ma la direzione del canale è ormai fissata: flusso automatizzato in dashboard con autenticazione preventiva, non più Telegram (§5.7). Restano da definire i dettagli operativi del processo (criteri, colloquio, tempistiche). -**§5.7 — Onboarding nuovi Admin** -12. Il processo di candidatura/colloquio è già stato ridisegnato con HR e Team IT (come richiesto dal vecchio PRD stesso), o va progettato da zero in questo ciclo? +**§5.1 — Identity Provider PoliNetwork** *(nuovo gruppo)* +20. Il nuovo Identity Provider PoliNetwork (§5.1.6) sostituisce integralmente l'attuale autenticazione Better Auth, o si affianca ad essa come livello applicativo sopra le identità Telegram/Azure/Better Auth esistenti? +21. Il consenso privacy raccolto in dashboard (§5.1.5) sostituisce integralmente i form esterni oggi in uso, o convive con essi durante una fase di transizione? +22. Con quale periodicità si svolge il Censimento Admin/Team (§5.2.3) — es. una volta per anno accademico, o legato a un altro evento? **§6.1 — Area Associazioni Partner** -13. Un account per associazione, o più referenti per la stessa associazione fin dal MVP? -14. Le richieste di pubblicazione riguardano solo Telegram (unico canale oggi integrato) o resta necessaria l'integrazione WhatsApp menzionata nel vecchio PRD? -15. Il sistema a crediti per le pubblicazioni resta previsto, e con quale logica di ricarica/consumo? -16. La gestione della pagina pubblica dell'associazione deve diventare un flusso di richiesta/approvazione (come indicato dal vecchio PRD), sostituendo l'attuale CRUD diretto di PoliNetwork su `Web Associations`? +13. Un account per associazione, o più referenti per la stessa associazione fin dal MVP? — **Deciso**: si possono creare **uno o più account/referenti** per associazione fin dal MVP, con possibilità di **nominare un successore e trasferire l'ownership** dell'account. +14. Le richieste di pubblicazione riguardano solo Telegram (unico canale oggi integrato) o resta necessaria l'integrazione WhatsApp menzionata nel vecchio PRD? — **Ancora aperta**: da verificare nei documenti di business esterni citati dal Team IT. +15. Il sistema a crediti per le pubblicazioni resta previsto, e con quale logica di ricarica/consumo? — **Ancora aperta**, logica non definita. +16. La gestione della pagina pubblica dell'associazione deve diventare un flusso di richiesta/approvazione (come indicato dal vecchio PRD), sostituendo l'attuale CRUD diretto di PoliNetwork su `Web Associations`? — **Deciso**: sì. Le associazioni richiedono dalla propria pagina/area, PoliNetwork approva; le richieste possono riguardare più gruppi contemporaneamente e la dashboard mostra già l'elenco completo dei gruppi disponibili. **§6.2 — Eventi / PoliTamTam** -17. Gli eventi sono inseriti direttamente dalle associazioni partner (richiede §6.1) o da PoliNetwork per conto loro (realizzabile prima, sul modello di `Web Projects`)? -18. Gli eventi vengono pubblicati immediatamente o richiedono approvazione PoliNetwork? +17. Gli eventi sono inseriti direttamente dalle associazioni partner (richiede §6.1) o da PoliNetwork per conto loro (realizzabile prima, sul modello di `Web Projects`)? — **Deciso**: le associazioni inseriscono gli eventi dalla propria pagina; PoliNetwork può aggiungere anche eventi propri o, eventualmente, per conto di altre associazioni. +18. Gli eventi vengono pubblicati immediatamente o richiedono approvazione PoliNetwork? — **Deciso**: richiedono sempre approvazione; nessuna pubblicazione avviene direttamente. **§7 — Lingua dell'interfaccia** -19. L'interfaccia amministrativa deve diventare bilingue con preferenza per utente, o restare in italiano per il team associativo mantenendo IT/EN solo sui contenuti pubblici? +19. L'interfaccia amministrativa deve diventare bilingue con preferenza per utente, o restare in italiano per il team associativo mantenendo IT/EN solo sui contenuti pubblici? — **Deciso**: bilingue, **con preferenza impostabile per singolo utente**. From 143f3e88526dbacbef3f23c7704f21a938d9578e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gabriele=20Vigan=C3=B2?= Date: Sat, 29 Aug 2026 02:19:49 +0200 Subject: [PATCH 5/6] docs: remove superseded PRD and roadmap report PRD_Admin_Dashboard_PoliNetwork.md is now the single source of truth; drop the old associazione PRD and the standalone roadmap report it replaced. Co-Authored-By: Claude Sonnet 5 --- PRD_Admin_Dashboard_Associazione.md | 248 ------------- PRD_Admin_Dashboard_PoliNetwork.md | 2 +- REPORT_FEATURE_E_ROADMAP.md | 530 ---------------------------- 3 files changed, 1 insertion(+), 779 deletions(-) delete mode 100644 PRD_Admin_Dashboard_Associazione.md delete mode 100644 REPORT_FEATURE_E_ROADMAP.md diff --git a/PRD_Admin_Dashboard_Associazione.md b/PRD_Admin_Dashboard_Associazione.md deleted file mode 100644 index 0bf1ca0..0000000 --- a/PRD_Admin_Dashboard_Associazione.md +++ /dev/null @@ -1,248 +0,0 @@ -# Admin Dashboard Associazione - -**Documento di specifica funzionale per il Team IT** -**Versione:** 0.2 -**Data:** 20 agosto 2026 -**Stato:** Bozza per revisione - -## Scopo del documento - -Questo documento raccoglie le funzionalità attualmente previste per l'Admin Dashboard dell'associazione, distinguendo tra funzionalità prioritarie e funzionalità secondarie. - -L'obiettivo generale è concentrare nella dashboard il maggior numero possibile di processi oggi distribuiti tra form, fogli Excel, email e operazioni manuali, mantenendo però ogni area sufficientemente modulare da poter essere sviluppata e ampliata nel tempo. - -# Feature prioritarie - -## 1. Area Associazioni Partner - -L'area dedicata alle associazioni partner è una delle funzionalità prioritarie della piattaforma. - -Ogni associazione partner deve avere un proprio accesso alla dashboard e poter gestire da un'unica area le interazioni principali con PoliNetwork. - -### 1.1 Accesso e gestione degli account - -La soluzione deve essere pensata per gestire in modo ordinato e scalabile decine di associazioni diverse. - -Come soluzione di riferimento, PoliNetwork può creare e gestire direttamente un indirizzo email dedicato `@polinetwork.org` per ciascuna associazione partner, da utilizzare come identità per l'accesso alla dashboard. - -Resta da definire con il Team IT il modello tecnico definitivo di autenticazione e gestione degli account, tenendo conto almeno di: - -- creazione e disattivazione degli account; -- recupero delle credenziali; -- eventuale cambio dei referenti dell'associazione; -- possibilità futura di avere più referenti per la stessa associazione; -- gestione centralizzata degli accessi da parte di PoliNetwork. - -### 1.2 Richieste di pubblicazione nei gruppi - -Le associazioni partner devono poter inviare richieste di pubblicazione di messaggi nei gruppi WhatsApp e/o Telegram gestiti da PoliNetwork. - -Per ogni richiesta devono essere disponibili almeno: - -- contenuto del messaggio; -- gruppo o insieme di gruppi destinatari; -- eventuali allegati o link; -- data della richiesta; -- stato della richiesta; -- storico delle richieste precedenti. - -Se viene mantenuto un sistema a crediti, l'associazione deve inoltre poter visualizzare: - -- crediti disponibili; -- crediti utilizzati; -- data dell'eventuale rinnovo o ricarica. - -La logica precisa dei crediti resta da definire. - -### 1.3 Gestione della pagina pubblica dell'associazione - -Ogni associazione deve avere una propria pagina pubblica sul sito PoliNetwork. - -Dalla dashboard l'associazione deve poter richiedere modifiche ai dati mostrati pubblicamente, tra cui: - -- nome e informazioni principali; -- descrizione; -- logo; -- sito web; -- link Instagram; -- link LinkedIn; -- altri link social; -- eventuali contatti o altre informazioni pubbliche previste dalla pagina. - -Le modifiche non devono necessariamente essere pubblicate direttamente: la dashboard deve supportare un flusso di richiesta e approvazione da parte di PoliNetwork, così da mantenere il controllo sui contenuti presenti sul sito. - -### 1.4 Eventi delle associazioni — nuovo PoliTamTam - -La gestione degli eventi delle associazioni è una feature prioritaria. - -Le associazioni partner devono poter inserire direttamente dalla dashboard gli eventi da mostrare nella pagina dedicata agli eventi delle associazioni sul sito PoliNetwork. - -Questa sezione rappresenta l'evoluzione del vecchio concetto di **PoliTamTam**: un punto unico in cui raccogliere e mostrare in modo ordinato gli eventi delle associazioni. - -Per ogni evento devono essere previsti almeno: - -- titolo; -- associazione organizzatrice; -- descrizione; -- data e orario; -- luogo oppure link online; -- link di iscrizione, se presente; -- immagine o locandina, se prevista; -- stato dell'evento; -- eventuale data di scadenza o rimozione automatica dalla pagina. - -Il flusso di pubblicazione deve essere definito con il Team IT. In particolare, va deciso se gli eventi vengano pubblicati immediatamente oppure sottoposti prima ad approvazione da parte di PoliNetwork. - -## 2. Aree Team - -Ogni team interno deve avere una propria area dedicata all'interno della dashboard. - -Le aree previste sono: - -- **Team IT**; -- **Team Design & Social**; -- **Team International**; -- **Team HR**; -- **Team Events & Partnerships**. - -La struttura deve essere modulare: ogni team deve avere uno spazio indipendente, con permessi dedicati e la possibilità di aggiungere in seguito strumenti specifici senza dover riprogettare l'intera dashboard. - -Le funzionalità specifiche di ciascun team verranno definite separatamente insieme ai rispettivi responsabili. In questa fase è sufficiente prevedere correttamente struttura, ruoli, accessi e separazione delle aree. - -## 3. Dashboard Admin e Capo Admin - -La dashboard deve permettere ai responsabili degli admin di visualizzare e gestire le informazioni relative agli admin di propria competenza. - -### 3.1 Vista Capo Admin - -Un Capo Admin deve poter visualizzare gli admin del proprio corso di studi e filtrare rapidamente le informazioni disponibili. - -Per ogni admin devono essere disponibili almeno: - -- nome; -- cognome; -- anno di corso; -- data di ingresso in PoliNetwork; -- indicazione se è rappresentante o meno; -- altre associazioni di cui fa parte; -- numero di telefono; -- username o contatto Telegram; -- collegamento rapido per contattarlo tramite WhatsApp o Telegram. - -### 3.2 Filtri e ricerca - -Devono essere disponibili almeno: - -- ricerca per nome e cognome; -- filtro per anno; -- filtro per rappresentanza; -- filtro per appartenenza ad altre associazioni. - -### 3.3 Link dei gruppi - -Il Capo Admin deve avere una sezione dedicata contenente i link ai gruppi WhatsApp e Telegram di propria competenza. - -La gestione dei permessi deve garantire che ciascun Capo Admin possa vedere esclusivamente i dati e i gruppi relativi al proprio ambito. - -## 4. Gestione Soci e Rinnovi - -La dashboard deve centralizzare anche la gestione dello stato associativo dei soci. - -### 4.1 Rinnovo automatico via email - -Poco prima della scadenza dell'iscrizione, il socio deve ricevere automaticamente una mail che gli ricorda di rinnovare. - -La mail deve contenere le informazioni necessarie per completare il rinnovo secondo il processo associativo definito. - -Non è quindi necessario che il pagamento venga effettuato direttamente dalla dashboard nella prima versione. - -### 4.2 Vista Direttivo sullo stato dei soci - -Il Direttivo deve poter visualizzare lo stato del rinnovo di ciascun socio e distinguere chiaramente almeno tra: - -- rinnovo da verificare; -- pagamento effettuato; -- pagamento non ancora effettuato. - -Per ogni socio il Direttivo deve poter eseguire almeno due azioni: - -**Segna come pagato** -Aggiorna lo stato del socio e invia automaticamente una mail di conferma al socio interessato. - -**Invia reminder** -Invia una nuova mail di promemoria al socio che non ha ancora completato il rinnovo. - -La dashboard deve mantenere uno storico minimo delle azioni effettuate, in modo da sapere quando è stato inviato un reminder e quando un rinnovo è stato confermato. - -### 4.3 Informazioni utili sul socio - -Dove utile, la dashboard può inoltre mostrare: - -- data di ingresso in PoliNetwork; -- anzianità nell'associazione; -- ruoli ricoperti; -- team di appartenenza; -- eventuale corso di studi; -- stato associativo corrente. - -## 5. Email automatiche di compleanno - -Nel giorno del compleanno, i soci devono ricevere automaticamente una mail di auguri da parte di PoliNetwork. - -La funzionalità riguarda esclusivamente i soci e utilizza esclusivamente l'email: non è prevista, in questa fase, l'integrazione con Telegram per gli auguri. - -Il provider e il sistema tecnico utilizzato per l'invio automatico delle email devono essere definiti con il Team IT. - -## 6. Onboarding nuovi Admin - -Il processo attuale di onboarding degli admin è troppo frammentato e comprende passaggi distribuiti tra form, email, colloqui, fogli Excel e operazioni manuali. - -L'obiettivo della nuova dashboard è portare **il maggior numero possibile di passaggi direttamente all'interno della piattaforma**, riducendo gli strumenti esterni e usando la dashboard come punto centrale del processo. - -Il flusso definitivo deve ancora essere progettato nel dettaglio. - -Come principio generale, la soluzione futura dovrebbe cercare di centralizzare almeno: - -- gestione delle candidature; -- stato della candidatura; -- gestione del colloquio; -- raccolta dei dati necessari; -- approvazione del nuovo admin; -- creazione/attivazione del profilo; -- assegnazione del corso, dei ruoli e delle competenze; -- passaggi successivi necessari all'ingresso operativo dell'admin. - -Prima di implementare questa parte è necessario ridisegnare il processo insieme a HR e Team IT, evitando di digitalizzare alla lettera un flusso attuale che è già inutilmente complesso. - -# Feature secondarie - -Le seguenti funzionalità sono considerate utili, ma non prioritarie rispetto alle aree descritte sopra. - -## 7. Area Aziende - -Possibili funzionalità: - -- pubblicazione di annunci di lavoro e stage; -- eventuale consultazione dei CV dei membri, esclusivamente con un sistema di consenso e gestione privacy adeguato. - -La funzionalità deve essere progettata in dettaglio prima dello sviluppo. - -## 8. Area Proprietari di casa - -Possibile area dedicata ai proprietari per la pubblicazione di annunci immobiliari relativi ad affitto o vendita di camere e appartamenti. - -## 9. Bacheca ricerca casa e coinquilini - -Possibile area dedicata agli utenti che vogliono pubblicare annunci per: - -- ricerca di una stanza o appartamento; -- ricerca di coinquilini; -- altre esigenze collegate alla bacheca casa. - -## 10. Newsletter - -La newsletter è una feature secondaria e non deve bloccare lo sviluppo della prima versione della dashboard. - -In futuro potrà utilizzare i dati già presenti nella piattaforma, in particolare gli eventi inseriti dalle associazioni partner, per semplificare la selezione e la pubblicazione dei contenuti. - -Il modello editoriale, il sistema di approvazione e il provider di invio verranno definiti in una fase successiva. diff --git a/PRD_Admin_Dashboard_PoliNetwork.md b/PRD_Admin_Dashboard_PoliNetwork.md index f696f43..297f3ee 100644 --- a/PRD_Admin_Dashboard_PoliNetwork.md +++ b/PRD_Admin_Dashboard_PoliNetwork.md @@ -8,7 +8,7 @@ ## 0. Scopo e metodo di questo documento -Questo documento è un **nuovo PRD**, distinto da [`PRD_Admin_Dashboard_Associazione.md`](PRD_Admin_Dashboard_Associazione.md) (v0.2, non modificato). Il vecchio documento resta un riferimento sui bisogni di business espressi dall'associazione, ma **non è usato come fonte di verità tecnica**: ogni funzionalità qui descritta è stata verificata direttamente su: +Questo documento è un **nuovo PRD**, che sostituisce il precedente `PRD_Admin_Dashboard_Associazione.md` (v0.2, rimosso da questa repository perché superato). Il vecchio documento restava un riferimento sui bisogni di business espressi dall'associazione, ma **non era usato come fonte di verità tecnica**: ogni funzionalità qui descritta è stata verificata direttamente su: - il codice del frontend/BFF in `src/` (route, feature, server functions, middleware di autorizzazione); - il contratto tipizzato del backend reale, `node_modules/@polinetwork/backend/dist/index.d.ts` (unica sorgente di verità su cosa il backend espone oggi via tRPC: router `tg`, `azure`, `web`, `auth`, `test`); diff --git a/REPORT_FEATURE_E_ROADMAP.md b/REPORT_FEATURE_E_ROADMAP.md deleted file mode 100644 index 3e65b81..0000000 --- a/REPORT_FEATURE_E_ROADMAP.md +++ /dev/null @@ -1,530 +0,0 @@ -# PoliNetwork Admin — report feature e roadmap - -Data analisi: 19 agosto 2026 -Repository analizzato: `admin`, branch `main` - -## Sintesi esecutiva - -Il progetto è una buona base per una console operativa: autenticazione con passkey, collegamento Telegram, ruoli, server functions protette, dashboard React/TanStack Start, gestione Telegram, Microsoft 365 e contenuti web. Oggi però è soprattutto un pannello tecnico diviso per integrazione; non è ancora il sistema centrale per gestire l’associazione. - -Il vuoto più importante è il censimento. `Azure members` oggi rappresenta utenti Entra/Microsoft 365 con un numero associativo, mentre `Telegram users` rappresenta profili Telegram: manca un’anagrafica associativa canonica che colleghi persona, iscrizione, rinnovo, consensi, ruoli, team, attività e identità esterne. Anche la home è un indice di link statici, non un centro di controllo: non mostra KPI, scadenze, anomalie, attività recenti o cose da fare. - -La direzione consigliata è: - -1. stabilizzare la base tecnica e separare lettura/scrittura; -2. costruire il censimento come dominio principale; -3. trasformare la home in una command center con alert e workflow; -4. collegare Telegram, Azure e sito alla scheda unica del socio; -5. aggiungere governance, comunicazioni, contenuti e operatività interna. - -## Stato attuale verificato - -### Stack e fondamenta - -- React 19, TanStack Start/Router, Vite, Nitro, Tailwind CSS v4 e shadcn/ui (`README.md`). -- Backend tipizzato tramite tRPC e `@polinetwork/backend` (`src/lib/api/types.ts`). -- Server functions con middleware di sessione e autorizzazione (`src/server/auth.middleware.ts:51-66`). -- Autenticazione con Better Auth, passkey, sessioni attive e link Telegram (`src/features/account`, `src/features/onboarding`). -- Validazione Zod, toast, conferme sulle azioni distruttive, optimistic update in alcune pagine e test di sicurezza (`tests/server-security.test.mjs`). - -### Moduli presenti - -| Area | Cosa esiste oggi | Gap principale | -| --- | --- | --- | -| Overview | Sei card di accesso alle aree operative (`src/features/dashboard/overview-page.tsx:6-119`) | Nessun dato aggregato, alert, task o stato integrazioni | -| Telegram users | Lista, ricerca, profilo, ruoli, amministratori di gruppo, messaggi recenti, audit Telegram, grant | Nessuna anagrafica associativa collegata; paginazione/search lato server assente | -| Telegram groups | Elenco, tag, invito, visibilità, uscita dal gruppo | Mancano ciclo di vita, ownership, health check, metriche e storico | -| Telegram grants | Grant attivi e programmati, creazione e interruzione | Nessuna vista storica/archivio, reminder o approvazione | -| Microsoft 365 members | Elenco utenti Entra, numero associativo, licenze visibili, creazione account | Non è un vero registro soci; licenze non gestibili dalla UI | -| Microsoft 365 groups | Elenco gruppi e aggiunta/rimozione membri | Nessun access review, owner, gruppo orfano o drift detection | -| Web associations | CRUD bilingue, logo e dieci link pubblici (`src/features/associations/associations-page.tsx:144-200`) | È il catalogo pubblico delle associazioni, non il censimento dei membri | -| Web projects | CRUD bilingue, categorie, logo, link e drag-and-drop | È contenuto pubblico, non project management interno | -| Freshman guide | Upload, versione, data, download e delete PDF | Manca workflow di bozza/approvazione, preview, storico editoriale e reminder | -| Account | Profilo, passkey, sessioni, identità Telegram e ruoli | Mancano preferenze, notifiche e centro sicurezza amministrativo | - -### Capacità del backend già sfruttabili - -Il contratto tRPC installato espone già alcune superfici che non sono ancora raggiunte dalla navigazione della dashboard: - -- FAQ bilingui complete: categorie, creazione, modifica e cancellazione (`node_modules/@polinetwork/backend/dist/index.d.ts:1119-1237`). -- Composizione del direttivo (`tg.permissions.getDirettivo`), verifica gruppo, assegnazione ruoli e `canAddBot` (`.../index.d.ts:311-404`). -- Ricerca gruppi Telegram per testo, tag, invite link e ID (`.../index.d.ts:165-228`). -- Ultima guida disponibile (`web.guides_matricole.getLatestGuide`) (`.../index.d.ts:1378-1414`). -- Messaggi cifrati e audit Telegram, già utilizzati in parte nel profilo utente (`src/features/telegram/users.functions.ts:61-84`). -- Gestione grant attivi e schedulati, ma non un endpoint storico (`.../index.d.ts:704-827`). -- Directory Azure, numero associativo e membership dei gruppi (`.../index.d.ts:827-925`). - -Queste API permettono di realizzare rapidamente FAQ, centro direttivo, health check Telegram e widget “ultima guida”. Il censimento, invece, richiede un nuovo dominio dati o un’estensione del backend. - -## Diagnosi prodotto - -### 1. Manca un’entità persona centrale - -Il progetto ha tre rappresentazioni separate della stessa possibile persona: - -- Telegram: `id`, nome, username, ruoli e appartenenze; -- Microsoft 365: `id`, mail, nome, `employeeId`, `isMember`, licenze; -- account admin: identità Better Auth e Telegram collegato. - -Non c’è una relazione esplicita e auditabile tra questi record. Il numero associativo viene gestito dentro Azure (`src/features/azure/azure.functions.ts:19-42`), ma un socio non dovrebbe dipendere dall’esistenza di un account Microsoft 365. - -### 2. La home non aiuta a decidere cosa fare - -`DashboardOverviewPage` mostra aree navigabili e descrizioni statiche (`src/features/dashboard/overview-page.tsx:51-119`). Per un’associazione la prima schermata dovrebbe rispondere a domande operative: - -- quanti soci sono attivi e quanti stanno per scadere; -- chi non ha completato il profilo o il consenso; -- quali account Telegram/Azure non sono riconciliati; -- quali grant stanno per terminare; -- quali gruppi sono senza membri o senza owner; -- quali contenuti sono da revisionare; -- quali azioni recenti richiedono attenzione. - -### 3. Autorizzazione ancora globale - -Su `main` l’accesso è concesso a `owner`, `direttivo` e `president`, mentre `creator` è escluso (`src/server/authorization.ts:1-9`). Tutte le mutazioni usano il medesimo `adminMiddleware`; non esiste una matrice per modulo o operazione (`src/features/telegram/users.functions.ts:87-116`, `src/features/azure/azure.functions.ts:19-58`). - -È già presente una branch remota `origin/agent/hr-dashboard-read-only` che introduce l’idea corretta di ruolo HR in sola lettura. Va portata a un modello stabile e granulare prima di esporre dati personali del censimento. - -### 4. I dati sono caricati spesso tutti in una volta - -Le pagine chiamano `getAll` e filtrano/smistano principalmente nel browser. È comodo per il prototipo, ma diventa fragile con molti soci, gruppi e messaggi. Il censimento deve nascere con query server-side, filtri URL, paginazione reale, ordinamento e autorizzazione per campo. - -### 5. CMS pubblico e gestione interna sono ancora mescolati - -`Web projects` è un catalogo di contenuti pubblici con categorie `news`, `general`, `deprecated`, non un sistema per seguire attività, responsabili e scadenze interne. Conviene mantenere separati: - -- Content management: associazioni pubbliche, progetti pubblici, FAQ e guide; -- Operations: iniziative, task, eventi, volontari e responsabilità. - -## Feature prioritarie - -### P0 — fondamenta necessarie prima di allargare la dashboard - -#### Autorizzazione per capacità - -Passare da “admin sì/no” a permessi per modulo e azione: - -- `members.read`, `members.write`, `members.export`; -- `telegram.read`, `telegram.moderate`, `telegram.grants`; -- `azure.read`, `azure.members.write`, `azure.groups.write`; -- `content.read`, `content.write`, `content.publish`; -- `governance.read`, `governance.write`; -- `audit.read`, `settings.write`. - -Prevedere ruoli composti, per esempio `HR` read-only sui soci, `Content editor`, `Telegram moderator`, `Finance`, `Board member` e `Owner`. Le azioni ad alto impatto — cancellazioni, assegnazione ruoli, rimozione da gruppi, export dati — dovrebbero mostrare permesso richiesto, anteprima e conferma esplicita. - -#### Audit amministrativo unificato - -Creare un audit log per ogni modifica, indipendente dall’audit di moderazione Telegram: - -- attore, ruolo, data, IP/sessione; -- oggetto e valori prima/dopo; -- motivo obbligatorio per azioni sensibili; -- esito, errore e correlation ID; -- filtri per persona, modulo, azione e intervallo; -- export riservato e retention configurabile. - -#### Ricerca globale e centro notifiche - -Una command palette `⌘K`/`Ctrl+K` per cercare soci, utenti Telegram, gruppi, account Azure, FAQ e contenuti. Un centro notifiche dovrebbe raccogliere scadenze, errori di sincronizzazione, richieste in attesa, grant in scadenza e assegnazioni da completare. - -#### Health check integrazioni - -Card e pagina “Integrations” con ultimo sync, latenza, ultimo errore, contatori e azione retry per Telegram, Microsoft 365, Better Auth e sito. Il backend ha già endpoint utili per alcune verifiche; i problemi non dovrebbero apparire solo come toast dopo un click. - -### P1 — Censimento soci: il dominio centrale - -#### Anagrafica canonica - -Creare una sezione `/dashboard/association/members` con una tabella filtrabile e una scheda dettaglio `/dashboard/association/members/:memberId`. - -Campi consigliati per l’MVP: - -| Blocco | Dati | -| --- | --- | -| Identità | nome, cognome, nome visualizzato, email principale, telefono opzionale | -| Identificativo | ID interno, numero tessera/associativo univoco, eventuale codice fiscale solo se realmente necessario | -| Stato | prospect, richiesta, attivo, sospeso, scaduto, ex socio, archiviato | -| Iscrizione | data ingresso, anno/periodo associativo, data scadenza, tipo di iscrizione, stato rinnovo | -| Profilo associativo | università, corso, sede/città, anno di studio, competenze, lingue, interessi, disponibilità | -| Relazioni | team, ruolo interno, responsabile, progetti, eventi, turni e attività | -| Integrazioni | Telegram ID/username, Azure user ID, email Microsoft, gruppi, licenze, ultimo sync | -| Compliance | consensi separati, data consenso, fonte, revoca, note operative, ultima modifica | - -Evitare di trasformare il censimento in un contenitore indiscriminato di dati personali: ogni campo deve avere uno scopo, un responsabile e una retention. - -#### Workflow di iscrizione e rinnovo - -- richiesta di iscrizione con stato `pending`; -- checklist di verifica e approvazione da parte dell’HR/direttivo; -- assegnazione automatica del numero associativo; -- periodo di validità e reminder 30/15/7 giorni prima della scadenza; -- rinnovo, sospensione, uscita e riattivazione con storico; -- email/Telegram di benvenuto e conferma; -- badge visivo “profilo incompleto”, “consenso mancante”, “integrazione non collegata”. - -#### Importazione, deduplicazione e merge - -Import CSV con: - -- mapping delle colonne; -- dry-run prima del salvataggio; -- anteprima di nuove righe, aggiornamenti, duplicati ed errori; -- matching per email, numero associativo, Telegram ID, Azure ID e nome normalizzato; -- merge assistito con confronto campo per campo; -- report scaricabile per riga. - -Le operazioni massive devono sempre avere preview e conferma, senza cancellazioni implicite. - -#### Scheda socio 360° - -La pagina dettaglio dovrebbe riunire in un’unica timeline: - -- dati anagrafici e stato iscrizione; -- rinnovi e pagamenti, se il modulo economico viene attivato; -- identità Telegram/Azure e stato sincronizzazione; -- ruoli e gruppi; -- progetti, team, eventi e presenze; -- comunicazioni e notifiche inviate; -- documenti e consensi; -- audit completo delle modifiche. - -### P1 — Dashboard command center - -Sostituire la home a card statiche con una pagina composta da widget configurabili per ruolo: - -1. **Soci**: attivi, nuovi, in scadenza, da rinnovare, incompleti. -2. **Riconciliazione**: Telegram non collegati, Azure senza numero, duplicati sospetti. -3. **Accessi**: licenze assegnate, gruppi con accesso anomalo, utenti inattivi. -4. **Telegram**: grant attivi/in scadenza, gruppi nascosti, gruppi senza owner, errori bot. -5. **Contenuti**: FAQ/guide da pubblicare, contenuti obsoleti, link rotti. -6. **Attività recenti**: ultime modifiche con filtri e link diretto. -7. **Integrazioni**: stato e ultimo aggiornamento di ogni servizio. - -Ogni KPI deve essere cliccabile e portare a una lista già filtrata. Aggiungere quick action per “Nuovo socio”, “Importa soci”, “Cerca persona”, “Crea grant”, “Apri richieste” e “Controlla sincronizzazione”. - -### P1 — Riconciliazione identità e sincronizzazione - -Creare una pagina `Integrations → Reconciliation` che confronti il registro canonico con Telegram e Microsoft 365: - -- persona presente nel censimento ma non in Azure; -- account Azure senza socio corrispondente; -- Telegram username cambiato o account non collegato; -- numero associativo duplicato o incoerente; -- licenza assegnata a ex socio; -- membro di un gruppo senza ruolo o team compatibile; -- record che richiedono merge manuale. - -Per ogni differenza: motivo, confidence del matching, proposta di correzione, preview e azione manuale. In una fase successiva si può aggiungere sync automatica con regole approvate. - -### P1 — Governance e ruoli associativi - -Il backend espone già `getDirettivo`, ma manca una sezione amministrativa. Aggiungere: - -- composizione del direttivo e degli organi; -- incarico, data inizio/fine e sostituto; -- responsabili di team e deleghe; -- matrice ruoli/permessi della dashboard; -- storico delle nomine e revoche; -- registro decisioni, verbali e action item; -- agenda riunioni, quorum, votazioni e scadenze; -- approvazione a due persone per azioni sensibili. - -Una buona regola è distinguere sempre ruolo associativo, ruolo Telegram e permesso tecnico della dashboard: non devono essere sinonimi. - -### P1 — Comunicazioni e notifiche - -- Template bilingui per benvenuto, rinnovo, scadenza e cambio stato. -- Invio email e Telegram con anteprima, destinatari, variabili e log di consegna. -- Segmenti salvati: soci attivi, ex soci, team, corso, sede, gruppo Telegram. -- Digest giornaliero/settimanale per direttivo e HR. -- Preferenze personali e opt-out dove applicabile. -- Coda notifiche fallite con retry e motivo dell’errore. - -## Feature per area già presente - -### Telegram - -#### Moderation center - -Trasformare il profilo utente e l’audit in una console di moderazione completa: - -- coda di segnalazioni e casi; -- ban, unban, kick, mute e unmute con durata, motivo e storico; -- azioni di gruppo con conferma e limite di sicurezza; -- ricerca messaggi e contesto conversazionale; -- filtri per gruppo, gravità, stato e moderatore; -- link diretto al messaggio e prova dell’azione; -- analytics su volume, utenti attivi, segnalazioni e tempi di risposta. - -Il contratto backend contiene già i tipi di audit `ban`, `unban`, `kick`, `mute`, `unmute`, `ban_all` e `unban_all`: il passo mancante è costruire workflow e UI sopra questi eventi. - -#### Gruppi e bot - -- creazione/import di gruppi con validazione titolo, tag e invite link; -- controllo link rotto, gruppo nascosto, gruppo senza membri e gruppo senza amministratore; -- owner/responsabile operativo e data di ultima revisione; -- rotazione inviti e gestione ciclo di vita; -- check `canAddBot` e pagina salute del bot; -- statistiche per gruppo e ultimo messaggio; -- aggiornamento live tramite WebSocket/SSE, se il backend `WS_PATH` viene adottato. - -#### Grants - -- storico completo, inclusi terminati e interrotti; -- calendario e vista timeline; -- grant in scadenza e reminder automatici; -- approvazione da parte del direttivo; -- motivazione obbligatoria, allegati e log di invio Telegram; -- ricerca per richiedente, autorizzatore, gruppo e periodo; -- endpoint backend storico dedicato: oggi il contratto espone solo `getOngoing` e `getScheduled`. - -### Microsoft 365 / Azure - -- dashboard licenze: assegnate, inutilizzate, mancanti e a rischio; -- assegnazione/revoca licenze con permesso dedicato e audit; -- account inattivi e gruppi senza owner; -- access review periodico per gruppo; -- richieste di accesso con approvazione; -- onboarding guidato: crea socio → crea account → assegna numero → aggiunge gruppi → invia welcome mail; -- offboarding: blocca accessi, rimuove gruppi, revoca licenze, conserva audit; -- mapping diretto tra membro canonico e oggetto Entra; -- export report di conformità. - -La UI attuale visualizza `assignedLicensesIds`, ma il contratto disponibile espone mutazioni per numero associativo e membership gruppi, non per gestione licenze: per quest’ultima serve un’estensione backend/Graph API. - -### Web e contenuti - -#### FAQ - -Aggiungere `Web → FAQs`: è la feature con il miglior rapporto valore/dipendenza perché il backend espone già categorie e CRUD bilingue. MVP: - -- categorie con titolo e icona; -- domanda/risposta IT e EN; -- ricerca e filtro per categoria; -- ordinamento drag-and-drop; -- anteprima pubblica; -- stato bozza/pubblicata e storico modifiche. - -#### Workflow editoriale - -- draft, review, approvazione e publish; -- ruoli editor/reviewer/publisher; -- preview prima della pubblicazione; -- versioni e rollback; -- scheduling per data/ora; -- checklist lingua IT/EN, immagini e link; -- link checker e report contenuti obsoleti; -- metadata SEO, slug, social preview e canonical URL; -- cronologia “chi ha cambiato cosa”. - -#### Guide e associazioni pubbliche - -- preview PDF e indicazione della versione attualmente pubblicata; -- deprecazione invece della cancellazione definitiva; -- conteggio download e file sostitutivo; -- stato pubblico/nascosto e data revisione; -- validazione automatica dei link social; -- scheda associazione con owner interno, contatti di riferimento e stato verifica; -- approvazione a due step per contenuti pubblici. - -### Operatività interna - -Da tenere separata dal catalogo `Web projects`: - -- progetti interni con owner, stato, priorità, scadenza, milestone e task; -- board Kanban e calendario; -- assegnazione a team e volontari; -- commenti, allegati e decisioni; -- eventi con iscrizione, lista partecipanti, presenze e turni; -- gestione sale, attrezzatura e checklist; -- registro ore/attività volontarie; -- report impatto per progetto/evento. - -### Amministrazione economica e documentale - -Da introdurre quando il flusso associativo è chiaro: - -- quote associative e stato pagamento; -- ricevute, fatture, note spese e rimborsi; -- budget annuale per progetto/evento; -- approvazione spese e doppia firma; -- scadenze fiscali e assicurative; -- archivio documenti con versioni, permessi e retention; -- verbali, statuto, contratti e certificazioni; -- export per commercialista e report di bilancio. - -Per pagamenti e documenti sensibili è preferibile integrare servizi specializzati invece di costruire una contabilità completa dentro questa dashboard. - -## Censimento: proposta tecnica minima - -### Entità - -```text -Member -├── MembershipPeriod iscrizione annuale o per periodo -├── MemberIdentity Telegram, Azure, email e altri provider -├── MemberConsent consenso, fonte, data e revoca -├── MemberRole ruolo associativo con periodo di validità -├── MemberTeam appartenenza a team/progetto -├── MemberDocument documenti con permesso e retention -├── Payment quota/ricevuta, se attivato -└── Activity eventi, task, presenze e comunicazioni -``` - -Vincoli indispensabili: - -- numero associativo univoco; -- identità esterne univoche quando presenti; -- storico, non sovrascrittura cieca di stato e periodo; -- audit di ogni lettura sensibile e di ogni mutazione; -- permessi a livello di modulo e, se necessario, di campo; -- export del singolo socio e cancellazione/anonymizzazione secondo policy; -- nessun dato sensibile nei log applicativi o nei toast; -- retention configurabile e documentata. - -### Flusso MVP - -```text -Richiesta → verifica dati → deduplica → approvazione → numero socio - → collegamento Telegram/Azure → welcome → rinnovo → storico -``` - -### Acceptance criteria - -- Un operatore può creare un socio senza creare prima un account Azure. -- La scheda mostra chiaramente identità locale, Telegram e Azure e segnala i collegamenti mancanti. -- L’import CSV non scrive nulla prima della conferma dell’anteprima. -- Duplicati e conflitti vengono mostrati campo per campo. -- Un HR read-only può consultare solo ciò che il suo ruolo consente e non vede pulsanti di scrittura. -- Ogni cambio di stato, numero, consenso o identità esterna è rintracciabile nell’audit. -- Il socio in scadenza compare automaticamente nella coda di attenzione. -- Nessuna cancellazione massiva è disponibile senza conferma esplicita e riepilogo delle righe coinvolte. - -## Miglioramenti UX e frontend - -### Navigazione - -Aggiungere categorie coerenti: - -```text -Overview -Association - Members / Renewals / Teams -Operations - Tasks / Projects / Events -Governance - Board / Meetings / Decisions -Integrations - Telegram / Microsoft 365 / Reconciliation / Health -Content - Associations / Projects / FAQs / Guides -Reports -Account -``` - -### Liste e dettagli - -- Filtri, tab, ordinamento e pagina nello URL, così un link conserva il contesto. -- Query server-side e paginazione reale per il censimento e i log. -- Tabelle su desktop, card/row sheet su mobile; evitare che ogni lista richieda scroll orizzontale. -- Colonne configurabili e viste salvate per ruolo. -- Selezione multipla solo dove esiste un caso d’uso reale, sempre con preview e conferma. -- Stati uniformi: loading, empty, error, stale, saving e permission denied. -- Timeline e deep link tra membro, gruppi, ruoli, contenuti e audit. - -### Lingua e contenuti - -Il contenuto pubblico richiede IT/EN, mentre l’interfaccia amministrativa è quasi tutta in inglese. Decidere una direzione esplicita: - -- UI bilingue con preferenza per utente; oppure -- UI italiana per il team associativo, mantenendo IT/EN sui contenuti pubblici. - -In entrambi i casi servono messaggi e validazioni non misti e un controllo di completezza linguistica. - -### Design system e responsive - -L’audit statico `@memi-design/cli@2.7.9 diagnose . --json --no-write --fail-on none` ha prodotto 87/100, con accessibilità 100, componenti 100, visual-system 76, colore 68 e responsive 88. Le evidenze principali sono: - -- 9 colori hex rilevati; uno è in `src/styles.css:9` e diversi provengono da CSS compilato in `.output`; -- 82 utility colore; -- 13 dimensioni testo; -- 88 utility di spacing; -- 8 radius e 6 shadow utility; -- 190 valori Tailwind arbitrari; -- 18 route e solo 23 utility responsive rilevate. - -Il punteggio è un indicatore, non un gate funzionale: il target include anche `.output`, quindi va ripetuto escludendo gli artefatti generati. Il lavoro consigliato è promuovere colori, radius, shadow e spacing ricorrenti a token semantici e verificare mobile/tablet sulle pagine con tabelle e dialog lunghi. Il feedback dinamico e il recupero da errori non sono completamente valutabili con lo scan statico e richiedono prove interattive. - -## Roadmap proposta - -| Fase | Obiettivo | Risultato | -| --- | --- | --- | -| 0 — Stabilizzazione | RBAC read/write, audit unificato, health check, query server-side, cleanup file duplicati | Base sicura e osservabile | -| 1 — Censimento MVP | `Member`, periodi iscrizione, stati, lista, dettaglio, import dry-run, deduplica, consensi | Registro soci utilizzabile | -| 2 — Command center | KPI aggregati, attention queue, notifiche, quick actions, riconciliazione Telegram/Azure | Dashboard che guida il lavoro quotidiano | -| 3 — Workflow | richieste, rinnovi, welcome, offboarding, team, ruoli associativi, direttivo | Gestione del ciclo di vita | -| 4 — Content e community | FAQ, workflow editoriale, moderation center, grant history, bot/group health | Copertura completa dei canali esistenti | -| 5 — Operations | task, eventi, volontari, documenti e finanza essenziale | Gestione associativa end-to-end | -| 6 — Automazioni | reminder, sync approvata, digest, report schedulati, anomalie | Riduzione del lavoro manuale | - -## Priorità valore/dipendenze - -| Feature | Valore | Dipendenza | Priorità | -| --- | --- | --- | --- | -| Censimento soci | Molto alto | nuovo modello/API | P1 | -| Dashboard KPI + attention queue | Molto alto | aggregati censimento | P1 | -| RBAC granulare | Molto alto | policy ruoli | P0 | -| Riconciliazione identità | Molto alto | Member + connettori | P1 | -| FAQ CMS | Alto | backend quasi pronto | P1 | -| Rinnovi/notifiche | Alto | Member + scheduler/email | P1 | -| Audit amministrativo | Alto | schema audit | P0 | -| Azure access review/licenze | Alto | Graph/backend extension | P2 | -| Moderation center | Alto | casi/segnalazioni backend | P2 | -| Governance direttivo | Alto | dati organi/mandati | P2 | -| Eventi e volontari | Medio-alto | calendario/registrazioni | P2 | -| Finanza e documenti | Alto | policy e integrazione dedicata | P3 | -| AI assistant interno | Medio | permessi, audit, privacy, retrieval | P3 | - -## Feature “fighe” con valore reale - -Da aggiungere dopo il nucleo, non prima: - -- tessera socio digitale con QR e validità; -- profilo socio condivisibile solo con consenso; -- mappa dei team, competenze e disponibilità; -- timeline visuale dell’associazione e degli incarichi; -- sincronizzazione con indicatore di drift “prima/dopo”; -- dashboard con widget personalizzabili per HR, direttivo e moderatori; -- report PDF/CSV schedulati inviati al direttivo; -- centro comando da tastiera con azioni rapide; -- rilevazione di duplicati e anomalie con spiegazione del matching; -- preview pubblica dei contenuti con confronto tra versione online e bozza; -- modalità mobile/PWA per check-in eventi e gestione rapida; -- assistant interno limitato ai documenti e ai dati autorizzati, con citazione della fonte e nessuna azione irreversibile autonoma. - -## Verifica tecnica eseguita - -Comandi eseguiti dopo aver riallineato `node_modules` al lockfile con `pnpm install --frozen-lockfile`: - -- `pnpm typecheck` — passato; -- `pnpm test` — 16 test passati; -- `pnpm check` — Biome pulito su 141 file; -- `pnpm build` — build client, SSR e Nitro passato; -- `npx -y @memi-design/cli@2.7.9 diagnose . --json --no-write --fail-on none` — 87/100, 0 critici, 8 finding di design/maintainability/responsive. - -Il report non modifica il codice applicativo. L’unica azione locale aggiuntiva è stata l’installazione delle dipendenze già dichiarate nel lockfile, necessaria perché l’ambiente iniziale non aveva `@dnd-kit/react` e aveva una versione precedente del backend. - -## Decisioni da prendere prima di implementare il censimento - -1. Il numero associativo resta un identificativo Azure o diventa proprietà del nuovo `Member`? -2. L’iscrizione è annuale, semestrale o senza scadenza? -3. Quali dati sono davvero necessari per il tesseramento e quali sono vietati/non pertinenti? -4. HR può leggere tutto o alcuni campi devono essere mascherati? -5. Il pagamento è manuale, bonifico, Stripe o altro? -6. Chi approva iscrizioni, rinnovi, ruoli e cancellazioni? -7. Qual è la policy di conservazione, export e anonimizzazione? -8. I progetti interni devono essere separati dal catalogo pubblico esistente? - -La decisione architetturale più importante è la prima: se il nuovo censimento nasce direttamente come registro canonico, tutte le altre feature — dashboard, Azure, Telegram, notifiche, eventi e report — possono costruirsi attorno alla stessa persona invece di aggiungere altre liste scollegate. From 093d50770c02f8186eaa58a2b1bf05dda244e04b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gabriele=20Vigan=C3=B2?= Date: Sat, 29 Aug 2026 02:24:32 +0200 Subject: [PATCH 6/6] docs: streamline PRD into a plain feature spec MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Drop verification tables, priority matrix, roadmap, and acceptance criteria — that analysis artifact doesn't belong in the living spec. Keep only roles/hierarchy, feature descriptions, constraints, and open decisions. Co-Authored-By: Claude Sonnet 5 --- PRD_Admin_Dashboard_PoliNetwork.md | 500 ++++++++--------------------- 1 file changed, 141 insertions(+), 359 deletions(-) diff --git a/PRD_Admin_Dashboard_PoliNetwork.md b/PRD_Admin_Dashboard_PoliNetwork.md index 297f3ee..a215909 100644 --- a/PRD_Admin_Dashboard_PoliNetwork.md +++ b/PRD_Admin_Dashboard_PoliNetwork.md @@ -1,516 +1,298 @@ # PRD — Admin Dashboard PoliNetwork **Documento di prodotto per il Team IT** -**Versione:** 1.1 -**Data:** 29 agosto 2026 (revisione con correzioni e decisioni del Team IT rispetto alla v1.0 del 20 agosto 2026) +**Versione:** 2.0 +**Data:** 29 agosto 2026 **Stato:** Bozza per revisione -**Branch/commit di riferimento per l'analisi:** `report/new-feature-roadmap`, con `pnpm install --frozen-lockfile` eseguito per ispezionare il contratto `@polinetwork/backend@0.17.1`. -## 0. Scopo e metodo di questo documento +## 0. Scopo -Questo documento è un **nuovo PRD**, che sostituisce il precedente `PRD_Admin_Dashboard_Associazione.md` (v0.2, rimosso da questa repository perché superato). Il vecchio documento restava un riferimento sui bisogni di business espressi dall'associazione, ma **non era usato come fonte di verità tecnica**: ogni funzionalità qui descritta è stata verificata direttamente su: - -- il codice del frontend/BFF in `src/` (route, feature, server functions, middleware di autorizzazione); -- il contratto tipizzato del backend reale, `node_modules/@polinetwork/backend/dist/index.d.ts` (unica sorgente di verità su cosa il backend espone oggi via tRPC: router `tg`, `azure`, `web`, `auth`, `test`); -- i test (`tests/server-security.test.mjs`) e la configurazione (`AGENTS.md`, `package.json`, `README.md`). - -Dove il vecchio PRD presuppone dati, ruoli o flussi che non esistono nel codice attuale, questo documento lo segnala esplicitamente come **mancante**, propone l'ipotesi minima necessaria per renderlo implementabile, e rimanda le decisioni non deducibili alla sezione **11. Decisioni aperte**. - -**Criterio di priorità dichiarato dal Team IT e applicato qui:** le funzionalità interne di PoliNetwork (anagrafica soci, censimento admin/team, ruoli e gerarchie, governance, team) hanno priorità sulle aree pensate per soggetti esterni (associazioni partner, aziende, alloggi), **anche dove il vecchio PRD indicava l'ordine opposto**. Questo è il motivo principale per cui la struttura delle priorità in questo documento differisce da quella del documento originale. +Documento di riferimento per le funzionalità della Admin Dashboard di PoliNetwork. Le funzionalità interne (anagrafica soci, censimento admin/team, ruoli, governance, team) hanno priorità sulle aree pensate per soggetti esterni (associazioni partner, aziende, alloggi). --- -## 1. Stato reale verificato della piattaforma - -### 1.1 Stack e perimetro del repository - -- Frontend: React 19, TanStack Start/Router, Vite, server Nitro, Tailwind CSS v4, shadcn/ui, TanStack Table (`package.json`, `README.md`). -- Autenticazione: Better Auth (client in `src/lib/auth.ts`, server in `src/server/auth.server.ts`), con email OTP e passkey (`@better-auth/passkey`). -- Backend: **esterno**, consumato come pacchetto npm tipizzato `@polinetwork/backend` via tRPC (`AppRouter`) più un plugin Better Auth dedicato per il collegamento Telegram. Questo repository **non ha database proprio, non ha job/cron, non ha invio email**: tutta la logica di dominio (utenti Telegram, gruppi, membri Azure, contenuti web) vive nel backend condiviso. -- `AGENT_MODE=true` (solo se `NODE_ENV=development`) sostituisce sessione e ruoli con una sessione fittizia con tutti i ruoli admin, esclusivamente per anteprime locali (`src/server/auth.server.ts:16-44`, `AGENTS.md`). Non ha effetto in produzione. - -### 1.2 Autenticazione e onboarding — flusso verificato - -1. `/login`: email OTP o passkey (`src/features/auth/login-page.tsx`). Nessuna registrazione self-service: presuppone un account Better Auth già esistente. -2. Dopo il login, `dashboardAccessMiddleware`/`adminMiddleware` (`src/server/auth.middleware.ts`) controllano la sessione: - - nessun `telegramId` collegato → redirect a `/onboarding/link`, dove l'utente genera un codice temporizzato e lo usa con `/link` sul bot Telegram (`src/features/onboarding/telegram-link-page.tsx`); - - `telegramId` presente ma nessun ruolo admin → redirect a `/onboarding/unauthorized`; - - ruolo admin presente → accesso a `/dashboard`. -3. I ruoli non sono un concetto della dashboard: sono **letti in diretta da Telegram** (`backend.tg.permissions.getRoles`), la stessa fonte usata dal bot. +## 1. Persone, ruoli e gerarchie -### 1.3 Ruoli e permessi — modello attuale (`src/server/authorization.ts`, contratto `USER_ROLE`) +### 1.1 Ruoli Telegram Il backend Telegram conosce sei ruoli: `admin`, `hr`, `president`, `direttivo`, `creator`, `owner`. -| Ruolo | Accesso dashboard (`ADMIN_ROLES`) | Scrittura dashboard (`WRITE_ADMIN_ROLES`) | +| Ruolo | Accesso dashboard | Scrittura dashboard | |---|---|---| | `owner` | sì | sì | | `direttivo` | sì | sì | | `president` | sì | sì | -| `hr` | sì | **no — sola lettura** (PR #67) | -| `admin` | **no** | no | -| `creator` | **no, escluso esplicitamente** anche se combinato con altri ruoli | no | - -Osservazioni rilevanti per questo PRD: - -- **Il ruolo base `admin` — la maggioranza dei collaboratori PoliNetwork — non ha alcun accesso alla dashboard oggi**, indipendentemente da eventuali incarichi come "Capo Admin". Questo è il gap principale rispetto alla sezione 3 del vecchio PRD ("Dashboard Admin e Capo Admin"). -- `creator` è escluso per progetto (`hasAdminRole` ritorna `false` se la lista ruoli contiene `creator`), verosimilmente per segregare l'account con pieni poteri sul bot dal pannello web. Va preservato salvo decisione contraria. -- I permessi sono **binari e globali per ruolo**: non esiste granularità per modulo/azione (es. "può leggere i soci ma non modificarli"), né scoping (es. "vede solo gli admin del proprio corso"). `hr` è l'unica eccezione, ed è un blocco di scrittura totale, non selettivo. -- **Non esistono nel backend**: concetto di "corso di studi", "team interno" (IT, Design & Social, International, HR, Events & Partnerships), "Capo Admin", "rappresentante". Sono assenti sia come ruolo Telegram sia come campo dati in qualunque entità esposta dal contratto. - -### 1.4 Cosa esiste davvero, area per area - -| Area | Percorso | Stato | Dettaglio verificato | -|---|---|---|---| -| Overview | `/dashboard` | **Implementato (minimale)** | Sei card statiche di collegamento alle aree (`overview-page.tsx`). Nessun KPI, alert, scadenza o attività recente. | -| Telegram Users | `/dashboard/telegram/users`, `/users/$userId` | **Implementato** | Elenco (ricerca/paginazione lato client), profilo con ruoli, gruppi amministrati, ultimi messaggi, audit di moderazione, grant. Azioni: assegna/rimuovi ruolo e admin di gruppo, crea/interrompi grant. | -| Telegram Groups | `/dashboard/telegram/groups` | **Implementato** | Elenco, tag, invito, toggle visibilità, uscita dal gruppo con conferma. Manca creazione gruppo, ownership, statistiche, stato del bot. | -| Telegram Grants | `/dashboard/telegram/grants` | **Implementato** | Tab attivi/programmati, creazione/interruzione. Il backend espone solo `getOngoing`/`getScheduled`: **non esiste uno storico** dei grant terminati. | -| Azure Members | `/dashboard/azure/members` | **Implementato** | Elenco con numero associativo (`employeeId`) e licenze, filtro "solo membri", creazione con invio email di benvenuto, modifica numero. Nessuna cancellazione; nessuna gestione licenze (il backend non la espone). | -| Azure Groups | `/dashboard/azure/groups` | **Implementato** | Elenco gruppi, aggiunta/rimozione membri. | -| Web Associations | `/dashboard/web/associations` | **Implementato** | CRUD bilingue IT/EN, logo, 10 link social, editing inline. È la **vetrina pubblica** delle associazioni sul sito, non un'area a cui le associazioni stesse accedono. | -| Web Projects | `/dashboard/web/projects` | **Implementato** | CRUD bilingue, categorie (`news`/`general`/`deprecated`), drag&drop, logo, link. | -| Web Guides | `/dashboard/web/guides` | **Implementato** | Upload/versione/data/eliminazione PDF guida matricole. Manca bozza/approvazione, storico, anteprima pubblica. | -| Account | `/dashboard/account` | **Implementato** | Profilo, identità Telegram + ruoli, passkey, sessioni attive con revoca. | -| Onboarding/Login | `/login`, `/onboarding/*` | **Implementato** | Vedi §1.2. | - -### 1.5 Capacità del backend già pronte ma non raggiunte dal frontend - -- `web.faqs.*`: categorie e CRUD FAQ bilingue completo — pronto, nessuna pagina. -- `tg.permissions.getDirettivo`: composizione del Direttivo — pronto, nessuna UI di governance. -- `tg.permissions.canAddBot`, `tg.groups.search/getByTag/getByInviteLink` — pronti, non usati. -- `web.guides_matricole.getLatestGuide` — pronto, non mostrato da nessuna parte come "ultima guida disponibile". - -### 1.6 Cosa non esiste — né in frontend né nel contratto backend - -Nessuna delle seguenti è realizzabile senza nuovo lavoro sul backend condiviso o su un nuovo servizio dati: - -- Un'entità **socio/membro associativo** indipendente da Telegram e da Azure. Oggi il numero associativo esiste solo dentro Azure (`azure.members.setAssocNumber`), e presuppone un account Microsoft 365 — un volontario senza account Azure non è "socio" da nessuna parte. -- Stato di iscrizione, rinnovo, scadenza, storico pagamenti. -- Invio email automatico (rinnovo, compleanno, benvenuto oltre a quello già presente per la creazione membro Azure) — non esiste un motore di scheduling/cron in questo repository, che è un frontend/BFF. -- Integrazione WhatsApp (solo Telegram è integrato, in ogni sua parte). -- Eventi delle associazioni / "PoliTamTam". -- Sistema di crediti per le associazioni partner. -- Accesso alla dashboard per le associazioni partner stesse (oggi l'autenticazione presuppone un singolo tipo di utente: un collaboratore interno con ruolo Telegram). -- "Corso di studi", "team interno", "Capo Admin", "rappresentante" come dati. -- Workflow di candidatura/onboarding per nuovi admin. -- Un **audit log amministrativo** che copra le azioni della dashboard stessa (creazione/modifica associazione, assegnazione ruolo, ecc.). Esiste solo l'audit di moderazione Telegram (`ban`/`unban`/`kick`/`mute`/`unmute`/`ban_all`/`unban_all`), che riguarda la moderazione dei gruppi, non le operazioni amministrative sulla piattaforma. - ---- - -## 2. Principi guida di questo PRD - -1. **Priorità interna prima che esterna**: anagrafica soci, censimento admin/team, ruoli, governance e team vengono prima di associazioni partner, aziende, alloggi — vedi §0. -2. **Una sola identità persona**: qualunque nuova funzionalità deve collegarsi all'identità esistente (Telegram / Azure / Better Auth), non aggiungere una quarta rappresentazione scollegata. -3. **Continuità del modello di permessi**: qualunque estensione dei permessi deve restare compatibile con `ADMIN_ROLES`/`WRITE_ADMIN_ROLES` e i ruoli Telegram esistenti, introducendo granularità in modo incrementale. -4. **Nessuna azione distruttiva multipla senza anteprima e conferma esplicita** — vincolo permanente da `AGENTS.md`. -5. **Minimizzazione dei dati personali**: ogni nuovo campo su soci/admin deve avere uno scopo dichiarato, un responsabile e un'ipotesi di retention. -6. **Riuso prima di ricostruzione**: dove il backend espone già una capacità (FAQ, Direttivo, ricerca gruppi), si costruisce la UI prima di chiedere nuovo lavoro di backend. - ---- +| `hr` | sì | no — sola lettura | +| `admin` | da estendere (§1.3) | no | +| `creator` | no, escluso esplicitamente anche se combinato con altri ruoli | no | -## 3. Persone, ruoli, gerarchie e struttura organizzativa +I permessi sono binari e globali per ruolo: non esiste granularità per modulo/azione né scoping (es. "vede solo gli admin del proprio corso"). Va introdotta un'autorizzazione per capacità (§2.1) che estenda questo modello senza sostituirlo. -Questa sezione risponde esplicitamente alla richiesta di un'attenzione dedicata a membri, soci, admin, team, gerarchie e permessi. +### 1.2 Socio, Admin e membro di team — categorie indipendenti -### 3.1 I tre piani oggi sovrapposti +Socio, Admin e membro di un team interno (IT, Design & Social, International, HR, Events & Partnerships, ...) sono **tre categorie indipendenti**, non una gerarchia annidata: -Nel sistema attuale esiste un solo piano di identità/permesso: il ruolo Telegram. Concettualmente andrebbero distinti tre piani, oggi confusi in uno: +- **Socio**: chi risulta iscritto e in regola con la quota associativa (Anagrafica Soci, §3). +- **Admin**: chi ha un ruolo operativo/organizzativo su PoliNetwork. +- **Membro di team**: chi fa parte di un team interno (§7). -| Piano | Cosa rappresenta | Stato oggi | -|---|---|---| -| Ruolo associativo/organizzativo | Chi sei nell'associazione: socio, admin, Capo Admin, membro del Direttivo, Presidente | **Non esiste come dato**: è implicito nei ruoli Telegram, che però non distinguono "admin semplice" da "Capo Admin" | -| Ruolo/permesso Telegram | Cosa puoi fare nei gruppi gestiti dal bot | Esiste (`USER_ROLE`) | -| Permesso applicativo della dashboard | Cosa puoi vedere/modificare in questa applicazione | Esiste solo come mappatura 1:1 dal ruolo Telegram (`ADMIN_ROLES`/`WRITE_ADMIN_ROLES`) | - -**Raccomandazione**: introdurre progressivamente il primo piano come dato del futuro Censimento Admin/Team e dell'Anagrafica Soci (§5.2), e permessi applicativi granulari (§5.1.1) sopra — senza necessariamente toccare il piano Telegram, che resta la fonte di verità per la moderazione dei gruppi. - -### 3.2 Socio, Admin e membro di team — categorie indipendenti, non annidate - -**Correzione rispetto a una lettura gerarchica**: il vecchio PRD usa "socio" (chi versa la quota associativa) e "admin" (chi si occupa operativamente dell'associazione) in un modo che suggerisce una relazione di inclusione ("admin, spesso ma non necessariamente anche socio"). Questa lettura va corretta: si tratta di **tre categorie indipendenti**, non di una gerarchia annidata: - -- **Socio**: chi risulta iscritto e in regola con la quota associativa (Anagrafica Soci, §5.2). -- **Admin**: chi ha un ruolo operativo/organizzativo su PoliNetwork (oggi il ruolo Telegram `admin` e superiori). -- **Membro di un team interno** (IT, Design & Social, International, HR, Events & Partnerships, ...): chi fa parte di un team (§5.6). - -Un admin può essere socio o no; un socio può essere admin o no; un membro di un team può essere admin, socio, entrambi o nessuno dei due. **Le tre categorie possono intersecarsi in qualunque combinazione** e nessuna implica automaticamente le altre due. - -**Il Socio resta comunque la categoria più rilevante per l'associazione**: è chi la costituisce formalmente dal punto di vista associativo. Admin e membro di team sono categorie organizzative/operative e non sostituiscono né presuppongono lo status di socio. +Un admin può essere socio o no; un socio può essere admin o no; un membro di un team può essere admin, socio, entrambi o nessuno dei due: le tre categorie si intersecano liberamente e nessuna implica le altre. **Il Socio resta la categoria più rilevante per l'associazione**: è chi la costituisce formalmente. Admin e membro di team sono categorie organizzative/operative e non sostituiscono né presuppongono lo status di socio. -Nel codice attuale questa distinzione non esiste: `AzureMember.isMember` è l'unico flag di appartenenza, e riguarda solo chi ha (o dovrebbe avere) un account Microsoft 365. Un admin senza account Azure non è "socio" in nessuna parte del sistema oggi. - -**Ipotesi minima adottata in questo PRD** (da confermare, vedi Decisioni aperte §11): - -- Un **Socio** è un record dell'Anagrafica Soci (§5.2), indipendente da Telegram e da Azure, e indipendente dall'essere o meno admin/membro di team. -- Un **Admin** è una persona con un ruolo organizzativo (Admin, Capo Admin, Direttivo, Presidente, ...) tracciato dal Censimento Admin/Team (§5.2) e — se opera sui canali PoliNetwork — con un'identità Telegram collegata, necessaria per accedere alla dashboard con l'attuale meccanismo di autenticazione. Non deve necessariamente essere anche Socio. +- Un **Socio** è un record dell'Anagrafica Soci (§3), indipendente dall'essere admin o membro di team. +- Un **Admin** è una persona con un ruolo organizzativo (Admin, Capo Admin, Direttivo, Presidente, ...) tracciato dal Censimento Admin/Team (§3), con un'identità Telegram collegata se opera sui canali PoliNetwork. Non deve necessariamente essere anche Socio. - Un **Capo Admin** è un Admin con uno scope aggiuntivo (es. corso di studi) e visibilità limitata al proprio ambito. -### 3.3 Gerarchia proposta (minima, non inventata) - -La gerarchia seguente riguarda **solo l'asse ruolo organizzativo/operativo** (Owner → Capo Admin → Admin). Lo status di **Socio** e l'appartenenza a un **team interno** sono assi indipendenti (§3.2): non sono un livello sotto "Admin", ma condizioni che possono coesistere con qualunque punto della gerarchia sottostante, o con nessuno. +### 1.3 Gerarchia organizzativa ``` Owner / Presidente / Direttivo — governance, accesso e scrittura completi │ Capo Admin (per corso/ambito) — visibilità e azioni limitate al proprio ambito │ - Admin — operativo, oggi senza accesso alla dashboard + Admin — operativo ``` -Questa gerarchia **non corrisponde a nulla nel backend attuale** oltre al livello Owner/Presidente/Direttivo/HR. Costruirla richiede: un nuovo campo scope (es. corso di studi) sugli admin, un modo per marcare "Capo Admin" (nuovo ruolo o flag con scope — **ancora da decidere**, §11), e l'estensione di `ADMIN_ROLES` per dare accesso in lettura scoped agli admin semplici e ai Capo Admin. **Deciso**: l'admin semplice deve ottenere accesso alla dashboard, con permessi determinati dal proprio scope (§11) — oggi ne è escluso, quindi resta lavoro da fare su `authorization.ts`. +Lo status di Socio e l'appartenenza a un team interno sono assi indipendenti (§1.2): possono coesistere con qualunque punto della gerarchia sopra, o con nessuno. ---- +Il Direttivo assegna e revoca il ruolo di Capo Admin (periodicità da definire). L'admin "semplice" deve ottenere accesso alla dashboard, con permessi determinati dal proprio scope. Resta da decidere se "Capo Admin" sia un nuovo ruolo Telegram/backend o un attributo applicativo (scope) gestito solo lato dashboard (§19). -## 4. Matrice di priorità complessiva - -Legenda stato: 🟢 Implementato · 🟡 Parziale · 🔴 Mancante · ⚪ Obsoleto (non verrà realizzato) - -| # | Funzionalità | Origine | Stato | Priorità | Dipendenza principale | -|---|---|---|---|---|---| -| 1 | RBAC granulare per modulo/scope | Nuova (emersa dall'analisi) | 🔴 | **P0** | Nessuna, estende `authorization.ts` | -| 2 | Audit amministrativo unificato | Nuova | 🔴 | **P0** | Nuovo schema/endpoint backend | -| 3 | Identity Provider PoliNetwork | Nuova (richiesta esplicita Team IT) | 🔴 | **P0** | Nuovo servizio; precondizione di §5.1.5, §5.7, §6.1 | -| 4 | Gestione consensi e firma privacy policy in dashboard | Nuova (richiesta esplicita Team IT) | 🔴 | **P0** | Identity Provider (#3) | -| 5 | Anagrafica Soci (attivi paganti + storico) | Vecchio PRD §4 (implicito), corretta | 🔴 | **P1** | Nuovo dominio dati backend | -| 6 | Censimento Admin/Team (rinnovo interesse) | Nuova, corretta da bozza "censimento soci" | 🔴 | **P1** | Nuovo dominio dati backend + Identity Provider (#3) per il flusso self-service (§5.7) | -| 7 | Dashboard "command center" (home con KPI) | Nuova, evoluzione overview attuale | 🟡 | **P1** | Aggregati da Anagrafica Soci/Censimento | -| 8 | Governance / Direttivo (pagina dedicata) | Nuova (backend pronto) | ⚪ **Obsoleto** | — | Assorbito dal Censimento Admin/Team (#6), vedi §5.3 | -| 9 | Dashboard Admin e Capo Admin | Vecchio PRD §3 | 🔴 | **P1** | Censimento Admin/Team + nuovo scope "corso" + estensione ruoli | -| 10 | Gestione Soci e Rinnovi (quota, ricevute) | Vecchio PRD §4, corretta | 🔴 | **P1** | Anagrafica Soci + upload/approvazione ricevute in dashboard | -| 11 | FAQ (Web) | Nuova (backend pronto) | 🟡 (backend pronto, UI assente) | **P1** | Nessuna, basso sforzo | -| 12 | Aree Team interni | Vecchio PRD §2 | 🔴 | **P2** | Struttura team come dato | -| 13 | Onboarding e Censimento Admin (flusso self-service) | Vecchio PRD §6, molto ampliata | 🔴 | **P2** | Identity Provider (#3), Censimento Admin/Team (#6) | -| 14 | Email di compleanno | Vecchio PRD §5 | 🔴 | **P2** | Anagrafica Soci (data di nascita non esiste oggi) | -| 15 | Miglioramenti Telegram (storico grant, moderazione) | Aree esistenti | 🟡 | **P2** | Nuovi endpoint backend per lo storico | -| 16 | Miglioramenti Azure (licenze, access review) | Aree esistenti | 🟡 | **P2** | Estensione backend/Graph | -| 17 | Area Associazioni Partner (accesso multi-referente, richieste, crediti) | Vecchio PRD §1 (era P0 lì), corretta | 🔴 | **P2** (declassata, vedi §0) | Identity Provider (#3) per l'accesso esterno multi-tenant | -| 18 | Eventi associazioni / PoliTamTam | Vecchio PRD §1.4, corretta | 🔴 | **P2** | Area Associazioni Partner (#17), flusso di approvazione | -| 19 | Area Aziende | Vecchio PRD §7 | 🔴 | **P3** | Da progettare, soggetti esterni | -| 20 | Area proprietari casa / Bacheca casa | Vecchio PRD §8-9 | 🔴 | **P3** | Da progettare, soggetti esterni | -| 21 | Newsletter | Vecchio PRD §10 | 🔴 | **P3** | Anagrafica Soci + eventi | +Una persona admin appartiene a **un solo corso di studi** come dato anagrafico personale, ma può essere admin/Capo Admin con **scope su gruppi di corsi diversi** contemporaneamente: il corso di appartenenza personale e lo scope di responsabilità sono due campi distinti. --- -## 5. Feature prioritarie — dominio interno PoliNetwork - -### 5.1 Fondamenta (P0) - -#### 5.1.1 Autorizzazione per capacità (RBAC granulare) +## 2. Fondamenta -**Stato: mancante.** Oggi un ruolo apre o chiude intere aree; non esiste un permesso per singola azione né uno scoping ("solo il mio corso", "solo lettura su questo modulo"). +### 2.1 Autorizzazione per capacità (RBAC granulare) -Requisiti minimi: -- Permessi indipendenti per modulo: lettura/scrittura su soci, Telegram, Azure, contenuti, governance, audit. -- Composizione di ruoli: un utente può avere più capacità (es. Content editor + Telegram moderator). -- Azioni ad alto impatto (cancellazioni, assegnazione ruoli, rimozione da gruppi, export dati personali) devono mostrare il permesso richiesto e richiedere conferma esplicita. -- Deve restare retrocompatibile con `ADMIN_ROLES`/`WRITE_ADMIN_ROLES`: i ruoli Telegram esistenti diventano un caso particolare del nuovo modello, non vengono sostituiti da un giorno all'altro. +Permessi indipendenti per modulo: lettura/scrittura su soci, Telegram, Azure, contenuti, governance, audit. Un utente può avere più capacità (es. Content editor + Telegram moderator). Le azioni ad alto impatto (cancellazioni, assegnazione ruoli, rimozione da gruppi, export dati personali) mostrano il permesso richiesto e richiedono conferma esplicita. Resta retrocompatibile con i ruoli Telegram esistenti, che diventano un caso particolare del nuovo modello. -#### 5.1.2 Audit amministrativo unificato +### 2.2 Audit amministrativo unificato -**Stato: mancante** (esiste solo l'audit di moderazione Telegram, dominio diverso). +Ogni mutazione amministrativa produce una voce di audit con: attore, ruolo al momento dell'azione, timestamp, oggetto modificato, valori prima/dopo, motivo (obbligatorio per azioni sensibili), esito. Precondizione per esporre dati personali dell'Anagrafica/Censimento a più ruoli. -Ogni mutazione lanciata da `writeAdminMiddleware` dovrebbe produrre una voce di audit con: attore, ruolo al momento dell'azione, timestamp, oggetto modificato, valori prima/dopo, motivo (obbligatorio per azioni sensibili), esito. Necessario prima di esporre dati personali del Censimento a più ruoli. +### 2.3 Ricerca globale -#### 5.1.3 Home come centro operativo +Command palette che cerca trasversalmente soci, utenti Telegram, gruppi, membri Azure, FAQ e contenuti. -**Stato: parziale** — oggi è un elenco statico di link (`overview-page.tsx:6-119`). Priorità P1 (dipende dagli aggregati del Censimento, quindi viene dopo le fondamenta P0), ma la si cita qui perché è il punto di ingresso di tutte le altre funzionalità: soci in scadenza, account non riconciliati, grant in scadenza, contenuti da pubblicare, attività recenti. Ogni indicatore deve poter essere cliccato per aprire la lista filtrata corrispondente. +### 2.4 Home come centro operativo -#### 5.1.4 Ricerca globale +Indicatori azionabili: soci in scadenza, account non riconciliati, grant in scadenza, contenuti da pubblicare, attività recenti. Ogni indicatore è cliccabile e apre la lista filtrata corrispondente. -**Stato: mancante.** Una command palette che cerchi trasversalmente soci, utenti Telegram, gruppi, membri Azure, FAQ e contenuti, utile fin da subito e non dipendente dal Censimento (può iniziare cercando solo su Telegram/Azure/contenuti già esistenti). +### 2.5 Gestione dei consensi e firma della privacy policy in dashboard -#### 5.1.5 Gestione dei consensi e firma della privacy policy in dashboard +Oggi le autorizzazioni privacy vengono raccolte tramite vari form esterni inviati caso per caso: le domande possono cambiare o diventare obsolete nel tempo, e la perdita di un form comporta la perdita della possibilità di dimostrare/recuperare il consenso raccolto con quella versione. -**Stato: mancante.** Oggi le autorizzazioni privacy vengono raccolte tramite vari form esterni inviati caso per caso. Questo espone a un rischio concreto: le domande dei form possono cambiare o diventare obsolete nel tempo, e la perdita o l'abbandono di un form significa perdere anche la possibilità di dimostrare/recuperare il consenso raccolto con quella versione. +- La firma della privacy policy (e di altre informative) avviene **dentro il flusso della dashboard** (iscrizione socio, §3.1; onboarding/censimento admin, §8), non più solo tramite form esterni scollegati. +- Ogni consenso è legato a una **versione specifica del testo firmato**, con data e revoca tracciabili: un cambiamento futuro del testo non invalida né sovrascrive lo storico dei consensi già raccolti. +- La firma passa per l'audit unificato (§2.2). +- Richiede l'Identity Provider (§2.6) per autenticare con certezza chi sta firmando. -Requisiti minimi: -- La firma della privacy policy (e di eventuali altre informative) avviene **dentro il flusso della dashboard** (iscrizione socio, §5.2.2; onboarding/censimento admin, §5.7), non più solo tramite form esterni scollegati. -- Ogni consenso registrato è legato a una **versione specifica del testo firmato**, con data e revoca tracciabili nel tempo (campo "Consensi" di §5.2.1/§5.2.3): un cambiamento futuro del testo non invalida né sovrascrive lo storico dei consensi già raccolti. -- L'evento di firma passa per l'audit unificato (§5.1.2). -- Richiede l'Identity Provider (§5.1.6) per autenticare con certezza chi sta firmando prima di associare il consenso alla persona corretta. +### 2.6 Identity Provider PoliNetwork -#### 5.1.6 Identity Provider PoliNetwork +Identity/authentication provider proprio di PoliNetwork, distinto dal login attuale, come punto di ingresso unico per i flussi self-service: -**Stato: mancante — nuovo requisito del Team IT.** Il Team IT ha richiesto esplicitamente di realizzare un **identity/authentication provider** proprio di PoliNetwork, distinto dal semplice login attuale (email OTP/passkey su Better Auth, §1.2), da usare come punto di ingresso unico per i flussi self-service rivolti a persone interne (ed eventualmente esterne): - -- autenticazione preventiva obbligatoria prima di qualunque flusso di censimento/onboarding (§5.7), firma documenti (§5.1.5) o consultazione delle proprie statistiche/riferimenti (es. Capo Admin di riferimento); -- base per assegnare permessi differenziati "in base a cosa la persona fa/è" all'interno di PoliNetwork (ogni persona ha comunque un livello minimo di accesso alle proprie informazioni); -- precondizione per un futuro accesso esterno multi-tenant (associazioni partner, §6.1), oggi non supportato dal modello di autenticazione attuale. - -Il rapporto tra questo nuovo Identity Provider e l'attuale Better Auth (sostituzione, estensione, o livello applicativo sopra le identità Telegram/Azure esistenti) resta una decisione architetturale da prendere a parte (vedi Decisioni aperte, §11): questo PRD ne registra il requisito, non la soluzione tecnica. +- autenticazione preventiva obbligatoria prima di qualunque flusso di censimento/onboarding (§8), firma documenti (§2.5) o consultazione delle proprie statistiche/riferimenti (es. Capo Admin di riferimento); +- base per assegnare permessi differenziati in base a cosa la persona fa/è in PoliNetwork — ogni persona ha comunque un livello minimo di accesso alle proprie informazioni; +- precondizione per un futuro accesso esterno multi-tenant (associazioni partner, §12). --- -### 5.2 Anagrafica Soci e Censimento Admin/Team (P1) +## 3. Anagrafica Soci e Censimento Admin/Team -**Stato: mancante.** È il gap più importante identificato: oggi non esiste un'entità "persona" canonica. Telegram, Azure e Better Auth rappresentano la stessa persona con tre identità scollegate. +Due registri distinti, coerenti con l'indipendenza delle categorie di §1.2: -**Correzione rispetto a una bozza precedente che parlava genericamente di "censimento soci"**: si tratta in realtà di due cose distinte, coerenti con l'indipendenza delle categorie di §3.2: +- **Anagrafica Soci**: registro dei **soci attivi e paganti**, con **storico** dei soci passati. Per un socio l'azione ricorrente è il **rinnovo della quota associativa** (§6), non una rilevazione periodica di interesse. +- **Censimento Admin/Team**: rilevazione rivolta ad **admin e membri dei team**, il cui scopo è **rinnovare l'interesse/la disponibilità** a continuare il proprio ruolo — non una quota. Si integra con l'Onboarding (§8). -- **Anagrafica Soci**: un registro dei **soci attivi e paganti**, con **storico** dei soci passati. Per un socio l'azione ricorrente è il **rinnovo della quota associativa** (§5.5), non una rilevazione periodica di interesse. -- **Censimento Admin/Team**: una rilevazione rivolta ad **admin e membri dei team**, il cui scopo è **rinnovare l'interesse/la disponibilità** a continuare il proprio ruolo organizzativo — non una quota. Si integra con l'Onboarding (§5.7). +Una persona può comparire in entrambi, in uno solo, o in nessuno dei due. -Una persona può comparire in entrambi, in uno solo, o in nessuno dei due (§3.2). - -#### 5.2.1 Anagrafica Soci — campi MVP +### 3.1 Anagrafica Soci — campi | Blocco | Campi | Note | |---|---|---| | Identità | nome, cognome, email, telefono (opzionale) | | -| Identificativo | ID interno, numero associativo univoco | **Deciso**: il numero associativo diventa proprietà di questo nuovo registro (database PoliNetwork); Azure lo referenzia se presente, non è più l'unica fonte (§11) | +| Identificativo | ID interno, numero associativo univoco | proprietà di questo registro (database PoliNetwork); Azure lo referenzia se presente | | Stato | attivo pagante, sospeso, scaduto, ex socio | | -| Iscrizione | data ingresso, anno associativo (**deciso: iscrizione annuale**, §11), data scadenza, stato rinnovo | | -| Profilo associativo | corso di studi, anno di corso, sede, competenze/interessi (opzionali) | necessario anche per §5.6 | -| Consensi | consenso privacy policy, fonte, data, versione firmata, revoca | firma diretta in dashboard, vedi §5.1.5 | +| Iscrizione | data ingresso, anno associativo (iscrizione annuale), data scadenza, stato rinnovo | | +| Profilo associativo | corso di studi, anno di corso, sede, competenze/interessi (opzionali) | | +| Consensi | consenso privacy policy, fonte, data, versione firmata, revoca | firma diretta in dashboard, §2.5 | -Alcuni campi sono obbligatori e altri opzionali (**deciso in linea di principio**; l'elenco puntuale, incluso se serva il codice fiscale, resta da definire — §11). Lettura: HR può leggere l'Anagrafica Soci; il dettaglio dei permessi granulari campo per campo resta da definire con calma (§11). +Alcuni campi sono obbligatori, altri opzionali (l'elenco puntuale, incluso se serva il codice fiscale, resta da definire). HR può leggere l'Anagrafica Soci; il dettaglio dei permessi granulari campo per campo resta da definire. -Vincoli: numero associativo univoco; storicizzazione degli stati (non sovrascrittura: i soci scaduti/ex soci restano nello storico, non vengono rimossi); nessuna cancellazione bulk senza anteprima e conferma; ogni lettura/scrittura sensibile passa per l'audit di §5.1.2. +Vincoli: numero associativo univoco; storicizzazione degli stati (non sovrascrittura: i soci scaduti/ex soci restano nello storico); nessuna cancellazione bulk senza anteprima e conferma; ogni lettura/scrittura sensibile passa per l'audit (§2.2). -#### 5.2.2 Flusso MVP — Anagrafica Soci +Flusso: richiesta/iscrizione → verifica dati → deduplica → firma privacy policy → approvazione → numero socio → collegamento opzionale a Telegram/Azure → rinnovo annuale della quota (§6) → storico. -``` -Richiesta/iscrizione → verifica dati → deduplica → firma privacy policy (§5.1.5) → approvazione → numero socio - → collegamento opzionale a Telegram/Azure → rinnovo annuale della quota (§5.5) → storico -``` - -#### 5.2.3 Censimento Admin/Team — campi e flusso MVP +### 3.2 Censimento Admin/Team — campi -Rivolto a chi ha un ruolo organizzativo (Admin, Capo Admin, Direttivo, membro di team), indipendentemente dall'essere anche Socio (§3.2). +Rivolto a chi ha un ruolo organizzativo (Admin, Capo Admin, Direttivo, membro di team), indipendentemente dall'essere anche Socio. | Blocco | Campi | Note | |---|---|---| | Identità | nome, cognome, email, telefono | | -| Relazioni | ruolo organizzativo (§3.3), team (§5.6), Capo Admin/responsabile di riferimento | | +| Relazioni | ruolo organizzativo (§1.3), team (§7), Capo Admin/responsabile di riferimento | | | Integrazioni | Telegram ID/username, Azure user ID, ultimo sync | collega senza duplicare | | Rinnovo interesse | data ultima conferma, prossima scadenza conferma, esito | sostituisce il concetto di "quota" per questa popolazione | -| Consensi | consenso privacy policy, fonte, data, versione firmata | vedi §5.1.5 | +| Consensi | consenso privacy policy, fonte, data, versione firmata | §2.5 | -Flusso: rilevazione periodica (periodicità da definire, es. legata all'anno accademico — §11) → conferma interesse/disponibilità tramite il flusso automatizzato di Onboarding/Censimento in dashboard (§5.7) → aggiornamento stato → storico. +Flusso: rilevazione periodica (periodicità da definire, es. legata all'anno accademico) → conferma interesse/disponibilità tramite il flusso di Onboarding/Censimento in dashboard (§8) → aggiornamento stato → storico. -#### 5.2.4 Permessi +### 3.3 Permessi -- Creazione/modifica (Anagrafica Soci e Censimento Admin/Team): ruoli con `members.write` (Direttivo/Owner/President inizialmente). -- Lettura: `members.read`, assegnabile anche a HR **in sola lettura** (coerente con il pattern già in uso per HR sul resto della dashboard); quali campi restino mascherati anche per HR va deciso con calma (§11). -- Un operatore deve poter creare un socio o un record del Censimento Admin/Team **senza** dover prima creare un account Azure: oggi non è possibile, perché il numero associativo esiste solo dentro Azure. +Creazione/modifica: ruoli con `members.write` (Direttivo/Owner/President inizialmente). Lettura: `members.read`, assegnabile anche a HR in sola lettura. Un operatore può creare un socio o un record del Censimento Admin/Team senza dover prima creare un account Azure. --- -### 5.3 Governance e Direttivo — ⚪ Obsoleto - -**Stato: dichiarato obsoleto dal Team IT.** Questa sezione (pagina "Direttivo" dedicata, in sola lettura, con eventuale storico incarichi) **non verrà realizzata come area a sé stante**. I dati utili che avrebbe dovuto mostrare — composizione del Direttivo, ruolo organizzativo, incarico — sono coperti dal Censimento Admin/Team (§5.2.3) e dalla gerarchia ruoli (§3.3), che restano la fonte di riferimento per queste informazioni. +## 4. Governance e Direttivo -`tg.permissions.getDirettivo` (composizione del Direttivo con `isPresident`) resta comunque una capacità di backend già pronta e riusabile come sorgente dati per il Censimento Admin/Team, non serve più però una pagina dedicata separata. +Non verrà realizzata come area dedicata separata. La composizione del Direttivo, il ruolo organizzativo e l'incarico sono coperti dal Censimento Admin/Team (§3.2) e dalla gerarchia ruoli (§1.3). --- -### 5.4 Dashboard Admin e Capo Admin (dal vecchio PRD §3, P1) - -**Stato: mancante**, sia come dato che come UI e come permesso (§3.3, §1.3). - -Requisiti (adattati dal vecchio PRD, subordinati al Censimento): +## 5. Dashboard Admin e Capo Admin - Vista Capo Admin: elenco degli admin del proprio corso di studi con nome, cognome, anno di corso, data di ingresso, flag rappresentante, altre associazioni di appartenenza, telefono, username/contatto Telegram, link rapido WhatsApp/Telegram. - Filtri: nome/cognome, anno, rappresentanza, altre associazioni. - Sezione link ai gruppi Telegram di competenza del Capo Admin. -- Permessi: il Capo Admin deve vedere **solo** i dati e i gruppi del proprio ambito — richiede lo scoping descritto in §5.1.1, non disponibile con il modello attuale a ruoli globali. - -**Deciso**: una persona admin appartiene a **un solo corso di studi** come dato anagrafico personale, ma può essere **admin/Capo Admin con scope su gruppi di corsi diversi** contemporaneamente (§11) — il "corso di appartenenza" personale e lo "scope di responsabilità" da admin sono due campi distinti, non lo stesso valore. Il modello dati deve quindi separare il corso personale del Censimento Admin/Team (§5.2.3) dallo/dagli scope assegnati come Capo Admin. +- Permessi: il Capo Admin vede **solo** i dati e i gruppi del proprio ambito (scoping, §2.1). -**Precondizione bloccante**: senza il Censimento Admin/Team (corso di studi, data di ingresso, rappresentanza) e senza l'estensione dei permessi per dare accesso scoped a chi ha solo il ruolo `admin`, questa funzionalità non è costruibile nella forma descritta dal vecchio PRD. +Il modello dati separa il corso personale (Censimento Admin/Team, §3.2) dallo/dagli scope assegnati come Capo Admin (§1.3). --- -### 5.5 Gestione Soci e Rinnovi (dal vecchio PRD §4, P1) +## 6. Gestione Soci e Rinnovi -**Stato: mancante**, dipende interamente dall'Anagrafica Soci (§5.2). +Il pagamento della quota resta un **bonifico bancario fuori dashboard**; il flusso di verifica del pagamento è in-dashboard: -**Correzione rispetto alla bozza precedente**: il pagamento della quota resta un **bonifico bancario fuori dashboard** (non si integra un gateway di pagamento in questa fase, §10), ma il **flusso di verifica del pagamento diventa in-dashboard**: - -- Il socio può **caricare la ricevuta del bonifico in dashboard**; il caricamento avvia una richiesta di approvazione. -- Il Direttivo/ruolo autorizzato approva la ricevuta caricata, oppure segna il rinnovo come effettuato **manualmente** se la ricevuta non viene caricata (es. verifica diretta in banca). -- **Ricevuta automatizzata**: quando un rinnovo viene approvato, la dashboard genera e invia automaticamente la ricevuta al socio (nuovo requisito rispetto alla bozza precedente). -- Per i rinnovi **del Direttivo verso l'associazione stessa** (quota versata dai membri del Direttivo), la ricevuta viene generata/automatizzata allo stesso modo dalla dashboard; quando è richiesta una firma, il flusso notifica il **Presidente**, che deve firmarla. -- Rinnovo automatico via email poco prima della scadenza: richiede un motore di invio email nel backend condiviso (non presente in questo repository) e la data di scadenza dell'Anagrafica Soci. +- Il socio può caricare la ricevuta del bonifico in dashboard; il caricamento avvia una richiesta di approvazione. +- Il Direttivo/ruolo autorizzato approva la ricevuta caricata, oppure segna il rinnovo come effettuato manualmente se la ricevuta non viene caricata. +- **Ricevuta automatizzata**: quando un rinnovo viene approvato, la dashboard genera e invia automaticamente la ricevuta al socio. +- Per i rinnovi del Direttivo verso l'associazione stessa, la ricevuta viene generata/automatizzata allo stesso modo; quando è richiesta una firma, il flusso notifica il Presidente, che deve firmarla. +- Reminder via email poco prima della scadenza. - Vista Direttivo sullo stato dei soci: da verificare, ricevuta caricata in attesa di approvazione, pagamento effettuato, pagamento non effettuato. -- Azioni: "Approva ricevuta"/"Segna come pagato" (aggiorna stato + genera ricevuta + email di conferma), "Invia reminder" (nuova email di promemoria). -- Storico minimo delle azioni (chi ha approvato/segnato pagato, quando è stato inviato un reminder, ricevute generate) — si appoggia all'audit unificato di §5.1.2. -- Resta da decidere se il permesso di "segnare come pagato"/approvare ricevute sia riservato al solo Direttivo o esteso a un futuro ruolo Finance dedicato (§11). +- Azioni: "Approva ricevuta"/"Segna come pagato" (aggiorna stato + genera ricevuta + email di conferma), "Invia reminder". +- Storico delle azioni (chi ha approvato/segnato pagato, reminder inviati, ricevute generate), tracciato nell'audit (§2.2). +- Resta da decidere se il permesso di segnare come pagato/approvare ricevute sia riservato al solo Direttivo o esteso a un futuro ruolo Finance dedicato. --- -### 5.6 Aree Team interni (dal vecchio PRD §2, P2) - -**Stato: mancante come dato**, ma la navigazione attuale (`dashboardNavigation` in `src/components/dashboard-navigation.ts`) è già organizzata a categorie modulari (Telegram / Azure / Web), quindi si presta ad accogliere nuove categorie (es. "Team IT", "Team HR", ...) senza ristrutturazioni. - -Per questa fase, l'obiettivo minimo è **struttura, ruoli e separazione degli accessi**, non le funzionalità specifiche di ciascun team (che il vecchio PRD stesso rimanda a una definizione successiva con i responsabili): +## 7. Aree Team interni -- ogni team come entità del Censimento Admin/Team (§5.2.3, blocco "Relazioni"); -- pagina/area indipendente per team con permesso dedicato (si appoggia a §5.1.1); -- nessuna funzionalità specifica di team implementata in questa fase. +Ogni team (IT, Design & Social, International, HR, Events & Partnerships, ...) è un'entità del Censimento Admin/Team (§3.2, blocco "Relazioni"), con pagina/area indipendente e permesso dedicato (§2.1). Obiettivo iniziale: struttura, ruoli e separazione degli accessi, non le funzionalità specifiche di ciascun team. --- -### 5.7 Onboarding e Censimento Admin — flusso self-service in dashboard (dal vecchio PRD §6, P2) +## 8. Onboarding e Censimento Admin — flusso self-service in dashboard -**Stato: mancante.** Il vecchio PRD stesso richiede di ridisegnare il processo con HR e Team IT prima di digitalizzarlo; il dettaglio del processo (candidatura, colloquio, criteri) **resta da definire bene** (§11). Questo PRD ne fissa però una direzione precisa, indicata esplicitamente dal Team IT: +Sia il censimento di nuovi candidati admin, sia il censimento periodico di admin già attivi, avvengono tramite un **flusso automatizzato della dashboard**, attivabile tramite un link o una mail inviata alla persona — non più tramite Telegram e scambio di messaggi manuale. -**Cambio di canale**: sia il censimento di nuovi candidati admin, sia il censimento periodico di admin già attivi, non passano più per Telegram e scambio di messaggi manuale, ma per un **flusso automatizzato della dashboard**, attivabile tramite un link o una mail inviata alla persona. +- Autenticazione preventiva obbligatoria sull'Identity Provider PoliNetwork (§2.6) prima di poter proseguire nel flusso — identifica la persona e determina il tipo di candidatura/censimento applicabile. +- Una volta autenticato, l'utente accede a un'area personale dove può: firmare i documenti richiesti (§2.5), consultare le proprie statistiche, vedere il proprio Capo Admin di riferimento. +- Permessi differenziati per ruolo: ogni membro di PoliNetwork ha un livello di accesso diverso in base a cosa fa/è, ma tutti hanno accesso a qualcosa nella propria area. +- Richieste che risalgono la gerarchia: un admin può presentare dalla propria area la richiesta di diventare admin di un determinato gruppo, e la richiesta arriva al proprio Capo Admin di riferimento per l'approvazione. -Requisiti minimi: -- **Autenticazione preventiva obbligatoria** sull'Identity Provider PoliNetwork (§5.1.6) prima di poter proseguire nel flusso — serve sia a identificare con certezza la persona sia a determinare il tipo di candidatura/censimento applicabile al suo caso. -- Una volta autenticato, l'utente accede a un'area personale dove può: firmare i documenti richiesti (privacy policy e altri, §5.1.5), consultare le proprie statistiche, vedere il proprio **Capo Admin di riferimento** (dato dal Censimento Admin/Team, §5.2.3). -- **Permessi differenziati per ruolo**: ogni membro di PoliNetwork ha un livello di accesso diverso in base a cosa fa/è nell'associazione, ma **tutti hanno accesso a qualcosa** nella propria area — nessun ruolo resta completamente escluso dal proprio spazio personale. -- **Richieste che risalgono la gerarchia**: ad esempio, un admin può presentare dalla propria area la richiesta di diventare admin di un determinato gruppo, e la richiesta arriva al proprio Capo Admin di riferimento per l'approvazione (pattern di richiesta/approvazione coerente con quello descritto per le associazioni partner, §6.1). - -Ambito minimo suggerito una volta definito il dettaglio del processo: link/mail di attivazione → autenticazione (Identity Provider) → candidatura o conferma censimento periodico → firma documenti → colloquio/approvazione (per i nuovi) → creazione/aggiornamento profilo (Censimento Admin/Team, §5.2.3) → assegnazione corso/ruoli/team → passaggi di ingresso operativo. +Ambito: link/mail di attivazione → autenticazione (Identity Provider) → candidatura o conferma censimento periodico → firma documenti → colloquio/approvazione (per i nuovi) → creazione/aggiornamento profilo (Censimento Admin/Team) → assegnazione corso/ruoli/team → passaggi di ingresso operativo. Il dettaglio del processo (candidatura, colloquio, criteri) resta da definire con HR e Team IT. --- -### 5.8 Email di compleanno (dal vecchio PRD §5, P2) +## 9. Email di compleanno -**Stato: mancante.** Dipende dall'Anagrafica Soci (nessuna entità ha oggi una data di nascita) e da un motore email nel backend condiviso. Riguarda solo i soci e solo l'email, come indicato nel vecchio PRD. +Riguarda solo i soci. Dipende dall'Anagrafica Soci (data di nascita) e da un motore email. --- -### 5.9 FAQ pubbliche (P1, basso sforzo) +## 10. FAQ pubbliche -**Stato: backend pronto, UI assente.** `web.faqs.*` espone già categorie e CRUD bilingue completo (§1.5). È il rapporto valore/sforzo migliore di tutto il documento: aggiungere `Web → FAQs` con categorie, domanda/risposta IT/EN, ricerca, riordino drag&drop (pattern già usato in `Web Projects`), stato bozza/pubblicata. +Categorie e CRUD FAQ bilingue IT/EN, ricerca, riordino drag&drop, stato bozza/pubblicata. --- -### 5.10 Miglioramenti alle aree esistenti (P2) +## 11. Miglioramenti alle aree esistenti -- **Telegram grants**: storico dei grant terminati/interrotti (richiede un endpoint backend dedicato: oggi esiste solo `getOngoing`/`getScheduled`); reminder sulle scadenze imminenti. +- **Telegram grants**: storico dei grant terminati/interrotti; reminder sulle scadenze imminenti. - **Telegram groups**: creazione/import di gruppi dalla dashboard, indicatori di salute (gruppo senza owner, invito rotto), statistiche. -- **Azure**: gestione licenze dalla UI (richiede estensione del backend/Graph API, oggi non esposta); access review periodico sui gruppi. +- **Azure**: gestione licenze dalla UI; access review periodico sui gruppi. - **Guide**: workflow bozza/pubblicazione, anteprima PDF, storico versioni invece di sola sostituzione. --- -## 6. Feature secondarie — aree per soggetti esterni - -Per il criterio dichiarato in §0 e §2.1, queste aree sono **declassate in priorità** rispetto al vecchio PRD, pur restando le funzionalità di business più corpose descritte nel documento originale. - -### 6.1 Area Associazioni Partner (dal vecchio PRD §1 — lì priorità massima) - -**Stato: mancante interamente.** Riguarda un pubblico esterno (le associazioni partner) e presuppone un **modello di autenticazione multi-tenant** che oggi non esiste: l'unico meccanismo di accesso attuale presume un singolo tipo di utente (un collaboratore interno con ruolo Telegram). Il dettaglio di business di quest'area è già definito nei documenti dell'associazione; qui si registra solo quanto rilevante per la dashboard, includendo, secondo il vecchio PRD e le precisazioni del Team IT: - -- accesso e gestione account per decine di associazioni. **Deciso**: si può creare l'account a **uno o più referenti** della stessa associazione fin dal MVP, e i referenti possono **nominare un successore trasferendo l'ownership** del proprio account (es. passaggio di consegne interno all'associazione partner); -- richieste di pubblicazione nei gruppi Telegram: **deciso**, le associazioni presentano la richiesta dalla propria pagina/area e PoliNetwork approva. Le richieste possono riguardare **più gruppi contemporaneamente**; la dashboard mostra già l'elenco completo dei gruppi tra cui scegliere, quindi non serve un nuovo modulo di selezione gruppi. Resta da chiarire se serva anche l'integrazione WhatsApp menzionata nel vecchio PRD (§11), oggi non integrata in nessuna parte del sistema; -- gestione della pagina pubblica dell'associazione con flusso di richiesta/approvazione: **deciso**, sostituisce l'attuale CRUD diretto di PoliNetwork su `Web Associations` — è un cambio di modello, non una semplice estensione; -- eventuale sistema a crediti: logica ancora non definita, resta aperta (§11); -- eventi delle associazioni / "PoliTamTam" (§6.2). - -Questo PRD non ne nega il valore di business, ma lo colloca dopo le fondamenta interne (§5), perché richiede l'Identity Provider PoliNetwork (§5.1.6) per l'accesso esterno multi-tenant, che è più sicuro introdurre dopo aver stabilizzato RBAC, audit e Anagrafica Soci/Censimento. - -### 6.2 Eventi delle associazioni — PoliTamTam (dal vecchio PRD §1.4) +## 12. Area Associazioni Partner -**Stato: mancante.** **Deciso**: gli eventi vengono inseriti dalle associazioni partner **dalla propria pagina/area** (dipende quindi dall'accesso esterno di §6.1); PoliNetwork può inoltre aggiungere propri eventi, o eventualmente eventi per conto di altre associazioni. In nessun caso la pubblicazione è diretta: **ogni evento richiede approvazione** prima di comparire pubblicamente, sullo stesso pattern di richiesta/approvazione di §6.1. +- Accesso e gestione account per decine di associazioni: si può creare l'account a **uno o più referenti** della stessa associazione fin dal MVP, e i referenti possono **nominare un successore trasferendo l'ownership** del proprio account. +- Richieste di pubblicazione nei gruppi Telegram: le associazioni presentano la richiesta dalla propria pagina/area e PoliNetwork approva. Le richieste possono riguardare più gruppi contemporaneamente; la dashboard mostra già l'elenco completo dei gruppi tra cui scegliere. Resta da chiarire se serva anche l'integrazione WhatsApp. +- Gestione della pagina pubblica dell'associazione con flusso di richiesta/approvazione, al posto dell'attuale CRUD diretto di PoliNetwork. +- Eventuale sistema a crediti: logica ancora non definita. +- Eventi delle associazioni / "PoliTamTam" (§13). -### 6.3 Area Aziende (dal vecchio PRD §7) +Richiede l'Identity Provider PoliNetwork (§2.6) per l'accesso esterno multi-tenant. -**Stato: mancante.** Da progettare in dettaglio prima dello sviluppo, come indicato anche nel vecchio PRD. Priorità bassa in questo documento. - -### 6.4 Area proprietari di casa / Bacheca casa e coinquilini (dal vecchio PRD §8-9) - -**Stato: mancante.** Riguarda esclusivamente soggetti esterni (proprietari, cercatori di stanza). Priorità più bassa dell'intero documento. +--- -### 6.5 Newsletter (dal vecchio PRD §10) +## 13. Eventi delle associazioni — PoliTamTam -**Stato: mancante.** Il vecchio PRD la marca già come non bloccante. Dipende dall'Anagrafica Soci (segmentazione destinatari) ed eventualmente da §6.2 (eventi come fonte di contenuti). +Le associazioni partner inseriscono gli eventi dalla propria pagina/area; PoliNetwork può inoltre aggiungere propri eventi, o eventualmente eventi per conto di altre associazioni. Ogni evento richiede approvazione prima di comparire pubblicamente — nessuna pubblicazione diretta. --- -## 7. Vincoli trasversali +## 14. Area Aziende -- **Nessuna azione distruttiva su più righe** senza anteprima e conferma esplicita (vincolo permanente, `AGENTS.md`). -- `AGENT_MODE` resta esclusivo dell'ambiente di sviluppo locale; ogni modifica a codice di autenticazione/redirect va verificata anche con `AGENT_MODE=false`. -- **Minimizzazione dati**: ogni campo del Censimento deve avere uno scopo dichiarato; dati sensibili (es. codice fiscale) solo se realmente necessari per il tesseramento. -- **Audit prima di esporre dati personali** a più ruoli (§5.1.2 è precondizione di §5.2, §5.4, §5.5). -- **Query lato server e paginazione reale**: oggi tutte le liste caricano `getAll` e filtrano nel browser (`users-page.tsx`, `members-page.tsx`, ecc.). Accettabile ai volumi attuali; da rivedere non appena il Censimento supera qualche centinaio di record. -- **Lingua**: i contenuti pubblici (associazioni, progetti, FAQ) sono già bilingue IT/EN nel backend; l'interfaccia amministrativa è oggi interamente in inglese. **Deciso**: l'interfaccia amministrativa diventerà **bilingue IT/EN con preferenza impostabile per singolo utente** (§11) — le nuove pagine con testo lungo (Anagrafica Soci, Censimento Admin/Team, Rinnovi) vanno progettate da subito con questo vincolo. +Da progettare in dettaglio prima dello sviluppo. --- -## 8. Roadmap proposta +## 15. Area proprietari di casa / Bacheca casa e coinquilini -| Fase | Contenuto | Obiettivo | -|---|---|---| -| **0 — Fondamenta** | RBAC per capacità (§5.1.1), audit unificato (§5.1.2), ricerca globale (§5.1.4), Identity Provider PoliNetwork (§5.1.6), consensi/firma privacy in dashboard (§5.1.5) | Base sicura, osservabile e autenticata per esporre dati personali e far firmare documenti in fase 1 | -| **1 — Anagrafica e censimento** | Anagrafica Soci MVP (§5.2.1-2), Censimento Admin/Team MVP (§5.2.3), FAQ (§5.9) — nota: la governance/Direttivo dedicata (§5.3) è **obsoleta** e non rientra più in questa fase | Registro soci e censimento admin/team utilizzabili, primo valore rapido a basso sforzo | -| **2 — Gerarchia e rinnovi** | Dashboard Admin/Capo Admin (§5.4), Gestione Soci e Rinnovi con ricevute in dashboard (§5.5), home come command center (§5.1.3) | Gestione del ciclo di vita di admin e soci | -| **3 — Team e onboarding** | Aree Team (§5.6), Onboarding e Censimento Admin self-service (§5.7, dopo riprogettazione con HR), email di compleanno (§5.8) | Copertura dei processi interni residui | -| **4 — Aree esistenti** | Miglioramenti Telegram/Azure (§5.10) | Colmare i gap sulle integrazioni già in produzione | -| **5 — Aree esterne** | Associazioni Partner multi-referente (§6.1), PoliTamTam (§6.2) | Prima area rivolta a soggetti esterni, dopo le fondamenta interne e l'Identity Provider | -| **6 — Espansione** | Aziende, Casa, Newsletter (§6.3-6.5) | Funzionalità secondarie, a valutazione | +Riguarda esclusivamente soggetti esterni (proprietari, cercatori di stanza). --- -## 9. Criteri di accettazione (MVP Anagrafica Soci e Censimento Admin/Team, come esempio di riferimento) - -Ripresi e confermati perché indipendenti da qualunque decisione aperta: +## 16. Newsletter -- Un operatore può creare un socio senza dover prima creare un account Azure. -- La scheda del socio/admin mostra chiaramente identità locale, Telegram e Azure e segnala i collegamenti mancanti. -- Nessuna scrittura in un'importazione massiva prima della conferma di un'anteprima. -- Un ruolo HR read-only può consultare solo ciò che il suo permesso consente e non vede pulsanti di scrittura. -- Ogni cambio di stato, numero associativo o identità esterna è rintracciabile nell'audit. -- Nessuna cancellazione massiva senza conferma esplicita e riepilogo delle righe coinvolte. -- Un socio può caricare la ricevuta di un bonifico in dashboard e vederne lo stato di approvazione; se non la carica, il rinnovo può comunque essere segnato manualmente da chi ha il permesso. -- Un consenso privacy firmato in dashboard resta associato alla versione del testo firmata al momento della firma, anche se il testo cambia in seguito. -- Nessun flusso di censimento/onboarding self-service procede senza autenticazione riuscita sull'Identity Provider PoliNetwork. +Dipende dall'Anagrafica Soci (segmentazione destinatari) ed eventualmente dagli eventi (§13) come fonte di contenuti. --- -## 10. Cosa NON fa parte di questo PRD +## 17. Vincoli -- Non ridefinisce lo statuto, gli organi sociali o le regole di voto dell'associazione: assume che la struttura Owner/Presidente/Direttivo esistente sui ruoli Telegram sia quella corretta finché non diversamente indicato. -- Non decide se e come integrare un gateway di pagamento (Stripe, altro): il pagamento resta un bonifico bancario **eseguito fuori dashboard**. È invece in scope la **verifica** del pagamento in dashboard (upload ricevuta, approvazione, ricevuta automatizzata — §5.5): non è più un rinvio integrale come nella bozza precedente, ma resta comunque escluso qualunque flusso di incasso/gateway dentro l'applicazione. -- Non propone una contabilità completa (fatture, bilanci): per pagamenti e documenti sensibili resta preferibile integrare servizi specializzati. +- Nessuna azione distruttiva su più righe senza anteprima e conferma esplicita. +- Minimizzazione dei dati: ogni campo su soci/admin ha uno scopo dichiarato, un responsabile e un'ipotesi di retention; dati sensibili (es. codice fiscale) solo se realmente necessari. +- Audit prima di esporre dati personali a più ruoli. +- Interfaccia amministrativa bilingue IT/EN con preferenza impostabile per singolo utente. --- -## 11. Decisioni aperte +## 18. Fuori scope -Raggruppate per paragrafo di riferimento. Nessuna ipotesi organizzativa è stata inventata: dove il vecchio PRD o il codice non permettevano di dedurre una risposta, la domanda è riportata qui invece di essere decisa autonomamente. +- Non ridefinisce lo statuto, gli organi sociali o le regole di voto dell'associazione. +- Non decide se e come integrare un gateway di pagamento (Stripe, altro): il pagamento resta un bonifico bancario eseguito fuori dashboard. È invece in scope la verifica del pagamento in dashboard (upload ricevuta, approvazione, ricevuta automatizzata, §6). +- Non propone una contabilità completa (fatture, bilanci). -**§3 — Ruoli e gerarchie** -1. Il ruolo "Capo Admin" va modellato come nuovo ruolo Telegram/backend, o come attributo applicativo (scope) sopra il ruolo `admin` esistente, gestito solo lato dashboard? — **Ancora da decidere**, risposta esplicita del Team IT: "non lo so, da decidere". -2. Chi assegna e revoca il ruolo di Capo Admin, e con quale periodicità (es. legato all'anno accademico)? — **Deciso in parte**: il **Direttivo** assegna e revoca il ruolo. La periodicità resta da definire. -3. Il ruolo `admin` "semplice" deve ottenere accesso alla dashboard (anche solo in lettura sul proprio ambito), oppure resta escluso come oggi? — **Deciso**: sì, l'admin ottiene accesso con **permessi determinati** dal proprio scope (vedi §3.3, §5.1.1). +--- -**§5.2 — Anagrafica Soci e Censimento Admin/Team** -4. Il numero associativo resta una proprietà di Azure, o diventa proprietà del nuovo registro soci (con Azure che lo referenzia)? — **Deciso**: i dati diventano proprietà del **nostro database** (Anagrafica Soci); Azure lo referenzia se presente. -5. L'iscrizione è annuale, semestrale o senza scadenza? — **Deciso**: **annuale**. -6. Quali dati sono realmente necessari per il tesseramento (es. il codice fiscale è richiesto dal processo associativo reale, o va escluso)? — **Deciso in parte**: alcuni dati saranno obbligatori, altri opzionali. L'elenco puntuale campo per campo (incluso se serva il codice fiscale) resta da definire. -7. Un ruolo HR read-only può leggere tutti i campi del socio, o alcuni campi (es. dati di contatto personali) devono essere mascherati anche per HR? — **Deciso in parte**: HR può leggere l'Anagrafica Soci; i permessi granulari campo per campo vanno pensati con calma, restano da definire nel dettaglio. +## 19. Decisioni aperte -**§5.4 — Dashboard Admin e Capo Admin** -8. Come si definisce "corso di studi" nel sistema (elenco chiuso dei corsi del Politecnico, testo libero, altro)? — **Ancora aperta**, non affrontata. -9. Un admin può appartenere a più corsi/ambiti, o a uno solo? — **Deciso**: una persona admin appartiene a **un solo corso** come dato personale, ma può **essere admin/Capo Admin su gruppi di corsi diversi** come scope di responsabilità (i due concetti sono distinti, vedi §5.4). +**§1 — Ruoli e gerarchie** +1. Il ruolo "Capo Admin" va modellato come nuovo ruolo Telegram/backend, o come attributo applicativo (scope) sopra il ruolo `admin` esistente, gestito solo lato dashboard? — da decidere. +2. Con quale periodicità viene rinnovato il ruolo di Capo Admin (es. legato all'anno accademico)? -**§5.5 — Gestione Soci e Rinnovi** -10. Il pagamento della quota resta interamente manuale (bonifico/altro) fuori dashboard, o si prevede in futuro un'integrazione (es. Stripe)? — **Deciso**: il pagamento resta **bonifico**, eseguito fuori dashboard. In dashboard il socio può però **caricare la ricevuta** per farla approvare, oppure il rinnovo viene segnato **manualmente** se la ricevuta non è caricata. Per i rinnovi del Direttivo verso l'associazione, la ricevuta viene generata/automatizzata dalla dashboard, con firma del Presidente quando richiesta. -11. Chi ha il permesso di "segnare come pagato": solo Direttivo, o anche un ruolo Finance dedicato non ancora esistente? — **Ancora aperta**: il Direttivo approva le ricevute caricate, ma se questo compito debba restare esclusivo del Direttivo o essere esteso a un futuro ruolo Finance non è stato specificato. +**§2 — Fondamenta** +3. Il nuovo Identity Provider PoliNetwork (§2.6) sostituisce integralmente l'attuale autenticazione, o si affianca ad essa come livello applicativo sopra le identità Telegram/Azure esistenti? +4. Il consenso privacy raccolto in dashboard (§2.5) sostituisce integralmente i form esterni oggi in uso, o convive con essi durante una fase di transizione? -**§5.7 — Onboarding e Censimento Admin** -12. Il processo di candidatura/colloquio è già stato ridisegnato con HR e Team IT (come richiesto dal vecchio PRD stesso), o va progettato da zero in questo ciclo? — **Ancora da definire bene** (risposta esplicita del Team IT), ma la direzione del canale è ormai fissata: flusso automatizzato in dashboard con autenticazione preventiva, non più Telegram (§5.7). Restano da definire i dettagli operativi del processo (criteri, colloquio, tempistiche). +**§3 — Anagrafica Soci e Censimento Admin/Team** +5. Quali dati sono realmente necessari per il tesseramento (es. il codice fiscale è richiesto o va escluso)? +6. Un ruolo HR read-only può leggere tutti i campi del socio, o alcuni campi (es. dati di contatto personali) devono essere mascherati anche per HR? +7. Con quale periodicità si svolge il Censimento Admin/Team — es. una volta per anno accademico, o legato a un altro evento? -**§5.1 — Identity Provider PoliNetwork** *(nuovo gruppo)* -20. Il nuovo Identity Provider PoliNetwork (§5.1.6) sostituisce integralmente l'attuale autenticazione Better Auth, o si affianca ad essa come livello applicativo sopra le identità Telegram/Azure/Better Auth esistenti? -21. Il consenso privacy raccolto in dashboard (§5.1.5) sostituisce integralmente i form esterni oggi in uso, o convive con essi durante una fase di transizione? -22. Con quale periodicità si svolge il Censimento Admin/Team (§5.2.3) — es. una volta per anno accademico, o legato a un altro evento? +**§5 — Dashboard Admin e Capo Admin** +8. Come si definisce "corso di studi" nel sistema (elenco chiuso dei corsi del Politecnico, testo libero, altro)? -**§6.1 — Area Associazioni Partner** -13. Un account per associazione, o più referenti per la stessa associazione fin dal MVP? — **Deciso**: si possono creare **uno o più account/referenti** per associazione fin dal MVP, con possibilità di **nominare un successore e trasferire l'ownership** dell'account. -14. Le richieste di pubblicazione riguardano solo Telegram (unico canale oggi integrato) o resta necessaria l'integrazione WhatsApp menzionata nel vecchio PRD? — **Ancora aperta**: da verificare nei documenti di business esterni citati dal Team IT. -15. Il sistema a crediti per le pubblicazioni resta previsto, e con quale logica di ricarica/consumo? — **Ancora aperta**, logica non definita. -16. La gestione della pagina pubblica dell'associazione deve diventare un flusso di richiesta/approvazione (come indicato dal vecchio PRD), sostituendo l'attuale CRUD diretto di PoliNetwork su `Web Associations`? — **Deciso**: sì. Le associazioni richiedono dalla propria pagina/area, PoliNetwork approva; le richieste possono riguardare più gruppi contemporaneamente e la dashboard mostra già l'elenco completo dei gruppi disponibili. +**§6 — Gestione Soci e Rinnovi** +9. Chi ha il permesso di segnare come pagato/approvare ricevute: solo Direttivo, o anche un ruolo Finance dedicato non ancora esistente? -**§6.2 — Eventi / PoliTamTam** -17. Gli eventi sono inseriti direttamente dalle associazioni partner (richiede §6.1) o da PoliNetwork per conto loro (realizzabile prima, sul modello di `Web Projects`)? — **Deciso**: le associazioni inseriscono gli eventi dalla propria pagina; PoliNetwork può aggiungere anche eventi propri o, eventualmente, per conto di altre associazioni. -18. Gli eventi vengono pubblicati immediatamente o richiedono approvazione PoliNetwork? — **Deciso**: richiedono sempre approvazione; nessuna pubblicazione avviene direttamente. +**§8 — Onboarding e Censimento Admin** +10. Il processo di candidatura/colloquio va definito nel dettaglio con HR e Team IT (criteri, colloquio, tempistiche). -**§7 — Lingua dell'interfaccia** -19. L'interfaccia amministrativa deve diventare bilingue con preferenza per utente, o restare in italiano per il team associativo mantenendo IT/EN solo sui contenuti pubblici? — **Deciso**: bilingue, **con preferenza impostabile per singolo utente**. +**§12 — Area Associazioni Partner** +11. Le richieste di pubblicazione riguardano solo Telegram, o resta necessaria anche l'integrazione WhatsApp? +12. Il sistema a crediti per le pubblicazioni resta previsto, e con quale logica di ricarica/consumo?