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.

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:

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

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:

displayName
tracks
validPoints
distanceMeters
elevationGainMeters
duration
sport
diagnostics

---

activity_entry.dart

È il modello persistito nel DB.

Contiene i dati salvati della activity:

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

Qui abbiamo aggiunto/gestito anche:

copyWith(...)
bestName

bestName ora usa priorità tipo:

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:

ActivityEntryPreview
ActivitySportGroupsView
ActivityAlbumGroupsView
ActivityEntryListTile

---

activity_grouping.dart

Nuovo file per raggruppare attività.

Contiene:

ActivitySportGroup
ActivityAlbumGroup
ActivityGrouping

Responsabilità:

buildSportGroups(...)
buildAlbumGroups(...)

Quindi ora la logica per creare:

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

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:

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:

_openActivity(activity)

Usa ActivityTrack.

---

4. Componenti lista e griglie

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:

ActivityEntryListTile
ActivityTrackListTile

ActivityEntryListTile mostra attività salvate nel DB:

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

Menu azioni:

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:

ActivitySportGroup

Mostra card tipo:

Corsa
Bici
Camminata
Senza sport

Ogni card ha:

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

Tap sulla card:

apre lista filtrata per quello sport

---

activity_album_groups_view.dart

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

Usa:

ActivityAlbumGroup

Mostra card tipo:

Activity
main
Garmin
Zepp
Strava

Ogni card ha:

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

Tap sulla card:

apre lista filtrata per quell’album

---

5. Preview thumbnail

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:

List<ActivityPreviewPoint>

Contiene:

ActivityEntryPreview
_ActivityEntryPreviewPainter

---

preview/activity_track_preview.dart

Disegna la miniatura per attività aperte manualmente.

Usa:

ActivityTrack

Contiene:

ActivityTrackPreview
_ActivityTrackPreviewPainter

---

6. Dialog Activity

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

---

dialogs/activity_recalculate_dialog.dart

Contiene:

showActivityRecalculateDialog(...)

Mostra il dialog:

Confronto ricalcolo

Confronta:

distanza file
distanza ricalcolata
differenza distanza
D+ file
D+ ricalcolato
differenza D+

Usa:

ActivityFormatters

---

dialogs/activity_db_fields_dialog.dart

Contiene:

showActivityDbFieldsDialog(...)

Mostra tutti i campi DB della activity.

Include:

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

Prima questa logica stava tutta dentro activity_files_page.dart.

---

7. Utility Activity

lib/widgets/activity/utils/activity_formatters.dart

activity_formatters.dart

Contiene:

ActivityFormatters

Responsabilità:

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

Metodi principali:

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

---

Struttura completa attuale

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:

✓ 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.