Hexagonale Architektur (Ports & Adapters)

                 ┌───────────────────────── außen: Adapter ────────────────────────────┐
                 │  presentation (driving)                 infrastructure (driven)     │
  Nutzer ──────▶ │  TasksPage, TaskItem                    HttpTaskRepository, TaskDto │ ──▶ server
                 │        │   ┌──────────── application ─────────────┐   ▲             │
                 │        └──▶│ TaskBoard / AddTask ──▶ TaskRepository│───┘ implementiert│
                 │            │        │      ┌──── domain ────┐     │                  │
                 │            │        └─────▶│ Task, createTask│    │                  │
                 │            │               └─────────────────┘     │                  │
                 │            └───────────────────────────────────────┘                  │
                 └──────────────────────────────────────────────────────────────────────┘
  Regel: Import-Pfeile zeigen NUR nach innen. Die Domäne importiert nichts von außen.
  app.config.ts (Composition Root) ist die einzige Stelle, die TaskRepository an einen Adapter bindet.

// tasks/domain/task.ts — reines TypeScript: kein Import aus Angular, RxJS oder dem Browser
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` und `id` kommen als Parameter herein: Die Domäne liest weder die Uhr noch erzeugt sie selbst IDs
export function createTask(raw: string, existing: readonly Task[], now: Date, id: TaskId): Task {
  const title = normalizeTitle(raw);
  if (title.length < 3) throw new DomainError('Der Titel braucht mindestens 3 Zeichen.');
  if (existing.some((t) => !t.done && t.title.toLowerCase() === title.toLowerCase())) {
    throw new DomainError('Es gibt bereits eine offene Aufgabe mit diesem Titel.');
  }
  return { id, title, done: false, createdAt: now };
}

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

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

// Abstrakte Klasse, kein Interface: Sie existiert zur Laufzeit und ist daher direkt ein DI-Token.
// Sie hat kein @Injectable und kennt keine Implementierung.
export abstract class TaskRepository {
  abstract list(): Promise<readonly Task[]>;
  abstract save(task: Task): Promise<void>; // upsert
  abstract remove(id: TaskId): Promise<void>;
}

// Teil des Vertrags: Adapter übersetzen ihre technischen Fehler hierin.
export class RepositoryUnavailableError extends Error {
  override readonly name = 'RepositoryUnavailableError';
}

// tasks/application/add-task.ts — ein Use Case = eine Klasse mit einer einzigen öffentlichen Methode
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); // der Port — er weiß nicht, welcher Adapter antwortet

  async execute(title: string): Promise<Task> {
    const existing = await this.repo.list();
    const task = createTask(title, existing, new Date(), crypto.randomUUID() as TaskId); // die Regel: in der Domäne
    await this.repo.save(task); // I/O: über den Port
    return task;
  }
}

// tasks/infrastructure/http-task-repository.ts — der HTTP-ADAPTER
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 → Domäne, hier und nirgends sonst
  }

  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 verlässt den Adapter nicht: Der Kern erhält den Fehler des Ports
  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: die einzige Datei, die weiß, welchen Adapter wir nutzen
export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(withInterceptors([authInterceptor])),
    { provide: TaskRepository, useClass: HttpTaskRepository },
  ],
};

// Use-Case-Test: der In-Memory-Adapter statt 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('speichert über den Port', async () => {
    await addTask.execute('Tests schreiben');
    expect((await repo.list()).map((t) => t.title)).toEqual(['Tests schreiben']);
  });

  it('speichert nichts, wenn eine Domänenregel verletzt wird', async () => {
    await expect(addTask.execute('ab')).rejects.toThrow(DomainError);
    expect(await repo.list()).toEqual([]);
  });
});

// Die Dependency Rule, bei jedem Commit geprüft (ESLint no-restricted-imports mit Regex)
export default [
  {
    files: ['src/app/features/*/domain/**/*.ts'],
    rules: {
      'no-restricted-imports': ['error', { patterns: [
        { regex: '^(@angular/|rxjs)', message: 'Die Domäne ist reines TypeScript: kein Angular, kein RxJS.' },
        { regex: '/(application|infrastructure|ui)/', message: 'Die Domäne hängt nicht von den äußeren Schichten ab.' },
      ] }],
    },
  },
  {
    files: ['src/app/features/*/application/**/*.ts'],
    rules: {
      'no-restricted-imports': ['error', { patterns: [
        { regex: '/(infrastructure|ui)/', message: 'Application hängt von Ports ab, nicht von Adaptern oder der UI.' },
        { regex: '^@angular/common/http', message: 'HTTP nur in infrastructure.' },
      ] }],
    },
  },
  {
    files: ['src/app/features/*/ui/**/*.ts'],
    rules: {
      'no-restricted-imports': ['error', { patterns: [
        { regex: '/infrastructure/', message: 'Die UI injiziert den Port oder den Use Case, nicht den Adapter.' },
      ] }],
    },
  },
];
// In einem Nx-Monorepo: domain/application/infrastructure als separate Libraries, mit Tags
// und @nx/enforce-module-boundaries (siehe die Seite Monorepo).

// ✗ „Standardimplementierung“ am Port
@Injectable({ providedIn: 'root', useClass: HttpTaskRepository }) // der Port importiert den Adapter!
export abstract class TaskRepository { /* ... */ }
// Application → infrastructure: Die Dependency Rule ist verletzt, und HttpClient
// landet im Bundle, selbst für die App, die nur localStorage nutzt.

// ✓ Der Port bleibt leer; die Wahl liegt in der Composition Root
export abstract class TaskRepository { /* ... */ }
providers: [{ provide: TaskRepository, useClass: HttpTaskRepository }]

SCHICHTEN (Imports zeigen nur nach innen)
  domain          Task, createTask()         reines TypeScript — kein Angular, RxJS, Browser
  application     TaskRepository (Port)      abstrakte Klasse = Typ + DI-Token
                  AddTask / TaskBoard        inject(TaskRepository), Signals für die UI
  infrastructure  HttpTaskRepository         extends TaskRepository, DTO ↔ Domäne, Fehler übersetzt
  presentation    TasksPage, TaskItem        injiziert application, niemals infrastructure
  composition     app.config / route.providers  { provide: TaskRepository, useClass: Http… }

REZEPTE
  Adapter tauschen         ein anderes useClass in der Composition Root (oder provideTasks('local'))
  Use-Case-Test            providers: [{ provide: TaskRepository, useClass: InMemoryTaskRepository }]
  Adapter-Test             gemeinsamer Contract + HttpTestingController für das HTTP-Mapping
  DTO                      nur in infrastructure; der Port spricht in Entitäten
  Fehler                   der Adapter wirft RepositoryUnavailableError, nicht HttpErrorResponse

WANN NICHT
  CRUD ohne Regeln, kleine App, Prototyp → httpResource in der Komponente + Mapping in parse