import type { AppTour } from '../types';

/**
 * Visite de la retenue à la source.
 *
 * L'écran le plus normé de l'application. Trois règles vérifiées dans les
 * services `App\Services\Retenue\*` :
 *
 *  - l'arithmétique **tronque au millime, elle n'arrondit jamais** — c'est ce
 *    que fait l'administration, et `brut = retenue + net` doit tomber juste ;
 *  - une déclaration est **mensuelle et unique** par franchise et par mois —
 *    y compris quand l'écran affiche « du … au … » : une plage n'est qu'une VUE
 *    sur plusieurs déclarations mensuelles, jamais une déclaration de plusieurs
 *    mois (la DGI reçoit un fichier par mois) ;
 *  - le dépôt est **irréversible** : il ne se corrige que par un rectificatif.
 *
 * Le bandeau d'avertissement se calcule sur TOUTE la période affichée alors que
 * le tableau est filtré : une ligne signalée peut donc être absente de l'écran,
 * et le bouton de correction efface alors les filtres pour la faire réapparaître.
 *
 * L'étape « dgi » (2026-09-24) explique ce que l'écran fait SANS qu'on le lui
 * demande : il relit lui-même le verdict de la DGI tant qu'un envoi l'attend
 * (`etat-dgi.tsx`, règles dans `depot.ts`). Un comportement automatique qu'on
 * ne dit pas passe pour une panne le jour où il ne se déclenche pas.
 *
 * L'étape « mois » (2026-09-28) accompagne la plage « du … au … » : ce que
 * disent les pastilles des mois, pourquoi il n'y a pas de statut global, et
 * pourquoi « Vérifier » s'y éteint. Une pastille AFFICHE un mois seul, elle
 * ne lance rien : « Vérifier » s'offre ensuite, sur un mois ouvert.
 *
 * Les étapes « import » et « envoiLot » (2026-10-08) : le fichier des paiements
 * tenu par la comptabilité. L'import ne crée rien avant l'aperçu confirmé ;
 * l'envoi enchaîne un dépôt par ligne et s'arrête à la première erreur
 * (`pages/retenue/import-sheet/lot-runner.ts`). Les pastilles de l'aperçu
 * portent une ancre (`retenue-import-apercu`) mais pas d'étape : elles vivent
 * dans un dialogue, et TOURS.md interdit d'en ouvrir un pendant la visite.
 *
 * Textes dans `lang/{fr,en}/tours.php`, clés `retenue.<key>.title|content`.
 */
export const retenueTour: AppTour = {
    id: 'retenue',
    components: ['retenue/index'],
    steps: [
        // Onglets du groupe, dans la barre du haut (FinanceBarre) : absents quand un seul écran est permis.
        { anchor: 'retenue-onglets', key: 'onglets', order: 5, optional: true },
        // La barre est TOUJOURS là : « Ajouter une ligne » n'y disparaît plus
        // sur un mois pas encore ouvert — il l'ouvre (`demarrerUneLigne`).
        // D'où l'absence de `optional` : une ancre manquante serait un bug.
        { anchor: 'retenue-actions', key: 'actions', order: 10 },
        // Le fichier des paiements — compte principal seulement (prop
        // `import_sheet`) : ailleurs le bouton n'existe pas, état normal.
        { anchor: 'retenue-import', key: 'import', order: 12, permission: 'retenue.create', optional: true },
        // L'envoi en lot n'existe que quand des lignes importées attendent.
        { anchor: 'retenue-envoi-lot', key: 'envoiLot', order: 14, permission: 'retenue_cloture.declare', optional: true },
        { anchor: 'retenue-filters', key: 'filters', order: 20 },
        // Les pastilles des mois — sur une PLAGE seulement, ouverte ou non (un
        // mois « Non ouvert » a sa pastille, et c'est vers elle que renvoie
        // « Vérifier » éteint). Un mois seul garde son en-tête d'avant, sans
        // pastille : `optional` pour ce seul état normal.
        { anchor: 'retenue-mois', key: 'mois', order: 22, optional: true },
        // L'état DGI et « Actualiser l'état DGI ». Absents — normalement — d'une
        // période dont aucun mois n'est ouvert, et de tout compte qui ne relit
        // pas la DGI (franchise, intégration coupée) : `can.actualiser_tej` faux.
        { anchor: 'retenue-dgi', key: 'dgi', order: 25, optional: true },
        // Absent — et c'est la bonne nouvelle — quand aucune ligne ne bloque le dépôt.
        { anchor: 'retenue-warning', key: 'warning', order: 30, optional: true },
        // Totaux et lignes : absents tant qu'aucun mois de la période n'est ouvert.
        { anchor: 'retenue-totals', key: 'totals', order: 40, optional: true },
        { anchor: 'retenue-lines', key: 'lines', order: 50, optional: true },
    ],
};