# Pause Accounting + Reorderable Handelingen + Login-Tab Fix — Design

- **Created:** 2026-06-17
- **Status:** Approved (brainstorming) — ready for implementation plan
- **Tracker:** Plane (workspace `solelog`, project SoleLog)
- **Touches:** `packages/shared`, `apps/api`, `apps/worker`, `apps/admin`

## Goal

Four maintainer-reported items, grouped because three of them share one root change
(server-authoritative pause):

1. **Admin shows paused sessions as running.** Pause is client-only today, so the admin
   live view (filters `status='active'`) can't tell paused from running.
2. **Reorderable handelingen.** Admin sets the order; the worker picker follows it.
3. **Saved duration ignores pause.** Stop stores wall-clock `(end − start)`, but the
   stopwatch displays *worked* time. Save worked time, and store paused time too
   ("gewerkt 1:00 · pauze 0:20").
4. **Wrong default tab after re-login.** Logout happens on the Account tab, leaving the URL
   at `/account`; the next login re-mounts there instead of Stopwatch.

## Root-cause findings (from current code)

- `apps/worker/src/screens/Stopwatch.tsx`: pause is **purely client-side** (`pausedMs`
  accumulator); the server session stays `status='active'`, `paused` unknown server-side.
- `apps/api/src/routes/sessions.ts` stop: `durationSeconds = round((end − start)/1000)` —
  wall-clock, includes paused time. The worker's displayed elapsed already excludes pause,
  hence the mismatch (#3).
- `apps/api/src/db/schema.ts`: `work_sessions` has no pause columns; `activities` has no
  `sort_order`.
- Worker logout sits on the Account tab → `BrowserRouter` re-mounts at `/account` (#4).

## A. Server-authoritative pause (#1 + #3)

**Data model** (migration `0003`, via `db:generate`):
- `work_sessions.paused_seconds` — `integer NOT NULL DEFAULT 0` (accumulated paused secs).
- `work_sessions.paused_at` — `integer timestamp_ms NULL` (set while paused; null = running).
- Status stays `active | completed | discarded`; a paused session is still **active** with
  `paused_at` set, so no existing status filter changes.

**Shared contract** `WorkSession`: add `paused_seconds: number` and
`paused_at: string | null` (ISO). `toWorkSession` maps both.

**Endpoints** (`sessions.ts`, user-scoped exactly like stop/discard):
- `POST /api/sessions/:id/pause` — active + not already paused → set `paused_at = now`;
  else 409. Returns the updated `WorkSession`.
- `POST /api/sessions/:id/resume` — paused → `paused_seconds += round((now − paused_at)/1000)`,
  clear `paused_at`; else 409.
- `POST /api/sessions/:id/stop` — **changed**: if `paused_at` set, fold the open span into
  `paused_seconds` first; then `duration_seconds = round((end − start)/1000) − paused_seconds`
  (clamp ≥ 0); set `paused_at = null`, status `completed`. Stores worked + paused.

**Worker `Stopwatch.tsx`:** pause/resume call the new endpoints (`usePauseSession` /
`useResumeSession`); keep the local clock for snappy feel, server is source of truth.
Recovery-on-load restores `paused_at`/`paused_seconds` (today it forces running). Displayed
elapsed remains worked time; `isPaused` derives from `paused_at`.

## B. Paused-time display (#3 display)

- **Worker History card:** "Gewerkt H:MM:SS" + (if `paused_seconds > 0`) a grey
  "Pauze H:MM:SS".
- **Admin Live + admin sessions views:** a **"Gepauzeerd"** badge when `paused_at` set; the
  elapsed timer **freezes** while paused (worked = `(paused_at − start) − paused_seconds`),
  and paused total shown.
- **CSV export** (`/api/export`): new "Paused Duration" column (`formatDuration(paused_seconds)`);
  the existing "Total Duration" stays = worked.

## C. Reorderable handelingen (#2) — arrow buttons

**Data model** (same `0003`): `activities.sort_order` — `integer NOT NULL DEFAULT 0`.
Existing rows get 0; `GET` orders by `(sort_order ASC, name ASC)` so current alphabetical
order is preserved until an admin reorders. `Activity` contract gains `sort_order: number`.

**Endpoints** (`activities.ts`):
- `GET /api/activities` orders by `(sort_order, name)`.
- `PUT /api/activities/reorder` (admin-gated): body `{ ids: number[] }` (the full ordered
  id list) → assigns `sort_order = index`. Validates the ids; returns the reordered list.
- `POST /api/activities` sets new rows to `sort_order = max(sort_order)+1` (append).

**Admin Activities screen:** each row gets ↑/↓ buttons (disabled at the ends) that swap with
the neighbour and fire the reorder mutation (invalidate `['activities']`). No new dependency.
**Worker picker:** inherits the order from `GET` — no worker UI change.

## D. Login-tab fix (#4)

Worker `AuthContext.signOut` resets the path to `/` (`window.history.replaceState(null, '', '/')`)
before clearing auth, so the next authed mount starts on Stopwatch. The **admin**
`AuthContext.signOut` gets the same one-liner (lands on Live) for consistency.

## Error handling

- pause/resume/stop on a non-owned or wrong-state session → 404/409 as today; client surfaces
  nothing intrusive (the active-session query reconciles).
- reorder with unknown/missing ids → 400.
- Clamp negative worked durations to 0 (guards clock skew / odd pause data).

## Testing

- **API:** pause sets `paused_at`; resume accumulates; stop excludes paused and folds an open
  pause span; reorder assigns `sort_order` by index and `GET` returns ordered; create appends.
- **Worker:** Stopwatch calls pause/resume; recovery restores paused state; History renders the
  pauze line when `paused_seconds > 0`; after `signOut` the path is `/` so login shows Stopwatch.
- **Admin:** Live shows "Gepauzeerd" + frozen timer; Activities ↑/↓ fire the reorder mutation
  with the swapped order; paused total shown in session views.

## Out of scope

- Admin pausing/resuming/stopping *another worker's* session (that's the Phase 3b
  manual-entry/admin-control work). Pause remains a worker action here.
- Drag-and-drop reordering (arrows chosen; DnD would add dnd-kit against the dependency-light
  goal).

## Build approach

One spec → `writing-plans` → **one Workflow** (per the maintainer's standing preference),
~8 TDD tasks, commit per task, final verify pass. Tracked as a Plane epic.