feat: add task status transitions

docs/features/005-task-status.md

@@ -0,0 +1,123 @@
+# Feature 5 – Statusändring och statusregler
+
+## Status
+
+Färdig och verifierad på feature-branchen; ännu inte mergad till `main`.
+
+## Bakgrund
+
+Efter Feature 4 kan uppgifter vara otilldelade eller ha en ansvarig, men inget
+API eller gränssnitt kan ändra status. Feature 5 inför ett enkelt knappflöde
+före drag-and-drop och säkerställer statusreglerna i backend.
+
+## Mål
+
+- ändra status genom ett särskilt backend-API;
+- tillåta direkta övergångar mellan `WAITING`, `IN_PROGRESS` och `COMPLETED`;
+- kräva ansvarig för `IN_PROGRESS`;
+- automatiskt tilldela aktiv browseranvändare när en otilldelad uppgift
+  påbörjas;
+- tillåta statusberoende ändringar av ansvarig;
+- använda serverbekräftade uppdateringar och vänteläge per kort.
+
+## Status- och tilldelningsregler
+
+Alla statusar får ändras direkt till varandra. Ett anrop med aktuell status som
+mål är giltigt och idempotent. En uppgift behöver inte passera
+`IN_PROGRESS` för att bli `COMPLETED`.
+
+`WAITING` och `COMPLETED` får vara tilldelade eller otilldelade.
+`IN_PROGRESS` måste alltid ha en ansvarig. Det befintliga tilldelnings-API:t
+kan tilldela eller byta ansvarig i samtliga statusar och ta bort ansvarig i
+`WAITING` och `COMPLETED`. Ett försök att ta bort ansvarig i `IN_PROGRESS`
+avvisas med `409 TASK_REQUIRES_ASSIGNEE`. Tilldelning ändrar aldrig status.
+
+När en otilldelad uppgift ändras till `IN_PROGRESS` skickar frontend aktiv
+användares id. Backend verifierar användaren, tilldelar den och ändrar status i
+samma transaktion. Om uppgiften redan har en ansvarig behålls den, och skickat
+`activeUserId` används inte för att byta ansvarig.
+
+## API-förändringar
+
+Status ändras med:
+
+```http
+PUT /api/tasks/{taskId}/status
+```
+
+```json
+{
+  "status": "IN_PROGRESS",
+  "activeUserId": "d56b54dd-31b0-4d71-8a10-82464be59a61"
+}
+```
+
+`status` är obligatoriskt. `activeUserId` krävs endast när en otilldelad
+uppgift ska bli `IN_PROGRESS`. Responsen använder samma fullständiga
+task-format som övriga task-operationer.
+
+Kända fel använder befintligt format med `code` och `message`:
+
+- okänd uppgift: `404 TASK_NOT_FOUND`;
+- saknad, null eller okänd status: `400 INVALID_TASK_STATUS`;
+- okänd användare: `404 USER_NOT_FOUND`;
+- otilldelad `IN_PROGRESS`: `409 TASK_REQUIRES_ASSIGNEE`;
+- ogiltigt UUID-format: `400` med befintlig requestfelkod.
+
+`USER_NOT_FOUND` och `INVALID_TASK_ASSIGNMENT` återanvänds från Feature 4 i
+stället för att införa parallella felkoder för samma användar-id.
+
+## Databasförändringar
+
+Inga. Befintliga kolumner för status och ansvarig är tillräckliga.
+
+## Frontendförändringar
+
+Varje kort visar två statusknappar:
+
+- `WAITING`: `Påbörja`, `Markera klar`;
+- `IN_PROGRESS`: `Till Väntande`, `Markera klar`;
+- `COMPLETED`: `Till Väntande`, `Påbörja igen`.
+
+Tilldelningskontrollen är redigerbar i alla statusar. Alternativet `Ingen`
+visas inte för `IN_PROGRESS`.
+
+Status och tilldelning delar ett vänteläge per uppgift. Under ett anrop ligger
+kortet kvar i sin kolumn och båda kontrollerna på kortet är inaktiverade.
+Övriga kort är fortsatt interaktiva. Vid framgång ersätts uppgiften med
+serverresponsen; vid fel behålls tidigare data och felet visas lokalt.
+
+## Tester och verifiering
+
+Backendtesterna omfattar samtliga direkta övergångar, idempotens, automatisk
+tilldelning, bevarad ansvarig, statusvalidering, okända id:n, statusberoende
+tilldelning och oförändrade uppgiftsfält.
+
+Frontendtesterna omfattar knapparnas statusmappning, requestformat,
+serverbekräftad flytt, automatisk tilldelning i responsen, lokalt vänteläge,
+dubbelsubmitsskydd, fel utan optimistisk ändring och statusberoende
+tilldelningsalternativ.
+
+Manuell verifiering genomfördes genom ett sammanhängande flöde genom alla tre
+statusar, automatisk tilldelning, byte och borttagning av ansvarig, omladdning
+och centrala API-fel. Browserflödet verifierades i desktop- och mobilbredd utan
+upptäckta problem.
+
+## Avgränsningar
+
+Ingen drag-and-drop, radering, generell redigering, sortering, deadline,
+återkommande uppgift, status- eller poänghistorik, slutföranderegistrering,
+statistik, användaradministration, autentisering eller behörighetskontroll
+införs.
+
+## Kända begränsningar
+
+Aktiv användare är ett lokalt browserval och inte autentisering. Backend kan
+verifiera att id:t finns, men inte vem som faktiskt använder browsern.
+Statusknapparna är ett första gränssnitt före Feature 6. Det finns ingen
+versionskontroll för konkurrerande uppdateringar utöver transaktioner och
+aktuell serverlogik.
+
+## Relaterade commits
+
+Fylls i efter implementation och merge.