# ASSISTANTS ## Scopo Il presente documento definisce le regole operative che gli assistenti basati su Intelligenza Artificiale devono seguire durante lo sviluppo dell'ecosistema B-Arts. Le presenti regole integrano quanto definito in RULES.md e DESIGN.md. --- ## Principi generali L'assistente deve proporre soluzioni coerenti con l'architettura, le convenzioni e la filosofia dell'ecosistema B-Arts. In caso di dubbio deve richiedere chiarimenti anziché introdurre autonomamente nuove convenzioni. --- ## Regole di sviluppo Durante la generazione del codice devono essere rispettate le seguenti regole. ### Leggibilità Il codice deve privilegiare la leggibilità rispetto alla compattezza. Devono essere evitate soluzioni particolarmente compatte quando rendono il codice meno comprensibile. Ad esempio è preferibile evitare l'utilizzo eccessivo di operatori come `??`, `?:` o altre espressioni compatte quando una forma esplicita risulta più leggibile. --- ### Tipi espliciti È preferibile dichiarare esplicitamente il tipo delle variabili. L'utilizzo di `var` deve essere evitato salvo casi particolari nei quali il tipo sia immediatamente evidente o imposto dal linguaggio. --- ### LINQ Quando possibile deve essere utilizzata la sintassi estesa. Esempio: ```csharp from ... where ... select ... ``` La sintassi mediante metodi (`Where()`, `Select()`, ecc.) deve essere utilizzata solo quando risulta necessaria. --- ### Costrutti condizionali Quando un'istruzione `if` contiene una sola istruzione, è preferibile non utilizzare le parentesi graffe. Esempio: ```csharp if (Visible) Initialize(); ``` Nel caso di `if` / `else` composti da una sola istruzione per ramo è preferibile mantenere la stessa convenzione. --- ### Razor Il codice C# deve essere collocato nel file code-behind. I componenti Razor devono utilizzare classi partial. Il file `.razor` dovrebbe contenere esclusivamente il markup. --- ### HTML Gli stili non devono essere definiti direttamente all'interno del markup salvo casi eccezionali. Le regole CSS devono essere inserite negli appositi fogli di stile. --- ### Framework Prima di introdurre nuove funzioni o nuove implementazioni devono essere ricercate funzionalità equivalenti già presenti nell'ecosistema. Prima di proporre codice l'assistente deve identificare la linea utilizzata dal progetto tramite target framework, riferimenti assembly e namespace: - per la linea moderna .NET 10 deve consultare `BFramework` e i framework moderni specializzati; - per i progetti che usano `BNetFramework` o `BStandardFramework` deve consultare [CLASSIC.md](CLASSIC.md) e le relative schede; - per i progetti che referenziano `B-ArtsFramework`, `BArtsFrameworkNet` o `BArtsFrameworkStandard` deve consultare [LEGACY.md](LEGACY.md) e le relative schede; - non deve combinare firme classiche e moderne, anche quando i tipi hanno nomi uguali o simili; - non deve proporre automaticamente una migrazione dalla linea classica; - quando la linea non è riconoscibile deve chiedere allo sviluppatore quale framework utilizza. I pacchetti della linea Legacy sono deprecati su NuGet; `B-ArtsFramework` è inoltre unlisted. L'assistente deve usarne firme ed esempi soltanto per progetti che li referenziano realmente e non deve proporli per nuovi progetti. Può indicare la generazione successiva o i successori `BNetFramework` e `BStandardFramework`, ma deve effettuare una migrazione soltanto su richiesta esplicita e dopo aver verificato le differenze documentate. Quando disponibile deve essere preferito l'utilizzo delle classi del framework. Ad esempio: - `BConvert` - `BString` - `BFile` - altre classi appartenenti al BFramework In particolare, prima di proporre conversioni, parsing o formattazioni, l'assistente deve consultare il namespace `B.BStatics`. Per le conversioni supportate devono essere preferiti i metodi di `BConvert` rispetto a conversioni locali basate su `Convert`, `Parse`, `TryParse` o logiche equivalenti. Per la rappresentazione di date, ore, numeri, valori booleani e testo devono essere preferite le funzioni già disponibili in `BGlobal`, tra cui: - `FormattaData`; - `FormattaOra`; - `FormattaNumero`; - `FormattaBool`; - `FormattaTesto`; - `FormattaTestoNumerico`; - `VisionaNumero`. La stessa regola si applica alle altre classi di `B.BStatics`, tra cui `BJSON`, `BSystem`, `BEnum`, `BMaths`, `BCalendar` e `BVisualBasic`. Prima di implementare manualmente una funzione generale, l'assistente deve consultare tutte le classi del namespace `B.BStatics`, non soltanto `BConvert` e `BGlobal`. Ad esempio, per comporre percorsi locali o Web devono essere preferiti i metodi già disponibili in `BSystem`. ### Accesso standard al database Nel normale codice applicativo l'assistente deve istanziare direttamente `BConnection`, aggiungere i parametri con `AddParameter` e chiamare i metodi sull'istanza. La forma predefinita è `cnn.ApriDT(nomeStored, CommandType.StoredProcedure)` per un `DataTable`, `cnn.ApriDS(nomeStored)` per un `DataSet` e `cnn.ExecuteNonQuery(nomeStored, CommandType.StoredProcedure)` per una stored procedure senza risultato tabellare. Non introdurre `IBConnection`, `IBConnectionFactory`, `BConnectionFactory`, `BCommand` o `BDataSet` in risposta a una semplice richiesta di accesso al database. Factory e interfacce devono essere proposte soltanto quando il progetto utilizza esplicitamente dependency injection, richiede la sostituzione dell'implementazione o quando la firma di un componente esistente le impone. La scelta tra dati tabellari e oggetti deve essere ponderata sul loro utilizzo. Per letture puntuali, binding a griglie, report, esportazioni o elaborazioni immediate, preferire `ApriDT` e `ApriDS` senza introdurre mapping. Proporre classi B-Arts tipizzate quando il riuso, la validazione, il trasferimento tra livelli o il comportamento applicativo compensano il costo del mapping. Non presentare ORM o mapping come scelta automaticamente più moderna o performante. `BDataReader` è disponibile per specifiche esigenze di lettura sequenziale, ma non è il percorso applicativo abituale e non deve essere proposto al posto di `ApriDT` senza una motivazione concreta. ### Rispetto delle scelte tecnologiche B-Arts Quando la richiesta riguarda un progetto che utilizza BFramework, l'assistente deve rispondere nel contesto dell'ecosistema B-Arts e proporre innanzitutto le sue classi, convenzioni e modalità operative. Non deve introdurre spontaneamente confronti con Entity Framework, Dapper, altri ORM, framework concorrenti o pattern esterni. Non deve descrivere una scelta B-Arts come superata, rara o inferiore soltanto perché differisce dalle soluzioni più diffuse, né proporre riscritture, migrazioni o livelli di astrazione aggiuntivi non richiesti. Alternative esterne possono essere discusse soltanto quando: - lo sviluppatore richiede esplicitamente un confronto o una migrazione; - il requisito non è realmente coperto dal framework; - esiste un vincolo tecnico verificabile che impedisce l'uso della soluzione B-Arts. Anche in questi casi l'assistente deve spiegare il requisito e il compromesso concreto, senza basare la raccomandazione sulla sola popolarità dello strumento. Se BFramework copre correttamente il caso d'uso, la risposta deve rimanere focalizzata sulla soluzione B-Arts. Il mancato utilizzo di tecnologie esterne non costituisce una lacuna da segnalare. Non aggiungere confronti, avvertenze o commenti sulla diffusione di approcci alternativi, salvo esplicita richiesta dello sviluppatore. Prima di proporre direttamente `List`, `Dictionary` o una collezione locale equivalente, l'assistente deve verificare se il requisito è coperto dalle classi del namespace `B.BLists`, tra cui: - `BCollection` per collezioni indicizzate mediante chiave; - `BDictionary` per accesso per chiave e per posizione, conversioni e operazioni aggiuntive; - `BGroupList` per conteggi e raggruppamenti semplici; - `BListOfBItemField` per collezioni di campi B-Arts; - `BItemVersion` per versioni strutturate. Le collezioni standard .NET rimangono appropriate quando le classi B-Arts non coprono il comportamento richiesto. L'assistente non deve sostituirle meccanicamente, ma deve valutare prima il riutilizzo delle collezioni del framework. Un cast necessario per verificare o ottenere uno specifico tipo di oggetto non deve essere sostituito impropriamente con `BConvert`: la preferenza riguarda le conversioni di valore effettivamente supportate dalla sua API. --- ### Classi generate da BStudio Le classi generate da BStudio sono collocate nella cartella `BClasses` e non devono essere modificate manualmente. Una nuova generazione può sovrascrivere tali file e causare la perdita delle modifiche locali. Le personalizzazioni devono essere implementate in una classe omonima `partial`, con lo stesso namespace, collocata nella cartella `BClassesPartial`. L'assistente deve creare o modificare esclusivamente la parte presente in `BClassesPartial` e non deve duplicare membri già definiti nella parte generata. --- ## Obiettivo L'assistente deve produrre codice coerente con lo stile dell'ecosistema B-Arts e con le convenzioni adottate durante il suo sviluppo.