architecture.md 14 KB


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'

completedAt: '2026-02-09'

Architecture — dirCops

Application : dirCops — suivi facturation / échéancier / paiement
Mode : POC puis migration vers MODX en production


1. Contexte et périmètre

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.


2. Vue d’ensemble et architecture fonctionnelle

2.1 Schéma de contexte

                    ┌─────────────────────────────────────────────────────────────────┐
                    │                        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)   │

2.2 Acteurs

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

2.3 Vue par couches

┌─────────────────────────────────────────────────────────────────────────────┐
│  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)            │
└─────────────────────────────────────────────────────────────────────────────┘

2.4 Modules fonctionnels

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.


3. Décisions techniques

3.1 Stack POC

  • Backend : PHP (API REST)
  • Frontend : JavaScript vanilla + Tailwind CSS + HTML (MPA)
  • Base de données : MariaDB/MySQL
  • Authentification : Sessions PHP simples ou auth basique ; pas de JWT/OAuth

3.2 Base de données

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

3.3 API REST

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

3.4 Frontend

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

3.5 Infra

Dev : php -S ou Apache/Nginx
Déploiement : Hébergement PHP + MariaDB ; sql/schema.sql une fois ; .env en production


4. Patterns et conventions

4.1 Nommage

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

4.2 Formats API

  • Succès : réponse directe {...} (pas de wrapper data)
  • Erreur : {error: "message"} + code HTTP approprié
  • Dates : ISO (2026-02-09T10:00:00Z)

4.3 Règles agents IA

  • snake_case en DB et JSON API ; camelCase en PHP/JS
  • Respecter la structure des endpoints et du projet
  • Retourner les erreurs au format {error: "message"}
  • Anti-patterns : pas de wrapper {data: ...} ; pas de mélange camelCase/snake_case dans le même contexte

5. Interfaces logicielles

5.1 I1 — Utilisateur ↔ Application

Points 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.

5.2 I2 — Frontend ↔ API

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)

5.3 I3 — API ↔ Base de données

Protocole : PDO, pilote pdo_mysql. Connexion dans config.php (getPdo()).
Opérations : SELECT, INSERT, UPDATE, DELETE ; requêtes préparées. Charset utf8mb4.

5.4 I4 — Export CSV

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.

5.5 I5 — Pennylane (hors MVP)

Non réalisé en MVP. Facturation dans Pennylane ; saisie manuelle dans l’appli. Évolution possible : import ou sync factures/paiements.

5.6 Récapitulatif

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

6. Structure projet et validation

6.1 Arborescence

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

6.2 Flux de données

  • Liste clients : index.html → api/clients.php → DB
  • Détail client : client.html → API (clients, factures, paiements, calculs, écheanciers) → DB
  • Dashboard : dashboard.html → api/calculs.php, api/reporting.php → DB
  • Paiement : client.html + js/paiements.js → api/paiements.php → DB → recalcul API

6.3 Validation

Statut : 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.

6.4 Priorité d’implémentation

  1. sql/schema.sql
  2. api/config.php
  3. Endpoints de base : clients.php, factures.php, paiements.php, echeanciers.php

Document de référence pour toute question d’architecture. À mettre à jour en cas d’ajout d’écrans, d’endpoints ou d’intégrations externes.