Files
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

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