# 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) :** ```bash 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).*