MyMoney Documentation Version 1.0 Yannick Chabbert 20 June 2016
Table des matières 1 Contenus 3 1.1 Installation................................................ 3 1.1.1 Prérequis............................................ 3 1.1.2 Déploiement.......................................... 3 Backend.............................................. 3 Frontend............................................. 4 1.1.3 Internationalisation....................................... 5 1.1.4 Démo.............................................. 6 1.1.5 Tests............................................... 6 Tox................................................ 6 Manuellement.......................................... 6 1.2 Utilisateurs................................................ 7 1.2.1 Création d un utilisateur basique................................ 7 1.2.2 Permissions........................................... 7 1.2.3 Utilisateur anonyme....................................... 7 1.3 Compte bancaires............................................ 7 1.4 Étiquettes................................................. 8 1.5 Planifications............................................... 8 1.5.1 Champs............................................. 8 Période.............................................. 8 Récurrence............................................ 8 Date................................................ 9 Commencer maintenant..................................... 9 1.6 Transactions bancaires.......................................... 9 1.6.1 Champs............................................. 9 Statut............................................... 9 Drapeau pointé.......................................... 10 1.7 Statistiques................................................ 10 1.7.1 Proportionnel.......................................... 10 Filtre type : somme ou unitaire.................................. 10 1.8 Back-office................................................ 10 i
ii
Ceci est la documentation du projet MyMoney, application web de gestion de finance personnelle, construite avec le framework Django. Bien sûr, tout comme ce projet, cette documentation n est pas vraiment utile. C est surtout une bonne occasion pour apprendre Sphrinx et ReadTheDoc :) Table des matières 1
2 Table des matières
CHAPITRE 1 Contenus 1.1 Installation 1.1.1 Prérequis Python 3.4 (pas de compabitilité descendante) PostgreSQL uniquement (pas de support MySQL ou SQLite) 1.1.2 Déploiement Backend Le déploiement est similaire à d autres projets Django. Voici un bref résumé : 1. installer les paquets systèmes requis. Par exemple sur Debian : apt-get install python3 python3-dev postgresql-9.4 libpq-dev virtualenv 2. créer un cluster de base de données pour PostgreSQL ainsi qu un rôle et un propriétaire 3. créer un virtualenv : virtualenv <NAME> -p python3 4. installer les dépendances avec pip (voir Production ou Développement) 5. configurer les paramètres ( voir Production ou Développement) 6. exporter la variable d environnement DJANGO_SETTINGS_MODULE pour facilement utiliser manage.py avec les paramètres de production. Par exemple : export DJANGO_SETTINGS_MODULE="mymoney.settings.production" 7. importer le schéma SQL :./manage.py migrate 8. créer un super utilisateur :./manage.py createsuperuser Note : WSGI utilisera les paramètres production.py alors que manage.py utilisera local.py par défaut. 3
Production Installer les dépendances (dans un virtualenv) : pip install -r requirements/production.txt copier mymoney/settings/production.dist en mymoney/settings/production.py puis l éditer : cp mymoney/settings/production.dist mymoney/settings/production.py installer les librairies JS avant avec Bower (voir Frontend) puis collecter les fichiers statiques :./manage.py collectstatic exécuter la commande de vérification de Django puis appliquer des corrections si besoin :./manage.py check --deploy Configurer des tâches cron sur le serveur pour exécuter les commandes suivantes : dupliquer les transactions bancaires récurrentes./manage.py clonescheduled tâches de nettoyages (utile uniquement avec plusieurs comptes utilisateurs) :./manage.py deleteorphansbankaccounts À la racine du projet, le répertoire scripts fourni des scripts bash pour exécuter ces commandes. Par conséquent, vous pouvez les utiliser en créant des règles cron similaire à : 0 1 * * * ABSOLUTE_PATH/scripts/clonescheduled.sh <ABSOLUTE_PATH_TO_V_ENV> 0 2 * * * ABSOLUTE_PATH/scripts/deleteorphansbankaccounts.sh <ABSOLUTE_PATH_TO_V_ENV> Par exemple, créez un fichier à /etc/cron.d/clonescheduled, puis éditez : 0 2 * * * <USER> /ABSOLUTE_PATH/scripts/clonescheduled.sh <ABSOLUTE_PATH_TO_V_ENV> Développement Installer les dépendances : pip install -r requirements/local.txt copiez mymoney/settings/local.dist à mymoney/settings/local.py et éditez le. cp mymoney/settings/local.dist mymoney/settings/local.py Frontend 1. first intall npm (embed with nodejs) 2. install Bower with npm : npm install --production 3. À la racine du projet, exécutez la commande suivante pour installer les librairies JS requises :./node_modules/bower/bin/bower install --production 4 Chapitre 1. Contenus
Développement 1. install gulp globally to use it as a command line tool : npm install -g gulp 2. aller dans le répertoire racine du projet et installer les dépendances de gulp : npm install 3. une fois les paquets node installés en local dans./node_modules, vous devriez pouvoir exécuter les commandes gulp suivantes implémentées dans gulpfile.js : js : concatène et minifie le js css : concatène et minifie la css Pour exécuter toutes les commandes d un coup, à partir de la racine du projet, il suffit d éxecuter : gulp 1.1.3 Internationalisation 1. copiez mymoney/settings/l10n.dist à mymoney/settings/l10n.py et éditez le. cp mymoney/settings/l10n.dist mymoney/settings/l10n.py Plusieurs remarques sur les paramètres supplémentaires : USE_L10N_DIST : Faut-il ou non utiliser le fichier minifié qui inclut les traductions. Cela implique que le fichier minifié avec traductions a été généré avec gulp (mymoney.min.<langcode>.js). Si c est faux (par défaut), les fichiers JS de traductions seront chargés en plus. BOOTSTRAP_CALENDAR_LANGCODE : Si USE_L10N_DIST est faux, le code langue à utiliser pour charger le fichier de traduction à : mymoney/static/bower_components/bootstrap-calendar/js/language/<langcode>.js BOOTSTRAP_DATEPICKER_LANGCODE : Si USE_L10N_DIST est faux, le code langue à utiliser pour charger le fichier de traduction à : mymoney/static/bower_components/bootstrap-datepicker/js/locales/bootstrap-datepicke 2. éditez votre fichier de configuration finale pour utiliser le fichier de configuration l10n à la place : # from.base import * from.l10n import * 3. optionnellement, construisez le fichier JS minifié de la distribution pour votre langue. Pour y parvenir, vous devez d abord avoir gulp d installé. Voir la section Développement pour plus de détails à propos de gulp. La commande gulp js a des paramètres optionnels : --lang : le code langue IETF de la forme : xx-xx. Doit être le même que le paramètre Django LANGUAGE_CODE. --lang_bt_cal : La langue de Bootstrap calendar à utiliser. Pour connaître la liste des codes disponibles, jetez un oeil à : mymoney/static/bower_components/bootstrap-calendar/js/language/<langcode>.js --lang_bt_dp : le code langue de Bootstrap datepicker à utiliser. Attention actuellement, le code langue est de la forme xx et non xx-xx. Pour connaître la liste des codes langues disponibles, regardez à : mymoney/static/bower_components/bootstrap-datepicker/js/locales/bootstrap-datepicke Par exemple pour un fichier JS minifié français, vous devriez exécuter : gulp js --lang=fr-fr --lang_bt_cal=fr-fr --lang_bt_dp=fr 1.1. Installation 5
Note : Il semble trop verbeux d avoir 3 arguments pour la langue mais malheureusement, aucun d entre eux n utilisent les mêmes... Note : Les traductions en français sont uniquement supportées pour le moment. Mais toutes contributions sont les bienvenues! 1.1.4 Démo Pour un aperçu rapide, vous pouvez générer des données avec la commande suivante :./manage.py demo Vous pouvez aussi nettoyer les données relatives aux modèles du projet avec :./manage.py demo --purge 1.1.5 Tests Qu importe la méthode utilisée, vous devez créer un fichier de configuration de test. Copiez mymoney/settings/test.dist à mymoney/settings/test.py et éditez le. cp mymoney/settings/test.dist mymoney/settings/test.py Tox Vous pouvez utiliser Tox. À la racine du projet sans virtualenv, exécutez juste : tox En coulisses, plusieurs testenv sont exécutés : pylama isort Sphinx suite de tests avec couverture et rapport Manuellement 1. installer les dépendances : pip install -r requirements/test.txt 2. puis exécutez les tests :./manage.py test --settings=mymoney.settings.test mymoney 6 Chapitre 1. Contenus
1.2 Utilisateurs 1.2.1 Création d un utilisateur basique Afin de ne pas mélanger les permissions utilisateur d un compte basique et d un compte super utilisateur, vous devez créer et utiliser uniquement un compte utilisateur basique. Sinon, si vous utilisez un compte super utilisateur en frontoffice et que vous essayez de créer un compte bancaire, vous ne pourrez pas voir votre propre compte dans la liste des propriétaires. Note : C est intentionnel : un utilisateur basique ne peut pas ajouter un super utilisateur ou un membre de l équipe comme propriétaire du compte bancaire. 1. créez un super utilisateur si ca n est pas déjà fait :./manage.py createsuperuser 2. connectez-vous au back-office de Django afin de créer un compte utilisateur Avertissement : N oubliez pas d assigner les permissions requises (commençant par bank). 1.2.2 Permissions Chaque permissions sont hérités du modèle par défaut de Django (ajouter, changer, supprimer). Cependant, voici des permissions supplémentaires : administer owners : autorise un utilisateur à administrer les propriétaires de ces compte bancaires 1.2.3 Utilisateur anonyme Parce que l authentification est requise, un utilisateur anonyme peut uniquement accéder aux urls /login (LOGIN_URL) et au back-office (ADMIN_BASE_URL). Toutes tentatives d accès à d autres urls en tant qu utilisateur anonyme seront redirigées sur la page de connexion. 1.3 Compte bancaires La première chose que vous devez faire est de créer un compte bancaire. Après s être authentifié, vous devriez être sur la page /bank-account/. Vous pouvez voir les liens d actions en haut à droite. Cliquez sur Ajouter. Une fois crée, vous devriez le voir dans la liste. Cliquez dessus. Vous serez dirigé sur la page d aperçu du compte bancaire. À partir de cette page, vous pouvez : éditer le compte bancaire supprimer le compte bancaire (via les liens d actions) planifier des transactions bancaires pour ce compte bancaire voir les statistiques de ce compte bancaire ajouter des transactions bancaires pour ce compte bancaire filtrer les résultats avec un formulaire appliquer certaines actions sur les transactions bancaires 1.2. Utilisateurs 7
Note : Si vous avez seulement un compte bancaire, vous serez redirigé sur sa page après vous être authentifié. Sinon, vous serez redirigé sur la page qui liste les comptes bancaires à /bank-account/. 1.4 Étiquettes La seconde étape pourrait être de créer des étiquettes. Dans la barre de navigation, dans la section étiquettes, cliquez sur Mes étiquettes (/bank-transaction-tag/list/). Vous êtes sur la page d aperçu des étiquettes. Sur cette page, vous pouvez appliquer les actions suivantes sur les étiquettes : ajouter éditer supprimer Note : Les propriétaires d un même compte bancaire que le votre peuvent aussi voir/utiliser vos étiquettes (donc même si ils n en sont pas les propriétaires directement). Cependant, les utilisateurs sans relation avec vous (c-a-d n étant pas propriétaire commun) ne peuvent pas voir/utiliser vos étiquettes. 1.5 Planifications Avant même d essayer de créer de nouvelles transactions, une meilleure approche serait de créer d abord des planifications (pour des paiments récurrents par exemple). Sur la page du compte bancaire, cliquez sur le lien Planifier de l onglet du menu. Vous êtes redirigé sur la page d aperçu des planifications. Sur cette page, vous pouvez : voir un résumé périodique débit/crédit ajouter/modifier/supprimer des planifications 1.5.1 Champs Certains champs nécessitent quelques explications : Période Pour le moment, il y a deux types de périodes : hebdomadaire : duplique les transactions bancaires toutes les semaines à partir d une date, dépendant de la localisation (premier jour de la semaine). mensuelle : duplique les transactions bancaires tous les mois à partir d une date. Pas d inquiétude, chaque mois est correctement respecté : le 29/01/2015 deviendra le 28/02/2015 pour le mois suivant. Récurrence Vous pouvez spécifier combien de fois la planification sera répétée avec le champ récurrence. Laissez le vide pour une répétition infinie. Si elle n est pas infinie, quand 0 est atteint, la planificiation sera automatiquement supprimée. 8 Chapitre 1. Contenus
Date La date est utilisée comme base pour les répétitions. Par exemple, si vous avez un loyer tous les 10 du mois, vous devriez saisir une date au 10 pour le mois courant (pas le mois suivant), même si le jour courant est le 26 par exemple. Avertissement : Gardez à l esprit que lorsque la tâche de fond (cron) essaye de dupliquer les transactions bancaires, ce sera pour la date suivante. Commencer maintenant Quand vous créer une planification, vous serez peut-être intéressé pour la lancer immédiatement. Cependant prenez garde, cela va créer une nouvelle transaction bancaire pour la période suivante de la date donnée. Donc si vous voulez créer une transaction bancaire automatique pour le mois courant, le champ date doit être saisi avec le mois précédent. 1.6 Transactions bancaires Une fois les comptes bancaires, étiquettes et planificateurs crées, vous pouvez désormais commencer à créer des transactions bancaires. Vous pouvez gérer les transactions bancaires à partir de la page d aperçu du compte bancaire : ajouter éditer supprimer Sur la page du compte bancaire, vous pouvez filtrer les transactions bancaires. Mais aussi appliquer certaines actions en masse en cochant les cases adéquates : pointer les transactions bancaires sélectionnées dépointer les transactions bancaires sélectionnées supprimer Les transactions bancaires modifient le solde du compte bancaire quand elles sont : crées modifiées supprimées Si vous ne voulez pas appliquer ces modifications, vous pouvez mettre le statut de la transaction bancaire à inactive. Voir Statut. 1.6.1 Champs Certains champs nécessitent plus d explications : Statut Chaques statuts peuvent appliquer les actions suivantes : Statut Modifier le solde Statistiques actif Oui Oui ignoré Oui Non inactif Non Non En effet, les transactions bancaires peuvent : modifier le solde du compte bancaire. Par conséquent, elles sont comptabilisées dans le total du solde (futur, courant, pointé) être utilisées pour les statistiques (proportionnelle ou chronologique) 1.6. Transactions bancaires 9
Actif est le statut par défaut. Ignoré peut être utilisé pour des virements internes par exemple. Vous pouvez en avoir besoin si vous voulez modifier le solde bancaire mais ne voulez pas polluer les statistiques. Inactif existe juste par principe, je n ai pas trouvé de cas d utilisation pour le moment. Cela peut changer à l avenir (voir supprimer). Drapeau pointé C est un pointeur qui indique si c est synchronisé avec votre vrai compte bancaire. C est utile par exemple pour anticiper vos dépenses. Vous pouvez voir un bref résumé du solde pointé tout comme le solde total pointé. Au contraire, vous pouvez aussi voir le solde à partir d une transaction bancaire ou le solde total futur. 1.7 Statistiques Vous pouvez visualiser les statistiques d un compte bancaire. Pour cela, allez sur la page du compte bancaire et cliquez sur le lien du menu Statistiques. Vous pouvez ensuite basculer entre deux types de vues : rapport proportionnel : basés sur les étiquettes rapport chronologique : basés sur les dates Chaques rapports fournissent des filtres et un résumé. Chaques résumés ont plus de détails quand vous cliquez sur l un de ces éléments. 1.7.1 Proportionnel Filtre type : somme ou unitaire Les statistiques proportionnelles affichent des résultats groupés par étiquettes. Afin d obtenir des pourcentages pertinents, les nombres comparés doivent être du même signe (positif ou négatif). C est pourquoi il existe deux sous-types : dépenses revenus Pour une recherche de dépenses en mode unitaire, chaques transactions bancaires négatives sont utilisées. Pour une recherche de dépenses en mode somme, chaques sommes négatives d étiquettes sont utilisées. Par exemple, imaginez que vous avez fait du shopping pour 100 C. Malheureusement, vous découvrez qu un bien n est pas bon. Vous le retourné et vous êtes remboursé de 25C. Avec le filtre type unitaire, le montant utilisé sera 100C. Alors qu avec le filtre type somme, le montant utilisé sera de -100 + 25 = 75C. La plupart du temps, le mode le plus désiré sera somme, c est pourquoi c est le mode par défaut. 1.8 Back-office À tout moment, rappelez-vous que si vous devez outrepasser l interface utilisateur, vous pouvez toujours utiliser le back-office de Django, joignable à /admin (par défaut) avec un membre de l équipe ou super utilisateur. Note : Vous pouvez modifier le paramètre ADMIN_BASE_URL pour une autre valeur que admin à des fins de sécurités. Avertissement : Avec le template de configuration de production, ADMIN_BASE_URL est volontairement vide afin de soulever un message de vérification de type CRITIQUE quand la commande suivante est exécutée :./manage.py check --deploy 10 Chapitre 1. Contenus