Installazione

Prerequisiti

• JDK 21 e Maven 3.9+ (backend)
• Node.js 22 LTS e npm (frontend)
• PostgreSQL 16 (database)
• Apache Tomcat 10.1+ (deploy dei WAR)

1. Database

Il repository database contiene la procedura di installazione from-scratch in install/ (DDL completi dei 9 database, seed di bootstrap per menu/ruoli/traduzioni/cataloghi, creazione dell'amministratore e del portale) — vedi database/install/README.md:

export DB_PASSWORD='...' ADMIN_MAIL='...' ADMIN_PASSWORD='...' PORTAL_URL='https://...'
sudo -u postgres ./install.sh

Le cartelle schemas/, functions/, views/, migrations/ documentano l'evoluzione incrementale (utili per aggiornare un'installazione esistente, non per la prima installazione).

I database devono essere inesistenti o vuoti: install.sh non è idempotente su un database già popolato.

2. Librerie condivise

I microservizi dipendono da tre librerie com.kondorcs non pubblicate su Maven Central: installarle nel repository Maven locale in quest'ordine:

mvn -f kondorcs-utils/pom.xml clean install -DskipTests
mvn -f kondorcs-jwt/pom.xml   clean install -DskipTests
mvn -f kondorcs-model/pom.xml clean install -DskipTests

3. Microservizi Spring

Ogni servizio carica la configurazione da classpath:config/<company>/<env>.application.properties, selezionata con due proprietà JVM:

• -Dspring.profiles.company=<cartella> (es. example)
• -Dspring.profiles.active=<dev|test|prod>

Ogni repository include src/main/resources/config/example/ con tutti i parametri e placeholder al posto di credenziali e host: copiare la cartella example in una cartella con il nome della propria installazione (es. config/miaazienda/), compilare i valori (connessione DB, jwt.secret, SMTP, log) e ricompilare.

Il jwt.secret deve essere identico su tutti i servizi della stessa installazione e diverso per ogni installazione (base64, almeno 64 byte).

Build e deploy:

mvn -f ws_spring_portal_login/pom.xml clean package -DskipTests
# ... per ogni servizio; i WAR in target/ vanno deployati su Tomcat

In setenv.sh/setenv.bat di Tomcat impostare:

JAVA_OPTS="$JAVA_OPTS -Dspring.profiles.company=miaazienda -Dspring.profiles.active=prod"

Permessi dei file generati. Alcuni servizi scrivono file destinati al download (PDF, Excel, ZIP) sotto la cartella del portale (pathTemp, per impostazione predefinita <docroot>/assets/temp), che vengono poi serviti dal web server. Se web server e Tomcat girano con utenti diversi, quei file devono restare leggibili: catalina.sh impone umask 0027 (file 640) salvo che la variabile d'ambiente UMASK sia valorizzata, e il download risponderebbe 403. Impostare quindi UMASK=0022 nell'ambiente di Tomcat (con systemd, Environment="UMASK=0022" oltre a UMask=0022), oppure far girare il web server con un utente del gruppo di Tomcat.

Cartelle di lavoro

I servizi non creano le cartelle in cui scrivono: se una manca, la generazione del file termina con FileNotFoundException … (No such file or directory). Vanno create in anticipo e devono appartenere all'utente di Tomcat.

I percorsi sono quelli delle config/example: sono composti da una radice più un sottopercorso, quindi vanno creati anche i livelli intermedi.

Proprietà (servizio)	Percorso di esempio	Contenuto
pathTemp (tutti)	<docroot>/assets/temp	file generati per il download (PDF, Excel, ZIP)
pathLogo, pathTemplate (cmp)	<docroot>/assets/images, …/assets/templates	logo azienda, template documenti
file_upload_destination_path (cmp)	/repository	radice degli archivi del gestionale
+ qrcode_file_upload_path	/repository/qrcode	QR code di cantieri e sedi
+ xml_file_upload_path	/repository/import_xml	fatture XML importate
+ xml_fussi_path	/repository/flussi	flussi bancari
+ riconciliazioni_pdf_path	/repository/riconciliazioni	riconciliazioni
file_upload_destination_path (documentary)	/var/www/allegati + /pdf, /qrcode	archivio documentale
image_upload_destination_path (ecommerce)	/repository/onlineshop	immagini dei prodotti
image_upload_destination_path (bakeka)	/var/www/bacheca/<area>	foto e audio della bacheca
image_upload_temp_path (ecommerce, bakeka)	<docroot>/assets/temp/<area>	upload temporanei

Le cartelle sotto la docroot del portale (assets/…) vengono cancellate a ogni deploy del frontend: ricrearle subito dopo, insieme ai permessi.

4. Portale web

cd portale_angular_18
npm ci
npm run build:prod        # output in dist/browser

Per lo sviluppo locale: copiare src/environments/environment.local.ts.example in src/environments/environment.local.ts, configurare gli URL dei servizi e usare npm run start:local.

Documentazione delle API (opzionale)

Ogni WAR pubblica la propria specifica OpenAPI e la propria pagina Swagger UI:

• https://<host>/<servizio>/openapi.json
• https://<host>/<servizio>/swagger-ui.html

La pagina del singolo servizio prende gli asset di Swagger UI da /api-docs/, che è la cartella platform/api copiata nella docroot del portale:

cp -r platform/api /var/www/html/api-docs

Così si ottiene anche https://<host>/api-docs/, la Swagger UI unica con il selettore del servizio. Essendo dentro la docroot, il deploy del frontend la cancella: va ricopiata dopo ogni deploy, come le cartelle assets/….

Senza questo passo i servizi restano funzionanti e openapi.json resta scaricabile: solo l'interfaccia grafica non si carica, e la pagina lo dice.

Le specifiche descrivono l'intera superficie API. Non contengono segreti — il codice è pubblico — ma se preferisci non esporle, blocca /openapi.json e /swagger-ui.html nel reverse proxy: nessuna funzione della piattaforma le usa.

5. App mobile

cd app-data-smart
npm ci
npm run build:mytown      # web build + capacitor sync

Per generare l'APK Android serve un proprio progetto Firebase: creare android/app/google-services.json (vedi google-services.json.example se presente, o la console Firebase) e compilare con Android Studio / Gradle.

6. Scheduler (job pianificati)

Lo scheduler è incluso nella distribuzione (Windows / .NET Framework):

• kondorcs.scheduleservices — l'host KCSSchedule.exe (servizio Windows); requisito: .NET Framework 4.8 Developer Pack, build con MSBuild (VS 2022)
• kondorcs.schedulelibrary.datasmart — job Notificatore (coda users_notify e token SMS del 2FA), ReportFotovoltaico, CreditoSmsHosting
• kondorcs.schedulelibrary.aifileprocessor — estrazione dati da PDF documentali (certificati di pagamento, SAL, PDF generici)

Lo scheduler richiede Windows e un'istanza di Microsoft SQL Server (anche Express) per lo store della pianificazione (quali job, quando, con quali parametri) — separato dai database PostgreSQL della piattaforma. Ogni job legge/ scrive comunque i dati applicativi su PostgreSQL tramite la propria connection string. Procedura completa da zero:

a) Creare il job-store su SQL Server (script nel repo database):

sqlcmd -S <sqlserver> -E -Q "CREATE DATABASE KondorCS"
sqlcmd -S <sqlserver> -E -d KondorCS -i database/install-scheduler/10_schema_scheduler_sqlserver.sql

Crea 3 tabelle (KCS_ScheduleLibrarys, KCS_ScheduleConfigLibrarys, KCS_ScheduleLogs) e 2 stored procedure (KCS_ScheduleGetLibrarys, KCS_ScheduleSetLog).

b) Registrare il job Notificatore (notifiche + OTP del 2FA). Aprire database/install-scheduler/20_seed_scheduler_notificatore.sql, sostituire i placeholder (<mittente>, <PG_HOST>, <PG_USER>, <PG_PASSWORD> — la connection string PostgreSQL verso il proprio KCS-Portal), poi:

sqlcmd -S <sqlserver> -E -d KondorCS -i database/install-scheduler/20_seed_scheduler_notificatore.sql

c) Puntare l'host al job-store — la connection string verso SQL Server è letta dal registro di Windows (non dal .config dell'host):

reg add "HKLM\SOFTWARE\KondorCS\DATA" /v ConnDB /t REG_SZ ^
  /d "Data Source=<sqlserver>;Initial Catalog=KondorCS;User ID=<sql_user>;Password=<sql_password>"

d) Buildare e installare l'host (kondorcs.scheduleservices): compilare in Release (MSBuild, .NET Framework 4.8), copiare l'output dell'host + le DLL dei job (kondorcs.schedulelibrary.*, con le loro dipendenze) nella cartella di installazione (es. C:\KondorCS\Services\ScheduleServices\) e registrare il servizio con installutil KCSSchedule.exe (vedi i README dei singoli repo).

e) Configurare l'account SMTP per l'OTP (vedi punto sotto), quindi avviare il servizio:

sc start KCSScheduleService

Consegna OTP del login a due fattori. Il job Notificatore invia il codice OTP via email, leggendo l'account SMTP dalla tabella config_mail (database PostgreSQL KCS-Portal), riga con cfm_type = 'LOGIN_TOKEN' e cfm_active = true (cfm_server, cfm_port, cfm_ssl, cfm_user, cfm_password, cfm_text con il segnaposto [@Token]). L'account SMTP va fornito dall'installazione: la distribuzione non include alcuna casella. La password in cfm_password è cifrata AES-ECB/PKCS7 (base64) con la chiave definita nel job; configurarla dalla UI di amministrazione (sezione Email) oppure inserendo direttamente la riga cifrata.

Verifica. Al login, dopo il primo fattore, l'OTP deve arrivare via email; in KCS_ScheduleLogs compare --01-- Library Started e Invio SMS Token N di N senza errori. Un 535 authentication failed indica credenziali/relay SMTP non validi lato mail server, non un problema dello scheduler.

Funzione non inclusa: la scadenza automatica di prenotazioni/preventivi e i promemoria programmatici di BizAppointments facevano parte di un job del modulo enterprise; vanno forniti dall'installazione (vedi ARCHITECTURE.md).

Login a due fattori senza scheduler: il codice OTP viene recapitato dal job Notificatore. Finché lo scheduler non è attivo, l'OTP si legge dal database KCS-Portal: SELECT * FROM contact_login_bidtoken_get('<email utente>');