Dataviz finances Montreuil

Contribuer

Au vu du scope du projet et de sa spécificité franco-française, il est décidé que le readme, les issues, pull requests et messages de commit sont à écrire en français.

Le code et les commentaires sont à écrire en anglais.

Documents de travail

• 📋 Brief projet
• ⏳ Dépenses (temps passé par chacun·e d'entre nous)
• 📝 Journal de bord (chacun·e le remplit à son rythme)
• 🗂 Documentation (comptes rendus, entretiens, etc.)
• 🔤 Glossaire
• 🔢 Plan d'itérations (vue priorisée)
• 🗄 Actions à mener (vue non-priorisée)
• 🎨 Maquettes (navigation, userflow, analyse des contenus, écrans en cours, etc.)

Présentation de l'outil

L’outil créé est une application 100% front-end chargée à partir de fichiers statiques HTML, CSS, JS, images, etc. Cette application utilise la bibliothèque React.js.

Le code source de référence est actuellement sur github à l’adresse suivante : github.com/dtc-innovation/dataviz-finances-montreuil.

L'outil est composé comme suit :

• 📊 Visualisation grand public : la visualisation telle qu'elle sera visible par le grand public ;
• 📋 Fonctions d'agrégation : visualisation de l'état de partition des fonctions d'agrégation
• 🔢 Test des formules : formules d'agrégation interactives

Intégration sur un site web

<div class="finance-dataviz-container"></div>
<link rel="stylesheet" href="https://dtc-innovation.github.io/dataviz-finances-montreuil/build/public.css">
<script defer crossorigin="anonymous" src="https://polyfill.io/v3/polyfill.min.js?flags=gated&features=Map%2CSet%2CIntl%2CArray.prototype.flat%2CArray.prototype.flatMap%2Ces2017%2Ces2016%2Ces2015"></script>
<script defer src="https://dtc-innovation.github.io/dataviz-finances-montreuil/build/dataviz-finance-bundle.js"></script>

Compatibilité navigateur

Minima:

• Edge
• Firefox Extended Support Release (ESR)
• Chrome
• navigateurs mobiles

Installer le projet

L'installation de node@>=12 est nécessaire avant de continuer.

Il faut (forker et) cloner ce dépôt pour procéder à l'installation des dépendances du projet :

npm install

Faire fonctionner le projet sur son ordinateur

La commande suivante reconstruit les fichiers d'interface dès qu'un fichier source est modifié. Les composants web sont visualisables dans un navigateur web :

npm start

Deux adresses sont ensuite accessibles :

• localhost:3000 : visualisation nature/fonction ;
• localhost:3000/public/ : l'exploration éditorialisée, à destination du grand public.

Anatomie des répertoires

• ./build : fichiers de données et de l'application web
• ./data
  • ./data/finances/CA : comptes administratifs anonymisés (format XML DocumentBudgetaire)
  • ./data/finances/plansDeCompte : plans de compte (format XML)
  • ./data/texts : éditorialisation des fonctions et natures (format CSV)
• ./fonctions.html : outil de visualisation des fonctions
• ./images : ressources iconographiques
• ./index.html : squelette de la visualisation nature/fonction
• ./public/index.html : squelette de l'exploration éditorialisée
• ./src
  • ./src/finance-overview : composants pour la visualisation nature/fonction
  • ./src/public : composants de l'exploration éditorialisée
  • ./src/shared : composants partagés
• ./tests : assurance qualité de calculs critiques
• ./tools : outils en ligne de commande pour transformer des documents source en données optimisées

Intégration continue

L'intégration continue est automatise les éléments suivants :

• exécution des tests sur chaque branche ;
• déploiement de la démo depuis master ;

Le suivi des builds est assuré par Travis CI.

Actionner le projet

En se rendant sur Travis CI :

1. se connecter avec son compte GitHub (Sign in with Github) ;
2. se rendre sur son profil Travis CI ;
3. cocher la case du projet datalocale/dataviz-finances-gironde.

Reste ensuite à configurer l'outil.

Générer un token GitHub

Un Personal access token est nécessaire pour que l'automate d'intégration continue puisse publier la démo.

🔓 Générer un nouveau token

Le token créé est à renseigner dans la configuration Travis CI.

Configurer TravisCI

Deux variables d'environnement doivent être configurées dans l'onglet Settings :

Name	Value	Display value in build logs
GH_TOKEN	voir Générer un token	Off

Déploiement

Remarque : les étapes de la section Installer le projet doivent avoir été suivies au préalable.

Il existe 2 environnements :

• démo autonome : npm run build (construite par l'intégration continue)
• développement : npm start

Variable d'environnement	Valeur par défaut	Utilité
BASE_URL	https://dtc-innovation.github.io/dataviz-finances-montreuil	Explicite où sont hébergées les données et assets de l'application.
NODE_ENV	undefined	Optimise les artéfacts lorsque la valeur est production.

Mise à jour des données financières

Les actions nécessaires à la mise à jour des contenus sont de plusieurs nature :

• mise à jour des labels finances
• mise à jour des données budgétaires
• mise à jour des règles d'agrégats

Les labels finances

Actuellement les labels des articles de la norme comptable sont stockés dans un fichier csv. Ce fichier est mis à disposition par la direction des finances au format Excel.

Ce fichier Excel se convertit en CSV à l'aide de csvkit :

in2csv --skip-lines 1 \
        --no-inference \
        --sheet "Table_Natures" \
        "data/NATURES - FONCTIONS v9_2.xlsx" > "data/agrégation-montreuil.csv"

Les données budgétaires

Pour mettre à jour l'exercice budgétaire rendu visible dans la page d'accueil les étapes suivantes sont actuellement nécessaires

1. Mettre le fichier XML du nouveau CA dans data/finances/CA
2. Lancer la commande npm run dl:plans-de-compte pour ajouter automatiquement le bon plan de compte dans data/finances/planDeComptes [^plan-de-compte].

Les données d'agrégats

La dataviz finances est basé sur plusieurs éléments contribuant à son interopérabilité et à sa réutilisabilité :

• appui sur la norme comptable M14 et le plan de compte associé
• appui sur le schéma XSD ToTem
• déploiement continu d'une SPA (Single page application) qui peut être intégré à n'importe quel type de publication (site web autonome, page dans un gestionnaire de contenu)

En plus des présentations par fonctions ou nature M52, le Département de la Gironde présente ses comptes sous un format dit “agrégé”. Ils s’agit d’une centaine de catégories. Il existe (à une petite exception près) une association qui permet de passer d’un document budgétaire en M52 à un document agrégé.

Pour faciliter la gestion actuelle, un tableur numérique collaboratif permet l'écriture des formules en langage métier

https://docs.google.com/spreadsheets/d/1vb9YLAcjjkW1QA5bkuOpYOmD9y34YHwJAcgzepnLXxw/edit#gid=568066882

Cette association est encodée en JavaScript dans les deux fichier suivants :

https://github.com/datalocale/dataviz-finances-gironde/blob/master/src/shared/js/finance/m52ToAggregated.js https://github.com/datalocale/dataviz-finances-gironde/blob/master/src/shared/js/finance/hierarchicalAggregated.js

Par ailleurs, il a été découvert début octobre 2017 que dans de rares cas, un montant associé à une même ligne M52 (fonction/article) se découpe dans 2 agrégats différents. Pour résoudre ce cas, un fichier de “correction” a été ajouté. Il peut être trouvé ici : https://github.com/datalocale/dataviz-finances-gironde/blob/master/data/finances/corrections-agregation.csv

Dans ce fichier CSV, chaque ligne correspond à l’assignation d’une ligne M52 à un agrégat pour un exercice donné

Pour réduire la charge de travail nécesaire, un prototype d'outil permettant de visualiser le résultat des formules a été développé

https://davidbruant.github.io/formule-doc-budg/

Avec quelques évolutions, il pourrait permettre d'enregistrer les formules saisies directement dans le code de l'application.

Les données éditoriales

L’outil contient des pages dites “focus” qui permettent au Département de créer du contenu plus éditorialisé pour mettre en valeur ses actions et parler un peu moins de finance et un peu plus de l’action qui en découle.

Licence

MIT