Files
CoHaiSe-CLOUD/backend/README.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

213 lines
11 KiB
Markdown

# Cloud — modèle de données
Stockage privé de fichiers. Le contenu ne vit jamais dans la base : MariaDB ne
décrit que des métadonnées, les octets restent sur le disque sous
`storage_locations.mount_path`.
Le service **existe et sert ce modèle** : 11 routeurs sous `/api/cloud`
(`src/routes/{authRoutes,accountRoutes,adminRoutes,chatRoutes,directoryRoutes,fileRoutes,folderRoutes,mediaRoutes,searchRoutes,trashRoutes,uploadRoutes}.ts`),
adossés aux services métier de `src/services/*Service.ts`. Le détail des
endpoints, des droits et du déploiement est dans
[`../../docs/api.md`](../../docs/api.md),
[`../../docs/security.md`](../../docs/security.md) et
[`../../docs/architecture.md`](../../docs/architecture.md).
## Modèle de données
```mermaid
erDiagram
roles ||--o{ users : "attribue"
users ||--o{ user_sessions : "ouvre"
users ||--o{ user_avatars : "a pour photo"
users ||--o{ password_reset_tokens : "demande"
users ||--o{ email_change_requests : "demande"
users ||--o{ folders : "proprietaire"
users ||--o{ files : "proprietaire"
users ||--o{ folder_permissions : "beneficie"
users ||--o{ chat_messages : "ecrit"
users ||--o{ audit_logs : "trace"
storage_locations ||--o{ folders : "contient"
storage_locations ||--o{ files : "contient"
storage_locations ||--o{ user_avatars : "contient"
folders ||--o{ folders : "parent de"
folders ||--o{ files : "contient"
folders ||--o{ folder_permissions : "accede"
files ||--o{ media_metadata : "decrit"
files ||--o{ file_variants : "derive"
```
## Tables
16 tables en base après `007` (`share_links` ayant été supprimée par `004`).
Seules celles marquées « `/…` » sont atteignables depuis le front.
| Table | Rôle | Exposée par l'API |
|---|---|---|
| `roles` | `admin` et `user` (le `readonly` de `002` a été retiré par `004`) | indirectement (`users.role_slug`) |
| `users` | Comptes : prénom, nom, e-mail, mot de passe, quotas | `/auth/*` |
| `user_sessions` | Appareils connectés, révocation, expiration | session interne |
| `user_avatars` | Photo de profil, une ligne par compte | non |
| `password_reset_tokens` | Réinitialisation de mot de passe, hachée | non (aucune route) |
| `email_change_requests` | Validation du nouvel e-mail d'un compte | non (aucune route) |
| `storage_locations` | Volumes de stockage et quotas globaux | non (interne à `storage.ts`) |
| `folders` | Arborescence, avec `access_type` | `/folders` |
| `folder_permissions` | Droits nominatifs sur un dossier `shared` | non (aucune route) |
| `files` | Métadonnées de l'original, jamais ré-écrit | `/files` |
| `media_metadata` | Dimensions, durée, codecs, EXIF, couleur dominante | non (galerie non exposée) |
| `file_variants` | Miniatures et aperçus WebP dérivés | non |
| `chat_messages` | Salon d'un dossier : dossier (`ON DELETE CASCADE`), auteur (`ON DELETE SET NULL`), soft-delete | `/folders/:id/chat` |
| `settings` | Configuration clé-valeur | non |
| `audit_logs` | Piste d'audit | non (écrit par `audit()`) |
| `schema_migrations` | Versions appliquées | non |
## Trois notions à ne pas confondre
| Notion | Où elle vit | Ce que c'est |
|---|---|---|
| Le fichier | le disque | les octets d'origine, jamais ré-encodés |
| La ligne `files` | la base | le nom, la taille, la somme de contrôle, le chemin |
| La ligne `media_metadata` | la base | ce qu'un lecteur sait du fichier : dimensions, durée, appareil |
Un fichier dénué de `media_metadata` reste valide : un PDF ou un ZIP n'ont pas
de dimensions. C'est le comportement voulu, une entrée de galerie non encore
analysée doit rester listable.
## Originaux intacts, aperçus dérivés
Aucun fichier téléversé n'est ré-encodé. Le contenu reçu est écrit tel quel et
sa somme SHA-256 est mémorisée, ce qui sert à la fois de preuve d'intégrité et
de détection de doublon. Les WebP d'aperçu sont des fichiers **supplémentaires**
décrits par `file_variants`, avec un `purpose` valant `thumbnail` ou `preview` ;
un `UNIQUE` sur `(file_id, purpose)` interdit d'en empiler deux du même type.
La conséquence assumée : une photo contient ses coordonnées GPS, et puisqu'aucun
fichier n'est modifié, ces coordonnées restent lisibles dans l'original. Les
aperçus WebP sont ré-encodés et ne les portent pas.
## Trois types d'accès aux dossiers
`folders.access_type` porte l'intention, et non une garde :
| Valeur | Qui accède | Écriture |
|---|---|---|
| `private` | le propriétaire seul | le propriétaire |
| `shared` | le propriétaire et les comptes listés dans `folder_permissions` | selon le niveau `read`, `write` ou `admin` |
| `public` | tous les comptes de l'installation | tous peuvent ajouter, personne ne supprime les fichiers d'autrui |
Un seul dossier de l'instance porte `is_system = 1`, et l'unicité est réelle en
base : la colonne générée `system_marker` vaut `1` pour lui et `NULL` pour tous
les autres, donc un second dossier système viole `uq_folders_system`.
`chk_folders_system` impose en outre qu'un dossier système soit `public`.
Les dossiers enfants d'un dossier `public` restent soumis à l'unicité de nom :
deux enfants ne peuvent pas s'appeler pareil, puisque leur `parent_id` n'est pas
`NULL`. La limite ne concerne que la racine, dont les éléments ont
`parent_id IS NULL`.
Le niveau d'accès est **vérifié à chaque requête** en base, depuis la session :
voir [`../../docs/api.md`](../../docs/api.md).
## Budget et plafond par utilisateur
Deux réglages distincts, tous deux portés par `users` :
| Colonne | Effet |
|---|---|
| `quota_bytes` | volume total que le compte peut occuper, borné par `chk_users_quota` |
| `max_file_bytes` | taille maximale d'un dépôt unique |
`used_bytes` est maintenu par l'application et borné en base : impossible
d'écrire `used_bytes > quota_bytes`, quelle que soit la requête. Le quota est en
outre **re-vérifié en transaction** au moment de l'écriture. `max_file_bytes`, en
revanche, ne peut pas être garanti par une contrainte, car il compare une ligne
de `files` à une ligne d'`users` : c'est à l'application de le vérifier, sur la
taille déclarée et sur la taille réellement reçue.
`default_quota_bytes` et `max_upload_bytes` dans `settings` ne sont pas des
plafonds globaux, seulement les valeurs proposées à la création d'un compte.
## Unicité après suppression logique
Un nom ou une adresse peut être réutilisé après une suppression logique, grâce à
des colonnes générées :
```sql
active_email VARCHAR(255) GENERATED ALWAYS AS (IF(deleted_at IS NULL, email, NULL)) STORED,
UNIQUE KEY uq_users_email (active_email)
```
La ligne supprimée produit `NULL`, et en SQL plusieurs `NULL` ne sont pas
égaux : l'index ne la voit plus. C'est cette propriété qui sert deux fois, pour
libérer une adresse de compte et pour autoriser la réimportation d'un fichier au
même nom.
## Métadonnées : la part utile et le reste
Ce que la galerie filtre ou affiche est mis en colonnes indexées : `taken_at`,
`width`, `height`, `duration_ms`, `kind`, `video_codec`, `camera_make`,
`camera_model`, `dominant_color`. Le reste des EXIF, qui peut représenter une
trentaine de réglages d'objectif pour quelques kilo-octets et n'est jamais lu,
est facultatif et compressé dans `extra_metadata`. Rien n'oblige à le remplir.
## Chemin physique
Le nom affiché **n'entre jamais dans le chemin** : `${MEDIA_DIR}/<slug>/<uuid><ext>`,
avec `resolveInside()` qui refuse toute cible hors base. Le choix de
l'emplacement se fait parmi les `storage_locations` actifs, en privilégiant la
plus grande marge disponible.
## Migrations
| Fichier | Contenu |
|---|---|
| `000_schema_migrations.sql` | table de suivi des versions |
| `001_initial_schema.sql` | 11 tables, 17 clés étrangères, 14 `CHECK` |
| `002_reference_data.sql` | rôles, emplacement principal, réglages |
| `003_integrity_backstop.sql` | `CHECK` d'audit, interdiction du dossier parent de lui-même |
| `004_cloud_requirements.sql` | identité complète, sessions, validation d'e-mail, avatar, `access_type`, médias, variantes, budget par compte, suppression des liens publics |
| `005_storage_location_realign.sql` | `mount_path` réaligné sur `/data/media`, quota 400 Go, garde-fou sur les emplacements sans quota |
| `006_public_folder.sql` | crée le dossier système « Public », retire les réglages devenus morts |
| `007_chat.sql` | crée `chat_messages`, le salon d'un dossier (FK dossier `ON DELETE CASCADE`) |
`004` porte le passage d'un modèle de partage public vers un stockage privé :
elle supprime `share_links`, scinde `display_name` en `first_name` et
`last_name`, et remplace le plafond global `max_upload_bytes` par les deux
colonnes portées par `users`. Elle a aussi supprimé le rôle `readonly`, qui
venait d'une supposition et non d'un besoin formulé.
Une migration appliquée ne se modifie jamais : le checksum la fige. Voir
[`../../docs/deployment.md`](../../docs/deployment.md).
## Sécurité (couche modèle)
- Suppression d'un rôle encore attribué, ou d'un emplacement contenant des
données : refusée par la base (`ON DELETE RESTRICT`).
- Sessions et jetons stockés hachés en `CHAR(64)` ; `password_changed_at`
permet de dater un changement.
- Les identifiants de dossier et de fichier sont des UUID, non devinables.
- `audit_logs` survit à la suppression d'un utilisateur (`ON DELETE SET NULL`)
plus un instantané `user_email`, `ip_address`, `user_agent`.
En-têtes (CSP/HSTS), CORS et limitation de débit sont décrits dans
[`../../docs/security.md`](../../docs/security.md). Il n'y a **pas** de jeton
CSRF : les écritures sont des `POST`/`PUT`/`DELETE` et le cookie de session est
`SameSite=Lax`, ce qui bloque les écritures inter-origines.
## Limites actuelles
- **La règle « ne pas supprimer les fichiers d'autrui » n'est pas en base.**
Aucune contrainte SQL ne peut exprimer « le propriétaire ou un administrateur » :
elle ne vit que dans l'API, et une personne ouvrant un client SQL la contourne.
`audit_logs` est le seul rempart réel.
- **`max_file_bytes` n'est pas appliqué en base** (voir plus haut).
- **Les cycles profonds ne sont pas empêchés.** `chk_folders_not_self_parent`
bloque le parent direct de lui-même, mais `A → B → A` reste possible et demande
un parcours `WITH RECURSIVE` au moment d'un déplacement.
- **Deux éléments racine peuvent porter le même nom**, dossier ou fichier, puisque
leur clé étrangère de parent vaut `NULL`.
- `extra_metadata` n'est pas contraint en taille.
- **Partages publics par lien** : retirés par `004` ; le seul espace partagé est
le dossier système « Public » (`006`), ouvert à tout compte authentifié.
- Les réglages `allow_public_shares` et `default_share_expiry_days` ont été
supprimés par `006` (données mortes).