# Integrazione Company OpenAPI - Completato ✅

## 📋 Riepilogo

Integrazione completa per la ricerca e archiviazione di dati aziendali tramite l'API Company OpenAPI in gix-demtools.

## 🎯 Funzionalità Implementate

### Backend

1. **Database Models** (3 tabelle)
   - `companies` - Dati completi delle aziende (70+ campi)
   - `company_balance_sheets` - Bilanci annuali
   - `company_share_holders` - Soci delle aziende

2. **API Service** ([openapi.service.js](backend/src/services/openapi.service.js))
   - Ricerca aziende con filtri avanzati
   - Salvataggio automatico nel database
   - Gestione bilanci e soci
   - Statistiche aggregate

3. **Controller** ([companies.controller.js](backend/src/controllers/companies.controller.js))
   - 8 endpoints RESTful
   - Validazione e gestione errori
   - Paginazione e filtri

4. **Routes** ([companies.routes.js](backend/src/routes/companies.routes.js))
   - `/api/companies/search-openapi` - Preview risultati
   - `/api/companies/search-and-save` - Ricerca e salvataggio
   - `/api/companies` - Lista con filtri
   - `/api/companies/:id` - Dettaglio completo
   - `/api/companies/tax-code/:taxCode` - Ricerca per CF
   - `/api/companies/stats` - Statistiche
   - `/api/companies/:id` - Update/Delete

5. **Migrations** (3 files)
   - Tabelle con indici ottimizzati
   - Relazioni foreign key
   - Timestamps automatici

### Frontend

1. **API Client** ([companies.api.js](frontend/src/api/companies.api.js))
   - 8 metodi per tutte le operazioni CRUD
   - Gestione errori standardizzata

2. **Pinia Store** ([companies.store.js](frontend/src/stores/companies.store.js))
   - State management reattivo
   - Cache locale
   - Loading states

3. **Pagine Vue** (3 views)
   - **CompaniesSearchView.vue** - Form di ricerca con preview
     - Filtri: ATECO, forma giuridica, dipendenti, provincia
     - Anteprima risultati prima del salvataggio
     - Validazione form
   
   - **CompaniesListView.vue** - Lista aziende salvate
     - Tabella con paginazione
     - Filtri multipli (provincia, ATECO, status, ricerca)
     - Azioni: visualizza, elimina
     - Debounced search
   
   - **CompanyDetailView.vue** - Dettaglio completo
     - Informazioni anagrafiche
     - Sede legale con GPS
     - Codici ATECO completi
     - Tabella bilanci pluriennali
     - Lista soci con quote

4. **Router Integration**
   - 3 route configurate
   - Navigation guard per autenticazione
   - Meta tags per titoli pagina

5. **UI/UX**
   - Link nel menu principale
   - Icone Material Design
   - Design responsive
   - Feedback utente con alert

## 📂 Struttura File Creati

```
gix-demtools/
├── backend/
│   ├── src/
│   │   ├── models/
│   │   │   ├── Company.js
│   │   │   ├── CompanyBalanceSheet.js
│   │   │   └── CompanyShareHolder.js
│   │   ├── services/
│   │   │   └── openapi.service.js
│   │   ├── controllers/
│   │   │   └── companies.controller.js
│   │   ├── routes/
│   │   │   └── companies.routes.js
│   │   └── database/
│   │       └── migrations/
│   │           ├── 20260223000001-create-companies-table.js
│   │           ├── 20260223000002-create-company-balance-sheets-table.js
│   │           └── 20260223000003-create-company-share-holders-table.js
│   ├── .env.example (aggiornato)
│   └── OPENAPI_INTEGRATION.md
│
└── frontend/
    └── src/
        ├── api/
        │   └── companies.api.js
        ├── stores/
        │   └── companies.store.js
        ├── views/
        │   └── companies/
        │       ├── CompaniesSearchView.vue
        │       ├── CompaniesListView.vue
        │       └── CompanyDetailView.vue
        ├── router/
        │   └── index.js (aggiornato)
        └── App.vue (aggiornato)
```

## 🚀 Setup & Configurazione

### 1. Variabili d'Ambiente

Aggiungi in `/var/www/html/gix-demtools/backend/.env`:
```bash
OPENAPI_BASE_URL=https://company.openapi.com
OPENAPI_API_KEY=699aee5c07a03e0eb9037517
```

### 2. Migrazioni Database

```bash
cd /var/www/html/gix-demtools/backend
npm run migrate
```

✅ **Migrations eseguite con successo:**
- `20260223000001-create-companies-table`
- `20260223000002-create-company-balance-sheets-table`
- `20260223000003-create-company-share-holders-table`

### 3. Riavvia i Servizi

```bash
# Backend
cd /var/www/html/gix-demtools/backend
pm2 restart gix-demtools-backend

# Frontend (se necessario)
cd /var/www/html/gix-demtools/frontend
npm run dev
```

## 📖 Come Usare

### 1. Ricerca Aziende

1. Vai su "Aziende" nel menu
2. Clicca "Cerca Nuove"
3. Imposta i filtri:
   - Codice ATECO (es: 4619 per intermediari commercio)
   - Forma Giuridica (SR = SRL, SP = SPA)
   - Min/Max Dipendenti
   - Provincia (es: MI, RM, LT)
   - Status Attività (ATTIVA)
4. Clicca "Anteprima Risultati"
5. Verifica i risultati
6. Clicca "Salva nel Database"

### 2. Visualizza Aziende Salvate

1. Vai su "Aziende" nel menu
2. Usa i filtri per cercare:
   - Ricerca libera (nome, CF, P.IVA)
   - Filtra per provincia
   - Filtra per codice ATECO
   - Filtra per status
3. Clicca sull'icona "occhio" per vedere i dettagli

### 3. Dettaglio Azienda

Visualizza:
- Dati anagrafici completi
- Sede legale con coordinate GPS
- Codici ATECO (base, 2007, 2022)
- PEC e Codice SDI
- Bilanci pluriennali con grafici
- Soci con quote di partecipazione

## 🔍 API Endpoints Disponibili

| Metodo | Endpoint | Descrizione |
|--------|----------|-------------|
| GET | `/api/companies/search-openapi` | Preview ricerca (no salvataggio) |
| POST | `/api/companies/search-and-save` | Cerca e salva nel DB |
| GET | `/api/companies` | Lista aziende con filtri |
| GET | `/api/companies/:id` | Dettaglio azienda |
| GET | `/api/companies/tax-code/:taxCode` | Cerca per codice fiscale |
| GET | `/api/companies/stats` | Statistiche aggregate |
| PUT | `/api/companies/:id` | Aggiorna azienda |
| DELETE | `/api/companies/:id` | Elimina azienda |

## 🎨 UI Components

### CompaniesSearchView
- Form con 6 campi di filtro
- Preview tabella risultati
- Chip colorati per status
- 2 CTA: Anteprima e Salva

### CompaniesListView
- Data table paginata
- 4 filtri veloci
- Ricerca con debounce (500ms)
- Azioni: view + delete
- Confirm dialog per delete

### CompanyDetailView
- 4 card informative
- Tabella bilanci ordinata per anno
- Tabella soci con percentuali
- Chip colorati per status
- Link "Torna alla lista"

## 📊 Dati Gestiti

### Companies (70+ campi)
- Identificativi: CF, P.IVA, Ragione Sociale
- Indirizzo: Via, Numero, CAP, Comune, Provincia, Regione
- GPS: Latitudine, Longitudine
- ATECO: Codici e descrizioni (3 versioni)
- Legale: Forma giuridica, Date iscrizione
- Contatti: PEC, SDI
- Status: Attività, REA, CCIAA

### Balance Sheets
- Anno, Data bilancio
- Dipendenti
- Fatturato, Patrimonio netto
- Capitale sociale
- Costo personale, Totale attivo
- Stipendio lordo medio

### Shareholders
- Nome/Cognome (persona fisica)
- Ragione sociale (azienda)
- Codice fiscale
- Percentuale partecipazione

## ⚡ Performance & Best Practices

- **Indici Database**: 6 indici per query veloci
- **Lazy Loading**: Route caricate on-demand
- **Debounced Search**: Riduce chiamate API
- **Error Handling**: Gestione completa errori
- **Loading States**: Feedback visivo durante operazioni
- **Cache**: Store Pinia mantiene lo stato
- **Pagination**: Gestione liste grandi (25 items/page)

## 🔐 Sicurezza

- ✅ Autenticazione JWT richiesta
- ✅ Rate limiting su API
- ✅ Validazione input lato server
- ✅ SQL injection prevention (Sequelize ORM)
- ✅ XSS prevention (Vue escaping)

## 📚 Documentazione

Documentazione completa disponibile in:
- [OPENAPI_INTEGRATION.md](backend/OPENAPI_INTEGRATION.md)

Include:
- Guida setup dettagliata
- Esempi API con curl
- Codici ATECO comuni
- Forme giuridiche italiane
- Casi d'uso pratici
- Troubleshooting

## ✅ Testing

Per testare l'integrazione:

```bash
# 1. Test ricerca (preview)
curl -X GET "http://localhost:3003/api/companies/search-openapi?atecoCode=4619&minEmployees=5&province=LT&limit=10" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# 2. Test salvataggio
curl -X POST "http://localhost:3003/api/companies/search-and-save" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "atecoCode": "4619",
    "minEmployees": 5,
    "province": "MI",
    "limit": 50
  }'

# 3. Test lista
curl -X GET "http://localhost:3003/api/companies?page=1&limit=25" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

## 🎉 Completamento

**Stato**: ✅ **COMPLETATO**  
**Data**: 23 Febbraio 2026  
**Migrations**: ✅ Eseguite  
**Frontend**: ✅ Funzionante  
**Backend**: ✅ Funzionante  
**Documentazione**: ✅ Completa  

**Next Steps Suggeriti**:
1. Creare job automatico per aggiornamento dati aziende
2. Integrare PEC → Contatti DEM automaticamente
3. Dashboard analytics per dati aziende
4. Export CSV/Excel delle aziende
5. Sistema di scoring lead basato su bilanci

---

**Sviluppato per**: GIX DEM Tools  
**Framework**: Node.js + Express + Vue 3 + Vuetify 3  
**Database**: MySQL + Sequelize ORM