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/erp/
│   └── {module}/           # Data access per modulo
│       └── {Resource}_api_model.php
│
├── routes/erp/
│   └── {module}.php        # Route per modulo
│
└── 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}/{id}/{action}

Esempi:

GET  /erp/admin/brands           # Lista marchi
POST /erp/admin/brands           # Crea marchio
GET  /erp/admin/brands/123       # Dettaglio marchio
PUT  /erp/admin/brands/123       # Aggiorna marchio
DELETE /erp/admin/brands/123     # Elimina marchio (soft delete)
POST /erp/admin/brands/123/restore  # Ripristina marchio

Flusso Richiesta

Request
   │
   ▼
┌─────────────────────────────────────────────────────────────┐
│  routes/erp/{module}.php                                     │
│  Mappa URL → Controller method                              │
└─────────────────────────────────────────────────────────────┘
   │
   ▼
┌─────────────────────────────────────────────────────────────┐
│  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/erp/{module}/{Resource}_api_model.php                │
│  - Query database                                           │
│  - CRUD operations                                          │
│  - Mapping dati                                             │
└─────────────────────────────────────────────────────────────┘

Organizzazione Routes

Le route sono organizzate per modulo in src/routes/:

// src/routes/erp/admin.php
$route['erp/admin/brands/(:num)/restore']['POST'] = 'erp/admin/brands/restore/$1';
$route['erp/admin/brands/(:num)'] = 'erp/admin/brands/id/$1';

Il file principale config/routes.php include i moduli:

// config/routes.php
require_once APPPATH . 'routes/erp/admin.php';
// require_once APPPATH . 'routes/erp/store.php';  // Future

Perche routes/ e non config/routes/?

La directory routes/ e separata da config/ per:

• Developer experience: Gli sviluppatori lavorano in routes/, non toccano config/
• Separazione: config/ contiene solo configurazione core
• Parallelismo: routes/erp/ e parallelo a controllers/erp/, models/erp/

Base Controller

Tutti i controller ERP estendono Erp_controller:

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

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

Fornisce:

• Accesso a $this->CI (CodeIgniter instance)
• 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->ctx->getCompanyId();

// Nella library
$this->CI->brands_api_model->getAll($companyId, ...);

// Nel model
$this->db->where('ID_COMPANY', $companyId);

Importante

Non fidarti mai dell'ID azienda passato dal client. Usa sempre $this->ctx->getCompanyId() 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}_api_model.php	Brands_api_model.php
Response	Erp{Resource}Responses.php	ErpBrandsResponses.php
Route file	{module}.php	admin.php
Endpoint	/erp/{module}/{resource}	/erp/admin/brands