docs : add task documents upload design spec
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
171
docs/superpowers/specs/2026-03-15-task-documents-design.md
Normal file
171
docs/superpowers/specs/2026-03-15-task-documents-design.md
Normal file
@@ -0,0 +1,171 @@
|
||||
# Task Documents — Design Spec
|
||||
|
||||
## Overview
|
||||
|
||||
Ajout d'un système de documents attachés aux tickets (tasks). Les utilisateurs peuvent uploader des fichiers via drag & drop ou sélection, les visualiser (images, PDF) dans une modale plein écran, et les télécharger.
|
||||
|
||||
## Contraintes
|
||||
|
||||
- **Taille max par fichier** : 50 Mo
|
||||
- **Types acceptés** : tous types de fichiers
|
||||
- **Nombre par ticket** : illimité
|
||||
- **Stockage** : filesystem local (`var/uploads/documents/`)
|
||||
- **Permissions** : ROLE_ADMIN pour créer/supprimer, ROLE_USER pour lire
|
||||
|
||||
## Backend
|
||||
|
||||
### Entité `TaskDocument`
|
||||
|
||||
| Champ | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `id` | int (auto) | Clé primaire |
|
||||
| `task` | ManyToOne → Task | Ticket parent (CASCADE on delete) |
|
||||
| `originalName` | string (255) | Nom original du fichier uploadé |
|
||||
| `fileName` | string (255) | Nom unique sur disque (`{uuid}.{extension}`) |
|
||||
| `mimeType` | string (100) | Type MIME (ex: `image/png`, `application/pdf`) |
|
||||
| `size` | int | Taille en octets |
|
||||
| `createdAt` | DateTimeImmutable | Date d'upload |
|
||||
| `uploadedBy` | ManyToOne → User | Utilisateur ayant uploadé (SET NULL on delete) |
|
||||
|
||||
### Relation inverse sur Task
|
||||
|
||||
- `Task.documents` : OneToMany → TaskDocument
|
||||
- Sérialisé dans le groupe `task:read` pour charger les documents avec le ticket
|
||||
|
||||
### Stockage filesystem
|
||||
|
||||
- Répertoire : `var/uploads/documents/`
|
||||
- Nommage : `{uuid}.{extension}` — évite les collisions et les caractères spéciaux
|
||||
- Volume Docker dédié pour persister les uploads
|
||||
- Servir les fichiers via Nginx (`/uploads/{fileName}`) ou un endpoint Symfony dédié pour contrôle d'accès
|
||||
|
||||
### API Endpoints
|
||||
|
||||
| Méthode | Route | Description | Accès |
|
||||
|---------|-------|-------------|-------|
|
||||
| `POST` | `/api/task_documents` | Upload multipart/form-data | ROLE_ADMIN |
|
||||
| `GET` | `/api/task_documents?task=/api/tasks/{id}` | Liste documents d'un ticket | ROLE_USER |
|
||||
| `GET` | `/api/task_documents/{id}` | Métadonnées d'un document | ROLE_USER |
|
||||
| `DELETE` | `/api/task_documents/{id}` | Supprime document + fichier | ROLE_ADMIN |
|
||||
|
||||
### State Processor — POST (`TaskDocumentProcessor`)
|
||||
|
||||
1. Reçoit le fichier via multipart/form-data + IRI de la task
|
||||
2. Valide : fichier non vide, taille ≤ 50 Mo
|
||||
3. Génère un UUID v4, extrait l'extension du nom original
|
||||
4. Déplace le fichier uploadé dans `var/uploads/documents/{uuid}.{ext}`
|
||||
5. Crée et persiste l'entité `TaskDocument` avec toutes les métadonnées
|
||||
6. Set `uploadedBy` depuis le token JWT courant
|
||||
|
||||
### State Processor — DELETE
|
||||
|
||||
1. Récupère le `fileName` de l'entité
|
||||
2. Supprime le fichier du filesystem (`var/uploads/documents/{fileName}`)
|
||||
3. Supprime l'entité de la base de données
|
||||
|
||||
### Validation
|
||||
|
||||
- Contrainte sur `originalName` : NotBlank
|
||||
- Contrainte sur `task` : NotNull
|
||||
- Validation dans le Processor : taille fichier ≤ 50 Mo, fichier présent dans la requête
|
||||
- PHP `upload_max_filesize` et `post_max_size` à configurer ≥ 50 Mo
|
||||
|
||||
### Configuration PHP/Nginx
|
||||
|
||||
- `php.ini` : `upload_max_filesize = 50M`, `post_max_size = 55M`
|
||||
- Nginx : `client_max_body_size 55m;`
|
||||
|
||||
## Frontend
|
||||
|
||||
### Placement dans l'UI
|
||||
|
||||
La zone de documents est placée **sous la description** dans le `TaskModal`, visible en mode édition.
|
||||
|
||||
### Composants à créer
|
||||
|
||||
Tous dans `frontend/components/task/` :
|
||||
|
||||
#### `TaskDocumentUpload.vue`
|
||||
|
||||
- Zone drag & drop avec bordure pointillée
|
||||
- Texte : "Glisser des fichiers ici ou cliquer pour sélectionner"
|
||||
- Input file caché (`multiple`, `accept="*"`)
|
||||
- Événements : `dragover`, `dragleave`, `drop` pour le feedback visuel
|
||||
- Barre de progression par fichier pendant l'upload
|
||||
- Upload séquentiel ou parallèle (un POST multipart par fichier)
|
||||
- Émet un événement quand l'upload est terminé pour rafraîchir la liste
|
||||
|
||||
#### `TaskDocumentList.vue`
|
||||
|
||||
- Grille de cartes compactes pour chaque document
|
||||
- **Images** (`image/*`) : miniature 64x64 en `object-fit: cover`, chargée depuis l'URL du fichier
|
||||
- **Autres fichiers** : icône selon le type MIME :
|
||||
- PDF → icône PDF
|
||||
- Word/Excel → icônes Office
|
||||
- Archives → icône archive
|
||||
- Défaut → icône fichier générique
|
||||
- Informations affichées : nom original (tronqué si > ~30 chars), taille formatée (Ko/Mo)
|
||||
- Clic sur un document → ouvre `TaskDocumentPreview`
|
||||
- Bouton supprimer (visible uniquement pour ROLE_ADMIN, avec confirmation)
|
||||
|
||||
#### `TaskDocumentPreview.vue`
|
||||
|
||||
- Modale plein écran (overlay sombre semi-transparent)
|
||||
- Contenu selon le type :
|
||||
- **Images** (`image/*`) : `<img>` centré, taille adaptative
|
||||
- **PDF** (`application/pdf`) : `<iframe>` intégré
|
||||
- **Autres** : grande icône + nom du fichier + taille + bouton "Télécharger"
|
||||
- Navigation : flèches gauche/droite pour parcourir les documents du ticket
|
||||
- Fermeture : bouton X en haut à droite, clic sur l'overlay, touche Escape
|
||||
- Raccourcis clavier : flèches pour naviguer, Escape pour fermer
|
||||
|
||||
### Service API
|
||||
|
||||
`frontend/services/task-documents.ts` :
|
||||
|
||||
```typescript
|
||||
// Fonctions du service
|
||||
getByTask(taskId: number): Promise<TaskDocument[]>
|
||||
upload(taskId: number, file: File): Promise<TaskDocument> // POST multipart, un fichier à la fois
|
||||
remove(id: number): Promise<void>
|
||||
getFileUrl(fileName: string): string // Construit l'URL publique du fichier
|
||||
```
|
||||
|
||||
### DTO TypeScript
|
||||
|
||||
`frontend/services/dto/task-document.ts` :
|
||||
|
||||
```typescript
|
||||
type TaskDocument = {
|
||||
id: number
|
||||
task: string // IRI
|
||||
originalName: string
|
||||
fileName: string
|
||||
mimeType: string
|
||||
size: number
|
||||
createdAt: string
|
||||
uploadedBy: string // IRI
|
||||
}
|
||||
```
|
||||
|
||||
### Intégration dans TaskModal
|
||||
|
||||
- Import des 3 composants dans `TaskModal.vue`
|
||||
- Sous le champ description :
|
||||
1. `TaskDocumentUpload` (si mode édition, ROLE_ADMIN)
|
||||
2. `TaskDocumentList` (toujours visible, passe les documents du ticket)
|
||||
- `TaskDocumentPreview` monté conditionnellement (v-if sur document sélectionné)
|
||||
- Chargement des documents : via la relation `task.documents` déjà sérialisée, ou appel séparé au service
|
||||
|
||||
## Migration
|
||||
|
||||
- Nouvelle table `task_document` avec les colonnes correspondant à l'entité
|
||||
- Index sur `task_id` pour les requêtes filtrées
|
||||
- Clé étrangère `task_id` → `task.id` ON DELETE CASCADE
|
||||
- Clé étrangère `uploaded_by_id` → `user.id` ON DELETE SET NULL
|
||||
|
||||
## Docker
|
||||
|
||||
- Ajouter un volume dans `docker-compose.yml` pour `var/uploads/` afin de persister les fichiers
|
||||
- Vérifier la config PHP pour `upload_max_filesize` et `post_max_size`
|
||||
- Ajouter une location Nginx pour servir `/uploads/` si accès direct souhaité
|
||||
Reference in New Issue
Block a user