Démarrage local

Le Clos des Eucalyptus se compose de deux dépôts Git indépendants placés dans un même dossier de travail : web/ pour SvelteKit et backend/ pour Go/PocketBase. Le Makefile à la racine orchestre les deux sans fusionner leur historique Git.

Prérequis

Outil	Version ou source	Vérification
Node.js	version exacte de web/.nvmrc : 22.19.0	node --version
npm	livré avec Node.js	npm --version
Go	version exacte de backend/.go-version : 1.24.3	go version
staticcheck	honnef.co/go/tools/cmd/[email protected]	staticcheck -version
Chromium Playwright	installé par Playwright ou son image CI	npx playwright --version
Make et Git	versions récentes	make --version, git --version

Avec nvm, placez-vous dans web/ puis exécutez nvm use. Installez staticcheck avec la version utilisée en CI :

go install honnef.co/go/tools/cmd/[email protected]

Disposition attendue

HarmonyV2/
├── Makefile       # orchestration locale des deux dépôts
├── AGENTS.md      # conventions partagées
├── web/           # dépôt Chris589/harmony-web
└── backend/       # dépôt Chris589/harmony-backend

Exécutez toujours les commandes Git dans le dépôt concerné. git status lancé dans web/ ne dit rien de l’état de backend/.

Installer les dépendances

Depuis HarmonyV2/ :

make install

Cette commande exécute go mod download, npm ci pour l’application web et npm ci --prefix documentation pour Starlight. Elle respecte les fichiers de verrouillage et doit être préférée à npm install pour reproduire la CI.

Pour installer un seul dépôt :

make -C backend install
make -C web install

Configurer le frontend

Copiez web/.env.example vers web/.env et adaptez les valeurs locales :

Variable	Valeur locale typique	Sensibilité
API_BASE_URL	http://127.0.0.1:8090	serveur uniquement
API_TOKEN	vide par défaut	secret serveur, facultatif
PUBLIC_MAPTILER_KEY	clé limitée aux domaines autorisés	publique par définition

API_TOKEN sert aux lectures serveur qui doivent recevoir des champs administratifs. Il ne doit jamais être importé dans un composant ou un module client. Une variable PUBLIC_* est intégrée au bundle : n’y placez aucun secret.

Initialiser les données

Depuis la racine du workspace :

make seed

Le backend effectue deux opérations idempotentes dans backend/pb_data :

1. superuser upsert crée ou met à jour le superutilisateur PocketBase ;
2. la commande de seed compilée avec le tag dev charge les données de démonstration.

Les valeurs par défaut sont réservées au développement. Pour les remplacer :

make seed \
  [email protected] \
  SEED_SUPERUSER_PASSWORD='mot-de-passe-local' \
  PB_DATA_DIR=pb_data

Le seed contient notamment trois appartements, des services, plans tarifaires, promotions, demandes fictives et utilisateurs de chaque rôle. Une seconde exécution met à jour les mêmes enregistrements au lieu de les dupliquer.

Attention

Ne ciblez jamais un répertoire de production avec PB_DATA_DIR. Les identifiants de seed sont publics dans le dépôt et ne sont pas des secrets acceptables hors environnement local.

Lancer la plateforme

Dans un terminal à la racine :

make dev

Le Makefile démarre les deux processus en parallèle :

Service	Adresse
Frontend SvelteKit	http://localhost:5173
API PocketBase	http://127.0.0.1:8090
Santé API	http://127.0.0.1:8090/api/hello
Administration PocketBase	http://127.0.0.1:8090/_/

Pour isoler les sorties, démarrez chaque application dans son propre terminal :

make dev-backend
make dev-web

Lancer les outils annexes

Depuis web/ :

make storybook
make docs

Storybook écoute sur http://localhost:6006. La documentation écoute sur http://localhost:4321 et synchronise le contrat OpenAPI avant de démarrer. Pour désigner explicitement le dépôt backend :

HARMONY_BACKEND_DIR=../backend npm run docs:dev

Première validation

Après l’installation et le seed :

make verify
make e2e

make verify valide d’abord le backend, puis le frontend et la documentation. make e2e reseed le backend, attend /api/hello, puis exécute Playwright contre le build de production du frontend.

Boucle de développement recommandée

1. Consultez l’issue et les dépendances cross-stack.
2. Créez une branche depuis develop dans chaque dépôt concerné.
3. Lancez le test ciblé en mode rapide pendant l’implémentation.
4. Vérifiez manuellement le parcours modifié.
5. Exécutez la validation complète du ou des dépôts.
6. Exécutez les E2E lorsqu’un parcours ou contrat traverse les deux applications.
7. Mettez à jour la documentation, OpenAPI et Storybook dans la même branche.

La suite est détaillée dans le workflow Git et pull requests.