Matthieu
439 lines
15 KiB
Markdown
439 lines
15 KiB
Markdown
# Task Notifications Implementation Plan
|
|
|
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
|
|
**Goal:** Recréer un producteur de notifications en notifiant le nouvel assigné d'une tâche et les collaborateurs ajoutés, via un listener Doctrine couvrant tous les chemins d'écriture.
|
|
|
|
**Architecture:** Un unique `TaskNotificationListener` Doctrine écoute `onFlush` (collecte les destinataires à partir des changesets d'assignation et des ajouts de collaborateurs) et `postFlush` (persiste les `Notification` puis re-flush). L'acteur courant est lu via `Security`; on ne se notifie jamais soi-même, et sans acteur authentifié aucune notification n'est créée.
|
|
|
|
**Tech Stack:** PHP 8.4, Symfony 8, Doctrine ORM 3.6, PHPUnit (KernelTestCase).
|
|
|
|
---
|
|
|
|
## Référence spec
|
|
|
|
`docs/superpowers/specs/2026-06-15-task-notifications-design.md`
|
|
|
|
## File Structure
|
|
|
|
- **Create** `src/EventListener/TaskNotificationListener.php` — listener Doctrine, seul producteur de notifications de tâche. Responsabilité unique : traduire les changements d'assignation/collaboration en entités `Notification`.
|
|
- **Create** `tests/Functional/EventListener/TaskNotificationListenerTest.php` — tests fonctionnels (KernelTestCase) couvrant tous les cas de la spec.
|
|
- Aucune migration, aucun changement d'entité, aucun changement frontend.
|
|
|
|
### Détails de plateforme vérifiés
|
|
|
|
- Doctrine ORM 3.6 : le mapping d'une `PersistentCollection` s'obtient via `$collection->getMapping()->fieldName` (objet `AssociationMapping`, **pas** un tableau).
|
|
- `Task` non-nullables : `number` (int), `title` (string), `project` (relation). `assignee` est nullable, `collaborators` est une `Collection`.
|
|
- En test, on réutilise un `Project` existant (chargé par les fixtures) et on crée des `User` frais (isolation par `uniqid`).
|
|
- L'acteur courant : `Security::getUser()` lit le token storage. En test, on pose un token via `TokenStorageInterface::setToken()`.
|
|
|
|
---
|
|
|
|
## Task 1: Listener + notifications d'assignation
|
|
|
|
**Files:**
|
|
- Create: `src/EventListener/TaskNotificationListener.php`
|
|
- Test: `tests/Functional/EventListener/TaskNotificationListenerTest.php`
|
|
|
|
- [ ] **Step 1: Écrire les tests d'assignation (échouent)**
|
|
|
|
Créer `tests/Functional/EventListener/TaskNotificationListenerTest.php` :
|
|
|
|
```php
|
|
<?php
|
|
|
|
declare(strict_types=1);
|
|
|
|
namespace App\Tests\Functional\EventListener;
|
|
|
|
use App\Entity\Notification;
|
|
use App\Entity\Project;
|
|
use App\Entity\Task;
|
|
use App\Entity\User;
|
|
use App\Repository\NotificationRepository;
|
|
use Doctrine\ORM\EntityManagerInterface;
|
|
use Symfony\Bundle\FrameworkBundle\Test\KernelTestCase;
|
|
use Symfony\Component\Security\Core\Authentication\Token\Storage\TokenStorageInterface;
|
|
use Symfony\Component\Security\Core\Authentication\Token\UsernamePasswordToken;
|
|
|
|
/**
|
|
* @internal
|
|
*/
|
|
class TaskNotificationListenerTest extends KernelTestCase
|
|
{
|
|
private EntityManagerInterface $em;
|
|
private NotificationRepository $notifications;
|
|
private TokenStorageInterface $tokenStorage;
|
|
private Project $project;
|
|
private User $actor;
|
|
private User $alice;
|
|
private User $bob;
|
|
|
|
protected function setUp(): void
|
|
{
|
|
self::bootKernel();
|
|
$c = self::getContainer();
|
|
$this->em = $c->get(EntityManagerInterface::class);
|
|
$this->notifications = $c->get(NotificationRepository::class);
|
|
$this->tokenStorage = $c->get(TokenStorageInterface::class);
|
|
|
|
$project = $this->em->getRepository(Project::class)->findOneBy([]);
|
|
self::assertNotNull($project, 'Les fixtures doivent fournir au moins un projet.');
|
|
$this->project = $project;
|
|
|
|
$this->actor = $this->makeUser('actor');
|
|
$this->alice = $this->makeUser('alice');
|
|
$this->bob = $this->makeUser('bob');
|
|
$this->em->flush();
|
|
}
|
|
|
|
public function testAssignmentToOtherUserCreatesNotification(): void
|
|
{
|
|
$this->loginAs($this->actor);
|
|
|
|
$task = $this->makeTask();
|
|
$task->setAssignee($this->alice);
|
|
$this->em->persist($task);
|
|
$this->em->flush();
|
|
|
|
$rows = $this->notifications->findBy(['user' => $this->alice]);
|
|
self::assertCount(1, $rows);
|
|
self::assertSame('task_assigned', $rows[0]->getType());
|
|
self::assertStringContainsString((string) $task->getTitle(), (string) $rows[0]->getMessage());
|
|
}
|
|
|
|
public function testSelfAssignmentCreatesNoNotification(): void
|
|
{
|
|
$this->loginAs($this->actor);
|
|
|
|
$task = $this->makeTask();
|
|
$task->setAssignee($this->actor);
|
|
$this->em->persist($task);
|
|
$this->em->flush();
|
|
|
|
self::assertCount(0, $this->notifications->findBy(['user' => $this->actor]));
|
|
}
|
|
|
|
public function testReassignmentNotifiesOnlyNewAssignee(): void
|
|
{
|
|
$this->loginAs($this->actor);
|
|
|
|
$task = $this->makeTask();
|
|
$task->setAssignee($this->alice);
|
|
$this->em->persist($task);
|
|
$this->em->flush();
|
|
|
|
$task->setAssignee($this->bob);
|
|
$this->em->flush();
|
|
|
|
self::assertCount(1, $this->notifications->findBy(['user' => $this->alice]));
|
|
self::assertCount(1, $this->notifications->findBy(['user' => $this->bob]));
|
|
}
|
|
|
|
public function testAssigneeSetToNullCreatesNoNotificationForNull(): void
|
|
{
|
|
$this->loginAs($this->actor);
|
|
|
|
$task = $this->makeTask();
|
|
$task->setAssignee($this->alice);
|
|
$this->em->persist($task);
|
|
$this->em->flush();
|
|
|
|
$task->setAssignee(null);
|
|
$this->em->flush();
|
|
|
|
// alice a reçu la 1re notif, mais le passage à null n'en crée aucune autre.
|
|
self::assertCount(1, $this->notifications->findBy(['user' => $this->alice]));
|
|
}
|
|
|
|
public function testNoActorCreatesNoNotification(): void
|
|
{
|
|
$this->tokenStorage->setToken(null);
|
|
|
|
$task = $this->makeTask();
|
|
$task->setAssignee($this->alice);
|
|
$this->em->persist($task);
|
|
$this->em->flush();
|
|
|
|
self::assertCount(0, $this->notifications->findBy(['user' => $this->alice]));
|
|
}
|
|
|
|
private function makeUser(string $prefix): User
|
|
{
|
|
$user = new User();
|
|
$user->setUsername($prefix.'-'.uniqid());
|
|
$user->setPassword('x');
|
|
$user->setRoles(['ROLE_USER']);
|
|
$this->em->persist($user);
|
|
|
|
return $user;
|
|
}
|
|
|
|
private function makeTask(): Task
|
|
{
|
|
$task = new Task();
|
|
$task->setNumber(random_int(100000, 999999));
|
|
$task->setTitle('Tâche de test '.uniqid());
|
|
$task->setProject($this->project);
|
|
|
|
return $task;
|
|
}
|
|
|
|
private function loginAs(User $user): void
|
|
{
|
|
$this->tokenStorage->setToken(
|
|
new UsernamePasswordToken($user, 'main', $user->getRoles()),
|
|
);
|
|
}
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 2: Lancer les tests pour vérifier qu'ils échouent**
|
|
|
|
Run: `docker exec php-lesstime-fpm php bin/phpunit tests/Functional/EventListener/TaskNotificationListenerTest.php`
|
|
Expected: FAIL — aucune `Notification` créée (le listener n'existe pas encore), `assertCount(1, ...)` échoue.
|
|
|
|
- [ ] **Step 3: Créer le listener**
|
|
|
|
Créer `src/EventListener/TaskNotificationListener.php` :
|
|
|
|
```php
|
|
<?php
|
|
|
|
declare(strict_types=1);
|
|
|
|
namespace App\EventListener;
|
|
|
|
use App\Entity\Notification;
|
|
use App\Entity\Task;
|
|
use App\Entity\User;
|
|
use DateTimeImmutable;
|
|
use Doctrine\Bundle\DoctrineBundle\Attribute\AsDoctrineListener;
|
|
use Doctrine\ORM\Event\OnFlushEventArgs;
|
|
use Doctrine\ORM\Event\PostFlushEventArgs;
|
|
use Doctrine\ORM\Events;
|
|
use Symfony\Bundle\SecurityBundle\Security;
|
|
|
|
#[AsDoctrineListener(event: Events::onFlush)]
|
|
#[AsDoctrineListener(event: Events::postFlush)]
|
|
final class TaskNotificationListener
|
|
{
|
|
/** @var list<array{user: User, type: string, task: Task}> */
|
|
private array $pending = [];
|
|
|
|
public function __construct(private readonly Security $security)
|
|
{
|
|
}
|
|
|
|
public function onFlush(OnFlushEventArgs $args): void
|
|
{
|
|
$actor = $this->security->getUser();
|
|
if (!$actor instanceof User) {
|
|
return;
|
|
}
|
|
|
|
$uow = $args->getObjectManager()->getUnitOfWork();
|
|
|
|
// Assignation sur une tâche nouvellement créée.
|
|
foreach ($uow->getScheduledEntityInsertions() as $entity) {
|
|
if (!$entity instanceof Task) {
|
|
continue;
|
|
}
|
|
$assignee = $entity->getAssignee();
|
|
if ($assignee instanceof User && $assignee !== $actor) {
|
|
$this->pending[] = ['user' => $assignee, 'type' => 'task_assigned', 'task' => $entity];
|
|
}
|
|
}
|
|
|
|
// Changement d'assignation sur une tâche existante.
|
|
foreach ($uow->getScheduledEntityUpdates() as $entity) {
|
|
if (!$entity instanceof Task) {
|
|
continue;
|
|
}
|
|
$changeSet = $uow->getEntityChangeSet($entity);
|
|
if (!isset($changeSet['assignee'])) {
|
|
continue;
|
|
}
|
|
$new = $changeSet['assignee'][1];
|
|
if ($new instanceof User && $new !== $actor) {
|
|
$this->pending[] = ['user' => $new, 'type' => 'task_assigned', 'task' => $entity];
|
|
}
|
|
}
|
|
}
|
|
|
|
public function postFlush(PostFlushEventArgs $args): void
|
|
{
|
|
if ([] === $this->pending) {
|
|
return;
|
|
}
|
|
|
|
$pending = $this->pending;
|
|
$this->pending = [];
|
|
|
|
$em = $args->getObjectManager();
|
|
foreach ($pending as $item) {
|
|
$em->persist($this->buildNotification($item['user'], $item['type'], $item['task']));
|
|
}
|
|
$em->flush();
|
|
}
|
|
|
|
private function buildNotification(User $user, string $type, Task $task): Notification
|
|
{
|
|
[$title, $message] = $this->render($type, $task);
|
|
|
|
$notification = new Notification();
|
|
$notification->setUser($user);
|
|
$notification->setType($type);
|
|
$notification->setTitle($title);
|
|
$notification->setMessage($message);
|
|
$notification->setCreatedAt(new DateTimeImmutable());
|
|
|
|
return $notification;
|
|
}
|
|
|
|
/**
|
|
* @return array{0: string, 1: string}
|
|
*/
|
|
private function render(string $type, Task $task): array
|
|
{
|
|
$projectName = $task->getProject()?->getName() ?? '';
|
|
$suffix = '' !== $projectName ? sprintf(' — %s', $projectName) : '';
|
|
$context = sprintf('« %s »%s', (string) $task->getTitle(), $suffix);
|
|
|
|
return match ($type) {
|
|
'task_assigned' => ['Nouvelle tâche assignée', $context],
|
|
'task_collaborator_added' => ['Ajout à une tâche', $context],
|
|
default => ['Notification', $context],
|
|
};
|
|
}
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 4: Lancer les tests pour vérifier qu'ils passent**
|
|
|
|
Run: `docker exec php-lesstime-fpm php bin/phpunit tests/Functional/EventListener/TaskNotificationListenerTest.php`
|
|
Expected: PASS (5 tests).
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
git add src/EventListener/TaskNotificationListener.php tests/Functional/EventListener/TaskNotificationListenerTest.php
|
|
git commit -m "feat(notification) : notifier le nouvel assigné d'une tâche"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 2: Notifications d'ajout de collaborateur
|
|
|
|
**Files:**
|
|
- Modify: `src/EventListener/TaskNotificationListener.php` (méthode `onFlush`)
|
|
- Test: `tests/Functional/EventListener/TaskNotificationListenerTest.php` (ajout de tests)
|
|
|
|
- [ ] **Step 1: Ajouter les tests collaborateurs (échouent)**
|
|
|
|
Ajouter ces deux méthodes dans `TaskNotificationListenerTest` :
|
|
|
|
```php
|
|
public function testAddingCollaboratorCreatesNotification(): void
|
|
{
|
|
$this->loginAs($this->actor);
|
|
|
|
$task = $this->makeTask();
|
|
$this->em->persist($task);
|
|
$this->em->flush();
|
|
|
|
$task->addCollaborator($this->alice);
|
|
$this->em->flush();
|
|
|
|
$rows = $this->notifications->findBy(['user' => $this->alice]);
|
|
self::assertCount(1, $rows);
|
|
self::assertSame('task_collaborator_added', $rows[0]->getType());
|
|
}
|
|
|
|
public function testAddingSelfAsCollaboratorCreatesNoNotification(): void
|
|
{
|
|
$this->loginAs($this->actor);
|
|
|
|
$task = $this->makeTask();
|
|
$this->em->persist($task);
|
|
$this->em->flush();
|
|
|
|
$task->addCollaborator($this->actor);
|
|
$this->em->flush();
|
|
|
|
self::assertCount(0, $this->notifications->findBy(['user' => $this->actor]));
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 2: Lancer les nouveaux tests pour vérifier qu'ils échouent**
|
|
|
|
Run: `docker exec php-lesstime-fpm php bin/phpunit tests/Functional/EventListener/TaskNotificationListenerTest.php --filter Collaborator`
|
|
Expected: FAIL — `testAddingCollaboratorCreatesNotification` échoue (aucune notification créée).
|
|
|
|
- [ ] **Step 3: Étendre `onFlush` pour gérer les collaborateurs**
|
|
|
|
Dans `src/EventListener/TaskNotificationListener.php`, ajouter ce bloc à la fin de `onFlush()`, juste avant la fin de méthode (après la boucle `getScheduledEntityUpdates`) :
|
|
|
|
```php
|
|
// Ajout de collaborateur(s) (tâche nouvelle ou existante).
|
|
foreach ($uow->getScheduledCollectionUpdates() as $collection) {
|
|
$owner = $collection->getOwner();
|
|
if (!$owner instanceof Task) {
|
|
continue;
|
|
}
|
|
if ('collaborators' !== $collection->getMapping()->fieldName) {
|
|
continue;
|
|
}
|
|
foreach ($collection->getInsertDiff() as $user) {
|
|
if ($user instanceof User && $user !== $actor) {
|
|
$this->pending[] = ['user' => $user, 'type' => 'task_collaborator_added', 'task' => $owner];
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 4: Lancer toute la classe de tests pour vérifier qu'elle passe**
|
|
|
|
Run: `docker exec php-lesstime-fpm php bin/phpunit tests/Functional/EventListener/TaskNotificationListenerTest.php`
|
|
Expected: PASS (7 tests).
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
git add src/EventListener/TaskNotificationListener.php tests/Functional/EventListener/TaskNotificationListenerTest.php
|
|
git commit -m "feat(notification) : notifier les collaborateurs ajoutés à une tâche"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 3: Vérification globale & style
|
|
|
|
**Files:** aucun nouveau fichier.
|
|
|
|
- [ ] **Step 1: Lancer la suite de tests complète**
|
|
|
|
Run: `make test`
|
|
Expected: PASS (aucune régression).
|
|
|
|
- [ ] **Step 2: Corriger le style PHP**
|
|
|
|
Run: `make php-cs-fixer-allow-risky`
|
|
Expected: les nouveaux fichiers sont conformes (strict types, ordre des imports).
|
|
|
|
- [ ] **Step 3: Commit si php-cs-fixer a modifié des fichiers**
|
|
|
|
```bash
|
|
git add -A
|
|
git commit -m "style(notification) : php-cs-fixer sur le listener de notifications"
|
|
```
|
|
|
|
(Sauter cette étape si php-cs-fixer n'a rien changé.)
|
|
|
|
---
|
|
|
|
## Self-review (auteur du plan)
|
|
|
|
- **Couverture spec :** assignation (création + update) ✔ Task 1 ; collaborateur ajouté ✔ Task 2 ; auto-exclusion ✔ (tests self) ; pas d'acteur → rien ✔ ; réassignation A→B ✔ ; `assignee=null` ✔ ; contenu réutilisant l'entité existante ✔ ; aucun changement front ✔.
|
|
- **Placeholders :** aucun — tout le code (listener + tests) est complet.
|
|
- **Cohérence des types :** `pending` typé `list<array{user,type,task}>` ; types `task_assigned` / `task_collaborator_added` identiques entre listener et tests ; `getMapping()->fieldName` (ORM 3) ; `addCollaborator()` confirmé sur l'entité Task.
|