Questo progetto nasce dall'esigenza dei coordinatori del Grest di Capralba di poter organizzare i turni degli animatori in modo rapido e senza perdite di tempo.
Sto scherzando, ho fatto questo perché sono tremendamente pigro.
La fase preliminare di tutto il workflow è il setup dell'environment, che viene effettuato modificando il file environment.py nella root del package generator.
Devono essere inserite le seguenti variabili d'ambiente:
- per quanto riguarda il package
solver:FORM_API_KEY: token fornito da Tally per accedere alle API;FORM_ENDPOINT: link al quale trovare le risposte del form;PRE_ANIMATORS: numero di animatori al pre;POST_ANIMATORS: numero di animatori al post;LUNCH_ANIMATORS: numero di animatori in mensa;SHARE_LUNCH_ANIMATORS: numero di animatori al pranzo condiviso;MAX_NUMBER_DAILY_SLOTS: massimo numero di turni giornalieri;MAX_REPETITION_SAME_SLOT: massima ripetizione dello stesso turno;
- per quanto riguarda il package
telegram:CHANNEL_ID: canale nel quale verranno inviati i risultati del workflow;TELEGRAM_API_KEY: token fornito da telegram per accedere al bot.
Nel repository è presente anche il file turni_obbligatori.txt, che durante le settimane viene popolato con i nomi degli animatori che devono fare dei turni obbligatori.
La prima fase è la popolazione del modello di PLI che permette di calcolare l'assegnamento degli animatori nelle varia fasce orarie dei vari giorni di grest.
Ogni animatore compila un form Tally tra venerdì mattina e domenica pomeriggio, dove inserisce:
- nome;
- cognome;
- disponibilità e necessità per le seguenti fasce orarie:
- pre (dalle 08:00 alle 08:45);
- mensa (dalle 12:00 alle 13:30);
- post (dalle 17:00 alle 18:00).
Domenica sera vengono effettuate delle richieste HTTP alle API fornite da Tally per scaricare le risposte date dagli animatori e popolare il modello di PLI, usando anche i dati inseriti nel file environment.py.
La seconda fase è la creazione del file turni.pdf, il quale conterrà i turni che ogni animatore dovrà svolgere nell nella settimana di Grest.
Il modello precedentemente creato viene passato ad un SAT-solver che calcola l'assegnamento migliore degli animatori. Quest'ultimo è una matrice di assegnamento tridimensionale, che indica, per ogni fascia oraria, quale animatore è presente e in quale giorno.
La matrice risultante viene interrogata dagli script del package template per popolare il file template.typ, che contiene il template base per la creazione della tabella dei turni.
La tabella contiene tre righe, una per ogni fascia oraria, e cinque colonne, una per ogni giorno di Grest.
Il file template.typ viene compilato tramite typst per generare il file turni.pdf.
Viene preferito il formato typ a quello md per la sua semplicità e facilità nella compilazione per generare il file PDF dei turni.
La terza e ultima fase è l'invio, tramite bot Telegram, dei turni generati alla fase precedente in un canale privato.
Questa fase è la più semplice ed è gestita dagli script presenti nel package telegram, che inviano, oltre al PDF dei turni, anche il numero di turni che ogni animatore deve fare durante la settimana e gli animatori che la settimana successiva devono fare obbligatoriamente almeno un turno.