feat(init): initialisation du projet Angular 19 PWA — v0.0.1

- Angular 19 avec routing, SCSS, PWA (Service Worker + manifest) - Couverture de tests ≥ 90% configurée dans karma.conf.js - Docker pour tests isolés (Dockerfile.test + docker-compose.test.yml) - Image de production multi-stage (Dockerfile + nginx.conf) - Hook pre-commit bloquant si tests échouent ou couverture < 90% - CI Gitea (.gitea/workflows/ci.yml) : tests + build/push image Docker - Versioning SemVer depuis 0.0.1 avec scripts npm version:* - Feature flags par environnement (src/environments/) - Documentation fonctionnelle (docs/functional/) et technique (docs/technical/) - CLAUDE.md avec toutes les règles de développement Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-06-06 18:52:08 +02:00
commit 915d3ce3a7
47 changed files with 17424 additions and 0 deletions
@@ -0,0 +1,165 @@
+# 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.