480e7eafbd
📋 Commit iniziale con: - ✅ Documentazione unificata in docs/ - ✅ Codice Laravel in netgescon-laravel/ - ✅ Script automazione in scripts/ - ✅ Configurazione sync rsync - ✅ Struttura organizzata e pulita 🔄 Versione: 2025.07.19-1644 🎯 Sistema pronto per Git distribuito
307 lines
15 KiB
Plaintext
307 lines
15 KiB
Plaintext
Documentazione API e Cosa Chiedere al Gruppo
|
||
|
||
sistema Laravel: Espone degli endpoint API REST per ricevere i dati.
|
||
|
||
Noi abbiamo già definito gli endpoint API principali per l'importazione e i relativi payload JSON attesi.
|
||
|
||
|
||
Endpoint URL e Metodi HTTP:
|
||
|
||
POST /api/v1/import/condominio
|
||
POST /api/v1/import/fornitore
|
||
POST /api/v1/import/anagrafica (Definiti in routes/api.php e gestiti da ImportController)
|
||
Formato Dati Richiesto (Payload JSON Esempi): Li abbiamo definiti nella nostra precedente conversazione. Ad esempio, per /api/v1/import/condominio:
|
||
|
||
json
|
||
{
|
||
"id_stabile": 123,
|
||
"denominazione": "Condominio Primavera",
|
||
"indirizzo": "Via dei Girasoli 10",
|
||
"cap": "00100",
|
||
"citta": "Roma",
|
||
"pr": "RM",
|
||
"codice_fisc": "9876543210987654",
|
||
"cf_amministratore": "RSSMRA80A01H501X",
|
||
"note1": "Note aggiuntive"
|
||
}
|
||
|
||
Devi fornire esempi simili per fornitore e anagrafica basati sulle validazioni e sulla logica in ImportController.
|
||
|
||
Campi Obbligatori e Opzionali: Questi sono definiti nelle regole di validazione dentro ImportController (es. 'id_stabile' => ['required', 'integer']).
|
||
|
||
Risposta Attesa: I metodi in ImportController restituiscono risposte JSON come:
|
||
|
||
Successo: {'message': 'Condominio importato...', 'data': { ... }} (status 200 o 201)
|
||
Errore di validazione: Struttura JSON di Laravel con gli errori (status 422)
|
||
Non trovato/Non autorizzato: {'message': '...'} (status 404, 403)
|
||
Autenticazione: Tramite Bearer Token (Authorization: Bearer <TOKEN>).
|
||
Il token viene generato dall'amministratore nella dashboard del sistema Laravel.
|
||
|
||
Conferma di Comprensione degli Endpoint Esistenti:
|
||
|
||
"Avete ricevuto e compreso la documentazione degli endpoint API /api/v1/import/condominio, /api/v1/import/fornitore e /api/v1/import/anagrafica, inclusi URL, metodo POST, payload JSON attesi e meccanismo di autenticazione con Bearer Token?"
|
||
Mappatura Dati dal Vecchio GESCON:
|
||
|
||
"La struttura delle tabelle del vecchio GESCON (che avete elencato e che è nel file GESCON schermate\tabelle per importazioni dati da GESCON.txt) è la base da cui estrarrete i dati. Avete bisogno di chiarimenti su come mappare i campi specifici di quelle tabelle ai campi dei payload JSON che i nostri endpoint si aspettano?"
|
||
Ad esempio, per condomin.nom_cond come deve essere mappato a anagrafiche.ragione_sociale o nome/cognome? (Attualmente il nostro ImportController per anagrafica usa nom_cond per ragione_sociale).
|
||
Gestione delle Dipendenze nell'Importazione:
|
||
|
||
"Quale sarà l'ordine di importazione dei dati? Ad esempio, è necessario importare prima un Condominio (da stabili) prima di poter importare un'Anagrafica (da condomin) e associarla a un'unità immobiliare di quel condominio (usando condomin.id_stabile per trovare il condominio_id nuovo)?"
|
||
Questo è cruciale perché l'endpoint importAnagrafica cerca un Condominio esistente tramite old_id (che corrisponde a stabili.id_stabile).
|
||
Necessità di Endpoint per Altre Entità:
|
||
|
||
"Le tabelle del vecchio GESCON includono anche rate, incassi, singolo_anno_assemblee. Avete bisogno di endpoint API specifici per importare anche questi dati? Se sì, per ognuna:
|
||
Quali campi sono essenziali?
|
||
Come si relazionano alle entità già importate (condomini, anagrafiche)?" (Se servono, dovremo creare nuovi metodi in ImportController e nuove rotte API).
|
||
Dettagli sulla Tabella parti_comuni_amministratore:
|
||
|
||
"La tabella parti_comuni_amministratore del vecchio GESCON sembra contenere i dettagli dello studio di amministrazione. Questi dati nel nuovo sistema sono gestiti nella tabella amministratori (collegata a users). L'importazione di questi dati avviene implicitamente quando un utente con ruolo amministratore si registra o viene creato, o c'è necessità di un import massivo anche per questi?"
|
||
Nota: Attualmente non abbiamo un endpoint API per importare amministratori perché la logica è che un Amministratore (utente) usa le API per importare i suoi dati condominiali.
|
||
Chiarimenti sui Campi Specifici (se necessario):
|
||
|
||
Ad esempio, in condomin, ci sono E_mail_condomino e E_mail_inquilino. L'attuale importAnagrafica usa solo E_mail_condomino. Se E_mail_inquilino deve generare un'anagrafica separata di tipo 'inquilino' per la stessa unità, il payload e la logica dell'API andranno adattati.
|
||
|
||
|
||
Assicurati che il tuo gruppo comprenda che gli old_id (es. id_stabile, id_fornitore, id_cond) che inviano nei payload JSON sono gli ID primari delle rispettive tabelle nel vecchio database GESCON.
|
||
Il sistema Laravel li userà per updateOrCreate e per mantenere un riferimento all'origine del dato.
|
||
|
||
|
||
****************************
|
||
Ecco come puoi organizzare le informazioni da fornire al gruppo che prepara **maschere** e **archivi** per l’importazione dati via API REST.
|
||
|
||
---
|
||
|
||
## 1. **Struttura delle tabelle principali e relazioni**
|
||
|
||
### **Tabelle principali (esempio):**
|
||
- **condomin**: anagrafica condomini
|
||
- **stabili**: dettagli stabili/edifici
|
||
- **fornitori**: anagrafica fornitori
|
||
- **rate**: rate condominiali
|
||
- **incassi**: pagamenti ricevuti
|
||
- **parti_comuni_amministratore**: amministratori
|
||
- **singolo_anno_assemblee**: assemblee annuali
|
||
|
||
### **Esempio di struttura e relazioni**
|
||
|
||
| Tabella | Campo | Tipo | Descrizione | Relazione |
|
||
|-------------|--------------------|--------------|------------------------------------|--------------------------|
|
||
| condomin | id | int | PK Condominio | |
|
||
| condomin | denominazione | varchar | Nome condominio | |
|
||
| condomin | indirizzo | varchar | Indirizzo | |
|
||
| condomin | amministratore_id | int | FK amministratore | parti_comuni_amministratore.id |
|
||
| stabili | id | int | PK Stabile | |
|
||
| stabili | condominio_id | int | FK condominio | condomin.id |
|
||
| fornitori | id | int | PK Fornitore | |
|
||
| fornitori | nome | varchar | Nome fornitore | |
|
||
| rate | id | int | PK Rata | |
|
||
| rate | condominio_id | int | FK condominio | condomin.id |
|
||
| incassi | id | int | PK Incasso | |
|
||
| incassi | rata_id | int | FK rata | rate.id |
|
||
| parti_comuni_amministratore | id | int | PK Amministratore | |
|
||
| singolo_anno_assemblee | id | int | PK Assemblea | |
|
||
| singolo_anno_assemblee | condominio_id | int | FK condominio | condomin.id |
|
||
|
||
> **Nota:**
|
||
> Le relazioni FK (foreign key) sono solo indicative: verifica i nomi reali dei campi nel tuo database!
|
||
|
||
---
|
||
|
||
## 2. **Cosa fornire al gruppo che prepara le maschere/archivi**
|
||
|
||
- **Per ogni tabella**:
|
||
- Nome tabella
|
||
- Elenco campi (nome, tipo, descrizione)
|
||
- Chiavi primarie e chiavi esterne (relazioni)
|
||
- Esempio dati (opzionale, aiuta molto)
|
||
|
||
- **Schema delle relazioni** (come sopra, tabella con FK)
|
||
|
||
- **Eventuali vincoli** (es: un condominio può avere più stabili, una rata appartiene a un condominio, ecc.)
|
||
|
||
---
|
||
|
||
## 3. **Cosa chiedere al gruppo che prepara le API REST**
|
||
|
||
Chiedi di fornirti per ogni endpoint:
|
||
|
||
- **Endpoint URL** (es: `/api/v1/import/condominio`)
|
||
- **Metodo HTTP** (POST, PUT, ecc.)
|
||
- **Formato dati richiesto** (JSON, con esempio payload)
|
||
- **Campi obbligatori e opzionali**
|
||
- **Risposta attesa** (esempio di risposta JSON)
|
||
- **Gestione errori** (come vengono restituiti gli errori)
|
||
- **Eventuali vincoli di autenticazione** (token, Bearer, ecc.)
|
||
|
||
---
|
||
|
||
## 4. **Esempio di documentazione da inviare**
|
||
|
||
### **Tabella: condomin**
|
||
| Campo | Tipo | Descrizione | Relazione/FK |
|
||
|------------------|-----------|---------------------|-----------------------------|
|
||
| id | int | PK | |
|
||
| denominazione | varchar | Nome condominio | |
|
||
| indirizzo | varchar | Indirizzo | |
|
||
| amministratore_id| int | FK amministratore | parti_comuni_amministratore |
|
||
|
||
### **Endpoint API**
|
||
- **URL:** `/api/v1/import/condominio`
|
||
- **Metodo:** POST
|
||
- **Payload esempio:**
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"denominazione": "Condominio Alfa",
|
||
"indirizzo": "Via Roma 1",
|
||
"amministratore_id": 2
|
||
}
|
||
```
|
||
- **Risposta attesa:**
|
||
```json
|
||
{ "ok": true, "id": 1 }
|
||
```
|
||
|
||
---
|
||
|
||
## 5. **Checklist per il gruppo API**
|
||
|
||
Chiedi di fornirti:
|
||
- Elenco endpoint disponibili
|
||
- Per ogni endpoint: payload richiesto, risposta attesa, campi obbligatori
|
||
- Specifica delle relazioni tra i dati (es: come collegare rate e incassi)
|
||
- Specifica autenticazione (token, Bearer, ecc.)
|
||
|
||
---
|
||
|
||
**Se vuoi, puoi incollare qui la struttura di una tabella (output di DESCRIBE) e ti aiuto a scrivere la documentazione dettagliata per il gruppo!**
|
||
|
||
|
||
*******************************************************
|
||
|
||
Chiamate API REST per l'Importazione
|
||
L'autenticazione avviene tramite un token API che l'amministratore (utente con ruolo amministratore) genera dalla sua dashboard.
|
||
|
||
Header Comuni per tutte le richieste API:
|
||
|
||
Authorization: Bearer <IL_TUO_TOKEN_API>
|
||
Accept: application/json
|
||
Content-Type: application/json (per le richieste POST con payload JSON)
|
||
Endpoint e Payload Esempio:
|
||
|
||
Importa Condominio (Stabile)
|
||
|
||
Endpoint: POST /api/v1/import/condominio
|
||
Controller: App\Http\Controllers\Api\ImportController@importCondominio
|
||
Payload JSON Esempio (basato su stabili e validazione controller):
|
||
json
|
||
{
|
||
"id_stabile": 123, // old_id da stabili.id_stabile
|
||
"cod_stabile": "STAB001", // opzionale, per stabili.cod_stabile
|
||
"denominazione": "Condominio Primavera", // per stabili.denominazione
|
||
"indirizzo": "Via dei Girasoli 10", // per stabili.indirizzo
|
||
"cap": "00100", // per stabili.cap
|
||
"citta": "Roma", // per stabili.citta
|
||
"pr": "RM", // per stabili.pr
|
||
"codice_fisc": "9876543210987654", // per stabili.codice_fisc
|
||
"cf_amministratore": "RSSMRA80A01H501X", // per stabili.cf_amministratore
|
||
"note1": "Note aggiuntive sul condominio" // per stabili.note1
|
||
}
|
||
Importa Fornitore
|
||
|
||
Endpoint: POST /api/v1/import/fornitore
|
||
Controller: App\Http\Controllers\Api\ImportController@importFornitore
|
||
Payload JSON Esempio (basato su fornitori e validazione controller):
|
||
json
|
||
{
|
||
"id_fornitore": 45, // old_id da fornitori.id_fornitore
|
||
"cognome": "Rossi", // per fornitori.cognome (o parte della ragione sociale)
|
||
"nome": "Mario", // per fornitori.nome (o parte della ragione sociale)
|
||
"indirizzo": "Via Garibaldi 50", // per fornitori.indirizzo
|
||
"cap": "20100", // per fornitori.cap
|
||
"citta": "Milano", // per fornitori.citta
|
||
"pr": "MI", // per fornitori.pr
|
||
"p_iva": "01234567890", // per fornitori.p_iva
|
||
"cod_fisc": "RSSMRA75B01F205Z", // per fornitori.cod_fisc
|
||
"Indir_Email": "mario.rossi@example.com", // per fornitori.Indir_Email
|
||
"Cellulare": "3331234567", // per fornitori.Cellulare
|
||
"PEC_Fornitore": "mario.rossi@pec.example.com" // per fornitori.PEC_Fornitore
|
||
}
|
||
Nota: Nel controller importFornitore, ragione_sociale è costruita concatenando cognome e nome. Se hai una ragione_sociale completa nel vecchio DB, potresti volerla passare direttamente e adattare il controller.
|
||
Importa Anagrafica (e associazione a Unità)
|
||
|
||
Endpoint: POST /api/v1/import/anagrafica
|
||
Controller: App\Http\Controllers\Api\ImportController@importAnagrafica
|
||
Payload JSON Esempio (basato su condomin e validazione controller):
|
||
json
|
||
{
|
||
"id_cond": 789, // old_id da condomin.id_cond
|
||
"nom_cond": "Bianchi Luigi (Prop.)", // per condomin.nom_cond
|
||
"ind": "Via Roma 1, Apt 3", // per condomin.ind (indirizzo dell'anagrafica, se diverso da quello dell'unità)
|
||
"cap": "00150", // per condomin.cap
|
||
"citta": "Roma", // per condomin.citta
|
||
"pr": "RM", // per condomin.pr
|
||
"E_mail_condomino": "luigi.bianchi@example.com", // per condomin.E_mail_condomino
|
||
// "E_mail_inquilino": "paolo.verdi@example.com", // Se hai un campo separato e vuoi creare un'altra anagrafica
|
||
"id_stabile": 123, // ID del vecchio stabile (stabili.id_stabile) a cui questa anagrafica/unità appartiene
|
||
"scala": "A", // per condomin.scala (per identificare/creare l'UnitaImmobiliare)
|
||
"int": "3", // per condomin.int (per identificare/creare l'UnitaImmobiliare)
|
||
"tipo_pr": "PR" // per condomin.tipo_pr (es. PR, IN, US per mappare a proprietario, inquilino, usufruttuario)
|
||
// Aggiungere altri campi se necessari e validati:
|
||
// "cod_fisc": "BNCLGU...",
|
||
// "telefono": "06112233"
|
||
}
|
||
|
||
|
||
***************************************************************************************************
|
||
php artisan tinker
|
||
Psy Shell v0.12.8 (PHP 8.3.6 — cli) by Justin Hileman
|
||
> $user = App\Models\User::where('email', 'michele@nethome.it')->first();
|
||
= App\Models\User {#6339
|
||
id: 2,
|
||
name: "michele barone",
|
||
email: "michele@nethome.it",
|
||
email_verified_at: null,
|
||
#password: "$2y$12$ndylLy53XFHexUNGNtA4xe5kKgO9DOxTm6n7YFia9sdvshKU4bVDq",
|
||
role: "admin",
|
||
#remember_token: null,
|
||
created_at: "2025-06-16 00:00:59",
|
||
updated_at: "2025-06-16 00:01:39",
|
||
}
|
||
|
||
|
||
> echo $user->createToken('import-token')->plainTextToken;
|
||
1|yBuaEHKsPtKRcVrQlsfnTWjKTES3Z2e9mwmfVeX0524f371d⏎
|
||
>
|
||
|
||
curl -X POST http://127.0.0.1:8000/api/v1/import/condominio \
|
||
-H "Authorization: yBuaEHKsPtKRcVrQlsfnTWjKTES3Z2e9mwmfVeX0524f371d" \
|
||
-H "Content-Type: application/json" \
|
||
-H "Accept: application/json" \
|
||
-d '{
|
||
"id_stabile": 148,
|
||
"denominazione": "SUPERCONDOMINIO MILIZIE 3",
|
||
"indirizzo": "VIALE DELLE MILIZIE 3",
|
||
"cap": "00192",
|
||
"citta": "Roma",
|
||
"pr": "RM",
|
||
"codice_fisc": "97487690584",
|
||
"cf_amministratore": "TRDCCL74T52H501R"
|
||
}'
|
||
|
||
|
||
curl -X POST http://127.0.0.1:8000/api/v1/import/fornitore \
|
||
-H "Authorization: yBuaEHKsPtKRcVrQlsfnTWjKTES3Z2e9mwmfVeX0524f371d" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"id_fornitore": 1,
|
||
"cognome": "Idraulica Rossi",
|
||
"nome": "SNC",
|
||
"p_iva": "01234567890"
|
||
}'
|
||
|
||
|
||
sto cercando di inserire un valore nella colonna `cod_fisc_amministratore` nella tabella `condomini`,
|
||
ma questa colonna **non esiste** nella tabella.
|
||
|
||
Token API creato con successo! Copia il token: 3|yVt3r764wovEAyrenzwDSqGnbNmFuPgG7Q1pmIfz915f1605 |