refactor: restructure frontend and backend by domain services (#26)
CD — Deployment / deploy (push) Successful in 34s
CD — Deployment / deploy (push) Successful in 34s
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]>
This commit was merged in pull request #26.
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