Lesstime/docs/superpowers/specs/2026-06-19-lst-56-modular-monolith-design.md

# LST-56 — Socle modular monolith DDD + pilote « Projets/Tâches »

> Ticket Lesstime **#56** (1/5 — groupe « Refonte / Alignement Starseed »).
> Design validé le 2026-06-19. Référence vivante : repo **Starseed** (`.claude/rules/*.md` + implémentation réelle), et `Starseed/doc/architecture-modulaire-malio.md` (vision cible théorique — **non contraignante** là où elle diverge du code réel).

## 1. Objectif & contraintes

Poser dans Lesstime l'**infrastructure d'un modular monolith DDD** calquée sur Starseed, et **migrer un premier module pilote** (Projets/Tâches) de bout en bout comme preuve que la mécanique tient sur le cœur métier.

Contraintes **non négociables** :

- **Ne rien casser de l'existant.** Migration **strangler progressive** : le code legacy (`src/Entity/…`) et les modules (`src/Module/…`) coexistent ; l'application reste fonctionnelle et `make test` vert à **chaque** étape.
- **Prod = Docker, BDD peuplée** → uniquement des migrations **additives et nullable** (aucun `DROP`, aucun `NOT NULL` rétroactif, aucun déplacement de données).
- **Profondeur DDD : pragmatique**, alignée sur le **Starseed réel** (pas la doc théorique) : ORM attributs conservés dans les entités Domain, Repository = interface (Domain) + impl Doctrine (Infrastructure), Provider/Processor API Platform, contrats `Shared/Domain/Contract` pour le cross-module. **Pas de CQRS bus systématique, pas de multi-tenant.**

### Décisions de cadrage (figées)

| Sujet | Décision |
|-------|----------|
| Périmètre #56 | Socle complet + **1 module pilote** migré de bout en bout |
| Stratégie | **Strangler progressif** (legacy + modules en parallèle) |
| Profondeur DDD | **Pragmatique** (= Starseed réel) |
| Module pilote | **Projets/Tâches** (cœur métier) |
| Dépendances du pilote (User/Client/Notification) | Restent **legacy**, câblées via **contrats `Shared/Domain/Contract`** + `resolve_target_entities` |
| Infra d'audit Starseed | **Différée** → ticket Lesstime dédié (créé séparément) |
| Périmètre front #56 | **Câblage shell/shared/middlewares + migration du pilote en layer**, sans relooking (le relooking Malio reste #60) |
| Exposition API du pilote | **Garder les `#[ApiResource]` actuels** (étendre seulement les chemins de scan) — zéro régression API |
| Tâche → Notification | **Contrat `NotifierInterface`** (impl legacy crée la `Notification`) |
| Nom/ID du module | back `ProjectManagement` / front `project-management` / ID `project_management` |

## 2. Garde-fous Starseed retenus pour #56

Repris : `declare(strict_types=1)`, `src/Module/<X>/{Domain,Application,Infrastructure}`, `Shared/Domain/Contract` + `resolve_target_entities` (zéro import inter-modules), `config/modules.php` + `config/sidebar.php`, endpoints `/api/modules` + `/api/sidebar` + `/api/version`, `TimestampableBlamableTrait` + subscriber, pagination obligatoire, `COMMENT ON COLUMN` (helper `ColumnCommentsCatalog`), front layers auto-détectés + `useSidebar`/`useModules` + `auth.global.ts`/`modules.global.ts`.

Reportés (hors #56) : **infra d'audit** (`#[Auditable]`/`#[AuditIgnore]`, table `audit_log`, listener, resource) → ticket dédié. **RBAC fin** (`module.resource.action`) → #57 ; en #56 la sidebar filtre **par module actif** (au plus un gate `ROLE_ADMIN`).

## 3. Backend — arborescence cible

```
src/Shared/
├── Domain/
│   ├── Contract/        UserInterface, UserResolverInterface, ClientInterface, NotifierInterface
│   ├── Event/           DomainEventInterface
│   └── Trait/           TimestampableBlamableTrait
├── Infrastructure/
│   ├── Doctrine/        TimestampableBlamableSubscriber
│   ├── Database/        ColumnCommentsCatalog (helper COMMENT ON COLUMN + 4 colonnes std)
│   └── ApiPlatform/
│       ├── Resource/    ModulesResource, SidebarResource
│       └── State/       ModulesProvider, SidebarProvider
│
src/Module/ProjectManagement/
├── ProjectManagementModule.php   ID='project_management', LABEL='Projets', REQUIRED=false, permissions()=[] (stub, RBAC réel #57)
├── Domain/
│   ├── Entity/          Project, Task, Workflow, TaskStatus, TaskGroup, TaskEffort,
│   │                    TaskPriority, TaskTag, TaskRecurrence, TaskDocument
│   └── Repository/      *RepositoryInterface (une interface par agrégat consommé)
├── Application/         RecurrenceCalculator/RecurrenceHandler + services task-centric déplacés
└── Infrastructure/
    ├── Doctrine/        Doctrine*Repository + Migrations/ (additif Timestampable)
    ├── ApiPlatform/     State/Provider + State/Processor déplacés (TaskNumber, TaskCalendar,
    │                    TaskDocument*, SwitchProjectWorkflow, WorkflowDelete, ActiveTimeEntry resté legacy…)
    └── Mcp/Tool/        MCP tools Project/, Task/, TaskMeta/, Workflow/ déplacés
```

`src/Entity/` conserve **intacts** : `User`, `Client`, `Notification`, `TimeEntry`, `AbsenceRequest`/`AbsencePolicy`/`AbsenceBalance`, `Mail*`, `Gitea*`/`BookStack*`/`Zimbra*`/`Share*Configuration`. Ces domaines seront modularisés dans des tickets ultérieurs.

> **Note de découpage** : `TimeEntry` reste legacy en #56 (domaine Time tracking séparé). Le lien `Task ↔ TimeEntry` est porté côté `TimeEntry` (FK nullable vers la table `task`) ; aucune contrainte ne casse car la table `task` ne change pas de nom.

## 4. Câblage des dépendances (zéro import inter-modules)

1. Interfaces dans `src/Shared/Domain/Contract/` :
   - `UserInterface` (id + identifiants nécessaires aux entités du module : assignee, collaborators, createdBy/updatedBy),
   - `ClientInterface` (id + nom, pour `Project.client`),
   - `UserResolverInterface` (résoudre un user par id, pour les State/MCP du module),
   - `NotifierInterface` (créer une notification — impl legacy).
2. Les entités du module **type-hintent les interfaces**, jamais `App\Entity\*`.
3. `config/packages/doctrine.yaml → orm.resolve_target_entities` :
   ```yaml
   resolve_target_entities:
       App\Shared\Domain\Contract\UserInterface:   App\Entity\User
       App\Shared\Domain\Contract\ClientInterface: App\Entity\Client
   ```
4. `App\Entity\User` `implements UserInterface`, `App\Entity\Client` `implements ClientInterface` (legacy modifié à minima, additif).
5. Notifications : `App\Module\ProjectManagement\…` appelle `NotifierInterface` ; impl `App\…\LegacyNotifier` (wrappe le `NotificationService` actuel). Le `TaskNotificationListener` est déplacé/adapté pour passer par le contrat.

## 5. Config backend (toutes additives)

- **`doctrine.yaml`** — ajouter un mapping module (garder `App → src/Entity`) :
  ```yaml
  mappings:
      App: { type: attribute, is_bundle: false, dir: '%kernel.project_dir%/src/Entity', prefix: 'App\Entity', alias: App }
      ProjectManagement:
          type: attribute
          is_bundle: false
          dir: '%kernel.project_dir%/src/Module/ProjectManagement/Domain/Entity'
          prefix: 'App\Module\ProjectManagement\Domain\Entity'
  ```
  Les entités déplacées **gardent leur `#[ORM\Table(name: '…')]` actuel** (table inchangée → aucune donnée déplacée). `#[ORM\Entity(repositoryClass: DoctrineXxxRepository::class)]` mis à jour vers la nouvelle classe.
- **`doctrine_migrations.yaml`** — ajouter le namespace module (garder `DoctrineMigrations`) :
  ```yaml
  migrations_paths:
      DoctrineMigrations: '%kernel.project_dir%/migrations'
      'App\Module\ProjectManagement\Infrastructure\Doctrine\Migrations': '%kernel.project_dir%/src/Module/ProjectManagement/Infrastructure/Doctrine/Migrations'
  ```
  > ⚠️ Doctrine Migrations trie par FQCN entre namespaces : le legacy `DoctrineMigrations` (setup initial) passe avant les migrations modulaires sur base vide. Sur la prod déjà migrée, seules les **nouvelles** migrations additives s'appliquent → pas d'impact d'ordre.
- **`api_platform.yaml`** — déclarer les chemins de mapping (entités + resources legacy **et** module) pour que les `#[ApiResource]` du pilote restent découverts :
  ```yaml
  mapping:
      paths:
          - '%kernel.project_dir%/src/Entity'
          - '%kernel.project_dir%/src/ApiResource'
          - '%kernel.project_dir%/src/Shared/Infrastructure/ApiPlatform/Resource'
          - '%kernel.project_dir%/src/Module/ProjectManagement/Domain/Entity'
  ```
- **`services.yaml`** — mettre à jour les FQCN explicites déplacés : `App\EventListener\TaskDocumentListener`, `App\State\TaskDocumentProcessor`, `App\Controller\TaskDocumentDownloadController`, `App\Mcp\Tool\Task\AddTaskDocumentTool`, `App\Mcp\Tool\Task\UpdateTaskDocumentTool` → nouveaux namespaces module. Le glob `App\: '../src/'` continue d'autowire les classes déplacées.

## 6. Garde-fous portés dans #56

- **TimestampableBlamable** : trait `Shared/Domain/Trait/TimestampableBlamableTrait` (4 colonnes `created_at`, `updated_at`, `created_by`, `updated_by` — toutes **nullable**), rempli par `TimestampableBlamableSubscriber` (prePersist/preUpdate). Appliqué aux entités du pilote → **1 migration additive** par table concernée, avec `COMMENT ON COLUMN` via `ColumnCommentsCatalog::addStandardTimestampableBlamableComments()`.
- **Pagination** : conserver le standard API Platform actuel (les collections du pilote restent paginées comme aujourd'hui).
- **`COMMENT ON COLUMN`** : appliqué sur les colonnes ajoutées par #56 (pas de rétro-commentaire forcé sur le legacy).

## 7. Endpoints modules / sidebar / version

- `GET /api/modules` (public) — `ModulesResource` + `ModulesProvider` lisant `config/modules.php` (renvoie `{ modules: ["project_management", …] }`).
- `GET /api/sidebar` (auth) — `SidebarResource` + `SidebarProvider` lisant `config/sidebar.php` ; filtrage **par module actif** (item `module` absent de la liste active → masqué + route ajoutée à `disabledRoutes`) ; gate de section optionnel `ROLE_ADMIN`. Le filtrage par **permissions fines** est explicitement reporté à #57.
- `GET /api/version` — **déjà présent** (`AppVersion`) ; vérifier le format `{ version }`, ré-aligner si besoin (déplacement optionnel vers `Shared/`).
- `config/modules.php` : `return [ ProjectManagementModule::class ];` (Core viendra plus tard ; pas de module REQUIRED bloquant en #56).
- `config/sidebar.php` : sections « Projets » / « Mes tâches » avec `module => 'project_management'` ; les entrées des domaines encore legacy (Time tracking, Absences, Mail, Admin…) listées **sans** clé `module` (donc toujours visibles) pour ne rien masquer.

## 8. Frontend — câblage + pilote en layer (sans relooking)

```
frontend/app/
├── layouts/default.vue            shell : sidebar (depuis /api/sidebar) + main
├── middleware/auth.global.ts      protège routes, charge sidebar+modules après login
└── middleware/modules.global.ts   redirige si route ∈ disabledRoutes
frontend/shared/
├── composables/  useApi (déplacé), useSidebar, useModules, + existants réutilisés
├── stores/       auth, ui, timer (timer reste partagé : Time tracking encore legacy)
├── utils/        api.ts (extractHydraMembers/fetchAllHydra), …
└── types/
frontend/modules/project-management/
├── nuxt.config.ts                 defineNuxtConfig({})
├── pages/        my-tasks.vue, projects/index.vue, projects/[id]/*  (déplacés tels quels)
├── components/   task/*, project/*  (déplacés)
├── services/     tasks.ts, projects.ts, task-*.ts, workflows.ts (déplacés)
└── stores/       (si spécifiques au domaine)
```

- **`nuxt.config.ts`** : auto-détection des layers `modules/*/` (scan `readdirSync` comme Starseed) ajoutés à `extends`, + dirs d'auto-import des composables/stores par layer. `extends: ['@malio/layer-ui']` conservé en tête.
- **`useSidebar`/`useModules`** : état singleton, `loadSidebar()`/`loadModules()` appelés dans `auth.global.ts`, `reset*()` au logout.
- **`modules.global.ts`** : `isRouteDisabled(to.path)` → `navigateTo('/')`.
- **Migration des pages** : déplacement **sans réécriture visuelle** ; les pages des autres domaines (time-tracking, absences, mail, admin, profile…) **restent dans `frontend/pages/`** (legacy) tant que leurs modules ne sont pas migrés. Nuxt fusionne les routes du shell + des layers → cohabitation transparente.

> Point de vigilance front : vérifier que la cohabitation `frontend/pages/` (legacy) + `frontend/modules/*/pages/` (layer) ne crée pas de collision de routes ; `my-tasks`/`projects` sont déplacés **et retirés** de `frontend/pages/` pour éviter le doublon.

## 9. Plan strangler (ordre d'exécution — app verte à chaque palier)

1. **Shared/ + garde-fous** : trait, subscriber, `ColumnCommentsCatalog`. Neutre (rien ne les consomme encore).
2. **Endpoints modules/sidebar** + `config/modules.php` + `config/sidebar.php` (toutes entrées legacy sans `module` → rien masqué). Additif.
3. **Contrats `Shared/Domain/Contract`** + `resolve_target_entities` + `User`/`Client` `implements …Interface`. Neutre.
4. **Déplacement back du module** ProjectManagement (entités → Domain/Entity, repos → Infra/Doctrine + interfaces Domain, State, MCP) + mises à jour `doctrine.yaml`/`api_platform.yaml`/`doctrine_migrations.yaml`/`services.yaml`. **`make test` vert.**
5. **Migration additive Timestampable** sur les tables du pilote (+ `COMMENT ON COLUMN`).
6. **Front shell** : `app/` + `shared/` + middlewares + auto-détection `nuxt.config.ts`. App encore en pages plates.
7. **Déplacement front du pilote** vers `modules/project-management/` (pages/components/services), retrait des doublons de `frontend/pages/`.
8. **Vérification bout-en-bout** : commenter `ProjectManagementModule::class` dans `config/modules.php` → `/api/modules` ne le liste plus, `/api/sidebar` masque ses entrées + peuple `disabledRoutes`, le front redirige `/my-tasks`→`/`. Décommenter → tout revient. Documenter le test.

## 10. Critères d'acceptation (repris du ticket, raffinés)

- [ ] `src/Shared/` + `src/Module/ProjectManagement/{Domain,Application,Infrastructure}` en place.
- [ ] `/api/modules`, `/api/sidebar` fonctionnels ; `/api/version` aligné.
- [ ] Aucun import direct `App\Entity\User`/`Client` depuis le module (contrats + `resolve_target_entities`).
- [ ] Front : layers `frontend/modules/*/` auto-détectés ; `useSidebar`/`useModules` + `auth.global.ts`/`modules.global.ts` opérationnels ; pilote migré sans régression visuelle.
- [ ] Garde-fous : TimestampableBlamable (migration additive + `COMMENT ON COLUMN`) ; pagination conservée. **Audit explicitement hors périmètre** (ticket dédié).
- [ ] `make test` vert ; activation/désactivation du module validée de bout en bout.
- [ ] Aucune migration destructive ; prod déployable sans perte.

## 11. Risques & points de vigilance

- **Prod peuplée** : seules migrations additives nullable. `created_by`/`updated_by` non backfillés (historique) — conforme Starseed.
- **Changement de namespace des entités** : sans impact DB (Doctrine mappe par table). Vérifier qu'aucun code legacy ne référence en dur `App\Entity\Task` etc. → grep + remplacement (le pilote tire Task/Project, consommés par TimeEntry/Mail/BookStack links restés legacy : ces liens passeront par les contrats ou un type-hint relâché).
- **Collision de routes front** legacy vs layer (cf. §8).
- **MCP tools** (spécificité Lesstime) : déplacés sous `Module/*/Infrastructure/Mcp/` ; confirmer que `McpSchemaGeneratorPass` les redécouvre (scan `src/`).
- **`auto_mapping: true`** : valider que l'ajout d'un mapping explicite ne perturbe pas la résolution (sinon désactiver `auto_mapping` et lister explicitement).

## 12. Suite

- Ticket **audit** dédié à créer (infra `#[Auditable]` + `audit_log` + listener + resource), prérequis souple de #57.
- #57 RBAC fin (permissions `module.resource.action`, sidebar filtrée par permission).
- #58 Répertoire (Clients/Prospects), #59 Reporting, #60 Refonte front Malio.