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/ :

  // 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

// 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

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.