Guide de Contribution Scell.io

Version : 1.0 Derniere mise a jour : 2026-03-03

Table des matieres

1. Prerequis
2. Installation
3. Conventions de Code
4. Workflow Git
5. Tests
6. Structure du Projet
7. Variables d'Environnement
8. Depannage

1. Prerequis

Outils requis

Outil	Version minimale	Verification
PHP	8.2+	`php -v`
Composer	2.x	`composer -V`
Node.js	20+	`node -v`
npm	10+	`npm -v`
PostgreSQL	17	`psql --version`
Redis	7.4	`redis-server --version`
Git	2.x	`git --version`

Extensions PHP requises

bcmath, ctype, curl, dom, fileinfo, gd, intl, json, mbstring,
openssl, pcre, pdo, pdo_pgsql, tokenizer, xml, zip

Verification rapide :

bash

php -m | grep -E "bcmath|ctype|curl|dom|fileinfo|gd|intl|json|mbstring|openssl|pcre|pdo|pdo_pgsql|tokenizer|xml|zip"

Services

PostgreSQL 17 : base de donnees principale
Redis 7.4 : cache, sessions, queues

2. Installation

2.1 Cloner le depot

bash

git clone git@github.com:QrCommunication/scell.io.git
cd scell.io

2.2 Backend (Laravel)

bash

cd backend

# Installer les dependances PHP
composer install

# Copier et configurer le fichier d'environnement
cp .env.example .env
# Editer .env avec vos parametres (voir section 7)

# Generer la cle d'application
php artisan key:generate

# Creer la base de donnees PostgreSQL
createdb scell_io

# Executer les migrations
php artisan migrate

# Peupler la base avec les donnees initiales
php artisan db:seed

# Lancer le serveur de developpement
php artisan serve
# -> http://localhost:8000

2.3 Frontend (React)

bash

cd frontend

# Installer les dependances
npm install

# Copier et configurer le fichier d'environnement
cp .env.example .env
# Verifier que VITE_API_URL pointe vers votre backend local

# Lancer le serveur de developpement
npm run dev
# -> http://localhost:5173

2.4 Services optionnels

bash

# Laravel Horizon (traitement des queues)
cd backend
php artisan horizon

# Widget d'onboarding (si necessaire)
cd frontend/packages/onboarding-widget
npm install
npm run dev

2.5 Verification de l'installation

bash

# Backend : health check
curl http://localhost:8000/api/health
# Attendu : {"status":"ok","timestamp":"..."}

# Backend : tests
cd backend && php artisan test

# Frontend : build de verification
cd frontend && npm run build

3. Conventions de Code

3.1 Backend (PHP / Laravel)

Standard : PSR-12

Regles specifiques au projet :

Regle	Detail
Cles primaires	UUID via trait `HasUuids` sur tous les modeles
Validation	Toujours via Form Requests (jamais dans le controleur)
Reponses API	Toujours via API Resources pour la serialisation
Messages d'erreur	En francais pour les erreurs utilisateur
Service Layer	La logique metier va dans `app/Services/`, pas dans les controleurs
Observers	Pour les regles transversales (immutabilite, audit)
Scopes	Utiliser `HasTenantScope` pour l'isolation tenant

Structure d'un controleur :

php

class ExempleController extends Controller
{
    // Injection de dependance du service
    public function __construct(
        private readonly ExempleService $service
    ) {}

    // Form Request pour la validation
    public function store(StoreExempleRequest $request): ExempleResource
    {
        // Le controleur orchestre, le service execute
        $result = $this->service->create($request->validated());

        return new ExempleResource($result);
    }
}

Nommage :

Element	Convention	Exemple
Modele	PascalCase singulier	`TenantInvoice`
Controller	PascalCase + Controller	`TenantInvoiceController`
Service	PascalCase + Service	`InvoiceNumberingService`
Migration	snake_case avec date	`2026_01_11_000005_create_invoices_table`
Form Request	PascalCase + Request	`StoreInvoiceRequest`
Resource	PascalCase + Resource	`InvoiceResource`
Job	PascalCase	`ProcessInvoice`
Middleware	PascalCase	`EnsureTenantIsolation`

3.2 Frontend (React / TypeScript)

Standard : ESLint + TypeScript strict

Regles specifiques au projet :

Regle	Detail
Composants	Fonctionnels avec hooks (pas de classes)
Taille	Maximum 300 lignes par composant
Data fetching	Hooks Refine (`useList`, `useCreate`, `useUpdate`, etc.)
UI	Composants Ant Design 5 exclusivement
Typage	TypeScript strict, interfaces dans `src/types/`
i18n	Toutes les chaines via `useTranslation()`

Nommage :

Element	Convention	Exemple
Composant	PascalCase	`TenantDashboard.tsx`
Hook	camelCase avec "use"	`useTenant.ts`
Context	PascalCase + Context	`TenantContext.tsx`
Provider	camelCase + Provider	`tenantDataProvider.ts`
Type/Interface	PascalCase	`SubTenant`
Fichier traduction	kebab-case	`common.json`

3.3 Base de donnees

Regle	Detail
Tables	snake_case pluriel (`invoices`, `fiscal_entries`)
Colonnes	snake_case (`invoice_number`, `tenant_id`)
Foreign keys	`{table_singulier}_id` (`tenant_id`, `user_id`)
Indexes	Nommer explicitement pour les index custom
JSON	Type JSONB PostgreSQL pour `metadata`, `settings`, etc.
Montants	`DECIMAL(12,4)` pour tous les montants financiers

4. Workflow Git

4.1 Branches

Prefix	Usage	Exemple
`feature/`	Nouvelle fonctionnalite	`feature/tenant-billing-export`
`fix/`	Correction de bug	`fix/fiscal-chain-integrity`
`docs/`	Documentation	`docs/api-reference-update`
`refactor/`	Refactoring sans changement fonctionnel	`refactor/service-layer-cleanup`
`test/`	Ajout/modification de tests	`test/fiscal-anchoring`

Branche principale : main

4.2 Commits conventionnels

Format : type(scope): description

bash

# Exemples
feat(fiscal): add RFC3161 TSA anchoring for fiscal entries
fix(tenant): prevent cross-tenant data access in sub-tenant queries
docs(api): update OpenAPI spec with incoming invoice endpoints
refactor(services): extract InvoiceNumberingService from controller
test(fiscal): add chain integrity verification tests
chore(deps): update Laravel to 12.1

Types autorises :

Type	Description
`feat`	Nouvelle fonctionnalite
`fix`	Correction de bug
`docs`	Documentation
`refactor`	Refactoring
`test`	Tests
`chore`	Maintenance (deps, CI, config)
`perf`	Amelioration de performance
`style`	Formatage (pas de changement de code)

4.3 Processus de Pull Request

Creer une branche depuis main
Developper avec des commits atomiques
Verifier les tests localement (php artisan test)
Pousser la branche et ouvrir une PR
Remplir le template de PR (description, tests, captures si UI)
Attendre la review et les checks CI
Merger apres approbation

Regles de PR :

Titre concis (moins de 70 caracteres)
Description avec contexte, changements et plan de test
Tests passes (coverage minimum 80%)
Pas de fichiers sensibles (.env, credentials)

5. Tests

5.1 Backend

bash

cd backend

# Lancer tous les tests
php artisan test

# Lancer un fichier de test specifique
php artisan test --filter=FiscalLedgerServiceTest

# Lancer les tests avec couverture
php artisan test --coverage

# Lancer les tests d'un dossier
php artisan test tests/Feature/Fiscal/

Coverage minimum requis : 80%

5.2 Structure des tests

backend/tests/
  Feature/
    Api/
      IncomingInvoiceDownloadTest.php
      IncomingInvoiceMarkPaidTest.php
      V1/
        TenantCreditNoteUpdateDeleteTest.php
        TenantDirectCreditNoteControllerTest.php
        TenantDirectInvoiceControllerTest.php
        TenantIncomingInvoiceControllerTest.php
        TenantInvoiceUpdateDeleteTest.php
        TenantMultiTenantIsolationTest.php
        TenantStatsControllerTest.php
    Fiscal/
      FiscalAnchoringServiceTest.php
      FiscalClosingServiceTest.php
      FiscalControllerTest.php
      FiscalLedgerServiceTest.php
      FiscalRuleEngineServiceTest.php
    MCP/
      McpServerTest.php
      McpTenantSessionTest.php
    Onboarding/
      OnboardingApiTest.php
    Services/
      InvoiceNumberingServiceTest.php
    Tenant/
      BulkInvoiceControllerTest.php
      TenantCreditNoteControllerTest.php
    Webhooks/
      ProcessIncomingInvoiceWebhookTest.php
      SuperPDPWebhookTest.php
  Unit/
    MCP/
      Tools/
        CreditNoteToolsTest.php
        FiscalToolsTest.php
    Models/
      InvoiceSequenceTest.php
      SubTenantTest.php
      SyncCursorTest.php
      TenantTest.php
    Services/
      InvoiceNumberingServiceTest.php
      KybServiceTest.php
      SuperPDP/
        SuperPDPServiceTest.php
      TenantBillingServiceTest.php

5.3 Convention de test

Feature tests : testent un flux complet via l'API HTTP.

php

class TenantInvoiceControllerTest extends TestCase
{
    public function test_tenant_can_create_invoice(): void
    {
        $tenant = Tenant::factory()->create(['kyb_status' => 'verified']);
        // ...
        $response = $this->withHeaders([
            'X-Tenant-Key' => $tenant->api_key,
        ])->postJson('/api/v1/tenant/invoices', $payload);

        $response->assertStatus(201);
        $this->assertDatabaseHas('invoices', ['tenant_id' => $tenant->id]);
    }
}

Unit tests : testent une classe ou methode isolee.

php

class InvoiceNumberingServiceTest extends TestCase
{
    public function test_generates_sequential_numbers(): void
    {
        $service = new InvoiceNumberingService();
        $number1 = $service->getNextNumber($tenantId, null, 2026, 1);
        $number2 = $service->getNextNumber($tenantId, null, 2026, 1);

        $this->assertNotEquals($number1, $number2);
    }
}

5.4 Tester les cas critiques

Les tests suivants sont obligatoires pour toute modification du module fiscal :

Verification de la chaine de hachage apres insertion
Tentative de modification d'une entree fiscale (doit echouer)
Tentative de suppression d'un avoir non-brouillon (doit echouer)
Isolation multi-tenant (un tenant ne peut pas acceder aux donnees d'un autre)
Kill-switch (les operations doivent etre bloquees quand actif)

6. Structure du Projet

scell.io/
  backend/                          # API Laravel 12
    app/
      Console/Commands/             # Commandes artisan (cron, fiscal)
      Contracts/                    # Interfaces (AnchoringProvider, etc.)
      Events/                       # Evenements metier
      Exceptions/                   # Exceptions custom
      Http/
        Controllers/
          Api/                      # Controllers API utilisateur
            Admin/                  # Controllers admin
            V1/                     # Controllers V1 (tenant, fiscal, onboarding)
          Webhooks/                 # Controllers webhooks entrants
        Middleware/                 # 18 middleware custom
        Requests/                  # Form Requests (validation)
        Resources/                 # API Resources (serialisation)
      Jobs/                        # Jobs asynchrones (Horizon)
      MCP/                         # Serveur MCP (54 outils)
        Session/                   # Gestion sessions MCP
        Tools/                     # Outils MCP par categorie
        Transport/                 # Transport HTTP/SSE
      Models/                      # 41 modeles Eloquent
        Traits/                    # HasTenantScope, LogsImmutabilityViolation
      Notifications/               # Notifications email
      Observers/                   # InvoiceObserver, CreditNoteObserver
      Policies/                    # Policies d'autorisation
      Providers/                   # Service providers
      Rules/                       # Regles de validation custom
      Services/                    # Services metier
        BulkGate/                  # Integration SMS
        FacturX/                   # Generation Factur-X
        Fiscal/                    # Module fiscal NF525
          Providers/               # Providers d'ancrage (RFC3161)
        Onboarding/                # Onboarding B2B
        OpenAPI/                   # Integration OpenAPI.com
        Sandbox/                   # Services mock
        SuperPDP/                  # Integration SuperPDP
    config/                        # Configuration (fiscal, mcp, billing, etc.)
    database/
      factories/                   # Factories de test
      migrations/                  # 51 migrations
      seeders/                     # Seeders (FiscalRuleSeeder, etc.)
    routes/
      api.php                      # Toutes les routes API (~400 lignes)
    storage/
      api-docs/                    # Specification OpenAPI generee
      certs/                       # Certificats (INSEE)
    tests/
      Feature/                     # Tests d'integration
      Unit/                        # Tests unitaires

  frontend/                        # SPA React 19
    packages/
      onboarding-widget/           # Widget embarquable
    src/
      components/                  # Composants reutilisables
        layout/                    # Header, Sider, Title
      content/legal/               # Contenus legaux (CGU, CGV, etc.)
      context/                     # Contexts React (Theme, Environment)
      contexts/                    # Contexts metier (Tenant)
      hooks/                       # Hooks custom
      i18n/                        # Internationalisation (FR, EN)
        locales/
          en/                      # Traductions anglaises
          fr/                      # Traductions francaises
      pages/
        admin/                     # Pages administration
        auth/                      # Pages connexion/inscription
        dashboard/                 # Pages dashboard utilisateur
        landing/                   # Pages publiques
        onboarding/                # Flux d'onboarding
        tenant/                    # Pages tenant multi-tenant
      providers/                   # Data et auth providers Refine
      styles/                      # Theme Ant Design, CSS
      types/                       # Types TypeScript

  superpdp-agent/                  # Agent MCP Node.js
    src/
      index.ts                     # Point d'entree
      superpdp-docs.ts             # Documentation SuperPDP

  assets/                          # Logos, icones, favicons
  docs/                            # Documentation technique
    dev/                           # Documentation developpeur
    plans/                         # Plans d'architecture
    postman/                       # Collections Postman

7. Variables d'Environnement

Backend (`backend/.env`)

Les variables essentielles pour le developpement local :

bash

# Application
APP_NAME=Scell.io
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost:8000

# Base de donnees
DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=scell_io
DB_USERNAME=postgres
DB_PASSWORD=

# Redis
REDIS_HOST=127.0.0.1
REDIS_PORT=6379

# Queue
QUEUE_CONNECTION=redis

# Sandbox (services mock actives en local)
SANDBOX_ENABLED=true

Consulter backend/.env.example pour la liste complete incluant les cles API des services externes (OpenAPI.com, BulkGate, Stripe, INSEE, etc.).

Frontend (`frontend/.env`)

bash

VITE_API_URL=http://localhost:8000/api
VITE_APP_NAME=Scell.io
VITE_ENVIRONMENT=local

8. Depannage

Erreurs frequentes

"SQLSTATE Connection refused"

PostgreSQL n'est pas demarre ou les parametres .env sont incorrects.

bash

# Verifier que PostgreSQL tourne
sudo systemctl status postgresql
# Verifier la connexion
psql -U postgres -d scell_io -c "SELECT 1"

"Redis connection refused"

bash

# Verifier que Redis tourne
redis-cli ping
# Attendu : PONG

"Class not found" apres ajout de modele

bash

cd backend
composer dump-autoload

Tests echouent avec "table does not exist"

bash

cd backend
php artisan migrate:fresh --seed --env=testing

Frontend : "Failed to fetch" lors des appels API

Verifier que :

Le backend tourne (php artisan serve)
La variable VITE_API_URL pointe vers la bonne URL
La configuration CORS est correcte (backend/config/cors.php)

Commandes utiles

bash

# Backend
cd backend
php artisan route:list                    # Lister toutes les routes
php artisan migrate:status                # Statut des migrations
php artisan config:clear                  # Vider le cache de config
php artisan cache:clear                   # Vider le cache applicatif
php artisan queue:work                    # Worker de queue (dev)
php artisan horizon                       # Dashboard Horizon

# Frontend
cd frontend
npm run build                             # Build production
npm run lint                              # Lint ESLint

Guide de Contribution Scell.io ​

Table des matieres ​

1. Prerequis ​

Outils requis ​

Extensions PHP requises ​

Services ​

2. Installation ​

2.1 Cloner le depot ​

2.2 Backend (Laravel) ​

2.3 Frontend (React) ​

2.4 Services optionnels ​

2.5 Verification de l'installation ​

3. Conventions de Code ​

3.1 Backend (PHP / Laravel) ​

3.2 Frontend (React / TypeScript) ​

3.3 Base de donnees ​

4. Workflow Git ​

4.1 Branches ​

4.2 Commits conventionnels ​

4.3 Processus de Pull Request ​

5. Tests ​

5.1 Backend ​

5.2 Structure des tests ​

5.3 Convention de test ​

5.4 Tester les cas critiques ​

6. Structure du Projet ​

7. Variables d'Environnement ​

Backend (backend/.env) ​

Frontend (frontend/.env) ​

8. Depannage ​

Erreurs frequentes ​

Commandes utiles ​

Guide de Contribution Scell.io

Table des matieres

1. Prerequis

Outils requis

Extensions PHP requises

Services

2. Installation

2.1 Cloner le depot

2.2 Backend (Laravel)

2.3 Frontend (React)

2.4 Services optionnels

2.5 Verification de l'installation

3. Conventions de Code

3.1 Backend (PHP / Laravel)

3.2 Frontend (React / TypeScript)

3.3 Base de donnees

4. Workflow Git

4.1 Branches

4.2 Commits conventionnels

4.3 Processus de Pull Request

5. Tests

5.1 Backend

5.2 Structure des tests

5.3 Convention de test

5.4 Tester les cas critiques

6. Structure du Projet

7. Variables d'Environnement

Backend (`backend/.env`)

Frontend (`frontend/.env`)

8. Depannage

Erreurs frequentes

Commandes utiles