2-6-pieces-jointes-a-la-soumission-fr17.md 19 KB

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)

    • Subtask 1.1 : Ajouter la dépendance : pnpm add @vercel/blob
    • 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) :

      BLOB_READ_WRITE_TOKEN: z.string().optional(),
      
  • [x] Task 2 : Prisma - modèle IdeaAttachment (AC: #3, #6)

    • Subtask 2.1 : Ajouter le modèle IdeaAttachment dans prisma/schema.prisma (voir section Dev Notes)
    • Subtask 2.2 : Ajouter la relation attachments IdeaAttachment[] sur le modèle Idea
    • 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)

    • 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()
    • Subtask 3.2 : Implémenter la logique de construction du path : {workspaceId}/attachments/{ideaId}/{sanitizedFilename}
    • 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)

    • Subtask 4.1 : Créer src/app/api/upload/attachments/route.ts - route POST Next.js App Router
    • Subtask 4.2 : Parser le multipart/form-data via req.formData() - extraire workspaceSlug (string), ideaId (string), et les fichiers (jusqu'à 3)
    • 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
    • Subtask 4.4 : Pour chaque fichier valide, appeler uploadAttachment() du service storage
    • Subtask 4.5 : Créer les enregistrements IdeaAttachment en base (transaction Prisma) avec workspaceId, ideaId, filename, contentType, size, url, blobPath
    • Subtask 4.6 : Retourner NextResponse.json({ success: true, attachments: [...] }, { status: 200 })
    • 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)

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

    • Subtask 6.1 : Créer src/app/api/upload/attachments/route.test.ts avec Vitest - mocker @vercel/blob, ~/server/db
    • Subtask 6.2 : Test : workspaceSlug ou ideaId manquant → 400
    • Subtask 6.3 : Test : workspace non trouvé → 404
    • Subtask 6.4 : Test : idea n'appartient pas au workspace → 404
    • Subtask 6.5 : Test : type de fichier non autorisé → 400
    • Subtask 6.6 : Test : fichier > 10 Mo → 400
    • Subtask 6.7 : Test : plus de 3 fichiers → 400
    • Subtask 6.8 : Test : upload valide → 200, IdeaAttachment créé avec bons champs
    • 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 :

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 :

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 :

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 :

// 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 :

attachments  IdeaAttachment[]

Parsing formData() dans le Route Handler :

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