Initial public release

docs/17-max-prep/M9_BUILD_BLOCKERS_AND_RECOVERY.md

@@ -0,0 +1,101 @@
+# M9 Build Blockers and Recovery
+
+## Database connection failure
+
+Symptoms:
+
+- backend cannot connect to PostgreSQL,
+- migrations fail,
+- PostGIS extension missing.
+
+Recovery:
+
+1. Check Docker Compose service names.
+2. Check environment variables.
+3. Confirm database is reachable from backend container or local process.
+4. Run a minimal connection test.
+5. Do not replace PostGIS with SQLite except for explicitly isolated unit tests.
+
+## PostGIS geometry error
+
+Symptoms:
+
+- invalid geometry,
+- SRID missing,
+- geometry column cannot be created.
+
+Recovery:
+
+1. Store all app geometry in EPSG:4326 unless a processing-specific CRS is required.
+2. Validate GeoJSON before persistence.
+3. Use Shapely for geometry validation.
+4. Use PostGIS geometry column for persistent area/reference features.
+5. Document any CRS transformation.
+
+## Frontend API mismatch
+
+Symptoms:
+
+- UI expects raw data but API returns envelope,
+- errors not shown,
+- undefined data states.
+
+Recovery:
+
+1. Update frontend API client, not individual components.
+2. Normalize envelope handling centrally.
+3. Ensure every component handles loading, empty, error and ready states.
+
+## Dependency installation failure
+
+Symptoms:
+
+- GDAL/Rasterio install errors,
+- PyTorch package issue,
+- platform binary mismatch.
+
+Recovery:
+
+1. Do not remove the feature from docs.
+2. Add dependency note to `docs/DEPENDENCY_LOCK_PLAN.md`.
+3. Implement interfaces and tests around pure-Python parts first.
+4. Defer heavy binary package execution if needed, but leave adapter boundaries.
+
+## External data unavailable
+
+Symptoms:
+
+- WFS unavailable,
+- Sentinel catalog unavailable,
+- credentials missing.
+
+Recovery:
+
+1. Use demo fixtures.
+2. Keep adapter disabled but present.
+3. Return explicit `external_service_unavailable` status.
+4. Do not fake that live data was fetched.
+
+## AI model unavailable
+
+Symptoms:
+
+- YOLO weights missing,
+- SAM unavailable,
+- GPU unavailable.
+
+Recovery:
+
+1. Build model registry and adapter interface.
+2. Add CPU-safe mock inference only if marked as demo mode.
+3. Keep output schema identical to real inference.
+4. Do not present demo inference as production inference.
+
+## Test failures
+
+Recovery:
+
+1. Fix tests if implementation is wrong.
+2. Fix implementation if test reflects contract.
+3. Update specs only if they are clearly inconsistent.
+4. Document unresolved failures in execution log.