113 lines
6.8 KiB
Markdown
113 lines
6.8 KiB
Markdown
# Phase 3b·1 — Manual Session Entry/Edit + Admin Stop/Fix — Design
|
||
|
||
- **Created:** 2026-06-17
|
||
- **Status:** Approved (brainstorming) — ready for implementation plan
|
||
- **Tracker:** Plane (workspace `solelog`, project SoleLog)
|
||
- **Cycle:** First of three Phase 3b cycles (then reports/export, then user management)
|
||
- **Touches:** `packages/shared`, `apps/api`, `apps/admin`, `apps/worker`
|
||
|
||
## Goal
|
||
|
||
An admin can find any work session, **create** a manual one for a worker, **edit/correct** any
|
||
session, and **stop or cancel** a worker's stuck active session — the "manual fallback wherever
|
||
something fails" from the vision. Because the backend is the source of truth, the **worker
|
||
converges** to admin changes (no stuck stopwatch).
|
||
|
||
_Done when:_ an admin can list/filter all sessions, hand-create a completed session for a worker,
|
||
edit any session's fields (server recomputes duration), and stop/cancel a worker's active
|
||
session — and within ~15s the worker's stopwatch reflects a stop/cancel done by the admin.
|
||
|
||
## Scope decisions (confirmed during brainstorming, 2026-06-17)
|
||
|
||
1. **Slicing:** three sequenced 3b cycles; **this one first** (manual entry/edit + admin
|
||
stop/fix), then reports/export, then user management.
|
||
2. **Sessions UI:** a full **"Sessies"** admin screen (the all-sessions list deferred from 3a
|
||
lands here; the reports cycle reuses it).
|
||
3. **Editable fields:** start/end time, activity, insole type, pair count, paused seconds,
|
||
notes, status. The worker is chosen **only on create** — no reassignment on edit. Duration is
|
||
always **derived** server-side (`end − start − paused`), never typed.
|
||
4. **Worker convergence:** folded into this cycle — the worker polls and reconciles to server
|
||
truth (an admin stop/cancel reflects on the phone within ~15s; no stuck state).
|
||
|
||
## A. Backend (under the existing admin-gated `/api/admin/*` guard in `routes/admin.ts`)
|
||
|
||
- `GET /api/admin/users` — `{ id, name, email }[]` from the `user` table (ordered by name), to
|
||
populate the create form's worker picker. Direct DB query — no better-auth client dependency.
|
||
- `POST /api/admin/sessions` — manual create. Body `CreateManualSessionInput`:
|
||
`user_id, activity_id, insole_type, pair_count, start_time, end_time, paused_seconds?, notes?`.
|
||
Produces a **completed** session, `source='manual'`, `paused_at=null`,
|
||
`duration_seconds = max(0, round((end−start)/1000) − paused_seconds)`.
|
||
- `PUT /api/admin/sessions/:id` — edit any session. Body `AdminUpdateSessionInput`:
|
||
`activity_id, insole_type, pair_count, start_time, end_time(nullable), paused_seconds, notes,
|
||
status`. Recomputes `duration_seconds` from times − paused when `end_time` is present; when
|
||
`status='active'`/`end_time` null, `duration_seconds=null`. No user reassignment.
|
||
- `POST /api/admin/sessions/:id/stop` — quick "stop now": fold any open pause, `end=now`,
|
||
`status='completed'`, recompute duration.
|
||
- `POST /api/admin/sessions/:id/discard` — `status='discarded'`, `end=now`.
|
||
|
||
New `@solelog/shared` contracts: `CreateManualSessionInput`, `AdminUpdateSessionInput`. **No DB
|
||
migration** — reuses existing `work_sessions` columns (incl. the pause fields). Responses use the
|
||
existing `toWorkSession` mapper (so they carry `user_name`/`activity_name` where joined).
|
||
|
||
### Validation
|
||
`end ≥ start`; `pair_count ≥ 1`; `paused_seconds ≥ 0` and `≤ (end−start)`; activity must exist;
|
||
user must exist (create); `insole_type` a valid `InsoleType`. Invalid → 400; missing
|
||
session/user → 404. No hard delete — cancellation is `status='discarded'` (already excluded from
|
||
exports).
|
||
|
||
## B. Admin UI
|
||
|
||
- **`components/Sidebar.tsx`** — add `{ to: '/sessies', label: 'Sessies' }` to `navItems`; drop
|
||
`'Handmatig'` from the muted `soonItems` (now built → leaves `['Rapporten', 'Gebruikers']`).
|
||
- **`App.tsx`** — add `<Route path="/sessies" element={<Sessions />} />`.
|
||
- **`screens/Sessions.tsx`** — lists all sessions via `useAllSessions` (`GET /api/admin/sessions`,
|
||
newest first), a status filter (alle / actief / voltooid / geannuleerd), and a
|
||
`+ Nieuwe registratie` button. Each row: worker · activity · type · worked (+ pauze) · date.
|
||
**Active** rows show `[Stop]` `[Annuleer]`; **all** rows show ✎ edit.
|
||
- **`components/SessionForm.tsx`** — shared create/edit form: worker picker (create only, from
|
||
`useAdminUsers`), activity dropdown, insole-type, pair count, start/end datetime-local, paused,
|
||
status (edit only), notes, and a live **"gewerkt"** preview. Submits create or update.
|
||
- **`api/admin-sessions.ts`** — add `useAllSessions`, `useAdminUsers`, `useCreateManualSession`,
|
||
`useUpdateSession`, `useAdminStopSession`, `useAdminDiscardSession` (all invalidate the
|
||
`['admin','sessions']` query family; keep the existing `useActiveSessions`).
|
||
- **`screens/Live.tsx`** — add `[Stop]` `[Annuleer]` to each `LiveCard`, wired to the admin
|
||
stop/discard hooks (invalidate the active query).
|
||
|
||
## C. Worker convergence (`apps/worker`)
|
||
|
||
- **`api/sessions.ts`** — give `useActiveSessions` a `refetchInterval: 15000` (poll), plus the
|
||
default refetch-on-window-focus.
|
||
- **`screens/Stopwatch.tsx`** — extend the active-session effect to **reconcile**: if a session is
|
||
running locally (`sessionId` set) but the latest `activeSessionsQuery.data` no longer contains a
|
||
matching **active** session for it, the session was stopped/cancelled elsewhere → reset the
|
||
timer and surface a brief notice **"Deze sessie is door de beheerder gestopt."** Also: treat a
|
||
**409** from the worker's own stop/discard as already-closed → reset locally instead of erroring.
|
||
|
||
## Error handling
|
||
|
||
- Worker reconciliation notice is transient (dismissible / auto-clears on next start).
|
||
- Admin form: inline validation errors mirror the API 400s (end before start, count < 1).
|
||
- Stop/discard on a non-active session → 409; admin UI refetches and the row reflects truth.
|
||
|
||
## Testing
|
||
|
||
- **API** (`admin.test.ts`): create computes duration + `source='manual'`; edit recomputes and
|
||
rejects `end<start`; stop/discard act on **another** user's session; all 401/403 gated;
|
||
`GET /api/admin/users` returns the roster.
|
||
- **Admin:** Sessions list renders + status filter; create form posts the right body; edit
|
||
prefills + PUTs; Live `Stop`/`Annuleer` fire the right mutations.
|
||
- **Worker:** when the active query returns without a locally-running session, the stopwatch
|
||
resets + shows the notice; a 409 on stop resets instead of erroring.
|
||
|
||
## Out of scope (later 3b cycles)
|
||
|
||
- Aggregated/on-screen **reporting** + all-users filtered CSV (reports cycle).
|
||
- Full **user management** UI — create/role/deactivate via `/api/auth/admin/*` (user-mgmt cycle);
|
||
this cycle only *reads* the roster (`GET /api/admin/users`) for the picker.
|
||
- Real-time push (SSE) — polling is sufficient at this scale.
|
||
|
||
## Build approach
|
||
|
||
spec → `writing-plans` → one **Workflow** (~7 TDD tasks), commit per task, final verify. Tracked
|
||
as a Plane epic.
|