generated from john/python-template
267 lines
9.4 KiB
Markdown
267 lines
9.4 KiB
Markdown
## Step 7: Error Handling Standardization and Operational Visibility
|
|
|
|
## Objective
|
|
|
|
Apply the canonical error policy from `docs/error_handling.md` to the MVP implementation so failures are:
|
|
|
|
- consistently classified
|
|
- visibly surfaced in the GUI
|
|
- paired with suggested corrective actions
|
|
- traceable through logs via error reference IDs
|
|
- validated through deterministic tests after each phase
|
|
|
|
This step extends MVP hardening by converting current ad hoc exception behavior into a stable cross-layer contract.
|
|
|
|
---
|
|
|
|
## Scope
|
|
|
|
### In scope
|
|
- Introduce a shared application error contract and taxonomy implementation
|
|
- Normalize service/provider exceptions into taxonomy categories
|
|
- Improve GUI error visibility and suggested-action UX
|
|
- Standardize worker failure persistence and logging context
|
|
- Add API error-envelope policy hooks for current/future endpoints
|
|
- Add targeted tests and phase-level/full-suite validation gates
|
|
|
|
### Out of scope
|
|
- Major architecture rewrites (distributed queue, multi-service decomposition)
|
|
- Post-MVP feature expansion unrelated to error handling
|
|
- Full observability platform rollout (tracing backends, APM)
|
|
|
|
---
|
|
|
|
## Policy Source of Truth
|
|
|
|
- Canonical policy document: `docs/error_handling.md`
|
|
- If implementation and policy diverge, policy is authoritative and code/tests must be updated.
|
|
|
|
---
|
|
|
|
## Planned Deliverables
|
|
|
|
### Runtime code
|
|
- `src/transcription/errors.py` *(new shared contract module)*
|
|
- `src/transcription/ui/error_presenter.py` *(new UI error rendering helper)*
|
|
- Updates to:
|
|
- `src/transcription/services/upload.py`
|
|
- `src/transcription/services/transcription.py`
|
|
- `src/transcription/providers/openrouter.py`
|
|
- `src/transcription/worker.py`
|
|
- `src/transcription/ui/upload_page.py`
|
|
- `src/transcription/ui/jobs_page.py`
|
|
- `src/transcription/api/*` *(as needed for envelope/handlers)*
|
|
|
|
### Tests
|
|
- `tests/test_errors.py` *(new shared error contract tests)*
|
|
- updates/additions in:
|
|
- `tests/services/test_upload.py`
|
|
- `tests/services/test_transcription.py` *(add if missing)*
|
|
- `tests/providers/test_openrouter.py`
|
|
- `tests/services/test_worker.py`
|
|
- `tests/ui/test_upload_page.py`
|
|
- `tests/ui/test_jobs_page.py`
|
|
- `tests/api/test_error_responses.py` *(new, if API handlers added)*
|
|
|
|
### Documentation
|
|
- Update `docs/error_handling.md` only if implementation reveals policy gaps
|
|
- Capture validation evidence in a Step 7 results artifact (`docs/step7-results.md`)
|
|
|
|
---
|
|
|
|
## Design and Policy Decisions
|
|
|
|
1. **Stable taxonomy contract**
|
|
- Use policy categories as stable identifiers (`validation_error`, `user_input_error`, etc.).
|
|
|
|
2. **Actionable UX is mandatory**
|
|
- User-visible errors must include a suggested course of action.
|
|
|
|
3. **Traceability by default**
|
|
- Non-trivial errors include an `error_id` in both logs and user-facing output.
|
|
|
|
4. **Safe surface / rich logs**
|
|
- UI/API show safe summaries; logs retain diagnostic detail and traceback.
|
|
|
|
5. **Deterministic verification cadence**
|
|
- Targeted tests after each change batch, then phase-level regression gates.
|
|
|
|
---
|
|
|
|
## Implementation Plan + Checklist
|
|
|
|
## Phase A — Baseline Validation and Gap Confirmation
|
|
|
|
- [ ] Run baseline tests before changes
|
|
- [ ] Record baseline outputs and any known flaky behavior
|
|
- [ ] Confirm current behavior against `docs/error_handling.md` requirements
|
|
|
|
### Validation gate
|
|
- [ ] `uv run pytest -m "not external" -q`
|
|
- [ ] `uv run pytest -q`
|
|
|
|
## Phase B — Shared Error Contract Foundation
|
|
|
|
- [ ] Add `src/transcription/errors.py` with:
|
|
- [ ] stable category enum
|
|
- [ ] base `AppError` (category/message/suggestion/error_id/retriable)
|
|
- [ ] helpers for error-id generation and fallback classification
|
|
- [ ] Keep category names aligned with `docs/error_handling.md`
|
|
|
|
### Tests
|
|
- [ ] Add `tests/test_errors.py`
|
|
- [ ] category stability assertions
|
|
- [ ] error_id creation behavior
|
|
- [ ] fallback classification for unexpected exceptions
|
|
|
|
### Validation gate
|
|
- [ ] `uv run pytest tests/test_errors.py -q`
|
|
- [ ] `uv run pytest -m "not external" -q`
|
|
|
|
## Phase C — Service and Provider Normalization
|
|
|
|
- [ ] Refactor upload service exceptions to shared taxonomy
|
|
- [ ] Refactor transcription service exceptions to shared taxonomy
|
|
- [ ] Normalize provider adapter failures into deterministic categories
|
|
- [ ] Preserve causal chaining (`raise ... from exc`)
|
|
|
|
### Tests
|
|
- [ ] Extend `tests/services/test_upload.py`:
|
|
- [ ] empty payload category/suggestion
|
|
- [ ] unsupported extension category/suggestion
|
|
- [ ] persistence failure category mapping
|
|
- [ ] Add/extend `tests/services/test_transcription.py`:
|
|
- [ ] missing/empty prompt behavior
|
|
- [ ] unsupported file type behavior
|
|
- [ ] provider failure mapping behavior
|
|
- [ ] Extend `tests/providers/test_openrouter.py`:
|
|
- [ ] auth error mapping
|
|
- [ ] malformed response mapping
|
|
|
|
### Validation gate
|
|
- [ ] `uv run pytest tests/services/test_upload.py -q`
|
|
- [ ] `uv run pytest tests/services/test_transcription.py -q`
|
|
- [ ] `uv run pytest tests/providers/test_openrouter.py -q`
|
|
- [ ] `uv run pytest -m "not external" -q`
|
|
|
|
## Phase D — GUI Visibility and Suggested Actions
|
|
|
|
- [ ] Add `src/transcription/ui/error_presenter.py`
|
|
- [ ] Update upload/jobs pages to use centralized error presentation
|
|
- [ ] Ensure GUI surfaces:
|
|
- [ ] user-safe message
|
|
- [ ] suggested action
|
|
- [ ] error reference ID
|
|
- [ ] optional technical details panel
|
|
- [ ] Replace raw `str(exc)` UX where policy requires safer messaging
|
|
|
|
### Tests
|
|
- [ ] Extend `tests/ui/test_upload_page.py` for actionable error UX paths
|
|
- [ ] Extend `tests/ui/test_jobs_page.py` for refresh/detail error guidance
|
|
- [ ] Add `tests/ui/test_error_presenter.py` *(optional but recommended)*
|
|
|
|
### Validation gate
|
|
- [ ] `uv run pytest tests/ui/test_upload_page.py -q`
|
|
- [ ] `uv run pytest tests/ui/test_jobs_page.py -q`
|
|
- [ ] `uv run pytest -m "not external" -q`
|
|
|
|
## Phase E — Worker Failure Persistence and Logging Context
|
|
|
|
- [ ] Update worker failure handling to classify errors before persistence
|
|
- [ ] Ensure failed jobs persist actionable, structured error detail
|
|
- [ ] Add log context fields where available (`error_id`, `category`, `operation`, `job_id`)
|
|
- [ ] Ensure retry semantics are explicit and bounded (or clearly documented as deferred)
|
|
|
|
### Tests
|
|
- [ ] Extend `tests/services/test_worker.py`:
|
|
- [ ] missing document failure contract
|
|
- [ ] provider/transcription failure contract
|
|
- [ ] persisted error detail includes category/suggestion/error_id markers
|
|
- [ ] Validate integration failure flow in `tests/integration/test_pipeline_flow.py`
|
|
|
|
### Validation gate
|
|
- [ ] `uv run pytest tests/services/test_worker.py -q`
|
|
- [ ] `uv run pytest tests/integration/test_pipeline_flow.py -q`
|
|
- [ ] `uv run pytest -m "not external" -q`
|
|
|
|
## Phase F — API Error Envelope Alignment (Current + Future Routes)
|
|
|
|
- [ ] Add shared API error serialization utilities/handlers (as needed)
|
|
- [ ] Ensure API responses can include:
|
|
- [ ] `error_id`
|
|
- [ ] `category`
|
|
- [ ] `message`
|
|
- [ ] `suggestion`
|
|
- [ ] `timestamp`
|
|
- [ ] Map categories to HTTP status guidance from `docs/error_handling.md`
|
|
|
|
### Tests
|
|
- [ ] Add `tests/api/test_error_responses.py` *(if handlers added)*
|
|
- [ ] Keep `tests/api/test_health.py` passing
|
|
|
|
### Validation gate
|
|
- [ ] `uv run pytest tests/api/test_error_responses.py -q` *(if added)*
|
|
- [ ] `uv run pytest tests/api/test_health.py -q`
|
|
- [ ] `uv run pytest -m "not external" -q`
|
|
|
|
## Phase G — Final Regression and Documentation Closure
|
|
|
|
- [ ] Reconcile implementation details with `docs/error_handling.md`
|
|
- [ ] Update policy doc only where required by confirmed implementation learning
|
|
- [ ] Capture execution evidence in `docs/step7-results.md`
|
|
|
|
### Final validation sequence (strict)
|
|
- [ ] `uv run pytest --collect-only -q`
|
|
- [ ] `uv run pytest -m unit -q`
|
|
- [ ] `uv run pytest -m integration -q`
|
|
- [ ] `uv run pytest -m "not external" -q`
|
|
- [ ] `uv run pytest tests/integration/test_pipeline_flow.py -q`
|
|
- [ ] `uv run pytest tests/ui/test_upload_page.py -q`
|
|
- [ ] `uv run pytest tests/ui/test_jobs_page.py -q`
|
|
- [ ] `uv run pytest -q`
|
|
|
|
Optional:
|
|
- [ ] `uv run pytest -m external -q`
|
|
|
|
---
|
|
|
|
## Guardrails
|
|
|
|
- Do not weaken user-facing clarity to expose raw internals.
|
|
- Do not introduce silent exception swallowing.
|
|
- Do not break category-name stability without policy update.
|
|
- Do not merge phase changes without passing that phase validation gate.
|
|
- Keep targeted tests fast and deterministic; isolate external-provider tests under `external`.
|
|
|
|
---
|
|
|
|
## Definition of Done (Step 7)
|
|
|
|
- [ ] Shared error taxonomy is implemented and used across MVP layers
|
|
- [ ] GUI error experiences are visible, actionable, and traceable
|
|
- [ ] Worker persists and logs failure context consistently
|
|
- [ ] API error contract path is aligned for current/future endpoints
|
|
- [ ] Phase-by-phase test gates pass
|
|
- [ ] Full suite remains green (`uv run pytest -q`)
|
|
- [ ] Step 7 results are documented with evidence
|
|
|
|
---
|
|
|
|
## PR Checklist (Step 7)
|
|
|
|
### Implementation
|
|
- [ ] Added shared error contract module
|
|
- [ ] Updated service/provider/worker/UI error handling paths
|
|
- [ ] Added actionable GUI guidance for user-visible failures
|
|
- [ ] Added error reference IDs for traceability
|
|
|
|
### Testing
|
|
- [ ] Added/updated tests per phase scope
|
|
- [ ] Ran targeted phase tests after each change batch
|
|
- [ ] Ran `not external` regression at each phase boundary
|
|
- [ ] Ran full suite before closeout
|
|
|
|
### Documentation and Evidence
|
|
- [ ] `docs/error_handling.md` reviewed for alignment
|
|
- [ ] `docs/step7-results.md` includes executed command outputs
|
|
- [ ] Residual risks and deferred items explicitly recorded |