feat(behandel): behandel-portal — werkbak + beoordeling (closes #13) (#87)

## What & why

Finishes **S-12 · Behandel-portal — werkbak + beoordeling**. The backend sub-slices (S-12a/b/c-1/c-2) were merged, but the slice's stated outcome — a behandel *portal* with medewerker login, a werkbak, and decide — had no frontend. This adds it.

- **`libs/auth`**: `MedewerkerAuthService` + `provideMedewerkerAuth` (Keycloak `medewerker` realm), a `roles`/`hasRole` surface on the shared `AuthService`, and a realm-roles protocol mapper so the SPA can read `behandelaar`/`teamlead` from the token. The BFF remains the security boundary (ADR-0013).
- **`apps/behandel`**: a new Nx Angular app mirroring self-service — medewerker OIDC login and a **werkbak** page listing registrations awaiting beoordeling (`GET /behandel/werkbak`) with per-row **Goedkeuren/Afwijzen** actions (`POST /behandel/registrations/{id}/decide`) that refresh the list. NL DS/Utrecht, standalone + signals.
- **e2e**: the walking-skeleton happy path now approves through the real portal (behandelaar logs in, finds the row by reference, clicks Goedkeuren) instead of the temporary admin endpoint.
- **infra/docs**: behandel service in compose (`:8142`, depends on Keycloak); added to the smoke `WAIT_SVCS` + CI log dump; `frontend-decisions.md` and `demo-script.md` updated.

Closes #13

## Definition of Done

- [x] Linked Gitea issue (above).
- [x] Failing test committed before the implementation.
- [x] Implementation makes the test pass; refactor commit if structure improved.
- [x] Conventional Commits referencing the issue (`refs #13`).
- [ ] CI green — all Gitea Actions jobs.
- [x] `docker compose up` from a fresh clone reaches green health checks within 3 minutes. *(behandel image + container verified locally; full stack gated in CI.)*
- [x] Docs updated if behaviour, contracts, or operations changed.
- [x] ADR added — ADR-0013 (merged with the backend sub-slices) already covers the wiring; no new decision here.
- [x] Demo note in `docs/demo-script.md`.

## Notes for reviewers

- Verified locally: auth + behandel + all frontend projects pass lint & unit tests (incl. axe WCAG 2.1 AA); production build green; the behandel Docker image builds and serves with the correct baked `medewerker` config + SPA fallback.
- The full compose-up smoke, e2e, and mutation are CI-gated (known local full-stack verify limits).
- **Follow-ups (not in scope):** the `WerkbakItem` contract has no citizen name (werkbak shows the BSN) — adding one is a BFF+domain contract change; and the domain's temporary admin `approve` endpoint is now unused by the e2e and could be removed.

Reviewed-on: #87

apps/behandel/src/app/app.config.spec.ts

@@ -0,0 +1,73 @@
+import { provideHttpClient, withInterceptors } from '@angular/common/http';
+import { HttpTestingController, provideHttpClientTesting } from '@angular/common/http/testing';
+import { TestBed } from '@angular/core/testing';
+import { BffApiV1Service } from 'api-client';
+import { authInterceptor } from 'auth';
+import { AbstractSecurityStorage, ConfigurationService } from 'angular-auth-oidc-client';
+import { SECURE_API_ROUTES } from './app.config';
+
+// Guards the medewerker token wiring end-to-end. The api-client calls the BFF with RELATIVE URLs, and
+// the angular-auth-oidc-client interceptor attaches the token only when `req.url` starts with a
+// configured secureRoute. A regression to an absolute origin makes the relative URL never match, so
+// the behandel calls go out unauthenticated and the BFF answers 401. This drives the REAL interceptor
+// and the REAL api-client against the REAL production route value (SECURE_API_ROUTES); only the config
+// source and token storage are faked, so the assertion turns on the actual route-matching.
+describe('behandel medewerker token wiring', () => {
+  let http: HttpTestingController;
+  let bff: BffApiV1Service;
+  const token = 'medewerker-access-token';
+
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      providers: [
+        provideHttpClient(withInterceptors([authInterceptor()])),
+        provideHttpClientTesting(),
+        {
+          provide: ConfigurationService,
+          useValue: {
+            hasAtLeastOneConfig: () => true,
+            getAllConfigurations: () => [{ configId: 'medewerker', secureRoutes: SECURE_API_ROUTES }],
+          },
+        },
+        {
+          // A signed-in session: the storage the interceptor's token lookup reads from.
+          provide: AbstractSecurityStorage,
+          useValue: {
+            read: () => JSON.stringify({ authzData: token, authnResult: { id_token: 'id-token' } }),
+            write: () => undefined,
+            remove: () => undefined,
+            clear: () => undefined,
+          },
+        },
+      ],
+    });
+    http = TestBed.inject(HttpTestingController);
+    bff = TestBed.inject(BffApiV1Service);
+  });
+
+  afterEach(() => http.verify());
+
+  it('attaches the bearer token to the relative werkbak call', () => {
+    bff.getBehandelWerkbak().subscribe();
+
+    const req = http.expectOne('/behandel/werkbak');
+    expect(req.request.headers.get('Authorization')).toBe(`Bearer ${token}`);
+    req.flush([]);
+  });
+
+  it('attaches the bearer token to the relative decide call', () => {
+    bff.postBehandelRegistrationsIdDecide('reg-1', { besluit: 'goedkeuren' }).subscribe();
+
+    const req = http.expectOne('/behandel/registrations/reg-1/decide');
+    expect(req.request.headers.get('Authorization')).toBe(`Bearer ${token}`);
+    req.flush(null);
+  });
+
+  it('leaves the anonymous openbaar register call unauthenticated', () => {
+    bff.getOpenbaarRegister().subscribe();
+
+    const req = http.expectOne((r) => r.url === '/openbaar/register');
+    expect(req.request.headers.has('Authorization')).toBe(false);
+    req.flush([]);
+  });
+});

apps/behandel/src/app/app.config.ts

@@ -0,0 +1,39 @@
+import { provideHttpClient, withInterceptors } from '@angular/common/http';
+import { ApplicationConfig, provideBrowserGlobalErrorListeners } from '@angular/core';
+import { provideRouter } from '@angular/router';
+import { authInterceptor, provideMedewerkerAuth } from 'auth';
+import { appRoutes } from './app.routes';
+
+/** Environment-specific settings fetched from /config.json at startup (see main.ts). */
+export interface RuntimeConfig {
+  /** The Keycloak `medewerker` realm issuer as the browser reaches it (dev: localhost; compose: keycloak:8080). */
+  authority: string;
+}
+
+/**
+ * Route prefixes whose requests carry the medewerker token. These MUST match the **relative** URLs
+ * the api-client actually calls (same-origin via the nginx proxy) — the interceptor matches on
+ * `req.url`, which stays relative, so an absolute origin would never match and the token would go
+ * unattached. Only `/behandel/` is secured; the app calls no other endpoint group.
+ */
+export const SECURE_API_ROUTES = ['/behandel/'];
+
+/**
+ * Build the app providers from runtime config. `redirectUrl` is the app's own origin (where Keycloak
+ * redirects back). `secureRoutes` uses {@link SECURE_API_ROUTES} — relative prefixes, not the origin.
+ */
+export function appConfig(runtime: RuntimeConfig): ApplicationConfig {
+  const origin = typeof window !== 'undefined' ? window.location.origin : '/';
+  return {
+    providers: [
+      provideBrowserGlobalErrorListeners(),
+      provideRouter(appRoutes),
+      provideHttpClient(withInterceptors([authInterceptor()])),
+      provideMedewerkerAuth({
+        authority: runtime.authority,
+        redirectUrl: origin,
+        secureRoutes: SECURE_API_ROUTES,
+      }),
+    ],
+  };
+}

apps/behandel/src/app/app.html

@@ -0,0 +1 @@
+<router-outlet></router-outlet>

apps/behandel/src/app/app.routes.ts

@@ -0,0 +1,7 @@
+import { Route } from '@angular/router';
+import { authenticatedGuard } from 'auth';
+import { WerkbakPage } from './werkbak/werkbak-page';
+
+export const appRoutes: Route[] = [
+  { path: '', component: WerkbakPage, canActivate: [authenticatedGuard] },
+];

apps/behandel/src/app/app.spec.ts

@@ -0,0 +1,15 @@
+import { provideRouter } from '@angular/router';
+import { render, screen } from '@testing-library/angular';
+import { App } from './app';
+
+describe('App', () => {
+  it('renders the router outlet shell', async () => {
+    const { container } = await render(App, {
+      providers: [provideRouter([])],
+    });
+
+    // The shell is a thin host for routed pages (the WerkbakPage owns the heading).
+    expect(container.querySelector('router-outlet')).toBeTruthy();
+    expect(screen).toBeTruthy();
+  });
+});

apps/behandel/src/app/app.ts

@@ -0,0 +1,12 @@
+import { Component } from '@angular/core';
+import { RouterModule } from '@angular/router';
+
+@Component({
+  imports: [RouterModule],
+  selector: 'app-root',
+  templateUrl: './app.html',
+  styleUrl: './app.css',
+})
+export class App {
+  protected title = 'behandel';
+}

apps/behandel/src/app/werkbak/werkbak-page.html

@@ -0,0 +1,64 @@
+<main utrecht-document class="utrecht-theme">
+  <utrecht-article>
+    <utrecht-heading-1>Werkbak</utrecht-heading-1>
+    <p utrecht-paragraph>
+      Registraties die wachten op beoordeling. Keur elke registratie goed of wijs deze af.
+    </p>
+
+    @if (loading()) {
+      <p utrecht-paragraph role="status">Bezig met laden…</p>
+    } @else if (failed()) {
+      <p utrecht-paragraph role="alert">
+        Kon de werkbak niet laden. Controleer of je als behandelaar bent ingelogd en probeer het
+        opnieuw.
+      </p>
+    } @else if (loaded() && items().length === 0) {
+      <p utrecht-paragraph role="status">De werkbak is leeg.</p>
+    } @else if (items().length > 0) {
+      <table utrecht-table>
+        <caption>
+          Registraties in behandeling
+        </caption>
+        <thead>
+          <tr>
+            <th scope="col">Referentie</th>
+            <th scope="col">BSN</th>
+            <th scope="col">Status</th>
+            <th scope="col">Actie</th>
+          </tr>
+        </thead>
+        <tbody>
+          @for (item of items(); track item.registrationId) {
+            <tr>
+              <td>{{ item.registrationId }}</td>
+              <td>{{ item.bsn }}</td>
+              <td>{{ item.status }}</td>
+              <td>
+                <button
+                  utrecht-button
+                  appearance="primary-action-button"
+                  type="button"
+                  [attr.aria-label]="'Goedkeuren ' + item.registrationId"
+                  [disabled]="deciding() === item.registrationId"
+                  (click)="decide(item.registrationId, 'goedkeuren')"
+                >
+                  Goedkeuren
+                </button>
+                <button
+                  utrecht-button
+                  appearance="secondary-action-button"
+                  type="button"
+                  [attr.aria-label]="'Afwijzen ' + item.registrationId"
+                  [disabled]="deciding() === item.registrationId"
+                  (click)="decide(item.registrationId, 'afwijzen')"
+                >
+                  Afwijzen
+                </button>
+              </td>
+            </tr>
+          }
+        </tbody>
+      </table>
+    }
+  </utrecht-article>
+</main>

apps/behandel/src/app/werkbak/werkbak-page.spec.ts

@@ -0,0 +1,110 @@
+import { signal } from '@angular/core';
+import { fireEvent, render, screen } from '@testing-library/angular';
+import { of, throwError } from 'rxjs';
+import { BffApiV1Service, type WerkbakItem } from 'api-client';
+import { AuthService } from 'auth';
+import { axe } from 'vitest-axe';
+import { WerkbakPage } from './werkbak-page';
+
+const sample: WerkbakItem[] = [
+  { registrationId: 'reg-1', bsn: '123456782', status: 'InBehandeling' },
+  { registrationId: 'reg-2', bsn: '111222333', status: 'InBehandeling' },
+];
+
+class FakeAuth extends AuthService {
+  readonly isAuthenticated = signal(true);
+  readonly bsn = signal<string | undefined>(undefined);
+  override readonly roles = signal<readonly string[]>(['behandelaar']);
+  login(): void {
+    /* not exercised here */
+  }
+  logout(): void {
+    /* spied in tests */
+  }
+}
+
+function setup(
+  overrides: {
+    getBehandelWerkbak?: ReturnType<typeof vi.fn>;
+    postBehandelRegistrationsIdDecide?: ReturnType<typeof vi.fn>;
+  } = {},
+) {
+  const getBehandelWerkbak =
+    overrides.getBehandelWerkbak ?? vi.fn().mockReturnValue(of(sample));
+  const postBehandelRegistrationsIdDecide =
+    overrides.postBehandelRegistrationsIdDecide ?? vi.fn().mockReturnValue(of(undefined));
+  return {
+    getBehandelWerkbak,
+    postBehandelRegistrationsIdDecide,
+    providers: [
+      {
+        provide: BffApiV1Service,
+        useValue: { getBehandelWerkbak, postBehandelRegistrationsIdDecide },
+      },
+      { provide: AuthService, useClass: FakeAuth },
+    ],
+  };
+}
+
+describe('WerkbakPage', () => {
+  it('lists the registrations awaiting beoordeling on open', async () => {
+    const { getBehandelWerkbak, providers } = setup();
+    await render(WerkbakPage, { providers });
+
+    expect(getBehandelWerkbak).toHaveBeenCalled();
+    expect(await screen.findByText('reg-1')).toBeTruthy();
+    expect(screen.getByText('123456782')).toBeTruthy();
+    expect(screen.getByText('reg-2')).toBeTruthy();
+  });
+
+  it('approves a registration (goedkeuren) and refreshes the werkbak', async () => {
+    const { getBehandelWerkbak, postBehandelRegistrationsIdDecide, providers } = setup();
+    await render(WerkbakPage, { providers });
+
+    fireEvent.click((await screen.findAllByRole('button', { name: /goedkeuren/i }))[0]);
+
+    expect(postBehandelRegistrationsIdDecide).toHaveBeenCalledWith('reg-1', {
+      besluit: 'goedkeuren',
+    });
+    // Reloaded after the decision: once on open, once after deciding.
+    expect(getBehandelWerkbak).toHaveBeenCalledTimes(2);
+  });
+
+  it('rejects a registration (afwijzen) via the decide endpoint', async () => {
+    const { postBehandelRegistrationsIdDecide, providers } = setup();
+    await render(WerkbakPage, { providers });
+
+    fireEvent.click((await screen.findAllByRole('button', { name: /afwijzen/i }))[0]);
+
+    expect(postBehandelRegistrationsIdDecide).toHaveBeenCalledWith('reg-1', {
+      besluit: 'afwijzen',
+    });
+  });
+
+  it('shows an empty state when the werkbak has no items', async () => {
+    const { providers } = setup({ getBehandelWerkbak: vi.fn().mockReturnValue(of([])) });
+    await render(WerkbakPage, { providers });
+
+    expect(await screen.findByText(/werkbak is leeg/i)).toBeTruthy();
+  });
+
+  it('surfaces a load failure instead of swallowing it', async () => {
+    const { providers } = setup({
+      getBehandelWerkbak: vi.fn().mockReturnValue(throwError(() => new Error('403'))),
+    });
+    await render(WerkbakPage, { providers });
+
+    expect(await screen.findByText(/kon de werkbak niet laden/i)).toBeTruthy();
+  });
+
+  it('has no WCAG 2.1 AA violations', async () => {
+    document.documentElement.lang = 'nl';
+    const { container } = await render(WerkbakPage, { providers: setup().providers });
+
+    const results = await axe(container, {
+      runOnly: { type: 'tag', values: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'] },
+    });
+
+    expect(results.violations).toEqual([]);
+  });
+});

apps/behandel/src/app/werkbak/werkbak-page.ts

@@ -0,0 +1,65 @@
+import { Component, inject, signal } from '@angular/core';
+import { BffApiV1Service, type WerkbakItem } from 'api-client';
+import { UtrechtComponentsModule } from 'ui';
+
+/** The two decisions a behandelaar can make; the BFF validates these exact values (ADR-0013). */
+type Besluit = 'goedkeuren' | 'afwijzen';
+
+/**
+ * The behandel werkbak: a signed-in behandelaar sees the registrations awaiting beoordeling (the open
+ * Flowable `Beoordelen` tasks, read through the domain) and decides each — goedkeuren or afwijzen. A
+ * decision posts to the BFF, which applies the domain transition and completes the workflow task
+ * (ADR-0013; S-12). After a decision the werkbak refreshes so the handled item drops off the list.
+ */
+@Component({
+  selector: 'app-werkbak-page',
+  imports: [UtrechtComponentsModule],
+  templateUrl: './werkbak-page.html',
+})
+export class WerkbakPage {
+  private readonly bff = inject(BffApiV1Service);
+
+  protected readonly items = signal<WerkbakItem[]>([]);
+  protected readonly loading = signal(false);
+  protected readonly loaded = signal(false);
+  protected readonly failed = signal(false);
+  protected readonly deciding = signal<string | undefined>(undefined);
+
+  constructor() {
+    this.load();
+  }
+
+  load(): void {
+    this.loading.set(true);
+    this.failed.set(false);
+    this.bff.getBehandelWerkbak().subscribe({
+      next: (rows: WerkbakItem[]) => {
+        this.items.set(rows);
+        this.loading.set(false);
+        this.loaded.set(true);
+      },
+      // Surface the failure (e.g. 403 for a non-behandelaar) instead of swallowing it.
+      error: () => {
+        this.items.set([]);
+        this.loading.set(false);
+        this.loaded.set(true);
+        this.failed.set(true);
+      },
+    });
+  }
+
+  decide(registrationId: string, besluit: Besluit): void {
+    this.deciding.set(registrationId);
+    this.bff.postBehandelRegistrationsIdDecide(registrationId, { besluit }).subscribe({
+      // Refresh so the decided registration drops off the werkbak (its task is now completed).
+      next: () => {
+        this.deciding.set(undefined);
+        this.load();
+      },
+      error: () => {
+        this.deciding.set(undefined);
+        this.failed.set(true);
+      },
+    });
+  }
+}

apps/behandel/src/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="nl">
+  <head>
+    <meta charset="utf-8" />
+    <title>Behandelportaal BIG-register</title>
+    <base href="/" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link rel="icon" type="image/x-icon" href="favicon.ico" />
+  </head>
+  <body>
+    <app-root></app-root>
+  </body>
+</html>

apps/behandel/src/main.ts

@@ -0,0 +1,10 @@
+import { bootstrapApplication } from '@angular/platform-browser';
+import { App } from './app/app';
+import { appConfig, type RuntimeConfig } from './app/app.config';
+
+// Load environment config before bootstrap so the OIDC authority is set per environment
+// (dev: localhost; compose: keycloak:8080) from a single build — 12-factor (S-08d).
+fetch('config.json')
+  .then((response) => response.json() as Promise<RuntimeConfig>)
+  .then((config) => bootstrapApplication(App, appConfig(config)))
+  .catch((err) => console.error(err));

apps/behandel/src/styles.css

@@ -0,0 +1,2 @@
+/* NL Design System theme — Utrecht design tokens (docs/frontend-decisions.md). */
+@import '@utrecht/design-tokens/dist/index.css';