Files
CoHaiSe-CLOUD/docs/workflow.md
T
Gitea ActionsandEsiah f689ab4d57
CD — Deployment / deploy (push) Successful in 34s
refactor: restructure frontend and backend by domain services (#26)
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.

---------

Co-authored-by: xEsiah <[email protected]>
Reviewed-on: #26
Reviewed-by: Esiah <[email protected]>
Co-authored-by: Gitea Actions <-[email protected]>
2026-11-13 09:13:27 +00: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).