coach-ios/README.md

# Coach Hypnotruck — iOS

Wrapper natif iOS de [coach.hypnotruck.ch](https://coach.hypnotruck.ch) basé sur Capacitor 8.

## Architecture

- **Backend** : FastAPI + Jinja2 hébergé sur le VPS, accessible via `https://coach.hypnotruck.ch`
- **Coque iOS** : Capacitor 8 charge l'URL distante dans un WKWebView
- **Plugins natifs** : push notifications, local notifications, géolocalisation, HealthKit (Capgo), splash, status bar, haptics

Le code web n'est pas embarqué — l'app pointe vers la prod via `server.url` dans `capacitor.config.ts`. Avantage : déploiement web = mise à jour instantanée de l'app sans review Apple.

## Bundle ID & nom

- **Bundle ID** : `ch.hypnotruck.coach`
- **App Store name** : `Coach Hypnotruck`
- **Display name** : `Coach Hypnotruck`

## Prérequis (sur le Mac mini)

- macOS 13+ (Ventura ou plus récent)
- Xcode 15+ (App Store, ~10 Go)
- Command Line Tools : `xcode-select --install`
- Homebrew + `brew install node cocoapods`
- Node 20 LTS (compatible avec Cap 8)
- Compte Apple Developer Program actif (99 USD/an)
- Apple ID `dev@hypnotruck.ch` connecté dans Xcode → Settings → Accounts

## Workflow build

### 1. Cloner le repo sur le Mac mini

```bash
git clone git@gitea:sylvain/coach-ios.git
cd coach-ios
npm install
```

### 2. Générer les icônes & splash

```bash
npx @capacitor/assets generate --ios
```

Génère toutes les tailles requises depuis `resources/icon.png` (1024×1024) et `resources/splash.png` (2732×2732).

### 3. Ajouter la plateforme iOS (à faire UNE SEULE FOIS sur le Mac)

```bash
npx cap add ios
```

Cette commande crée le dossier `ios/` avec le projet Xcode, qui sera ensuite committé.

### 4. Sync (à chaque changement de plugins ou config)

```bash
npx cap sync ios
```

### 5. Ouvrir dans Xcode

```bash
npx cap open ios
```

Dans Xcode :

1. Sélectionner le projet **App** dans la navigation gauche
2. Onglet **Signing & Capabilities** :
   - Team : ton équipe Apple Developer
   - Bundle Identifier : `ch.hypnotruck.coach`
   - Cocher "Automatically manage signing"
3. Ajouter les capabilities requises :
   - **HealthKit** (lecture FC, pas, calories, VO2max)
   - **Push Notifications**
   - **Background Modes** → Remote notifications
4. Onglet **Info** : ajouter les clés Privacy obligatoires (voir section ci-dessous)

### 6. Build sur simulateur / device

- Simulateur : choisir un iPhone dans la barre du haut → ⌘R
- Device physique : connecter iPhone par USB, sélectionner, ⌘R (la 1ère fois iOS demande de faire confiance au certificat dev dans Réglages → Général → VPN et gestion des appareils)

### 7. Upload TestFlight

1. Xcode → Product → **Archive**
2. Fenêtre Organizer s'ouvre → sélectionner l'archive → **Distribute App** → **App Store Connect** → **Upload**
3. Sur [App Store Connect](https://appstoreconnect.apple.com) : créer une nouvelle app (1ère fois), section **TestFlight** → ajouter testeurs (jusqu'à 100 internes sans review, 10 000 externes avec review légère)

## Privacy keys requises (Info.plist)

Sans ces clés, iOS crashe à l'usage du plugin. À ajouter dans Xcode → onglet Info → Custom iOS Target Properties :

| Clé | Valeur (description affichée à l'utilisateur) |
|---|---|
| `NSHealthShareUsageDescription` | "Coach Hypnotruck lit vos données de santé (FC, pas, calories) pour adapter vos séances." |
| `NSHealthUpdateUsageDescription` | "Coach Hypnotruck enregistre vos séances dans Santé pour suivre votre progression." |
| `NSLocationWhenInUseUsageDescription` | "Coach Hypnotruck utilise votre position pour tracer vos sorties course et VTT." |
| `NSLocationAlwaysAndWhenInUseUsageDescription` | "Permet le suivi GPS pendant les sorties même app en arrière-plan." |
| `NSMotionUsageDescription` | "Coach Hypnotruck utilise les capteurs de mouvement pour mesurer votre activité." |
| `NSCameraUsageDescription` | "Coach Hypnotruck peut utiliser l'appareil photo pour scanner des codes-barres alimentaires." |

## Anti-rejet App Store (Guideline 4.2)

Apple rejette les apps qui sont juste un wrapper webview sans valeur native. Pour passer review :

- ✅ **Push notifications natives** (rappel séances) — implémenté côté iOS via `@capacitor/push-notifications`
- ✅ **HealthKit** (lecture FC, pas, calories) — implémenté via `@capgo/capacitor-health`
- ✅ **Géolocalisation** native pour tracking sorties
- ✅ **Local notifications** (rappels hors-ligne)
- ✅ **Haptics** sur actions importantes
- ⏳ À implémenter côté web : appeler ces plugins via JS bridge depuis coach.hypnotruck.ch

## Structure repo

```
coach-ios/
├── capacitor.config.ts       # Config Capacitor (bundle ID, URL, plugins)
├── package.json              # Deps Capacitor + plugins
├── www/                      # Page de bootstrap (chargement, fallback)
│   └── index.html
├── resources/                # Source icônes & splash (1024×1024, 2732×2732)
│   ├── icon.png
│   └── splash.png
├── ios/                      # Projet Xcode (généré par `cap add ios` sur Mac)
└── README.md
```

## Mise à jour de l'app

| Type de modif | Action requise |
|---|---|
| Changement web (templates, CSS, routes) | **Aucune** — l'app charge la prod en direct |
| Ajout plugin Capacitor | `npm install` + `npx cap sync ios` + nouveau build TestFlight |
| Changement icône / splash | `npx @capacitor/assets generate --ios` + sync + nouveau build |
| Changement bundle ID, version, capabilities | Build + soumission Apple review |

## TODO Phase 0

- [ ] Sur le Mac : `npx cap add ios` et commit du dossier `ios/`
- [ ] Configurer signing dans Xcode avec Apple ID `dev@hypnotruck.ch`
- [ ] Ajouter les Privacy keys dans Info.plist
- [ ] 1er build simulateur pour vérifier que la PWA charge bien
- [ ] 1er build device physique (iPhone perso)
- [ ] Upload TestFlight pour beta interne
- [ ] Préparer screenshots App Store (6.7" iPhone, min 3)
- [ ] Privacy policy URL (obligatoire avec HealthKit) — à héberger sur coach.hypnotruck.ch/privacy

## Support

- [Doc Capacitor](https://capacitorjs.com/docs)
- [Capgo Health plugin](https://github.com/Cap-go/capacitor-health)
- [Apple Developer](https://developer.apple.com/account)