shoottracker/README.md

# ShootTracker

**PWA de suivi de performance en tir sportif** — Analyse d'impacts par IA (YOLOv8), scores, progression, export PDF/Excel.

---

## Architecture

| Composant | Technologie | Rôle |
|---|---|---|
| Frontend | React 18 + TypeScript + Tailwind + Vite + PWA | Interface utilisateur |
| Backend | Node.js + Express + TypeScript | API proxy IA, exports PDF/Excel |
| Base de données | Supabase (PostgreSQL) | Données, authentification, stockage photos |
| Microservice IA | Python + FastAPI + YOLOv8 + OpenCV | Analyse automatique des impacts |
| Déploiement | Docker + Coolify + Gitea | Infrastructure domench.fr |

---

## Démarrage rapide (développement local)

### Prérequis
- Node.js 20+
- Python 3.11+
- Un projet Supabase créé (voir ci-dessous)

### 1. Configurer Supabase

1. Créez un projet sur [supabase.com](https://supabase.com)
2. Dans **SQL Editor**, exécutez le fichier `supabase/migrations/001_initial_schema.sql`
3. Dans **Storage**, créez 3 buckets privés : `avatars`, `weapon-photos`, `target-photos`
4. Dans **Authentication → URL Configuration**, ajoutez `http://localhost:5173` en Site URL

### 2. Variables d'environnement

```bash
# Frontend
cp frontend/.env.example frontend/.env
# Remplir VITE_SUPABASE_URL et VITE_SUPABASE_ANON_KEY

# Backend
cp backend/.env.example backend/.env
# Remplir SUPABASE_URL et SUPABASE_SERVICE_ROLE_KEY
```

### 3. Lancer le microservice IA

```bash
cd ai-service
pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
# → http://localhost:8000
```

### 4. Lancer le backend

```bash
cd backend
npm install
npm run dev
# → http://localhost:3001
```

### 5. Lancer le frontend

```bash
cd frontend
npm install
npm run dev
# → http://localhost:5173
```

---

## Déploiement sur domench.fr

```bash
# Depuis le dossier Applications VPS
python deploy_shoottracker.py
```

Le script :
1. Demande les clés Supabase
2. Crée les repos Gitea (`shoottracker` + `shoottracker-ai`)
3. Push le code
4. Crée et configure les applications dans Coolify
5. Déclenche le déploiement
6. Attends que l'app soit live

**URLs de production :**
- Application : `https://shoottracker.domench.fr`
- Microservice IA : `https://shoottracker-ai.domench.fr`

---

## Déploiement avec Docker Compose (local)

```bash
# Créer .env depuis le modèle
cp .env.example .env
# Remplir les valeurs Supabase

# Build et démarrage
docker-compose up --build

# L'app est accessible sur http://localhost:3001
```

---

## Structure du projet

```
shoottracker/
├── frontend/                    # React PWA
│   ├── src/
│   │   ├── pages/
│   │   │   ├── auth/            # Login, Register
│   │   │   ├── session/         # NewSession, SessionCapture, SessionDetail
│   │   │   ├── Dashboard.tsx
│   │   │   ├── Arsenal.tsx      # Coffre virtuel
│   │   │   ├── WeaponForm.tsx
│   │   │   ├── Progress.tsx     # Progression + graphiques
│   │   │   └── Profile.tsx      # Profil + invitations
│   │   ├── components/          # Layout, BottomNav, Sidebar...
│   │   ├── lib/                 # supabase.ts, api.ts, store.ts
│   │   └── types/               # TypeScript interfaces
│   └── ...
├── backend/                     # Node.js/Express
│   └── src/
│       ├── routes/
│       │   ├── analyze.ts       # Proxy → microservice IA
│       │   └── export.ts        # PDF et Excel
│       └── middleware/auth.ts   # Vérification JWT Supabase
├── ai-service/                  # Python FastAPI
│   ├── main.py                  # API FastAPI
│   ├── analyzer.py              # YOLOv8 + OpenCV
│   ├── requirements.txt
│   └── Dockerfile
└── supabase/
    └── migrations/
        └── 001_initial_schema.sql  # Tables + RLS + Storage
```

---

## Modules

### Module 1 — Authentification
- Inscription / connexion email via Supabase Auth
- Profil éditable (nom, club, disciplines, photo)
- Invitations : jusqu'à 5 amis (lien unique, 7 jours)

### Module 2 — Arsenal (coffre virtuel)
- CRUD armes avec photo, type, calibre, marque, modèle, numéro de série
- Filtre par type, recherche, archivage
- Photos stockées dans Supabase Storage

### Module 3 — Séance d'entraînement
- Ouverture : date, lieu (mémorisé), arme, type cible, distance
- Cycle de tirs : photo → IA → ajustement manuel
- Analyse IA : YOLOv8 + zones ISSF (1-10) + groupement
- Soustraction d'image pour les séries sur même cible
- Clôture avec résumé complet

### Module 4 — Dashboard & Progression
- Tableau de bord global avec graphiques Recharts
- Filtres : période (30j/90j/1an/tout) + arme
- Courbe de progression, dispersion, histogramme
- Historique cliquable des séances

### Module 5 — Export
- PDF par séance (jsPDF + jspdf-autotable) avec photo annotée
- Excel global (SheetJS) avec toutes les séances

---

## Variables d'environnement

### Frontend (Vite)
| Variable | Description |
|---|---|
| `VITE_SUPABASE_URL` | URL du projet Supabase |
| `VITE_SUPABASE_ANON_KEY` | Clé publique Supabase |

### Backend (Node.js)
| Variable | Description |
|---|---|
| `SUPABASE_URL` | URL du projet Supabase |
| `SUPABASE_SERVICE_ROLE_KEY` | Clé service role (privée) |
| `AI_SERVICE_URL` | URL du microservice IA |
| `PORT` | Port du serveur (défaut: 3001) |
| `CORS_ORIGIN` | Domaine autorisé en CORS |

### Microservice IA (Python)
| Variable | Description |
|---|---|
| `PORT` | Port du serveur (défaut: 8000) |
| `YOLO_MODEL_PATH` | Chemin du modèle YOLOv8 (défaut: yolov8n.pt) |

---

## Fine-tuning YOLOv8

Pour améliorer la détection des impacts au-delà du modèle généraliste :

1. Collectez des photos de cibles annotées (labelisez les trous)
2. Utilisez [Roboflow](https://roboflow.com) pour l'annotation
3. Entraînez avec Ultralytics :
   ```bash
   yolo train model=yolov8n.pt data=dataset.yaml epochs=100 imgsz=640
   ```
4. Remplacez `yolov8n.pt` par votre modèle fine-tuné dans `YOLO_MODEL_PATH`

---

## Sécurité

- Row Level Security (RLS) activé sur toutes les tables Supabase
- Chaque utilisateur n'accède qu'à ses propres données
- Photos stockées avec accès privé (buckets Supabase)
- Clé `service_role` uniquement côté backend, jamais exposée au frontend
- Tokens JWT Supabase vérifiés sur chaque appel API backend