102 lines
2.3 KiB
Markdown
102 lines
2.3 KiB
Markdown
# 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.
|