diff --git a/Checklist_Sito_Web.md b/Checklist_Sito_Web.md new file mode 100644 index 0000000..05c2d77 --- /dev/null +++ b/Checklist_Sito_Web.md @@ -0,0 +1,100 @@ +# Checklist lancio sito PoliNetwork + +**Aggiornamento:** 30 ottobre 2026. +Fonte codice: [web main 0e04231](https://github.com/PoliNetworkOrg/web/tree/0e042311a3b21e442b14ebd2d3d769d84cc55762). +[PRD admin](PRD_Admin_Dashboard_PoliNetwork.md), [roadmap](PRD_Classificazione_Feature.md). + +`[x]` codice integrato verificato; `[ ]` lavoro o verifica da completare. Non certifica il deploy né la qualità +dei dati di produzione. Responsabili personali sotto riportati ereditati dalla checklist, da riconfermare. +MVP.md contiene il MVP interno admin: questa è l'unica checklist per il lancio pubblico. + +## Base già integrata + +- [x] Correzioni rapide [web#192](https://github.com/PoliNetworkOrg/web/pull/192): link Appunti nel sito, + contatti progetto ripuliti, Team, immagine Unisciti compressa e link Collabora corretto. +- [x] Sfondo procedurale [web#183](https://github.com/PoliNetworkOrg/web/pull/183): non è più una PR da aggiornare. +- [x] Pagine Su di noi [#188](https://github.com/PoliNetworkOrg/web/pull/188), dettaglio progetto + [#189](https://github.com/PoliNetworkOrg/web/pull/189), Storia [#190](https://github.com/PoliNetworkOrg/web/pull/190) + e Struttura [#186](https://github.com/PoliNetworkOrg/web/pull/186). + L'alternativa [#191](https://github.com/PoliNetworkOrg/web/pull/191) è chiusa senza merge: non scegliere più tra due PR aperte. +- [x] Matricole legge risorse, hub Telegram e FAQ da `web.freshman`; admin #124 permette modifica e riordino + degli slot previsti e scelta FAQ, oltre alla gestione PDF Guida. +- [x] Web #198 rende obbligatorio il token IdP di servizio per tutte le chiamate backend. + +## Raffinamento visuale aperto + +La serie **#199 → #213 è ancora aperta**, impilata: review e merge dal basso, rispettando le basi. +Non segnare le correzioni come concluse perché esistono screenshot nelle PR. + +| PR web | Area e prossimo controllo | +| ------------------------------------------------------ | --------------------------------------------------------- | +| [#199](https://github.com/PoliNetworkOrg/web/pull/199) | Home: proporzioni, card, tipografia | +| [#200](https://github.com/PoliNetworkOrg/web/pull/200) | Storia: gerarchia e timeline | +| [#201](https://github.com/PoliNetworkOrg/web/pull/201) | Su di noi: decidere con designer v1/v2, la PR mantiene v1 | +| [#202](https://github.com/PoliNetworkOrg/web/pull/202) | Struttura: organigramma condiviso con Storia | +| [#203](https://github.com/PoliNetworkOrg/web/pull/203) | Team: sezioni e specializzazioni | +| [#204](https://github.com/PoliNetworkOrg/web/pull/204) | Unisciti: ritmo e sezioni | +| [#205](https://github.com/PoliNetworkOrg/web/pull/205) | Collabora e ritmo condiviso | +| [#206](https://github.com/PoliNetworkOrg/web/pull/206) | Contatti: griglia e layout | +| [#207](https://github.com/PoliNetworkOrg/web/pull/207) | Progetti: card, ricerca e fallback | +| [#208](https://github.com/PoliNetworkOrg/web/pull/208) | Gruppi: risultati e link | +| [#209](https://github.com/PoliNetworkOrg/web/pull/209) | Matricole: layout e CardIcon responsive | +| [#210](https://github.com/PoliNetworkOrg/web/pull/210) | Associazioni: fallback logo e accordion | +| [#211](https://github.com/PoliNetworkOrg/web/pull/211) | FAQ: categoria iniziale non vuota e layout | +| [#212](https://github.com/PoliNetworkOrg/web/pull/212) | Guide: hub e rimozione placeholder lorem | +| [#213](https://github.com/PoliNetworkOrg/web/pull/213) | Guida Matricola: pagina download | + +- [ ] Confrontare [web#179](https://github.com/PoliNetworkOrg/web/pull/179), ancora aperta, con il ritmo condiviso + della serie #199–#213. Risolvere sovrapposizione prima di integrare due sistemi di spaziatura. +- [ ] Dopo lo stack, verificare desktop/mobile, navigazione tastiera e movimento ridotto, inclusi sfondo e accordion. + Nuove animazioni decorative non sono un gate autonomo di lancio. +- [ ] #163 (easter egg) e #145 (gioco CFU), ancora aperte, sono extra e non dipendenze del lancio. + +## Contenuti e gestione admin + +- [ ] **Gruppi:** verificare nomi, piattaforma e anno (es. Informatica WhatsApp 26/27), il generale Telegram assente + dalla ricerca e i link reali. Prima distinguere errore di dati/etichette da errore della ricerca. +- [ ] **Matricole:** aggiornare card senza destinazione e link vecchi. Provare modifica admin → ricaricamento web + senza fallback statico, errori backend e FAQ selezionate. Struttura e titoli restano fissi. +- [ ] **FAQ:** popolare catalogo da gruppi/vecchio sito e definire import da file; riferimento precedente @L3ox64. + Non confondere CRUD admin esistente con import ancora mancante. +- [ ] **Guide:** decidere quali contenuti conservare e migrare. La gestione PDF Matricole non è un CMS generico + delle guide; #212 sistema il sito ma non completa produzione/migrazione dei testi. +- [ ] **Progetti:** rivedere elenco, archiviare contenuti vecchi e aggiungere nuovi progetti tramite le funzioni esistenti. + Verificare riferimenti pubblici a `info@polinetwork.org` invece di contatti personali. +- [ ] **Link progetto per piattaforma:** [backend#72](https://github.com/PoliNetworkOrg/backend/pull/72) ancora aperta; + poi pubblicare i tipi, implementare editor admin e visualizzazione web. La pagina dettaglio già integrata non basta. +- [ ] **Associazioni:** verificare campi richiesti dal vecchio sito (Twitch, più canali Telegram). Richieste di aggiunta, + modifica e approvazione da esterni sono un nuovo workflow, non il CRUD interno attuale. +- [ ] **Storia/Su di noi/Team:** dati direttivi passati, ringraziamenti, numeri coerenti e testi approvati. + #202 condivide l'organigramma nel codice; non dedurre aggiornamento dei dati da quel refactor. +- [ ] **Home:** numeri derivati da dati attivi o contenuti editoriali verificati, senza contatori dimostrativi. +- [ ] **Appunti:** verificare tutti i link alla destinazione attuale; valutare link GitLab. Upload/archivio sul nuovo sito + e dashboard personale sono backlog separati, da definire prima di sviluppo. + +## Documenti e processi esterni + +- [ ] **Design Documenti:** statuto, regolamenti, regole utenti, privacy/cookie e bilanci; valutare donazioni/5x1000. + Riferimento precedente: Simone (designer), incarico da riconfermare. +- [ ] Implementare Documenti dopo il design e collegare il footer alle versioni approvate. +- [ ] Definire referenti, ownership e moderazione di richieste associazioni/progetti; non assegnare ownership + trasferendo account personali. È backlog esterno del PRD, non gate del MVP People. +- [ ] Valutare il Figma della dashboard utente (riferimento precedente Enrico) e il bisogno di login personale. + Il token di servizio del sito non offre già quel login. + +## Verifiche prima del lancio + +- [ ] Inventario URL vecchi e redirect `/it/…`, `/en/…`, graduatorie, eventi; verificare destinazione e codici HTTP. +- [ ] Piano passaggio beta → dominio principale, DNS, certificati e rollback del sito. +- [ ] Google Search Console, sitemap, robots, canonical e anteprime social sui nuovi URL. +- [ ] Italiano coerente; decidere scope e responsabilità dell'eventuale versione inglese. +- [ ] Backend non disponibile: messaggi e retry comprensibili sulle pagine, senza cataloghi finti. +- [ ] Configurare client web, chiave e risorsa `backend:public:read`; senza token il backend rifiuta la richiesta. +- [ ] Allineare tipi e versione distribuita del backend. La vecchia nota README sul pacchetto 1.4.0 non è + prova di un blocco attuale: admin risolve 4.0.0; verificare separatamente il lockfile web. +- [ ] Controllare con i responsabili i contenuti di produzione e gli eventuali dati di prova. + Non eliminare righe in massa durante il controllo. +- [ ] Smoke test pubblico: ricerca gruppi, Appunti, FAQ, Matricole/PDF, progetto e link, contatti e Documenti; + ripetere su telefono e verificare i failure del backend. + +Nessuna casella operativa viene spuntata da questa revisione senza evidenza dell'ambiente di destinazione. diff --git a/IdentityProvider_DataModel.md b/IdentityProvider_DataModel.md new file mode 100644 index 0000000..7d3ebde --- /dev/null +++ b/IdentityProvider_DataModel.md @@ -0,0 +1,112 @@ +# Modello dati e contratti — Auth, backend e admin + +**Versione:** 3.0 · **Aggiornamento:** 30 ottobre 2026. +[Design IdP](IdentityProvider_Design.md), [People](Persone_Volontari_Soci.md), +[RBAC](RBAC_Ruoli_Permessi.md), [fonti/SHA](PRD_Admin_Dashboard_PoliNetwork.md#20-fonti-della-revisione). + +Questo documento distingue lo schema presente dai contratti in lavorazione. Non è una migrazione SQL né +un'autorizzazione a modificare dati. Non creare tabelle usando i nomi delle vecchie proposte. + +## 1. Auth main + +Fonte: `src/db/auth-schema.ts`, `src/db/evidence.ts`, `src/db/rbac.ts` nel repository Auth. + +| Blocco | Responsabilità | +| ---------------------------------------- | --------------------------------------------------------------------------------------- | +| Utente / account / sessione / passkey | Identità login e provider verificati, con vincoli di ownership | +| `identity_evidence` | Evidenze per issuer/subject, ID esterni verificati, Telegram e stati | +| `student_verification_challenge` | Verifica mail Polimi con hash, scadenza, tentativi e cooldown | +| `permission`, `permission_implication` | Chiavi stabili e implicazioni transitive senza cicli | +| `role`, `role_parent`, `role_permission` | Ruoli, ereditarietà e permessi | +| `user_role` | Assegnazioni manuali con attore/data; ruoli gestiti derivati da evidenze/configurazione | +| `rbac_audit_event` | Audit append-only con attore, operazione, target, prima/dopo e data | +| OAuth / snapshot / outbox | Client e risorse, proiezioni accesso e aggiornamenti verso consumer | + +Username/email di contatto non sono chiavi di autorizzazione. Il modello globale non contiene un sistema +`capability_grant` con livelli e scope corso/team: quella proposta non è stata adottata. +Schema Auth main non contiene i binding People della PR #73 né gli utenti preliminari di #75. +Gli override di permessi ereditati sono in Auth#68, ancora aperta: non sono una proprietà verificata di main. + +## 2. Backend e BFF main + +- Il backend richiede token IdP: attore dal token, scope e tipo attore verificati, permessi correnti da snapshot. + `me.access` è la fonte della dashboard. Nessun percorso anonimo o login legacy nella baseline #97. +- I grant correnti sono in `tg_grants` con soggetto IdP del grantor. Non descrivere più una convivenza + operativa `tg_grants_v2`/legacy o chiedere nuovi `admin_id` Telegram per l'audit. +- Contenuti conservano autori `*_by_sub`; i riferimenti storici Telegram non equivalgono all'audit prima/dopo. +- People main espone `persons`, `members`, `fees`, `receipts`, `census`, `linking`, `capo`, `me`, `teams`: + contratto consumato tramite adapter e parsing Zod in admin. È la prima versione, da ridurre e rifare per fasi. +- Admin usa Redis dedicato per token/sessioni e cookie opaco nel browser. Il contesto route non contiene token. +- Microsoft 365: Entra object ID per l'utente, `employeeId` per numero socio, gruppo Soci per appartenenza. + La dashboard non modifica membership dei gruppi; crea il nuovo socio tramite workflow backend fisso. + +La dipendenza admin/lockfile è `@polinetwork/backend` 4.0.0, con `web.freshman` presente. Versione del pacchetto, +versione dell'app backend e contratto realmente distribuito sono evidenze diverse: controllarle separatamente. + +## 3. Cleanup in PR, non ancora main + +[Admin#147](https://github.com/PoliNetworkOrg/admin/pull/147) scollega soci/quote/ricevute/censimento e rimuove +matching, gruppi People e ponte eSign. [Backend#104](https://github.com/PoliNetworkOrg/backend/pull/104) +elimina i router e i campi collegati; conserva per ora record e identità People nella forma ridotta. + +La migrazione proposta `0030_people_cleanup.sql` elimina file/ricevute/associazioni richieste e numero socio +People, e svuota i record di test secondo #146. Non è un backfill. Non eseguire la migrazione nell'ambito +di questa revisione. Deploy frontend prima del backend, poi rimozione dei permessi obsoleti Auth#77. + +I mockup admin devono avere dati propri, separati da `people.contract.ts`, senza API o server functions. +La shell deve smettere di caricare i vecchi conteggi. Il contratto di transizione deve tollerare sia il backend +precedente sia quello ripulito fino al completamento dell'ordine di deploy. + +## 4. Fase 1: contratto pianificato + +Fonti: [auth#78](https://github.com/PoliNetworkOrg/auth/issues/78), +[backend#101](https://github.com/PoliNetworkOrg/backend/issues/101), +[#102](https://github.com/PoliNetworkOrg/backend/issues/102), +[#103](https://github.com/PoliNetworkOrg/backend/issues/103). + +### Auth + +- Campo binding del ruolo con tipi `admin`, `capo`, `team::member`, `team::lead` e vincoli. +- Directory interna dei ruoli associati e titolari; senza elenco Soci/utenti Microsoft 365 come fonte People. +- Lettura `GET /api/internal/people-roles`; comandi `POST` con scope interno `idp:people:roles`. +- Comando `{ id, actor, sub, reason, changes }`, idempotente, atomico; `sub` sempre account reale. + Auth risolve i permessi dell'attore e rifiuta binding ambigui, auto-grant e delega insufficiente. +- Nuovo permesso di binding delegabile, nome proposto `idp:people:bind`; non creare un endpoint preliminari. + +Questi contratti sono il target della rielaborazione #73; non considerarli già distribuiti. + +### Backend + +Record relazionali per persone, incarichi, relazione Capo, storico e inviti. Incarichi con stato +`pending`/`sent`/`applied`/`refused`, motivo e autore; account collegato univoco, contatti informativi. +Outbox comandi Auth con revisioni e retry; un record senza account non produce scritture Auth. + +Inviti: hash token, 14 giorni, monouso e revocati al reinvio; nessun vincolo di uguaglianza email account/contatto. +Accettazione per account autenticato anche senza `people:self`; comandi attribuiti agli autori degli incarichi. +Link/unlink manuali con `people:link`; revoca ruoli prima di staccare l'account, cronologia e lista 30 giorni. + +Import CSV: preview errori/duplicati/delega, commit idempotente e inviti opzionali. Nessuna ricerca identità +per matching durante il commit. Esportare i nuovi tipi nel pacchetto prima di aggiornare i consumer. + +### Admin + +Aggiornare adapter/parsing, permessi, fixture, route e test insieme al nuovo contratto. Gestire esplicitamente +pending/rifiuto senza successo ottimistico della concessione. La landing invito vive fuori dal gate dashboard. +I nomi delle nuove procedure e i dettagli wire definitivi vanno fissati nelle PR implementative; il vecchio +`docs/people/contract.md` non deve introdurre endpoint eliminati nel nuovo flusso. + +## 5. Proposte ritirate e modelli da progettare + +- Ritirati: `capability_grant`, utenti preliminari, matching/merge di record, `membership_claim` e claim del socio + mediante codice, join gruppi Telegram come fonte degli incarichi, registro socio People indipendente da Entra. +- Soci fase 2 #144: quote agganciate all'object ID Entra; namespace dedicato, schema annualità/ricevute da disegnare. +- Censimento fase 3 #145: collegato alla fase 1; uscita tramite stesso comando di revoca ruolo Auth. +- Informative, prove di consenso, retention ed export: definire policy prima del nuovo schema. +- Audit unico: backend#90 propone `common_audit_events`/`audit.list`; auth#76 e admin#123 completano il filone. + Non dedurre che l'audit RBAC sia già federato dal solo fatto che entrambe le tabelle esistano. + +## 6. Criteri di compatibilità + +Documentare ordine deploy e differenze wire in ogni PR; nessun silenziamento dei tipi per superare un disallineamento. +Testare righe fuori ambito, token mancanti, delega, revoche, attori, retry, outage e vecchio/nuovo payload nella +transizione. Agent mode usa il fake People; non dimostra schema PostgreSQL, OAuth o consegna dei comandi Auth. diff --git a/IdentityProvider_Design.md b/IdentityProvider_Design.md new file mode 100644 index 0000000..85aad1a --- /dev/null +++ b/IdentityProvider_Design.md @@ -0,0 +1,93 @@ +# Design — Identity Provider e integrazione admin + +**Versione:** 3.0 · **Aggiornamento:** 30 ottobre 2026. +[PRD](PRD_Admin_Dashboard_PoliNetwork.md), [dati e contratti](IdentityProvider_DataModel.md), +[RBAC](RBAC_Ruoli_Permessi.md), [People](Persone_Volontari_Soci.md). +Baseline e SHA dei repository nel PRD §20; distinguere sempre main, PR e provisioning dell'ambiente. + +## 1. Confini già implementati + +Auth è un IdP autonomo, con Better Auth/OAuth provider e Postgres/Drizzle. Admin è un consumer OIDC, +non ospita Better Auth e non condivide cookie con Auth o backend. + +- Login/registrazione Google o Entra PoliNetwork; passkey e collegamenti nell'account IdP. +- Telegram si collega tramite OIDC ufficiale, non con il vecchio codice bot, e non assegna ruoli da solo. +- Verifica studente `@mail.polimi.it` distinta da Telegram, ruolo Socio e Direttivo. +- Socio/Direttivo provengono dai gruppi Entra. La loro presenza non prova pagamento di una quota annuale. +- Directory, ruoli/permessi e applicazioni OAuth sono gestiti nell'IdP; account personale, passkey e sessioni + si gestiscono lì, non nelle vecchie pagine di sicurezza di admin. + +Non serve una nuova implementazione di autenticazione per iniziare People. Il README Auth contiene ancora +introduzioni storiche sul backend provider: per lo stato dei consumer usare il loro codice attuale. + +## 2. Flusso admin BFF + +1. `/auth/login` prepara Authorization Code con PKCE, state e nonce. +2. `/auth/callback` scambia il codice e verifica issuer, firma e nonce dell'ID token. +3. Access/refresh/ID token restano nella sessione Redis dedicata; il browser ha un cookie opaco HttpOnly. +4. `me.access` determina i permessi correnti. La shell riceve dati visualizzabili e permessi, mai token. +5. Le server functions inviano bearer token al backend, che controlla autonomamente scope/attore/permesso. +6. Refresh coordinato e POST `/auth/logout` completano il ciclo; le richieste mutanti controllano l'Origin. + +L'ingresso dashboard ammette `admin:access` oppure `people:self`, che apre solo le proprie viste. +Redis indisponibile dà errore, non fallback a sessioni locali. Registrazione client, chiavi, redirect esatti, +Redis e prova del login nell'ambiente target sono requisiti operativi, non conseguenze del merge. +[Handoff BFF](docs/idp-phase4c-handoff.md). + +## 3. Comunicazione tra servizi: stato aggiornato + +Backend main ha rimosso accesso anonimo, login legacy e campi attore forniti dal chiamante (#97). +Ogni caller presenta il token IdP; gli input non sono una fonte attendibile dell'attore. +Non configurare `LEGACY_ANONYMOUS=allow` come rollback: il percorso non esiste più nella baseline. + +Web main richiede il token di servizio `backend:public:read` in tutte le chiamate (#198). +Questo non implementa login personale dei visitatori. Token personali e servizi hanno policy distinte; +act-as del bot necessita del suo scope. Snapshot/refresh della policy restano responsabilità dei servizi. + +La vecchia RFC resta riferimento architetturale; non usare le sue checklist storiche per dedurre che +anonimo/grant v2/vecchio login siano ancora vie operative. Per bot e altri consumer non riesaminati qui, +verificare il rispettivo main prima di dichiarare conclusi provisioning o cleanup. + +## 4. People fase 1: direzione corrente + +La [roadmap #146](https://github.com/PoliNetworkOrg/admin/issues/146) sostituisce il modello dei preliminari: + +- Persone senza account solo nel backend, mai utenti placeholder Auth. +- Due soli collegamenti: invito monouso accettato dopo login con qualsiasi account, oppure link manuale + con `people:link`. Nessun matching per email, Telegram o nome, nessuna approvazione Master Admin del preliminare. +- Dopo il link Auth è fonte dei ruoli; comandi idempotenti, atomici e attribuiti all'attore autorizzato. +- Binding `admin`, `capo`, `team::member`, `team::lead`, senza `idp:*` anche indiretti. +- Niente autoassegnazioni o deleghe oltre i permessi correnti. Auth verifica, il backend replica le regole + sugli incarichi pending e la UI presenta attesa/applicato/rifiutato con motivo. + +[Auth#73](https://github.com/PoliNetworkOrg/auth/pull/73) è aperta e va rielaborata secondo +[auth#78](https://github.com/PoliNetworkOrg/auth/issues/78), rimuovendo #75 incorporata nel branch. +Nuova review, poi [setup #79](https://github.com/PoliNetworkOrg/auth/issues/79), quindi backend e UI. +I nomi concreti delle tabelle e dei nuovi permessi seguono il contratto rivisto, non questa vecchia proposta. + +## 5. Soci: requisito separato + +[Fase 2 #144](https://github.com/PoliNetworkOrg/admin/issues/144): Entra è fonte dei soci e object ID chiave +per quote/rinnovi; nessuna condivisione di record con People. Ammissione attraverso Azure esistente. +La precedente proposta di registro socio indipendente da Entra con `membership_claim` e codice IdP è ritirata. +Non aggiungere endpoint di claim per realizzare il piano attuale. + +Censimento #145 segue People fase 1; consensi, firma privacy e onboarding HR richiedono ancora design di processo. +Né login né firma PDF generica attestano da soli l'intero processo associativo. + +## 6. MCP e audit + +MCP Auth è in main (PR #72), con il suo controllo `idp:mcp`. MCP admin è separato, ancora in #137: +client pubblico Native con PKCE, callback loopback, `ADMIN_MCP_CLIENT_ID`, deploy e prova reale necessari. +L'attivazione non è stata effettuata da questa revisione; firma CIE sempre con persona/agent locale. + +Audit unificato è un filone aperto auth#76/backend#90/admin#123. L'audit RBAC esiste, ma verificare che le +modifiche Auth siano effettivamente consultabili nel nuovo registro; non dedurre copertura dal solo middleware backend. + +## 7. Prossimi controlli + +- Login/refresh/logout normali con `AGENT_MODE=false`, permessi revocati e Redis indisponibile. +- Consumer con token corretto, anonimo rifiutato e nessun ripiego se il token è invalido. +- Binding e ruoli produzione secondo auth#79; ruoli IT con `idp:*` non bindabili a People. +- Invito accettato da account senza permessi su una pagina fuori dalla shell; nessun auto-grant. +- Unlink con revoca confermata, retry idempotenti, attori e outage; prove backend/Auth reali in staging. diff --git a/MVP.md b/MVP.md new file mode 100644 index 0000000..97ab64f --- /dev/null +++ b/MVP.md @@ -0,0 +1,58 @@ +# MVP interno — prossimo rilascio + +**Aggiornamento:** 30 ottobre 2026 · [PRD](PRD_Admin_Dashboard_PoliNetwork.md) · +[roadmap](PRD_Classificazione_Feature.md) · [lancio sito](Checklist_Sito_Web.md). + +Questo file definisce il prossimo risultato utilizzabile della dashboard. La vecchia copia parziale della +checklist web è sostituita dal rimando sopra, per evitare due elenchi di lancio divergenti. + +## Obiettivo + +Direttivo e Lead gestiscono Group Admin, Capo Admin e team dalla dashboard; gli account collegati ricevono +solo i ruoli Auth autorizzati. Una persona può essere censita prima del login, senza creare utenti fittizi in Auth. +La base è [fase 1 #143](https://github.com/PoliNetworkOrg/admin/issues/143), preceduta dal cleanup #142. + +## Gate di rilascio + +- [ ] **Cleanup frontend:** #147/#138 distribuita; soci, ricevute e censimento mostrano il banner mockup, + dati di esempio separati e azioni disabilitate, senza loader/API. Nessun badge della shell legge procedure rimosse. +- [ ] **Cleanup backend/IdP:** backend#104 dopo dashboard; auth#77 rimuove i permessi obsoleti. + Nessuna migrazione dei record People di test prevista da #146. +- [ ] **Auth:** #78 e setup #79, binding `admin`, `capo`, membri/Lead; nessun ruolo legato con `idp:*`; + nuova review di #73. Catalogo e risorsa del client backend configurati nell'ambiente di destinazione. +- [ ] **Record e incarichi:** backend#101 e admin#139; creazione con nome/cognome, stati attesa/invio/applicato/rifiutato, + motivo Auth leggibile. Una revoca in Auth si riflette nella scheda e nella vista Capo. +- [ ] **Link:** backend#102 e admin#140; invito monouso, reinvio/revoca e link manuale con `people:link`. + Account privo di permessi accetta l'invito fuori dalla shell dashboard; email di login anche diversa. +- [ ] **Unlink:** revoca effettiva dei ruoli in Auth prima dello scollegamento; storico metodo/attore; + collegamenti recenti consultabili per correggere errori. +- [ ] **CSV:** backend#103 e admin#141; template, anteprima errori/duplicati/deleghe, commit esplicito, + retry senza duplicati e inviti opzionali. Nessuna scrittura all'upload. + +## Prove di accettazione + +1. Creare una persona senza account con un incarico consentito: rimane pending solo nel backend. +2. Accettare l'invito con un account nuovo: applicazione con attore originario dell'assegnazione; + se nel frattempo ha perso la delega, mostrare il rifiuto senza dichiarare il ruolo assegnato. +3. Ripetere una consegna del comando: nessuna doppia assegnazione. Simulare indisponibilità Auth: + mostrare l'attesa e non usare dati obsoleti oltre la policy backend. +4. Un Lead gestisce solo i membri del proprio team, non promuove Lead e non assegna ruoli a sé stesso. + Un Capo legge soltanto i propri admin; accessi diretti a record altrui vengono rifiutati dal backend. +5. Scollegare con conferma e permesso: verificare revoca ruoli, cronologia e incarichi pending. +6. Provare il flusso con backend + Auth reali in staging; agent mode copre solo UI/fixture. + +Ogni PR esegue `pnpm check`, `pnpm typecheck`, `pnpm test`, `pnpm build` e verifica desktop/mobile. +Il deploy segue i gate sopra; codice in main e screenshot con fixture non bastano a spuntare questi esiti. + +## Filoni che possono avanzare separatamente + +- Audit auth#76/backend#90/admin#123: registro leggibile e permesso disponibile. +- eSign: configurazione drive/Graph, installazione e firma reale; conservare il flusso generico durante il cleanup. +- Matricole: modifica autorizzata da admin visibile alla successiva richiesta web; errori e FAQ protette. +- MCP #137: registrazione OAuth, review e collaudo personale dopo riallineamento al nuovo People. + +## Dopo il MVP + +Soci/quote su Entra (#144) e censimento admin (#145) richiedono design prima di sviluppo. Il primo non condivide +record con People; il secondo usa gli incarichi fase 1. Restano fuori candidature HR, gestione gruppi dal Capo, +partner/eventi, newsletter, aziende e casa. Nessuna di queste funzioni è necessaria per ricostruire auth o RBAC. diff --git a/PRD_Admin_Dashboard_PoliNetwork.md b/PRD_Admin_Dashboard_PoliNetwork.md new file mode 100644 index 0000000..2f35dd7 --- /dev/null +++ b/PRD_Admin_Dashboard_PoliNetwork.md @@ -0,0 +1,254 @@ +# PRD — Admin Dashboard PoliNetwork + +**Versione:** 3.0 · **Aggiornamento:** 30 ottobre 2026 · **Stato:** proposta di prodotto aggiornata per revisione. + +Documenti: [classificazione e prossime attività](PRD_Classificazione_Feature.md), [MVP](MVP.md), +[People](Persone_Volontari_Soci.md), [permessi](RBAC_Ruoli_Permessi.md), +[design IdP](IdentityProvider_Design.md), [modello dati](IdentityProvider_DataModel.md), +[checklist sito](Checklist_Sito_Web.md). + +## 0. Scopo e metodo + +Dare al team una base attuale per decidere e assegnare il lavoro. Prima gli strumenti interni, poi i servizi +per soggetti esterni. Questa revisione sostituisce le ipotesi di agosto–ottobre, in particolare il registro +unico persone/soci/censimento e i collegamenti automatici delle identità. + +**Presente in main** significa codice integrato, non deploy o collaudo certificato. **In PR** significa lavoro +non integrato. **Da progettare** significa che il requisito non è un contratto da implementare subito. +Le decisioni People del 29 ottobre in [admin#146](https://github.com/PoliNetworkOrg/admin/issues/146) +prevalgono sui vecchi documenti e sulle descrizioni delle PR #132/#136. Le fonti fissate sono in §20. + +### 0.1 Stato attuale + +- OIDC/BFF, permessi puntuali, shell, overview, Telegram, WhatsApp, etichette, report e CMS sono in main. +- eSign è integrato: richieste, firma CIE locale, più firmatari, posizioni e documenti, OneDrive e consegna email. +- People, soci, quote, ricevute e censimento sono entrati in main con #97/#100. Il backend espone `people.*`: + non è più corretto descriverli come sole UI in PR o chiedere di implementare da zero il vecchio contratto. + La roadmap #146 riporta però un'area vuota/non collegata a RBAC, con soli dati di test: serve il nuovo percorso sotto. +- Microsoft 365 crea soci e cambia il numero associativo; i gruppi e i loro membri sono in sola lettura (#133). +- Matricole è modificabile da admin (#124), e web legge il contenuto backend. Il lockfile admin risolve + `@polinetwork/backend` 4.0.0, che include `web.freshman`: la nota README su 1.4.0 è storica. +- Il backend main rifiuta tutte le chiamate senza token (#97); web richiede il proprio token (#198). + Non pianificare un rollback con `LEGACY_ANONYMOUS=allow`. + +## 1. Persone, ruoli e gerarchie + +Socio, Group Admin e membro di team sono categorie indipendenti. Essere admin di un gruppo Telegram non +costituisce la fonte dei ruoli organizzativi. Telegram collegato non è necessario per entrare nella dashboard. + +La direzione approvata in #146 separa: + +1. **People:** Group Admin, Capo Admin e membri/Lead dei team, collegati ai ruoli Auth. +2. **Soci:** utenti Entra ID, quote e rinnovi, separati dai record People. +3. **Censimento:** conferma periodica degli admin, costruita dopo la fase 1. + +Una persona non collegata vive soltanto nel backend. Nessun utente preliminare in Auth, nessun matching +per nome, email o Telegram. Sono previsti solo invito accettato e collegamento manuale autorizzato. + +## 2. Fondamenta + +### 2.1 Autorizzazione + +Implementata: `me.access`, permessi esatti, middleware BFF e controllo indipendente nel backend. +`/dashboard` ammette `admin:access` oppure `people:self`; quest'ultimo apre la vista limitata. +In main gli incarichi People vengono dalla scheda; il loro collegamento ai ruoli Auth è lavoro di fase 1. + +Requisito fase 1: binding predeterminati `admin`, `capo`, `team::member`, `team::lead`. +Auth controlla delega, autorizzazione corrente e divieto di autoassegnazione. Ruoli con permessi `idp:*` +non sono associabili a People. Un Lead può gestire i membri del proprio team, senza promuovere Lead. +Il Capo Admin consulta i propri admin; la loro gestione resta futura. + +### 2.2 Audit amministrativo + +L'audit RBAC di Auth e quello di moderazione non sono un registro unificato già disponibile in admin. +Filone aperto: [auth#76](https://github.com/PoliNetworkOrg/auth/pull/76) registra `audit:read`, +[backend#90](https://github.com/PoliNetworkOrg/backend/pull/90) registra le mutazioni e offre `audit.list`, +[admin#123](https://github.com/PoliNetworkOrg/admin/pull/123) aggiunge la pagina. + +Accettazione: ricerca e filtri per attore, oggetto, azione, esito e periodo; dettaglio prima/dopo dove raccolto; +sola lettura; nessun segreto o contenuto dei file nei log. Verificare la copertura degli eventi Auth: +il middleware backend da solo non dimostra che le modifiche avviate nell'IdP compaiano nella vista comune. + +### 2.3 Ricerca + +La palette ⌘K esiste: naviga alle sezioni e avvia ricerche tramite `?q=`. Una ricerca unica che restituisca +record di più domini resta futura; non ricostruire la palette per implementarla. + +### 2.4 Overview + +Conteggi, segnalazioni, grant e andamento della creazione utenti Telegram sono implementati secondo i permessi. +Quest'ultimo non misura utenti attivi o audience. Indicatori People/quote richiedono i nuovi domini stabili. + +### 2.5 Consensi + +Esistono UI e contratto People della prima iterazione, ma non certificano un processo definitivo di informative, +consensi versionati e retention. Il cleanup toglie i flussi collegati al censimento. Progettare il processo futuro +con testi, prova di accettazione, revoca e destinatari prima di collegarlo a eSign. Una firma PDF generica non +completa da sola il processo privacy. + +### 2.6 Identity Provider + +Auth è autonomo; admin è un consumer OIDC con sessioni Redis dedicate e token solo server-side. +Google/Entra, passkey, Telegram collegato e verifica studente vivono nell'IdP. Socio/Direttivo derivano da Entra. +Il sito usa credenziali di servizio per le letture: questo non è login personale dei visitatori. +Non ricostruire autenticazione o RBAC dentro admin. + +### 2.7 eSign + +La firma CIE passa dall'app locale: il PIN resta nella sua pagina, mai nel BFF. Da telefono/tablet si consulta; +la firma richiede computer e lettore. La dashboard non permette upload di un PDF firmato altrove nel flusso generico. +Riusare viewer, compositore, firma multipla e gestione drive. Il ponte ricevute People oggi presente sarà rimosso +nel cleanup; la sua eventuale reintroduzione è una decisione della fase Soci, non una dipendenza della fase 1. +Prima di dichiarare il servizio operativo, raccogliere evidenza di configurazione Graph/drive, permessi, +installazione dell'agent e firma con CIE reale sui sistemi supportati ([tracker](docs/esign/TRACKER.md)). + +## 3. People: cleanup e fase 1 + +Il programma corrente è [#146](https://github.com/PoliNetworkOrg/admin/issues/146). +[Specifica dettagliata](Persone_Volontari_Soci.md). + +- **Cleanup #142:** admin#147 implementa #138: soci, quote, ricevute e censimento restano mockup espliciti, + senza backend e con azioni disabilitate. Vengono rimossi matching, gruppi Telegram e ponte ricevute/eSign. + Distribuire prima di backend#104; poi rimuovere i permessi obsoleti secondo auth#77. +- **Fase 1 #143:** Auth#73 va rielaborata secondo auth#78 e nuovamente revisionata; segue configurazione auth#79. + Backend#101 costruisce record, incarichi e sincronizzazione; #102 inviti/link; #103 import CSV. + Admin#139/#140/#141 consumano quei contratti. +- **Non mergiare #132/#136 o backend#99 come soluzione finale:** #146 li supera; recuperare solo le parti richieste + dalle nuove issue. Le revisioni People sono sospese finché le sottoissue non le riaprono. + +Accettazione: record creato con soli nome/cognome; incarichi non collegati in attesa; dopo il link Auth applica +oppure rifiuta con motivo; la UI distingue attesa dal successo. Invito utilizzabile anche da un account +senza permessi dashboard, su una pagina esterna alla shell protetta. Nessuna assegnazione a sé stessi. + +## 4. Governance e Direttivo + +Nessuna nuova area separata impegnata in questo ciclo. Auth gestisce ruoli e permessi; lo stato associativo +proviene da Entra. Storico degli organi e contenuti pubblici non vanno dedotti dai record People. + +## 5. Admin e Capo Admin + +Le pagine esistono in main, ma hanno residui del vecchio modello Telegram. Il cleanup li rimuove; +admin#139 le ricostruisce sui ruoli Auth e sulla relazione «Capo di riferimento». +Il corso personale non determina automaticamente l'ambito di responsabilità. La vista del Capo deve escludere +admin altrui anche chiamando direttamente il backend; approvare ingressi nei gruppi non è nella fase 1. + +## 6. Soci, quote e ricevute + +[Fase 2 #144](https://github.com/PoliNetworkOrg/admin/issues/144): non iniziata, design necessario. +Entra ID è fonte dei soci, object ID chiave del dominio quote e `employeeId` numero associativo. +Nessuna condivisione con People o claim del record socio. L'ammissione resta nel workflow Azure esistente. + +Bonifico esterno, caricamento prova, revisione, ricevuta numerata, firma CIE e reminder sono bisogni da +riesaminare usando #100 come riferimento storico. Definire annualità, importi, numerazione, firmatari, +annullamento, destinatari e permessi prima di ricostruirli. `soci:*` è un namespace proposto, non un catalogo già attivo. + +## 7. Team + +UI team e vista Lead sono in main; sincronizzazione dei ruoli Auth e stati degli incarichi sono nella fase 1. +Chiavi previste: `it`, `hr`, `design`, `intl`, `events`, da validare contro i binding Auth. +Un team senza binding non è assegnabile. Il nome «Design & Marketing» è un riuso richiesto da #139. +I tool specifici dei team non sono parte del primo rilascio. + +## 8. Censimento e onboarding + +[Fase 3 #145](https://github.com/PoliNetworkOrg/admin/issues/145): design necessario dopo la fase 1. +Chiede ai Group Admin se continuano; chi non è collegato riceve prima un invito. L'uscita usa lo stesso +comando di revoca ruolo della fase 1. Il vecchio wizard Forms non è il contratto futuro. +Candidature, colloqui HR, richieste ai gruppi e firma dei documenti restano processi da definire separatamente. + +## 9. Email di compleanno + +Backlog, dopo il design Soci: richiede uno scopo per la raccolta della data, destinatari e regole di invio. +Non è motivo per aggiungere dati di nascita alla fase 1 People. + +## 10. FAQ + +CRUD bilingue e categorie sono presenti. Matricole seleziona cinque FAQ dal catalogo. +Import da file e popolamento editoriale restano da fare; riordino e bozza/pubblicazione sono estensioni +future da validare anche sul contratto backend, non blocchi automatici del lancio. + +## 11. Aree operative e CMS + +- **Telegram/WhatsApp:** gruppi, visibilità, etichette e pubblicazione sono presenti. Telegram non crea gruppi + dalla dashboard. Grant attivi/programmati esistono; storico completo e reminder restano backlog. +- **Microsoft 365:** directory (`azure:members:read`), nuovo socio (`azure:members:create`), cambio numero + (`azure:members:write`, conferma e email opzionale). Il backend rifiuta numeri occupati e richiede un token utente + per il cambio. Gruppi (`azure:groups:read`) sempre in sola lettura: Soci determina ruoli IdP. + Modifiche generiche a utenti, licenze o membership non sono il prossimo incremento autorizzato. +- **Matricole:** risorse, hub Telegram, cinque FAQ e tab Guida; vecchio URL guide rediretto. + Titoli/struttura restano fissi. Verificare il ciclo admin → backend → web con dati effettivi. +- **Progetti/associazioni:** CRUD interno disponibile. Risorse per piattaforma: backend#72 ancora aperta, + poi servono editor admin e lettura web. Non confondere questo con il singolo link progetto esistente. + +## 12. Associazioni partner + +Backlog dopo il lavoro interno: referenti multipli, ownership dell'organizzazione, richieste di creazione/modifica, +approvazione editoriale e pubblicazioni sui canali. Il CRUD interno non offre accesso esterno scoped. +Definire isolamento dei record e successione dei referenti, senza trasferire account personali. +Canali (Telegram/WhatsApp), crediti e responsabilità di approvazione restano da concordare. + +## 13. Eventi / PoliTamTam + +Backlog: inserimento da partner o PoliNetwork e approvazione prima della pubblicazione. +Dipende dal design di ownership e revisione dei contenuti; non è parte del MVP interno. + +## 14. Aziende + +Da progettare con un referente di prodotto; nessun incremento assegnabile finché manca lo scope. + +## 15. Casa e coinquilini + +Backlog esterno: definire identità degli inserzionisti, moderazione e ciclo di vita degli annunci. + +## 16. Newsletter + +Backlog: segmenti, consensi, disiscrizione e invio. Non usare automaticamente contatti People come mailing list. + +## 17. Vincoli e verifica + +Permessi puntuali su UI/BFF/backend, dati personali limitati allo scopo, nessun token nel client. +Le mutazioni ricaricano i loader prima di chiudere/toast; errore di reload dopo salvataggio non invita a ripetere. +Nessuna azione distruttiva su più righe senza istruzione esplicita dell'utente (AGENTS.md). +La cancellazione dei dati di test pianificata dal cleanup è lavoro della PR backend, non di questi documenti. + +Agent mode non prova autenticazione o accesso al backend reale: People usa il fake; gli altri domini possono +ricevere `UNAUTHORIZED` dal backend main. Per integrazioni usare staging con token reali e fixture isolate. +Verificare anche ruoli limitati, desktop/mobile e failure di Auth, non solo l'account con tutti i permessi. +UI admin prevalentemente inglese; localizzazione IT/EN resta un requisito futuro distinto dai contenuti bilingui. + +## 18. Fuori scope del ciclo + +Contabilità completa, gateway pagamenti, modifica dello statuto, gestione libera dei gruppi Entra e migrazione +dei dati People di test. MCP admin è un filone separato in [#137](https://github.com/PoliNetworkOrg/admin/pull/137): +OAuth personale e permessi correnti, ancora da integrare e attivare; la firma richiede comunque la persona. + +## 19. Decisioni residue e prossimo ordine + +1. Completare e distribuire il cleanup nell'ordine #142; verificare che i mockup non facciano chiamate. +2. Stabilizzare binding/delega e provisioning Auth (#78/#79), poi tipi backend e pagine fase 1. +3. Collaudare inviti senza permessi, link/unlink, revoche, attori e comandi idempotenti. +4. Portare avanti audit (#76/#90/#123) e collaudo Matricole come filoni separati. +5. Definire design Soci (#144) e censimento (#145), senza ripristinare il vecchio dominio unificato. +6. Decidere retention, visibilità dei contatti, processo consensi, candidatura HR e localizzazione. +7. Concordare scope partner/eventi, newsletter e casa solo dopo le priorità interne. + +Non riaprire come decisioni tecniche il metodo di login, il matching automatico o la fonte dei soci: +sono già fissati rispettivamente dal BFF e dalla roadmap #146. + +## 20. Fonti della revisione + +Snapshot consultato il **30 ottobre 2026**; stato delle PR distinto dal loro eventuale deploy. + +| Fonte | Baseline / uso | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | +| [admin main c4b5abf](https://github.com/PoliNetworkOrg/admin/tree/c4b5abfe8078d2fcecb958924d162278b7b26dd6) | Codice, route, permessi, lockfile, test; #97/#100/#124/#130/#133/#134/#135 integrati | +| [backend main 1c9f937](https://github.com/PoliNetworkOrg/backend/tree/1c9f937e77866a59d950dd28384c2f435016f494) | README autenticazione, policy e `src/people/router.ts`; chiamate anonime eliminate | +| [auth main 720e8bc](https://github.com/PoliNetworkOrg/auth/tree/720e8bcf36f696cc819e952bbe6365e6b9fd119a) | README, schema RBAC; MCP Auth integrato, binding People ancora in PR | +| [web main 0e04231](https://github.com/PoliNetworkOrg/web/tree/0e042311a3b21e442b14ebd2d3d769d84cc55762) | README, client backend e pagina Matricole; token di servizio obbligatorio | +| [Roadmap People #146](https://github.com/PoliNetworkOrg/admin/issues/146) | Decisioni del 29 ottobre e precedenza sui vecchi piani | +| [Cleanup #142](https://github.com/PoliNetworkOrg/admin/issues/142), [fase 1 #143](https://github.com/PoliNetworkOrg/admin/issues/143), [Soci #144](https://github.com/PoliNetworkOrg/admin/issues/144), [censimento #145](https://github.com/PoliNetworkOrg/admin/issues/145) | Ordine, sottoissue e criteri di accettazione | + +Consultate le PR aperte di admin, auth, backend e web; inventario operativo nella classificazione. +I documenti `docs/people/*` descrivono la prima implementazione: usarli per leggere main, non per contraddire #146. +I vecchi SHA di bot, polinet.cc, aule, slide e altri progetti non sono una verifica aggiornata di quei repository. +Questa PR aggiorna documenti e incorpora main per verificarli sul codice attuale; non distribuisce servizi. diff --git a/PRD_Classificazione_Feature.md b/PRD_Classificazione_Feature.md new file mode 100644 index 0000000..b40f418 --- /dev/null +++ b/PRD_Classificazione_Feature.md @@ -0,0 +1,77 @@ +# Classificazione feature e roadmap + +**Aggiornamento:** 30 ottobre 2026 · [PRD](PRD_Admin_Dashboard_PoliNetwork.md) · [MVP](MVP.md). + +Gli ID storici sono mantenuti per i riferimenti. Le vecchie stime di effort sono ritirate: contratto e scope +People sono cambiati. Priorità: **P0** stabilizzazione interna, **P1** completamento interno, **P2** backlog. +«Main» non certifica deploy; «PR» non significa approvata. Fonti e SHA nel PRD §20. + +## Stato per funzionalità + +| ID | Funzionalità | Stato verificato | Priorità e prossimo passo | +| --- | ---------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | +| 0 | Identity Provider / OIDC BFF | Main, token server-side e Redis; backend senza fallback anonimo | P0: collaudo consumer/configurazione e ruoli reali, senza ricostruire auth | +| 1 | RBAC e scope | Globale in main; ruoli People non collegati | P0: Auth#78/#79, backend#101, admin#139; controllo record e delega | +| 2 | Consensi versionati | Prima UI People presente, processo definitivo da progettare | P1: definire testi, prova, revoca, retention; non ripristinare il vecchio matching | +| 2a | Audit amministrativo | Audit di dominio esiste; registro unico in PR | P1: auth#76 → backend#90 → admin#123, verificando copertura Auth | +| 2b | Firma CIE / eSign | Main, anche firma multipla, OneDrive, drive policy | P1: verifiche operative CIE/agent/Graph; ponte ricevute People da rimuovere nel cleanup | +| 3 | People / Soci / censimento | Prima versione in main (#97/#100), superata da #146 | P0: cleanup #142, poi People #143. Soci #144 e censimento #145 separati, design necessario | +| 4 | Overview e ricerca | Overview e palette ⌘K in main | P2: eventuale ricerca record trasversale e KPI dei nuovi domini | +| 5 | Admin e Capo Admin | UI main con residui Telegram | P0: #147 li rimuove; #139 aggiunge incarichi Auth e Capo in sola lettura | +| 6 | Rinnovi / quote / ricevute | Implementazione main da disconnettere | P1: mockup in #147, nuovo design Entra in #144; nessun `people:fees:*` futuro | +| 7 | Team | UI e viste limitate in main | P0: binding e stati incarichi nella fase 1, Lead limitato al team | +| 8 | Onboarding / censimento | UI precedente presente; flusso ruoli e inviti incompleto | P0: inviti/link #140 e import CSV #141. Censimento #145 e candidature HR successivi | +| 9 | Compleanni | Backlog | P2: dopo design Soci e regole dati/invio | +| 10 | FAQ | CRUD bilingue main, selezione Matricole main | P1: contenuti/import; workflow editoriale avanzato P2 | +| 11 | Aree operative | Telegram/WhatsApp/CMS/M365 main | P1: collaudo Matricole; risorse progetto dopo backend#72. Gruppi M365 solo lettura | +| 12 | Partner esterni | Solo CRUD interno associazioni | P2: ownership e richieste approvate; nessuna area esterna già pronta | +| 13 | PoliTamTam | Backlog | P2: design eventi e approvazione dopo ownership partner | +| 14 | Aziende | Scope assente | P2: definire bisogni prima di assegnare sviluppo | +| 15 | Casa | Backlog | P2: processo annunci e moderazione | +| 16 | Newsletter | Backlog | P2: segmenti, consensi e disiscrizione | +| 17 | MCP admin | PR #137; MCP Auth già main, servizio distinto | P1: review, registrazione client e deploy, smoke test personale e permessi | + +## PR admin aperte: come trattarle + +| PR | Stato nel piano | Prossimo passo / dipendenza | +| ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------- | +| [#147](https://github.com/PoliNetworkOrg/admin/pull/147) | Cleanup #138, aperta | Verificare assenza chiamate rimosse e mockup espliciti; distribuire prima di backend#104 | +| [#136](https://github.com/PoliNetworkOrg/admin/pull/136), [#132](https://github.com/PoliNetworkOrg/admin/pull/132) | Superate da #146, anche se ancora aperte | Non mergiare; recuperare solo rimozione gruppi, campi mancanti e rename team nelle nuove issue | +| [#137](https://github.com/PoliNetworkOrg/admin/pull/137) | MCP personale | Client Native/Public PKCE, `ADMIN_MCP_CLIENT_ID`, deploy e prova reale; riallineare People al cleanup | +| [#123](https://github.com/PoliNetworkOrg/admin/pull/123) | UI audit | Auth#76 e backend#90; verificare permessi e copertura effettiva | +| [#75](https://github.com/PoliNetworkOrg/admin/pull/75) | Gestione template email | Riesaminare su OIDC e contratto attuale; non completa rinnovi, newsletter o scheduler | +| [#68](https://github.com/PoliNetworkOrg/admin/pull/68) | Questi documenti | Review della nuova baseline e delle priorità | +| [#53](https://github.com/PoliNetworkOrg/admin/pull/53) | Aggiornamento Better Auth storico | Verificare pertinenza: main admin usa `openid-client`, non Better Auth; non pianificare un merge automatico | + +#95/#96/#97/#98/#100/#110/#111 sono già integrate: non assegnare più rebase o backend del vecchio contratto. +#133 rende obsoleta la gestione membership introdotta da #96. + +## Dipendenze tra repository + +| Filone | Lavoro e ordine | +| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Cleanup People | [admin#138](https://github.com/PoliNetworkOrg/admin/issues/138) / PR #147 → [backend#100](https://github.com/PoliNetworkOrg/backend/issues/100) / [PR #104](https://github.com/PoliNetworkOrg/backend/pull/104) → [auth#77](https://github.com/PoliNetworkOrg/auth/issues/77) | +| Ruoli People | [auth#78](https://github.com/PoliNetworkOrg/auth/issues/78) rielabora [PR #73](https://github.com/PoliNetworkOrg/auth/pull/73), nuova review → [setup #79](https://github.com/PoliNetworkOrg/auth/issues/79) → [backend#101](https://github.com/PoliNetworkOrg/backend/issues/101) → [admin#139](https://github.com/PoliNetworkOrg/admin/issues/139) | +| Collegamenti | [backend#102](https://github.com/PoliNetworkOrg/backend/issues/102) → [admin#140](https://github.com/PoliNetworkOrg/admin/issues/140), dopo record e ruoli | +| Import persone | [backend#103](https://github.com/PoliNetworkOrg/backend/issues/103) → [admin#141](https://github.com/PoliNetworkOrg/admin/issues/141), dopo record e ruoli; non è import censimento | +| Audit | [auth#76](https://github.com/PoliNetworkOrg/auth/pull/76) → [backend#90](https://github.com/PoliNetworkOrg/backend/pull/90) → admin#123 | +| Risorse progetti | [backend#72](https://github.com/PoliNetworkOrg/backend/pull/72) → pacchetto tipi → editor admin e visualizzazione web | + +[Backend#99](https://github.com/PoliNetworkOrg/backend/pull/99) è superata; riusare solo il codice ruoli richiesto +in #101. Auth#75 è stata incorporata nel branch #73, non in main: il modello utenti preliminari va eliminato +secondo #78. Le revisioni People restano sospese secondo #146 fino all'indicazione delle sottoissue. +Le PR Auth #68 (override permessi), #70 (guida servizi), #74 (controlli UI) e backend #57 (audit precedente), +#55 (email), #38 (warn) sono aperte ma non sostituiscono i contratti del piano sopra; verificare sovrapposizioni +prima di riprendere i vecchi filoni. Le PR di sole dipendenze non indicano avanzamento di prodotto. + +## Cosa assegnare adesso + +1. **Team dashboard:** finire #147/#138; dimostrare che mockup e shell non chiamino procedure eliminate. +2. **Team Auth:** #78 e #79, binding sicuri, delega e catalogo; rifare la review di #73 dopo il taglio di #75. +3. **Team backend:** cleanup #104 dopo dashboard; poi #101, #102 e #103 con tipi pubblicati. +4. **Team dashboard:** #139, #140, #141 dopo i rispettivi contratti. Test account senza permessi e ruoli limitati. +5. **Filoni indipendenti:** audit, collaudo eSign e Matricole, review MCP; vedere [MVP](MVP.md) per gli esiti attesi. +6. **Prodotto/Direttivo:** design Soci e censimento; contenuti e lancio web nella [checklist](Checklist_Sito_Web.md). + +Non assegnare l'implementazione integrale di `docs/people/contract.md` o nuove funzioni su quote/censimento +prima del nuovo design. Nessuna data di consegna o nuovo responsabile personale è implicato da questo elenco. diff --git a/Persone_Volontari_Soci.md b/Persone_Volontari_Soci.md new file mode 100644 index 0000000..94ce832 --- /dev/null +++ b/Persone_Volontari_Soci.md @@ -0,0 +1,168 @@ +# People, volontari e Soci — direzione di prodotto + +**Versione:** 3.0 · **Aggiornamento:** 30 ottobre 2026. + +Fonti prevalenti: [roadmap #146](https://github.com/PoliNetworkOrg/admin/issues/146), +[cleanup #142](https://github.com/PoliNetworkOrg/admin/issues/142), +[fase 1 #143](https://github.com/PoliNetworkOrg/admin/issues/143), +[Soci #144](https://github.com/PoliNetworkOrg/admin/issues/144), +[censimento #145](https://github.com/PoliNetworkOrg/admin/issues/145). +[PRD](PRD_Admin_Dashboard_PoliNetwork.md), [roadmap operativa](PRD_Classificazione_Feature.md). + +Questa revisione sostituisce il progetto del registro unico People/Libro Soci e del matching tramite Telegram. +I vecchi dettagli di schema, permessi e API non sono specifiche da ripristinare. `docs/people/*` e #97/#100 +spiegano l'implementazione in main e forniscono riferimenti storici; #146 stabilisce il prossimo lavoro. + +## 1. Da dove partiamo + +Admin #97/#100/#134 e backend #83/#94 hanno integrato pagine e API per persone, soci, quote, ricevute, +censimento, consensi e collegamenti. La roadmap #146 riporta l'area People vuota e non collegata ai ruoli RBAC, +con dati soltanto di test. Non basta rendere visibili altre colonne: va separato il dominio e chiusa la delega Auth. + +| Dominio | Direzione approvata | Cosa non implica | +| ---------- | ------------------------------------------------------------------- | -------------------------------------------------------- | +| People | Record backend, incarichi Admin/Capo/team, account Auth facoltativo | Non crea soci e non assegna gruppi Telegram | +| Auth | Identità reali e ruoli RBAC degli account collegati | Non conserva persone preliminari senza credenziali | +| Soci | Entra ID, object ID come chiave, numero in `employeeId` | Non usa schede o inviti People | +| Censimento | Conferma degli admin sugli incarichi fase 1 | Non ricostruisce il vecchio censimento misto soci/gruppi | + +## 2. Cleanup: prima della nuova funzionalità + +[Admin#147](https://github.com/PoliNetworkOrg/admin/pull/147) realizza +[#138](https://github.com/PoliNetworkOrg/admin/issues/138). È ancora una PR, non lo stato di main. + +- Libro Soci, ricevute, censimento e card quota restano mockup con dati statici, banner esplicito e azioni disabilitate. + Visibili con `people:read`, non a chi possiede solo `people:self`. +- Rimuovere server functions, chiamate e contratto di quei flussi; eliminare anche i conteggi della shell collegati. +- Eliminare matching/review/merge, «Sei tu?», collegamenti dedotti, gruppi amministrati/richiesti e approvazioni Capo. +- Togliere ponte ricevute/eSign e permessi `people:members:*`, `people:fees:write`, `people:receipts:sign`. + Conservare eSign generico e miglioramenti condivisi al viewer. +- Conservare schede, Admin, Capo Admin, Team, inviti/link manuale e La mia area come base della fase 1. + +**Ordine:** distribuire admin #147, poi [backend#104](https://github.com/PoliNetworkOrg/backend/pull/104) +(issue #100), poi [auth#77](https://github.com/PoliNetworkOrg/auth/issues/77). Il backend elimina tabelle/flussi +obsoleti; nessun dato People di test viene migrato secondo #146. Questo documento non esegue cancellazioni. + +Accettazione: nessuna chiamata alle procedure rimosse, inclusi layout/badge; mockup chiaramente riconoscibili; +contratto residuo compatibile durante l'ordine di deploy; verifiche e agent mode passano. + +## 3. Fase 1: modello e responsabilità + +[Backend#101](https://github.com/PoliNetworkOrg/backend/issues/101) definisce il nuovo modello relazionale. +I nomi sotto sono concetti del contratto da implementare, non tabelle già disponibili in main. + +| Entità | Dati e vincoli richiesti | +| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| Persona | ID stabile, nome/cognome obbligatori, contatto email, telefono e Telegram opzionali, note, `account_sub` nullable/univoco, autori/date | +| Incarico | Persona, tipo `admin`/`capo`/`team`, team e ruolo, date/motivo fine, `assigned_by`, stato e motivo rifiuto | +| Capo di riferimento | Relazione alla scheda del Capo, distinta dal corso della persona; ambito sull'incarico Capo | +| Activity | Storico append-only di modifiche e collegamenti | +| Invito | Token conservato come hash, destinatario, scadenza, uso/revoca e attore | + +Le chiavi team restano configurate (`it`, `hr`, `design`, `intl`, `events`) e verificate contro i binding Auth. +Un team senza ruoli associati non è assegnabile. Non occorre un catalogo dinamico di team per questo rilascio. + +### Incarichi e fonte di verità + +- Scheda senza account: incarichi **pending** nel backend, con chi li ha assegnati; Auth non riceve persone o ruoli. +- Scheda collegata: Auth è fonte dei ruoli. Backend legge i binding e invia comandi tramite outbox idempotente. +- Stati richiesti: `pending`, `sent` (attesa Auth), `applied`, `refused` con motivo. La UI non mostra successo prima + della conferma. Le revoche esterne in Auth si riflettono nelle viste. +- Un account con ruolo associato in Auth ma senza scheda produce una scheda già collegata. +- Cache e disponibilità seguono il contratto backend: gestire outage e revisioni senza far prevalere una risposta + precedente su una revoca. TTL e soglia massima vanno fissati nel contratto implementativo, non dedotti dai mockup. + +## 4. Binding e delega + +[Auth#78](https://github.com/PoliNetworkOrg/auth/issues/78) rielabora la PR #73; il codice preliminare di #75 +va rimosso e la PR nuovamente revisionata. [Auth#79](https://github.com/PoliNetworkOrg/auth/issues/79) +configura i binding in produzione prima del backend. + +- Tipi ammessi: `admin`, `capo`, `team::member`, `team::lead`; mai ruoli con `idp:*`, anche indiretti. +- Admin/membri: `admin:access` + `people:write`, oppure Lead del team per i suoi membri. +- Nomine Lead/Capo: `admin:access` + `people:appoint`. +- Nessuna autoassegnazione; nessuna concessione di permessi che l'attore non possiede. +- Auth calcola l'accesso corrente dell'attore e applica il comando tutto o niente; ambiguità e ruoli ancora + ereditati causano un rifiuto esplicito. Il backend applica le stesse regole agli incarichi pending. +- Il nuovo permesso di binding (`idp:people:bind`, nome da confermare) rende l'operazione delegabile. + Non introdurre nuovi controlli hard-coded «solo Master Admin» per sostituire i permessi. + +La gestione dei propri admin da parte del Capo è futura. Per ora il Capo legge soltanto; relazione e regole +per tipo di binding devono permettere un'estensione successiva senza concedere gestione oggi. + +## 5. Esattamente due modi di collegare + +Specifica: [backend#102](https://github.com/PoliNetworkOrg/backend/issues/102), +[admin#140](https://github.com/PoliNetworkOrg/admin/issues/140). + +**Invito:** operatore con `people:write` o Lead nel proprio team invia alla mail di contatto. Token monouso, +hash a riposo, durata 14 giorni; reinvio invalida il precedente. Il destinatario entra con **qualsiasi account**, +anche con email diversa, e conferma il collegamento. Un account già collegato altrove viene rifiutato. + +Serve una pagina esterna alla shell dashboard, accessibile a qualsiasi account autenticato: richiedere +`people:self` prima di accettare crea un circolo, perché i ruoli arrivano solo dopo il link. + +**Manuale:** `admin:access` + nuovo `people:link`; ricerca directory Auth, conferma, link con storico. +Non usare nome/email/Telegram per collegamenti automatici, suggerimenti da confermare o merge. + +**Applicazione ruoli:** nel link manuale l'attore è chi collega; nell'invito è l'originario `assigned_by` +di ciascun incarico. Comandi distinti per attore, ID derivati dal link e retry idempotenti. Il destinatario +non è attore di una propria autoassegnazione. Se l'assegnatore ha perso delega, mostrare il rifiuto di Auth. + +**Unlink:** con `people:link`, conferma che spiega la perdita ruoli; revocare in Auth prima di staccare l'account. +Gli incarichi tornano pending. Mostrare collegamenti degli ultimi 30 giorni con metodo, data e attore, +così un invito inoltrato o un link errato può essere individuato e annullato. + +## 6. Pagine da costruire sul nuovo contratto + +[Admin#139](https://github.com/PoliNetworkOrg/admin/issues/139): + +- **Overview:** record, Admin, Capo, team, collegamento e stati pending/refused. +- **Scheda:** profilo, account, incarichi con stato/motivo e storico. Creazione con soli nome/cognome. +- **Admins:** attivi e Capo di riferimento modificabile; nomina/fine Capo protette da `people:appoint`. +- **Capo Admin:** propri admin in sola lettura; scoping nel backend, non filtro solo browser. +- **Teams:** membri e Lead; il Lead gestisce soltanto i membri del proprio team. +- **La mia area:** propria scheda e ruoli con stato, senza funzionalità Soci/censimento riattivate. +- **Linking:** inviti, link manuale e collegamenti recenti; nessuna coda di matching. + +Riutilizzare da #132 solo valori profilo mancanti («—») e nome Design & Marketing; da #136 la rimozione +Telegram se non già nel cleanup. **Non mergiare quelle PR**: #146 le considera superate, come backend#99. + +## 7. Import persone + +[Backend#103](https://github.com/PoliNetworkOrg/backend/issues/103) e +[admin#141](https://github.com/PoliNetworkOrg/admin/issues/141): CSV template → upload → anteprima con errori, +duplicati e incarichi non autorizzati → commit esplicito → eventuali inviti. Non è import censimento. +Il vecchio wizard può fornire componenti da recuperare dalla storia, eliminando i passaggi di campagna. +Non collegare account per contatto o nome durante l'import. Verificare idempotenza e delega anche al commit. + +## 8. Fase 2: Soci separati + +#144 richiede **design prima dello sviluppo**. Soci deriva da Entra; object ID identifica il socio e `employeeId` +il numero. Nessuna condivisione con record People, nessun claim del tesseramento o match necessario. +Ammissione soci in Azure con `azure:members:create`; la fase 2 non crea un secondo workflow account. + +Quote, annualità, stato rinnovo, ricevute bonifico, ricevute numerate e firma possono riusare idee da #100, +non il vecchio contratto. Definire separatamente identificazione storica, importi, numerazione, correzioni, +firmatari, prove di pagamento, mail, retention e catalogo (`soci:*` soltanto un esempio di namespace). +Non ripristinare i vecchi permessi `people:members:*`, `people:fees:*`, `people:receipts:*`. + +## 9. Fase 3: censimento admin + +#145 richiede design dopo la fase 1. Le persone collegate rispondono in dashboard; le altre ricevono un invito. +La risposta «lascio» termina l'incarico admin con lo stesso comando Auth già usato in fase 1. +Definire calendario, solleciti, risposte tardive/correzioni, mancata risposta e informative. Non dedurre ruoli +da dichiarazioni sui gruppi o dallo status socio. Candidature e colloqui HR restano un processo distinto. + +## 10. Verifiche e ordine + +Cleanup: admin → backend → permessi IdP. Fase 1: Auth → setup → backend → rispettiva UI. +Review People sospese secondo #146 finché le sottoissue non riaprono il percorso. + +Testare pending/linked, ogni stato incarico, autoassegnazione, bounded delegation, Lead e Capo fuori ambito, +account senza permessi che accetta invito, email diverse, token scaduto/riusato/revocato, conflitti di account, +revoca all'unlink, retry e outage Auth. Le prove finali usano backend/Auth reali in staging; agent mode serve alla UI. + +`pnpm check`, `pnpm typecheck`, `pnpm test`, `pnpm build`; desktop/mobile e permessi limitati. +Nessuna nuova scelta di retention o visibilità dei contatti è approvata da questo documento: va decisa con +i responsabili. Non ampliare i campi raccolti recuperando automaticamente tutti quelli del vecchio Forms. diff --git a/RBAC_Ruoli_Permessi.md b/RBAC_Ruoli_Permessi.md new file mode 100644 index 0000000..9619689 --- /dev/null +++ b/RBAC_Ruoli_Permessi.md @@ -0,0 +1,88 @@ +# Ruoli e permessi — dashboard e People + +**Versione:** 3.0 · **Aggiornamento:** 30 ottobre 2026. +[PRD](PRD_Admin_Dashboard_PoliNetwork.md), [People](Persone_Volontari_Soci.md), +[IdP](IdentityProvider_Design.md), [modello dati](IdentityProvider_DataModel.md). + +## 1. Contratto corrente in admin main + +Fonte: [`src/server/permissions.ts`](src/server/permissions.ts), +[`auth.middleware.ts`](src/server/auth.middleware.ts), [`nav.ts`](src/components/shell/nav.ts). + +`admin:access` oppure `people:self` permette l'ingresso nella shell. Il secondo da solo apre La mia area +e le viste per gli incarichi sul proprio record, non la dashboard completa. La navigazione non costituisce +un controllo sufficiente: BFF e backend verificano le chiamate. Telegram collegato non conferisce ruoli. + +| Permessi esatti presenti in main | Uso | +| ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- | +| `admin:access` | Accesso amministrativo e letture di base | +| `tg:users:read`, `tg:messages:read`, `tg:audit:read` | Utenti, messaggi e audit moderazione | +| `tg:groups:manage` | Gestione gruppi Telegram | +| `tg:grants:read`, `tg:grants:manage` | Lettura e mutazioni grant | +| `wa:groups:manage` | Gestione gruppi WhatsApp | +| `groups:labels:write` | Etichette comuni | +| `web:content:write`, `web:reports:manage` | CMS incluso Matricole; gestione report | +| `azure:members:read`, `azure:members:create`, `azure:members:write` | Directory, creazione socio, cambio numero | +| `azure:groups:read` | Gruppi e membri in sola lettura | +| `people:self`, `people:read`, `people:write`, `people:appoint` | Area personale, registri, scritture e nomine attuali | +| `people:members:read`, `people:members:write`, `people:fees:write`, `people:receipts:sign` | Prima implementazione Soci/quote/ricevute: **da rimuovere nel cleanup** | +| `esign:sign`, `esign:requests:manage`, `esign:drives:manage` | Firma, richieste e regole drive | + +`azure:groups:write` non appartiene più al catalogo della dashboard. Cambiare membership Soci concederebbe +o revocherebbe ruoli IdP; non riproporre quel controllo. Il cambio numero richiede token utente reale. +Non inferire permessi da prefissi, dal nome del ruolo o dal possesso di un permesso diverso: le eventuali +implicazioni sono risolte nell'IdP. + +## 2. Auth e delega già implementata + +Auth mantiene ruoli, assegnazioni, ereditarietà e implicazioni, con audit RBAC. I ruoli gestiti Master Admin, +Socio, Direttivo e Student sono distinti da quelli personalizzati; gli stati Entra/Student non dimostrano +quote pagate o incarichi People. Le assegnazioni dei ruoli personalizzati usano permessi IdP distinti dalla +modifica delle definizioni. Non ripristinare `ADMIN_ROLES`, il veto `creator` o `capability_grant`. + +Il vecchio «HR sola lettura ovunque» non è una regola runtime: l'accesso deriva dal catalogo corrente. +Le nuove deleghe vanno approvate e configurate; queste tabelle non assegnano permessi a nessuno. + +## 3. People fase 1 — requisiti, non ancora catalogo completo in main + +Fonte: [#143](https://github.com/PoliNetworkOrg/admin/issues/143), +[auth#78](https://github.com/PoliNetworkOrg/auth/issues/78), +[backend#101](https://github.com/PoliNetworkOrg/backend/issues/101). + +| Operazione | Requisito futuro | +| -------------------------------------------------------- | ---------------------------------------------------------------------- | +| Leggere registri globali | `admin:access` + `people:read` | +| Creare/modificare persona, assegnare Admin o membro team | `admin:access` + `people:write`, oppure Lead per il proprio team | +| Nominare/revocare Capo o Lead | `admin:access` + `people:appoint` | +| La mia area / Capo sui propri admin | `people:self` e relazione sul record; Capo in sola lettura | +| Inviare inviti | `people:write` o Lead per membri del proprio team | +| Accettare invito | Qualsiasi account autenticato + token valido, senza gate `people:self` | +| Link/unlink manuale | `admin:access` + **nuovo `people:link`** | +| Associare ruolo a significato People in Auth | **Nuovo permesso**, es. `idp:people:bind`; nome da confermare | + +Binding ammessi: `admin`, `capo`, `team::member`, `team::lead`. Ruoli managed e ruoli con `idp:*` +non sono bindabili. Il vincolo deve comprendere ereditarietà/implicazioni e successive modifiche del ruolo. + +Auth verifica sempre l'attore: niente autoassegnazione, nessuna delega oltre i propri permessi, comando atomico +ed idempotente. Il backend applica gli stessi limiti agli incarichi pending. Nell'accettazione invito l'attore +del comando è chi assegnò l'incarico, non l'invitato. Un rifiuto rimane visibile con il motivo. +Scoping Team Lead/Capo dipende dalle relazioni backend e dai controlli Auth: un campo `scopeType/scopeValue` +in una vecchia proposta non offre questa protezione. Il Capo non gestisce admin o ingressi gruppi in fase 1. + +## 4. Cataloghi in evoluzione + +- Cleanup: rimuovere i quattro permessi Soci/quote/ricevute da UI/BFF e poi IdP secondo #142/auth#77. +- Audit: `audit:read` è in [auth#76](https://github.com/PoliNetworkOrg/auth/pull/76), non nel catalogo admin main; + distinto da `tg:audit:read`. Richiede backend#90/admin#123 e assegnazione esplicita ai revisori. +- Soci fase 2: namespace proprio (es. `soci:*`) da progettare; non ripristinare `members.*` o `membership.self*` + come se fossero permessi disponibili. Il socio deriva da Entra, non da un claim People. +- Censimento fase 3, candidature, partner, eventi e newsletter: catalogo da definire con il processo. +- MCP admin #137: account personale e permessi delle stesse operazioni; nessun ruolo «agente» con poteri impliciti. + L'MCP Auth già integrato è un servizio separato. + +## 5. Accettazione dell'autorizzazione + +Provare ogni scrittura con permesso assente e con accesso diretto al backend, oltre ai controlli UI. +Provare un Lead fuori team, un Capo su admin altrui, autoassegnazione, ruolo che implica Lead, attore che +perde delega tra invito e conferma e unlink con revoca. Aggiornare il catalogo condiviso e i security test +quando si aggiunge una server function. Non introdurre permessi descrittivi che nessun servizio applica.