📖 DOCUMENTAZIONE PER IL TEAM
👉 LEGGI LA GUIDA SVILUPPATORI

Introduzione

Il progetto è nato con l'intento di semplificare la procedura di autenticazione degli utenti, in modo tale da fornire un'esperienza più pulita ed uniformata tra le diverse applicazioni della scuola. Al sistema di login, si è unita quindi la stesura di una documentazione sullo stile, in modo tale che tutte le applicazioni si assomiglino tra di loro, riducendo l'attrito e abbassando la curva di apprendimento.

Stesura degli standard

Non volevamo che lo stile fosse imposto, ma bensì che fosse frutto della collaborazione dei diversi gruppi. Abbiamo quindi creato una prima bozza con alcuni esempi di componenti, e poi "passato il testimone" ai gruppi, in modo tale che ci comunicassero le loro necessità

Vetrina stili (Cliccando sul profilo si può scaricare il codice sorgente aggiornato)

La build viene effettuata tramite un Makefile che crea lo zip, lo carica sulla VPS e poi carica il codice sorgente stesso della pagina. La pagina è nascosta dietro un tunnel di cloudflare. È stato necessario disabilitare il caching (molto aggressivo sulle pagine statiche). Per caricare il codice bisogna connettersi alla VPN apposita.

Come funziona

Lo schema di funzionamento del progetto è ancora in via di costruzione, ma ad oggi siamo arrivati alle seguenti conclusioni

Login

`

Il sistema di login è così fatto: Il sito satellite verifica se nei cookie del browser è salvato un token per l'API del portale (portal_token). Questo funziona grazie al fatto che tutti i siti saranno sotto lo stesso dominio (ad esempio calvino.edu.it). Se così non fosse, le pagine non potrebbero leggere i cookie derivanti dal portale centrale. SE il sito satellite trova il cookie, effettua una richiesta al portale centrale, che restituisce le informazioni sull'utente. Se il sito non trova il cookie, reindirizza la pagina sul login del portale centrale.

Registrazione tramite portale

todo: capire come gestire le registrazioni sui diversi siti (primo login dal portale)

Containers

Per hostare i progetti degli altri gruppi, abbiamo messo a disposizione dei containers LXC tutti uguali in una rete isolata

Info

OS: debian 12.9.0 RAM: 512MB Dimensione disco: 8GB (aumentabile) Dominio: i5ai (temporaneo) Gateway/DNS: 192.168.101.1 Password root: Calvino (da cambiare) IP: DHCP (gestito da pfsense)

DB

Per il database, abbiamo scelto di creare un container unico alla quale tutti i progetti si possono riferire (se in futuro si preferisse spostarlo altrove, basterebbe fare un dump)

(mariadb-secure-installation) Root password: Calvino2026

Per l'interfaccia grafica abbiamo scelto di usare adminer, per la sua semplicità e leggerezza Adminer consiste in un solo file .php, quindi basta installare un webserver (nel nostro caso nginx) e configurarlo

Per gli sviluppatori

Worktrees

I worktrees sono una funzionalità di git che permette di avere più branch attivi contemporaneamente, ognuno in una cartella diversa. Questo evita il continuo git checkout, permettendo di lavorare in parallelo.

Creare un worktree

Sintassi: git worktree add <path> <branch>

Esempio:

git worktree add ../Progettone-dev dev`
git worktree add ../Progettone-notes notes

Questo crea due cartelle

Progettone-dev/        -> branch dev
Progettone-notes/      -> branch notes

Lavorare su un branch

cd <directory>
git status
git add .
git commit -m "..."
git push

Ogni cartella è bloccata sul proprio branch. Per “cambiare branch” si cambia cartella, non si usa git checkout.

Creare branch per nuove funzionalità

È possibile creare nuovi branch direttamente dentro un worktree:

cd Progettone-dev
git checkout -b feature/nome-funzionalità

Se vuoi tenere aperti più branch in parallelo, puoi creare un nuovo worktree:

git worktree add ../Progettone-feature-xyz feature/xyz

Aliases

In futuro ho intenzione di documentare meglio, ma fino ad ora

Importare gli alias

git config include.path ../.gitconfig.repo

API

Elenco

#POST /api/users #GET /api/users #DELETE /api/users/:id #GET /api/websites #POST /api/websites #PATCH /api/websites/:id #POST /api/roles #PATCH /api/roles/:id #GET /api/roles

POST /api/users

Permette di aggiungere un utente

Request

Method: POST URL: /api/users Content-Type: application/json

Request body

name: Mario
surname: Rossi
email: mario.rossi@calvino.edu.it
password: Password123.
profile_image: https://cdn.calvino.edu.it/mariorossi.jpg

MULTIPART

• name: string
• surname: string
• email: string
• password: string
• profile_image: string/file

Name	Type	Required	Description
name	string	yes	User's name
surname	string	yes	User's surname
email	string	yes	User's email
password	string	yes	User's password (in clear)
profile_image	string/file	no	User's profile image (URL or file)

Responses

Success

Status: 200

{
	"success": true,
	"message": "Utente creato",
	"data": {
		"id": <user_id>
	}
}

Fail

Duplicate email Status: 409

{
	"success": false,
	"message": "L'email mario.rossi@calvino.edu.it esiste già",
	"data": {
		"email": "mario.rossi@calvino.edu.it"
	}
}

GET /api/users

Permette di ottenere tutti gli utenti (da modificare)

TODO

• Documentare la paginazione

Request

Method: GET URL: /api/users Params:

• page: selected page (default 1)
• pageSize (default 50, max 200)

Responses

Success

Status: 200

{
	"success": true,
	"message": "No message",
	"data": {
		"users": [
				{
					"id": 1,
					"name": "Angelo",
					"surname": "Ciausu",
					"email": "angelo.ciausu.2006@calvino.edu.it",
					"profile_image": null,
					"created_at": "2026-02-20T07:34:48.000Z",
					"roles": [
						{
							"id":1,
							"role_name":"studente",
							"assigned_at":"2026-03-11 11:24:45"
						}
					]
				},
				{
					"id": 2,
					"name": "Sergio",
					"surname": "Bianchi",
					"email": "sergio.bianchi.2007@calvino.edu.it",
					"profile_image": null,
					"created_at": "2026-02-20T07:36:42.000Z",
					"roles":[]
				},
		]
	},
	"total": 2,
	"page": 1,
	"page_size":50,
	"has_more": false

}

Fail

<todo>

Page size too high status: 400 ! max_page_size potrebbe cambiare

{
	"success":false,
	"message":"Page size too high",
	"details": {
		"page_size":"<pageSize>",
		"max_page_size":200,
	}
}

DELETE /api/users/:id

Permette di eliminare un utente

Request

Method: DELETE URL: /api/users/:id Content-Type: application/json

Responses

Success

{
	"success": true,
	"message": "Utente eliminato",
	"data": {
		"id": "<id>"
	}
}

Fail

user not found Status: 404

{
	"success": false,
	"message": "Utente non trovato",
	"data": {
		"id": "<id>"
	}
}

GET /api/websites

Restituisce l'elenco di tutti i siti associati

Request

Method: GET URL: /api/websites/

Response

Success

{
	"success":true,
	"message":"Siti restituiti",
	"data": {
		"websites": [
			{
				"id": 1,
				"title":"Gestione orari docenti",
				"short_description": "Applicazione per gestire gli orari dei docenti",
				"cover": "https://gestione.webp",
				"url": "https://orariodocenti.calvino.edu.it",
				"authorized_roles": ["docenti","segreteria"]
			},
			{...}
		]
	
	}
}

TODO

#todo

• Mockup
• altre

POST /api/websites

Aggiungi un nuovo sito all'elenco dei siti esistenti

Request

Method: POST URL: /api/websites/ Content-Type: application/json

Body

{
	"title":"Gestione orari docenti",
	"description": "Applicazione per gestire gli orari dei docenti",
	"cover": "https://gestione.webp",
	"url": "https://orariodocenti.calvino.edu.it",
	"authorized_roles": ["docenti","segreteria"]
}

Nell'esempio ho messo i ruoli autorizzato sotto forma di nomi. Potrei metterli sotto forma di ID

TODO

#todo

• Mockup

PATCH /api/websites/:id

Modifica un sito

TODO

#todo

• Mockup

Request

Method: PATCH URL: /api/websites/:id Content-Type: application/json

Body

{
	"title":"Gestione orari docenti",
	"description": "Applicazione per gestire gli orari dei docenti",
	"cover": "https://gestione.webp",
	"url": "https://orariodocenti.calvino.edu.it",
	"authorized_roles": ["docenti","segreteria"]
}

Nell'esempio ho messo i ruoli autorizzato sotto forma di nomi. Potrei metterli sotto forma di ID

POST /api/roles

Aggiunge un ruolo

Request

Method: POST URL: /api/roles/ Content-Type: application/json

Body

{
	"role_name":"studenti", 
	"group_id": "",
}

TODO

#todo

• Mockup
• Definire le risposte di fail

Response

Success

Status: 200

{
	"success": true,
	"message": "Ruolo aggiunto",
	"data": {
		"id": "<role_id>"
	}
}

Fail

{
	"success": false,
}

PATCH /api/roles/:id

Modifica un ruolo esistente

Request

Method: PATCH URL: /api/roles/:id Content-Type: application/json

TODO

#todo

• Mockup

Body JSON

{
	"role_name":"studenti", 
	"google_group_id": "",
}

GET /api/roles

Ottieni l'elenco dei ruoli

Request

Method: GET URL: /api/roles Content-Type: none

TODO

#todo

• Mockup

Responses

Success

Status: 200

{
	"success": true,
	"message": "No message",
	"data": {
		"roles": [
				{
					"id":1,
					"role_name":"studente",
					"assigned_at":"2026-03-11 11:24:45",
					"group_id": null,
				},
				{
					"id":2,
					"role_name":"docente",
					"assigned_at":"2026-03-11 11:24:45",
					"group_id":"03vac5uf35x7bbq"
				},
		]
	},
	"total": 2, 
	"page": 1, // Non penso che implementerò le pagine per i ruoli
	"page_size":50,
	"has_more": false

}