Attività pianificate e comandi console
Una parte rilevante del comportamento della piattaforma non dipende da richieste dei client ma da comandi console del backend, eseguiti a cadenza fissa oppure a mano. Questa pagina ne è il catalogo operativo: quali comandi girano da soli, quando e in quale ambiente; quali vanno lanciati a mano e con quali cautele; quali interruttori funzionali ne condizionano il comportamento. Come eseguirli su un ambiente è descritto in Rilascio e operatività con fpc.
Ogni comando, pianificato o manuale, è un'azione php yii <comando>/<azione> e ogni sua esecuzione viene registrata nella base dati con esito, durata e unità di lavoro non trattate, consultabili dall'area amministrativa come descritto in Area amministrativa e controllo operativo.
Come sono eseguite le attività pianificate
Le pianificazioni sono regole Amazon EventBridge definite nel repository FormandoPercorsi/aws, in infra/ecs/eventbridge/<env>/eventbridge-cron.yaml, una copia per ambiente. A ogni scadenza la regola avvia un task ECS effimero basato sull'immagine cron del backend, che esegue un solo comando e termina; i log finiscono nel gruppo CloudWatch /ecs/formandopercorsi-cron-<env>.
Tre conseguenze di questo modello:
- Gli orari sono in UTC. Le espressioni EventBridge non conoscono il fuso orario italiano: un'attività pianificata alle 02:00 UTC gira alle 03:00 in inverno e alle 04:00 in estate, ora di Roma. I comandi stessi, invece, ragionano in
Europe/Rome(per esempio quando stabiliscono quale sia «il mese precedente»). - Ogni esecuzione usa l'ultima immagine del proprio ambiente: un rilascio del backend è recepito dalla prima esecuzione successiva senza ridistribuire le regole.
- Le esecuzioni non si coordinano fra loro. Due attività pianificate allo stesso minuto girano in parallelo su task distinti; l'ordine fra attività dipendenti è garantito solo dagli orari scelti (la derivazione delle disponibilità alle 05:00 precede il ricalcolo del ranking alle 05:30).
Calendario delle attività pianificate
| Comando | Cadenza (UTC) | Sviluppo | Produzione | Che cosa fa |
|---|---|---|---|---|
lessons/check-expired-lessons | ogni 15 minuti (:00, :15, :30, :45) | attiva | attiva | Rete di sicurezza del webhook di pagamento: per gli ordini ancora in attesa oltre la durata della sessione (30 minuti) chiede a Stripe l'esito e applica lo stesso trattamento del webhook — conferma l'ordine pagato (lezioni pagate, documento, notifiche) o libera quello scaduto (slot, promozione, credito). Webhook e cron non elaborano mai due volte lo stesso ordine. |
lesson-reminder/send-reminders | ogni 15 minuti (:00, :15, :30, :45) | attiva | attiva | Invia il promemoria delle lezioni pagate che iniziano entro 25 minuti, alla famiglia e, se ha un proprio indirizzo e il consenso, allo studente. Se la lezione è l'ultima di un percorso formativo, invia anche al genitore l'invito al rinnovo; un errore nell'invito non blocca il promemoria. |
lesson-deletion-by-teacher/expire-deleted-lessons | ogni 15 minuti (:05, :20, :35, :50) | attiva | attiva | Risolve con il rimborso le lezioni cancellate dall'insegnante per le quali la famiglia non ha scelto entro la scadenza; si veda Modifiche e cancellazioni. |
lesson-modification/expire-modification-requests | ogni 15 minuti (:10, :25, :40, :55) | attiva | attiva | Fa decadere le richieste di modifica a cui la famiglia non ha risposto prima dell'inizio della lezione. |
tracking-aggregate/hourly | ogni ora al minuto 1 | attiva | attiva | Calcola le metriche orarie di utilizzo; si veda Tracking degli eventi e metriche. |
tracking-aggregate/daily | ogni giorno alle 00:05 | attiva | attiva | Calcola le metriche giornaliere. |
invoices/synchronize-teacher-invoices | ogni giorno alle 02:00 | attiva | attiva | Scarica i documenti da ACube e ne riallinea lo stato nella base dati (in attesa, inviato, scartato, consegnato…). |
availabilities/remove-old-availabilities | ogni giorno alle 02:00 | attiva | attiva | Rimuove le disponibilità derivate ormai passate e i gruppi di disponibilità rimasti vuoti. |
auth/cleanup-tokens | ogni giorno alle 03:00 | attiva | attiva | Elimina i refresh token revocati il cui periodo di validità di 30 giorni è trascorso. |
availabilities/create-derived-for-pending-availabilities | ogni giorno alle 05:00 | attiva | attiva | Deriva gli slot prenotabili dalle disponibilità dichiarate dagli insegnanti; si veda Disponibilità. |
teacher-score/recompute | ogni giorno alle 05:30 | attiva | in attivazione | Ricalcola gli indicatori usati per l'ordinamento in ricerca e attenua i contatori di esposizione; si veda Ordinamento dei risultati di ricerca. |
payments/process-daily-payouts | ogni giorno alle 07:00 | attiva | attiva | Liquidazione giornaliera, alla fascia base; si veda Pagamenti, payout e fatturazione. |
payments/process-monthly-payouts | giorno 7 di ogni mese alle 03:00 | attiva | attiva | Liquidazione mensile del mese precedente, con ricalcolo delle fasce e, se attivo, maturazione dell'indennizzo sulle lezioni gratuite. |
school-year/rollover | 1° settembre alle 04:00 | attiva | attiva | Passaggio di classe annuale; chi conclude un ciclo perde scuola e anno, e la famiglia deve riselezionarli prima di poter prenotare. |
In produzione la regola del ricalcolo notturno del ranking viene abilitata insieme alla promozione su main del codice che lo contiene: l'immagine di produzione attuale non ha ancora il comando, e una regola attiva prima fallirebbe ogni notte. Alla prima attivazione il comando va lanciato una volta a mano (prima con --dryRun=1), così che gli indicatori siano disponibili senza attendere la notte. Fino ad allora l'ordinamento degrada correttamente al punteggio iniziale e nessun insegnante sparisce dai risultati.
Le attività legate alla copertura assicurativa (insurance/expire, insurance/expire-unpaid, insurance/report-pending-compensations) non sono pianificate in nessun ambiente, coerentemente con la funzionalità, che è disattivata (si veda Interruttori funzionali). Vanno aggiunte alle regole EventBridge contestualmente alla sua attivazione, con le cadenze indicate in Copertura assicurativa.
Comandi da eseguire a mano
I comandi seguenti non sono pianificati. Vanno eseguiti con ./fpc run (o, in locale, con php yii dentro il container), e sono raggruppati per finalità. Dove esiste, la modalità di prova (--dryRun=1) calcola e riporta ciò che il comando farebbe senza scrivere nulla: è il primo passo consigliato prima di qualunque esecuzione su prod.
Rieseguire o recuperare un'elaborazione
| Comando | Uso |
|---|---|
payments/process-monthly-payouts [YYYY-MM] | Riesegue la liquidazione mensile di un mese determinato. Rieseguirla su un mese già liquidato è un'operazione prevista e non produce movimenti duplicati: vengono registrate solo le differenze di fascia. Il mese deve essere nel formato YYYY-MM e concluso: il mese in corso o futuro, o un formato diverso, termina con errore dati senza elaborare nulla. Con --currentMonth=1 è ammesso anche il mese in corso (solo lezioni già concluse) e con --competenceOnly=1 si liquidano solo le lezioni con scuola di competenza; vedi Liquidazione parziale. |
payments/preview-monthly-payouts [YYYY-MM] | Anteprima in sola lettura della precedente, con le stesse opzioni: per insegnante ore, fascia e lezioni che verrebbero liquidate. |
payments/process-daily-payouts | Riesegue la liquidazione giornaliera. |
tracking-aggregate/date <YYYY-MM-DD> | Ricalcola le metriche di una data, tipicamente per recuperare un intervallo non elaborato. |
teacher-score/recompute [--dryRun=1] | Ricalcolo completo del ranking; in prova riporta le variazioni più rilevanti. |
teacher-score/recompute-teacher <id> [--dryRun=1] | Ricalcolo per un singolo insegnante. |
school-year/rollover [data] [--dryRun=1] | Passaggio di classe riferito a una data diversa da oggi. |
invoices/synchronize-all-invoices-in-db | Per ogni documento presente nella base dati rilegge da ACube cliente e data. Utile dopo un'anomalia di sincronizzazione. |
Tariffe e scuole esterne
| Comando | Uso |
|---|---|
price-change/preview, schedule, list, show, cancel, revert, current | Aggiornamenti tariffari versionati; sono la controparte da riga di comando della pagina «Tariffe» dell'area amministrativa e condividono con essa le stesse regole. È l'unico modo supportato di modificare una tariffa: non vanno mai modificate a mano le righe tariffarie nella base dati. |
external-schools/add-external-school | Creazione interattiva di una scuola esterna. Richiede un terminale interattivo, quindi non è eseguibile con ./fpc run in modalità effimera: in alternativa si usa l'area amministrativa, che segue lo stesso percorso di creazione. |
external-schools/assign-cities <id>|--self=1 --city=A,B --province=C [--dryRun=1] | Assegna città di competenza a una scuola esterna. Idempotente; rifiuta una città già assegnata a un'altra scuola. |
external-schools/provision-self-school [--dryRun=1] | Crea l'utente e la scuola esterna attraverso cui FPC stessa opera come provider; si veda Scuole esterne, provider e incasso. |
I limiti delle fasce di ore non hanno un comando console: si modificano solo dall'area amministrativa.
Le numerazioni dei documenti non richiedono alcun intervento a inizio anno: sono distinte per anno e la prima emissione dell'anno nuovo apre da sola la serie che riparte da 1. Il vecchio comando che le azzerava è stato rimosso, perché azzerava anche le numerazioni dell'anno in corso producendo numeri duplicati.
Recuperi una tantum
Comandi scritti per riallineare dati storici dopo l'introduzione di una nuova colonna o di un nuovo comportamento. Sono idempotenti — una seconda esecuzione non modifica nulla — e vanno eseguiti una volta per ambiente, dopo le migrazioni che li rendono necessari.
| Comando | Uso |
|---|---|
lesson-cost-backfill/run [--dryRun=1] | Valorizza la ripartizione dei costi per lezione rimasta vuota sulle lezioni anteriori alla sua introduzione. |
lesson-deletion-reason-backfill/run [--dryRun=1] | Ricostruisce il motivo di cancellazione delle lezioni cancellate prima che venisse registrato. |
invoice-line-backfill/run [--dryRun=1] [--limit=N] [--pauseMs=200] | Rilegge da ACube il contenuto dei documenti già emessi (righe, dati per il PDF, emissione per conto terzi). Procede a ritmo controllato, può essere spezzato in lotti con --limit e si ferma dopo cinque documenti consecutivi a cui ACube non risponde, con codice di uscita 69: i restanti vengono ripresi all'esecuzione successiva. |
google-calendar-backfill/run | Crea i calendari Google mancanti degli insegnanti e accoda la sincronizzazione delle lezioni degli ultimi due mesi e future. |
google-calendar-backfill/hide-existing | Nasconde i calendari degli insegnanti dall'elenco dell'account di servizio. |
headquarter/backfill-managing-school [--dryRun=1] | Propone come sede gestita da ciascuna scuola esterna la sede che la scuola usa come propria base, scrivendo solo i casi non ambigui: salta la scuola della piattaforma, una sede mancante o eliminata, una sede che è la base di più scuole e una già gestita da un'altra scuola. Una seconda esecuzione riporta le proprie righe come già assegnate. La migrazione lascia la colonna vuota di proposito, quindi l'esito va rivisto prima di eseguirlo su prod. |
Cancellare un ordine
| Comando | Uso |
|---|---|
lesson-order/cancel <orderId> [opzioni] | Cancella un ordine intero già pagato e non erogato, emette la nota di credito e rimborsa la carta. Opzioni: --reason, --refundInsurance=1, --releasePromotion=1, --allowPast=1, --actorId, --dryRun=1, --interactive=0. Mostra l'anteprima e chiede conferma. Se una esecuzione si è fermata a metà, rilanciarlo con le stesse opzioni la riprende. Codici di uscita: 0 completato, nulla da fare, rifiutato o prova; 65 impedimento o ordine inesistente; 64 --actorId non valido; 75 ordine in uso da un'altra esecuzione, o opzioni diverse da quelle registrate; 70 un passo è fallito. |
lesson-order/cancellation-status <orderId> | Sola lettura: anteprima, oppure stato di avanzamento di una cancellazione già avviata. |
La procedura completa è in Modifiche e cancellazioni delle lezioni.
Comandi da usare con particolare cautela
| Comando | Cautela |
|---|---|
policy-update/notify-users | Invia a tutti gli utenti la notifica e l'email di aggiornamento dei termini. Va eseguito una sola volta per ogni aggiornamento, e mai in sviluppo con una base dati contenente indirizzi reali. Non registra alcuna accettazione e non pubblica alcuna versione: si veda Condizioni generali di contratto. |
invoices/force-update-all-business-registry-configurations | Riscrive su ACube la configurazione anagrafica di tutti gli insegnanti attivi. |
stripe-users-management/update-all-teacher-and-external-schools-accounts | Migrazione una tantum degli account Stripe connessi di insegnanti e scuole esterne verso la configurazione corrente; sposta saldi. Non va rieseguita. |
insurance/claim-replacement-report <da> <a> [--teacherId=] [--email=1] | Analisi di quanta parte degli slot liberati dai sinistri è stata ri-prenotata; di sola lettura, ma rilevante solo con l'assicurazione attiva. |
Interruttori funzionali
Il comportamento di diversi comandi dipende da interruttori definiti nei parametri dell'applicazione. Sono parte del codice, quindi identici in tutti gli ambienti a parità di versione distribuita: cambiarli richiede una modifica al backend e un rilascio (si veda Ambienti di sviluppo e produzione). Lo stato attuale sul branch develop:
| Interruttore | Stato | Effetto |
|---|---|---|
| Copertura assicurativa | spento | La copertura non è proposta alla prenotazione; le attività di scadenza non sono pianificate. Si veda Copertura assicurativa. |
| Credito degli insegnanti | acceso | Sulle lezioni incassate dall'insegnante la liquidazione gli fa assorbire lo sconto della famiglia o della promozione e gli matura un credito di pari importo; quando incassa la scuola la ripartizione resta quella precedente. Spento, nessuna maturazione. Si veda Crediti degli insegnanti. |
| Indennizzo sulle lezioni gratuite | spento | Efficace solo con il credito degli insegnanti acceso; l'importo orario vale zero finché non viene fissato. Si veda Crediti degli insegnanti. |
| Programma referral | acceso | Spento, non vengono più riconosciuti crediti di benvenuto né alla famiglia invitante; la restituzione del credito sulle lezioni rimborsate resta attiva. Si veda Crediti e programma referral. |
| Ordinamento algoritmico | acceso | Pesi e saturazioni sono anch'essi parametri; cambiarli richiede un rilascio e un ricalcolo, perché i pesi della parte precalcolata sono incorporati nel punteggio memorizzato. |
| PDF dei documenti generati internamente | acceso | Spento, i PDF tornano a essere quelli di ACube. Si veda Documenti fiscali e ricevute. |
| Ricevute occasionali: insegnante sempre provider | acceso | Spento, torna il giro in cui la scuola esterna incassa anche per l'insegnante occasionale. |
| Ricevute occasionali: marca da bollo apposta da FPC | acceso | Richiede comunque la delega del singolo insegnante. |
| Ricevute occasionali: bollo virtuale | spento | Richiede anche l'autorizzazione (BOLLO_VIRTUAL_AUTH_*) e la delega del singolo insegnante. |
| Ritenuta d'acconto trattenuta sui trasferimenti | spento | La ritenuta è esposta in ricevuta ma il compenso è trasferito al lordo. |
| Pacchetti con insegnanti occasionali | spento |
Alcuni interruttori — in particolare il credito degli insegnanti — spostano denaro fra FPC, scuole e insegnanti: la loro attivazione va preceduta da una liquidazione di verifica in un ambiente non di produzione, e non coincide con un rilascio qualsiasi.