Logica e automazione

L'app mostra già i dati e lascia modificarli. Manca la parte che lavora da sola: uno script che, tutte le mattine, guarda il pipeline, conta ciò che è aperto e registra le chiusure previste per la settimana.

In questa tappa scrivi quello script in Python, lo esegui a mano per vederne il risultato, e gli fissi un orario — tutti i giorni alle 07:00.

#Che cosa farà lo script

L'atualizar_indicadores risponde a tre domande, e le restituisce in un esito che resta nella cronologia:

Domanda	Che cosa restituisce
Quante opportunità sono aperte?	oportunidades_abertas
Quanto vale il pipeline?	valor_pipeline
Quante chiusure sono previste per i prossimi 7 giorni?	fechos_proximos_7_dias

Oltre all'esito, scrive dei log — una riga per ogni chiusura della settimana — perché chi apre la cronologia capisca, senza fare conti, che cosa era in programma quel giorno.

#Creare lo script

1. Scegli il pannello Codice nella barra laterale.
2. Sulla riga Script, clicca sul + (Nuovo script). Si apre la finestra Nuovo script — "Scegli il runtime e crea — il codice si modifica subito dopo, con il contratto sotto gli occhi."
3. In Nome, scrivi atualizar_indicadores. Il nome identifica lo script ovunque — nelle pianificazioni, nei passi di API, nelle dipendenze di altri script.
4. Runtime è fisso su Python.
5. In Descrizione, scrivi Ricalcola gli indicatori commerciali e avvisa quando ci sono chiusure per questa settimana.
6. In Limite di tempo, lascia 1 minuto. È il tetto dell'esecuzione: passato quel tempo, la piattaforma interrompe.
7. Clicca su Crea script. L'editor si apre con il main.py pronto.

#Scrivere il main.py

Il contratto di uno script è breve: una funzione main(input) che restituisce qualcosa. Quello che restituisci resta nella cronologia delle esecuzioni e, se lo script viene chiamato da un'API, è la sua risposta.

Scrivi questo nell'editor:

from datetime import date, timedelta

from api_manager import db, log


def main(input):
    """Ricalcola gli indicatori del cruscotto commerciale.

    Viene eseguito tutti i giorni alle 7:00 (pianificazione "Indicatori
    giornalieri") e restituisce il riepilogo — la cronologia delle
    esecuzioni conserva un registro leggibile per ogni giorno.
    """
    crm = db("Dados CRM")

    abertas = crm.query(
        "select count(*) as n, coalesce(sum(valor), 0) as total "
        "from oportunidades where fase not in ('fechada_ganha', 'fechada_perdida')"
    )[0]

    limite = (date.today() + timedelta(days=7)).isoformat()
    fechos_semana = crm.query(
        "select titulo, data_fecho from oportunidades "
        "where fase not in ('fechada_ganha', 'fechada_perdida') "
        "and data_fecho <= ? order by data_fecho",
        [limite],
    )

    log("pipeline:", abertas["n"], "opportunità /", abertas["total"], "EUR")
    for op in fechos_semana:
        log("chiusura questa settimana:", op["titulo"], "(", op["data_fecho"], ")")

    return {
        "oportunidades_abertas": abertas["n"],
        "valor_pipeline": abertas["total"],
        "fechos_proximos_7_dias": len(fechos_semana),
    }

Quattro cose da ricordare di questo codice:

Riga	Che cosa fa
from api_manager import db, log	L'accesso della piattaforma: db apre i database, log scrive nella cronologia.
db("Dados CRM")	Il database per nome interno del datasource — lo stesso che hai registrato nella tappa del modello. Cambia il nome lì e questa riga smette di funzionare.
crm.query(sql, [valori])	Query parametrizzata. I valori vanno sempre separati dalla query — mai incollati al testo.
return { … }	L'esito dell'esecuzione. Resta nella cronologia ed è ciò che un'API restituirebbe.

L'input che la funzione riceve porta gli argomenti dell'esecuzione — quelli di un'API, quelli di una pianificazione o quelli che scrivi a mano qui di seguito. Qui non ne usiamo nessuno.

#Eseguire lo script a mano

1. In cima all'editor, clicca su Esegui ora.
2. Si apre la finestra — "Definisci gli argomenti di questa esecuzione (opzionale). I valori arrivano allo script come testo." Non ce ne serve nessuno.
3. Clicca su Esegui.

Il pannello Esito dell'esecuzione, in basso, si riempie: il contrassegno Riuscito con la durata, il valore restituito in JSON e il blocco Log con le righe scritte dal log().

#La cronologia delle esecuzioni

L'esito nell'editor è solo quello della sessione attuale. La cronologia completa sta nel pulsante Esecuzioni, accanto all'Esegui ora:

Ogni riga dice Inizio, Origine (Manuale, quando sei stato tu; Pianificazione, quando è stata l'ora fissata), Stato e Durata, e il link Dettagli apre l'esecuzione: gli argomenti, l'esito restituito e i log di quella corsa in concreto. È da qui che si capisce, tre settimane dopo, che cosa ha visto lo script la mattina in cui nessuno guardava.

#Pianificare per tutte le mattine

Uno script che gira solo quando qualcuno preme un pulsante non è automazione. È il momento di fissargli un'ora.

1. Nell'albero del pannello Codice, espandi il nodo dello script atualizar_indicadores. Appaiono tre sezioni: File, Dipendenze e Pianificazioni.
2. Passa il mouse su Pianificazioni e clicca sul + (Nuova pianificazione).
3. Dalle il nome Indicatori giornalieri e crea. L'editor della pianificazione si apre in una scheda.
4. In Frequenza, scegli In momenti precisi — "A un'ora del giorno, nei giorni che scegli."
5. In Ripete, scegli Tutti i giorni (nei giorni scelti).
6. In All'ora, scrivi 07:00.
7. In Giorni, lascia tutti e sette selezionati (o clicca su Feriali se il fine settimana non interessa).
8. In Fuso orario, scegli Europe/Lisbon. È il fuso a decidere che cosa sono "le sette del mattino" — senza di lui, l'ora giusta cambia con il cambio dell'ora.
9. In Se un'esecuzione viene persa, scegli Ignora.
10. Verifica che l'interruttore Attivo sia acceso e clicca su Salva.

#Le tre frequenze

Frequenza	Quando usarla
Ripetere	Ogni N minuti o ore, senza sosta. Sincronizzazioni, sondaggi.
In momenti precisi	A un'ora del giorno, nei giorni scelti. È il nostro caso — e il più comune.
Finestra di sorveglianza	Sonda ogni N minuti fra due orari e si ferma quando il lavoro del giorno è fatto. Per aspettare un file che arriva "di mattina, a orari variabili".

Chi preferisce scrivere a mano l'espressione di pianificazione ha il link Scrivere l'espressione a mano sotto le tre opzioni.

#Che cosa fare con ciò che non è stato eseguito

Il server era giù alle sette del mattino. Quando torna, che cosa succede all'occorrenza fallita? È quello che decide Se un'esecuzione viene persa:

Opzione	Che cosa fa
Ignora	Non recupera. Resta registrato che è andata persa.
Solo la più recente	Recupera l'ultima rimasta indietro; le precedenti restano registrate come perse.
Tutte	Recupera tutte quelle rimaste indietro, nell'ordine in cui erano fissate.

Per un riepilogo giornaliero, Ignora è la scelta giusta: eseguire il riepilogo di martedì il giovedì non serve a nessuno. Per una fatturazione mensile, Tutte ha tutto il senso del mondo.

#Il pannello delle esecuzioni della pianificazione

A destra dell'editor c'è il pannello Esecuzioni, con gli orari previsti e quello che è successo a ciascuno: Fatta, Da fare, Persa o Saltata.

#E poi?

Lo script è pronto per molto più dell'ora fissata: può essere un passo di un'API (perché il riepilogo venga calcolato su richiesta), può chiamare altri script come dipendenza, e può installare i package Python di cui ha bisogno. Il capitolo Script percorre tutto questo, e l'SDK degli script documenta l'api_manager — database, file, secrets, notifiche e chiamate HTTP.

#Perché non…?

• Perché lo script fallisce con "datasource non trovato"? Il nome in db("…") deve essere esattamente il Nome interno del datasource, maiuscole comprese.
• Perché non vedo il pulsante Esegui ora? Lo script è inattivo — accendi l'interruttore in alto.
• Perché l'esecuzione è stata interrotta a metà? Ha sbattuto contro il Limite di tempo. O lo script ci mette davvero tanto, e allora alzi il limite, oppure sta facendo troppo lavoro per il posto da cui viene chiamato.
• Perché la pianificazione non è mai partita? Controlla, in ordine: la pianificazione è Attiva? Lo script è Attivo? Il pianificatore è in esecuzione su questa installazione? E il Fuso orario è quello che pensi che sia?

Il CRM è completo. Manca metterlo online: pubblicare e usare.