Architettura ERP API

Questa pagina descrive l'architettura e la struttura delle API ERP.

Struttura Directory

Le API sono organizzate in moduli che rispecchiano la struttura di Elerama ERP:

src/
├── controllers/erp/
│   └── {module}/           # Controller per modulo
│       └── {Resource}.php
│
├── libraries/erp/
│   ├── Erp_controller.php  # Base controller (condiviso)
│   └── {module}/           # Business logic per modulo
│       └── {Resource}_api_lib.php
│
├── models/
│   └── {module}/           # Symlinks ai model di elerama
│       └── {Resource}_model.php → elerama/src/modules/...
│
└── response/contexts/erp/
    └── Erp{Resource}Responses.php

Moduli Disponibili

Modulo	Path	Descrizione
admin	/erp/admin/*	Anagrafiche base (brands, categories, groups)
store	/erp/store/*	Gestione magazzino (future)
orders	/erp/orders/*	Gestione ordini (future)

Pattern URL

Gli endpoint seguono il pattern:

/erp/{module}/{resource}
/erp/{module}/{resource}/{id}
/erp/{module}/{resource}/{action}

Esempi:

GET    /erp/admin/brands           # Lista marchi
POST   /erp/admin/brands           # Crea marchio
PUT    /erp/admin/brands/123       # Aggiorna marchio
DELETE /erp/admin/brands/123       # Elimina marchio
DELETE /erp/admin/brands/unused    # Elimina marchi non utilizzati

Flusso Richiesta

Request
   │
   ▼
┌─────────────────────────────────────────────────────────────┐
│  controllers/erp/{module}/{Resource}.php                     │
│  - Parsing parametri (query/body)                           │
│  - Validazione input                                        │
│  - Chiamata a library                                       │
│  - Formattazione response                                   │
└─────────────────────────────────────────────────────────────┘
   │
   ▼
┌─────────────────────────────────────────────────────────────┐
│  libraries/erp/{module}/{Resource}_api_lib.php               │
│  - Business logic                                           │
│  - Validazioni di dominio                                   │
│  - Orchestrazione operazioni                                │
│  - Ritorna ServiceResponse                                  │
└─────────────────────────────────────────────────────────────┘
   │
   ▼
┌─────────────────────────────────────────────────────────────┐
│  models/{module}/{Resource}_model.php                        │
│  - Symlink a model esistente in elerama                     │
│  - Query database                                           │
│  - CRUD operations                                          │
└─────────────────────────────────────────────────────────────┘

Base Controller

Tutti i controller ERP estendono Erp_controller:

// src/libraries/erp/Erp_controller.php
class Erp_controller extends REST_Controller
{
    protected $CI;
    protected $auth;

    public function __construct()
    {
        parent::__construct();
        $this->CI = &get_instance();
        $this->auth = $this->CI->auth;
    }
}

Fornisce:

• Accesso a $this->CI (CodeIgniter instance)
• Accesso a $this->auth per dati sessione
• Metodi REST ($this->get(), $this->post(), $this->put())
• Response handling

Response Pattern

Tutti i metodi della library ritornano ServiceResponse:

// Success
return ServiceResponseFactory::ok($data, 'brands', 'list');

// Error
return ServiceResponseFactory::fail(
    'brands',
    'notFound',
    ['id' => $id],
    ServiceErrorType::NotFound,
    'Marchio non trovato'
);

Il controller usa ErpApiResponseFactory per convertire in JSON:

ErpApiResponseFactory::brands()->auto($response)->toJson();

Multi-tenancy

Tutte le operazioni sono automaticamente filtrate per azienda:

// Nel controller
$companyId = $this->auth->get_active_company_id();

// Nella library
$this->CI->brands_model->read_brands($companyId);

Importante

Non fidarti mai dell'ID azienda passato dal client. Usa sempre $this->auth->get_active_company_id() per ottenere l'azienda dalla sessione autenticata.

Convenzioni di Naming

Elemento	Pattern	Esempio
Controller	{Resource}.php	Brands.php
Library	{Resource}_api_lib.php	Brands_api_lib.php
Model	{Resource}_model.php (symlink)	Brands_model.php
Response	Erp{Resource}Responses.php	ErpBrandsResponses.php
Endpoint	/erp/{module}/{resource}	/erp/admin/brands