Current Action Inventory (v0) - Exhaustive
This document is a deep-dive inventory of the existing "next action" behaviors currently implied by the backend codebase. It serves as the "as-is" analysis, mapping current error and success responses to a proposed ActionSpec type from the v1 contract.
This is the foundation for refactoring towards the formal API Response Contract.
Exhaustive Implicit Action Inventory
| Endpoint / Scenario | Trigger | Implied UI Action | Proposed ActionSpec | work_state | File references |
|---|---|---|---|---|---|
| Any Authenticated Route | Missing or invalid JWT token | Redirect user to the login page | REAUTHENTICATE | NOT_SAVED | http/middleware/auth.go |
| Any Capability-Gated Route | User lacks the required capability | Inform user they have insufficient permissions | REQUEST_ACCESS | NOT_SAVED | services/authz/service.go |
GET for a resource | RLS prevents access or resource does not exist | Show a standard "Not Found" page | (None) | (N/A) | Various handlers (services.ErrNotFound) |
Any endpoint (e.g. /auth/login) | Rate limit exceeded (429 Too Many Requests) | Inform user to wait before trying again | RETRY | NOT_SAVED | http/middleware/ratelimit.go |
| Any Write Operation | Optimistic locking failure (e.g., stale updated_at) | Inform user data is stale; refresh and retry | REFRESH_AND_RETRY | NOT_SAVED | services/evaluation_service.go |
POST /users | ErrConflict due to existing email | Inform user the email is already in use | RESOLVE_VALIDATION | NOT_SAVED | http/handler/user_handlers.go |
POST /evaluations/.../publish | services.ValidationError (e.g., empty sections) | Display specific validation warnings to the author | RESOLVE_VALIDATION | NOT_SAVED | http/handler/evaluation_versions.go |
DELETE /evaluations/\{id\} | services.EvaluationInUseError (has submissions) | Inform user it was archived, not deleted | GO_TO_DASHBOARD (kind: PARTIAL_SUCCESS) | (N/A) | http/handler/evaluation_core.go |
POST /sessions/.../submit | Session is already submitted (Idempotency) | Inform user the submission is already complete | GO_TO_DASHBOARD | SAFE | http/handler/evaluation_sessions.go |
POST /sessions/.../answers or .../submit | Session is closed or abandoned | Inform user the attempt is over; input was not saved | GO_TO_DASHBOARD | NOT_SAVED | http/handler/evaluation_sessions.go |
POST /assignments | ErrConflict on unique index (duplicate assignment) | Inform user an identical assignment already exists | NEW ACTION NEEDED (VIEW_EXISTING) | NOT_SAVED | services/assignments_service.go |
POST /assignments/\{id\}/redeem | ErrInvalidInput (attempt limit reached) | Inform user they have no more attempts remaining | GO_TO_DASHBOARD | NOT_SAVED | services/assignments_service.go |
POST /assignments/\{id\}/redeem | User has an existing active session | Offer to resume the existing session | RESUME_SESSION | NOT_SAVED | services/assignments_service.go |
POST /compliance/... (Async Jobs) | Successful async job creation (202 Accepted) | Start polling the job's URL for completion | POLL_JOB | (N/A) | http/handler/compliance_jobs.go |
POST /results/.../apply (Async Jobs) | Successful async remediation job start (202 Accepted) | Navigate to a view to monitor the batch status | VIEW_BATCH_STATUS | (N/A) | http/handler/results_remediation_handlers.go |
POST /compliance/forget | Target user is under a legal hold | Inform user the action is blocked by a legal hold | NEW ACTION NEEDED (VIEW_LEGAL_HOLD) | NOT_SAVED | workers/privacy_jobs_worker.go |
POST /programmes/\{id\}/enrol | ErrConflict because user is already enrolled | Inform user they are already enrolled | NEW ACTION NEEDED (VIEW_ENROLMENT) | NOT_SAVED | services/programme_enrolment_service.go |
| (Any endpoint) | Attempt to edit a published/immutable resource | Block the action and inform the user why | CREATE_NEW_VERSION | NOT_SAVED | (Gap - See Action Gap List) |
| (Any endpoint) | Unhandled exception / panic | Show a generic error with a reference code | NEW ACTION NEEDED (FATAL_ERROR) | UNKNOWN | http/middleware/recoverer.go |
Note: This more exhaustive list covers the primary and cross-cutting "next action" behaviors implemented or implied in the backend. work_state is only noted where user-entered input could be at risk.