refactor: restructure frontend and backend by domain services
PR — Ouverture automatique / create-pr (push) Successful in 3s
PR — Ouverture automatique / create-pr (push) Successful in 3s
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.
This commit is contained in:
+11
-7
@@ -32,8 +32,8 @@ CI). L'exécuter avant de déclarer un travail fini.
|
||||
seulement. Le checksum bloquerait le démarrage.
|
||||
5. **API admin** : les routes `/api/cloud/admin/*` existent (UI Administration).
|
||||
La CLI (`make admin`) reste pour l'amorçage et les cas hors ligne.
|
||||
6. **Chemin disque** : toujours via `storage.ts` (`resolveInside`), jamais par
|
||||
concaténation depuis une entrée utilisateur.
|
||||
6. **Chemin disque** : toujours via `services/storageService.ts` (`resolveInside`),
|
||||
jamais par concaténation depuis une entrée utilisateur.
|
||||
7. **404 plutôt que 403** sur une ressource non accessible : ne pas introduire
|
||||
d'énumération.
|
||||
8. **CSP stricte** : pas de script en ligne dans `index.html` (utiliser un
|
||||
@@ -42,13 +42,17 @@ CI). L'exécuter avant de déclarer un travail fini.
|
||||
## Conventions
|
||||
|
||||
- TypeScript strict, project references racine.
|
||||
- Back : `routes/*Routes.ts` (HTTP fin) appellent `services/*Service.ts`
|
||||
(métier) ; le socle vit dans `config/`, `middleware/`, `utils/`, les types
|
||||
partagés dans `models/types.ts`.
|
||||
- Hono + Zod : toute route avec corps passe par un schéma Zod dédié.
|
||||
- Erreurs : `AppError` + codes (`errors.ts`) — jamais `throw` brut, jamais de
|
||||
détail de schéma dans une 500.
|
||||
- Erreurs : `AppError` + codes (`utils/errors.ts`) — jamais `throw` brut, jamais
|
||||
de détail de schéma dans une 500.
|
||||
- SQL : requêtes préparées uniquement, pas de `raw()` hors DDL.
|
||||
- Front : un seul client HTTP (`frontend/src/lib/api.ts`),
|
||||
`credentials: "same-origin"`. React Router 7 (`App.tsx`) + `AppShell`, contexte
|
||||
de session dans `lib/session.tsx`.
|
||||
- Front : un client HTTP (`frontend/src/services/apiClient.ts`), puis un service
|
||||
par domaine (`services/*Service.ts`), `credentials: "same-origin"`. React
|
||||
Router 7 (`App.tsx`) + `AppShell`, contexte de session dans
|
||||
`contexts/SessionContext.tsx`.
|
||||
- `.editorconfig` : 2 espaces, LF, UTF-8.
|
||||
|
||||
## Design system
|
||||
|
||||
+6
-6
@@ -91,7 +91,7 @@ l'offset exact.
|
||||
### Discussion (chat d'un dossier et membres)
|
||||
|
||||
Chaque dossier possède son propre salon. Le droit d'accès au dossier fait loi :
|
||||
lecture comme écriture passent par `canRead` (`backend/src/access.ts`), donc le
|
||||
lecture comme écriture passent par `canRead` (`backend/src/services/auditService.ts`), donc le
|
||||
salon d'un dossier `public` est ouvert à tout compte authentifié. La lecture est
|
||||
en texte brut, React échappe le rendu. La synchronisation est incrémentale par
|
||||
identifiant (`after`), sans WebSocket.
|
||||
@@ -158,7 +158,7 @@ utilise alors le sien.
|
||||
## Droits d'accès
|
||||
|
||||
Calculés **en base à chaque requête**, depuis la session — jamais depuis un
|
||||
en-tête (`backend/src/access.ts`).
|
||||
en-tête (`backend/src/services/auditService.ts`).
|
||||
|
||||
| Concept | Règle |
|
||||
| --- | --- |
|
||||
@@ -190,9 +190,9 @@ par tous les membres authentifiés, en écriture pour son propriétaire.
|
||||
|
||||
## Courriels
|
||||
|
||||
Les messages sortants sont construits par `backend/src/lib/mail-template.ts` :
|
||||
gabarit HTML aux couleurs de l'app (`#b71c1c`), logo, bouton d'action et mention
|
||||
**ne pas répondre**. Un repli texte accompagne chaque envoi.
|
||||
Les messages sortants sont construits par `backend/src/services/mailService.ts`
|
||||
(gabarit HTML aux couleurs de l'app (`#b71c1c`), logo, bouton d'action et mention
|
||||
**ne pas répondre**). Un repli texte accompagne chaque envoi.
|
||||
|
||||
Le logo `backend/src/assets/logo.png` est **embarqué** dans le message (pièce
|
||||
jointe `cid`), donc visible même quand le client bloque les images distantes.
|
||||
@@ -229,7 +229,7 @@ audit_logs, user_file_stars, chat_reads`.
|
||||
|
||||
## Erreurs métier
|
||||
|
||||
`AppError` avec codes stables (`backend/src/lib/errors.ts`). Correspondances
|
||||
`AppError` avec codes stables (`backend/src/utils/errors.ts`). Correspondances
|
||||
MariaDB : `1062` → 409, `1146` → 503 `NOT_MIGRATED`, `1406` → 422. Le corps d'une
|
||||
500 ne contient jamais de détail de schéma. Réponse normalisée :
|
||||
|
||||
|
||||
+30
-20
@@ -9,27 +9,36 @@ Node/TypeScript, une base MariaDB, un stockage de fichiers monté en volume.
|
||||
| Élément | Où |
|
||||
| --- | --- |
|
||||
| React 19 + Vite 8 + Tailwind 4 + react-router-dom 7 | `frontend` |
|
||||
| Hono | `backend/src/index.ts` (`src/lib` pour le socle) |
|
||||
| MariaDB (`mysql2`) | `backend/src/lib/db.ts` |
|
||||
| Nodemailer | `backend/src/lib/mail.ts` |
|
||||
| sharp (vignettes) | `backend/src/media.ts` |
|
||||
| Validation Zod | `backend/src/lib/config.ts` et chaque route |
|
||||
| Hono | `backend/src/index.ts` (`src/utils` pour le socle HTTP) |
|
||||
| MariaDB (`mysql2`) | `backend/src/config/db.ts` |
|
||||
| Nodemailer | `backend/src/services/mailService.ts` |
|
||||
| sharp (vignettes) | `backend/src/services/mediaService.ts` |
|
||||
| Validation Zod | `backend/src/config/appConfig.ts`, `src/utils/validators.ts` et chaque route |
|
||||
|
||||
## Découpage
|
||||
|
||||
```
|
||||
backend/src/lib/ socle serveur : config, db, mail, mail-template, ratelimit, http, service, auth, errors
|
||||
backend/src/ routes/, access.ts, storage.ts, media.ts, admin.ts
|
||||
backend/migrations/ 000 … 006
|
||||
frontend/src/ui/ design system (boutons, cartes, champs, spinner)
|
||||
frontend/src/ router + AppShell + pages/
|
||||
docker/ Dockerfile(.app/.api), nginx/, publish.sh
|
||||
backend/src/config/ configuration et connexion base (appConfig, db)
|
||||
backend/src/middleware/ gardes HTTP (auth : session, rôles)
|
||||
backend/src/models/ types partages (types.ts)
|
||||
backend/src/routes/ routeurs HTTP fins, un par domaine (*Routes.ts)
|
||||
backend/src/services/ logique metier, un fichier par domaine (*Service.ts)
|
||||
backend/src/utils/ socle technique : errors, http, ratelimit, validators, migrate, service
|
||||
backend/src/ index.ts (bootstrap), cli.ts, admin.ts
|
||||
backend/migrations/ 000 … 010
|
||||
frontend/src/services/ clients API par domaine (*Service.ts + apiClient.ts)
|
||||
frontend/src/contexts/ SessionContext, ThemeContext, I18nContext
|
||||
frontend/src/types/ types partages du front
|
||||
frontend/src/utils/ formatage (format.ts)
|
||||
frontend/src/ui/ design system (boutons, cartes, champs, spinner)
|
||||
frontend/src/ router + AppShell + pages/
|
||||
docker/ Dockerfile(.app/.api), nginx/, publish.sh
|
||||
```
|
||||
|
||||
`backend/src/lib` porte la mécanique générique (sessions, erreurs,
|
||||
migrations, courriel, limitation de débit), le reste de `backend` porte le
|
||||
métier : droits, quotas, chemins disque, traitement média. Tout vit dans un seul
|
||||
paquet, sans dépendance de workspace.
|
||||
`backend/src/utils` porte la mécanique générique (erreurs, HTTP, migrations,
|
||||
limitation de débit, validation), `backend/src/services` porte le métier :
|
||||
sessions, droits, quotas, chemins disque, traitement média, courriel.
|
||||
Tout vit dans un seul paquet, sans dépendance de workspace.
|
||||
|
||||
## Chaîne de démarrage
|
||||
|
||||
@@ -58,8 +67,9 @@ app-build (publish.sh, terminé avant nginx)
|
||||
- Pages : `Login`, `ForgotPassword`, `ResetPassword`, `ConfirmEmail`,
|
||||
`ChangePassword`, `Browser`, `Search`, `Gallery`, `Trash`, `Profile`,
|
||||
`Admin` (comptes / stockage / journal).
|
||||
- Client HTTP unique `lib/api.ts` (base `/api/cloud`, `same-origin`) ; contexte
|
||||
de session `lib/session.tsx` ; dialogues réutilisables dans
|
||||
- Client HTTP unique `services/apiClient.ts` (base `/api/cloud`, `same-origin`) ;
|
||||
services par domaine dans `services/*Service.ts` ; contexte de session
|
||||
`contexts/SessionContext.tsx` ; dialogues réutilisables dans
|
||||
`components/dialogs.tsx`.
|
||||
- En-têtes nginx : CSP stricte, HSTS, `nosniff`, `Referrer-Policy`,
|
||||
`Permissions-Policy` (`docker/nginx/snippets/`). `X-Frame-Options` est
|
||||
@@ -78,9 +88,9 @@ app-build (publish.sh, terminé avant nginx)
|
||||
## Stockage et médias
|
||||
|
||||
- `MEDIA_DIR=/data/media/originals`, `VARIANT_DIR=/data/media/variants`.
|
||||
- Chemin physique `${MEDIA_DIR}/<slug>/<uuid><ext>` (`storage.ts`), nom affiché
|
||||
jamais dans le chemin.
|
||||
- `media.ts` : classification (`image/video/audio/document/archive/other`),
|
||||
- Chemin physique `${MEDIA_DIR}/<slug>/<uuid><ext>` (`storageService.ts`), nom
|
||||
affiché jamais dans le chemin.
|
||||
- `mediaService.ts` : classification (`image/video/audio/document/archive/other`),
|
||||
vignette (`sharp`, seuil 480 px) écrite dans `VARIANT_DIR`, métadonnées dans
|
||||
`media_metadata` / `file_variants`. Indexation **best-effort** après upload.
|
||||
- Avatars dans `user_avatars`.
|
||||
|
||||
+1
-1
@@ -12,7 +12,7 @@ Réponse sur **`http://localhost:8083`**.
|
||||
|
||||
La configuration est validée **avant** l'ouverture d'aucun port : si une variable
|
||||
manque ou est mal formée, le process s'arrête en listant exactement ce qui
|
||||
pose problème (`backend/src/lib/config.ts`).
|
||||
pose problème (`backend/src/config/appConfig.ts`).
|
||||
|
||||
## Variables
|
||||
|
||||
|
||||
+3
-3
@@ -18,7 +18,7 @@
|
||||
|
||||
### Limitation de débit
|
||||
|
||||
- **Applicatif** : `createRateLimiter` (`backend/src/lib/ratelimit.ts`) par IP
|
||||
- **Applicatif** : `createRateLimiter` (`backend/src/utils/ratelimit.ts`) par IP
|
||||
sur `auth/login`, `account/forgot-password`, `account/reset-password`,
|
||||
`account/email-change`. Réglages `RATE_LIMIT_LOGIN_MAX` (10) et
|
||||
`RATE_LIMIT_LOGIN_WINDOW_MS` (60 s).
|
||||
@@ -36,7 +36,7 @@
|
||||
### Droits d'accès
|
||||
|
||||
Calculés **en base à chaque requête**, depuis la session — jamais depuis un
|
||||
en-tête (`backend/src/access.ts`). Lecture : propriétaire, permission
|
||||
en-tête (`backend/src/services/auditService.ts`). Lecture : propriétaire, permission
|
||||
`folder_permissions` (`read`/`write`/`admin`), ou dossier `public`. Écriture :
|
||||
`write`/`admin`. **404 plutôt que 403** : jamais d'indice sur l'existence d'une
|
||||
ressource.
|
||||
@@ -64,7 +64,7 @@ d'écriture par compte sur 10 s), édition et épinglage compris.
|
||||
|
||||
### Courriel
|
||||
|
||||
Nodemailer (`backend/src/lib/mail.ts`) avec `SMTP_HOST`. `PUBLIC_ORIGIN`
|
||||
Nodemailer (`backend/src/services/mailService.ts`) avec `SMTP_HOST`. `PUBLIC_ORIGIN`
|
||||
(obligatoire) construit les liens de réinitialisation et de confirmation ;
|
||||
aucun HTML utilisateur n'est injecté dans les messages.
|
||||
|
||||
|
||||
+1
-1
@@ -54,7 +54,7 @@ Design system local à `frontend/src/ui` : `Button`, `Card`, `Input`,
|
||||
|
||||
| Élément | Attendu |
|
||||
| --- | --- |
|
||||
| Socle & design system | internes à `backend/src/lib` et `frontend/src/ui` |
|
||||
| Socle & design system | internes à `backend/src/{config,middleware,utils}` et `frontend/src/ui` |
|
||||
| Port HTTP | `8083` (`COHAISE_HTTP_PORT`) |
|
||||
| Dépôt | autonome, importance égale front et back |
|
||||
| `.env` | jamais versionné (`.env.example` seulement) |
|
||||
|
||||
+8
-8
@@ -33,13 +33,13 @@ fichier est copié dans l'image, pas monté.
|
||||
|
||||
## Modifier une route
|
||||
|
||||
1. Schéma d'entrée : Zod dans `backend/src/routes/<entity>.ts`.
|
||||
2. Droits : passer par `backend/src/access.ts` (jamais par un paramètre
|
||||
venu du client).
|
||||
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/lib/errors.ts`.
|
||||
5. Audit si l'action est sensible (`audit()` dans `access.ts`).
|
||||
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
|
||||
@@ -65,10 +65,10 @@ Le design system vit dans `frontend/src/ui` (+ `src/styles`).
|
||||
|
||||
| Besoin | Fichier |
|
||||
| --- | --- |
|
||||
| Droit d'accès à un dossier/fichier | `backend/src/access.ts` |
|
||||
| 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/storage.ts` |
|
||||
| En-têtes, CORS, healthz | `backend/src/lib/http.ts` |
|
||||
| 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` |
|
||||
|
||||
Reference in New Issue
Block a user