Initial public release

docs/PROJECT_PROFESSIONALIZATION_AUDIT_2026-07-27.md

@@ -0,0 +1,185 @@
+# GeoIntel professionaliseringsaudit — 27 juli 2026
+
+## Managementsamenvatting
+
+GeoIntel is inhoudelijk veel sterker dan de eerste visuele indruk deed
+vermoeden. De repository bevat een volwassen, documentatiegestuurde
+GIS-architectuur, expliciete bron- en provenancecontracten, uitgebreide
+kwaliteitscontrole en een product dat bewust geen resultaten fabriceert wanneer
+brondata of modellen ontbreken. De grootste productrisico's zaten niet in de
+GIS-kern, maar in de toegangservaring, de presentatie van de functiedichtheid
+en de gegroeide frontend-stijllagen.
+
+Deze pass professionaliseert de eerste gebruikerservaring en voegt een veilige
+gastdemonstratie toe. Een bezoeker kan nu rechtstreeks vanaf de landingspagina
+een tijdelijke demowerkruimte openen. Die sessie is server-side aan één
+voorbeeldproject gebonden, heeft een kortere levensduur en kan geen
+operatorwijzigingen uitvoeren. De interface toont in gastmodus alleen de kaart
+en bestaand kwaliteitsbewijs.
+
+## Wat al sterk was
+
+- **Inhoudelijke geloofwaardigheid.** Officiële bronnen, meeteenheden, CRS,
+  dekking, beperkingen en provenance worden als productgegevens behandeld en
+  niet als decoratieve metadata.
+- **Fail-closed gedrag.** Niet-geconfigureerde bronnen en modellen worden niet
+  stilzwijgend vervangen door fixtures of gesimuleerd succes.
+- **Map-first productmodel.** Project, gebied, dataset, analyse en QA delen een
+  ruimtelijke context, wat veel sterker is dan een verzameling losse dashboards.
+- **Operationele discipline.** De repository bevat releasegates, Unraid-assets,
+  migraties, herstelpaden, tests en expliciete scope-/beperkingsdocumentatie.
+- **Bestaande demofundering.** Het idempotente demoworkflowcontract maakte een
+  gecontroleerde gastbeleving mogelijk zonder een tweede fictieve applicatie te
+  bouwen.
+
+## Belangrijkste bevindingen
+
+### P0 — Er ontbrak een toegankelijke productdemo
+
+De oorspronkelijke ingang bood alleen een operatorlogin. Voor een recruiter,
+stakeholder of eerste beoordelaar was daardoor niet zichtbaar wat het platform
+kan zonder vooraf accounts of wachtwoorden uit te wisselen. Een onbegrensde
+“login zonder wachtwoord” zou echter toegang tot operationele functies hebben
+gegeven.
+
+**Oplossing:** een config-gated `POST /api/v1/auth/guest`, een gesigneerde
+gastrol met projectscope, server-side mutatieblokkering en een expliciete knop
+**Als gast verkennen**. De demo wordt bij openen idempotent voorbereid.
+
+### P1 — De landingspagina communiceerde de productwaarde onvoldoende snel
+
+De informatie was aanwezig, maar de primaire actie, productbelofte,
+betrouwbaarheidssignalen en demonstratiemogelijkheid concurreerden visueel met
+elkaar. Op kleinere schermen voelde de ingang langer en minder doelgericht.
+
+**Oplossing:** nieuwe hero- en loginhiërarchie, heldere keuze tussen operator en
+gast, compactere capability-sectie, concreter vierstappenproces, betere mobiele
+navigatie en begrijpelijke foutmeldingen in plaats van ruwe servicefouten.
+
+### P1 — De workbench was voor een gast te breed en te technisch
+
+De volledige operatornavigatie bevat projectbeheer, imports, AI-taken, exports
+en geavanceerde analyses. Dat is gepast voor een beheerder, maar werkt tegen een
+snelle demonstratie.
+
+**Oplossing:** de gastrol ziet alleen **Kaart** en **Kwaliteit**, krijgt een
+blijvende alleen-lezen contextbanner en ziet geen creatie-, import-, export-,
+AI- of beheeracties. De backend blijft de autoritatieve grens.
+
+### P1 — De visuele laag is historisch gegroeid
+
+Vier opeenvolgende workbench-stijlbestanden bevatten samen 13.818 regels CSS:
+`app.css`, `premium.css`, `atlas-workbench.css` en `atlas-premium-v2.css`. Over
+de volledige actieve stijllaag zijn tientallen mediaqueries aanwezig. Dat
+verhoogt de kans op cascadeconflicten, onverwachte responsive afwijkingen en
+onnodig moeilijke toekomstige aanpassingen.
+
+**Oplossing in deze pass:** een kleine, als laatste geladen
+`professionalization.css` met gerichte correcties voor navigatierail, contextbalk,
+werkruimtehoogte, gaststatus, truncation en responsive gedrag. De historische
+lagen zijn bewust niet massaal herschreven zonder volledige visuele
+regressiebaseline.
+
+**Aanbevolen vervolgstap:** component voor component consolideren naar tokens,
+layout primitives en één stylesheet per functioneel domein, telkens beschermd
+door desktop-, ultrawide- en mobiele screenshots.
+
+### P2 — Twee frontendcomponenten dragen te veel verantwoordelijkheid
+
+`App.tsx` telt circa 1.400 regels en `MapWorkspace.tsx` circa 3.900 regels. Dat
+is nog werkbaar, maar maakt layout-, permissie- en interactiewijzigingen
+risicovoller dan nodig.
+
+**Aanbevolen vervolgstap:** splits shell/navigatie, workspace-routing,
+gastsessiecontext, kaartselectie, bronresolutie en analysepresentatie in
+afzonderlijke domeincomponenten en hooks. Doe dit pas na de huidige
+regressietests, zodat gedrag niet tegelijk met structuur wordt gewijzigd.
+
+### P2 — Gastmodus is geen tenantisolatie
+
+De sessie is cryptografisch gesigneerd, kort geldig, projectgebonden en
+alleen-lezen. Toch blijft GeoIntel architecturaal een single-operatorproduct. De
+gastrol is bedoeld voor een aparte demo-installatie, niet om operationele en
+publieke gebruikers veilig in dezelfde datastore te mengen.
+
+## Geleverde wijzigingen
+
+| Domein | Professionalisering |
+|---|---|
+| Toegang | Nieuwe gastactie, wachtwoordzichtbaarheid, heldere operator/gastkeuze en bruikbare foutmeldingen |
+| Sessies | Versie 2-sessietoken met expliciete `operator`/`guest`-rol, TTL en optionele projectscope |
+| Backendgrens | Positieve read-allowlist, gastprojectfilter, cross-projectblokkering en mutatieblokkering met stabiele foutcodes |
+| Demo | Canonieke demoworkflow wordt idempotent voorbereid bij gastlogin |
+| Workbench | Gereduceerde gastnavigatie, alleen-lezen statusbanner en verborgen beheerfuncties |
+| Kaart | Alleen-lezen variant zonder on-demand acquisitie of geavanceerde operatorcontrole |
+| Layout | Rustigere desktop-shell, betere truncation, responsieve gaststatus en reduced-motion ondersteuning |
+| Deployment | Gastvariabelen in Compose, Unraid-env, DockerMan-template en runtimevalidatie |
+| Documentatie | API-contract, README, Unraid-instructies, beperkingen, TODO en uitvoeringslog bijgewerkt |
+
+## Configuratie
+
+Gasttoegang staat standaard ingeschakeld zodra de operator-login actief is.
+Voor een afzonderlijke demo-installatie:
+
+```env
+GEOINTEL_AUTH_ENABLED=true
+GEOINTEL_AUTH_USERNAME=operator
+GEOINTEL_AUTH_PASSWORD_HASH=pbkdf2_sha256$...
+GEOINTEL_AUTH_SESSION_SECRET=<minstens-32-willekeurige-tekens>
+GEOINTEL_GUEST_ACCESS_ENABLED=true
+GEOINTEL_GUEST_DISPLAY_NAME=Gast
+GEOINTEL_GUEST_SESSION_TTL_SECONDS=7200
+```
+
+Zet `GEOINTEL_GUEST_ACCESS_ENABLED=false` om gasttoegang expliciet uit te schakelen.
+Gebruik een afzonderlijke container, database en storage-root wanneer de demo
+van buiten het vertrouwde LAN bereikbaar wordt. Plaats geen private, klant- of
+operationele datasets in die omgeving.
+
+## Validatie
+
+De volgende controles zijn op 27 juli 2026 uitgevoerd:
+
+| Controle | Resultaat |
+|---|---|
+| Gerichte backend auth-/gastbeveiligingstests | **Geslaagd — 6/6** |
+| Python compile van `backend/app` en de nieuwe authtests | **Geslaagd** |
+| Volledige frontend TypeScript-typecheck | **Geslaagd** |
+| Gerichte frontend-interactiesmokes: gast/operator-login en beperkte bootstrap | **Geslaagd — 2/2** |
+| CSS-syntax van de vernieuwde landing en professionaliseringslaag | **Geslaagd** |
+| Compose YAML, Unraid XML en DockerMan-shellsyntax | **Geslaagd** |
+| Whitespacecontrole op alle in deze pass gewijzigde bestanden | **Geslaagd** |
+
+De gerichte backendtests draaiden met SQLite en een tijdelijke minimale
+`geoalchemy2`-importstub buiten de repository, omdat de reviewcontainer de
+PostGIS-runtimepackages niet bevatte. Daarmee zijn tokenvalidatie, cookies,
+login/logout, gastscope, cross-projectblokkering en route-/mutatieblokkering
+wel rechtstreeks getest; het is geen vervanging voor de bestaande volledige
+PostgreSQL/PostGIS-integratiegate.
+
+De nieuwe logincomponent en de beperkte workbench-bootstrap zijn aanvullend
+rechtstreeks in JSDOM uitgevoerd via een tijdelijke TypeScript-loader buiten de
+repository. Daarmee zijn de zichtbaarheid van gastacties, de `POST` naar de
+gastendpoint, de operatorlogin en het uitschakelen van operator-only
+bootstrapcalls interactief gecontroleerd.
+
+De aangeleverde `node_modules` bevat alleen Windows-native Rollup- en
+esbuildpakketten. Daardoor konden de normale Vitest-runner en de
+Vite-productiebundel in deze Linux-reviewcontainer niet starten. Een schone
+dependency-installatie was niet mogelijk doordat de beschikbare packageproxy
+tijdens de controle 503-responses en time-outs gaf. De TypeScript-compiler voltooide wel zonder fouten. De
+frontend-unit- en productiebuildgates moeten daarom na `npm ci` op Windows of
+in de normale Linux CI-/Dockeromgeving nogmaals worden uitgevoerd.
+
+## Aanbevolen roadmap
+
+1. Leg visuele regressiesnapshots vast voor login, kaart, kwaliteit en alle
+   primaire workspaces op mobiel, desktop en ultrawide.
+2. Consolideer de vier historische workbench-CSS-lagen incrementeel; verwijder
+   pas selectors nadat screenshots en interactietests gelijkwaardig zijn.
+3. Splits `App.tsx` en `MapWorkspace.tsx` langs domeingrenzen, zonder API- of
+   analysegedrag te wijzigen.
+4. Voeg een expliciete demo-reset/refreshstrategie en misbruiktelemetrie toe
+   wanneer de demo publiek wordt blootgesteld.
+5. Bouw alleen bij echte multi-userbehoefte een afzonderlijk identiteits-,
+   autorisatie- en tenantmodel; breid gastmodus daar niet ad hoc voor uit.