Logique et automatisation

L'app montre déjà des données et laisse les modifier. Il manque la partie qui travaille toute seule : un script qui, tous les matins, regarde le pipeline, compte ce qui est ouvert et consigne les clôtures prévues pour la semaine.

Dans cette étape, vous écrivez ce script en Python, vous l'exécutez à la main pour voir le résultat, et vous lui fixez une heure — tous les jours à 07:00.

#Ce que le script va faire

Le atualizar_indicadores répond à trois questions, et les renvoie dans un résultat qui reste dans l'historique :

Question	Ce qu'il renvoie
Combien d'opportunités sont ouvertes ?	oportunidades_abertas
Combien vaut le pipeline ?	valor_pipeline
Combien de clôtures sont prévues pour les 7 prochains jours ?	fechos_proximos_7_dias

En plus du résultat, il écrit des logs — une ligne par clôture de la semaine — pour que celui qui ouvre l'historique comprenne, sans calcul, ce qui était prévu ce jour-là.

#Créer le script

1. Choisissez le panneau Code dans la barre latérale.
2. Sur la ligne Scripts, cliquez sur le + (Nouveau script). La boîte de dialogue Nouveau script s'ouvre — « Choisissez le runtime et créez — le code se modifie ensuite, avec le contrat sous les yeux. »
3. Dans Nom, écrivez atualizar_indicadores. Le nom identifie le script partout — dans les planifications, dans les étapes d'API, dans les dépendances d'autres scripts.
4. Runtime est fixé sur Python.
5. Dans Description, écrivez Recalcula os indicadores comerciais e avisa quando há fechos para esta semana.
6. Dans Temps limite, laissez 1 minute. C'est le plafond de l'exécution : passé ce temps, la plateforme coupe.
7. Cliquez sur Créer le script. L'éditeur s'ouvre avec le main.py prêt.

#Écrire le main.py

Le contrat d'un script est court : une fonction main(input) qui renvoie quelque chose. Ce que vous renvoyez reste dans l'historique des exécutions et, si le script est appelé par une API, c'est sa réponse.

Écrivez ceci dans l'éditeur :

from datetime import date, timedelta

from api_manager import db, log


def main(input):
    """Recalcule les indicateurs du tableau de bord commercial.

    S'exécute tous les jours à 7h00 (planification "Indicadores diários") et
    renvoie le résumé — l'historique des exécutions garde ainsi un
    enregistrement lisible par jour.
    """
    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és /", abertas["total"], "EUR")
    for op in fechos_semana:
        log("clôture cette semaine :", op["titulo"], "(", op["data_fecho"], ")")

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

Quatre choses à retenir de ce code :

Ligne	Ce qu'elle fait
from api_manager import db, log	L'accès de la plateforme : db ouvre des bases de données, log écrit dans l'historique.
db("Dados CRM")	La base de données par le nom interne du datasource — le même que celui enregistré à l'étape du modèle. Changez ce nom là-bas et cette ligne cesse de fonctionner.
crm.query(sql, [valeurs])	Requête paramétrée. Les valeurs voyagent toujours à part de la requête — jamais collées au texte.
return { … }	Le résultat de l'exécution. Il reste dans l'historique et c'est ce qu'une API renverrait.

L'input que la fonction reçoit apporte les arguments de l'exécution — ceux d'une API, ceux d'une planification ou ceux que vous écrirez à la main tout à l'heure. Ici nous n'en utilisons aucun.

#Exécuter le script à la main

1. En haut de l'éditeur, cliquez sur Exécuter maintenant.
2. La boîte de dialogue s'ouvre — « Définissez les arguments de cette exécution (facultatif). Les valeurs arrivent au script sous forme de texte. » Nous n'en avons besoin d'aucun.
3. Cliquez sur Exécuter.

Le panneau Résultat de l'exécution, en bas, se remplit : le badge Succès avec la durée, la valeur renvoyée en JSON et le bloc Logs avec les lignes que le log() a écrites.

#L'historique des exécutions

Le résultat dans l'éditeur n'est que celui de la session en cours. L'historique complet est dans le bouton Exécutions, à côté de l' Exécuter maintenant :

Chaque ligne dit Début, Source (Manuel, quand c'était vous ; Planification, quand c'était l'heure fixée), État et Durée, et le lien Détails ouvre l'exécution : les arguments, le résultat renvoyé et les logs de ce passage précis. C'est par là qu'on comprend, trois semaines plus tard, ce que le script a vu le matin où personne ne regardait.

#Planifier pour tous les matins

Un script qui ne s'exécute que quand quelqu'un appuie sur le bouton n'est pas de l'automatisation. Il est temps de lui fixer une heure.

1. Dans l'arborescence du panneau Code, dépliez le nœud du script atualizar_indicadores. Trois sections apparaissent : Fichiers, Dépendances et Planifications.
2. Passez la souris sur Planifications et cliquez sur le + (Nouvelle planification).
3. Donnez-lui le nom Indicadores diários et créez. L'éditeur de la planification s'ouvre dans un onglet.
4. Dans Fréquence, choisissez À des moments précis — « À une heure du jour, les jours que vous choisissez. »
5. Dans Répète, choisissez Tous les jours (les jours choisis).
6. Dans À l'heure, écrivez 07:00.
7. Dans Jours, laissez les sept sélectionnés (ou cliquez sur Ouvrés si le week-end n'a pas d'intérêt).
8. Dans Fuseau horaire, choisissez Europe/Lisbon. C'est le fuseau qui décide de ce que sont « sept heures du matin » — sans lui, l'heure juste bouge au changement d'heure.
9. Dans Si une exécution est manquée, choisissez Ignorer.
10. Vérifiez que l'interrupteur Actif est activé et cliquez sur Enregistrer.

#Les trois fréquences

Fréquence	Quand l'utiliser
Répéter	Toutes les N minutes ou heures, sans arrêt. Synchronisations, sondages.
À des moments précis	À une heure du jour, les jours choisis. C'est notre cas — et le plus courant.
Fenêtre de surveillance	Sonde toutes les N minutes entre deux heures et s'arrête quand le travail du jour est fait. Pour attendre un fichier qui arrive « le matin, à des heures variables ».

Qui préfère écrire l'expression de planification à la main a le lien Écrire l'expression à la main sous les trois options.

#Quoi faire de ce qui n'a pas été exécuté

Le serveur était à l'arrêt à sept heures du matin. À son retour, qu'arrive-t-il à l'occurrence manquée ? C'est ce que décide Si une exécution est manquée :

Option	Ce qu'elle fait
Ignorer	Ne rattrape pas. Il reste consigné qu'elle s'est perdue.
Seulement la plus récente	Rattrape la dernière restée en plan ; les précédentes sont consignées comme manquées.
Toutes	Rattrape toutes celles restées en plan, dans l'ordre où elles étaient prévues.

Pour un résumé quotidien, Ignorer est le bon choix : exécuter le résumé du mardi le jeudi ne sert à personne. Pour une facturation mensuelle, Toutes a tout son sens.

#Le panneau d'exécutions de la planification

À droite de l'éditeur se trouve le panneau Exécutions, avec les heures prévues et ce qui est arrivé à chacune : Effectuée, En attente, Manquée ou Ignorée.

#Et ensuite ?

Le script est prêt pour plus que l'heure fixée : il peut être une étape d'une API (pour que le résumé soit calculé à la demande), il peut appeler d'autres scripts comme dépendance, et il peut installer les packages Python dont il a besoin. Le chapitre Scripts parcourt tout cela, et le SDK des scripts documente api_manager — base de données, fichiers, secrets, notifications et appels HTTP.

#Pourquoi pas… ?

• Pourquoi le script échoue-t-il avec « datasource introuvable » ? Le nom dans db("…") doit être exactement le Nom interne du datasource, majuscules comprises.
• Pourquoi je ne vois pas le bouton Exécuter maintenant ? Le script est inactif — activez l'interrupteur en haut.
• Pourquoi l'exécution a-t-elle été coupée en plein milieu ? Elle a atteint le Temps limite. Soit le script prend vraiment ce temps, et vous augmentez la limite, soit il fait trop de travail pour l'endroit d'où il est appelé.
• Pourquoi la planification ne s'est-elle jamais exécutée ? Regardez, dans l'ordre : la planification est-elle Active ? Le script est-il Actif ? Le planificateur tourne-t-il sur cette installation ? Et le Fuseau horaire est-il bien celui que vous croyez ?

Le CRM est complet. Il reste à le mettre en ligne : publier et utiliser.