generated from john/python-template
134 lines
5.1 KiB
Markdown
134 lines
5.1 KiB
Markdown
## 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. |