Le niveau `cloud` etait redondant : il ne reste qu'une seule application. - backend/cloud/* -> backend/*, frontend/cloud/* -> frontend/* - workspaces npm : frontend et backend ; reference tsconfig ./backend - extends tsconfig.base corrige (../ au lieu de ../../) - docker-compose : APP_DIR backend/frontend, montage ./backend/migrations - deploy.yml : reconstruit aussi l'image migrate - chemins mis a jour dans les docs, le Makefile et docker/README.md
141 lines
6.6 KiB
Markdown
141 lines
6.6 KiB
Markdown
# API et modèle de données — CoHaiSe Cloud
|
|
|
|
Base : **`/api/cloud`**, plus `GET /healthz` (sonde base, `503` si indisponible).
|
|
Middleware `attachUser` monté sur les préfixes ; `requireAuth` sur chaque route
|
|
sauf la connexion et les flux publics (mot de passe oublié, confirmation
|
|
d'adresse).
|
|
|
|
## Routes
|
|
|
|
### Session
|
|
|
|
| Méthode | Chemin | Garde |
|
|
| --- | --- | --- |
|
|
| POST | `/api/cloud/auth/login` | publique, **limitée par IP** |
|
|
| POST | `/api/cloud/auth/logout` | `requireAuth` |
|
|
| GET | `/api/cloud/auth/me` | `requireAuth` |
|
|
| POST | `/api/cloud/auth/change-password` | `requireAuth` + Zod |
|
|
|
|
### Compte
|
|
|
|
| Méthode | Chemin | Garde |
|
|
| --- | --- | --- |
|
|
| PATCH | `/api/cloud/account/profile` | `requireAuth` |
|
|
| GET | `/api/cloud/account/sessions` | `requireAuth` |
|
|
| DELETE | `/api/cloud/account/sessions/:id` | `requireAuth` |
|
|
| DELETE | `/api/cloud/account/sessions` | `requireAuth` (les autres) |
|
|
| PUT | `/api/cloud/account/avatar` | `requireAuth` (corps brut image) |
|
|
| GET | `/api/cloud/account/avatar/:userId` | `requireAuth` |
|
|
| DELETE | `/api/cloud/account/avatar` | `requireAuth` |
|
|
| POST | `/api/cloud/account/forgot-password` | publique, **limitée par IP** |
|
|
| POST | `/api/cloud/account/reset-password` | publique, **limitée par IP** |
|
|
| POST | `/api/cloud/account/email-change` | `requireAuth`, **limitée** |
|
|
| POST | `/api/cloud/account/email-change/confirm` | publique (jeton) |
|
|
|
|
### Dossiers et fichiers
|
|
|
|
| Méthode | Chemin | Garde |
|
|
| --- | --- | --- |
|
|
| GET | `/api/cloud/folders` | `requireAuth` (visibles seulement) |
|
|
| POST | `/api/cloud/folders` | `requireAuth` |
|
|
| PATCH | `/api/cloud/folders/:id` | `requireAuth` + gestion du dossier |
|
|
| POST | `/api/cloud/folders/:id/move` | `requireAuth` + gestion |
|
|
| DELETE | `/api/cloud/folders/:id` | `requireAuth` + gestion (corbeille) |
|
|
| GET | `/api/cloud/folders/:id/permissions` | `requireAuth` + gestion |
|
|
| POST | `/api/cloud/folders/:id/permissions` | `requireAuth` + gestion |
|
|
| DELETE | `/api/cloud/folders/:id/permissions/:userId` | `requireAuth` + gestion |
|
|
| GET | `/api/cloud/files` | `requireAuth` |
|
|
| PUT | `/api/cloud/files` | `requireAuth` (corps brut, upload) |
|
|
| GET | `/api/cloud/files/:id/download` | `requireAuth` |
|
|
| GET | `/api/cloud/files/:id/thumbnail` | `requireAuth` |
|
|
| PATCH | `/api/cloud/files/:id` | `requireAuth` + écriture (renommer) |
|
|
| POST | `/api/cloud/files/:id/move` | `requireAuth` + écriture |
|
|
| PUT | `/api/cloud/files/:id/star` | `requireAuth` |
|
|
| DELETE | `/api/cloud/files/:id` | `requireAuth` + écriture (corbeille) |
|
|
|
|
### Corbeille, recherche, galerie
|
|
|
|
| Méthode | Chemin | Garde |
|
|
| --- | --- | --- |
|
|
| GET | `/api/cloud/trash` | `requireAuth` |
|
|
| POST | `/api/cloud/trash/folders/:id/restore` | `requireAuth` |
|
|
| POST | `/api/cloud/trash/files/:id/restore` | `requireAuth` |
|
|
| DELETE | `/api/cloud/trash/folders/:id` | `requireAuth` (purge) |
|
|
| DELETE | `/api/cloud/trash/files/:id` | `requireAuth` (purge) |
|
|
| DELETE | `/api/cloud/trash` | `requireAuth` (vider) |
|
|
| GET | `/api/cloud/search` | `requireAuth` |
|
|
| GET | `/api/cloud/media` | `requireAuth` |
|
|
|
|
### Administration (`role_slug = admin`)
|
|
|
|
| Méthode | Chemin |
|
|
| --- | --- |
|
|
| GET | `/api/cloud/admin/stats` |
|
|
| GET | `/api/cloud/admin/users` |
|
|
| POST | `/api/cloud/admin/users` |
|
|
| PATCH | `/api/cloud/admin/users/:id` |
|
|
| DELETE | `/api/cloud/admin/users/:id` |
|
|
| POST | `/api/cloud/admin/users/:id/reset-password` |
|
|
| GET | `/api/cloud/admin/storage-locations` |
|
|
| POST | `/api/cloud/admin/storage-locations` |
|
|
| PATCH | `/api/cloud/admin/storage-locations/:id` |
|
|
| GET | `/api/cloud/admin/audit` |
|
|
|
|
## Droits d'accès
|
|
|
|
Calculés **en base à chaque requête**, depuis la session — jamais depuis un
|
|
en-tête (`backend/src/access.ts`).
|
|
|
|
| Concept | Règle |
|
|
| --- | --- |
|
|
| Rôles (`users.role_slug`) | `admin` passe tout, `user` par défaut ; `readonly` seedé par `002` puis supprimé par `004` |
|
|
| Lecture | propriétaire du dossier, **ou** ligne `folder_permissions` de niveau `read`/`write`/`admin`, **ou** dossier `access_type = 'public'` |
|
|
| Écriture | propriétaire, **ou** `write`/`admin` dans `folder_permissions` |
|
|
| Gestion (renommer/déplacer/partager/supprimer) | propriétaire, `admin` de partage, ou rôle global `admin` (`canManageFolder`) |
|
|
| Expiration | `expires_at NULL` ou future ; une permission expirée disparaît de la lecture |
|
|
| Listing | filtré en SQL — les entrées non visibles ne sont pas chargées puis masquées |
|
|
| Réponse | **404 plutôt que 403** : jamais d'indice sur l'existence d'une ressource |
|
|
|
|
Le dossier **Public** (`006_public_folder.sql`, `access_type='public'`) est lisible
|
|
par tous les membres authentifiés, en écriture pour son propriétaire.
|
|
|
|
## Validation et limites d'upload
|
|
|
|
| Contrôle | Détail |
|
|
| --- | --- |
|
|
| Corps | `PUT /files` en flux brut (pas de multipart), `?name=` et `?folderId=` |
|
|
| Taille | plafond `users.max_file_bytes`, vérifié en flux (coupure si dépassement) |
|
|
| Quota | `users.used_bytes` + quota `storage_locations`, revérifiés avant écriture |
|
|
| Chemin disque | dérivé du slug + UUID, jamais du nom affiché (`storage.ts`) |
|
|
| Renommage | `PATCH /files/:id { name }`, `PATCH /folders/:id { name, description }` |
|
|
| Déplacement | `folderId`/`parentId` : refuse de placer un dossier dans son propre sous-arbre |
|
|
|
|
## Modèle de données
|
|
|
|
`backend/migrations/` — application stricte dans l'ordre, checksum SHA-256
|
|
par fichier, dérive refusée au démarrage.
|
|
|
|
| Fichier | Contenu |
|
|
| --- | --- |
|
|
| `000_schema_migrations.sql` | table de suivi (`version`, `applied_at`, `checksum`) |
|
|
| `001_initial_schema.sql` | `roles, users, password_reset_tokens, storage_locations, folders, files, folder_permissions, share_links, settings, audit_logs` |
|
|
| `002_reference_data.sql` | seeds : rôles, emplacement `principal`, réglages |
|
|
| `003_integrity_backstop.sql` | `CHECK` d'intégrité (audit, auto-parenté) |
|
|
| `004_cloud_requirements.sql` | `first_name`/`last_name`, `used_bytes`, `max_file_bytes`, `user_sessions`, `media_metadata`, `file_variants`, **suppression de `share_links`** |
|
|
| `005_storage_location_realign.sql` | réalignement des emplacements |
|
|
| `006_public_folder.sql` | `folders.access_type` / `is_system`, dossier `Public` |
|
|
|
|
Tables actives : `users, user_sessions, folders, folder_permissions, files,
|
|
media_metadata, file_variants, user_avatars, storage_locations, settings,
|
|
password_reset_tokens, email_change_requests, audit_logs`.
|
|
|
|
## Erreurs métier
|
|
|
|
`AppError` avec codes stables (`backend/src/lib/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 :
|
|
|
|
```json
|
|
{ "error": { "status": 404, "code": "NOT_FOUND", "message": "…", "requestId": "…" } }
|
|
```
|