Aves_mio0.88/activity.md

Riassunto aggiornato dei **file usati per la feature Activity** e cosa fa ciascuno.

## 1. Parser e lettura file attività

Questi file trasformano GPX / TCX / FIT in un modello comune `ActivityTrack`.

```text
lib/utils/activity_file_parser.dart
lib/utils/fit_activity_parser.dart
lib/utils/gpx_activity_parser.dart
lib/utils/tcx_activity_parser.dart
```

### `activity_file_parser.dart`

È il parser “centrale”.

Fa da router:

```text
file .gpx → GpxActivityParser
file .tcx → TcxActivityParser
file .fit → FitActivityParser
```

Responsabilità:

* controlla se il file è supportato;
* riceve bytes + nome file;
* sceglie il parser corretto;
* restituisce un `ActivityTrack`.

***

### `gpx_activity_parser.dart`

Parser specifico per file GPX.

Legge:

* traccia GPS;
* segmenti;
* punti;
* quota;
* timestamp;
* eventuale nome percorso;
* distanza / dislivello se disponibili o calcolabili.

***

### `tcx_activity_parser.dart`

Parser specifico per file TCX.

Legge:

* attività;
* lap;
* trackpoint;
* distanza;
* quota;
* durata;
* sport;
* eventuali dati cardio/cadenza se presenti.

***

### `fit_activity_parser.dart`

Parser specifico per file FIT.

Legge il formato binario FIT e ricava:

* coordinate GPS;
* distanza;
* dislivello;
* tempo;
* sport;
* metriche eventuali;
* dati utili per creare `ActivityTrack`.

***

## 2. Modelli dati Activity

```text
lib/model/activity/activity_track.dart
lib/model/activity/activity_entry.dart
lib/model/activity/activity_preview_point.dart
lib/model/activity/activity_grouping.dart
lib/model/activity/activity_scan_service.dart
lib/model/activity/activity_library_bootstrap.dart
```

***

### `activity_track.dart`

È il modello **in memoria** di una attività appena letta da file.

Usato quando:

* apri un file manualmente;
* apri una activity DB e il file viene riparsato;
* mostri la mappa.

Contiene cose tipo:

```text
displayName
tracks
validPoints
distanceMeters
elevationGainMeters
duration
sport
diagnostics
```

***

### `activity_entry.dart`

È il modello **persistito nel DB**.

Contiene i dati salvati della activity:

```text
id
uri
relativePath
directoryName
fileName
sport
title
routeName
distanceMeters
elevationGainMeters
durationMillis
isFavorite
tags
rating
diagnostics
...
```

Qui abbiamo aggiunto/gestito anche:

```dart
copyWith(...)
bestName
```

`bestName` ora usa priorità tipo:

```text
title personalizzato
routeName
displayName
fileName
```

***

### `activity_preview_point.dart`

È il modello dei punti semplificati salvati nel DB per disegnare la miniatura della traccia.

Serve per non dover riparsare tutto il file solo per vedere la thumbnail.

Usato da:

```text
ActivityEntryPreview
ActivitySportGroupsView
ActivityAlbumGroupsView
ActivityEntryListTile
```

***

### `activity_grouping.dart`

Nuovo file per raggruppare attività.

Contiene:

```dart
ActivitySportGroup
ActivityAlbumGroup
ActivityGrouping
```

Responsabilità:

```text
buildSportGroups(...)
buildAlbumGroups(...)
```

Quindi ora la logica per creare:

```text
Sport → Corsa / Bici / Camminata / Senza sport
Album → main / Garmin / Zepp / Strava / Activity
```

non sta più dentro `activity_files_page.dart`.

***

### `activity_scan_service.dart`

È il servizio che scansiona la cartella Activity tramite SAF.

Fa:

* lista file attività;
* riconoscimento GPX / TCX / FIT;
* parsing;
* creazione/aggiornamento `ActivityEntry`;
* salvataggio preview points;
* conservazione di dati utente come preferiti e nome personalizzato.

È uno dei file più importanti lato backend Activity.

***

### `activity_library_bootstrap.dart`

Serve per inizializzare/preparare la libreria Activity.

Tipicamente gestisce bootstrap iniziale, setup cartelle o stato iniziale della feature Activity.

***

## 3. Pagina e controller UI Activity

```text
lib/widgets/activity/activity_files_page.dart
lib/widgets/activity/activity_auto_sync_controller.dart
lib/widgets/activity/activity_map_page.dart
```

***

### `activity_files_page.dart`

È ancora la pagina principale Activity.

Ora gestisce:

* barra Activity;
* caricamento attività DB;
* preferiti;
* rename;
* apertura file manuale;
* scan manuale;
* auto scan;
* filtro attività;
* vista lista;
* vista Sport;
* vista Album;
* apertura mappa;
* apertura dialog ricalcolo;
* apertura dialog dettagli DB.

Adesso però è più leggero perché abbiamo spostato fuori:

* preview;
* list tile;
* sport group view;
* album group view;
* formatter;
* grouping;
* dialog ricalcolo;
* dialog dettagli DB.

***

### `activity_auto_sync_controller.dart`

Gestisce lo scheduling degli scan automatici.

Usato per:

```text
page_open
app_resumed
directory_selected
```

In pratica decide quando richiedere uno scan silenzioso senza farlo partire continuamente.

***

### `activity_map_page.dart`

È la pagina che mostra la traccia sulla mappa.

Viene aperta da:

```dart
_openActivity(activity)
```

Usa `ActivityTrack`.

***

## 4. Componenti lista e griglie

```text
lib/widgets/activity/activity_list_tile.dart
lib/widgets/activity/activity_sport_groups_view.dart
lib/widgets/activity/activity_album_groups_view.dart
```

***

### `activity_list_tile.dart`

Contiene le righe della lista Activity.

Classi:

```dart
ActivityEntryListTile
ActivityTrackListTile
```

`ActivityEntryListTile` mostra attività salvate nel DB:

```text
thumbnail
nome
data
sport · distanza · D+ · durata
cuore preferito
menu azioni
freccia
```

Menu azioni:

```text
Modifica nome
Ricalcola e confronta
Dettagli DB
```

`ActivityTrackListTile` mostra attività aperte manualmente con il pulsante `+`.

***

### `activity_sport_groups_view.dart`

Mostra la griglia tipo album per Sport.

Usa:

```dart
ActivitySportGroup
```

Mostra card tipo:

```text
Corsa
Bici
Camminata
Senza sport
```

Ogni card ha:

* thumbnail traccia;
* nome sport;
* numero attività.

Tap sulla card:

```text
apre lista filtrata per quello sport
```

***

### `activity_album_groups_view.dart`

Mostra la griglia tipo album per cartelle/album attività.

Usa:

```dart
ActivityAlbumGroup
```

Mostra card tipo:

```text
Activity
main
Garmin
Zepp
Strava
```

Ogni card ha:

* thumbnail traccia;
* nome album/cartella;
* numero attività.

Tap sulla card:

```text
apre lista filtrata per quell’album
```

***

## 5. Preview thumbnail

```text
lib/widgets/activity/preview/activity_entry_preview.dart
lib/widgets/activity/preview/activity_track_preview.dart
```

***

### `preview/activity_entry_preview.dart`

Disegna la miniatura per attività salvate nel DB.

Usa:

```dart
List<ActivityPreviewPoint>
```

Contiene:

```dart
ActivityEntryPreview
_ActivityEntryPreviewPainter
```

***

### `preview/activity_track_preview.dart`

Disegna la miniatura per attività aperte manualmente.

Usa:

```dart
ActivityTrack
```

Contiene:

```dart
ActivityTrackPreview
_ActivityTrackPreviewPainter
```

***

## 6. Dialog Activity

```text
lib/widgets/activity/dialogs/activity_recalculate_dialog.dart
lib/widgets/activity/dialogs/activity_db_fields_dialog.dart
```

***

### `dialogs/activity_recalculate_dialog.dart`

Contiene:

```dart
showActivityRecalculateDialog(...)
```

Mostra il dialog:

```text
Confronto ricalcolo
```

Confronta:

```text
distanza file
distanza ricalcolata
differenza distanza
D+ file
D+ ricalcolato
differenza D+
```

Usa:

```dart
ActivityFormatters
```

***

### `dialogs/activity_db_fields_dialog.dart`

Contiene:

```dart
showActivityDbFieldsDialog(...)
```

Mostra tutti i campi DB della activity.

Include:

```text
id
uri
relativePath
directoryName
fileName
sport
title
distanceMeters
durationMillis
isFavorite
diagnostics
...
```

Prima questa logica stava tutta dentro `activity_files_page.dart`.

***

## 7. Utility Activity

```text
lib/widgets/activity/utils/activity_formatters.dart
```

### `activity_formatters.dart`

Contiene:

```dart
ActivityFormatters
```

Responsabilità:

```text
format distanza
format D+
format durata
format data
delta distanza
delta quota
calcolo distanza da traccia
lettura diagnostics
validazione path Activity root
```

Metodi principali:

```dart
ActivityFormatters.distance(...)
ActivityFormatters.distanceDelta(...)
ActivityFormatters.elevation(...)
ActivityFormatters.entryElevation(...)
ActivityFormatters.elevationDelta(...)
ActivityFormatters.entryDate(...)
ActivityFormatters.entryDuration(...)
ActivityFormatters.computeDistanceFromTrack(...)
ActivityFormatters.readDiagnosticDouble(...)
ActivityFormatters.isExpectedActivityRoot(...)
```

***

# Struttura completa attuale

```text
lib/
├── utils/
│   ├── activity_file_parser.dart
│   ├── fit_activity_parser.dart
│   ├── gpx_activity_parser.dart
│   └── tcx_activity_parser.dart
│
├── model/
│   └── activity/
│       ├── activity_entry.dart
│       ├── activity_grouping.dart
│       ├── activity_library_bootstrap.dart
│       ├── activity_preview_point.dart
│       ├── activity_scan_service.dart
│       └── activity_track.dart
│
└── widgets/
    └── activity/
        ├── activity_auto_sync_controller.dart
        ├── activity_files_page.dart
        ├── activity_list_tile.dart
        ├── activity_map_page.dart
        ├── activity_sport_groups_view.dart
        ├── activity_album_groups_view.dart
        │
        ├── dialogs/
        │   ├── activity_db_fields_dialog.dart
        │   └── activity_recalculate_dialog.dart
        │
        ├── preview/
        │   ├── activity_entry_preview.dart
        │   └── activity_track_preview.dart
        │
        └── utils/
            └── activity_formatters.dart
```

***

## Stato attuale della feature

Adesso Activity supporta:

```text
✓ scan cartella Activity
✓ auto scan
✓ apertura file GPX / TCX / FIT
✓ lista attività
✓ preview traccia
✓ dettagli DB
✓ ricalcolo confronto
✓ preferiti
✓ rinomina attività
✓ Sport page tipo album
✓ Album page tipo album
✓ filtro per sport
✓ filtro per album
✓ apertura mappa attività
```

Il prossimo passo, quando vuoi, può essere uno di questi:

1. **pulizia finale di `activity_files_page.dart`**  
   spostando caricamenti DB in un controller/helper;

2. **UI griglia attività stile Collection**  
   al posto della lista;

3. **miglioramento card Sport/Album**  
   con overlay, icone sport, ultimo allenamento, distanza totale;

4. **statistiche per Sport/Album**  
   numero attività, km totali, D+ totale, tempo totale.