feat: implementare ReportingService per KPI e statistiche Dashboard

[artcava]

🎯 Obiettivo

Implementare un servizio dedicato per calcolare KPI e statistiche aggregate mostrate nella Dashboard del Coordinatore.

📋 Contesto

La Dashboard (#50) richiede dati aggregati che non sono semplici query su singole entità:

• Numero pazienti totali
• Numero progetti attivi/sospesi/completati/deceased
• Numero educatori operativi
• Percentuale visite completate vs schedulate
• Andamento visite mensile (serie temporale)
• Top N educatori per numero visite registrate

Attualmente manca un servizio dedicato per orchestrare queste query e preparare i DTO per la Dashboard.

🎯 Servizio da Implementare

IReportingService + ReportingService

Metodi principali (proposta):

public interface IReportingService
{
    // KPI Cards
    Task<DashboardKpiDto> GetDashboardKpiAsync(CancellationToken ct = default);
    
    // Grafici andamento
    Task<VisitTrendDto> GetVisitTrendAsync(DateTime from, DateTime to, CancellationToken ct = default);
    
    // Classifiche
    Task<IReadOnlyList<TopEducatorDto>> GetTopEducatorsAsync(int count, DateTime? from = null, DateTime? to = null, CancellationToken ct = default);
    
    // Report dettagliati (futuri)
    Task<PatientStatisticsDto> GetPatientStatisticsAsync(Guid patientId, CancellationToken ct = default);
    Task<EducatorStatisticsDto> GetEducatorStatisticsAsync(Guid educatorId, CancellationToken ct = default);
}

public record DashboardKpiDto(
    int TotalPatients,
    int ActiveProjects,
    int SuspendedProjects,
    int CompletedProjects,
    int DeceasedProjects,
    int OperationalEducators,
    int ScheduledVisitsThisMonth,
    int CompletedVisitsThisMonth,
    decimal CompletionRate
);

public record VisitTrendDto(
    DateTime PeriodStart,
    DateTime PeriodEnd,
    IReadOnlyList<VisitDataPoint> DataPoints
);

public record VisitDataPoint(DateTime Date, int Scheduled, int Completed, int Missed);

public record TopEducatorDto(
    Guid EducatorId,
    string FullName,
    int VisitsRegistered,
    int ActiveProjects
);

📋 Tasks

• Definire IReportingService in PTRP.Services/Interfaces/
• Definire DTO per Dashboard in PTRP.Models/DTOs/ o namespace dedicato
• Implementare ReportingService in PTRP.Services/
• Integrare con repository esistenti (Patient, TherapyProject, ScheduledVisit, ActualVisit, Educator)
• Ottimizzare query aggregate (usare proiezioni, evitare N+1)
• Implementare caching in-memory per KPI con TTL configurabile (es. 5 minuti)
• Registrare servizio in DI container
• Aggiungere unit tests per calcolo KPI
• Integrare con DashboardViewModel (FASE 2 - Core Features: Dashboard Coordinatore con KPI Cards #50)

✅ Acceptance Criteria

• GetDashboardKpiAsync restituisce tutti i KPI richiesti dalla Dashboard
• GetVisitTrendAsync genera serie temporale per grafico andamento visite
• GetTopEducatorsAsync restituisce classifica educatori ordinata per numero visite
• Query aggregate ottimizzate (max 3-4 query DB per GetDashboardKpiAsync)
• Caching implementato per ridurre carico su refresh Dashboard
• Test coverage ≥ 80% per logiche di calcolo

🔗 Riferimenti

• FASE 2 - Core Features: Dashboard Coordinatore con KPI Cards #50 - FASE 2: Dashboard Coordinatore
• 📚 DOCUMENTAZIONE: Architettura UI Completa - Design System, Navigazione e Roadmap #55 - Architettura UI Completa (sezione Dashboard)
• feat: implementare PatientService e TherapyProjectService #73 - PatientService e TherapyProjectService
• feat: implementare repositories per progetti, appuntamenti e visite #72 - Repositories progetti/appuntamenti/visite
• perf: ottimizzare query database e implementare caching #16 - Performance e caching (ottimizzazioni correlate)

---

CLUSTER: Domain & Data (gap 5.1)
FASE: 2 - Core Business
PRIORITÀ: 🟡 ALTA
DIPENDENZE: #72, #73
BLOCKING: Dashboard (#50) necessita di dati aggregati