# BLOC-1-RAPPORT-FINAL.md — Engagement Layer Complet

**Date**: 2026-05-28
**Sessions**: 139-145 (SPEC-BLOC-1A a SPEC-BLOC-1H)
**Statut**: COMPLET

---

## 1. Perimetre livre

Le Bloc 1 "Engagement Layer" est un socle transversal qui ajoute 5 modules fonctionnels a l'ERP MetallKart:

| Module | Description | Route |
|--------|-------------|-------|
| Tasks | Gestion de taches (liste + Kanban + drawer) | /tasks |
| Decisions | Decisions structurees (BINARY / MULTI_CHOICE) | /decisions |
| Reminders | Rappels planifies (SCHEDULED / SENT / ACKNOWLEDGED) | /reminders |
| Agenda | Calendrier unifie (jour/semaine/mois) | /agenda |
| PWA | Application installable + Web Push | manifest + SW |

## 2. Backend — Modeles et services

### 2.1 Modeles Prisma (11 tables)

| Modele | Description |
|--------|-------------|
| Task | Taches avec statut, priorite, assignation |
| TaskDependency | Dependances entre taches (blocksTaskId/dependsOnTaskId) |
| TaskEntityLink | Liens taches <-> entites ERP |
| Decision | Decisions avec kind BINARY/MULTI_CHOICE |
| DecisionLog | Journal des evenements decision |
| DecisionEntityLink | Liens decisions <-> entites ERP |
| Reminder | Rappels planifies multi-canal |
| EngagementAutoRule | Regles automatiques (8 seedees) |
| UserMemory | Preferences utilisateur (PREFERENCE -> CONSTRAINT) |
| AgendaCalendarConfig | Configuration calendrier par utilisateur |
| NotificationDelivery | Suivi livraison notifications multi-canal |

### 2.2 Services (7)

| Service | Responsabilite |
|---------|----------------|
| TasksService | CRUD + status transitions + recherche |
| DecisionsService | CRUD + decide + escalate + cancel + reopen |
| RemindersService | CRUD + acknowledge + liste filtree |
| AgendaService | Aggregation taches+decisions par plage |
| CalendarConfigService | Config calendrier par user (upsert) |
| UserMemoryService | Preferences utilisateur CRUD |
| EngagementRouterService | Auto-rules CRUD + toggle |

### 2.3 Routes (7 fichiers, ~30 endpoints)

| Fichier | Prefix | Endpoints |
|---------|--------|-----------|
| tasks.routes.ts | /engagement/tasks | CRUD + status + search |
| decisions.routes.ts | /engagement/decisions | CRUD + decide + escalate + cancel + reopen |
| reminders.routes.ts | /engagement/reminders | CRUD + acknowledge |
| agenda.routes.ts | /engagement/agenda | GET agenda + GET/PUT config |
| user-memory.routes.ts | /engagement/user-memory | CRUD |
| router.routes.ts | /engagement/router | auto-rules list + toggle |
| engagement.routes.ts | /engagement (barrel) | Registre tous les sous-modules |

### 2.4 Hooks et Crons

| Hook/Cron | Declencheur |
|-----------|-------------|
| reminder-dispatch.cron | Toutes les 5 min, envoie les rappels SCHEDULED echus |
| decision-escalation.cron | Toutes les 15 min, escalade les decisions en retard |
| engagement-auto-rules seed | Au demarrage, upsert 8 regles referentiel |

## 3. Frontend — Composants

### 3.1 Tasks (frontend/src/modules/engagement/tasks/)

| Composant | Role |
|-----------|------|
| TasksPage | Page principale (liste + Kanban toggle) |
| TaskListView | Tableau AntD avec filtres et pagination |
| TaskKanbanView | Vue colonnes drag & drop |
| TaskCreateModal | Modal creation tache |
| TaskDetailDrawer | Drawer detail tache (720px) |
| store.ts | Zustand state management |

### 3.2 Decisions (frontend/src/modules/engagement/decisions/)

| Composant | Role |
|-----------|------|
| DecisionsPage | Page principale avec KPI cards |
| DecisionCreateModal | Modal creation (BINARY / MULTI_CHOICE) |
| DecisionDetailDrawer | Drawer detail avec log et reminders |
| DecisionDecideModal | Modal pour decider (boutons / radio) |
| store.ts | Zustand state management |

### 3.3 Agenda (frontend/src/modules/engagement/agenda/)

| Composant | Role |
|-----------|------|
| AgendaPage | Page calendrier avec stats |
| AgendaDayView / WeekView / MonthView | 3 vues calendrier |

### 3.4 PWA

| Composant | Role |
|-----------|------|
| sw.ts | Service Worker (push + notificationclick) |
| PwaInstallPrompt | Banniere installation PWA |
| NotificationOptInBanner | Opt-in push dans AgendaPage |

## 4. Auth — Migration HTTPOnly Cookies

| Avant (BLOC-1E) | Apres (BLOC-1F) |
|------------------|-----------------|
| JWT dans localStorage | Cookie `mk_erp_token` HTTPOnly 15min |
| Bearer header explicite | Cookie auto-envoye par navigateur |
| Refresh via body | Cookie `mk_erp_refresh` HTTPOnly 7d path=/api/v1/auth/refresh |
| — | Bearer fallback preserve pour E2E Playwright |
| — | SameSite=Strict, Secure conditionnel HTTPS_ENABLED |

## 5. Tests automatises

### 5.1 Vitest (backend)

| Module | Tests |
|--------|-------|
| BLOC-1A (schemas + foundation) | 12 |
| BLOC-1B (services + routes) | 30 |
| Total | 42 |

### 5.2 Playwright E2E

| Fichier spec | Tests | Description |
|-------------|-------|-------------|
| engagement-tasks.spec.ts | 22 | Liste, Kanban, filtres, CRUD, drawer, statut |
| engagement-decisions.spec.ts | 6 | Display, filtrage, create API, decide BINARY/MULTI |
| engagement-reminders.spec.ts | 5 | Display, filtrage statut, acknowledge, create API |
| engagement-agenda.spec.ts | 5 | Vues jour/semaine/mois, items, multi-user, config API |
| engagement-router-admin.spec.ts | 4 | Auto-rules list, toggle, structure, auth guard |
| engagement-pwa-cross.spec.ts | 5 | Manifest, SW, sidebar, deep-links, auth cookies |
| **Total engagement** | **47** | |

### 5.3 Total E2E projet (avant BLOC-1)

~200 tests existants. Objectif: 0 regression. Suite complete executee et validee.

## 6. Seed E2E (seed-test.ts)

Donnees ajoutees au seed E2E pour le module engagement:

| Entite | Quantite | Details |
|--------|----------|---------|
| Tasks | 4 | TODO, IN_PROGRESS, DONE, CANCELLED |
| Decisions | 3 | BINARY PENDING, MULTI_CHOICE PENDING, BINARY DECIDED |
| Reminders | 2 | SCHEDULED, SENT |
| AgendaCalendarConfig | 1 | Admin, defaultView WEEK |
| EngagementAutoRules | 8 | Seedees via referentiel |

## 7. Bugs decouverts et corriges

| Bug | Cause | Correction |
|-----|-------|------------|
| GET /decisions/:id retourne 500 | Prisma include `logs` au lieu de `log` (nom relation) | decisions.service.ts: logs -> log |
| CalendarConfig enableReminders undefined | toDto() lisait `c.enableReminders` au lieu de `c.showReminders` | calendar-config.service.ts: mapping corrige |
| Decision BINARY options vides | Seed manquait le champ `options` | seed-test.ts: ajout options approve/reject |
| Dropdown AntD ne se ferme pas | `getByText('Напоминания').click()` bloque par overlay | Remplace par `page.keyboard.press('Escape')` |
| Prisma validation reminders relation | Include `target` nommage relation "ReminderTarget" | Fix dans BLOC-1C via `targetUser -> target` |

## 8. Architecture — Decisions cles

| Decision | Justification |
|----------|---------------|
| Zustand (pas Redux/Context) | Leger, pas de boilerplate, store isole par module |
| Cookie HTTPOnly (pas Bearer) | Securite XSS, pas de token en JS accessible |
| Bearer fallback E2E | Playwright ne peut pas injecter des cookies same-site facilement |
| API-based E2E pour create/decide | DatePicker AntD v6 unreliable avec fill(), API plus stable |
| engagement_auto_rules = referentiel | Jamais tronque par seed, upsert idempotent |

## 9. Fichiers cles

```
prisma/schema.prisma                        # 11 modeles engagement
src/modules/engagement/                      # Backend complet
  services/ (7 fichiers)
  routes/ (7 fichiers)
  schemas/ (5 fichiers)
  helpers/entity-resolver.ts
  crons/ (2 fichiers)
frontend/src/modules/engagement/             # Frontend complet
  tasks/ (6 composants + store)
  decisions/ (5 composants + store)
  agenda/ (4 composants)
frontend/src/sw.ts                           # Service Worker PWA
tests/e2e/engagement-*.spec.ts              # 6 fichiers, 47 tests
tests/e2e/seed-test.ts                      # Seed engagement
MANUAL-VALIDATION-BLOC-1.md                 # Checklist manuelle
scripts/cleanup-demo-engagement.sh          # Purge donnees demo
```

## 10. Metriques finales

| Metrique | Valeur |
|----------|--------|
| Modeles Prisma ajoutes | 11 |
| Enums ajoutes | 17 |
| Services backend | 7 |
| Routes backend | ~30 endpoints |
| Composants frontend | ~20 |
| Vitest | 42 |
| Playwright E2E | 47 |
| Bugs corriges | 5 |
| Erreurs TS | 0 |
| Regressions E2E | 0 |

## 11. Livraison

- [x] BLOC-1A: Foundation (11 modeles, 17 enums, 10 Zod, 12 Vitest)
- [x] BLOC-1B: Backend services + routes + hooks + crons (30 Vitest)
- [x] BLOC-1C: Frontend Tasks (Liste + Kanban + Drawer + Modal)
- [x] BLOC-1D: E2E Tasks (22 tests)
- [x] BLOC-1E: Router wiring + deep-links + cron migration
- [x] BLOC-1F: PWA + Web Push + Auth HTTPOnly cookies (5 Vitest)
- [x] BLOC-1H: E2E Decisions/Reminders/Agenda/Router/PWA (25 tests) + docs + rapport