office_translator/_bmad-output/planning-artifacts/prd.md

---
stepsCompleted: [step-01-init, step-02-discovery, step-02b-vision, step-02c-executive-summary, step-03-success, step-04-journeys, step-05-domain, step-06-innovation, step-07-project-type, step-08-scoping, step-09-functional, step-10-nonfunctional, step-11-polish, step-12-complete]
inputDocuments:
  - product-brief-office_translator-2026-02-18.md
workflowType: 'prd'
documentCounts:
  briefs: 1
  research: 0
  projectDocs: 0
classification:
  projectType: 'Application web SaaS + API REST'
  domain: 'Traduction de documents / Productivité B2B'
  complexity: 'Moyenne-Haute'
  projectContext: 'brownfield'
date: 2026-02-18
---

# Product Requirements Document - office_translator

**Author:** Sepehr
**Date:** 2026-02-18

## Executive Summary

Office Translator est une plateforme SaaS de traduction de documents Office (Excel, Word, PowerPoint) qui résout un problème critique pour les entreprises : le **temps perdu à remettre en page un document mal traduit** coûte plus cher que la traduction elle-même.

La vision est simple — l'utilisateur dépose un document, le récupère traduit et **visuellement identique** à l'original (couleurs, cellules fusionnées, graphiques, mises en page), sans aucune retouche nécessaire.

**Cible** : Professionnels et entreprises ayant besoin de traduire des documents Office complexes avec une qualité "prête à l'emploi".

### What Makes This Special

- **Sanitisation et reconstruction de document supérieure** : Notre traitement des fichiers Office dépasse les solutions existantes sur la préservation du format.
- **Fiabilité sur l'expérimentation** : Utilisation de moteurs éprouvés (LLMs stables : Ollama, OpenAI, compatibles) plutôt que des IA génératives instables.
- **Administration SaaS robuste** : Monitoring, abonnements, rate limiting — pensé pour un déploiement production et une monétisation sereine.

**Insight unique** : La valeur n'est pas dans la traduction elle-même, mais dans l'élimination du travail post-traduction.

## Project Classification

| Élément | Valeur |
|---------|--------|
| **Type** | Application web SaaS + API REST |
| **Domaine** | Traduction de documents / Productivité B2B |
| **Complexité** | Moyenne-Haute |
| **Contexte** | Brownfield (refonte de l'existant) |

## Success Criteria

### User Success

**Rapidité (avec distinction par mode)** :
- Mode Classique (Google/DeepL) : < 15 secondes pour un document standard (ex: Word 10 pages) — impression d'instantanéité
- Mode LLM (Ollama/OpenAI) : 1 à 3 minutes acceptables si barre de progression claire
- **Critère clé** : Feedback visuel (progression) immédiat dans tous les cas

**Qualité "prête à l'emploi"** :
- Format Fidelity : Le fichier traduit s'ouvre sans erreur dans Office
- Zéro casse visuelle : 0% de tableaux explosés, images déplacées, mises en page brisées
- Taux de retouche < 10% : l'utilisateur corrige une tournure, jamais ne reconstruit le document

### Business Success (MVP)

**Objectif : Capacité à Facturer (Billability)** :
- Le système de tracking (Admin) remonte 100% des usages réels
- Le système de quotas (Rate Limiting) bloque effectivement les abus
- **Définition du succès** : Si déployé demain, possibilité d'onboarder un client payant sans risque de consommation illimitée gratuite

### Technical Success

- **Fiabilité** : Gestion d'erreurs "graceful" — fichiers corrompus/illisibles → erreur 400 claire (JSON), jamais de crash serveur (500)
- **Hygiène** : 100% des fichiers temporaires supprimés après TTL (confidentialité + espace disque)
- **Performance** : 5 conversions simultanées sans ralentissement perceptible de l'interface Admin

### Measurable Outcomes

| Critère | Cible |
|---------|-------|
| Temps de traduction (mode classique) | < 15 sec (doc 10 pages) |
| Temps de traduction (mode LLM) | 1-3 min avec progression |
| Taux de retouche utilisateur | < 10% |
| Fichiers ouvrables sans erreur | 100% |
| Caisse visuelle (format) | 0% |
| Couverture tracking usage | 100% |
| Nettoyage fichiers temporaires | 100% |
| Conversions simultanées supportées | 5 |

## Product Scope

### MVP - Minimum Viable Product

- Refonte backend : code épuré, suppression code mort
- Traduction via LLMs (Ollama, OpenAI, compatibles) + Google/DeepL si API pas chère
- Préservation parfaite du format (Excel, Word, PowerPoint)
- Système de tracking usage (Admin)
- Rate limiting par utilisateur/abonnement
- Gestion d'erreurs robuste
- Nettoyage automatique des fichiers temporaires

### Growth Features (Post-MVP)

- Intégration API Google Traduction officielle (si coût acceptable)
- Dashboard analytics avancé
- Historique de traductions pour utilisateurs
- Webhooks / notifications
- Support de formats supplémentaires (PDF ?)

### Vision (Future)

- Mode "Team" avec collaboration
- Intégrations (Zapier, Make, etc.)
- API publique documentée pour développeurs tiers
- Marketplace de templates/glossaires

## User Journeys

### Journey 1 : Marie, Utilisatrice Web Gratuite

**Situation** : Marie est consultante marketing freelance. Elle reçoit un rapport PowerPoint en anglais d'un client et doit le présenter en français à une réunion dans 2 heures.

**Parcours** :
1. Marie découvre Office Translator via une recherche ou bouche-à-oreille
2. Elle arrive sur la page d'accueil, comprend immédiatement le propos (traduction de documents, format préservé)
3. Elle glisse-dépose son fichier PPT (15 slides)
4. Elle sélectionne "Anglais → Français" et choisit le mode "Classique" (gratuit, rapide)
5. Une barre de progression s'affiche immédiatement : "Traitement en cours... 3/15 slides"
6. Après 12 secondes, le fichier est prêt → téléchargement automatique
7. Elle ouvre le fichier : le design est intact, les graphiques sont en place
8. Elle corrige 2-3 tournures de phrases, sauvegarde et envoie à la réunion

**Résultat** : Mission accomplie en moins de 5 minutes. Elle bookmark le site.

**Exigences révélées** : Landing page claire, upload drag & drop, feedback visuel temps réel, téléchargement fluide, qualité de format.

### Journey 2 : Thomas, Utilisateur API Pro

**Situation** : Thomas est lead dev dans un cabinet d'audit. Son équipe traite 200 rapports financiers Excel par mois pour des clients internationaux. Il automatise avec n8n.

**Parcours** :
1. Thomas s'abonne au plan Pro (gestion manuelle par Admin pour le MVP)
2. Il accède à son Dashboard → génère une **Clé API stable**
3. Il lit la documentation API : endpoints, auth, rate limits, codes d'erreur JSON
4. Il configure son workflow n8n avec la clé API
5. Premier test : fichier Excel complexe envoyé → réponse structurée (fichier + métadonnées)
6. Il teste un cas d'erreur : quota dépassé → API renvoie `{"error": "quota_exceeded", "message": "Limite mensuelle atteinte"}`
7. Il active les **fonctionnalités Pro** : Glossaires personnalisés + Prompts système pour la terminologie financière
8. Déploiement production → 200 fichiers/mois traités, erreurs gérées automatiquement par ses scripts

**Résultat** : Gain de 15h/mois. Sa raison de payer : personnalisation terminologique + volume.

**Exigences révélées** : Génération Clés API dans Dashboard, erreurs JSON structurées, documentation, Glossaires/Prompts système (Pro).

### Journey 3 : L'Admin (Dashboard)

**Situation** : C'est vous, lundi matin. Vous vérifiez le système et gérez les premiers clients.

**Parcours** :
1. Connexion au Dashboard Admin (auth sécurisée)
2. Vue d'ensemble : santé système, espace disque, mémoire, statut providers
3. **Gestion des utilisateurs** : vous voyez une nouvelle demande de Thomas
4. Vous passez Thomas de "Free" à "Pro" manuellement (dropdown → "Pro")
5. Sa Clé API est automatiquement générée/activée dans son Dashboard utilisateur
6. Vous vérifiez les stats : 847 traductions ce weekend, 3 erreurs gérées proprement (400)
7. Vérification du rate limiting : utilisateur X bloqué après quota gratuit
8. Purge des fichiers temporaires orphelins → système propre

**Résultat** : Client Pro onboardé manuellement, système stable, prêt pour la facturation.

**Exigences révélées** : Dashboard métriques, **changement de tier manuel** (Free→Pro), **génération/révocation clés API**, statut providers, logs, purge fichiers.

### Journey 4 : Cas d'Erreur - Fichier Non Supporté

**Situation** : Un utilisateur essaie de traduire un PDF scanné.

**Parcours** :
1. Upload du fichier PDF
2. Le système détecte le format non supporté
3. API renvoie : `{"error": "invalid_format", "message": "Format PDF non supporté. Formats acceptés : .xlsx, .docx, .pptx"}`
4. L'utilisateur comprend et convertit son fichier
5. Deuxième tentative : succès

**Résultat** : Pas de frustration, message explicite, pas de crash serveur.

**Exigences révélées** : Validation format, erreurs JSON utilisateur-friendly, gestion graceful.

### Journey Requirements Summary

| Parcours | Capacités Révélées |
|----------|-------------------|
| Utilisateur Web Gratuit | Landing page, upload drag & drop, progression temps réel, téléchargement |
| Utilisateur API Pro | **Génération Clés API**, documentation, erreurs JSON structurées, **Glossaires/Prompts (Pro)** |
| Admin Dashboard | Métriques système, **changement de tier manuel**, **gestion clés API**, statut providers, logs, purge |
| Gestion d'erreurs | Validation format, erreurs JSON claires, graceful degradation |

## Domain-Specific Requirements

### Confidentialité des données (Data Confidentiality)

- **Politique "Zéro Rétention"** : Système "Passe-plat" (Pass-through)
- **Stockage** : Strictement temporaire (/tmp), suppression automatique (Hard Delete) après TTL de 60 minutes ou immédiatement après téléchargement réussi
- **Logs** : Aucun contenu de document loggué. Seules métadonnées conservées (nom, taille, hash, timestamp)

### RGPD / Conformité (GDPR)

- **Cible** : Clients européens visés
- **Stratégie** : Conformité par minimisation des données — pas de stockage durable = "Droit à l'oubli" respecté par défaut
- **Hébergement** : Préférence serveur UE pour le MVP

### Propriété Intellectuelle (IP)

- **Clause** : L'utilisateur reste seul propriétaire des documents
- **"No Training Policy"** : Garantie que les documents ne sont jamais utilisés pour entraîner les modèles (différenciateur clé B2B)

### Sécurité API (API Security)

| Vecteur | Mécanisme |
|---------|-----------|
| Web/Admin | JWT (Access + Refresh Tokens) |
| API Automation | Clés API statiques générées par Admin |
| Contrôle | Révocation immédiate via Dashboard (pas de rotation auto MVP) |

### Audit / Traçabilité

- **Logs structurés** : Qui, Quand, Quoi, Volume, Status Code
- **Usage** : Debugging + facturation/quota (pages traduites)
- **Scope** : Pas d'audit légal complexe pour le MVP

## SaaS B2B + API Backend - Exigences Spécifiques

### Architecture Multi-Tenant

| Aspect | Décision |
|--------|----------|
| Isolation | Par utilisateur (quotas, clés API séparées) |
| Stockage | Local éphémère (/tmp) - pas de S3 pour le MVP |
| Données persistantes | Utilisateurs, clés API, logs métadonnées uniquement |

### Modèle de Permissions (RBAC)

| Rôle | Accès |
|------|-------|
| **Free** | Traduction web, mode classique uniquement, quota limité |
| **Pro** | Traduction web + API, tous modes (LLM inclus), glossaires/prompts, quota élevé |
| **Admin** | Dashboard complet, gestion utilisateurs, révocation clés, métriques système |

### Tiers d'Abonnement

| Tier | Quota | Providers | Fonctionnalités |
|------|-------|-----------|-----------------|
| Free | 5 fichiers/jour | Google/DeepL | Traduction web uniquement |
| Pro | Illimité (fair use) | Tous (LLM inclus) | API, Glossaires, Prompts système, Webhooks |

### Spécifications API

**Versioning :**
- Tous les endpoints préfixés par `/api/v1/`
- Obligatoire pour préserver les intégrations clients

**Endpoints principaux :**
| Endpoint | Méthode | Description |
|----------|---------|-------------|
| `/api/v1/translate` | POST | Traduire un document |
| `/api/v1/languages` | GET | Langues supportées |
| `/api/v1/health` | GET | Santé du service |
| `/api/v1/download/{id}` | GET | Télécharger fichier traduit |

**Authentification :**
| Contexte | Méthode |
|----------|---------|
| Web/Admin | JWT (Access + Refresh Tokens) |
| API Automation | API Key statique (header `X-API-Key`) |

**Gestion d'erreurs :**
- Format JSON structuré : `{"error": "code", "message": "description"}`
- Codes HTTP appropriés (400 client, 500 server - à éviter)

**Documentation :**
- OpenAPI (Swagger/Redoc) interactif
- Pas de SDK client pour le MVP

### Intégrations & Webhooks

| Intégration | Statut MVP |
|-------------|------------|
| Stockage S3 | Non (local éphémère) |
| Email transactionnel | Non (gestion manuelle Admin) |
| **Webhooks** | **Oui** - Fire & Forget (POST URL client après traduction) |

### Exigences de Conformité

| Exigence | Implémentation |
|----------|----------------|
| RGPD | Minimisation données (zero retention) |
| Confidentialité | TTL 60 min, hard delete automatique |
| Hébergement | Préférence UE |
| "No Training Policy" | Clause contractuelle |

## Project Scoping & Phased Development

### MVP Strategy & Philosophy

**Approche MVP** : Revenue-Ready Hybride
- Module paiement existant à refactorer (Clean Architecture)
- Gestion manuelle Admin en backup (sécurité support client)
- Objectif : déployer avec capacité de facturer immédiatement

**Parcours prioritaire** : Thomas (API Pro) — API first, revenus first

**Ressources** : Solo Developer → Architecture monolithique modulaire

### MVP Feature Set (Phase 1)

**Parcours utilisateurs supportés :**
| Parcours | Priorité MVP |
|----------|--------------|
| Thomas (API Pro) | **Critique** — Priorité absolue |
| Admin Dashboard | **Critique** — Gestion clients + monitoring |
| Marie (Web Gratuit) | Important — Acquisition utilisateur |
| Gestion d'erreurs | **Critique** — Expérience API |

**Must-Have Capabilities :**

| Capacité | Priorité | Notes |
|----------|----------|-------|
| Traduction Excel/Word/PPT | **Critique** | Risque technique n°1 |
| Préservation format | **Critique** | Cœur de valeur |
| API /v1/ + documentation OpenAPI | **Critique** | Parcours Thomas |
| Clés API (génération/révocation) | **Critique** | Parcours Thomas |
| Erreurs JSON structurées | **Critique** | Parcours Thomas |
| Webhooks (Fire & Forget) | **Critique** | Automation |
| Dashboard Admin | **Critique** | Monitoring + gestion |
| Changement tier manuel (Free→Pro) | **Critique** | Backup paiement |
| Module paiement refactoré | Important | Revenue-ready |
| Rate limiting | **Critique** | Protection abus |
| Nettoyage fichiers (TTL 60min) | **Critique** | Confidentialité |
| Auth JWT (Admin) | **Critique** | Sécurité |
| Upload Web drag & drop | Important | Parcours Marie |
| Barre progression | Important | UX |

**Peut attendre Post-MVP :**
- Historique traductions utilisateur
- Dashboard analytics avancé
- Intégrations Zapier/Make
- SDK client

### Post-MVP Features

**Phase 2 (Growth) :**
- Glossaires personnalisés (Pro)
- Prompts système personnalisables
- Historique de traductions
- Dashboard analytics avancé
- Support PDF (si demandé)

**Phase 3 (Expansion) :**
- Mode Team / collaboration
- Intégrations Zapier, Make
- API publique pour développeurs tiers
- SDK client (Python, JS)
- Marketplace templates/glossaires

### Risk Mitigation Strategy

| Risque | Type | Mitigation |
|--------|------|------------|
| **Préservation format Office** | Technique | Tests automatisés sur fichiers complexes, validation visuelle, corpus de test |
| Intégration multi-providers LLM | Technique | Abstraction provider, fallback entre providers |
| Bug paiement | Business | Gestion manuelle Admin en backup |
| Solo developer | Ressource | Monolithe modulaire, scope strict, dette technique zero |
| Acquisition utilisateurs | Marché | Parcours Marie fonctionnel, bouche-à-oreille |

### Architecture Decision

**Monolithe Modulaire** (pas de micro-services) :
- `modules/translation/` — cœur métier
- `modules/auth/` — JWT + API Keys
- `modules/payment/` — paiement refactoré
- `modules/admin/` — dashboard
- `modules/webhooks/` — notifications

## Functional Requirements

### Document Translation

- FR1: Users can upload Excel files (.xlsx) for translation
- FR2: Users can upload Word files (.docx) for translation
- FR3: Users can upload PowerPoint files (.pptx) for translation
- FR4: Users can select source and target languages for translation
- FR5: Users can choose translation mode (Classic or LLM) based on their subscription tier
- FR6: System can translate documents using Google/DeepL providers (Classic mode)
- FR7: System can translate documents using LLM providers (Ollama, OpenAI, OpenAI-compatible)
- FR8: System can process multiple translation requests concurrently

### Format Preservation

- FR9: System preserves document layout after translation (colors, fonts, spacing)
- FR10: System preserves merged cells in Excel files
- FR11: System preserves tables in Word and PowerPoint files
- FR12: System preserves images and their positions in all document types
- FR13: System preserves charts and their data links in Excel files
- FR14: System preserves formulas in Excel files (translating only text content)
- FR15: System preserves slide layouts and animations in PowerPoint files
- FR16: Users can open translated files in Microsoft Office without errors

### User Management & Authentication

- FR17: Users can create an account with email and password
- FR18: Users can log in to the web application via JWT authentication
- FR19: Users can log out of the web application
- FR20: System assigns users to subscription tiers (Free or Pro)
- FR21: Admin can change user tier from Free to Pro manually
- FR22: Admin can change user tier from Pro to Free manually

### Subscription & Billing

- FR23: System enforces daily file quotas based on user tier
- FR24: Free users are limited to 5 files per day
- FR25: Pro users have unlimited translations (fair use policy)
- FR26: Pro users can access LLM translation modes
- FR27: System tracks translation usage per user for billing purposes
- FR28: Payment module updates user tier upon successful payment

### API & Integration

- FR29: Pro users can generate API keys from their dashboard
- FR30: Pro users can revoke their own API keys
- FR31: Admin can revoke any user's API key
- FR32: System authenticates API requests via X-API-Key header
- FR33: System provides REST API endpoints under /api/v1/ prefix
- FR34: System returns errors in structured JSON format with error code and message
- FR35: System provides interactive API documentation (OpenAPI/Swagger)

### Webhooks

- FR36: Users can specify webhook URL per translation request (passed as parameter)
- FR37: System sends POST request to webhook URL when translation completes
- FR38: System includes translation metadata in webhook payload (file ID, status, timestamp)
- FR65: Webhook URL is passed as parameter in the API request body
- FR66: System sends webhook notification only if URL is provided in request

### Admin Dashboard

- FR39: Admin can log in to admin dashboard with secure authentication
- FR40: Admin can view system health metrics (disk space, memory usage)
- FR41: Admin can view provider status (Google, DeepL, Ollama, OpenAI connectivity)
- FR42: Admin can view translation statistics (count, errors, usage)
- FR43: Admin can view rate limiting status per user
- FR44: Admin can trigger manual cleanup of orphaned temporary files
- FR45: Admin can view error logs with structured information

### Web User Interface

- FR46: Users can upload files via drag-and-drop interface
- FR47: Users see real-time progress indicator during translation
- FR48: Users can download translated files after completion
- FR49: Users receive clear error messages for unsupported file formats

### File Management

- FR50: System validates file format before processing (xlsx, docx, pptx only)
- FR51: System stores uploaded files in temporary location
- FR52: System automatically deletes files after TTL (60 minutes)
- FR53: System deletes files immediately after successful download
- FR54: System logs file metadata (name, size, hash, timestamp) without content

### Error Handling

- FR55: System returns HTTP 400 errors for client-side issues (invalid format, quota exceeded)
- FR56: System never returns HTTP 500 errors (graceful degradation required)
- FR57: System provides actionable error messages in user's language

### Glossaries & Custom Prompts (Pro Feature)

- FR58: Pro users can include a custom glossary in translation requests
- FR59: Pro users can include custom system prompt/instructions in translation requests
- FR60: System applies glossary terms during LLM translation
- FR61: System applies custom prompts to guide LLM translation context

### URL Ingestion (Automation)

- FR62: API can accept a file URL as input (in addition to binary upload)
- FR63: System downloads files from public URLs (S3, Drive, etc.) before processing
- FR64: System validates downloaded files against supported formats

## Non-Functional Requirements

### Performance

| ID | Exigence | Critère |
|----|----------|---------|
| NFR1 | Temps de réponse mode classique | < 15 secondes pour document 10 pages |
| NFR2 | Temps de réponse mode LLM | 1-3 minutes maximum avec progression visible |
| NFR3 | Feedback utilisateur | Progression affichée en temps réel (< 500ms latence) |
| NFR4 | Concurrence | 5 conversions simultanées sans dégradation perceptible |
| NFR5 | Interface Admin | Réponse < 2 secondes même pendant conversions |

### Security

| ID | Exigence | Critère |
|----|----------|---------|
| NFR6 | Authentification Web | JWT avec Access Token (15min) + Refresh Token (7 jours) |
| NFR7 | Authentification API | Clés API (256-bit minimum) via header X-API-Key |
| NFR8 | Chiffrement transit | HTTPS obligatoire (TLS 1.2+) |
| NFR9 | Chiffrement repos | Non requis (pas de stockage persistant de documents) |
| NFR10 | Secrets | Variables d'environnement, jamais dans le code |
| NFR11 | Données sensibles | Aucun contenu de document dans les logs |

### Reliability

| ID | Exigence | Critère |
|----|----------|---------|
| NFR12 | Gestion d'erreurs | 0% d'erreurs HTTP 500 - toujours retour 4xx avec message JSON |
| NFR13 | Disponibilité providers | Fallback automatique entre providers si l'un échoue |
| NFR14 | Récupération fichiers | Fichiers temporaires nettoyés même après crash (TTL 60min) |

### Data Retention & Privacy

| ID | Exigence | Critère |
|----|----------|---------|
| NFR15 | Rétention fichiers | 60 minutes maximum, suppression après téléchargement |
| NFR16 | Logs | Métadonnées uniquement (nom, taille, hash, timestamp) |
| NFR17 | RGPD | Droit à l'oubli respecté par design (zero retention) |

### API Quality

| ID | Exigence | Critère |
|----|----------|---------|
| NFR18 | Documentation | OpenAPI 3.0 interactif (Swagger UI ou Redoc) |
| NFR19 | Erreurs API | Format JSON structuré : `{error, message, details?}` |
| NFR20 | Rate limiting | Par utilisateur, réponse 429 avec `Retry-After` header |
| NFR21 | Versioning | Préfixe /api/v1/ obligatoire |

---

## Document Summary

**Office Translator PRD — Version MVP**

| Métrique | Valeur |
|----------|--------|
| Exigences Fonctionnelles | 66 FRs |
| Exigences Non-Fonctionnelles | 21 NFRs |
| Parcours Utilisateurs | 4 |
| Tiers d'abonnement | 2 (Free, Pro) |
| Formats supportés | 3 (xlsx, docx, pptx) |

**Traceabilité :**
- Vision → Success Criteria → User Journeys → Functional Requirements → NFRs
- Toutes les FRs sont traçables vers un besoin utilisateur ou business
- Les NFRs définissent les critères de qualité mesurables

**Prochaines étapes BMAD :**
1. Architecture Technique (à partir des FRs/NFRs)
2. Epics & User Stories (à partir des FRs)
3. Développement itératif

---

*Document généré via workflow BMAD create-prd — 2026-02-18*