Architecture hexagonale (ports et adapters)

                 ┌──────────────────────── extérieur : adaptateurs ────────────────────┐
                 │  presentation (driving)                 infrastructure (driven)     │
  utilisateur ─▶ │  TasksPage, TaskItem                    HttpTaskRepository, TaskDto │ ──▶ server
                 │        │   ┌──────────── application ─────────────┐   ▲             │
                 │        └──▶│ TaskBoard / AddTask ──▶ TaskRepository│───┘ implémente   │
                 │            │        │      ┌──── domain ────┐     │                  │
                 │            │        └─────▶│ Task, createTask│    │                  │
                 │            │               └─────────────────┘     │                  │
                 │            └───────────────────────────────────────┘                  │
                 └──────────────────────────────────────────────────────────────────────┘
  Règle : les flèches d’import pointent UNIQUEMENT vers l’intérieur. Le domaine n’importe rien de l’extérieur.
  app.config.ts (composition root) est le seul endroit qui lie TaskRepository à un adaptateur.

// tasks/domain/task.ts — TypeScript pur : aucun import d’Angular, de RxJS ni du navigateur
export type TaskId = string & { readonly __brand: 'TaskId' };

export interface Task {
  readonly id: TaskId;
  readonly title: string;
  readonly done: boolean;
  readonly createdAt: Date;
}

export class DomainError extends Error {
  override readonly name = 'DomainError';
}

export function normalizeTitle(raw: string): string {
  return raw.trim().replace(/\s+/g, ' ');
}

// `now` et `id` arrivent en paramètres : le domaine ne lit pas l’horloge et ne génère pas d’ids lui-même
export function createTask(raw: string, existing: readonly Task[], now: Date, id: TaskId): Task {
  const title = normalizeTitle(raw);
  if (title.length < 3) throw new DomainError('Le titre doit contenir au moins 3 caractères.');
  if (existing.some((t) => !t.done && t.title.toLowerCase() === title.toLowerCase())) {
    throw new DomainError('Il existe déjà une tâche ouverte avec ce titre.');
  }
  return { id, title, done: false, createdAt: now };
}

export function toggleTask(task: Task): Task {
  return { ...task, done: !task.done };
}

// tasks/application/task-repository.ts — le PORT
import { Task, TaskId } from '../domain/task';

// Classe abstraite, pas une interface : elle existe à l’exécution, c’est donc directement un token de DI.
// Elle n’a pas de @Injectable et ne connaît aucune implémentation.
export abstract class TaskRepository {
  abstract list(): Promise<readonly Task[]>;
  abstract save(task: Task): Promise<void>; // upsert
  abstract remove(id: TaskId): Promise<void>;
}

// Fait partie du contrat : les adaptateurs y traduisent leurs erreurs techniques.
export class RepositoryUnavailableError extends Error {
  override readonly name = 'RepositoryUnavailableError';
}

// tasks/application/add-task.ts — un cas d’usage = une classe avec une seule méthode publique
import { Injectable, inject } from '@angular/core';
import { Task, TaskId, createTask } from '../domain/task';
import { TaskRepository } from './task-repository';

@Injectable({ providedIn: 'root' })
export class AddTask {
  private readonly repo = inject(TaskRepository); // le port — ne sait pas quel adaptateur répond

  async execute(title: string): Promise<Task> {
    const existing = await this.repo.list();
    const task = createTask(title, existing, new Date(), crypto.randomUUID() as TaskId); // la règle : dans le domaine
    await this.repo.save(task); // E/S : via le port
    return task;
  }
}

// tasks/infrastructure/http-task-repository.ts — l’ADAPTATEUR HTTP
import { HttpClient, HttpErrorResponse } from '@angular/common/http';
import { Injectable, inject } from '@angular/core';
import { Observable, firstValueFrom } from 'rxjs';
import { Task, TaskId } from '../domain/task';
import { RepositoryUnavailableError, TaskRepository } from '../application/task-repository';
import { TaskDto, taskFromDto, taskToDto } from './task-dto';

@Injectable()
export class HttpTaskRepository extends TaskRepository {
  private readonly http = inject(HttpClient);
  private readonly url = '/api/tasks';

  async list(): Promise<readonly Task[]> {
    const dtos = await this.call(this.http.get<TaskDto[]>(this.url));
    return dtos.map(taskFromDto); // DTO → domaine, ici et nulle part ailleurs
  }

  async save(task: Task): Promise<void> {
    await this.call(this.http.put<TaskDto>(`${this.url}/${task.id}`, taskToDto(task)));
  }

  async remove(id: TaskId): Promise<void> {
    await this.call(this.http.delete<void>(`${this.url}/${id}`));
  }

  // HttpErrorResponse ne quitte pas l’adaptateur : le cœur reçoit l’erreur du port
  private async call<T>(request: Observable<T>): Promise<T> {
    try {
      return await firstValueFrom(request);
    } catch (e) {
      if (e instanceof HttpErrorResponse) throw new RepositoryUnavailableError(`HTTP ${e.status}`);
      throw e;
    }
  }
}

// app.config.ts — COMPOSITION ROOT : le seul fichier qui sait quel adaptateur on utilise
export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(withInterceptors([authInterceptor])),
    { provide: TaskRepository, useClass: HttpTaskRepository },
  ],
};

// Test de cas d’usage : l’adaptateur en mémoire à la place de HTTP
import { TestBed } from '@angular/core/testing';

describe('AddTask', () => {
  let addTask: AddTask;
  let repo: InMemoryTaskRepository;

  beforeEach(() => {
    TestBed.configureTestingModule({
      providers: [{ provide: TaskRepository, useClass: InMemoryTaskRepository }],
    });
    addTask = TestBed.inject(AddTask);
    repo = TestBed.inject(TaskRepository) as InMemoryTaskRepository;
  });

  it('enregistre via le port', async () => {
    await addTask.execute('Écrire des tests');
    expect((await repo.list()).map((t) => t.title)).toEqual(['Écrire des tests']);
  });

  it('n’enregistre rien si une règle du domaine est violée', async () => {
    await expect(addTask.execute('ab')).rejects.toThrow(DomainError);
    expect(await repo.list()).toEqual([]);
  });
});

// La règle de dépendance, vérifiée à chaque commit (no-restricted-imports d’ESLint avec regex)
export default [
  {
    files: ['src/app/features/*/domain/**/*.ts'],
    rules: {
      'no-restricted-imports': ['error', { patterns: [
        { regex: '^(@angular/|rxjs)', message: 'Le domaine est du TypeScript pur : pas d’Angular, pas de RxJS.' },
        { regex: '/(application|infrastructure|ui)/', message: 'Le domaine ne dépend pas des couches externes.' },
      ] }],
    },
  },
  {
    files: ['src/app/features/*/application/**/*.ts'],
    rules: {
      'no-restricted-imports': ['error', { patterns: [
        { regex: '/(infrastructure|ui)/', message: 'Application dépend des ports, pas des adaptateurs ni de l’UI.' },
        { regex: '^@angular/common/http', message: 'HTTP uniquement dans infrastructure.' },
      ] }],
    },
  },
  {
    files: ['src/app/features/*/ui/**/*.ts'],
    rules: {
      'no-restricted-imports': ['error', { patterns: [
        { regex: '/infrastructure/', message: 'L’UI injecte le port ou le cas d’usage, pas l’adaptateur.' },
      ] }],
    },
  },
];
// Dans un monorepo Nx : domain/application/infrastructure comme bibliothèques séparées, avec des tags
// et @nx/enforce-module-boundaries (voir la page Monorepo).

// ✗ « Implémentation par défaut » placée sur le port
@Injectable({ providedIn: 'root', useClass: HttpTaskRepository }) // le port importe l’adaptateur !
export abstract class TaskRepository { /* ... */ }
// Application → infrastructure : la règle de dépendance est violée, et HttpClient
// finit dans le bundle même pour l’application qui n’utilise que localStorage.

// ✓ Le port reste vide ; le choix vit dans la composition root
export abstract class TaskRepository { /* ... */ }
providers: [{ provide: TaskRepository, useClass: HttpTaskRepository }]

COUCHES (les imports ne pointent que vers l’intérieur)
  domain          Task, createTask()         TypeScript pur — ni Angular, ni RxJS, ni navigateur
  application     TaskRepository (port)      classe abstraite = type + token de DI
                  AddTask / TaskBoard        inject(TaskRepository), Signals pour l’UI
  infrastructure  HttpTaskRepository         extends TaskRepository, DTO ↔ domaine, erreurs traduites
  presentation    TasksPage, TaskItem        injecte application, jamais infrastructure
  composition     app.config / route.providers  { provide: TaskRepository, useClass: Http… }

RECETTES
  changer d’adaptateur     un autre useClass dans la composition root (ou provideTasks('local'))
  test de cas d’usage      providers: [{ provide: TaskRepository, useClass: InMemoryTaskRepository }]
  test d’adaptateur        contrat partagé + HttpTestingController pour le mapping HTTP
  DTO                      uniquement dans infrastructure ; le port parle en entités
  erreurs                  l’adaptateur lance RepositoryUnavailableError, pas HttpErrorResponse

QUAND S’EN ABSTENIR
  CRUD sans règles, petite application, prototype → httpResource dans le composant + mapping dans parse