Error handling added to MVP according to error_handling.md guideline

2026-06-25 12:56:35 -05:00
parent 0cc6b0e1eb
commit e291ffc907
18 changed files with 819 additions and 28 deletions
@@ -0,0 +1,134 @@
+## Step 7 Results: Error Handling Standardization and Operational Visibility
+
+## Summary
+
+Step 7 was implemented across the MVP runtime boundaries with a shared error taxonomy, actionable UI error surfacing, worker failure normalization, and API error envelope handling.
+
+All required validation gates in `docs/step7.md` were executed and passed.
+
+---
+
+## Scope Delivered
+
+### Implemented
+- Shared application error contract and taxonomy
+- Service-layer error normalization (upload + transcription)
+- UI error presentation helpers with suggested actions and error references
+- Worker failure persistence format with category/suggestion/error_id markers
+- API exception handlers for structured error responses
+- Targeted tests for new error contract behavior
+
+### Not implemented in this step
+- External lane execution (`-m external`) was not required for Step 7 completion and was not run in this pass.
+
+---
+
+## Files Added
+
+- `src/transcription/errors.py`
+- `src/transcription/api/errors.py`
+- `src/transcription/ui/error_presenter.py`
+- `tests/test_errors.py`
+- `tests/api/test_error_responses.py`
+- `docs/step7.md`
+
+## Files Updated
+
+- `src/transcription/app.py`
+- `src/transcription/services/upload.py`
+- `src/transcription/services/transcription.py`
+- `src/transcription/ui/upload_page.py`
+- `src/transcription/ui/jobs_page.py`
+- `src/transcription/worker.py`
+- `tests/services/test_upload.py`
+- `tests/services/test_transcription.py`
+- `tests/services/test_worker.py`
+- `tests/integration/test_pipeline_flow.py`
+- `uv.lock`
+
+---
+
+## Implementation Notes by Phase
+
+### Phase A/B (Foundation)
+- Added `ErrorCategory` enum and `AppError` base type in `src/transcription/errors.py`.
+- Added helper utilities:
+  - `new_error_id()`
+  - `build_error_envelope(...)`
+  - `classify_unexpected_error(...)`
+  - `format_error_detail(...)`
+
+### Phase C (Service/Provider normalization)
+- `UploadError` now extends `AppError` and includes category/suggestion/retriable metadata.
+- `PromptLoadError` and `TranscriptionError` now extend `AppError`.
+- Provider failures are mapped with deterministic category semantics (auth/payload/provider-failure cases).
+
+### Phase D (UI visibility)
+- Added `src/transcription/ui/error_presenter.py`.
+- Upload and jobs pages now use centralized UI error rendering and summary helpers.
+- UI error paths now include more visible/actionable guidance and reference IDs.
+
+### Phase E (Worker failure handling)
+- Worker now normalizes exception handling into structured persisted `error_detail` strings with:
+  - category marker
+  - suggestion marker
+  - error_id marker
+- Logging now includes category/error_id context in failure paths.
+
+### Phase F (API envelope)
+- Added `src/transcription/api/errors.py` and registered handlers in app factory.
+- AppError and unexpected exceptions now serialize to stable API envelopes with mapped status codes.
+
+---
+
+## Validation Commands and Outcomes
+
+All commands were executed with `uv run python -m pytest ...` and completed successfully.
+
+1. `uv run python -m pytest tests/test_errors.py -q` ✅
+2. `uv run python -m pytest tests/services/test_upload.py -q` ✅
+3. `uv run python -m pytest tests/services/test_transcription.py -q` ✅
+4. `uv run python -m pytest tests/providers/test_openrouter.py -q` ✅
+5. `uv run python -m pytest tests/services/test_worker.py -q` ✅
+6. `uv run python -m pytest tests/integration/test_pipeline_flow.py -q` ✅
+7. `uv run python -m pytest tests/api/test_error_responses.py -q` ✅
+8. `uv run python -m pytest tests/ui/test_upload_page.py -q` ✅
+9. `uv run python -m pytest tests/ui/test_jobs_page.py -q` ✅
+10. `uv run python -m pytest -m "not external" -q` ✅
+11. `uv run python -m pytest --collect-only -q` ✅
+12. `uv run python -m pytest -m unit -q` ✅
+13. `uv run python -m pytest -m integration -q` ✅
+14. `uv run python -m pytest tests/integration/test_pipeline_flow.py -q` ✅
+15. `uv run python -m pytest tests/ui/test_upload_page.py -q` ✅
+16. `uv run python -m pytest tests/ui/test_jobs_page.py -q` ✅
+17. `uv run python -m pytest -q` ✅
+
+Observed warning (non-blocking): Starlette/FastAPI TestClient deprecation warning related to `httpx` package naming.
+
+---
+
+## Policy Alignment Check (`docs/error_handling.md`)
+
+Aligned items:
+- Stable taxonomy categories are implemented.
+- Unexpected errors are normalized.
+- User-facing UI paths include actionable guidance and references.
+- Worker persistence includes trace-friendly failure detail.
+- API error responses are structured and category-aware.
+
+Follow-up candidates:
+- Add richer UI tests that validate rendered suggested-action content end-to-end (current tests focus helper/service contracts).
+- Consider typed storage fields for error metadata instead of packed `error_detail` strings in a future schema revision.
+
+---
+
+## Step 7 Definition of Done Status
+
+- [x] Shared error taxonomy implemented across MVP layers
+- [x] GUI error paths upgraded for visibility/actionability
+- [x] Worker failure persistence and log context standardized
+- [x] API error envelope handling added and tested
+- [x] Phase-level and full-suite validation gates passed
+- [x] Results documented in this report
+
+Step 7 is complete.