Lesstime/docs/superpowers/plans/2026-05-19-mail-integration-master-plan.md

Mail Integration — Master Plan

Master plan : ce document décrit le découpage en phases. Chaque phase aura son propre plan détaillé (rédigé par un subagent rédacteur) puis sera implémentée par un subagent codeur, en cycle.

Spec source : docs/superpowers/specs/2026-05-19-mail-integration-design.md

Goal : Ajouter à Lesstime un client mail intégré pour une boîte partagée OVH (IMAP/SMTP), avec lecture inbox/dossiers et création/lien tâche depuis un mail.

Stratégie : 7 phases séquentielles, dépendances claires, chaque phase = working software testable. Cycle par phase : rédacteur → codeur → review humaine → phase suivante.

---

Cartographie des phases

Phase 1 (Backend foundations)   ──┐
                                  ├─→ Phase 2 (IMAP provider + sync)  ──┐
                                  │                                     ├─→ Phase 3 (API backend)  ──┐
                                  │                                     │                            │
                                  └─→─────────────────────────────────────────────────────────────────┤
                                                                                                     │
Phase 4 (Frontend services + store)  ←──────────────────────────────────────────────────────────────┘
        │
        ├─→ Phase 5 (UI principale 3 colonnes)
        │
        ├─→ Phase 6 (Intégration tâches : modals, onglet TaskDrawer)
        │
        └─→ Phase 7 (Admin config + sidebar + polish)

Chaque phase produit du logiciel fonctionnel (testable, mergeable) sans casser les précédentes.

---

Phase 1 — Backend Foundations

Plan détaillé attendu : docs/superpowers/plans/2026-05-19-mail-phase1-foundations.md

Scope :

• Entité MailConfiguration (singleton, fields complets de la spec, encryptedPassword via TokenEncryptor)
• Entité MailFolder
• Entité MailMessage
• Entité TaskMailLink (avec unique constraint)
• Repositories : MailConfigurationRepository::findSingleton(), MailFolderRepository, MailMessageRepository, TaskMailLinkRepository
• Migration Doctrine unique créant les 4 tables (raw SQL)
• DTOs sous src/Mail/Dto/ : MailFolderDto, MailMessageHeaderDto, MailMessageDetailDto, MailAttachmentDto
• Interface App\Mail\MailProviderInterface (signatures uniquement, pas d'impl)
• Exception App\Mail\Exception\MailProviderException
• Tests unitaires repositories (au moins le pattern singleton)

Critère d'acceptation :

• make migration-migrate passe sans erreur
• php bin/console doctrine:schema:validate OK
• make test vert (au moins les tests créés)
• Fixture MailConfiguration désactivée (OVH defaults) ajoutée

Dépendances : aucune (point d'entrée).

---

Phase 2 — IMAP Provider + Sync

Plan détaillé attendu : docs/superpowers/plans/2026-05-19-mail-phase2-imap-sync.md

Scope :

• Ajout dépendance Composer webklex/php-imap (vérifier compat PHP 8.4)
• Implémentation App\Mail\ImapMailProvider implements MailProviderInterface
  • Lecture config via MailConfigurationRepository::findSingleton()
  • Déchiffrement password via TokenEncryptor
  • listFolders, listMessages, fetchMessage, markRead, markFlagged, moveMessage, fetchAttachment
  • Wrapping erreurs en MailProviderException
• App\Service\MailSyncService
  • syncAll(): MailSyncReport
  • syncFolder(string $folderPath): MailSyncReport
  • syncFolderStructure(): void
  • Algorithme exact de la spec (UID FETCH lastUid+1:*, resync flags N=200 derniers, detect suppressions avec garde 50%)
• DTO MailSyncReport (count créés / mis à jour / supprimés / errors)
• Symfony Lock (mail.sync, TTL 10 min)
• Commande console app:mail:sync (avec option --folder=...)
• Documentation cron OS + cible Makefile make mail-sync
• Tests : ImapMailProvider mocké via fixture serveur ou interface, MailSyncService avec provider mocké

Critère d'acceptation :

• php bin/console app:mail:sync --dry-run fonctionne contre une fake config
• Tests make test verts
• make mail-sync documentée dans Makefile

Dépendances : Phase 1.

---

Phase 3 — API Backend

Plan détaillé attendu : docs/superpowers/plans/2026-05-19-mail-phase3-api.md

Scope :

• API Platform ressources :
  • GET /api/mail/configuration (ROLE_ADMIN) — singleton provider
  • PATCH /api/mail/configuration (ROLE_ADMIN) — processor (jamais retourner password en clair, accepter nouveau password à chiffrer)
• Custom controllers (priority: 1) :
  • POST /api/mail/configuration/test (ROLE_ADMIN) — test connexion
  • GET /api/mail/folders (ROLE_USER, refus ROLE_CLIENT explicite) — arbre + unreadCount depuis BDD
  • GET /api/mail/folders/{path}/messages?page&limit — pagination cursor sentAt DESC, id DESC
  • GET /api/mail/messages/{id} — fetch live IMAP + cache Symfony mail_body_{messageId} TTL 5 min
  • POST /api/mail/messages/{id}/read (body { read: bool })
  • POST /api/mail/messages/{id}/flag
  • POST /api/mail/messages/{id}/create-task (body { projectId, taskGroupId?, priority? })
  • POST /api/mail/messages/{id}/link-task (body { taskId })
  • DELETE /api/mail/messages/{id}/link-task/{taskId}
  • GET /api/tasks/{id}/mails
  • GET /api/mail/attachments/{id} — stream, Content-Disposition: attachment, jamais inline
  • POST /api/mail/sync — async via Messenger
• Message + Handler Symfony Messenger MailSyncRequested
• Sécurité : #[IsGranted('IS_AUTHENTICATED_FULLY')] + check ROLE_USER && !ROLE_CLIENT explicite
• Tests fonctionnels endpoints (auth, format réponses, ROLE_CLIENT refusé)

Critère d'acceptation :

• Tous endpoints répondent corrects status/format
• Tests make test verts
• ROLE_CLIENT refusé sur 100% des endpoints mail
• Password jamais leak dans les réponses

Dépendances : Phase 1, Phase 2.

---

Phase 4 — Frontend Services + Store

Plan détaillé attendu : docs/superpowers/plans/2026-05-19-mail-phase4-frontend-services.md

Scope :

• Install npm dompurify + types
• frontend/services/dto/mail.ts : tous les types TS
• frontend/services/mail.ts : méthodes API (suivre pattern tasks.ts)
  • listFolders, listMessages, getMessage, markRead, markFlagged
  • createTaskFromMail, linkTask, unlinkTask, listMailsForTask
  • triggerSync
  • getConfiguration, updateConfiguration, testConfiguration
  • downloadAttachment (retourne Blob)
• Store Pinia frontend/stores/useMailStore.ts
  • State : folders, selectedFolderPath, messages[], selectedMessageId, selectedMessageDetail, loading, syncing, globalUnreadCount
  • Actions correspondantes
  • Polling pollUnreadCount() toutes les 30s (start/stop)
• Sanitization helper frontend/utils/sanitizeMailHtml.ts (DOMPurify avec config bloquante : script/iframe/object/embed/on*/javascript:, strip ou placeholder pour <img src="http(s)://..."> distants)

Critère d'acceptation :

• cd frontend && npx tsc --noEmit OK
• Test manuel d'un appel mail.listFolders() depuis devtools renvoie 401 si pas authentifié, 200 sinon

Dépendances : Phase 3 (les endpoints doivent exister).

---

Phase 5 — UI principale (page /mail)

Plan détaillé attendu : docs/superpowers/plans/2026-05-19-mail-phase5-ui-main.md

Scope :

• Page frontend/pages/mail.vue — layout 3 colonnes (dossiers / liste / lecteur), responsive
• Composants frontend/components/mail/ :
  • MailFolderTree.vue — arbre récursif avec badges unread, sélection
  • MailMessageList.vue — liste paginée (infinite scroll), indicateurs lu/étoilé/PJ, formatage relatif des dates
  • MailMessageViewer.vue — header (de/à/cc/date) + body sanitizé via DOMPurify + liste PJ téléchargeables + actions (Créer tâche / Lier / Marquer lu/non-lu / Étoiler)
  • MailRefreshButton.vue — bouton sync manuel, désactivé pendant syncing
• i18n clés mail.* dans frontend/i18n/locales/fr.json (et en.json si présent) : titres, vides, actions, erreurs
• Mapping noms dossiers système (INBOX, Sent, Drafts, Archive, Trash, Junk) → labels traduits
• Gestion query param ?messageId=X pour deep-link vers un mail (selection auto à l'ouverture)
• Refus visuel pour ROLE_CLIENT (le middleware backend bloque déjà, mais ajouter check côté router/middleware Nuxt)

Critère d'acceptation :

• Page accessible à /mail pour ROLE_USER/ROLE_ADMIN
• ROLE_CLIENT redirigé vers /portal
• Pas d'XSS via body mail (test manuel avec un mail contenant <script>alert(1)</script>)
• Pixels tracking distants remplacés par placeholder

Dépendances : Phase 4.

---

Phase 6 — Intégration Tâches

Plan détaillé attendu : docs/superpowers/plans/2026-05-19-mail-phase6-task-integration.md

Scope :

• frontend/components/mail/MailCreateTaskModal.vue — wrapper du TaskDrawer existant pré-rempli :
  • Titre = subject
  • Description = body plain text
  • Picker projet + groupe + priorité
  • À la création : appelle POST /api/mail/messages/{id}/create-task, ferme modal, redirige ou affiche succès
• frontend/components/mail/MailLinkTaskModal.vue — autocomplete sur tâches existantes (filter par projet, statut non-archivé)
• Onglet "Mails" sur TaskDrawer.vue :
  • Nouvelle section affichée à côté Documents / Time tracking / etc.
  • Liste MailMessage liés à la tâche (via GET /api/tasks/{id}/mails)
  • Item cliquable → router.push('/mail?messageId=' + id)
  • Bouton "Lier un mail" → ouvre un picker mail (TBD selon ergonomie : modal recherche ou redirige vers /mail)
• Tests manuels : créer tâche depuis mail, lier mail à tâche existante, voir mail depuis onglet tâche

Critère d'acceptation :

• Workflow complet : mail → "Créer tâche" → tâche créée et liée → visible dans onglet "Mails" du TaskDrawer
• Workflow : tâche existante → "Lier mail" → mail apparaît dans onglet

Dépendances : Phase 5.

---

Phase 7 — Admin Config + Sidebar + Polish

Plan détaillé attendu : docs/superpowers/plans/2026-05-19-mail-phase7-admin-polish.md

Scope :

• frontend/components/admin/AdminMailTab.vue (calqué sur AdminZimbraTab.vue) :
  • Form : protocol (imap pour MVP), imapHost/Port/Encryption, smtpHost/Port/Encryption, username, password (write-only, hasPassword: true côté GET), sentFolderPath, enabled toggle
  • Bouton "Tester la connexion" → POST /api/mail/configuration/test
  • Indicateur OVH defaults pré-remplis (ssl0.ovh.net:993/465)
• Ajout onglet AdminMailTab dans la page admin (selon pattern existant)
• Lien sidebar dans le layout default :
  • Icône material-symbols:mail-outline
  • Label traduit
  • Badge unread (count useMailStore.globalUnreadCount)
  • Visible uniquement pour ROLE_USER && !ROLE_CLIENT
• Lifecycle polling 30s : start dans app.vue ou layout default, stop au logout
• Documentation finale :
  • README ou docs/ : section "Mail integration" (cron OS, variables config, sécurité)
  • Makefile : make mail-sync documentée
• Vérification finale tracking pixels (relire sanitizeMailHtml.ts + tester)
• QA passe : workflow end-to-end depuis vraie boîte OVH (si dispo) ou IMAP test (greenmail/dovecot local)

Critère d'acceptation :

• Admin peut configurer la boîte, tester, activer
• Sidebar affiche badge unread temps réel (30s polling)
• Doc d'install à jour
• Aucun warning console front, aucun ERROR PHP dans make logs-dev

Dépendances : Phase 5 (sidebar utilise le store), Phase 3 (admin API).

---

Conventions communes à toutes les phases

• TDD : test rouge → code → test vert → commit
• Strict types PHP (declare(strict_types=1)) en tête de chaque fichier
• PHP CS Fixer : make php-cs-fixer-allow-risky avant chaque commit
• Commits : format <type>(mail) : <message> (espace avant :)
• Branche : feat/mail-integration (créée au début de Phase 1)
• Pas de jamais logger : bodies, password, attachments
• Review humaine entre chaque phase : le user valide avant lancement phase suivante

---

Cycle d'exécution

Pour chaque phase N :

1. Spawn subagent rédacteur (feature-dev:code-architect)

   • Input : ce master plan + spec + scope phase N
   • Output : docs/superpowers/plans/2026-05-19-mail-phaseN-*.md au format writing-plans (tasks bite-sized, fichiers exacts, code complet, commandes test)

2. Spawn subagent codeur (ruflo-core:coder)

   • Input : plan détaillé phase N
   • Output : code + tests + commits (TDD strict)

3. Review humaine : user valide ou demande corrections

4. Phase suivante uniquement si OK