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.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? 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.