# Stitch-integratieplan

## Auditbaseline

De ontvangen ZIP `stitch_vacatureradar_intelligence_cockpit.zip` is geïnventariseerd en bytegelijk aan de blijvende referenties onder `docs/design/stitch-reference/`. Er is geen afzonderlijke aanvullende `design.md` aangetroffen. De referenties worden niet als runtimefrontend geserveerd en zijn via `.dockerignore` uit de productieimage gehouden.

| Stitch-scherm | Afmeting | Dominante compositie | Productieroute / template |
| --- | ---: | --- | --- |
| Dashboard overzicht | 1480×1600 | KPI-strip, brede matchfeed, actie-/activiteitsrail | `/` · `dashboard/today.html` |
| Nieuwe matches | 1600×1550 | filterbar, masterlijst en geselecteerde intelligence | `/jobs/` · `jobs/list.html` |
| Vacature intelligence detail | 1600×1525 | hero, scorepaneel, inhoudtabs, intelligence-rail en actiedock | `/jobs/<uuid>/` · `jobs/detail.html` |
| Sollicitatie pipeline | 1600×1280 | horizontale kanban met lijsttoggle | `/jobs/applications/` · `applications/list.html` |
| Zoekprofiel editor | 1600×1280 | configuratiestappen met vaste radarpreview | `/profiles/<id>/` · `profiles/edit.html` |
| Bronnenbeheer & gezondheid | 1600×1340 | bronstatusrijen, disclosures en integriteitspanelen | `/sources/` · `sources/list.html` |
| Automatisering centrum | 1540×1600 | pipelinefasen, operationele KPI's, brontabel en lograil | `/system/` · `system/status.html` |
| Activiteitenlogboek | 1600×1441 | filterbare technische tijdlijn met samenvatting | `/jobs/activity/` · `activity/list.html` |
| Werkgevers intelligence | 1600×931 | employer table met intelligence-detailrail | `/jobs/employers/` en `/jobs/employers/<id>/` · employer templates |

## Tokens en herbruikbare bouwstenen

De negen HTML-referenties gebruiken dezelfde palette- en typografieschaal: darkest/surface `#060e20`/`#0b1326`, vijf tonale containers, Signal Cyan `#00f5ff`, Emerald `#4edea3`, lichte hoofdtekst `#dae2fd`, gedempte tekst `#b9caca`, koraal `#ffb4ab`, 8px basisritme en 2–8px radii. Headings zijn 20/32px, body 14/16px en metadata 12/13px mono. Productie vertaalt dit naar CSS custom properties en lokale SVG's.

Herbruikbare componenten: app-shell, nav-link, contextbar, page-heading, KPI-tile, tonal-panel, status-chip, score-ring/tile, data-table, intelligence-rail, timeline-event, filterbar/drawer, disclosure, empty state, form-section, sticky action dock en mobile bottom navigation. De componenten dragen semantiek; paginatemplates leveren alleen domeindata en compositie.

## Data- en routeaudit

| Component | Echte databron / service | Ontbrekend of aangepaste presentatie |
| --- | --- | --- |
| Dag-KPI's en beste matches | `JobPosting`, laatste `ScoreRun`, `Application`, `SourceRun`; nieuwe cockpit-queryservice | Geen fictieve trendpercentages; onbekende meting krijgt tekststatus. |
| Verkenner | `JobPosting` met laatste profielscore, relevance-query, filters en paginering | Stitch quick-apply wordt detail/dossier/externe bronactie. |
| Detailintelligence | `ScoreRun`, `JobSourceAlias`, `FieldProvenance`, `JobVersion`, `Feedback`, `Application` | Geen ervarings-/senioriteitsscore; geen kaart of salaris wanneer onbekend. |
| Pipeline | gebruikersgescopeerde `Application` en `ApplicationTimelineEvent` | Geen drag-and-dropvereiste; statuswijziging krijgt toegankelijke POST-selectie. |
| Radarconfiguratie | `SearchProfileForm`, profielrevisies, laatste scores | Preview is server-rendered uit laatste echte match; geen demo-vacature. |
| Brongezondheid | `Source`, laatste `SourceRun`, `collect_source_health`, mailboxverbindingen | Geen algemene healthyclaim zonder runbewijs; technische fouttekst begrensd. |
| Automatisering | readiness, `SourceRun`, jobs, scores, notificatie-outbox en configuratie | Uptime/worker/AI/browserstatus alleen indien afleidbaar, anders niet geconfigureerd. |
| Activiteit | nieuwe queryservice over `SourceRun`, `JobVersion`, `Feedback`, `ApplicationTimelineEvent`, outbox en `ProfileRevision` | Modellen vormen één read-only tijdlijn; geen nieuw generiek auditmodel nodig. |
| Werkgevers | nieuwe queryservice over `Employer`, jobs, scores, aliases, sources en applications | Sector/locatie/notities alleen indien opgeslagen; geen CRM- of contactpersoonfinder. |

De twee nieuwe domeinervaringen worden read-only geïmplementeerd in `apps/jobs/services/activity.py` en `apps/jobs/services/employer_intelligence.py`. Dit houdt aggregatielogica uit views en vermijdt een migratie. Querysets gebruiken annotaties, `select_related`, `prefetch_related` en begrensde lijsten om N+1 te voorkomen.

## Fidelitymatrix

| Scherm | Stitch-element | Echte implementatie | Fidelitydoel | Noodzakelijke aanpassing | Verificatie |
| --- | --- | --- | --- | --- | --- |
| Dashboard | vier KPI's + matchfeed + rail | actuele job/score/source/application-aggregaties | zeer hoog | trends alleen bij meetbaar tijdvenster | desktop/mobile screenshot + contexttests |
| Nieuwe matches | split explorer | gepagineerde serverlijst met geselecteerd echt resultaat | zeer hoog | URL blijft deelbaar; geen SPA-state | filters/back/pagination tests + screenshot |
| Detail | hero, score rail, tabs, dock | scorebewijs, provenance, versies, veilige acties | hoog | geen nepbeeld, quick apply of ervaringseffect | safe-link/sanitization tests + screenshots |
| Pipeline | kanban + lijsttoggle | statuskolommen en echte POST statusselectie | zeer hoog | geen drag-and-drop als enige invoer | POST/user-scope tests + screenshot |
| Zoekprofiel | secties + live preview | gegroepeerde widgets en laatste echte match | hoog | preview ververst na server-save | form/revision tests + screenshot |
| Bronnen | health rows + details | bronkaart/tabel, runbewijs, retry en imports | zeer hoog | policy/securityflows blijven zichtbaar | retry/policy tests + screenshot |
| Automatisering | pipeline en logs | afgeleide fasestatus, run- en outboxtelemetrie | hoog | onbekende infrastructuur eerlijk gelabeld | view-context tests + screenshot |
| Activiteit | filtertijdlijn | gepagineerde multi-model read service | zeer hoog | alleen objecttypen met betrouwbare auditdata | filter/scope/pagination tests + screenshot |
| Werkgevers | tabel + drawer | index met geselecteerde detailrail en aparte detail-URL | zeer hoog | geen AI-contactfinder of verzonnen sector | aggregate/scope/empty tests + screenshot |

## Responsive strategie en risico's

De desktop shell gebruikt een 256px sidebar en een flexibele canvas tot ultrawide. Dashboard, explorer en detail schakelen bij 1180–1360px van twee/three-column naar gestapeld; op ultrawide worden rails vast en feeds ruimer. Kanban behoudt gecontroleerde horizontale inhoudscroll, niet paginascroll. Tabellen krijgen bij mobiel semantische kaartregels of een gelabelde scrollcontainer. De profielpreview wordt onder de editor geplaatst; de vacatureselectie opent als volledige detailkaart.

Belangrijkste accessibilityrisico's uit het prototype zijn icon-only controls, kleur-only status, lage metadata-contrastwaarden, vaste hoogtes, horizontale kanban en JavaScript-only toggles. Productie voegt namen, zichtbare statustekst, voldoende contrast, natuurlijke hoogte, keyboardbediening, serverfallbacks, focusmanagement en `prefers-reduced-motion` toe.

## Migratievolgorde en legacy-opruiming

1. Contract, tokens, icon sprite en volledig nieuwe shell.
2. Dashboard, explorer en detail plus benodigde querycontext.
3. Pipeline, zoekprofiel en bronnen zonder bestaande POST/contracts te breken.
4. Automatisering, activiteit en werkgevers met nieuwe read services/routes.
5. Login, fouttemplates, mobile/adaptive lagen, browsercontrole en accessibility.
6. Verwijder oude selectors, dubbele cards/panels, achterhaalde JS en screenshots die niet tot de huidige validatie horen; zoek alle productietemplates na op de oude shell.

`templates/base.html`, alle niet-e-mailtemplates onder `templates/`, `static/css/app.css` en `static/js/app.js` worden vervangen of fundamenteel herschikt. E-mailtemplates blijven buiten de cockpit omdat zij geen browserfrontend zijn. Named routes en bestaande formulier-/securitycontracts blijven behouden.

## Gate en artifacts

Per fase: Ruff format/check, relevante tests, diffreview en logische commit. Eindmatrix: 1440×900, 1280×800, 1024×768, 768×1024, 390×844 en 360×800; aanvullende 1920/2560px ultrawidecontrole. De elf verplichte beelden komen onder `artifacts/visual-validation/`; het eindrapport legt fidelity, afwijkingen, consolebevindingen, accessibility, queries en testresultaten vast.