diff --git a/Checklist_Sito_Web.md b/Checklist_Sito_Web.md new file mode 100644 index 0000000..c681a3c --- /dev/null +++ b/Checklist_Sito_Web.md @@ -0,0 +1,92 @@ +# Checklist lancio sito PoliNetwork + +**Aggiornamento:** 16 novembre 2026. +Fonte codice: [web main 17f8c5b](https://github.com/PoliNetworkOrg/web/tree/17f8c5bb10dc9452d9dc6fee49af870c6408c7a3). +[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: integrato e residuo + +- [x] Lo stack #199–#216 è confluito nel branch Home e poi in main tramite + [#199](https://github.com/PoliNetworkOrg/web/pull/199) (130 file): Home, Storia, Su di noi, Struttura, + Team, Unisciti, Collabora, Contatti, Progetti, Gruppi, Matricole, Associazioni, FAQ, Guide, header/footer e 404. + #218/#219 sono state integrate sullo stesso branch prima di #199; #217 è chiusa senza merge. + Non assegnare una nuova sequenza di merge #200–#216 sulla base della vecchia checklist. +- [x] [#221](https://github.com/PoliNetworkOrg/web/pull/221): posizione della navbar mobile. +- [ ] [#222](https://github.com/PoliNetworkOrg/web/pull/222): ulteriori correzioni Su di noi/Storia/Unisciti e caroselli mobile. +- [ ] [#223](https://github.com/PoliNetworkOrg/web/pull/223): audit sito, hydration/404, SEO, risorse mobile, + accessibilità, copy e immagini. È aperta: risultati e screenshot della PR non sono baseline main. +- [ ] [#179](https://github.com/PoliNetworkOrg/web/pull/179): confrontare la spaziatura proposta con lo stack già integrato. +- [ ] Verificare desktop/mobile, tastiera e movimento ridotto sul risultato finale. +- [ ] #163 (easter egg), #145 (gioco CFU) e #197 (dipendenza Zod) sono aperte, non traguardi del lancio. + +#223 segnala inoltre attività esterne al codice: Email Obfuscation Cloudflare con hydration su alcune pagine, +contenuti backend mancanti/di prova e decisioni sul copy inglese. Verificare nell'ambiente target e assegnare ai +responsabili; questa revisione non modifica Cloudflare o dati di produzione. + +## 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 + +- [x] Backend#132: catalogo Documenti con categorie e storico versioni. +- [ ] Integrare [admin#162](https://github.com/PoliNetworkOrg/admin/pull/162) e + [web#220](https://github.com/PoliNetworkOrg/web/pull/220): gestione CMS, catalogo pubblico e viewer PDF. +- [ ] Popolare statuto, regolamenti, privacy/cookie, bilanci e collegare il footer alle versioni approvate. + Non confondere questo catalogo con l’editor collaborativo RRI già presente in admin. Donazioni/5x1000 da valutare. +- [ ] 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..9cf5e41 --- /dev/null +++ b/IdentityProvider_DataModel.md @@ -0,0 +1,88 @@ +# Modello dati e contratti — Auth, backend e admin + +**Versione:** 4.0 · **Aggiornamento:** 16 novembre 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 contiene `role.peopleBinding` e il supporto comandi People di #73; nessun utente preliminare. +Auth#86 espone `entraObjectId` nello snapshot e #87 il claim array `polinetwork_permission_list`. +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`, `admins`, `capos`, `teams`, `linking`, `capo`, `me`; schema relazionale, + incarichi e comandi Auth sono in `src/db/schema/people/index.ts`. Nessun router quote/censimento sotto People. +- Soci separato espone `members`, `fees`, `me`: registro, prove bonifico, revisione e self-service. +- Regolamenti ha schema/contratto propri e collaborazione Yjs; Documenti pubblici è un catalogo CMS distinto. +- 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. + Microsoft 365 è in sola lettura; il nuovo socio è ammesso tramite il workflow `soci.members.admit`. + +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 e contratti integrati + +Admin#147 e backend#104 hanno rimosso il vecchio dominio unificato. Backend#105/#106/#109 e admin#148/#149 +realizzano record, incarichi, inviti, link e unlink. Non ripristinare tabelle, matching e ponte ricevute/eSign rimossi. +Solo Censimento resta mockup: Soci usa il contratto reale separato. + +Auth#73 applica binding `admin`, `capo`, `team::member`, `team::lead`, con `idp:people:bind` e scope +interno `idp:people:roles`. I comandi sono idempotenti, attribuiti all'attore e controllati per delega/autoassegnazione. +Incarichi `pending`/`sent`/`applied`/`refused`; account collegato univoco, contatti non usati per matching. +Inviti monouso con hash, scadenza e revoca; landing `/people/invite` senza gate dashboard. +Unlink revoca i ruoli prima di scollegare. Schema e wire effettivi: [contratto People](docs/people/contract.md). +L'import CSV generale non è nel router corrente; seed admin#153 è un altro flusso, ancora in PR. + +## 4. Soci e Regolamenti: contratti presenti e limiti + +Soci usa `soci_members`, `soci_fees`, `soci_files`, `soci_activity`, `soci_mail`, collegati all'object ID Entra. +Numeri non riutilizzabili, quota di 500 centesimi e annualità settembre–agosto; file PDF/PNG/JPEG fino a 10 MB. +Review riferita al file caricato; outbox email idempotente. `me.completeDetails` compila soltanto campi vuoti. +Il router corrente non espone ancora `members.end`/`restore`, `accounts.delete` o `lapse.preview`, benché presenti +nel [design](docs/people/soci.md). Non generare client per quei requisiti come se fossero API già distribuite. + +Regolamenti usa `regulations.*`, accessi per bozza e deleghe backend, ticket monouso per il servizio collaborativo, +worker LaTeX isolato, GitHub App per emanare e outbox notifiche. Vedere [contratto](src/features/regulations/regulations.contract.ts). +Documenti pubblici: backend#132 integrata, consumer admin#162/web#220 in PR; non coincide con l'editor RRI. + +## 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: completare fine appartenenza/decadenza/cancellazione sul design del 9 novembre; quote già integrate. +- 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..f579361 --- /dev/null +++ b/IdentityProvider_Design.md @@ -0,0 +1,95 @@ +# Design — Identity Provider e integrazione admin + +**Versione:** 4.0 · **Aggiornamento:** 16 novembre 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. + +People riusa l’autenticazione esistente. Auth#70 integra la guida servizi; per lo stato effettivo dei consumer +confrontare la guida con codice e configurazione corrente. + +## 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. +Un’assegnazione a una bozza o una delega Regolamenti ammette inoltre alla sola area Bozze tramite +`regulations.me.get`; le capacità per bozza arrivano dal backend. +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) è in main, consumata da backend#105/#106 e admin#148/#149. +`idp:people:bind` è un permesso effettivo, non un nome provvisorio. Setup dei binding e prove ambiente restano +separati dal merge; non riaprire la progettazione degli utenti preliminari. + +## 5. Soci e ruoli istituzionali + +Soci è un dominio implementato separatamente da People. Ammissione e cambio numero passano da `soci.*`; +le scritture `azure.members.create`/`setAssocNumber` sono rimosse. Auth#86 espone `entraObjectId` nello snapshot +per `soci.me.*`, che usa l'account Microsoft 365 autenticato anche senza scheda People. +Il design del 9 novembre esclude ricevute associative/CIE: vedere [Soci](docs/people/soci.md). +Auth#82 introduce Presidente e Segretario, usati dal workflow Regolamenti; Auth#87 aggiunge il claim array +`polinetwork_permission_list`. Questo non sostituisce i controlli correnti backend su `me.access`. + +Censimento #145, consensi e onboarding HR richiedono ancora design. Login e firma PDF non attestano il processo intero. + +## 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..c8c8349 --- /dev/null +++ b/MVP.md @@ -0,0 +1,44 @@ +# MVP interno — stabilizzazione e completamento + +**Aggiornamento:** 16 novembre 2026 · [PRD](PRD_Admin_Dashboard_PoliNetwork.md) · +[roadmap](PRD_Classificazione_Feature.md) · [lancio sito](Checklist_Sito_Web.md). + +Il precedente obiettivo di costruire People fase 1 è implementato. Il prossimo risultato è verificarlo con i servizi +reali, completare il ciclo Soci e rendere utilizzabili Regolamenti e Documenti. Codice integrato e rilascio operativo +sono traguardi distinti: le caselle seguenti non attestano produzione. + +## Codice disponibile + +- [x] Cleanup e People: admin#147/#148/#149, Auth#73, backend#104/#105/#106/#109. +- [x] Registro Soci/ammissione/dati/numero: admin#158–#161, backend#126–#128. +- [x] Quote, revisione bonifici, pagamento manuale e My area: admin#163/backend#129; identità Entra Auth#86. +- [x] Email quote e compleanni backend#129/#130. +- [x] Regolamenti: admin#150/#151, backend#110–#117/#133/#134; ruoli Presidente/Segretario Auth#82. +- [x] Catalogo Documenti backend#132; editor CMS e sito non ancora integrati. + +## Gate da chiudere + +- [ ] **People reale:** binding configurati, invito accettabile senza permessi dashboard, link/unlink e revoca, + stati pending/sent/applied/refused, attore che perde delega, retry/outage, Lead e Capo fuori ambito. +- [ ] **Import:** decidere revisione/esecuzione del seed admin#153; l'import CSV generale #141/backend#103 + richiede ancora preview, commit idempotente e autorizzazioni. Non confondere i due deliverable. +- [ ] **Soci reale:** ammissione e registrazione esistenti, numero univoco, My area senza scheda People, identità Entra, + upload/sostituzione prova, review sul file corrente, rifiuto e pagamento manuale, annualità/esenzioni ed email. +- [ ] **Ciclo Soci residuo:** cessazione/ripristino, decadenza automatica e coda/cancellazione account secondo il design. + Il router corrente non implementa queste operazioni; l'avviso di scadenza UI non prova il job di decadenza. +- [ ] **Regolamenti reale:** collab e worker isolato, due editor, permessi per bozza/deleghe e revoche, compile/diff, + approvazione, GitHub App, pubblicazione e destinatari notifiche. Gestione creazione/rinomina/rimozione file residua. +- [ ] **Documenti pubblici:** admin#162 e web#220 sul backend#132, categorie/versioni/PDF e contenuti approvati. + +Ogni PR funzionale esegue `pnpm check`, `pnpm typecheck`, `pnpm test`, `pnpm build` e verifica UI/permessi. +Le fixture non provano provisioning, recapito email, Graph o firma CIE. Non spuntare gate operativi senza evidenze. + +## Filoni indipendenti + +Audit auth#76/backend#90/admin#123; eSign con CIE reale, agent e Graph; Matricole end-to-end; +MCP admin#137 con client OAuth personale e permessi correnti. Il lancio web ha una checklist dedicata. + +## Fuori dal prossimo rilascio + +Censimento #145 resta mockup in attesa di design. Candidature HR, gestione gruppi dal Capo, partner/eventi, +newsletter, aziende e casa restano backlog. Le ricevute associative numerate/CIE sono escluse dal design Soci corrente. diff --git a/PRD_Admin_Dashboard_PoliNetwork.md b/PRD_Admin_Dashboard_PoliNetwork.md new file mode 100644 index 0000000..e872dce --- /dev/null +++ b/PRD_Admin_Dashboard_PoliNetwork.md @@ -0,0 +1,265 @@ +# PRD — Admin Dashboard PoliNetwork + +**Versione:** 4.0 · **Aggiornamento:** 16 novembre 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 generico è integrato: CIE locale, più firmatari/documenti, OneDrive e consegna email. +- Cleanup People #147, record/incarichi #148 e inviti/link #149 sono integrati; Auth#73 e backend#105/#106/#109 + implementano binding e sincronizzazione. L'import CSV generale non è presente; admin#153 propone un seed una tantum. +- Soci ha un dominio separato `soci.*`: registro/ammissione #158–#161, quote e area personale #163 in main. + Censimento resta mockup. Decadenza e cancellazione account sono ancora requisiti, non procedure disponibili. +- Microsoft 365 è interamente in sola lettura. Ammissione e cambio numero sono passati a Soci; + backend#127 ha rimosso `azure.members.create` e `setAssocNumber`. +- Regolamenti #150/#151 e backend#110–#117/#133/#134 sono integrati: editor collaborativo LaTeX, + PDF, diff, merge, iter di approvazione, emanazione e notifiche. +- Matricole è modificabile da admin e letto da web. Documenti pubblici: backend#132 integrata, + admin#162 e web#220 aperte. Il lockfile admin risolve ancora `@polinetwork/backend` 4.0.0: + non equivale alla versione corrente del servizio backend. +- Backend rifiuta chiamate anonime; web usa il proprio token. Nessun rollback `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. +Un’assegnazione o delega Regolamenti consente inoltre il solo accesso alle Bozze, verificato dal backend. +In main gli incarichi delle schede collegate sono sincronizzati con Auth; quelli senza account restano pending. + +Implementati in Auth#73: 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 aggregati People/quote restano un incremento da definire sui domini attuali. + +### 2.5 Consensi + +La prima iterazione People non costituisce il contratto corrente né certifica un processo definitivo di informative, +consensi versionati e retention. Il cleanup ha tolto 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 è stato rimosso; il design Soci del 9 novembre esclude ricevute associative e firma CIE. +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: fase 1 integrata e import residuo + +La roadmap [#146](https://github.com/PoliNetworkOrg/admin/issues/146) resta il riferimento di separazione dei domini. +Cleanup #147, ruoli #148 e collegamenti #149 sono in main con Auth#73 e backend#105/#106/#109. +[Specifica e stato dettagliati](Persone_Volontari_Soci.md). + +Le schede richiedono nome/cognome; incarichi `pending`, `sent`, `applied`, `refused` distinguono attesa e rifiuto. +Invito e link manuale sono gli unici collegamenti; `/people/invite` è fuori dalla shell protetta. +Non creare placeholder Auth o ripristinare matching, merge identità e tracciamento gruppi Telegram. +Restano import CSV generale (#141/backend#103), seed una tantum in PR #153 e collaudo dei binding nell'ambiente target. +Il seed non sostituisce il workflow CSV con preview e commit, e questa revisione non lo esegue. + +## 4. Governance e Regolamenti + +Regolamenti è ora un'area implementata (admin#150/#151), inizialmente per la Raccolta dei Regolamenti Interni. +Comprende bozze, assegnazioni viewer/commenter/editor, collaborazione CodeMirror/Yjs, PDF, commenti, storico, +differenze, merge, approvazione, emanazione tramite GitHub App e notifiche Soci con copia a Direttivo/Probiviri. +Auth#82 aggiunge Presidente e Segretario. Permessi e deleghe sono descritti nel documento RBAC. + +Verificare worker LaTeX isolato, servizio collab, repository legal, GitHub App e destinatari prima del rilascio operativo. +L'editor seleziona i file esistenti ma non li aggiunge/rinomina/elimina. Non estendere automaticamente il supporto +allo statuto. Fonte implementativa: [Regolamenti](docs/regulations/README.md). + +## 5. Admin e Capo Admin + +Pagine ricostruite in #148 sui ruoli Auth e sulla relazione «Capo di riferimento»; nessuna dipendenza dai gruppi Telegram. +Il Capo consulta solo i propri admin; gestione e approvazione ingressi restano fuori scope. +Verificare lo scoping anche chiamando il backend direttamente. + +## 6. Soci e quote + +Il [design approvato il 9 novembre](docs/people/soci.md) sostituisce le ipotesi precedenti della fase 2 #144. +Entra è fonte dell'appartenenza corrente; object ID collega il registro e `employeeId` conserva il numero. +`soci:read` / `soci:write` sono attivi. Registro, ammissione, registrazione soci Entra esistenti, modifica dati e numero +sono integrati; Microsoft 365 non offre più scritture. + +Quote: 5 euro, annualità settembre–agosto, scadenza rinnovo 31 dicembre ed esenzione dell'annualità successiva +per ammissioni giugno–agosto. Il socio carica la prova bonifico PDF/PNG/JPEG (10 MB); il Direttivo conferma, +rifiuta con motivo o segna pagato manualmente. My area funziona anche senza scheda People, tramite `people:self` +e object ID Entra nello snapshot Auth#86. Nessuna ricevuta associativa numerata o firma CIE in questa fase. + +Backend#129 e admin#163 implementano quote e self-service; backend#130 compleanni e template italiani. +Decadenza automatica, cessazione/ripristino e coda cancellazione account restano da implementare: compaiono nel design, +ma non nel router corrente. Non dichiarare attivo `SOCI_AUTO_LAPSE` sulla sola base della specifica. + +## 7. Team + +UI, vista Lead, binding e stati degli incarichi sono in main. Chiavi del contratto People: +`it`, `hr`, `design` (Design & Marketing), `intl`, `events`. Un ruolo senza binding non è assegnabile. +Il Lead gestisce i membri del proprio team, non promuove Lead. Il catalogo pubblico del sito non determina i binding. +Tool specifici dei team restano backlog. + +## 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 + +Backend#130 ha implementato job e template italiani per i soci attivi, indirizzati alla casella PoliNetwork. +Verificare dati di nascita, pianificazione, outbox e recapito nell'ambiente target; non aggiungere date alla scheda +People per questa funzione e non equipararla a una newsletter. + +## 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`) e gruppi (`azure:groups:read`) in sola lettura. + Ammissione e cambio numero passano da Soci con `soci:write`; niente gestione libera di utenti/licenze/membership. +- **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, Regolamenti in italiano; localizzazione generale IT/EN resta futura. + +## 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. Collaudare People integrato: binding/delega, inviti senza permessi, link/unlink, revoche e indisponibilità Auth. +2. Revisionare il seed #153 separatamente dall'import CSV generale #141/backend#103; nessun import implicito. +3. Completare il ciclo Soci (cessazione, ripristino, decadenza e cancellazione manuale account) sul design approvato; + verificare quote, email e identità Entra senza ripristinare le ricevute associative. +4. Collaudare Regolamenti end-to-end con i suoi servizi e permessi; completare gestione file dell'editor. +5. Completare Documenti pubblici (admin#162/web#220), audit e review MCP; collaudo eSign/Matricole separato. +6. Progettare censimento #145, consensi, candidature HR e localizzazione. Lancio web nella checklist dedicata. +7. Concordare partner/eventi, newsletter e casa dopo le priorità interne. + +## 20. Fonti della revisione + +Snapshot consultato il **16 novembre 2026**: fetch dei main, lettura di codice/contratti e stato GitHub delle PR. +Il merge non certifica il deploy. Non sono state eseguite migrazioni, import o verifiche di produzione. + +| Repository | Baseline fissata | Evidenze principali | +| -------------------------------------------------------------------------------------------------- | ---------------- | ----------------------------------------------------------------------------- | +| [admin](https://github.com/PoliNetworkOrg/admin/tree/e98b2b7acc7ab77f7f8949bbfad9786f5e1ffb91) | `e98b2b7` | Route, permessi, contratti People/Soci/Regolamenti, lockfile e test | +| [backend](https://github.com/PoliNetworkOrg/backend/tree/275f519a81d2d00c873221d4d8fae69c88fee1d6) | `275f519` | Router People/Soci, schema, job quote/compleanni, Documenti e Regolamenti | +| [auth](https://github.com/PoliNetworkOrg/auth/tree/9fe232e2bffab154b070f30532cb9e45f68b0ca9) | `9fe232e` | Binding People, Presidente/Segretario, object ID Entra e claim permessi array | +| [web](https://github.com/PoliNetworkOrg/web/tree/17f8c5bb10dc9452d9dc6fee49af870c6408c7a3) | `17f8c5b` | Stack visuale confluito in #199, header #221, token backend e Matricole | + +Fonti di prodotto: [roadmap #146](https://github.com/PoliNetworkOrg/admin/issues/146), +[contratto People](docs/people/contract.md), [design Soci](docs/people/soci.md), +[Regolamenti](docs/regulations/README.md). Il design Soci include ancora operazioni future: confrontarlo con +`src/features/soci/soci.contract.ts` e il router backend, non trattarlo come elenco di API già disponibili. + +Inventario PR nella [classificazione](PRD_Classificazione_Feature.md) e nella [checklist web](Checklist_Sito_Web.md). +I documenti storici `docs/people/fees.md` non prevalgono sul design Soci del 9 novembre; alcune note README e +contratto People sui mockup restano storiche. Solo Censimento è ancora mockup nella baseline admin. +Bot, legal, polinet.cc, aule e altri repository non sono stati riesaminati: i riferimenti non attestano il loro deploy. +Questa PR incorpora main e modifica soltanto gli otto documenti di pianificazione rispetto a quella baseline. diff --git a/PRD_Classificazione_Feature.md b/PRD_Classificazione_Feature.md new file mode 100644 index 0000000..8645ece --- /dev/null +++ b/PRD_Classificazione_Feature.md @@ -0,0 +1,65 @@ +# Classificazione feature e roadmap + +**Aggiornamento:** 16 novembre 2026 · [PRD](PRD_Admin_Dashboard_PoliNetwork.md) · [MVP](MVP.md). + +ID storici conservati. P0: stabilizzazione interna; P1: completamento; P2: backlog. +Main indica codice integrato, non deploy verificato. Baseline e fonti nel PRD §20. + +## Stato per funzionalità + +| ID | Funzionalità | Stato verificato | Priorità e prossimo passo | +| --- | ---------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------- | +| 0 | IdP / OIDC BFF | Main, token server-side, backend autenticato | P0: collaudo consumer e configurazione | +| 1 | RBAC / People | Binding Auth e sincronizzazione in main | P0: delega, revoche, outage e setup ambiente | +| 2 | Consensi | Processo definitivo da progettare | P1: testi, prova, revoca e retention | +| 2a | Audit comune | Auth#76/backend#90/admin#123 aperte | P1: completare e verificare copertura eventi Auth | +| 2b | eSign | Main, CIE/multi-documento/OneDrive | P1: firma reale e Graph; nessun ponte ricevute Soci | +| 3 | People / Soci | Domini separati in main | P0: collaudo e completamento ciclo Soci | +| 4 | Overview / ricerca | Overview e palette in main | P2: ricerca trasversale e KPI | +| 5 | Admin / Capo | Incarichi Auth e Capo in sola lettura in main | P0: scoping reale; gestione Capo futura | +| 6 | Quote | Revisione bonifici e My area in main | P0: cessazione, ripristino, decadenza e cancellazione account residue | +| 7 | Team | Binding, stati e Lead in main | P0: verifica delega; tool team P2 | +| 8 | Inviti / import / censimento | Inviti/link main; seed #153 aperta; import generale assente; censimento mockup | P1: distinguere import e fase 3 da progettare | +| 9 | Compleanni | Backend#130 main | P1: dati, job e recapito reale | +| 10 | FAQ | CRUD e selezione Matricole main | P1: contenuti/import; editoriale avanzato P2 | +| 11 | Operatività / CMS / M365 | Main; M365 solo lettura | P1: collaudo; risorse progetto backend#72 aperta | +| 12 | Partner | CRUD interno | P2: ownership e richieste esterne | +| 13 | PoliTamTam | Backlog | P2: eventi/approvazione, distinto da altri servizi Live | +| 14 | Aziende | Scope assente | P2: definire bisogni | +| 15 | Casa | Backlog | P2: annunci e moderazione | +| 16 | Newsletter | Backlog | P2: segmenti, consenso, disiscrizione | +| 17 | MCP admin | #137 aperta; MCP Auth main | P1: review, client personale e collaudo | +| 18 | Regolamenti | Editor e workflow main | P0: collab/worker/GitHub/notifiche; gestione file residua | +| 19 | Documenti pubblici | Backend#132 main, admin#162/web#220 aperte | P1: integrare consumer e popolare versioni approvate | + +## PR admin aperte + +| PR | Prossimo passo | +| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | +| [#162](https://github.com/PoliNetworkOrg/admin/pull/162) | CMS Documenti sul backend integrato; coordinare web#220 | +| [#153](https://github.com/PoliNetworkOrg/admin/pull/153) | Revisionare seed una tantum da censimento; non è import CSV generale né esecuzione autorizzata qui | +| [#152](https://github.com/PoliNetworkOrg/admin/pull/152) | Guida contributi/stack locale | +| [#137](https://github.com/PoliNetworkOrg/admin/pull/137) | MCP: riallineare domini e permessi, OAuth e smoke test | +| [#123](https://github.com/PoliNetworkOrg/admin/pull/123) | Audit dopo Auth#76/backend#90 | +| [#75](https://github.com/PoliNetworkOrg/admin/pull/75) | Template email: rivalutare rispetto ai template Soci già integrati | +| [#68](https://github.com/PoliNetworkOrg/admin/pull/68) | Questa revisione documentale | +| [#53](https://github.com/PoliNetworkOrg/admin/pull/53) | Dipendenza Better Auth storica: admin usa openid-client, verificare pertinenza | + +## Dipendenze e attività residue + +1. **People:** implementazione Auth#73 → backend#105/#106/#109 → admin#148/#149 integrata. + Verificare provisioning e flusso reale. Import #141/backend#103 non disponibile, seed #153 separato. +2. **Soci:** registro e quote integrati. Implementare il resto del design del 9 novembre senza ricevute associative/CIE. + Auth#86 fornisce object ID Entra; non aggiungere matching People. +3. **Regolamenti:** codice integrato, richiede collab, compiler, legal, GitHub App e notifiche configurati. +4. **Documenti:** backend#132 integrata → admin#162/web#220 aperte → contenuti approvati e test pubblico. +5. **Audit:** Auth#76 → backend#90 → admin#123; non considerare automaticamente federato l'audit RBAC Auth. +6. **Risorse progetto:** backend#72 → tipi → editor admin e sito. Catalogo Documenti è un altro filone. +7. **Prodotto:** censimento #145, consensi/HR, lancio web e backlog esterno. + +Auth#70 (guida integrazione servizi) è integrata. Restano aperte Auth#68 (override), #74 (UI), #76 (audit), +#83 (contributi), #88–#91 (limite verifica studente, endpoint account, header sicurezza, ereditarietà ruoli built-in). +Non trattare queste correzioni aperte come protezioni già presenti nella baseline. +Backend#118 (contributi), #90 (audit), #72 (risorse), #57 (audit precedente), #55 (email) e #38 (warn) sono aperte; +confrontare i vecchi filoni con le implementazioni attuali prima di riprenderli. Le PR di dipendenze non attestano +avanzamento funzionale. Per web, elenco e verifiche nella [checklist](Checklist_Sito_Web.md). diff --git a/Persone_Volontari_Soci.md b/Persone_Volontari_Soci.md new file mode 100644 index 0000000..e09349c --- /dev/null +++ b/Persone_Volontari_Soci.md @@ -0,0 +1,147 @@ +# People, volontari e Soci — direzione di prodotto + +**Versione:** 4.0 · **Aggiornamento:** 16 novembre 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 distingue codice integrato e lavoro residuo. Il contratto People corrente è in +[docs/people/contract.md](docs/people/contract.md); Soci segue il [design del 9 novembre](docs/people/soci.md). + +## 1. Baseline + +Admin#147/#148/#149 e Auth#73/backend#105/#106/#109 sono in main. People gestisce volontari e incarichi, +Auth identità reali e ruoli degli account collegati, Soci il registro separato collegato a Entra. +Censimento è un mockup senza API, con dati statici e azioni disabilitate: fase 3 ancora da progettare. + +## 2. Cleanup completato nel codice + +Sono rimossi matching, merge identità, utenti preliminari, gruppi Telegram People e ponte ricevute/eSign. +Non riaprire il cleanup come prossimo sviluppo e non recuperare il vecchio dominio unificato. +I mockup Soci e ricevute introdotti dalla transizione sono stati sostituiti da `soci.*` (#158/#163). +Le vecchie PR #132/#136/backend#99 non sono il percorso implementativo; usare i contratti correnti. + +## 3. Fase 1 implementata: modello e responsabilità + +Backend#105 implementa il modello relazionale (`src/db/schema/people/index.ts`); backend#106 aggiunge gli inviti. +La tabella riassume concetti del contratto; i nomi SQL sono definiti nello schema. + +| 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 implementati: `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. Verificare TTL e soglie nel servizio corrente, senza dedurli dai mockup. + +## 4. Binding e delega + +Auth#73 è integrata: binding, comandi e delega sono codice corrente. La configurazione dei ruoli +nell'ambiente target resta una verifica operativa distinta dal merge (setup auth#79). + +- 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 permesso di binding `idp:people:bind` 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. + +La pagina `/people/invite` vive fuori dalla shell, 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` + `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 integrate sul nuovo contratto + +Admin#148/#149 implementano: + +- **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, con card Socio separata via `soci.me.*`, senza censimento. +- **Linking:** inviti, link manuale e collegamenti recenti; nessuna coda di matching. + +## 7. Import persone: lavoro residuo + +[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 router corrente non espone l’import CSV generale. Admin#153, ancora aperta, propone uno script una tantum +di seed dal censimento: non sostituisce questo flusso e non viene eseguito qui. +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 implementati in parte + +Registro e ammissione (#158–#161), quote e My area (#163) sono in main, con backend#126/#128/#129 e Auth#86. +Entra fornisce appartenenza corrente e object ID; `employeeId` conserva il numero, non riutilizzabile. +L'ammissione passa da Soci con `soci:write`; backend#127 ha ritirato le scritture Azure precedenti. + +La quota è 5 euro; il socio carica prova bonifico e il Direttivo conferma/rifiuta o marca pagato. +My area usa `people:self` anche senza scheda People, con identità Microsoft 365 verificata. +Nessuna ricevuta associativa numerata o firma CIE nel design approvato. Backend#130 implementa i compleanni. +Cessazione/ripristino, decadenza automatica e cancellazione account restano da implementare: non basta che siano +elencati nel design. Valutare il nuovo permesso di cancellazione quando si realizza quel flusso. + +## 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 residuo + +Collaudare i binding configurati, pending/linked, ogni stato incarico, autoassegnazione, delega, 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. Usare backend/Auth reali in staging; agent mode serve alle fixture UI. + +Per Soci: registrazione esistenti, ammissione, unicità numero, accesso proprio senza People, upload e sostituzione prova, +review concorrente sul `fileId`, rifiuto e pagamento manuale, annualità/esenzioni ed email idempotenti. +Completare il ciclo fine appartenenza prima di dichiarare operativa la decadenza automatica. + +Import generale e seed richiedono revisioni distinte; censimento segue un nuovo design. +`pnpm check`, `pnpm typecheck`, `pnpm test`, `pnpm build`; test UI desktop/mobile e permessi limitati nelle PR funzionali. +Questa revisione documentale non autorizza ulteriori raccolte di dati o import di massa. diff --git a/RBAC_Ruoli_Permessi.md b/RBAC_Ruoli_Permessi.md new file mode 100644 index 0000000..f738918 --- /dev/null +++ b/RBAC_Ruoli_Permessi.md @@ -0,0 +1,98 @@ +# Ruoli e permessi — dashboard e People + +**Versione:** 4.0 · **Aggiornamento:** 16 novembre 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` | Directory in sola lettura | +| `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:link`, `soci:read`, `soci:write` | Link/unlink; registro, ammissione, dati e quote Soci | +| `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 passa da `soci:write`; anche `azure:members:create` e `azure:members:write` sono rimossi. +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, Presidente, Segretario 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 — implementata + +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 | Controllo corrente | +| -------------------------------------------------------- | ---------------------------------------------------------------------- | +| 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` + `people:link` | +| Associare ruolo a significato People in Auth | `idp:people:bind`, introdotto da Auth#73 | + +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 integrato: i permessi `people:members:*`, `people:fees:write`, `people:receipts:sign` non sono nel catalogo admin. +- 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: `soci:read`/`soci:write` attivi con `admin:access`; `soci.me.*` usa `people:self` e object ID Entra verificato. + Il futuro `soci:delete` del design non è nel catalogo admin né applicato da un router di cancellazione corrente. +- 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. Regolamenti e accesso alla shell + +`regulations:read` legge documenti e bozze; `regulations:write` crea/modifica, assegna, unisce e invia in approvazione; +`regulations:manage` registra approvazione, emana e rigenera diff; `regulations:rectify` abilita rettifiche e deleghe. +Questi quattro permessi sono nel catalogo admin main. Presidente/Segretario sono ruoli Auth#82. + +Un'assegnazione viewer/commenter/editor o una delega è un dato backend, non un permesso globale IdP. +`regulations.me.get` ammette alla sola area Bozze anche senza `admin:access`/`people:self`; le azioni usano il `can` +della bozza. Non ampliare l'accesso agli altri documenti o alla dashboard per concedere questa collaborazione. + +## 6. Accettazione dell'autorizzazione + +Provare ogni scrittura senza permesso e con accesso diretto al backend, Lead fuori team, Capo su admin altrui, +autoassegnazione, attore che perde delega prima dell'invito, unlink e revoca. Per Soci verificare accesso soltanto +al proprio object ID, e per Regolamenti isolamento tra bozze, revoca assegnazioni e deleghe. +Agent mode non certifica i controlli reali. Aggiornare catalogo e security test con ogni nuova server function.