Onboarding sviluppatore

Percorso completo per un nuovo sviluppatore Infocad: da zero fino a costruire, avviare, debuggare e modificare in sicurezza il codice. Il taglio è pratico e tarato sul verticale RequestCenter / Service Desk (batch DEV-1), ma l'impostazione vale per tutti i domini. Classificazione: la struttura dei repo e la toolchain sono VERIFIED; la topologia di hosting IIS/Windows Service in ambiente reale è UNKNOWN (vedi OQ-2).

Questa pagina presuppone che tu non abbia mai lavorato su Infocad. Per la panoramica architetturale vedi Architettura; per i comandi di build sintetici vedi la panoramica delle Guide.

Cos'è Infocad

Infocad è la piattaforma enterprise di Descor per facility/property management, BIM, energia, contabilità e document management. Il namespace radice è Descor.<Dominio> (Descor.Booking, Descor.BIM, Descor.Energy, Descor.Property, Descor.Accounting, Descor.RequestCenter, Descor.ServiceDesk, Descor.Common, …). Il backend dati è Oracle; non esiste ORM (niente EF, niente Dapper): la DAL invoca stored procedure dentro package Oracle. VERIFIED

Lo stack è prevalentemente .NET Framework 4.8 (Windows: WCF, ASP.NET Web Forms, Windows Services, ODP.NET unmanaged). È in corso una migrazione a .NET 8 affiancata (progetti *XNET SDK-style che re-linkano lo stesso sorgente, senza duplicarlo). VERIFIED

I due repository e come si relazionano

La cartella di lavoro Documentation/ non è un repo Git: contiene due repo indipendenti affiancati. VERIFIED

Repository	Cosa contiene	Framework
`InfocadServer/`	tier servizio/business: Windows Services + WCF sottile self-hosted (159 progetti, `InfocadServer.sln`)	139 v4.8 · 20 net8 (XNET)
`InfocadWeb/`	front-end ASP.NET Web Forms + integrazione/scheduler; tutti gli endpoint SOAP/WCF (46 `.asmx` + 35 `.svc`) vivono qui	144 v4.8 · 3 net8 (XNET) · 1 netstandard2.0

Relazione principale tra i due repo: l'integrazione Web↔Server è mediata quasi interamente dal database Oracle condiviso, non da chiamate dirette. Esiste un solo riferimento a compile-time che attraversa i repo: un progetto sotto InfocadWeb/InfocadIntegration/.../ServiceJob.CUT referenzia InfocadServer/ArchiveManager/ArchiveManager.csproj per percorso relativo. Per questo i due repo devono essere clonati come sibling sotto la stessa cartella padre, altrimenti quel riferimento non risolve. VERIFIED

Radice dei sorgenti web (usata spesso in questa doc): InfocadWeb/WebMachine/. La UI del verticale RequestCenter sta sotto InfocadWeb/WebMachine/CASSANDRA/RequestCenterWeb/. SUPPORTED

Strumenti richiesti

Strumento	Uso	Note
Windows + Visual Studio 2022 (o Build Tools)	build/run completo v4.8	obbligatorio per WCF/Web Forms/Windows Services `VERIFIED`
Oracle Client (ODP.NET unmanaged `Oracle.DataAccess`)	connettività Oracle nel codice legacy	richiesto a runtime dai progetti v4.8 `VERIFIED`
.NET 8 SDK (`dotnet`)	build dei progetti `*XNET` (net8/netstandard2.0)	non richiede Oracle Client per compilare `VERIFIED`
NuGet	restore `packages.config` (progetti legacy)	`SUPPORTED`
Git	due repo, branch `develop`, remoti Azure DevOps	`VERIFIED`
Python 3 + `python-oracledb` (thin mode)	verifiche DB read-only senza Oracle Client	usato dalla toolchain di doc `VERIFIED`

Note

Su macOS/Linux (come questo host) puoi compilare solo i progetti *XNET che chiudono le dipendenze in net8. Attenzione: RequestCenter.DAL.OracleODPXNET e RequestCenterXNET non compilano headless perché la chiusura delle dipendenze tira dentro assembly 4.8 solo-Windows (Descor.Stock.*, *.Controllers). DataManagerXNET compila 0/0 ma docfx metadata fallisce (BC30002 System.Data). SUPPORTED

Preparare il workspace

# clona i due repo come SIBLING sotto la stessa cartella padre
mkdir Documentation && cd Documentation
git clone <azure-devops>/InfocadServer   # branch develop
git clone <azure-devops>/InfocadWeb       # branch develop
# risultato atteso:
#   Documentation/InfocadServer/
#   Documentation/InfocadWeb/

I remoti sono su Azure DevOps (dev.azure.com/descor/InfocadProjectManagement), branch develop. VERIFIED

Restore delle dipendenze

# legacy .NET Framework 4.8 (packages.config) — Windows
nuget restore InfocadServer/InfocadServer.sln
nuget restore InfocadWeb/WebMachine/WebMachine.sln

# progetti *XNET (SDK-style, PackageReference) — cross-platform
dotnet restore InfocadServer/CommonXNET/CommonXNET.csproj

Warning

I comandi nuget/msbuild sono NON verificati su questo host (macOS, nessun Oracle Client): vanno eseguiti su Windows. dotnet restore/build sui *XNET compilabili è l'unico verificabile qui.

Configurazione ambiente locale

Le connection string non si editano a mano per singola app. In deploy: InfocadServer/ConnectionsService legge un connections.xml deposto accanto al servizio e riscrive la sezione <connectionStrings> (e l'applicationName dei provider Oracle Membership/Role) nel *.exe.config di destinazione, poi riavvia il servizio invocando restartserver.bat. VERIFIED (InfocadServer/ConnectionsService/Program.cs:37,97,116,322)

Connessioni note nei config: MainConnection (core Infocad), RequestCenterConnection, DEMConnection, OracleProvidersDB (membership/ruoli ASP.NET). SUPPORTED

Per il solo sviluppo/doc, le credenziali del DB di dev stanno nel file untracked .env alla radice Documentation/ (perms 600): host 192.168.0.100:1521, Service Name dev, schemi ASPNET_TEST38, INFOCAD_TEST38, REQUESTCENTER_TEST38, DEM_TEST38. Usa .env solo per verifiche DB read-only (python-oracledb thin mode, nessun Oracle Client), mai per riscrivere config di runtime. VERIFIED

Caution

Le password Passbolt contengono parentesi quadre letterali (NAME [value]): fanno parte del valore, non vanno rimosse.

Build di ciascun progetto

# solution intere (Windows)
msbuild InfocadServer/InfocadServer.sln -p:Configuration=Debug -m
msbuild InfocadWeb/WebMachine/WebMachine.sln -p:Configuration=Debug -m   # web principale
# solution focalizzate web: ECM.sln, IEM.sln, Customizations.sln (plug-in per cliente)

# singolo progetto (l'analogo di "un test")
msbuild InfocadServer/BookingDAL/BookingDAL.csproj -p:Configuration=Debug

# progetti *XNET (cross-platform)
dotnet build InfocadServer/CommonXNET/CommonXNET.csproj

Comandi msbuild NON verificati su questo host. VERIFIED (esistenza solution/progetti; esecuzione richiede Windows)

Avvio delle applicazioni

Windows Services (lavoro in background): classi ServiceBase — InfocadServer, IEMServer, ECMServer, più ConnectionsService/UpdateService/IEMService/WindowService. VERIFIED
WCF in InfocadServer è sottile: solo EnergyService (3 [ServiceContract]) è self-hosted via ServiceHost.Open() in Business/Start.vb (non IIS). Tutta la superficie SOAP/WCF ampia (46 .asmx + 35 .svc) vive in InfocadWeb. VERIFIED
Web Forms: un'app web per dominio (RequestCenterWeb, AccountingWeb, BIMCenterWeb, …), servite in IIS. Topologia IIS in ambiente reale: UNKNOWN (numero di siti/app-pool, binding, host) — vedi OQ-2.

Autenticazione locale

Autenticazione via ASP.NET Oracle Membership/Role providers (OracleMembershipProvider, OracleRoleProvider) sullo schema ASPNET (OracleProvidersDB). SSO esterno per-cliente è pluggabile: ExternalAuth.<Customer> che implementa ExternalAuth.Interface (es. ExternalAuth.BPER, CustomAuth.CUT). VERIFIED

Esecuzione dei test

Non esiste una suite di test automatici nei repo (nessun xUnit/NUnit/MSTest) e nessun CI. VERIFIED Se ti chiedono di "far girare i test", dillo esplicitamente invece di inventare un comando. Per verifiche manuali/integrazione esiste l'harness console InfocadServer/InfocadTester. SUPPORTED Non dichiarare copertura non misurata.

Dove trovare i log

UNKNOWN in questa fase: la posizione/formato dei log applicativi in ambiente reale non è stata verificata su questo host. Da chiarire in una guida dedicata di debugging (in preparazione).

Come debuggare FE e BE

Backend (Windows Service / WCF): build in Debug, poi Attach to Process di Visual Studio al processo del servizio (o al processo host WCF self-hosted). INFERRED
Frontend (Web Forms): debug della web app in IIS/IIS Express con Attach to Process a w3wp.exe. INFERRED (dipende dalla topologia IIS, UNKNOWN).
Guida dettagliata: debugging (in preparazione).

Come navigare da UI a backend (esempio RequestCenter)

Traccia il percorso di una funzionalità partendo dalla UI:

Shell Default.aspx + gate RequestCenterPage.Page_PreInit; menu "Requests". SUPPORTED
User control UserControls/FlowActions/makeTicket.ascx (+ .ascx.vb, base BaseClasses.CreateUserControlBase). Trigger: btnPost_Click (InfocadWeb/WebMachine/CASSANDRA/RequestCenterWeb/UserControls/FlowActions/makeTicket.ascx.vb:82, Handles actSubmt.ActivityRun). SUPPORTED
BL: Descor.RequestCenter.Ticket.Request (RequestCenter/Classes/Request.vb), es. Create, SetDescription/WriteDescription, SetType, SetContract, Close.
Transazione: New RequestCenter.Transaction → OpenConnection() → Begin() … Commit()/ Rollback() → CloseConnection().
DAL: RequestDAL.vb (implementa IRequestDAL, Interfaces/TicketInterfaces.vb:39) invoca i package Oracle tramite l'helper cm di GlobalDataManager (cm.ExecuteReader/ExecuteNonQuery/Fill("PACKAGE.PROC", OracleParameter…)), es. addRequest → GESTREQUEST_T2.ADDREQUEST, setDescription → GESTREQUEST.ADDDESCRIPTIONTOREQUEST.
DB: package GESTREQUEST / GESTREQUEST_T2 sullo schema REQUESTCENTER_TEST38.

Equivalenti WCF dello stesso verticale: RequestsReaderWCF.svc, RequestsCacheService.svc, ExtraFlowActionsProxy.svc. Il flusso end-to-end è documentato in FLOW-REQ-001; le regole in BR-REQ; il dominio in Service Desk.

Come localizzare gli oggetti DB

Reference per schema: REQUESTCENTER_TEST38 (index.md, tables.md, procedures.md).
Chi legge/scrive cosa: matrice CRUD (procedura ⇄ tabelle).
A runtime, un metodo DAL nomina il package+proc nella stringa passata a cm.* (es. "GESTREQUEST.ADDWORKFLOWINTERFACE"): cerca quella stringa nel DAL per risalire dalla proc al chiamante, e viceversa. SUPPORTED
Verifica read-only dello schema: python-oracledb thin mode con .env (dsn="192.168.0.100:1521/dev"), sulle viste USER_*. VERIFIED

Come fare una modifica documentation-only sicura

Scrivi solo sotto docs/ (prosa italiana; identificatori/DB/route/config non tradotti).
Classifica ogni affermazione sostanziale (VERIFIED/SUPPORTED/INFERRED/UNKNOWN/CONFLICTING).
Chiudi ogni pagina con ## Evidenze (file:line, oggetti DB, metadati).
DB solo read-only; mai stampare segreti/credenziali.

Ricostruisci il portale e verifica 0 warning/link rotti:

docs-site/scripts/build.sh      # genera reference + docfx build -> _site
docs-site/scripts/validate.sh   # warning docfx + check link locali
docs-site/scripts/serve.sh      # anteprima locale http://localhost:8080

build.sh/serve.sh/validate.sh sono verificati su questo host. VERIFIED

Aggiorna gli state file in docs/_state/ (work-queue.md, claims.ndjson, conflicts.md, open-questions.md, coverage.csv).

Non toccare mai file sorgente (.vb/.cs/.vbproj/.aspx/.ascx) né i generati My Project/*.Designer.vb.

Come fare una modifica normale (codice)

Individua il dominio e rispetta la slice verticale a cinque strati: <Dominio>{SharedObjects,Interface,DAL,BL,Controllers} — non collassare gli strati.
Per l'accesso dati usa gli helper DAL + stored procedure esistenti; niente SQL inline, niente nuovo ORM.
Per un nuovo cliente aggiungi un progetto parallelo <Layer><Customer> (EntityLayer<Customer>, ServiceJob.<Customer>, TicketLoader<Customer>, backend ExternalDocSave.{Alfresco,Opentext,Docs}) raccolto in Customizations.sln — non fare fork del codice condiviso né branch/flag per cliente. VERIFIED
Cambiamenti chirurgici: tocca solo ciò che serve, rispetta lo stile esistente, non "migliorare" codice adiacente.
Build del singolo progetto toccato + della solution che lo contiene (vedi sopra).
Guide di dettaglio: database-development e common-development-tasks (in preparazione).

Come verificare di non rompere flussi correlati

Senza test automatici, la rete di sicurezza è la tracciabilità della documentazione:

Parti dal FLOW-REQ-001 e dalle regole BR-REQ del verticale toccato: verifica che il tuo cambiamento non violi un passo/una regola.
Consulta la matrice CRUD: se cambi una stored procedure o una tabella, individua tutti i chiamanti (BL/DAL/WCF) prima di modificare.
Non dichiarare "inutilizzato" un simbolo solo per assenza di chiamanti statici: possono esserci reflection, WCF, routing, config, serializzazione.
Ricostruisci il portale (build.sh) e riesegui l'harness manuale InfocadTester sulle aree toccate.

Primo giorno

[ ] Clona InfocadServer e InfocadWeb come sibling sotto Documentation/. VERIFIED
[ ] Installa Windows + Visual Studio 2022 + Oracle Client; installa .NET 8 SDK. VERIFIED
[ ] nuget restore delle solution principali (Windows); dotnet restore di un progetto *XNET.
[ ] Leggi Architettura e le landing repo InfocadServer / InfocadWeb.
[ ] Costruisci il portale doc: docs-site/scripts/build.sh (atteso 0/0) e apri docs-site/scripts/serve.sh. VERIFIED
[ ] Verifica la connettività DB read-only con python-oracledb (.env, service dev). VERIFIED
[ ] Localizza il file .env (perms 600) e conferma di non committarlo mai.

Prima settimana

[ ] Compila WebMachine.sln e InfocadServer.sln in Debug su Windows.
[ ] Percorri end-to-end un ticket seguendo FLOW-REQ-001: da makeTicket.ascx → Request (BL) → RequestDAL → package GESTREQUEST(_T2).
[ ] Naviga la Reference del codice del verticale RequestCenter.
[ ] Esplora lo schema REQUESTCENTER_TEST38 e la matrice CRUD.
[ ] Studia il pattern di customizzazione per-cliente (Customizations.sln) e l'auth Membership/Role Oracle.
[ ] Rivedi la superficie API SOAP/WCF (tutta in InfocadWeb).
[ ] Fai una prima modifica documentation-only end-to-end (scrivi in docs/, build.sh, validate.sh, aggiorna _state/).

Vedi anche

Guide per sviluppatori (panoramica)
database-development · common-development-tasks · debugging — in preparazione
Repository · Reference del codice
Qualità e test

Evidenze

Struttura workspace, framework, ORM assente, slice a 5 strati, hosting, auth, customizzazioni, assenza test/CI: Documentation/CLAUDE.md (istruzioni di progetto). VERIFIED
Due repo, branch develop, remoti Azure DevOps, unico ref cross-repo (ServiceJob.CUT → InfocadServer/ArchiveManager/ArchiveManager.csproj): docs/02-repositories/index.md. VERIFIED
ConnectionsService riscrive connections.xml → <connectionStrings> e invoca restartserver.bat: InfocadServer/ConnectionsService/Program.cs:37,97,116,322. SUPPORTED
Trigger UI RequestCenter btnPost_Click … Handles actSubmt.ActivityRun + Inherits BaseClasses.CreateUserControlBase: InfocadWeb/WebMachine/CASSANDRA/RequestCenterWeb/UserControls/FlowActions/makeTicket.ascx.vb:5,82. SUPPORTED
Helper cm/motore transazioni: InfocadWeb/WebMachine/DataManager/GlobalDataManager.vb (BeginTransaction:155/163; ExecuteReader:297–317). SUPPORTED
Interfaccia DAL IRequestDAL: InfocadWeb/WebMachine/RequestCenter/Interfaces/TicketInterfaces.vb:39. SUPPORTED
Package Oracle GESTREQUEST / GESTREQUEST_T2, schema REQUESTCENTER_TEST38: docs/05-databases/REQUESTCENTER_TEST38/. VERIFIED
Toolchain portale (build.sh/serve.sh/validate.sh) e verifica DB read-only python-oracledb: docs/03-developer-guides/index.md; DB dev host 192.168.0.100:1521/dev, schemi *_TEST38: Documentation/CLAUDE.md (§Database & local dev). VERIFIED
Topologia IIS reale e posizione dei log: UNKNOWN — docs/_state/open-questions.md (OQ-2).

Table of Contents