📚 DOCUMENTAZIONE: Architettura UI Completa - Design System, Navigazione e Roadmap

[artcava]

📚 DOCUMENTAZIONE: Architettura UI Completa

Questa issue contiene la documentazione completa dell'architettura UI proposta per PTRP.
Include: struttura componenti, design system, schema colori, navigazione, flussi utente, e considerazioni tecniche.

---

🏛️ Struttura Architetturale

Pattern MVVM Completo

PTRP.App/
├── Views/
│   ├── MainWindow.xaml              # Shell principale con NavigationFrame
│   ├── Dashboard/
│   │   └── DashboardView.xaml       # Dashboard con KPI cards
│   ├── Patients/
│   │   ├── PatientListView.xaml     # Master-Detail layout
│   │   └── PatientFormView.xaml     # Form add/edit paziente
│   ├── Projects/
│   │   ├── ProjectListView.xaml
│   │   └── ProjectFormView.xaml
│   ├── Educators/
│   │   ├── EducatorListView.xaml
│   │   └── EducatorFormView.xaml
│   ├── Calendar/
│   │   ├── CalendarView.xaml        # Calendario appuntamenti
│   │   └── AppointmentFormView.xaml
│   ├── Visits/
│   │   └── VisitFormView.xaml       # Registrazione visita
│   ├── Sync/
│   │   ├── SyncView.xaml            # Export/Import pacchetti
│   │   └── ConflictResolutionView.xaml
│   ├── Setup/
│   │   └── FirstRunView.xaml        # Schermata primo avvio
│   └── Dialogs/
│       ├── ConfirmationDialog.xaml
│       └── ErrorDetailsDialog.xaml
│
├── ViewModels/
│   ├── MainViewModel.cs
│   ├── ViewModelBase.cs
│   ├── DashboardViewModel.cs
│   ├── PatientListViewModel.cs
│   └── ...
│
├── Services/
│   ├── INavigationService.cs
│   ├── IConfigurationService.cs
│   ├── IErrorHandlingService.cs
│   └── ...
│
├── Behaviors/
│   └── ValidationBehavior.cs
│
├── Converters/
│   ├── BoolToVisibilityConverter.cs
│   ├── ProjectStateToColorConverter.cs
│   └── ...
│
├── Validation/
│   └── ValidationAttributes.cs
│
└── Styles/
    ├── Colors.xaml              # Design system colors
    ├── Typography.xaml          # Font styles
    ├── Buttons.xaml             # Button styles
    └── Controls.xaml            # Custom control styles

---

🎨 Design System Completo

Palette Colori

Primary Colors

<Color x:Key="PrimaryColor">#28A745</Color>        <!-- Verde Terapeutico -->
<Color x:Key="PrimaryLightColor">#34D058</Color>  <!-- Hover state -->
<Color x:Key="PrimaryDarkColor">#1E7E34</Color>   <!-- Active state -->

<SolidColorBrush x:Key="PrimaryBrush" Color="{StaticResource PrimaryColor}"/>
<SolidColorBrush x:Key="PrimaryLightBrush" Color="{StaticResource PrimaryLightColor}"/>
<SolidColorBrush x:Key="PrimaryDarkBrush" Color="{StaticResource PrimaryDarkColor}"/>

Secondary Colors

<Color x:Key="SecondaryColor">#007BFF</Color>      <!-- Blu Informativo -->
<Color x:Key="SecondaryLightColor">#3395FF</Color>
<Color x:Key="SecondaryDarkColor">#0056B3</Color>

<SolidColorBrush x:Key="SecondaryBrush" Color="{StaticResource SecondaryColor}"/>

Semantic Colors

<!-- Success -->
<Color x:Key="SuccessColor">#28A745</Color>
<SolidColorBrush x:Key="SuccessBrush" Color="{StaticResource SuccessColor}"/>

<!-- Warning -->
<Color x:Key="WarningColor">#FFC107</Color>
<SolidColorBrush x:Key="WarningBrush" Color="{StaticResource WarningColor}"/>

<!-- Error -->
<Color x:Key="ErrorColor">#DC3545</Color>
<SolidColorBrush x:Key="ErrorBrush" Color="{StaticResource ErrorColor}"/>

<!-- Info -->
<Color x:Key="InfoColor">#17A2B8</Color>
<SolidColorBrush x:Key="InfoBrush" Color="{StaticResource InfoColor}"/>

Neutral Colors

<Color x:Key="TextPrimaryColor">#212529</Color>      <!-- Testo principale -->
<Color x:Key="TextSecondaryColor">#6C757D</Color>   <!-- Testo secondario -->
<Color x:Key="TextDisabledColor">#ADB5BD</Color>    <!-- Testo disabilitato -->

<Color x:Key="BackgroundColor">#FFFFFF</Color>      <!-- Sfondo principale -->
<Color x:Key="SurfaceColor">#F8F9FA</Color>         <!-- Sfondo cards -->
<Color x:Key="BorderColor">#DEE2E6</Color>          <!-- Bordi -->

<SolidColorBrush x:Key="TextPrimaryBrush" Color="{StaticResource TextPrimaryColor}"/>
<SolidColorBrush x:Key="TextSecondaryBrush" Color="{StaticResource TextSecondaryColor}"/>
<SolidColorBrush x:Key="TextDisabledBrush" Color="{StaticResource TextDisabledColor}"/>
<SolidColorBrush x:Key="BackgroundBrush" Color="{StaticResource BackgroundColor}"/>
<SolidColorBrush x:Key="SurfaceBrush" Color="{StaticResource SurfaceColor}"/>
<SolidColorBrush x:Key="BorderBrush" Color="{StaticResource BorderColor}"/>

Tipografia

<!-- Headings -->
<Style x:Key="H1Style" TargetType="TextBlock">
    <Setter Property="FontSize" Value="32"/>
    <Setter Property="FontWeight" Value="Bold"/>
    <Setter Property="Foreground" Value="{StaticResource TextPrimaryBrush}"/>
</Style>

<Style x:Key="H2Style" TargetType="TextBlock">
    <Setter Property="FontSize" Value="24"/>
    <Setter Property="FontWeight" Value="SemiBold"/>
    <Setter Property="Foreground" Value="{StaticResource TextPrimaryBrush}"/>
</Style>

<Style x:Key="H3Style" TargetType="TextBlock">
    <Setter Property="FontSize" Value="18"/>
    <Setter Property="FontWeight" Value="SemiBold"/>
    <Setter Property="Foreground" Value="{StaticResource TextPrimaryBrush}"/>
</Style>

<!-- Body Text -->
<Style x:Key="BodyStyle" TargetType="TextBlock">
    <Setter Property="FontSize" Value="14"/>
    <Setter Property="FontWeight" Value="Normal"/>
    <Setter Property="Foreground" Value="{StaticResource TextPrimaryBrush}"/>
</Style>

<Style x:Key="CaptionStyle" TargetType="TextBlock">
    <Setter Property="FontSize" Value="12"/>
    <Setter Property="Foreground" Value="{StaticResource TextSecondaryBrush}"/>
</Style>

Spacing System

<system:Double x:Key="Spacing0">0</system:Double>
<system:Double x:Key="Spacing4">4</system:Double>
<system:Double x:Key="Spacing8">8</system:Double>
<system:Double x:Key="Spacing12">12</system:Double>
<system:Double x:Key="Spacing16">16</system:Double>
<system:Double x:Key="Spacing20">20</system:Double>
<system:Double x:Key="Spacing24">24</system:Double>
<system:Double x:Key="Spacing32">32</system:Double>
<system:Double x:Key="Spacing40">40</system:Double>

---

🗺️ Schermate Dettagliate

1. MainWindow (Shell)

┌─────────────────────────────────────────────────────────────────┐
│ 🏛  PTRP                                         [User] [⚙] [×] │
├─────────────────────────────────────────────────────────────────┤
│ SIDEBAR (240px)         │ CONTENT AREA                    │
│                          │                                 │
│ 📊 Dashboard           │  [Dynamic View loaded here]      │
│ 👥 Pazienti            │                                 │
│ 📋 Progetti            │  (e.g., DashboardView,           │
│ 👨‍🏫 Educatori          │   PatientListView, etc.)          │
│ 📅 Calendario          │                                 │
│                          │                                 │
│ --- Sincronizzazione --- │                                 │
│ 🔄 Sync                 │                                 │
│                          │                                 │
│ --- Informazioni ---     │                                 │
│ 📊 Report              │                                 │
│ ⚙ Impostazioni         │                                 │
└──────────────────────────┴─────────────────────────────────┘
│ Snackbar: "Dati salvati con successo"                      │
└─────────────────────────────────────────────────────────────────┘

Componenti:

• Top Bar: Logo, Nome app, User info, Impostazioni
• Sidebar: Menu navigazione con icone MaterialDesign
• Content Area: Frame per navigazione views
• Snackbar: Toast notifications bottom-center

---

2. Dashboard Coordinatore

┌─────────────────────────────────────────────────────────────────┐
│ 📊 Dashboard                                              │
├─────────────────────────────────────────────────────────────────┤
│                                                               │
│ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ ┌────────────┐ │
│ │   42          │ │   18          │ │   8           │ │  15/20      │ │
│ │ Pazienti     │ │ Progetti     │ │ Educatori    │ │ Visite     │ │
│ │ Totali       │ │ Attivi       │ │ Operativi    │ │ Completate │ │
│ └───────────────┘ └───────────────┘ └───────────────┘ └────────────┘ │
│                                                               │
│ ┌─────────────────────────────────────────┐ ┌────────────────────┐ │
│ │ Gennaio 2025 - Andamento Visite      │ │ Top Educatori      │ │
│ │                                       │ │                    │ │
│ │  [Chart Area]                         │ │ 1. Bianchi (12)    │ │
│ │                                       │ │ 2. Verdi (10)      │ │
│ │  Line chart visite completate         │ │ 3. Rossi (8)       │ │
│ │  vs schedulate                         │ │ 4. Neri (7)        │ │
│ │                                       │ │ 5. Gialli (5)      │ │
│ └─────────────────────────────────────────┘ └────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

KPI Cards: Pazienti Totali, Progetti Attivi, Educatori Operativi, Visite Completate (con progress)
Grafici: Line chart andamento visite mese corrente
Liste: Top 5 educatori per numero visite

---

3. PatientListView (Master-Detail)

Vedi issue #51 per layout completo.

Layout:

• Sinistra (2)*: DataGrid con search/filtri
• Destra (*): Detail panel con anagrafica, progetto attivo, prossimo appuntamento

---

4. CalendarView

┌─────────────────────────────────────────────────────────────────┐
│ 📅 Calendario Appuntamenti                   [◀ Oggi ▶] [+]  │
├─────────────────────────────────────────────────────────────────┤
│                                                               │
│ ┌─ Gennaio 2025 ─────────────────────────────────────────┐ │
│ │ Lun   Mar   Mer   Gio   Ven   Sab   Dom                      │ │
│ │                                                             │ │
│ │  1     2     3     4     5     6     7                      │ │
│ │  8     9    10    11    12    13    14                      │ │
│ │ 15    16    17   [18]   19    20    21  <- Oggi evidenziato │ │
│ │ 22    23    24    25    26    27    28                      │ │
│ │ 29    30    31                                              │ │
│ │                                                             │ │
│ │ Days con appuntamenti: badge colorato                       │ │
│ └─────────────────────────────────────────────────────────────┘ │
│                                                               │
│ ┌─ Appuntamenti del 18/01/2025 ────────────────────────────┐ │
│ │                                                             │ │
│ │ 09:00 - Prima Apertura - Mario Rossi (Bianchi)             │ │
│ │ 10:30 - Visita Domiciliare - Luca Verdi (Neri)             │ │
│ │ 14:00 - Follow-up - Anna Bianchi (Gialli)                  │ │
│ │                                                             │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

Features:

• Calendario mensile con giorni cliccabili
• Badge su giorni con appuntamenti
• Lista appuntamenti giorno selezionato
• Bottone "Oggi" per tornare a data odierna
• Bottone "+" per nuovo appuntamento

---

🧭 Navigazione e Flussi

Flusso Coordinatore

1. PRIMO AVVIO
   └─> FirstRunView → Importa admin.ptrp → Dashboard

2. GESTIONE PAZIENTI
   Dashboard → Pazienti → PatientListView
   ├─> [Nuovo Paziente] → PatientFormView → Salva → PatientListView
   ├─> [Modifica] → PatientFormView → Salva → PatientListView
   └─> [Nuovo Progetto] → ProjectFormView → Salva → PatientListView

3. GESTIONE EDUCATORI
   Dashboard → Educatori → EducatorListView
   ├─> [Nuovo Educatore] → EducatorFormView → Salva → EducatorListView
   └─> [Modifica] → EducatorFormView → Salva → EducatorListView

4. CALENDARIO APPUNTAMENTI
   Dashboard → Calendario → CalendarView
   ├─> [Giorno] → Lista appuntamenti giorno
   ├─> [Nuovo Appuntamento] → AppointmentFormView → Salva → CalendarView
   └─> [Registra Visita] → VisitFormView → Salva → CalendarView

5. SINCRONIZZAZIONE
   Dashboard → Sync → SyncView
   ├─> [Tab Esporta] → Seleziona Educatore + Periodo → Esporta .ptrp
   └─> [Tab Importa] → Seleziona .ptrp → Verifica → Conflitti? → ConflictResolutionView → Importa

Flusso Educatore

1. PRIMO AVVIO
   └─> FirstRunView → Importa appointments_*.ptrp → Calendario

2. CALENDARIO (VIEW PRINCIPALE)
   CalendarView (Read-Only per appuntamenti)
   └─> [Registra Visita] → VisitFormView → Salva → CalendarView

3. SINCRONIZZAZIONE
   Calendario → Sync → SyncView
   ├─> [Tab Esporta] → Esporta visite registrate → .ptrp per Coordinatore
   └─> [Tab Importa] → Importa nuovi appuntamenti da Coordinatore

---

⚙️ Considerazioni Tecniche

Performance

1. Virtualizzazione: DataGrid con EnableRowVirtualization="True" per liste >500 items
2. Lazy Loading: Caricare dati al bisogno (es. detail panel solo quando paziente selezionato)
3. Async Operations: Tutte le operazioni DB async per non bloccare UI thread
4. Caching: Cache in-memory per dati frequentemente accessati (educatori, stati progetto)

Accessibilità

1. Keyboard Navigation: Tutti i controlli accessibili via tastiera (Tab, Enter, Esc)
2. Focus Management: Focus visibile e logico tra controlli
3. Screen Reader: AutomationProperties.Name per controlli custom
4. Contrast: Ratio 4.5:1 per testo normale, 3:1 per large text

Testing Strategy

1. Unit Tests: ViewModels con MOQ per repository mocking
2. Integration Tests: Services + Repository layer
3. UI Tests: Appium/WinAppDriver per critical paths
4. Manual Testing: Checklist per ogni schermata

Security

1. HMAC Validation: Firma digitale per pacchetti .ptrp
2. Data Encryption: AES per contenuto pacchetti
3. Input Sanitization: Validazione input utente per prevenire SQL injection
4. Audit Trail: Log operazioni critiche (creazione/modifica/eliminazione)

---

🛣️ Roadmap Implementazione

FASE 1: Foundation (Issue #45-49)

• Struttura base MainWindow con sidebar
• Navigation service
• Design system (colors, typography, styles)
• Schermata primo avvio

FASE 2: Core Features (Issue #50-51, +altri)

• Dashboard Coordinatore
• PatientListView Master-Detail
• EducatorListView
• CalendarView
• Form CRUD (Patient, Project, Educator, Appointment)
• VisitFormView

FASE 3: Sync & Advanced (Issue #52-53)

• SyncView (Export/Import)
• ConflictResolutionView
• HMAC validation
• Package encryption

FASE 4: Polish & Deploy (Issue #54, +altri)

• Validation UI
• Error handling globale
• Accessibility improvements
• Performance optimization
• Testing
• Documentation
• Deployment

---

📝 Riferimenti Issue

• FASE 1 - Foundation: Struttura Base MainWindow e Architettura UI #45 - FASE 1: Struttura Base MainWindow
• FASE 1 - Foundation: Implementazione HeaderControl #46 - FASE 1: Navigation Service
• FASE 1 - Foundation: Implementazione SidebarControl con Menu Dinamico #47 - FASE 1: Design System (Colors, Typography, Styles)
• FASE 1 - Foundation: Implementazione StatusBarControl #48 - FASE 1: MaterialDesignInXaml Integration
• FASE 1 - Foundation: Schermata Primo Avvio (First Run Setup) #49 - FASE 1: Schermata Primo Avvio
• FASE 2 - Core Features: Dashboard Coordinatore con KPI Cards #50 - FASE 2: Dashboard Coordinatore
• FASE 2 - Core Features: PatientListView con Master-Detail Layout #51 - FASE 2: PatientListView Master-Detail
• FASE 3 - Sync & Advanced: UI Sincronizzazione (Import/Export Pacchetti) #52 - FASE 3: UI Sincronizzazione
• FASE 3 - Sync & Advanced: Conflict Resolution UI #53 - FASE 3: Conflict Resolution UI
• FASE 4 - Polish & Deploy: Validation UI e Error Handling Globale #54 - FASE 4: Validation & Error Handling

---

🎯 Prossimi Passi

1. Iniziare con FASE 1 - Issue FASE 1 - Foundation: Struttura Base MainWindow e Architettura UI #45 (MainWindow structure)
2. Seguire roadmap sequenzialmente
3. Testing incrementale ad ogni fase
4. Review code + UI/UX dopo ogni milestone
5. Iterare basandosi su feedback

---

Questa documentazione è un living document. Aggiornare man mano che l'implementazione procede.

[artcava]

✅ Issue Create con Successo

Ho creato 11 issue dettagliate nel repository per completare tutti gli sviluppi necessari all'architettura UI proposta.

📋 Riepilogo Issue

FASE 1 - Foundation (5 issue)

• #45 - Struttura Base MainWindow con Sidebar e TopBar
• #46 - Navigation Service Implementation
• #47 - Design System (Colors, Typography, Styles)
• #48 - MaterialDesignInXaml Integration
• #49 - Schermata Primo Avvio (First Run Setup)

FASE 2 - Core Features (2 issue principali)

• #50 - Dashboard Coordinatore con KPI Cards
• #51 - PatientListView Master-Detail Layout

FASE 3 - Sync & Advanced (2 issue)

• #52 - UI Sincronizzazione (Import/Export Pacchetti)
• #53 - Conflict Resolution UI

FASE 4 - Polish & Deploy (1 issue)

• #54 - Validation UI e Error Handling Globale

DOCUMENTAZIONE (questa issue)

• #55 - Architettura UI Completa (questo documento)

---

📦 Contenuti delle Issue

Ogni issue include:

✅ Obiettivo chiaro e scope definito
✅ Codice completo XAML/C# per implementazione
✅ Struttura componenti (Views, ViewModels, Services)
✅ Design system integrato (colori, typography, spacing)
✅ Esempi pratici e pattern da seguire
✅ Acceptance criteria per verifica completamento
✅ Note implementative con best practices
✅ Issue correlate per tracciabilità

---

🎯 Ordine di Implementazione Consigliato

FASE 1 (Settimana 1-2)
├─ #45 → MainWindow Structure
├─ #46 → Navigation Service  
├─ #47 → Design System
├─ #48 → MaterialDesign Setup
└─ #49 → First Run View

FASE 2 (Settimana 3-5)
├─ #50 → Dashboard
└─ #51 → PatientList Master-Detail
    └─ (+ altre issue per EducatorList, Calendar, Forms)

FASE 3 (Settimana 6-7)
├─ #52 → Sync UI
└─ #53 → Conflict Resolution

FASE 4 (Settimana 8-9)
└─ #54 → Validation & Error Handling
    └─ (+ testing, accessibility, polish)

---

🔗 Collegamenti Rapidi

• Issue Dashboard: Repository Issues
• Filtra per label: fase-1, fase-2, fase-3, fase-4, ui, documentation
• Documentazione completa: Issue 📚 DOCUMENTAZIONE: Architettura UI Completa - Design System, Navigazione e Roadmap #55 (questa)

---

💡 Suggerimenti per lo Sviluppo

1. Branch Strategy: Creare feature branch per ogni issue

   git checkout -b feat/issue-45-mainwindow-structure

2. Commit Convention: Referenziare l'issue nei commit

   git commit -m "feat: implement MainWindow structure (#45)"

3. Pull Request: Una PR per issue, linkare l'issue nella descrizione

   Closes #45
   
   Implementazione struttura base MainWindow con sidebar...
   

4. Review: Code review + UI/UX review prima di merge su develop

5. Testing: Unit tests per ViewModels, integration tests per Services

---

Tutti i contenuti proposti nella risposta originale sono stati inclusi nelle issue. Pronto per iniziare l'implementazione! 🚀