82 lines
2.4 KiB
Markdown
82 lines
2.4 KiB
Markdown
# Regression Traps
|
|
|
|
This document lists common failure modes Codex must actively avoid.
|
|
|
|
## Geospatial Traps
|
|
|
|
### CRS Loss
|
|
|
|
Never store or return geometries without CRS context. GeoJSON is usually WGS84 by convention, but source CRS must still be preserved in dataset metadata.
|
|
|
|
### Bounding Box Confusion
|
|
|
|
Never mix `[minx, miny, maxx, maxy]` with `[west, south, east, north]` without explicitly naming fields.
|
|
|
|
### Area Units
|
|
|
|
Never compute area in degrees. Reproject to an appropriate projected CRS before area or distance calculations. For Flanders/Kempen, prefer Belgian Lambert 72 / EPSG:31370 for metric calculations unless a stronger reason is documented.
|
|
|
|
### Raster/Vector Alignment
|
|
|
|
Never compare raster-derived outputs with vector reference layers without documenting resolution, CRS and alignment assumptions.
|
|
|
|
### Invalid Geometry
|
|
|
|
Always validate polygons. Attempt safe fixes only when documented; otherwise return a validation error.
|
|
|
|
## AI Traps
|
|
|
|
### Confidence Is Not Accuracy
|
|
|
|
Do not present model confidence as accuracy. Accuracy requires comparison against reference or labels.
|
|
|
|
### Fixture Detection Is Not Real AI
|
|
|
|
When using fixture/stub output, label it clearly as fixture/demo mode.
|
|
|
|
### Silent Model Fallback
|
|
|
|
Never silently fall back from real model inference to fixture mode. The response must indicate the mode used.
|
|
|
|
### Mask Polygonization Noise
|
|
|
|
Segmentation polygonization must include simplification/cleanup parameters and preserve original mask path.
|
|
|
|
## Backend Traps
|
|
|
|
### Long Work in Request Thread
|
|
|
|
Do not run heavy raster/AI operations synchronously inside request handlers. Use a job boundary.
|
|
|
|
### Inconsistent Status Values
|
|
|
|
Use the frozen status enum only: `queued`, `running`, `completed`, `failed`, `cancelled`.
|
|
|
|
### File Path Leakage
|
|
|
|
API responses may expose logical storage keys or download URLs, not arbitrary host paths.
|
|
|
|
## Frontend Traps
|
|
|
|
### UI-Only State
|
|
|
|
Do not create project, area, dataset or analysis state only in frontend memory. Persist via API.
|
|
|
|
### Empty Success Screens
|
|
|
|
Every page must distinguish loading, empty, error, ready and completed states.
|
|
|
|
### Map Layer Ambiguity
|
|
|
|
Every map layer must show source, timestamp, opacity, visibility and legend where applicable.
|
|
|
|
## Documentation Traps
|
|
|
|
### TODO Instead of Decision
|
|
|
|
Do not use TODO comments for architecture gaps. Either implement, document a limitation, or ask for a decision.
|
|
|
|
### Contract Drift
|
|
|
|
If code changes API responses, update contract docs and examples in the same pass.
|