# Story 2.6 : Pièces jointes à la soumission (FR17) Status: done ## Story En tant que Contributeur, je veux joindre des fichiers (PDF, DOCX, XLSX, PNG, JPG) à ma soumission, afin d'enrichir ma description avec des documents de contexte. ## Acceptance Criteria 1. **Given** je suis sur le formulaire de soumission `/submit/[workspaceSlug]` **When** j'affiche la section pièces jointes **Then** un composant de sélection de fichiers est affiché (bouton + zone de dépôt) **And** les types autorisés sont indiqués : PDF, DOCX, XLSX, PNG, JPG **And** les limites sont visibles : max 3 fichiers, max 10 Mo par fichier 2. **Given** je sélectionne un ou plusieurs fichiers **When** les fichiers passent la validation front-end (type, taille, nombre) **Then** les fichiers sélectionnés s'affichent avec leur nom et taille **And** je peux retirer individuellement un fichier sélectionné **And** un fichier de type non autorisé ou dépassant 10 Mo est rejeté avec un message explicite **And** un 4ème fichier est refusé avec le message "Maximum 3 pièces jointes par soumission" 3. **Given** j'ai sélectionné des fichiers valides et soumis le formulaire **When** la mutation tRPC `idea.submit` réussit (ideaId obtenu) **Then** les fichiers sont uploadés via `POST /api/upload/attachments` (multipart/form-data) **And** le handler valide que l'idée appartient bien au workspace via workspaceSlug + ideaId **And** chaque fichier est stocké sur Vercel Blob avec le path `{workspaceId}/attachments/{ideaId}/{filename}` **And** un enregistrement `IdeaAttachment` est créé en base pour chaque fichier **And** l'upload échoue silencieusement s'il y a une erreur (l'idée est déjà créée — ne pas bloquer) 4. **Given** les fichiers sont uploadés avec succès **When** le stockage est effectué **Then** les pièces jointes sont stockées chiffrées au repos (AES-256 via Vercel Blob — NFR15) **And** le stockage est dans un datacenter EU (Vercel Blob région EU — NFR13) **And** les URLs Vercel Blob sont enregistrées dans `IdeaAttachment.url` 5. **Given** les pièces jointes sont optionnelles **When** le contributeur soumet sans fichier **Then** l'idée est créée normalement sans pièce jointe **And** aucune erreur n'est générée côté upload 6. **Given** un `IdeaAttachment` est enregistré en base **When** Story 3.4 affichera la fiche détaillée d'une idée **Then** les pièces jointes seront accessibles via `idea.attachments` (relation Prisma) **And** les URLs Vercel Blob permettront le téléchargement direct ## Tasks / Subtasks - [x] Task 1 : Installer `@vercel/blob` et configurer l'environnement (AC: #4) - [x] Subtask 1.1 : Ajouter la dépendance : `pnpm add @vercel/blob` - [x] Subtask 1.2 : Ajouter `BLOB_READ_WRITE_TOKEN` dans `.env.example` (token Vercel Blob — configuré automatiquement en déployant sur Vercel via Dashboard → Storage → Blob) - [x] Subtask 1.3 : Ajouter `BLOB_READ_WRITE_TOKEN` dans `src/env.js` (server-side, optionnel en dev pour les tests) : ```ts BLOB_READ_WRITE_TOKEN: z.string().optional(), ``` - [x] Task 2 : Prisma — modèle `IdeaAttachment` (AC: #3, #6) - [x] Subtask 2.1 : Ajouter le modèle `IdeaAttachment` dans `prisma/schema.prisma` (voir section Dev Notes) - [x] Subtask 2.2 : Ajouter la relation `attachments IdeaAttachment[]` sur le modèle `Idea` - [x] Subtask 2.3 : Générer la migration : `prisma migrate dev --name add_idea_attachment` - [x] Task 3 : Service `src/server/services/storage.ts` (AC: #3, #4) - [x] Subtask 3.1 : Créer `src/server/services/storage.ts` avec la fonction `uploadAttachment(fileBuffer: Buffer, filename: string, contentType: string, blobPath: string): Promise<{ url: string; pathname: string }>` utilisant `@vercel/blob` `put()` - [x] Subtask 3.2 : Implémenter la logique de construction du path : `{workspaceId}/attachments/{ideaId}/{sanitizedFilename}` - [x] Subtask 3.3 : Gérer le mode développement (sans `BLOB_READ_WRITE_TOKEN`) — log le path sans upload réel ou utiliser le mock - [x] Task 4 : Route Handler `POST /api/upload/attachments` (AC: #3, #4, #5) - [x] Subtask 4.1 : Créer `src/app/api/upload/attachments/route.ts` — route `POST` Next.js App Router - [x] Subtask 4.2 : Parser le `multipart/form-data` via `req.formData()` — extraire `workspaceSlug` (string), `ideaId` (string), et les fichiers (jusqu'à 3) - [x] Subtask 4.3 : Validation serveur : - Vérifier que `workspaceSlug` et `ideaId` sont présents et non vides - Chercher le workspace par slug, puis vérifier que `idea.workspaceId === workspace.id` — si non → `404` - Vérifier max 3 fichiers — si > 3 → `400` - Vérifier type MIME de chaque fichier (`application/pdf`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document`, `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`, `image/png`, `image/jpeg`) — si non autorisé → `400` avec message explicite - Vérifier taille ≤ 10 Mo (10 × 1024 × 1024 = 10 485 760 bytes) — si dépassé → `400` - [x] Subtask 4.4 : Pour chaque fichier valide, appeler `uploadAttachment()` du service storage - [x] Subtask 4.5 : Créer les enregistrements `IdeaAttachment` en base (transaction Prisma) avec `workspaceId`, `ideaId`, `filename`, `contentType`, `size`, `url`, `blobPath` - [x] Subtask 4.6 : Retourner `NextResponse.json({ success: true, attachments: [...] }, { status: 200 })` - [x] Subtask 4.7 : Gérer les erreurs avec les bons codes HTTP (`NextResponse.json({ error: message }, { status: 400/404/500 })`) - [x] Task 5 : Composant `FileUploadInput` dans le formulaire de soumission (AC: #1, #2) - [x] Subtask 5.1 : Créer `src/components/form/FileUploadInput.tsx` — composant client avec : - Zone de dépôt (`drag & drop` optionnel) + bouton "Ajouter une pièce jointe" - Validation front-end : type (`accept` attribute), taille 10 Mo, max 3 fichiers - Liste des fichiers sélectionnés avec nom, taille, bouton de suppression (icône `X`) - Messages d'erreur inline (type non autorisé, taille dépassée, limite atteinte) - [x] Subtask 5.2 : Intégrer `FileUploadInput` dans `IdeaSubmissionForm.tsx` : - Ajouter état `selectedFiles: File[]` et setter - Afficher le composant sous le champ `frequency` (avant le bouton Submit) - Adapter la soumission : après mutation `idea.submit` réussie + si `selectedFiles.length > 0`, appeler `POST /api/upload/attachments` via `fetch` avec `FormData` - L'upload en erreur est logué en console mais ne bloque pas l'affichage de `SubmissionConfirmation` - [x] Subtask 5.3 : Afficher un indicateur de chargement pendant l'upload (optionnel mais recommandé — loader `Loader2` de lucide-react) - [x] Task 6 : Tests (AC: #2, #3, #4, #5) - [x] Subtask 6.1 : Créer `src/app/api/upload/attachments/route.test.ts` avec Vitest — mocker `@vercel/blob`, `~/server/db` - [x] Subtask 6.2 : Test : `workspaceSlug` ou `ideaId` manquant → 400 - [x] Subtask 6.3 : Test : workspace non trouvé → 404 - [x] Subtask 6.4 : Test : idea n'appartient pas au workspace → 404 - [x] Subtask 6.5 : Test : type de fichier non autorisé → 400 - [x] Subtask 6.6 : Test : fichier > 10 Mo → 400 - [x] Subtask 6.7 : Test : plus de 3 fichiers → 400 - [x] Subtask 6.8 : Test : upload valide → 200, `IdeaAttachment` créé avec bons champs - [x] Subtask 6.9 : Test : aucun fichier (soumission sans pièce jointe) → aucune erreur ## Dev Notes ### Architecture & décisions techniques **Choix du provider de stockage — Vercel Blob :** - Architecture dit "Vercel Blob ou S3-compatible EU" — on choisit **Vercel Blob** car : - Intégration native Vercel (même plateforme de déploiement) - AES-256 at rest inclus par défaut (NFR15) - Région EU configurable dans le dashboard Vercel (NFR13) - API simple : `@vercel/blob` package, fonction `put()` - `BLOB_READ_WRITE_TOKEN` : automatiquement injecté par Vercel en production lors de la liaison du Blob store dans le dashboard. En local, copier le token depuis Vercel → Settings → Storage. **Flow d'upload en deux temps (pattern client) :** 1. `api.idea.submit.mutateAsync(formData)` → obtenir `ideaId` 2. Si `selectedFiles.length > 0` : `fetch('/api/upload/attachments', { method: 'POST', body: formData })` avec `{ ideaId, workspaceSlug, files[] }` 3. L'upload est fire-and-forget côté UX (l'idée est déjà créée) — l'erreur d'upload est loguée mais ne rebascule pas vers une erreur de formulaire **Pourquoi pas de tRPC pour l'upload ?** - tRPC utilise JSON — pas adapté au `multipart/form-data` - Route Handler Next.js est le bon pattern pour les uploads de fichiers binaires (aligné avec l'architecture existante pour les webhooks) **Sécurité du Route Handler public :** - Pas d'auth requise (formulaire public comme pour `idea.submit`) - Validation : `workspace.slug` + `idea.workspaceId === workspace.id` → confirme que l'idée appartient au bon workspace - La relation workspaceSlug ↔ ideaId empêche l'upload cross-workspace - Les CUIDs Prisma sont aléatoires (non-devinables) — acceptable pour une soumission contributeur **`accept` HTML attribute pour le file input :** ``` accept=".pdf,.docx,.xlsx,.png,.jpg,.jpeg,application/pdf,application/vnd.openxmlformats-officedocument.wordprocessingml.document,application/vnd.openxmlformats-officedocument.spreadsheetml.sheet,image/png,image/jpeg" ``` **Types MIME acceptés côté serveur :** ```typescript const ALLOWED_MIME_TYPES = new Set([ 'application/pdf', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', // .docx 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', // .xlsx 'image/png', 'image/jpeg', ]); const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10 Mo const MAX_FILES = 3; ``` **Path Vercel Blob :** ```typescript const blobPath = `${workspaceId}/attachments/${ideaId}/${sanitizedFilename}`; // Sanitiser le filename : retirer les caractères spéciaux dangereux const sanitizedFilename = filename.replace(/[^a-zA-Z0-9._-]/g, '_'); ``` **Service `storage.ts` — usage de `@vercel/blob` :** ```typescript import { put } from '@vercel/blob'; export async function uploadAttachment( fileBuffer: Buffer, blobPath: string, contentType: string, ): Promise<{ url: string; pathname: string }> { const { url, pathname } = await put(blobPath, fileBuffer, { access: 'public', // URL publique pour affichage dans la fiche détaillée contentType, addRandomSuffix: false, // conserver le path exact pour la convention {workspaceId}/attachments/{ideaId}/{filename} }); return { url, pathname }; } ``` **Note sur `access: 'public'` :** - Les pièces jointes ont une URL publique mais non-devinable (CUID dans le path) - En post-MVP, envisager `access: 'private'` avec URLs signées pour plus de sécurité - Pour le MVP, `public` est acceptable (pas de données PII dans les fichiers attendus) **Schéma Prisma — `IdeaAttachment` :** ```prisma // Story 2.6 : Pièces jointes à la soumission (FR17) model IdeaAttachment { id String @id @default(cuid()) ideaId String idea Idea @relation(fields: [ideaId], references: [id], onDelete: Cascade) workspaceId String // dénormalisé pour isolation multi-tenant filename String // nom original sanitisé contentType String // MIME type size Int // taille en bytes url String // URL Vercel Blob blobPath String // path convention : {workspaceId}/attachments/{ideaId}/{filename} createdAt DateTime @default(now()) @@index([ideaId]) @@index([workspaceId]) } ``` Sur le modèle `Idea`, ajouter : ```prisma attachments IdeaAttachment[] ``` **Parsing `formData()` dans le Route Handler :** ```typescript export async function POST(req: NextRequest) { const formData = await req.formData(); const workspaceSlug = formData.get('workspaceSlug') as string | null; const ideaId = formData.get('ideaId') as string | null; const files = formData.getAll('files') as File[]; // ... } ``` **Mode développement sans Vercel Blob :** - Si `BLOB_READ_WRITE_TOKEN` est absent → le storage service logue le path et retourne une URL fictive (`/dev-blob/${blobPath}`) - Permet de développer et tester sans compte Vercel Blob - Les tests Vitest mockent `@vercel/blob` : `vi.mock('@vercel/blob', () => ({ put: vi.fn().mockResolvedValue({ url: 'https://blob.test/...', pathname: '...' }) }))` ### Structure des fichiers | Fichier | Action | |---------|--------| | `aimpact-hub/src/app/api/upload/attachments/route.ts` | Créer — Route Handler upload pièces jointes | | `aimpact-hub/src/app/api/upload/attachments/route.test.ts` | Créer — tests Vitest | | `aimpact-hub/src/server/services/storage.ts` | Créer — service Vercel Blob | | `aimpact-hub/src/components/form/FileUploadInput.tsx` | Créer — composant sélection fichiers | | `aimpact-hub/src/components/form/IdeaSubmissionForm.tsx` | Modifier — intégrer FileUploadInput + logique upload | | `aimpact-hub/prisma/schema.prisma` | Modifier — ajouter `IdeaAttachment` + relation sur `Idea` | | `aimpact-hub/prisma/migrations/YYYYMMDD_add_idea_attachment/migration.sql` | Créer — migration Prisma | | `aimpact-hub/.env.example` | Modifier — ajouter `BLOB_READ_WRITE_TOKEN` | | `aimpact-hub/src/env.js` | Modifier — ajouter `BLOB_READ_WRITE_TOKEN` (optionnel) | ### Conventions architecture à respecter - **Multi-tenant** : `workspaceId` dénormalisé sur `IdeaAttachment` — toujours filtrer par `workspaceId` dans les requêtes Prisma futures (Story 3.4) - **Route Handlers** : réponses via `NextResponse.json()` avec les bons codes HTTP - **Import PrismaClient** : `import { db } from "~/server/db"` (singleton), pas de `new PrismaClient()` - **Import Blob** : `import { put } from "@vercel/blob"` — ne pas instancier, la fonction utilise `BLOB_READ_WRITE_TOKEN` automatiquement - **ESM** : projet en `"type": "module"` — pas d'import CommonJS sans `.cjs` - **Nommage composant** : `FileUploadInput.tsx` (PascalCase), export nommé `FileUploadInput` - **Constantes** : `ALLOWED_MIME_TYPES`, `MAX_FILE_SIZE`, `MAX_FILES` en `UPPER_SNAKE_CASE` dans le Route Handler ou un fichier `src/lib/constants.ts` ### Apprentissages story précédente (2.5) — contexte pertinent - Pattern Route Handler avec `NextResponse.json()` déjà établi dans `src/app/api/webhooks/email/route.ts` - Pattern mock Vitest pour modules externes : `vi.mock('module', () => ({ fn: vi.fn() }))` - `import { db } from "~/server/db"` pour le PrismaClient dans les routes - `idea.router.submit` pattern de matching contributeur → réutiliser pour validation ownership dans le Route Handler upload (`idea.workspaceId === workspace.id`) ### Dépendances inter-stories - **Dépend de Story 2.2** : `IdeaSubmissionForm` existe et utilise `api.idea.submit.mutateAsync()` qui retourne `{ ideaId }` — cette story étend ce flow - **Sera consommée par Story 3.4** : la fiche détaillée lira `idea.attachments` (relation Prisma `IdeaAttachment[]`) pour afficher/télécharger les pièces jointes — s'assurer que la relation est correctement définie dans le schéma - **Sera consommée par Story 4.6** : la suppression de données contributeurs devra supprimer les `IdeaAttachment` (cascade déjà configuré via `onDelete: Cascade` sur `ideaId`) ### Configuration Vercel Blob (steps à faire hors code) 1. Dans le dashboard Vercel → Storage → Create new Blob Store → choisir la région EU (eu-central-1 ou eu-west) 2. Lier le Blob Store au projet → le `BLOB_READ_WRITE_TOKEN` est automatiquement injecté en déploiement 3. Copier le token depuis Vercel → variable d'environnement locale `BLOB_READ_WRITE_TOKEN` dans `.env.local` 4. Vérifier que la région est bien EU avant de créer le Blob Store (obligation RGPD — NFR13) ### NFR concernés - **NFR15** : pièces jointes chiffrées au repos (AES-256) — garanti par Vercel Blob (chiffrement standard) - **NFR13** : hébergement EU — Vercel Blob store créé en région EU (eu-central-1 Frankfurt ou eu-west) - **NFR14** : isolation workspace — `workspaceId` dans le path Blob ET dans `IdeaAttachment.workspaceId` ### Project Structure Notes - Le Route Handler `src/app/api/upload/attachments/route.ts` s'inscrit dans la structure `src/app/api/` définie dans `architecture.md` - Le service `src/server/services/storage.ts` est prévu dans l'arborescence cible : `src/server/services/storage.ts # Convention: {workspaceId}/attachments/{ideaId}/{filename}` - Le composant `FileUploadInput.tsx` va dans `src/components/form/` (feature-based, aligné avec `IdeaSubmissionForm.tsx`) ### References - [Source: epics.md#Story 2.6 — Pièces jointes à la soumission (FR17)] - [Source: epics.md#FR17 — types acceptés, taille max, nombre max] - [Source: epics.md#NFR15 — chiffrement AES-256 au repos] - [Source: epics.md#NFR13 — hébergement EU] - [Source: architecture.md#Infrastructure & Deployment — Stockage fichiers : Vercel Blob ou S3-compatible EU] - [Source: architecture.md#Architecture Boundaries — Stockage path : {workspaceId}/attachments/{ideaId}/{filename}] - [Source: architecture.md#Project Structure — src/server/services/storage.ts] - [Source: architecture.md#API & Communication Patterns — Route Handlers pour webhooks/uploads] - [Source: implementation-artifacts/2-5-soumission-didee-par-email-fr15.md — patterns Route Handler, mock Vitest, PrismaClient import] - [Source: src/components/form/IdeaSubmissionForm.tsx — formulaire existant à étendre] - [Source: src/server/api/routers/idea.ts — mutation submit retournant { ideaId }] - [Source: vercel.com/docs/storage/vercel-blob — @vercel/blob put() API] ## Dev Agent Record ### Agent Model Used {{agent_model_name_version}} ### Debug Log References ### Completion Notes List - ✅ Task 1 : @vercel/blob installé, BLOB_READ_WRITE_TOKEN dans .env.example et env.js (server) - ✅ Task 2 : Modèle IdeaAttachment + relation sur Idea, migration 20260228000000_add_idea_attachment - ✅ Task 3 : Service storage.ts avec uploadAttachment, buildBlobPath, fallback dev sans token - ✅ Task 4 : Route POST /api/upload/attachments avec validation complète (workspace, idea, type MIME, taille, nombre) - ✅ Task 5 : FileUploadInput (drag & drop, validation, liste) + intégration IdeaSubmissionForm (flow submit → upload) - ✅ Task 6 : 9 tests Vitest (400/404/400 type/taille/nombre, 200 valide, 200 vide) — mock formData pour contourner limitations jsdom ### File List - aimpact-hub/package.json (modifié — @vercel/blob) - aimpact-hub/.env.example (modifié — BLOB_READ_WRITE_TOKEN) - aimpact-hub/src/env.js (modifié — BLOB_READ_WRITE_TOKEN server) - aimpact-hub/prisma/schema.prisma (modifié — IdeaAttachment, relation Idea) - aimpact-hub/prisma/migrations/20260228000000_add_idea_attachment/migration.sql (créé) - aimpact-hub/src/server/services/storage.ts (créé) - aimpact-hub/src/app/api/upload/attachments/route.ts (créé) - aimpact-hub/src/app/api/upload/attachments/route.test.ts (créé) - aimpact-hub/src/components/form/FileUploadInput.tsx (créé) - aimpact-hub/src/components/form/IdeaSubmissionForm.tsx (modifié)