migrazione verso gitea

docs/flows/async_msssql_query_flow.md

@@ -0,0 +1,41 @@
+# `async_msssql_query.py`
+
+## Scopo
+
+Questo modulo centralizza la costruzione del DSN SQL Server e l'accesso
+asincrono al database tramite `AsyncMSSQLClient`.
+
+## Flusso di utilizzo
+
+```{mermaid}
+flowchart TD
+    A["main.py o modulo chiamante"] --> B["make_mssql_dsn(...)"]
+    B --> C["Crea stringa mssql+aioodbc"]
+    C --> D["AsyncMSSQLClient(dsn)"]
+    D --> E["query_json(...) o exec(...)"]
+    E --> F["_ensure_engine()"]
+    F --> G{"Engine gia creato?"}
+    G -- No --> H["create_async_engine(..., NullPool, loop corrente)"]
+    G -- Si --> I["Riusa engine esistente"]
+    H --> J["execute(text(sql), params)"]
+    I --> J
+    J --> K["Normalizza rows/columns"]
+    K --> L["Ritorna payload JSON-friendly"]
+```
+
+## Schema di chiamata
+
+```{mermaid}
+flowchart LR
+    DSN["make_mssql_dsn"] --> Client["AsyncMSSQLClient.__init__"]
+    Client --> Ensure["_ensure_engine"]
+    Ensure --> Query["query_json"]
+    Ensure --> Exec["exec"]
+    Client --> Dispose["dispose"]
+```
+
+## Note
+
+- `NullPool` evita problemi di riuso connessioni tra loop diversi.
+- L'engine viene creato solo al primo utilizzo reale.
+- `query_json()` restituisce un formato gia pronto per le callback GUI.