ecintelligence/cleo-erp repository overview

⁠Cleo ERP

La gestion d'entreprise, simplement.

Plateforme ERP complete developpee par EC Intelligence⁠ pour les PME francophones.

⁠Modules

• CRM — Gestion contacts, entreprises, opportunites, pipeline commercial
• Catalogue — Produits, categories de produits, tarification, gestion centralisee du referentiel articles
• Ventes — Devis, commandes, factures, avoirs, paiements, comptes bancaires, gestion multi-devises avec conversion automatique. Contact optionnel sur tous les documents. Devise configurable par ligne de document avec validation d'homogeneite. Autocompletion produits par recherche serveur (debounce 300ms). Modal email universel sur devis/commandes/factures avec pre-remplissage contact. Bouton Modifier disponible sur commandes en statut brouillon
• Gestion des stocks — Entrepots, niveaux de stock, mouvements, inventaires, alertes de reapprovisionnement
• Achats — Fournisseurs, commandes d'achat, receptions, factures fournisseurs (produit optionnel sur les lignes — saisie de services possible), pieces jointes, avoirs, paiements. Design module entierement refonte (Ant Design 5.x, Design System Clouder)
• RH — Gestion des employes (unification User/Employee, creation automatique de compte, situation familiale pour le calcul fiscal), departements, postes, contrats (CDI/CDD/Stage/Freelance) avec desactivation automatique Celery, missions, disponibilites, formations, competences. Portail self-service employe, annonces internes (signal bienvenue automatique), attestations de travail PDF, gestion des doleances (anonymat configurable), recompenses et reconnaissance. Gestion des conges avec workflow double validation (N+1 → RH), soldes par type, acquisition mensuelle Celery, calendrier equipe, report annuel pack-agnostique. Notes de frais professionnelles avec workflow manager → finance, ecriture comptable automatique et export PDF WeasyPrint. Jours feries configurables (CRUD interface, fixtures par pack, exclusion dans le calcul des jours ouvres).
• Paie — Periodes, lancements avec auto-generation des bulletins, bulletins de paie professionnels avec moteur generique de cotisations (SalaryComponent.category + rate_parameter_code + base_rule), cumuls annuels (year-to-date), classification employe (categorie, coefficient, echelon, convention collective), solde de conges sur le bulletin, formatage nombres avec separateurs de milliers. Cotisations detaillees par pays (5+ salariales, 5-8 patronales), integration comptable automatique (journal SAL), architecture multi-pays via PayrollParameterResolver avec versioning des taux (reference_date). 3 methodes de calcul fiscal extensibles : bareme progressif + deductions (MA, CI, ML, TG, BJ, NE, GN, FR), quotient familial (SN), abattement sur le brut + reduction familiale (BF). 10 pays supportes avec fixtures completes. Administration configurable via interface (CRUD composants, parametres, tranches IR, types de contrat). Labels adaptatifs par pays (hook usePayrollLabels, zero hardcodage). Formulaire donnees de paie adaptatif par pays (champs visibles/masques resolus dynamiquement via pack-config). Actions rapides operateur (situation familiale, prime exceptionnelle, conges periode). Templates PDF par pays : CI style GOS (part salariale/patronale cote a cote, Parts IGR, display_order), MA style Attijari (Code/Libelle/Base/Taux, N° C.I.M.R, N° Assurance Maladie), generique pour les autres. Logo entreprise dans le PDF, export XLSX recapitulatif. Fiche de paie creee automatiquement a la creation d'un employe (signal enrichi, migration backfill). Formulaire donnees de paie restructure en 6 sections avec bloc infos RH en lecture seule.
• Recrutement — Offres d'emploi, candidatures, entretiens, evaluations
• Comptabilite — Plan comptable, ecritures, journaux (VEN, ACH, BNK, CSH, OD, SAL), releves bancaires (import OFX), rapprochement automatique et manuel, immobilisations, rapports reglementaires (ESG, journal officiel, tableau des amortissements), roles comptables dynamiques (AccountMapping/AccountResolver — 13 roles)
• Tresorerie — Import OFX/CSV, rapprochement bancaire automatique et manuel, previsions de tresorerie avec salaires integres
• Dashboard decisionnel — Vue consolidee des KPI par module, graphiques et indicateurs temps reel, totaux multi-devises convertis en devise locale
• Gestion utilisateurs — Profils, roles, permissions granulaires par module, matrice roles/permissions, journal d'activite
• Notifications — Alertes temps reel (Celery/Redis), centre de notifications, preferences utilisateur
• Configuration — Page d'administration plateforme (entreprise, branding/logo, parametres, email SMTP, informations systeme, sauvegardes, export RGPD, journal d'audit)

⁠Fonctionnalites transversales

• Recherche globale — Barre de recherche multi-modules accessible via Ctrl+K (13 modeles, 8 modules, resultats groupes avec navigation directe)
• Branding entreprise — Upload du logo affiche sur la page de login, la sidebar et les documents
• Journal d'audit — Tracabilite complete des actions utilisateurs (connexion, modifications, IP) avec filtres par module et recherche
• Documentation API — Swagger UI (/api/docs/) et ReDoc (/api/redoc/) auto-generes via drf-spectacular (OpenAPI 3.0)
• Authentification JWT — Tokens JWT (access 1h, refresh 7j) en complement de l'authentification session, pour integrations tierces et API mobile
• Backup automatise — Sauvegarde quotidienne PostgreSQL (2h00), rotation 30 jours, backup manuel et telechargement depuis l'interface
• Export RGPD — Export integral des donnees (17 fichiers JSON, 11 modules) en archive ZIP, conforme Article 20 du RGPD
• Localisation Ant Design — Interface entierement francisee (tableaux, pagination, calendriers, modales)
• Page de login professionnelle — Design gradient deux panneaux, nom et logo entreprise dynamiques, version affichee
• Design System Clouder — Palette unifiee, typographie, espacements, ombres, variables CSS, cartes modules Variante B (gradient top strip 4px, icones outlined colorees)
• Multi-devises — Conversion automatique des prix catalogue lors de la creation de documents en devise etrangere, totaux agreges convertis en devise locale sur les listes et dashboards
• Integration comptable automatique — Ecritures generees automatiquement lors de la validation des factures clients/fournisseurs, paiements, bulletins de paie et notes de frais (100% via AccountResolver)

⁠Roles et permissions

Cleo ERP integre un systeme de permissions granulaires avec 6 niveaux d'acces hierarchiques appliques sur 10 modules :

7 roles par defaut sont crees automatiquement au demarrage : Administrateur, Directeur, Ventes, Ressources Humaines, Finance, Logistique, Employe. La matrice complete est consultable depuis l'interface d'administration (/users/roles).

⁠Stack technique

• Backend : Django 5.2 / Django REST Framework 3.16
• Frontend : React 19 / Ant Design 5.x (compile dans l'image, locale fr_FR)
• Base de donnees : PostgreSQL 14+
• File d'attente : Redis + Celery (notifications asynchrones, backups planifies, conges, paie)
• Authentification : Session (frontend) + JWT (API externe)
• Documentation API : drf-spectacular (OpenAPI 3.0 / Swagger UI / ReDoc)
• Reverse proxy : Nginx
• Conteneurisation : Docker / Docker Compose

⁠Internationalisation

Cleo ERP supporte 10 pays regroupes sous 3 packs comptables, selectionnables au premier lancement via un Setup Wizard :

Chaque pays dispose de : devises, plan comptable complet, taxes, journaux, exercice fiscal, parametres de paie (16+ parametres configurables via PayrollParameterResolver), parametres de conges (10 parametres LEAVE_*), tranches d'imposition, jours feries initiaux, categories de frais, labels PDF dynamiques (cotisations, impots, numeros sociaux) et donnees de demonstration optionnelles.

L'architecture distingue accounting_pack (OHADA/MA/FR — plan comptable et TVA) et country_code (CI/SN/ML/.../FR — paie, jours feries, conges, devise). L'ajout d'un nouveau pays ne necessite que la creation d'un fichier fixture dans payroll/fixtures/locales/ et d'une entree dans COUNTRY_PACKS — zero modification du code applicatif.

Depuis v3.13.0, chaque pack charge egalement 13 roles comptables (AccountMapping) qui permettent au systeme de resoudre dynamiquement les comptes utilises dans les ecritures automatiques (ventes, achats, paie, notes de frais), sans aucun code hardcode.

Depuis v3.29.0, chaque pays peut disposer de son propre template de bulletin de paie (CI style GOS, MA style Attijari, generique pour les autres), selectionne automatiquement via CompanySetup.country_code.

Le choix du pays est irreversible apres la premiere ecriture comptable (verrouillage automatique).

⁠Documentation API

La documentation interactive de l'API REST est disponible apres deploiement :

Tous les endpoints sont groupes par module (CRM, Catalog, Sales, Purchasing, Inventory, HR, Payroll, Accounting, Recruitment, Users, Notifications, Dashboard, Core).

⁠Authentification API (JWT)

# Obtenir un token
curl -X POST http://localhost:8000/api/token/ \
  -H "Content-Type: application/json" \
  -d '{"username":"[email protected]","password":"admin"}'

# Utiliser le token
curl -H "Authorization: Bearer <access_token>" http://localhost:8000/api/sales/invoices/

# Rafraichir le token
curl -X POST http://localhost:8000/api/token/refresh/ \
  -H "Content-Type: application/json" \
  -d '{"refresh":"<refresh_token>"}'

⁠Demarrage rapide

# 1. Creer le repertoire
mkdir -p /opt/cleo && cd /opt/cleo

# 2. Creer le fichier .env
cat > .env << 'EOF'
# Cleo ERP — Configuration
SECRET_KEY=changez-moi-avec-une-vraie-cle-secrete
DEBUG=False
ALLOWED_HOSTS=localhost,votre-ip,votre-domaine.com

# Base de donnees
DB_NAME=cleo_db
DB_USER=cleo_user
DB_PASSWORD=votre-mot-de-passe-securise

# Email (optionnel — configurable aussi depuis /settings)
EMAIL_HOST=smtp.example.com
EMAIL_PORT=587
EMAIL_USE_TLS=True
[email protected]
EMAIL_HOST_PASSWORD=votre-mot-de-passe
[email protected]

# API taux de change (optionnel)
OPENEXCHANGE_API_KEY=votre-cle

# Securite
CORS_ORIGIN_WHITELIST=http://localhost:8000
CSRF_TRUSTED_ORIGINS=http://localhost:8000
SESSION_COOKIE_SECURE=False
CSRF_COOKIE_SECURE=False

# Superuser (cree automatiquement au premier lancement)
[email protected]
DJANGO_SUPERUSER_PASSWORD=admin

# URL du site (utilisee dans les emails et PDFs)
SITE_URL=http://localhost:8000

# Celery (requis pour backups, notifications, conges et paie)
CELERY_BROKER_URL=redis://redis:6379/0
CELERY_RESULT_BACKEND=redis://redis:6379/0
EOF

# 3. Creer docker-compose.yml
cat > docker-compose.yml << 'EOF'
services:

  db:
    image: postgres:14-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: ${DB_NAME:-cleo_db}
      POSTGRES_USER: ${DB_USER:-cleo_user}
      POSTGRES_PASSWORD: "${DB_PASSWORD:?DB_PASSWORD requis dans .env}"
    volumes:
      - pg_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USER:-cleo_user} -d ${DB_NAME:-cleo_db}"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 10s

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

  backend:
    image: ecintelligence/cleo-erp:3.34.1
    restart: unless-stopped
    env_file: .env
    environment:
      DB_HOST: db
      DB_PORT: "5432"
      DJANGO_ENV: production
      REDIS_URL: redis://redis:6379/0
    volumes:
      - static_data:/data/static
      - media_data:/data/media
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/api/check-auth/"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

  celery-worker:
    image: ecintelligence/cleo-erp:3.34.1
    restart: unless-stopped
    env_file: .env
    environment:
      DB_HOST: db
      DB_PORT: "5432"
      DJANGO_ENV: production
      REDIS_URL: redis://redis:6379/0
    command: celery -A cleo_platform worker -l info
    volumes:
      - media_data:/data/media
    depends_on:
      backend:
        condition: service_healthy

  celery-beat:
    image: ecintelligence/cleo-erp:3.34.1
    restart: unless-stopped
    env_file: .env
    environment:
      DB_HOST: db
      DB_PORT: "5432"
      DJANGO_ENV: production
      REDIS_URL: redis://redis:6379/0
    command: celery -A cleo_platform beat -l info --scheduler django_celery_beat.schedulers:DatabaseScheduler
    volumes:
      - media_data:/data/media
    depends_on:
      backend:
        condition: service_healthy

  nginx:
    image: nginx:alpine
    restart: unless-stopped
    ports:
      - "${CLEO_PORT:-8000}:80"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
      - static_data:/data/static:ro
      - media_data:/data/media:ro
    depends_on:
      backend:
        condition: service_healthy

volumes:
  pg_data:
    name: cleo_pg_data
  static_data:
    name: cleo_static_data
  media_data:
    name: cleo_media_data
EOF

# 4. Creer nginx.conf
cat > nginx.conf << 'EOF'
upstream django {
    server backend:8000;
}

server {
    listen 80;
    server_name _;
    client_max_body_size 50M;

    location /static/ {
        alias /data/static/;
        expires 30d;
        add_header Cache-Control "public, immutable";
        access_log off;
    }

    location /media/ {
        alias /data/media/;
        expires 7d;
        add_header Cache-Control "public";
    }

    location / {
        proxy_pass http://django;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_redirect off;
        proxy_read_timeout 120s;
        proxy_connect_timeout 10s;
    }
}
EOF

# 5. Lancer
docker compose up -d

# 6. Acceder a http://localhost:8000
# Le Setup Wizard apparait au premier acces pour choisir le pack
# Credentials : [email protected] / admin

⁠Variables d'environnement

⁠Tags Docker Hub

• latest — Derniere version stable (3.34.1)
• 3.34.1 — Amelioration templates PDF CI + MA — 0 migration DB
• 3.34.0 — Formulaire EmployeePayroll adaptatif par pays — 1 migration DB (payroll/0009)
• 3.33.0 — Lancement global + Labels adaptatifs + Actions rapides operateur — 0 migration DB

L'historique complet des tags est disponible sur Docker Hub⁠.

⁠Changelog

• 3.34.1 — Amelioration templates PDF CI (Parts IGR en-tete, numerotation display_order, en-tete fixe 3 lignes) + MA (N° C.I.M.R, N° Assurance Maladie, 6 colonnes fixes colgroup, accents)
• 3.34.0 — Formulaire EmployeePayroll adaptatif par pays (endpoint pack-config, 3 champs optionnels, payroll_form_fields dans COUNTRY_PACKS)
• 3.33.0 — Lancement global auto-generation bulletins + labels adaptatifs par pays (usePayrollLabels) + actions rapides operateur (situation familiale, prime, conges) + fix signals/deduplication

L'historique complet des versions est disponible dans le depot Git.

⁠Liens

• Documentation API : /api/docs/ (Swagger UI) ou /api/redoc/ (ReDoc)
• Support : [email protected]⁠