ONBOARDING-STAGIAIRE.md 6.0 KB

Guide stagiaire – Onboarding projet bmad

Projet : Suivi facturation / échéancier / paiement (EMGI).
Objectif : Comprendre le projet, lancer l’appli et savoir où modifier le code.


1. En deux phrases

L’appli remplace Excel pour le suivi des factures, paiements et échéanciers. Les factures sont émises dans Pennylane ; ici on les saisit pour le suivi (encours, paiements, tableaux de bord, exports).


2. Où sont les docs ?

Doc Contenu
Ce fichier (app/ONBOARDING-STAGIAIRE.md) Démarrage, structure, où modifier quoi.
app/README.md Installation (mock + base), structure dossiers, export.
_bmad-output/planning-artifacts/prd.md Périmètre, fonctionnalités (FR), user journeys.
_bmad-output/planning-artifacts/architecture.md Stack, API, conventions, limites techniques.
_bmad-output/planning-artifacts/schema-chiffrage-projet.md Modules, endpoints, données, points complexes.
_bmad-output/planning-artifacts/cahier-recettes-livraison.md Critères de recette (pour vérifier que ça marche).
_bmad-output/planning-artifacts/questions-en-suspens.md Questions pas encore tranchées (auth, Pennylane, etc.).

Ordre conseillé : README app → PRD (pour le métier) → ce guide → architecture si tu creuses le technique.


3. Lancer l’application

Sans base de données (démo mock) :

cd app
php -S localhost:8080

Puis ouvrir http://localhost:8080. Les données viennent de mock/*.json.

Avec base de données :

  1. Créer la base : mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS bmad CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
  2. Importer le schéma : mysql -u root -p bmad < sql/schema.sql
  3. Copier .env.example en .env, mettre MOCK_MODE=0 et renseigner DB_HOST, DB_NAME, DB_USER, DB_PASS
  4. Depuis app/ : php -S localhost:8080
  5. Ouvrir http://localhost:8080

Prérequis : PHP 7.4+ avec extensions pdo, pdo_mysql, json. MariaDB ou MySQL pour le mode base.


4. Structure du code (où modifier quoi)

Besoin Fichiers à toucher
Liste des clients, recherche index.html, js/ (script liste clients si dédié), api/clients.php
Fiche client (en-tête, encours) client.html, js/client-detail.js, api/clients.php, api/calculs.php
Liste des factures d’un client js/client-detail.js (affichage), api/factures.php (données)
Ajouter une facture client.html (formulaire), js/facture-form.js, api/factures.php (POST)
Liste des paiements, enregistrer un paiement client.html, js/paiements.js, api/paiements.php
Écheanciers (liste + ajout) client.html, js/client-detail.js, js/echeancier-form.js, api/echeanciers.php
Calculs (encours, échéances à venir) api/calculs.php (et logique mock dans api/factures.php, api/reporting.php)
Tableau de bord dashboard.html, js/dashboard.js, api/calculs.php, api/reporting.php
Top clients top-clients.html, js/top-clients.js, api/top-clients.php
Quantités par client quantites-clients.html, js/quantites-clients.js, api/quantites-clients.php
Export CSV api/reporting.php (?format=csv)
Schéma de données sql/schema.sql ; migrations dans sql/migration-*.sql

Convention : un fichier API par ressource (clients, factures, paiements, echeanciers, calculs, reporting, top-clients, quantites-clients). Pas d’appels API-to-API. Front en JavaScript vanilla (pas de framework) et Tailwind en CDN.


5. Conventions (résumé)

  • Base de données / API : noms en snake_case (ex. client_id, date_facture). Réponses JSON sans wrapper { data: ... } ; erreurs en { error: "message" }.
  • PHP : variables $camelCase, fonctions en camelCase.
  • JS : variables et fonctions en camelCase. Fichiers en minuscules avec tirets (ex. client-detail.js).
  • Endpoints : pluriel (/api/clients.php, /api/factures.php). Paramètres en query ou body selon besoin.

Détails complets dans _bmad-output/planning-artifacts/architecture.md.


6. Comment vérifier que ça marche

  • À la main : naviguer dans l’appli (liste clients, fiche client, ajout facture/paiement/écheancier, dashboard, Top clients, Quantités, export CSV).
  • Recette : le fichier cahier-recettes-livraison.md liste 32 critères (O/N) pour la livraison.
  • API sans le front : avec Postman ou curl, par ex. GET http://localhost:8080/api/clients.php, GET http://localhost:8080/api/factures.php?client_id=1, POST http://localhost:8080/api/paiements.php avec body JSON.

Il n’y a pas de tests automatisés pour le POC.


7. FAQ (questions que tu vas te poser)

  • Pourquoi saisir les factures à la main alors qu’il y a Pennylane ?
    L’appli fait le suivi (encours, paiements, écheanciers). La facturation « document » (PDF) reste dans Pennylane. Pas d’import automatique prévu en MVP.

  • Où est la logique d’encours ?
    Dans api/calculs.php. La même logique est reproduite en mode mock dans api/factures.php et api/reporting.php pour afficher encours et état par facture.

  • Pourquoi mock et DB ?
    Le mode mock permet de démo sans installer MySQL. En prod on utilise la base (MOCK_MODE=0 dans .env).

  • Je peux utiliser Vue / React ?
    Non pour ce POC : on reste en JavaScript vanilla (décision architecture).

  • Paiement supérieur au montant de la facture ?
    Règle à clarifier (autoriser ou bloquer) ; pour l’instant à vérifier dans le code et le cahier recettes.

  • Modifier / supprimer une facture ou un paiement ?
    Pas prévu dans le MVP ; à confirmer avec le responsable projet (voir questions-en-suspens.md).


8. Contact

En cas de doute technique ou métier : [à compléter — responsable technique / tuteur stagiaire].


À mettre à jour au fil des retours (nouvelles questions, changements de structure).