Olhar/CLAUDE.md

# CLAUDE.md — Règles de développement Olhar-PWA

## Contexte du projet

Application Angular 19 PWA de gestion et tri de photos personnelles.
- **Frontend** : Angular 19, SCSS, PWA (Service Worker)
- **Backend** : API REST séparée — dépôt `Olhar-API` sur Gitea
- **Git remote** : `ssh://git@git.goutailler-olivier.com:2222/Gato/Olhar.git`

---

## 1. Documentation

### 1.1 Documentation fonctionnelle (obligatoire)
- Chaque feature doit être documentée dans `docs/functional/`.
- Le fichier décrit **ce que fait** la feature du point de vue utilisateur : cas d'usage, flux, règles métier.
- Format : Markdown, nommé selon la feature (`photo-sorting.md`, `authentication.md`, etc.).
- Mettre à jour la doc fonctionnelle **avant ou pendant** le développement, jamais après coup.

### 1.2 Documentation technique (obligatoire, séparée)
- Chaque module ou service significatif doit être documenté dans `docs/technical/`.
- Le fichier décrit **comment** c'est implémenté : architecture, choix techniques, dépendances, API contracts.
- Ne pas mélanger fonctionnel et technique dans le même fichier.
- Mettre à jour lors de tout changement architectural.

---

## 2. Gestion des commits et des versions

### 2.1 Commit et push systématiques
- **Committer et pusher après chaque changement significatif.**
- Ne jamais laisser du travail non commité en fin de session.

### 2.2 Découpage logique des développements
- Découper chaque développement en **étapes logiques et indépendantes**.
- Chaque étape doit produire une **version fonctionnelle de l'application** (pas de commit avec l'app cassée).
- Chaque commit doit avoir un message explicatif clair décrivant **ce qui a changé et pourquoi**.
- Format de message de commit recommandé :
  ```
  feat(scope): description courte

  Détail optionnel si nécessaire.
  ```
  Exemples de scopes : `auth`, `photos`, `sorting`, `pwa`, `docs`, `ci`, `config`

### 2.3 Convention de branches
- `main` : code stable, toujours fonctionnel
- `feat/<nom>` : nouvelles fonctionnalités
- Merger dans `main` uniquement quand les tests passent.

---

## 3. Tests et couverture

### 3.1 Couverture minimale : 90%
- La couverture de code (statements, branches, functions, lines) doit être **≥ 90%** en permanence.
- Vérifiée automatiquement dans `karma.conf.js` via `coverageReporter.check`.
- Toute nouvelle feature doit être accompagnée de ses tests unitaires.

### 3.2 Hook pre-commit
- Un hook `pre-commit` bloque le commit si les tests échouent ou si la couverture est < 90%.
- Le hook utilise **Docker** (ou Podman si disponible) pour exécuter les tests dans un environnement isolé avec Chrome headless.
- **Installer les hooks** : `npm install` (le script `postinstall` les installe automatiquement).
- Pour installer manuellement : `bash scripts/install-hooks.sh`

### 3.3 Docker pour les tests
- `Dockerfile.test` : image avec Node 24 + Chromium headless.
- `docker-compose.test.yml` : lance les tests en conteneur.
- Commandes :
  - `npm run test` : tests en mode watch (dev local)
  - `npm run test:ci` : tests one-shot Chrome headless
  - `npm run test:coverage` : tests + rapport de couverture
  - `docker compose -f docker-compose.test.yml run --rm test` : via Docker

---

## 4. Intégration avec l'API backend (Olhar-API)

### 4.1 Créer une issue Gitea pour chaque besoin API
- Dès qu'une feature nécessite un appel API (lecture ou écriture de données), **créer une issue** sur :
  **https://git.goutailler-olivier.com/Gato/Olhar-API**
- L'issue doit décrire : endpoint attendu, méthode HTTP, payload, réponse attendue, contexte fonctionnel.

### 4.2 Feature flags obligatoires pour toute dépendance API
- **L'application doit fonctionner même si l'API n'est pas disponible.**
- Implémenter un **feature flag** pour chaque appel API :
  - `false` : utiliser des données mockées/statiques, l'UI reste fonctionnelle
  - `true` : appel réel à l'API
- Les feature flags sont définis dans `src/environments/` :
  ```typescript
  // src/environments/environment.ts
  export const environment = {
    production: false,
    features: {
      apiPhotoUpload: false,      // créer issue #X si false
      apiPhotoList: false,        // créer issue #Y si false
    },
    apiUrl: 'http://localhost:3000'
  };
  ```
- Quand l'API sera implémentée, passer le flag à `true` et le code existant devra fonctionner sans modification de logique.

### 4.3 Pattern de service avec feature flag
```typescript
// Exemple de pattern à suivre
@Injectable({ providedIn: 'root' })
export class PhotoService {
  getPhotos(): Observable<Photo[]> {
    if (!environment.features.apiPhotoList) {
      return of(MOCK_PHOTOS); // données mock
    }
    return this.http.get<Photo[]>(`${environment.apiUrl}/photos`);
  }
}
```

---

## 5. Issues Gitea — Suivi du projet

### 5.1 Lire et prioriser les issues du projet
- Lire les issues ouvertes sur **https://git.goutailler-olivier.com/Gato/Olhar/**
- Les implémenter **par ordre de priorité** (labels, milestones, ordre de création).
- Fermer l'issue correspondante après implémentation et push.

### 5.2 Issues API (Olhar-API)
- Issues à créer sur **https://git.goutailler-olivier.com/Gato/Olhar-API**
- Référencer l'issue dans le code avec un commentaire si nécessaire.

---

## 6. Versioning sémantique

### 6.1 Règle de bump obligatoire
- **Monter la version à chaque commit** dans `package.json`.
- La version suit le format **semver** : `MAJEUR.MINEUR.PATCH`.
- Version initiale : `0.0.1`
- Règles de bump :
  - `PATCH` (+0.0.1) : correction de bug, ajout mineur, refactoring
  - `MINOR` (+0.1.0) : nouvelle fonctionnalité complète et fonctionnelle
  - `MAJOR` (+1.0.0) : changement cassant ou livraison majeure

### 6.2 Commandes de bump
```bash
npm run version:patch   # 0.0.1 → 0.0.2
npm run version:minor   # 0.1.0 → 0.2.0
npm run version:major   # 1.0.0 → 2.0.0
```

### 6.3 CI — Image Docker sur Gitea
- À chaque push sur `main`, la CI Gitea (`.gitea/workflows/ci.yml`) :
  1. Exécute les tests dans Docker
  2. Build et publie l'image Docker taguée avec la version du `package.json`
  3. Tagge aussi `latest`
- Secrets requis dans Gitea : `REGISTRY_USER`, `REGISTRY_TOKEN`

---

## 7. Architecture et qualité du code

- Utiliser les **standalone components** Angular (pas de NgModule sauf si nécessaire).
- Séparer clairement : composants (UI), services (logique métier), modèles (interfaces/types).
- Aucun appel HTTP direct dans les composants — passer par des services.
- Ne pas ajouter de commentaires explicatifs sur ce que fait le code — seulement sur le **pourquoi** si non évident.
- Pas d'abstraction prématurée : coder ce qui est demandé, pas ce qui pourrait être utile un jour.