Files
CoHaiSe-CLOUD/docs/workflow.md
T
Esiah 68d4d5dea0
PR — Ouverture automatique / create-pr (push) Successful in 3s
refactor: restructure frontend and backend by domain services
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.
2026-11-13 09:45:21 +01:00

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

  1. Schéma d'entrée : Zod dans backend/src/routes/<entity>Routes.ts.
  2. Droits : passer par backend/src/services/auditService.ts (jamais par un paramètre venu du client).
  3. Réponse : renvoyer 404 si la ressource n'est pas censée exister pour ce compte, 403 seulement pour une règle explicite.
  4. Erreur métier : AppError depuis backend/src/utils/errors.ts.
  5. Audit si l'action est sensible (audit() dans services/auditService.ts).
  6. make check, puis redémarrage de l'API (docker compose up -d api).

Modifier le schéma

  1. Écrire backend/migrations/00N_….sql (número suivant, jamais éditer un fichier déjà appliqué).
  2. Vérifier : docker compose run --rm migrate node dist/cli.js --dir /migrations --check
  3. Appliquer : make migrate ou redémarrage de l'API.
  4. 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.css porte 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, remote origin https://git.cohaise.dev/Esiah/CoHaiSe-CLOUD.git.
  • Aucun commit pour l'instant : l'historique est vierge.
  • .gitignore exclut .env, .env.* (sauf .env.example), backups/, node_modules/, dist/, *.tsbuildinfo.

Pièges connus

  1. .env local désynchronisé de .env.example : les clés COHAISE_* manquantes basculent silencieusement sur les défauts compose.
  2. README de paquet (docker/README.md, backend/README.md) : états antérieurs du dépôt. Se fier à ce dossier docs/.
  3. Limitation de débit active (applicatif + nginx) : une rafale peut renvoyer 419/503.
  4. CSP stricte : aucun script inline dans index.html (voir public/theme.js).