Initial GeoIntel V1 foundation

docs/DATA_SPECIFICATION.md

@@ -0,0 +1,301 @@
+# Data Specification v1.0
+
+## 1. Principes
+
+GeoIntel werkt documentatiegedreven met expliciete data-contracten.
+
+Elke dataset krijgt:
+
+- bron
+- type
+- formaat
+- CRS
+- bounds
+- resolutie of schaal
+- licentie
+- updatefrequentie
+- gebruiksdoel
+- cache-strategie
+- kwaliteitsstatus
+
+## 2. Kernbronnen
+
+## GRB — Basiskaart Vlaanderen
+
+### Rol
+
+GRB is een primaire referentiebron voor Vlaanderen. Voor GeoIntel is GRB belangrijker dan OSM wanneer officiële referentiegeometrieën nodig zijn.
+
+### Gebruik
+
+- referentiegebouwen
+- wegen en terreinobjecten
+- QA/QC tegenover AI-detecties
+- validatie van gebouwdetectie
+- vergelijking met eigen detecties of segmentaties
+
+### Type
+
+Vector.
+
+### Mogelijke toegang
+
+- WFS per gebied
+- downloadpakketten
+- periodieke PostGIS-cache
+
+### Cache-strategie
+
+Voor V1 is een gebiedsgerichte cache het beste:
+
+1. gebruiker selecteert gebied
+2. backend vraagt relevante GRB-lagen op
+3. geometrieën worden opgeslagen in PostGIS
+4. analysis runs verwijzen naar de gecachete versie
+
+### Belangrijk voor QA/QC
+
+GRB-gebouwpolygonen worden gebruikt als ground-truth proxy. Niet absoluut perfect, maar zeer bruikbaar als officiële referentie.
+
+## Gebouwenregister
+
+### Rol
+
+Aanvullende gebouwinformatie bij geometrieën.
+
+### Gebruik
+
+- gebouwmetadata
+- identificatie
+- status
+- koppeling met GRB-gebouwpolygonen indien mogelijk
+
+### Type
+
+Vector/API/metadata.
+
+### Prioriteit
+
+V2 of V1.5.
+
+## OpenStreetMap
+
+### Rol
+
+Snelle open referentiedata, nuttig als fallback en voor POI's.
+
+### Gebruik
+
+- gebouwen indien GRB nog niet beschikbaar is
+- wegen
+- water
+- landuse
+- POI's
+- demo- en fallbackdata
+
+### Type
+
+Vector.
+
+### Toegang
+
+- Overpass API
+- pyrosm/osmnx
+- lokale extracten
+
+### Cache-strategie
+
+Opslaan per project/area in PostGIS.
+
+## Sentinel-2
+
+### Rol
+
+Remote sensing bron voor vegetatie, water en bebouwingsindices.
+
+### Gebruik
+
+- NDVI
+- NDWI
+- NDBI
+- seizoensvergelijking
+- trendanalyse
+- change detection
+
+### Type
+
+Raster multispectral.
+
+### Prioriteit
+
+V2.
+
+## DHMV / Hoogtemodel Vlaanderen
+
+### Rol
+
+Hoogtedata voor terrein- en watergevoeligheidsanalyse.
+
+### Gebruik
+
+- DEM
+- DSM
+- helling
+- laagste punten
+- hoogteprofiel
+- gebouwhoogte-inschatting indien DSM + gebouwpolygonen beschikbaar zijn
+
+### Type
+
+Raster / afgeleid van LiDAR.
+
+### Prioriteit
+
+V3.
+
+## LAS/LAZ LiDAR
+
+### Rol
+
+Advanced module voor puntenwolkanalyse.
+
+### Gebruik
+
+- puntenwolk metadata
+- clipping
+- classificatie
+- DEM/DSM generatie
+- hoogteprofielen
+
+### Tools
+
+- PDAL
+- laspy
+
+### Prioriteit
+
+V4/V5.
+
+## 3. Dataset Types
+
+### Raster
+
+Ondersteund:
+
+- GeoTIFF
+- TIFF
+- JPEG2000 later
+- PNG/JPG met worldfile later
+
+Metadata:
+
+- CRS
+- transform
+- bounds
+- width/height
+- band count
+- dtype
+- nodata
+- resolution
+
+### Vector
+
+Ondersteund:
+
+- GeoJSON
+- Shapefile
+- GPKG
+- WFS-resultaten
+
+Metadata:
+
+- CRS
+- bounds
+- geometry type
+- feature count
+- attributes
+- validity summary
+
+### Model outputs
+
+Ondersteund:
+
+- bounding boxes
+- polygons
+- masks
+- confidence scores
+- class labels
+- source tile reference
+
+## 4. Data Quality Requirements
+
+Elke dataset moet bij intake minimaal controleren:
+
+- bestand leesbaar
+- CRS aanwezig of expliciet onbekend
+- geometrieën geldig of herstelbaar
+- bounds binnen verwacht gebied
+- raster heeft bruikbare resolutie
+- geen lege lagen
+- opslagpad bestaat
+
+## 5. Data Lineage
+
+Elke output moet kunnen terugwijzen naar:
+
+- bronbestand
+- processing step
+- analysis run
+- modelversie
+- parameters
+- tijdstip
+- eventuele referentielaag
+
+## Sprint 7B Provider Contracts
+
+Sprint 7B makes provider architecture operationally visible without performing live external fetches.
+
+### GRB
+
+- provider_name: `grb`
+- authority_level: `authoritative`
+- configured: `false`
+- status: `not_configured`
+- supported_layers: `buildings`, `roads`, `parcels`
+- supported_geometry_types: `Polygon`, `MultiPolygon`, `LineString`, `MultiLineString`
+- supported_query_modes: `area`
+- dataset mapping: `dataset_role=reference`, `source_name=grb`
+- write path: future provider output must flow through `DatasetService` and `VectorFeatureService`
+- limitation: no live WFS call, no download, no fake GRB data in Sprint 7B
+
+### OSM
+
+- provider_name: `osm`
+- authority_level: `contextual`
+- configured: `false`
+- status: `not_configured`
+- supported_layers: `buildings`, `roads`, `water`, `landuse`
+- supported_geometry_types: `Polygon`, `MultiPolygon`, `LineString`, `MultiLineString`
+- supported_query_modes: `area`
+- default dataset mapping: `dataset_role=source`, `source_name=osm`
+- explicit reference mapping: `dataset_role=reference`, `source_name=osm`
+- write path: future provider output must flow through `DatasetService` and `VectorFeatureService`
+- limitation: no live Overpass call, no download, no fake OSM data in Sprint 7B
+
+### Manual
+
+- provider_name: `manual`
+- authority_level: `manual`
+- configured: `true`
+- status: `configured`
+- dataset mapping: `dataset_role=reference`, `source_name=manual`
+- write path: existing dataset upload/reference flow
+
+### Fixture
+
+- provider_name: `fixture`
+- authority_level: `fixture`
+- configured: `true`
+- status: `configured`
+- dataset mapping: `dataset_role=reference`, `source_name=fixture`
+- write path: checked-in demo/test fixture flow