stepsCompleted: [1, 2, 3, 4, 5, 6, 7, 8] inputDocuments: ['prd.md', 'product-brief-bmad-2026-02-09.md'] workflowType: 'architecture' project_name: 'dircops' user_name: 'Livinweb' date: '2026-02-09' lastStep: 8 status: 'complete'
Application : dirCops — suivi facturation / échéancier / paiement
Mode : POC puis migration vers MODX en production
Exigences fonctionnelles : 13 FR en 6 catégories (Client Management, Invoice Tracking, Payment Management, Financial Calculations, Reporting & Analytics, Data Management). Application web MPA, calculs automatiques (encours, échéances), export CSV.
Exigences non fonctionnelles : Sécurité (accès restreint), Performance (< 3s chargement, < 1s interactions).
Contraintes : Facturation gérée dans Pennylane ; l’appli assure uniquement le suivi (saisie manuelle des factures). Budget restreint → architecture minimale. Stack : PHP (API REST) + JavaScript + Tailwind + HTML + MariaDB/MySQL. Application interne uniquement.
Périmètre utilisateurs : Un seul type traité : commercial / admin (accès complet). Les autres rôles (lecteur, stagiaire, etc.) sont en option.
┌─────────────────────────────────────────────────────────────────┐
│ EXTERNE │
│ • Pennylane (facturation document) — pas d'échange technique │
│ • Hébergeur / réseau (accès, firewall, SSL) │
│ • Navigateur (Chrome, Firefox, Edge) │
└─────────────────────────────────────────────────────────────────┘
│
Entrées : │ Sorties :
• Saisies utilisateur │ • Pages HTML (écrans)
• Clics, navigation │ • Export CSV (téléchargement)
• Paramètres de requête │ • Réponses JSON (données)
▼
┌─────────────────────────────────────────────────────────────────┐
│ APPLICATION (dirCops) │
│ Frontend (HTML / JS / Tailwind) + API REST (PHP) │
│ + Base de données (MariaDB/MySQL) │
└─────────────────────────────────────────────────────────────────┘
│
Sorties techniques : │ Entrées techniques :
• Fichiers CSV générés │ • Connexion DB (PDO)
• Réponses HTTP/JSON │ • Variables .env (config)
• Pages servies (HTML) │
| Acteur | Rôle | Entrées fournies | Sorties reçues |
|---|---|---|---|
| Commercial (équipe EMGI) | Utilisateur principal | Recherche client, saisie facture/paiement/écheancier, filtres (type, cycle), demande d’export | Liste clients, fiche client, tableau de bord, Top clients, Quantités, fichier CSV |
| Trésorerie / Direction (si accès) | Consultation | Consultation écrans, export | Mêmes sorties en lecture |
| Système (automatique) | — | — | Calculs encours, état facture (payé/en attente), échéances |
┌─────────────────────────────────────────────────────────────────────────────┐
│ COUCHE PRÉSENTATION (Frontend) │
│ index.html, client.html, dashboard.html, top-clients.html, quantites-clients.html
└─────────────────────────────────────────────────────────────────────────────┘
│ HTTP (GET/POST) – JSON
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ COUCHE API (Backend PHP) │
│ clients.php, factures.php, paiements.php, echeanciers.php, calculs.php, │
│ reporting.php, top-clients.php, quantites-clients.php, config.php │
└─────────────────────────────────────────────────────────────────────────────┘
│ PDO
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ COUCHE DONNÉES │
│ MariaDB/MySQL (tables clients, factures, paiements, echeanciers) │
└─────────────────────────────────────────────────────────────────────────────┘
| Module | Responsabilité | Fichiers principaux |
|---|---|---|
| Config | Connexion DB, .env, helpers (sendJson, sendError) | api/config.php, .env |
| Clients | Liste, recherche, détail, création, suppression | api/clients.php, index.html, client.html, js/client-detail.js |
| Factures | Liste par client, ajout/modification/suppression (suivi) | api/factures.php, client.html, js/facture-form.js |
| Paiements | Liste, enregistrement, suppression | api/paiements.php, client.html, js/paiements.js |
| Écheanciers | Liste, création, suppression | api/echeanciers.php, client.html, js/echeancier-form.js |
| Calculs | Encours, échéances à venir | api/calculs.php, api/reporting.php, dashboard.html, js/dashboard.js |
| Reporting | Tableau de bord, export CSV (encours, factures PJ) | api/reporting.php, dashboard.html |
| Top clients | Agrégation type/cycle, quantités, CA | api/top-clients.php, top-clients.html, js/top-clients.js |
| Quantités par client | Synthèse quantités facturées/livrées | api/quantites-clients.php, quantites-clients.html, js/quantites-clients.js |
Dépendances : Clients indépendant ; Factures → Clients ; Paiements → Factures ; Écheanciers → Factures ; Calculs → Clients, Factures, Paiements ; Reporting → Calculs ; Top clients, Quantités → Factures, Clients.
Tables : clients, factures, paiements, echeanciers
Relations : factures → client, paiements → facture, echeanciers → facture
Champs factures : n_facture, n_vente, date_facture, type_produit (alevins/larves), cycle, quantites, qte_livree, montant_ht
Champs écheanciers : facture_id, nb_echeances, date_debut_echeancier
État payé/en attente : dérivé des paiements
Endpoints : /api/clients, /api/factures, /api/paiements, /api/echeanciers, /api/calculs, /api/reporting, /api/top-clients, /api/quantites-clients
Format : JSON ; erreurs {error: "message"} avec codes HTTP 200, 400, 404, 500
Pages : index.html, client.html, dashboard.html, top-clients.html, quantites-clients.html
State : JavaScript vanilla, variables globales ou localStorage
Pas de SPA : rechargement de page après certaines actions
Dev : php -S ou Apache/Nginx
Déploiement : Hébergement PHP + MariaDB ; sql/schema.sql une fois ; .env en production
| Contexte | Convention | Exemple |
|---|---|---|
| Tables et colonnes | snake_case, pluriel tables | clients, client_id, n_facture |
| API (endpoints, params, JSON) | snake_case | ?client_id=1, {client_id: 1} |
| Code PHP/JS | camelCase | getClientData(), $clientId |
| Fichiers | minuscules, tirets | client-detail.js |
{...} (pas de wrapper data){error: "message"} + code HTTP approprié2026-02-09T10:00:00Z){error: "message"}{data: ...} ; pas de mélange camelCase/snake_case dans le même contextePoints d’entrée : index.html (liste clients), client.html?id= (fiche client), dashboard.html, top-clients.html, quantites-clients.html, lien « Exporter CSV » → api/reporting.php?format=csv.
Protocole : GET (lecture), POST (création), PUT (modification), DELETE (suppression). Body JSON pour POST/PUT.
Erreurs : 4xx/5xx avec {error: "message"} ; front : apiGet, apiPost, etc. dans utils.js.
Appels principaux :
| Appelant | Méthode | Endpoint | Rôle |
|---|---|---|---|
| index.html | GET/POST/DELETE | /api/clients.php |
Liste, recherche, création, suppression client |
| client.html | GET | /api/clients, /api/factures, /api/paiements, /api/calculs, /api/echeanciers |
Détail client |
| client.html | POST/PUT/DELETE | /api/factures.php, /api/paiements.php, /api/echeanciers.php |
Création, modification, suppression |
| dashboard.html | GET | /api/reporting.php |
Tableau de bord ; format=csv ou format=factures_csv pour export |
| top-clients.html | GET | /api/top-clients.php |
Données Top clients (params type, cycle) |
| quantites-clients.html | GET | /api/quantites-clients.php |
Quantités par client (param type) |
Protocole : PDO, pilote pdo_mysql. Connexion dans config.php (getPdo()).
Opérations : SELECT, INSERT, UPDATE, DELETE ; requêtes préparées. Charset utf8mb4.
Endpoint : api/reporting.php avec format=csv (encours par client) ou format=factures_csv (ensemble factures PJ). En-têtes Content-Type text/csv, Content-Disposition attachment.
Non réalisé en MVP. Facturation dans Pennylane ; saisie manuelle dans l’appli. Évolution possible : import ou sync factures/paiements.
| Id | Interface | Sens | Protocole |
|---|---|---|---|
| I1 | Utilisateur ↔ Application | Bidirectionnel | HTTP, navigateur, HTML/CSV |
| I2 | Frontend ↔ API | Front ↔ API | HTTP, JSON |
| I3 | API ↔ Base de données | API ↔ DB | PDO, MySQL/MariaDB |
| I4 | Application → Utilisateur (export) | API → navigateur | HTTP, CSV |
| I5 | Application ↔ Pennylane | — (hors MVP) | À définir |
dircops/
├── README.md
├── .env.example
├── .env
├── index.html
├── client.html
├── dashboard.html
├── top-clients.html
├── quantites-clients.html
├── api/
│ ├── config.php
│ ├── clients.php
│ ├── factures.php
│ ├── paiements.php
│ ├── calculs.php
│ ├── reporting.php
│ ├── top-clients.php
│ └── quantites-clients.php
├── js/
│ ├── utils.js
│ ├── client-detail.js
│ ├── paiements.js
│ ├── dashboard.js
│ ├── facture-form.js
│ ├── top-clients.js
│ └── quantites-clients.js
├── css/
└── sql/
└── schema.sql
index.html → api/clients.php → DBclient.html → API (clients, factures, paiements, calculs, écheanciers) → DBdashboard.html → api/calculs.php, api/reporting.php → DBclient.html + js/paiements.js → api/paiements.php → DB → recalcul APIStatut : READY FOR IMPLEMENTATION
Points forts : Stack simple ; séparation nette API / frontend / DB ; patterns explicites.
À préciser en implémentation : Schéma SQL détaillé, format export CSV.
Évolutions futures : Auth détaillée, migration MODX.
sql/schema.sqlapi/config.phpclients.php, factures.php, paiements.php, echeanciers.phpDocument de référence pour toute question d’architecture. À mettre à jour en cas d’ajout d’écrans, d’endpoints ou d’intégrations externes.