Split the monolithic backend (lib/, routes/, access.ts, storage.ts, media.ts) into a layered structure inspired by JeanXXIII-CRM: - config/: appConfig, db - middleware/: auth (session, roles, cookies) - models/: shared types - routes/: *Routes.ts (thin HTTP handlers) - services/: *Service.ts (business logic, one per domain) - utils/: errors, http, migrate, ratelimit, validators, service bootstrap Frontend likewise: services/*Service.ts + apiClient, contexts/, types/, utils/format. Route files now carry the "Routes" suffix; service files are named authService.ts, ratelimit.ts, etc. and live in their own files, frontend and backend separated. Updated docs and READMEs to reflect the new layout. Typecheck and builds pass.
3.7 KiB
Workflow — CoHaiSe Cloud
Boucle de développement
make dev # Vite sur http://localhost:5174, proxy /api → 127.0.0.1:3101
Le front tourne hors Docker ; l'API et la base doivent être levées :
make up # db + migrate + api (+ nginx si besoin)
Le proxy vite.config.ts envoie /api vers 3101, donc les appels
fetch('/api/cloud/…') du code source fonctionnent à l'identique en dev et en
prod.
Vérification
make check # npm run typecheck puis npm run build
curl -I http://localhost:8083/healthz
curl -s http://localhost:3101/healthz
Il n'y a ni linter, ni framework de test, ni CI : typecheck + build
sont les seules garanties automatiques. .editorconfig porte les conventions.
Après un changement de docker/nginx/cloud.conf : l'image doit être
reconstruite (docker compose build nginx && docker compose up -d nginx) — le
fichier est copié dans l'image, pas monté.
Modifier une route
- Schéma d'entrée : Zod dans
backend/src/routes/<entity>Routes.ts. - Droits : passer par
backend/src/services/auditService.ts(jamais par un paramètre venu du client). - Réponse : renvoyer 404 si la ressource n'est pas censée exister pour ce compte, 403 seulement pour une règle explicite.
- Erreur métier :
AppErrordepuisbackend/src/utils/errors.ts. - Audit si l'action est sensible (
audit()dansservices/auditService.ts). make check, puis redémarrage de l'API (docker compose up -d api).
Modifier le schéma
- Écrire
backend/migrations/00N_….sql(número suivant, jamais éditer un fichier déjà appliqué). - Vérifier :
docker compose run --rm migrate node dist/cli.js --dir /migrations --check - Appliquer :
make migrateou redémarrage de l'API. - Décrire la migration dans
docs/api.md(tableau des migrations).
Le DDL MariaDB n'est pas transactionnel : une migration interrompue peut laisser la base à moitié migrée. Dans ce cas, corriger par une nouvelle migration, pas en éditant l'ancienne (le checksum bloquerait le démarrage).
Modifier le design system
Le design system vit dans frontend/src/ui (+ src/styles).
tokens.cssporte les couleurs et typographies ; ne pas en coder ailleurs.- Après modification :
make front(le build Vite reprend tout).
Où changer quoi
| Besoin | Fichier |
|---|---|
| Droit d'accès à un dossier/fichier | backend/src/services/auditService.ts |
| Taille/quota par défaut | migration 004, table users / settings |
| Chemin physique des fichiers | backend/src/services/storageService.ts |
| En-têtes, CORS, healthz | backend/src/utils/http.ts |
| Durée de session | SESSION_TTL_HOURS |
| Port | COHAISE_HTTP_PORT (nginx), COHAISE_API_PORT (API) |
| Interface (parcours dossiers) | frontend/src/pages/Browser.tsx |
| Routes et gardes du front | frontend/src/App.tsx |
| Couleurs / composants | frontend/src/styles/tokens.css |
Git
- Branche
main, remoteorigin https://git.cohaise.dev/Esiah/CoHaiSe-CLOUD.git. - Aucun commit pour l'instant : l'historique est vierge.
.gitignoreexclut.env,.env.*(sauf.env.example),backups/,node_modules/,dist/,*.tsbuildinfo.
Pièges connus
.envlocal désynchronisé de.env.example: les clésCOHAISE_*manquantes basculent silencieusement sur les défauts compose.- README de paquet (
docker/README.md,backend/README.md) : états antérieurs du dépôt. Se fier à ce dossierdocs/. - Limitation de débit active (applicatif + nginx) : une rafale peut renvoyer
419/503. - CSP stricte : aucun script inline dans
index.html(voirpublic/theme.js).