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]>
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).