====== WvdS FPC RAD Studio - Documentazione per sviluppatori ======

//Documentazione interna per gli sviluppatori della WvdS FPC RAD Suite//

<note warning>Questa documentazione è destinata agli **sviluppatori interni** della suite, non agli utenti finali. Per la documentazione utente vedere [[..:p:start|Public Documentation]].</note>

===== Panoramica =====

WvdS FPC RAD Studio è una suite di estensioni per Visual Studio Code, scritta interamente in Pascal e transpilata in JavaScript tramite pas2js.

==== Principi fondamentali ====

  * **Nessun TypeScript** - Tutte le estensioni sono basate su Pascal
  * **SSOT** - Single Source of Truth in ''sources/''
  * **Separation of Concerns** - Architettura a strati rigorosa
  * **Conforme a KRITIS/NIS2** - Sicurezza come requisito fondamentale

===== Indice della documentazione =====

==== Architettura ====

^ Documento ^ Contenuto ^
| [[.:architektur|Panoramica architettura]] | Struttura monorepo, strati, dipendenze |
| [[.:umgebung|Ambiente di sviluppo]] | Struttura progetto, percorsi, regole SSOT |
| [[.:pxaml-pipeline|Pipeline PXAML]] | Da markup a IR a renderer |
| [[.:extension-architektur|Architettura estensioni]] | Entry point, attivazione, servizi |
| [[.:targets|Target di build]] | GUI, TUI, Web - Differenze e punti in comune |

==== Sviluppo ====

^ Documento ^ Contenuto ^
| [[.:extension-entwicklung|Sviluppo estensioni]] | Creare nuove estensioni, best practice |
| [[.:control-entwicklung|Sviluppo controlli]] | Workflow in 7 passaggi per i controlli UI |
| [[.:code-konventionen|Convenzioni del codice]] | Naming, struttura, documentazione |
| [[.:sicherheit|Linee guida sulla sicurezza]] | OWASP, KRITIS, audit |
| [[.:i18n|Internazionalizzazione]] | Resourcestrings, traduzioni |
| [[.:debugging|Debugging]] | Debug logging, analisi errori |

==== Build e release ====

^ Documento ^ Contenuto ^
| [[.:build-pipeline|Pipeline di build]] | Compilazione pas2js, CLI toolchain, artefatti |
| [[.:pack-struktur|Struttura pack]] | Pack di terze parti, manifesti, distribuzione |
| [[.:testing|Testing]] | Unit test, test di integrazione |
| [[.:release|Processo di release]] | Versionamento, creazione VSIX, pubblicazione |

==== Sviluppo TUI ====

^ Documento ^ Contenuto ^
| [[.:tui-entwicklung|Panoramica TUI]] | Architettura, requisiti di qualità, quando usare TUI |
| [[.:tui-engine|TUI Engine]] | CellBuffer, DiffEngine, rendering flicker-free |
| [[.:tui-controls|Controlli TUI]] | Pattern Model+Renderer, stati, input, focus |
| [[.:tui-layout|Layout TUI]] | Anchoring, responsive, breakpoint, container |

==== Assicurazione qualità ====

^ Documento ^ Contenuto ^
| [[.:qualitàetssicherung|Panoramica QA]] | Workflow, matrice profili, processi di audit |
| [[.:audit-core|Checklist core]] | Production-ready, gestione errori, logging |
| [[.:audit-sicherheit|Checklist sicurezza]] | KRITIS/NIS2, OWASP, crittografia |
| [[.:audit-codequalitàet|Checklist qualità codice]] | Naming, funzioni, DRY, SSOT |
| [[.:kommentierung|Standard di commento]] | PasDoc, doc-comments, review |
| [[.:audit-vscode|Checklist VSCode]] | Specifico per estensioni, pas2js |

==== Riferimento API ====

^ Documento ^ Contenuto ^
| [[.:core-api|Core API]] | Servizi condivisi, accesso toolchain |
| [[.:meta-api|Meta API]] | Registry componenti, provider IntelliSense |
| [[.:vscode-wrapper|VSCode Wrapper]] | Unit WvdS.VSCode.* |

==== Libreria controlli ====

^ Documento ^ Contenuto ^
| [[.:control-bibliothek|Catalogo controlli]] | Tutti i 108 controlli con mapping DevExpress |
| [[.:control-architektur|Architettura controlli]] | Pattern Properties/ViewInfo/Control |
| [[.:control-vsix-erstellen|Creare VSIX]] | Creare manualmente estensione controllo |
| [[.:control-generierung|Generazione controlli]] | Generazione batch con PowerShell |

==== Riferimento API controlli ====

^ Documento ^ Contenuto ^
| [[.:api-controls-basic|Controlli base]] | Label, Button, CheckBox, ecc. (12) |
| [[.:api-controls-editors|Controlli editor]] | TextEdit, SpinEdit, DateEdit, ecc. (18) |
| [[.:api-controls-navigation|Navigazione]] | TabControl, Wizard, NavBar, ecc. (7) |
| [[.:api-controls-data|Controlli dati]] | DataGrid, TreeList, PivotGrid, ecc. (10) |
| [[.:api-controls-charts|Grafici]] | LineSeries, PieSeries, Sparkline, ecc. (16) |
| [[.:api-controls-gauges|Indicatori]] | CircularGauge, LED, Thermometer, ecc. (10) |
| [[.:api-controls-layout|Layout]] | LayoutControl, DockingManager, ecc. (10) |
| [[.:api-controls-bars|Barre/Ribbon]] | RibbonControl, StatusBar, ecc. (10) |
| [[.:api-controls-specialized|Specializzati]] | Scheduler, Spreadsheet, Map, ecc. (15) |

===== Guida rapida per nuovi sviluppatori =====

==== 1. Configurare l'ambiente di sviluppo ====

<code bash>
# Clonare il repository
git clone https://github.com/ArmandoFilho/WvdS.FPC.git
cd WvdS.FPC

# Aprire VS Code
code .
</code>

==== 2. Installare gli strumenti ====

Richiesti:
  * Free Pascal Compiler 3.2.2+
  * pas2js 2.2.0+
  * Node.js 18+ (per vsce)
  * VS Code 1.85.0+

Opzionali:
  * lazbuild (per progetti LCL)
  * Inno Setup (per installer Windows)

==== 3. Prima compilazione ====

<code bash>
cd sources/extensions/wvds.vscode.core
pas2js -Jc -Jirtl.js -Tbrowser -Fu../../common -FE./dist extension_main.pas
</code>

==== 4. Testare l'estensione ====

  - ''F5'' in VS Code per avviare l'Extension Development Host
  - Si apre una nuova finestra VS Code con le estensioni caricate
  - Palette comandi: ''WVDS: Hello'' per testare

===== Struttura del repository =====

<code>
WvdS.FPC/
├── sources/                    # SSOT - Versionato
│   ├── common/                 # Unit condivise
│   │   ├── core/               # Unit base
│   │   ├── ui/                 # UI Framework
│   │   └── web/                # Host Bridges (Node, VSCode)
│   ├── extensions/             # Estensioni VSIX
│   │   ├── wvds.vscode.core/
│   │   ├── wvds.vscode.build/
│   │   ├── wvds.vscode.projects/
│   │   ├── wvds.vscode.packaging/
│   │   ├── wvds.vscode.ui.designer/
│   │   ├── wvds.vscode.ui.meta/
│   │   └── wvds.vscode.ui.preview/
│   ├── applications/           # Applicazioni standalone
│   ├── tools/                  # Strumenti CLI (wvds-build, ecc.)
│   └── packages/               # Pacchetti IDE
│
├── binaries/                   # Output build (non versionato)
│   ├── out/                    # Artefatti compilati
│   ├── cache/                  # Cache compilatore
│   ├── dist/                   # Pacchetti release
│   └── logs/                   # Log di build
│
└── .claude/                    # Configurazione Claude
    └── CLAUDE.md               # Regole repository
</code>

===== Regole di policy =====

Queste regole sono **non negoziabili** e vengono verificate da wvds-lint:

==== P0: Single Source of Truth ====

<code>
CONSENTITO:   sources/common/WvdS.System.pas
VIETATO:  sources/extensions/wvds.vscode.core/WvdS.System.pas (duplicato!)
</code>

==== P1: Niente TypeScript ====

<code>
CONSENTITO:   *.pas -> pas2js -> *.js
VIETATO:  *.ts, *.js scritto a mano
</code>

==== P2: Wrapper solo in common ====

<code>
CONSENTITO:   sources/common/web/vscode/VSCode.API.pas
VIETATO:  sources/extensions/wvds.vscode.build/VSCode.API.pas
</code>

==== P3: Output autocontenuto ====

<code>
dist/extension_main.js deve contenere tutte le unit necessarie
</code>

===== Contatti =====

  * **Repository:** [[https://github.com/ArmandoFilho/WvdS.FPC|github.com/ArmandoFilho/WvdS.FPC]]
  * **Issues:** [[https://github.com/ArmandoFilho/WvdS.FPC/issues|Bug report e richieste di funzionalità]]
  * **Code Review:** Pull request tramite GitHub

===== Prossimi passi =====

  * [[.:architektur|Comprendere l'architettura in dettaglio]]
  * [[.:extension-entwicklung|Sviluppare la prima estensione]]
  * [[.:code-konventionen|Interiorizzare le convenzioni del codice]]