CD — Déploiement / deploy (push) Successful in 19s
- chat: salon attache a un dossier, membres = comptes ayant acces au dossier - securite: suppression du passage automatique admin sur fichiers/dossiers/ corbeille/recherche/galerie/chat ; l'admin n'accede qu'a ses partages - favoris: tri en tete dans l'explorateur + page dediee (GET /favorites) - ui: retrait des pastilles Systeme/Public sur la carte dossier - migration 007_chat : table chat_messages --------- Co-authored-by: xEsiah <[email protected]> Reviewed-on: #8 Reviewed-by: Esiah <[email protected]> Co-authored-by: Gitea Actions <-[email protected]>
211 lines
10 KiB
Markdown
211 lines
10 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** : 10 routes sous `/api/cloud`
|
|
(`src/routes/{auth,folders,files}.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).
|